From e93270770901f21c178b159bca873c1ec032e220 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Wed, 26 Jan 2022 16:06:07 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E6=95=B4=E7=90=86libc=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../rt-thread-standard/_sidebar.md | 10 ++-- .../libc/{libc.md => compiler.md} | 54 ++++++------------- .../programming-manual/libc/introduction.md | 6 +++ .../libc/{ => posix}/dlmodule.md | 0 .../libc/posix/introduction.md | 10 ++++ .../programming-manual/libc/posix/pse51.md | 1 + 6 files changed, 41 insertions(+), 40 deletions(-) rename rt-thread-version/rt-thread-standard/programming-manual/libc/{libc.md => compiler.md} (68%) create mode 100644 rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md rename rt-thread-version/rt-thread-standard/programming-manual/libc/{ => posix}/dlmodule.md (100%) create mode 100644 rt-thread-version/rt-thread-standard/programming-manual/libc/posix/introduction.md create mode 100644 rt-thread-version/rt-thread-standard/programming-manual/libc/posix/pse51.md diff --git a/rt-thread-version/rt-thread-standard/_sidebar.md b/rt-thread-version/rt-thread-standard/_sidebar.md index df4b053..c1b549e 100644 --- a/rt-thread-version/rt-thread-standard/_sidebar.md +++ b/rt-thread-version/rt-thread-standard/_sidebar.md @@ -55,9 +55,13 @@ - [ringbuffer](/rt-thread-version/rt-thread-standard/programming-manual/device-ipc/ringbuffer/ringbuffer.md) - [workqueue](/rt-thread-version/rt-thread-standard/programming-manual/device-ipc/workqueue/workqueue.md) - 组件 - - C库 (Libc) - - [Libc](/rt-thread-version/rt-thread-standard/programming-manual/libc/libc.md) - - [动态模块](/rt-thread-version/rt-thread-standard/programming-manual/libc/dlmodule.md) + - C库 (LIBC) + - [概况](/rt-thread-version/rt-thread-standard/programming-manual/libc/libc.md) + - [编译器配平层](/rt-thread-version/rt-thread-standard/programming-manual/libc/compiler.md) + - POSIX + - [POSIX 简介](/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/introduction.md) + - [PSE51](/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/pse51.md) + - [动态模块](/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/dlmodule.md) - 网络组件 - [net 组件总概](/rt-thread-version/rt-thread-standard/programming-manual/net/net_introduce.md) - [AT 命令](/rt-thread-version/rt-thread-standard/programming-manual/at/at.md) diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/libc.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/compiler.md similarity index 68% rename from rt-thread-version/rt-thread-standard/programming-manual/libc/libc.md rename to rt-thread-version/rt-thread-standard/programming-manual/libc/compiler.md index 5c99925..93bb47f 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/libc/libc.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/libc/compiler.md @@ -1,22 +1,16 @@ -# LIBC - -RT-Thread 提供的 Libc (C library, C库)，包含编译器配平层和 POSIX 层两部分。布局如下图所示： - -![libc_structure](figures/libc_structure.png) - -## 1. 编译器配平层 +# 编译器配平层 编译器配平层负责对接编译器的底层桩函数以及平衡不同编译器内置C库函数的差异而设计，为上层 POSIX 层提供功能统一的接口，位于 [components/libc/compiler](https://github.com/RT-Thread/rt-thread/tree/master/components/libc/compilers) 文件目录下。之所以需要配平，是由于 GCC、Keil-MDK、IAR 三个编译工具所提供的标准 C 库函数支持程度不一样，编译器配平层负责将 Keil-MDK、IAR、GCC 三种不同的编译链所提供的标准 C 库平衡到相同的水平。编译器配平层无需用户手动干预，会在编译工程时，根据用户所使用的的编译平台和工具链自动进行配平。 配平层已经提供了一些基本的 libc 函数，这些函数不需要用户额外使能，可以即刻使用。 -### 1.1 标准输出函数 (printf 家族) +## 标准输出函数 (printf 家族) -#### 1.1.1 printf 函数 +### printf 函数 在 Keil 和 IAR 编译平台下，用户可以直接使用 printf 函数；在 GCC 下，需要额外使能 `RT_USING_POSIX_FS` 和 `RT_USING_POSIX_STDIO` 宏才能使用 printf 函数。 -#### 1.1.2 rt_kprintf 函数 与 printf 函数的使用选择 +### rt_kprintf 函数 与 printf 函数的使用选择 如果如果不是特殊需求，建议使用 rt_kprintf 函数，因为 printf 是有编译平台内部提供的，其空间占用、以及内存使用情况我们无从得知，printf 函数要比 rt_kprintf 函数的 ROM 占用大很多。 @@ -28,7 +22,7 @@ RT-Thread 提供的 Libc (C library, C库)，包含编译器配平层和 POSIX 2. 如需 rt_kprintf 函数支持线程安全输出，可以安装 [rt_kprintf_threadsafe 软件包](https://github.com/mysterywolf/rt_kprintf_threadsafe)。 3. 上述两个软件包可以同时安装使用，以同时让 rt_kprintf 支持线程安全和浮点类型输出的能力。 -#### 1.1.3 其他字符串格式化输出函数 (例如 snprintf 等) +### 其他字符串格式化输出函数 (例如 snprintf 等) 其他字符串格式化输出函数（例如 snprintf 等）都是可以直接使用的。 @@ -36,51 +30,37 @@ RT-Thread 提供的 Libc (C library, C库)，包含编译器配平层和 POSIX 同理，原生 rt_snprintf 等函数不支持浮点输出，用户可以通过安装 [rt_vsnprintf_full 软件包](https://github.com/mysterywolf/rt_vsnprintf_full) 来支持浮点数输出。 -### 1.2 内存相关函数 +## 内存相关函数 malloc 、realloc 、calloc 、free 内存分配函数可以直接使用，其已经被 rt_malloc 、rt_calloc 、rt_realloc 、rt_free 函数接管，二者无任何区别。 memcpy 、memset 等内存操作相关函数。这里需要注意的时，建议使用 rt_memcpy 以及 rt_memset 来代替 memcpy 和 memset ，虽然 rt_memxxx 函数要比C库的内存操作函数要慢一些，但是要更安全；除非您对拷贝速度非常在意，否则建议使用 rt_memxxx 函数。如果使用的是 Cortex-M 的 MCU，可以安装 [rt_memcpy_cm](https://github.com/mysterywolf/rt_memcpy_cm) 软件包来对 rt_memcpy 函数进行汇编加速，该软件包安全且高效。 -### 1.3 字符串相关函数 +## 字符串相关函数 strlen 等字符串相关函数为编译器C库内置函数，可以直接使用。 -### 1.4 系统函数 +## 系统函数 exit 、abort 函数，调用后相当于删除当前线程。 system 函数可以用于在 C 程序中内置执行一些 Finish 命令。 -### 1.5 时间函数 +## 时间函数 所有 ANSI/ISO-C 规定的时间函数均可以使用，例如 time 、ctime 等函数。注意：部分涉及到获取当前时间的函数需要使能 RTC 设备才可以正常工作，如果没有使能 RTC 设备就调用这些函数，会在串口终端给出警告。 支持时区功能，可以通过 `RT_LIBC_DEFAULT_TIMEZONE` 宏定义设置默认时区，默认的时区为 UTC+8 北京时间，在运行过程中也可以使用 tz_set() 、 tz_get() 、 tz_is_dst() 函数动态设置或获取时区相关信息（需要包含 头文件）。 -目前，RT-Thread 的时间相关 Libc 函数唯一不支持的是夏令时自动转换相关功能。夏令时在中国不使用，主要是欧美国家在使用。 - -> [!NOTE] -> 注：时区是给人看的，不是给机器看的。因此，底层驱动不应当使用带有时区的时间，而应该使用格林威治时间，即 UTC+0。当且仅当该时间需要显示出来给人看的时候，才需要临时将其使用带有时区转换功能的函数（例如 ctime）显示时间。否则很容易引发时间上的错乱。 -> -> 注意以下两组函数的区别，功能相同，唯一的区别是是否考虑时区问题： -> -> | | 考虑时区 | 不考虑时区 | -> | ------ | --------- | ---------- | -> | 第一组 | localtime | gmtime | -> | 第二组 | mktime | timegm | - -### 1.6 注意事项 - -1. 为保证跨不同编译器、不同工具链的兼容性，建议用户应用层代码： - - 使用 代替 - - 使用 代替 - - 使用 代替 +***注意：*** -## 2. POSIX 层 +1. 时区是给人看的，不是给机器看的。因此，底层驱动不应当使用带有时区的时间，而应该使用格林威治时间，即 UTC+0。当且仅当该时间需要显示出来给人看的时候，才需要临时将其使用带有时区转换功能的函数（例如 ctime）显示时间。否则很容易引发时间上的错乱。 -#### 2.1 标准输入输出函数 + 注意以下两组函数的区别，功能相同，唯一的区别是是否考虑时区问题： -在不使能 POSIX 层相关功能的情况下，用户无法使用 read 、getchar 等获取字符串输入的标准 C 函数，需要开启 `RT_USING_POSIX_FS` 和 `RT_USING_POSIX_STDIO` 宏。 + | | 考虑时区 | 不考虑时区 | + | ------ | --------- | ---------- | + | 第一组 | localtime | gmtime | + | 第二组 | mktime | timegm | -如果已经开启 Finish 功能的话，可以在 finish 线程下，使用 finish_getchar 代替 getchar，来获取从终端键入的字符。 +2. 目前，时间相关函数不支持的是夏令时自动转换相关功能。夏令时在中国不使用，主要是欧美国家在使用。 diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md new file mode 100644 index 0000000..988d26e --- /dev/null +++ b/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md @@ -0,0 +1,6 @@ +# LIBC 简介 + +RT-Thread 提供的 LIBC (C library, C库)，包含编译器配平层和 POSIX 层两部分。布局如下图所示： + +![libc_structure](figures/libc_structure.png) + diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/dlmodule.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/dlmodule.md similarity index 100% rename from rt-thread-version/rt-thread-standard/programming-manual/libc/dlmodule.md rename to rt-thread-version/rt-thread-standard/programming-manual/libc/posix/dlmodule.md diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/introduction.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/introduction.md new file mode 100644 index 0000000..d70673f --- /dev/null +++ b/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/introduction.md @@ -0,0 +1,10 @@ +# POSIX 简介 + + + +## 标准输入输出函数 + +在不使能 POSIX 层相关功能的情况下，用户无法使用 read 、getchar 等获取字符串输入的标准 C 函数，需要开启 `RT_USING_POSIX_FS` 和 `RT_USING_POSIX_STDIO` 宏。 + +如果已经开启 Finish 功能的话，可以在 finish 线程下，使用 finish_getchar 代替 getchar，来获取从终端键入的字符。 + diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/pse51.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/pse51.md new file mode 100644 index 0000000..8818118 --- /dev/null +++ b/rt-thread-version/rt-thread-standard/programming-manual/libc/posix/pse51.md @@ -0,0 +1 @@ +# PSE51 \ No newline at end of file -- Gitee From bc0453e0d3debdbc021dd0378b87585c39e9b67d Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Wed, 26 Jan 2022 16:15:45 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=E8=A1=A5=E5=85=85=E6=B3=A8=E6=84=8F?= =?UTF-8?q?=E4=BA=8B=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../programming-manual/libc/introduction.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md b/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md index 988d26e..d3288c4 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/libc/introduction.md @@ -4,3 +4,11 @@ RT-Thread 提供的 LIBC (C library, C库)，包含编译器配平层和 POSIX ![libc_structure](figures/libc_structure.png) +### 注意事项 + +为保证跨不同编译器、不同工具链的兼容性，建议用户应用层代码： + +- 使用 代替 +- 使用 代替 +- 使用 代替 + -- Gitee