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