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