4863a70395
- Remove trailing whitespace - Address igor and mandoc warnings - Sort options - Use macros consistently (e.g., Fl for flags, Dq for quoting, Bd for code blocks) - Add a history section - Fix incorrect use of macros in various places MFC after: 2 weeks
217 lines
6.2 KiB
Groff
217 lines
6.2 KiB
Groff
.\" 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 .
|