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