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