RT-Thread/rt-thread
1
0
Fork 0
mirror of https://github.com/RT-Thread/rt-thread.git synced 2025-10-21 15:41:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4942 from Jackistang/master

Browse Source 
[add] add commets for ringbuffer and workqueue.
This commit is contained in:
guo
2021-08-19 09:51:37 +08:00
committed by GitHub
parent d71e2ac582 4c6b4028e3
commit a98860d146
4 changed files with 179 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
components/drivers/src/ringbuffer.c
View File

@@ -9,6 +9,7 @@
* 2013-05-08 Grissiom reimplement
* 2016-08-18 heyuanjie add interface
* 2021-07-20 arminker fix write_index bug in function rt_ringbuffer_put_force
* 2021-08-14 Jackistang add comments for function interface.
*/
#include <rtthread.h>
@@ -27,6 +28,13 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb
return RT_RINGBUFFER_HALFFULL;
}
/**
* @brief Initialize the ring buffer object.
*
* @param rb A pointer to the ring buffer object.
* @param pool A pointer to the buffer.
* @param size The size of the buffer in bytes.
*/
void rt_ringbuffer_init(struct rt_ringbuffer *rb,
rt_uint8_t *pool,
rt_int16_t size)
@@ -45,7 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb,
RTM_EXPORT(rt_ringbuffer_init);
/**
* put a block of data into ring buffer
* @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will discard out-of-range data.
*
* @param rb A pointer to the ring buffer object.
* @param ptr A pointer to the data buffer.
* @param length The size of data in bytes.
*
* @return Return the data size we put into the ring buffer.
*/
rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
const rt_uint8_t *ptr,
@@ -92,9 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
RTM_EXPORT(rt_ringbuffer_put);
/**
* put a block of data into ring buffer
* @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will overwrite the existing data in the ring buffer.
*
* When the buffer is full, it will discard the old data.
* @param rb A pointer to the ring buffer object.
* @param ptr A pointer to the data buffer.
* @param length The size of data in bytes.
*
* @return Return the data size we put into the ring buffer.
*/
rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
const rt_uint8_t *ptr,
@@ -149,7 +167,13 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
RTM_EXPORT(rt_ringbuffer_put_force);
/**
* get data from ring buffer
* @brief Get data from the ring buffer.
*
* @param rb A pointer to the ring buffer.
* @param ptr A pointer to the data buffer.
* @param length The size of the data we want to read from the ring buffer.
*
* @return Return the data size we read from the ring buffer.
*/
rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
rt_uint8_t *ptr,
@@ -196,7 +220,14 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
RTM_EXPORT(rt_ringbuffer_get);
/**
* peak data from ring buffer
* @brief Get the first readable byte of the ring buffer.
*
* @param rb A pointer to the ringbuffer.
* @param ptr When this function return, *ptr is a pointer to the first readable byte of the ring buffer.
*
* @note It is recommended to read only one byte, otherwise it may cause buffer overflow.
*
* @return Return the size of the ring buffer.
*/
rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
{
@@ -230,7 +261,12 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
RTM_EXPORT(rt_ringbuffer_peak);
/**
* put a character into ring buffer
* @brief Put a byte into the ring buffer. If ring buffer is full, this operation will fail.
*
* @param rb A pointer to the ring buffer object.
* @param ch A byte put into the ring buffer.
*
* @return Return the data size we put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1.
*/
rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
{
@@ -258,9 +294,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
RTM_EXPORT(rt_ringbuffer_putchar);
/**
* put a character into ring buffer
* @brief Put a byte into the ring buffer. If ring buffer is full, it will discard an old data and put into a new data.
*
* When the buffer is full, it will discard one old data.
* @param rb A pointer to the ring buffer object.
* @param ch A byte put into the ring buffer.
*
* @return Return the data size we put into the ring buffer. Always return 1.
*/
rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch)
{
@@ -295,7 +334,13 @@ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t
RTM_EXPORT(rt_ringbuffer_putchar_force);
/**
* get a character from a ringbuffer
* @brief Get a byte from the ring buffer.
*
* @param rb The pointer to the ring buffer object.
* @param ch A pointer to the buffer, used to store one byte.
*
* @return 0 The ring buffer is empty.
* @return 1 Success
*/
rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
{
@@ -305,7 +350,7 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
if (!rt_ringbuffer_data_len(rb))
return 0;
/* put character */
/* put byte */
*ch = rb->buffer_ptr[rb->read_index];
if (rb->read_index == rb->buffer_size-1)
@@ -323,7 +368,11 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
RTM_EXPORT(rt_ringbuffer_getchar);
/**
* get the size of data in rb
* @brief Get the size of data in the ring buffer in bytes.
*
* @param rb The pointer to the ring buffer object.
*
* @return Return the size of data in the ring buffer in bytes.
*/
rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
{
@@ -348,7 +397,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
RTM_EXPORT(rt_ringbuffer_data_len);
/**
* empty the rb
* @brief Reset the ring buffer object, and clear all contents in the buffer.
*
* @param rb A pointer to the ring buffer object.
*/
void rt_ringbuffer_reset(struct rt_ringbuffer *rb)
{
@@ -363,7 +414,14 @@ RTM_EXPORT(rt_ringbuffer_reset);
#ifdef RT_USING_HEAP
struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size)
/**
* @brief Create a ring buffer object with a given size.
*
* @param size The size of the buffer in bytes.
*
* @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means this creation failed.
*/
struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size)
{
struct rt_ringbuffer *rb;
rt_uint8_t *pool;
@@ -390,6 +448,11 @@ exit:
}
RTM_EXPORT(rt_ringbuffer_create);
/**
* @brief Destroy the ring buffer object, which is created by rt_ringbuffer_create() .
*
* @param rb A pointer to the ring buffer object.
*/
void rt_ringbuffer_destroy(struct rt_ringbuffer *rb)
{
RT_ASSERT(rb != RT_NULL);