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