share/man/man4/spigen.4

   1 .\"
   2 .\" Copyright (c) 2018 Ian Lepore <ian@freebsd.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd April 7, 2018
  29 .Dt SPIGEN 4
  30 .Os
  31 .Sh NAME
  32 .Nm spigen
  33 .Nd SPI generic I/O device driver
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel,
  36 place the following lines in your
  37 kernel configuration file:
  38 .Bd -ragged -offset indent
  39 .Cd "device spi"
  40 .Cd "device spibus"
  41 .Cd "device spigen"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 spigen_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 driver provides direct access to a slave device on the SPI bus.
  54 Each instance of a
  55 .Nm
  56 device is associated with a single chip-select
  57 line on the bus, and all I/O performed through that instance is done
  58 with that chip-select line asserted.
  59 .Pp
  60 SPI data transfers are inherently bi-directional; there are not separate
  61 read and write operations.
  62 When commands and data are sent to a device, data also comes back from
  63 the device, although in some cases the data may not be useful (or even
  64 documented or predictable for some devices).
  65 Likewise on a read operation, whatever data is in the buffer at the start
  66 of the operation is sent to (and typically ignored by) the device, with each
  67 outgoing byte then replaced in the buffer by the corresponding incoming byte.
  68 Thus, all buffers passed to the transfer functions are both input and
  69 output buffers.
  70 .Pp
  71 The
  72 .Nm
  73 driver provides access to the SPI slave device with the following
  74 .Xr ioctl 2
  75 calls, defined in
  76 .In sys/spigenio.h :
  77 .Bl -tag -width indent
  78 .It Dv SPIGENIOC_TRANSFER Pq Vt "struct spigen_transfer"
  79 Transfer a command and optional associated data to/from the device,
  80 using the buffers described by the st_command and st_data fields in the
  81 .Vt spigen_transfer .
  82 Set
  83 .Vt st_data.iov_len
  84 to zero if there is no data associated with the command.
  85 .Bd -literal
  86 struct spigen_transfer {
  87         struct iovec st_command;
  88         struct iovec st_data;
  89 };
  90 .Ed
  91 .It Dv SPIGENIOC_TRANSFER_MMAPPED Pq Vt "spigen_transfer_mmapped"
  92 Transfer a command and optional associated data to/from the device.
  93 The buffers for the transfer are a previously-mmap'd region.
  94 The length of the command and data within that region are described by the
  95 .Vt stm_command_length
  96 and
  97 .Vt stm_data_length
  98 fields of
  99 .Vt spigen_transfer_mmapped .
 100 If
 101 .Vt stm_data_length
 102 is non-zero, the data appears in the memory region immediately
 103 following the command (that is, at offset
 104 .Vt stm_command_length
 105 from the start of the mapped region).
 106 .Bd -literal
 107 struct spigen_transfer_mmapped {
 108         size_t stm_command_length;
 109         size_t stm_data_length;
 110 };
 111 .Ed
 112 .It Dv SPIGENIOC_GET_CLOCK_SPEED Pq Vt uint32_t
 113 Get the maximum clock speed (bus frequency in Hertz) to be used
 114 when communicating with this slave device.
 115 .It Dv SPIGENIOC_SET_CLOCK_SPEED Pq Vt uint32_t
 116 Set the maximum clock speed (bus frequency in Hertz) to be used
 117 when communicating with this slave device.
 118 The setting remains in effect for subsequent transfers; it
 119 is not necessary to reset this before each transfer.
 120 The actual bus frequency may be lower due to hardware limitiations
 121 of the SPI bus controller device.
 122 .It Dv SPIGENIOC_GET_SPI_MODE Pq Vt uint32_t
 123 Get the SPI mode (clock polarity and phase) to be used
 124 when communicating with this device.
 125 .It Dv SPIGENIOC_SET_SPI_MODE Pq Vt uint32_t
 126 Set the SPI mode (clock polarity and phase) to be used
 127 when communicating with this device.
 128 The setting remains in effect for subsequent transfers; it
 129 is not necessary to reset this before each transfer.
 130 .El
 131 .Sh HINTS CONFIGURATION
 132 On a
 133 .Xr device.hints 5
 134 based system, such as
 135 .Li MIPS ,
 136 these values are configurable for
 137 .Nm :
 138 .Bl -tag -width indent
 139 .It Va hint.spigen.%d.at
 140 The spibus the
 141 .Nm
 142 instance is attached to.
 143 .It Va hint.spigen.%d.clock
 144 The maximum bus frequency to use when communicating with this device.
 145 Actual bus speed may be lower, depending on the capabilities of the SPI
 146 bus controller hardware.
 147 .It Va hint.spigen.%d.cs
 148 The chip-select number to assert when performing I/O for this device.
 149 Set the high bit (1 << 31) to invert the logic level of the chip select line.
 150 .It Va hint.spigen.%d.mode
 151 The SPI mode (0-3) to use when communicating with this device.
 152 .El
 153 .Sh FDT CONFIGURATION
 154 On an
 155 .Xr fdt 4
 156 based system, the spigen device is defined as a slave device subnode
 157 of the SPI bus controller node.
 158 All properties documented in the
 159 .Va spibus.txt
 160 bindings document can be used with the
 161 .Nm
 162 device.
 163 The most commonly-used ones are documented below.
 164 .Pp
 165 The following properties are required in the
 166 .Nm
 167 device subnode:
 168 .Bl -tag -width indent
 169 .It Va compatible
 170 Must be the string "freebsd,spigen".
 171 .It Va reg
 172 Chip select address of device.
 173 .It Va spi-max-frequency
 174 The maximum bus frequency to use when communicating with this slave device.
 175 Actual bus speed may be lower, depending on the capabilities of the SPI
 176 bus controller hardware.
 177 .El
 178 .Pp
 179 The following properties are optional for the
 180 .Nm
 181 device subnode:
 182 .Bl -tag -width indent
 183 .It Va spi-cpha
 184 Empty property indicating the slave device requires shifted clock
 185 phase (CPHA) mode.
 186 .It Va spi-cpol
 187 Empty property indicating the slave device requires inverse clock
 188 polarity (CPOL) mode.
 189 .It Va spi-cs-high
 190 Empty property indicating the slave device requires chip select active high.
 191 .El
 192 .Sh FILES
 193 .Bl -tag -width -compact
 194 .It Pa /dev/spigen*
 195 .El
 196 .Sh SEE ALSO
 197 .Xr fdt 4 ,
 198 .Xr device.hints 5
 199 .Sh HISTORY
 200 The
 201 .Nm
 202 driver
 203 appeared in
 204 .Fx 11.0 .
 205 FDT support appeared in
 206 .Fx 11.2 .