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