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

doxygen: create framework to unify markdown and source code part (#9946)

Browse Source 
* doxygen: adjust documentation directory structure

- Rename documentation/doxygen to documentation/0.doxygen and cleanup
  some unused files.

- Add/rename folders for each sub sections, such as
  1.introduction/...... Each sub section will be created as a subpage.

- Generate initial Doxyfile, this Doxyfile will be used to unify
  doxygen generated API documents and those markdown files under
  documentation folder. This patch just add the default Doxyfile
  generated by running "doxygen -g". It is used as baseline to add
  more features/configurations.

- Rename documentation/README.md to documentation/INDEX.md, and
  use it as mainpage.

- Move 0.doxygen/readme.md to documentation/README.md.

* doxygen: update configurations

These configurations are from old documentation/doxygen/Doxyfile.
Try best to compatible exixting design.

* doxygen: add run script

Add a script to automatic some operations.

Updated the README.md.

---------

Signed-off-by: Chen Wang <unicorn_wang@outlook.com>
Co-authored-by: Supper Thomas <78900636@qq.com>
This commit is contained in:
Chen Wang
2025-01-26 11:44:39 +08:00
committed by GitHub
parent c3e5152c13
commit 40f3b6a569
133 changed files with 1069 additions and 1043 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
documentation/dlmodule/README.md
View File

@@ -1,10 +1,10 @@
# Dynamic Module: dlmodule #
@page component_dlmodule Dynamic Module: dlmodule
In traditional desktop operating systems, user space and kernel space are separate. The application runs in user space, and the kernel and kernel modules run in kernel space. The kernel module can be dynamically loaded and deleted to extend the kernel functionality. `dlmodule` is a software component of the dynamic module loading mechanism provided in kernel space of RT-Thread. In versions of RT-Thread v3.1.0, this was also called the `Application Module`. After RT-Thread v3.1.0 and later, it returned to the tradition and was named after the `dynamic module`.
`dlmodule` is more of an ELF format loader. The code segment and data segment of a separately compiled elf file are loaded into memory, and the symbols are parsed and bound to the API address exported by the kernel. The elf files are primarily placed on file systems under RT-Thread.
## Introduction ##
# Introduction
The dynamic module provides a mechanism for dynamically loading program modules for RT-Thread. Because it is also compiled independently of the kernel, it is more flexible to use. In terms of implementation, this is a mechanism to separate the kernel from the dynamic modules. Through this mechanism, the kernel and dynamic modules can be compiled separately, and at runtime, the compiled dynamic modules are loaded into the kernel through the module loader in the kernel.
@@ -15,11 +15,11 @@ In the dynamic module of RT-Thread, two formats are currently supported:
The current RT-Thread architecture supporting dynamic modules mainly includes ARM architecture and x86 architecture, and will be extended to MIPS and RISC-V architecture in the future. The RT-Thread kernel firmware section can use a variety of compiler toolchains, such as GCC, ARMCC, IAR and other toolchains; however, dynamic module partial compilation currently only supports GNU GCC toolchain compilation. Therefore, compiling the RT-Thread module requires downloading GCC tools, such as CodeSourcery's arm-none-eabi toolchain. In general, it's best to use kernel and dynamic modules to compile with the same toolchain (so that it doesn't produce inconsistent behavior in *libc*). In addition, dynamic modules can only be loaded into RAM and used for symbol resolution binding to the API address exported by the kernel. Instead of running directly in XIP mode based on Flash (because Flash can't modify the code segment again).
## Using Dynamic Module ##
# Using Dynamic Module
When you want to use the dynamic modules in your system, you need to compile a firmware that supports dynamic modules, as well as dynamic modules that need to be run. The following two parts are compiling firmware and compiling dynamic modules.
### Compile Firmware ###
## Compile Firmware
When you want to use the dynamic module, you need to open the corresponding option in the firmware configuration, use menuconfig to open the following configuration:
@@ -82,7 +82,7 @@ Then execute the `scons` under the BSP project directory and generate the firmwa
to generate the kernel header file search path and global macro definitions that need to be included when compiling the dynamic module.
### Compile Dynamic Module ###
## Compile Dynamic Module
There is a separate repository on github: [rtthread-apps](https://github.com/RT-Thread/rtthread-apps) , which contains some examples of dynamic modules and dynamic libraries.
@@ -151,11 +151,11 @@ int main(int argc, char *argv[])
}
```
## APIs of Dynamic Module
# APIs of Dynamic Module
In addition to dynamically loading and executing dynamic modules via msh, dynamic modules can be loaded or unloaded using the dynamic module API provided by RT-Thread in the main program.
### Load Dynamic Module
## Load Dynamic Module
```c
struct rt_dlmodule *dlmodule_load(const char* pgname);
@@ -170,7 +170,7 @@ struct rt_dlmodule *dlmodule_load(const char* pgname);
This function loads the dynamic module from the file system into memory, and if it is loaded correctly, returns a pointer to the module. This function does not create a thread to execute this dynamic module, just load the module into memory and parse the symbolic address.
### Execute Dynamic Module
## Execute Dynamic Module
```c
struct rt_dlmodule *dlmodule_exec(const char* pgname, const char* cmd, int cmd_size);
@@ -187,7 +187,7 @@ struct rt_dlmodule *dlmodule_exec(const char* pgname, const char* cmd, int cmd_s
This function loads the dynamic module according to the `pgname` path and starts a thread to execute `main` of the dynamic module. At the same time, `cmd` is passed as the command line Parameter to `main` entry of the dynamic module.
### Exit Dynamic Module
## Exit Dynamic Module
```c
void dlmodule_exit(int ret_code);
@@ -199,7 +199,7 @@ void dlmodule_exit(int ret_code);
This function is called by the module runtime, it can set the return value of the module exit `ret_code`, and then exit from the module.
### Find Dynamic Modules
## Find Dynamic Modules
```c
struct rt_dlmodule *dlmodule_find(const char *name);
@@ -214,7 +214,7 @@ struct rt_dlmodule *dlmodule_find(const char *name);
This function uses `name` to find out if there is already a dynamic module loaded in the system.
### Return Dynamic Module
## Return Dynamic Module
```c
struct rt_dlmodule *dlmodule_self(void);
@@ -227,7 +227,7 @@ struct rt_dlmodule *dlmodule_self(void);
This function returns a pointer of the dynamic module in the calling context.
### Find Symbol
## Find Symbol
```c
rt_uint32_t dlmodule_symbol_find(const char *sym_str);
@@ -242,11 +242,11 @@ rt_uint32_t dlmodule_symbol_find(const char *sym_str);
This function returns the symbol address based on the symbol name.
## Libdl API of POSIX Standard ##
# Libdl API of POSIX Standard
The POSIX standard libdl API is also supported in RT-Thread dlmodule. It is similar to loading a dynamic library into memory (and parsing some of the symbol information). This dynamic library provides the corresponding set of function operations. The libdl API needs to include the header files: `#include <dlfcn.h>`
### Open Dynamic Library
## Open Dynamic Library
```c
void * dlopen (const char * pathname, int mode);
@@ -262,7 +262,7 @@ void * dlopen (const char * pathname, int mode);
This function is similar to the `dlmodule_load` , which loads the dynamic library from the file system and returns the handle pointer of the dynamic library.
### Find Symbol
## Find Symbol
```c
void* dlsym(void *handle, const char *symbol);
@@ -278,7 +278,7 @@ void* dlsym(void *handle, const char *symbol);
This function looks in the dynamic library `handle` for the presence of the symbol of `symbol` , if there is an address that returns it.
### Close Dynamic Library
## Close Dynamic Library
```
int dlclose (void *handle);
@@ -293,15 +293,15 @@ int dlclose (void *handle);
This function closes the dynamic library pointed to by `handle` and unloads it from memory. It should be noted that when the dynamic library is closed, the symbolic address originally returned by `dlsym` will no longer be available. If you still try to access it, it may cause a fault error.
## FAQs
# FAQs
Please refer to [*User Manual of Env*](../env/env.md) for issues related to the Env tool.
Please refer to @ref env for issues related to the Env tool.
### Q: Dynamic modules cannot be run successfully according to the documentation.
## Q: Dynamic modules cannot be run successfully according to the documentation.
**A:** Please update the RT-Thread source code to version 3.1.0 and above.
### Q: Compile the project with the scons command, prompting "undefined reference to __rtmsymtab_start".
## Q: Compile the project with the scons command, prompting "undefined reference to __rtmsymtab_start".
**A:** Please refer to the qemu-vexpress-a9 BSP GCC link script file *link.lds* to add the following to the TEXT section of the project's GCC link script.