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