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 March 19, 2015 31.Dt CAMCONTROL 8 32.Os 33.Sh NAME 34.Nm camcontrol 35.Nd CAM control program 36.Sh SYNOPSIS 37.Nm 38.Aq Ar command 39.Op device id 40.Op generic args 41.Op command args 42.Nm 43.Ic devlist 44.Op Fl b 45.Op Fl v 46.Nm 47.Ic periphlist 48.Op device id 49.Op Fl n Ar dev_name 50.Op Fl u Ar unit_number 51.Nm 52.Ic tur 53.Op device id 54.Op generic args 55.Nm 56.Ic inquiry 57.Op device id 58.Op generic args 59.Op Fl D 60.Op Fl S 61.Op Fl R 62.Nm 63.Ic identify 64.Op device id 65.Op generic args 66.Op Fl v 67.Nm 68.Ic reportluns 69.Op device id 70.Op generic args 71.Op Fl c 72.Op Fl l 73.Op Fl r Ar reporttype 74.Nm 75.Ic readcap 76.Op device id 77.Op generic args 78.Op Fl b 79.Op Fl h 80.Op Fl H 81.Op Fl N 82.Op Fl q 83.Op Fl s 84.Nm 85.Ic start 86.Op device id 87.Op generic args 88.Nm 89.Ic stop 90.Op device id 91.Op generic args 92.Nm 93.Ic load 94.Op device id 95.Op generic args 96.Nm 97.Ic eject 98.Op device id 99.Op generic args 100.Nm 101.Ic rescan 102.Aq all | bus Ns Op :target:lun 103.Nm 104.Ic reset 105.Aq all | bus Ns Op :target:lun 106.Nm 107.Ic defects 108.Op device id 109.Op generic args 110.Aq Fl f Ar format 111.Op Fl P 112.Op Fl G 113.Op Fl q 114.Op Fl s 115.Op Fl S Ar offset 116.Op Fl X 117.Nm 118.Ic modepage 119.Op device id 120.Op generic args 121.Aq Fl m Ar page | Fl l 122.Op Fl P Ar pgctl 123.Op Fl b | Fl e 124.Op Fl d 125.Nm 126.Ic cmd 127.Op device id 128.Op generic args 129.Aq Fl a Ar cmd Op args 130.Aq Fl c Ar cmd Op args 131.Op Fl d 132.Op Fl f 133.Op Fl i Ar len Ar fmt 134.Bk -words 135.Op Fl o Ar len Ar fmt Op args 136.Op Fl r Ar fmt 137.Ek 138.Nm 139.Ic smpcmd 140.Op device id 141.Op generic args 142.Aq Fl r Ar len Ar fmt Op args 143.Aq Fl R Ar len Ar fmt Op args 144.Nm 145.Ic smprg 146.Op device id 147.Op generic args 148.Op Fl l 149.Nm 150.Ic smppc 151.Op device id 152.Op generic args 153.Aq Fl p Ar phy 154.Op Fl l 155.Op Fl o Ar operation 156.Op Fl d Ar name 157.Op Fl m Ar rate 158.Op Fl M Ar rate 159.Op Fl T Ar pp_timeout 160.Op Fl a Ar enable|disable 161.Op Fl A Ar enable|disable 162.Op Fl s Ar enable|disable 163.Op Fl S Ar enable|disable 164.Nm 165.Ic smpphylist 166.Op device id 167.Op generic args 168.Op Fl l 169.Op Fl q 170.Nm 171.Ic smpmaninfo 172.Op device id 173.Op generic args 174.Op Fl l 175.Nm 176.Ic debug 177.Op Fl I 178.Op Fl P 179.Op Fl T 180.Op Fl S 181.Op Fl X 182.Op Fl c 183.Op Fl p 184.Aq all|off|bus Ns Op :target Ns Op :lun 185.Nm 186.Ic tags 187.Op device id 188.Op generic args 189.Op Fl N Ar tags 190.Op Fl q 191.Op Fl v 192.Nm 193.Ic negotiate 194.Op device id 195.Op generic args 196.Op Fl c 197.Op Fl D Ar enable|disable 198.Op Fl M Ar mode 199.Op Fl O Ar offset 200.Op Fl q 201.Op Fl R Ar syncrate 202.Op Fl T Ar enable|disable 203.Op Fl U 204.Op Fl W Ar bus_width 205.Op Fl v 206.Nm 207.Ic format 208.Op device id 209.Op generic args 210.Op Fl q 211.Op Fl r 212.Op Fl w 213.Op Fl y 214.Nm 215.Ic sanitize 216.Op device id 217.Op generic args 218.Aq Fl a Ar overwrite | block | crypto | exitfailure 219.Op Fl c Ar passes 220.Op Fl I 221.Op Fl P Ar pattern 222.Op Fl q 223.Op Fl U 224.Op Fl r 225.Op Fl w 226.Op Fl y 227.Nm 228.Ic idle 229.Op device id 230.Op generic args 231.Op Fl t Ar time 232.Nm 233.Ic standby 234.Op device id 235.Op generic args 236.Op Fl t Ar time 237.Nm 238.Ic sleep 239.Op device id 240.Op generic args 241.Nm 242.Ic apm 243.Op device id 244.Op generic args 245.Op Fl l Ar level 246.Nm 247.Ic aam 248.Op device id 249.Op generic args 250.Op Fl l Ar level 251.Nm 252.Ic fwdownload 253.Op device id 254.Op generic args 255.Aq Fl f Ar fw_image 256.Op Fl y 257.Op Fl s 258.Nm 259.Ic security 260.Op device id 261.Op generic args 262.Op Fl d Ar pwd 263.Op Fl e Ar pwd 264.Op Fl f 265.Op Fl h Ar pwd 266.Op Fl k Ar pwd 267.Op Fl l Ar high|maximum 268.Op Fl q 269.Op Fl s Ar pwd 270.Op Fl T Ar timeout 271.Op Fl U Ar user|master 272.Op Fl y 273.Nm 274.Ic hpa 275.Op device id 276.Op generic args 277.Op Fl f 278.Op Fl l 279.Op Fl P 280.Op Fl p Ar pwd 281.Op Fl q 282.Op Fl s Ar max_sectors 283.Op Fl U Ar pwd 284.Op Fl y 285.Nm 286.Ic persist 287.Op device id 288.Op generic args 289.Aq Fl i Ar action | Fl o Ar action 290.Op Fl a 291.Op Fl I Ar trans_id 292.Op Fl k Ar key 293.Op Fl K Ar sa_key 294.Op Fl p 295.Op Fl R Ar rel_tgt_port 296.Op Fl s Ar scope 297.Op Fl S 298.Op Fl T Ar res_type 299.Op Fl U 300.Nm 301.Ic help 302.Sh DESCRIPTION 303The 304.Nm 305utility is designed to provide a way for users to access and control the 306.Fx 307CAM subsystem. 308.Pp 309The 310.Nm 311utility 312can cause a loss of data and/or system crashes if used improperly. 313Even 314expert users are encouraged to exercise caution when using this command. 315Novice users should stay away from this utility. 316.Pp 317The 318.Nm 319utility has a number of primary functions, many of which support an optional 320device identifier. 321A device identifier can take one of three forms: 322.Bl -tag -width 14n 323.It deviceUNIT 324Specify a device name and unit number combination, like "da5" or "cd3". 325.It bus:target 326Specify a bus number and target id. 327The bus number can be determined from 328the output of 329.Dq camcontrol devlist . 330The lun defaults to 0. 331.It bus:target:lun 332Specify the bus, target and lun for a device. 333(e.g.\& 1:2:0) 334.El 335.Pp 336The device identifier, if it is specified, 337.Em must 338come immediately after the function name, and before any generic or 339function-specific arguments. 340Note that the 341.Fl n 342and 343.Fl u 344arguments described below will override any device name or unit number 345specified beforehand. 346The 347.Fl n 348and 349.Fl u 350arguments will 351.Em not 352override a specified bus:target or bus:target:lun, however. 353.Pp 354Most of the 355.Nm 356primary functions support these generic arguments: 357.Bl -tag -width 14n 358.It Fl C Ar count 359SCSI command retry count. 360In order for this to work, error recovery 361.Pq Fl E 362must be turned on. 363.It Fl E 364Instruct the kernel to perform generic SCSI error recovery for the given 365command. 366This is needed in order for the retry count 367.Pq Fl C 368to be honored. 369Other than retrying commands, the generic error recovery in 370the code will generally attempt to spin up drives that are not spinning. 371It may take some other actions, depending upon the sense code returned from 372the command. 373.It Fl n Ar dev_name 374Specify the device type to operate on, e.g.\& "da", "cd". 375.It Fl t Ar timeout 376SCSI command timeout in seconds. 377This overrides the default timeout for 378any given command. 379.It Fl u Ar unit_number 380Specify the device unit number, e.g.\& "1", "5". 381.It Fl v 382Be verbose, print out sense information for failed SCSI commands. 383.El 384.Pp 385Primary command functions: 386.Bl -tag -width periphlist 387.It Ic devlist 388List all physical devices (logical units) attached to the CAM subsystem. 389This also includes a list of peripheral drivers attached to each device. 390With the 391.Fl v 392argument, SCSI bus number, adapter name and unit numbers are printed as 393well. 394On the other hand, with the 395.Fl b 396argument, only the bus adapter, and unit information will be printed, and 397device information will be omitted. 398.It Ic periphlist 399List all peripheral drivers attached to a given physical device (logical 400unit). 401.It Ic tur 402Send the SCSI test unit ready (0x00) command to the given device. 403The 404.Nm 405utility will report whether the device is ready or not. 406.It Ic inquiry 407Send a SCSI inquiry command (0x12) to a device. 408By default, 409.Nm 410will print out the standard inquiry data, device serial number, and 411transfer rate information. 412The user can specify that only certain types of 413inquiry data be printed: 414.Bl -tag -width 4n 415.It Fl D 416Get the standard inquiry data. 417.It Fl S 418Print out the serial number. 419If this flag is the only one specified, 420.Nm 421will not print out "Serial Number" before the value returned by the drive. 422This is to aid in script writing. 423.It Fl R 424Print out transfer rate information. 425.El 426.It Ic identify 427Send a ATA identify command (0xec) to a device. 428.It Ic reportluns 429Send the SCSI REPORT LUNS (0xA0) command to the given device. 430By default, 431.Nm 432will print out the list of logical units (LUNs) supported by the target device. 433There are a couple of options to modify the output: 434.Bl -tag -width 14n 435.It Fl c 436Just print out a count of LUNs, not the actual LUN numbers. 437.It Fl l 438Just print out the LUNs, and do not print out the count. 439.It Fl r Ar reporttype 440Specify the type of report to request from the target: 441.Bl -tag -width 012345678 442.It default 443Return the default report. 444This is the 445.Nm 446default. 447Most targets will support this report if they support the REPORT LUNS 448command. 449.It wellknown 450Return only well known LUNs. 451.It all 452Return all available LUNs. 453.El 454.El 455.Pp 456.Nm 457will try to print out LUN numbers in a reasonable format. 458It can understand the peripheral, flat, LUN and extended LUN formats. 459.It Ic readcap 460Send the SCSI READ CAPACITY command to the given device and display 461the results. 462If the device is larger than 2TB, the SCSI READ CAPACITY (16) service 463action will be sent to obtain the full size of the device. 464By default, 465.Nm 466will print out the last logical block of the device, and the blocksize of 467the device in bytes. 468To modify the output format, use the following options: 469.Bl -tag -width 5n 470.It Fl b 471Just print out the blocksize, not the last block or device size. 472This cannot be used with 473.Fl N 474or 475.Fl s . 476.It Fl h 477Print out the device size in human readable (base 2, 1K == 1024) format. 478This implies 479.Fl N 480and cannot be used with 481.Fl q 482or 483.Fl b . 484.It Fl H 485Print out the device size in human readable (base 10, 1K == 1000) format. 486.It Fl N 487Print out the number of blocks in the device instead of the last logical 488block. 489.It Fl q 490Quiet, print out the numbers only (separated by a comma if 491.Fl b 492or 493.Fl s 494are not specified). 495.It Fl s 496Print out the last logical block or the size of the device only, and omit 497the blocksize. 498.El 499.It Ic start 500Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 501start bit set. 502.It Ic stop 503Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 504start bit cleared. 505.It Ic load 506Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 507start bit set and the load/eject bit set. 508.It Ic eject 509Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 510start bit cleared and the load/eject bit set. 511.It Ic rescan 512Tell the kernel to scan all busses in the system (with the 513.Ar all 514argument), the given bus (XPT_SCAN_BUS), or bus:target:lun 515(XPT_SCAN_LUN) for new devices or devices that have gone away. 516The user 517may specify a scan of all busses, a single bus, or a lun. 518Scanning all luns 519on a target is not supported. 520.It Ic reset 521Tell the kernel to reset all busses in the system (with the 522.Ar all 523argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus 524reset for that bus, or to reset the given bus:target:lun 525(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after 526connecting to that device. 527Note that this can have a destructive impact 528on the system. 529.It Ic defects 530Send the 531.Tn SCSI 532READ DEFECT DATA (10) command (0x37) or the 533.Tn SCSI 534READ DEFECT DATA (12) command (0xB7) to the given device, and 535print out any combination of: the total number of defects, the primary 536defect list (PLIST), and the grown defect list (GLIST). 537.Bl -tag -width 11n 538.It Fl f Ar format 539Specify the requested format of the defect list. 540The format argument is 541required. 542Most drives support the physical sector format. 543Some drives 544support the logical block format. 545Many drives, if they do not support the 546requested format, return the data in an alternate format, along with sense 547information indicating that the requested data format is not supported. 548The 549.Nm 550utility 551attempts to detect this, and print out whatever format the drive returns. 552If the drive uses a non-standard sense code to report that it does not 553support the requested format, 554.Nm 555will probably see the error as a failure to complete the request. 556.Pp 557The format options are: 558.Bl -tag -width 9n 559.It block 560Print out the list as logical blocks. 561This is limited to 32-bit block sizes, and isn't supported by many modern 562drives. 563.It longblock 564Print out the list as logical blocks. 565This option uses a 64-bit block size. 566.It bfi 567Print out the list in bytes from index format. 568.It extbfi 569Print out the list in extended bytes from index format. 570The extended format allows for ranges of blocks to be printed. 571.It phys 572Print out the list in physical sector format. 573Most drives support this format. 574.It extphys 575Print out the list in extended physical sector format. 576The extended format allows for ranges of blocks to be printed. 577.El 578.It Fl G 579Print out the grown defect list. 580This is a list of bad blocks that have 581been remapped since the disk left the factory. 582.It Fl P 583Print out the primary defect list. 584This is the list of defects that were present in the factory. 585.It Fl q 586When printing status information with 587.Fl s , 588only print the number of defects. 589.It Fl s 590Just print the number of defects, not the list of defects. 591.It Fl S Ar offset 592Specify the starting offset into the defect list. 593This implies using the 594.Tn SCSI 595READ DEFECT DATA (12) command, as the 10 byte version of the command 596doesn't support the address descriptor index field. 597Not all drives support the 12 byte command, and some drives that support 598the 12 byte command don't support the address descriptor index field. 599.It Fl X 600Print out defects in hexadecimal (base 16) form instead of base 10 form. 601.El 602.Pp 603If neither 604.Fl P 605nor 606.Fl G 607is specified, 608.Nm 609will print out the number of defects given in the READ DEFECT DATA header 610returned from the drive. 611Some drives will report 0 defects if neither the primary or grown defect 612lists are requested. 613.It Ic modepage 614Allows the user to display and optionally edit a SCSI mode page. 615The mode 616page formats are located in 617.Pa /usr/share/misc/scsi_modes . 618This can be overridden by specifying a different file in the 619.Ev SCSI_MODES 620environment variable. 621The 622.Ic modepage 623command takes several arguments: 624.Bl -tag -width 12n 625.It Fl d 626Disable block descriptors for mode sense. 627.It Fl b 628Displays mode page data in binary format. 629.It Fl e 630This flag allows the user to edit values in the mode page. 631The user may 632either edit mode page values with the text editor pointed to by his 633.Ev EDITOR 634environment variable, or supply mode page values via standard input, using 635the same format that 636.Nm 637uses to display mode page values. 638The editor will be invoked if 639.Nm 640detects that standard input is terminal. 641.It Fl l 642Lists all available mode pages. 643.It Fl m Ar mode_page 644This specifies the number of the mode page the user would like to view 645and/or edit. 646This argument is mandatory unless 647.Fl l 648is specified. 649.It Fl P Ar pgctl 650This allows the user to specify the page control field. 651Possible values are: 652.Bl -tag -width xxx -compact 653.It 0 654Current values 655.It 1 656Changeable values 657.It 2 658Default values 659.It 3 660Saved values 661.El 662.El 663.It Ic cmd 664Allows the user to send an arbitrary ATA or SCSI CDB to any device. 665The 666.Ic cmd 667function requires the 668.Fl c 669argument to specify SCSI CDB or the 670.Fl a 671argument to specify ATA Command Block registers values. 672Other arguments are optional, depending on 673the command type. 674The command and data specification syntax is documented 675in 676.Xr cam_cdbparse 3 . 677NOTE: If the CDB specified causes data to be transferred to or from the 678SCSI device in question, you MUST specify either 679.Fl i 680or 681.Fl o . 682.Bl -tag -width 17n 683.It Fl a Ar cmd Op args 684This specifies the content of 12 ATA Command Block registers (command, 685features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp. 686lba_high_exp, features_exp, sector_count, sector_count_exp). 687.It Fl c Ar cmd Op args 688This specifies the SCSI CDB. 689SCSI CDBs may be 6, 10, 12 or 16 bytes. 690.It Fl d 691Specifies DMA protocol to be used for ATA command. 692.It Fl f 693Specifies FPDMA (NCQ) protocol to be used for ATA command. 694.It Fl i Ar len Ar fmt 695This specifies the amount of data to read, and how it should be displayed. 696If the format is 697.Sq - , 698.Ar len 699bytes of data will be read from the device and written to standard output. 700.It Fl o Ar len Ar fmt Op args 701This specifies the amount of data to be written to a device, and the data 702that is to be written. 703If the format is 704.Sq - , 705.Ar len 706bytes of data will be read from standard input and written to the device. 707.It Fl r Ar fmt 708This specifies that 11 result ATA Command Block registers should be displayed 709(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp, 710lba_high_exp, sector_count, sector_count_exp), and how. 711If the format is 712.Sq - , 71311 result registers will be written to standard output in hex. 714.El 715.It Ic smpcmd 716Allows the user to send an arbitrary Serial 717Management Protocol (SMP) command to a device. 718The 719.Ic smpcmd 720function requires the 721.Fl r 722argument to specify the SMP request to be sent, and the 723.Fl R 724argument to specify the format of the SMP response. 725The syntax for the SMP request and response arguments is documented in 726.Xr cam_cdbparse 3 . 727.Pp 728Note that SAS adapters that support SMP passthrough (at least the currently 729known adapters) do not accept CRC bytes from the user in the request and do 730not pass CRC bytes back to the user in the response. 731Therefore users should not include the CRC bytes in the length of the 732request and not expect CRC bytes to be returned in the response. 733.Bl -tag -width 17n 734.It Fl r Ar len Ar fmt Op args 735This specifies the size of the SMP request, without the CRC bytes, and the 736SMP request format. 737If the format is 738.Sq - , 739.Ar len 740bytes of data will be read from standard input and written as the SMP 741request. 742.It Fl R Ar len Ar fmt Op args 743This specifies the size of the buffer allocated for the SMP response, and 744the SMP response format. 745If the format is 746.Sq - , 747.Ar len 748bytes of data will be allocated for the response and the response will be 749written to standard output. 750.El 751.It Ic smprg 752Allows the user to send the Serial Management Protocol (SMP) Report General 753command to a device. 754.Nm 755will display the data returned by the Report General command. 756If the SMP target supports the long response format, the additional data 757will be requested and displayed automatically. 758.Bl -tag -width 8n 759.It Fl l 760Request the long response format only. 761Not all SMP targets support the long response format. 762This option causes 763.Nm 764to skip sending the initial report general request without the long bit set 765and only issue a report general request with the long bit set. 766.El 767.It Ic smppc 768Allows the user to issue the Serial Management Protocol (SMP) PHY Control 769command to a device. 770This function should be used with some caution, as it can render devices 771inaccessible, and could potentially cause data corruption as well. 772The 773.Fl p 774argument is required to specify the PHY to operate on. 775.Bl -tag -width 17n 776.It Fl p Ar phy 777Specify the PHY to operate on. 778This argument is required. 779.It Fl l 780Request the long request/response format. 781Not all SMP targets support the long response format. 782For the PHY Control command, this currently only affects whether the 783request length is set to a value other than 0. 784.It Fl o Ar operation 785Specify a PHY control operation. 786Only one 787.Fl o 788operation may be specified. 789The operation may be specified numerically (in decimal, hexadecimal, or octal) 790or one of the following operation names may be specified: 791.Bl -tag -width 16n 792.It nop 793No operation. 794It is not necessary to specify this argument. 795.It linkreset 796Send the LINK RESET command to the phy. 797.It hardreset 798Send the HARD RESET command to the phy. 799.It disable 800Send the DISABLE command to the phy. 801Note that the LINK RESET or HARD RESET commands should re-enable the phy. 802.It clearerrlog 803Send the CLEAR ERROR LOG command. 804This clears the error log counters for the specified phy. 805.It clearaffiliation 806Send the CLEAR AFFILIATION command. 807This clears the affiliation from the STP initiator port with the same SAS 808address as the SMP initiator that requests the clear operation. 809.It sataportsel 810Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy. 811This will cause a SATA port selector to use the given phy as its active phy 812and make the other phy inactive. 813.It clearitnl 814Send the CLEAR STP I_T NEXUS LOSS command to the PHY. 815.It setdevname 816Send the SET ATTACHED DEVICE NAME command to the PHY. 817This requires the 818.Fl d 819argument to specify the device name. 820.El 821.It Fl d Ar name 822Specify the attached device name. 823This option is needed with the 824.Fl o Ar setdevname 825phy operation. 826The name is a 64-bit number, and can be specified in decimal, hexadecimal 827or octal format. 828.It Fl m Ar rate 829Set the minimum physical link rate for the phy. 830This is a numeric argument. 831Currently known link rates are: 832.Bl -tag -width 5n 833.It 0x0 834Do not change current value. 835.It 0x8 8361.5 Gbps 837.It 0x9 8383 Gbps 839.It 0xa 8406 Gbps 841.El 842.Pp 843Other values may be specified for newer physical link rates. 844.It Fl M Ar rate 845Set the maximum physical link rate for the phy. 846This is a numeric argument. 847See the 848.Fl m 849argument description for known link rate arguments. 850.It Fl T Ar pp_timeout 851Set the partial pathway timeout value, in microseconds. 852See the 853.Tn ANSI 854.Tn SAS 855Protocol Layer (SPL) 856specification for more information on this field. 857.It Fl a Ar enable|disable 858Enable or disable SATA slumber phy power conditions. 859.It Fl A Ar enable|disable 860Enable or disable SATA partial power conditions. 861.It Fl s Ar enable|disable 862Enable or disable SAS slumber phy power conditions. 863.It Fl S Ar enable|disable 864Enable or disable SAS partial phy power conditions. 865.El 866.It Ic smpphylist 867List phys attached to a SAS expander, the address of the end device 868attached to the phy, and the inquiry data for that device and peripheral 869devices attached to that device. 870The inquiry data and peripheral devices are displayed if available. 871.Bl -tag -width 5n 872.It Fl l 873Turn on the long response format for the underlying SMP commands used for 874this command. 875.It Fl q 876Only print out phys that are attached to a device in the CAM EDT (Existing 877Device Table). 878.El 879.It Ic smpmaninfo 880Send the SMP Report Manufacturer Information command to the device and 881display the response. 882.Bl -tag -width 5n 883.It Fl l 884Turn on the long response format for the underlying SMP commands used for 885this command. 886.El 887.It Ic debug 888Turn on CAM debugging printfs in the kernel. 889This requires options CAMDEBUG 890in your kernel config file. 891WARNING: enabling debugging printfs currently 892causes an EXTREME number of kernel printfs. 893You may have difficulty 894turning off the debugging printfs once they start, since the kernel will be 895busy printing messages and unable to service other requests quickly. 896The 897.Ic debug 898function takes a number of arguments: 899.Bl -tag -width 18n 900.It Fl I 901Enable CAM_DEBUG_INFO printfs. 902.It Fl P 903Enable CAM_DEBUG_PERIPH printfs. 904.It Fl T 905Enable CAM_DEBUG_TRACE printfs. 906.It Fl S 907Enable CAM_DEBUG_SUBTRACE printfs. 908.It Fl X 909Enable CAM_DEBUG_XPT printfs. 910.It Fl c 911Enable CAM_DEBUG_CDB printfs. 912This will cause the kernel to print out the 913SCSI CDBs sent to the specified device(s). 914.It Fl p 915Enable CAM_DEBUG_PROBE printfs. 916.It all 917Enable debugging for all devices. 918.It off 919Turn off debugging for all devices 920.It bus Ns Op :target Ns Op :lun 921Turn on debugging for the given bus, target or lun. 922If the lun or target 923and lun are not specified, they are wildcarded. 924(i.e., just specifying a 925bus turns on debugging printfs for all devices on that bus.) 926.El 927.It Ic tags 928Show or set the number of "tagged openings" or simultaneous transactions 929we attempt to queue to a particular device. 930By default, the 931.Ic tags 932command, with no command-specific arguments (i.e., only generic arguments) 933prints out the "soft" maximum number of transactions that can be queued to 934the device in question. 935For more detailed information, use the 936.Fl v 937argument described below. 938.Bl -tag -width 7n 939.It Fl N Ar tags 940Set the number of tags for the given device. 941This must be between the 942minimum and maximum number set in the kernel quirk table. 943The default for 944most devices that support tagged queueing is a minimum of 2 and a maximum 945of 255. 946The minimum and maximum values for a given device may be 947determined by using the 948.Fl v 949switch. 950The meaning of the 951.Fl v 952switch for this 953.Nm 954subcommand is described below. 955.It Fl q 956Be quiet, and do not report the number of tags. 957This is generally used when 958setting the number of tags. 959.It Fl v 960The verbose flag has special functionality for the 961.Em tags 962argument. 963It causes 964.Nm 965to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: 966.Bl -tag -width 13n 967.It dev_openings 968This is the amount of capacity for transactions queued to a given device. 969.It dev_active 970This is the number of transactions currently queued to a device. 971.It devq_openings 972This is the kernel queue space for transactions. 973This count usually mirrors 974dev_openings except during error recovery operations when 975the device queue is frozen (device is not allowed to receive 976commands), the number of dev_openings is reduced, or transaction 977replay is occurring. 978.It devq_queued 979This is the number of transactions waiting in the kernel queue for capacity 980on the device. 981This number is usually zero unless error recovery is in 982progress. 983.It held 984The held count is the number of CCBs held by peripheral drivers that have 985either just been completed or are about to be released to the transport 986layer for service by a device. 987Held CCBs reserve capacity on a given 988device. 989.It mintags 990This is the current "hard" minimum number of transactions that can be 991queued to a device at once. 992The 993.Ar dev_openings 994value above cannot go below this number. 995The default value for 996.Ar mintags 997is 2, although it may be set higher or lower for various devices. 998.It maxtags 999This is the "hard" maximum number of transactions that can be queued to a 1000device at one time. 1001The 1002.Ar dev_openings 1003value cannot go above this number. 1004The default value for 1005.Ar maxtags 1006is 255, although it may be set higher or lower for various devices. 1007.El 1008.El 1009.It Ic negotiate 1010Show or negotiate various communication parameters. 1011Some controllers may 1012not support setting or changing some of these values. 1013For instance, the 1014Adaptec 174x controllers do not support changing a device's sync rate or 1015offset. 1016The 1017.Nm 1018utility 1019will not attempt to set the parameter if the controller indicates that it 1020does not support setting the parameter. 1021To find out what the controller 1022supports, use the 1023.Fl v 1024flag. 1025The meaning of the 1026.Fl v 1027flag for the 1028.Ic negotiate 1029command is described below. 1030Also, some controller drivers do not support 1031setting negotiation parameters, even if the underlying controller supports 1032negotiation changes. 1033Some controllers, such as the Advansys wide 1034controllers, support enabling and disabling synchronous negotiation for 1035a device, but do not support setting the synchronous negotiation rate. 1036.Bl -tag -width 17n 1037.It Fl a 1038Attempt to make the negotiation settings take effect immediately by sending 1039a Test Unit Ready command to the device. 1040.It Fl c 1041Show or set current negotiation settings. 1042This is the default. 1043.It Fl D Ar enable|disable 1044Enable or disable disconnection. 1045.It Fl M Ar mode 1046Set ATA mode. 1047.It Fl O Ar offset 1048Set the command delay offset. 1049.It Fl q 1050Be quiet, do not print anything. 1051This is generally useful when you want to 1052set a parameter, but do not want any status information. 1053.It Fl R Ar syncrate 1054Change the synchronization rate for a device. 1055The sync rate is a floating 1056point value specified in MHz. 1057So, for instance, 1058.Sq 20.000 1059is a legal value, as is 1060.Sq 20 . 1061.It Fl T Ar enable|disable 1062Enable or disable tagged queueing for a device. 1063.It Fl U 1064Show or set user negotiation settings. 1065The default is to show or set 1066current negotiation settings. 1067.It Fl v 1068The verbose switch has special meaning for the 1069.Ic negotiate 1070subcommand. 1071It causes 1072.Nm 1073to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the 1074controller driver. 1075.It Fl W Ar bus_width 1076Specify the bus width to negotiate with a device. 1077The bus width is 1078specified in bits. 1079The only useful values to specify are 8, 16, and 32 1080bits. 1081The controller must support the bus width in question in order for 1082the setting to take effect. 1083.El 1084.Pp 1085In general, sync rate and offset settings will not take effect for a 1086device until a command has been sent to the device. 1087The 1088.Fl a 1089switch above will automatically send a Test Unit Ready to the device so 1090negotiation parameters will take effect. 1091.It Ic format 1092Issue the 1093.Tn SCSI 1094FORMAT UNIT command to the named device. 1095.Pp 1096.Em WARNING! WARNING! WARNING! 1097.Pp 1098Low level formatting a disk will destroy ALL data on the disk. 1099Use 1100extreme caution when issuing this command. 1101Many users low-level format 1102disks that do not really need to be low-level formatted. 1103There are 1104relatively few scenarios that call for low-level formatting a disk. 1105One reason for 1106low-level formatting a disk is to initialize the disk after changing 1107its physical sector size. 1108Another reason for low-level formatting a disk 1109is to revive the disk if you are getting "medium format corrupted" errors 1110from the disk in response to read and write requests. 1111.Pp 1112Some disks take longer than others to format. 1113Users should specify a 1114timeout long enough to allow the format to complete. 1115The default format 1116timeout is 3 hours, which should be long enough for most disks. 1117Some hard 1118disks will complete a format operation in a very short period of time 1119(on the order of 5 minutes or less). 1120This is often because the drive 1121does not really support the FORMAT UNIT command -- it just accepts the 1122command, waits a few minutes and then returns it. 1123.Pp 1124The 1125.Sq format 1126subcommand takes several arguments that modify its default behavior. 1127The 1128.Fl q 1129and 1130.Fl y 1131arguments can be useful for scripts. 1132.Bl -tag -width 6n 1133.It Fl q 1134Be quiet, do not print any status messages. 1135This option will not disable 1136the questions, however. 1137To disable questions, use the 1138.Fl y 1139argument, below. 1140.It Fl r 1141Run in 1142.Dq report only 1143mode. 1144This will report status on a format that is already running on the drive. 1145.It Fl w 1146Issue a non-immediate format command. 1147By default, 1148.Nm 1149issues the FORMAT UNIT command with the immediate bit set. 1150This tells the 1151device to immediately return the format command, before the format has 1152actually completed. 1153Then, 1154.Nm 1155gathers 1156.Tn SCSI 1157sense information from the device every second to determine how far along 1158in the format process it is. 1159If the 1160.Fl w 1161argument is specified, 1162.Nm 1163will issue a non-immediate format command, and will be unable to print any 1164information to let the user know what percentage of the disk has been 1165formatted. 1166.It Fl y 1167Do not ask any questions. 1168By default, 1169.Nm 1170will ask the user if he/she really wants to format the disk in question, 1171and also if the default format command timeout is acceptable. 1172The user 1173will not be asked about the timeout if a timeout is specified on the 1174command line. 1175.El 1176.It Ic sanitize 1177Issue the 1178.Tn SCSI 1179SANITIZE command to the named device. 1180.Pp 1181.Em WARNING! WARNING! WARNING! 1182.Pp 1183ALL data in the cache and on the disk will be destroyed or made inaccessible. 1184Recovery of the data is not possible. 1185Use extreme caution when issuing this command. 1186.Pp 1187The 1188.Sq sanitize 1189subcommand takes several arguments that modify its default behavior. 1190The 1191.Fl q 1192and 1193.Fl y 1194arguments can be useful for scripts. 1195.Bl -tag -width 6n 1196.It Fl a Ar operation 1197Specify the sanitize operation to perform. 1198.Bl -tag -width 16n 1199.It overwrite 1200Perform an overwrite operation by writing a user supplied 1201data pattern to the device one or more times. 1202The pattern is given by the 1203.Fl P 1204argument. 1205The number of times is given by the 1206.Fl c 1207argument. 1208.It block 1209Perform a block erase operation. 1210All the device's blocks are set to a vendor defined 1211value, typically zero. 1212.It crypto 1213Perform a cryptographic erase operation. 1214The encryption keys are changed to prevent the decryption 1215of the data. 1216.It exitfailure 1217Exits a previously failed sanitize operation. 1218A failed sanitize operation can only be exited if it was 1219run in the unrestricted completion mode, as provided by the 1220.Fl U 1221argument. 1222.El 1223.It Fl c Ar passes 1224The number of passes when performing an 1225.Sq overwrite 1226operation. 1227Valid values are between 1 and 31. 1228The default is 1. 1229.It Fl I 1230When performing an 1231.Sq overwrite 1232operation, the pattern is inverted between consecutive passes. 1233.It Fl P Ar pattern 1234Path to the file containing the pattern to use when 1235performing an 1236.Sq overwrite 1237operation. 1238The pattern is repeated as needed to fill each block. 1239.It Fl q 1240Be quiet, do not print any status messages. 1241This option will not disable 1242the questions, however. 1243To disable questions, use the 1244.Fl y 1245argument, below. 1246.It Fl U 1247Perform the sanitize in the unrestricted completion mode. 1248If the operation fails, it can later be exited with the 1249.Sq exitfailure 1250operation. 1251.It Fl r 1252Run in 1253.Dq report only 1254mode. 1255This will report status on a sanitize that is already running on the drive. 1256.It Fl w 1257Issue a non-immediate sanitize command. 1258By default, 1259.Nm 1260issues the SANITIZE command with the immediate bit set. 1261This tells the 1262device to immediately return the sanitize command, before 1263the sanitize has actually completed. 1264Then, 1265.Nm 1266gathers 1267.Tn SCSI 1268sense information from the device every second to determine how far along 1269in the sanitize process it is. 1270If the 1271.Fl w 1272argument is specified, 1273.Nm 1274will issue a non-immediate sanitize command, and will be unable to print any 1275information to let the user know what percentage of the disk has been 1276sanitized. 1277.It Fl y 1278Do not ask any questions. 1279By default, 1280.Nm 1281will ask the user if he/she really wants to sanitize the disk in question, 1282and also if the default sanitize command timeout is acceptable. 1283The user 1284will not be asked about the timeout if a timeout is specified on the 1285command line. 1286.El 1287.It Ic idle 1288Put ATA device into IDLE state. 1289Optional parameter 1290.Pq Fl t 1291specifies automatic standby timer value in seconds. 1292Value 0 disables timer. 1293.It Ic standby 1294Put ATA device into STANDBY state. 1295Optional parameter 1296.Pq Fl t 1297specifies automatic standby timer value in seconds. 1298Value 0 disables timer. 1299.It Ic sleep 1300Put ATA device into SLEEP state. 1301Note that the only way get device out of 1302this state may be reset. 1303.It Ic apm 1304It optional parameter 1305.Pq Fl l 1306specified, enables and sets advanced power management level, where 13071 -- minimum power, 127 -- maximum performance with standby, 1308128 -- minimum power without standby, 254 -- maximum performance. 1309If not specified -- APM is disabled. 1310.It Ic aam 1311It optional parameter 1312.Pq Fl l 1313specified, enables and sets automatic acoustic management level, where 13141 -- minimum noise, 254 -- maximum performance. 1315If not specified -- AAM is disabled. 1316.It Ic security 1317Update or report security settings, using an ATA identify command (0xec). 1318By default, 1319.Nm 1320will print out the security support and associated settings of the device. 1321The 1322.Ic security 1323command takes several arguments: 1324.Bl -tag -width 0n 1325.It Fl d Ar pwd 1326.Pp 1327Disable device security using the given password for the selected user according 1328to the devices configured security level. 1329.It Fl e Ar pwd 1330.Pp 1331Erase the device using the given password for the selected user. 1332.Pp 1333.Em WARNING! WARNING! WARNING! 1334.Pp 1335Issuing a secure erase will 1336.Em ERASE ALL 1337user data on the device and may take several hours to complete. 1338.Pp 1339When this command is used against an SSD drive all its cells will be marked as 1340empty, restoring it to factory default write performance. 1341For SSD's this action 1342usually takes just a few seconds. 1343.It Fl f 1344.Pp 1345Freeze the security configuration of the specified device. 1346.Pp 1347After command completion any other commands that update the device lock mode 1348shall be command aborted. 1349Frozen mode is disabled by power-off or hardware reset. 1350.It Fl h Ar pwd 1351.Pp 1352Enhanced erase the device using the given password for the selected user. 1353.Pp 1354.Em WARNING! WARNING! WARNING! 1355.Pp 1356Issuing an enhanced secure erase will 1357.Em ERASE ALL 1358user data on the device and may take several hours to complete. 1359.Pp 1360An enhanced erase writes predetermined data patterns to all user data areas, 1361all previously written user data shall be overwritten, including sectors that 1362are no longer in use due to reallocation. 1363.It Fl k Ar pwd 1364.Pp 1365Unlock the device using the given password for the selected user according to 1366the devices configured security level. 1367.It Fl l Ar high|maximum 1368.Pp 1369Specifies which security level to set when issuing a 1370.Fl s Ar pwd 1371command. 1372The security level determines device behavior when the master 1373password is used to unlock the device. 1374When the security level is set to high 1375the device requires the unlock command and the master password to unlock. 1376When the security level is set to maximum the device requires a secure erase 1377with the master password to unlock. 1378.Pp 1379This option must be used in conjunction with one of the security action commands. 1380.Pp 1381Defaults to 1382.Em high 1383.It Fl q 1384.Pp 1385Be quiet, do not print any status messages. 1386This option will not disable the questions, however. 1387To disable questions, use the 1388.Fl y 1389argument, below. 1390.It Fl s Ar pwd 1391.Pp 1392Password the device (enable security) using the given password for the selected 1393user. 1394This option can be combined with other options such as 1395.Fl e Em pwd 1396.Pp 1397A master password may be set in a addition to the user password. The purpose of 1398the master password is to allow an administrator to establish a password that 1399is kept secret from the user, and which may be used to unlock the device if the 1400user password is lost. 1401.Pp 1402.Em Note: 1403Setting the master password does not enable device security. 1404.Pp 1405If the master password is set and the drive supports a Master Revision Code 1406feature the Master Password Revision Code will be decremented. 1407.It Fl T Ar timeout 1408.Pp 1409Overrides the default timeout, specified in seconds, used for both 1410.Fl e 1411and 1412.Fl h 1413this is useful if your system has problems processing long timeouts correctly. 1414.Pp 1415Usually the timeout is calculated from the information stored on the drive if 1416present, otherwise it defaults to 2 hours. 1417.It Fl U Ar user|master 1418.Pp 1419Specifies which user to set / use for the running action command, valid values 1420are user or master and defaults to master if not set. 1421.Pp 1422This option must be used in conjunction with one of the security action commands. 1423.Pp 1424Defaults to 1425.Em master 1426.It Fl y 1427.Pp 1428Confirm yes to dangerous options such as 1429.Fl e 1430without prompting for confirmation. 1431.El 1432.Pp 1433If the password specified for any action commands does not match the configured 1434password for the specified user the command will fail. 1435.Pp 1436The password in all cases is limited to 32 characters, longer passwords will 1437fail. 1438.It Ic hpa 1439Update or report Host Protected Area details. 1440By default 1441.Nm 1442will print out the HPA support and associated settings of the device. 1443The 1444.Ic hpa 1445command takes several optional arguments: 1446.Bl -tag -width 0n 1447.It Fl f 1448.Pp 1449Freeze the HPA configuration of the specified device. 1450.Pp 1451After command completion any other commands that update the HPA configuration 1452shall be command aborted. 1453Frozen mode is disabled by power-off or hardware reset. 1454.It Fl l 1455.Pp 1456Lock the HPA configuration of the device until a successful call to unlock or 1457the next power-on reset occurs. 1458.It Fl P 1459.Pp 1460Make the HPA max sectors persist across power-on reset or a hardware reset. 1461This must be used in combination with 1462.Fl s Ar max_sectors 1463. 1464.It Fl p Ar pwd 1465.Pp 1466Set the HPA configuration password required for unlock calls. 1467.It Fl q 1468.Pp 1469Be quiet, do not print any status messages. 1470This option will not disable the questions. 1471To disable questions, use the 1472.Fl y 1473argument, below. 1474.It Fl s Ar max_sectors 1475.Pp 1476Configures the maximum user accessible sectors of the device. 1477This will change the number of sectors the device reports. 1478.Pp 1479.Em WARNING! WARNING! WARNING! 1480.Pp 1481Changing the max sectors of a device using this option will make the data on 1482the device beyond the specified value inaccessible. 1483.Pp 1484Only one successful 1485.Fl s Ar max_sectors 1486call can be made without a power-on reset or a hardware reset of the device. 1487.It Fl U Ar pwd 1488.Pp 1489Unlock the HPA configuration of the specified device using the given password. 1490If the password specified does not match the password configured via 1491.Fl p Ar pwd 1492the command will fail. 1493.Pp 1494After 5 failed unlock calls, due to password miss-match, the device will refuse 1495additional unlock calls until after a power-on reset. 1496.It Fl y 1497.Pp 1498Confirm yes to dangerous options such as 1499.Fl e 1500without prompting for confirmation 1501.El 1502.Pp 1503The password for all HPA commands is limited to 32 characters, longer passwords 1504will fail. 1505.It Ic fwdownload 1506Program firmware of the named SCSI device using the image file provided. 1507.Pp 1508Current list of supported vendors: 1509.Bl -bullet -offset indent -compact 1510.It 1511HITACHI 1512.It 1513HP 1514.It 1515IBM 1516.It 1517PLEXTOR 1518.It 1519QUANTUM 1520.It 1521SAMSUNG 1522.It 1523SEAGATE 1524.El 1525.Pp 1526.Em WARNING! WARNING! WARNING! 1527.Pp 1528Little testing has been done to make sure that different device models from 1529each vendor work correctly with the fwdownload command. 1530A vendor name appearing in the supported list means only that firmware of at 1531least one device type from that vendor has successfully been programmed with 1532the fwdownload command. 1533Extra caution should be taken when using this command since there is no 1534guarantee it will not break a device from the listed vendors. 1535Ensure that you have a recent backup of the data on the device before 1536performing a firmware update. 1537.Bl -tag -width 11n 1538.It Fl f Ar fw_image 1539Path to the firmware image file to be downloaded to the specified device. 1540.It Fl y 1541Do not ask for confirmation. 1542.It Fl s 1543Run in simulation mode. 1544Packet sizes that will be sent are shown, but no actual packet is sent to the 1545device. 1546No confirmation is asked in simulation mode. 1547.It Fl v 1548Besides showing sense information in case of a failure, the verbose option 1549causes 1550.Nm 1551to output a line for every firmware segment that is sent to the device by the 1552fwdownload command 1553-- the same as the ones shown in simulation mode. 1554.El 1555.It Ic persist 1556Persistent reservation support. 1557Persistent reservations are a way to reserve a particular 1558.Tn SCSI 1559LUN for use by one or more 1560.Tn SCSI 1561initiators. 1562If the 1563.Fl i 1564option is specified, 1565.Nm 1566will issue the 1567.Tn SCSI 1568PERSISTENT RESERVE IN 1569command using the requested service action. 1570If the 1571.Fl o 1572option is specified, 1573.Nm 1574will issue the 1575.Tn SCSI 1576PERSISTENT RESERVE OUT 1577command using the requested service action. 1578One of those two options is required. 1579.Pp 1580Persistent reservations are complex, and fully explaining them is outside 1581the scope of this manual. 1582Please visit 1583http://www.t10.org 1584and download the latest SPC spec for a full explanation of persistent 1585reservations. 1586.Bl -tag -width 8n 1587.It Fl i Ar mode 1588Specify the service action for the PERSISTENT RESERVE IN command. 1589Supported service actions: 1590.Bl -tag -width 19n 1591.It read_keys 1592Report the current persistent reservation generation (PRgeneration) and any 1593registered keys. 1594.It read_reservation 1595Report the persistent reservation, if any. 1596.It report_capabilities 1597Report the persistent reservation capabilities of the LUN. 1598.It read_full_status 1599Report the full status of persistent reservations on the LUN. 1600.El 1601.It Fl o Ar mode 1602Specify the service action for the PERSISTENT RESERVE OUT command. 1603For service actions like register that are components of other service 1604action names, the entire name must be specified. 1605Otherwise, enough of the service action name must be specified to 1606distinguish it from other possible service actions. 1607Supported service actions: 1608.Bl -tag -width 15n 1609.It register 1610Register a reservation key with the LUN or unregister a reservation key. 1611To register a key, specify the requested key as the Service Action 1612Reservation Key. 1613To unregister a key, specify the previously registered key as the 1614Reservation Key. 1615To change a key, specify the old key as the Reservation Key and the new 1616key as the Service Action Reservation Key. 1617.It register_ignore 1618This is similar to the register subcommand, except that the Reservation Key 1619is ignored. 1620The Service Action Reservation Key will overwrite any previous key 1621registered for the initiator. 1622.It reserve 1623Create a reservation. 1624A key must be registered with the LUN before the LUN can be reserved, and 1625it must be specified as the Reservation Key. 1626The type of reservation must also be specified. 1627The scope defaults to LUN scope (LU_SCOPE), but may be changed. 1628.It release 1629Release a reservation. 1630The Reservation Key must be specified. 1631.It clear 1632Release a reservation and remove all keys from the device. 1633The Reservation Key must be specified. 1634.It preempt 1635Remove a reservation belonging to another initiator. 1636The Reservation Key must be specified. 1637The Service Action Reservation Key may be specified, depending on the 1638operation being performed. 1639.It preempt_abort 1640Remove a reservation belonging to another initiator and abort all 1641outstanding commands from that initiator. 1642The Reservation Key must be specified. 1643The Service Action Reservation Key may be specified, depending on the 1644operation being performed. 1645.It register_move 1646Register another initiator with the LUN, and establish a reservation on the 1647LUN for that initiator. 1648The Reservation Key and Service Action Reservation Key must be specified. 1649.It replace_lost 1650Replace Lost Reservation information. 1651.El 1652.It Fl a 1653Set the All Target Ports (ALL_TG_PT) bit. 1654This requests that the key registration be applied to all target ports and 1655not just the particular target port that receives the command. 1656This only applies to the register and register_ignore actions. 1657.It Fl I Ar tid 1658Specify a Transport ID. 1659This only applies to the Register and Register and Move service actions for 1660Persistent Reserve Out. 1661Multiple Transport IDs may be specified with multiple 1662.Fl I 1663arguments. 1664With the Register service action, specifying one or more Transport IDs 1665implicitly enables the 1666.Fl S 1667option which turns on the SPEC_I_PT bit. 1668Transport IDs generally have the format protocol,id. 1669.Bl -tag -width 5n 1670.It SAS 1671A SAS Transport ID consists of 1672.Dq sas, 1673followed by a 64-bit SAS address. 1674For example: 1675.Pp 1676.Dl sas,0x1234567812345678 1677.It FC 1678A Fibre Channel Transport ID consists of 1679.Dq fcp, 1680followed by a 64-bit Fibre Channel World Wide Name. 1681For example: 1682.Pp 1683.Dl fcp,0x1234567812345678 1684.It SPI 1685A Parallel SCSI address consists of 1686.Dq spi, 1687followed by a SCSI target ID and a relative target port identifier. 1688For example: 1689.Pp 1690.Dl spi,4,1 1691.It 1394 1692An IEEE 1394 (Firewire) Transport ID consists of 1693.Dq sbp, 1694followed by a 64-bit EUI-64 IEEE 1394 node unique identifier. 1695For example: 1696.Pp 1697.Dl sbp,0x1234567812345678 1698.It RDMA 1699A SCSI over RDMA Transport ID consists of 1700.Dq srp, 1701followed by a 128-bit RDMA initiator port identifier. 1702The port identifier must be exactly 32 or 34 (if the leading 0x is 1703included) hexadecimal digits. 1704Only hexadecimal (base 16) numbers are supported. 1705For example: 1706.Pp 1707.Dl srp,0x12345678123456781234567812345678 1708.It iSCSI 1709An iSCSI Transport ID consists an iSCSI name and optionally a separator and 1710iSCSI session ID. 1711For example, if only the iSCSI name is specified: 1712.Pp 1713.Dl iqn.2012-06.com.example:target0 1714.Pp 1715If the iSCSI separator and initiator session ID are specified: 1716.Pp 1717.Dl iqn.2012-06.com.example:target0,i,0x123 1718.It PCIe 1719A SCSI over PCIe Transport ID consists of 1720.Dq sop, 1721followed by a PCIe Routing ID. 1722The Routing ID consists of a bus, device and function or in the alternate 1723form, a bus and function. 1724The bus must be in the range of 0 to 255 inclusive and the device must be 1725in the range of 0 to 31 inclusive. 1726The function must be in the range of 0 to 7 inclusive if the standard form 1727is used, and in the range of 0 to 255 inclusive if the alternate form is 1728used. 1729For example, if a bus, device and function are specified for the standard 1730Routing ID form: 1731.Pp 1732.Dl sop,4,5,1 1733.Pp 1734If the alternate Routing ID form is used: 1735.Pp 1736.Dl sop,4,1 1737.El 1738.It Fl k Ar key 1739Specify the Reservation Key. 1740This may be in decimal, octal or hexadecimal format. 1741The value is zero by default if not otherwise specified. 1742The value must be between 0 and 2^64 - 1, inclusive. 1743.It Fl K Ar key 1744Specify the Service Action Reservation Key. 1745This may be in decimal, octal or hexadecimal format. 1746The value is zero by default if not otherwise specified. 1747The value must be between 0 and 2^64 - 1, inclusive. 1748.It Fl p 1749Enable the Activate Persist Through Power Loss bit. 1750This is only used for the register and register_ignore actions. 1751This requests that the reservation persist across power loss events. 1752.It Fl s Ar scope 1753Specify the scope of the reservation. 1754The scope may be specified by name or by number. 1755The scope is ignored for register, register_ignore and clear. 1756If the desired scope isn't available by name, you may specify the number. 1757.Bl -tag -width 7n 1758.It lun 1759LUN scope (0x00). 1760This encompasses the entire LUN. 1761.It extent 1762Extent scope (0x01). 1763.It element 1764Element scope (0x02). 1765.El 1766.It Fl R Ar rtp 1767Specify the Relative Target Port. 1768This only applies to the Register and Move service action of the Persistent 1769Reserve Out command. 1770.It Fl S 1771Enable the SPEC_I_PT bit. 1772This only applies to the Register service action of Persistent Reserve Out. 1773You must also specify at least one Transport ID with 1774.Fl I 1775if this option is set. 1776If you specify a Transport ID, this option is automatically set. 1777It is an error to specify this option for any service action other than 1778Register. 1779.It Fl T Ar type 1780Specify the reservation type. 1781The reservation type may be specified by name or by number. 1782If the desired reservation type isn't available by name, you may specify 1783the number. 1784Supported reservation type names: 1785.Bl -tag -width 11n 1786.It read_shared 1787Read Shared mode. 1788.It wr_ex 1789Write Exclusive mode. 1790May also be specified as 1791.Dq write_exclusive . 1792.It rd_ex 1793Read Exclusive mode. 1794May also be specified as 1795.Dq read_exclusive . 1796.It ex_ac 1797Exclusive access mode. 1798May also be specified as 1799.Dq exclusive_access . 1800.It wr_ex_ro 1801Write Exclusive Registrants Only mode. 1802May also be specified as 1803.Dq write_exclusive_reg_only . 1804.It ex_ac_ro 1805Exclusive Access Registrants Only mode. 1806May also be specified as 1807.Dq exclusive_access_reg_only . 1808.It wr_ex_ar 1809Write Exclusive All Registrants mode. 1810May also be specified as 1811.Dq write_exclusive_all_regs . 1812.It ex_ac_ar 1813Exclusive Access All Registrants mode. 1814May also be specified as 1815.Dq exclusive_access_all_regs . 1816.El 1817.It Fl U 1818Specify that the target should unregister the initiator that sent 1819the Register and Move request. 1820By default, the target will not unregister the initiator that sends the 1821Register and Move request. 1822This option only applies to the Register and Move service action of the 1823Persistent Reserve Out command. 1824.El 1825.It Ic help 1826Print out verbose usage information. 1827.El 1828.Sh ENVIRONMENT 1829The 1830.Ev SCSI_MODES 1831variable allows the user to specify an alternate mode page format file. 1832.Pp 1833The 1834.Ev EDITOR 1835variable determines which text editor 1836.Nm 1837starts when editing mode pages. 1838.Sh FILES 1839.Bl -tag -width /usr/share/misc/scsi_modes -compact 1840.It Pa /usr/share/misc/scsi_modes 1841is the SCSI mode format database. 1842.It Pa /dev/xpt0 1843is the transport layer device. 1844.It Pa /dev/pass* 1845are the CAM application passthrough devices. 1846.El 1847.Sh EXAMPLES 1848.Dl camcontrol eject -n cd -u 1 -v 1849.Pp 1850Eject the CD from cd1, and print SCSI sense information if the command 1851fails. 1852.Pp 1853.Dl camcontrol tur da0 1854.Pp 1855Send the SCSI test unit ready command to da0. 1856The 1857.Nm 1858utility will report whether the disk is ready, but will not display sense 1859information if the command fails since the 1860.Fl v 1861switch was not specified. 1862.Bd -literal -offset indent 1863camcontrol tur da1 -E -C 4 -t 50 -v 1864.Ed 1865.Pp 1866Send a test unit ready command to da1. 1867Enable kernel error recovery. 1868Specify a retry count of 4, and a timeout of 50 seconds. 1869Enable sense 1870printing (with the 1871.Fl v 1872flag) if the command fails. 1873Since error recovery is turned on, the 1874disk will be spun up if it is not currently spinning. 1875The 1876.Nm 1877utility will report whether the disk is ready. 1878.Bd -literal -offset indent 1879camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e 1880 -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" 1881.Ed 1882.Pp 1883Issue a READ BUFFER command (0x3C) to cd1. 1884Display the buffer size of cd1, 1885and display the first 10 bytes from the cache on cd1. 1886Display SCSI sense 1887information if the command fails. 1888.Bd -literal -offset indent 1889camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e 1890 -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 1891.Ed 1892.Pp 1893Issue a WRITE BUFFER (0x3B) command to cd1. 1894Write out 10 bytes of data, 1895not including the (reserved) 4 byte header. 1896Print out sense information if 1897the command fails. 1898Be very careful with this command, improper use may 1899cause data corruption. 1900.Bd -literal -offset indent 1901camcontrol modepage da3 -m 1 -e -P 3 1902.Ed 1903.Pp 1904Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the 1905settings on the drive. 1906Mode page 1 contains a disk drive's auto read and 1907write reallocation settings, among other things. 1908.Pp 1909.Dl camcontrol rescan all 1910.Pp 1911Rescan all SCSI busses in the system for devices that have been added, 1912removed or changed. 1913.Pp 1914.Dl camcontrol rescan 0 1915.Pp 1916Rescan SCSI bus 0 for devices that have been added, removed or changed. 1917.Pp 1918.Dl camcontrol rescan 0:1:0 1919.Pp 1920Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or 1921changed. 1922.Pp 1923.Dl camcontrol tags da5 -N 24 1924.Pp 1925Set the number of concurrent transactions for da5 to 24. 1926.Bd -literal -offset indent 1927camcontrol negotiate -n da -u 4 -T disable 1928.Ed 1929.Pp 1930Disable tagged queueing for da4. 1931.Bd -literal -offset indent 1932camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a 1933.Ed 1934.Pp 1935Negotiate a sync rate of 20MHz and an offset of 15 with da3. 1936Then send a 1937Test Unit Ready command to make the settings take effect. 1938.Bd -literal -offset indent 1939camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" 1940.Ed 1941.Pp 1942Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs 1943it contains. 1944Display SMP errors if the command fails. 1945.Bd -literal -offset indent 1946camcontrol security ada0 1947.Ed 1948.Pp 1949Report security support and settings for ada0 1950.Bd -literal -offset indent 1951camcontrol security ada0 -U user -s MyPass 1952.Ed 1953.Pp 1954Enable security on device ada0 with the password MyPass 1955.Bd -literal -offset indent 1956camcontrol security ada0 -U user -e MyPass 1957.Ed 1958.Pp 1959Secure erase ada0 which has had security enabled with user password MyPass 1960.Pp 1961.Em WARNING! WARNING! WARNING! 1962.Pp 1963This will 1964.Em ERASE ALL 1965data from the device, so backup your data before using! 1966.Pp 1967This command can be used against an SSD drive to restoring it to 1968factory default write performance. 1969.Bd -literal -offset indent 1970camcontrol hpa ada0 1971.Ed 1972.Pp 1973Report HPA support and settings for ada0 (also reported via 1974identify). 1975.Bd -literal -offset indent 1976camcontrol hpa ada0 -s 10240 1977.Ed 1978.Pp 1979Enables HPA on ada0 setting the maximum reported sectors to 10240. 1980.Pp 1981.Em WARNING! WARNING! WARNING! 1982.Pp 1983This will 1984.Em PREVENT ACCESS 1985to all data on the device beyond this limit until HPA is disabled by setting 1986HPA to native max sectors of the device, which can only be done after a 1987power-on or hardware reset! 1988.Pp 1989.Em DO NOT 1990use this on a device which has an active filesystem! 1991.Bd -literal -offset indent 1992camcontrol persist da0 -v -i read_keys 1993.Ed 1994.Pp 1995This will read any persistent reservation keys registered with da0, and 1996display any errors encountered when sending the PERSISTENT RESERVE IN 1997.Tn SCSI 1998command. 1999.Bd -literal -offset indent 2000camcontrol persist da0 -v -o register -a -K 0x12345678 2001.Ed 2002.Pp 2003This will register the persistent reservation key 0x12345678 with da0, 2004apply that registration to all ports on da0, and display any errors that 2005occur when sending the PERSISTENT RESERVE OUT command. 2006.Bd -literal -offset indent 2007camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac 2008.Ed 2009.Pp 2010This will reserve da0 for the exlusive use of the initiator issuing the 2011command. 2012The scope of the reservation is the entire LUN. 2013Any errors sending the PERSISTENT RESERVE OUT command will be displayed. 2014.Bd -literal -offset indent 2015camcontrol persist da0 -v -i read_full 2016.Ed 2017.Pp 2018This will display the full status of all reservations on da0 and print out 2019status if there are any errors. 2020.Bd -literal -offset indent 2021camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac 2022.Ed 2023.Pp 2024This will release a reservation on da0 of the type ex_ac 2025(Exclusive Access). 2026The Reservation Key for this registration is 0x12345678. 2027Any errors that occur will be displayed. 2028.Bd -literal -offset indent 2029camcontrol persist da0 -v -o register -K 0x12345678 -S \e 2030 -I sas,0x1234567812345678 -I sas,0x8765432187654321 2031.Ed 2032.Pp 2033This will register the key 0x12345678 with da0, specifying that it applies 2034to the SAS initiators with SAS addresses 0x1234567812345678 and 20350x8765432187654321. 2036.Bd -literal -offset indent 2037camcontrol persist da0 -v -o register_move -k 0x87654321 \e 2038 -K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678 2039.Ed 2040.Pp 2041This will move the registration from the current initiator, whose 2042Registration Key is 0x87654321, to the Fibre Channel initiator with the 2043Fiber Channel World Wide Node Name 0x1234567812345678. 2044A new registration key, 0x12345678, will be registered for the initiator 2045with the Fibre Channel World Wide Node Name 0x1234567812345678, and the 2046current initiator will be unregistered from the target. 2047The reservation will be moved to relative target port 2 on the target 2048device. 2049The registration will persist across power losses. 2050.Sh SEE ALSO 2051.Xr cam 3 , 2052.Xr cam_cdbparse 3 , 2053.Xr cam 4 , 2054.Xr pass 4 , 2055.Xr xpt 4 2056.Sh HISTORY 2057The 2058.Nm 2059utility first appeared in 2060.Fx 3.0 . 2061.Pp 2062The mode page editing code and arbitrary SCSI command code are based upon 2063code in the old 2064.Xr scsi 8 2065utility and 2066.Xr scsi 3 2067library, written by Julian Elischer and Peter Dufault. 2068The 2069.Xr scsi 8 2070program first appeared in 2071.Bx 386 0.1.2.4 , 2072and first appeared in 2073.Fx 2074in 2075.Fx 2.0.5 . 2076.Sh AUTHORS 2077.An Kenneth Merry Aq Mt ken@FreeBSD.org 2078.Sh BUGS 2079The code that parses the generic command line arguments does not know that 2080some of the subcommands take multiple arguments. 2081So if, for instance, you 2082tried something like this: 2083.Bd -literal -offset indent 2084camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v 2085.Ed 2086.Pp 2087The sense information from the test unit ready command would not get 2088printed out, since the first 2089.Xr getopt 3 2090call in 2091.Nm 2092bails out when it sees the second argument to 2093.Fl c 2094(0x00), 2095above. 2096Fixing this behavior would take some gross code, or changes to the 2097.Xr getopt 3 2098interface. 2099The best way to circumvent this problem is to always make sure 2100to specify generic 2101.Nm 2102arguments before any command-specific arguments. 2103