1SG_RBUF(8) SG3_UTILS SG_RBUF(8)
2
6 sg_rbuf - reads data using SCSI READ BUFFER command
7
9 sg_rbuf [--buffer=EACH] [--dio] [--help] [--mmap] [--quick]
10 [--size=OVERALL] [--verbose] [--version] DEVICE
11 sg_rbuf [-b=EACH_KIB] [-d] [-m] [-q] [-s=OVERALL_MIB] [-t] [-v] [-V]
13 DEVICE
14
16 This command reads data with the SCSI READ BUFFER command and then dis‐
17 cards it. Typically the data being read is from a disk's memory cache.
18 It is assumed that the data is sourced quickly (although this is not
19 guaranteed by the SCSI standards) so that it is faster than reading
20 data from the media. This command is designed for timing transfer
21 speeds across a SCSI transport.
22 To fetch the data with a SCSI READ BUFFER command and optionally decode
24 it see the sg_read_buffer utility. There is also a sg_write_buffer
25 utility useful for downloading firmware amongst other things.
26 This utility supports two command line syntaxes, the preferred one is
28 shown first in the synopsis and explained in this section. A later sec‐
29 tion on the old command line syntax outlines the second group of
30 options.
31 This is a Linux only utility and only works when DEVICE is an sg device
33 (e.g. "/dev/sg1"). The sg_read_buffer utility has similar functionality
34 and is ported to other OSes and within Linux can use bsg and normal
35 block device names (e.g. "/dev/sdc").
36
38 Arguments to long options are mandatory for short options as well.
39 -b, --buffer=EACH
41 where EACH is the number of bytes to be transferred by each READ
42 BUFFER command. The default is the actual available buffer size
43 returned by the READ BUFFER (descriptor) command. The maximum is
44 the same as the default, hence this argument can only be used to
45 reduce the size of each transfer to less than the device's
46 actual available buffer size.
47 -d, --dio
49 use direct IO if available. This option is only available if the
50 DEVICE is a sg driver device node (e.g. /dev/sg1). In this case
51 the sg driver will attempt to configure the DMA from the SCSI
52 adapter to transfer directly into user memory. This will elimi‐
53 nate the copy via kernel buffers. If not available then this
54 will be reported and indirect IO will be done instead.
55 -h, --help
57 print usage message then exit.
58 -m, --mmap
60 use memory mapped IO if available. This option is only available
61 if the DEVICE is a sg driver device node (e.g. /dev/sg1). In
62 this case the sg driver will attempt to configure the DMA from
63 the SCSI adapter to transfer directly into user memory. This
64 will eliminate the copy via kernel buffers.
65 -O, --old
67 Switch to older style options. Please use as first option.
68 -q, --quick
70 only transfer the data into kernel buffers (typically by DMA
71 from the SCSI adapter card) and do not move it into the user
72 space. This option is only available if the DEVICE is a sg
73 driver device node (e.g. /dev/sg1).
74 -s, --size=OVERALL
76 where OVERALL is the size of total transfer in bytes. The
77 default is 200 MiB (200*1024*1024 bytes). The actual number of
78 bytes transferred may be slightly less than requested since all
79 transfers are the same size (and an integer division is involved
80 rounding towards zero).
81 -t, --time
83 times the bulk data transfer component of this command. The
84 elapsed time is printed out plus a MB/sec calculation. In this
85 case "MB" is 1,000,000 bytes. The gettimeofday() system call is
86 used internally for the time calculation.
87 -v, --verbose
89 increase level of verbosity. Can be used multiple times.
90 -V, --version
92 print out version string then exit.
93
95 This command is typically used on modern SCSI disks which have a RAM
96 cache in their drive electronics. If no IO to the magnetic media, or
97 slower devices like flash RAM, is involved then the disk may be able to
98 source data fast enough to saturate the bandwidth of the SCSI trans‐
99 port. The bottleneck may then be the DMA element in the HBA, the Linux
100 drivers or the host machine's hardware (e.g. speed of RAM).
101 Various numeric arguments (e.g. OVERALL) may include multiplicative
103 suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" sec‐
104 tion in the sg3_utils(8) man page.
105
107 On the test system /dev/sg0 corresponds to a fast disk on a U2W SCSI
108 bus (max 80 MB/sec). The disk specifications state that its cache is 4
109 MB.
110 $ time ./sg_rbuf /dev/sg0
111 READ BUFFER reports: buffer capacity=3434944,
112 offset boundary=6
113 Read 200 MiB (actual 199 MiB, 209531584 bytes),
114 buffer size=3354 KiB
115 real 0m5.072s, user 0m0.000s, sys 0m2.280s
116 So that is approximately 40 MB/sec at 40 % utilization. Now with the
118 addition of the "-q" option this throughput improves and the utiliza‐
119 tion drops to 0%.
120 $ time ./sg_rbuf -q /dev/sg0
121 READ BUFFER reports: buffer capacity=3434944,
122 offset boundary=6
123 Read 200 MiB (actual 199 MiB, 209531584 bytes),
124 buffer size=3354 KiB
125 real 0m2.784s, user 0m0.000s, sys 0m0.000s
126
128 The exit status of sg_rbuf is 0 when it is successful. Otherwise see
129 the sg3_utils(8) man page.
130
132 The options in this section were the only ones available prior to
133 sg3_utils version 1.23 . Since then this utility defaults to the newer
134 command line options which can be overridden by using --old (or -O) as
135 the first option. See the ENVIRONMENT VARIABLES section for another way
136 to force the use of these older command line options.
137 -b=EACH_KIB
139 where EACH_KIB is the number of Kilobytes (i.e. 1024 byte units)
140 to be transferred by each READ BUFFER command. Similar to the
141 --buffer=EACH option in the main description but the units are
142 different.
143 -d use direct IO if available. Equivalent to the --dio option in
145 the main description.
146 -m use memory mapped IO if available. Equivalent to the --mmap
148 option in the main description.
149 -N, --new
151 Switch to the newer style options.
152 -q only transfer the data into kernel buffers (typically by DMA
154 from the SCSI adapter card) and do not move it into the user
155 space. Equivalent to the --quick option in the main descrip‐
156 tion.
157 -s=OVERALL_MIB
159 where OVERALL_MIB is the size of total transfer in Megabytes
160 (1048576 bytes). Similar to the --size=OVERALL option in the
161 main description but the units are different.
162 -t times the bulk data transfer component of this command. Equiva‐
164 lent to the --time option in the main description.
165 -v increase level of verbosity. Can be used multiple times.
167 -V print out version string then exit.
169
171 Since sg3_utils version 1.23 the environment variable
172 SG3_UTILS_OLD_OPTS can be given. When it is present this utility will
173 expect the older command line options. So the presence of this environ‐
174 ment variable is equivalent to using --old (or -O) as the first command
175 line option.
176
178 Written by Douglas Gilbert
179
181 Report bugs to <dgilbert at interlog dot com>.
182
184 Copyright © 2000-2017 Douglas Gilbert
185 This software is distributed under the GPL version 2. There is NO war‐
186 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
187 POSE.
188
190 sg_read_buffer, sg_write_buffer, sg_test_rwbuf(all in sg3_utils)
191sg3_utils-1.43 October 2017 SG_RBUF(8)