STRUCT SPI_MESSAGE(9) Serial Peripheral Interface (S STRUCT SPI_MESSAGE(9)NAME
struct_spi_message - one multi-segment SPI transaction
SYNOPSIS
struct spi_message {
struct list_head transfers;
struct spi_device * spi;
unsigned is_dma_mapped:1;
void (* complete) (void *context);
void * context;
unsigned actual_length;
int status;
struct list_head queue;
void * state;
};
MEMBERS
transfers
list of transfer segments in this transaction
spi
SPI device to which the transaction is queued
is_dma_mapped
if true, the caller provided both dma and cpu virtual addresses for each transfer buffer
complete
called to report transaction completions
context
the argument to complete when it's called
actual_length
the total number of bytes that were transferred in all successful segments
status
zero for success, else negative errno
queue
for use by whichever driver currently owns the message
state
for use by whichever driver currently owns the message
DESCRIPTION
A spi_message is used to execute an atomic sequence of data transfers, each represented by a struct spi_transfer. The sequence is "atomic"
in the sense that no other spi_message may use that SPI bus until that sequence completes. On some systems, many such sequences can execute
as as single programmed DMA transfer. On all systems, these messages are queued, and might complete after transactions to other devices.
Messages sent to a given spi_device are alway executed in FIFO order.
The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize
every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them
until its completion callback.
COPYRIGHT Kernel Hackers Manual 2.6. July 2010 STRUCT SPI_MESSAGE(9)
Check Out this Related Man Page
STRUCT SPI_TRANSFER(9) Serial Peripheral Interface (S STRUCT SPI_TRANSFER(9)NAME
struct_spi_transfer - a read/write buffer pair
SYNOPSIS
struct spi_transfer {
const void * tx_buf;
void * rx_buf;
unsigned len;
dma_addr_t tx_dma;
dma_addr_t rx_dma;
unsigned cs_change:1;
u8 bits_per_word;
u16 delay_usecs;
u32 speed_hz;
struct list_head transfer_list;
};
MEMBERS
tx_buf
data to be written (dma-safe memory), or NULL
rx_buf
data to be read (dma-safe memory), or NULL
len
size of rx and tx buffers (in bytes)
tx_dma
DMA address of tx_buf, if spi_message.is_dma_mapped
rx_dma
DMA address of rx_buf, if spi_message.is_dma_mapped
cs_change
affects chipselect after this transfer completes
bits_per_word
select a bits_per_word other than the device default for this transfer. If 0 the default (from spi_device) is used.
delay_usecs
microseconds to delay after this transfer before (optionally) changing the chipselect status, then starting the next transfer or
completing this spi_message.
speed_hz
Select a speed other than the device default for this transfer. If 0 the default (from spi_device) is used.
transfer_list
transfers are sequenced through spi_message.transfers
DESCRIPTION
SPI transfers always write the same number of bytes as they read. Protocol drivers should always provide rx_buf and/or tx_buf. In some
cases, they may also want to provide DMA addresses for the data being transferred; that may reduce overhead, when the underlying driver
uses dma.
If the transmit buffer is null, zeroes will be shifted out while filling rx_buf. If the receive buffer is null, the data shifted in will be
discarded. Only "len" bytes shift out (or in). It's an error to try to shift out a partial word. (For example, by shifting out three bytes
with word size of sixteen or twenty bits; the former uses two bytes per word, the latter uses four bytes.)
In-memory data values are always in native CPU byte order, translated from the wire byte order (big-endian except with SPI_LSB_FIRST). So
for example when bits_per_word is sixteen, buffers are 2N bytes long (len = 2N) and hold N sixteen bit words in CPU byte order.
When the word size of the SPI transfer is not a power-of-two multiple of eight bits, those in-memory words include extra bits. In-memory
words are always seen by protocol drivers as right-justified, so the undefined (rx) or unused (tx) bits are always the most significant
bits.
All SPI transfers start with the relevant chipselect active. Normally it stays selected until after the last transfer in a message. Drivers
can affect the chipselect signal using cs_change.
(i) If the transfer isn't the last one in the message, this flag is used to make the chipselect briefly go inactive in the middle of the
message. Toggling chipselect in this way may be needed to terminate a chip command, letting a single spi_message perform all of group of
chip transactions together.
(ii) When the transfer is the last one in the message, the chip may stay selected until the next transfer. On multi-device SPI busses with
nothing blocking messages going to other devices, this is just a performance hint; starting a message to another device deselects this one.
But in other cases, this can be used to ensure correctness. Some devices need protocol transactions to be built from a series of
spi_message submissions, where the content of one message is determined by the results of previous messages and where the whole transaction
ends when the chipselect goes intactive.
The code that submits an spi_message (and its spi_transfers) to the lower layers is responsible for managing its memory. Zero-initialize
every field you don't set up explicitly, to insulate against future API updates. After you submit a message and its transfers, ignore them
until its completion callback.
COPYRIGHT Kernel Hackers Manual 2.6. July 2010 STRUCT SPI_TRANSFER(9)