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