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 June 4, 2012 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 help 232.Sh DESCRIPTION 233The 234.Nm 235utility is designed to provide a way for users to access and control the 236.Fx 237CAM subsystem. 238.Pp 239The 240.Nm 241utility 242can cause a loss of data and/or system crashes if used improperly. 243Even 244expert users are encouraged to exercise caution when using this command. 245Novice users should stay away from this utility. 246.Pp 247The 248.Nm 249utility has a number of primary functions, many of which support an optional 250device identifier. 251A device identifier can take one of three forms: 252.Bl -tag -width 14n 253.It deviceUNIT 254Specify a device name and unit number combination, like "da5" or "cd3". 255.It bus:target 256Specify a bus number and target id. 257The bus number can be determined from 258the output of 259.Dq camcontrol devlist . 260The lun defaults to 0. 261.It bus:target:lun 262Specify the bus, target and lun for a device. 263(e.g.\& 1:2:0) 264.El 265.Pp 266The device identifier, if it is specified, 267.Em must 268come immediately after the function name, and before any generic or 269function-specific arguments. 270Note that the 271.Fl n 272and 273.Fl u 274arguments described below will override any device name or unit number 275specified beforehand. 276The 277.Fl n 278and 279.Fl u 280arguments will 281.Em not 282override a specified bus:target or bus:target:lun, however. 283.Pp 284Most of the 285.Nm 286primary functions support these generic arguments: 287.Bl -tag -width 14n 288.It Fl C Ar count 289SCSI command retry count. 290In order for this to work, error recovery 291.Pq Fl E 292must be turned on. 293.It Fl E 294Instruct the kernel to perform generic SCSI error recovery for the given 295command. 296This is needed in order for the retry count 297.Pq Fl C 298to be honored. 299Other than retrying commands, the generic error recovery in 300the code will generally attempt to spin up drives that are not spinning. 301It may take some other actions, depending upon the sense code returned from 302the command. 303.It Fl n Ar dev_name 304Specify the device type to operate on, e.g.\& "da", "cd". 305.It Fl t Ar timeout 306SCSI command timeout in seconds. 307This overrides the default timeout for 308any given command. 309.It Fl u Ar unit_number 310Specify the device unit number, e.g.\& "1", "5". 311.It Fl v 312Be verbose, print out sense information for failed SCSI commands. 313.El 314.Pp 315Primary command functions: 316.Bl -tag -width periphlist 317.It Ic devlist 318List all physical devices (logical units) attached to the CAM subsystem. 319This also includes a list of peripheral drivers attached to each device. 320With the 321.Fl v 322argument, SCSI bus number, adapter name and unit numbers are printed as 323well. 324.It Ic periphlist 325List all peripheral drivers attached to a given physical device (logical 326unit). 327.It Ic tur 328Send the SCSI test unit ready (0x00) command to the given device. 329The 330.Nm 331utility will report whether the device is ready or not. 332.It Ic inquiry 333Send a SCSI inquiry command (0x12) to a device. 334By default, 335.Nm 336will print out the standard inquiry data, device serial number, and 337transfer rate information. 338The user can specify that only certain types of 339inquiry data be printed: 340.Bl -tag -width 4n 341.It Fl D 342Get the standard inquiry data. 343.It Fl S 344Print out the serial number. 345If this flag is the only one specified, 346.Nm 347will not print out "Serial Number" before the value returned by the drive. 348This is to aid in script writing. 349.It Fl R 350Print out transfer rate information. 351.El 352.It Ic identify 353Send a ATA identify command (0xec) to a device. 354.It Ic reportluns 355Send the SCSI REPORT LUNS (0xA0) command to the given device. 356By default, 357.Nm 358will print out the list of logical units (LUNs) supported by the target device. 359There are a couple of options to modify the output: 360.Bl -tag -width 14n 361.It Fl c 362Just print out a count of LUNs, not the actual LUN numbers. 363.It Fl l 364Just print out the LUNs, and don't print out the count. 365.It Fl r Ar reporttype 366Specify the type of report to request from the target: 367.Bl -tag -width 012345678 368.It default 369Return the default report. 370This is the 371.Nm 372default. 373Most targets will support this report if they support the REPORT LUNS 374command. 375.It wellknown 376Return only well known LUNs. 377.It all 378Return all available LUNs. 379.El 380.El 381.Pp 382.Nm 383will try to print out LUN numbers in a reasonable format. 384It can understand the peripheral, flat, LUN and extended LUN formats. 385.It Ic readcap 386Send the SCSI READ CAPACITY command to the given device and display 387the results. 388If the device is larger than 2TB, the SCSI READ CAPACITY (16) service 389action will be sent to obtain the full size of the device. 390By default, 391.Nm 392will print out the last logical block of the device, and the blocksize of 393the device in bytes. 394To modify the output format, use the following options: 395.Bl -tag -width 5n 396.It Fl b 397Just print out the blocksize, not the last block or device size. 398This cannot be used with 399.Fl N 400or 401.Fl s . 402.It Fl h 403Print out the device size in human readable (base 2, 1K == 1024) format. 404This implies 405.Fl N 406and cannot be used with 407.Fl q 408or 409.Fl b . 410.It Fl H 411Print out the device size in human readable (base 10, 1K == 1000) format. 412.It Fl N 413Print out the number of blocks in the device instead of the last logical 414block. 415.It Fl q 416Quiet, print out the numbers only (separated by a comma if 417.Fl b 418or 419.Fl s 420are not specified). 421.It Fl s 422Print out the last logical block or the size of the device only, and omit 423the blocksize. 424.El 425.It Ic start 426Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 427start bit set. 428.It Ic stop 429Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 430start bit cleared. 431.It Ic load 432Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 433start bit set and the load/eject bit set. 434.It Ic eject 435Send the SCSI Start/Stop Unit (0x1B) command to the given device with the 436start bit cleared and the load/eject bit set. 437.It Ic rescan 438Tell the kernel to scan all busses in the system (with the 439.Ar all 440argument), the given bus (XPT_SCAN_BUS), or bus:target:lun 441(XPT_SCAN_LUN) for new devices or devices that have gone away. 442The user 443may specify a scan of all busses, a single bus, or a lun. 444Scanning all luns 445on a target is not supported. 446.It Ic reset 447Tell the kernel to reset all busses in the system (with the 448.Ar all 449argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus 450reset for that bus, or to reset the given bus:target:lun 451(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after 452connecting to that device. 453Note that this can have a destructive impact 454on the system. 455.It Ic defects 456Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and 457print out any combination of: the total number of defects, the primary 458defect list (PLIST), and the grown defect list (GLIST). 459.Bl -tag -width 11n 460.It Fl f Ar format 461The three format options are: 462.Em block , 463to print out the list as logical blocks, 464.Em bfi , 465to print out the list in bytes from index format, and 466.Em phys , 467to print out the list in physical sector format. 468The format argument is 469required. 470Most drives support the physical sector format. 471Some drives 472support the logical block format. 473Many drives, if they do not support the 474requested format, return the data in an alternate format, along with sense 475information indicating that the requested data format is not supported. 476The 477.Nm 478utility 479attempts to detect this, and print out whatever format the drive returns. 480If the drive uses a non-standard sense code to report that it does not 481support the requested format, 482.Nm 483will probably see the error as a failure to complete the request. 484.It Fl G 485Print out the grown defect list. 486This is a list of bad blocks that have 487been remapped since the disk left the factory. 488.It Fl P 489Print out the primary defect list. 490.El 491.Pp 492If neither 493.Fl P 494nor 495.Fl G 496is specified, 497.Nm 498will print out the number of defects given in the READ DEFECT DATA header 499returned from the drive. 500Some drives will report 0 defects if neither the primary or grown defect 501lists are requested. 502.It Ic modepage 503Allows the user to display and optionally edit a SCSI mode page. 504The mode 505page formats are located in 506.Pa /usr/share/misc/scsi_modes . 507This can be overridden by specifying a different file in the 508.Ev SCSI_MODES 509environment variable. 510The 511.Ic modepage 512command takes several arguments: 513.Bl -tag -width 12n 514.It Fl d 515Disable block descriptors for mode sense. 516.It Fl b 517Displays mode page data in binary format. 518.It Fl e 519This flag allows the user to edit values in the mode page. 520The user may 521either edit mode page values with the text editor pointed to by his 522.Ev EDITOR 523environment variable, or supply mode page values via standard input, using 524the same format that 525.Nm 526uses to display mode page values. 527The editor will be invoked if 528.Nm 529detects that standard input is terminal. 530.It Fl l 531Lists all available mode pages. 532.It Fl m Ar mode_page 533This specifies the number of the mode page the user would like to view 534and/or edit. 535This argument is mandatory unless 536.Fl l 537is specified. 538.It Fl P Ar pgctl 539This allows the user to specify the page control field. 540Possible values are: 541.Bl -tag -width xxx -compact 542.It 0 543Current values 544.It 1 545Changeable values 546.It 2 547Default values 548.It 3 549Saved values 550.El 551.El 552.It Ic cmd 553Allows the user to send an arbitrary ATA or SCSI CDB to any device. 554The 555.Ic cmd 556function requires the 557.Fl c 558argument to specify SCSI CDB or the 559.Fl a 560argument to specify ATA Command Block registers values. 561Other arguments are optional, depending on 562the command type. 563The command and data specification syntax is documented 564in 565.Xr cam_cdbparse 3 . 566NOTE: If the CDB specified causes data to be transferred to or from the 567SCSI device in question, you MUST specify either 568.Fl i 569or 570.Fl o . 571.Bl -tag -width 17n 572.It Fl a Ar cmd Op args 573This specifies the content of 12 ATA Command Block registers (command, 574features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp. 575lba_high_exp, features_exp, sector_count, sector_count_exp). 576.It Fl c Ar cmd Op args 577This specifies the SCSI CDB. 578SCSI CDBs may be 6, 10, 12 or 16 bytes. 579.It Fl d 580Specifies DMA protocol to be used for ATA command. 581.It Fl f 582Specifies FPDMA (NCQ) protocol to be used for ATA command. 583.It Fl i Ar len Ar fmt 584This specifies the amount of data to read, and how it should be displayed. 585If the format is 586.Sq - , 587.Ar len 588bytes of data will be read from the device and written to standard output. 589.It Fl o Ar len Ar fmt Op args 590This specifies the amount of data to be written to a device, and the data 591that is to be written. 592If the format is 593.Sq - , 594.Ar len 595bytes of data will be read from standard input and written to the device. 596.It Fl r Ar fmt 597This specifies that 11 result ATA Command Block registers should be displayed 598(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp, 599lba_high_exp, sector_count, sector_count_exp), and how. 600If the format is 601.Sq - , 60211 result registers will be written to standard output in hex. 603.El 604.It Ic smpcmd 605Allows the user to send an arbitrary Serial 606Management Protocol (SMP) command to a device. 607The 608.Ic smpcmd 609function requires the 610.Fl r 611argument to specify the SMP request to be sent, and the 612.Fl R 613argument to specify the format of the SMP response. 614The syntax for the SMP request and response arguments is documented in 615.Xr cam_cdbparse 3 . 616.Pp 617Note that SAS adapters that support SMP passthrough (at least the currently 618known adapters) do not accept CRC bytes from the user in the request and do 619not pass CRC bytes back to the user in the response. 620Therefore users should not include the CRC bytes in the length of the 621request and not expect CRC bytes to be returned in the response. 622.Bl -tag -width 17n 623.It Fl r Ar len Ar fmt Op args 624This specifies the size of the SMP request, without the CRC bytes, and the 625SMP request format. If the format is 626.Sq - , 627.Ar len 628bytes of data will be read from standard input and written as the SMP 629request. 630.It Fl R Ar len Ar fmt Op args 631This specifies the size of the buffer allocated for the SMP response, and 632the SMP response format. 633If the format is 634.Sq - , 635.Ar len 636bytes of data will be allocated for the response and the response will be 637written to standard output. 638.El 639.It Ic smprg 640Allows the user to send the Serial Management Protocol (SMP) Report General 641command to a device. 642.Nm 643will display the data returned by the Report General command. 644If the SMP target supports the long response format, the additional data 645will be requested and displayed automatically. 646.Bl -tag -width 8n 647.It Fl l 648Request the long response format only. 649Not all SMP targets support the long response format. 650This option causes 651.Nm 652to skip sending the initial report general request without the long bit set 653and only issue a report general request with the long bit set. 654.El 655.It Ic smppc 656Allows the user to issue the Serial Management Protocol (SMP) PHY Control 657command to a device. 658This function should be used with some caution, as it can render devices 659inaccessible, and could potentially cause data corruption as well. 660The 661.Fl p 662argument is required to specify the PHY to operate on. 663.Bl -tag -width 17n 664.It Fl p Ar phy 665Specify the PHY to operate on. 666This argument is required. 667.It Fl l 668Request the long request/response format. 669Not all SMP targets support the long response format. 670For the PHY Control command, this currently only affects whether the 671request length is set to a value other than 0. 672.It Fl o Ar operation 673Specify a PHY control operation. 674Only one 675.Fl o 676operation may be specified. 677The operation may be specified numerically (in decimal, hexadecimal, or octal) 678or one of the following operation names may be specified: 679.Bl -tag -width 16n 680.It nop 681No operation. 682It is not necessary to specify this argument. 683.It linkreset 684Send the LINK RESET command to the phy. 685.It hardreset 686Send the HARD RESET command to the phy. 687.It disable 688Send the DISABLE command to the phy. 689Note that the LINK RESET or HARD RESET commands should re-enable the phy. 690.It clearerrlog 691Send the CLEAR ERROR LOG command. 692This clears the error log counters for the specified phy. 693.It clearaffiliation 694Send the CLEAR AFFILIATION command. 695This clears the affiliation from the STP initiator port with the same SAS 696address as the SMP initiator that requests the clear operation. 697.It sataportsel 698Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy. 699This will cause a SATA port selector to use the given phy as its active phy 700and make the other phy inactive. 701.It clearitnl 702Send the CLEAR STP I_T NEXUS LOSS command to the PHY. 703.It setdevname 704Send the SET ATTACHED DEVICE NAME command to the PHY. 705This requires the 706.Fl d 707argument to specify the device name. 708.El 709.It Fl d Ar name 710Specify the attached device name. 711This option is needed with the 712.Fl o Ar setdevname 713phy operation. 714The name is a 64-bit number, and can be specified in decimal, hexadecimal 715or octal format. 716.It Fl m Ar rate 717Set the minimum physical link rate for the phy. 718This is a numeric argument. 719Currently known link rates are: 720.Bl -tag -width 5n 721.It 0x0 722Do not change current value. 723.It 0x8 7241.5 Gbps 725.It 0x9 7263 Gbps 727.It 0xa 7286 Gbps 729.El 730.Pp 731Other values may be specified for newer physical link rates. 732.It Fl M Ar rate 733Set the maximum physical link rate for the phy. 734This is a numeric argument. 735See the 736.Fl m 737argument description for known link rate arguments. 738.It Fl T Ar pp_timeout 739Set the partial pathway timeout value, in microseconds. 740See the 741.Tn ANSI 742.Tn SAS 743Protocol Layer (SPL) 744specification for more information on this field. 745.It Fl a Ar enable|disable 746Enable or disable SATA slumber phy power conditions. 747.It Fl A Ar enable|disable 748Enable or disable SATA partial power conditions. 749.It Fl s Ar enable|disable 750Enable or disable SAS slumber phy power conditions. 751.It Fl S Ar enable|disable 752Enable or disable SAS partial phy power conditions. 753.El 754.It Ic smpphylist 755List phys attached to a SAS expander, the address of the end device 756attached to the phy, and the inquiry data for that device and peripheral 757devices attached to that device. 758The inquiry data and peripheral devices are displayed if available. 759.Bl -tag -width 5n 760.It Fl l 761Turn on the long response format for the underlying SMP commands used for 762this command. 763.It Fl q 764Only print out phys that are attached to a device in the CAM EDT (Existing 765Device Table). 766.El 767.It Ic smpmaninfo 768Send the SMP Report Manufacturer Information command to the device and 769display the response. 770.Bl -tag -width 5n 771.It Fl l 772Turn on the long response format for the underlying SMP commands used for 773this command. 774.El 775.It Ic debug 776Turn on CAM debugging printfs in the kernel. 777This requires options CAMDEBUG 778in your kernel config file. 779WARNING: enabling debugging printfs currently 780causes an EXTREME number of kernel printfs. 781You may have difficulty 782turning off the debugging printfs once they start, since the kernel will be 783busy printing messages and unable to service other requests quickly. 784The 785.Ic debug 786function takes a number of arguments: 787.Bl -tag -width 18n 788.It Fl I 789Enable CAM_DEBUG_INFO printfs. 790.It Fl P 791Enable CAM_DEBUG_PERIPH printfs. 792.It Fl T 793Enable CAM_DEBUG_TRACE printfs. 794.It Fl S 795Enable CAM_DEBUG_SUBTRACE printfs. 796.It Fl X 797Enable CAM_DEBUG_XPT printfs. 798.It Fl c 799Enable CAM_DEBUG_CDB printfs. 800This will cause the kernel to print out the 801SCSI CDBs sent to the specified device(s). 802.It Fl p 803Enable CAM_DEBUG_PROBE printfs. 804.It all 805Enable debugging for all devices. 806.It off 807Turn off debugging for all devices 808.It bus Ns Op :target Ns Op :lun 809Turn on debugging for the given bus, target or lun. 810If the lun or target 811and lun are not specified, they are wildcarded. 812(i.e., just specifying a 813bus turns on debugging printfs for all devices on that bus.) 814.El 815.It Ic tags 816Show or set the number of "tagged openings" or simultaneous transactions 817we attempt to queue to a particular device. 818By default, the 819.Ic tags 820command, with no command-specific arguments (i.e., only generic arguments) 821prints out the "soft" maximum number of transactions that can be queued to 822the device in question. 823For more detailed information, use the 824.Fl v 825argument described below. 826.Bl -tag -width 7n 827.It Fl N Ar tags 828Set the number of tags for the given device. 829This must be between the 830minimum and maximum number set in the kernel quirk table. 831The default for 832most devices that support tagged queueing is a minimum of 2 and a maximum 833of 255. 834The minimum and maximum values for a given device may be 835determined by using the 836.Fl v 837switch. 838The meaning of the 839.Fl v 840switch for this 841.Nm 842subcommand is described below. 843.It Fl q 844Be quiet, and do not report the number of tags. 845This is generally used when 846setting the number of tags. 847.It Fl v 848The verbose flag has special functionality for the 849.Em tags 850argument. 851It causes 852.Nm 853to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: 854.Bl -tag -width 13n 855.It dev_openings 856This is the amount of capacity for transactions queued to a given device. 857.It dev_active 858This is the number of transactions currently queued to a device. 859.It devq_openings 860This is the kernel queue space for transactions. 861This count usually mirrors 862dev_openings except during error recovery operations when 863the device queue is frozen (device is not allowed to receive 864commands), the number of dev_openings is reduced, or transaction 865replay is occurring. 866.It devq_queued 867This is the number of transactions waiting in the kernel queue for capacity 868on the device. 869This number is usually zero unless error recovery is in 870progress. 871.It held 872The held count is the number of CCBs held by peripheral drivers that have 873either just been completed or are about to be released to the transport 874layer for service by a device. 875Held CCBs reserve capacity on a given 876device. 877.It mintags 878This is the current "hard" minimum number of transactions that can be 879queued to a device at once. 880The 881.Ar dev_openings 882value above cannot go below this number. 883The default value for 884.Ar mintags 885is 2, although it may be set higher or lower for various devices. 886.It maxtags 887This is the "hard" maximum number of transactions that can be queued to a 888device at one time. 889The 890.Ar dev_openings 891value cannot go above this number. 892The default value for 893.Ar maxtags 894is 255, although it may be set higher or lower for various devices. 895.El 896.El 897.It Ic negotiate 898Show or negotiate various communication parameters. 899Some controllers may 900not support setting or changing some of these values. 901For instance, the 902Adaptec 174x controllers do not support changing a device's sync rate or 903offset. 904The 905.Nm 906utility 907will not attempt to set the parameter if the controller indicates that it 908does not support setting the parameter. 909To find out what the controller 910supports, use the 911.Fl v 912flag. 913The meaning of the 914.Fl v 915flag for the 916.Ic negotiate 917command is described below. 918Also, some controller drivers do not support 919setting negotiation parameters, even if the underlying controller supports 920negotiation changes. 921Some controllers, such as the Advansys wide 922controllers, support enabling and disabling synchronous negotiation for 923a device, but do not support setting the synchronous negotiation rate. 924.Bl -tag -width 17n 925.It Fl a 926Attempt to make the negotiation settings take effect immediately by sending 927a Test Unit Ready command to the device. 928.It Fl c 929Show or set current negotiation settings. 930This is the default. 931.It Fl D Ar enable|disable 932Enable or disable disconnection. 933.It Fl M Ar mode 934Set ATA mode. 935.It Fl O Ar offset 936Set the command delay offset. 937.It Fl q 938Be quiet, do not print anything. 939This is generally useful when you want to 940set a parameter, but do not want any status information. 941.It Fl R Ar syncrate 942Change the synchronization rate for a device. 943The sync rate is a floating 944point value specified in MHz. 945So, for instance, 946.Sq 20.000 947is a legal value, as is 948.Sq 20 . 949.It Fl T Ar enable|disable 950Enable or disable tagged queueing for a device. 951.It Fl U 952Show or set user negotiation settings. 953The default is to show or set 954current negotiation settings. 955.It Fl v 956The verbose switch has special meaning for the 957.Ic negotiate 958subcommand. 959It causes 960.Nm 961to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the 962controller driver. 963.It Fl W Ar bus_width 964Specify the bus width to negotiate with a device. 965The bus width is 966specified in bits. 967The only useful values to specify are 8, 16, and 32 968bits. 969The controller must support the bus width in question in order for 970the setting to take effect. 971.El 972.Pp 973In general, sync rate and offset settings will not take effect for a 974device until a command has been sent to the device. 975The 976.Fl a 977switch above will automatically send a Test Unit Ready to the device so 978negotiation parameters will take effect. 979.It Ic format 980Issue the 981.Tn SCSI 982FORMAT UNIT command to the named device. 983.Pp 984.Em WARNING! WARNING! WARNING! 985.Pp 986Low level formatting a disk will destroy ALL data on the disk. 987Use 988extreme caution when issuing this command. 989Many users low-level format 990disks that do not really need to be low-level formatted. 991There are 992relatively few scenarios that call for low-level formatting a disk. 993One reason for 994low-level formatting a disk is to initialize the disk after changing 995its physical sector size. 996Another reason for low-level formatting a disk 997is to revive the disk if you are getting "medium format corrupted" errors 998from the disk in response to read and write requests. 999.Pp 1000Some disks take longer than others to format. 1001Users should specify a 1002timeout long enough to allow the format to complete. 1003The default format 1004timeout is 3 hours, which should be long enough for most disks. 1005Some hard 1006disks will complete a format operation in a very short period of time 1007(on the order of 5 minutes or less). 1008This is often because the drive 1009does not really support the FORMAT UNIT command -- it just accepts the 1010command, waits a few minutes and then returns it. 1011.Pp 1012The 1013.Sq format 1014subcommand takes several arguments that modify its default behavior. 1015The 1016.Fl q 1017and 1018.Fl y 1019arguments can be useful for scripts. 1020.Bl -tag -width 6n 1021.It Fl q 1022Be quiet, do not print any status messages. 1023This option will not disable 1024the questions, however. 1025To disable questions, use the 1026.Fl y 1027argument, below. 1028.It Fl r 1029Run in 1030.Dq report only 1031mode. 1032This will report status on a format that is already running on the drive. 1033.It Fl w 1034Issue a non-immediate format command. 1035By default, 1036.Nm 1037issues the FORMAT UNIT command with the immediate bit set. 1038This tells the 1039device to immediately return the format command, before the format has 1040actually completed. 1041Then, 1042.Nm 1043gathers 1044.Tn SCSI 1045sense information from the device every second to determine how far along 1046in the format process it is. 1047If the 1048.Fl w 1049argument is specified, 1050.Nm 1051will issue a non-immediate format command, and will be unable to print any 1052information to let the user know what percentage of the disk has been 1053formatted. 1054.It Fl y 1055Do not ask any questions. 1056By default, 1057.Nm 1058will ask the user if he/she really wants to format the disk in question, 1059and also if the default format command timeout is acceptable. 1060The user 1061will not be asked about the timeout if a timeout is specified on the 1062command line. 1063.El 1064.It Ic idle 1065Put ATA device into IDLE state. Optional parameter 1066.Pq Fl t 1067specifies automatic standby timer value in seconds. Value 0 disables timer. 1068.It Ic standby 1069Put ATA device into STANDBY state. Optional parameter 1070.Pq Fl t 1071specifies automatic standby timer value in seconds. Value 0 disables timer. 1072.It Ic sleep 1073Put ATA device into SLEEP state. Note that the only way get device out of 1074this state may be reset. 1075.It Ic fwdownload 1076Program firmware of the named SCSI device using the image file provided. 1077.Pp 1078Current list of supported vendors: 1079.Bl -bullet -offset indent -compact 1080.It 1081HITACHI 1082.It 1083HP 1084.It 1085IBM 1086.It 1087PLEXTOR 1088.It 1089QUANTUM 1090.It 1091SEAGATE 1092.El 1093.Pp 1094.Em WARNING! WARNING! WARNING! 1095.Pp 1096Little testing has been done to make sure that different device models from 1097each vendor work correctly with the fwdownload command. 1098A vendor name appearing in the supported list means only that firmware of at 1099least one device type from that vendor has successfully been programmed with 1100the fwdownload command. 1101Extra caution should be taken when using this command since there is no 1102guarantee it will not break a device from the listed vendors. 1103Ensure that you have a recent backup of the data on the device before 1104performing a firmware update. 1105.Bl -tag -width 11n 1106.It Fl f Ar fw_image 1107Path to the firmware image file to be downloaded to the specified device. 1108.It Fl y 1109Do not ask for confirmation. 1110.It Fl s 1111Run in simulation mode. 1112Packet sizes that will be sent are shown, but no actual packet is sent to the 1113device. 1114No confirmation is asked in simulation mode. 1115.It Fl v 1116Besides showing sense information in case of a failure, the verbose option 1117causes 1118.Nm 1119to output a line for every firmware segment that is sent to the device by the 1120fwdownload command 1121-- the same as the ones shown in simulation mode. 1122.El 1123.It Ic help 1124Print out verbose usage information. 1125.El 1126.Sh ENVIRONMENT 1127The 1128.Ev SCSI_MODES 1129variable allows the user to specify an alternate mode page format file. 1130.Pp 1131The 1132.Ev EDITOR 1133variable determines which text editor 1134.Nm 1135starts when editing mode pages. 1136.Sh FILES 1137.Bl -tag -width /usr/share/misc/scsi_modes -compact 1138.It Pa /usr/share/misc/scsi_modes 1139is the SCSI mode format database. 1140.It Pa /dev/xpt0 1141is the transport layer device. 1142.It Pa /dev/pass* 1143are the CAM application passthrough devices. 1144.El 1145.Sh EXAMPLES 1146.Dl camcontrol eject -n cd -u 1 -v 1147.Pp 1148Eject the CD from cd1, and print SCSI sense information if the command 1149fails. 1150.Pp 1151.Dl camcontrol tur da0 1152.Pp 1153Send the SCSI test unit ready command to da0. 1154The 1155.Nm 1156utility will report whether the disk is ready, but will not display sense 1157information if the command fails since the 1158.Fl v 1159switch was not specified. 1160.Bd -literal -offset indent 1161camcontrol tur da1 -E -C 4 -t 50 -v 1162.Ed 1163.Pp 1164Send a test unit ready command to da1. 1165Enable kernel error recovery. 1166Specify a retry count of 4, and a timeout of 50 seconds. 1167Enable sense 1168printing (with the 1169.Fl v 1170flag) if the command fails. 1171Since error recovery is turned on, the 1172disk will be spun up if it is not currently spinning. 1173The 1174.Nm 1175utility will report whether the disk is ready. 1176.Bd -literal -offset indent 1177camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e 1178 -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" 1179.Ed 1180.Pp 1181Issue a READ BUFFER command (0x3C) to cd1. 1182Display the buffer size of cd1, 1183and display the first 10 bytes from the cache on cd1. 1184Display SCSI sense 1185information if the command fails. 1186.Bd -literal -offset indent 1187camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e 1188 -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 1189.Ed 1190.Pp 1191Issue a WRITE BUFFER (0x3B) command to cd1. 1192Write out 10 bytes of data, 1193not including the (reserved) 4 byte header. 1194Print out sense information if 1195the command fails. 1196Be very careful with this command, improper use may 1197cause data corruption. 1198.Bd -literal -offset indent 1199camcontrol modepage da3 -m 1 -e -P 3 1200.Ed 1201.Pp 1202Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the 1203settings on the drive. 1204Mode page 1 contains a disk drive's auto read and 1205write reallocation settings, among other things. 1206.Pp 1207.Dl camcontrol rescan all 1208.Pp 1209Rescan all SCSI busses in the system for devices that have been added, 1210removed or changed. 1211.Pp 1212.Dl camcontrol rescan 0 1213.Pp 1214Rescan SCSI bus 0 for devices that have been added, removed or changed. 1215.Pp 1216.Dl camcontrol rescan 0:1:0 1217.Pp 1218Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or 1219changed. 1220.Pp 1221.Dl camcontrol tags da5 -N 24 1222.Pp 1223Set the number of concurrent transactions for da5 to 24. 1224.Bd -literal -offset indent 1225camcontrol negotiate -n da -u 4 -T disable 1226.Ed 1227.Pp 1228Disable tagged queueing for da4. 1229.Bd -literal -offset indent 1230camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a 1231.Ed 1232.Pp 1233Negotiate a sync rate of 20MHz and an offset of 15 with da3. 1234Then send a 1235Test Unit Ready command to make the settings take effect. 1236.Bd -literal -offset indent 1237camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" 1238.Ed 1239.Pp 1240Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs 1241it contains. 1242Display SMP errors if the command fails. 1243.Sh SEE ALSO 1244.Xr cam 3 , 1245.Xr cam_cdbparse 3 , 1246.Xr cam 4 , 1247.Xr pass 4 , 1248.Xr xpt 4 1249.Sh HISTORY 1250The 1251.Nm 1252utility first appeared in 1253.Fx 3.0 . 1254.Pp 1255The mode page editing code and arbitrary SCSI command code are based upon 1256code in the old 1257.Xr scsi 8 1258utility and 1259.Xr scsi 3 1260library, written by Julian Elischer and Peter Dufault. 1261The 1262.Xr scsi 8 1263program first appeared in 1264.Bx 386 0.1.2.4 , 1265and first appeared in 1266.Fx 1267in 1268.Fx 2.0.5 . 1269.Sh AUTHORS 1270.An Kenneth Merry Aq ken@FreeBSD.org 1271.Sh BUGS 1272The code that parses the generic command line arguments does not know that 1273some of the subcommands take multiple arguments. 1274So if, for instance, you 1275tried something like this: 1276.Bd -literal -offset indent 1277camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v 1278.Ed 1279.Pp 1280The sense information from the test unit ready command would not get 1281printed out, since the first 1282.Xr getopt 3 1283call in 1284.Nm 1285bails out when it sees the second argument to 1286.Fl c 1287(0x00), 1288above. 1289Fixing this behavior would take some gross code, or changes to the 1290.Xr getopt 3 1291interface. 1292The best way to circumvent this problem is to always make sure 1293to specify generic 1294.Nm 1295arguments before any command-specific arguments. 1296