1.\" Copyright (c) 2018 by S.F.T. Inc. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 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. 11.\" 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 22.\" SUCH DAMAGE. 23.\" 24.Dd August 21, 2020 25.Dt SPI 8 26.Os 27.Sh NAME 28.Nm spi 29.Nd communicate on SPI bus with slave devices 30.Sh SYNOPSIS 31.Nm 32.Op Fl A 33.Op Fl b 34.Op Fl L 35.Op Fl v 36.Op Fl C Ar command-bytes 37.Op Fl c Ar count 38.Op Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw 39.Op Fl f Ar device 40.Op Fl m Ar mode 41.Op Fl S 42.Op Fl s Ar max-speed 43.Nm 44.Op Fl i 45.Op Fl v 46.Op Fl f Ar device 47.Nm 48.Op Fl h 49.Sh DESCRIPTION 50The 51.Nm 52utility can be used to perform raw data transfers 53.Pq read, write, or simultaneous read/write 54with devices on the SPI bus, via the 55.Xr spigen 4 56device. 57.Pp 58Each 59.Xr spigen 4 60device is associated with a specific 61.Dq chip select 62.Pq cs 63pin on the spibus, and therefore needs to be specified. 64If no device name is specified on the command line, 65.Nm 66assumes 67.Dq spigen0.0 . 68.Pp 69For more information on the spigen device, see 70.Xr spigen 4 . 71.Pp 72The options are as follows: 73.Bl -tag -width "-f device" 74.It Fl A 75Specifies ASCII mode. 76Both read and write data is input and output as 772-character hexadecimal values, optionally separated by white space, 78such as 00 01 02 etc. 79When combined with the 80.Fl b 81flag, the data on stdin remains a sequence of ASCII hexadecimal 82byte values, but the output reverts to binary mode. 83.It Fl b 84Binary 85.Pq output 86mode. 87Only has an effect when 88.Fl A 89has been specified. 90Reverts the output back to binary 91.Pq rather than ASCII , 92while leaving the input format as-is. 93Use in combination with 94.Fl A 95to allow using something like 96.Dq echo 97to pass hexadecimal values to the SPI device, but output the received data 98on stdout as binary. 99.It Fl C Ar command-bytes 100Sends one or more command bytes, 101skipping any bytes read-in during the transfer. 102The byte values should be specified as a quoted parameter, similar to the 103format for data on stdin for 104.Fl A , 105that is, 2 character hexadecimal values, optionally separated by white space. 106An SPI device will typically require that a command be sent, followed by 107bytes of data. 108You can use this option to send the command without receiving any data bytes 109during the command sequence. 110.It Fl c Ar count 111The total number of bytes to transfer as a decimal integer. 112If a write or a read/write transaction is being performed, and fewer than 113this number of bytes are read in from stdin, the remaining bytes will be 114sent with a value of 115.Dq 0 . 116If the length can be determined from the input file size, you can use a 117.Ar count 118value of 119.Dq -1 120to base the transfer on the input file's size. 121.It Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw 122Transfer direction: Use 123.Cm r 124for read, 125.Cm w 126for write, and 127.Cm rw 128for simultaneous read and write. 129.It Fl f Ar device 130SPI device to use 131.Pq default is Pa /dev/spigen0 . 132.It Fl h 133Print help text to stderr, explaining the command line options. 134.It Fl i 135Displays information about the SPI device to stderr. 136Whenever this flag is specified, no data is read or written, and the mode 137and clock speed are not changed. 138.It Fl L 139LSB bit order. 140The default is MSB, i.e., the highest order bit is 141transmitted first. 142Specifying 143.Fl L 144caused the LSB to be transmitted and read first. 145.It Fl m Cm 0 Ns | Ns Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 146SPI mode, 0 through 3. 147This defines the clock phase and timing with respect to reading and writing 148data, as per the SPI specification. 149.It Fl S 150Constantly stream from 151.Xr stdin 3 152to the 153.Nm 154bus. 155.It Fl s Ar speed 156Specify the maximum speed, in Hz, for the SPI clock. 157The bus will operate at its highest available speed which does not 158exceed this maximum. 159.It Fl v 160Specifies Verbose mode. 161Diagnostics and information are written to stderr. 162You can specify 163.Fl v 164more than once to increase verbosity. 165.El 166.Sh EXAMPLES 167Here are a few examples of using the spi utility: 168.Bl -bullet 169.It 170Get information about the default SPI device 171.Bd -literal 172spi -i 173.Ed 174.It 175Set the maximum clock speed to 200Khz and the mode to 3 on spigen0.1, but do 176not transmit nor receive any data 177.Bd -literal 178spi -f spigen0.1 -s 200000 -m 3 179.Ed 180.It 181Send a command sequence consisting of 2 bytes, and read 2 additional bytes 182from the SPI device, using the current mode and speed on the default device 183.Bd -literal 184spi -d r -C "00 01" -c 2 185.Ed 186.It 187Transmit a byte value of 5, and receive 2 bytes, displaying their values as 1882-byte ASCII hexadecimal, with mode 2, and a maximum clock speed of 500khz. 189.Bd -literal 190echo "05" | spi -A -d rw -m 2 -s 500000 -c 2 191.Ed 192.It 193Send a binary file, and output the SPI result through 194.Xr od 1 195as hexadecimal bytes, using the current maximum clock speed and SPI mode. 196.Bd -literal 197spi -d rw -c -1 <input_file.bin | od -An -t x1 198.Ed 199.It 200Send 2 bytes of data, receive a total of 4 bytes, and output the SPI result 201as binary data, piped through 202.Xr od 1 , 203displaying it as two hexadecimal unsigned short integer values. 204.Bd -literal 205echo "00 01" | spi -A -b -d rw -c 4 | od -t x2 206.Ed 207.It 208Query the manufacturer ID and size from a standard spiflash device, by 209sending the command byte 0x9f and displaying the 3-byte reply in ASCII hex. 210.Bd -literal 211spi -f spigen0.0 -m 0 -s 1000000 -d r -c 3 -A -C 9f 212.Ed 213.El 214.Sh SEE ALSO 215.Xr spigen 4 216.Sh HISTORY 217The 218.Nm 219utility 220appeared in 221.Fx 11.3 . 222