2 .\" Copyright (c) 1998, 1999, 2000, 2002, 2005, 2006, 2007 Kenneth D. Merry.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nd CAM control program
49 .Op Fl u Ar unit_number
72 .Op Fl r Ar reporttype
101 .Aq all | bus Ns Op :target:lun
104 .Aq all | bus Ns Op :target:lun
116 .Aq Fl m Ar page | Fl l
124 .Aq Fl a Ar cmd Op args
125 .Aq Fl c Ar cmd Op args
126 .Op Fl i Ar len Ar fmt
128 .Op Fl o Ar len Ar fmt Op args
139 .Aq all|off|bus Ns Op :target Ns Op :lun
152 .Op Fl D Ar enable|disable
157 .Op Fl T Ar enable|disable
159 .Op Fl W Ar bus_width
188 utility is designed to provide a way for users to access and control the
195 can cause a loss of data and/or system crashes if used improperly.
197 expert users are encouraged to exercise caution when using this command.
198 Novice users should stay away from this utility.
202 utility has a number of primary functions, many of which support an optional
204 A device identifier can take one of three forms:
207 Specify a device name and unit number combination, like "da5" or "cd3".
208 Note that character device node names (e.g.\& /dev/da0) are
212 Specify a bus number and target id.
213 The bus number can be determined from
215 .Dq camcontrol devlist .
216 The lun defaults to 0.
218 Specify the bus, target and lun for a device.
222 The device identifier, if it is specified,
224 come immediately after the function name, and before any generic or
225 function-specific arguments.
230 arguments described below will override any device name or unit number
231 specified beforehand.
238 override a specified bus:target or bus:target:lun, however.
242 primary functions support these generic arguments:
245 SCSI command retry count.
246 In order for this to work, error recovery
250 Instruct the kernel to perform generic SCSI error recovery for the given
252 This is needed in order for the retry count
255 Other than retrying commands, the generic error recovery in
256 the code will generally attempt to spin up drives that are not spinning.
257 It may take some other actions, depending upon the sense code returned from
260 Specify the device type to operate on, e.g.\& "da", "cd".
262 SCSI command timeout in seconds.
263 This overrides the default timeout for
265 .It Fl u Ar unit_number
266 Specify the device unit number, e.g.\& "1", "5".
268 Be verbose, print out sense information for failed SCSI commands.
271 Primary command functions:
272 .Bl -tag -width periphlist
274 List all physical devices (logical units) attached to the CAM subsystem.
275 This also includes a list of peripheral drivers attached to each device.
278 argument, SCSI bus number, adapter name and unit numbers are printed as
281 List all peripheral drivers attached to a given physical device (logical
284 Send the SCSI test unit ready (0x00) command to the given device.
287 utility will report whether the device is ready or not.
289 Send a SCSI inquiry command (0x12) to a device.
292 will print out the standard inquiry data, device serial number, and
293 transfer rate information.
294 The user can specify that only certain types of
295 inquiry data be printed:
298 Get the standard inquiry data.
300 Print out the serial number.
301 If this flag is the only one specified,
303 will not print out "Serial Number" before the value returned by the drive.
304 This is to aid in script writing.
306 Print out transfer rate information.
309 Send a ATA identify command (0xec) to a device.
311 Send the SCSI REPORT LUNS (0xA0) command to the given device.
314 will print out the list of logical units (LUNs) supported by the target device.
315 There are a couple of options to modify the output:
318 Just print out a count of LUNs, not the actual LUN numbers.
320 Just print out the LUNs, and don't print out the count.
321 .It Fl r Ar reporttype
322 Specify the type of report to request from the target:
323 .Bl -tag -width 012345678
325 Return the default report.
329 Most targets will support this report if they support the REPORT LUNS
332 Return only well known LUNs.
334 Return all available LUNs.
339 will try to print out LUN numbers in a reasonable format.
340 It can understand the peripheral, flat, LUN and extended LUN formats.
342 Send the SCSI READ CAPACITY command to the given device and display
344 If the device is larger than 2TB, the SCSI READ CAPACITY (16) service
345 action will be sent to obtain the full size of the device.
348 will print out the last logical block of the device, and the blocksize of
350 To modify the output format, use the following options:
353 Just print out the blocksize, not the last block or device size.
354 This cannot be used with
359 Print out the device size in human readable (base 2, 1K == 1024) format.
362 and cannot be used with
367 Print out the device size in human readable (base 10, 1K == 1000) format.
369 Print out the number of blocks in the device instead of the last logical
372 Quiet, print out the numbers only (separated by a comma if
378 Print out the last logical block or the size of the device only, and omit
382 Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
385 Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
388 Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
389 start bit set and the load/eject bit set.
391 Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
392 start bit cleared and the load/eject bit set.
394 Tell the kernel to scan all busses in the system (with the
396 argument), the given bus (XPT_SCAN_BUS), or bus:target:lun
397 (XPT_SCAN_LUN) for new devices or devices that have gone away.
399 may specify a scan of all busses, a single bus, or a lun.
401 on a target is not supported.
403 Tell the kernel to reset all busses in the system (with the
405 argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus
406 reset for that bus, or to reset the given bus:target:lun
407 (XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after
408 connecting to that device.
409 Note that this can have a destructive impact
412 Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and
413 print out any combination of: the total number of defects, the primary
414 defect list (PLIST), and the grown defect list (GLIST).
417 The three format options are:
419 to print out the list as logical blocks,
421 to print out the list in bytes from index format, and
423 to print out the list in physical sector format.
424 The format argument is
426 Most drives support the physical sector format.
428 support the logical block format.
429 Many drives, if they do not support the
430 requested format, return the data in an alternate format, along with sense
431 information indicating that the requested data format is not supported.
435 attempts to detect this, and print out whatever format the drive returns.
436 If the drive uses a non-standard sense code to report that it does not
437 support the requested format,
439 will probably see the error as a failure to complete the request.
441 Print out the grown defect list.
442 This is a list of bad blocks that have
443 been remapped since the disk left the factory.
445 Print out the primary defect list.
454 will print out the number of defects given in the READ DEFECT DATA header
455 returned from the drive.
457 Allows the user to display and optionally edit a SCSI mode page.
459 page formats are located in
460 .Pa /usr/share/misc/scsi_modes .
461 This can be overridden by specifying a different file in the
463 environment variable.
466 command takes several arguments:
469 Disable block descriptors for mode sense.
471 Displays mode page data in binary format.
473 This flag allows the user to edit values in the mode page.
475 either edit mode page values with the text editor pointed to by his
477 environment variable, or supply mode page values via standard input, using
480 uses to display mode page values.
481 The editor will be invoked if
483 detects that standard input is terminal.
485 Lists all available mode pages.
486 .It Fl m Ar mode_page
487 This specifies the number of the mode page the user would like to view
489 This argument is mandatory unless
493 This allows the user to specify the page control field.
495 .Bl -tag -width xxx -compact
507 Allows the user to send an arbitrary ATA or SCSI CDB to any device.
510 function requires the
512 argument to specify SCSI CDB or the
514 argument to specify ATA Command Block registers values.
515 Other arguments are optional, depending on
517 The command and data specification syntax is documented
520 NOTE: If the CDB specified causes data to be transfered to or from the
521 SCSI device in question, you MUST specify either
526 .It Fl a Ar cmd Op args
527 This specifies the content of 12 ATA Command Block registers (command,
528 features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp.
529 lba_high_exp, features_exp, sector_count, sector_count_exp).
530 .It Fl c Ar cmd Op args
531 This specifies the SCSI CDB.
532 SCSI CDBs may be 6, 10, 12 or 16 bytes.
533 .It Fl i Ar len Ar fmt
534 This specifies the amount of data to read, and how it should be displayed.
538 bytes of data will be read from the device and written to standard output.
539 .It Fl o Ar len Ar fmt Op args
540 This specifies the amount of data to be written to a device, and the data
541 that is to be written.
545 bytes of data will be read from standard input and written to the device.
547 This specifies that 11 result ATA Command Block registers should be displayed
548 (status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp,
549 lba_high_exp, sector_count, sector_count_exp), and how.
552 11 result registers will be written to standard output in hex.
555 Turn on CAM debugging printfs in the kernel.
556 This requires options CAMDEBUG
557 in your kernel config file.
558 WARNING: enabling debugging printfs currently
559 causes an EXTREME number of kernel printfs.
560 You may have difficulty
561 turning off the debugging printfs once they start, since the kernel will be
562 busy printing messages and unable to service other requests quickly.
565 function takes a number of arguments:
568 Enable CAM_DEBUG_INFO printfs.
570 Enable CAM_DEBUG_PERIPH printfs.
572 Enable CAM_DEBUG_TRACE printfs.
574 Enable CAM_DEBUG_SUBTRACE printfs.
576 Enable CAM_DEBUG_XPT printfs.
578 Enable CAM_DEBUG_CDB printfs.
579 This will cause the kernel to print out the
580 SCSI CDBs sent to the specified device(s).
582 Enable debugging for all devices.
584 Turn off debugging for all devices
585 .It bus Ns Op :target Ns Op :lun
586 Turn on debugging for the given bus, target or lun.
588 and lun are not specified, they are wildcarded.
589 (i.e., just specifying a
590 bus turns on debugging printfs for all devices on that bus.)
593 Show or set the number of "tagged openings" or simultaneous transactions
594 we attempt to queue to a particular device.
597 command, with no command-specific arguments (i.e., only generic arguments)
598 prints out the "soft" maximum number of transactions that can be queued to
599 the device in question.
600 For more detailed information, use the
602 argument described below.
605 Set the number of tags for the given device.
606 This must be between the
607 minimum and maximum number set in the kernel quirk table.
609 most devices that support tagged queueing is a minimum of 2 and a maximum
611 The minimum and maximum values for a given device may be
612 determined by using the
619 subcommand is described below.
621 Be quiet, and do not report the number of tags.
622 This is generally used when
623 setting the number of tags.
625 The verbose flag has special functionality for the
630 to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB:
633 This is the amount of capacity for transactions queued to a given device.
635 This is the number of transactions currently queued to a device.
637 This is the kernel queue space for transactions.
638 This count usually mirrors
639 dev_openings except during error recovery operations when
640 the device queue is frozen (device is not allowed to receive
641 commands), the number of dev_openings is reduced, or transaction
644 This is the number of transactions waiting in the kernel queue for capacity
646 This number is usually zero unless error recovery is in
649 The held count is the number of CCBs held by peripheral drivers that have
650 either just been completed or are about to be released to the transport
651 layer for service by a device.
652 Held CCBs reserve capacity on a given
655 This is the current "hard" minimum number of transactions that can be
656 queued to a device at once.
659 value above cannot go below this number.
660 The default value for
662 is 2, although it may be set higher or lower for various devices.
664 This is the "hard" maximum number of transactions that can be queued to a
668 value cannot go above this number.
669 The default value for
671 is 255, although it may be set higher or lower for various devices.
675 Show or negotiate various communication parameters.
677 not support setting or changing some of these values.
679 Adaptec 174x controllers do not support changing a device's sync rate or
684 will not attempt to set the parameter if the controller indicates that it
685 does not support setting the parameter.
686 To find out what the controller
694 command is described below.
695 Also, some controller drivers do not support
696 setting negotiation parameters, even if the underlying controller supports
698 Some controllers, such as the Advansys wide
699 controllers, support enabling and disabling synchronous negotiation for
700 a device, but do not support setting the synchronous negotiation rate.
703 Attempt to make the negotiation settings take effect immediately by sending
704 a Test Unit Ready command to the device.
706 Show or set current negotiation settings.
708 .It Fl D Ar enable|disable
709 Enable or disable disconnection.
713 Set the command delay offset.
715 Be quiet, do not print anything.
716 This is generally useful when you want to
717 set a parameter, but do not want any status information.
719 Change the synchronization rate for a device.
720 The sync rate is a floating
721 point value specified in MHz.
724 is a legal value, as is
726 .It Fl T Ar enable|disable
727 Enable or disable tagged queueing for a device.
729 Show or set user negotiation settings.
730 The default is to show or set
731 current negotiation settings.
733 The verbose switch has special meaning for the
738 to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the
740 .It Fl W Ar bus_width
741 Specify the bus width to negotiate with a device.
744 The only useful values to specify are 8, 16, and 32
746 The controller must support the bus width in question in order for
747 the setting to take effect.
750 In general, sync rate and offset settings will not take effect for a
751 device until a command has been sent to the device.
754 switch above will automatically send a Test Unit Ready to the device so
755 negotiation parameters will take effect.
759 FORMAT UNIT command to the named device.
761 .Em WARNING! WARNING! WARNING!
763 Low level formatting a disk will destroy ALL data on the disk.
765 extreme caution when issuing this command.
766 Many users low-level format
767 disks that do not really need to be low-level formatted.
769 relatively few scenarios that call for low-level formatting a disk.
771 low-level formatting a disk is to initialize the disk after changing
772 its physical sector size.
773 Another reason for low-level formatting a disk
774 is to revive the disk if you are getting "medium format corrupted" errors
775 from the disk in response to read and write requests.
777 Some disks take longer than others to format.
778 Users should specify a
779 timeout long enough to allow the format to complete.
781 timeout is 3 hours, which should be long enough for most disks.
783 disks will complete a format operation in a very short period of time
784 (on the order of 5 minutes or less).
785 This is often because the drive
786 does not really support the FORMAT UNIT command -- it just accepts the
787 command, waits a few minutes and then returns it.
791 subcommand takes several arguments that modify its default behavior.
796 arguments can be useful for scripts.
800 Be quiet, do not print any status messages.
801 This option will not disable
802 the questions, however.
803 To disable questions, use the
810 This will report status on a format that is already running on the drive.
812 Issue a non-immediate format command.
815 issues the FORMAT UNIT command with the immediate bit set.
817 device to immediately return the format command, before the format has
823 sense information from the device every second to determine how far along
824 in the format process it is.
827 argument is specified,
829 will issue a non-immediate format command, and will be unable to print any
830 information to let the user know what percentage of the disk has been
833 Do not ask any questions.
836 will ask the user if he/she really wants to format the disk in question,
837 and also if the default format command timeout is acceptable.
839 will not be asked about the timeout if a timeout is specified on the
843 Put ATA device into IDLE state. Optional parameter specifies automatic
844 idle timer value in seconds.
846 Put ATA device into STANDBY state. Optional parameter specifies automatic
847 standby timer value in seconds.
849 Put ATA device into SLEEP state. Note that the only way get device out of
850 this state may be reset.
852 Print out verbose usage information.
857 variable allows the user to specify an alternate mode page format file.
861 variable determines which text editor
863 starts when editing mode pages.
865 .Bl -tag -width /usr/share/misc/scsi_modes -compact
866 .It Pa /usr/share/misc/scsi_modes
867 is the SCSI mode format database.
869 is the transport layer device.
871 are the CAM application passthrough devices.
874 .Dl camcontrol eject -n cd -u 1 -v
876 Eject the CD from cd1, and print SCSI sense information if the command
879 .Dl camcontrol tur da0
881 Send the SCSI test unit ready command to da0.
884 utility will report whether the disk is ready, but will not display sense
885 information if the command fails since the
887 switch was not specified.
889 .Bd -literal -offset indent
890 camcontrol tur da1 -E -C 4 -t 50 -v
893 Send a test unit ready command to da1.
894 Enable kernel error recovery.
895 Specify a retry count of 4, and a timeout of 50 seconds.
899 flag) if the command fails.
900 Since error recovery is turned on, the
901 disk will be spun up if it is not currently spinning.
904 utility will report whether the disk is ready.
905 .Bd -literal -offset indent
906 camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
907 -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
910 Issue a READ BUFFER command (0x3C) to cd1.
911 Display the buffer size of cd1,
912 and display the first 10 bytes from the cache on cd1.
914 information if the command fails.
916 .Bd -literal -offset indent
917 camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
918 -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
921 Issue a WRITE BUFFER (0x3B) command to cd1.
922 Write out 10 bytes of data,
923 not including the (reserved) 4 byte header.
924 Print out sense information if
926 Be very careful with this command, improper use may
927 cause data corruption.
929 .Bd -literal -offset indent
930 camcontrol modepage da3 -m 1 -e -P 3
933 Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
934 settings on the drive.
935 Mode page 1 contains a disk drive's auto read and
936 write reallocation settings, among other things.
938 .Dl camcontrol rescan all
940 Rescan all SCSI busses in the system for devices that have been added,
943 .Dl camcontrol rescan 0
945 Rescan SCSI bus 0 for devices that have been added, removed or changed.
947 .Dl camcontrol rescan 0:1:0
949 Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or
952 .Dl camcontrol tags da5 -N 24
954 Set the number of concurrent transactions for da5 to 24.
956 .Bd -literal -offset indent
957 camcontrol negotiate -n da -u 4 -T disable
960 Disable tagged queueing for da4.
962 .Bd -literal -offset indent
963 camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a
966 Negotiate a sync rate of 20MHz and an offset of 15 with da3.
968 Test Unit Ready command to make the settings take effect.
978 utility first appeared in
981 The mode page editing code and arbitrary SCSI command code are based upon
986 library, written by Julian Elischer and Peter Dufault.
989 program first appeared in
991 and first appeared in
996 .An Kenneth Merry Aq ken@FreeBSD.org
998 The code that parses the generic command line arguments does not know that
999 some of the subcommands take multiple arguments.
1000 So if, for instance, you
1001 tried something like this:
1002 .Bd -literal -offset indent
1003 camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
1006 The sense information from the test unit ready command would not get
1007 printed out, since the first
1011 bails out when it sees the second argument to
1015 Fixing this behavior would take some gross code, or changes to the
1018 The best way to circumvent this problem is to always make sure
1021 arguments before any command-specific arguments.
projects / FreeBSD / stable / 8.git / blob