優(yōu)雅地用宏實(shí)現(xiàn)環(huán)形緩沖區(qū)
之前寫的環(huán)行緩沖區(qū)文章
柔性數(shù)組和環(huán)形隊(duì)列之間的故事
循環(huán)緩沖區(qū)是嵌入式軟件工程師在日常開發(fā)過程中的關(guān)鍵組件。
多年來，互聯(lián)網(wǎng)上出現(xiàn)了許多不同的循環(huán)緩沖區(qū)實(shí)現(xiàn)和示例。我非常喜歡這個(gè)模塊，可以GitHub上找到這個(gè)開源的 CBUF.h 模塊。
地址：https://github.com/barraq/BRBrain/blob/master/firmware/CBUF.h
CBUF.h 模塊使用宏實(shí)現(xiàn)循環(huán)緩沖區(qū)，具體源碼如下所示；
#if !defined( CBUF_H )
#define CBUF_H /**< Include Guard */
/* ---- Include Files ---------------------------------------------------- */
/* ---- Constants and Types ---------------------------------------------- */
/**
* Initializes the circular buffer for use.
*/
#define CBUF_Init( cbuf ) cbuf.m_getIdx = cbuf.m_putIdx = 0
/**
* Returns the number of elements which are currently contained in the
* circular buffer.
*/
#define CBUF_Len( cbuf ) ((typeof( cbuf.m_putIdx ))(( cbuf.m_putIdx ) - ( cbuf.m_getIdx )))
/**
* Appends an element to the end of the circular buffer
*/
#define CBUF_Push( cbuf, elem ) (cbuf.m_entry)[ cbuf.m_putIdx++ & (( cbuf##_SIZE ) - 1 )] = (elem)
/**
* Retrieves an element from the beginning of the circular buffer
*/
#define CBUF_Pop( cbuf ) (cbuf.m_entry)[ cbuf.m_getIdx++ & (( cbuf##_SIZE ) - 1 )]
/**
* Retrieves the i'th element from the beginning of the circular buffer
*/
#define CBUF_Get( cbuf, idx ) (cbuf.m_entry)[( cbuf.m_getIdx + idx ) & (( cbuf##_SIZE ) - 1 )]
/**
* Retrieves the i'th element from the end of the circular buffer
*/
#define CBUF_GetEnd( cbuf, idx ) (cbuf.m_entry)[( cbuf.m_putIdx - idx - 1 ) & (( cbuf##_SIZE ) - 1 )]
/**
* Determines if the circular buffer is empty
*/
#define CBUF_IsEmpty( cbuf ) ( CBUF_Len( cbuf ) == 0 )
/**
* Determines if the circular buffer is full.
*/
#define CBUF_IsFull( cbuf ) ( CBUF_Len( cbuf ) == ( cbuf##_SIZE ))
/**
* Determines if the circular buffer is currenly overflowed or underflowed.
*/
#define CBUF_Error( cbuf ) ( CBUF_Len( cbuf ) > cbuf##_SIZE )
#if defined( __cplusplus )
template < class IndexType, unsigned Size, class EntryType >
class CBUF
{
public:
CBUF()
{
m_getIdx = m_putIdx = 0;
}
IndexType Len() const { return m_putIdx - m_getIdx; }
bool IsEmpty() const { return Len() == 0; }
bool IsFull() const { return Len() == Size; }
bool Error() const { return Len() > Size; }
void Push( EntryType val )
{
m_entry[ m_putIdx++ & ( Size - 1 )] = val;
}
EntryType Pop()
{
return m_entry[ m_getIdx++ & ( Size - 1 )];
}
private:
volatile IndexType m_getIdx;
volatile IndexType m_putIdx;
EntryType m_entry[ Size ];
};
#endif // __cplusplus
/* ---- Variable Externs ------------------------------------------------- */
/* ---- Function Prototypes ---------------------------------------------- */
/** @} */
#endif // CBUF_H
現(xiàn)在一般我不喜歡以這種方式使用宏，但實(shí)現(xiàn)已被證明是快速、高效且工作相對良好的，這是很難爭論的。
循環(huán)緩沖區(qū)的設(shè)置非常簡單。首先，需要定義循環(huán)緩沖區(qū)的大小。這是通過定義宏 myQ_SIZE 來完成的，同時(shí)記住緩沖區(qū)大小需要是 2 的冪。
然后通過創(chuàng)建一個(gè) myQ 類型的變量來聲明循環(huán)緩沖區(qū)。例如，如果 myQ_SIZE 定義為 64 字節(jié)，則可以定義 UART 的發(fā)送和接收緩沖區(qū)，如下面的圖 1 所示。
在此示例中，myQ 被定義為靜態(tài)以限制緩沖區(qū)的范圍并聲明為易失性，因?yàn)樗鼈冊谥袛鄡?nèi)被修改。定義循環(huán)緩沖區(qū)只是第一步。為了分配緩沖區(qū)，必須將這些變量傳遞給 CBUF_INIT 宏，如下圖 2 所示。
除了這個(gè)初始設(shè)置之外，緩沖區(qū)相當(dāng)簡單且易于使用。例如，可以使用 CBUF_PUSH 將通過串行接口接收 UART接收的字符推送到循環(huán)緩沖區(qū)，如圖 3 所示。
開發(fā)人員不僅希望將數(shù)據(jù)推送到循環(huán)緩沖區(qū)上，還希望從緩沖區(qū)彈出或獲取數(shù)據(jù)。看到這一點(diǎn)的一個(gè)簡單示例是需要獲取字符并通過 UART 傳輸?shù)拇邪l(fā)送器。圖 4 中可以看到一個(gè)示例傳輸函數(shù)。
在健壯的應(yīng)用程序中，還應(yīng)檢查循環(huán)緩沖區(qū)長度和溢出狀態(tài)。CBUF 模塊確實(shí)提供了能夠檢查這些重要指標(biāo)的宏。
要記住的一個(gè)重要問題是，如果需要對 CBUF 本身進(jìn)行任何調(diào)試，這是不可能的。無法為宏設(shè)置斷點(diǎn)，因此如果出現(xiàn)問題，則需要對模塊進(jìn)行功能化以逐步執(zhí)行和調(diào)試。
多年來使用這個(gè)模塊雖然我沒有發(fā)現(xiàn)任何問題。循環(huán)緩沖區(qū)是在嵌入式系統(tǒng)中與串行設(shè)備通信的一個(gè)重要方面。
循環(huán)緩沖區(qū)也很好理解，應(yīng)該創(chuàng)建它們以便它們可以模塊化并從一個(gè)應(yīng)用程序到下一個(gè)應(yīng)用程序重復(fù)使用。
到目前為止，CBUF 模塊已被證明是這樣一個(gè)模塊，所以在這里，我強(qiáng)烈推薦一下這個(gè)模塊。好了，今天的文章就到這里，我們下期再見。
再貼上代碼的注釋部分
/****************************************************************************
*
* Since this code originated from code which is public domain, I
* hereby declare this code to be public domain as well.
*
****************************************************************************/
/**
*
* @file CBUF.h
*
* @brief This file contains global definitions for circular buffer
* manipulation.
*
* These macros implement a circular buffer which employs get and put
* pointers, in such a way that mutual exclusion is not required
* (assumes one reader & one writer).
*
* It requires that the circular buffer size be a power of two, and the
* size of the buffer needs to smaller than the index. So an 8 bit index
* supports a circular buffer upto ( 1 << 7 ) = 128 entries, and a 16 bit index
* supports a circular buffer upto ( 1 << 15 ) = 32768 entries.
*
* The basis for these routines came from an article in Jack Ganssle's
* Embedded Muse: http://www.ganssle.com/tem/tem110.pdf
*
* In order to offer the most amount of flexibility for embedded environments
* you need to define a macro for the size.
*
* First, you need to name your circular buffer. For this example, we'll
* call it myQ.
*
* The size macro that needs to be defined will be the name of the
* circular buffer followed by _SIZE. The size must be a power of two
* and it needs to fit in the get/put indicies. i.e. if you use an
* 8 bit index, then the maximum supported size would be 128.
*
* The structure which defines the circular buffer needs to have 3 members
* m_getIdx, m_putIdx, and m_entry.
*
* m_getIdx and m_putIdx need to be unsigned integers of the same size.
*
* m_entry needs to be an array of xxx_SIZE entries, or a pointer to an
* array of xxx_SIZE entries. The type of each entry is entirely up to the
* caller.
*
* #define myQ_SIZE 64
*
* volatile struct
* {
* uint8_t m_getIdx;
* uint8_t m_putIdx;
* uint8_t m_entry[ myQ_SIZE ];
*
* } myQ;
*
* You could then use
*
* CBUF_Push( myQ, 'x' );
*
* to add a character to the circular buffer, or
*
* ch = CBUF_Pop( myQ );
*
* to retrieve an element from the buffer.
*
* If you happen to prefer to use C++ instead, there is a templatized
* version which requires no macros. You just declare 3 template parameters:
*
* - The type that should be used for the index
* - The size of the circular buffer
* - The type that should be used for the entry
*
* For example:
*
* CBUF< uint8_t, 64, char > myQ;
*
****************************************************************************/
推薦閱讀：