« back to all changes in this revision
Viewing changes to README
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Luk Claes
- Date: 2006-11-05 17:23:29 UTC
- mfrom: (1.1.4 upstream) (3.1.2 edgy)
- Revision ID: james.westby@ubuntu.com-20061105172329-l4loha00sk36qz6k
* Non-maintainer upload.
* Fix FTBFS due to old syscall usage (Closes: #395512).
* Fix FTBFS due to old syscall usage (Closes: #395512).
- files added:
- COPYING
- archive/sg_io_linux.h
- archive/sg_lib.h
- archive/sg_linux_inc.h
- doc
- examples/sg_io_linux.h
- examples/sg_lib.h
- examples/sg_linux_inc.h
- examples/sg_pt.h
- getopt_long
- no_lib
- utils/sg_lib.h
- files removed:
- archive/sg_err.h
- files modified:
- CHANGELOG
- archive/llseek.h
added
removed
README
2
2
====================
3
3
Introduction
4
4
============
5
This package contains utilities and test programs for the Linux SCSI
6
subsystem. In the Linux 2.6 kernel series almost all of these programs
7
will work on any devices that use the SCSI command set. Apart from SCSI
8
parallel devices, ATAPI devices (CD/DVDs and tapes), USB mass storage
9
devices, Fibre Channel disks and IEEE 1394 storage devices (that use
10
the "SBP" protocol) use the SCSI command set.
11
5
This package contains low level utilities for devices that use a SCSI
6
command set. Apart from SCSI parallel interface (SPI) devices, the SCSI
7
command set is used by ATAPI devices (CD/DVDs and tapes), USB
8
mass storage devices, Fibre Channel disks and IEEE 1394 storage
9
devices (that use the "SBP" protocol).
10
11
This package targets the Linux SCSI subsystem. Recent changes
12
allow many utilities within this package to be used on other operating
13
systems which have Unix like support. Most operating systems have
14
a pass through mechanism for sending SCSI commands and receiving
15
the corresponding response. This README mainly concentrates on
16
Linux; see the README.freebsd file to information about the FreeBSD
17
port.
18
19
Most utilities within the sg3_utils package work at the SCSI command
20
level. For example the sg_inq utility issues a SCSI INQUIRY command
21
and decodes the response. To view the relationship between the sg3_utils'
22
utility and the main SCSI command(s) that it issues see the COVERAGE file.
23
The only utilities that interface at a slightly higher level are sg_dd,
24
sgm_dd and sgp_dd. These are closely related to the Unix dd command and
25
typically issue a sequence of SCSI READ and WRITE commands to copy data.
26
27
Description
28
===========
12
29
A web site supporting the sg3_utils package, its predecessor sg_utils,
13
30
and the Linux SCSI generic driver (and the scsi_debug driver) can be
14
31
found at http://www.torque.net/sg . The most recent release version
15
32
of sg3_utils and the most recent beta is on that page. There is also
16
33
a page describing the utilities in the sg3_utils and sg_utils packages:
17
http://www.torque.net/sg/u_index.html .
34
http://www.torque.net/sg/sg3_utils.html . A copy of the "sg3_utils.html"
35
file is in the "doc" subdirectory.
18
36
19
In the Linux 2.4 kernel series these programs need to use the SCSI generic
37
In the Linux 2.4 kernel series these utilities need to use the SCSI generic
20
38
(sg) driver to access SCSI devices. The name of this package (i.e.
21
39
sg3_utils) refers to version 3 of the SCSI generic (sg) driver which
22
40
was introduced at the beginning of the 2.4 linux kernel series. Significantly
25
43
sg driver in the 2.2 and earlier linux kernel series. The sg_io_hdr structure
26
44
is also more flexible than the awkward (and limiting) interface to the
27
45
SCSI_IOCTL_SEND_COMMAND ioctl supported by the linux SCSI mid level.
28
Also added in the version 3 sg driver was the SG_IO ioctl that is synchronous
46
The version 3 sg driver also added the SG_IO ioctl that is synchronous
29
47
(i.e. it issues the requested SCSI command and waits for the response
30
48
(or a timeout) before the ioctl returns to the user space program that
31
invoked it). The SG_IO ioctl is now found in other parts of the linux
49
invoked it). The SG_IO ioctl is now supported in other parts of the linux
32
50
kernel in the 2.6 series.
33
51
34
52
Utilities that wish to use the asynchronous SCSI command interface
35
53
(i.e. via a write() read() sequence) or issue special "commands"
36
(e.g. bus and device resets) still need to use the sg driver. Note
54
(e.g. bus and device resets) still need to use the linux sg driver. Note
37
55
that various drivers (e.g. cdrom/sr) have different open() flag and
38
56
permissions policies that the user may need to take into account.
39
57
40
58
If you have problems or questions about them please contact the author.
41
Documentation for the sg device driver can be found at:
59
Documentation for the linux sg device driver can be found at:
42
60
http://www.torque.net/sg/p/sg_v3_ho.html .
43
61
This is written in DocBook and the original xml can be found in the
44
62
same directory with the ".xml" extension. Postscript and
46
64
Older documentation for the sg version 3 driver can be found at:
47
65
http://www.torque.net/sg/p/scsi_generic_v3.txt .
48
66
49
All programs are "GPL"-ed so you can incorporate all or part of them
50
in your applications as you please. The "sg_err.[hc]" files contain
51
ASCII text corresponding to most of the error and warning conditions
52
defined in recent drafts at www.t10.org which is the home site of
53
SCSI (draft) standards.
54
55
Additional information (including a version number) can be found
56
towards the top of each ".c" file corresponding to each utility and
57
test program.
58
59
60
Scope
61
=====
67
All utilities are either "GPL"-ed or have a FreeBSD license. The
68
intention is that users may incorporate all or part of the code in their
69
work as they please. Attribution is encouraged. Please check the code as
70
other contributors (apart from the author) may also have copyright
71
notices. For a list of contributors see the CREDITS file.
72
73
The "sg_lib.[hc]" files contain ASCII text corresponding to most
74
of the SCSI commands, errors and warning conditions. The "sg_cmds.[hc]"
75
files contains code to invoke common SCSI commands and associated
76
response processing. Both are guided by recent drafts at www.t10.org
77
which is the home site of SCSI (draft) standards. Linux specific
78
code has been removed from sg_lib.[hc] and sg_cmds.[hc] . The SCSI
79
common command implementations in sg_cmds.c access the OS pass through
80
mechanism via the function based interface defined in sg_pt.h . The
81
linux specific implementation of that pass through is found in the
82
sg_pt_linux.c file. Since almost all of the utilities use these files,
83
a shared library called "libsgutils.so" is built. Use of this library
84
cuts down the size of the binary distributions of sg3_utils
85
significantly. The "Makefile" provided in the main directory builds
86
libsgutils.so and then builds each utility to use that shared library.
87
Alternatively there is a script called "make_no_lib.sh" that will build
88
utilities without depending on libsgutils.so . For example
89
"./make_no_lib.sh sg_dd" builds a version of the sg_dd utility that
90
does not depend on libsgutils.so . See the INSTALL file for more
91
information.
92
93
All the utilities in the main directory have "man" pages. There is
94
also a sg3_utils (8) man page that summarizes common facilities
95
including exit statuses. Additional information (including a version
96
number) can be found towards the top of each ".c" file corresponding
97
to each utility.
98
62
99
The sg driver in Linux can be seen as having 3 distinct versions:
63
100
64
101
v1 lk < 2.2.6 sg_header based relatively unchanged since 1992
72
109
73
110
Some sg ioctls (notably SG_IO) are defined for many block devices
74
111
in lk 2.6 . In practice this means all SCSI block devices, ATAPI block devices
75
(mainly CD and DVD players) but _not_ ATA disks (currently). Support for
76
the SG_IO as been added to the scsi tape driver (st) in lk 2.6.6 (and
77
support for osst will soon follow).
112
(mainly CD and DVD players) but _not_ ATA disks (currently). SATA disks that
113
use the libata kernel library accept SCSI commands and thus are supported.
114
Support for the SG_IO as been added to the scsi tape driver (st) in lk 2.6.6
115
(and support for osst and ch (medium changer) may soon follow).
78
116
79
117
No utilities in the main directory use the sg driver's older "sg_header"
80
118
interface; instead they use the newer "sg_io_hdr" interface. The "sg_io_hdr"
82
120
- using the SG_IO ioctl [for synchronous access]
83
121
- using a write()/read() sequence that convey instances of "sg_io_hdr"
84
122
85
All utilities in the main directory use the SG_IO ioctl except for sgp_dd.
86
This is due to the asynchronous nature of sgp_dd. Note that sgp_dd does _not_
87
support the "blk_sgio" switch found in sg_dd. This is important since block
88
devices often identify themselves (programmatically) as sg devices in lk 2.6
89
and it would cause serious damage to do a write() of the sg driver's "sg_io_hdr"
90
metadata (i.e. disk corruption).
123
All utilities in the main directory that issue SCSI commands use the SG_IO
124
ioctl except for sgp_dd. This is due to the asynchronous nature of sgp_dd.
125
Note that sgp_dd does _not_ support the "blk_sgio" switch found in sg_dd.
126
This is important since block devices often identify themselves
127
(programmatically) as sg devices in lk 2.6 and it would cause serious damage
128
to do a write() of the sg driver's "sg_io_hdr" meta data (i.e. disk
129
corruption).
130
131
Warning
132
=======
133
Many devices use SCSI command sets over transport protocols not normally
134
associated with SCSI (as defined at http://www.t10.org ). Some of these
135
devices react poorly (e.g. lock up) when sent SCSI commands that they
136
don't support. Even sending a supported SCSI command with a field set
137
to an unexpected value can cause problems.
138
139
For example, all "SCSI" devices must support the INQUIRY command which
140
the SCSI-2 standard says should request a 36 byte response. However later
141
SCSI standards (e.g. SPC-2) have increased that length but some SCSI
142
devices lock up when they receive a request for anything other than
143
a 36 byte response.
144
145
Any well implemented "SCSI" device should react sensibly when a utility in
146
sg3_utils sends a SCSI command that it doesn't support. Unfortunately this
147
cannot be guaranteed.
91
148
92
149
93
150
Utilities
94
151
=========
95
Here is a (somewhat arbitrary) categorization of the utilities included
96
in this package:
97
1) dd variants: sg_dd, sgp_dd, sgm_dd and sgq_dd
98
2) scanning and mapping: sg_scan, sg_map and scsi_devfs_scan
99
3) SCSI support: sg_inq, scsi_inquiry, sginfo, sg_readcap, sg_start,
100
sg_modes, sg_logs, sg_senddiag, sg_reset, sg_opcodes, sg_persist,
101
sg_write_long and sg_read_long
102
4) timing and testing: sg_rbuf, sg_test_rwbuf, sg_read, sg_turs,
103
and sg_debug
104
5) example programs: sg_simple1, sg_simple2, sg_simple3, sg_simple4
105
and sg_simple16
106
6) miscellaneous programs: isosize, hxascdmp
107
108
There is a brief description of each utility in the following sections.
109
All utilities in the main directory have a "man" page in section 8
110
which is a category for administration and privileged commands. Some
111
utilities in the other (sub-)directories have man pages.
112
113
114
1) dd variants
115
--------------
116
The main utility is a variant of the standard Unix command "dd" that
117
is called "sg_dd". This program takes a useful subset of the command
118
line arguments that "dd" takes. Furthermore "sg_dd" will only work if
119
one or both of the given files (ie "if" or "of") is an "sg" or a raw
120
device. If "bs" (block size) is not given it is assumed to be 512 bytes.
121
Available dd options:
122
bs=<n> typically 512 or 2048
123
ibs=<n> if given must be the same as "bs"
124
obs=<n> if given must be the same as "bs"
125
if=<name> like dd plus sg device or "-" (read from stdin)
126
of=<name> like dd plus sg device or "-" (write to stdout)
127
skip=<n> block offset to start reading "if"
128
seek=<n> block offset to start writing "of"
129
Extra options:
130
bpt=<n> blocks per transfer (default 128)
131
dio=<n> 0 or 1, request direct IO (default 0)
132
cdbsz=6|10|12|16 allow the command size of SCSI READ and WRITE commands
133
to be specified (default is 10)
134
sync=0|1 when 1, do a SYNCHRONIZE CACHE on "of" after the transfer
135
is complete
136
fua=0|1|2|3 when 0, do not set 'force unit access' bit; when 1, set it
137
on "of"; when 2, set it on "if"; when 3, set it on "if"+"of"
138
time=0|1 times the transfer and calculates a throughput figure when
139
1, output sent to stderr. Default is 0
140
coe=0|1 continue on error (only on sg devices) when 1. Default is 0.
141
142
Numeric arguments can be given in decimal or hexadecimal. Hex arguments should
143
be prefixed with "0x" or "0X". Decimal arguments can take multiplier suffixes:
144
"c", "C" * 1
145
"b", "B" * 512
146
"k" * 1024 [2 ^ 10]
147
"K" * 1000 [10 ^ 3]
148
"m" * 1048576 [2 ^ 20]
149
"M" * 1000000 [10 ^ 6]
150
"g" * 1073741824 [2 ^ 30]
151
"G" * 1000000000 [10 ^ 9]
152
"t" * 1099511627776 [2 ^ 40]
153
"T" * 1000000000000 [10 ^ 12]
154
The 'skip' and 'seek' options lead to the use of the system command
155
lseek() to a byte offset when used on raw devices and normal files.
156
[For sg devices 32 bit block addresses are used thus limiting accesses
157
on disks with 512 byte blocks to 1 TB.] On 32 bit architectures the
158
normal lseek() is limited to a signed 32 bit byte offset (i.e. 2 GB).
159
"sg_dd" bypasses this limit by using Linux's _llseek() [while modern
160
"dd" commands use read loops to "walk" around the limit].
161
If 'count' is not given then the SCSI READ CAPACITY command will be
162
used (on sg devices) if appropriate. Block devices are queried for their
163
length if 'count' is not given. [Note that READ CAPACITY often
164
gives a 2 block overestimate for iso9660 file systems on CD-ROMs.
165
See the "isosize" command below.] Disk partition information can
166
be found with a command like "fdisk -ul /dev/sda". The 'dio' argument
167
requests direct IO (only functions in 2.4 kernels). A warning is issued
168
if direct IO is requested and /proc/scsi/sg/allow_dio == 0 .
169
"of=/dev/null" causes writes to be skipped, and "of=." is accepted as
170
an alias for "of=/dev/null" (convenient shorthand).
171
172
"sgp_dd" uses POSIX threads and attempts to run multiple IO operations
173
in parallel. The user can control the amount of parallelism from
174
1 worker (i.e. single threaded) through to 16 worker threads. This is
175
done via the "thr=<n>" option (default 4). Copies from one sg device to
176
another can be considerably faster due to this parallelism. There is
177
also some speed benefit when raw devices are used. To obtain fine level
178
SCSI command level control, sg devices should be used rather than block
179
devices which will be interpreted as normal Unix files.
180
181
"sgm_dd" is very similar to sg_dd but it uses mmap-ed IO on one of its
182
given sg device names. If both "if" and "of" are sg devices then mmap-ed
183
IO is selected on "if" while normal IO is selected on "of". Direct IO
184
cannot be selected with this command. To obtain fine level SCSI command
185
level control, sg devices should be used rather than block devices which
186
will be interpreted as normal Unix files.
187
188
"sgq_dd" is yet another implementation found in the archive directory.
189
From the user point of view it is very similar to sgp_dd but uses a
190
non-blocking state machine rather then POSIX threads for parallelism.
191
192
193
2) Scanning and mapping
194
-----------------------
195
"sg_scan" does a scan of all sg device and prints the results to
196
standard output. Alternatively one or more device names can be
197
given (e.g. 'sg_scan -i /dev/scd[01]') and these will be scanned instead
198
of the sg devices. Additional information from the INQUIRY command can
199
be obtained by using the "-i" option.
200
201
"sg_map" shows the mapping between sg device names and those of the
202
sd, sr and st device names. Some devices such as scanners have no
203
corresponding sd, sr nor st device names.
204
205
"scsi_devfs_scan" is a utility for doing a directory scan on a system
206
running devfs to identify SCSI (and optionally IDE) devices. Various
207
information (including an INQUIRY) can be listed for each found device.
208
209
210
3) SCSI support
211
---------------
212
"sg_inq" is a utility for examining the INQUIRY command which
213
contains much interesting information. It is based on SCSI 3's SPC-2
214
document. Has switches to output "vital product data" and "command support"
215
(now obsolete) pages. It can output in formatted ASCII, hex or binary.
216
Has '-i' to decode the now mandatory device identification VPD page (0x83).
217
This command is applicable to SCSI 2 (and perhaps SCSI 1) devices as well.
218
152
Here is list in alphabetical order of utilities found in the main directory
153
of the sg3_utils directory:
154
- sginfo, sgm_dd, sgp_dd, sg_dd, sg_emc_trespass, sg_get_config,
155
sg_format, sg_ident, sg_inq, sg_logs, sg_luns, sg_map, sg_map26,
156
sg_modes, sg_opcodes, sg_persist, sg_prevent, sg_rbuf, sg_rdac, sg_read,
157
sg_readcap, sg_read_long, sg_reassign, sg_request, sg_reset, sg_rmsn,
158
sg_rtpg, sg_scan, sg_senddiag, sg_ses, sg_start, sg_sync,
159
sg_test_rwbuff, sg_turs, sg_verify, sg_vpd, sg_write_long, sg_wr_mode
160
161
These utilities and the libsgutils.so library which they depend on are built
162
by the Makefile in the main directory. This Makefile does not invoke the
163
Makefile's in the subdirectories. Each utility in the main directory has a
164
"man" page in section 8 (system administration commands). Binary
165
distributions of the sg3_utils package (e.g. "rpm" and debian packages)
166
typically contains the shared library, the utilities in the main directory,
167
their associated man pages and some documentation files (e.g. README, INSTALL,
168
CREDITS, COPYING and COVERAGE). See the INSTALL file for instructions about
169
building and installing from a "tarball".
170
171
Man pages can be read (without building and installing the package) by
172
going to the main directory and executing something like this:
173
$ man ./sg_dd.8
174
175
To see which SCSI commands (and ATA commands) are used by these
176
utilities see the COVERAGE file.
177
178
Here is a list in alphabetical order of utilities found in the archive
179
subdirectory:
180
- isosize, scsi_devfs_scan, sg_debug, sgq_dd
181
Some of these utilities have man pages.
182
183
Here is a list in alphabetical order of utilities found in the examples
184
subdirectory:
185
- scsi_inquiry, sg_simple1, sg_simple2, sg_simple3, sg_simple4,
186
sg_simple5 and sg_simple16.c
187
188
Also in that subdirectory is a script to test sg_persist, an example
189
data file for sg_persist (called "transport_ids.txt") and an example
190
data file for sg_reassign (called "reassign_addr.txt"). There are also
191
two scripts for 'sg_senddiag -pf -raw=-' that will put some SAS disk
192
phys into a compliant jitter tolerance pattern (CJTPAT).
193
194
The "utils" subdirectory contains source and a Makefile to build
195
"hxascdmp" which accepts binary data from stdin (or a file on the
196
command line) and outputs an ASCII-HEX and ASCII representation of
197
it. It is similar to the Unix od command. There is also code to
198
sg_chk_asc.c which checks a given text file (typically a copy of
199
http://www.t10.org/lists/asc-num.txt ) and checks it against the
200
asc/ascq test strings held in sg_lib.c .
201
202
The "doc" subdirectory contains copies of web pages relevant to
203
the sg3_utils package. Currently it contains:
204
- sg_dd.html : describes the sg_dd utility and compares it with the
205
Unix dd command
206
- sg_io.html : describes the SG_IO ioctl used by sg3_utils. Looks
207
at differences between the lk 2.4 and 2.6 series;
208
including its use with block devices
209
- sg3_utils.html : a description of the sg3_utils package contents
210
- tools.html : a list of SCSI and storage tools with a summary and url
211
212
213
Notes for utilities without man pages
214
=====================================
219
215
The "scsi_inquiry" program shows the use of the SCSI_IOCTL_SEND_COMMAND
220
216
ioctl to send a SCSI INQUIRY command. That ioctl() is supported by the
221
217
SCSI sub system mid level and so is common to all sd, sr, st and sg devices.
222
218
This program has been placed in the "examples" subdirectory.
223
219
224
"sginfo" is a port of the "scsiinfo" program by Eric Youngdale to use the sg
225
devices. It can still take other SCSI device nodes (e.g. /dev/sda, /dev/st0
226
or /dev/hdc (if "hdc" is an ATAPI device)). This program outputs mode
227
page (and subpage) information and allows it to be modified. Additionally
228
defect lists (for disks) can be output and information from the SCSI INQUIRY
229
command is available.
230
231
"sg_readcap" call a READ CAPACITY command on the given device. Now also
232
supports "partial medium indicator" (PMI) flag that indicates where the
233
next significant delay will be on the media (after a given address).
234
235
"sg_start" has been provided by Kurt Garloff <garloff at suse dot de>
236
for spinning up (or down) disks.
237
see the README.sg_start file.
238
239
"sg_modes" and "sg_logs" print out mode sense pages and log sense pages
240
respectively.
241
242
"sg_senddiag" permits various device self tests to be run. It can also
243
list the diagnostic pages support by a device.
244
245
"sg_reset" exercises the SCSI device/bus/host reset capability. It is
246
supported by the sg driver in lk 2.2.16 and beyond but associated
247
SCSI middle level driver changes have not been accepted into the
248
standard kernel at this time. Many distributions contain the patch to
249
the mid-level that activates this feature. This patch is in later
250
lk 2.4 versions and in the lk 2.6 series. This utility will only
251
work on sg device names.
252
253
"sg_opcodes" lists available opcode names. It uses the REPORT SUPPORTED
254
OPERATION CODES SCSI command which was introduced in February 2002
255
(and replaced the Cmd modes (CmdDt bit) in the INQUIRY command). Opcode
256
names include various SCSI commands with service actions (e.g.
257
the Maintenance In command) and variable length commands. The command
258
list is either unsorted (as returned by the device), numerically sorted
259
(default) or alphabetically sorted. An individual opcode (and optionally
260
a service action) can be given in which case the "changeable" bits of
261
that command are output. With the '-t' command line option this utility
262
will list supported task management functions.
263
264
"sg_persist" accesses the Persistent Reservation In and Out commands.
265
These are relatively complex commands and potential users are referred
266
to the SPC-3 document at http://www.t10.org . That said, it is
267
relatively safe to query the state of existing registrations and
268
reservations with the PR In command (use the switch "--in" with
269
sg_persist to enforce this).
270
271
"sg_write_long" can be used to write a "long" block to the given device
272
(typically a disk). A "long" block includes data, ECC information and
273
and other vendor specific information.
274
275
"sg_read_long" can be used to read a "long" block from the given device
276
(typically a disk).
277
278
279
4) Timing and testing
280
---------------------
281
"sg_rbuf" does repeated SCSI READ BUFFER commands which allows SCSI
282
bus bandwidth and the SCSI sub-system throughput to be measured.
283
This can be done in 4 modes: normal transfer to user space, no
284
transfer to user space, direct IO or mmap-ed IO. The latter one wins
285
on my hardware.
286
287
"sg_test_rwbuf" is a program by Kurt Garloff <garloff at suse dot de> that
288
has the following description: Program to test the SCSI host adapter by
289
issuing write and read operations on a device's buffer and calculating
290
checksums.
291
292
"sg_read" reads multiple blocks of data starting at the same logical
293
address. It can time the transfers (potentially ignoring the first
294
issued command) and calculate a MB/sec figure. [In keeping with most
295
disk manufacturers, "MB" is 1,000,000 bytes in this context.] Its
296
command line syntax is modelled on "sg_dd". It allows SCSI device,
297
SCSI bus bandwidth and the SCSI sub-system throughput to be measured.
298
This can be done in 3 modes: normal transfer to user space, direct
299
IO or mmap-ed IO.
300
301
"sg_turs" executes a user specified number of TEST UNIT READY commands on
302
the given device. This can be used to time SCSI command overhead.
220
"sgq_dd" is yet another variant of dd found in the archive directory.
221
From the user's point of view it is very similar to sgp_dd but uses a
222
non-blocking state machine rather then POSIX threads for parallelism.
303
223
304
224
"sg_debug" is effectively defunct now. The user can instead do:
305
225
$ cat /proc/scsi/sg/debug . This command has been placed in the
306
226
archive directory.
307
227
308
309
5) Example programs
310
-------------------
311
228
"sg_simple1" and "sg_simple2" are simple example programs demonstrating
312
229
calls to the SCSI INQUIRY and TEST UNIT READY commands. They only differ
313
in their error processing: sg_simple1 uses sg_err.[hc] for error
230
in their error processing: sg_simple1 uses sg_lib.[hc] for error
314
231
processing while sg_simple2 does its own more primitive checks.
315
232
316
233
"sg_simple3" tests out user space scatter gather added to the version 3
319
236
"sg_simple4" shows the INQUIRY command using mmap-ed IO to obtain its
320
237
response buffer.
321
238
239
"sg_simple5" also sends and INQUIRY and TEST UNIT READY commands. It
240
uses the generic pass through mechanism based on sg_pt.h . It will
241
currently build in linux and FreeBSD (with "make -f Makefile.freebsd").
242
It has extensive error checking code.
243
322
244
"sg_simple16" attempts to send a 16 byte SCSI command, READ_16, to the
323
245
scsi device. This is only supported for lk >= 2.4.15 and for adapter
324
246
drivers that indicate that they have 16 byte CDB capability (otherwise
325
247
DID_ABORT will appear in the host_status).
326
248
327
All these example programs (plus scsi_inquiry) have been placed in the
328
"examples" subdirectory with their own Makefile.
329
330
331
6) Miscellaneous
332
----------------
333
"isosize" is a utility that gives the number of bytes in an iso9660
334
file system. It is a rewrite by Andries Brouwer<Andries.Brouwer at cwi dot nl>
335
of a utility that first appeared in the cdwrite package but is now
336
difficult to obtain. Note that the value given by isosize is usually
337
2 or more blocks less than the READ CAPACITY SCSI command yields on
338
a CD-ROM (due to run out sectors). This command has a "man" page
339
[section 8]. This utility has been moved to the archive directory
340
as isosize is now available in the util-linux-2.10s package (and later).
341
342
Building
343
========
344
A Makefile is provided that builds the above utilities and test programs
345
'make' and 'make all' will cause everything (that is stale) to be built.
346
347
A complete rebuild can be forced by executing 'make clean' prior to
348
any of the above make commands. Individual commands can be built be
349
giving the executable name to make, for example: 'make sg_dd'.
350
351
There is also a 'make dep' but that shouldn't be needed very often.
352
A 'make install' will build if necessary and then install the
353
executables into /usr/local/bin by default (controlled by variable
354
INSTDIR). The "man" pages are loaded int /usr/local/man/man8 by default.
355
356
Header file problems
357
====================
358
These utilities include 2 special Linux header files:
249
"sg_sat_identify" attempts to push an ATA IDENTIFY DEVICE or
250
IDENTIFY pACKET DEVICE command through the SAT-defined ATA PASS
251
THROUGH (16) SCSI command. If successful, the 256 word (512 byte)
252
response is output.
253
254
"sg_sat_chk_power" attempts to push an ATA CHECK POWER MODE command
255
through the SAT-defined ATA PASS THROUGH (16) SCSI command. That
256
ATA command needs to read the "FIS" registers after the command is
257
completed which involves using the ATA Status Return (sense data)
258
descriptor (as defined in SAT).
259
260
"sg_sat_smart_rd_data" attempts to push an ATA SMART/READ DATA command
261
through the SAT-defined ATA PASS THROUGH (16) SCSI command. If
262
successful, the 256 word (512 byte) response is output.
263
264
265
Command line processing
266
=======================
267
These utilities can be divided into 3 groups when their handling of
268
command line arguments is considered:
269
- ad hoc, typically in a short form only, sometimes longer (e.g.
270
"sg_logs -pcb /dev/sdc")
271
- inspired by the dd Unix command (e.g. sg_dd, sgm_dd, sgp_dd, sg_read)
272
- recent utilities use "getopt_long" (see "man getopt_long")
273
type command lines. These have short form (starting with "-")
274
and corresponding longer form (starting with "--") options.
275
276
The recent utilities that use "getopt_long" are, in alphabetical
277
order:
278
- sg_format sg_get_config sg_ident sg_luns sg_map26 sg_persist
279
sg_prevent sg_read_long sg_reassign sg_requests sg_rmsn sg_rtpg
280
sg_ses sg_sync sg_test_rwbuf sg_verify sg_vpd sg_write_long sg_wr_mode
281
282
283
Linux header file problems
284
==========================
285
In linux some utilities include 2 important header files:
359
286
#include <scsi/sg.h>
360
287
#include <scsi/scsi.h>
361
288
These files are typically found in the directory /usr/include/scsi which
373
300
#include <linux/../scsi/sg.h>
374
301
#include <linux/../scsi/scsi.h>
375
302
to find the kernel supplied header files. However recent versions of
376
glibc have removed this symlink! Hence this technique is no longer
303
glibc have removed this symlink. Hence this technique is no longer
377
304
recommended.
378
305
379
306
The include file path issues are now all addressed in one file called
380
"sg_include.h". Please read that file.
307
"sg_linux_inc.h". Please read that file. This fetching of the scsi.h and
308
sg.h header files has not been a problem in the latter lk 2.4 and lk 2.6
309
series.
381
310
382
311
scsirastools
383
312
============
389
318
- sgdefects: list primary and grown defect lists
390
319
- sgdiag to perform format and other test functions
391
320
321
plscsi
322
======
323
This is a utility which can issue arbitrary SCSI commands (i.e. supplied by
324
user). It is available for Linux and other operating systems.
325
See http://members.aol.com/plscsi .
326
392
327
Doug Gilbert
393
31st August 2004
328
6th July 2006
Loggerhead is a web-based interface for Breezy
Version: 2.0.1