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