What You Will Learn

• The fields inside struct spi_device and what each one means to your driver
• The modern struct spi_driver registration model, including the void-returning remove() callback
• How CPOL and CPHA combine to form the four SPI clock modes
• How to move data with spi_sync(), spi_message, and spi_transfer
• A complete, original spi driver linux kernel example you can build and load today

Prerequisites

• Part 1 of this chapter (SPI bus fundamentals, wiring, chip select)
• Comfort writing and building an out-of-tree kernel module (Makefile, insmod, dmesg)
• A Linux system running kernel 6.x with kernel headers installed, and an SPI controller enabled (a Raspberry Pi with spi-bcm2835 or a similar board works well)

The struct spi_device: One Slave On The Bus

Every SPI peripheral your spi driver linux kernel module talks to is represented internally by an instance of struct spi_device, created for you automatically once the SPI core matches your driver against a real device (usually declared in the device tree). You never allocate this structure yourself in a client driver; you simply read the fields you need inside probe().

SPI Clock Modes: CPOL And CPHA

Getting the SPI mode wrong is the number one reason a brand-new spi driver linux kernel bring-up silently returns garbage data. The mode is built from two independent settings:

• CPOL (Clock Polarity) — whether the clock idles low (0) or idles high (1) when no data is being transferred
• CPHA (Clock Phase) — whether data is sampled on the first clock edge or the second clock edge of each bit period

The diagram below shows how the clock line’s idle state and active sampling edge change across the four modes, without any data bits drawn — just the concept of where the clock starts and which edge matters.

In practice, the overwhelming majority of real hardware you will meet uses SPI_MODE_0 or SPI_MODE_3. Always confirm the exact mode from the chip’s datasheet timing diagram rather than guessing.

The struct spi_driver: Registering Your Driver

Where spi_device represents one physical chip, struct spi_driver represents your driver’s registration with the SPI core — the probe/remove pair, the matching table, and the embedded struct device_driver. On modern kernels (5.18 and newer), the remove() callback is void-returning, matching the same modernization already applied to platform and I2C drivers in our earlier lectures.

Original Example: ep_spi_temp_demo Driver

The example below is an original driver written for this course, modeling a fictional SPI temperature sensor that exposes an 8-bit register at address 0x00. It demonstrates the modern registration pattern, half-duplex register read using spi_write_then_read(), and a full-duplex transfer using spi_sync() with two chained spi_transfer descriptors.

// ep_spi_temp_demo.c
// Original example driver for EmbeddedPathashala - free linux kernel development course
#include <linux/module.h>
#include <linux/spi/spi.h>
#include <linux/of.h>

#define EP_TEMP_REG_ADDR   0x00

struct ep_spi_temp {
    struct spi_device *spi;
};

/* Half-duplex style read: write the register address, then read the value */
static int ep_temp_read_reg(struct spi_device *spi, u8 reg, u8 *value)
{
    u8 tx = reg;
    return spi_write_then_read(spi, &tx, 1, value, 1);
}

/* Full-duplex style transfer: MOSI and MISO active in the same spi_sync call */
static int ep_temp_full_duplex_demo(struct spi_device *spi)
{
    u8 tx_buf[2] = { EP_TEMP_REG_ADDR, 0x00 };
    u8 rx_buf[2] = { 0 };
    struct spi_transfer xfer = {
        .tx_buf = tx_buf,
        .rx_buf = rx_buf,
        .len = 2,
    };
    struct spi_message msg;

    spi_message_init(&msg);
    spi_message_add_tail(&xfer, &msg);

    return spi_sync(spi, &msg);
}

static int ep_spi_temp_probe(struct spi_device *spi)
{
    struct ep_spi_temp *priv;
    u8 temp_val;
    int ret;

    priv = devm_kzalloc(&spi->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    priv->spi = spi;
    spi_set_drvdata(spi, priv);

    /* Configure clocking before first transfer */
    spi->mode = SPI_MODE_0;
    spi->bits_per_word = 8;
    ret = spi_setup(spi);
    if (ret)
        return ret;

    ret = ep_temp_read_reg(spi, EP_TEMP_REG_ADDR, &temp_val);
    if (ret)
        return ret;

    dev_info(&spi->dev, "ep_spi_temp_demo: register value = 0x%02x\n", temp_val);

    ret = ep_temp_full_duplex_demo(spi);
    if (ret)
        dev_warn(&spi->dev, "full duplex demo transfer failed: %d\n", ret);

    return 0;
}

/* Modern SPI remove callback returns void on kernel 5.18+ */
static void ep_spi_temp_remove(struct spi_device *spi)
{
    dev_info(&spi->dev, "ep_spi_temp_demo: driver removed\n");
}

static const struct of_device_id ep_spi_temp_of_match[] = {
    { .compatible = "ep,spi-temp-demo" },
    { }
};
MODULE_DEVICE_TABLE(of, ep_spi_temp_of_match);

static struct spi_driver ep_spi_temp_driver = {
    .driver = {
        .name = "ep_spi_temp_demo",
        .of_match_table = ep_spi_temp_of_match,
    },
    .probe = ep_spi_temp_probe,
    .remove = ep_spi_temp_remove,
};
module_spi_driver(ep_spi_temp_driver);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Original example SPI device driver for the free linux kernel development course");

A few points worth calling out about this spi driver linux kernel example:

• spi_write_then_read() is a small convenience wrapper the kernel provides specifically for the write-then-read register pattern so common in SPI peripherals — you do not need to build a spi_message by hand for this case.
• spi_sync() combined with a manually built spi_message/spi_transfer pair is the general-purpose way to run any custom transfer, including full-duplex transfers where tx_buf and rx_buf are both active on the same spi_transfer.
• module_spi_driver() is the same boilerplate-eliminating macro pattern you already saw for platform and I2C drivers — it generates module_init()/module_exit() for you.
• The remove callback returns void, not int, matching the kernel-wide modernization merged for SPI drivers.

Build And Test Workflow

$ make -C /lib/modules/$(uname -r)/build M=$(pwd) modules
$ sudo insmod ep_spi_temp_demo.ko
$ dmesg | tail -5
[  102.441823] ep_spi_temp_demo: register value = 0x1a
$ sudo rmmod ep_spi_temp_demo
$ dmesg | tail -2
[  118.220110] ep_spi_temp_demo: driver removed

The exact register value printed depends entirely on your target hardware — on real silicon it will reflect whatever the chip actually returns for that register address.

Common Mistakes And Troubleshooting

Best Practices, Performance, And Security Notes

• Always call spi_setup() after changing spi->mode, bits_per_word, or max_speed_hz, so the controller driver reconfigures its hardware registers
• Prefer devm_kzalloc() for driver-private memory so cleanup happens automatically on remove
• Batch related register reads/writes into one spi_message with multiple spi_transfer entries instead of issuing many separate spi_sync() calls, which reduces per-transfer overhead
• Validate any buffer length coming from user space before it reaches a spi_transfer, especially if you later expose this data through a character device or spidev-style interface

Summary And Key Takeaways

• struct spi_device describes one physical peripheral; struct spi_driver describes your driver’s registration and probe/remove logic
• SPI mode is built from CPOL and CPHA, giving four possible modes, with SPI_MODE_0 and SPI_MODE_3 being the most common in real hardware
• spi_write_then_read() is the convenient half-duplex helper; spi_sync() with spi_message/spi_transfer is the general-purpose transfer API and supports full-duplex operation
• The remove() callback is void-returning on modern kernels (5.18+), consistent with the platform and I2C driver modernization covered earlier in this free linux kernel development course

Frequently Asked Questions