xref: /freebsd/sbin/camcontrol/camcontrol.8 (revision 5ca34122ecdd5abc62bdae39663fec9ac8523d87)
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 August 6, 2015
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 b
45.Op Fl v
46.Nm
47.Ic periphlist
48.Op device id
49.Op Fl n Ar dev_name
50.Op Fl u Ar unit_number
51.Nm
52.Ic tur
53.Op device id
54.Op generic args
55.Nm
56.Ic inquiry
57.Op device id
58.Op generic args
59.Op Fl D
60.Op Fl S
61.Op Fl R
62.Nm
63.Ic identify
64.Op device id
65.Op generic args
66.Op Fl v
67.Nm
68.Ic reportluns
69.Op device id
70.Op generic args
71.Op Fl c
72.Op Fl l
73.Op Fl r Ar reporttype
74.Nm
75.Ic readcap
76.Op device id
77.Op generic args
78.Op Fl b
79.Op Fl h
80.Op Fl H
81.Op Fl N
82.Op Fl q
83.Op Fl s
84.Nm
85.Ic start
86.Op device id
87.Op generic args
88.Nm
89.Ic stop
90.Op device id
91.Op generic args
92.Nm
93.Ic load
94.Op device id
95.Op generic args
96.Nm
97.Ic eject
98.Op device id
99.Op generic args
100.Nm
101.Ic rescan
102.Aq all | bus Ns Op :target:lun
103.Nm
104.Ic reset
105.Aq all | bus Ns Op :target:lun
106.Nm
107.Ic defects
108.Op device id
109.Op generic args
110.Aq Fl f Ar format
111.Op Fl P
112.Op Fl G
113.Op Fl q
114.Op Fl s
115.Op Fl S Ar offset
116.Op Fl X
117.Nm
118.Ic modepage
119.Op device id
120.Op generic args
121.Aq Fl m Ar page | Fl l
122.Op Fl P Ar pgctl
123.Op Fl b | Fl e
124.Op Fl d
125.Nm
126.Ic cmd
127.Op device id
128.Op generic args
129.Aq Fl a Ar cmd Op args
130.Aq Fl c Ar cmd Op args
131.Op Fl d
132.Op Fl f
133.Op Fl i Ar len Ar fmt
134.Bk -words
135.Op Fl o Ar len Ar fmt Op args
136.Op Fl r Ar fmt
137.Ek
138.Nm
139.Ic smpcmd
140.Op device id
141.Op generic args
142.Aq Fl r Ar len Ar fmt Op args
143.Aq Fl R Ar len Ar fmt Op args
144.Nm
145.Ic smprg
146.Op device id
147.Op generic args
148.Op Fl l
149.Nm
150.Ic smppc
151.Op device id
152.Op generic args
153.Aq Fl p Ar phy
154.Op Fl l
155.Op Fl o Ar operation
156.Op Fl d Ar name
157.Op Fl m Ar rate
158.Op Fl M Ar rate
159.Op Fl T Ar pp_timeout
160.Op Fl a Ar enable|disable
161.Op Fl A Ar enable|disable
162.Op Fl s Ar enable|disable
163.Op Fl S Ar enable|disable
164.Nm
165.Ic smpphylist
166.Op device id
167.Op generic args
168.Op Fl l
169.Op Fl q
170.Nm
171.Ic smpmaninfo
172.Op device id
173.Op generic args
174.Op Fl l
175.Nm
176.Ic debug
177.Op Fl I
178.Op Fl P
179.Op Fl T
180.Op Fl S
181.Op Fl X
182.Op Fl c
183.Op Fl p
184.Aq all|off|bus Ns Op :target Ns Op :lun
185.Nm
186.Ic tags
187.Op device id
188.Op generic args
189.Op Fl N Ar tags
190.Op Fl q
191.Op Fl v
192.Nm
193.Ic negotiate
194.Op device id
195.Op generic args
196.Op Fl c
197.Op Fl D Ar enable|disable
198.Op Fl M Ar mode
199.Op Fl O Ar offset
200.Op Fl q
201.Op Fl R Ar syncrate
202.Op Fl T Ar enable|disable
203.Op Fl U
204.Op Fl W Ar bus_width
205.Op Fl v
206.Nm
207.Ic format
208.Op device id
209.Op generic args
210.Op Fl q
211.Op Fl r
212.Op Fl w
213.Op Fl y
214.Nm
215.Ic sanitize
216.Op device id
217.Op generic args
218.Aq Fl a Ar overwrite | block | crypto | exitfailure
219.Op Fl c Ar passes
220.Op Fl I
221.Op Fl P Ar pattern
222.Op Fl q
223.Op Fl U
224.Op Fl r
225.Op Fl w
226.Op Fl y
227.Nm
228.Ic idle
229.Op device id
230.Op generic args
231.Op Fl t Ar time
232.Nm
233.Ic standby
234.Op device id
235.Op generic args
236.Op Fl t Ar time
237.Nm
238.Ic sleep
239.Op device id
240.Op generic args
241.Nm
242.Ic apm
243.Op device id
244.Op generic args
245.Op Fl l Ar level
246.Nm
247.Ic aam
248.Op device id
249.Op generic args
250.Op Fl l Ar level
251.Nm
252.Ic fwdownload
253.Op device id
254.Op generic args
255.Aq Fl f Ar fw_image
256.Op Fl q
257.Op Fl s
258.Op Fl y
259.Nm
260.Ic security
261.Op device id
262.Op generic args
263.Op Fl d Ar pwd
264.Op Fl e Ar pwd
265.Op Fl f
266.Op Fl h Ar pwd
267.Op Fl k Ar pwd
268.Op Fl l Ar high|maximum
269.Op Fl q
270.Op Fl s Ar pwd
271.Op Fl T Ar timeout
272.Op Fl U Ar user|master
273.Op Fl y
274.Nm
275.Ic hpa
276.Op device id
277.Op generic args
278.Op Fl f
279.Op Fl l
280.Op Fl P
281.Op Fl p Ar pwd
282.Op Fl q
283.Op Fl s Ar max_sectors
284.Op Fl U Ar pwd
285.Op Fl y
286.Nm
287.Ic persist
288.Op device id
289.Op generic args
290.Aq Fl i Ar action | Fl o Ar action
291.Op Fl a
292.Op Fl I Ar trans_id
293.Op Fl k Ar key
294.Op Fl K Ar sa_key
295.Op Fl p
296.Op Fl R Ar rel_tgt_port
297.Op Fl s Ar scope
298.Op Fl S
299.Op Fl T Ar res_type
300.Op Fl U
301.Nm
302.Ic attrib
303.Op device id
304.Op generic args
305.Aq Fl r Ar action | Fl w Ar attrib
306.Op Fl a Ar attr_num
307.Op Fl c
308.Op Fl e Ar elem_addr
309.Op Fl F Ar form1,form2
310.Op Fl p Ar part
311.Op Fl s Ar start_addr
312.Op Fl T Ar elem_type
313.Op Fl V Ar lv_num
314.Nm
315.Ic opcodes
316.Op device id
317.Op generic args
318.Op Fl o Ar opcode
319.Op Fl s Ar service_action
320.Op Fl N
321.Op Fl T
322.Nm
323.Ic help
324.Sh DESCRIPTION
325The
326.Nm
327utility is designed to provide a way for users to access and control the
328.Fx
329CAM subsystem.
330.Pp
331The
332.Nm
333utility
334can cause a loss of data and/or system crashes if used improperly.
335Even
336expert users are encouraged to exercise caution when using this command.
337Novice users should stay away from this utility.
338.Pp
339The
340.Nm
341utility has a number of primary functions, many of which support an optional
342device identifier.
343A device identifier can take one of three forms:
344.Bl -tag -width 14n
345.It deviceUNIT
346Specify a device name and unit number combination, like "da5" or "cd3".
347.It bus:target
348Specify a bus number and target id.
349The bus number can be determined from
350the output of
351.Dq camcontrol devlist .
352The lun defaults to 0.
353.It bus:target:lun
354Specify the bus, target and lun for a device.
355(e.g.\& 1:2:0)
356.El
357.Pp
358The device identifier, if it is specified,
359.Em must
360come immediately after the function name, and before any generic or
361function-specific arguments.
362Note that the
363.Fl n
364and
365.Fl u
366arguments described below will override any device name or unit number
367specified beforehand.
368The
369.Fl n
370and
371.Fl u
372arguments will
373.Em not
374override a specified bus:target or bus:target:lun, however.
375.Pp
376Most of the
377.Nm
378primary functions support these generic arguments:
379.Bl -tag -width 14n
380.It Fl C Ar count
381SCSI command retry count.
382In order for this to work, error recovery
383.Pq Fl E
384must be turned on.
385.It Fl E
386Instruct the kernel to perform generic SCSI error recovery for the given
387command.
388This is needed in order for the retry count
389.Pq Fl C
390to be honored.
391Other than retrying commands, the generic error recovery in
392the code will generally attempt to spin up drives that are not spinning.
393It may take some other actions, depending upon the sense code returned from
394the command.
395.It Fl n Ar dev_name
396Specify the device type to operate on, e.g.\& "da", "cd".
397.It Fl t Ar timeout
398SCSI command timeout in seconds.
399This overrides the default timeout for
400any given command.
401.It Fl u Ar unit_number
402Specify the device unit number, e.g.\& "1", "5".
403.It Fl v
404Be verbose, print out sense information for failed SCSI commands.
405.El
406.Pp
407Primary command functions:
408.Bl -tag -width periphlist
409.It Ic devlist
410List all physical devices (logical units) attached to the CAM subsystem.
411This also includes a list of peripheral drivers attached to each device.
412With the
413.Fl v
414argument, SCSI bus number, adapter name and unit numbers are printed as
415well.
416On the other hand, with the
417.Fl b
418argument, only the bus adapter, and unit information will be printed, and
419device information will be omitted.
420.It Ic periphlist
421List all peripheral drivers attached to a given physical device (logical
422unit).
423.It Ic tur
424Send the SCSI test unit ready (0x00) command to the given device.
425The
426.Nm
427utility will report whether the device is ready or not.
428.It Ic inquiry
429Send a SCSI inquiry command (0x12) to a device.
430By default,
431.Nm
432will print out the standard inquiry data, device serial number, and
433transfer rate information.
434The user can specify that only certain types of
435inquiry data be printed:
436.Bl -tag -width 4n
437.It Fl D
438Get the standard inquiry data.
439.It Fl S
440Print out the serial number.
441If this flag is the only one specified,
442.Nm
443will not print out "Serial Number" before the value returned by the drive.
444This is to aid in script writing.
445.It Fl R
446Print out transfer rate information.
447.El
448.It Ic identify
449Send a ATA identify command (0xec) to a device.
450.It Ic reportluns
451Send the SCSI REPORT LUNS (0xA0) command to the given device.
452By default,
453.Nm
454will print out the list of logical units (LUNs) supported by the target device.
455There are a couple of options to modify the output:
456.Bl -tag -width 14n
457.It Fl c
458Just print out a count of LUNs, not the actual LUN numbers.
459.It Fl l
460Just print out the LUNs, and do not print out the count.
461.It Fl r Ar reporttype
462Specify the type of report to request from the target:
463.Bl -tag -width 012345678
464.It default
465Return the default report.
466This is the
467.Nm
468default.
469Most targets will support this report if they support the REPORT LUNS
470command.
471.It wellknown
472Return only well known LUNs.
473.It all
474Return all available LUNs.
475.El
476.El
477.Pp
478.Nm
479will try to print out LUN numbers in a reasonable format.
480It can understand the peripheral, flat, LUN and extended LUN formats.
481.It Ic readcap
482Send the SCSI READ CAPACITY command to the given device and display
483the results.
484If the device is larger than 2TB, the SCSI READ CAPACITY (16) service
485action will be sent to obtain the full size of the device.
486By default,
487.Nm
488will print out the last logical block of the device, and the blocksize of
489the device in bytes.
490To modify the output format, use the following options:
491.Bl -tag -width 5n
492.It Fl b
493Just print out the blocksize, not the last block or device size.
494This cannot be used with
495.Fl N
496or
497.Fl s .
498.It Fl h
499Print out the device size in human readable (base 2, 1K == 1024) format.
500This implies
501.Fl N
502and cannot be used with
503.Fl q
504or
505.Fl b .
506.It Fl H
507Print out the device size in human readable (base 10, 1K == 1000) format.
508.It Fl N
509Print out the number of blocks in the device instead of the last logical
510block.
511.It Fl q
512Quiet, print out the numbers only (separated by a comma if
513.Fl b
514or
515.Fl s
516are not specified).
517.It Fl s
518Print out the last logical block or the size of the device only, and omit
519the blocksize.
520.El
521.It Ic start
522Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
523start bit set.
524.It Ic stop
525Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
526start bit cleared.
527.It Ic load
528Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
529start bit set and the load/eject bit set.
530.It Ic eject
531Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
532start bit cleared and the load/eject bit set.
533.It Ic rescan
534Tell the kernel to scan all busses in the system (with the
535.Ar all
536argument), the given bus (XPT_SCAN_BUS), or bus:target:lun
537(XPT_SCAN_LUN) for new devices or devices that have gone away.
538The user
539may specify a scan of all busses, a single bus, or a lun.
540Scanning all luns
541on a target is not supported.
542.It Ic reset
543Tell the kernel to reset all busses in the system (with the
544.Ar all
545argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus
546reset for that bus, or to reset the given bus:target:lun
547(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after
548connecting to that device.
549Note that this can have a destructive impact
550on the system.
551.It Ic defects
552Send the
553.Tn SCSI
554READ DEFECT DATA (10) command (0x37) or the
555.Tn SCSI
556READ DEFECT DATA (12) command (0xB7) to the given device, and
557print out any combination of: the total number of defects, the primary
558defect list (PLIST), and the grown defect list (GLIST).
559.Bl -tag -width 11n
560.It Fl f Ar format
561Specify the requested format of the defect list.
562The format argument is
563required.
564Most drives support the physical sector format.
565Some drives
566support the logical block format.
567Many drives, if they do not support the
568requested format, return the data in an alternate format, along with sense
569information indicating that the requested data format is not supported.
570The
571.Nm
572utility
573attempts to detect this, and print out whatever format the drive returns.
574If the drive uses a non-standard sense code to report that it does not
575support the requested format,
576.Nm
577will probably see the error as a failure to complete the request.
578.Pp
579The format options are:
580.Bl -tag -width 9n
581.It block
582Print out the list as logical blocks.
583This is limited to 32-bit block sizes, and isn't supported by many modern
584drives.
585.It longblock
586Print out the list as logical blocks.
587This option uses a 64-bit block size.
588.It bfi
589Print out the list in bytes from index format.
590.It extbfi
591Print out the list in extended bytes from index format.
592The extended format allows for ranges of blocks to be printed.
593.It phys
594Print out the list in physical sector format.
595Most drives support this format.
596.It extphys
597Print out the list in extended physical sector format.
598The extended format allows for ranges of blocks to be printed.
599.El
600.It Fl G
601Print out the grown defect list.
602This is a list of bad blocks that have
603been remapped since the disk left the factory.
604.It Fl P
605Print out the primary defect list.
606This is the list of defects that were present in the factory.
607.It Fl q
608When printing status information with
609.Fl s ,
610only print the number of defects.
611.It Fl s
612Just print the number of defects, not the list of defects.
613.It Fl S Ar offset
614Specify the starting offset into the defect list.
615This implies using the
616.Tn SCSI
617READ DEFECT DATA (12) command, as the 10 byte version of the command
618doesn't support the address descriptor index field.
619Not all drives support the 12 byte command, and some drives that support
620the 12 byte command don't support the address descriptor index field.
621.It Fl X
622Print out defects in hexadecimal (base 16) form instead of base 10 form.
623.El
624.Pp
625If neither
626.Fl P
627nor
628.Fl G
629is specified,
630.Nm
631will print out the number of defects given in the READ DEFECT DATA header
632returned from the drive.
633Some drives will report 0 defects if neither the primary or grown defect
634lists are requested.
635.It Ic modepage
636Allows the user to display and optionally edit a SCSI mode page.
637The mode
638page formats are located in
639.Pa /usr/share/misc/scsi_modes .
640This can be overridden by specifying a different file in the
641.Ev SCSI_MODES
642environment variable.
643The
644.Ic modepage
645command takes several arguments:
646.Bl -tag -width 12n
647.It Fl d
648Disable block descriptors for mode sense.
649.It Fl b
650Displays mode page data in binary format.
651.It Fl e
652This flag allows the user to edit values in the mode page.
653The user may
654either edit mode page values with the text editor pointed to by his
655.Ev EDITOR
656environment variable, or supply mode page values via standard input, using
657the same format that
658.Nm
659uses to display mode page values.
660The editor will be invoked if
661.Nm
662detects that standard input is terminal.
663.It Fl l
664Lists all available mode pages.
665.It Fl m Ar mode_page
666This specifies the number of the mode page the user would like to view
667and/or edit.
668This argument is mandatory unless
669.Fl l
670is specified.
671.It Fl P Ar pgctl
672This allows the user to specify the page control field.
673Possible values are:
674.Bl -tag -width xxx -compact
675.It 0
676Current values
677.It 1
678Changeable values
679.It 2
680Default values
681.It 3
682Saved values
683.El
684.El
685.It Ic cmd
686Allows the user to send an arbitrary ATA or SCSI CDB to any device.
687The
688.Ic cmd
689function requires the
690.Fl c
691argument to specify SCSI CDB or the
692.Fl a
693argument to specify ATA Command Block registers values.
694Other arguments are optional, depending on
695the command type.
696The command and data specification syntax is documented
697in
698.Xr cam_cdbparse 3 .
699NOTE: If the CDB specified causes data to be transferred to or from the
700SCSI device in question, you MUST specify either
701.Fl i
702or
703.Fl o .
704.Bl -tag -width 17n
705.It Fl a Ar cmd Op args
706This specifies the content of 12 ATA Command Block registers (command,
707features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp.
708lba_high_exp, features_exp, sector_count, sector_count_exp).
709.It Fl c Ar cmd Op args
710This specifies the SCSI CDB.
711SCSI CDBs may be 6, 10, 12 or 16 bytes.
712.It Fl d
713Specifies DMA protocol to be used for ATA command.
714.It Fl f
715Specifies FPDMA (NCQ) protocol to be used for ATA command.
716.It Fl i Ar len Ar fmt
717This specifies the amount of data to read, and how it should be displayed.
718If the format is
719.Sq - ,
720.Ar len
721bytes of data will be read from the device and written to standard output.
722.It Fl o Ar len Ar fmt Op args
723This specifies the amount of data to be written to a device, and the data
724that is to be written.
725If the format is
726.Sq - ,
727.Ar len
728bytes of data will be read from standard input and written to the device.
729.It Fl r Ar fmt
730This specifies that 11 result ATA Command Block registers should be displayed
731(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp,
732lba_high_exp, sector_count, sector_count_exp), and how.
733If the format is
734.Sq - ,
73511 result registers will be written to standard output in hex.
736.El
737.It Ic smpcmd
738Allows the user to send an arbitrary Serial
739Management Protocol (SMP) command to a device.
740The
741.Ic smpcmd
742function requires the
743.Fl r
744argument to specify the SMP request to be sent, and the
745.Fl R
746argument to specify the format of the SMP response.
747The syntax for the SMP request and response arguments is documented in
748.Xr cam_cdbparse 3 .
749.Pp
750Note that SAS adapters that support SMP passthrough (at least the currently
751known adapters) do not accept CRC bytes from the user in the request and do
752not pass CRC bytes back to the user in the response.
753Therefore users should not include the CRC bytes in the length of the
754request and not expect CRC bytes to be returned in the response.
755.Bl -tag -width 17n
756.It Fl r Ar len Ar fmt Op args
757This specifies the size of the SMP request, without the CRC bytes, and the
758SMP request format.
759If the format is
760.Sq - ,
761.Ar len
762bytes of data will be read from standard input and written as the SMP
763request.
764.It Fl R Ar len Ar fmt Op args
765This specifies the size of the buffer allocated for the SMP response, and
766the SMP response format.
767If the format is
768.Sq - ,
769.Ar len
770bytes of data will be allocated for the response and the response will be
771written to standard output.
772.El
773.It Ic smprg
774Allows the user to send the Serial Management Protocol (SMP) Report General
775command to a device.
776.Nm
777will display the data returned by the Report General command.
778If the SMP target supports the long response format, the additional data
779will be requested and displayed automatically.
780.Bl -tag -width 8n
781.It Fl l
782Request the long response format only.
783Not all SMP targets support the long response format.
784This option causes
785.Nm
786to skip sending the initial report general request without the long bit set
787and only issue a report general request with the long bit set.
788.El
789.It Ic smppc
790Allows the user to issue the Serial Management Protocol (SMP) PHY Control
791command to a device.
792This function should be used with some caution, as it can render devices
793inaccessible, and could potentially cause data corruption as well.
794The
795.Fl p
796argument is required to specify the PHY to operate on.
797.Bl -tag -width 17n
798.It Fl p Ar phy
799Specify the PHY to operate on.
800This argument is required.
801.It Fl l
802Request the long request/response format.
803Not all SMP targets support the long response format.
804For the PHY Control command, this currently only affects whether the
805request length is set to a value other than 0.
806.It Fl o Ar operation
807Specify a PHY control operation.
808Only one
809.Fl o
810operation may be specified.
811The operation may be specified numerically (in decimal, hexadecimal, or octal)
812or one of the following operation names may be specified:
813.Bl -tag -width 16n
814.It nop
815No operation.
816It is not necessary to specify this argument.
817.It linkreset
818Send the LINK RESET command to the phy.
819.It hardreset
820Send the HARD RESET command to the phy.
821.It disable
822Send the DISABLE command to the phy.
823Note that the LINK RESET or HARD RESET commands should re-enable the phy.
824.It clearerrlog
825Send the CLEAR ERROR LOG command.
826This clears the error log counters for the specified phy.
827.It clearaffiliation
828Send the CLEAR AFFILIATION command.
829This clears the affiliation from the STP initiator port with the same SAS
830address as the SMP initiator that requests the clear operation.
831.It sataportsel
832Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy.
833This will cause a SATA port selector to use the given phy as its active phy
834and make the other phy inactive.
835.It clearitnl
836Send the CLEAR STP I_T NEXUS LOSS command to the PHY.
837.It setdevname
838Send the SET ATTACHED DEVICE NAME command to the PHY.
839This requires the
840.Fl d
841argument to specify the device name.
842.El
843.It Fl d Ar name
844Specify the attached device name.
845This option is needed with the
846.Fl o Ar setdevname
847phy operation.
848The name is a 64-bit number, and can be specified in decimal, hexadecimal
849or octal format.
850.It Fl m Ar rate
851Set the minimum physical link rate for the phy.
852This is a numeric argument.
853Currently known link rates are:
854.Bl -tag -width 5n
855.It 0x0
856Do not change current value.
857.It 0x8
8581.5 Gbps
859.It 0x9
8603 Gbps
861.It 0xa
8626 Gbps
863.El
864.Pp
865Other values may be specified for newer physical link rates.
866.It Fl M Ar rate
867Set the maximum physical link rate for the phy.
868This is a numeric argument.
869See the
870.Fl m
871argument description for known link rate arguments.
872.It Fl T Ar pp_timeout
873Set the partial pathway timeout value, in microseconds.
874See the
875.Tn ANSI
876.Tn SAS
877Protocol Layer (SPL)
878specification for more information on this field.
879.It Fl a Ar enable|disable
880Enable or disable SATA slumber phy power conditions.
881.It Fl A Ar enable|disable
882Enable or disable SATA partial power conditions.
883.It Fl s Ar enable|disable
884Enable or disable SAS slumber phy power conditions.
885.It Fl S Ar enable|disable
886Enable or disable SAS partial phy power conditions.
887.El
888.It Ic smpphylist
889List phys attached to a SAS expander, the address of the end device
890attached to the phy, and the inquiry data for that device and peripheral
891devices attached to that device.
892The inquiry data and peripheral devices are displayed if available.
893.Bl -tag -width 5n
894.It Fl l
895Turn on the long response format for the underlying SMP commands used for
896this command.
897.It Fl q
898Only print out phys that are attached to a device in the CAM EDT (Existing
899Device Table).
900.El
901.It Ic smpmaninfo
902Send the SMP Report Manufacturer Information command to the device and
903display the response.
904.Bl -tag -width 5n
905.It Fl l
906Turn on the long response format for the underlying SMP commands used for
907this command.
908.El
909.It Ic debug
910Turn on CAM debugging printfs in the kernel.
911This requires options CAMDEBUG
912in your kernel config file.
913WARNING: enabling debugging printfs currently
914causes an EXTREME number of kernel printfs.
915You may have difficulty
916turning off the debugging printfs once they start, since the kernel will be
917busy printing messages and unable to service other requests quickly.
918The
919.Ic debug
920function takes a number of arguments:
921.Bl -tag -width 18n
922.It Fl I
923Enable CAM_DEBUG_INFO printfs.
924.It Fl P
925Enable CAM_DEBUG_PERIPH printfs.
926.It Fl T
927Enable CAM_DEBUG_TRACE printfs.
928.It Fl S
929Enable CAM_DEBUG_SUBTRACE printfs.
930.It Fl X
931Enable CAM_DEBUG_XPT printfs.
932.It Fl c
933Enable CAM_DEBUG_CDB printfs.
934This will cause the kernel to print out the
935SCSI CDBs sent to the specified device(s).
936.It Fl p
937Enable CAM_DEBUG_PROBE printfs.
938.It all
939Enable debugging for all devices.
940.It off
941Turn off debugging for all devices
942.It bus Ns Op :target Ns Op :lun
943Turn on debugging for the given bus, target or lun.
944If the lun or target
945and lun are not specified, they are wildcarded.
946(i.e., just specifying a
947bus turns on debugging printfs for all devices on that bus.)
948.El
949.It Ic tags
950Show or set the number of "tagged openings" or simultaneous transactions
951we attempt to queue to a particular device.
952By default, the
953.Ic tags
954command, with no command-specific arguments (i.e., only generic arguments)
955prints out the "soft" maximum number of transactions that can be queued to
956the device in question.
957For more detailed information, use the
958.Fl v
959argument described below.
960.Bl -tag -width 7n
961.It Fl N Ar tags
962Set the number of tags for the given device.
963This must be between the
964minimum and maximum number set in the kernel quirk table.
965The default for
966most devices that support tagged queueing is a minimum of 2 and a maximum
967of 255.
968The minimum and maximum values for a given device may be
969determined by using the
970.Fl v
971switch.
972The meaning of the
973.Fl v
974switch for this
975.Nm
976subcommand is described below.
977.It Fl q
978Be quiet, and do not report the number of tags.
979This is generally used when
980setting the number of tags.
981.It Fl v
982The verbose flag has special functionality for the
983.Em tags
984argument.
985It causes
986.Nm
987to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB:
988.Bl -tag -width 13n
989.It dev_openings
990This is the amount of capacity for transactions queued to a given device.
991.It dev_active
992This is the number of transactions currently queued to a device.
993.It devq_openings
994This is the kernel queue space for transactions.
995This count usually mirrors
996dev_openings except during error recovery operations when
997the device queue is frozen (device is not allowed to receive
998commands), the number of dev_openings is reduced, or transaction
999replay is occurring.
1000.It devq_queued
1001This is the number of transactions waiting in the kernel queue for capacity
1002on the device.
1003This number is usually zero unless error recovery is in
1004progress.
1005.It held
1006The held count is the number of CCBs held by peripheral drivers that have
1007either just been completed or are about to be released to the transport
1008layer for service by a device.
1009Held CCBs reserve capacity on a given
1010device.
1011.It mintags
1012This is the current "hard" minimum number of transactions that can be
1013queued to a device at once.
1014The
1015.Ar dev_openings
1016value above cannot go below this number.
1017The default value for
1018.Ar mintags
1019is 2, although it may be set higher or lower for various devices.
1020.It maxtags
1021This is the "hard" maximum number of transactions that can be queued to a
1022device at one time.
1023The
1024.Ar dev_openings
1025value cannot go above this number.
1026The default value for
1027.Ar maxtags
1028is 255, although it may be set higher or lower for various devices.
1029.El
1030.El
1031.It Ic negotiate
1032Show or negotiate various communication parameters.
1033Some controllers may
1034not support setting or changing some of these values.
1035For instance, the
1036Adaptec 174x controllers do not support changing a device's sync rate or
1037offset.
1038The
1039.Nm
1040utility
1041will not attempt to set the parameter if the controller indicates that it
1042does not support setting the parameter.
1043To find out what the controller
1044supports, use the
1045.Fl v
1046flag.
1047The meaning of the
1048.Fl v
1049flag for the
1050.Ic negotiate
1051command is described below.
1052Also, some controller drivers do not support
1053setting negotiation parameters, even if the underlying controller supports
1054negotiation changes.
1055Some controllers, such as the Advansys wide
1056controllers, support enabling and disabling synchronous negotiation for
1057a device, but do not support setting the synchronous negotiation rate.
1058.Bl -tag -width 17n
1059.It Fl a
1060Attempt to make the negotiation settings take effect immediately by sending
1061a Test Unit Ready command to the device.
1062.It Fl c
1063Show or set current negotiation settings.
1064This is the default.
1065.It Fl D Ar enable|disable
1066Enable or disable disconnection.
1067.It Fl M Ar mode
1068Set ATA mode.
1069.It Fl O Ar offset
1070Set the command delay offset.
1071.It Fl q
1072Be quiet, do not print anything.
1073This is generally useful when you want to
1074set a parameter, but do not want any status information.
1075.It Fl R Ar syncrate
1076Change the synchronization rate for a device.
1077The sync rate is a floating
1078point value specified in MHz.
1079So, for instance,
1080.Sq 20.000
1081is a legal value, as is
1082.Sq 20 .
1083.It Fl T Ar enable|disable
1084Enable or disable tagged queueing for a device.
1085.It Fl U
1086Show or set user negotiation settings.
1087The default is to show or set
1088current negotiation settings.
1089.It Fl v
1090The verbose switch has special meaning for the
1091.Ic negotiate
1092subcommand.
1093It causes
1094.Nm
1095to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the
1096controller driver.
1097.It Fl W Ar bus_width
1098Specify the bus width to negotiate with a device.
1099The bus width is
1100specified in bits.
1101The only useful values to specify are 8, 16, and 32
1102bits.
1103The controller must support the bus width in question in order for
1104the setting to take effect.
1105.El
1106.Pp
1107In general, sync rate and offset settings will not take effect for a
1108device until a command has been sent to the device.
1109The
1110.Fl a
1111switch above will automatically send a Test Unit Ready to the device so
1112negotiation parameters will take effect.
1113.It Ic format
1114Issue the
1115.Tn SCSI
1116FORMAT UNIT command to the named device.
1117.Pp
1118.Em WARNING! WARNING! WARNING!
1119.Pp
1120Low level formatting a disk will destroy ALL data on the disk.
1121Use
1122extreme caution when issuing this command.
1123Many users low-level format
1124disks that do not really need to be low-level formatted.
1125There are
1126relatively few scenarios that call for low-level formatting a disk.
1127One reason for
1128low-level formatting a disk is to initialize the disk after changing
1129its physical sector size.
1130Another reason for low-level formatting a disk
1131is to revive the disk if you are getting "medium format corrupted" errors
1132from the disk in response to read and write requests.
1133.Pp
1134Some disks take longer than others to format.
1135Users should specify a
1136timeout long enough to allow the format to complete.
1137The default format
1138timeout is 3 hours, which should be long enough for most disks.
1139Some hard
1140disks will complete a format operation in a very short period of time
1141(on the order of 5 minutes or less).
1142This is often because the drive
1143does not really support the FORMAT UNIT command -- it just accepts the
1144command, waits a few minutes and then returns it.
1145.Pp
1146The
1147.Sq format
1148subcommand takes several arguments that modify its default behavior.
1149The
1150.Fl q
1151and
1152.Fl y
1153arguments can be useful for scripts.
1154.Bl -tag -width 6n
1155.It Fl q
1156Be quiet, do not print any status messages.
1157This option will not disable
1158the questions, however.
1159To disable questions, use the
1160.Fl y
1161argument, below.
1162.It Fl r
1163Run in
1164.Dq report only
1165mode.
1166This will report status on a format that is already running on the drive.
1167.It Fl w
1168Issue a non-immediate format command.
1169By default,
1170.Nm
1171issues the FORMAT UNIT command with the immediate bit set.
1172This tells the
1173device to immediately return the format command, before the format has
1174actually completed.
1175Then,
1176.Nm
1177gathers
1178.Tn SCSI
1179sense information from the device every second to determine how far along
1180in the format process it is.
1181If the
1182.Fl w
1183argument is specified,
1184.Nm
1185will issue a non-immediate format command, and will be unable to print any
1186information to let the user know what percentage of the disk has been
1187formatted.
1188.It Fl y
1189Do not ask any questions.
1190By default,
1191.Nm
1192will ask the user if he/she really wants to format the disk in question,
1193and also if the default format command timeout is acceptable.
1194The user
1195will not be asked about the timeout if a timeout is specified on the
1196command line.
1197.El
1198.It Ic sanitize
1199Issue the
1200.Tn SCSI
1201SANITIZE command to the named device.
1202.Pp
1203.Em WARNING! WARNING! WARNING!
1204.Pp
1205ALL data in the cache and on the disk will be destroyed or made inaccessible.
1206Recovery of the data is not possible.
1207Use extreme caution when issuing this command.
1208.Pp
1209The
1210.Sq sanitize
1211subcommand takes several arguments that modify its default behavior.
1212The
1213.Fl q
1214and
1215.Fl y
1216arguments can be useful for scripts.
1217.Bl -tag -width 6n
1218.It Fl a Ar operation
1219Specify the sanitize operation to perform.
1220.Bl -tag -width 16n
1221.It overwrite
1222Perform an overwrite operation by writing a user supplied
1223data pattern to the device one or more times.
1224The pattern is given by the
1225.Fl P
1226argument.
1227The number of times is given by the
1228.Fl c
1229argument.
1230.It block
1231Perform a block erase operation.
1232All the device's blocks are set to a vendor defined
1233value, typically zero.
1234.It crypto
1235Perform a cryptographic erase operation.
1236The encryption keys are changed to prevent the decryption
1237of the data.
1238.It exitfailure
1239Exits a previously failed sanitize operation.
1240A failed sanitize operation can only be exited if it was
1241run in the unrestricted completion mode, as provided by the
1242.Fl U
1243argument.
1244.El
1245.It Fl c Ar passes
1246The number of passes when performing an
1247.Sq overwrite
1248operation.
1249Valid values are between 1 and 31.
1250The default is 1.
1251.It Fl I
1252When performing an
1253.Sq overwrite
1254operation, the pattern is inverted between consecutive passes.
1255.It Fl P Ar pattern
1256Path to the file containing the pattern to use when
1257performing an
1258.Sq overwrite
1259operation.
1260The pattern is repeated as needed to fill each block.
1261.It Fl q
1262Be quiet, do not print any status messages.
1263This option will not disable
1264the questions, however.
1265To disable questions, use the
1266.Fl y
1267argument, below.
1268.It Fl U
1269Perform the sanitize in the unrestricted completion mode.
1270If the operation fails, it can later be exited with the
1271.Sq exitfailure
1272operation.
1273.It Fl r
1274Run in
1275.Dq report only
1276mode.
1277This will report status on a sanitize that is already running on the drive.
1278.It Fl w
1279Issue a non-immediate sanitize command.
1280By default,
1281.Nm
1282issues the SANITIZE command with the immediate bit set.
1283This tells the
1284device to immediately return the sanitize command, before
1285the sanitize has actually completed.
1286Then,
1287.Nm
1288gathers
1289.Tn SCSI
1290sense information from the device every second to determine how far along
1291in the sanitize process it is.
1292If the
1293.Fl w
1294argument is specified,
1295.Nm
1296will issue a non-immediate sanitize command, and will be unable to print any
1297information to let the user know what percentage of the disk has been
1298sanitized.
1299.It Fl y
1300Do not ask any questions.
1301By default,
1302.Nm
1303will ask the user if he/she really wants to sanitize the disk in question,
1304and also if the default sanitize command timeout is acceptable.
1305The user
1306will not be asked about the timeout if a timeout is specified on the
1307command line.
1308.El
1309.It Ic idle
1310Put ATA device into IDLE state.
1311Optional parameter
1312.Pq Fl t
1313specifies automatic standby timer value in seconds.
1314Value 0 disables timer.
1315.It Ic standby
1316Put ATA device into STANDBY state.
1317Optional parameter
1318.Pq Fl t
1319specifies automatic standby timer value in seconds.
1320Value 0 disables timer.
1321.It Ic sleep
1322Put ATA device into SLEEP state.
1323Note that the only way get device out of
1324this state may be reset.
1325.It Ic apm
1326It optional parameter
1327.Pq Fl l
1328specified, enables and sets advanced power management level, where
13291 -- minimum power, 127 -- maximum performance with standby,
1330128 -- minimum power without standby, 254 -- maximum performance.
1331If not specified -- APM is disabled.
1332.It Ic aam
1333It optional parameter
1334.Pq Fl l
1335specified, enables and sets automatic acoustic management level, where
13361 -- minimum noise, 254 -- maximum performance.
1337If not specified -- AAM is disabled.
1338.It Ic security
1339Update or report security settings, using an ATA identify command (0xec).
1340By default,
1341.Nm
1342will print out the security support and associated settings of the device.
1343The
1344.Ic security
1345command takes several arguments:
1346.Bl -tag -width 0n
1347.It Fl d Ar pwd
1348.Pp
1349Disable device security using the given password for the selected user according
1350to the devices configured security level.
1351.It Fl e Ar pwd
1352.Pp
1353Erase the device using the given password for the selected user.
1354.Pp
1355.Em WARNING! WARNING! WARNING!
1356.Pp
1357Issuing a secure erase will
1358.Em ERASE ALL
1359user data on the device and may take several hours to complete.
1360.Pp
1361When this command is used against an SSD drive all its cells will be marked as
1362empty, restoring it to factory default write performance.
1363For SSD's this action
1364usually takes just a few seconds.
1365.It Fl f
1366.Pp
1367Freeze the security configuration of the specified device.
1368.Pp
1369After command completion any other commands that update the device lock mode
1370shall be command aborted.
1371Frozen mode is disabled by power-off or hardware reset.
1372.It Fl h Ar pwd
1373.Pp
1374Enhanced erase the device using the given password for the selected user.
1375.Pp
1376.Em WARNING! WARNING! WARNING!
1377.Pp
1378Issuing an enhanced secure erase will
1379.Em ERASE ALL
1380user data on the device and may take several hours to complete.
1381.Pp
1382An enhanced erase writes predetermined data patterns to all user data areas,
1383all previously written user data shall be overwritten, including sectors that
1384are no longer in use due to reallocation.
1385.It Fl k Ar pwd
1386.Pp
1387Unlock the device using the given password for the selected user according to
1388the devices configured security level.
1389.It Fl l Ar high|maximum
1390.Pp
1391Specifies which security level to set when issuing a
1392.Fl s Ar pwd
1393command.
1394The security level determines device behavior when the master
1395password is used to unlock the device.
1396When the security level is set to high
1397the device requires the unlock command and the master password to unlock.
1398When the security level is set to maximum the device requires a secure erase
1399with the master password to unlock.
1400.Pp
1401This option must be used in conjunction with one of the security action commands.
1402.Pp
1403Defaults to
1404.Em high
1405.It Fl q
1406.Pp
1407Be quiet, do not print any status messages.
1408This option will not disable the questions, however.
1409To disable questions, use the
1410.Fl y
1411argument, below.
1412.It Fl s Ar pwd
1413.Pp
1414Password the device (enable security) using the given password for the selected
1415user.
1416This option can be combined with other options such as
1417.Fl e Em pwd
1418.Pp
1419A master password may be set in a addition to the user password. The purpose of
1420the master password is to allow an administrator to establish a password that
1421is kept secret from the user, and which may be used to unlock the device if the
1422user password is lost.
1423.Pp
1424.Em Note:
1425Setting the master password does not enable device security.
1426.Pp
1427If the master password is set and the drive supports a Master Revision Code
1428feature the Master Password Revision Code will be decremented.
1429.It Fl T Ar timeout
1430.Pp
1431Overrides the default timeout, specified in seconds, used for both
1432.Fl e
1433and
1434.Fl h
1435this is useful if your system has problems processing long timeouts correctly.
1436.Pp
1437Usually the timeout is calculated from the information stored on the drive if
1438present, otherwise it defaults to 2 hours.
1439.It Fl U Ar user|master
1440.Pp
1441Specifies which user to set / use for the running action command, valid values
1442are user or master and defaults to master if not set.
1443.Pp
1444This option must be used in conjunction with one of the security action commands.
1445.Pp
1446Defaults to
1447.Em master
1448.It Fl y
1449.Pp
1450Confirm yes to dangerous options such as
1451.Fl e
1452without prompting for confirmation.
1453.El
1454.Pp
1455If the password specified for any action commands does not match the configured
1456password for the specified user the command will fail.
1457.Pp
1458The password in all cases is limited to 32 characters, longer passwords will
1459fail.
1460.It Ic hpa
1461Update or report Host Protected Area details.
1462By default
1463.Nm
1464will print out the HPA support and associated settings of the device.
1465The
1466.Ic hpa
1467command takes several optional arguments:
1468.Bl -tag -width 0n
1469.It Fl f
1470.Pp
1471Freeze the HPA configuration of the specified device.
1472.Pp
1473After command completion any other commands that update the HPA configuration
1474shall be command aborted.
1475Frozen mode is disabled by power-off or hardware reset.
1476.It Fl l
1477.Pp
1478Lock the HPA configuration of the device until a successful call to unlock or
1479the next power-on reset occurs.
1480.It Fl P
1481.Pp
1482Make the HPA max sectors persist across power-on reset or a hardware reset.
1483This must be used in combination with
1484.Fl s Ar max_sectors
1485.
1486.It Fl p Ar pwd
1487.Pp
1488Set the HPA configuration password required for unlock calls.
1489.It Fl q
1490.Pp
1491Be quiet, do not print any status messages.
1492This option will not disable the questions.
1493To disable questions, use the
1494.Fl y
1495argument, below.
1496.It Fl s Ar max_sectors
1497.Pp
1498Configures the maximum user accessible sectors of the device.
1499This will change the number of sectors the device reports.
1500.Pp
1501.Em WARNING! WARNING! WARNING!
1502.Pp
1503Changing the max sectors of a device using this option will make the data on
1504the device beyond the specified value inaccessible.
1505.Pp
1506Only one successful
1507.Fl s Ar max_sectors
1508call can be made without a power-on reset or a hardware reset of the device.
1509.It Fl U Ar pwd
1510.Pp
1511Unlock the HPA configuration of the specified device using the given password.
1512If the password specified does not match the password configured via
1513.Fl p Ar pwd
1514the command will fail.
1515.Pp
1516After 5 failed unlock calls, due to password miss-match, the device will refuse
1517additional unlock calls until after a power-on reset.
1518.It Fl y
1519.Pp
1520Confirm yes to dangerous options such as
1521.Fl e
1522without prompting for confirmation
1523.El
1524.Pp
1525The password for all HPA commands is limited to 32 characters, longer passwords
1526will fail.
1527.It Ic fwdownload
1528Program firmware of the named
1529.Tn SCSI
1530or ATA device using the image file provided.
1531.Pp
1532If the device is a
1533.Tn SCSI
1534device and it provides a recommended timeout for the WRITE BUFFER command
1535(see the
1536.Nm
1537opcodes subcommand), that timeout will be used for the firmware download.
1538The drive-recommended timeout value may be overridden on the command line
1539with the
1540.Fl t
1541option.
1542.Pp
1543Current list of supported vendors for SCSI/SAS drives:
1544.Bl -tag -width 10n
1545.It HGST
1546Tested with 4TB SAS drives, model number HUS724040ALS640.
1547.It HITACHI
1548.It HP
1549.It IBM
1550Tested with LTO-5 (ULTRIUM-HH5) and LTO-6 (ULTRIUM-HH6) tape drives.
1551There is a separate table entry for hard drives, because the update method
1552for hard drives is different than the method for tape drives.
1553.It PLEXTOR
1554.It QUALSTAR
1555.It QUANTUM
1556.It SAMSUNG
1557Tested with SM1625 SSDs.
1558.It SEAGATE
1559Tested with Constellation ES (ST32000444SS), ES.2 (ST33000651SS) and
1560ES.3 (ST1000NM0023) drives.
1561.It SmrtStor
1562Tested with 400GB Optimus SSDs (TXA2D20400GA6001).
1563.El
1564.Pp
1565.Em WARNING! WARNING! WARNING!
1566.Pp
1567Little testing has been done to make sure that different device models from
1568each vendor work correctly with the fwdownload command.
1569A vendor name appearing in the supported list means only that firmware of at
1570least one device type from that vendor has successfully been programmed with
1571the fwdownload command.
1572Extra caution should be taken when using this command since there is no
1573guarantee it will not break a device from the listed vendors.
1574Ensure that you have a recent backup of the data on the device before
1575performing a firmware update.
1576.Pp
1577Note that unknown
1578.Tn SCSI
1579protocol devices will not be programmed, since there is little chance of
1580the firmware download succeeding.
1581.Pp
1582.Nm
1583will currently attempt a firmware download to any
1584.Tn ATA
1585or
1586.Tn SATA
1587device, since the standard
1588.Tn ATA
1589DOWNLOAD MICROCODE command may work.
1590Firmware downloads to
1591.Tn ATA
1592and
1593.Tn SATA
1594devices are supported for devices connected
1595to standard
1596.Tn ATA
1597and
1598.Tn SATA
1599controllers, and devices connected to SAS controllers
1600with
1601.Tn SCSI
1602to
1603.Tn ATA
1604translation capability.
1605In the latter case,
1606.Nm
1607uses the
1608.Tn SCSI
1609.Tn ATA
1610PASS-THROUGH command to send the
1611.Tn ATA
1612DOWNLOAD MICROCODE command to the drive.
1613Some
1614.Tn SCSI
1615to
1616.Tn ATA
1617translation implementations don't work fully when translating
1618.Tn SCSI
1619WRITE BUFFER commands to
1620.Tn ATA
1621DOWNLOAD MICROCODE commands, but do support
1622.Tn ATA
1623passthrough well enough to do a firmware download.
1624.Bl -tag -width 11n
1625.It Fl f Ar fw_image
1626Path to the firmware image file to be downloaded to the specified device.
1627.It Fl q
1628Do not print informational messages, only print errors.
1629This option should be used with the
1630.Fl y
1631option to suppress all output.
1632.It Fl s
1633Run in simulation mode.
1634Device checks are run and the confirmation dialog is shown, but no firmware
1635download will occur.
1636.It Fl v
1637Show
1638.Tn SCSI
1639or
1640.Tn ATA
1641errors in the event of a failure.
1642.Pp
1643In simulation mode, print out the
1644.Tn SCSI
1645CDB
1646or
1647.Tn ATA
1648register values that would be used for the firmware download command.
1649.It Fl y
1650Do not ask for confirmation.
1651.El
1652.It Ic persist
1653Persistent reservation support.
1654Persistent reservations are a way to reserve a particular
1655.Tn SCSI
1656LUN for use by one or more
1657.Tn SCSI
1658initiators.
1659If the
1660.Fl i
1661option is specified,
1662.Nm
1663will issue the
1664.Tn SCSI
1665PERSISTENT RESERVE IN
1666command using the requested service action.
1667If the
1668.Fl o
1669option is specified,
1670.Nm
1671will issue the
1672.Tn SCSI
1673PERSISTENT RESERVE OUT
1674command using the requested service action.
1675One of those two options is required.
1676.Pp
1677Persistent reservations are complex, and fully explaining them is outside
1678the scope of this manual.
1679Please visit
1680http://www.t10.org
1681and download the latest SPC spec for a full explanation of persistent
1682reservations.
1683.Bl -tag -width 8n
1684.It Fl i Ar mode
1685Specify the service action for the PERSISTENT RESERVE IN command.
1686Supported service actions:
1687.Bl -tag -width 19n
1688.It read_keys
1689Report the current persistent reservation generation (PRgeneration) and any
1690registered keys.
1691.It read_reservation
1692Report the persistent reservation, if any.
1693.It report_capabilities
1694Report the persistent reservation capabilities of the LUN.
1695.It read_full_status
1696Report the full status of persistent reservations on the LUN.
1697.El
1698.It Fl o Ar mode
1699Specify the service action for the PERSISTENT RESERVE OUT command.
1700For service actions like register that are components of other service
1701action names, the entire name must be specified.
1702Otherwise, enough of the service action name must be specified to
1703distinguish it from other possible service actions.
1704Supported service actions:
1705.Bl -tag -width 15n
1706.It register
1707Register a reservation key with the LUN or unregister a reservation key.
1708To register a key, specify the requested key as the Service Action
1709Reservation Key.
1710To unregister a key, specify the previously registered key as the
1711Reservation Key.
1712To change a key, specify the old key as the Reservation Key and the new
1713key as the Service Action Reservation Key.
1714.It register_ignore
1715This is similar to the register subcommand, except that the Reservation Key
1716is ignored.
1717The Service Action Reservation Key will overwrite any previous key
1718registered for the initiator.
1719.It reserve
1720Create a reservation.
1721A key must be registered with the LUN before the LUN can be reserved, and
1722it must be specified as the Reservation Key.
1723The type of reservation must also be specified.
1724The scope defaults to LUN scope (LU_SCOPE), but may be changed.
1725.It release
1726Release a reservation.
1727The Reservation Key must be specified.
1728.It clear
1729Release a reservation and remove all keys from the device.
1730The Reservation Key must be specified.
1731.It preempt
1732Remove a reservation belonging to another initiator.
1733The Reservation Key must be specified.
1734The Service Action Reservation Key may be specified, depending on the
1735operation being performed.
1736.It preempt_abort
1737Remove a reservation belonging to another initiator and abort all
1738outstanding commands from that initiator.
1739The Reservation Key must be specified.
1740The Service Action Reservation Key may be specified, depending on the
1741operation being performed.
1742.It register_move
1743Register another initiator with the LUN, and establish a reservation on the
1744LUN for that initiator.
1745The Reservation Key and Service Action Reservation Key must be specified.
1746.It replace_lost
1747Replace Lost Reservation information.
1748.El
1749.It Fl a
1750Set the All Target Ports (ALL_TG_PT) bit.
1751This requests that the key registration be applied to all target ports and
1752not just the particular target port that receives the command.
1753This only applies to the register and register_ignore actions.
1754.It Fl I Ar tid
1755Specify a Transport ID.
1756This only applies to the Register and Register and Move service actions for
1757Persistent Reserve Out.
1758Multiple Transport IDs may be specified with multiple
1759.Fl I
1760arguments.
1761With the Register service action, specifying one or more Transport IDs
1762implicitly enables the
1763.Fl S
1764option which turns on the SPEC_I_PT bit.
1765Transport IDs generally have the format protocol,id.
1766.Bl -tag -width 5n
1767.It SAS
1768A SAS Transport ID consists of
1769.Dq sas,
1770followed by a 64-bit SAS address.
1771For example:
1772.Pp
1773.Dl sas,0x1234567812345678
1774.It FC
1775A Fibre Channel Transport ID consists of
1776.Dq fcp,
1777followed by a 64-bit Fibre Channel World Wide Name.
1778For example:
1779.Pp
1780.Dl fcp,0x1234567812345678
1781.It SPI
1782A Parallel SCSI address consists of
1783.Dq spi,
1784followed by a SCSI target ID and a relative target port identifier.
1785For example:
1786.Pp
1787.Dl spi,4,1
1788.It 1394
1789An IEEE 1394 (Firewire) Transport ID consists of
1790.Dq sbp,
1791followed by a 64-bit EUI-64 IEEE 1394 node unique identifier.
1792For example:
1793.Pp
1794.Dl sbp,0x1234567812345678
1795.It RDMA
1796A SCSI over RDMA Transport ID consists of
1797.Dq srp,
1798followed by a 128-bit RDMA initiator port identifier.
1799The port identifier must be exactly 32 or 34 (if the leading 0x is
1800included) hexadecimal digits.
1801Only hexadecimal (base 16) numbers are supported.
1802For example:
1803.Pp
1804.Dl srp,0x12345678123456781234567812345678
1805.It iSCSI
1806An iSCSI Transport ID consists an iSCSI name and optionally a separator and
1807iSCSI session ID.
1808For example, if only the iSCSI name is specified:
1809.Pp
1810.Dl iqn.2012-06.com.example:target0
1811.Pp
1812If the iSCSI separator and initiator session ID are specified:
1813.Pp
1814.Dl iqn.2012-06.com.example:target0,i,0x123
1815.It PCIe
1816A SCSI over PCIe Transport ID consists of
1817.Dq sop,
1818followed by a PCIe Routing ID.
1819The Routing ID consists of a bus, device and function or in the alternate
1820form, a bus and function.
1821The bus must be in the range of 0 to 255 inclusive and the device must be
1822in the range of 0 to 31 inclusive.
1823The function must be in the range of 0 to 7 inclusive if the standard form
1824is used, and in the range of 0 to 255 inclusive if the alternate form is
1825used.
1826For example, if a bus, device and function are specified for the standard
1827Routing ID form:
1828.Pp
1829.Dl sop,4,5,1
1830.Pp
1831If the alternate Routing ID form is used:
1832.Pp
1833.Dl sop,4,1
1834.El
1835.It Fl k Ar key
1836Specify the Reservation Key.
1837This may be in decimal, octal or hexadecimal format.
1838The value is zero by default if not otherwise specified.
1839The value must be between 0 and 2^64 - 1, inclusive.
1840.It Fl K Ar key
1841Specify the Service Action Reservation Key.
1842This may be in decimal, octal or hexadecimal format.
1843The value is zero by default if not otherwise specified.
1844The value must be between 0 and 2^64 - 1, inclusive.
1845.It Fl p
1846Enable the Activate Persist Through Power Loss bit.
1847This is only used for the register and register_ignore actions.
1848This requests that the reservation persist across power loss events.
1849.It Fl s Ar scope
1850Specify the scope of the reservation.
1851The scope may be specified by name or by number.
1852The scope is ignored for register, register_ignore and clear.
1853If the desired scope isn't available by name, you may specify the number.
1854.Bl -tag -width 7n
1855.It lun
1856LUN scope (0x00).
1857This encompasses the entire LUN.
1858.It extent
1859Extent scope (0x01).
1860.It element
1861Element scope (0x02).
1862.El
1863.It Fl R Ar rtp
1864Specify the Relative Target Port.
1865This only applies to the Register and Move service action of the Persistent
1866Reserve Out command.
1867.It Fl S
1868Enable the SPEC_I_PT bit.
1869This only applies to the Register service action of Persistent Reserve Out.
1870You must also specify at least one Transport ID with
1871.Fl I
1872if this option is set.
1873If you specify a Transport ID, this option is automatically set.
1874It is an error to specify this option for any service action other than
1875Register.
1876.It Fl T Ar type
1877Specify the reservation type.
1878The reservation type may be specified by name or by number.
1879If the desired reservation type isn't available by name, you may specify
1880the number.
1881Supported reservation type names:
1882.Bl -tag -width 11n
1883.It read_shared
1884Read Shared mode.
1885.It wr_ex
1886Write Exclusive mode.
1887May also be specified as
1888.Dq write_exclusive .
1889.It rd_ex
1890Read Exclusive mode.
1891May also be specified as
1892.Dq read_exclusive .
1893.It ex_ac
1894Exclusive access mode.
1895May also be specified as
1896.Dq exclusive_access .
1897.It wr_ex_ro
1898Write Exclusive Registrants Only mode.
1899May also be specified as
1900.Dq write_exclusive_reg_only .
1901.It ex_ac_ro
1902Exclusive Access Registrants Only mode.
1903May also be specified as
1904.Dq exclusive_access_reg_only .
1905.It wr_ex_ar
1906Write Exclusive All Registrants mode.
1907May also be specified as
1908.Dq write_exclusive_all_regs .
1909.It ex_ac_ar
1910Exclusive Access All Registrants mode.
1911May also be specified as
1912.Dq exclusive_access_all_regs .
1913.El
1914.It Fl U
1915Specify that the target should unregister the initiator that sent
1916the Register and Move request.
1917By default, the target will not unregister the initiator that sends the
1918Register and Move request.
1919This option only applies to the Register and Move service action of the
1920Persistent Reserve Out command.
1921.El
1922.It Ic attrib
1923Issue the
1924.Tn SCSI
1925READ or WRITE ATTRIBUTE commands.
1926These commands are used to read and write attributes in Medium Auxiliary
1927Memory (MAM).
1928The most common place Medium Auxiliary Memory is found is small flash chips
1929included tape cartriges.
1930For instance,
1931.Tn LTO
1932tapes have MAM.
1933Either the
1934.Fl r
1935option or the
1936.Fl w
1937option must be specified.
1938.Bl -tag -width 14n
1939.It Fl r Ar action
1940Specify the READ ATTRIBUTE service action.
1941.Bl -tag -width 11n
1942.It attr_values
1943Issue the ATTRIBUTE VALUES service action.
1944Read and decode the available attributes and their values.
1945.It attr_list
1946Issue the ATTRIBUTE LIST service action.
1947List the attributes that are available to read and write.
1948.It lv_list
1949Issue the LOGICAL VOLUME LIST service action.
1950List the available logical volumes in the MAM.
1951.It part_list
1952Issue the PARTITION LIST service action.
1953List the available partitions in the MAM.
1954.It supp_attr
1955Issue the SUPPORTED ATTRIBUTES service action.
1956List attributes that are supported for reading or writing.
1957These attributes may or may not be currently present in the MAM.
1958.El
1959.It Fl w Ar attr
1960Specify an attribute to write to the MAM.
1961This option is not yet implemented.
1962.It Fl a Ar num
1963Specify the attribute number to display.
1964This option only works with the attr_values, attr_list and supp_attr
1965arguments to
1966.Fl r .
1967.It Fl c
1968Display cached attributes.
1969If the device supports this flag, it allows displaying attributes for the
1970last piece of media loaded in the drive.
1971.It Fl e Ar num
1972Specify the element address.
1973This is used for specifying which element number in a medium changer to
1974access when reading attributes.
1975The element number could be for a picker, portal, slot or drive.
1976.It Fl F Ar form1,form2
1977Specify the output format for the attribute values (attr_val) display as a
1978comma separated list of options.
1979The default output is currently set to field_all,nonascii_trim,text_raw.
1980Once this code is ported to FreeBSD 10, any text fields will be converted
1981from their codeset to the user's native codeset with
1982.Xr iconv 3 .
1983.Pp
1984The text options are mutually exclusive; if you specify more than one, you
1985will get unpredictable results.
1986The nonascii options are also mutually exclusive.
1987Most of the field options may be logically ORed together.
1988.Bl -tag -width 12n
1989.It text_esc
1990Print text fields with non-ASCII characters escaped.
1991.It text_raw
1992Print text fields natively, with no codeset conversion.
1993.It nonascii_esc
1994If any non-ASCII characters occur in fields that are supposed to be ASCII,
1995escape the non-ASCII characters.
1996.It nonascii_trim
1997If any non-ASCII characters occur in fields that are supposed to be ASCII,
1998omit the non-ASCII characters.
1999.It nonascii_raw
2000If any non-ASCII characters occur in fields that are supposed to be ASCII,
2001print them as they are.
2002.It field_all
2003Print all of the prefix fields: description, attribute number, attribute
2004size, and the attribute's readonly status.
2005If field_all is specified, specifying any other field options will not have
2006an effect.
2007.It field_none
2008Print none of the prefix fields, and only print out the attribute value.
2009If field_none is specified, specifying any other field options will result
2010in those fields being printed.
2011.It field_desc
2012Print out the attribute description.
2013.It field_num
2014Print out the attribute number.
2015.It field_size
2016Print out the attribute size.
2017.It field_rw
2018Print out the attribute's readonly status.
2019.El
2020.It Fl p Ar part
2021Specify the partition.
2022When the media has multiple partitions, specifying different partition
2023numbers allows seeing the values for each individual partition.
2024.It Fl s Ar start_num
2025Specify the starting attribute number.
2026This requests that the target device return attribute information starting
2027at the given number.
2028.It Fl T Ar elem_type
2029Specify the element type.
2030For medium changer devices, this allows specifying the type the element
2031referenced in the element address (
2032.Fl e ) .
2033Valid types are:
2034.Dq all ,
2035.Dq picker ,
2036.Dq slot ,
2037.Dq portal ,
2038and
2039.Dq drive .
2040.El
2041.It Fl V Ar vol_num
2042Specify the number of the logical volume to operate on.
2043If the media has multiple logical volumes, this will allow displaying
2044or writing attributes on the given logical volume.
2045.It Ic opcodes
2046Issue the REPORT SUPPORTED OPCODES service action of the
2047.Tn SCSI
2048MAINTENANCE IN
2049command.
2050Without arguments, this command will return a list of all
2051.Tn SCSI
2052commands supported by the device, including service actions of commands
2053that support service actions.
2054It will also include the
2055.Tn SCSI
2056CDB (Command Data Block) length for each command, and the description of
2057each command if it is known.
2058.Bl -tag -width 18n
2059.It Fl o Ar opcode
2060Request information on a specific opcode instead of the list of supported
2061commands.
2062If supported, the target will return a CDB-like structure that indicates
2063the opcode, service action (if any), and a mask of bits that are supported
2064in that CDB.
2065.It Fl s Ar service_action
2066For commands that support a service action, specify the service action to
2067query.
2068.It Fl N
2069If a service action is specified for a given opcode, and the device does
2070not support the given service action, the device should not return a
2071.Tn SCSI
2072error, but rather indicate in the returned parameter data that the command
2073is not supported.
2074By default, if a service action is specified for an opcode, and service
2075actions are not supported for the opcode in question, the device will
2076return an error.
2077.It Fl T
2078Include timeout values.
2079This option works with the default display, which includes all commands
2080supported by the device, and with the
2081.Fl o
2082and
2083.Fl s
2084options, which request information on a specific command and service
2085action.
2086This requests that the device report Nominal and Recommended timeout values
2087for the given command or commands.
2088The timeout values are in seconds.
2089The timeout descriptor also includes a command-specific
2090.El
2091.It Ic help
2092Print out verbose usage information.
2093.El
2094.Sh ENVIRONMENT
2095The
2096.Ev SCSI_MODES
2097variable allows the user to specify an alternate mode page format file.
2098.Pp
2099The
2100.Ev EDITOR
2101variable determines which text editor
2102.Nm
2103starts when editing mode pages.
2104.Sh FILES
2105.Bl -tag -width /usr/share/misc/scsi_modes -compact
2106.It Pa /usr/share/misc/scsi_modes
2107is the SCSI mode format database.
2108.It Pa /dev/xpt0
2109is the transport layer device.
2110.It Pa /dev/pass*
2111are the CAM application passthrough devices.
2112.El
2113.Sh EXAMPLES
2114.Dl camcontrol eject -n cd -u 1 -v
2115.Pp
2116Eject the CD from cd1, and print SCSI sense information if the command
2117fails.
2118.Pp
2119.Dl camcontrol tur da0
2120.Pp
2121Send the SCSI test unit ready command to da0.
2122The
2123.Nm
2124utility will report whether the disk is ready, but will not display sense
2125information if the command fails since the
2126.Fl v
2127switch was not specified.
2128.Bd -literal -offset indent
2129camcontrol tur da1 -E -C 4 -t 50 -v
2130.Ed
2131.Pp
2132Send a test unit ready command to da1.
2133Enable kernel error recovery.
2134Specify a retry count of 4, and a timeout of 50 seconds.
2135Enable sense
2136printing (with the
2137.Fl v
2138flag) if the command fails.
2139Since error recovery is turned on, the
2140disk will be spun up if it is not currently spinning.
2141The
2142.Nm
2143utility will report whether the disk is ready.
2144.Bd -literal -offset indent
2145camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
2146	-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
2147.Ed
2148.Pp
2149Issue a READ BUFFER command (0x3C) to cd1.
2150Display the buffer size of cd1,
2151and display the first 10 bytes from the cache on cd1.
2152Display SCSI sense
2153information if the command fails.
2154.Bd -literal -offset indent
2155camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
2156	-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
2157.Ed
2158.Pp
2159Issue a WRITE BUFFER (0x3B) command to cd1.
2160Write out 10 bytes of data,
2161not including the (reserved) 4 byte header.
2162Print out sense information if
2163the command fails.
2164Be very careful with this command, improper use may
2165cause data corruption.
2166.Bd -literal -offset indent
2167camcontrol modepage da3 -m 1 -e -P 3
2168.Ed
2169.Pp
2170Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
2171settings on the drive.
2172Mode page 1 contains a disk drive's auto read and
2173write reallocation settings, among other things.
2174.Pp
2175.Dl camcontrol rescan all
2176.Pp
2177Rescan all SCSI busses in the system for devices that have been added,
2178removed or changed.
2179.Pp
2180.Dl camcontrol rescan 0
2181.Pp
2182Rescan SCSI bus 0 for devices that have been added, removed or changed.
2183.Pp
2184.Dl camcontrol rescan 0:1:0
2185.Pp
2186Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or
2187changed.
2188.Pp
2189.Dl camcontrol tags da5 -N 24
2190.Pp
2191Set the number of concurrent transactions for da5 to 24.
2192.Bd -literal -offset indent
2193camcontrol negotiate -n da -u 4 -T disable
2194.Ed
2195.Pp
2196Disable tagged queueing for da4.
2197.Bd -literal -offset indent
2198camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a
2199.Ed
2200.Pp
2201Negotiate a sync rate of 20MHz and an offset of 15 with da3.
2202Then send a
2203Test Unit Ready command to make the settings take effect.
2204.Bd -literal -offset indent
2205camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1"
2206.Ed
2207.Pp
2208Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs
2209it contains.
2210Display SMP errors if the command fails.
2211.Bd -literal -offset indent
2212camcontrol security ada0
2213.Ed
2214.Pp
2215Report security support and settings for ada0
2216.Bd -literal -offset indent
2217camcontrol security ada0 -U user -s MyPass
2218.Ed
2219.Pp
2220Enable security on device ada0 with the password MyPass
2221.Bd -literal -offset indent
2222camcontrol security ada0 -U user -e MyPass
2223.Ed
2224.Pp
2225Secure erase ada0 which has had security enabled with user password MyPass
2226.Pp
2227.Em WARNING! WARNING! WARNING!
2228.Pp
2229This will
2230.Em ERASE ALL
2231data from the device, so backup your data before using!
2232.Pp
2233This command can be used against an SSD drive to restoring it to
2234factory default write performance.
2235.Bd -literal -offset indent
2236camcontrol hpa ada0
2237.Ed
2238.Pp
2239Report HPA support and settings for ada0 (also reported via
2240identify).
2241.Bd -literal -offset indent
2242camcontrol hpa ada0 -s 10240
2243.Ed
2244.Pp
2245Enables HPA on ada0 setting the maximum reported sectors to 10240.
2246.Pp
2247.Em WARNING! WARNING! WARNING!
2248.Pp
2249This will
2250.Em PREVENT ACCESS
2251to all data on the device beyond this limit until HPA is disabled by setting
2252HPA to native max sectors of the device, which can only be done after a
2253power-on or hardware reset!
2254.Pp
2255.Em DO NOT
2256use this on a device which has an active filesystem!
2257.Bd -literal -offset indent
2258camcontrol persist da0 -v -i read_keys
2259.Ed
2260.Pp
2261This will read any persistent reservation keys registered with da0, and
2262display any errors encountered when sending the PERSISTENT RESERVE IN
2263.Tn SCSI
2264command.
2265.Bd -literal -offset indent
2266camcontrol persist da0 -v -o register -a -K 0x12345678
2267.Ed
2268.Pp
2269This will register the persistent reservation key 0x12345678 with da0,
2270apply that registration to all ports on da0, and display any errors that
2271occur when sending the PERSISTENT RESERVE OUT command.
2272.Bd -literal -offset indent
2273camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac
2274.Ed
2275.Pp
2276This will reserve da0 for the exlusive use of the initiator issuing the
2277command.
2278The scope of the reservation is the entire LUN.
2279Any errors sending the PERSISTENT RESERVE OUT command will be displayed.
2280.Bd -literal -offset indent
2281camcontrol persist da0 -v -i read_full
2282.Ed
2283.Pp
2284This will display the full status of all reservations on da0 and print out
2285status if there are any errors.
2286.Bd -literal -offset indent
2287camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac
2288.Ed
2289.Pp
2290This will release a reservation on da0 of the type ex_ac
2291(Exclusive Access).
2292The Reservation Key for this registration is 0x12345678.
2293Any errors that occur will be displayed.
2294.Bd -literal -offset indent
2295camcontrol persist da0 -v -o register -K 0x12345678 -S \e
2296	-I sas,0x1234567812345678 -I sas,0x8765432187654321
2297.Ed
2298.Pp
2299This will register the key 0x12345678 with da0, specifying that it applies
2300to the SAS initiators with SAS addresses 0x1234567812345678 and
23010x8765432187654321.
2302.Bd -literal -offset indent
2303camcontrol persist da0 -v -o register_move -k 0x87654321 \e
2304	-K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678
2305.Ed
2306.Pp
2307This will move the registration from the current initiator, whose
2308Registration Key is 0x87654321, to the Fibre Channel initiator with the
2309Fiber Channel World Wide Node Name 0x1234567812345678.
2310A new registration key, 0x12345678, will be registered for the initiator
2311with the Fibre Channel World Wide Node Name 0x1234567812345678, and the
2312current initiator will be unregistered from the target.
2313The reservation will be moved to relative target port 2 on the target
2314device.
2315The registration will persist across power losses.
2316.Bd -literal -offset indent
2317camcontrol attrib sa0 -v -i attr_values -p 1
2318.Ed
2319.Pp
2320This will read and decode the attribute values from partition 1 on the tape
2321in tape drive sa0, and will display any
2322.Tn SCSI
2323errors that result.
2324.Sh SEE ALSO
2325.Xr cam 3 ,
2326.Xr cam_cdbparse 3 ,
2327.Xr cam 4 ,
2328.Xr pass 4 ,
2329.Xr xpt 4
2330.Sh HISTORY
2331The
2332.Nm
2333utility first appeared in
2334.Fx 3.0 .
2335.Pp
2336The mode page editing code and arbitrary SCSI command code are based upon
2337code in the old
2338.Xr scsi 8
2339utility and
2340.Xr scsi 3
2341library, written by Julian Elischer and Peter Dufault.
2342The
2343.Xr scsi 8
2344program first appeared in
2345.Bx 386 0.1.2.4 ,
2346and first appeared in
2347.Fx
2348in
2349.Fx 2.0.5 .
2350.Sh AUTHORS
2351.An Kenneth Merry Aq Mt ken@FreeBSD.org
2352.Sh BUGS
2353The code that parses the generic command line arguments does not know that
2354some of the subcommands take multiple arguments.
2355So if, for instance, you
2356tried something like this:
2357.Bd -literal -offset indent
2358camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
2359.Ed
2360.Pp
2361The sense information from the test unit ready command would not get
2362printed out, since the first
2363.Xr getopt 3
2364call in
2365.Nm
2366bails out when it sees the second argument to
2367.Fl c
2368(0x00),
2369above.
2370Fixing this behavior would take some gross code, or changes to the
2371.Xr getopt 3
2372interface.
2373The best way to circumvent this problem is to always make sure
2374to specify generic
2375.Nm
2376arguments before any command-specific arguments.
2377