1.\" 2.\" Copyright (c) 1998, 1999, 2000, 2002, 2005, 2006, 2007 Kenneth D. Merry. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd July 22, 2019 31.Dt CAMCONTROL 8 32.Os 33.Sh NAME 34.Nm camcontrol 35.Nd CAM control program 36.Sh SYNOPSIS 37.Nm 38.Aq Ar command 39.Op device id 40.Op generic args 41.Op command args 42.Nm 43.Ic devlist 44.Op Fl b 45.Op Fl v 46.Nm 47.Ic periphlist 48.Op device id 49.Op Fl n Ar dev_name 50.Op Fl u Ar unit_number 51.Nm 52.Ic tur 53.Op device id 54.Op generic args 55.Nm 56.Ic inquiry 57.Op device id 58.Op generic args 59.Op Fl D 60.Op Fl S 61.Op Fl R 62.Nm 63.Ic identify 64.Op device id 65.Op generic args 66.Op Fl v 67.Nm 68.Ic reportluns 69.Op device id 70.Op generic args 71.Op Fl c 72.Op Fl l 73.Op Fl r Ar reporttype 74.Nm 75.Ic readcap 76.Op device id 77.Op generic args 78.Op Fl b 79.Op Fl h 80.Op Fl H 81.Op Fl l 82.Op Fl N 83.Op Fl q 84.Op Fl s 85.Nm 86.Ic start 87.Op device id 88.Op generic args 89.Nm 90.Ic stop 91.Op device id 92.Op generic args 93.Nm 94.Ic load 95.Op device id 96.Op generic args 97.Nm 98.Ic eject 99.Op device id 100.Op generic args 101.Nm 102.Ic reprobe 103.Op device id 104.Nm 105.Ic rescan 106.Aq all | device id | bus Ns Op :target:lun 107.Nm 108.Ic reset 109.Aq all | device id | bus Ns Op :target:lun 110.Nm 111.Ic defects 112.Op device id 113.Op generic args 114.Aq Fl f Ar format 115.Op Fl P 116.Op Fl G 117.Op Fl q 118.Op Fl s 119.Op Fl S Ar offset 120.Op Fl X 121.Nm 122.Ic modepage 123.Op device id 124.Op generic args 125.Aq Fl m Ar page[,subpage] | Fl l 126.Op Fl P Ar pgctl 127.Op Fl b | Fl e 128.Op Fl d 129.Nm 130.Ic cmd 131.Op device id 132.Op generic args 133.Aq Fl a Ar cmd Op args 134.Aq Fl c Ar cmd Op args 135.Op Fl d 136.Op Fl f 137.Op Fl i Ar len Ar fmt 138.Bk -words 139.Op Fl o Ar len Ar fmt Op args 140.Op Fl r Ar fmt 141.Ek 142.Nm 143.Ic smpcmd 144.Op device id 145.Op generic args 146.Aq Fl r Ar len Ar fmt Op args 147.Aq Fl R Ar len Ar fmt Op args 148.Nm 149.Ic smprg 150.Op device id 151.Op generic args 152.Op Fl l 153.Nm 154.Ic smppc 155.Op device id 156.Op generic args 157.Aq Fl p Ar phy 158.Op Fl l 159.Op Fl o Ar operation 160.Op Fl d Ar name 161.Op Fl m Ar rate 162.Op Fl M Ar rate 163.Op Fl T Ar pp_timeout 164.Op Fl a Ar enable|disable 165.Op Fl A Ar enable|disable 166.Op Fl s Ar enable|disable 167.Op Fl S Ar enable|disable 168.Nm 169.Ic smpphylist 170.Op device id 171.Op generic args 172.Op Fl l 173.Op Fl q 174.Nm 175.Ic smpmaninfo 176.Op device id 177.Op generic args 178.Op Fl l 179.Nm 180.Ic debug 181.Op Fl I 182.Op Fl P 183.Op Fl T 184.Op Fl S 185.Op Fl X 186.Op Fl c 187.Op Fl p 188.Aq all | off | device id | bus Ns Op :target Ns Op :lun 189.Nm 190.Ic tags 191.Op device id 192.Op generic args 193.Op Fl N Ar tags 194.Op Fl q 195.Op Fl v 196.Nm 197.Ic negotiate 198.Op device id 199.Op generic args 200.Op Fl c 201.Op Fl D Ar enable|disable 202.Op Fl M Ar mode 203.Op Fl O Ar offset 204.Op Fl q 205.Op Fl R Ar syncrate 206.Op Fl T Ar enable|disable 207.Op Fl U 208.Op Fl W Ar bus_width 209.Op Fl v 210.Nm 211.Ic format 212.Op device id 213.Op generic args 214.Op Fl q 215.Op Fl r 216.Op Fl w 217.Op Fl y 218.Nm 219.Ic sanitize 220.Op device id 221.Op generic args 222.Aq Fl a Ar overwrite | block | crypto | exitfailure 223.Op Fl c Ar passes 224.Op Fl I 225.Op Fl P Ar pattern 226.Op Fl q 227.Op Fl U 228.Op Fl r 229.Op Fl w 230.Op Fl y 231.Nm 232.Ic idle 233.Op device id 234.Op generic args 235.Op Fl t Ar time 236.Nm 237.Ic standby 238.Op device id 239.Op generic args 240.Op Fl t Ar time 241.Nm 242.Ic sleep 243.Op device id 244.Op generic args 245.Nm 246.Ic powermode 247.Op device id 248.Op generic args 249.Nm 250.Ic apm 251.Op device id 252.Op generic args 253.Op Fl l Ar level 254.Nm 255.Ic aam 256.Op device id 257.Op generic args 258.Op Fl l Ar level 259.Nm 260.Ic fwdownload 261.Op device id 262.Op generic args 263.Aq Fl f Ar fw_image 264.Op Fl q 265.Op Fl s 266.Op Fl y 267.Nm 268.Ic security 269.Op device id 270.Op generic args 271.Op Fl d Ar pwd 272.Op Fl e Ar pwd 273.Op Fl f 274.Op Fl h Ar pwd 275.Op Fl k Ar pwd 276.Op Fl l Ar high|maximum 277.Op Fl q 278.Op Fl s Ar pwd 279.Op Fl T Ar timeout 280.Op Fl U Ar user|master 281.Op Fl y 282.Nm 283.Ic hpa 284.Op device id 285.Op generic args 286.Op Fl f 287.Op Fl l 288.Op Fl P 289.Op Fl p Ar pwd 290.Op Fl q 291.Op Fl s Ar max_sectors 292.Op Fl U Ar pwd 293.Op Fl y 294.Nm 295.Ic ama 296.Op device id 297.Op generic args 298.Op Fl f 299.Op Fl q 300.Op Fl s Ar max_sectors 301.Nm 302.Ic persist 303.Op device id 304.Op generic args 305.Aq Fl i Ar action | Fl o Ar action 306.Op Fl a 307.Op Fl I Ar trans_id 308.Op Fl k Ar key 309.Op Fl K Ar sa_key 310.Op Fl p 311.Op Fl R Ar rel_tgt_port 312.Op Fl s Ar scope 313.Op Fl S 314.Op Fl T Ar res_type 315.Op Fl U 316.Nm 317.Ic attrib 318.Op device id 319.Op generic args 320.Aq Fl r Ar action | Fl w Ar attrib 321.Op Fl a Ar attr_num 322.Op Fl c 323.Op Fl e Ar elem_addr 324.Op Fl F Ar form1,form2 325.Op Fl p Ar part 326.Op Fl s Ar start_addr 327.Op Fl T Ar elem_type 328.Op Fl V Ar lv_num 329.Nm 330.Ic opcodes 331.Op device id 332.Op generic args 333.Op Fl o Ar opcode 334.Op Fl s Ar service_action 335.Op Fl N 336.Op Fl T 337.Nm 338.Ic zone 339.Aq Fl c Ar cmd 340.Op Fl a 341.Op Fl l Ar lba 342.Op Fl o Ar rep_opts 343.Op Fl P Ar print_opts 344.Nm 345.Ic epc 346.Aq Fl c Ar cmd 347.Op Fl d 348.Op Fl D 349.Op Fl e 350.Op Fl H 351.Op Fl p Ar power_cond 352.Op Fl P 353.Op Fl r Ar restore_src 354.Op Fl s 355.Op Fl S Ar power_src 356.Op Fl T Ar timer 357.Nm 358.Ic timestamp 359.Op device id 360.Op generic args 361.Ao Fl r Oo Ns Fl f Ar format | Fl m | Fl U Oc | Fl s Ao Fl f Ar format Fl T Ar time | Fl U Ac Ac 362.Nm 363.Ic devtype 364.Op device id 365.Nm 366.Ic help 367.Sh DESCRIPTION 368The 369.Nm 370utility is designed to provide a way for users to access and control the 371.Fx 372CAM subsystem. 373.Pp 374The 375.Nm 376utility 377can cause a loss of data and/or system crashes if used improperly. 378Even 379expert users are encouraged to exercise caution when using this command. 380Novice users should stay away from this utility. 381.Pp 382The 383.Nm 384utility has a number of primary functions, many of which support an optional 385device identifier. 386A device identifier can take one of three forms: 387.Bl -tag -width 14n 388.It deviceUNIT 389Specify a device name and unit number combination, like "da5" or "cd3". 390.It bus:target 391Specify a bus number and target id. 392The bus number can be determined from 393the output of 394.Dq camcontrol devlist . 395The lun defaults to 0. 396.It bus:target:lun 397Specify the bus, target and lun for a device. 398(e.g.\& 1:2:0) 399.El 400.Pp 401The device identifier, if it is specified, 402.Em must 403come immediately after the function name, and before any generic or 404function-specific arguments. 405Note that the 406.Fl n 407and 408.Fl u 409arguments described below will override any device name or unit number 410specified beforehand. 411The 412.Fl n 413and 414.Fl u 415arguments will 416.Em not 417override a specified bus:target or bus:target:lun, however. 418.Pp 419Most of the 420.Nm 421primary functions support these generic arguments: 422.Bl -tag -width 14n 423.It Fl C Ar count 424SCSI command retry count. 425In order for this to work, error recovery 426.Pq Fl E 427must be turned on. 428.It Fl E 429Instruct the kernel to perform generic SCSI error recovery for the given 430command. 431This is needed in order for the retry count 432.Pq Fl C 433to be honored. 434Other than retrying commands, the generic error recovery in 435the code will generally attempt to spin up drives that are not spinning. 436It may take some other actions, depending upon the sense code returned from 437the command. 438.It Fl n Ar dev_name 439Specify the device type to operate on, e.g.\& "da", "cd". 440.It Fl Q Ar task_attr 441.Tn SCSI 442task attribute for the command, if it is a 443.Tn SCSI 444command. 445This may be ordered, simple, head, or aca. 446In most cases this is not needed. 447The default is simple, which works with all 448.Tn SCSI 449devices. 450The task attribute may also be specified numerically. 451.It Fl t Ar timeout 452SCSI command timeout in seconds. 453This overrides the default timeout for 454any given command. 455.It Fl u Ar unit_number 456Specify the device unit number, e.g.\& "1", "5". 457.It Fl v 458Be verbose, print out sense information for failed SCSI commands. 459.El 460.Pp 461Primary command functions: 462.Bl -tag -width periphlist 463.It Ic devlist 464List all physical devices (logical units) attached to the CAM subsystem. 465This also includes a list of peripheral drivers attached to each device. 466With the 467.Fl v 468argument, SCSI bus number, adapter name and unit numbers are printed as 469well. 470On the other hand, with the 471.Fl b 472argument, only the bus adapter, and unit information will be printed, and 473device information will be omitted. 474.It Ic periphlist 475List all peripheral drivers attached to a given physical device (logical 476unit). 477.It Ic tur 478Send the SCSI test unit ready (0x00) command to the given device. 479The 480.Nm 481utility will report whether the device is ready or not. 482.It Ic inquiry 483Send a SCSI inquiry command (0x12) to a device. 484By default, 485.Nm 486will print out the standard inquiry data, device serial number, and 487transfer rate information. 488The user can specify that only certain types of 489inquiry data be printed: 490.Bl -tag -width 4n 491.It Fl D 492Get the standard inquiry data. 493.It Fl S 494Print out the serial number. 495If this flag is the only one specified, 496.Nm 497will not print out "Serial Number" before the value returned by the drive. 498This is to aid in script writing. 499.It Fl R 500Print out transfer rate information. 501.El 502.It Ic identify 503Send a ATA identify command (0xec) to a device. 504.It Ic reportluns 505Send the SCSI REPORT LUNS (0xA0) command to the given device. 506By default, 507.Nm 508will print out the list of logical units (LUNs) supported by the target device. 509There are a couple of options to modify the output: 510.Bl -tag -width 14n 511.It Fl c 512Just print out a count of LUNs, not the actual LUN numbers. 513.It Fl l 514Just print out the LUNs, and do not print out the count. 515.It Fl r Ar reporttype 516Specify the type of report to request from the target: 517.Bl -tag -width 012345678 518.It default 519Return the default report. 520This is the 521.Nm 522default. 523Most targets will support this report if they support the REPORT LUNS 524command. 525.It wellknown 526Return only well known LUNs. 527.It all 528Return all available LUNs. 529.El 530.El 531.Pp 532.Nm 533will try to print out LUN numbers in a reasonable format. 534It can understand the peripheral, flat, LUN and extended LUN formats. 535.It Ic readcap 536Send the SCSI READ CAPACITY command to the given device and display 537the results. 538If the device is larger than 2TB, the SCSI READ CAPACITY (16) service 539action will be sent to obtain the full size of the device. 540By default, 541.Nm 542will print out the last logical block of the device, and the blocksize of 543the device in bytes. 544To modify the output format, use the following options: 545.Bl -tag -width 5n 546.It Fl b 547Just print out the blocksize, not the last block or device size. 548This cannot be used with 549.Fl N 550or 551.Fl s . 552.It Fl h 553Print out the device size in human readable (base 2, 1K == 1024) format. 554This implies 555.Fl N 556and cannot be used with 557.Fl q 558or 559.Fl b . 560.It Fl H 561Print out the device size in human readable (base 10, 1K == 1000) format. 562.It Fl l 563Skip sending the SCSI READ CAPACITY (10) command. 564Send only the SCSI READ CAPACITY (16) service action and report 565its results. 566When the two do not match, a quirk is needed to resolve the ambiguity. 567.It Fl N 568Print out the number of blocks in the device instead of the last logical 569block. 570.It Fl q 571Quiet, print out the numbers only (separated by a comma if 572.Fl b 573or 574.Fl s 575are not specified). 576.It Fl s 577Print out the last logical block or the size of the device only, and omit 578the blocksize. 579.El 580.Pp 581Note that this command only displays the information, it does not update 582the kernel data structures. 583Use the 584.Nm 585reprobe subcommand to do that. 586.It Ic start 587Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 588start bit set. 589.It Ic stop 590Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 591start bit cleared. 592.It Ic load 593Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 594start bit set and the load/eject bit set. 595.It Ic eject 596Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 597start bit cleared and the load/eject bit set. 598.It Ic rescan 599Tell the kernel to scan all buses in the system (with the 600.Ar all 601argument), the given bus (XPT_SCAN_BUS), bus:target:lun or device 602(XPT_SCAN_LUN) for new devices or devices that have gone away. 603The user 604may specify a scan of all buses, a single bus, or a lun. 605Scanning all luns 606on a target is not supported. 607.Pp 608If a device is specified by peripheral name and unit number, for instance 609da4, it may only be rescanned if that device currently exists in the CAM EDT 610(Existing Device Table). 611If the device is no longer there (see 612.Nm 613devlist ), 614you must use the bus:target:lun form to rescan it. 615.It Ic reprobe 616Tell the kernel to refresh the information about the device and 617notify the upper layer, 618.Xr GEOM 4 . 619This includes sending the SCSI READ CAPACITY command and updating 620the disk size visible to the rest of the system. 621.It Ic reset 622Tell the kernel to reset all buses in the system (with the 623.Ar all 624argument), the given bus (XPT_RESET_BUS) by issuing a SCSI bus 625reset for that bus, or to reset the given bus:target:lun or device 626(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after 627connecting to that device. 628Note that this can have a destructive impact 629on the system. 630.It Ic defects 631Send the 632.Tn SCSI 633READ DEFECT DATA (10) command (0x37) or the 634.Tn SCSI 635READ DEFECT DATA (12) command (0xB7) to the given device, and 636print out any combination of: the total number of defects, the primary 637defect list (PLIST), and the grown defect list (GLIST). 638.Bl -tag -width 11n 639.It Fl f Ar format 640Specify the requested format of the defect list. 641The format argument is 642required. 643Most drives support the physical sector format. 644Some drives 645support the logical block format. 646Many drives, if they do not support the 647requested format, return the data in an alternate format, along with sense 648information indicating that the requested data format is not supported. 649The 650.Nm 651utility 652attempts to detect this, and print out whatever format the drive returns. 653If the drive uses a non-standard sense code to report that it does not 654support the requested format, 655.Nm 656will probably see the error as a failure to complete the request. 657.Pp 658The format options are: 659.Bl -tag -width 9n 660.It block 661Print out the list as logical blocks. 662This is limited to 32-bit block sizes, and isn't supported by many modern 663drives. 664.It longblock 665Print out the list as logical blocks. 666This option uses a 64-bit block size. 667.It bfi 668Print out the list in bytes from index format. 669.It extbfi 670Print out the list in extended bytes from index format. 671The extended format allows for ranges of blocks to be printed. 672.It phys 673Print out the list in physical sector format. 674Most drives support this format. 675.It extphys 676Print out the list in extended physical sector format. 677The extended format allows for ranges of blocks to be printed. 678.El 679.It Fl G 680Print out the grown defect list. 681This is a list of bad blocks that have 682been remapped since the disk left the factory. 683.It Fl P 684Print out the primary defect list. 685This is the list of defects that were present in the factory. 686.It Fl q 687When printing status information with 688.Fl s , 689only print the number of defects. 690.It Fl s 691Just print the number of defects, not the list of defects. 692.It Fl S Ar offset 693Specify the starting offset into the defect list. 694This implies using the 695.Tn SCSI 696READ DEFECT DATA (12) command, as the 10 byte version of the command 697doesn't support the address descriptor index field. 698Not all drives support the 12 byte command, and some drives that support 699the 12 byte command don't support the address descriptor index field. 700.It Fl X 701Print out defects in hexadecimal (base 16) form instead of base 10 form. 702.El 703.Pp 704If neither 705.Fl P 706nor 707.Fl G 708is specified, 709.Nm 710will print out the number of defects given in the READ DEFECT DATA header 711returned from the drive. 712Some drives will report 0 defects if neither the primary or grown defect 713lists are requested. 714.It Ic modepage 715Allows the user to display and optionally edit a SCSI mode page. 716The mode 717page formats are located in 718.Pa /usr/share/misc/scsi_modes . 719This can be overridden by specifying a different file in the 720.Ev SCSI_MODES 721environment variable. 722The 723.Ic modepage 724command takes several arguments: 725.Bl -tag -width 12n 726.It Fl d 727Disable block descriptors for mode sense. 728.It Fl b 729Displays mode page data in binary format. 730.It Fl e 731This flag allows the user to edit values in the mode page. 732The user may 733either edit mode page values with the text editor pointed to by his 734.Ev EDITOR 735environment variable, or supply mode page values via standard input, using 736the same format that 737.Nm 738uses to display mode page values. 739The editor will be invoked if 740.Nm 741detects that standard input is terminal. 742.It Fl l 743Lists all available mode pages. 744If specified more then once, also lists subpages. 745.It Fl m Ar page[,subpage] 746This specifies the number of the mode page and optionally subpage the user 747would like to view and/or edit. 748This argument is mandatory unless 749.Fl l 750is specified. 751.It Fl P Ar pgctl 752This allows the user to specify the page control field. 753Possible values are: 754.Bl -tag -width xxx -compact 755.It 0 756Current values 757.It 1 758Changeable values 759.It 2 760Default values 761.It 3 762Saved values 763.El 764.El 765.It Ic cmd 766Allows the user to send an arbitrary ATA or SCSI CDB to any device. 767The 768.Ic cmd 769function requires the 770.Fl c 771argument to specify SCSI CDB or the 772.Fl a 773argument to specify ATA Command Block registers values. 774Other arguments are optional, depending on 775the command type. 776The command and data specification syntax is documented 777in 778.Xr cam_cdbparse 3 . 779NOTE: If the CDB specified causes data to be transferred to or from the 780SCSI device in question, you MUST specify either 781.Fl i 782or 783.Fl o . 784.Bl -tag -width 17n 785.It Fl a Ar cmd Op args 786This specifies the content of 12 ATA Command Block registers (command, 787features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp. 788lba_high_exp, features_exp, sector_count, sector_count_exp). 789.It Fl c Ar cmd Op args 790This specifies the SCSI CDB. 791SCSI CDBs may be 6, 10, 12 or 16 bytes. 792.It Fl d 793Specifies DMA protocol to be used for ATA command. 794.It Fl f 795Specifies FPDMA (NCQ) protocol to be used for ATA command. 796.It Fl i Ar len Ar fmt 797This specifies the amount of data to read, and how it should be displayed. 798If the format is 799.Sq - , 800.Ar len 801bytes of data will be read from the device and written to standard output. 802.It Fl o Ar len Ar fmt Op args 803This specifies the amount of data to be written to a device, and the data 804that is to be written. 805If the format is 806.Sq - , 807.Ar len 808bytes of data will be read from standard input and written to the device. 809.It Fl r Ar fmt 810This specifies that 11 result ATA Command Block registers should be displayed 811(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp, 812lba_high_exp, sector_count, sector_count_exp), and how. 813If the format is 814.Sq - , 81511 result registers will be written to standard output in hex. 816.El 817.It Ic smpcmd 818Allows the user to send an arbitrary Serial 819Management Protocol (SMP) command to a device. 820The 821.Ic smpcmd 822function requires the 823.Fl r 824argument to specify the SMP request to be sent, and the 825.Fl R 826argument to specify the format of the SMP response. 827The syntax for the SMP request and response arguments is documented in 828.Xr cam_cdbparse 3 . 829.Pp 830Note that SAS adapters that support SMP passthrough (at least the currently 831known adapters) do not accept CRC bytes from the user in the request and do 832not pass CRC bytes back to the user in the response. 833Therefore users should not include the CRC bytes in the length of the 834request and not expect CRC bytes to be returned in the response. 835.Bl -tag -width 17n 836.It Fl r Ar len Ar fmt Op args 837This specifies the size of the SMP request, without the CRC bytes, and the 838SMP request format. 839If the format is 840.Sq - , 841.Ar len 842bytes of data will be read from standard input and written as the SMP 843request. 844.It Fl R Ar len Ar fmt Op args 845This specifies the size of the buffer allocated for the SMP response, and 846the SMP response format. 847If the format is 848.Sq - , 849.Ar len 850bytes of data will be allocated for the response and the response will be 851written to standard output. 852.El 853.It Ic smprg 854Allows the user to send the Serial Management Protocol (SMP) Report General 855command to a device. 856.Nm 857will display the data returned by the Report General command. 858If the SMP target supports the long response format, the additional data 859will be requested and displayed automatically. 860.Bl -tag -width 8n 861.It Fl l 862Request the long response format only. 863Not all SMP targets support the long response format. 864This option causes 865.Nm 866to skip sending the initial report general request without the long bit set 867and only issue a report general request with the long bit set. 868.El 869.It Ic smppc 870Allows the user to issue the Serial Management Protocol (SMP) PHY Control 871command to a device. 872This function should be used with some caution, as it can render devices 873inaccessible, and could potentially cause data corruption as well. 874The 875.Fl p 876argument is required to specify the PHY to operate on. 877.Bl -tag -width 17n 878.It Fl p Ar phy 879Specify the PHY to operate on. 880This argument is required. 881.It Fl l 882Request the long request/response format. 883Not all SMP targets support the long response format. 884For the PHY Control command, this currently only affects whether the 885request length is set to a value other than 0. 886.It Fl o Ar operation 887Specify a PHY control operation. 888Only one 889.Fl o 890operation may be specified. 891The operation may be specified numerically (in decimal, hexadecimal, or octal) 892or one of the following operation names may be specified: 893.Bl -tag -width 16n 894.It nop 895No operation. 896It is not necessary to specify this argument. 897.It linkreset 898Send the LINK RESET command to the phy. 899.It hardreset 900Send the HARD RESET command to the phy. 901.It disable 902Send the DISABLE command to the phy. 903Note that the LINK RESET or HARD RESET commands should re-enable the phy. 904.It clearerrlog 905Send the CLEAR ERROR LOG command. 906This clears the error log counters for the specified phy. 907.It clearaffiliation 908Send the CLEAR AFFILIATION command. 909This clears the affiliation from the STP initiator port with the same SAS 910address as the SMP initiator that requests the clear operation. 911.It sataportsel 912Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy. 913This will cause a SATA port selector to use the given phy as its active phy 914and make the other phy inactive. 915.It clearitnl 916Send the CLEAR STP I_T NEXUS LOSS command to the PHY. 917.It setdevname 918Send the SET ATTACHED DEVICE NAME command to the PHY. 919This requires the 920.Fl d 921argument to specify the device name. 922.El 923.It Fl d Ar name 924Specify the attached device name. 925This option is needed with the 926.Fl o Ar setdevname 927phy operation. 928The name is a 64-bit number, and can be specified in decimal, hexadecimal 929or octal format. 930.It Fl m Ar rate 931Set the minimum physical link rate for the phy. 932This is a numeric argument. 933Currently known link rates are: 934.Bl -tag -width 5n 935.It 0x0 936Do not change current value. 937.It 0x8 9381.5 Gbps 939.It 0x9 9403 Gbps 941.It 0xa 9426 Gbps 943.El 944.Pp 945Other values may be specified for newer physical link rates. 946.It Fl M Ar rate 947Set the maximum physical link rate for the phy. 948This is a numeric argument. 949See the 950.Fl m 951argument description for known link rate arguments. 952.It Fl T Ar pp_timeout 953Set the partial pathway timeout value, in microseconds. 954See the 955.Tn ANSI 956.Tn SAS 957Protocol Layer (SPL) 958specification for more information on this field. 959.It Fl a Ar enable|disable 960Enable or disable SATA slumber phy power conditions. 961.It Fl A Ar enable|disable 962Enable or disable SATA partial power conditions. 963.It Fl s Ar enable|disable 964Enable or disable SAS slumber phy power conditions. 965.It Fl S Ar enable|disable 966Enable or disable SAS partial phy power conditions. 967.El 968.It Ic smpphylist 969List phys attached to a SAS expander, the address of the end device 970attached to the phy, and the inquiry data for that device and peripheral 971devices attached to that device. 972The inquiry data and peripheral devices are displayed if available. 973.Bl -tag -width 5n 974.It Fl l 975Turn on the long response format for the underlying SMP commands used for 976this command. 977.It Fl q 978Only print out phys that are attached to a device in the CAM EDT (Existing 979Device Table). 980.El 981.It Ic smpmaninfo 982Send the SMP Report Manufacturer Information command to the device and 983display the response. 984.Bl -tag -width 5n 985.It Fl l 986Turn on the long response format for the underlying SMP commands used for 987this command. 988.El 989.It Ic debug 990Turn on CAM debugging printfs in the kernel. 991This requires options CAMDEBUG 992in your kernel config file. 993WARNING: enabling debugging printfs currently 994causes an EXTREME number of kernel printfs. 995You may have difficulty 996turning off the debugging printfs once they start, since the kernel will be 997busy printing messages and unable to service other requests quickly. 998The 999.Ic debug 1000function takes a number of arguments: 1001.Bl -tag -width 18n 1002.It Fl I 1003Enable CAM_DEBUG_INFO printfs. 1004.It Fl P 1005Enable CAM_DEBUG_PERIPH printfs. 1006.It Fl T 1007Enable CAM_DEBUG_TRACE printfs. 1008.It Fl S 1009Enable CAM_DEBUG_SUBTRACE printfs. 1010.It Fl X 1011Enable CAM_DEBUG_XPT printfs. 1012.It Fl c 1013Enable CAM_DEBUG_CDB printfs. 1014This will cause the kernel to print out the 1015SCSI CDBs sent to the specified device(s). 1016.It Fl p 1017Enable CAM_DEBUG_PROBE printfs. 1018.It all 1019Enable debugging for all devices. 1020.It off 1021Turn off debugging for all devices 1022.It bus Ns Op :target Ns Op :lun 1023Turn on debugging for the given bus, target or lun. 1024If the lun or target 1025and lun are not specified, they are wildcarded. 1026(i.e., just specifying a 1027bus turns on debugging printfs for all devices on that bus.) 1028.El 1029.It Ic tags 1030Show or set the number of "tagged openings" or simultaneous transactions 1031we attempt to queue to a particular device. 1032By default, the 1033.Ic tags 1034command, with no command-specific arguments (i.e., only generic arguments) 1035prints out the "soft" maximum number of transactions that can be queued to 1036the device in question. 1037For more detailed information, use the 1038.Fl v 1039argument described below. 1040.Bl -tag -width 7n 1041.It Fl N Ar tags 1042Set the number of tags for the given device. 1043This must be between the 1044minimum and maximum number set in the kernel quirk table. 1045The default for 1046most devices that support tagged queueing is a minimum of 2 and a maximum 1047of 255. 1048The minimum and maximum values for a given device may be 1049determined by using the 1050.Fl v 1051switch. 1052The meaning of the 1053.Fl v 1054switch for this 1055.Nm 1056subcommand is described below. 1057.It Fl q 1058Be quiet, and do not report the number of tags. 1059This is generally used when 1060setting the number of tags. 1061.It Fl v 1062The verbose flag has special functionality for the 1063.Em tags 1064argument. 1065It causes 1066.Nm 1067to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: 1068.Bl -tag -width 13n 1069.It dev_openings 1070This is the amount of capacity for transactions queued to a given device. 1071.It dev_active 1072This is the number of transactions currently queued to a device. 1073.It devq_openings 1074This is the kernel queue space for transactions. 1075This count usually mirrors 1076dev_openings except during error recovery operations when 1077the device queue is frozen (device is not allowed to receive 1078commands), the number of dev_openings is reduced, or transaction 1079replay is occurring. 1080.It devq_queued 1081This is the number of transactions waiting in the kernel queue for capacity 1082on the device. 1083This number is usually zero unless error recovery is in 1084progress. 1085.It held 1086The held count is the number of CCBs held by peripheral drivers that have 1087either just been completed or are about to be released to the transport 1088layer for service by a device. 1089Held CCBs reserve capacity on a given 1090device. 1091.It mintags 1092This is the current "hard" minimum number of transactions that can be 1093queued to a device at once. 1094The 1095.Ar dev_openings 1096value above cannot go below this number. 1097The default value for 1098.Ar mintags 1099is 2, although it may be set higher or lower for various devices. 1100.It maxtags 1101This is the "hard" maximum number of transactions that can be queued to a 1102device at one time. 1103The 1104.Ar dev_openings 1105value cannot go above this number. 1106The default value for 1107.Ar maxtags 1108is 255, although it may be set higher or lower for various devices. 1109.El 1110.El 1111.It Ic negotiate 1112Show or negotiate various communication parameters. 1113Some controllers may 1114not support setting or changing some of these values. 1115For instance, the 1116Adaptec 174x controllers do not support changing a device's sync rate or 1117offset. 1118The 1119.Nm 1120utility 1121will not attempt to set the parameter if the controller indicates that it 1122does not support setting the parameter. 1123To find out what the controller 1124supports, use the 1125.Fl v 1126flag. 1127The meaning of the 1128.Fl v 1129flag for the 1130.Ic negotiate 1131command is described below. 1132Also, some controller drivers do not support 1133setting negotiation parameters, even if the underlying controller supports 1134negotiation changes. 1135Some controllers, such as the Advansys wide 1136controllers, support enabling and disabling synchronous negotiation for 1137a device, but do not support setting the synchronous negotiation rate. 1138.Bl -tag -width 17n 1139.It Fl a 1140Attempt to make the negotiation settings take effect immediately by sending 1141a Test Unit Ready command to the device. 1142.It Fl c 1143Show or set current negotiation settings. 1144This is the default. 1145.It Fl D Ar enable|disable 1146Enable or disable disconnection. 1147.It Fl M Ar mode 1148Set ATA mode. 1149.It Fl O Ar offset 1150Set the command delay offset. 1151.It Fl q 1152Be quiet, do not print anything. 1153This is generally useful when you want to 1154set a parameter, but do not want any status information. 1155.It Fl R Ar syncrate 1156Change the synchronization rate for a device. 1157The sync rate is a floating 1158point value specified in MHz. 1159So, for instance, 1160.Sq 20.000 1161is a legal value, as is 1162.Sq 20 . 1163.It Fl T Ar enable|disable 1164Enable or disable tagged queueing for a device. 1165.It Fl U 1166Show or set user negotiation settings. 1167The default is to show or set 1168current negotiation settings. 1169.It Fl v 1170The verbose switch has special meaning for the 1171.Ic negotiate 1172subcommand. 1173It causes 1174.Nm 1175to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the 1176controller driver. 1177.It Fl W Ar bus_width 1178Specify the bus width to negotiate with a device. 1179The bus width is 1180specified in bits. 1181The only useful values to specify are 8, 16, and 32 1182bits. 1183The controller must support the bus width in question in order for 1184the setting to take effect. 1185.El 1186.Pp 1187In general, sync rate and offset settings will not take effect for a 1188device until a command has been sent to the device. 1189The 1190.Fl a 1191switch above will automatically send a Test Unit Ready to the device so 1192negotiation parameters will take effect. 1193.It Ic format 1194Issue the 1195.Tn SCSI 1196FORMAT UNIT command to the named device. 1197.Pp 1198.Em WARNING! WARNING! WARNING! 1199.Pp 1200Low level formatting a disk will destroy ALL data on the disk. 1201Use 1202extreme caution when issuing this command. 1203Many users low-level format 1204disks that do not really need to be low-level formatted. 1205There are 1206relatively few scenarios that call for low-level formatting a disk. 1207One reason for 1208low-level formatting a disk is to initialize the disk after changing 1209its physical sector size. 1210Another reason for low-level formatting a disk 1211is to revive the disk if you are getting "medium format corrupted" errors 1212from the disk in response to read and write requests. 1213.Pp 1214Some disks take longer than others to format. 1215Users should specify a 1216timeout long enough to allow the format to complete. 1217The default format 1218timeout is 3 hours, which should be long enough for most disks. 1219Some hard 1220disks will complete a format operation in a very short period of time 1221(on the order of 5 minutes or less). 1222This is often because the drive 1223does not really support the FORMAT UNIT command -- it just accepts the 1224command, waits a few minutes and then returns it. 1225.Pp 1226The 1227.Sq format 1228subcommand takes several arguments that modify its default behavior. 1229The 1230.Fl q 1231and 1232.Fl y 1233arguments can be useful for scripts. 1234.Bl -tag -width 6n 1235.It Fl q 1236Be quiet, do not print any status messages. 1237This option will not disable 1238the questions, however. 1239To disable questions, use the 1240.Fl y 1241argument, below. 1242.It Fl r 1243Run in 1244.Dq report only 1245mode. 1246This will report status on a format that is already running on the drive. 1247.It Fl w 1248Issue a non-immediate format command. 1249By default, 1250.Nm 1251issues the FORMAT UNIT command with the immediate bit set. 1252This tells the 1253device to immediately return the format command, before the format has 1254actually completed. 1255Then, 1256.Nm 1257gathers 1258.Tn SCSI 1259sense information from the device every second to determine how far along 1260in the format process it is. 1261If the 1262.Fl w 1263argument is specified, 1264.Nm 1265will issue a non-immediate format command, and will be unable to print any 1266information to let the user know what percentage of the disk has been 1267formatted. 1268.It Fl y 1269Do not ask any questions. 1270By default, 1271.Nm 1272will ask the user if he/she really wants to format the disk in question, 1273and also if the default format command timeout is acceptable. 1274The user 1275will not be asked about the timeout if a timeout is specified on the 1276command line. 1277.El 1278.It Ic sanitize 1279Issue the 1280.Tn SCSI 1281SANITIZE command to the named device. 1282.Pp 1283.Em WARNING! WARNING! WARNING! 1284.Pp 1285ALL data in the cache and on the disk will be destroyed or made inaccessible. 1286Recovery of the data is not possible. 1287Use extreme caution when issuing this command. 1288.Pp 1289The 1290.Sq sanitize 1291subcommand takes several arguments that modify its default behavior. 1292The 1293.Fl q 1294and 1295.Fl y 1296arguments can be useful for scripts. 1297.Bl -tag -width 6n 1298.It Fl a Ar operation 1299Specify the sanitize operation to perform. 1300.Bl -tag -width 16n 1301.It overwrite 1302Perform an overwrite operation by writing a user supplied 1303data pattern to the device one or more times. 1304The pattern is given by the 1305.Fl P 1306argument. 1307The number of times is given by the 1308.Fl c 1309argument. 1310.It block 1311Perform a block erase operation. 1312All the device's blocks are set to a vendor defined 1313value, typically zero. 1314.It crypto 1315Perform a cryptographic erase operation. 1316The encryption keys are changed to prevent the decryption 1317of the data. 1318.It exitfailure 1319Exits a previously failed sanitize operation. 1320A failed sanitize operation can only be exited if it was 1321run in the unrestricted completion mode, as provided by the 1322.Fl U 1323argument. 1324.El 1325.It Fl c Ar passes 1326The number of passes when performing an 1327.Sq overwrite 1328operation. 1329Valid values are between 1 and 31. 1330The default is 1. 1331.It Fl I 1332When performing an 1333.Sq overwrite 1334operation, the pattern is inverted between consecutive passes. 1335.It Fl P Ar pattern 1336Path to the file containing the pattern to use when 1337performing an 1338.Sq overwrite 1339operation. 1340The pattern is repeated as needed to fill each block. 1341.It Fl q 1342Be quiet, do not print any status messages. 1343This option will not disable 1344the questions, however. 1345To disable questions, use the 1346.Fl y 1347argument, below. 1348.It Fl U 1349Perform the sanitize in the unrestricted completion mode. 1350If the operation fails, it can later be exited with the 1351.Sq exitfailure 1352operation. 1353.It Fl r 1354Run in 1355.Dq report only 1356mode. 1357This will report status on a sanitize that is already running on the drive. 1358.It Fl w 1359Issue a non-immediate sanitize command. 1360By default, 1361.Nm 1362issues the SANITIZE command with the immediate bit set. 1363This tells the 1364device to immediately return the sanitize command, before 1365the sanitize has actually completed. 1366Then, 1367.Nm 1368gathers 1369.Tn SCSI 1370sense information from the device every second to determine how far along 1371in the sanitize process it is. 1372If the 1373.Fl w 1374argument is specified, 1375.Nm 1376will issue a non-immediate sanitize command, and will be unable to print any 1377information to let the user know what percentage of the disk has been 1378sanitized. 1379.It Fl y 1380Do not ask any questions. 1381By default, 1382.Nm 1383will ask the user if he/she really wants to sanitize the disk in question, 1384and also if the default sanitize command timeout is acceptable. 1385The user 1386will not be asked about the timeout if a timeout is specified on the 1387command line. 1388.El 1389.It Ic idle 1390Put ATA device into IDLE state. 1391Optional parameter 1392.Pq Fl t 1393specifies automatic standby timer value in seconds. 1394Value 0 disables timer. 1395.It Ic standby 1396Put ATA device into STANDBY state. 1397Optional parameter 1398.Pq Fl t 1399specifies automatic standby timer value in seconds. 1400Value 0 disables timer. 1401.It Ic sleep 1402Put ATA device into SLEEP state. 1403Note that the only way get device out of 1404this state may be reset. 1405.It Ic powermode 1406Report ATA device power mode. 1407.It Ic apm 1408It optional parameter 1409.Pq Fl l 1410specified, enables and sets advanced power management level, where 14111 -- minimum power, 127 -- maximum performance with standby, 1412128 -- minimum power without standby, 254 -- maximum performance. 1413If not specified -- APM is disabled. 1414.It Ic aam 1415It optional parameter 1416.Pq Fl l 1417specified, enables and sets automatic acoustic management level, where 14181 -- minimum noise, 254 -- maximum performance. 1419If not specified -- AAM is disabled. 1420.It Ic security 1421Update or report security settings, using an ATA identify command (0xec). 1422By default, 1423.Nm 1424will print out the security support and associated settings of the device. 1425The 1426.Ic security 1427command takes several arguments: 1428.Bl -tag -width 0n 1429.It Fl d Ar pwd 1430.Pp 1431Disable device security using the given password for the selected user according 1432to the devices configured security level. 1433.It Fl e Ar pwd 1434.Pp 1435Erase the device using the given password for the selected user. 1436.Pp 1437.Em WARNING! WARNING! WARNING! 1438.Pp 1439Issuing a secure erase will 1440.Em ERASE ALL 1441user data on the device and may take several hours to complete. 1442.Pp 1443When this command is used against an SSD drive all its cells will be marked as 1444empty, restoring it to factory default write performance. 1445For SSD's this action 1446usually takes just a few seconds. 1447.It Fl f 1448.Pp 1449Freeze the security configuration of the specified device. 1450.Pp 1451After command completion any other commands that update the device lock mode 1452shall be command aborted. 1453Frozen mode is disabled by power-off or hardware reset. 1454.It Fl h Ar pwd 1455.Pp 1456Enhanced erase the device using the given password for the selected user. 1457.Pp 1458.Em WARNING! WARNING! WARNING! 1459.Pp 1460Issuing an enhanced secure erase will 1461.Em ERASE ALL 1462user data on the device and may take several hours to complete. 1463.Pp 1464An enhanced erase writes predetermined data patterns to all user data areas, 1465all previously written user data shall be overwritten, including sectors that 1466are no longer in use due to reallocation. 1467.It Fl k Ar pwd 1468.Pp 1469Unlock the device using the given password for the selected user according to 1470the devices configured security level. 1471.It Fl l Ar high|maximum 1472.Pp 1473Specifies which security level to set when issuing a 1474.Fl s Ar pwd 1475command. 1476The security level determines device behavior when the master 1477password is used to unlock the device. 1478When the security level is set to high 1479the device requires the unlock command and the master password to unlock. 1480When the security level is set to maximum the device requires a secure erase 1481with the master password to unlock. 1482.Pp 1483This option must be used in conjunction with one of the security action commands. 1484.Pp 1485Defaults to 1486.Em high 1487.It Fl q 1488.Pp 1489Be quiet, do not print any status messages. 1490This option will not disable the questions, however. 1491To disable questions, use the 1492.Fl y 1493argument, below. 1494.It Fl s Ar pwd 1495.Pp 1496Password the device (enable security) using the given password for the selected 1497user. 1498This option can be combined with other options such as 1499.Fl e Em pwd 1500.Pp 1501A master password may be set in a addition to the user password. The purpose of 1502the master password is to allow an administrator to establish a password that 1503is kept secret from the user, and which may be used to unlock the device if the 1504user password is lost. 1505.Pp 1506.Em Note: 1507Setting the master password does not enable device security. 1508.Pp 1509If the master password is set and the drive supports a Master Revision Code 1510feature the Master Password Revision Code will be decremented. 1511.It Fl T Ar timeout 1512.Pp 1513Overrides the default timeout, specified in seconds, used for both 1514.Fl e 1515and 1516.Fl h 1517this is useful if your system has problems processing long timeouts correctly. 1518.Pp 1519Usually the timeout is calculated from the information stored on the drive if 1520present, otherwise it defaults to 2 hours. 1521.It Fl U Ar user|master 1522.Pp 1523Specifies which user to set / use for the running action command, valid values 1524are user or master and defaults to master if not set. 1525.Pp 1526This option must be used in conjunction with one of the security action commands. 1527.Pp 1528Defaults to 1529.Em master 1530.It Fl y 1531.Pp 1532Confirm yes to dangerous options such as 1533.Fl e 1534without prompting for confirmation. 1535.El 1536.Pp 1537If the password specified for any action commands does not match the configured 1538password for the specified user the command will fail. 1539.Pp 1540The password in all cases is limited to 32 characters, longer passwords will 1541fail. 1542.It Ic hpa 1543Update or report Host Protected Area details. 1544By default 1545.Nm 1546will print out the HPA support and associated settings of the device. 1547The 1548.Ic hpa 1549command takes several optional arguments: 1550.Bl -tag -width 0n 1551.It Fl f 1552.Pp 1553Freeze the HPA configuration of the specified device. 1554.Pp 1555After command completion any other commands that update the HPA configuration 1556shall be command aborted. 1557Frozen mode is disabled by power-off or hardware reset. 1558.It Fl l 1559.Pp 1560Lock the HPA configuration of the device until a successful call to unlock or 1561the next power-on reset occurs. 1562.It Fl P 1563.Pp 1564Make the HPA max sectors persist across power-on reset or a hardware reset. 1565This must be used in combination with 1566.Fl s Ar max_sectors 1567. 1568.It Fl p Ar pwd 1569.Pp 1570Set the HPA configuration password required for unlock calls. 1571.It Fl q 1572.Pp 1573Be quiet, do not print any status messages. 1574This option will not disable the questions. 1575To disable questions, use the 1576.Fl y 1577argument, below. 1578.It Fl s Ar max_sectors 1579.Pp 1580Configures the maximum user accessible sectors of the device. 1581This will change the number of sectors the device reports. 1582.Pp 1583.Em WARNING! WARNING! WARNING! 1584.Pp 1585Changing the max sectors of a device using this option will make the data on 1586the device beyond the specified value inaccessible. 1587.Pp 1588Only one successful 1589.Fl s Ar max_sectors 1590call can be made without a power-on reset or a hardware reset of the device. 1591.It Fl U Ar pwd 1592.Pp 1593Unlock the HPA configuration of the specified device using the given password. 1594If the password specified does not match the password configured via 1595.Fl p Ar pwd 1596the command will fail. 1597.Pp 1598After 5 failed unlock calls, due to password miss-match, the device will refuse 1599additional unlock calls until after a power-on reset. 1600.It Fl y 1601.Pp 1602Confirm yes to dangerous options such as 1603.Fl e 1604without prompting for confirmation 1605.El 1606.Pp 1607The password for all HPA commands is limited to 32 characters, longer passwords 1608will fail. 1609.It Ic ama 1610Update or report Accessible Max Address Configuration. 1611By default 1612.Nm 1613will print out the Accessible Max Address Configuration support and associated 1614settings of the device. 1615The 1616.Ic ama 1617command takes several optional arguments: 1618.Bl -tag -width 0n 1619.It Fl f 1620.Pp 1621Freeze the Accessible Max Address Configuration of the specified device. 1622.Pp 1623After command completion any other commands that update the configuration 1624shall be command aborted. 1625Frozen mode is disabled by power-off. 1626.It Fl q 1627.Pp 1628Be quiet, do not print any status messages. 1629.It Fl s Ar max_sectors 1630.Pp 1631Configures the maximum user accessible sectors of the device. 1632This will change the number of sectors the device reports. 1633.Pp 1634.Em WARNING! WARNING! WARNING! 1635.Pp 1636Changing the max sectors of a device using this option will make the data on 1637the device beyond the specified value indeterminate. 1638.Pp 1639Only one successful 1640.Fl s Ar max_sectors 1641call can be made without a power-on reset of the device. 1642.El 1643.It Ic fwdownload 1644Program firmware of the named 1645.Tn SCSI 1646or ATA device using the image file provided. 1647.Pp 1648If the device is a 1649.Tn SCSI 1650device and it provides a recommended timeout for the WRITE BUFFER command 1651(see the 1652.Nm 1653opcodes subcommand), that timeout will be used for the firmware download. 1654The drive-recommended timeout value may be overridden on the command line 1655with the 1656.Fl t 1657option. 1658.Pp 1659Current list of supported vendors for SCSI/SAS drives: 1660.Bl -tag -width 10n 1661.It HGST 1662Tested with 4TB SAS drives, model number HUS724040ALS640. 1663.It HITACHI 1664.It HP 1665.It IBM 1666Tested with LTO-5 (ULTRIUM-HH5) and LTO-6 (ULTRIUM-HH6) tape drives. 1667There is a separate table entry for hard drives, because the update method 1668for hard drives is different than the method for tape drives. 1669.It PLEXTOR 1670.It QUALSTAR 1671.It QUANTUM 1672.It SAMSUNG 1673Tested with SM1625 SSDs. 1674.It SEAGATE 1675Tested with Constellation ES (ST32000444SS), ES.2 (ST33000651SS) and 1676ES.3 (ST1000NM0023) drives. 1677.It SmrtStor 1678Tested with 400GB Optimus SSDs (TXA2D20400GA6001). 1679.El 1680.Pp 1681.Em WARNING! WARNING! WARNING! 1682.Pp 1683Little testing has been done to make sure that different device models from 1684each vendor work correctly with the fwdownload command. 1685A vendor name appearing in the supported list means only that firmware of at 1686least one device type from that vendor has successfully been programmed with 1687the fwdownload command. 1688Extra caution should be taken when using this command since there is no 1689guarantee it will not break a device from the listed vendors. 1690Ensure that you have a recent backup of the data on the device before 1691performing a firmware update. 1692.Pp 1693Note that unknown 1694.Tn SCSI 1695protocol devices will not be programmed, since there is little chance of 1696the firmware download succeeding. 1697.Pp 1698.Nm 1699will currently attempt a firmware download to any 1700.Tn ATA 1701or 1702.Tn SATA 1703device, since the standard 1704.Tn ATA 1705DOWNLOAD MICROCODE command may work. 1706Firmware downloads to 1707.Tn ATA 1708and 1709.Tn SATA 1710devices are supported for devices connected 1711to standard 1712.Tn ATA 1713and 1714.Tn SATA 1715controllers, and devices connected to SAS controllers 1716with 1717.Tn SCSI 1718to 1719.Tn ATA 1720translation capability. 1721In the latter case, 1722.Nm 1723uses the 1724.Tn SCSI 1725.Tn ATA 1726PASS-THROUGH command to send the 1727.Tn ATA 1728DOWNLOAD MICROCODE command to the drive. 1729Some 1730.Tn SCSI 1731to 1732.Tn ATA 1733translation implementations don't work fully when translating 1734.Tn SCSI 1735WRITE BUFFER commands to 1736.Tn ATA 1737DOWNLOAD MICROCODE commands, but do support 1738.Tn ATA 1739passthrough well enough to do a firmware download. 1740.Bl -tag -width 11n 1741.It Fl f Ar fw_image 1742Path to the firmware image file to be downloaded to the specified device. 1743.It Fl q 1744Do not print informational messages, only print errors. 1745This option should be used with the 1746.Fl y 1747option to suppress all output. 1748.It Fl s 1749Run in simulation mode. 1750Device checks are run and the confirmation dialog is shown, but no firmware 1751download will occur. 1752.It Fl v 1753Show 1754.Tn SCSI 1755or 1756.Tn ATA 1757errors in the event of a failure. 1758.Pp 1759In simulation mode, print out the 1760.Tn SCSI 1761CDB 1762or 1763.Tn ATA 1764register values that would be used for the firmware download command. 1765.It Fl y 1766Do not ask for confirmation. 1767.El 1768.It Ic persist 1769Persistent reservation support. 1770Persistent reservations are a way to reserve a particular 1771.Tn SCSI 1772LUN for use by one or more 1773.Tn SCSI 1774initiators. 1775If the 1776.Fl i 1777option is specified, 1778.Nm 1779will issue the 1780.Tn SCSI 1781PERSISTENT RESERVE IN 1782command using the requested service action. 1783If the 1784.Fl o 1785option is specified, 1786.Nm 1787will issue the 1788.Tn SCSI 1789PERSISTENT RESERVE OUT 1790command using the requested service action. 1791One of those two options is required. 1792.Pp 1793Persistent reservations are complex, and fully explaining them is outside 1794the scope of this manual. 1795Please visit 1796http://www.t10.org 1797and download the latest SPC spec for a full explanation of persistent 1798reservations. 1799.Bl -tag -width 8n 1800.It Fl i Ar mode 1801Specify the service action for the PERSISTENT RESERVE IN command. 1802Supported service actions: 1803.Bl -tag -width 19n 1804.It read_keys 1805Report the current persistent reservation generation (PRgeneration) and any 1806registered keys. 1807.It read_reservation 1808Report the persistent reservation, if any. 1809.It report_capabilities 1810Report the persistent reservation capabilities of the LUN. 1811.It read_full_status 1812Report the full status of persistent reservations on the LUN. 1813.El 1814.It Fl o Ar mode 1815Specify the service action for the PERSISTENT RESERVE OUT command. 1816For service actions like register that are components of other service 1817action names, the entire name must be specified. 1818Otherwise, enough of the service action name must be specified to 1819distinguish it from other possible service actions. 1820Supported service actions: 1821.Bl -tag -width 15n 1822.It register 1823Register a reservation key with the LUN or unregister a reservation key. 1824To register a key, specify the requested key as the Service Action 1825Reservation Key. 1826To unregister a key, specify the previously registered key as the 1827Reservation Key. 1828To change a key, specify the old key as the Reservation Key and the new 1829key as the Service Action Reservation Key. 1830.It register_ignore 1831This is similar to the register subcommand, except that the Reservation Key 1832is ignored. 1833The Service Action Reservation Key will overwrite any previous key 1834registered for the initiator. 1835.It reserve 1836Create a reservation. 1837A key must be registered with the LUN before the LUN can be reserved, and 1838it must be specified as the Reservation Key. 1839The type of reservation must also be specified. 1840The scope defaults to LUN scope (LU_SCOPE), but may be changed. 1841.It release 1842Release a reservation. 1843The Reservation Key must be specified. 1844.It clear 1845Release a reservation and remove all keys from the device. 1846The Reservation Key must be specified. 1847.It preempt 1848Remove a reservation belonging to another initiator. 1849The Reservation Key must be specified. 1850The Service Action Reservation Key may be specified, depending on the 1851operation being performed. 1852.It preempt_abort 1853Remove a reservation belonging to another initiator and abort all 1854outstanding commands from that initiator. 1855The Reservation Key must be specified. 1856The Service Action Reservation Key may be specified, depending on the 1857operation being performed. 1858.It register_move 1859Register another initiator with the LUN, and establish a reservation on the 1860LUN for that initiator. 1861The Reservation Key and Service Action Reservation Key must be specified. 1862.It replace_lost 1863Replace Lost Reservation information. 1864.El 1865.It Fl a 1866Set the All Target Ports (ALL_TG_PT) bit. 1867This requests that the key registration be applied to all target ports and 1868not just the particular target port that receives the command. 1869This only applies to the register and register_ignore actions. 1870.It Fl I Ar tid 1871Specify a Transport ID. 1872This only applies to the Register and Register and Move service actions for 1873Persistent Reserve Out. 1874Multiple Transport IDs may be specified with multiple 1875.Fl I 1876arguments. 1877With the Register service action, specifying one or more Transport IDs 1878implicitly enables the 1879.Fl S 1880option which turns on the SPEC_I_PT bit. 1881Transport IDs generally have the format protocol,id. 1882.Bl -tag -width 5n 1883.It SAS 1884A SAS Transport ID consists of 1885.Dq sas, 1886followed by a 64-bit SAS address. 1887For example: 1888.Pp 1889.Dl sas,0x1234567812345678 1890.It FC 1891A Fibre Channel Transport ID consists of 1892.Dq fcp, 1893followed by a 64-bit Fibre Channel World Wide Name. 1894For example: 1895.Pp 1896.Dl fcp,0x1234567812345678 1897.It SPI 1898A Parallel SCSI address consists of 1899.Dq spi, 1900followed by a SCSI target ID and a relative target port identifier. 1901For example: 1902.Pp 1903.Dl spi,4,1 1904.It 1394 1905An IEEE 1394 (Firewire) Transport ID consists of 1906.Dq sbp, 1907followed by a 64-bit EUI-64 IEEE 1394 node unique identifier. 1908For example: 1909.Pp 1910.Dl sbp,0x1234567812345678 1911.It RDMA 1912A SCSI over RDMA Transport ID consists of 1913.Dq srp, 1914followed by a 128-bit RDMA initiator port identifier. 1915The port identifier must be exactly 32 or 34 (if the leading 0x is 1916included) hexadecimal digits. 1917Only hexadecimal (base 16) numbers are supported. 1918For example: 1919.Pp 1920.Dl srp,0x12345678123456781234567812345678 1921.It iSCSI 1922An iSCSI Transport ID consists an iSCSI name and optionally a separator and 1923iSCSI session ID. 1924For example, if only the iSCSI name is specified: 1925.Pp 1926.Dl iqn.2012-06.com.example:target0 1927.Pp 1928If the iSCSI separator and initiator session ID are specified: 1929.Pp 1930.Dl iqn.2012-06.com.example:target0,i,0x123 1931.It PCIe 1932A SCSI over PCIe Transport ID consists of 1933.Dq sop, 1934followed by a PCIe Routing ID. 1935The Routing ID consists of a bus, device and function or in the alternate 1936form, a bus and function. 1937The bus must be in the range of 0 to 255 inclusive and the device must be 1938in the range of 0 to 31 inclusive. 1939The function must be in the range of 0 to 7 inclusive if the standard form 1940is used, and in the range of 0 to 255 inclusive if the alternate form is 1941used. 1942For example, if a bus, device and function are specified for the standard 1943Routing ID form: 1944.Pp 1945.Dl sop,4,5,1 1946.Pp 1947If the alternate Routing ID form is used: 1948.Pp 1949.Dl sop,4,1 1950.El 1951.It Fl k Ar key 1952Specify the Reservation Key. 1953This may be in decimal, octal or hexadecimal format. 1954The value is zero by default if not otherwise specified. 1955The value must be between 0 and 2^64 - 1, inclusive. 1956.It Fl K Ar key 1957Specify the Service Action Reservation Key. 1958This may be in decimal, octal or hexadecimal format. 1959The value is zero by default if not otherwise specified. 1960The value must be between 0 and 2^64 - 1, inclusive. 1961.It Fl p 1962Enable the Activate Persist Through Power Loss bit. 1963This is only used for the register and register_ignore actions. 1964This requests that the reservation persist across power loss events. 1965.It Fl s Ar scope 1966Specify the scope of the reservation. 1967The scope may be specified by name or by number. 1968The scope is ignored for register, register_ignore and clear. 1969If the desired scope isn't available by name, you may specify the number. 1970.Bl -tag -width 7n 1971.It lun 1972LUN scope (0x00). 1973This encompasses the entire LUN. 1974.It extent 1975Extent scope (0x01). 1976.It element 1977Element scope (0x02). 1978.El 1979.It Fl R Ar rtp 1980Specify the Relative Target Port. 1981This only applies to the Register and Move service action of the Persistent 1982Reserve Out command. 1983.It Fl S 1984Enable the SPEC_I_PT bit. 1985This only applies to the Register service action of Persistent Reserve Out. 1986You must also specify at least one Transport ID with 1987.Fl I 1988if this option is set. 1989If you specify a Transport ID, this option is automatically set. 1990It is an error to specify this option for any service action other than 1991Register. 1992.It Fl T Ar type 1993Specify the reservation type. 1994The reservation type may be specified by name or by number. 1995If the desired reservation type isn't available by name, you may specify 1996the number. 1997Supported reservation type names: 1998.Bl -tag -width 11n 1999.It read_shared 2000Read Shared mode. 2001.It wr_ex 2002Write Exclusive mode. 2003May also be specified as 2004.Dq write_exclusive . 2005.It rd_ex 2006Read Exclusive mode. 2007May also be specified as 2008.Dq read_exclusive . 2009.It ex_ac 2010Exclusive access mode. 2011May also be specified as 2012.Dq exclusive_access . 2013.It wr_ex_ro 2014Write Exclusive Registrants Only mode. 2015May also be specified as 2016.Dq write_exclusive_reg_only . 2017.It ex_ac_ro 2018Exclusive Access Registrants Only mode. 2019May also be specified as 2020.Dq exclusive_access_reg_only . 2021.It wr_ex_ar 2022Write Exclusive All Registrants mode. 2023May also be specified as 2024.Dq write_exclusive_all_regs . 2025.It ex_ac_ar 2026Exclusive Access All Registrants mode. 2027May also be specified as 2028.Dq exclusive_access_all_regs . 2029.El 2030.It Fl U 2031Specify that the target should unregister the initiator that sent 2032the Register and Move request. 2033By default, the target will not unregister the initiator that sends the 2034Register and Move request. 2035This option only applies to the Register and Move service action of the 2036Persistent Reserve Out command. 2037.El 2038.It Ic attrib 2039Issue the 2040.Tn SCSI 2041READ or WRITE ATTRIBUTE commands. 2042These commands are used to read and write attributes in Medium Auxiliary 2043Memory (MAM). 2044The most common place Medium Auxiliary Memory is found is small flash chips 2045included tape cartriges. 2046For instance, 2047.Tn LTO 2048tapes have MAM. 2049Either the 2050.Fl r 2051option or the 2052.Fl w 2053option must be specified. 2054.Bl -tag -width 14n 2055.It Fl r Ar action 2056Specify the READ ATTRIBUTE service action. 2057.Bl -tag -width 11n 2058.It attr_values 2059Issue the ATTRIBUTE VALUES service action. 2060Read and decode the available attributes and their values. 2061.It attr_list 2062Issue the ATTRIBUTE LIST service action. 2063List the attributes that are available to read and write. 2064.It lv_list 2065Issue the LOGICAL VOLUME LIST service action. 2066List the available logical volumes in the MAM. 2067.It part_list 2068Issue the PARTITION LIST service action. 2069List the available partitions in the MAM. 2070.It supp_attr 2071Issue the SUPPORTED ATTRIBUTES service action. 2072List attributes that are supported for reading or writing. 2073These attributes may or may not be currently present in the MAM. 2074.El 2075.It Fl w Ar attr 2076Specify an attribute to write to the MAM. 2077This option is not yet implemented. 2078.It Fl a Ar num 2079Specify the attribute number to display. 2080This option only works with the attr_values, attr_list and supp_attr 2081arguments to 2082.Fl r . 2083.It Fl c 2084Display cached attributes. 2085If the device supports this flag, it allows displaying attributes for the 2086last piece of media loaded in the drive. 2087.It Fl e Ar num 2088Specify the element address. 2089This is used for specifying which element number in a medium changer to 2090access when reading attributes. 2091The element number could be for a picker, portal, slot or drive. 2092.It Fl F Ar form1,form2 2093Specify the output format for the attribute values (attr_val) display as a 2094comma separated list of options. 2095The default output is currently set to field_all,nonascii_trim,text_raw. 2096Once this code is ported to FreeBSD 10, any text fields will be converted 2097from their codeset to the user's native codeset with 2098.Xr iconv 3 . 2099.Pp 2100The text options are mutually exclusive; if you specify more than one, you 2101will get unpredictable results. 2102The nonascii options are also mutually exclusive. 2103Most of the field options may be logically ORed together. 2104.Bl -tag -width 12n 2105.It text_esc 2106Print text fields with non-ASCII characters escaped. 2107.It text_raw 2108Print text fields natively, with no codeset conversion. 2109.It nonascii_esc 2110If any non-ASCII characters occur in fields that are supposed to be ASCII, 2111escape the non-ASCII characters. 2112.It nonascii_trim 2113If any non-ASCII characters occur in fields that are supposed to be ASCII, 2114omit the non-ASCII characters. 2115.It nonascii_raw 2116If any non-ASCII characters occur in fields that are supposed to be ASCII, 2117print them as they are. 2118.It field_all 2119Print all of the prefix fields: description, attribute number, attribute 2120size, and the attribute's readonly status. 2121If field_all is specified, specifying any other field options will not have 2122an effect. 2123.It field_none 2124Print none of the prefix fields, and only print out the attribute value. 2125If field_none is specified, specifying any other field options will result 2126in those fields being printed. 2127.It field_desc 2128Print out the attribute description. 2129.It field_num 2130Print out the attribute number. 2131.It field_size 2132Print out the attribute size. 2133.It field_rw 2134Print out the attribute's readonly status. 2135.El 2136.It Fl p Ar part 2137Specify the partition. 2138When the media has multiple partitions, specifying different partition 2139numbers allows seeing the values for each individual partition. 2140.It Fl s Ar start_num 2141Specify the starting attribute number. 2142This requests that the target device return attribute information starting 2143at the given number. 2144.It Fl T Ar elem_type 2145Specify the element type. 2146For medium changer devices, this allows specifying the type the element 2147referenced in the element address ( 2148.Fl e ) . 2149Valid types are: 2150.Dq all , 2151.Dq picker , 2152.Dq slot , 2153.Dq portal , 2154and 2155.Dq drive . 2156.It Fl V Ar vol_num 2157Specify the number of the logical volume to operate on. 2158If the media has multiple logical volumes, this will allow displaying 2159or writing attributes on the given logical volume. 2160.El 2161.It Ic opcodes 2162Issue the REPORT SUPPORTED OPCODES service action of the 2163.Tn SCSI 2164MAINTENANCE IN 2165command. 2166Without arguments, this command will return a list of all 2167.Tn SCSI 2168commands supported by the device, including service actions of commands 2169that support service actions. 2170It will also include the 2171.Tn SCSI 2172CDB (Command Data Block) length for each command, and the description of 2173each command if it is known. 2174.Bl -tag -width 18n 2175.It Fl o Ar opcode 2176Request information on a specific opcode instead of the list of supported 2177commands. 2178If supported, the target will return a CDB-like structure that indicates 2179the opcode, service action (if any), and a mask of bits that are supported 2180in that CDB. 2181.It Fl s Ar service_action 2182For commands that support a service action, specify the service action to 2183query. 2184.It Fl N 2185If a service action is specified for a given opcode, and the device does 2186not support the given service action, the device should not return a 2187.Tn SCSI 2188error, but rather indicate in the returned parameter data that the command 2189is not supported. 2190By default, if a service action is specified for an opcode, and service 2191actions are not supported for the opcode in question, the device will 2192return an error. 2193.It Fl T 2194Include timeout values. 2195This option works with the default display, which includes all commands 2196supported by the device, and with the 2197.Fl o 2198and 2199.Fl s 2200options, which request information on a specific command and service 2201action. 2202This requests that the device report Nominal and Recommended timeout values 2203for the given command or commands. 2204The timeout values are in seconds. 2205The timeout descriptor also includes a command-specific 2206.El 2207.It Ic zone 2208Manage 2209.Tn SCSI 2210and 2211.Tn ATA 2212Zoned Block devices. 2213This allows managing devices that conform to the 2214.Tn SCSI 2215Zoned Block Commands (ZBC) and 2216.Tn ATA 2217Zoned ATA Command Set (ZAC) 2218specifications. 2219Devices using these command sets are usually hard drives using Shingled 2220Magnetic Recording (SMR). 2221There are three types of SMR drives: 2222.Bl -tag -width 13n 2223.It Drive Managed 2224Drive Managed drives look and act just like a standard random access block 2225device, but underneath, the drive reads and writes the bulk of its capacity 2226using SMR zones. 2227Sequential writes will yield better performance, but writing sequentially 2228is not required. 2229.It Host Aware 2230Host Aware drives expose the underlying zone layout via 2231.Tn SCSI 2232or 2233.Tn ATA 2234commands and allow the host to manage the zone conditions. 2235The host is not required to manage the zones on the drive, though. 2236Sequential writes will yield better performance in Sequential Write 2237Preferred zones, but the host can write randomly in those zones. 2238.It Host Managed 2239Host Managed drives expose the underlying zone layout via 2240.Tn SCSI 2241or 2242.Tn ATA 2243commands. 2244The host is required to access the zones according to the rules described 2245by the zone layout. 2246Any commands that violate the rules will be returned with an error. 2247.El 2248.Pp 2249SMR drives are divided into zones (typically in the range of 256MB each) 2250that fall into three general categories: 2251.Bl -tag -width 20n 2252.It Conventional 2253These are also known as Non Write Pointer zones. 2254These zones can be randomly written without an unexpected performance penalty. 2255.It Sequential Preferred 2256These zones should be written sequentially starting at the write pointer 2257for the zone. 2258They may be written randomly. 2259Writes that do not conform to the zone layout may be significantly slower 2260than expected. 2261.It Sequential Required 2262These zones must be written sequentially. 2263If they are not written sequentially, starting at the write pointer, the 2264command will fail. 2265.El 2266.Pp 2267.Bl -tag -width 12n 2268.It Fl c Ar cmd 2269Specify the zone subcommand: 2270.Bl -tag -width 6n 2271.It rz 2272Issue the Report Zones command. 2273All zones are returned by default. 2274Specify report options with 2275.Fl o 2276and printing options with 2277.Fl P . 2278Specify the starting LBA with 2279.Fl l . 2280Note that 2281.Dq reportzones 2282is also accepted as a command argument. 2283.It open 2284Explicitly open the zone specified by the starting LBA. 2285.It close 2286Close the zone specified by starting LBA. 2287.It finish 2288Finish the zone specified by the starting LBA. 2289.It rwp 2290Reset the write pointer for the zone specified by the starting LBA. 2291.El 2292.It Fl a 2293For the Open, Close, Finish, and Reset Write Pointer operations, apply the 2294operation to all zones on the drive. 2295.It Fl l Ar lba 2296Specify the starting LBA. 2297For the Report Zones command, this tells the drive to report starting with 2298the zone that starts at the given LBA. 2299For the other commands, this allows the user to identify the zone requested 2300by its starting LBA. 2301The LBA may be specified in decimal, hexadecimal or octal notation. 2302.It Fl o Ar rep_opt 2303For the Report Zones command, specify a subset of zones to report. 2304.Bl -tag -width 8n 2305.It all 2306Report all zones. 2307This is the default. 2308.It emtpy 2309Report only empty zones. 2310.It imp_open 2311Report zones that are implicitly open. 2312This means that the host has sent a write to the zone without explicitly 2313opening the zone. 2314.It exp_open 2315Report zones that are explicitly open. 2316.It closed 2317Report zones that have been closed by the host. 2318.It full 2319Report zones that are full. 2320.It ro 2321Report zones that are in the read only state. 2322Note that 2323.Dq readonly 2324is also accepted as an argument. 2325.It offline 2326Report zones that are in the offline state. 2327.It reset 2328Report zones where the device recommends resetting write pointers. 2329.It nonseq 2330Report zones that have the Non Sequential Resources Active flag set. 2331These are zones that are Sequential Write Preferred, but have been written 2332non-sequentially. 2333.It nonwp 2334Report Non Write Pointer zones, also known as Conventional zones. 2335.El 2336.It Fl P Ar print_opt 2337Specify a printing option for Report Zones: 2338.Bl -tag -width 7n 2339.It normal 2340Normal Report Zones output. 2341This is the default. 2342The summary and column headings are printed, fields are separated by spaces 2343and the fields themselves may contain spaces. 2344.It summary 2345Just print the summary: the number of zones, the maximum LBA (LBA of the 2346last logical block on the drive), and the value of the 2347.Dq same 2348field. 2349The 2350.Dq same 2351field describes whether the zones on the drive are all identical, all 2352different, or whether they are the same except for the last zone, etc. 2353.It script 2354Print the zones in a script friendly format. 2355The summary and column headings are omitted, the fields are separated by 2356commas, and the fields do not contain spaces. 2357The fields contain underscores where spaces would normally be used. 2358.El 2359.El 2360.It Ic epc 2361Issue 2362.Tn ATA 2363Extended Power Conditions (EPC) feature set commands. 2364This only works on 2365.Tn ATA 2366protocol drives, and will not work on 2367.Tn SCSI 2368protocol drives. 2369It will work on 2370.Tn SATA 2371drives behind a 2372.Tn SCSI 2373to 2374.Tn ATA 2375translation layer (SAT). 2376It may be helpful to read the ATA Command Set - 4 (ACS-4) description of 2377the Extended Power Conditions feature set, available at t13.org, to 2378understand the details of this particular 2379.Nm 2380subcommand. 2381.Bl -tag -width 6n 2382.It Fl c Ar cmd 2383Specify the epc subcommand 2384.Bl -tag -width 7n 2385.It restore 2386Restore drive power condition settings. 2387.Bl -tag -width 6n 2388.It Fl r Ar src 2389Specify the source for the restored power settings, either 2390.Dq default 2391or 2392.Dq saved . 2393This argument is required. 2394.It Fl s 2395Save the settings. 2396This only makes sense to specify when restoring from defaults. 2397.El 2398.It goto 2399Go to the specified power condition. 2400.Bl -tag -width 7n 2401.It Fl p Ar cond 2402Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z. 2403This argument is required. 2404.It Fl D 2405Specify delayed entry to the power condition. 2406The drive, if it supports this, can enter the power condition after the 2407command completes. 2408.It Fl H 2409Hold the power condition. 2410If the drive supports this option, it will hold the power condition and 2411reject all commands that would normally cause it to exit that power 2412condition. 2413.El 2414.It timer 2415Set the timer value for a power condition and enable or disable the 2416condition. 2417See the 2418.Dq list 2419display described below to see what the current timer settings are for each 2420Idle and Standby mode supported by the drive. 2421.Bl -tag -width 8n 2422.It Fl e 2423Enable the power condition. 2424One of 2425.Fl e 2426or 2427.Fl d 2428is required. 2429.It Fl d 2430Disable the power condition. 2431One of 2432.Fl d 2433or 2434.Fl e 2435is required. 2436.It Fl T Ar timer 2437Specify the timer in seconds. 2438The user may specify a timer as a floating point number with a maximum 2439supported resolution of tenths of a second. 2440Drives may or may not support sub-second timer values. 2441.It Fl p Ar cond 2442Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z. 2443This argument is required. 2444.It Fl s 2445Save the timer and power condition enable/disable state. 2446By default, if this option is not specified, only the current values for 2447this power condition will be affected. 2448.El 2449.It state 2450Enable or disable a particular power condition. 2451.Bl -tag -width 7n 2452.It Fl e 2453Enable the power condition. 2454One of 2455.Fl e 2456or 2457.Fl d 2458is required. 2459.It Fl d 2460Disable the power condition. 2461One of 2462.Fl d 2463or 2464.Fl e 2465is required. 2466.It Fl p Ar cond 2467Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z. 2468This argument is required. 2469.It Fl s 2470Save the power condition enable/disable state. 2471By default, if this option is not specified, only the current values for 2472this power condition will be affected. 2473.El 2474.It enable 2475Enable the Extended Power Condition (EPC) feature set. 2476.It disable 2477Disable the Extended Power Condition (EPC) feature set. 2478.It source 2479Specify the EPC power source. 2480.Bl -tag -width 6n 2481.It Fl S Ar src 2482Specify the power source, either 2483.Dq battery 2484or 2485.Dq nonbattery . 2486.El 2487.It status 2488Get the current status of several parameters related to the Extended Power 2489Condition (EPC) feature set, including whether APM and EPC are supported 2490and enabled, whether Low Power Standby is supported, whether setting the 2491EPC power source is supported, whether Low Power Standby is supported and 2492the current power condition. 2493.Bl -tag -width 3n 2494.It Fl P 2495Only report the current power condition. 2496Some drives will exit their current power condition if a command other than 2497the 2498.Tn ATA 2499CHECK POWER MODE command is received. 2500If this flag is specified, 2501.Nm 2502will only issue the 2503.Tn ATA 2504CHECK POWER MODE command to the drive. 2505.El 2506.It list 2507Display the 2508.Tn ATA 2509Power Conditions log (Log Address 0x08). 2510This shows the list of Idle and Standby power conditions the drive 2511supports, and a number of parameters about each condition, including 2512whether it is enabled and what the timer value is. 2513.El 2514.El 2515.It Ic timestamp 2516Issue REPORT TIMESTAMP or SET TIMESTAMP 2517.Tn SCSI 2518commands. Either the 2519.Fl r 2520option or the 2521.Fl s 2522option must be specified. 2523.Bl -tag -width 6n 2524.It Fl r 2525Report the device's timestamp. 2526If no more arguments are specified, the timestamp will be reported using 2527the national representation of the date and time, followed by the time 2528zone. 2529.Bl -tag -width 9n 2530.It Fl f Ar format 2531Specify the strftime format string, as documented in strftime(3), to be used 2532to format the reported timestamp. 2533.It Fl m 2534Report the timestamp as milliseconds since the epoch. 2535.It Fl U 2536Report the timestamp using the national representation of the date and 2537time, but override the system time zone and use UTC instead. 2538.El 2539.El 2540.Bl -tag -width 6n 2541.It Fl s 2542Set the device's timestamp. Either the 2543.Fl f 2544and 2545.Fl T 2546options or the 2547.Fl U 2548option must be specified. 2549.Bl -tag -width 9n 2550.It Fl f Ar format 2551Specify the strptime format string, as documented in strptime(3). 2552The time must also be specified with the 2553.Fl T 2554option. 2555.It Fl T Ar time 2556Provide the time in the format specified with the 2557.Fl f 2558option. 2559.It Fl U 2560Set the timestamp to the host system's time in UTC. 2561.El 2562.El 2563.It Ic devtype 2564Print out the device type for specified device. 2565.Bl -tag -width 10n 2566.It ata 2567An ATA device attached directly to an ATA controller 2568.It satl 2569An SATA device attached behind a SAS controller via SCSI-ATA Translation Layer (SATL) 2570.It scsi 2571A SCSI device 2572.It nvme 2573An directly attached NVMe device 2574.It mmcsd 2575An MMC or SD device attached via a mmcsd bus 2576.It none 2577No device type reported 2578.It unknown 2579Device type is unknown 2580.It illegal 2581A programming error occurred 2582.El 2583.It Ic help 2584Print out verbose usage information. 2585.El 2586.Sh ENVIRONMENT 2587The 2588.Ev SCSI_MODES 2589variable allows the user to specify an alternate mode page format file. 2590.Pp 2591The 2592.Ev EDITOR 2593variable determines which text editor 2594.Nm 2595starts when editing mode pages. 2596.Sh FILES 2597.Bl -tag -width /usr/share/misc/scsi_modes -compact 2598.It Pa /usr/share/misc/scsi_modes 2599is the SCSI mode format database. 2600.It Pa /dev/xpt0 2601is the transport layer device. 2602.It Pa /dev/pass* 2603are the CAM application passthrough devices. 2604.El 2605.Sh EXAMPLES 2606.Dl camcontrol eject -n cd -u 1 -v 2607.Pp 2608Eject the CD from cd1, and print SCSI sense information if the command 2609fails. 2610.Pp 2611.Dl camcontrol tur da0 2612.Pp 2613Send the SCSI test unit ready command to da0. 2614The 2615.Nm 2616utility will report whether the disk is ready, but will not display sense 2617information if the command fails since the 2618.Fl v 2619switch was not specified. 2620.Bd -literal -offset indent 2621camcontrol tur da1 -E -C 4 -t 50 -Q head -v 2622.Ed 2623.Pp 2624Send a test unit ready command to da1. 2625Enable kernel error recovery. 2626Specify a retry count of 4, and a timeout of 50 seconds. 2627Enable sense 2628printing (with the 2629.Fl v 2630flag) if the command fails. 2631Since error recovery is turned on, the 2632disk will be spun up if it is not currently spinning. 2633The 2634.Tn SCSI 2635task attribute for the command will be set to Head of Queue. 2636The 2637.Nm 2638utility will report whether the disk is ready. 2639.Bd -literal -offset indent 2640camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e 2641 -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" 2642.Ed 2643.Pp 2644Issue a READ BUFFER command (0x3C) to cd1. 2645Display the buffer size of cd1, 2646and display the first 10 bytes from the cache on cd1. 2647Display SCSI sense 2648information if the command fails. 2649.Bd -literal -offset indent 2650camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e 2651 -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 2652.Ed 2653.Pp 2654Issue a WRITE BUFFER (0x3B) command to cd1. 2655Write out 10 bytes of data, 2656not including the (reserved) 4 byte header. 2657Print out sense information if 2658the command fails. 2659Be very careful with this command, improper use may 2660cause data corruption. 2661.Bd -literal -offset indent 2662camcontrol modepage da3 -m 1 -e -P 3 2663.Ed 2664.Pp 2665Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the 2666settings on the drive. 2667Mode page 1 contains a disk drive's auto read and 2668write reallocation settings, among other things. 2669.Pp 2670.Dl camcontrol rescan all 2671.Pp 2672Rescan all SCSI buses in the system for devices that have been added, 2673removed or changed. 2674.Pp 2675.Dl camcontrol rescan 0 2676.Pp 2677Rescan SCSI bus 0 for devices that have been added, removed or changed. 2678.Pp 2679.Dl camcontrol rescan 0:1:0 2680.Pp 2681Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or 2682changed. 2683.Pp 2684.Dl camcontrol tags da5 -N 24 2685.Pp 2686Set the number of concurrent transactions for da5 to 24. 2687.Bd -literal -offset indent 2688camcontrol negotiate -n da -u 4 -T disable 2689.Ed 2690.Pp 2691Disable tagged queueing for da4. 2692.Bd -literal -offset indent 2693camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a 2694.Ed 2695.Pp 2696Negotiate a sync rate of 20MHz and an offset of 15 with da3. 2697Then send a 2698Test Unit Ready command to make the settings take effect. 2699.Bd -literal -offset indent 2700camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" 2701.Ed 2702.Pp 2703Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs 2704it contains. 2705Display SMP errors if the command fails. 2706.Bd -literal -offset indent 2707camcontrol security ada0 2708.Ed 2709.Pp 2710Report security support and settings for ada0 2711.Bd -literal -offset indent 2712camcontrol security ada0 -U user -s MyPass 2713.Ed 2714.Pp 2715Enable security on device ada0 with the password MyPass 2716.Bd -literal -offset indent 2717camcontrol security ada0 -U user -e MyPass 2718.Ed 2719.Pp 2720Secure erase ada0 which has had security enabled with user password MyPass 2721.Pp 2722.Em WARNING! WARNING! WARNING! 2723.Pp 2724This will 2725.Em ERASE ALL 2726data from the device, so backup your data before using! 2727.Pp 2728This command can be used against an SSD drive to restoring it to 2729factory default write performance. 2730.Bd -literal -offset indent 2731camcontrol hpa ada0 2732.Ed 2733.Pp 2734Report HPA support and settings for ada0 (also reported via 2735identify). 2736.Bd -literal -offset indent 2737camcontrol hpa ada0 -s 10240 2738.Ed 2739.Pp 2740Enables HPA on ada0 setting the maximum reported sectors to 10240. 2741.Pp 2742.Em WARNING! WARNING! WARNING! 2743.Pp 2744This will 2745.Em PREVENT ACCESS 2746to all data on the device beyond this limit until HPA is disabled by setting 2747HPA to native max sectors of the device, which can only be done after a 2748power-on or hardware reset! 2749.Pp 2750.Em DO NOT 2751use this on a device which has an active filesystem! 2752.Bd -literal -offset indent 2753camcontrol persist da0 -v -i read_keys 2754.Ed 2755.Pp 2756This will read any persistent reservation keys registered with da0, and 2757display any errors encountered when sending the PERSISTENT RESERVE IN 2758.Tn SCSI 2759command. 2760.Bd -literal -offset indent 2761camcontrol persist da0 -v -o register -a -K 0x12345678 2762.Ed 2763.Pp 2764This will register the persistent reservation key 0x12345678 with da0, 2765apply that registration to all ports on da0, and display any errors that 2766occur when sending the PERSISTENT RESERVE OUT command. 2767.Bd -literal -offset indent 2768camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac 2769.Ed 2770.Pp 2771This will reserve da0 for the exlusive use of the initiator issuing the 2772command. 2773The scope of the reservation is the entire LUN. 2774Any errors sending the PERSISTENT RESERVE OUT command will be displayed. 2775.Bd -literal -offset indent 2776camcontrol persist da0 -v -i read_full 2777.Ed 2778.Pp 2779This will display the full status of all reservations on da0 and print out 2780status if there are any errors. 2781.Bd -literal -offset indent 2782camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac 2783.Ed 2784.Pp 2785This will release a reservation on da0 of the type ex_ac 2786(Exclusive Access). 2787The Reservation Key for this registration is 0x12345678. 2788Any errors that occur will be displayed. 2789.Bd -literal -offset indent 2790camcontrol persist da0 -v -o register -K 0x12345678 -S \e 2791 -I sas,0x1234567812345678 -I sas,0x8765432187654321 2792.Ed 2793.Pp 2794This will register the key 0x12345678 with da0, specifying that it applies 2795to the SAS initiators with SAS addresses 0x1234567812345678 and 27960x8765432187654321. 2797.Bd -literal -offset indent 2798camcontrol persist da0 -v -o register_move -k 0x87654321 \e 2799 -K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678 2800.Ed 2801.Pp 2802This will move the registration from the current initiator, whose 2803Registration Key is 0x87654321, to the Fibre Channel initiator with the 2804Fiber Channel World Wide Node Name 0x1234567812345678. 2805A new registration key, 0x12345678, will be registered for the initiator 2806with the Fibre Channel World Wide Node Name 0x1234567812345678, and the 2807current initiator will be unregistered from the target. 2808The reservation will be moved to relative target port 2 on the target 2809device. 2810The registration will persist across power losses. 2811.Bd -literal -offset indent 2812camcontrol attrib sa0 -v -i attr_values -p 1 2813.Ed 2814.Pp 2815This will read and decode the attribute values from partition 1 on the tape 2816in tape drive sa0, and will display any 2817.Tn SCSI 2818errors that result. 2819.Pp 2820.Bd -literal -offset indent 2821camcontrol zone da0 -v -c rz -P summary 2822.Ed 2823.Pp 2824This will request the SMR zone list from disk da0, and print out a 2825summary of the zone parameters, and display any 2826.Tn SCSI 2827or 2828.Tn ATA 2829errors that result. 2830.Pp 2831.Bd -literal -offset indent 2832camcontrol zone da0 -v -c rz -o reset 2833.Ed 2834.Pp 2835This will request the list of SMR zones that should have their write 2836pointer reset from the disk da0, and display any 2837.Tn SCSI 2838or 2839.Tn ATA 2840errors that result. 2841.Pp 2842.Bd -literal -offset indent 2843camcontrol zone da0 -v -c rwp -l 0x2c80000 2844.Ed 2845.Pp 2846This will issue the Reset Write Pointer command to disk da0 for the zone 2847that starts at LBA 0x2c80000 and display any 2848.Tn SCSI 2849or 2850.Tn ATA 2851errors that result. 2852.Pp 2853.Bd -literal -offset indent 2854camcontrol epc ada0 -c timer -T 60.1 -p Idle_a -e -s 2855.Ed 2856.Pp 2857Set the timer for the Idle_a power condition on drive 2858.Pa ada0 2859to 60.1 seconds, enable that particular power condition, and save the timer 2860value and the enabled state of the power condition. 2861.Pp 2862.Bd -literal -offset indent 2863camcontrol epc da4 -c goto -p Standby_z -H 2864.Ed 2865.Pp 2866Tell drive 2867.Pa da4 2868to go to the Standby_z power state (which is 2869the drive's lowest power state) and hold in that state until it is 2870explicitly released by another 2871.Cm goto 2872command. 2873.Pp 2874.Bd -literal -offset indent 2875camcontrol epc da2 -c status -P 2876.Ed 2877.Pp 2878Report only the power state of 2879drive 2880.Pa da2 . 2881Some drives will power up in response to the commands sent by the 2882.Pa status 2883subcommand, and the 2884.Fl P 2885option causes 2886.Nm 2887to only send the 2888.Tn ATA 2889CHECK POWER MODE command, which should not trigger a change in the drive's 2890power state. 2891.Pp 2892.Bd -literal -offset indent 2893camcontrol epc ada0 -c list 2894.Ed 2895.Pp 2896Display the ATA Power Conditions log (Log Address 0x08) for 2897drive 2898.Pa ada0 . 2899.Pp 2900.Bd -literal -offset indent 2901camcontrol timestamp sa0 -s -f "%a, %d %b %Y %T %z" \e 2902 -T "Wed, 26 Oct 2016 21:43:57 -0600" 2903.Ed 2904.Pp 2905Set the timestamp of drive 2906.Pa sa0 2907using a 2908.Xr strptime 3 2909format string followed by a time string 2910that was created using this format string. 2911.Sh SEE ALSO 2912.Xr cam 3 , 2913.Xr cam_cdbparse 3 , 2914.Xr cam 4 , 2915.Xr pass 4 , 2916.Xr xpt 4 2917.Sh HISTORY 2918The 2919.Nm 2920utility first appeared in 2921.Fx 3.0 . 2922.Pp 2923The mode page editing code and arbitrary SCSI command code are based upon 2924code in the old 2925.Xr scsi 8 2926utility and 2927.Xr scsi 3 2928library, written by Julian Elischer and Peter Dufault. 2929The 2930.Xr scsi 8 2931program first appeared in 2932.Bx 386 0.1.2.4 , 2933and first appeared in 2934.Fx 2935in 2936.Fx 2.0.5 . 2937.Sh AUTHORS 2938.An Kenneth Merry Aq Mt ken@FreeBSD.org 2939.Sh BUGS 2940The code that parses the generic command line arguments does not know that 2941some of the subcommands take multiple arguments. 2942So if, for instance, you 2943tried something like this: 2944.Bd -literal -offset indent 2945camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v 2946.Ed 2947.Pp 2948The sense information from the test unit ready command would not get 2949printed out, since the first 2950.Xr getopt 3 2951call in 2952.Nm 2953bails out when it sees the second argument to 2954.Fl c 2955(0x00), 2956above. 2957Fixing this behavior would take some gross code, or changes to the 2958.Xr getopt 3 2959interface. 2960The best way to circumvent this problem is to always make sure 2961to specify generic 2962.Nm 2963arguments before any command-specific arguments. 2964