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] [--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
32       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

OPTIONS

38       Arguments to long options are mandatory for short options as well.
39
40       -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
48       -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
56       -h, --help
57              print usage message then exit.
58
59       -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
66       -O, --old
67              Switch to older style options. Please use as first option.
68
69       -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
75       -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
82       -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
88       -v, --verbose
89              increase level of verbosity. Can be used multiple times.
90
91       -V, --version
92              print out version string then exit.
93

NOTES

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
102       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

EXAMPLES

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
117       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

EXIT STATUS

128       The  exit  status  of sg_rbuf is 0 when it is successful. Otherwise see
129       the sg3_utils(8) man page.
130

OLDER COMMAND LINE OPTIONS

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
138       -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
144       -d     use  direct  IO  if available. Equivalent to the --dio option in
145              the main description.
146
147       -m     use memory mapped IO if  available.  Equivalent  to  the  --mmap
148              option in the main description.
149
150       -N, --new
151              Switch to the newer style options.
152
153       -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
158       -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
163       -t     times the bulk data transfer component of this command.  Equiva‐
164              lent to the --time option in the main description.
165
166       -v     increase level of verbosity. Can be used multiple times.
167
168       -V     print out version string then exit.
169

ENVIRONMENT VARIABLES

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

AUTHOR

178       Written by Douglas Gilbert
179

REPORTING BUGS

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

SEE ALSO

190       sg_read_buffer, sg_write_buffer, sg_test_rwbuf(all in sg3_utils)
191
192
193
194sg3_utils-1.43                   October 2017                       SG_RBUF(8)
Impressum