1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
README for sg_utils
===================
Introduction
------------
In this directory are some utilities and test programs for the Linux
sg device driver. If you have problems or questions about them
please contact me at dgilbert@interlog.com . The home site for the
Linux sg device driver is: http://www.torque.net/sg .
All programs are "GPL"-ed so you can incorporate all or part of them
in your applications as you please. The "sg_err.[hc]" files contain
ASCII text corresponding to most of the error and warning conditions
defined by the SCSI 2 standard. They are used by most other programs.
Additional information (including a version number) can be found
towards the top of each ".c" file corresponding to each utility and
test program.
Scope
-----
The sg driver in Linux can be seen as having 3 distinct versions:
v1 lk < 2.2.6 sg_header based relatively unchanged since 1992
v2 lk >= 2.2.6 enhanced sg_header interface structure
v3 lk >= 2.4 additional sg_io_hdr interface structure.
This package is targeted as "v2" but using "make common" will build
a subset of these utilities that will work with "v1". Another package
called "sg3_utils" is targeted at "v3" and has essentially the same
utilities (in some cases with extra options).
Utilities
---------
The main utility is a variant of the standard Unix command "dd" that
is called "sg_dd". This program takes a useful subset of the command
line arguments that "dd" takes. Furthermore "sg_dd" will only work if
one or both of the given files (ie "if" or "of") is an "sg" or raw
device. If "bs" (block size) is not given it is assumed to be 512
bytes. Available dd options:
bs=<n> typically 512 or 2048
ibs=<n> if given must be the same as "bs"
obs=<n> if given must be the same as "bs"
if=<name> like dd plus sg device or "-" (read from stdin)
of=<name> like dd plus sg device or "-" (write to stdout)
skip=<n> block offset to start reading "if"
seek=<n> block offset to start writing "of"
Extra options:
bpt=<n> blocks per transfer (default 128)
All numeric arguments can take multiplier suffixes:
"c", "C" * 1
"b", "B" * 512
"k" * 1024 [2 ^ 10]
"K" * 1000 [10 ^ 3]
"m" * 1048576 [2 ^ 20]
"M" * 1000000 [10 ^ 6]
"g" * 1073741824 [2 ^ 30]
"G" * 1000000000 [10 ^ 9]
The 'skip' and 'seek' options lead to the use of the system command
lseek() to a byte offset when used on raw devices and normal files.
[For sg devices 32 bit block addresses are used thus limiting accesses
on disks with 512 byte blocks to 1 TB.] On 32 bit architectures the
normal lseek() is limited to a signed 32 bit byte offset (i.e. 2 GB).
"sg_dd" bypasses this limit by using Linux's _llseek() [while modern
"dd" commands use read loops to "walk" around the limit].
If 'count' is not given then the SCSI READ CAPACITY command will be
used (on sg devices) if appropriate. [Note that READ CAPACITY often
gives a 2 block overestimate for iso9660 file systems on CD-ROMs. See
the "isosize" command below.] Disk partition information can be found
with a command like "fdisk -ul /dev/sda".
"sgp_dd" uses POSIX threads and attempts to run multiple IO operations
in parallel. The user can control the amount of parallelism from
1 worker (i.e. single threaded) through to 16 worker threads. This is
done via the "thr=<n>" option (default 4). Copies from one sg device to
another can be considerably faster due to this parallelism. There is
also some speed benefit when raw devices are used. Other enhancements
compared to "sg_dd" are a "gen=0 | 1" argument that allows general
copying (i.e. doesn't need to involve sg or raw devices) and that
signals are caught.
"sg_scan" does a SCSI bus scan and prints the results to standard output.
With no arguments only read permissions are needed on the sg devices
but if "-i" is given (to do a SCSI Inquiry command on the device) then
write permissions are also needed.
"sg_map" shows the mapping between sg device names and those of the
sd, sr and st device names. Some devices such as scanners have no
corresponding sd, sr nor st device names.
"sginfo" is a re-porting of the "scsiinfo" program by Eric Youngdale to
use the sg devices (rather than the sd, sr or st block devices). This
program outputs "mode sense" information. Amongst other things it outputs
the full defect list of a disk (which was truncated at 4096 bytes in
the original).
"isosize" is a utility that gives the number of bytes in an iso9660
file system. It is a rewrite by Andries Brouwer<Andries.Brouwer@cwi.nl>
of a utility that first appeared in the cdwrite package but is now
difficult to obtain. Note that the value given by isosize is usually
2 or more blocks less than the READ CAPACITY SCSI command yields on
a CD-ROM (due to run out sectors).
"sg_inq" is a utility for poking around the INQUIRY command which
contains much interesting information. It is based on SCSI 3's SPC-1
document and has additional fields defined in the draft SPC-2 document
(revision 18 from May 2000). This command is applicable to SCSI 2 (and
perhaps SCSI 1) devices as well.
"sg_test_rwbuf" is a program by Kurt Garloff <garloff@suse.de> that has
the following description: Program to test the SCSI host adapter by
issueing write and read operations on a device's buffer and calculating
checksums.
"sg_start" has been provided by Kurt Garloff <garloff@suse.de> for spinning
up (or down) disks. See README.sg_start .
Test Programs
-------------
"sg_debug" must be given a valid sg device as an argument but outputs
internal debug information on the state of _all_ currently open
sg file descriptors. That output goes to the console and perhaps the
log file as well (eg to /var/log/messages depending on the settings
in /etc/syslog.conf).
"sg_whoami" outputs information about the given sg device and if "-rc"
is given as an additinal argument, it does a SCSI Read capacity
command and outputs the result. A "-h" argument can also be given to
output information about the host adapter connected to the given sg
device.
"sg_runt_ex" is an example program that uses run time selection to
decide which version of the sg device driver it has and uses the extra
features where appropriate. It performs an INQUIRY and a TEST UNIT READY
command and outputs the results. This program is meant as an example to
application writers who need to use sg.
"sg_readcap" is built using the same framework as "sg_runt_ex". It
performs a READ CAPACITY command and outputs the result.
"sg_rbuf" is designed to test SCSI bus speed. It does this by reading
200MB using the SCSI Read Buffer command from the nominated device.
This command should involve _no_ physical IO (if you wish to time that
use 'time sg_dd ...' instead).
"sg_turs" executes a user specified number of TEST UNIT READY commands on
the given device. This can be used to time SCSI command overhead.
"sg_reset" exercises the SCSI device/bus/host reset capability. It is
supported by the sg driver in lk 2.2.16 and beyond but associated
SCSI middle level driver changes have not been accepted into the
standard kernel at this time. Some distributions contain the patch to
the mid-level that activates this feature. Due to this uncertainty
the source is placed in the "archive" directory.
"sg_simple1" and "sg_simple2" are simple example programs demonstrating
calls to the SCSI INQUIRY and TEST UNIT READY commands. They only differ
in their error processing: sg_simple1 uses sg_err.[hc] for error
processing while sg_simple2 does its own more primitive checks.
An experimental version of a "scsi_inquiry" program is included to
show the use of the SCSI_IOCTL_SEND_COMMAND ioctl to send a SCSI
INQUIRY command. That ioctl() is supported by the SCSI sub system
mid level and so is common to all sd, sr, st and sg devices.
Building
--------
A Makefile is provided that builds the above utilities and test programs
'make' and 'make all' will cause everything (that is stale) to be built.
The following programs: sg_dd, sg_scan, sg_rbuf, isosize, sg_turs,
sginfo, sg_runt_ex, sg_readcap, sg_simple2, sg_inq and scsi_inquiry
can be built with either the original sg device driver or the new one.
To build just these executables use 'make common'.
A complete rebuild can be forced by executing 'make clean' prior to
any of the above make commands. Individual commands can be built be
giving the executable name to make, for example: 'make sg_dd'.
There is also a 'make dep' but that shouldn't be needed very often.
A 'make install' will build if necessary and then install the
executables into /usr/local/bin by default (controlled by variable
INSTDIR).
Header file problems
--------------------
These utilities include 2 special Linux header files:
#include <scsi/sg.h>
#include <scsi/scsi.h>
These files are typically found in the directory /usr/include/scsi which
is maintained by the GNU glibc team. Unfortunately these GNU supplied
headers may not be (functionally) the same as those found in the kernel
source:
/usr/src/linux/include/scsi/sg.h and
/usr/src/linux/include/scsi/scsi.h
If glibc and the kernel on a machine are of the same vintage then it is
probably sufficient to use the simple includes listed at the start of this
section. Another technique is to rely on the fact that
/usr/include/linux is a symbolic link to /usr/src/linux/include/linux .
That will cause the following:
#include <linux/../scsi/sg.h>
#include <linux/../scsi/scsi.h>
to find the kernel supplied header files. However recent versions of
glibc have removed this symlink! Hence this technique is no longer
recommended.
The include file path issues are now all addressed in one file called
"sg_include.h". Please read that file.
Doug Gilbert
19th April 2001
|
