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