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