本應用筆記以驅動SPI接口的OLED顯示屏為例，說明了如何添加SPI設備驅動框架及底層硬件驅動，使用SPI設備驅動接口開發應用程序。并給出了在正點原子STM32F4探索者開發板上驗證的代碼示例。

1 本文的目的和結構

1.1 本文的目的和背景

串行外設接口（Serial Peripheral Interface Bus，SPI），是一種用于短程通信的同步串行通信接口規范，主要應用于單片機系統中。SPI主要應用于 EEPROM、FLASH、實時時鐘、AD轉換器、數字信號處理器和數字信號解碼器等。在芯片的管腳上占用四根線或三根線，簡單易用，因此越來越多的芯片集成了這種通信接口。

為了方便應用層程序開發，RT-Thread中引入了SPI設備驅動框架。本文說明了如何使用RT-Thread SPI設備驅動。

1.2 本文的結構

本文首先簡要介紹了RT-Thread SPI設備驅動框架，然后在正點原子STM32F4探索者開發板上運行了SPI設備驅動示例代碼。最后詳細描述SPI設備驅動框架接口的使用方法及參數取值。

2 SPI設備驅動框架簡介

RT-Thread SPI設備驅動框架把MCU的SPI硬件控制器虛擬成SPI總線（SPI BUS#n），總線上可以掛很多SPI設備(SPI BUS#0 CSm)，每個SPI設備只能掛載到一個SPI總線上。目前，RT-Thread已經實現了很多通用SPI設備的驅動，比如SD卡、各種系列Flash存儲器、ENC28J60以太網模塊等。SPI設備驅動框架的層次結構如下圖所示。

圖2-1SPI設備驅動框架層次結構體

基于前面的介紹用戶已經大致了解了RT-Thread SPI設備驅動框架，那么用戶如何使用SPI設備驅動框架呢？

3 運行示例代碼

本章節基于正點原子探索者STM32F4 開發板及SPI示例代碼，給出了RT-Thread SPI設備驅動框架的使用方法。

3.1 示例代碼軟硬件資源

RT-Thread 源碼

ENV工具

SPI設備驅動示例代碼

正點原子STM32F4探索者開發板

1.5寸彩色OLED顯示屏(SSD1351控制器)

MDK5

正點原子探索者STM32F4 開發板的MCU是STM32F407ZGT6，本示例使用USB轉串口（USART1）發送數據及供電，使用SEGGER J-LINK連接JTAG調試，STM32F4 有多個硬件SPI控制器，本例使用 SPI1。彩色OLED顯示屏板載SSD1351控制器，分辨率128*128。

STM32F4 與 OLED 顯示屏管腳連接如下表所示：

STM32管腳	OLED顯示屏管腳	說明
PA5	D0	SPI1 SCK，時鐘
PA6		SPI1 MISO，未使用
PA7	D1	SPI1 MOSI，主機輸出，從機輸入
PC6	D/C	GPIO，輸出，命令0/數據1選擇
PC7	RES	GPIO，輸出，復位，低電平有效
PC8	CS	GPIO，輸出，片選，低電平有效
3.3V	VCC	供電
GND	GND	接地

圖3.1-1 正點原子開發板

圖3.1-2 彩色OLED顯示屏

SPI設備驅動示例代碼包括app.c、drv_ssd1351.c、drv_ssd1351.h3個文件，drv_ssd1351.c是OLED顯示屏驅動文件，此驅動文件包含了SPI設備ssd1351的初始化、掛載到系統及通過命令控制OLED顯示的操作方法。由于RT-Thread上層應用API的通用性，因此這些代碼不局限于具體的硬件平臺，用戶可以輕松將它移植到其它平臺上。

3.2 配置工程

使用menuconfig配置工程：在env工具命令行使用cd 命令進入 rt-threadspstm32f4xx-HAL 目錄，然后輸入menuconfig命令進入配置界面。

修改工程芯片型號：修改 Device type為STM32F407ZG。

配置shell使用串口1：選中Using UART1，進入RT-Thread Kernel ---> Kernel Device Object菜單，修改the device name for console為uart1。

開啟SPI總線及設備驅動并注冊SPI總線到系統：進入RT-Thread Components ---> Device Drivers菜單，選中Using SPI Bus/Device device drivers，RT-Thread Configuration界面會默認選中Using SPI1，spi1總線設備會注冊到操作系統。

圖3.2-1 使用menuconfig開啟SPI

開啟GPIO驅動：進入RT-Thread Components ---> Device Drivers菜單，選中Using generic GPIO device drivers。OLED屏需要2個額外的GPIO用于DC、RES信號，SPI總線驅動也需要對片選管腳進行操作，都需要調用系統的GPIO驅動接口。

生成新工程及修改調試選項：退出menuconfig配置界面并保存配置，在ENV命令行輸入scons --target=mdk5 -s命令生成mdk5工程，新工程名為project。使用MDK5打開工程，修改調試選項為J-LINK。

圖3.2-2 修改調試選項

使用list_device命令查看SPI總線：添加SPI底層硬件驅動無誤后，在終端PuTTY(打開對應端口，波特率配置為115200)使用list_device命令就能看到SPI總線。同樣可以看到我們使用的UART設備和PIN設備。

圖3.2-3使用list_device命令查看系統設備

3.3 添加示例代碼

將SPI設備驅動示例代碼里的app.c拷貝到 t-threadspstm32f4xx-HALapplications目錄下。drv_ssd1351.c、drv_ssd1351.h拷貝到 t-threadspstm32f4xx-HALdrivers目錄下，并將它們添加到工程中對應分組。如圖所示：

圖3.3-1 添加示例代碼到工程

在main.c中調用app_init()，app_init()會創建一個oled線程，線程會循環展示彩虹顏色圖案和正方形顏圖案。

main.c調用測試代碼源碼如下:

#include #include extern int app_init(void); int main(void) { /* user app entry */ app_init(); return 0; }

圖3.3-2 使用list_device命令查看SPI設備驅動

圖3.3-3 實驗現象

4 SPI設備驅動接口使用詳解

按照前文的步驟，相信讀者能很快的將RT-Thread SPI設備驅動運行起來，那么如何使用SPI設備驅動接口開發應用程序呢？

RT-Thread SPI設備驅動使用流程大致如下：

定義SPI設備對象，調用rt_spi_bus_attach_device()掛載SPI設備到SPI總線。

調用rt_spi_configure()配置SPI總線模式。

使用rt_spi_send()等相關數據傳輸接口傳輸數據。

接下來本章節將詳細講解示例代碼使用到的主要的SPI設備驅動接口。

4.1 掛載SPI設備到總線

用戶定義了SPI設備對象后就可以調用此函數掛載SPI設備到SPI總線。

函數原型:

rt_err_t rt_spi_bus_attach_device(struct rt_spi_device *device, const char *name, const char *bus_name, void *user_data)

參數	描述
device	SPI設備句柄
name	SPI設備名稱
bus_name	SPI總線名稱
user_data	用戶數據指針

函數返回：成功返回RT_EOK，否則返回錯誤碼。

此函數用于掛載一個SPI設備到指定的SPI總線，向內核注冊SPI設備，并將user_data保存到SPI設備device里。

注意

用戶首先需要定義好SPI設備對象device

推薦SPI總線命名原則為spix， SPI設備命名原則為spixy，如 本示例的spi10 表示掛載在在 spi1 總線上的 0 號設備。

SPI總線名稱可以在msh shell輸入list_device 命令查看，確定SPI設備要掛載的SPI總線。

user_data一般為SPI設備的CS引腳指針，進行數據傳輸時SPI控制器會操作此引腳進行片選。

本文示例代碼底層驅動drv_ssd1351.c中rt_hw_ssd1351_config()掛載ssd1351設備到SPI總線源碼如下：

#define SPI_BUS_NAME "spi1" /* SPI總線名稱 */ #define SPI_SSD1351_DEVICE_NAME "spi10" /* SPI設備名稱 */ ... ... static struct rt_spi_device spi_dev_ssd1351; /* SPI設備ssd1351對象 */ static struct stm32_hw_spi_cs spi_cs; /* SPI設備CS片選引腳 */ ... ... static int rt_hw_ssd1351_config(void) { rt_err_t res; /* oled use PC8 as CS */ spi_cs.pin = CS_PIN; rt_pin_mode(spi_cs.pin, PIN_MODE_OUTPUT); /* 設置片選管腳模式為輸出 */ res = rt_spi_bus_attach_device(&spi_dev_ssd1351, SPI_SSD1351_DEVICE_NAME, SPI_BUS_NAME, (void*)&spi_cs); if (res != RT_EOK) { OLED_TRACE("rt_spi_bus_attach_device! "); return res; } ... ... }

4.2 配置SPI模式

掛載SPI設備到SPI總線后，為滿足不同設備的時鐘、數據寬度等要求，通常需要配置SPI模式、頻率參數。

SPI從設備的模式決定主設備的模式，所以SPI主設備的模式必須和從設備一樣兩者才能正常通訊。

函數原型:

rt_err_t rt_spi_configure(struct rt_spi_device *device, struct rt_spi_configuration *cfg)

參數	描述
device	SPI設備句柄
cfg	SPI傳輸配置參數指針

函數返回：返回RT_EOK。

此函數會保存cfg指向的模式參數到device里，當device調用數據傳輸函數時都會使用此配置信息。

struct rt_spi_configuration 原型如下：

struct rt_spi_configuration { rt_uint8_t mode; //spi模式 rt_uint8_t data_width; //數據寬度，可取8位、16位、32位 rt_uint16_t reserved; //保留 rt_uint32_t max_hz; //最大頻率 };

模式/mode:使用spi.h中的宏定義，包含MSB/LSB、主從模式、 時序模式等，可取宏組合如下。

/* 設置數據傳輸順序是MSB位在前還是LSB位在前 */ #define RT_SPI_LSB (0<<2) ? ? ? ? ? ? ? ? ? ? ? ?/* bit[2]: 0-LSB */ #define RT_SPI_MSB ? ? ?(1<<2) ? ? ? ? ? ? ? ? ? ? ? ?/* bit[2]: 1-MSB */ /* 設置SPI的主從模式 */ #define RT_SPI_MASTER ? (0<<3) ? ? ? ? ? ? ? ? ? ? ? ?/* SPI master device */ #define RT_SPI_SLAVE ? ?(1<<3) ? ? ? ? ? ? ? ? ? ? ? ?/* SPI slave device */ /* 設置時鐘極性和時鐘相位 */ #define RT_SPI_MODE_0 ? (0 | 0) ? ? ? ? ? ? ? ? ? ? ? /* CPOL = 0, CPHA = 0 */ #define RT_SPI_MODE_1 ? (0 | RT_SPI_CPHA) ? ? ? ? ? ? /* CPOL = 0, CPHA = 1 */ #define RT_SPI_MODE_2 ? (RT_SPI_CPOL | 0) ? ? ? ? ? ? /* CPOL = 1, CPHA = 0 */ #define RT_SPI_MODE_3 ? (RT_SPI_CPOL | RT_SPI_CPHA) ? /* CPOL = 1, CPHA = 1 */ #define RT_SPI_CS_HIGH ?(1<<4) ? ? ? ? ? ? ? ? ? ? ? ?/* Chipselect active high */ #define RT_SPI_NO_CS ? ?(1<<5) ? ? ? ? ? ? ? ? ? ? ? ?/* No chipselect */ #define RT_SPI_3WIRE ? ?(1<<6) ? ? ? ? ? ? ? ? ? ? ? ?/* SI/SO pin shared */ #define RT_SPI_READY ? ?(1<<7) ? ? ? ? ? ? ? ? ? ? ? ?/* Slave pulls low to pause */

數據寬度/data_width:根據SPI主設備及SPI從設備可發送及接收的數據寬度格式設置為8位、16位或者32位。

最大頻率/max_hz:設置數據傳輸的波特率，同樣根據SPI主設備及SPI從設備工作的波特率范圍設置。

注意

掛載SPI設備到SPI總線后必須使用此函數配置SPI設備的傳輸參數。

本文示例代碼底層驅動drv_ssd1351.c中rt_hw_ssd1351_config()配置SPI傳輸參數源碼如下：

static int rt_hw_ssd1351_config(void) { ... ... /* config spi */ { struct rt_spi_configuration cfg; cfg.data_width = 8; cfg.mode = RT_SPI_MASTER | RT_SPI_MODE_0 | RT_SPI_MSB; cfg.max_hz = 20 * 1000 *1000; /* 20M,SPI max 42MHz,ssd1351 4-wire spi */ rt_spi_configure(&spi_dev_ssd1351, &cfg); } ... ...

4.3 數據傳輸

SPI設備掛載到SPI總線并配置好相關SPI傳輸參數后就可以調用RT-Thread提供的一系列SPI設備驅動數據傳輸函數。

rt_spi_transfer_message()

函數原型:

struct rt_spi_message *rt_spi_transfer_message(struct rt_spi_device *device, struct rt_spi_message *message)

參數	描述
device	SPI設備句柄
message	消息指針

函數返回： 成功發送返回RT_NULL，否則返回指向剩余未發送的message

此函數可以傳輸一連串消息，用戶可以很靈活的設置message結構體各參數的數值，從而可以很方便的控制數據傳輸方式。

struct rt_spi_message原型如下：

struct rt_spi_message { const void *send_buf; /* 發送緩沖區指針 */ void *recv_buf; /* 接收緩沖區指針 */ rt_size_t length; /* 發送/接收 數據字節數 */ struct rt_spi_message *next; /* 指向繼續發送的下一條消息的指針 */ unsigned cs_take : 1; /* 值為1，CS引腳拉低，值為0,不改變引腳狀態 */ unsigned cs_release : 1; /* 值為1，CS引腳拉高，值為0,不改變引腳狀態 */ };

SPI是一種全雙工的通信總線，發送一字節數據的同時也會接收一字節數據，參數length為傳輸一次數據時發送/接收的數據字節數，發送的數據為send_buf指向的緩沖區數據，接收到的數據保存在recv_buf指向的緩沖區。若忽視接收的數據則recv_buf值為NULL，若忽視發送的數據只接收數據，則send_buf值為NULL。

參數next是指向繼續發送的下一條消息的指針，若只發送一條消息，則此指針值置為NULL。

rt_spi_send()

函數原型:

rt_size_t rt_spi_send(struct rt_spi_device *device, const void *send_buf, rt_size_t length)

參數	描述
device	SPI設備句柄
send_buf	發送緩沖區指針
length	發送數據的字節數

函數返回： 成功發送的數據字節數

調用此函數發送send_buf指向的緩沖區的數據，忽略接收到的數據。

此函數等同于調用rt_spi_transfer_message()傳輸一條消息，message參數配置如下：

struct rt_spi_message msg； msg.send_buf = send_buf; msg.recv_buf = RT_NULL; msg.length = length; msg.cs_take = 1; msg.cs_release = 1; msg.next = RT_NULL;

注意

調用此函數將發送一次數據。開始發送數據時片選開始，函數返回時片選結束。

本文示例代碼底層驅動drv_ssd1351.c調用rt_spi_send()向SSD1351發送指令和數據的函數源碼如下：

rt_err_t ssd1351_write_cmd(const rt_uint8_t cmd) { rt_size_t len; rt_pin_write(DC_PIN, PIN_LOW); /* 命令低電平 */ len = rt_spi_send(&spi_dev_ssd1351, &cmd, 1); if (len != 1) { OLED_TRACE("ssd1351_write_cmd error. %d ",len); return -RT_ERROR; } else { return RT_EOK; } } rt_err_t ssd1351_write_data(const rt_uint8_t data) { rt_size_t len; rt_pin_write(DC_PIN, PIN_HIGH); /* 數據高電平 */ len = rt_spi_send(&spi_dev_ssd1351, &data, 1); if (len != 1) { OLED_TRACE("ssd1351_write_data error. %d ",len); return -RT_ERROR; } else { return RT_EOK; } }

rt_spi_recv()

函數原型:

rt_size_t rt_spi_recv(struct rt_spi_device *device, void *recv_buf, rt_size_t length)

參數	描述
device	SPI設備句柄
recv_buf	接受緩沖區指針
length	接受到的數據字節數

函數返回： 成功接受的數據字節數

調用此函數將保存接受到的數據到recv_buf指向的緩沖區。

此函數等同于調用rt_spi_transfer_message()傳輸一條消息，message參數配置如下：

struct rt_spi_message msg； msg.send_buf = RT_NULL; msg.recv_buf = recv_buf; msg.length = length; msg.cs_take = 1; msg.cs_release = 1; msg.next = RT_NULL;

注意

調用此函數將接受一次數據。開始接收數據時片選開始，函數返回時片選結束。

rt_spi_send_then_send()

函數原型:

rt_err_t rt_spi_send_then_send(struct rt_spi_device *device, const void *send_buf1, rt_size_t send_length1, const void *send_buf2, rt_size_t send_length2);

參數	描述
device	SPI總線設備句柄
send_buf1	發送緩沖區1數據指針
send_length1	發送緩沖區數據字節數
send_buf2	發送緩沖區2數據指針
send_length2	發送緩沖區2數據字節數

函數返回： 成功返回RT_EOK，否則返回錯誤碼

此函數可以連續發送2個緩沖區的數據，忽略接收到的數據。發送send_buf1時片選開始，發送完send_buf2后片選結束。

此函數等同于調用rt_spi_transfer_message()傳輸2條消息，message參數配置如下：

struct rt_spi_message msg1,msg2； msg1.send_buf = send_buf1; msg1.recv_buf = RT_NULL; msg1.length = send_length1; msg1.cs_take = 1; msg1.cs_release = 0; msg1.next = &msg2; msg2.send_buf = send_buf2; msg2.recv_buf = RT_NULL; msg2.length = send_length2; msg2.cs_take = 0; msg2.cs_release = 1; msg2.next = RT_NULL;

rt_spi_send_then_recv()

函數原型:

rt_err_t rt_spi_send_then_recv(struct rt_spi_device *device, const void *send_buf, rt_size_t send_length, void *recv_buf, rt_size_t recv_length);

參數	描述
device	SPI總線設備句柄
send_buf	發送緩沖區數據指針
send_length	發送緩沖區數據字節數
recv_buf	接收緩沖區數據指針，spi是全雙工的，支持同時收發
length	接收緩沖區數據字節數

函數返回： 成功返回RT_EOK，否則返回錯誤碼

此函數發送第一條消息send_buf時開始片選，此時忽略接收到的數據，然后發送第二條消息，此時發送的數據為空，接收到的數據保存在recv_buf里，函數返回時片選結束。

此函數等同于調用rt_spi_transfer_message()傳輸2條消息，message參數配置如下：

struct rt_spi_message msg1,msg2； msg1.send_buf = send_buf; msg1.recv_buf = RT_NULL; msg1.length = send_length; msg1.cs_take = 1; msg1.cs_release = 0; msg1.next = &msg2; msg2.send_buf = RT_NULL; msg2.recv_buf = recv_buf; msg2.length = recv_length; msg2.cs_take = 0; msg2.cs_release = 1; msg2.next = RT_NULL;

rt_spi_sendrecv8()和rt_spi_sendrecv16()函數是對此函數的封裝，rt_spi_sendrecv8()發送一個字節數據同時收到一個字節數據，rt_spi_sendrecv16()發送2個字節數據同時收到2個字節數據。

4.4 SPI設備驅動應用

本文示例使用SSD1351顯示圖像信息，首先需要確定信息在顯示器上的行列起始地址，調用ssd1351_write_cmd()向SSD1351發送指令，調用ssd1351_write_data()向SSD1351發送數據，源代碼如下：

void set_column_address(rt_uint8_t start_address, rt_uint8_t end_address) { ssd1351_write_cmd(0x15); // Set Column Address ssd1351_write_data(start_address); // Default => 0x00 (Start Address) ssd1351_write_data(end_address); // Default => 0x7F (End Address) } void set_row_address(rt_uint8_t start_address, rt_uint8_t end_address) { ssd1351_write_cmd(0x75); // Set Row Address ssd1351_write_data(start_address); // Default => 0x00 (Start Address) ssd1351_write_data(end_address); // Default => 0x7F (End Address) }

5 參考

本文所有相關的API

SPI設備驅動框架所有API	頭文件
rt_spi_bus_register()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_bus_attach_device()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_configure ()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_send_then_send()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_send_then_recv()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_transfer()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_transfer_message()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_take_bus()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_release_bus()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_take()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_release()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_recv()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_send()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_sendrecv8()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_sendrecv16()	rt-threadcomponentsdriversincludedriversspi.h
rt_spi_message_append()	rt-threadcomponentsdriversincludedriversspi.h

示例代碼相關API	位置
ssd1351_write_cmd()	drv_ssd1351.c
ssd1351_write_data()	drv_ssd1351.c
rt_hw_ssd1351_config()	drv_ssd1351.c