diff --git a/docs/kernel/core_api/data_structures.md b/docs/kernel/core_api/data_structures.md new file mode 100644 index 00000000..4880bf32 --- /dev/null +++ b/docs/kernel/core_api/data_structures.md @@ -0,0 +1,254 @@ +# 内核数据结构 + +  内核中实现了常用的几种数据结构,这里是他们的api文档。 + +## kfifo先进先出缓冲区 + +  kfifo先进先出缓冲区定义于`common/kfifo.h`中。您可以使用它,创建指定大小的fifo缓冲区(最大大小为4GB) + +### kfifo_alloc + +`int kfifo_alloc(struct kfifo_t *fifo, uint32_t size, uint64_t reserved)` + +#### 描述 + +  通过动态方式初始化kfifo缓冲队列。fifo缓冲区的buffer将由该函数进行申请。 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +**size** + +  缓冲区大小(单位:bytes) + +**reserved** + +  当前字段保留,请将其置为0 + +#### 返回值 + +  当返回值为0时,表示正常初始化成功,否则返回对应的errno + +### kfifo_init + +`void kfifo_init(struct kfifo_t *fifo, void *buffer, uint32_t size)` + +#### 描述 + +  使用指定的缓冲区来初始化kfifo缓冲队列 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +**buffer** + +  缓冲区基地址指针 + +**size** + +  缓冲区大小(单位:bytes) + +### kfifo_free_alloc + +`void kfifo_free_alloc(struct kfifo_t* fifo)` + +#### 描述 + +  释放通过kfifo_alloc创建的fifo缓冲区. 请勿通过该函数释放其他方式创建的kfifo缓冲区。 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +### kfifo_in + +`uint32_t kfifo_in(struct kfifo_t *fifo, const void *from, uint32_t size)` + +#### 描述 + +  向kfifo缓冲区推入指定大小的数据。当队列中空间不足时,则不推入数据。 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +**from** + +  源数据基地址指针 + +**size** + +  数据大小(单位:bytes) + +#### 返回值 + +  返回成功被推入的数据的大小。 + +### kfifo_out + +`uint32_t kfifo_out(struct kfifo_t *fifo, void *to, uint32_t size)` + +#### 描述 + +  从kfifo缓冲区取出数据,并从队列中删除数据。当队列中数据量不足时,则不取出。 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +**to** + +  目标缓冲区基地址指针 + +**size** + +  数据大小(单位:bytes) + +#### 返回值 + +  返回成功被取出的数据的大小。 + +### kfifo_out_peek + +`uint32_t kfifo_out_peek(struct kfifo_t *fifo, void *to, uint32_t size)` + +#### 描述 + +  从kfifo缓冲区取出数据,但是不从队列中删除数据。当队列中数据量不足时,则不取出。 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +**to** + +  目标缓冲区基地址指针 + +**size** + +  数据大小(单位:bytes) + +#### 返回值 + +  返回成功被取出的数据的大小。 + +### kfifo_reset + +`kfifo_reset(fifo)` + +#### 描述 + +  忽略kfifo队列中的所有内容,并把输入和输出偏移量都归零 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +### kfifo_reset_out + +`kfifo_reset_out(fifo)` + +#### 描述 + +  忽略kfifo队列中的所有内容,并将输入偏移量赋值给输出偏移量 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +### kfifo_total_size + +`kfifo_total_size(fifo)` + +#### 描述 + +  获取kfifo缓冲区的最大大小 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +#### 返回值 + +  缓冲区最大大小 + +### kfifo_size + +`kfifo_size(fifo)` + +#### 描述 + +  获取kfifo缓冲区当前已使用的大小 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +#### 返回值 + +  缓冲区当前已使用的大小 + +### kfifo_empty + +`kfifo_empty(fifo)` + +#### 描述 + +  判断kfifo缓冲区当前是否为空 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +#### 返回值 + +| 情况 | 返回值 | +| ----------------------- | --- | +| 空 | 1 | +| 非空 | 0 | + +### kfifo_full + +`kfifo_full(fifo)` + +#### 描述 + +  判断kfifo缓冲区当前是否为满 + +#### 参数 + +**fifo** + +  kfifo队列结构体的指针 + +#### 返回值 + +| 情况 | 返回值 | +| ------| --- | +| 满 | 1 | +| 不满 | 0 | + diff --git a/docs/kernel/core_api/index.rst b/docs/kernel/core_api/index.rst index 9bf6d982..2b4a0c5a 100644 --- a/docs/kernel/core_api/index.rst +++ b/docs/kernel/core_api/index.rst @@ -10,6 +10,7 @@ kernel_api atomic + data_structures 内存管理 =================== diff --git a/kernel/common/kfifo.h b/kernel/common/kfifo.h index a03dc475..63a7b566 100644 --- a/kernel/common/kfifo.h +++ b/kernel/common/kfifo.h @@ -22,7 +22,7 @@ struct kfifo_t }) /** - * @brief 忽略kfifo队列中的所有内容,并使得输出偏移量为输入偏移量 + * @brief 忽略kfifo队列中的所有内容,并将输入偏移量赋值给输出偏移量 * */ #define kfifo_reset_out(fifo) (void)({ \ @@ -38,10 +38,10 @@ struct kfifo_t */ #define kfifo_total_size(fifo) ((fifo)->total_size) /** - * @brief 获取kfifo缓冲区当前已有元素大小 + * @brief 获取kfifo缓冲区当前已使用的大小 * * @param fifo 队列结构体 - * @return uint32_t 缓冲区当前已有元素大小 + * @return uint32_t 缓冲区当前已使用的大小 */ #define kfifo_size(fifo) ((fifo)->size) @@ -88,7 +88,7 @@ void kfifo_free_alloc(struct kfifo_t* fifo); void kfifo_init(struct kfifo_t *fifo, void *buffer, uint32_t size); /** - * @brief 向kfifo缓冲区推入数据 + * @brief 向kfifo缓冲区推入指定大小的数据 * * @param fifo 队列结构体 * @param from 来源数据地址