面向ametal框架與接口的編程ametal uart總線

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

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

5.8 UART 總線

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

>>> 5.8.1 初始化

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

表5.23 UART 實例初始化函數(shù)（am_lpc82x_inst_init.h）

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

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

>>> 5.8.2 接口函數(shù)

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

表5.24 UART 標準接口函數(shù)

1． UART 控制

實現(xiàn)UART 的常見的控制，比如，波特率、數(shù)據(jù)位數(shù)和奇偶校驗等。其函數(shù)原型為：

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

表5.25 UART 常用控制命令

表5.26 UART 硬件參數(shù)

表5.27 UART 模式

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

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

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

2． UART 發(fā)送（查詢模式）

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

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

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

3． UART 接收（查詢模式）

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

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

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

4． 設置回調函數(shù)（中斷模式）

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

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

表5.28 callback_type 的含義（am_uart.h）

以獲取一個待發(fā)送的字符為例，pfn_callback 參數(shù)的類型為am_uart_txchar_get_t：

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

程序清單5.104 設置“獲取發(fā)送數(shù)據(jù)的回調函數(shù)”范例程序

以提交一個已經(jīng)接收到的字符為例，pfn_callback 參數(shù)的類型為am_uart_rxchar_put_t：

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

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

5． 啟動發(fā)送（中斷模式）

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

使用中斷模式收發(fā)數(shù)據(jù)的范例程序詳見程序清單5.106。

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

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

>>> 5.8.3 帶緩沖區(qū)的UART 接口

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

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

表5.29 帶緩沖區(qū)的UART 通用接口函數(shù)（am_uart_rngbuf.h）

1． 初始化

指定關聯(lián)的串口外設（相應串口的實例句柄handle），以及用于發(fā)送和接收的數(shù)據(jù)緩沖區(qū)，初始化一個帶緩沖區(qū)的串口實例，其函數(shù)原型為：

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

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

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

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

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

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

2． 發(fā)送數(shù)據(jù)

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

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

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

注意，當該函數(shù)返回時，數(shù)據(jù)僅僅只是存放到了發(fā)送緩沖區(qū)中，并不代表已經(jīng)成功地將數(shù)據(jù)發(fā)送出去了。

3． 接收數(shù)據(jù)

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

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

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

4． 控制函數(shù)

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

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

表5.30 帶緩沖區(qū)的UART 擴展控制命令

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

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

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

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

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