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 "15 April 2018" 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 f Ar device 35.Op Fl d Ar r|w|rw 36.Op Fl m Ar mode 37.Op Fl s Ar max-speed 38.Op Fl c Ar count 39.Op Fl C Ar cmd_bytes 40.Op Fl A 41.Op Fl b 42.Op Fl L 43.Op Fl v 44.Nm 45.Op Fl i 46.Op Fl f Ar device 47.Op Fl v 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.Sq 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.Sq 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 ".Fl f Ar 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.Sq -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.Sq -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.Sq -A 96to allow using something like 97.Sq 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 102.Sq command 103bytes, skipping any bytes read-in during the transfer. 104The byte values should be specified as a quoted parameter, similar to the 105format for data on stdin for 106.Sq -A , 107that is, 2 character hexadecimal values, optionally separated by white space. 108An SPI device will typically require that a command be sent, followed by 109bytes of data. 110You can use this option to send the command without receiving any data bytes 111during the command sequence. 112.It Fl c Ar count 113The total number of bytes to transfer as a decimal integer. 114If a write or a read/write transaction is being performed, and fewer than 115this number of bytes are read in from stdin, the remaining bytes will be 116sent with a value of 117.Sq 0 . 118If the length can be determined from the input file size, you can use a 119.Sq count 120value of 121.Sq -1 122to base the transfer on the input file's size. 123.It Fl d Ar r|w|rw 124Transfer direction: Use 125.Sq r 126for read, 127.Sq w for write, and 128.Sq rw 129for simultaneous read and write. 130.It Fl f Ar device 131SPI device to use 132.Pq default is /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 -L caused the LSB to be transmitted and read first. 144.It Fl m Ar 0 - 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.Sq -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.Pp 165spi -i 166.It 167Set the maximum clock speed to 200Khz and the mode to 3 on spigen0.1, but do 168not transmit nor receive any data 169.Pp 170spi -f spigen0.1 -s 200000 -m 3 171.It 172Send a command sequence consisting of 2 bytes, and read 2 additional bytes 173from the SPI device, using the current mode and speed on the default device 174.Pp 175spi -d r -C "00 01" -c 2 176.It 177Transmit a byte value of 5, and receive 2 bytes, displaying their values as 1782-byte ASCII hexadecimal, with mode 2, and a maximum clock speed of 500khz. 179.Pp 180echo "05" | spi -A -d rw -m 2 -s 500000 -c 2 181.It 182Send a binary file, and output the SPI result through 183.Sq od 184as hexadecimal bytes, using the current maximum clock speed and SPI mode. 185.Pp 186spi -d rw -c -1 <input_file.bin | od -An -t x1 187.It 188Send 2 bytes of data, receive a total of 4 bytes, and output the SPI result 189as binary data, piped through 190.Sq od , 191displaying it as two hexadecimal unsigned short integer values. 192.Pp 193echo "00 01" | spi -A -b -d rw -c 4 | od -t x2 194.It 195Query the manufacturer ID and size from a standard spiflash device, by 196sending the command byte 0x9f and displaying the 3-byte reply in ASCII hex. 197.Pp 198spi -f spigen0.0 -m 0 -s 1000000 -d r -c 3 -A -C 9f 199 200.El 201.Pp 202.Sh SEE ALSO 203.Xr spigen 4 204