STRUCT SPI_TRANSFER(9)

💅 struct spi_transfer(9)

okay so this is the Kernel API Manual page for struct spi_transfer(9) — the little struct that holds one read/write buffer pair. bestie, it's literally the atom of every SPI message, and it's giving main character energy. let's get into it 🎀

---

✨ NAME ✨

struct spi_transfer — a read/write buffer pair. that's it. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

struct spi_transfer {
    const void      *tx_buf;
    void *rx_buf;
    unsigned len;
  #define SPI_TRANS_FAIL_NO_START BIT(0);
  #define SPI_TRANS_FAIL_IO       BIT(1);
    u16 error;
    bool tx_sg_mapped;
    bool rx_sg_mapped;
    struct sg_table tx_sg;
    struct sg_table rx_sg;
    dma_addr_t tx_dma;
    dma_addr_t rx_dma;
    unsigned dummy_data:1;
    unsigned cs_off:1;
    unsigned cs_change:1;
    unsigned tx_nbits:4;
    unsigned rx_nbits:4;
  #define SPI_MULTI_LANE_MODE_SINGLE      0 ;
  #define SPI_MULTI_LANE_MODE_STRIPE      1 ;
  #define SPI_MULTI_LANE_MODE_MIRROR      2 ;
    unsigned multi_lane_mode: 2;
    unsigned timestamped:1;
    bool dtr_mode;
  #define SPI_NBITS_SINGLE        0x01 ;
  #define SPI_NBITS_DUAL          0x02 ;
  #define SPI_NBITS_QUAD          0x04 ;
  #define SPI_NBITS_OCTAL 0x08 ;
    u8 bits_per_word;
    struct spi_delay        delay;
    struct spi_delay        cs_change_delay;
    struct spi_delay        word_delay;
    u32 speed_hz;
    u32 effective_speed_hz;
    unsigned int    offload_flags;
    unsigned int    ptp_sts_word_pre;
    unsigned int    ptp_sts_word_post;
    struct ptp_system_timestamp *ptp_sts;
    struct list_head transfer_list;
 };

---

🌈 Members 🌈

okay this is the long part, but every single field matters, so we're doing all of them. no skips. periodt. 💅

• tx_buf — the data to be written (DMA-safe memory), or NULL. 🫶
• rx_buf — the data to be read (DMA-safe memory), or NULL.
• len — size of rx and tx buffers (in bytes). one number, both buffers, that's the deal 💖
• error — Error status logged by SPI controller driver.
• tx_sg_mapped — If true, the tx_sg is mapped for DMA.
• rx_sg_mapped — If true, the rx_sg is mapped for DMA.
• tx_sg — Scatterlist for transmit, currently not for client use. 👀
• rx_sg — Scatterlist for receive, currently not for client use.
• tx_dma — DMA address of tx_buf, currently not for client use.
• rx_dma — DMA address of rx_buf, currently not for client use.
• dummy_data — indicates transfer is dummy bytes transfer.
• cs_off — performs the transfer with chipselect off.
• cs_change — affects chipselect after this transfer completes. this one's a whole personality trait, see below 😭
• tx_nbits — number of bits used for writing. If 0 the default (SPI_NBITS_SINGLE) is used.
• rx_nbits — number of bits used for reading. If 0 the default (SPI_NBITS_SINGLE) is used.
• multi_lane_mode — How to serialize data on multiple lanes. One of the SPI_MULTI_LANE_MODE_* values.
• timestamped — true if the transfer has been timestamped. ⏱️
• dtr_mode — true if supports double transfer rate.
• 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 — delay to be introduced after this transfer before (optionally) changing the chipselect status, then starting the next transfer or completing this spi_message.
• cs_change_delay — delay between cs deassert and assert when cs_change is set and spi_transfer is not the last in spi_message.
• word_delay — inter word delay to be introduced after each word size (set by bits_per_word) transmission.
• speed_hz — Select a speed other than the device default for this transfer. If 0 the default (from spi_device) is used.
• effective_speed_hz — the effective SCK-speed that was used to transfer this transfer. Set to 0 if the SPI bus driver does not support it. (yes, "used to transfer this transfer" — the docs said it, we keep it, slay 💀)
• offload_flags — Flags that are only applicable to specialized SPI offload transfers. See SPI_OFFLOAD_XFER_* in spi-offload.h.
• ptp_sts_word_pre — The word (subject to bits_per_word semantics) offset within tx_buf for which the SPI device is requesting that the time snapshot for this transfer begins. Upon completing the SPI transfer, this value may have changed compared to what was requested, depending on the available snapshotting resolution (DMA transfer, ptp_sts_supported is false, etc).
• ptp_sts_word_post — See ptp_sts_word_pre. The two can be equal (meaning that a single byte should be snapshotted). If the core takes care of the timestamp (if ptp_sts_supported is false for this controller), it will set ptp_sts_word_pre to 0, and ptp_sts_word_post to the length of the transfer. This is done purposefully (instead of setting to spi_transfer->len - 1) to denote that a transfer-level snapshot taken from within the driver may still be of higher quality. 💯
• ptp_sts — Pointer to a memory location held by the SPI target device where a PTP system timestamp structure may lie. If drivers use PIO or their hardware has some sort of assist for retrieving exact transfer timing, they can (and should) assert ptp_sts_supported and populate this structure using the ptp_read_system_*ts helper functions. The timestamp must represent the time at which the SPI target device has processed the word, i.e. the "pre" timestamp should be taken before transmitting the "pre" word, and the "post" timestamp after receiving transmit confirmation from the controller for the "post" word. 🧚
• transfer_list — transfers are sequenced through spi_message.transfers.

---

👑 Description 👑

SPI transfers always write the same number of bytes as they read. like, that's the rule, no cap. 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.

🎀 the two cs_change moods 🎀

(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 inactive. 🦋

---

🌟 lanes & rates 🌟

When SPI can transfer in 1x,2x or 4x. It can get this transfer information from device through tx_nbits and rx_nbits. In Bi-direction, these two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x) SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer.

User may also set dtr_mode to true to use dual transfer mode if desired. if not, default considered as single transfer mode.

---

💜 memory manners 💜

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. fr fr, don't touch. 🙈

---

💖 SEE ALSO 💖

Kernel file ./include/linux/spi/spi.h struct spi_statistics(9), struct spi_delay(9), struct spi_device(9), struct spi_driver(9), spi_unregister_driver(9), module_spi_driver(9), struct spi_controller(9), struct spi_res(9), struct spi_message(9), spi_message_init_with_transfers(9), spi_is_bpw_supported(9), spi_bpw_to_bytes(9), spi_controller_xfer_timeout(9), struct spi_replaced_transfers(9), spi_sync_transfer(9), spi_write(9), spi_read(9), spi_w8r8(9), spi_w8r16(9), spi_w8r16be(9), struct spi_board_info(9)

---

ngl bestie, that was a LOT of fields, but you ate that. go forth and shift some bytes 💅

that's the whole page!! straight from ./include/linux/spi, dated October 2026 — see you in the next struct spi_transfer(9) reading, mwah 🍓💜