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