From 39a09ffd72e8d536137c0190ce4636d9e930c6ec Mon Sep 17 00:00:00 2001 From: fslongjin Date: Tue, 12 Jul 2022 20:39:33 +0800 Subject: [PATCH] =?UTF-8?q?:new:=20=E5=86=85=E6=A0=B8=E6=A0=B8=E5=BF=83api?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/index.rst | 1 + docs/kernel/core_api/index.rst | 10 ++ docs/kernel/core_api/kernel_api.md | 223 +++++++++++++++++++++++++++++ kernel/common/glib.h | 13 +- 4 files changed, 237 insertions(+), 10 deletions(-) create mode 100644 docs/kernel/core_api/index.rst create mode 100644 docs/kernel/core_api/kernel_api.md diff --git a/docs/index.rst b/docs/index.rst index 85ea3f47..8a3d3284 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ :caption: 内核层 kernel/boot/index + kernel/core_api/index kernel/process_management/index kernel/filesystem/index diff --git a/docs/kernel/core_api/index.rst b/docs/kernel/core_api/index.rst new file mode 100644 index 00000000..f44d411e --- /dev/null +++ b/docs/kernel/core_api/index.rst @@ -0,0 +1,10 @@ +核心API文档 +==================================== + + 这里是DragonOS的核心api文档。 + +.. toctree:: + :maxdepth: 1 + :caption: 内核实用函数库 + + kernel_api diff --git a/docs/kernel/core_api/kernel_api.md b/docs/kernel/core_api/kernel_api.md new file mode 100644 index 00000000..1b07b931 --- /dev/null +++ b/docs/kernel/core_api/kernel_api.md @@ -0,0 +1,223 @@ +# DragonOS内核核心API + +## 循环链表管理函数 + +  循环链表是内核的重要的数据结构之一。包含在`kernel/common/glib.h`中。 + +### `void list_init(struct List *list)` + +#### 描述 + +  初始化一个List结构体，使其prev和next指针指向自身 + +#### 参数 + +**list** + +  要被初始化的List结构体 + +### `void list_add(struct List *entry, struct List *node)` + +#### 描述 + +  将node插入到entry的后方 + +#### 参数 + +**entry** + +  已存在于循环链表中的一个结点 + +**node** + +  待插入的结点 + +### `void list_append(struct List *entry, struct List *node)` + +#### 描述 + +  将node插入到entry的前方 + +#### 参数 + +**entry** + +  已存在于循环链表中的一个结点 + +**node** + +  待插入的结点 + +### `void list_del(struct List *entry)` + +#### 描述 + +  从链表中删除结点entry + +#### 参数 + +**entry** + +  待删除的结点 + +### `bool list_empty(struct List *entry)` + +#### 描述 + +  判断链表是否为空 + +#### 参数 + +**entry** + +  链表中的一个结点 + +### `struct List *list_prev(struct List *entry)` + +#### 描述 + +  获取entry的前一个结点 + +#### 参数 + +**entry** + +  链表中的一个结点 + +### `struct List *list_next(struct List *entry)` + +#### 描述 + +  获取entry的后一个结点 + +#### 参数 + +**entry** + +  链表中的一个结点 + +--- + +## 基础C函数库 + +  内核编程与应用层编程不同，你将无法使用LibC中的函数来进行编程。为此，内核实现了一些常用的C语言函数，并尽量使其与标准C库中的函数行为相近。值得注意的是，这些函数的行为可能与标准C库函数不同，请在使用时仔细阅读以下文档，这将会为你带来帮助。 + +### 字符串操作 + +#### `int strlen(const char *s)` + +##### 描述 + +测量并返回字符串长度。 + +##### 参数 + +**src** + +源字符串 + +#### `long strnlen(const char *src, unsigned long maxlen)` + +##### 描述 + +  测量并返回字符串长度。当字符串长度大于maxlen时，返回maxlen + +##### 参数 + +**src** + +  源字符串 + +**maxlen** + +  最大长度 + +#### `long strnlen_user(const char *src, unsigned long maxlen)` + +##### 描述 + +  测量并返回字符串长度。当字符串长度大于maxlen时，返回maxlen。 + +  该函数会进行地址空间校验，要求src字符串必须来自用户空间。当源字符串来自内核空间时，将返回0. + +##### 参数 + +**src** + +  源字符串，地址位于用户空间 + +**maxlen** + +  最大长度 + +#### `char *strncpy(char *dst, const char *src, long count)` + +##### 描述 + +  拷贝长度为count个字节的字符串，返回dst字符串 + +##### 参数 + +**src** + +  源字符串 + +**dst** + +  目标字符串 + +**count** + +  要拷贝的源字符串的长度 + + + +#### `long strncpy_from_user(char *dst, const char *src, unsigned long size)` + +##### 描述 + +  从用户空间拷贝长度为count个字节的字符串到内核空间，返回拷贝的字符串的大小 + +  该函数会对字符串的地址空间进行校验，防止出现地址空间越界的问题。 + +##### 参数 + +**src** + +  源字符串 + +**dst** + +  目标字符串 + +**size** + +  要拷贝的源字符串的长度 + +#### `int strcmp(char *FirstPart, char *SecondPart)` + +##### 描述 + +  比较两个字符串的大小。 + +***返回值*** + +| 情况 | 返回值 | +| ----------------------- | --- | +| FirstPart == SecondPart | 0 | +| FirstPart > SecondPart | 1 | +| FirstPart < SecondPart | -1 | + +##### 参数 + +**FirstPart** + +  第一个字符串 + +**SecondPart** + +  第二个字符串 + + + + diff --git a/kernel/common/glib.h b/kernel/common/glib.h index 948e3f4e..8c34ad85 100644 --- a/kernel/common/glib.h +++ b/kernel/common/glib.h @@ -283,13 +283,6 @@ int strcmp(char *FirstPart, char *SecondPart) return __res; } -// void *memset_c(void *dst, unsigned char c, ul n) -// { -// unsigned char *s = (unsigned char *)dst; -// for (int i = 0; i < n; ++i) -// s[i] = c; -// return dst; -// } // 从io口读入8个bit unsigned char io_in8(unsigned short port) @@ -541,7 +534,7 @@ static inline uint64_t copy_to_user(void *dst, void *src, uint64_t size) */ long strnlen_user(const char *src, unsigned long maxlen); -char *strncpy(char *Dest, const char *Src, long Count) +char *strncpy(char *dst, const char *src, long count) { __asm__ __volatile__("cld \n\t" "1: \n\t" @@ -555,9 +548,9 @@ char *strncpy(char *Dest, const char *Src, long Count) "stosb \n\t" "2: \n\t" : - : "S"(Src), "D"(Dest), "c"(Count) + : "S"(src), "D"(dst), "c"(count) : "ax", "memory"); - return Dest; + return dst; } long strncpy_from_user(char *dst, const char *src, unsigned long size)