1 .\" Copyright (c) 2018 by S.F.T. Inc.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .Nd communicate on SPI bus with slave devices
38 .Op Fl C Ar command-bytes
40 .Op Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw
53 utility can be used to perform raw data transfers
54 .Pq read, write, or simultaneous read/write
55 with devices on the SPI bus, via the
61 device is associated with a specific
64 pin on the spibus, and therefore needs to be specified.
65 If no device name is specified on the command line,
70 For more information on the spigen device, see
73 The options are as follows:
74 .Bl -tag -width "-f device"
77 Both read and write data is input and output as
78 2-character hexadecimal values, optionally separated by white space,
80 When combined with the
82 flag, the data on stdin remains a sequence of ASCII hexadecimal
83 byte values, but the output reverts to binary mode.
88 Only has an effect when
91 Reverts the output back to binary
92 .Pq rather than ASCII ,
93 while leaving the input format as-is.
94 Use in combination with
96 to allow using something like
98 to pass hexadecimal values to the SPI device, but output the received data
100 .It Fl C Ar command-bytes
101 Sends one or more command bytes,
102 skipping any bytes read-in during the transfer.
103 The byte values should be specified as a quoted parameter, similar to the
104 format for data on stdin for
106 that is, 2 character hexadecimal values, optionally separated by white space.
107 An SPI device will typically require that a command be sent, followed by
109 You can use this option to send the command without receiving any data bytes
110 during the command sequence.
112 The total number of bytes to transfer as a decimal integer.
113 If a write or a read/write transaction is being performed, and fewer than
114 this number of bytes are read in from stdin, the remaining bytes will be
117 If the length can be determined from the input file size, you can use a
121 to base the transfer on the input file's size.
122 .It Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw
123 Transfer direction: Use
129 for simultaneous read and write.
132 .Pq default is Pa /dev/spigen0 .
134 Print help text to stderr, explaining the command line options.
136 Displays information about the SPI device to stderr.
137 Whenever this flag is specified, no data is read or written, and the mode
138 and clock speed are not changed.
141 The default is MSB, i.e., the highest order bit is
145 caused the LSB to be transmitted and read first.
146 .It Fl m Cm 0 Ns | Ns Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3
147 SPI mode, 0 through 3.
148 This defines the clock phase and timing with respect to reading and writing
149 data, as per the SPI specification.
151 Specify the maximum speed, in Hz, for the SPI clock.
152 The bus will operate at its highest available speed which does not
155 Specifies Verbose mode.
156 Diagnostics and information are written to stderr.
159 more than once to increase verbosity.
162 Here are a few examples of using the spi utility:
165 Get information about the default SPI device
170 Set the maximum clock speed to 200Khz and the mode to 3 on spigen0.1, but do
171 not transmit nor receive any data
173 spi -f spigen0.1 -s 200000 -m 3
176 Send a command sequence consisting of 2 bytes, and read 2 additional bytes
177 from the SPI device, using the current mode and speed on the default device
179 spi -d r -C "00 01" -c 2
182 Transmit a byte value of 5, and receive 2 bytes, displaying their values as
183 2-byte ASCII hexadecimal, with mode 2, and a maximum clock speed of 500khz.
185 echo "05" | spi -A -d rw -m 2 -s 500000 -c 2
188 Send a binary file, and output the SPI result through
190 as hexadecimal bytes, using the current maximum clock speed and SPI mode.
192 spi -d rw -c -1 <input_file.bin | od -An -t x1
195 Send 2 bytes of data, receive a total of 4 bytes, and output the SPI result
196 as binary data, piped through
198 displaying it as two hexadecimal unsigned short integer values.
200 echo "00 01" | spi -A -b -d rw -c 4 | od -t x2
203 Query the manufacturer ID and size from a standard spiflash device, by
204 sending the command byte 0x9f and displaying the 3-byte reply in ASCII hex.
206 spi -f spigen0.0 -m 0 -s 1000000 -d r -c 3 -A -C 9f