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