freebsd-skq/usr.sbin/spi/spi.8

.\" Copyright (c) 2018 by S.F.T. Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 21, 2020
.Dt SPI 8
.Os
.Sh NAME
.Nm spi
.Nd communicate on SPI bus with slave devices
.Sh SYNOPSIS
.Nm
.Op Fl A
.Op Fl b
.Op Fl L
.Op Fl v
.Op Fl C Ar command-bytes
.Op Fl c Ar count
.Op Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw
.Op Fl f Ar device
.Op Fl m Ar mode
.Op Fl s Ar max-speed
.Nm
.Op Fl i
.Op Fl v
.Op Fl f Ar device
.Nm
.Op Fl h
.Sh DESCRIPTION
The
.Nm
utility can be used to perform raw data transfers
.Pq read, write, or simultaneous read/write
with devices on the SPI bus, via the
.Xr spigen 4
device.
.Pp
Each
.Xr spigen 4
device is associated with a specific
.Dq chip select
.Pq cs
pin on the spibus, and therefore needs to be specified.
If no device name is specified on the command line,
.Nm
assumes
.Dq spigen0.0 .
.Pp
For more information on the spigen device, see
.Xr spigen 4 .
.Pp
The options are as follows:
.Bl -tag -width "-f device"
.It Fl A
Specifies ASCII mode.
Both read and write data is input and output as
2-character hexadecimal values, optionally separated by white space,
such as 00 01 02 etc.
When combined with the
.Fl b
flag, the data on stdin remains a sequence of ASCII hexadecimal
byte values, but the output reverts to binary mode.
.It Fl b
Binary
.Pq output
mode.
Only has an effect when
.Fl A
has been specified.
Reverts the output back to binary
.Pq rather than ASCII ,
while leaving the input format as-is.
Use in combination with
.Fl A
to allow using something like
.Dq echo
to pass hexadecimal values to the SPI device, but output the received data
on stdout as binary.
.It Fl C Ar command-bytes
Sends one or more command bytes,
skipping any bytes read-in during the transfer.
The byte values should be specified as a quoted parameter, similar to the
format for data on stdin for
.Fl A ,
that is, 2 character hexadecimal values, optionally separated by white space.
An SPI device will typically require that a command be sent, followed by
bytes of data.
You can use this option to send the command without receiving any data bytes
during the command sequence.
.It Fl c Ar count
The total number of bytes to transfer as a decimal integer.
If a write or a read/write transaction is being performed, and fewer than
this number of bytes are read in from stdin, the remaining bytes will be
sent with a value of
.Dq 0 .
If the length can be determined from the input file size, you can use a
.Ar count
value of
.Dq -1
to base the transfer on the input file's size.
.It Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw
Transfer direction: Use
.Cm r
for read,
.Cm w
for write, and
.Cm rw
for simultaneous read and write.
.It Fl f Ar device
SPI device to use
.Pq default is Pa /dev/spigen0 .
.It Fl h
Print help text to stderr, explaining the command line options.
.It Fl i
Displays information about the SPI device to stderr.
Whenever this flag is specified, no data is read or written, and the mode
and clock speed are not changed.
.It Fl L
LSB bit order.
The default is MSB, i.e., the highest order bit is
transmitted first.
Specifying
.Fl L
caused the LSB to be transmitted and read first.
.It Fl m Cm 0 Ns | Ns Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3
SPI mode, 0 through 3.
This defines the clock phase and timing with respect to reading and writing
data, as per the SPI specification.
.It Fl s Ar speed
Specify the maximum speed, in Hz, for the SPI clock.
The bus will operate at its highest available speed which does not
exceed this maximum.
.It Fl v
Specifies Verbose mode.
Diagnostics and information are written to stderr.
You can specify
.Fl v
more than once to increase verbosity.
.El
.Sh EXAMPLES
Here are a few examples of using the spi utility:
.Bl -bullet
.It
Get information about the default SPI device
.Bd -literal
spi -i
.Ed
.It
Set the maximum clock speed to 200Khz and the mode to 3 on spigen0.1, but do
not transmit nor receive any data
.Bd -literal
spi -f spigen0.1 -s 200000 -m 3
.Ed
.It
Send a command sequence consisting of 2 bytes, and read 2 additional bytes
from the SPI device, using the current mode and speed on the default device
.Bd -literal
spi -d r -C "00 01" -c 2
.Ed
.It
Transmit a byte value of 5, and receive 2 bytes, displaying their values as
2-byte ASCII hexadecimal, with mode 2, and a maximum clock speed of 500khz.
.Bd -literal
echo "05" | spi -A -d rw -m 2 -s 500000 -c 2
.Ed
.It
Send a binary file, and output the SPI result through
.Xr od 1
as hexadecimal bytes, using the current maximum clock speed and SPI mode.
.Bd -literal
spi -d rw -c -1 <input_file.bin | od -An -t x1
.Ed
.It
Send 2 bytes of data, receive a total of 4 bytes, and output the SPI result
as binary data, piped through
.Xr od 1 ,
displaying it as two hexadecimal unsigned short integer values.
.Bd -literal
echo "00 01" | spi -A -b -d rw -c 4 | od -t x2
.Ed
.It
Query the manufacturer ID and size from a standard spiflash device, by
sending the command byte 0x9f and displaying the 3-byte reply in ASCII hex.
.Bd -literal
spi -f spigen0.0 -m 0 -s 1000000 -d r -c 3 -A -C 9f
.Ed
.El
.Sh SEE ALSO
.Xr spigen 4
.Sh HISTORY
The
.Nm
utility
appeared in
.Fx 11.3 .