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