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