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