libs/rt-thread
libs
/
rt-thread
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[ringbuffer] 添加 ringbuffer 的接口注释

This commit is contained in:
Jackistang 2021-08-14 13:47:05 +08:00
parent 0b4603d581
commit 1b7468979f
4 changed files with 90 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
components/drivers/include/ipc/ringbuffer.h
View File

@ -5,6 +5,7 @@
*
* Change Logs:
* Date Author Notes
* 2021-08-14 Jackistang add commets for function inferface.
*/
#ifndef RINGBUFFER_H__
#define RINGBUFFER_H__
@ -80,6 +81,13 @@ struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t length);
void rt_ringbuffer_destroy(struct rt_ringbuffer *rb);
#endif
/**
* @brief Get buffer size of the ringbuffer object.
*
* @param rb A pointer to the ringbuffer object.
*
* @return Buffer size.
*/
rt_inline rt_uint16_t rt_ringbuffer_get_size(struct rt_ringbuffer *rb)
{
RT_ASSERT(rb != RT_NULL);

1
components/drivers/include/ipc/workqueue.h
View File

@ -6,6 +6,7 @@
* Change Logs:
* Date Author Notes
* 2021-08-01 Meco Man remove rt_delayed_work_init() and rt_delayed_work structure
* 2021-08-14 Jackistang add commets for rt_work_init()
*/
#ifndef WORKQUEUE_H__
#define WORKQUEUE_H__

91
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 commets for function inferface.
*/
#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 Init a ringbuffer object with a given buffer.
*
* @param rb A pointer to the ringbuffer object.
* @param pool A pointer to the buffer.
* @param size 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 ringbuffer. If the size of ringbuffer is not enough, it will discard out-of-range data.
*
* @param rb A pointer to the ringbuffer object.
* @param ptr A pointer to the data buffer.
* @param length The size of data in bytes.
*
* @return Return the size in bytes put into the ringbuffer actually.
*/
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
*
* When the buffer is full, it will discard the old data.
* @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will overwrite the existing data in the ringbuffer.
*
* @param rb A pointer to the ringbuffer object.
* @param ptr A pointer to the data buffer.
* @param length The size of data in bytes.
*
* @return Return the size in bytes put into the ringbuffer actually.
*/
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 a block of data from the ringbuffer.
*
* @param rb A pointer to the ringbuffer.
* @param ptr A pointer to the data buffer.
* @param length The size of data we want to read from the ringbuffer.
*
* @return Return the size of data we read from the ringbuffer actually.
*/
rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
rt_uint8_t *ptr,
@ -198,6 +222,15 @@ RTM_EXPORT(rt_ringbuffer_get);
/**
* peak data from ring buffer
*/
/**
* @brief Peak data from the ringbuffer.
*
* @param rb A pointer to the ringbuffer.
* @param ptr When this function return, *ptr is a pointer to the first character of ringbuffer.
*
* @return Return the size of ringbuffer.
*/
rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
{
RT_ASSERT(rb != RT_NULL);
@ -230,7 +263,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 character into the ringbuffer. If ringbuffer is full, This operation will fail.
*
* @param rb A pointer to the ringbuffer object.
* @param ch A character to be put into the ringbuffer.
*
* @return Return the size in bytes put into the ringbuffer. If return 0, it means the ringbuffer if full. If return 1, it means success.
*/
rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
{
@ -258,9 +296,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
*
* When the buffer is full, it will discard one old data.
* @brief Put a character into the ringbuffer. If ringbuffer is full, it will discard one old data and put into a new data.
*
* @param rb A pointer to the ringbuffer object.
* @param ch A character to be put into the ringbuffer.
*
* @return Return the size in bytes put into the ringbuffer. Always return 1.
*/
rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch)
{
@ -297,6 +338,16 @@ RTM_EXPORT(rt_ringbuffer_putchar_force);
/**
* get a character from a ringbuffer
*/
/**
* @brief Get a character from the ringbuffer.
*
* @param rb The pointer to ringbuffer object.
* @param ch The buffer to store character read from ringbuffer.
*
* @return 0 Ringbuffer is empty.
* @return 1 Success
*/
rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
{
RT_ASSERT(rb != RT_NULL);
@ -323,7 +374,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 ringbuffer in bytes.
*
* @param rb The pointer to ringbuffer object.
*
* @return Return the size of data in the ringbuffer in bytes.
*/
rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
{
@ -344,7 +399,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
RTM_EXPORT(rt_ringbuffer_data_len);
/**
* empty the rb
* @brief Reset the ringbuffer object, and clear all contents in the buffer.
*
* @param rb A pointer to the ringbuffer object.
*/
void rt_ringbuffer_reset(struct rt_ringbuffer *rb)
{
@ -359,6 +416,13 @@ RTM_EXPORT(rt_ringbuffer_reset);
#ifdef RT_USING_HEAP
/**
* @brief Create a ringbuffer object with a given size.
*
* @param size Size of the buffer in bytes.
*
* @return Return a pointer to ringbuffer object. When the return value is RT_NULL, it means the creation failed.
*/
struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size)
{
struct rt_ringbuffer *rb;
@ -386,6 +450,11 @@ exit:
}
RTM_EXPORT(rt_ringbuffer_create);
/**
* @brief Destroy a ringbuffer object, which is created by rt_ringbuffer_create() .
*
* @param rb A pointer to the ringbuffer object.
*/
void rt_ringbuffer_destroy(struct rt_ringbuffer *rb)
{
RT_ASSERT(rb != RT_NULL);

1
components/drivers/src/workqueue.c
View File

@ -7,6 +7,7 @@
* Date Author Notes
* 2017-02-27 Bernard fix the re-work issue.
* 2021-08-01 Meco Man remove rt_delayed_work_init()
* 2021-08-14 Jackistang add commets for function interface.
*/
#include <rthw.h>