SPI 서브시스템 — SPI / QSPI

임베디드 Linux에서 고속 직렬 통신에 사용되는 SPI 서브시스템을 드라이버 개발 관점으로 정리합니다. SPI 프로토콜과 CPOL/CPHA 모드, spi_controller/spi_device 구조체, FIFO/DMA 기반 전송 경로, Quad/Octal SPI 및 XIP, Device Tree 바인딩, regmap을 활용한 레지스터(Register) 추상화까지 SPI 드라이버 개발에 필요한 핵심을 다룹니다.

SPI 프로토콜 기초

SPI (Serial Peripheral Interface)는 Motorola가 개발한 전이중(full-duplex) 동기 직렬 버스입니다. I2C보다 빠른 속도가 필요한 ADC, DAC, 디스플레이, Flash 메모리 등에 사용됩니다.

SPI 모드 (CPOL/CPHA)

SPI는 클럭 극성(CPOL)과 클럭 위상(CPHA) 조합으로 4가지 동작 모드를 정의합니다:

SPI 모드별 파형과 클럭 에지 동작

SPI의 4가지 모드는 CPOL(Clock Polarity)과 CPHA(Clock Phase) 비트 조합으로 결정됩니다. 데이터 시트에서 "상승 에지에서 샘플링"이라고 적혀 있다면 Mode 0 또는 Mode 3에 해당합니다. 아래 다이어그램은 각 모드의 SCK/MOSI/MISO 타이밍 관계를 보여줍니다.

Setup Time과 Hold Time

SPI 통신의 신뢰성은 setup time(t_SU)과 hold time(t_HD)에 의존합니다. Setup time은 샘플링 에지 전에 데이터가 안정되어야 하는 최소 시간이고, hold time은 샘플링 에지 후에 데이터가 유지되어야 하는 최소 시간입니다:

전이중(Full Duplex) vs 반이중(Half Duplex)

SPI는 기본적으로 전이중(Full Duplex) 통신을 지원합니다. 마스터가 MOSI로 데이터를 송신하는 동시에 MISO로 데이터를 수신합니다. 그러나 일부 디바이스는 단방향 또는 반이중 모드로 동작합니다:

전기적 특성과 신호 무결성

고속 SPI(10 MHz 이상)에서는 신호 무결성이 중요합니다. PCB 설계 시 다음 사항을 고려해야 합니다:

Linux SPI 서브시스템

SPI 서브시스템은 drivers/spi/에 구현되어 있으며 다음 핵심 구조체를 사용합니다:

spi_controller 구조

SPI 컨트롤러 드라이버의 핵심 콜백:

struct spi_controller {
    int (*setup)(struct spi_device *spi);
    int (*transfer_one_message)(struct spi_controller *ctlr,
                                 struct spi_message *msg);
    int (*transfer_one)(struct spi_controller *ctlr,
                         struct spi_device *spi,
                         struct spi_transfer *xfer);
    void (*set_cs)(struct spi_device *spi, bool enable);
    u32 min_speed_hz;
    u32 max_speed_hz;
    u16 num_chipselect;
    /* ... */
};

SPI 컨트롤러 레지스터 프로그래밍

SPI 컨트롤러 드라이버는 하드웨어 레지스터를 직접 프로그래밍하여 클럭 분주, FIFO 관리, DMA 채널 설정을 수행합니다. 아래 다이어그램은 SPI 컨트롤러 내부의 전송 데이터 경로를 보여줍니다.

클럭 분주(Divider) 계산

SPI 컨트롤러의 SCK 클럭 주파수는 부모 클럭(PCLK 또는 APB 클럭)을 분주하여 생성합니다. 대부분의 컨트롤러는 짝수 분주를 사용하며, 실제 속도가 요청 속도를 초과하지 않도록 올림 처리해야 합니다:

/* SPI 클럭 분주 계산: f_sck = f_pclk / (2 * (div + 1)) */
static u32 calc_spi_clk_div(u32 pclk_hz, u32 target_hz)
{
    u32 div;

    if (target_hz >= pclk_hz / 2)
        return 0;  /* 최소 분주 = 2배 */

    /* div = ceil(pclk / (2 * target)) - 1
     * 실제 속도가 target을 넘지 않도록 올림 처리 */
    div = DIV_ROUND_UP(pclk_hz, 2 * target_hz) - 1;

    /* 하드웨어 최대값 클램프 (예: 8-bit divider → 0~255) */
    return min_t(u32, div, 0xFF);
}

FIFO 관리와 Watermark 설정

TX/RX FIFO의 watermark 레벨은 인터럽트 빈도와 전송 효율의 균형을 결정합니다. Watermark가 너무 낮으면 인터럽트가 과다 발생하고, 너무 높으면 RX FIFO 오버플로 위험이 있습니다:

SPI 컨트롤러 드라이버 스켈레톤

#include <linux/spi/spi.h>
#include <linux/platform_device.h>
#include <linux/clk.h>
#include <linux/dmaengine.h>

#define SPI_CR1       0x00   /* Control Register 1 */
#define SPI_CR2       0x04   /* Control Register 2 */
#define SPI_SR        0x08   /* Status Register */
#define SPI_DR        0x0C   /* Data Register */
#define SPI_TXFR      0x10   /* TX FIFO Threshold */
#define SPI_RXFR      0x14   /* RX FIFO Threshold */

#define SPI_CR1_SPE   BIT(0)  /* SPI Enable */
#define SPI_CR1_MSTR  BIT(2)  /* Master Mode */
#define SPI_CR1_CPOL  BIT(3)  /* Clock Polarity */
#define SPI_CR1_CPHA  BIT(4)  /* Clock Phase */
#define SPI_SR_TXE    BIT(1)  /* TX FIFO Empty */
#define SPI_SR_RXNE   BIT(0)  /* RX FIFO Not Empty */
#define SPI_SR_BSY    BIT(7)  /* Busy */

struct my_spi_priv {
    void __iomem *base;
    struct clk *clk;
    int irq;
    struct completion xfer_done;
    const u8 *tx_buf;
    u8 *rx_buf;
    int tx_len, rx_len;
};

static int my_spi_transfer_one(struct spi_controller *ctlr,
                                struct spi_device *spi,
                                struct spi_transfer *xfer)
{
    struct my_spi_priv *priv = spi_controller_get_devdata(ctlr);
    u32 cr1, div;

    /* 클럭 분주 설정 */
    div = calc_spi_clk_div(clk_get_rate(priv->clk), xfer->speed_hz);
    cr1 = readl(priv->base + SPI_CR1);
    cr1 &= ~(0xFF << 8);      /* divider 필드 클리어 */
    cr1 |= (div << 8);          /* 새 divider 설정 */

    /* SPI 모드 설정 (CPOL/CPHA) */
    if (spi->mode & SPI_CPOL)
        cr1 |= SPI_CR1_CPOL;
    else
        cr1 &= ~SPI_CR1_CPOL;
    if (spi->mode & SPI_CPHA)
        cr1 |= SPI_CR1_CPHA;
    else
        cr1 &= ~SPI_CR1_CPHA;

    writel(cr1 | SPI_CR1_SPE, priv->base + SPI_CR1);

    /* FIFO watermark 설정 (깊이의 절반) */
    writel(8, priv->base + SPI_TXFR);  /* TX threshold */
    writel(8, priv->base + SPI_RXFR);  /* RX threshold */

    /* 전송 시작: PIO 또는 DMA */
    priv->tx_buf = xfer->tx_buf;
    priv->rx_buf = xfer->rx_buf;
    priv->tx_len = xfer->len;
    priv->rx_len = xfer->len;
    reinit_completion(&priv->xfer_done);

    /* IRQ 기반 PIO: TX empty 인터럽트 활성화 */
    writel(readl(priv->base + SPI_CR2) | BIT(0),
           priv->base + SPI_CR2);

    return 1;  /* 비동기: completion 대기 */
}

SPI DMA 통합

대용량 SPI 전송(수백 바이트 이상)에서는 DMA를 사용하여 CPU 부하를 줄입니다. DMA 버퍼(Buffer)는 캐시 라인(Cache Line) 정렬이 필수이며, scatter-gather 리스트로 비연속 메모리를 처리할 수 있습니다:

/* SPI DMA 전송 설정 */
static int my_spi_dma_xfer(struct my_spi_priv *priv,
                             struct spi_transfer *xfer)
{
    struct dma_async_tx_descriptor *tx_desc, *rx_desc;
    dma_addr_t tx_dma, rx_dma;
    struct device *dev = priv->dev;

    /* TX: 메모리 → 주변장치 (MEM_TO_DEV) */
    tx_dma = dma_map_single(dev, (void *)xfer->tx_buf,
                             xfer->len, DMA_TO_DEVICE);
    if (dma_mapping_error(dev, tx_dma))
        return -ENOMEM;

    /* RX: 주변장치 → 메모리 (DEV_TO_MEM) */
    rx_dma = dma_map_single(dev, xfer->rx_buf,
                             xfer->len, DMA_FROM_DEVICE);
    if (dma_mapping_error(dev, rx_dma)) {
        dma_unmap_single(dev, tx_dma, xfer->len, DMA_TO_DEVICE);
        return -ENOMEM;
    }

    /* RX DMA 먼저 준비 (데이터 유실 방지) */
    rx_desc = dmaengine_prep_slave_single(
        priv->rx_chan, rx_dma, xfer->len,
        DMA_DEV_TO_MEM, DMA_PREP_INTERRUPT);
    rx_desc->callback = my_spi_dma_rx_done;
    rx_desc->callback_param = priv;
    dmaengine_submit(rx_desc);
    dma_async_issue_pending(priv->rx_chan);

    /* TX DMA 시작 → SCK 생성 → 수신 자동 진행 */
    tx_desc = dmaengine_prep_slave_single(
        priv->tx_chan, tx_dma, xfer->len,
        DMA_MEM_TO_DEV, DMA_PREP_INTERRUPT);
    tx_desc->callback = my_spi_dma_tx_done;
    tx_desc->callback_param = priv;
    dmaengine_submit(tx_desc);
    dma_async_issue_pending(priv->tx_chan);

    return 0;
}

칩 셀렉트(CS) 관리

SPI 컨트롤러의 CS(Chip Select) 관리는 하드웨어 CS와 GPIO CS 두 가지 방식이 있습니다. 다중 슬레이브 환경에서는 CS 타이밍이 정확해야 버스 충돌을 방지할 수 있습니다:

spi_transfer 구조체의 cs_change 필드는 전송 간 CS 동작을 제어합니다. 이 필드가 설정되면 해당 transfer 종료 후 CS를 잠시 비활성화(deassert)했다가 다시 활성화합니다. 이는 일부 슬레이브 디바이스가 명령 사이에 CS 토글을 요구하는 경우에 필요합니다:

/* cs_change를 활용한 다중 명령 전송 */
static int spi_multi_cmd(struct spi_device *spi,
                          u8 *cmd1, size_t len1,
                          u8 *cmd2, size_t len2)
{
    struct spi_transfer xfer[2] = { };
    struct spi_message msg;

    /* Transfer 1: 첫 번째 명령 후 CS 토글 */
    xfer[0].tx_buf = cmd1;
    xfer[0].len = len1;
    xfer[0].cs_change = 1;  /* 이 transfer 후 CS deassert→reassert */
    xfer[0].cs_change_delay.value = 10;
    xfer[0].cs_change_delay.unit = SPI_DELAY_UNIT_USECS;

    /* Transfer 2: 두 번째 명령 (마지막이므로 CS 자동 해제) */
    xfer[1].tx_buf = cmd2;
    xfer[1].len = len2;

    spi_message_init_with_transfers(&msg, xfer, ARRAY_SIZE(xfer));
    return spi_sync(spi, &msg);
}

SPI 드라이버 작성

SPI ADC (Analog-to-Digital Converter) 드라이버 예제:

#include <linux/module.h>
#include <linux/spi/spi.h>
#include <linux/iio/iio.h>

#define ADC_CMD_READ_CH0  0x06
#define ADC_CMD_READ_CH1  0x07

struct my_adc_data {
    struct spi_device *spi;
    struct mutex lock;
    u8 tx_buf[3] ____cacheline_aligned;
    u8 rx_buf[3];
};

static int my_adc_read_channel(struct my_adc_data *data, int channel)
{
    struct spi_transfer xfer = {
        .tx_buf = data->tx_buf,
        .rx_buf = data->rx_buf,
        .len = 3,
        .speed_hz = 1000000,  /* 1 MHz */
    };
    int ret;

    data->tx_buf[0] = (channel == 0) ? ADC_CMD_READ_CH0 : ADC_CMD_READ_CH1;
    data->tx_buf[1] = 0x00;
    data->tx_buf[2] = 0x00;

    ret = spi_sync_transfer(data->spi, &xfer, 1);
    if (ret)
        return ret;

    /* 12비트 ADC: 상위 4비트 버림 */
    return ((data->rx_buf[1] & 0x0F) << 8) | data->rx_buf[2];
}

static int my_adc_read_raw(struct iio_dev *indio_dev,
                            struct iio_chan_spec const *chan,
                            int *val, int *val2, long mask)
{
    struct my_adc_data *data = iio_priv(indio_dev);
    int ret;

    switch (mask) {
    case IIO_CHAN_INFO_RAW:
        mutex_lock(&data->lock);
        ret = my_adc_read_channel(data, chan->channel);
        mutex_unlock(&data->lock);
        if (ret < 0)
            return ret;
        *val = ret;
        return IIO_VAL_INT;
    case IIO_CHAN_INFO_SCALE:
        /* Vref=3.3V, 12-bit: 3300/4096 = 0.805664 mV/LSB */
        *val = 3300;
        *val2 = 12;
        return IIO_VAL_FRACTIONAL_LOG2;
    default:
        return -EINVAL;
    }
}

static const struct iio_chan_spec my_adc_channels[] = {
    {
        .type = IIO_VOLTAGE,
        .channel = 0,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
        .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE),
    },
    {
        .type = IIO_VOLTAGE,
        .channel = 1,
        .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
        .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE),
    },
};

static const struct iio_info my_adc_info = {
    .read_raw = my_adc_read_raw,
};

static int my_adc_probe(struct spi_device *spi)
{
    struct iio_dev *indio_dev;
    struct my_adc_data *data;

    indio_dev = devm_iio_device_alloc(&spi->dev, sizeof(*data));
    if (!indio_dev)
        return -ENOMEM;

    data = iio_priv(indio_dev);
    data->spi = spi;
    mutex_init(&data->lock);

    indio_dev->name = "my-adc";
    indio_dev->info = &my_adc_info;
    indio_dev->channels = my_adc_channels;
    indio_dev->num_channels = ARRAY_SIZE(my_adc_channels);
    indio_dev->modes = INDIO_DIRECT_MODE;

    return devm_iio_device_register(&spi->dev, indio_dev);
}

static const struct spi_device_id my_adc_spi_id[] = {
    { "my-adc", 0 },
    { }
};
MODULE_DEVICE_TABLE(spi, my_adc_spi_id);

static const struct of_device_id my_adc_of_match[] = {
    { .compatible = "vendor,my-adc" },
    { }
};
MODULE_DEVICE_TABLE(of, my_adc_of_match);

static struct spi_driver my_adc_driver = {
    .driver = {
        .name = "my-adc",
        .of_match_table = my_adc_of_match,
    },
    .probe = my_adc_probe,
    .id_table = my_adc_spi_id,
};
module_spi_driver(my_adc_driver);

spi_message와 spi_transfer

복잡한 SPI 트랜잭션은 spi_message에 여러 spi_transfer를 연결하여 구성합니다:

/* 명령어 전송 후 데이터 수신 (CS 유지) */
static int spi_flash_read(struct spi_device *spi,
                           u32 addr, u8 *buf, size_t len)
{
    struct spi_message msg;
    struct spi_transfer xfer[2];
    u8 cmd[4];

    cmd[0] = 0x03;  /* READ 명령 */
    cmd[1] = (addr >> 16) & 0xFF;
    cmd[2] = (addr >> 8)  & 0xFF;
    cmd[3] = addr & 0xFF;

    memset(xfer, 0, sizeof(xfer));

    /* Transfer 1: 명령 + 주소 전송 */
    xfer[0].tx_buf = cmd;
    xfer[0].len = 4;

    /* Transfer 2: 데이터 수신 */
    xfer[1].rx_buf = buf;
    xfer[1].len = len;

    spi_message_init(&msg);
    spi_message_add_tail(&xfer[0], &msg);
    spi_message_add_tail(&xfer[1], &msg);

    return spi_sync(spi, &msg);
}

QSPI / Dual / Quad SPI

고속 SPI NOR Flash 등은 표준 SPI 외에 Dual (2-bit), Quad (4-bit), Octal (8-bit) I/O를 지원합니다. Linux 커널은 spi-mem 레이어를 통해 이를 추상화합니다.

spi-mem 프레임워크

spi-mem은 메모리형 SPI 디바이스를 위한 표준화된 인터페이스입니다:

#include <linux/spi/spi-mem.h>

/* spi_mem_op: 명령/주소/더미/데이터 단계를 분리하여 기술 */
struct spi_mem_op op = SPI_MEM_OP(
    SPI_MEM_OP_CMD(0xEB, 1),           /* Quad I/O Fast Read, 1-wire cmd */
    SPI_MEM_OP_ADDR(3, addr, 4),       /* 3-byte addr, 4-wire */
    SPI_MEM_OP_DUMMY(6, 4),            /* 6 dummy cycles, 4-wire */
    SPI_MEM_OP_DATA_IN(len, buf, 4)   /* 데이터 수신, 4-wire */
);

ret = spi_mem_exec_op(spi_mem, &op);

Quad SPI: DDR 모드와 XIP

고성능 SPI NOR Flash는 기본 Quad I/O를 넘어 DDR (Double Data Rate) 모드, Data Strobe (DQS), XIP (eXecute-In-Place) 등 고급 기능을 지원합니다. 아래 다이어그램은 Quad SPI 명령의 4단계 구조를 보여줍니다.

DDR (Double Data Rate) 모드

DDR 모드에서는 SCK의 상승 에지와 하강 에지 양쪽에서 데이터를 전송하여 SDR(Single Data Rate) 대비 2배 대역폭(Bandwidth)을 달성합니다. Octal DDR (8D-8D-8D) 모드에서는 8개 데이터 라인 x DDR로 사이클당 16비트를 전송합니다:

Data Strobe (DQS)

DDR 모드에서 고주파 클럭의 정확한 샘플링 타이밍을 보장하기 위해 DQS (Data Strobe) 신호가 사용됩니다. DQS는 슬레이브 디바이스가 데이터와 함께 출력하는 스트로브 신호로, 컨트롤러가 이 신호의 에지에서 데이터를 캡처합니다. 이는 SDR에서는 불필요하지만, DDR에서 클럭-데이터 스큐 보상에 필수적입니다.

XIP (eXecute-In-Place) 모드

XIP 모드는 SPI NOR Flash의 내용을 CPU 메모리 맵(Memory Map)에 직접 매핑하여, 별도의 복사 없이 Flash에서 직접 코드를 실행할 수 있게 합니다. QSPI 컨트롤러가 CPU의 메모리 접근을 자동으로 SPI 읽기 명령으로 변환합니다:

/* XIP 모드 활성화: QSPI 컨트롤러 메모리 매핑 예시 */
static int qspi_enable_xip(struct qspi_priv *priv)
{
    struct spi_mem_op op = SPI_MEM_OP(
        SPI_MEM_OP_CMD(0xEB, 1),          /* Fast Read Quad I/O */
        SPI_MEM_OP_ADDR(3, 0, 4),         /* 24-bit addr, 4-wire */
        SPI_MEM_OP_DUMMY(6, 4),           /* 6 dummy cycles */
        SPI_MEM_OP_DATA_IN(0, NULL, 4)   /* 4-wire data */
    );
    u32 cr;

    /* 메모리 매핑 윈도우 설정 */
    writel(priv->mmap_phys, priv->base + QSPI_MMAP_BASE);
    writel(priv->flash_size - 1, priv->base + QSPI_MMAP_SIZE);

    /* Continuous Read 모드: 반복 CMD 전송 생략 */
    cr = readl(priv->base + QSPI_CR);
    cr |= QSPI_CR_XIP_EN | QSPI_CR_CONT_READ;
    writel(cr, priv->base + QSPI_CR);

    /* XIP 후 Flash는 메모리처럼 접근 가능:
     * void *data = ioremap(priv->mmap_phys, priv->flash_size);
     * memcpy(dst, data + offset, len);  */

    return 0;
}

SPI Device Tree 바인딩

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

    adc@0 {
        compatible = "vendor,my-adc";
        reg = <0>;          /* chip select 0 */
        spi-max-frequency = <10000000>;  /* 10 MHz */
        spi-cpol;           /* CPOL=1 (Mode 2 or 3) */
        spi-cpha;           /* CPHA=1 (Mode 1 or 3) */
        /* spi-cpol + spi-cpha = Mode 3 */
    };

    flash@1 {
        compatible = "jedec,spi-nor";
        reg = <1>;
        spi-max-frequency = <50000000>;
        spi-rx-bus-width = <4>;  /* quad read */
        spi-tx-bus-width = <4>;  /* quad write */
        m25p,fast-read;
    };
};

regmap: SPI 레지스터 추상화 API

regmap은 다양한 버스(I2C, SPI, MMIO) 위의 레지스터 접근을 통합 추상화하는 프레임워크입니다. 드라이버 코드에서 버스별 전송 함수 호출을 제거하고, 캐싱, 범위 검사, endian 변환 등 공통 기능을 투명하게 제공합니다. SPI 드라이버에서는 devm_regmap_init_spi()로 초기화합니다. I2C 및 MMIO 버스에서의 regmap 사용에 대한 자세한 내용은 I2C 서브시스템 문서를 참조하세요.

regmap 설정

#include <linux/regmap.h>

/* 레지스터 기본값 (캐시 초기화용) */
static const struct reg_default my_reg_defaults[] = {
    { 0x00, 0x0000 },  /* STATUS */
    { 0x01, 0x001F },  /* CONFIG */
    { 0x02, 0x0000 },  /* DATA */
};

/* 읽기 가능 레지스터 범위 */
static bool my_readable_reg(struct device *dev, unsigned int reg)
{
    return reg <= 0x10;
}

/* 휘발성 레지스터 (캐시하지 않음) */
static bool my_volatile_reg(struct device *dev, unsigned int reg)
{
    return reg == 0x00 || reg == 0x02;  /* STATUS, DATA */
}

static const struct regmap_config my_regmap_config = {
    .reg_bits      = 8,         /* 레지스터 주소 비트 수 */
    .val_bits      = 16,        /* 레지스터 값 비트 수 */
    .max_register  = 0x10,
    .readable_reg  = my_readable_reg,
    .volatile_reg  = my_volatile_reg,
    .cache_type    = REGCACHE_RBTREE,
    .reg_defaults  = my_reg_defaults,
    .num_reg_defaults = ARRAY_SIZE(my_reg_defaults),
};

SPI regmap 생성

/* SPI regmap */
static int my_spi_probe(struct spi_device *spi)
{
    struct regmap *regmap;

    regmap = devm_regmap_init_spi(spi, &my_regmap_config);
    if (IS_ERR(regmap))
        return PTR_ERR(regmap);
    /* ... */
}

regmap 사용

unsigned int val;
int ret;

/* 단일 레지스터 읽기 */
ret = regmap_read(regmap, 0x00, &val);
if (ret)
    return ret;

/* 단일 레지스터 쓰기 */
ret = regmap_write(regmap, 0x01, 0x1234);

/* 비트 필드 업데이트 (read-modify-write 원자적 수행) */
ret = regmap_update_bits(regmap, 0x01,
                         0x00FF,    /* mask */
                         0x0042);   /* value */

/* 벌크 읽기 */
u16 buf[4];
ret = regmap_bulk_read(regmap, 0x00, buf, 4);

/* 폴링: 비트가 설정될 때까지 대기 */
ret = regmap_read_poll_timeout(regmap, 0x00, val,
                               val & BIT(0),     /* condition */
                               1000,              /* sleep_us */
                               100000);           /* timeout_us */

regmap IRQ 프레임워크

regmap-irq는 레지스터 기반 인터럽트 컨트롤러(Interrupt Controller)를 위한 generic IRQ chip을 제공합니다:

static const struct regmap_irq my_irqs[] = {
    REGMAP_IRQ_REG(0, 0, BIT(0)),  /* IRQ 0: bit 0 of reg 0 */
    REGMAP_IRQ_REG(1, 0, BIT(1)),  /* IRQ 1: bit 1 of reg 0 */
    REGMAP_IRQ_REG(2, 0, BIT(2)),  /* IRQ 2: bit 2 of reg 0 */
};

static const struct regmap_irq_chip my_irq_chip = {
    .name           = "my-device",
    .irqs           = my_irqs,
    .num_irqs       = ARRAY_SIZE(my_irqs),
    .num_regs       = 1,
    .status_base    = 0x08,  /* 인터럽트 상태 레지스터 */
    .mask_base      = 0x09,  /* 인터럽트 마스크 레지스터 */
    .ack_base       = 0x08,  /* ACK = 상태 레지스터에 W1C */
};

/* probe에서 등록 */
struct regmap_irq_chip_data *irq_data;

ret = devm_regmap_add_irq_chip(&spi->dev, regmap,
        spi->irq, IRQF_ONESHOT, 0,
        &my_irq_chip, &irq_data);

/* 하위 디바이스에서 가상 IRQ 사용 */
int virq = regmap_irq_get_virq(irq_data, 0);

regmap 내부 아키텍처

regmap 프레임워크는 버스 추상화 계층(bus abstraction layer)과 캐시 백엔드로 구성됩니다. 핵심 구조체 struct regmap은 드라이버에 불투명(opaque)하며, 내부적으로 버스 콜백, 캐시 상태, 잠금(Lock) 메커니즘을 관리합니다.

/* include/linux/regmap.h - regmap 핵심 구조 (개념도) */

/* struct regmap 내부 주요 필드(위 SVG 참고) */

/* 버스 추상화: 각 버스 타입이 이 콜백을 구현 */
struct regmap_bus {
    bool fast_io;                   /* true면 spinlock 사용 */
    int (*write)(void *context,      /* 레지스터 쓰기 */
                 const void *data, size_t count);
    int (*read)(void *context,       /* 레지스터 읽기 */
                const void *reg_buf, size_t reg_size,
                void *val_buf, size_t val_size);
    int (*reg_write)(void *context,  /* 단일 reg 쓰기 (선택) */
                     unsigned int reg, unsigned int val);
    int (*reg_read)(void *context,   /* 단일 reg 읽기 (선택) */
                    unsigned int reg, unsigned int *val);
    int (*reg_update_bits)(void *context, /* RMW 최적화 (선택) */
                          unsigned int reg,
                          unsigned int mask, unsigned int val);
    enum regmap_endian val_format_endian_default; /* 버스 기본 엔디안 */
};

regmap_field: 비트 필드 추상화

regmap_field는 레지스터 내 특정 비트 필드를 독립적인 객체로 추상화합니다. 비트 마스크/시프트 연산을 캡슐화(Encapsulation)하여 드라이버 코드의 가독성과 유지보수성을 높입니다.

#include <linux/regmap.h>

/* 레지스터 필드 정의 매크로 */
/* REG_FIELD(reg, lsb, msb) - 레지스터 주소와 비트 범위 지정 */

/* 예: 0x04 레지스터 레이아웃 (위 SVG 참고) */
static const struct reg_field enable_field  = REG_FIELD(0x04, 15, 15);
static const struct reg_field mode_field    = REG_FIELD(0x04, 12, 14);
static const struct reg_field gain_field    = REG_FIELD(0x04, 8,  11);
static const struct reg_field offset_field  = REG_FIELD(0x04, 0,  7);

struct my_device {
    struct regmap *regmap;
    struct regmap_field *f_enable;
    struct regmap_field *f_mode;
    struct regmap_field *f_gain;
    struct regmap_field *f_offset;
};

static int my_probe(struct spi_device *spi)
{
    struct my_device *dev;
    struct regmap *regmap;

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

    regmap = devm_regmap_init_spi(spi, &my_regmap_config);
    if (IS_ERR(regmap))
        return PTR_ERR(regmap);
    dev->regmap = regmap;

    /* 필드 객체 할당 */
    dev->f_enable = devm_regmap_field_alloc(&spi->dev, regmap, enable_field);
    if (IS_ERR(dev->f_enable))
        return PTR_ERR(dev->f_enable);

    dev->f_mode = devm_regmap_field_alloc(&spi->dev, regmap, mode_field);
    dev->f_gain = devm_regmap_field_alloc(&spi->dev, regmap, gain_field);
    dev->f_offset = devm_regmap_field_alloc(&spi->dev, regmap, offset_field);

    /* 필드 접근: 비트 마스크/시프트 불필요 */
    regmap_field_write(dev->f_enable, 1);           /* bit 15 = 1 */
    regmap_field_write(dev->f_mode, 0x5);           /* bits 14:12 = 5 */
    regmap_field_write(dev->f_gain, 0xA);           /* bits 11:8 = 0xA */

    unsigned int val;
    regmap_field_read(dev->f_offset, &val);         /* bits 7:0 읽기 */

    /* 필드 비트 업데이트 (field 범위 내에서 RMW) */
    regmap_field_update_bits(dev->f_mode, 0x3, 0x2); /* mode 하위 2비트만 수정 */

    return 0;
}

/* 벌크 필드 할당 (v5.3+): 여러 필드를 한 번에 할당 */
static const struct reg_field my_fields[] = {
    [F_ENABLE] = REG_FIELD(0x04, 15, 15),
    [F_MODE]   = REG_FIELD(0x04, 12, 14),
    [F_GAIN]   = REG_FIELD(0x04, 8,  11),
    [F_OFFSET] = REG_FIELD(0x04, 0,  7),
};

struct regmap_field *fields[F_MAX];
ret = devm_regmap_field_bulk_alloc(&spi->dev, regmap,
                                   fields, my_fields, F_MAX);

레지스터 접근 테이블

콜백 함수 대신 regmap_access_table을 사용하면 테이블 기반으로 레지스터 접근 권한을 정의할 수 있습니다. 레지스터가 많은 디바이스에서 더 간결합니다.

/* 레지스터 범위 정의 */
static const struct regmap_range my_readable_ranges[] = {
    regmap_reg_range(0x00, 0x0F),   /* 0x00 ~ 0x0F 읽기 가능 */
    regmap_reg_range(0x20, 0x2F),   /* 0x20 ~ 0x2F 읽기 가능 */
    regmap_reg_range(0x80, 0x80),   /* 0x80 단일 레지스터 */
};

static const struct regmap_range my_writeable_ranges[] = {
    regmap_reg_range(0x01, 0x0F),   /* 0x00(STATUS)은 읽기 전용 */
    regmap_reg_range(0x20, 0x2F),
};

static const struct regmap_range my_volatile_ranges[] = {
    regmap_reg_range(0x00, 0x00),   /* STATUS: 항상 HW 읽기 */
    regmap_reg_range(0x08, 0x09),   /* IRQ 상태/마스크 */
};

static const struct regmap_range my_precious_ranges[] = {
    regmap_reg_range(0x0A, 0x0A),   /* FIFO: 읽으면 값 소비됨 */
};

static const struct regmap_access_table my_rd_table = {
    .yes_ranges = my_readable_ranges,
    .n_yes_ranges = ARRAY_SIZE(my_readable_ranges),
};

static const struct regmap_access_table my_wr_table = {
    .yes_ranges = my_writeable_ranges,
    .n_yes_ranges = ARRAY_SIZE(my_writeable_ranges),
};

static const struct regmap_access_table my_volatile_table = {
    .yes_ranges = my_volatile_ranges,
    .n_yes_ranges = ARRAY_SIZE(my_volatile_ranges),
};

static const struct regmap_access_table my_precious_table = {
    .yes_ranges = my_precious_ranges,
    .n_yes_ranges = ARRAY_SIZE(my_precious_ranges),
};

static const struct regmap_config my_table_config = {
    .reg_bits      = 8,
    .val_bits      = 16,
    .max_register  = 0x80,
    .rd_table      = &my_rd_table,       /* 읽기 가능 범위 */
    .wr_table      = &my_wr_table,       /* 쓰기 가능 범위 */
    .volatile_table = &my_volatile_table, /* 캐시 안 함 */
    .precious_table = &my_precious_table, /* debugfs에서 읽지 않음 */
    .cache_type    = REGCACHE_RBTREE,
};

레지스터 윈도우와 페이지(Page) 매핑

일부 디바이스는 레지스터 공간이 커서 페이지 레지스터를 통해 윈도우 방식으로 접근합니다. regmap_range_cfg는 이러한 페이지 기반 레지스터 접근을 투명하게 처리합니다.

/*
 * 디바이스 레지스터 구조 (위 SVG 참고):
 */

static const struct regmap_range_cfg my_range_cfg[] = {
    {
        .name         = "pages",
        .range_min    = 0x81,        /* 윈도우 시작 (가상) */
        .range_max    = 0x2FF,       /* 윈도우 끝 (가상) */
        .selector_reg = 0x80,        /* 페이지 선택 레지스터 */
        .selector_mask = 0xFF,       /* 선택 비트 마스크 */
        .selector_shift = 0,         /* 선택 비트 시프트 */
        .window_start = 0x81,        /* 물리 윈도우 시작 */
        .window_len   = 0x7F,        /* 윈도우 크기 (바이트) */
    },
};

static const struct regmap_config my_paged_config = {
    .reg_bits      = 8,
    .val_bits      = 8,
    .max_register  = 0x2FF,        /* 가상 주소 공간 최대 */
    .ranges        = my_range_cfg,
    .num_ranges    = ARRAY_SIZE(my_range_cfg),
};

/* 드라이버에서는 가상 주소로 투명하게 접근 */
regmap_read(regmap, 0x185, &val);   /* 자동으로: page=1 선택 → 0x85 읽기 */
regmap_write(regmap, 0x281, 0x42);  /* 자동으로: page=2 선택 → 0x81 쓰기 */

다중 레지스터 연산

여러 레지스터를 원자적으로 읽거나 쓸 때 사용하는 고급 API입니다.

/* 다중 레지스터 쓰기 (시퀀스 보장) */
static const struct reg_sequence init_seq[] = {
    { 0x01, 0x0000 },                  /* CONFIG = 0 (리셋) */
    REG_SEQ0(0x01, 0x0000),              /* 동일, delay_us = 0 */
    { 0x02, 0x1234, 1000 },             /* DATA = 0x1234, 1ms 지연 후 다음 */
    { 0x01, 0x001F },                  /* CONFIG = 0x1F (활성화) */
};

/* 시퀀스를 한 번에 실행 */
ret = regmap_multi_reg_write(regmap, init_seq, ARRAY_SIZE(init_seq));

/* 레지스터 패치: regmap 생성 시 자동 적용되는 초기화 시퀀스 */
static const struct reg_sequence my_patch[] = {
    { 0x10, 0xABCD },
    { 0x11, 0x1234 },
};
ret = regmap_register_patch(regmap, my_patch, ARRAY_SIZE(my_patch));

/* raw 읽기/쓰기: 포맷 변환 없이 바이트 스트림 전송 */
u8 raw_buf[16];
ret = regmap_raw_read(regmap, 0x00, raw_buf, sizeof(raw_buf));
ret = regmap_raw_write(regmap, 0x00, raw_buf, sizeof(raw_buf));

/* noinc 읽기/쓰기: 주소 증가 없이 같은 레지스터 반복 접근 (FIFO) */
u8 fifo_buf[64];
ret = regmap_noinc_read(regmap, 0x0A, fifo_buf, sizeof(fifo_buf));
ret = regmap_noinc_write(regmap, 0x0A, fifo_buf, sizeof(fifo_buf));

regmap 캐시

regmap 캐시는 레지스터 값의 로컬 복사본을 유지하여 불필요한 버스 트랜잭션을 줄입니다. 전원 관리와 긴밀하게 연동되며, 캐시 상태 관리를 통해 resume 시 효율적인 레지스터 복원을 수행합니다.

/*
 * regmap 캐시 상태 머신 (위 SVG 참고)
 */

/* 캐시 제어 API */

/* 캐시 전용 모드: 버스 접근 차단, 캐시만 갱신 */
regcache_cache_only(regmap, true);   /* suspend 시 */
regmap_write(regmap, 0x01, 0x42);    /* 캐시에만 기록, dirty 마킹 */
regcache_cache_only(regmap, false);  /* resume 시 */

/* 캐시 → HW 동기화: dirty 레지스터만 하드웨어에 기록 */
ret = regcache_sync(regmap);

/* 특정 범위만 동기화 */
ret = regcache_sync_region(regmap, 0x00, 0x0F);

/* 캐시 전체를 dirty로 마킹 (resume 시 전체 복원 강제) */
regcache_mark_dirty(regmap);

/* 캐시 무효화: 캐시된 값 폐기, 다음 읽기 시 HW 접근 */
ret = regcache_drop_region(regmap, 0x00, 0x0F);

/* 캐시 바이패스: 일시적으로 캐시 우회, HW 직접 접근 */
regcache_cache_bypass(regmap, true);
regmap_read(regmap, 0x00, &val);      /* HW에서 직접 읽기 */
regcache_cache_bypass(regmap, false);

regmap 전원 관리 연동

regmap 캐시는 시스템 suspend/resume과 runtime PM에서 핵심적인 역할을 합니다. 전원 차단 시 캐시 전용 모드로 전환하고, 복원 시 dirty 레지스터만 하드웨어에 동기화하여 resume 시간을 최소화합니다.

/* 시스템 suspend/resume */
static int my_suspend(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);

    /* 디바이스 비활성화 */
    regmap_update_bits(mydev->regmap, 0x01, BIT(0), 0);

    /* 캐시 전용 모드: 이후 접근은 캐시에만 기록 */
    regcache_cache_only(mydev->regmap, true);

    /* 전체 캐시를 dirty로 마킹: resume 시 전체 복원 */
    regcache_mark_dirty(mydev->regmap);

    return 0;
}

static int my_resume(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);
    int ret;

    /* 캐시 전용 모드 해제: 버스 접근 재개 */
    regcache_cache_only(mydev->regmap, false);

    /* dirty 레지스터만 HW에 동기화 */
    ret = regcache_sync(mydev->regmap);
    if (ret)
        dev_err(dev, "regcache sync failed: %d\\n", ret);

    return ret;
}

/* Runtime PM과 regmap 연동 */
static int my_runtime_suspend(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);

    regcache_cache_only(mydev->regmap, true);
    regcache_mark_dirty(mydev->regmap);

    /* 레귤레이터/클록 비활성화 */
    regulator_disable(mydev->vdd);
    clk_disable_unprepare(mydev->clk);

    return 0;
}

static int my_runtime_resume(struct device *dev)
{
    struct my_device *mydev = dev_get_drvdata(dev);
    int ret;

    /* 레귤레이터/클록 활성화 */
    ret = clk_prepare_enable(mydev->clk);
    if (ret)
        return ret;

    ret = regulator_enable(mydev->vdd);
    if (ret) {
        clk_disable_unprepare(mydev->clk);
        return ret;
    }

    /* HW 안정화 대기 */
    usleep_range(1000, 1500);

    regcache_cache_only(mydev->regmap, false);
    ret = regcache_sync(mydev->regmap);

    return ret;
}

static DEFINE_RUNTIME_DEV_PM_OPS(my_pm_ops,
    my_runtime_suspend, my_runtime_resume, NULL);

regmap debugfs 디버깅

regmap은 자동으로 debugfs 인터페이스를 생성하여 런타임에 레지스터 값을 검사할 수 있습니다. CONFIG_DEBUG_FS와 CONFIG_REGMAP이 활성화되어야 합니다.

# regmap debugfs 위치
/sys/kernel/debug/regmap/

# 디바이스별 디렉토리 예시
/sys/kernel/debug/regmap/spi0.0/         # SPI bus 0, CS 0

# 레지스터 값 확인
$ cat /sys/kernel/debug/regmap/spi0.0/registers
00: 0042
01: 001f
02: 0000
03: abcd
...

# 접근 권한 확인
$ cat /sys/kernel/debug/regmap/spi0.0/access
00: RV      # R=readable, V=volatile
01: RW      # R=readable, W=writable
02: RWv     # v=volatile (소문자 = 캐시 안 함)
0a: RWP     # P=precious (debugfs dump 제외)

# 캐시 상태 확인
$ cat /sys/kernel/debug/regmap/spi0.0/cache_only
N           # Y=캐시 전용 모드 활성

regmap 고급 설정

regmap_config의 다양한 고급 옵션으로 복잡한 하드웨어 특성을 처리할 수 있습니다. SPI 디바이스에서 특히 read_flag_mask와 pad_bits 설정이 자주 사용됩니다.

static const struct regmap_config advanced_config = {
    .reg_bits        = 16,          /* 16비트 레지스터 주소 */
    .val_bits        = 32,          /* 32비트 레지스터 값 */
    .reg_stride      = 4,           /* 레지스터 주소 간격 (MMIO 워드 정렬) */
    .max_register    = 0x1000,

    /* 엔디안 설정 */
    .reg_format_endian = REGMAP_ENDIAN_BIG,     /* 주소 바이트 순서 */
    .val_format_endian = REGMAP_ENDIAN_LITTLE,  /* 값 바이트 순서 */

    /* SPI 읽기 시 상위 비트 설정 (SPI 프로토콜 관례) */
    .read_flag_mask  = 0x80,        /* 레지스터 주소에 OR */
    .write_flag_mask = 0x00,

    /* 레지스터 주소 패딩 (일부 SPI 디바이스 요구) */
    .pad_bits        = 8,           /* 주소 뒤 패딩 비트 */

    /* 읽기 전 지연 (슬로우 디바이스) */
    .read_delay_us   = 10,          /* 주소 전송 후 읽기 전 지연 */

    /* 캐시 설정 */
    .cache_type      = REGCACHE_MAPLE,
    .reg_defaults    = my_defaults,
    .num_reg_defaults = ARRAY_SIZE(my_defaults),

    /* 동기화 비활성 레지스터: cache_sync 시 기록하지 않을 범위 */
    .disable_locking = false,       /* true면 외부 잠금 사용 */

    /* 커스텀 잠금 (기존 잠금과 통합 시) */
    .lock            = my_lock_fn,
    .unlock          = my_unlock_fn,
    .lock_arg        = &my_mutex,

    /* 레지스터 값 비트 후처리 */
    .use_single_read  = true,       /* bulk를 단일 읽기로 분해 */
    .use_single_write = true,       /* bulk를 단일 쓰기로 분해 */
    .can_multi_write  = true,       /* multi_reg_write 최적화 허용 */

    /* 비동기 쓰기 지원 */
    .use_hwlock      = false,       /* HW spinlock 사용 여부 */
};

regmap ftrace 이벤트

regmap은 ftrace 이벤트를 통해 모든 레지스터 접근을 추적할 수 있습니다. 버스 트랜잭션 디버깅과 성능 분석에 활용됩니다.

# regmap 관련 ftrace 이벤트
$ ls /sys/kernel/debug/tracing/events/regmap/
regmap_reg_read/         # 레지스터 읽기
regmap_reg_write/        # 레지스터 쓰기
regmap_bulk_read/        # 벌크 읽기
regmap_bulk_write/       # 벌크 쓰기
regmap_hw_read_start/    # HW 읽기 시작
regmap_hw_read_done/     # HW 읽기 완료
regmap_hw_write_start/   # HW 쓰기 시작
regmap_hw_write_done/    # HW 쓰기 완료
regmap_cache_only/       # 캐시 전용 모드 전환
regmap_cache_sync/       # 캐시 동기화
regmap_cache_bypass/     # 캐시 바이패스 전환

# 특정 regmap만 필터링
$ cd /sys/kernel/debug/tracing
$ echo 1 > events/regmap/regmap_reg_write/enable
$ cat trace
# 출력 예:
#    my_driver-1234  [002] ....  1.234567: regmap_reg_write:
#        spi0.0 reg=01 val=1234

# 특정 디바이스만 추적
$ echo 'name == "spi0.0"' > events/regmap/regmap_reg_write/filter

# HW 접근 시간 측정 (start/done 이벤트 페어)
$ echo 1 > events/regmap/regmap_hw_read_start/enable
$ echo 1 > events/regmap/regmap_hw_read_done/enable
$ cat trace_pipe
# hw_read_start와 hw_read_done 타임스탬프 차이 = 실제 버스 지연

Device Tree 통합: SPI 바인딩 패턴

SPI 서브시스템의 Device Tree 바인딩에서 사용되는 공통 프로퍼티와 패턴을 정리합니다.

SPI 공통 프로퍼티

SPI Device Tree 종합 예제

실제 임베디드 보드에서 SPI Flash와 SPI ADC를 함께 사용하는 Device Tree 예제:

&pinctrl {
    spi1_default: spi1-default-pins {
        mosi-sck-pins {
            pins = "PB3", "PB5";
            function = "spi1";
            bias-disable;
            drive-push-pull;
            slew-rate = <1>;  /* high speed */
        };
        miso-pin {
            pins = "PB4";
            function = "spi1";
            bias-pull-down;
        };
    };
};

&spi1 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&spi1_default>;

    /* SPI NOR Flash */
    flash@0 {
        compatible = "jedec,spi-nor";
        reg = <0>;
        spi-max-frequency = <50000000>;
        spi-rx-bus-width = <4>;
        m25p,fast-read;

        partitions {
            compatible = "fixed-partitions";
            #address-cells = <1>;
            #size-cells = <1>;

            bootloader@0 {
                label = "bootloader";
                reg = <0x0 0x40000>;
                read-only;
            };

            firmware@40000 {
                label = "firmware";
                reg = <0x40000 0x3C0000>;
            };
        };
    };

    /* SPI ADC */
    adc@1 {
        compatible = "vendor,my-adc";
        reg = <1>;
        spi-max-frequency = <5000000>;
        vref-supply = <&reg_3v3>;
    };
};

SPI Device Tree 디버깅

SPI 관련 Device Tree 문제를 디버깅하는 방법:

# SPI 디바이스 확인
ls /sys/bus/spi/devices/          # 등록된 SPI 디바이스
ls /sys/class/spi_master/         # SPI 컨트롤러

# pinctrl 핀 매핑 확인
cat /sys/kernel/debug/pinctrl/*/pins  # pinctrl 핀 매핑

# Device Tree 런타임 확인
ls /proc/device-tree/             # DT 노드 트리
dtc -I fs /proc/device-tree/      # 런타임 DT를 DTS로 디컴파일

# dmesg로 SPI 관련 메시지 확인
dmesg | grep -i spi               # SPI 드라이버 로드/에러 확인

참고자료

커널 공식 문서

• Linux SPI Subsystem — Linux SPI 서브시스템 문서
• Overview of Linux kernel SPI support — SPI 지원 개요
• SPI userspace API — SPI 유저스페이스 API (spidev)
• PXA2xx SPI Controller Driver — PXA2xx SPI 드라이버

커널 소스 코드

• drivers/spi/spi.c — SPI 코어 구현
• include/linux/spi/spi.h — spi_device, spi_driver, spi_controller 정의
• include/linux/spi/spi-mem.h — SPI-MEM (QSPI/OSPI 메모리) 인터페이스
• drivers/spi/spi-mem.c — SPI-MEM 코어 구현
• drivers/spi/spidev.c — /dev/spidev* 유저스페이스 인터페이스
• drivers/spi/spi-cadence-quadspi.c — Cadence QSPI 컨트롤러 드라이버
• drivers/mtd/spi-nor/core.c — SPI NOR 플래시 프레임워크

외부 자료

• SPI / MTD improvements — SPI 및 MTD 개선 사항
• Rethinking the SPI subsystem — SPI 서브시스템 재설계 논의
• Introduction to SPI Interface — SPI 인터페이스 소개 (Analog Devices)

관련 문서

이 주제와 관련된 다른 문서를 더 깊이 이해하고 싶다면 다음을 참고하세요.

• I2C 서브시스템 — I2C 프로토콜, i2c_adapter/client, SMBus, I3C
• GPIO 서브시스템 — gpiod API, gpio_chip, IRQ 컨트롤러, pinctrl
• 디바이스 드라이버 — 디바이스 드라이버 모델, DMA, IRQ
• 인터럽트 처리 — IRQ 핸들링
• DMA — DMA 매핑과 전송
• 전원 관리 — 디바이스 전원 관리