1STRUCT SPI_TRANSFER(9) Serial Peripheral Interface (S STRUCT SPI_TRANSFER(9)
2
6 struct_spi_transfer - a read/write buffer pair
7
9 struct spi_transfer {
10 const void * tx_buf;
11 void * rx_buf;
12 unsigned len;
13 dma_addr_t tx_dma;
14 dma_addr_t rx_dma;
15 unsigned cs_change:1;
16 u8 bits_per_word;
17 u16 delay_usecs;
18 u32 speed_hz;
19 struct list_head transfer_list;
20 };
21
23 tx_buf
24 data to be written (dma-safe memory), or NULL
25 rx_buf
27 data to be read (dma-safe memory), or NULL
28 len
30 size of rx and tx buffers (in bytes)
31 tx_dma
33 DMA address of tx_buf, if spi_message.is_dma_mapped
34 rx_dma
36 DMA address of rx_buf, if spi_message.is_dma_mapped
37 cs_change
39 affects chipselect after this transfer completes
40 bits_per_word
42 select a bits_per_word other than the device default for this
43 transfer. If 0 the default (from spi_device) is used.
44 delay_usecs
46 microseconds to delay after this transfer before (optionally)
47 changing the chipselect status, then starting the next transfer or
48 completing this spi_message.
49 speed_hz
51 Select a speed other than the device default for this transfer. If
52 0 the default (from spi_device) is used.
53 transfer_list
55 transfers are sequenced through spi_message.transfers
56
58 SPI transfers always write the same number of bytes as they read.
59 Protocol drivers should always provide rx_buf and/or tx_buf. In some
60 cases, they may also want to provide DMA addresses for the data being
61 transferred; that may reduce overhead, when the underlying driver uses
62 dma.
63 If the transmit buffer is null, zeroes will be shifted out while
65 filling rx_buf. If the receive buffer is null, the data shifted in will
66 be discarded. Only “len” bytes shift out (or in). It's an error to try
67 to shift out a partial word. (For example, by shifting out three bytes
68 with word size of sixteen or twenty bits; the former uses two bytes per
69 word, the latter uses four bytes.)
70 In-memory data values are always in native CPU byte order, translated
72 from the wire byte order (big-endian except with SPI_LSB_FIRST). So for
73 example when bits_per_word is sixteen, buffers are 2N bytes long (len =
74 2N) and hold N sixteen bit words in CPU byte order.
75 When the word size of the SPI transfer is not a power-of-two multiple
77 of eight bits, those in-memory words include extra bits. In-memory
78 words are always seen by protocol drivers as right-justified, so the
79 undefined (rx) or unused (tx) bits are always the most significant
80 bits.
81 All SPI transfers start with the relevant chipselect active. Normally
83 it stays selected until after the last transfer in a message. Drivers
84 can affect the chipselect signal using cs_change.
85 (i) If the transfer isn't the last one in the message, this flag is
87 used to make the chipselect briefly go inactive in the middle of the
88 message. Toggling chipselect in this way may be needed to terminate a
89 chip command, letting a single spi_message perform all of group of chip
90 transactions together.
91 (ii) When the transfer is the last one in the message, the chip may
93 stay selected until the next transfer. On multi-device SPI busses with
94 nothing blocking messages going to other devices, this is just a
95 performance hint; starting a message to another device deselects this
96 one. But in other cases, this can be used to ensure correctness. Some
97 devices need protocol transactions to be built from a series of
98 spi_message submissions, where the content of one message is determined
99 by the results of previous messages and where the whole transaction
100 ends when the chipselect goes intactive.
101 The code that submits an spi_message (and its spi_transfers) to the
103 lower layers is responsible for managing its memory. Zero-initialize
104 every field you don't set up explicitly, to insulate against future API
105 updates. After you submit a message and its transfers, ignore them
106 until its completion callback.
107
109Kernel Hackers Manual 3.10 June 2019 STRUCT SPI_TRANSFER(9)