1SG_RBUF(8)                         SG3_UTILS                        SG_RBUF(8)
2
3
4

NAME

6       sg_rbuf - reads data using SCSI READ BUFFER command
7

SYNOPSIS

9       sg_rbuf    [--buffer=EACH]    [--dio]   [--help]   [--mmap]   [--quick]
10       [--size=OVERALL] [--test] [--verbose] [--version] DEVICE
11
12       sg_rbuf [-b=EACH_KIB] [-d] [-m] [-q] [-s=OVERALL_MIB]  [-t]  [-v]  [-V]
13       DEVICE
14

DESCRIPTION

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
23       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
27       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

OPTIONS

33       Arguments to long options are mandatory for short options as well.
34
35       -b, --buffer=EACH
36              where EACH is the number of bytes to be transferred by each READ
37              BUFFER command. The default is the actual available buffer  size
38              returned by the READ BUFFER (descriptor) command. The maximum is
39              the same as the default, hence this argument can only be used to
40              reduce  the  size  of  each  transfer  to less than the device's
41              actual available buffer size.
42
43       -d, --dio
44              use direct IO if available. This option is only available if the
45              DEVICE  is a sg driver device node (e.g. /dev/sg1). In this case
46              the sg driver will attempt to configure the DMA  from  the  SCSI
47              adapter  to transfer directly into user memory. This will elimi‐
48              nate the copy via kernel buffers. If  not  available  then  this
49              will be reported and indirect IO will be done instead.
50
51       -h, --help
52              print usage message then exit.
53
54       -m, --mmap
55              use memory mapped IO if available. This option is only available
56              if the DEVICE is a sg driver device  node  (e.g.  /dev/sg1).  In
57              this  case  the sg driver will attempt to configure the DMA from
58              the SCSI adapter to transfer directly  into  user  memory.  This
59              will eliminate the copy via kernel buffers.
60
61       -O, --old
62              switch to older style options.
63
64       -q, --quick
65              only  transfer  the  data  into kernel buffers (typically by DMA
66              from the SCSI adapter card) and do not move  it  into  the  user
67              space.  This  option  is  only  available  if the DEVICE is a sg
68              driver device node (e.g. /dev/sg1).
69
70       -s, --size=OVERALL
71              where OVERALL is the  size  of  total  transfer  in  bytes.  The
72              default  is  200 MiB (200*1024*1024 bytes). The actual number of
73              bytes transferred may be slightly less than requested since  all
74              transfers are the same size (and an integer division is involved
75              rounding towards zero).
76
77       -t, --time
78              times the bulk data transfer  component  of  this  command.  The
79              elapsed  time  is printed out plus a MB/sec calculation. In this
80              case "MB" is 1,000,000 bytes. The gettimeofday() system call  is
81              used internally for the time calculation.
82
83       -v, --verbose
84              increase level of verbosity. Can be used multiple times.
85
86       -V, --version
87              print out version string then exit.
88

NOTES

90       This  command  is  typically used on modern SCSI disks which have a RAM
91       cache in their drive electronics. If no IO to the  magnetic  media,  or
92       slower devices like flash RAM, is involved then the disk may be able to
93       source data fast enough to saturate the bandwidth of  the  SCSI  trans‐
94       port.  The bottleneck may then be the DMA element in the HBA, the Linux
95       drivers or the host machine's hardware (e.g. speed of RAM).
96
97       Various numeric arguments (e.g.  OVERALL)  may  include  multiplicative
98       suffixes  or  be given in hexadecimal. See the "NUMERIC ARGUMENTS" sec‐
99       tion in the sg3_utils(8) man page.
100

EXAMPLES

102       On the test system /dev/sg0 corresponds to a fast disk on  a  U2W  SCSI
103       bus  (max 80 MB/sec). The disk specifications state that its cache is 4
104       MB.
105          $ time ./sg_rbuf /dev/sg0
106       READ BUFFER reports: buffer capacity=3434944,
107           offset boundary=6
108       Read 200 MiB (actual 199 MiB, 209531584 bytes),
109           buffer size=3354 KiB
110       real 0m5.072s, user 0m0.000s, sys 0m2.280s
111
112       So that is approximately 40 MB/sec at 40 % utilization.  Now  with  the
113       addition  of  the "-q" option this throughput improves and the utiliza‐
114       tion drops to 0%.
115          $ time ./sg_rbuf -q /dev/sg0
116       READ BUFFER reports: buffer capacity=3434944,
117           offset boundary=6
118       Read 200 MiB (actual 199 MiB, 209531584 bytes),
119           buffer size=3354 KiB
120       real 0m2.784s, user 0m0.000s, sys 0m0.000s
121

EXIT STATUS

123       The exit status of sg_rbuf is 0 when it is  successful.  Otherwise  see
124       the sg3_utils(8) man page.
125

OLDER COMMAND LINE OPTIONS

127       The  options  in  this  section  were  the only ones available prior to
128       sg3_utils version 1.23 . In sg3_utils  version  1.23  and  later  these
129       older  options can be selected by either setting the SG3_UTILS_OLD_OPTS
130       environment variable or using '--old' (or '-O) as the first option.
131
132       -b=EACH_KIB
133              where EACH_KIB is the number of Kilobytes (i.e. 1024 byte units)
134              to  be  transferred  by each READ BUFFER command. Similar to the
135              --buffer=EACH option in the main description but the  units  are
136              different.
137
138       -d     use  direct  IO  if available. Equivalent to the --dio option in
139              the main description.
140
141       -m     use memory mapped IO if  available.  Equivalent  to  the  --mmap
142              option in the main description.
143
144       -N     switch to the newer style options.
145
146       -q     only  transfer  the  data  into kernel buffers (typically by DMA
147              from the SCSI adapter card) and do not move  it  into  the  user
148              space.   Equivalent  to  the --quick option in the main descrip‐
149              tion.
150
151       -s=OVERALL_MIB
152              where OVERALL_MIB is the size of  total  transfer  in  Megabytes
153              (1048576  bytes).  Similar  to  the --size=OVERALL option in the
154              main description but the units are different.
155
156       -t     times the bulk data transfer component of this command.  Equiva‐
157              lent to the --time option in the main description.
158
159       -v     increase level of verbosity. Can be used multiple times.
160
161       -V     print out version string then exit.
162

AUTHOR

164       Written by Douglas Gilbert
165

REPORTING BUGS

167       Report bugs to <dgilbert at interlog dot com>.
168
170       Copyright © 2000-2007 Douglas Gilbert
171       This  software is distributed under the GPL version 2. There is NO war‐
172       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
173       POSE.
174

SEE ALSO

176       sg_read_buffer, sg_write_buffer, sg_test_rwbuf(all in sg3_utils)
177
178
179
180sg3_utils-1.23                   January 2007                       SG_RBUF(8)
Impressum