usr.sbin/spi/spi.8

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