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