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