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