周立功教授新書《面向AMetal框架與接口的編程（上）》，對AMetal框架進行了詳細介紹，通過閱讀這本書，你可以學到高度復用的軟件設計原則和面向接口編程的開發思想，聚焦自己的“核心域”，改變自己的編程思維，實現企業和個人的共同進步。經周立功教授授權，即日起，致遠電子公眾號將對該書內容進行連載，愿共勉之。

第五章為深入淺出AMetal，本文內容為5.8 UART 總線。

5.8 UART 總線

UART（Universal Asynchronous Receiver/Transmitter）是一種通用異步收發傳輸器，其使用串行的方式在雙機之間進行數據交換，實現全雙工通信，數據引腳僅包含用于接收數據的RXD 和用于發送數據的TXD。

>>> 5.8.1 初始化

在使用UART 接口前，必須先完成UART 的初始化，獲取標準UART 實例句柄。在LPC82x 中，能夠提供UART 服務的外設有USART0、USART1 和USART2。注意，USART和UART 的概念很容易混淆，USART 比UART 多了一個S——同步（Synchronous），USART支持同步和異步兩種通信方式，而UART 僅支持異步通信方式。同步方式與異步方式主要的區別在于，同步方式需要使用一根時鐘線進行時鐘的同步。由于使用較多的是異步通信方式，因此AMetal 僅僅提供了異步通信方式的通用接口，即LPC824 的USART 外設也僅被用作UART。為了方便用戶使用，AMetal 提供了與外設對應的實例初始化函數，詳見表5.23。

表5.23 UART 實例初始化函數（am_lpc82x_inst_init.h）

這些函數的返回值均為am_uart_handle_t 類型的UART 實例句柄，該句柄將作為UART通用接口中handle 參數的實參。類型am_uart_handle_t（am_uart.h）定義如下：

由于函數返回的UART 實例句柄僅作為參數傳遞給UART 通用接口，因此不需要對該句柄作其它任何操作。若函數返回的實例句柄的值為NULL，則表明初始化失敗，不能使用該實例句柄。如果使用串口0，則調用串口0 實例初始化函數，即可獲取對應的實例句柄：

>>> 5.8.2 接口函數

AMetal 提供了5 個與UART 相關的標準接口函數（am_uart.h），詳見表5.24。

表5.24 UART 標準接口函數

1． UART 控制

實現UART 的常見的控制，比如，波特率、數據位數和奇偶校驗等。其函數原型為：

常見命令與對應的p_arg 參數，UART 硬件參數與UART 模式分別詳見表5.25、表5.26和表5.27。

表5.25 UART 常用控制命令

表5.26 UART 硬件參數

表5.27 UART 模式

為了便于傳遞不同類型的值，通常將p_arg 設置為void *類型。比如，在設置波特率時，其類型為uint32_t；而在獲取波特率時，其類型為 uint32_t *。如果返回AM_OK，說明本次控制命令執行成功；如果返回-AM_EINVAL，說明因參數無效導致控制命令執行失敗。比如，設置UART 為查詢模式，波特率為115200，8 位數據位，無校驗，1 位停止位，使用范例詳見程序清單5.101。

程序清單5.101 am_uart_ioctl()范例程序

由于對應控制命令的參數均為uint32_t 類型，而函數形參為void *，因此需要使用強制類型轉換將uint32_t 強制轉換為 void *。

2． UART 發送（查詢模式）

如果以查詢的方式發送UART 數據，則該函數會等待發送結束后返回。其函數原型為：

在使用該函數前，應確保UART 工作在查詢模式，其返回值為成功發送數據的個數。比如，發送一個字符串"Hello World! "，詳見程序清單5.102。

程序清單5.102 am_uart_poll_send()范例程序

3． UART 接收（查詢模式）

如果以查詢的方式接收UART 數據，則該函數會等到指定個數的數據接收完成后返回。其函數原型為：

在使用該函數前，應確保UART 工作在查詢模式，其返回值為成功接收數據的個數。比如，從串口0 接收10 個數據，詳見程序清單5.103。

程序清單5.103 am_uart_poll_receive()范例程序

4． 設置回調函數（中斷模式）

由于在查詢模式下收發數據會阻塞程序，因此最好的方式是使用中斷模式發送數據。當中斷事件發生時，通過回調函數與應用程序交互。其函數原型為：

其中，callback_type 表示本次設置的類型，即設置發送回調函數還是接收回調函數，詳見表5.28。

表5.28 callback_type 的含義（am_uart.h）

以獲取一個待發送的字符為例，pfn_callback 參數的類型為am_uart_txchar_get_t：

當可以發送一個字符時，UART 驅動將自動調用設置的該類型回調函數，p_arg 為用戶自定義的參數（即為設置該類型回調函數時指定的p_arg），p_char 指針用于獲取一個待發送的字符，詳見程序清單5.104。

程序清單5.104 設置“獲取發送數據的回調函數”范例程序

以提交一個已經接收到的字符為例，pfn_callback 參數的類型為am_uart_rxchar_put_t：

當接收一個字符時，UART 驅動將自動調用設置的該類型函數，p_arg 為用戶自定義的參數（即為設置該類型回調函數時指定的p_arg），ch 為接收的字符數據，詳見程序清單5.105。

程序清單5.105 設置“提交已接收數據回調函數”范例程序

5． 啟動發送（中斷模式）

如果UART 使用中斷模式發送數據，當UART 發送器為空時，就會調用設置的“獲取發送數據的回調函數”以獲取發送數據。其函數原型為：

使用中斷模式收發數據的范例程序詳見程序清單5.106。

程序清單5.106 中斷模式范例程序

該程序的功能是將每次收到的10 個數據原封不動地發送出去，am_main()函數中的主循環可以不參與任何處理，即可實現串口數據的收發。

>>> 5.8.3 帶緩沖區的UART 接口

由于查詢模式會阻塞整個應用，因此在實際應用中幾乎都使用中斷模式。在中斷模式下，UART 每收到一個數據都會調用回調函數。如果將數據的處理放在回調函數中，很有可能因當前數據的處理還未結束而丟失下一個數據。基于此，AMetal 提供了帶緩沖區的UART 接收函數，其實現是在UART 中斷接收與應用程序之間，增加一個接收緩沖區。當串口收到數據時，將數據存放在緩沖區中，應用程序直接訪問緩沖區即可。

對于UART 發送，雖然不存在丟失數據的問題，但為了便于開發應用程序，避免在UART中斷模式下的回調函數接口中一次發送單個數據，同樣提供了帶緩沖區的UART 發送函數。當應用程序發送數據時，將發送數據存放在發送緩沖區中，串口在發送空閑時提取發送緩沖區中的數據進行發送。基于此，AMetal 提供了一組帶緩沖區的UART 通用接口，詳見表5.29。如無特殊需求，均建議使用帶緩沖區的UART 通用接口。

表5.29 帶緩沖區的UART 通用接口函數（am_uart_rngbuf.h）

1． 初始化

指定關聯的串口外設（相應串口的實例句柄handle），以及用于發送和接收的數據緩沖區，初始化一個帶緩沖區的串口實例，其函數原型為：

其中， p_dev 為指向am_uart_rngbuf_dev_t 類型的帶緩沖區的串口實例指針，在使用時，只需要定義一個am_uart_rngbuf_dev_t 類型（am_uart_rngbuf.h）的實例即可：

其中，g_uart0_rngbuf_dev 為用戶自定義的實例，其地址作為p_dev 的實參傳遞。handle為 UART 實例句柄，用于指定該帶緩沖區的串口實際關聯的串口。p_rxbuf 和rxbuf_size 用于指定接收緩沖區及其大小，p_txbuf 和txbuf_size 用于指定發送緩沖區及其大小。

函數的返回值為帶緩沖區串口的實例句柄，可用作其它通用接口函數中handle 參數的實參。其類型am_uart_rngbuf_handle_t（am_uart_rngbuf.h）定義如下：

如果返回值為NULL，表明初始化失敗，初始化函數使用范例詳見程序清單5.107。

程序清單5.107 am_uart_rngbuf_init()范例程序

雖然程序將緩沖區的大小設置為128，但實際上緩沖區的大小應根據實際情況確定。若接收數據的緩沖區過小，則可能在接收緩沖區滿后又接收新的數據發生溢出而丟失數據。若發送緩沖區過小，則在發送數據時很可能因為發送緩沖區已滿需要等待，直至發送緩沖區有空閑空間而造成等待過程。

2． 發送數據

發送數據就是將數據存放到am_uart_rngbuf_init()指定的發送緩沖區中，串口可以進行數據發送時（發送空閑），從發送緩沖區中提取需要發送的數據進行發送。其函數原型為：

該函數將數據成功存放到發送緩沖區后返回，返回值為成功寫入的數據個數。比如，發送一個字符串“Hello World!“，詳見程序清單5.108。

程序清單5.108 am_uart_rngbuf_send()范例程序

注意，當該函數返回時，數據僅僅只是存放到了發送緩沖區中，并不代表已經成功地將數據發送出去了。

3． 接收數據

接收數據就是從am_uart_rngbuf_init()指定的接收緩沖區中提取接收到的數據，其函數原型為：

該函數返回值為成功讀取數據的個數，使用范例詳見程序清單5.109。

程序清單5.109 am_uart_rngbuf_receive()范例程序

4． 控制函數

與UART 控制函數類似，用于完成一些基本的控制操作。其函數原型為：

“控制命令”和“對應命令的參數”，與UART 控制函數am_uart_ioctl()的含義類似。帶緩沖區的UART 可以看作是在UART 基礎上的一個擴展，因此絕大部分UART 控制函數的命令均可直接使用。之所以不支持“模式設置”命令，是因為帶緩沖區的UART 在初始化后始終工作在中斷模式，不能修改為查詢模式。除支持串口控制函數的絕大部分命令外，還新定義了一些擴展命令，詳見表5.30。

表5.30 帶緩沖區的UART 擴展控制命令

前5 條命令都是用于操作緩沖區的一些命令，“獲取可讀數據的個數”命令用于獲取接收緩沖區中已經接收的數據個數，“獲取已經寫入數據的個數”命令可以獲取當前已經寫入發送緩沖區中的數據個數。當不再需要發送或接收緩沖區的數據時，即可直接使用“清空緩沖區”命令將對應的緩沖區直接清空，其相應的范例程序詳見程序清單5.110。

程序清單5.110 am_uart_rngbuf_ioctl()范例程序

“設置讀超時時間”命令用于設置讀超時時間，該時間在am_uart_rngbuf_receive()接收數據時起作用。在接收數據時會指定接收數據的個數，在接收數據過程中，可能由于接收緩沖區中無數據可讀而進入等待狀態。在默認情況下，如果沒有設置讀超時時間，則會一直等到數據接收完成（接收到指定的數據個數）才會返回。當設置了超時時間后，假設設置超時時間為50ms，則在等待過程中超過50ms 都沒有接收到任何新數據時，函數同樣會返回，其返回值為實際接收到的數據個數，其相應的范例詳見程序清單5.111。

程序清單5.111 設置超時時間范例程序

注意，超時時間并不是每次接收數據前都需要設置，往往只需要設置一次。如果需要修改超時時間，可以使用該函數重新設置一個超時時間。特別地，若希望接收數據不足時立即返回，則可以設置超時時間為AM_NO_WAIT（am_common.h），若需要恢復為一直等待到數據接收完成才返回，則可以設置超時時間為AM_WAIT_FOREVER（am_common.h）。