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