3.0.35 SPI主机控制器驱动和外设驱动

SPI（同步外设接口）是由motorola开发的全双工同步串行总线，其接口由MISO（串行数据输入），MOSI（串行数据输出），SCK（串行移位时钟）

SS（从使能信号）4种信号构成。SS决定了惟一的与主设备通信的从设备，主设备通过产生移位时钟来发起通信。

在3.0.35 内核中，用spi_master 结构体来描述一个spi 主机控制器驱动，如下定义（include/linux/spi/spi.h）：

/**
 * struct spi_master - interface to SPI master controller
 * @dev: device interface to this driver
 * @list: link with the global spi_master list
 * @bus_num: board-specific (and often SOC-specific) identifier for a
 *    given SPI controller.
 * @num_chipselect: chipselects are used to distinguish individual
 *    SPI slaves, and are numbered from zero to num_chipselects.
 *    each slave has a chipselect signal, but it‘s common that not
 *    every chipselect is connected to a slave.
 * @dma_alignment: SPI controller constraint on DMA buffers alignment.
 * @mode_bits: flags understood by this controller driver
 * @flags: other constraints relevant to this driver
 * @bus_lock_spinlock: spinlock for SPI bus locking
 * @bus_lock_mutex: mutex for SPI bus locking
 * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
 * @setup: updates the device mode and clocking records used by a
 *    device‘s SPI controller; protocol code may call this.  This
 *    must fail if an unrecognized or unsupported mode is requested.
 *    It‘s always safe to call this unless transfers are pending on
 *    the device whose settings are being modified.
 * @transfer: adds a message to the controller‘s transfer queue.
 * @cleanup: frees controller-specific state
 *
 * Each SPI master controller can communicate with one or more @spi_device
 * children.  These make a small bus, sharing MOSI, MISO and SCK signals
 * but not chip select signals.  Each device may be configured to use a
 * different clock rate, since those shared signals are ignored unless
 * the chip is selected.
 *
 * The driver for an SPI controller manages access to those devices through
 * a queue of spi_message transactions, copying data between CPU memory and
 * an SPI slave device.  For each such message it queues, it calls the
 * message‘s completion function when the transaction completes.
 */
struct spi_master {
    struct device    dev;

    struct list_head list;

    /* other than negative (== assign one dynamically), bus_num is fully
     * board-specific.  usually that simplifies to being SOC-specific.
     * example:  one SOC has three SPI controllers, numbered 0..2,
     * and one board‘s schematics might show it using SPI-2.  software
     * would normally use bus_num=2 for that controller.
     */
    s16            bus_num;

    /* chipselects will be integral to many controllers; some others
     * might use board-specific GPIOs.
     */
    u16            num_chipselect;

    /* some SPI controllers pose alignment requirements on DMAable
     * buffers; let protocol drivers know about these requirements.
     */
    u16            dma_alignment;

    /* spi_device.mode flags understood by this controller driver */
    u16            mode_bits;

    /* other constraints relevant to this driver */
    u16            flags;
#define SPI_MASTER_HALF_DUPLEX    BIT(0)        /* can‘t do full duplex */
#define SPI_MASTER_NO_RX    BIT(1)        /* can‘t do buffer read */
#define SPI_MASTER_NO_TX    BIT(2)        /* can‘t do buffer write */

    /* lock and mutex for SPI bus locking */
    spinlock_t        bus_lock_spinlock;
    struct mutex        bus_lock_mutex;

    /* flag indicating that the SPI bus is locked for exclusive use */
    bool            bus_lock_flag;

    /* Setup mode and clock, etc (spi driver may call many times).　　
     *
     * IMPORTANT:  this may be called when transfers to another
     * device are active.  DO NOT UPDATE SHARED REGISTERS in ways
     * which could break those transfers.
     */
    int            (*setup)(struct spi_device *spi);

    /* bidirectional bulk transfers
     *
     * + The transfer() method may not sleep; its main role is
     *   just to add the message to the queue.
     * + For now there‘s no remove-from-queue operation, or
     *   any other request management
     * + To a given spi_device, message queueing is pure fifo
     *
     * + The master‘s main job is to process its message queue,
     *   selecting a chip then transferring data
     * + If there are multiple spi_device children, the i/o queue
     *   arbitration algorithm is unspecified (round robin, fifo,
     *   priority, reservations, preemption, etc)
     *
     * + Chipselect stays active during the entire message
     *   (unless modified by spi_transfer.cs_change != 0).
     * + The message transfers use clock and SPI mode parameters
     *   previously established by setup() for this device
     */
    int            (*transfer)(struct spi_device *spi,
                        struct spi_message *mesg);

    /* called on release() to free memory provided by spi_master */
    void            (*cleanup)(struct spi_device *spi);
};

分配、注册和注销SPI主控制器的API由SPI核心层提供（drivers/spi/spi.c）：

struct spi_master *spi_alloc_master(struct device *dev, unsigned size);
int spi_register_master(struct spi_master *master);
void spi_unregister_master(struct spi_master *master);

在3.0.35 内核中使用 spi_driver 结构体来描述一个SPI外设驱动，可以认为是spi_master 的 client 驱动

spi_driver 结构体定义（include/linux/spi/spi.h）如下：

/**
 * struct spi_driver - Host side "protocol" driver
 * @id_table: List of SPI devices supported by this driver
 * @probe: Binds this driver to the spi device.  Drivers can verify
 *    that the device is actually present, and may need to configure
 *    characteristics (such as bits_per_word) which weren‘t needed for
 *    the initial configuration done during system setup.
 * @remove: Unbinds this driver from the spi device
 * @shutdown: Standard shutdown callback used during system state
 *    transitions such as powerdown/halt and kexec
 * @suspend: Standard suspend callback used during system state transitions
 * @resume: Standard resume callback used during system state transitions
 * @driver: SPI device drivers should initialize the name and owner
 *    field of this structure.
 *
 * This represents the kind of device driver that uses SPI messages to
 * interact with the hardware at the other end of a SPI link.  It‘s called
 * a "protocol" driver because it works through messages rather than talking
 * directly to SPI hardware (which is what the underlying SPI controller
 * driver does to pass those messages).  These protocols are defined in the
 * specification for the device(s) supported by the driver.
 *
 * As a rule, those device protocols represent the lowest level interface
 * supported by a driver, and it will support upper level interfaces too.
 * Examples of such upper levels include frameworks like MTD, networking,
 * MMC, RTC, filesystem character device nodes, and hardware monitoring.
 */
struct spi_driver {
    const struct spi_device_id *id_table;
    int            (*probe)(struct spi_device *spi);
    int            (*remove)(struct spi_device *spi);
    void            (*shutdown)(struct spi_device *spi);
    int            (*suspend)(struct spi_device *spi, pm_message_t mesg);
    int            (*resume)(struct spi_device *spi);
    struct device_driver    driver;
};

可以看出，spi_driver 结构体和 platform_driver 结构体有极大的相似性，都有 probe(), remove(), shutdown(), suspend(), resume()这样

的接口。这几乎是一切client 端驱动的习惯模板。

在SPI 外设驱动中，当透过SPI总线进行数据传输的时候，使用了一套与CPU无关的统一接口。这套接口的第一个关键数据结构就是spi_transfer，

它用于描述SPI传输，如下示：（include/linux/spi/spi.h）

/*
 * I/O INTERFACE between SPI controller and protocol drivers
 *
 * Protocol drivers use a queue of spi_messages, each transferring data
 * between the controller and memory buffers.
 *
 * The spi_messages themselves consist of a series of read+write transfer
 * segments.  Those segments always read the same number of bits as they
 * write; but one or the other is easily ignored by passing a null buffer
 * pointer.  (This is unlike most types of I/O API, because SPI hardware
 * is full duplex.)
 *
 * NOTE:  Allocation of spi_transfer and spi_message memory is entirely
 * up to the protocol driver, which guarantees the integrity of both (as
 * well as the data buffers) for as long as the message is queued.
 */
struct spi_transfer {
    /* it‘s ok if tx_buf == rx_buf (right?)
     * for MicroWire, one buffer must be null
     * buffers must work with dma_*map_single() calls, unless
     *   spi_message.is_dma_mapped reports a pre-existing mapping
     */
    const void    *tx_buf;
    void        *rx_buf;
    unsigned    len;

    dma_addr_t    tx_dma;
    dma_addr_t    rx_dma;

    unsigned    cs_change:1;
    u8        bits_per_word;
    u16        delay_usecs;
    u32        speed_hz;

    struct list_head transfer_list;
};

而一次完整的SPI传输流程可能不只包含一次spi_transfer，它可能包含一个或多个spi_transfer, 这些 spi_transfer 最终通过spi_message 组织在一起

其定义如下（include/linux/spi/spi.h）：

struct spi_message {
    struct list_head    transfers;

    struct spi_device    *spi;

    unsigned        is_dma_mapped:1;

    /* REVISIT:  we might want a flag affecting the behavior of the
     * last transfer ... allowing things like "read 16 bit length L"
     * immediately followed by "read L bytes".  Basically imposing
     * a specific message scheduling algorithm.
     *
     * Some controller drivers (message-at-a-time queue processing)
     * could provide that as their default scheduling algorithm.  But
     * others (with multi-message pipelines) could need a flag to
     * tell them about such special cases.
     */

    /* completion is reported through a callback */
    void            (*complete)(void *context);
    void            *context;
    unsigned        actual_length;
    int            status;

    /* for optional use by whatever driver currently owns the
     * spi_message ...  between calls to spi_async and then later
     * complete(), that‘s the spi_master controller driver.
     */
    struct list_head    queue;
    void            *state;
};

通过spi_message_init() 可以初始化spi_message，而将 spi_transfer 添加到 spi_message 的法则是：

static inline void
spi_message_add_tail(struct spi_transfer *t, struct spi_message *m)
{
    list_add_tail(&t->transfer_list, &m->transfers);
}

发起一次spi_message 的传输有同步和异步两种方式，使用同步API时，会阻塞等待这个消息被处理完，同步操作时，使用的API如下：

int spi_sync(struct spi_device *spi, struct spi_message *message);

使用异步API时，不会阻塞等待这个消息被处理完，但是可以在spi_message 的complete 字段挂载一个回调函数，当消息被处理完成后

该函数会被自动调用。异步操作时使用的API如下：

int spi_async(struct spi_device *spi, struct spi_message *message);

如下是一个典型的初始化spi_transfer, spi_message, 并进行spi数据传输的例子，同时它也是SPI核心层的一个通用API，

在SPI外设驱动中可以直接调用它进行读写操作。

/**
 * spi_write_then_read - SPI synchronous write followed by read
 * @spi: device with which data will be exchanged
 * @txbuf: data to be written (need not be dma-safe)
 * @n_tx: size of txbuf, in bytes
 * @rxbuf: buffer into which data will be read (need not be dma-safe)
 * @n_rx: size of rxbuf, in bytes
 * Context: can sleep
 *
 * This performs a half duplex MicroWire style transaction with the
 * device, sending txbuf and then reading rxbuf.  The return value
 * is zero for success, else a negative errno status code.
 * This call may only be used from a context that may sleep.
 *
 * Parameters to this routine are always copied using a small buffer;
 * portable code should never use this for more than 32 bytes.
 * Performance-sensitive or bulk transfer code should instead use
 * spi_{async,sync}() calls with dma-safe buffers.
 */
int spi_write_then_read(struct spi_device *spi,
        const void *txbuf, unsigned n_tx,
        void *rxbuf, unsigned n_rx)
{
    static DEFINE_MUTEX(lock);

    int            status;
    struct spi_message    message;
    struct spi_transfer    x[2];
    u8            *local_buf;

    /* Use preallocated DMA-safe buffer.  We can‘t avoid copying here,
     * (as a pure convenience thing), but we can keep heap costs
     * out of the hot path ...
     */
    if ((n_tx + n_rx) > SPI_BUFSIZ)
        return -EINVAL;

    spi_message_init(&message);
    memset(x, 0, sizeof x);
    if (n_tx) {
        x[0].len = n_tx;
        spi_message_add_tail(&x[0], &message);
    }
    if (n_rx) {
        x[1].len = n_rx;
        spi_message_add_tail(&x[1], &message);
    }

    /* ... unless someone else is using the pre-allocated buffer */
    if (!mutex_trylock(&lock)) {
        local_buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);
        if (!local_buf)
            return -ENOMEM;
    } else
        local_buf = buf;

    memcpy(local_buf, txbuf, n_tx);
    x[0].tx_buf = local_buf;
    x[1].rx_buf = local_buf + n_tx;

    /* do the i/o */
    status = spi_sync(spi, &message);
    if (status == 0)
        memcpy(rxbuf, x[1].rx_buf, n_rx);

    if (x[0].tx_buf == buf)
        mutex_unlock(&lock);
    else
        kfree(local_buf);

    return status;
}
EXPORT_SYMBOL_GPL(spi_write_then_read);

SPI只是一种总线，spi_driver 有作用只是将spi外设挂接在该总线上，因此在spi_driver 的probe() 成员函数中，将注册SPI外设本身所属设备的驱动类型。

和platform_driver 对应着一个platform_device一样，spi_driver也对应一个spi_device，platform_device需要在BSP的板文件中添加板信息数据，而

spi_device也同样需要。spi_device 的板信息用 spi_board_info 结构体描述，定义如下（include/linux/spi/spi.h）：

struct spi_board_info {
    /* the device name and module name are coupled, like platform_bus;
     * "modalias" is normally the driver name.
     *
     * platform_data goes to spi_device.dev.platform_data,
     * controller_data goes to spi_device.controller_data,
     * irq is copied too
     */
    char        modalias[SPI_NAME_SIZE];
    const void    *platform_data;
    void        *controller_data;
    int        irq;

    /* slower signaling on noisy or low voltage boards */
    u32        max_speed_hz;

    /* bus_num is board specific and matches the bus_num of some
     * spi_master that will probably be registered later.
     *
     * chip_select reflects how this chip is wired to that master;
     * it‘s less than num_chipselect.
     */
    u16        bus_num;
    u16        chip_select;

    /* mode becomes spi_device.mode, and is essential for chips
     * where the default of SPI_CS_HIGH = 0 is wrong.
     */
    u8        mode;

    /* ... may need additional spi_device chip config data here.
     * avoid stuff protocol drivers can set; but include stuff
     * needed to behave without being bound to a driver:
     *  - quirks like clock rate mattering when not selected
     */
};

该结构体描述了SPI外设使用的主机控制器序号，片选序号，数据比特率，SPI传输模式。