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