PREV_LEC | NEXT_LEC

Quick Recap: What Is SPI?

SPI (Serial Peripheral Interface) is a synchronous, full-duplex bus used to connect a controller to one or more peripheral chips such as flash memory, ADCs, DACs, sensors, and displays. Every SPI transaction is clocked by the controller — peripherals never generate the clock themselves.

Because one controller can drive several peripherals, each peripheral needs its own chip-select line. That single fact — “which chip select does this device use?” — is exactly the piece of information the kernel needs before it can create a struct spi_device for your driver to bind to. This is where device instantiation comes in.

Two Ways to Instantiate an SPI Device

In both cases the destination is identical: a populated struct spi_device that the SPI core matches against a registered spi_driver. Only the source of that information changes.

The Old Way: Board Files

Before device tree existed, every board had a hand-written C file under arch/<architecture>/mach-<board>/ that described all the hardware present on that board, including SPI devices. This is only relevant today on systems that still boot without a device tree, which is now rare. It is worth understanding for legacy code you may encounter, but you should not write new drivers this way.

struct my_platform_data {
    int  foo;
    bool bar;
};

static struct my_platform_data mpfd = {
    .foo = 15,
    .bar = true,
};

static struct spi_board_info my_board_spi_info[] __initdata = {
    {
        .modalias       = "ep-spi-demo",   /* must match spi_driver name */
        .max_speed_hz   = 1000000,
        .bus_num        = 0,
        .chip_select    = 0,
        .platform_data  = &mpfd,
        .mode           = SPI_MODE_0,
    },
};

static int __init board_init(void)
{
    return spi_register_board_info(my_board_spi_info,
                                    ARRAY_SIZE(my_board_spi_info));
}

Why it is deprecated: board files hard-code hardware details in kernel C source, which means a new board needs a kernel rebuild. Device tree separates hardware description from kernel code, so the same kernel image can support many boards. On current kernels, spi_register_board_info() still exists in the SPI core for backward compatibility, but almost no active driver relies on it — device tree (or ACPI on x86) has replaced it everywhere.

The Modern Way: Device Tree

An SPI device is declared as a child node of its SPI controller node in the device tree. The controller node already defines #address-cells = <1> and #size-cells = <0>, which tells the parser that the child’s reg property is a single one-cell address with no size — that single cell is the chip select index, not a memory address.

&spi0 {
    status = "okay";
    #address-cells = <1>;
    #size-cells = <0>;

    ep_spi_demo: ep-spi-demo@0 {
        compatible     = "embeddedpathashala,ep-spi-demo";
        reg            = <0>;              /* chip select 0 */
        spi-max-frequency = <4000000>;      /* 4 MHz cap */
        spi-cpha;                            /* clock phase shifted */
        ep,sample-rate = <100>;              /* custom application property */
    };
};

Defining and Registering the SPI Driver

Once the device tree node exists, the kernel needs a matching spi_driver to bind to it. The pattern has three parts: a match table, the probe/remove callbacks, and the driver structure itself.

/* 1. Device tree match table */
static const struct of_device_id ep_spi_of_match[] = {
    { .compatible = "embeddedpathashala,ep-spi-demo" },
    { }
};
MODULE_DEVICE_TABLE(of, ep_spi_of_match);

/* 2. Fallback ID table (used when matching by name, not by DT) */
static const struct spi_device_id ep_spi_id[] = {
    { "ep-spi-demo", 0 },
    { }
};
MODULE_DEVICE_TABLE(spi, ep_spi_id);

/* 3. Driver structure */
static struct spi_driver ep_spi_driver = {
    .driver = {
        .name           = "ep_spi_dtreg_demo",
        .of_match_table = ep_spi_of_match,
    },
    .probe    = ep_spi_probe,
    .remove   = ep_spi_remove,
    .id_table = ep_spi_id,
};
module_spi_driver(ep_spi_driver);

MODULE_DEVICE_TABLE() exports the compatible string so that user-space module loading tools (udev/modprobe) can auto-load your module when a matching device tree node is present. module_spi_driver() is a helper macro that generates the boilerplate module_init()/module_exit() pair for a driver that has no special init/exit needs — you saw this same helper in the earlier probe/remove lecture.

Kernel 6.x Modernizations to Know

Complete Example: ep_spi_dtreg_demo

This original driver demonstrates the full path: a device tree node is matched, the driver’s probe() runs, and it reads back both standard and custom properties.

#include <linux/module.h>
#include <linux/spi/spi.h>
#include <linux/of.h>
#include <linux/property.h>

static int ep_spi_probe(struct spi_device *spi)
{
    u32 sample_rate = 0;
    bool cpha_set;

    dev_info(&spi->dev, "ep_spi_dtreg_demo: probing device\n");
    dev_info(&spi->dev, "  chip select : %d\n", spi_get_chipselect(spi, 0));
    dev_info(&spi->dev, "  max speed   : %u Hz\n", spi->max_speed_hz);
    dev_info(&spi->dev, "  controller  : spi%d\n", spi->controller->bus_num);

    cpha_set = device_property_read_bool(&spi->dev, "spi-cpha");
    dev_info(&spi->dev, "  cpha requested : %s\n", cpha_set ? "yes" : "no");

    if (device_property_read_u32(&spi->dev, "ep,sample-rate", &sample_rate) == 0)
        dev_info(&spi->dev, "  ep,sample-rate = %u\n", sample_rate);

    return 0;
}

static void ep_spi_remove(struct spi_device *spi)
{
    dev_info(&spi->dev, "ep_spi_dtreg_demo: removing device\n");
}

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

static const struct spi_device_id ep_spi_id[] = {
    { "ep-spi-demo", 0 },
    { }
};
MODULE_DEVICE_TABLE(spi, ep_spi_id);

static struct spi_driver ep_spi_driver = {
    .driver = {
        .name           = "ep_spi_dtreg_demo",
        .of_match_table = ep_spi_of_match,
    },
    .probe    = ep_spi_probe,
    .remove   = ep_spi_remove,
    .id_table = ep_spi_id,
};
module_spi_driver(ep_spi_driver);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Demo SPI driver showing device tree registration");

Build and Test Workflow

Save the DT snippet shown earlier as an overlay source file, and the driver code above as ep_spi_dtreg_demo.c.

# Compile the device tree overlay
dtc -@ -I dts -O dtb -o ep-spi-demo.dtbo ep-spi-demo-overlay.dts

# Copy it to the firmware overlays directory (path varies by board)
sudo cp ep-spi-demo.dtbo /boot/firmware/overlays/

# Apply it (or add it to config.txt / your bootloader config and reboot)
sudo dtoverlay ep-spi-demo

# Build the kernel module
make -C /lib/modules/$(uname -r)/build M=$(pwd) modules

# Load the module
sudo insmod ep_spi_dtreg_demo.ko

# Check the kernel log
dmesg | tail -n 10

Expected dmesg output:

ep_spi_dtreg_demo: probing device
  chip select : 0
  max speed   : 4000000 Hz
  controller  : spi0
  cpha requested : yes
  ep,sample-rate = 100

# Unload
sudo rmmod ep_spi_dtreg_demo

Common Mistakes and Troubleshooting

Best Practices

• Always prefer device tree over board files for any board built after ~2013
• Keep spi-max-frequency conservative until you have verified signal integrity at higher speeds
• Use device_property_* calls instead of of_property_* so your driver also works on ACPI-based systems without changes
• Export both an of_device_id and a spi_device_id table for maximum compatibility

Performance and Security Considerations

Performance: the SPI core enforces spi-max-frequency in hardware-relevant paths, so setting it too low needlessly caps throughput, while setting it above the device’s datasheet rating causes corrupted transfers. Security: validate any data read back from an SPI peripheral in your driver before exposing it to user space through sysfs or a character device — a compromised or faulty peripheral should never be able to crash the kernel or corrupt driver-internal state.

Real-World Use Cases

• SPI NOR/NAND flash storage declared as device tree children of the SPI controller
• TFT display controllers and e-paper panels bound via compatible strings
• ADC/DAC front-ends in industrial and measurement equipment
• TPM security chips connected over SPI

Summary and Key Takeaways

• SPI devices are represented in the kernel as struct spi_device, built either from a legacy board file or from a device tree node
• Board files are deprecated and only relevant on systems without device tree support
• The device tree reg property on an SPI child node means chip select index, not a memory address
• Standard SPI DT properties (spi-max-frequency, spi-cpol, spi-cpha, spi-cs-high) configure bus timing and polarity automatically
• A complete driver needs an of_device_id table, an optional spi_device_id table, and a registered spi_driver
• Kernel 6.x renamed spi_master to spi_controller and moved chip-select access behind spi_get_chipselect()

Conclusion

Understanding SPI device tree registration closes the gap between “I wrote a probe function” and “my driver actually gets called.” Once you can read and write the device tree node, choose the right standard properties, and register a matching spi_driver, you have everything needed to bring up real SPI peripherals on modern Linux boards. The next lecture in this free Linux device drivers course builds on this foundation with userspace SPI access using spidev, followed by half-duplex and full-duplex transfer patterns in real driver code.

Frequently Asked Questions

PREV_LEC | NEXT_LEC