xref: /freebsd/sbin/camcontrol/camcontrol.8 (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
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 October 20, 2021
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 l
82.Op Fl N
83.Op Fl q
84.Op Fl s
85.Nm
86.Ic start
87.Op device id
88.Op generic args
89.Nm
90.Ic stop
91.Op device id
92.Op generic args
93.Nm
94.Ic load
95.Op device id
96.Op generic args
97.Nm
98.Ic eject
99.Op device id
100.Op generic args
101.Nm
102.Ic reprobe
103.Op device id
104.Nm
105.Ic rescan
106.Aq all | device id | bus Ns Op :target:lun
107.Nm
108.Ic reset
109.Aq all | device id | bus Ns Op :target:lun
110.Nm
111.Ic defects
112.Op device id
113.Op generic args
114.Aq Fl f Ar format
115.Op Fl P
116.Op Fl G
117.Op Fl q
118.Op Fl s
119.Op Fl S Ar offset
120.Op Fl X
121.Nm
122.Ic modepage
123.Op device id
124.Op generic args
125.Op Fl 6
126.Aq Fl m Ar page[,subpage] | Fl l
127.Op Fl P Ar pgctl
128.Op Fl D
129.Op Fl L
130.Op Fl b | Fl e
131.Op Fl d
132.Nm
133.Ic cmd
134.Op device id
135.Op generic args
136.Aq Fl a Ar cmd Op args
137.Aq Fl c Ar cmd Op args
138.Op Fl d
139.Op Fl f
140.Op Fl i Ar len Ar fmt
141.Bk -words
142.Op Fl o Ar len Ar fmt Op args
143.Op Fl r Ar fmt
144.Ek
145.Nm
146.Ic smpcmd
147.Op device id
148.Op generic args
149.Aq Fl r Ar len Ar fmt Op args
150.Aq Fl R Ar len Ar fmt Op args
151.Nm
152.Ic smprg
153.Op device id
154.Op generic args
155.Op Fl l
156.Nm
157.Ic smppc
158.Op device id
159.Op generic args
160.Aq Fl p Ar phy
161.Op Fl l
162.Op Fl o Ar operation
163.Op Fl d Ar name
164.Op Fl m Ar rate
165.Op Fl M Ar rate
166.Op Fl T Ar pp_timeout
167.Op Fl a Ar enable|disable
168.Op Fl A Ar enable|disable
169.Op Fl s Ar enable|disable
170.Op Fl S Ar enable|disable
171.Nm
172.Ic smpphylist
173.Op device id
174.Op generic args
175.Op Fl l
176.Op Fl q
177.Nm
178.Ic smpmaninfo
179.Op device id
180.Op generic args
181.Op Fl l
182.Nm
183.Ic debug
184.Op Fl I
185.Op Fl P
186.Op Fl T
187.Op Fl S
188.Op Fl X
189.Op Fl c
190.Op Fl p
191.Aq all | off | device id | bus Ns Op :target Ns Op :lun
192.Nm
193.Ic tags
194.Op device id
195.Op generic args
196.Op Fl N Ar tags
197.Op Fl q
198.Op Fl v
199.Nm
200.Ic negotiate
201.Op device id
202.Op generic args
203.Op Fl c
204.Op Fl D Ar enable|disable
205.Op Fl M Ar mode
206.Op Fl O Ar offset
207.Op Fl q
208.Op Fl R Ar syncrate
209.Op Fl T Ar enable|disable
210.Op Fl U
211.Op Fl W Ar bus_width
212.Op Fl v
213.Nm
214.Ic format
215.Op device id
216.Op generic args
217.Op Fl q
218.Op Fl r
219.Op Fl w
220.Op Fl y
221.Nm
222.Ic sanitize
223.Op device id
224.Op generic args
225.Aq Fl a Ar overwrite | block | crypto | exitfailure
226.Op Fl c Ar passes
227.Op Fl I
228.Op Fl P Ar pattern
229.Op Fl q
230.Op Fl U
231.Op Fl r
232.Op Fl w
233.Op Fl y
234.Nm
235.Ic idle
236.Op device id
237.Op generic args
238.Op Fl t Ar time
239.Nm
240.Ic standby
241.Op device id
242.Op generic args
243.Op Fl t Ar time
244.Nm
245.Ic sleep
246.Op device id
247.Op generic args
248.Nm
249.Ic powermode
250.Op device id
251.Op generic args
252.Nm
253.Ic apm
254.Op device id
255.Op generic args
256.Op Fl l Ar level
257.Nm
258.Ic aam
259.Op device id
260.Op generic args
261.Op Fl l Ar level
262.Nm
263.Ic fwdownload
264.Op device id
265.Op generic args
266.Aq Fl f Ar fw_image
267.Op Fl q
268.Op Fl s
269.Op Fl y
270.Nm
271.Ic security
272.Op device id
273.Op generic args
274.Op Fl d Ar pwd
275.Op Fl e Ar pwd
276.Op Fl f
277.Op Fl h Ar pwd
278.Op Fl k Ar pwd
279.Op Fl l Ar high|maximum
280.Op Fl q
281.Op Fl s Ar pwd
282.Op Fl T Ar timeout
283.Op Fl U Ar user|master
284.Op Fl y
285.Nm
286.Ic hpa
287.Op device id
288.Op generic args
289.Op Fl f
290.Op Fl l
291.Op Fl P
292.Op Fl p Ar pwd
293.Op Fl q
294.Op Fl s Ar max_sectors
295.Op Fl U Ar pwd
296.Op Fl y
297.Nm
298.Ic ama
299.Op device id
300.Op generic args
301.Op Fl f
302.Op Fl q
303.Op Fl s Ar max_sectors
304.Nm
305.Ic persist
306.Op device id
307.Op generic args
308.Aq Fl i Ar action | Fl o Ar action
309.Op Fl a
310.Op Fl I Ar trans_id
311.Op Fl k Ar key
312.Op Fl K Ar sa_key
313.Op Fl p
314.Op Fl R Ar rel_tgt_port
315.Op Fl s Ar scope
316.Op Fl S
317.Op Fl T Ar res_type
318.Op Fl U
319.Nm
320.Ic attrib
321.Op device id
322.Op generic args
323.Aq Fl r Ar action | Fl w Ar attrib
324.Op Fl a Ar attr_num
325.Op Fl c
326.Op Fl e Ar elem_addr
327.Op Fl F Ar form1,form2
328.Op Fl p Ar part
329.Op Fl s Ar start_addr
330.Op Fl T Ar elem_type
331.Op Fl V Ar lv_num
332.Nm
333.Ic opcodes
334.Op device id
335.Op generic args
336.Op Fl o Ar opcode
337.Op Fl s Ar service_action
338.Op Fl N
339.Op Fl T
340.Nm
341.Ic zone
342.Aq Fl c Ar cmd
343.Op Fl a
344.Op Fl l Ar lba
345.Op Fl o Ar rep_opts
346.Op Fl P Ar print_opts
347.Nm
348.Ic epc
349.Aq Fl c Ar cmd
350.Op Fl d
351.Op Fl D
352.Op Fl e
353.Op Fl H
354.Op Fl p Ar power_cond
355.Op Fl P
356.Op Fl r Ar restore_src
357.Op Fl s
358.Op Fl S Ar power_src
359.Op Fl T Ar timer
360.Nm
361.Ic timestamp
362.Op device id
363.Op generic args
364.Ao Fl r Oo Ns Fl f Ar format | Fl m | Fl U Oc | Fl s Ao Fl f Ar format Fl T Ar time | Fl U Ac Ac
365.Nm
366.Ic devtype
367.Op device id
368.Nm
369.Ic depop
370.Op device id
371.Op generic args
372.Ao Fl l | Fl d | Fl r Ac
373.Op Fl e Ar elem
374.Op Fl c Ar capacity
375.Nm
376.Ic help
377.Sh DESCRIPTION
378The
379.Nm
380utility is designed to provide a way for users to access and control the
381.Fx
382CAM subsystem.
383.Pp
384The
385.Nm
386utility
387can cause a loss of data and/or system crashes if used improperly.
388Even
389expert users are encouraged to exercise caution when using this command.
390Novice users should stay away from this utility.
391.Pp
392The
393.Nm
394utility has a number of primary functions, many of which support an optional
395device identifier.
396A device identifier can take one of three forms:
397.Bl -tag -width 14n
398.It deviceUNIT
399Specify a device name and unit number combination, like "da5" or "cd3".
400.It bus:target
401Specify a bus number and target id.
402The bus number can be determined from
403the output of
404.Dq camcontrol devlist .
405The lun defaults to 0.
406.It bus:target:lun
407Specify the bus, target and lun for a device.
408(e.g.\& 1:2:0)
409.El
410.Pp
411The device identifier, if it is specified,
412.Em must
413come immediately after the function name, and before any generic or
414function-specific arguments.
415Note that the
416.Fl n
417and
418.Fl u
419arguments described below will override any device name or unit number
420specified beforehand.
421The
422.Fl n
423and
424.Fl u
425arguments will
426.Em not
427override a specified bus:target or bus:target:lun, however.
428.Pp
429Most of the
430.Nm
431primary functions support these generic arguments:
432.Bl -tag -width 14n
433.It Fl C Ar count
434SCSI command retry count.
435In order for this to work, error recovery
436.Pq Fl E
437must be turned on.
438.It Fl E
439Instruct the kernel to perform generic SCSI error recovery for the given
440command.
441This is needed in order for the retry count
442.Pq Fl C
443to be honored.
444Other than retrying commands, the generic error recovery in
445the code will generally attempt to spin up drives that are not spinning.
446It may take some other actions, depending upon the sense code returned from
447the command.
448.It Fl n Ar dev_name
449Specify the device type to operate on, e.g.\& "da", "cd".
450.It Fl Q Ar task_attr
451.Tn SCSI
452task attribute for the command, if it is a
453.Tn SCSI
454command.
455This may be ordered, simple, head, or aca.
456In most cases this is not needed.
457The default is simple, which works with all
458.Tn SCSI
459devices.
460The task attribute may also be specified numerically.
461.It Fl t Ar timeout
462SCSI command timeout in seconds.
463This overrides the default timeout for
464any given command.
465.It Fl u Ar unit_number
466Specify the device unit number, e.g.\& "1", "5".
467.It Fl v
468Be verbose, print out sense information for failed SCSI commands.
469.El
470.Pp
471Primary command functions:
472.Bl -tag -width periphlist
473.It Ic devlist
474List all physical devices (logical units) attached to the CAM subsystem.
475This also includes a list of peripheral drivers attached to each device.
476With the
477.Fl v
478argument, SCSI bus number, adapter name and unit numbers are printed as
479well.
480On the other hand, with the
481.Fl b
482argument, only the bus adapter, and unit information will be printed, and
483device information will be omitted.
484.It Ic periphlist
485List all peripheral drivers attached to a given physical device (logical
486unit).
487.It Ic tur
488Send the SCSI test unit ready (0x00) command to the given device.
489The
490.Nm
491utility will report whether the device is ready or not.
492.It Ic inquiry
493Send a SCSI inquiry command (0x12) to a device.
494By default,
495.Nm
496will print out the standard inquiry data, device serial number, and
497transfer rate information.
498The user can specify that only certain types of
499inquiry data be printed:
500.Bl -tag -width 4n
501.It Fl D
502Get the standard inquiry data.
503.It Fl S
504Print out the serial number.
505If this flag is the only one specified,
506.Nm
507will not print out "Serial Number" before the value returned by the drive.
508This is to aid in script writing.
509.It Fl R
510Print out transfer rate information.
511.El
512.It Ic identify
513Send a ATA identify command (0xec) to a device.
514.It Ic reportluns
515Send the SCSI REPORT LUNS (0xA0) command to the given device.
516By default,
517.Nm
518will print out the list of logical units (LUNs) supported by the target device.
519There are a couple of options to modify the output:
520.Bl -tag -width 14n
521.It Fl c
522Just print out a count of LUNs, not the actual LUN numbers.
523.It Fl l
524Just print out the LUNs, and do not print out the count.
525.It Fl r Ar reporttype
526Specify the type of report to request from the target:
527.Bl -tag -width 012345678
528.It default
529Return the default report.
530This is the
531.Nm
532default.
533Most targets will support this report if they support the REPORT LUNS
534command.
535.It wellknown
536Return only well known LUNs.
537.It all
538Return all available LUNs.
539.El
540.El
541.Pp
542.Nm
543will try to print out LUN numbers in a reasonable format.
544It can understand the peripheral, flat, LUN and extended LUN formats.
545.It Ic readcap
546Send the SCSI READ CAPACITY command to the given device and display
547the results.
548If the device is larger than 2TB, the SCSI READ CAPACITY (16) service
549action will be sent to obtain the full size of the device.
550By default,
551.Nm
552will print out the last logical block of the device, and the blocksize of
553the device in bytes.
554To modify the output format, use the following options:
555.Bl -tag -width 5n
556.It Fl b
557Just print out the blocksize, not the last block or device size.
558This cannot be used with
559.Fl N
560or
561.Fl s .
562.It Fl h
563Print out the device size in human readable (base 2, 1K == 1024) format.
564This implies
565.Fl N
566and cannot be used with
567.Fl q
568or
569.Fl b .
570.It Fl H
571Print out the device size in human readable (base 10, 1K == 1000) format.
572.It Fl l
573Skip sending the SCSI READ CAPACITY (10) command.
574Send only the SCSI READ CAPACITY (16) service action and report
575its results.
576When the two do not match, a quirk is needed to resolve the ambiguity.
577.It Fl N
578Print out the number of blocks in the device instead of the last logical
579block.
580.It Fl q
581Quiet, print out the numbers only (separated by a comma if
582.Fl b
583or
584.Fl s
585are not specified).
586.It Fl s
587Print out the last logical block or the size of the device only, and omit
588the blocksize.
589.El
590.Pp
591Note that this command only displays the information, it does not update
592the kernel data structures.
593Use the
594.Nm
595reprobe subcommand to do that.
596.It Ic start
597Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
598start bit set.
599.It Ic stop
600Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
601start bit cleared.
602.It Ic load
603Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
604start bit set and the load/eject bit set.
605.It Ic eject
606Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
607start bit cleared and the load/eject bit set.
608.It Ic rescan
609Tell the kernel to scan all buses in the system (with the
610.Ar all
611argument), the given bus (XPT_SCAN_BUS), bus:target:lun or device
612(XPT_SCAN_LUN) for new devices or devices that have gone away.
613The user
614may specify a scan of all buses, a single bus, or a lun.
615Scanning all luns
616on a target is not supported.
617.Pp
618If a device is specified by peripheral name and unit number, for instance
619da4, it may only be rescanned if that device currently exists in the CAM EDT
620(Existing Device Table).
621If the device is no longer there (see
622.Nm
623devlist ),
624you must use the bus:target:lun form to rescan it.
625.It Ic reprobe
626Tell the kernel to refresh the information about the device and
627notify the upper layer,
628.Xr GEOM 4 .
629This includes sending the SCSI READ CAPACITY command and updating
630the disk size visible to the rest of the system.
631.It Ic reset
632Tell the kernel to reset all buses in the system (with the
633.Ar all
634argument), the given bus (XPT_RESET_BUS) by issuing a SCSI bus
635reset for that bus, or to reset the given bus:target:lun or device
636(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after
637connecting to that device.
638Note that this can have a destructive impact
639on the system.
640.It Ic defects
641Send the
642.Tn SCSI
643READ DEFECT DATA (10) command (0x37) or the
644.Tn SCSI
645READ DEFECT DATA (12) command (0xB7) to the given device, and
646print out any combination of: the total number of defects, the primary
647defect list (PLIST), and the grown defect list (GLIST).
648.Bl -tag -width 11n
649.It Fl f Ar format
650Specify the requested format of the defect list.
651The format argument is
652required.
653Most drives support the physical sector format.
654Some drives
655support the logical block format.
656Many drives, if they do not support the
657requested format, return the data in an alternate format, along with sense
658information indicating that the requested data format is not supported.
659The
660.Nm
661utility
662attempts to detect this, and print out whatever format the drive returns.
663If the drive uses a non-standard sense code to report that it does not
664support the requested format,
665.Nm
666will probably see the error as a failure to complete the request.
667.Pp
668The format options are:
669.Bl -tag -width 9n
670.It block
671Print out the list as logical blocks.
672This is limited to 32-bit block sizes, and isn't supported by many modern
673drives.
674.It longblock
675Print out the list as logical blocks.
676This option uses a 64-bit block size.
677.It bfi
678Print out the list in bytes from index format.
679.It extbfi
680Print out the list in extended bytes from index format.
681The extended format allows for ranges of blocks to be printed.
682.It phys
683Print out the list in physical sector format.
684Most drives support this format.
685.It extphys
686Print out the list in extended physical sector format.
687The extended format allows for ranges of blocks to be printed.
688.El
689.It Fl G
690Print out the grown defect list.
691This is a list of bad blocks that have
692been remapped since the disk left the factory.
693.It Fl P
694Print out the primary defect list.
695This is the list of defects that were present in the factory.
696.It Fl q
697When printing status information with
698.Fl s ,
699only print the number of defects.
700.It Fl s
701Just print the number of defects, not the list of defects.
702.It Fl S Ar offset
703Specify the starting offset into the defect list.
704This implies using the
705.Tn SCSI
706READ DEFECT DATA (12) command, as the 10 byte version of the command
707doesn't support the address descriptor index field.
708Not all drives support the 12 byte command, and some drives that support
709the 12 byte command don't support the address descriptor index field.
710.It Fl X
711Print out defects in hexadecimal (base 16) form instead of base 10 form.
712.El
713.Pp
714If neither
715.Fl P
716nor
717.Fl G
718is specified,
719.Nm
720will print out the number of defects given in the READ DEFECT DATA header
721returned from the drive.
722Some drives will report 0 defects if neither the primary or grown defect
723lists are requested.
724.It Ic modepage
725Allows the user to display and optionally edit a SCSI mode page.
726The mode
727page formats are located in
728.Pa /usr/share/misc/scsi_modes .
729This can be overridden by specifying a different file in the
730.Ev SCSI_MODES
731environment variable.
732The
733.Ic modepage
734command takes several arguments:
735.Bl -tag -width 12n
736.It Fl 6
737Use 6 byte MODE commands instead of default 10 byte.
738Old devices may not support 10 byte MODE commands, while new devices may
739not be able to report all mode pages with 6 byte commands.
740If not specified,
741.Nm
742starts with 10 byte commands and falls back to 6 byte on error.
743.It Fl d
744Disable block descriptors for mode sense.
745.It Fl D
746Display/edit block descriptors instead of mode page.
747.It Fl L
748Use long LBA block descriptors.
749Allows number of LBAs bigger then 2^^32.
750.It Fl b
751Displays mode page data in binary format.
752.It Fl e
753This flag allows the user to edit values in the mode page.
754The user may
755either edit mode page values with the text editor pointed to by his
756.Ev EDITOR
757environment variable, or supply mode page values via standard input, using
758the same format that
759.Nm
760uses to display mode page values.
761The editor will be invoked if
762.Nm
763detects that standard input is terminal.
764.It Fl l
765Lists all available mode pages.
766If specified more then once, also lists subpages.
767.It Fl m Ar page[,subpage]
768This specifies the number of the mode page and optionally subpage the user
769would like to view and/or edit.
770This argument is mandatory unless
771.Fl l
772is specified.
773.It Fl P Ar pgctl
774This allows the user to specify the page control field.
775Possible values are:
776.Bl -tag -width xxx -compact
777.It 0
778Current values
779.It 1
780Changeable values
781.It 2
782Default values
783.It 3
784Saved values
785.El
786.El
787.It Ic cmd
788Allows the user to send an arbitrary ATA or SCSI CDB to any device.
789The
790.Ic cmd
791function requires the
792.Fl c
793argument to specify SCSI CDB or the
794.Fl a
795argument to specify ATA Command Block registers values.
796Other arguments are optional, depending on
797the command type.
798The command and data specification syntax is documented
799in
800.Xr cam_cdbparse 3 .
801NOTE: If the CDB specified causes data to be transferred to or from the
802SCSI device in question, you MUST specify either
803.Fl i
804or
805.Fl o .
806.Bl -tag -width 17n
807.It Fl a Ar cmd Op args
808This specifies the content of 12 ATA Command Block registers (command,
809features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp.
810lba_high_exp, features_exp, sector_count, sector_count_exp).
811.It Fl c Ar cmd Op args
812This specifies the SCSI CDB.
813SCSI CDBs may be 6, 10, 12 or 16 bytes.
814.It Fl d
815Specifies DMA protocol to be used for ATA command.
816.It Fl f
817Specifies FPDMA (NCQ) protocol to be used for ATA command.
818.It Fl i Ar len Ar fmt
819This specifies the amount of data to read, and how it should be displayed.
820If the format is
821.Sq - ,
822.Ar len
823bytes of data will be read from the device and written to standard output.
824.It Fl o Ar len Ar fmt Op args
825This specifies the amount of data to be written to a device, and the data
826that is to be written.
827If the format is
828.Sq - ,
829.Ar len
830bytes of data will be read from standard input and written to the device.
831.It Fl r Ar fmt
832This specifies that 11 result ATA Command Block registers should be displayed
833(status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp,
834lba_high_exp, sector_count, sector_count_exp), and how.
835If the format is
836.Sq - ,
83711 result registers will be written to standard output in hex.
838.El
839.It Ic smpcmd
840Allows the user to send an arbitrary Serial
841Management Protocol (SMP) command to a device.
842The
843.Ic smpcmd
844function requires the
845.Fl r
846argument to specify the SMP request to be sent, and the
847.Fl R
848argument to specify the format of the SMP response.
849The syntax for the SMP request and response arguments is documented in
850.Xr cam_cdbparse 3 .
851.Pp
852Note that SAS adapters that support SMP passthrough (at least the currently
853known adapters) do not accept CRC bytes from the user in the request and do
854not pass CRC bytes back to the user in the response.
855Therefore users should not include the CRC bytes in the length of the
856request and not expect CRC bytes to be returned in the response.
857.Bl -tag -width 17n
858.It Fl r Ar len Ar fmt Op args
859This specifies the size of the SMP request, without the CRC bytes, and the
860SMP request format.
861If the format is
862.Sq - ,
863.Ar len
864bytes of data will be read from standard input and written as the SMP
865request.
866.It Fl R Ar len Ar fmt Op args
867This specifies the size of the buffer allocated for the SMP response, and
868the SMP response format.
869If the format is
870.Sq - ,
871.Ar len
872bytes of data will be allocated for the response and the response will be
873written to standard output.
874.El
875.It Ic smprg
876Allows the user to send the Serial Management Protocol (SMP) Report General
877command to a device.
878.Nm
879will display the data returned by the Report General command.
880If the SMP target supports the long response format, the additional data
881will be requested and displayed automatically.
882.Bl -tag -width 8n
883.It Fl l
884Request the long response format only.
885Not all SMP targets support the long response format.
886This option causes
887.Nm
888to skip sending the initial report general request without the long bit set
889and only issue a report general request with the long bit set.
890.El
891.It Ic smppc
892Allows the user to issue the Serial Management Protocol (SMP) PHY Control
893command to a device.
894This function should be used with some caution, as it can render devices
895inaccessible, and could potentially cause data corruption as well.
896The
897.Fl p
898argument is required to specify the PHY to operate on.
899.Bl -tag -width 17n
900.It Fl p Ar phy
901Specify the PHY to operate on.
902This argument is required.
903.It Fl l
904Request the long request/response format.
905Not all SMP targets support the long response format.
906For the PHY Control command, this currently only affects whether the
907request length is set to a value other than 0.
908.It Fl o Ar operation
909Specify a PHY control operation.
910Only one
911.Fl o
912operation may be specified.
913The operation may be specified numerically (in decimal, hexadecimal, or octal)
914or one of the following operation names may be specified:
915.Bl -tag -width 16n
916.It nop
917No operation.
918It is not necessary to specify this argument.
919.It linkreset
920Send the LINK RESET command to the phy.
921.It hardreset
922Send the HARD RESET command to the phy.
923.It disable
924Send the DISABLE command to the phy.
925Note that the LINK RESET or HARD RESET commands should re-enable the phy.
926.It clearerrlog
927Send the CLEAR ERROR LOG command.
928This clears the error log counters for the specified phy.
929.It clearaffiliation
930Send the CLEAR AFFILIATION command.
931This clears the affiliation from the STP initiator port with the same SAS
932address as the SMP initiator that requests the clear operation.
933.It sataportsel
934Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy.
935This will cause a SATA port selector to use the given phy as its active phy
936and make the other phy inactive.
937.It clearitnl
938Send the CLEAR STP I_T NEXUS LOSS command to the PHY.
939.It setdevname
940Send the SET ATTACHED DEVICE NAME command to the PHY.
941This requires the
942.Fl d
943argument to specify the device name.
944.El
945.It Fl d Ar name
946Specify the attached device name.
947This option is needed with the
948.Fl o Ar setdevname
949phy operation.
950The name is a 64-bit number, and can be specified in decimal, hexadecimal
951or octal format.
952.It Fl m Ar rate
953Set the minimum physical link rate for the phy.
954This is a numeric argument.
955Currently known link rates are:
956.Bl -tag -width 5n
957.It 0x0
958Do not change current value.
959.It 0x8
9601.5 Gbps
961.It 0x9
9623 Gbps
963.It 0xa
9646 Gbps
965.El
966.Pp
967Other values may be specified for newer physical link rates.
968.It Fl M Ar rate
969Set the maximum physical link rate for the phy.
970This is a numeric argument.
971See the
972.Fl m
973argument description for known link rate arguments.
974.It Fl T Ar pp_timeout
975Set the partial pathway timeout value, in microseconds.
976See the
977.Tn ANSI
978.Tn SAS
979Protocol Layer (SPL)
980specification for more information on this field.
981.It Fl a Ar enable|disable
982Enable or disable SATA slumber phy power conditions.
983.It Fl A Ar enable|disable
984Enable or disable SATA partial power conditions.
985.It Fl s Ar enable|disable
986Enable or disable SAS slumber phy power conditions.
987.It Fl S Ar enable|disable
988Enable or disable SAS partial phy power conditions.
989.El
990.It Ic smpphylist
991List phys attached to a SAS expander, the address of the end device
992attached to the phy, and the inquiry data for that device and peripheral
993devices attached to that device.
994The inquiry data and peripheral devices are displayed if available.
995.Bl -tag -width 5n
996.It Fl l
997Turn on the long response format for the underlying SMP commands used for
998this command.
999.It Fl q
1000Only print out phys that are attached to a device in the CAM EDT (Existing
1001Device Table).
1002.El
1003.It Ic smpmaninfo
1004Send the SMP Report Manufacturer Information command to the device and
1005display the response.
1006.Bl -tag -width 5n
1007.It Fl l
1008Turn on the long response format for the underlying SMP commands used for
1009this command.
1010.El
1011.It Ic debug
1012Turn on CAM debugging printfs in the kernel.
1013This requires options CAMDEBUG
1014in your kernel config file.
1015WARNING: enabling debugging printfs currently
1016causes an EXTREME number of kernel printfs.
1017You may have difficulty
1018turning off the debugging printfs once they start, since the kernel will be
1019busy printing messages and unable to service other requests quickly.
1020The
1021.Ic debug
1022function takes a number of arguments:
1023.Bl -tag -width 18n
1024.It Fl I
1025Enable CAM_DEBUG_INFO printfs.
1026.It Fl P
1027Enable CAM_DEBUG_PERIPH printfs.
1028.It Fl T
1029Enable CAM_DEBUG_TRACE printfs.
1030.It Fl S
1031Enable CAM_DEBUG_SUBTRACE printfs.
1032.It Fl X
1033Enable CAM_DEBUG_XPT printfs.
1034.It Fl c
1035Enable CAM_DEBUG_CDB printfs.
1036This will cause the kernel to print out the
1037SCSI CDBs sent to the specified device(s).
1038.It Fl p
1039Enable CAM_DEBUG_PROBE printfs.
1040.It all
1041Enable debugging for all devices.
1042.It off
1043Turn off debugging for all devices
1044.It bus Ns Op :target Ns Op :lun
1045Turn on debugging for the given bus, target or lun.
1046If the lun or target
1047and lun are not specified, they are wildcarded.
1048(i.e., just specifying a
1049bus turns on debugging printfs for all devices on that bus.)
1050.El
1051.It Ic tags
1052Show or set the number of "tagged openings" or simultaneous transactions
1053we attempt to queue to a particular device.
1054By default, the
1055.Ic tags
1056command, with no command-specific arguments (i.e., only generic arguments)
1057prints out the "soft" maximum number of transactions that can be queued to
1058the device in question.
1059For more detailed information, use the
1060.Fl v
1061argument described below.
1062.Bl -tag -width 7n
1063.It Fl N Ar tags
1064Set the number of tags for the given device.
1065This must be between the
1066minimum and maximum number set in the kernel quirk table.
1067The default for
1068most devices that support tagged queueing is a minimum of 2 and a maximum
1069of 255.
1070The minimum and maximum values for a given device may be
1071determined by using the
1072.Fl v
1073switch.
1074The meaning of the
1075.Fl v
1076switch for this
1077.Nm
1078subcommand is described below.
1079.It Fl q
1080Be quiet, and do not report the number of tags.
1081This is generally used when
1082setting the number of tags.
1083.It Fl v
1084The verbose flag has special functionality for the
1085.Em tags
1086argument.
1087It causes
1088.Nm
1089to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB:
1090.Bl -tag -width 13n
1091.It dev_openings
1092This is the amount of capacity for transactions queued to a given device.
1093.It dev_active
1094This is the number of transactions currently queued to a device.
1095.It allocated
1096This is the number of CCBs allocated for the device.
1097.It held
1098The held count is the number of CCBs held by peripheral drivers that have
1099either just been completed or are about to be released to the transport
1100layer for service by a device.
1101Held CCBs reserve capacity on a given
1102device.
1103.It mintags
1104This is the current "hard" minimum number of transactions that can be
1105queued to a device at once.
1106The
1107.Ar dev_openings
1108value above cannot go below this number.
1109The default value for
1110.Ar mintags
1111is 2, although it may be set higher or lower for various devices.
1112.It maxtags
1113This is the "hard" maximum number of transactions that can be queued to a
1114device at one time.
1115The
1116.Ar dev_openings
1117value cannot go above this number.
1118The default value for
1119.Ar maxtags
1120is 255, although it may be set higher or lower for various devices.
1121.El
1122.El
1123.It Ic negotiate
1124Show or negotiate various communication parameters.
1125Some controllers may
1126not support setting or changing some of these values.
1127For instance, the
1128Adaptec 174x controllers do not support changing a device's sync rate or
1129offset.
1130The
1131.Nm
1132utility
1133will not attempt to set the parameter if the controller indicates that it
1134does not support setting the parameter.
1135To find out what the controller
1136supports, use the
1137.Fl v
1138flag.
1139The meaning of the
1140.Fl v
1141flag for the
1142.Ic negotiate
1143command is described below.
1144Also, some controller drivers do not support
1145setting negotiation parameters, even if the underlying controller supports
1146negotiation changes.
1147Some controllers, such as the Advansys wide
1148controllers, support enabling and disabling synchronous negotiation for
1149a device, but do not support setting the synchronous negotiation rate.
1150.Bl -tag -width 17n
1151.It Fl a
1152Attempt to make the negotiation settings take effect immediately by sending
1153a Test Unit Ready command to the device.
1154.It Fl c
1155Show or set current negotiation settings.
1156This is the default.
1157.It Fl D Ar enable|disable
1158Enable or disable disconnection.
1159.It Fl M Ar mode
1160Set ATA mode.
1161.It Fl O Ar offset
1162Set the command delay offset.
1163.It Fl q
1164Be quiet, do not print anything.
1165This is generally useful when you want to
1166set a parameter, but do not want any status information.
1167.It Fl R Ar syncrate
1168Change the synchronization rate for a device.
1169The sync rate is a floating
1170point value specified in MHz.
1171So, for instance,
1172.Sq 20.000
1173is a legal value, as is
1174.Sq 20 .
1175.It Fl T Ar enable|disable
1176Enable or disable tagged queueing for a device.
1177.It Fl U
1178Show or set user negotiation settings.
1179The default is to show or set
1180current negotiation settings.
1181.It Fl v
1182The verbose switch has special meaning for the
1183.Ic negotiate
1184subcommand.
1185It causes
1186.Nm
1187to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the
1188controller driver.
1189.It Fl W Ar bus_width
1190Specify the bus width to negotiate with a device.
1191The bus width is
1192specified in bits.
1193The only useful values to specify are 8, 16, and 32
1194bits.
1195The controller must support the bus width in question in order for
1196the setting to take effect.
1197.El
1198.Pp
1199In general, sync rate and offset settings will not take effect for a
1200device until a command has been sent to the device.
1201The
1202.Fl a
1203switch above will automatically send a Test Unit Ready to the device so
1204negotiation parameters will take effect.
1205.It Ic format
1206Issue the
1207.Tn SCSI
1208FORMAT UNIT command to the named device.
1209.Pp
1210.Em WARNING! WARNING! WARNING!
1211.Pp
1212Low level formatting a disk will destroy ALL data on the disk.
1213Use
1214extreme caution when issuing this command.
1215Many users low-level format
1216disks that do not really need to be low-level formatted.
1217There are
1218relatively few scenarios that call for low-level formatting a disk.
1219One reason for
1220low-level formatting a disk is to initialize the disk after changing
1221its physical sector size.
1222Another reason for low-level formatting a disk
1223is to revive the disk if you are getting "medium format corrupted" errors
1224from the disk in response to read and write requests.
1225.Pp
1226Some disks take longer than others to format.
1227Users should specify a
1228timeout long enough to allow the format to complete.
1229The default format
1230timeout is 3 hours, which should be long enough for most disks.
1231Some hard
1232disks will complete a format operation in a very short period of time
1233(on the order of 5 minutes or less).
1234This is often because the drive
1235does not really support the FORMAT UNIT command -- it just accepts the
1236command, waits a few minutes and then returns it.
1237.Pp
1238The
1239.Sq format
1240subcommand takes several arguments that modify its default behavior.
1241The
1242.Fl q
1243and
1244.Fl y
1245arguments can be useful for scripts.
1246.Bl -tag -width 6n
1247.It Fl q
1248Be quiet, do not print any status messages.
1249This option will not disable
1250the questions, however.
1251To disable questions, use the
1252.Fl y
1253argument, below.
1254.It Fl r
1255Run in
1256.Dq report only
1257mode.
1258This will report status on a format that is already running on the drive.
1259.It Fl w
1260Issue a non-immediate format command.
1261By default,
1262.Nm
1263issues the FORMAT UNIT command with the immediate bit set.
1264This tells the
1265device to immediately return the format command, before the format has
1266actually completed.
1267Then,
1268.Nm
1269gathers
1270.Tn SCSI
1271sense information from the device every second to determine how far along
1272in the format process it is.
1273If the
1274.Fl w
1275argument is specified,
1276.Nm
1277will issue a non-immediate format command, and will be unable to print any
1278information to let the user know what percentage of the disk has been
1279formatted.
1280.It Fl y
1281Do not ask any questions.
1282By default,
1283.Nm
1284will ask the user if he/she really wants to format the disk in question,
1285and also if the default format command timeout is acceptable.
1286The user
1287will not be asked about the timeout if a timeout is specified on the
1288command line.
1289.El
1290.It Ic sanitize
1291Issue the SANITIZE command to the named device.
1292.Pp
1293.Em WARNING! WARNING! WARNING!
1294.Pp
1295ALL data on the disk will be destroyed or made inaccessible.
1296Recovery of the data is not possible.
1297Use extreme caution when issuing this command.
1298.Pp
1299The
1300.Sq sanitize
1301subcommand takes several arguments that modify its default behavior.
1302The
1303.Fl q
1304and
1305.Fl y
1306arguments can be useful for scripts.
1307.Bl -tag -width 6n
1308.It Fl a Ar operation
1309Specify the sanitize operation to perform.
1310.Bl -tag -width 16n
1311.It overwrite
1312Perform an overwrite operation by writing a user supplied
1313data pattern to the device one or more times.
1314The pattern is given by the
1315.Fl P
1316argument.
1317The number of times is given by the
1318.Fl c
1319argument.
1320.It block
1321Perform a block erase operation.
1322All the device's blocks are set to a vendor defined
1323value, typically zero.
1324.It crypto
1325Perform a cryptographic erase operation.
1326The encryption keys are changed to prevent the decryption
1327of the data.
1328.It exitfailure
1329Exits a previously failed sanitize operation.
1330A failed sanitize operation can only be exited if it was
1331run in the unrestricted completion mode, as provided by the
1332.Fl U
1333argument.
1334.El
1335.It Fl c Ar passes
1336The number of passes when performing an
1337.Sq overwrite
1338operation.
1339Valid values are between 1 and 31.
1340The default is 1.
1341.It Fl I
1342When performing an
1343.Sq overwrite
1344operation, the pattern is inverted between consecutive passes.
1345.It Fl P Ar pattern
1346Path to the file containing the pattern to use when
1347performing an
1348.Sq overwrite
1349operation.
1350The pattern is repeated as needed to fill each block.
1351.It Fl q
1352Be quiet, do not print any status messages.
1353This option will not disable
1354the questions, however.
1355To disable questions, use the
1356.Fl y
1357argument, below.
1358.It Fl U
1359Perform the sanitize in the unrestricted completion mode.
1360If the operation fails, it can later be exited with the
1361.Sq exitfailure
1362operation.
1363.It Fl r
1364Run in
1365.Dq report only
1366mode.
1367This will report status on a sanitize that is already running on the drive.
1368.It Fl w
1369Issue a non-immediate sanitize command.
1370By default,
1371.Nm
1372issues the SANITIZE command with the immediate bit set.
1373This tells the
1374device to immediately return the sanitize command, before
1375the sanitize has actually completed.
1376Then,
1377.Nm
1378gathers
1379.Tn SCSI
1380sense information from the device every second to determine how far along
1381in the sanitize process it is.
1382If the
1383.Fl w
1384argument is specified,
1385.Nm
1386will issue a non-immediate sanitize command, and will be unable to print any
1387information to let the user know what percentage of the disk has been
1388sanitized.
1389.It Fl y
1390Do not ask any questions.
1391By default,
1392.Nm
1393will ask the user if he/she really wants to sanitize the disk in question,
1394and also if the default sanitize command timeout is acceptable.
1395The user
1396will not be asked about the timeout if a timeout is specified on the
1397command line.
1398.El
1399.It Ic idle
1400Put ATA device into IDLE state.
1401Optional parameter
1402.Pq Fl t
1403specifies automatic standby timer value in seconds.
1404Value 0 disables timer.
1405.It Ic standby
1406Put ATA device into STANDBY state.
1407Optional parameter
1408.Pq Fl t
1409specifies automatic standby timer value in seconds.
1410Value 0 disables timer.
1411.It Ic sleep
1412Put ATA device into SLEEP state.
1413Note that the only way get device out of
1414this state may be reset.
1415.It Ic powermode
1416Report ATA device power mode.
1417.It Ic apm
1418It optional parameter
1419.Pq Fl l
1420specified, enables and sets advanced power management level, where
14211 -- minimum power, 127 -- maximum performance with standby,
1422128 -- minimum power without standby, 254 -- maximum performance.
1423If not specified -- APM is disabled.
1424.It Ic aam
1425It optional parameter
1426.Pq Fl l
1427specified, enables and sets automatic acoustic management level, where
14281 -- minimum noise, 254 -- maximum performance.
1429If not specified -- AAM is disabled.
1430.It Ic security
1431Update or report security settings, using an ATA identify command (0xec).
1432By default,
1433.Nm
1434will print out the security support and associated settings of the device.
1435The
1436.Ic security
1437command takes several arguments:
1438.Bl -tag -width 0n
1439.It Fl d Ar pwd
1440.Pp
1441Disable device security using the given password for the selected user according
1442to the devices configured security level.
1443.It Fl e Ar pwd
1444.Pp
1445Erase the device using the given password for the selected user.
1446.Pp
1447.Em WARNING! WARNING! WARNING!
1448.Pp
1449Issuing a secure erase will
1450.Em ERASE ALL
1451user data on the device and may take several hours to complete.
1452.Pp
1453When this command is used against an SSD drive all its cells will be marked as
1454empty, restoring it to factory default write performance.
1455For SSD's this action
1456usually takes just a few seconds.
1457.It Fl f
1458.Pp
1459Freeze the security configuration of the specified device.
1460.Pp
1461After command completion any other commands that update the device lock mode
1462shall be command aborted.
1463Frozen mode is disabled by power-off or hardware reset.
1464.It Fl h Ar pwd
1465.Pp
1466Enhanced erase the device using the given password for the selected user.
1467.Pp
1468.Em WARNING! WARNING! WARNING!
1469.Pp
1470Issuing an enhanced secure erase will
1471.Em ERASE ALL
1472user data on the device and may take several hours to complete.
1473.Pp
1474An enhanced erase writes predetermined data patterns to all user data areas,
1475all previously written user data shall be overwritten, including sectors that
1476are no longer in use due to reallocation.
1477.It Fl k Ar pwd
1478.Pp
1479Unlock the device using the given password for the selected user according to
1480the devices configured security level.
1481.It Fl l Ar high|maximum
1482.Pp
1483Specifies which security level to set when issuing a
1484.Fl s Ar pwd
1485command.
1486The security level determines device behavior when the master
1487password is used to unlock the device.
1488When the security level is set to high
1489the device requires the unlock command and the master password to unlock.
1490When the security level is set to maximum the device requires a secure erase
1491with the master password to unlock.
1492.Pp
1493This option must be used in conjunction with one of the security action commands.
1494.Pp
1495Defaults to
1496.Em high
1497.It Fl q
1498.Pp
1499Be quiet, do not print any status messages.
1500This option will not disable the questions, however.
1501To disable questions, use the
1502.Fl y
1503argument, below.
1504.It Fl s Ar pwd
1505.Pp
1506Password the device (enable security) using the given password for the selected
1507user.
1508This option can be combined with other options such as
1509.Fl e Em pwd
1510.Pp
1511A master password may be set in a addition to the user password.
1512The purpose of the master password is to allow an administrator to establish
1513a password that is kept secret from the user, and which may be used to unlock
1514the device if the user password is lost.
1515.Pp
1516.Em Note:
1517Setting the master password does not enable device security.
1518.Pp
1519If the master password is set and the drive supports a Master Revision Code
1520feature the Master Password Revision Code will be decremented.
1521.It Fl T Ar timeout
1522.Pp
1523Overrides the default timeout, specified in seconds, used for both
1524.Fl e
1525and
1526.Fl h
1527this is useful if your system has problems processing long timeouts correctly.
1528.Pp
1529Usually the timeout is calculated from the information stored on the drive if
1530present, otherwise it defaults to 2 hours.
1531.It Fl U Ar user|master
1532.Pp
1533Specifies which user to set / use for the running action command, valid values
1534are user or master and defaults to master if not set.
1535.Pp
1536This option must be used in conjunction with one of the security action commands.
1537.Pp
1538Defaults to
1539.Em master
1540.It Fl y
1541.Pp
1542Confirm yes to dangerous options such as
1543.Fl e
1544without prompting for confirmation.
1545.El
1546.Pp
1547If the password specified for any action commands does not match the configured
1548password for the specified user the command will fail.
1549.Pp
1550The password in all cases is limited to 32 characters, longer passwords will
1551fail.
1552.It Ic hpa
1553Update or report Host Protected Area details.
1554By default
1555.Nm
1556will print out the HPA support and associated settings of the device.
1557The
1558.Ic hpa
1559command takes several optional arguments:
1560.Bl -tag -width 0n
1561.It Fl f
1562.Pp
1563Freeze the HPA configuration of the specified device.
1564.Pp
1565After command completion any other commands that update the HPA configuration
1566shall be command aborted.
1567Frozen mode is disabled by power-off or hardware reset.
1568.It Fl l
1569.Pp
1570Lock the HPA configuration of the device until a successful call to unlock or
1571the next power-on reset occurs.
1572.It Fl P
1573.Pp
1574Make the HPA max sectors persist across power-on reset or a hardware reset.
1575This must be used in combination with
1576.Fl s Ar max_sectors
1577.
1578.It Fl p Ar pwd
1579.Pp
1580Set the HPA configuration password required for unlock calls.
1581.It Fl q
1582.Pp
1583Be quiet, do not print any status messages.
1584This option will not disable the questions.
1585To disable questions, use the
1586.Fl y
1587argument, below.
1588.It Fl s Ar max_sectors
1589.Pp
1590Configures the maximum user accessible sectors of the device.
1591This will change the number of sectors the device reports.
1592.Pp
1593.Em WARNING! WARNING! WARNING!
1594.Pp
1595Changing the max sectors of a device using this option will make the data on
1596the device beyond the specified value inaccessible.
1597.Pp
1598Only one successful
1599.Fl s Ar max_sectors
1600call can be made without a power-on reset or a hardware reset of the device.
1601.It Fl U Ar pwd
1602.Pp
1603Unlock the HPA configuration of the specified device using the given password.
1604If the password specified does not match the password configured via
1605.Fl p Ar pwd
1606the command will fail.
1607.Pp
1608After 5 failed unlock calls, due to password miss-match, the device will refuse
1609additional unlock calls until after a power-on reset.
1610.It Fl y
1611.Pp
1612Confirm yes to dangerous options such as
1613.Fl e
1614without prompting for confirmation
1615.El
1616.Pp
1617The password for all HPA commands is limited to 32 characters, longer passwords
1618will fail.
1619.It Ic ama
1620Update or report Accessible Max Address Configuration.
1621By default
1622.Nm
1623will print out the Accessible Max Address Configuration support and associated
1624settings of the device.
1625The
1626.Ic ama
1627command takes several optional arguments:
1628.Bl -tag -width 0n
1629.It Fl f
1630.Pp
1631Freeze the Accessible Max Address Configuration of the specified device.
1632.Pp
1633After command completion any other commands that update the configuration
1634shall be command aborted.
1635Frozen mode is disabled by power-off.
1636.It Fl q
1637.Pp
1638Be quiet, do not print any status messages.
1639.It Fl s Ar max_sectors
1640.Pp
1641Configures the maximum user accessible sectors of the device.
1642This will change the number of sectors the device reports.
1643.Pp
1644.Em WARNING! WARNING! WARNING!
1645.Pp
1646Changing the max sectors of a device using this option will make the data on
1647the device beyond the specified value indeterminate.
1648.Pp
1649Only one successful
1650.Fl s Ar max_sectors
1651call can be made without a power-on reset of the device.
1652.El
1653.It Ic fwdownload
1654Program firmware of the named
1655.Tn SCSI
1656or ATA device using the image file provided.
1657.Pp
1658If the device is a
1659.Tn SCSI
1660device and it provides a recommended timeout for the WRITE BUFFER command
1661(see the
1662.Nm
1663opcodes subcommand), that timeout will be used for the firmware download.
1664The drive-recommended timeout value may be overridden on the command line
1665with the
1666.Fl t
1667option.
1668.Pp
1669Current list of supported vendors for SCSI/SAS drives:
1670.Bl -tag -width 10n
1671.It HGST
1672Tested with 4TB SAS drives, model number HUS724040ALS640.
1673.It HITACHI
1674.It HP
1675.It IBM
1676Tested with LTO-5 (ULTRIUM-HH5) and LTO-6 (ULTRIUM-HH6) tape drives.
1677There is a separate table entry for hard drives, because the update method
1678for hard drives is different than the method for tape drives.
1679.It PLEXTOR
1680.It QUALSTAR
1681.It QUANTUM
1682.It SAMSUNG
1683Tested with SM1625 SSDs.
1684.It SEAGATE
1685Tested with Constellation ES (ST32000444SS), ES.2 (ST33000651SS) and
1686ES.3 (ST1000NM0023) drives.
1687.It SmrtStor
1688Tested with 400GB Optimus SSDs (TXA2D20400GA6001).
1689.El
1690.Pp
1691.Em WARNING! WARNING! WARNING!
1692.Pp
1693Little testing has been done to make sure that different device models from
1694each vendor work correctly with the fwdownload command.
1695A vendor name appearing in the supported list means only that firmware of at
1696least one device type from that vendor has successfully been programmed with
1697the fwdownload command.
1698Extra caution should be taken when using this command since there is no
1699guarantee it will not break a device from the listed vendors.
1700Ensure that you have a recent backup of the data on the device before
1701performing a firmware update.
1702.Pp
1703Note that unknown
1704.Tn SCSI
1705protocol devices will not be programmed, since there is little chance of
1706the firmware download succeeding.
1707.Pp
1708.Nm
1709will currently attempt a firmware download to any
1710.Tn ATA
1711or
1712.Tn SATA
1713device, since the standard
1714.Tn ATA
1715DOWNLOAD MICROCODE command may work.
1716Firmware downloads to
1717.Tn ATA
1718and
1719.Tn SATA
1720devices are supported for devices connected
1721to standard
1722.Tn ATA
1723and
1724.Tn SATA
1725controllers, and devices connected to SAS controllers
1726with
1727.Tn SCSI
1728to
1729.Tn ATA
1730translation capability.
1731In the latter case,
1732.Nm
1733uses the
1734.Tn SCSI
1735.Tn ATA
1736PASS-THROUGH command to send the
1737.Tn ATA
1738DOWNLOAD MICROCODE command to the drive.
1739Some
1740.Tn SCSI
1741to
1742.Tn ATA
1743translation implementations don't work fully when translating
1744.Tn SCSI
1745WRITE BUFFER commands to
1746.Tn ATA
1747DOWNLOAD MICROCODE commands, but do support
1748.Tn ATA
1749passthrough well enough to do a firmware download.
1750.Bl -tag -width 11n
1751.It Fl f Ar fw_image
1752Path to the firmware image file to be downloaded to the specified device.
1753.It Fl q
1754Do not print informational messages, only print errors.
1755This option should be used with the
1756.Fl y
1757option to suppress all output.
1758.It Fl s
1759Run in simulation mode.
1760Device checks are run and the confirmation dialog is shown, but no firmware
1761download will occur.
1762.It Fl v
1763Show
1764.Tn SCSI
1765or
1766.Tn ATA
1767errors in the event of a failure.
1768.Pp
1769In simulation mode, print out the
1770.Tn SCSI
1771CDB
1772or
1773.Tn ATA
1774register values that would be used for the firmware download command.
1775.It Fl y
1776Do not ask for confirmation.
1777.El
1778.It Ic persist
1779Persistent reservation support.
1780Persistent reservations are a way to reserve a particular
1781.Tn SCSI
1782LUN for use by one or more
1783.Tn SCSI
1784initiators.
1785If the
1786.Fl i
1787option is specified,
1788.Nm
1789will issue the
1790.Tn SCSI
1791PERSISTENT RESERVE IN
1792command using the requested service action.
1793If the
1794.Fl o
1795option is specified,
1796.Nm
1797will issue the
1798.Tn SCSI
1799PERSISTENT RESERVE OUT
1800command using the requested service action.
1801One of those two options is required.
1802.Pp
1803Persistent reservations are complex, and fully explaining them is outside
1804the scope of this manual.
1805Please visit
1806http://www.t10.org
1807and download the latest SPC spec for a full explanation of persistent
1808reservations.
1809.Bl -tag -width 8n
1810.It Fl i Ar mode
1811Specify the service action for the PERSISTENT RESERVE IN command.
1812Supported service actions:
1813.Bl -tag -width 19n
1814.It read_keys
1815Report the current persistent reservation generation (PRgeneration) and any
1816registered keys.
1817.It read_reservation
1818Report the persistent reservation, if any.
1819.It report_capabilities
1820Report the persistent reservation capabilities of the LUN.
1821.It read_full_status
1822Report the full status of persistent reservations on the LUN.
1823.El
1824.It Fl o Ar mode
1825Specify the service action for the PERSISTENT RESERVE OUT command.
1826For service actions like register that are components of other service
1827action names, the entire name must be specified.
1828Otherwise, enough of the service action name must be specified to
1829distinguish it from other possible service actions.
1830Supported service actions:
1831.Bl -tag -width 15n
1832.It register
1833Register a reservation key with the LUN or unregister a reservation key.
1834To register a key, specify the requested key as the Service Action
1835Reservation Key.
1836To unregister a key, specify the previously registered key as the
1837Reservation Key.
1838To change a key, specify the old key as the Reservation Key and the new
1839key as the Service Action Reservation Key.
1840.It register_ignore
1841This is similar to the register subcommand, except that the Reservation Key
1842is ignored.
1843The Service Action Reservation Key will overwrite any previous key
1844registered for the initiator.
1845.It reserve
1846Create a reservation.
1847A key must be registered with the LUN before the LUN can be reserved, and
1848it must be specified as the Reservation Key.
1849The type of reservation must also be specified.
1850The scope defaults to LUN scope (LU_SCOPE), but may be changed.
1851.It release
1852Release a reservation.
1853The Reservation Key must be specified.
1854.It clear
1855Release a reservation and remove all keys from the device.
1856The Reservation Key must be specified.
1857.It preempt
1858Remove a reservation belonging to another initiator.
1859The Reservation Key must be specified.
1860The Service Action Reservation Key may be specified, depending on the
1861operation being performed.
1862.It preempt_abort
1863Remove a reservation belonging to another initiator and abort all
1864outstanding commands from that initiator.
1865The Reservation Key must be specified.
1866The Service Action Reservation Key may be specified, depending on the
1867operation being performed.
1868.It register_move
1869Register another initiator with the LUN, and establish a reservation on the
1870LUN for that initiator.
1871The Reservation Key and Service Action Reservation Key must be specified.
1872.It replace_lost
1873Replace Lost Reservation information.
1874.El
1875.It Fl a
1876Set the All Target Ports (ALL_TG_PT) bit.
1877This requests that the key registration be applied to all target ports and
1878not just the particular target port that receives the command.
1879This only applies to the register and register_ignore actions.
1880.It Fl I Ar tid
1881Specify a Transport ID.
1882This only applies to the Register and Register and Move service actions for
1883Persistent Reserve Out.
1884Multiple Transport IDs may be specified with multiple
1885.Fl I
1886arguments.
1887With the Register service action, specifying one or more Transport IDs
1888implicitly enables the
1889.Fl S
1890option which turns on the SPEC_I_PT bit.
1891Transport IDs generally have the format protocol,id.
1892.Bl -tag -width 5n
1893.It SAS
1894A SAS Transport ID consists of
1895.Dq sas,
1896followed by a 64-bit SAS address.
1897For example:
1898.Pp
1899.Dl sas,0x1234567812345678
1900.It FC
1901A Fibre Channel Transport ID consists of
1902.Dq fcp,
1903followed by a 64-bit Fibre Channel World Wide Name.
1904For example:
1905.Pp
1906.Dl fcp,0x1234567812345678
1907.It SPI
1908A Parallel SCSI address consists of
1909.Dq spi,
1910followed by a SCSI target ID and a relative target port identifier.
1911For example:
1912.Pp
1913.Dl spi,4,1
1914.It 1394
1915An IEEE 1394 (Firewire) Transport ID consists of
1916.Dq sbp,
1917followed by a 64-bit EUI-64 IEEE 1394 node unique identifier.
1918For example:
1919.Pp
1920.Dl sbp,0x1234567812345678
1921.It RDMA
1922A SCSI over RDMA Transport ID consists of
1923.Dq srp,
1924followed by a 128-bit RDMA initiator port identifier.
1925The port identifier must be exactly 32 or 34 (if the leading 0x is
1926included) hexadecimal digits.
1927Only hexadecimal (base 16) numbers are supported.
1928For example:
1929.Pp
1930.Dl srp,0x12345678123456781234567812345678
1931.It iSCSI
1932An iSCSI Transport ID consists an iSCSI name and optionally a separator and
1933iSCSI session ID.
1934For example, if only the iSCSI name is specified:
1935.Pp
1936.Dl iqn.2012-06.com.example:target0
1937.Pp
1938If the iSCSI separator and initiator session ID are specified:
1939.Pp
1940.Dl iqn.2012-06.com.example:target0,i,0x123
1941.It PCIe
1942A SCSI over PCIe Transport ID consists of
1943.Dq sop,
1944followed by a PCIe Routing ID.
1945The Routing ID consists of a bus, device and function or in the alternate
1946form, a bus and function.
1947The bus must be in the range of 0 to 255 inclusive and the device must be
1948in the range of 0 to 31 inclusive.
1949The function must be in the range of 0 to 7 inclusive if the standard form
1950is used, and in the range of 0 to 255 inclusive if the alternate form is
1951used.
1952For example, if a bus, device and function are specified for the standard
1953Routing ID form:
1954.Pp
1955.Dl sop,4,5,1
1956.Pp
1957If the alternate Routing ID form is used:
1958.Pp
1959.Dl sop,4,1
1960.El
1961.It Fl k Ar key
1962Specify the Reservation Key.
1963This may be in decimal, octal or hexadecimal format.
1964The value is zero by default if not otherwise specified.
1965The value must be between 0 and 2^64 - 1, inclusive.
1966.It Fl K Ar key
1967Specify the Service Action Reservation Key.
1968This may be in decimal, octal or hexadecimal format.
1969The value is zero by default if not otherwise specified.
1970The value must be between 0 and 2^64 - 1, inclusive.
1971.It Fl p
1972Enable the Activate Persist Through Power Loss bit.
1973This is only used for the register and register_ignore actions.
1974This requests that the reservation persist across power loss events.
1975.It Fl s Ar scope
1976Specify the scope of the reservation.
1977The scope may be specified by name or by number.
1978The scope is ignored for register, register_ignore and clear.
1979If the desired scope isn't available by name, you may specify the number.
1980.Bl -tag -width 7n
1981.It lun
1982LUN scope (0x00).
1983This encompasses the entire LUN.
1984.It extent
1985Extent scope (0x01).
1986.It element
1987Element scope (0x02).
1988.El
1989.It Fl R Ar rtp
1990Specify the Relative Target Port.
1991This only applies to the Register and Move service action of the Persistent
1992Reserve Out command.
1993.It Fl S
1994Enable the SPEC_I_PT bit.
1995This only applies to the Register service action of Persistent Reserve Out.
1996You must also specify at least one Transport ID with
1997.Fl I
1998if this option is set.
1999If you specify a Transport ID, this option is automatically set.
2000It is an error to specify this option for any service action other than
2001Register.
2002.It Fl T Ar type
2003Specify the reservation type.
2004The reservation type may be specified by name or by number.
2005If the desired reservation type isn't available by name, you may specify
2006the number.
2007Supported reservation type names:
2008.Bl -tag -width 11n
2009.It read_shared
2010Read Shared mode.
2011.It wr_ex
2012Write Exclusive mode.
2013May also be specified as
2014.Dq write_exclusive .
2015.It rd_ex
2016Read Exclusive mode.
2017May also be specified as
2018.Dq read_exclusive .
2019.It ex_ac
2020Exclusive access mode.
2021May also be specified as
2022.Dq exclusive_access .
2023.It wr_ex_ro
2024Write Exclusive Registrants Only mode.
2025May also be specified as
2026.Dq write_exclusive_reg_only .
2027.It ex_ac_ro
2028Exclusive Access Registrants Only mode.
2029May also be specified as
2030.Dq exclusive_access_reg_only .
2031.It wr_ex_ar
2032Write Exclusive All Registrants mode.
2033May also be specified as
2034.Dq write_exclusive_all_regs .
2035.It ex_ac_ar
2036Exclusive Access All Registrants mode.
2037May also be specified as
2038.Dq exclusive_access_all_regs .
2039.El
2040.It Fl U
2041Specify that the target should unregister the initiator that sent
2042the Register and Move request.
2043By default, the target will not unregister the initiator that sends the
2044Register and Move request.
2045This option only applies to the Register and Move service action of the
2046Persistent Reserve Out command.
2047.El
2048.It Ic attrib
2049Issue the
2050.Tn SCSI
2051READ or WRITE ATTRIBUTE commands.
2052These commands are used to read and write attributes in Medium Auxiliary
2053Memory (MAM).
2054The most common place Medium Auxiliary Memory is found is small flash chips
2055included tape cartriges.
2056For instance,
2057.Tn LTO
2058tapes have MAM.
2059Either the
2060.Fl r
2061option or the
2062.Fl w
2063option must be specified.
2064.Bl -tag -width 14n
2065.It Fl r Ar action
2066Specify the READ ATTRIBUTE service action.
2067.Bl -tag -width 11n
2068.It attr_values
2069Issue the ATTRIBUTE VALUES service action.
2070Read and decode the available attributes and their values.
2071.It attr_list
2072Issue the ATTRIBUTE LIST service action.
2073List the attributes that are available to read and write.
2074.It lv_list
2075Issue the LOGICAL VOLUME LIST service action.
2076List the available logical volumes in the MAM.
2077.It part_list
2078Issue the PARTITION LIST service action.
2079List the available partitions in the MAM.
2080.It supp_attr
2081Issue the SUPPORTED ATTRIBUTES service action.
2082List attributes that are supported for reading or writing.
2083These attributes may or may not be currently present in the MAM.
2084.El
2085.It Fl w Ar attr
2086Specify an attribute to write to the MAM.
2087This option is not yet implemented.
2088.It Fl a Ar num
2089Specify the attribute number to display.
2090This option only works with the attr_values, attr_list and supp_attr
2091arguments to
2092.Fl r .
2093.It Fl c
2094Display cached attributes.
2095If the device supports this flag, it allows displaying attributes for the
2096last piece of media loaded in the drive.
2097.It Fl e Ar num
2098Specify the element address.
2099This is used for specifying which element number in a medium changer to
2100access when reading attributes.
2101The element number could be for a picker, portal, slot or drive.
2102.It Fl F Ar form1,form2
2103Specify the output format for the attribute values (attr_val) display as a
2104comma separated list of options.
2105The default output is currently set to field_all,nonascii_trim,text_raw.
2106Once this code is ported to FreeBSD 10, any text fields will be converted
2107from their codeset to the user's native codeset with
2108.Xr iconv 3 .
2109.Pp
2110The text options are mutually exclusive; if you specify more than one, you
2111will get unpredictable results.
2112The nonascii options are also mutually exclusive.
2113Most of the field options may be logically ORed together.
2114.Bl -tag -width 12n
2115.It text_esc
2116Print text fields with non-ASCII characters escaped.
2117.It text_raw
2118Print text fields natively, with no codeset conversion.
2119.It nonascii_esc
2120If any non-ASCII characters occur in fields that are supposed to be ASCII,
2121escape the non-ASCII characters.
2122.It nonascii_trim
2123If any non-ASCII characters occur in fields that are supposed to be ASCII,
2124omit the non-ASCII characters.
2125.It nonascii_raw
2126If any non-ASCII characters occur in fields that are supposed to be ASCII,
2127print them as they are.
2128.It field_all
2129Print all of the prefix fields: description, attribute number, attribute
2130size, and the attribute's readonly status.
2131If field_all is specified, specifying any other field options will not have
2132an effect.
2133.It field_none
2134Print none of the prefix fields, and only print out the attribute value.
2135If field_none is specified, specifying any other field options will result
2136in those fields being printed.
2137.It field_desc
2138Print out the attribute description.
2139.It field_num
2140Print out the attribute number.
2141.It field_size
2142Print out the attribute size.
2143.It field_rw
2144Print out the attribute's readonly status.
2145.El
2146.It Fl p Ar part
2147Specify the partition.
2148When the media has multiple partitions, specifying different partition
2149numbers allows seeing the values for each individual partition.
2150.It Fl s Ar start_num
2151Specify the starting attribute number.
2152This requests that the target device return attribute information starting
2153at the given number.
2154.It Fl T Ar elem_type
2155Specify the element type.
2156For medium changer devices, this allows specifying the type the element
2157referenced in the element address (
2158.Fl e ) .
2159Valid types are:
2160.Dq all ,
2161.Dq picker ,
2162.Dq slot ,
2163.Dq portal ,
2164and
2165.Dq drive .
2166.It Fl V Ar vol_num
2167Specify the number of the logical volume to operate on.
2168If the media has multiple logical volumes, this will allow displaying
2169or writing attributes on the given logical volume.
2170.El
2171.It Ic opcodes
2172Issue the REPORT SUPPORTED OPCODES service action of the
2173.Tn SCSI
2174MAINTENANCE IN
2175command.
2176Without arguments, this command will return a list of all
2177.Tn SCSI
2178commands supported by the device, including service actions of commands
2179that support service actions.
2180It will also include the
2181.Tn SCSI
2182CDB (Command Data Block) length for each command, and the description of
2183each command if it is known.
2184.Bl -tag -width 18n
2185.It Fl o Ar opcode
2186Request information on a specific opcode instead of the list of supported
2187commands.
2188If supported, the target will return a CDB-like structure that indicates
2189the opcode, service action (if any), and a mask of bits that are supported
2190in that CDB.
2191.It Fl s Ar service_action
2192For commands that support a service action, specify the service action to
2193query.
2194.It Fl N
2195If a service action is specified for a given opcode, and the device does
2196not support the given service action, the device should not return a
2197.Tn SCSI
2198error, but rather indicate in the returned parameter data that the command
2199is not supported.
2200By default, if a service action is specified for an opcode, and service
2201actions are not supported for the opcode in question, the device will
2202return an error.
2203.It Fl T
2204Include timeout values.
2205This option works with the default display, which includes all commands
2206supported by the device, and with the
2207.Fl o
2208and
2209.Fl s
2210options, which request information on a specific command and service
2211action.
2212This requests that the device report Nominal and Recommended timeout values
2213for the given command or commands.
2214The timeout values are in seconds.
2215The timeout descriptor also includes a command-specific
2216.El
2217.It Ic zone
2218Manage
2219.Tn SCSI
2220and
2221.Tn ATA
2222Zoned Block devices.
2223This allows managing devices that conform to the
2224.Tn SCSI
2225Zoned Block Commands (ZBC) and
2226.Tn ATA
2227Zoned ATA Command Set (ZAC)
2228specifications.
2229Devices using these command sets are usually hard drives using Shingled
2230Magnetic Recording (SMR).
2231There are three types of SMR drives:
2232.Bl -tag -width 13n
2233.It Drive Managed
2234Drive Managed drives look and act just like a standard random access block
2235device, but underneath, the drive reads and writes the bulk of its capacity
2236using SMR zones.
2237Sequential writes will yield better performance, but writing sequentially
2238is not required.
2239.It Host Aware
2240Host Aware drives expose the underlying zone layout via
2241.Tn SCSI
2242or
2243.Tn ATA
2244commands and allow the host to manage the zone conditions.
2245The host is not required to manage the zones on the drive, though.
2246Sequential writes will yield better performance in Sequential Write
2247Preferred zones, but the host can write randomly in those zones.
2248.It Host Managed
2249Host Managed drives expose the underlying zone layout via
2250.Tn SCSI
2251or
2252.Tn ATA
2253commands.
2254The host is required to access the zones according to the rules described
2255by the zone layout.
2256Any commands that violate the rules will be returned with an error.
2257.El
2258.Pp
2259SMR drives are divided into zones (typically in the range of 256MB each)
2260that fall into three general categories:
2261.Bl -tag -width 20n
2262.It Conventional
2263These are also known as Non Write Pointer zones.
2264These zones can be randomly written without an unexpected performance penalty.
2265.It Sequential Preferred
2266These zones should be written sequentially starting at the write pointer
2267for the zone.
2268They may be written randomly.
2269Writes that do not conform to the zone layout may be significantly slower
2270than expected.
2271.It Sequential Required
2272These zones must be written sequentially.
2273If they are not written sequentially, starting at the write pointer, the
2274command will fail.
2275.El
2276.Bl -tag -width 12n
2277.It Fl c Ar cmd
2278Specify the zone subcommand:
2279.Bl -tag -width 6n
2280.It rz
2281Issue the Report Zones command.
2282All zones are returned by default.
2283Specify report options with
2284.Fl o
2285and printing options with
2286.Fl P .
2287Specify the starting LBA with
2288.Fl l .
2289Note that
2290.Dq reportzones
2291is also accepted as a command argument.
2292.It open
2293Explicitly open the zone specified by the starting LBA.
2294.It close
2295Close the zone specified by starting LBA.
2296.It finish
2297Finish the zone specified by the starting LBA.
2298.It rwp
2299Reset the write pointer for the zone specified by the starting LBA.
2300.El
2301.It Fl a
2302For the Open, Close, Finish, and Reset Write Pointer operations, apply the
2303operation to all zones on the drive.
2304.It Fl l Ar lba
2305Specify the starting LBA.
2306For the Report Zones command, this tells the drive to report starting with
2307the zone that starts at the given LBA.
2308For the other commands, this allows the user to identify the zone requested
2309by its starting LBA.
2310The LBA may be specified in decimal, hexadecimal or octal notation.
2311.It Fl o Ar rep_opt
2312For the Report Zones command, specify a subset of zones to report.
2313.Bl -tag -width 8n
2314.It all
2315Report all zones.
2316This is the default.
2317.It emtpy
2318Report only empty zones.
2319.It imp_open
2320Report zones that are implicitly open.
2321This means that the host has sent a write to the zone without explicitly
2322opening the zone.
2323.It exp_open
2324Report zones that are explicitly open.
2325.It closed
2326Report zones that have been closed by the host.
2327.It full
2328Report zones that are full.
2329.It ro
2330Report zones that are in the read only state.
2331Note that
2332.Dq readonly
2333is also accepted as an argument.
2334.It offline
2335Report zones that are in the offline state.
2336.It reset
2337Report zones where the device recommends resetting write pointers.
2338.It nonseq
2339Report zones that have the Non Sequential Resources Active flag set.
2340These are zones that are Sequential Write Preferred, but have been written
2341non-sequentially.
2342.It nonwp
2343Report Non Write Pointer zones, also known as Conventional zones.
2344.El
2345.It Fl P Ar print_opt
2346Specify a printing option for Report Zones:
2347.Bl -tag -width 7n
2348.It normal
2349Normal Report Zones output.
2350This is the default.
2351The summary and column headings are printed, fields are separated by spaces
2352and the fields themselves may contain spaces.
2353.It summary
2354Just print the summary:  the number of zones, the maximum LBA (LBA of the
2355last logical block on the drive), and the value of the
2356.Dq same
2357field.
2358The
2359.Dq same
2360field describes whether the zones on the drive are all identical, all
2361different, or whether they are the same except for the last zone, etc.
2362.It script
2363Print the zones in a script friendly format.
2364The summary and column headings are omitted, the fields are separated by
2365commas, and the fields do not contain spaces.
2366The fields contain underscores where spaces would normally be used.
2367.El
2368.El
2369.It Ic epc
2370Issue
2371.Tn ATA
2372Extended Power Conditions (EPC) feature set commands.
2373This only works on
2374.Tn ATA
2375protocol drives, and will not work on
2376.Tn SCSI
2377protocol drives.
2378It will work on
2379.Tn SATA
2380drives behind a
2381.Tn SCSI
2382to
2383.Tn ATA
2384translation layer (SAT).
2385It may be helpful to read the ATA Command Set - 4 (ACS-4) description of
2386the Extended Power Conditions feature set, available at t13.org, to
2387understand the details of this particular
2388.Nm
2389subcommand.
2390.Bl -tag -width 6n
2391.It Fl c Ar cmd
2392Specify the epc subcommand
2393.Bl -tag -width 7n
2394.It restore
2395Restore drive power condition settings.
2396.Bl -tag -width 6n
2397.It Fl r Ar src
2398Specify the source for the restored power settings, either
2399.Dq default
2400or
2401.Dq saved .
2402This argument is required.
2403.It Fl s
2404Save the settings.
2405This only makes sense to specify when restoring from defaults.
2406.El
2407.It goto
2408Go to the specified power condition.
2409.Bl -tag -width 7n
2410.It Fl p Ar cond
2411Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z.
2412This argument is required.
2413.It Fl D
2414Specify delayed entry to the power condition.
2415The drive, if it supports this, can enter the power condition after the
2416command completes.
2417.It Fl H
2418Hold the power condition.
2419If the drive supports this option, it will hold the power condition and
2420reject all commands that would normally cause it to exit that power
2421condition.
2422.El
2423.It timer
2424Set the timer value for a power condition and enable or disable the
2425condition.
2426See the
2427.Dq list
2428display described below to see what the current timer settings are for each
2429Idle and Standby mode supported by the drive.
2430.Bl -tag -width 8n
2431.It Fl e
2432Enable the power condition.
2433One of
2434.Fl e
2435or
2436.Fl d
2437is required.
2438.It Fl d
2439Disable the power condition.
2440One of
2441.Fl d
2442or
2443.Fl e
2444is required.
2445.It Fl T Ar timer
2446Specify the timer in seconds.
2447The user may specify a timer as a floating point number with a maximum
2448supported resolution of tenths of a second.
2449Drives may or may not support sub-second timer values.
2450.It Fl p Ar cond
2451Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z.
2452This argument is required.
2453.It Fl s
2454Save the timer and power condition enable/disable state.
2455By default, if this option is not specified, only the current values for
2456this power condition will be affected.
2457.El
2458.It state
2459Enable or disable a particular power condition.
2460.Bl -tag -width 7n
2461.It Fl e
2462Enable the power condition.
2463One of
2464.Fl e
2465or
2466.Fl d
2467is required.
2468.It Fl d
2469Disable the power condition.
2470One of
2471.Fl d
2472or
2473.Fl e
2474is required.
2475.It Fl p Ar cond
2476Specify the power condition: Idle_a, Idle_b, Idle_c, Standby_y, Standby_z.
2477This argument is required.
2478.It Fl s
2479Save the power condition enable/disable state.
2480By default, if this option is not specified, only the current values for
2481this power condition will be affected.
2482.El
2483.It enable
2484Enable the Extended Power Condition (EPC) feature set.
2485.It disable
2486Disable the Extended Power Condition (EPC) feature set.
2487.It source
2488Specify the EPC power source.
2489.Bl -tag -width 6n
2490.It Fl S Ar src
2491Specify the power source, either
2492.Dq battery
2493or
2494.Dq nonbattery .
2495.El
2496.It status
2497Get the current status of several parameters related to the Extended Power
2498Condition (EPC) feature set, including whether APM and EPC are supported
2499and enabled, whether Low Power Standby is supported, whether setting the
2500EPC power source is supported, whether Low Power Standby is supported and
2501the current power condition.
2502.Bl -tag -width 3n
2503.It Fl P
2504Only report the current power condition.
2505Some drives will exit their current power condition if a command other than
2506the
2507.Tn ATA
2508CHECK POWER MODE command is received.
2509If this flag is specified,
2510.Nm
2511will only issue the
2512.Tn ATA
2513CHECK POWER MODE command to the drive.
2514.El
2515.It list
2516Display the
2517.Tn ATA
2518Power Conditions log (Log Address 0x08).
2519This shows the list of Idle and Standby power conditions the drive
2520supports, and a number of parameters about each condition, including
2521whether it is enabled and what the timer value is.
2522.El
2523.El
2524.It Ic timestamp
2525Issue REPORT TIMESTAMP or SET TIMESTAMP
2526.Tn SCSI
2527commands.
2528Either the
2529.Fl r
2530option or the
2531.Fl s
2532option must be specified.
2533.Bl -tag -width 6n
2534.It Fl r
2535Report the device's timestamp.
2536If no more arguments are specified, the timestamp will be reported using
2537the national representation of the date and time, followed by the time
2538zone.
2539.Bl -tag -width 9n
2540.It Fl f Ar format
2541Specify the strftime format string, as documented in strftime(3), to be used
2542to format the reported timestamp.
2543.It Fl m
2544Report the timestamp as milliseconds since the epoch.
2545.It Fl U
2546Report the timestamp using the national representation of the date and
2547time, but override the system time zone and use UTC instead.
2548.El
2549.El
2550.Bl -tag -width 6n
2551.It Fl s
2552Set the device's timestamp.
2553Either the
2554.Fl f
2555and
2556.Fl T
2557options or the
2558.Fl U
2559option must be specified.
2560.Bl -tag -width 9n
2561.It Fl f Ar format
2562Specify the strptime format string, as documented in strptime(3).
2563The time must also be specified with the
2564.Fl T
2565option.
2566.It Fl T Ar time
2567Provide the time in the format specified with the
2568.Fl f
2569option.
2570.It Fl U
2571Set the timestamp to the host system's time in UTC.
2572.El
2573.El
2574.It Ic devtype
2575Print out the device type for specified device.
2576.Bl -tag -width 10n
2577.It ata
2578An ATA device attached directly to an ATA controller
2579.It satl
2580An SATA device attached behind a SAS controller via SCSI-ATA Translation Layer (SATL)
2581.It scsi
2582A SCSI device
2583.It nvme
2584An directly attached NVMe device
2585.It mmcsd
2586An MMC or SD device attached via a mmcsd bus
2587.It none
2588No device type reported
2589.It unknown
2590Device type is unknown
2591.It illegal
2592A programming error occurred
2593.El
2594.It Ic depop
2595Commands necessary to support the depopulation (depop) of defective elements of a device
2596(typically heads for hard drives) or setting capacity point (typically used on
2597flash drives).
2598Issues either GET PHYSICAL ELEMENT STATUS, REMOVE ELEMENT AND TRUNCATE, or RESTORE
2599ELEMENT AND REBUILD command to manage storage elements of a drive.
2600Removal or restoration of elements may take up to a day to complete.
2601One of the
2602.Fl d ,
2603.Fl l ,
2604or
2605.Fl r
2606options must be specified.
2607These options are mutually exclusive.
2608Only SCSI drives are supported.
2609Changing the storage elements of a storage drive may result in the loss of all
2610data on that storage drive.
2611The drive may need to reinitialize after
2612.Fl d
2613or
2614.Fl r
2615commands.
2616The data on the drive is inaccessible until one of these commands complete.
2617Once one of these commands start, the drive is format corrupt until the
2618operation successfully completes.
2619While format corrupt, no read or write I/O is possible to the drive.
2620If the drive power cycles, it will remain format corrupt and the operation
2621must be restarted.
2622TEST UNIT READY or
2623.Dq camcontrol tur
2624can monitor an in-progress depop operation.
2625.Bl -tag -width 6n
2626.It Fl c Ar capacity
2627Specify the desired capacity point for the drive.
2628Valid only for the
2629.Fl d
2630flag.
2631.It Fl d
2632Remove the physical element from service or set the capacity point specified by the
2633.Fl e
2634or
2635.Fl c
2636flags.
2637The drive's capacity may be reduced by this operation.
2638.It Fl e Ar element
2639Specify the physical element to remove from service.
2640Valid only for the
2641.Fl d
2642flag.
2643.It Fl l
2644Report the current status of the physical elements of a drive.
2645.It Fl r
2646Restore all the eligible physical elements to service.
2647.El
2648.It Ic help
2649Print out verbose usage information.
2650.El
2651.Sh ENVIRONMENT
2652The
2653.Ev SCSI_MODES
2654variable allows the user to specify an alternate mode page format file.
2655.Pp
2656The
2657.Ev EDITOR
2658variable determines which text editor
2659.Nm
2660starts when editing mode pages.
2661.Sh FILES
2662.Bl -tag -width /usr/share/misc/scsi_modes -compact
2663.It Pa /usr/share/misc/scsi_modes
2664is the SCSI mode format database.
2665.It Pa /dev/xpt0
2666is the transport layer device.
2667.It Pa /dev/pass*
2668are the CAM application passthrough devices.
2669.El
2670.Sh EXAMPLES
2671.Dl camcontrol eject -n cd -u 1 -v
2672.Pp
2673Eject the CD from cd1, and print SCSI sense information if the command
2674fails.
2675.Pp
2676.Dl camcontrol tur da0
2677.Pp
2678Send the SCSI test unit ready command to da0.
2679The
2680.Nm
2681utility will report whether the disk is ready, but will not display sense
2682information if the command fails since the
2683.Fl v
2684switch was not specified.
2685.Bd -literal -offset indent
2686camcontrol tur da1 -E -C 4 -t 50 -Q head -v
2687.Ed
2688.Pp
2689Send a test unit ready command to da1.
2690Enable kernel error recovery.
2691Specify a retry count of 4, and a timeout of 50 seconds.
2692Enable sense
2693printing (with the
2694.Fl v
2695flag) if the command fails.
2696Since error recovery is turned on, the
2697disk will be spun up if it is not currently spinning.
2698The
2699.Tn SCSI
2700task attribute for the command will be set to Head of Queue.
2701The
2702.Nm
2703utility will report whether the disk is ready.
2704.Bd -literal -offset indent
2705camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
2706	-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
2707.Ed
2708.Pp
2709Issue a READ BUFFER command (0x3C) to cd1.
2710Display the buffer size of cd1,
2711and display the first 10 bytes from the cache on cd1.
2712Display SCSI sense
2713information if the command fails.
2714.Bd -literal -offset indent
2715camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
2716	-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
2717.Ed
2718.Pp
2719Issue a WRITE BUFFER (0x3B) command to cd1.
2720Write out 10 bytes of data,
2721not including the (reserved) 4 byte header.
2722Print out sense information if
2723the command fails.
2724Be very careful with this command, improper use may
2725cause data corruption.
2726.Bd -literal -offset indent
2727camcontrol modepage da3 -m 1 -e -P 3
2728.Ed
2729.Pp
2730Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
2731settings on the drive.
2732Mode page 1 contains a disk drive's auto read and
2733write reallocation settings, among other things.
2734.Pp
2735.Dl camcontrol rescan all
2736.Pp
2737Rescan all SCSI buses in the system for devices that have been added,
2738removed or changed.
2739.Pp
2740.Dl camcontrol rescan 0
2741.Pp
2742Rescan SCSI bus 0 for devices that have been added, removed or changed.
2743.Pp
2744.Dl camcontrol rescan 0:1:0
2745.Pp
2746Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or
2747changed.
2748.Pp
2749.Dl camcontrol tags da5 -N 24
2750.Pp
2751Set the number of concurrent transactions for da5 to 24.
2752.Bd -literal -offset indent
2753camcontrol negotiate -n da -u 4 -T disable
2754.Ed
2755.Pp
2756Disable tagged queueing for da4.
2757.Bd -literal -offset indent
2758camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a
2759.Ed
2760.Pp
2761Negotiate a sync rate of 20MHz and an offset of 15 with da3.
2762Then send a
2763Test Unit Ready command to make the settings take effect.
2764.Bd -literal -offset indent
2765camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1"
2766.Ed
2767.Pp
2768Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs
2769it contains.
2770Display SMP errors if the command fails.
2771.Bd -literal -offset indent
2772camcontrol security ada0
2773.Ed
2774.Pp
2775Report security support and settings for ada0
2776.Bd -literal -offset indent
2777camcontrol security ada0 -U user -s MyPass
2778.Ed
2779.Pp
2780Enable security on device ada0 with the password MyPass
2781.Bd -literal -offset indent
2782camcontrol security ada0 -U user -e MyPass
2783.Ed
2784.Pp
2785Secure erase ada0 which has had security enabled with user password MyPass
2786.Pp
2787.Em WARNING! WARNING! WARNING!
2788.Pp
2789This will
2790.Em ERASE ALL
2791data from the device, so backup your data before using!
2792.Pp
2793This command can be used against an SSD drive to restoring it to
2794factory default write performance.
2795.Bd -literal -offset indent
2796camcontrol hpa ada0
2797.Ed
2798.Pp
2799Report HPA support and settings for ada0 (also reported via
2800identify).
2801.Bd -literal -offset indent
2802camcontrol hpa ada0 -s 10240
2803.Ed
2804.Pp
2805Enables HPA on ada0 setting the maximum reported sectors to 10240.
2806.Pp
2807.Em WARNING! WARNING! WARNING!
2808.Pp
2809This will
2810.Em PREVENT ACCESS
2811to all data on the device beyond this limit until HPA is disabled by setting
2812HPA to native max sectors of the device, which can only be done after a
2813power-on or hardware reset!
2814.Pp
2815.Em DO NOT
2816use this on a device which has an active filesystem!
2817.Bd -literal -offset indent
2818camcontrol persist da0 -v -i read_keys
2819.Ed
2820.Pp
2821This will read any persistent reservation keys registered with da0, and
2822display any errors encountered when sending the PERSISTENT RESERVE IN
2823.Tn SCSI
2824command.
2825.Bd -literal -offset indent
2826camcontrol persist da0 -v -o register -a -K 0x12345678
2827.Ed
2828.Pp
2829This will register the persistent reservation key 0x12345678 with da0,
2830apply that registration to all ports on da0, and display any errors that
2831occur when sending the PERSISTENT RESERVE OUT command.
2832.Bd -literal -offset indent
2833camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac
2834.Ed
2835.Pp
2836This will reserve da0 for the exlusive use of the initiator issuing the
2837command.
2838The scope of the reservation is the entire LUN.
2839Any errors sending the PERSISTENT RESERVE OUT command will be displayed.
2840.Bd -literal -offset indent
2841camcontrol persist da0 -v -i read_full
2842.Ed
2843.Pp
2844This will display the full status of all reservations on da0 and print out
2845status if there are any errors.
2846.Bd -literal -offset indent
2847camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac
2848.Ed
2849.Pp
2850This will release a reservation on da0 of the type ex_ac
2851(Exclusive Access).
2852The Reservation Key for this registration is 0x12345678.
2853Any errors that occur will be displayed.
2854.Bd -literal -offset indent
2855camcontrol persist da0 -v -o register -K 0x12345678 -S \e
2856	-I sas,0x1234567812345678 -I sas,0x8765432187654321
2857.Ed
2858.Pp
2859This will register the key 0x12345678 with da0, specifying that it applies
2860to the SAS initiators with SAS addresses 0x1234567812345678 and
28610x8765432187654321.
2862.Bd -literal -offset indent
2863camcontrol persist da0 -v -o register_move -k 0x87654321 \e
2864	-K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678
2865.Ed
2866.Pp
2867This will move the registration from the current initiator, whose
2868Registration Key is 0x87654321, to the Fibre Channel initiator with the
2869Fiber Channel World Wide Node Name 0x1234567812345678.
2870A new registration key, 0x12345678, will be registered for the initiator
2871with the Fibre Channel World Wide Node Name 0x1234567812345678, and the
2872current initiator will be unregistered from the target.
2873The reservation will be moved to relative target port 2 on the target
2874device.
2875The registration will persist across power losses.
2876.Bd -literal -offset indent
2877camcontrol attrib sa0 -v -i attr_values -p 1
2878.Ed
2879.Pp
2880This will read and decode the attribute values from partition 1 on the tape
2881in tape drive sa0, and will display any
2882.Tn SCSI
2883errors that result.
2884.Bd -literal -offset indent
2885camcontrol zone da0 -v -c rz -P summary
2886.Ed
2887.Pp
2888This will request the SMR zone list from disk da0, and print out a
2889summary of the zone parameters, and display any
2890.Tn SCSI
2891or
2892.Tn ATA
2893errors that result.
2894.Bd -literal -offset indent
2895camcontrol zone da0 -v -c rz -o reset
2896.Ed
2897.Pp
2898This will request the list of SMR zones that should have their write
2899pointer reset from the disk da0, and display any
2900.Tn SCSI
2901or
2902.Tn ATA
2903errors that result.
2904.Bd -literal -offset indent
2905camcontrol zone da0 -v -c rwp -l 0x2c80000
2906.Ed
2907.Pp
2908This will issue the Reset Write Pointer command to disk da0 for the zone
2909that starts at LBA 0x2c80000 and display any
2910.Tn SCSI
2911or
2912.Tn ATA
2913errors that result.
2914.Bd -literal -offset indent
2915camcontrol epc ada0 -c timer -T 60.1 -p Idle_a -e -s
2916.Ed
2917.Pp
2918Set the timer for the Idle_a power condition on drive
2919.Pa ada0
2920to 60.1 seconds, enable that particular power condition, and save the timer
2921value and the enabled state of the power condition.
2922.Bd -literal -offset indent
2923camcontrol epc da4 -c goto -p Standby_z -H
2924.Ed
2925.Pp
2926Tell drive
2927.Pa da4
2928to go to the Standby_z power state (which is
2929the drive's lowest power state) and hold in that state until it is
2930explicitly released by another
2931.Cm goto
2932command.
2933.Bd -literal -offset indent
2934camcontrol epc da2 -c status -P
2935.Ed
2936.Pp
2937Report only the power state of
2938drive
2939.Pa da2 .
2940Some drives will power up in response to the commands sent by the
2941.Pa status
2942subcommand, and the
2943.Fl P
2944option causes
2945.Nm
2946to only send the
2947.Tn ATA
2948CHECK POWER MODE command, which should not trigger a change in the drive's
2949power state.
2950.Bd -literal -offset indent
2951camcontrol epc ada0 -c list
2952.Ed
2953.Pp
2954Display the ATA Power Conditions log (Log Address 0x08) for
2955drive
2956.Pa ada0 .
2957.Bd -literal -offset indent
2958camcontrol timestamp sa0 -s -f "%a, %d %b %Y %T %z" \e
2959	-T "Wed, 26 Oct 2016 21:43:57 -0600"
2960.Ed
2961.Pp
2962Set the timestamp of drive
2963.Pa sa0
2964using a
2965.Xr strptime 3
2966format string followed by a time string
2967that was created using this format string.
2968.Sh SEE ALSO
2969.Xr cam 3 ,
2970.Xr cam_cdbparse 3 ,
2971.Xr cam 4 ,
2972.Xr pass 4 ,
2973.Xr xpt 4 ,
2974.Xr trim 8 ,
2975.Xr zonectl 8
2976.Sh HISTORY
2977The
2978.Nm
2979utility first appeared in
2980.Fx 3.0 .
2981.Pp
2982The mode page editing code and arbitrary SCSI command code are based upon
2983code in the old
2984.Xr scsi 8
2985utility and
2986.Xr scsi 3
2987library, written by Julian Elischer and Peter Dufault.
2988The
2989.Xr scsi 8
2990program first appeared in
2991.Bx 386 0.1.2.4 ,
2992and first appeared in
2993.Fx
2994in
2995.Fx 2.0.5 .
2996.Sh AUTHORS
2997.An Kenneth Merry Aq Mt ken@FreeBSD.org
2998.Sh BUGS
2999The code that parses the generic command line arguments does not know that
3000some of the subcommands take multiple arguments.
3001So if, for instance, you
3002tried something like this:
3003.Bd -literal -offset indent
3004camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
3005.Ed
3006.Pp
3007The sense information from the test unit ready command would not get
3008printed out, since the first
3009.Xr getopt 3
3010call in
3011.Nm
3012bails out when it sees the second argument to
3013.Fl c
3014(0x00),
3015above.
3016Fixing this behavior would take some gross code, or changes to the
3017.Xr getopt 3
3018interface.
3019The best way to circumvent this problem is to always make sure
3020to specify generic
3021.Nm
3022arguments before any command-specific arguments.
3023