Why Chain Multiple SPI Transfers?

Many real SPI devices need more than one back-to-back exchange to complete a single logical operation. A flash chip might need a command byte written, followed by an address, followed by a data read — all while the chip select line stays asserted the whole time. If you closed the chip select (CS) line between each of these steps, the device would treat them as three unrelated transactions and the operation would fail.

This is exactly the problem that chaining spi_transfer structures inside a single spi_message solves. Every transfer you add to the message runs in sequence over the wire, and you control whether CS toggles between each transfer using the cs_change field.

Understanding cs_change

The cs_change field of struct spi_transfer tells the SPI core what to do with the chip select line after that particular transfer finishes:

For a simple “write register address, then read the data” sequence, you almost always want cs_change = 0 on every transfer except the last one, so the device sees one uninterrupted transaction.

Original Driver: ep_spi_multixfer_demo

Below is an original, from-scratch driver example (not copied from any book) that reads a device register using a two-transfer chained message. It builds on the ep_spi_msg_demo driver introduced in the previous lecture and targets kernel 6.x.

#define EP_REG_READ_CMD   0x80

struct ep_spi_multixfer {
    struct spi_device *spi;
    struct mutex lock;
    u8 tx_cmd;
    u8 rx_val;
};

static int ep_multixfer_read_reg(struct ep_spi_multixfer *priv, u8 reg)
{
    struct spi_transfer xfers[2] = { };
    int ret;

    mutex_lock(&priv->lock);

    priv->tx_cmd = EP_REG_READ_CMD | reg;

    /* transfer 0: send the register address, keep CS asserted */
    xfers[0].tx_buf   = &priv->tx_cmd;
    xfers[0].len       = 1;
    xfers[0].cs_change  = 0;

    /* transfer 1: read back the register value, CS released after */
    xfers[1].rx_buf   = &priv->rx_val;
    xfers[1].len       = 1;

    ret = spi_sync_transfer(priv->spi, xfers, ARRAY_SIZE(xfers));

    mutex_unlock(&priv->lock);

    return ret;
}

Notice that this example uses spi_sync_transfer() instead of manually calling spi_message_init() and spi_message_add_tail() for every transfer. This is a modern helper — it builds the message internally and sends it in one call, so short chains like this one become far less boilerplate-heavy than the equivalent code in older kernel documentation.

spi_sync_transfer() vs Manual Message Building

spi_read, spi_write, and spi_write_then_read

For very small, simple exchanges, the SPI core also provides three convenience wrappers built on top of spi_sync(). Use them only for small amounts of data, since each one still allocates a temporary message internally.

int spi_read(struct spi_device *spi, void *buf, size_t len);
int spi_write(struct spi_device *spi, const void *buf, size_t len);
int spi_write_then_read(struct spi_device *spi,
                         const void *txbuf, unsigned n_tx,
                         void *rxbuf, unsigned n_rx);

• spi_read() — reads len bytes into buf with no data written first.
• spi_write() — writes len bytes from buf with nothing read back.
• spi_write_then_read() — writes n_tx bytes, then reads n_rx bytes, all with CS held across both halves — effectively a built-in two-transfer chain, and often a shorter way to write the exact driver shown above.

Putting It All Together: SPI Client Driver Checklist

We have now covered every building block of an SPI client driver across this chapter. Here is the complete checklist for writing one on kernel 6.x, recapping every earlier lecture in this free Linux kernel development course:

Build and Test Workflow

# build the module against your running kernel headers
make -C /lib/modules/$(uname -r)/build M=$PWD modules

# load it
sudo insmod ep_spi_multixfer_demo.ko

# confirm it bound to the device tree node
ls /sys/bus/spi/devices/

# check the kernel log for the probe message
dmesg | tail

Expected output in dmesg after a successful probe looks similar to:

ep_spi_multixfer_demo spi0.0: probed, register value = 0x2A

Common Mistakes

Best Practices and Performance Considerations

• Prefer spi_sync_transfer() for one-shot chained operations — it is less code and just as safe as manual message building.
• Batch related exchanges into a single message rather than issuing several separate spi_sync() calls, since each call has scheduling overhead.
• Protect shared driver state with a mutex, since spi_sync() and spi_sync_transfer() can sleep and must never be called from atomic context.
• For high-throughput paths, consider spi_async() with a completion callback instead of blocking the calling thread on every transfer.

Summary and Key Takeaways

• Chaining spi_transfer structs inside one spi_message lets you build multi-step SPI operations that stay atomic under one CS assertion.
• cs_change controls whether CS toggles between transfers or stays asserted through the whole message.
• spi_sync_transfer() is the modern, low-boilerplate way to send a short chain of transfers.
• spi_read(), spi_write(), and spi_write_then_read() cover the common small-data cases without building a message by hand.
• The five-step checklist in this lecture applies to every SPI client driver you will ever write on kernel 6.x.

Conclusion

This lecture closes the kernel-side half of the SPI driver-writing chapter in this free Linux device drivers course. You now know how to chain transfers correctly, which helper function fits which situation, and the full checklist for wiring a driver into the SPI core. In the next lecture of this free embedded Linux course, we move to the userspace side of SPI and see how the spidev driver lets applications talk to SPI hardware directly through /dev/spidevB.C, without writing any kernel code at all.

Frequently Asked Questions