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