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