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 April 24, 2013 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 v 45.Nm 46.Ic periphlist 47.Op device id 48.Op Fl n Ar dev_name 49.Op Fl u Ar unit_number 50.Nm 51.Ic tur 52.Op device id 53.Op generic args 54.Nm 55.Ic inquiry 56.Op device id 57.Op generic args 58.Op Fl D 59.Op Fl S 60.Op Fl R 61.Nm 62.Ic identify 63.Op device id 64.Op generic args 65.Op Fl v 66.Nm 67.Ic reportluns 68.Op device id 69.Op generic args 70.Op Fl c 71.Op Fl l 72.Op Fl r Ar reporttype 73.Nm 74.Ic readcap 75.Op device id 76.Op generic args 77.Op Fl b 78.Op Fl h 79.Op Fl H 80.Op Fl N 81.Op Fl q 82.Op Fl s 83.Nm 84.Ic start 85.Op device id 86.Op generic args 87.Nm 88.Ic stop 89.Op device id 90.Op generic args 91.Nm 92.Ic load 93.Op device id 94.Op generic args 95.Nm 96.Ic eject 97.Op device id 98.Op generic args 99.Nm 100.Ic rescan 101.Aq all | bus Ns Op :target:lun 102.Nm 103.Ic reset 104.Aq all | bus Ns Op :target:lun 105.Nm 106.Ic defects 107.Op device id 108.Op generic args 109.Aq Fl f Ar format 110.Op Fl P 111.Op Fl G 112.Nm 113.Ic modepage 114.Op device id 115.Op generic args 116.Aq Fl m Ar page | Fl l 117.Op Fl P Ar pgctl 118.Op Fl b | Fl e 119.Op Fl d 120.Nm 121.Ic cmd 122.Op device id 123.Op generic args 124.Aq Fl a Ar cmd Op args 125.Aq Fl c Ar cmd Op args 126.Op Fl d 127.Op Fl f 128.Op Fl i Ar len Ar fmt 129.Bk -words 130.Op Fl o Ar len Ar fmt Op args 131.Op Fl r Ar fmt 132.Ek 133.Nm 134.Ic smpcmd 135.Op device id 136.Op generic args 137.Aq Fl r Ar len Ar fmt Op args 138.Aq Fl R Ar len Ar fmt Op args 139.Nm 140.Ic smprg 141.Op device id 142.Op generic args 143.Op Fl l 144.Nm 145.Ic smppc 146.Op device id 147.Op generic args 148.Aq Fl p Ar phy 149.Op Fl l 150.Op Fl o Ar operation 151.Op Fl d Ar name 152.Op Fl m Ar rate 153.Op Fl M Ar rate 154.Op Fl T Ar pp_timeout 155.Op Fl a Ar enable|disable 156.Op Fl A Ar enable|disable 157.Op Fl s Ar enable|disable 158.Op Fl S Ar enable|disable 159.Nm 160.Ic smpphylist 161.Op device id 162.Op generic args 163.Op Fl l 164.Op Fl q 165.Nm 166.Ic smpmaninfo 167.Op device id 168.Op generic args 169.Op Fl l 170.Nm 171.Ic debug 172.Op Fl I 173.Op Fl P 174.Op Fl T 175.Op Fl S 176.Op Fl X 177.Op Fl c 178.Op Fl p 179.Aq all|off|bus Ns Op :target Ns Op :lun 180.Nm 181.Ic tags 182.Op device id 183.Op generic args 184.Op Fl N Ar tags 185.Op Fl q 186.Op Fl v 187.Nm 188.Ic negotiate 189.Op device id 190.Op generic args 191.Op Fl c 192.Op Fl D Ar enable|disable 193.Op Fl M Ar mode 194.Op Fl O Ar offset 195.Op Fl q 196.Op Fl R Ar syncrate 197.Op Fl T Ar enable|disable 198.Op Fl U 199.Op Fl W Ar bus_width 200.Op Fl v 201.Nm 202.Ic format 203.Op device id 204.Op generic args 205.Op Fl q 206.Op Fl r 207.Op Fl w 208.Op Fl y 209.Nm 210.Ic idle 211.Op device id 212.Op generic args 213.Op Fl t Ar time 214.Nm 215.Ic standby 216.Op device id 217.Op generic args 218.Op Fl t Ar time 219.Nm 220.Ic sleep 221.Op device id 222.Op generic args 223.Nm 224.Ic fwdownload 225.Op device id 226.Op generic args 227.Aq Fl f Ar fw_image 228.Op Fl y 229.Op Fl s 230.Nm 231.Ic security 232.Op device id 233.Op generic args 234.Op Fl d Ar pwd 235.Op Fl e Ar pwd 236.Op Fl f 237.Op Fl h Ar pwd 238.Op Fl k Ar pwd 239.Op Fl l Ar high|maximum 240.Op Fl q 241.Op Fl s Ar pwd 242.Op Fl T Ar timeout 243.Op Fl U Ar user|master 244.Op Fl y 245.Nm 246.Ic hpa 247.Op device id 248.Op generic args 249.Op Fl f 250.Op Fl l 251.Op Fl P 252.Op Fl p Ar pwd 253.Op Fl q 254.Op Fl s Ar max_sectors 255.Op Fl U Ar pwd 256.Op Fl y 257.Nm 258.Ic help 259.Sh DESCRIPTION 260The 261.Nm 262utility is designed to provide a way for users to access and control the 263.Fx 264CAM subsystem. 265.Pp 266The 267.Nm 268utility 269can cause a loss of data and/or system crashes if used improperly. 270Even 271expert users are encouraged to exercise caution when using this command. 272Novice users should stay away from this utility. 273.Pp 274The 275.Nm 276utility has a number of primary functions, many of which support an optional 277device identifier. 278A device identifier can take one of three forms: 279.Bl -tag -width 14n 280.It deviceUNIT 281Specify a device name and unit number combination, like "da5" or "cd3". 282.It bus:target 283Specify a bus number and target id. 284The bus number can be determined from 285the output of 286.Dq camcontrol devlist . 287The lun defaults to 0. 288.It bus:target:lun 289Specify the bus, target and lun for a device. 290(e.g.\& 1:2:0) 291.El 292.Pp 293The device identifier, if it is specified, 294.Em must 295come immediately after the function name, and before any generic or 296function-specific arguments. 297Note that the 298.Fl n 299and 300.Fl u 301arguments described below will override any device name or unit number 302specified beforehand. 303The 304.Fl n 305and 306.Fl u 307arguments will 308.Em not 309override a specified bus:target or bus:target:lun, however. 310.Pp 311Most of the 312.Nm 313primary functions support these generic arguments: 314.Bl -tag -width 14n 315.It Fl C Ar count 316SCSI command retry count. 317In order for this to work, error recovery 318.Pq Fl E 319must be turned on. 320.It Fl E 321Instruct the kernel to perform generic SCSI error recovery for the given 322command. 323This is needed in order for the retry count 324.Pq Fl C 325to be honored. 326Other than retrying commands, the generic error recovery in 327the code will generally attempt to spin up drives that are not spinning. 328It may take some other actions, depending upon the sense code returned from 329the command. 330.It Fl n Ar dev_name 331Specify the device type to operate on, e.g.\& "da", "cd". 332.It Fl t Ar timeout 333SCSI command timeout in seconds. 334This overrides the default timeout for 335any given command. 336.It Fl u Ar unit_number 337Specify the device unit number, e.g.\& "1", "5". 338.It Fl v 339Be verbose, print out sense information for failed SCSI commands. 340.El 341.Pp 342Primary command functions: 343.Bl -tag -width periphlist 344.It Ic devlist 345List all physical devices (logical units) attached to the CAM subsystem. 346This also includes a list of peripheral drivers attached to each device. 347With the 348.Fl v 349argument, SCSI bus number, adapter name and unit numbers are printed as 350well. 351.It Ic periphlist 352List all peripheral drivers attached to a given physical device (logical 353unit). 354.It Ic tur 355Send the SCSI test unit ready (0x00) command to the given device. 356The 357.Nm 358utility will report whether the device is ready or not. 359.It Ic inquiry 360Send a SCSI inquiry command (0x12) to a device. 361By default, 362.Nm 363will print out the standard inquiry data, device serial number, and 364transfer rate information. 365The user can specify that only certain types of 366inquiry data be printed: 367.Bl -tag -width 4n 368.It Fl D 369Get the standard inquiry data. 370.It Fl S 371Print out the serial number. 372If this flag is the only one specified, 373.Nm 374will not print out "Serial Number" before the value returned by the drive. 375This is to aid in script writing. 376.It Fl R 377Print out transfer rate information. 378.El 379.It Ic identify 380Send a ATA identify command (0xec) to a device. 381.It Ic reportluns 382Send the SCSI REPORT LUNS (0xA0) command to the given device. 383By default, 384.Nm 385will print out the list of logical units (LUNs) supported by the target device. 386There are a couple of options to modify the output: 387.Bl -tag -width 14n 388.It Fl c 389Just print out a count of LUNs, not the actual LUN numbers. 390.It Fl l 391Just print out the LUNs, and do not print out the count. 392.It Fl r Ar reporttype 393Specify the type of report to request from the target: 394.Bl -tag -width 012345678 395.It default 396Return the default report. 397This is the 398.Nm 399default. 400Most targets will support this report if they support the REPORT LUNS 401command. 402.It wellknown 403Return only well known LUNs. 404.It all 405Return all available LUNs. 406.El 407.El 408.Pp 409.Nm 410will try to print out LUN numbers in a reasonable format. 411It can understand the peripheral, flat, LUN and extended LUN formats. 412.It Ic readcap 413Send the SCSI READ CAPACITY command to the given device and display 414the results. 415If the device is larger than 2TB, the SCSI READ CAPACITY (16) service 416action will be sent to obtain the full size of the device. 417By default, 418.Nm 419will print out the last logical block of the device, and the blocksize of 420the device in bytes. 421To modify the output format, use the following options: 422.Bl -tag -width 5n 423.It Fl b 424Just print out the blocksize, not the last block or device size. 425This cannot be used with 426.Fl N 427or 428.Fl s . 429.It Fl h 430Print out the device size in human readable (base 2, 1K == 1024) format. 431This implies 432.Fl N 433and cannot be used with 434.Fl q 435or 436.Fl b . 437.It Fl H 438Print out the device size in human readable (base 10, 1K == 1000) format. 439.It Fl N 440Print out the number of blocks in the device instead of the last logical 441block. 442.It Fl q 443Quiet, print out the numbers only (separated by a comma if 444.Fl b 445or 446.Fl s 447are not specified). 448.It Fl s 449Print out the last logical block or the size of the device only, and omit 450the blocksize. 451.El 452.It Ic start 453Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 454start bit set. 455.It Ic stop 456Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 457start bit cleared. 458.It Ic load 459Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 460start bit set and the load/eject bit set. 461.It Ic eject 462Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 463start bit cleared and the load/eject bit set. 464.It Ic rescan 465Tell the kernel to scan all busses in the system (with the 466.Ar all 467argument), the given bus (XPT_SCAN_BUS), or bus:target:lun 468(XPT_SCAN_LUN) for new devices or devices that have gone away. 469The user 470may specify a scan of all busses, a single bus, or a lun. 471Scanning all luns 472on a target is not supported. 473.It Ic reset 474Tell the kernel to reset all busses in the system (with the 475.Ar all 476argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus 477reset for that bus, or to reset the given bus:target:lun 478(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after 479connecting to that device. 480Note that this can have a destructive impact 481on the system. 482.It Ic defects 483Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and 484print out any combination of: the total number of defects, the primary 485defect list (PLIST), and the grown defect list (GLIST). 486.Bl -tag -width 11n 487.It Fl f Ar format 488The three format options are: 489.Em block , 490to print out the list as logical blocks, 491.Em bfi , 492to print out the list in bytes from index format, and 493.Em phys , 494to print out the list in physical sector format. 495The format argument is 496required. 497Most drives support the physical sector format. 498Some drives 499support the logical block format. 500Many drives, if they do not support the 501requested format, return the data in an alternate format, along with sense 502information indicating that the requested data format is not supported. 503The 504.Nm 505utility 506attempts to detect this, and print out whatever format the drive returns. 507If the drive uses a non-standard sense code to report that it does not 508support the requested format, 509.Nm 510will probably see the error as a failure to complete the request. 511.It Fl G 512Print out the grown defect list. 513This is a list of bad blocks that have 514been remapped since the disk left the factory. 515.It Fl P 516Print out the primary defect list. 517.El 518.Pp 519If neither 520.Fl P 521nor 522.Fl G 523is specified, 524.Nm 525will print out the number of defects given in the READ DEFECT DATA header 526returned from the drive. 527Some drives will report 0 defects if neither the primary or grown defect 528lists are requested. 529.It Ic modepage 530Allows the user to display and optionally edit a SCSI mode page. 531The mode 532page formats are located in 533.Pa /usr/share/misc/scsi_modes . 534This can be overridden by specifying a different file in the 535.Ev SCSI_MODES 536environment variable. 537The 538.Ic modepage 539command takes several arguments: 540.Bl -tag -width 12n 541.It Fl d 542Disable block descriptors for mode sense. 543.It Fl b 544Displays mode page data in binary format. 545.It Fl e 546This flag allows the user to edit values in the mode page. 547The user may 548either edit mode page values with the text editor pointed to by his 549.Ev EDITOR 550environment variable, or supply mode page values via standard input, using 551the same format that 552.Nm 553uses to display mode page values. 554The editor will be invoked if 555.Nm 556detects that standard input is terminal. 557.It Fl l 558Lists all available mode pages. 559.It Fl m Ar mode_page 560This specifies the number of the mode page the user would like to view 561and/or edit. 562This argument is mandatory unless 563.Fl l 564is specified. 565.It Fl P Ar pgctl 566This allows the user to specify the page control field. 567Possible values are: 568.Bl -tag -width xxx -compact 569.It 0 570Current values 571.It 1 572Changeable values 573.It 2 574Default values 575.It 3 576Saved values 577.El 578.El 579.It Ic cmd 580Allows the user to send an arbitrary ATA or SCSI CDB to any device. 581The 582.Ic cmd 583function requires the 584.Fl c 585argument to specify SCSI CDB or the 586.Fl a 587argument to specify ATA Command Block registers values. 588Other arguments are optional, depending on 589the command type. 590The command and data specification syntax is documented 591in 592.Xr cam_cdbparse 3 . 593NOTE: If the CDB specified causes data to be transferred to or from the 594SCSI device in question, you MUST specify either 595.Fl i 596or 597.Fl o . 598.Bl -tag -width 17n 599.It Fl a Ar cmd Op args 600This specifies the content of 12 ATA Command Block registers (command, 601features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp. 602lba_high_exp, features_exp, sector_count, sector_count_exp). 603.It Fl c Ar cmd Op args 604This specifies the SCSI CDB. 605SCSI CDBs may be 6, 10, 12 or 16 bytes. 606.It Fl d 607Specifies DMA protocol to be used for ATA command. 608.It Fl f 609Specifies FPDMA (NCQ) protocol to be used for ATA command. 610.It Fl i Ar len Ar fmt 611This specifies the amount of data to read, and how it should be displayed. 612If the format is 613.Sq - , 614.Ar len 615bytes of data will be read from the device and written to standard output. 616.It Fl o Ar len Ar fmt Op args 617This specifies the amount of data to be written to a device, and the data 618that is to be written. 619If the format is 620.Sq - , 621.Ar len 622bytes of data will be read from standard input and written to the device. 623.It Fl r Ar fmt 624This specifies that 11 result ATA Command Block registers should be displayed 625(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp, 626lba_high_exp, sector_count, sector_count_exp), and how. 627If the format is 628.Sq - , 62911 result registers will be written to standard output in hex. 630.El 631.It Ic smpcmd 632Allows the user to send an arbitrary Serial 633Management Protocol (SMP) command to a device. 634The 635.Ic smpcmd 636function requires the 637.Fl r 638argument to specify the SMP request to be sent, and the 639.Fl R 640argument to specify the format of the SMP response. 641The syntax for the SMP request and response arguments is documented in 642.Xr cam_cdbparse 3 . 643.Pp 644Note that SAS adapters that support SMP passthrough (at least the currently 645known adapters) do not accept CRC bytes from the user in the request and do 646not pass CRC bytes back to the user in the response. 647Therefore users should not include the CRC bytes in the length of the 648request and not expect CRC bytes to be returned in the response. 649.Bl -tag -width 17n 650.It Fl r Ar len Ar fmt Op args 651This specifies the size of the SMP request, without the CRC bytes, and the 652SMP request format. If the format is 653.Sq - , 654.Ar len 655bytes of data will be read from standard input and written as the SMP 656request. 657.It Fl R Ar len Ar fmt Op args 658This specifies the size of the buffer allocated for the SMP response, and 659the SMP response format. 660If the format is 661.Sq - , 662.Ar len 663bytes of data will be allocated for the response and the response will be 664written to standard output. 665.El 666.It Ic smprg 667Allows the user to send the Serial Management Protocol (SMP) Report General 668command to a device. 669.Nm 670will display the data returned by the Report General command. 671If the SMP target supports the long response format, the additional data 672will be requested and displayed automatically. 673.Bl -tag -width 8n 674.It Fl l 675Request the long response format only. 676Not all SMP targets support the long response format. 677This option causes 678.Nm 679to skip sending the initial report general request without the long bit set 680and only issue a report general request with the long bit set. 681.El 682.It Ic smppc 683Allows the user to issue the Serial Management Protocol (SMP) PHY Control 684command to a device. 685This function should be used with some caution, as it can render devices 686inaccessible, and could potentially cause data corruption as well. 687The 688.Fl p 689argument is required to specify the PHY to operate on. 690.Bl -tag -width 17n 691.It Fl p Ar phy 692Specify the PHY to operate on. 693This argument is required. 694.It Fl l 695Request the long request/response format. 696Not all SMP targets support the long response format. 697For the PHY Control command, this currently only affects whether the 698request length is set to a value other than 0. 699.It Fl o Ar operation 700Specify a PHY control operation. 701Only one 702.Fl o 703operation may be specified. 704The operation may be specified numerically (in decimal, hexadecimal, or octal) 705or one of the following operation names may be specified: 706.Bl -tag -width 16n 707.It nop 708No operation. 709It is not necessary to specify this argument. 710.It linkreset 711Send the LINK RESET command to the phy. 712.It hardreset 713Send the HARD RESET command to the phy. 714.It disable 715Send the DISABLE command to the phy. 716Note that the LINK RESET or HARD RESET commands should re-enable the phy. 717.It clearerrlog 718Send the CLEAR ERROR LOG command. 719This clears the error log counters for the specified phy. 720.It clearaffiliation 721Send the CLEAR AFFILIATION command. 722This clears the affiliation from the STP initiator port with the same SAS 723address as the SMP initiator that requests the clear operation. 724.It sataportsel 725Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy. 726This will cause a SATA port selector to use the given phy as its active phy 727and make the other phy inactive. 728.It clearitnl 729Send the CLEAR STP I_T NEXUS LOSS command to the PHY. 730.It setdevname 731Send the SET ATTACHED DEVICE NAME command to the PHY. 732This requires the 733.Fl d 734argument to specify the device name. 735.El 736.It Fl d Ar name 737Specify the attached device name. 738This option is needed with the 739.Fl o Ar setdevname 740phy operation. 741The name is a 64-bit number, and can be specified in decimal, hexadecimal 742or octal format. 743.It Fl m Ar rate 744Set the minimum physical link rate for the phy. 745This is a numeric argument. 746Currently known link rates are: 747.Bl -tag -width 5n 748.It 0x0 749Do not change current value. 750.It 0x8 7511.5 Gbps 752.It 0x9 7533 Gbps 754.It 0xa 7556 Gbps 756.El 757.Pp 758Other values may be specified for newer physical link rates. 759.It Fl M Ar rate 760Set the maximum physical link rate for the phy. 761This is a numeric argument. 762See the 763.Fl m 764argument description for known link rate arguments. 765.It Fl T Ar pp_timeout 766Set the partial pathway timeout value, in microseconds. 767See the 768.Tn ANSI 769.Tn SAS 770Protocol Layer (SPL) 771specification for more information on this field. 772.It Fl a Ar enable|disable 773Enable or disable SATA slumber phy power conditions. 774.It Fl A Ar enable|disable 775Enable or disable SATA partial power conditions. 776.It Fl s Ar enable|disable 777Enable or disable SAS slumber phy power conditions. 778.It Fl S Ar enable|disable 779Enable or disable SAS partial phy power conditions. 780.El 781.It Ic smpphylist 782List phys attached to a SAS expander, the address of the end device 783attached to the phy, and the inquiry data for that device and peripheral 784devices attached to that device. 785The inquiry data and peripheral devices are displayed if available. 786.Bl -tag -width 5n 787.It Fl l 788Turn on the long response format for the underlying SMP commands used for 789this command. 790.It Fl q 791Only print out phys that are attached to a device in the CAM EDT (Existing 792Device Table). 793.El 794.It Ic smpmaninfo 795Send the SMP Report Manufacturer Information command to the device and 796display the response. 797.Bl -tag -width 5n 798.It Fl l 799Turn on the long response format for the underlying SMP commands used for 800this command. 801.El 802.It Ic debug 803Turn on CAM debugging printfs in the kernel. 804This requires options CAMDEBUG 805in your kernel config file. 806WARNING: enabling debugging printfs currently 807causes an EXTREME number of kernel printfs. 808You may have difficulty 809turning off the debugging printfs once they start, since the kernel will be 810busy printing messages and unable to service other requests quickly. 811The 812.Ic debug 813function takes a number of arguments: 814.Bl -tag -width 18n 815.It Fl I 816Enable CAM_DEBUG_INFO printfs. 817.It Fl P 818Enable CAM_DEBUG_PERIPH printfs. 819.It Fl T 820Enable CAM_DEBUG_TRACE printfs. 821.It Fl S 822Enable CAM_DEBUG_SUBTRACE printfs. 823.It Fl X 824Enable CAM_DEBUG_XPT printfs. 825.It Fl c 826Enable CAM_DEBUG_CDB printfs. 827This will cause the kernel to print out the 828SCSI CDBs sent to the specified device(s). 829.It Fl p 830Enable CAM_DEBUG_PROBE printfs. 831.It all 832Enable debugging for all devices. 833.It off 834Turn off debugging for all devices 835.It bus Ns Op :target Ns Op :lun 836Turn on debugging for the given bus, target or lun. 837If the lun or target 838and lun are not specified, they are wildcarded. 839(i.e., just specifying a 840bus turns on debugging printfs for all devices on that bus.) 841.El 842.It Ic tags 843Show or set the number of "tagged openings" or simultaneous transactions 844we attempt to queue to a particular device. 845By default, the 846.Ic tags 847command, with no command-specific arguments (i.e., only generic arguments) 848prints out the "soft" maximum number of transactions that can be queued to 849the device in question. 850For more detailed information, use the 851.Fl v 852argument described below. 853.Bl -tag -width 7n 854.It Fl N Ar tags 855Set the number of tags for the given device. 856This must be between the 857minimum and maximum number set in the kernel quirk table. 858The default for 859most devices that support tagged queueing is a minimum of 2 and a maximum 860of 255. 861The minimum and maximum values for a given device may be 862determined by using the 863.Fl v 864switch. 865The meaning of the 866.Fl v 867switch for this 868.Nm 869subcommand is described below. 870.It Fl q 871Be quiet, and do not report the number of tags. 872This is generally used when 873setting the number of tags. 874.It Fl v 875The verbose flag has special functionality for the 876.Em tags 877argument. 878It causes 879.Nm 880to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: 881.Bl -tag -width 13n 882.It dev_openings 883This is the amount of capacity for transactions queued to a given device. 884.It dev_active 885This is the number of transactions currently queued to a device. 886.It devq_openings 887This is the kernel queue space for transactions. 888This count usually mirrors 889dev_openings except during error recovery operations when 890the device queue is frozen (device is not allowed to receive 891commands), the number of dev_openings is reduced, or transaction 892replay is occurring. 893.It devq_queued 894This is the number of transactions waiting in the kernel queue for capacity 895on the device. 896This number is usually zero unless error recovery is in 897progress. 898.It held 899The held count is the number of CCBs held by peripheral drivers that have 900either just been completed or are about to be released to the transport 901layer for service by a device. 902Held CCBs reserve capacity on a given 903device. 904.It mintags 905This is the current "hard" minimum number of transactions that can be 906queued to a device at once. 907The 908.Ar dev_openings 909value above cannot go below this number. 910The default value for 911.Ar mintags 912is 2, although it may be set higher or lower for various devices. 913.It maxtags 914This is the "hard" maximum number of transactions that can be queued to a 915device at one time. 916The 917.Ar dev_openings 918value cannot go above this number. 919The default value for 920.Ar maxtags 921is 255, although it may be set higher or lower for various devices. 922.El 923.El 924.It Ic negotiate 925Show or negotiate various communication parameters. 926Some controllers may 927not support setting or changing some of these values. 928For instance, the 929Adaptec 174x controllers do not support changing a device's sync rate or 930offset. 931The 932.Nm 933utility 934will not attempt to set the parameter if the controller indicates that it 935does not support setting the parameter. 936To find out what the controller 937supports, use the 938.Fl v 939flag. 940The meaning of the 941.Fl v 942flag for the 943.Ic negotiate 944command is described below. 945Also, some controller drivers do not support 946setting negotiation parameters, even if the underlying controller supports 947negotiation changes. 948Some controllers, such as the Advansys wide 949controllers, support enabling and disabling synchronous negotiation for 950a device, but do not support setting the synchronous negotiation rate. 951.Bl -tag -width 17n 952.It Fl a 953Attempt to make the negotiation settings take effect immediately by sending 954a Test Unit Ready command to the device. 955.It Fl c 956Show or set current negotiation settings. 957This is the default. 958.It Fl D Ar enable|disable 959Enable or disable disconnection. 960.It Fl M Ar mode 961Set ATA mode. 962.It Fl O Ar offset 963Set the command delay offset. 964.It Fl q 965Be quiet, do not print anything. 966This is generally useful when you want to 967set a parameter, but do not want any status information. 968.It Fl R Ar syncrate 969Change the synchronization rate for a device. 970The sync rate is a floating 971point value specified in MHz. 972So, for instance, 973.Sq 20.000 974is a legal value, as is 975.Sq 20 . 976.It Fl T Ar enable|disable 977Enable or disable tagged queueing for a device. 978.It Fl U 979Show or set user negotiation settings. 980The default is to show or set 981current negotiation settings. 982.It Fl v 983The verbose switch has special meaning for the 984.Ic negotiate 985subcommand. 986It causes 987.Nm 988to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the 989controller driver. 990.It Fl W Ar bus_width 991Specify the bus width to negotiate with a device. 992The bus width is 993specified in bits. 994The only useful values to specify are 8, 16, and 32 995bits. 996The controller must support the bus width in question in order for 997the setting to take effect. 998.El 999.Pp 1000In general, sync rate and offset settings will not take effect for a 1001device until a command has been sent to the device. 1002The 1003.Fl a 1004switch above will automatically send a Test Unit Ready to the device so 1005negotiation parameters will take effect. 1006.It Ic format 1007Issue the 1008.Tn SCSI 1009FORMAT UNIT command to the named device. 1010.Pp 1011.Em WARNING! WARNING! WARNING! 1012.Pp 1013Low level formatting a disk will destroy ALL data on the disk. 1014Use 1015extreme caution when issuing this command. 1016Many users low-level format 1017disks that do not really need to be low-level formatted. 1018There are 1019relatively few scenarios that call for low-level formatting a disk. 1020One reason for 1021low-level formatting a disk is to initialize the disk after changing 1022its physical sector size. 1023Another reason for low-level formatting a disk 1024is to revive the disk if you are getting "medium format corrupted" errors 1025from the disk in response to read and write requests. 1026.Pp 1027Some disks take longer than others to format. 1028Users should specify a 1029timeout long enough to allow the format to complete. 1030The default format 1031timeout is 3 hours, which should be long enough for most disks. 1032Some hard 1033disks will complete a format operation in a very short period of time 1034(on the order of 5 minutes or less). 1035This is often because the drive 1036does not really support the FORMAT UNIT command -- it just accepts the 1037command, waits a few minutes and then returns it. 1038.Pp 1039The 1040.Sq format 1041subcommand takes several arguments that modify its default behavior. 1042The 1043.Fl q 1044and 1045.Fl y 1046arguments can be useful for scripts. 1047.Bl -tag -width 6n 1048.It Fl q 1049Be quiet, do not print any status messages. 1050This option will not disable 1051the questions, however. 1052To disable questions, use the 1053.Fl y 1054argument, below. 1055.It Fl r 1056Run in 1057.Dq report only 1058mode. 1059This will report status on a format that is already running on the drive. 1060.It Fl w 1061Issue a non-immediate format command. 1062By default, 1063.Nm 1064issues the FORMAT UNIT command with the immediate bit set. 1065This tells the 1066device to immediately return the format command, before the format has 1067actually completed. 1068Then, 1069.Nm 1070gathers 1071.Tn SCSI 1072sense information from the device every second to determine how far along 1073in the format process it is. 1074If the 1075.Fl w 1076argument is specified, 1077.Nm 1078will issue a non-immediate format command, and will be unable to print any 1079information to let the user know what percentage of the disk has been 1080formatted. 1081.It Fl y 1082Do not ask any questions. 1083By default, 1084.Nm 1085will ask the user if he/she really wants to format the disk in question, 1086and also if the default format command timeout is acceptable. 1087The user 1088will not be asked about the timeout if a timeout is specified on the 1089command line. 1090.El 1091.It Ic idle 1092Put ATA device into IDLE state. Optional parameter 1093.Pq Fl t 1094specifies automatic standby timer value in seconds. Value 0 disables timer. 1095.It Ic standby 1096Put ATA device into STANDBY state. Optional parameter 1097.Pq Fl t 1098specifies automatic standby timer value in seconds. Value 0 disables timer. 1099.It Ic sleep 1100Put ATA device into SLEEP state. Note that the only way get device out of 1101this state may be reset. 1102.It Ic security 1103Update or report security settings, using an ATA identify command (0xec). 1104By default, 1105.Nm 1106will print out the security support and associated settings of the device. 1107The 1108.Ic security 1109command takes several arguments: 1110.Bl -tag -width 0n 1111.It Fl d Ar pwd 1112.Pp 1113Disable device security using the given password for the selected user according 1114to the devices configured security level. 1115.It Fl e Ar pwd 1116.Pp 1117Erase the device using the given password for the selected user. 1118.Pp 1119.Em WARNING! WARNING! WARNING! 1120.Pp 1121Issuing a secure erase will 1122.Em ERASE ALL 1123user data on the device and may take several hours to complete. 1124.Pp 1125When this command is used against an SSD drive all its cells will be marked as 1126empty, restoring it to factory default write performance. For SSD's this action 1127usually takes just a few seconds. 1128.It Fl f 1129.Pp 1130Freeze the security configuration of the specified device. 1131.Pp 1132After command completion any other commands that update the device lock mode 1133shall be command aborted. 1134Frozen mode is disabled by power-off or hardware reset. 1135.It Fl h Ar pwd 1136.Pp 1137Enhanced erase the device using the given password for the selected user. 1138.Pp 1139.Em WARNING! WARNING! WARNING! 1140.Pp 1141Issuing an enhanced secure erase will 1142.Em ERASE ALL 1143user data on the device and may take several hours to complete. 1144.Pp 1145An enhanced erase writes predetermined data patterns to all user data areas, 1146all previously written user data shall be overwritten, including sectors that 1147are no longer in use due to reallocation. 1148.It Fl k Ar pwd 1149.Pp 1150Unlock the device using the given password for the selected user according to 1151the devices configured security level. 1152.It Fl l Ar high|maximum 1153.Pp 1154Specifies which security level to set when issuing a 1155.Fl s Ar pwd 1156command. The security level determines device behavior when the master 1157password is used to unlock the device. When the security level is set to high 1158the device requires the unlock command and the master password to unlock. 1159When the security level is set to maximum the device requires a secure erase 1160with the master password to unlock. 1161.Pp 1162This option must be used in conjunction with one of the security action commands. 1163.Pp 1164Defaults to 1165.Em high 1166.It Fl q 1167.Pp 1168Be quiet, do not print any status messages. 1169This option will not disable the questions, however. 1170To disable questions, use the 1171.Fl y 1172argument, below. 1173.It Fl s Ar pwd 1174.Pp 1175Password the device (enable security) using the given password for the selected 1176user. This option can be combined with other options such as 1177.Fl e Em pwd 1178.Pp 1179A master password may be set in a addition to the user password. The purpose of 1180the master password is to allow an administrator to establish a password that 1181is kept secret from the user, and which may be used to unlock the device if the 1182user password is lost. 1183.Pp 1184.Em Note: 1185Setting the master password does not enable device security. 1186.Pp 1187If the master password is set and the drive supports a Master Revision Code 1188feature the Master Password Revision Code will be decremented. 1189.It Fl T Ar timeout 1190.Pp 1191Overrides the default timeout, specified in seconds, used for both 1192.Fl e 1193and 1194.Fl h 1195this is useful if your system has problems processing long timeouts correctly. 1196.Pp 1197Usually the timeout is calculated from the information stored on the drive if 1198present, otherwise it defaults to 2 hours. 1199.It Fl U Ar user|master 1200.Pp 1201Specifies which user to set / use for the running action command, valid values 1202are user or master and defaults to master if not set. 1203.Pp 1204This option must be used in conjunction with one of the security action commands. 1205.Pp 1206Defaults to 1207.Em master 1208.It Fl y 1209.Pp 1210Confirm yes to dangerous options such as 1211.Fl e 1212without prompting for confirmation. 1213.Pp 1214.El 1215If the password specified for any action commands doesn't match the configured 1216password for the specified user the command will fail. 1217.Pp 1218The password in all cases is limited to 32 characters, longer passwords will 1219fail. 1220.It Ic hpa 1221Update or report Host Protected Area details. 1222By default 1223.Nm 1224will print out the HPA support and associated settings of the device. 1225The 1226.Ic hpa 1227command takes several optional arguments: 1228.Bl -tag -width 0n 1229.It Fl f 1230.Pp 1231Freeze the HPA configuration of the specified device. 1232.Pp 1233After command completion any other commands that update the HPA configuration 1234shall be command aborted. 1235Frozen mode is disabled by power-off or hardware reset. 1236.It Fl l 1237.Pp 1238Lock the HPA configuration of the device until a successful call to unlock or 1239the next power-on reset occurs. 1240.It Fl P 1241.Pp 1242Make the HPA max sectors persist across power-on reset or a hardware reset. 1243This must be used in combination with 1244.Fl s Ar max_sectors 1245. 1246.It Fl p Ar pwd 1247.Pp 1248Set the HPA configuration password required for unlock calls. 1249.It Fl q 1250.Pp 1251Be quiet, do not print any status messages. 1252This option will not disable the questions. 1253To disable questions, use the 1254.Fl y 1255argument, below. 1256.It Fl s Ar max_sectors 1257.Pp 1258Configures the maximum user accessible sectors of the device. 1259This will change the number of sectors the device reports. 1260.Pp 1261.Em WARNING! WARNING! WARNING! 1262.Pp 1263Changing the max sectors of a device using this option will make the data on 1264the device beyond the specified value inaccessible. 1265.Pp 1266Only one successful 1267.Fl s Ar max_sectors 1268call can be made without a power-on reset or a hardware reset of the device. 1269.It Fl U Ar pwd 1270.Pp 1271Unlock the HPA configuration of the specified device using the given password. 1272If the password specified doesn't match the password configured via 1273.Fl p Ar pwd 1274the command will fail. 1275.Pp 1276After 5 failed unlock calls, due to password miss-match, the device will refuse 1277additional unlock calls until after a power-on reset. 1278.It Fl y 1279.Pp 1280Confirm yes to dangerous options such as 1281.Fl e 1282without prompting for confirmation 1283.Pp 1284.El 1285The password for all HPA commands is limited to 32 characters, longer passwords 1286will fail. 1287.It Ic fwdownload 1288Program firmware of the named SCSI device using the image file provided. 1289.Pp 1290Current list of supported vendors: 1291.Bl -bullet -offset indent -compact 1292.It 1293HITACHI 1294.It 1295HP 1296.It 1297IBM 1298.It 1299PLEXTOR 1300.It 1301QUANTUM 1302.It 1303SEAGATE 1304.El 1305.Pp 1306.Em WARNING! WARNING! WARNING! 1307.Pp 1308Little testing has been done to make sure that different device models from 1309each vendor work correctly with the fwdownload command. 1310A vendor name appearing in the supported list means only that firmware of at 1311least one device type from that vendor has successfully been programmed with 1312the fwdownload command. 1313Extra caution should be taken when using this command since there is no 1314guarantee it will not break a device from the listed vendors. 1315Ensure that you have a recent backup of the data on the device before 1316performing a firmware update. 1317.Bl -tag -width 11n 1318.It Fl f Ar fw_image 1319Path to the firmware image file to be downloaded to the specified device. 1320.It Fl y 1321Do not ask for confirmation. 1322.It Fl s 1323Run in simulation mode. 1324Packet sizes that will be sent are shown, but no actual packet is sent to the 1325device. 1326No confirmation is asked in simulation mode. 1327.It Fl v 1328Besides showing sense information in case of a failure, the verbose option 1329causes 1330.Nm 1331to output a line for every firmware segment that is sent to the device by the 1332fwdownload command 1333-- the same as the ones shown in simulation mode. 1334.El 1335.It Ic help 1336Print out verbose usage information. 1337.El 1338.Sh ENVIRONMENT 1339The 1340.Ev SCSI_MODES 1341variable allows the user to specify an alternate mode page format file. 1342.Pp 1343The 1344.Ev EDITOR 1345variable determines which text editor 1346.Nm 1347starts when editing mode pages. 1348.Sh FILES 1349.Bl -tag -width /usr/share/misc/scsi_modes -compact 1350.It Pa /usr/share/misc/scsi_modes 1351is the SCSI mode format database. 1352.It Pa /dev/xpt0 1353is the transport layer device. 1354.It Pa /dev/pass* 1355are the CAM application passthrough devices. 1356.El 1357.Sh EXAMPLES 1358.Dl camcontrol eject -n cd -u 1 -v 1359.Pp 1360Eject the CD from cd1, and print SCSI sense information if the command 1361fails. 1362.Pp 1363.Dl camcontrol tur da0 1364.Pp 1365Send the SCSI test unit ready command to da0. 1366The 1367.Nm 1368utility will report whether the disk is ready, but will not display sense 1369information if the command fails since the 1370.Fl v 1371switch was not specified. 1372.Bd -literal -offset indent 1373camcontrol tur da1 -E -C 4 -t 50 -v 1374.Ed 1375.Pp 1376Send a test unit ready command to da1. 1377Enable kernel error recovery. 1378Specify a retry count of 4, and a timeout of 50 seconds. 1379Enable sense 1380printing (with the 1381.Fl v 1382flag) if the command fails. 1383Since error recovery is turned on, the 1384disk will be spun up if it is not currently spinning. 1385The 1386.Nm 1387utility will report whether the disk is ready. 1388.Bd -literal -offset indent 1389camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e 1390 -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" 1391.Ed 1392.Pp 1393Issue a READ BUFFER command (0x3C) to cd1. 1394Display the buffer size of cd1, 1395and display the first 10 bytes from the cache on cd1. 1396Display SCSI sense 1397information if the command fails. 1398.Bd -literal -offset indent 1399camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e 1400 -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 1401.Ed 1402.Pp 1403Issue a WRITE BUFFER (0x3B) command to cd1. 1404Write out 10 bytes of data, 1405not including the (reserved) 4 byte header. 1406Print out sense information if 1407the command fails. 1408Be very careful with this command, improper use may 1409cause data corruption. 1410.Bd -literal -offset indent 1411camcontrol modepage da3 -m 1 -e -P 3 1412.Ed 1413.Pp 1414Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the 1415settings on the drive. 1416Mode page 1 contains a disk drive's auto read and 1417write reallocation settings, among other things. 1418.Pp 1419.Dl camcontrol rescan all 1420.Pp 1421Rescan all SCSI busses in the system for devices that have been added, 1422removed or changed. 1423.Pp 1424.Dl camcontrol rescan 0 1425.Pp 1426Rescan SCSI bus 0 for devices that have been added, removed or changed. 1427.Pp 1428.Dl camcontrol rescan 0:1:0 1429.Pp 1430Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or 1431changed. 1432.Pp 1433.Dl camcontrol tags da5 -N 24 1434.Pp 1435Set the number of concurrent transactions for da5 to 24. 1436.Bd -literal -offset indent 1437camcontrol negotiate -n da -u 4 -T disable 1438.Ed 1439.Pp 1440Disable tagged queueing for da4. 1441.Bd -literal -offset indent 1442camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a 1443.Ed 1444.Pp 1445Negotiate a sync rate of 20MHz and an offset of 15 with da3. 1446Then send a 1447Test Unit Ready command to make the settings take effect. 1448.Bd -literal -offset indent 1449camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" 1450.Ed 1451.Pp 1452Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs 1453it contains. 1454Display SMP errors if the command fails. 1455.Bd -literal -offset indent 1456camcontrol security ada0 1457.Ed 1458.Pp 1459Report security support and settings for ada0 1460.Bd -literal -offset indent 1461camcontrol security ada0 -u user -s MyPass 1462.Ed 1463.Pp 1464Enable security on device ada0 with the password MyPass 1465.Bd -literal -offset indent 1466camcontrol security ada0 -u user -e MyPass 1467.Ed 1468.Pp 1469Secure erase ada0 which has had security enabled with user password MyPass 1470.Pp 1471.Em WARNING! WARNING! WARNING! 1472.Pp 1473This will 1474.Em ERASE ALL 1475data from the device, so backup your data before using! 1476.Pp 1477This command can be used used against an SSD drive to restoring it to 1478factory default write performance. 1479.Bd -literal -offset indent 1480camcontrol hpa ada0 1481.Ed 1482.Pp 1483Report HPA support and settings for ada0 (also reported via 1484identify). 1485.Bd -literal -offset indent 1486camcontrol hpa ada0 -s 10240 1487.Ed 1488.Pp 1489Enables HPA on ada0 setting the maximum reported sectors to 10240. 1490.Pp 1491.Em WARNING! WARNING! WARNING! 1492.Pp 1493This will 1494.Em PREVENT ACCESS 1495to all data on the device beyond this limit until HPA is disabled by setting 1496HPA to native max sectors of the device, which can only be done after a 1497power-on or hardware reset! 1498.Pp 1499.Em DO NOT 1500use this on a device which has an active filesystem! 1501.Sh SEE ALSO 1502.Xr cam 3 , 1503.Xr cam_cdbparse 3 , 1504.Xr cam 4 , 1505.Xr pass 4 , 1506.Xr xpt 4 1507.Sh HISTORY 1508The 1509.Nm 1510utility first appeared in 1511.Fx 3.0 . 1512.Pp 1513The mode page editing code and arbitrary SCSI command code are based upon 1514code in the old 1515.Xr scsi 8 1516utility and 1517.Xr scsi 3 1518library, written by Julian Elischer and Peter Dufault. 1519The 1520.Xr scsi 8 1521program first appeared in 1522.Bx 386 0.1.2.4 , 1523and first appeared in 1524.Fx 1525in 1526.Fx 2.0.5 . 1527.Sh AUTHORS 1528.An Kenneth Merry Aq ken@FreeBSD.org 1529.Sh BUGS 1530The code that parses the generic command line arguments does not know that 1531some of the subcommands take multiple arguments. 1532So if, for instance, you 1533tried something like this: 1534.Bd -literal -offset indent 1535camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v 1536.Ed 1537.Pp 1538The sense information from the test unit ready command would not get 1539printed out, since the first 1540.Xr getopt 3 1541call in 1542.Nm 1543bails out when it sees the second argument to 1544.Fl c 1545(0x00), 1546above. 1547Fixing this behavior would take some gross code, or changes to the 1548.Xr getopt 3 1549interface. 1550The best way to circumvent this problem is to always make sure 1551to specify generic 1552.Nm 1553arguments before any command-specific arguments. 1554