doc: Add ai doc translate tool and add English doc. (#1168)

- add tools/doc_translator.py
- translated docs into English

Signed-off-by: longjin <longjin@DragonOS.org>
This commit is contained in:
LoGin
2025-05-20 10:44:28 +08:00
committed by GitHub
parent fccfa6f7ff
commit 880720250e
98 changed files with 13972 additions and 6 deletions

View File

@ -0,0 +1,26 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/libs/id-allocation.md
- Translation time: 2025-05-19 01:41:12
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# ID Allocation
:::{note}
Author: Longjin <longjin@DragonOS.org>
September 25, 2024
:::
The kernel provides an ID allocator named `IdAllocator`, located in `kernel/crates/ida`.
It is capable of allocating and releasing IDs. By default, it increments to allocate IDs. If the ID exceeds the set maximum value, it will search for an available ID starting from the minimum value. If there are no available IDs, the allocation will fail.

View File

@ -0,0 +1,26 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/libs/index.rst
- Translation time: 2025-05-19 01:41:11
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Other Kernel Libraries
====================================
This section contains documentation for some libraries in the kernel that do not belong to any subsystem.
.. toctree::
:maxdepth: 1
lib_ui/scm
lib_ui/textui
unified-init
id-allocation

View File

@ -0,0 +1,97 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/libs/lib_ui/scm.md
- Translation time: 2025-05-19 01:41:31
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Screen Manager (SCM)
:::{note}
Author: Zhou Hanjie <2625553453@qq.com>
:::
&emsp;&emsp;The Screen Manager is used to control all UI frameworks. All frameworks must be registered with the Screen Manager before they can be used. Then, SCM controls which UI framework is currently in use.
## traits
### ScmUiFramework
&emsp;&emsp;Each UI framework that is to be registered with SCM must implement the methods defined in this trait, as follows:
```rust
pub trait ScmUiFramework: Sync + Send + Debug {
// 安装ui框架的回调函数
fn install(&self) -> Result<i32, SystemError> {
return Err(SystemError::ENOSYS);
}
// 卸载ui框架的回调函数
fn uninstall(&self) -> Result<i32, SystemError> {
return Err(SystemError::ENOSYS);
}
// 启用ui框架的回调函数
fn enable(&self) -> Result<i32, SystemError> {
return Err(SystemError::ENOSYS);
}
// 禁用ui框架的回调函数
fn disable(&self) -> Result<i32, SystemError> {
return Err(SystemError::ENOSYS);
}
// 改变ui框架的帧缓冲区的回调函数
fn change(&self, _buf: ScmBufferInfo) -> Result<i32, SystemError> {
return Err(SystemError::ENOSYS);
}
/// @brief 获取ScmUiFramework的元数据
/// @return 成功Ok(ScmUiFramework的元数据)
/// 失败Err(错误码)
fn metadata(&self) -> Result<ScmUiFrameworkMetadata, SystemError> {
// 若文件系统没有实现此方法,则返回“不支持”
return Err(SystemError::ENOSYS);
}
}
```
## Main APIs
### scm_init() - Initialize the screen management module
#### Prototype
```rust
pub extern "C" fn scm_init()
```
#### Description
&emsp;&emsp;scm_init() is mainly used to initialize some global variables used by SCM, such as the flag indicating whether double buffering is used, and some global variables used by textui when it is not initialized.
### scm_reinit() - Reinitialize the screen management module after the memory management unit is initialized
#### Prototype
```rust
pub extern "C" fn scm_reinit() -> i32
```
#### Description
&emsp;&emsp;scm_reinit() is used to reprocess the frame buffer issues after the memory management unit has been initialized.
### scm_enable_double_buffer() - Enable double buffering
#### Prototype
```rust
pub extern "C" fn scm_enable_double_buffer() -> i32
```
#### Description
&emsp;&emsp;scm_enable_double_buffer() is used to enable double buffering for outputting information to the window. After enabling, the information output to the window is temporarily stored in a buffer, and then this buffer's content is output to the window's frame buffer at regular intervals, rendering it to the window.
### scm_framework_enable() - Enable a specific UI framework and render its frame buffer to the screen
#### Prototype
```rust
pub fn scm_framework_enable(framework: Arc<dyn ScmUiFramework>) -> Result<i32, SystemError>
```
#### Description
&emsp;&emsp;scm_framework_enable is used to enable a specific UI framework and render its frame buffer to the screen.
### scm_register() - Register a UI framework with the screen manager
#### Prototype
```rust
pub fn scm_register(framework: Arc<dyn ScmUiFramework>) -> Result<i32, SystemError>
```
#### Description
&emsp;&emsp;scm_register is used to register a UI framework with SCM. It mainly calls the callback functions of the UI framework to install and activate it.

View File

@ -0,0 +1,44 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/libs/lib_ui/textui.md
- Translation time: 2025-05-19 01:41:14
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Text UI Framework (textui)
:::{note}
Author: Zhou Hanjie <2625553453@qq.com>
:::
&emsp;&emsp;The text framework is primarily used for rendering and displaying text windows in DragonOS. It outputs printed text information to the screen window. Displaying text in the window is divided into two scenarios: one is when the Memory Management Unit (MM) has not been initialized, which prevents dynamic memory allocation, imposing many restrictions (for example, not being able to use vec, mpsc, etc.), so it directly outputs the printed information to the window's frame buffer without using complex structures like virtual lines; the other is when the Memory Management Unit (MM) has been initialized, allowing dynamic memory allocation, which enables the use of more complex structures to handle the text information to be printed.
## Main APIs
### rs_textui_init() - Text UI framework initialization
#### Prototype
```rust
pub extern "C" fn rs_textui_init() -> i32
```
#### Description
&emsp;&emsp;rs_textui_init() is mainly used to initialize some global variable information that the textui framework needs (such as TEXTUIFRAMEWORK, TEXTUI_PRIVATE_INFO, etc.), and to register the textui framework with scm.
### textui_putchar() - Print text information to the currently used window in the textui framework
#### Prototype
```rust
pub extern "C" fn rs_textui_putchar(character: u8, fr_color: u32, bk_color: u32) -> i32
pub fn textui_putchar(
character: char,
fr_color: FontColor,
bk_color: FontColor,
) -> Result<(), SystemError>
```
#### Description
&emsp;&emsp;textui_putchar() needs to handle two scenarios: one is when the Memory Management Unit (MM) has not been initialized, which prevents dynamic memory allocation, imposing many restrictions (for example, not being able to use vec, mpsc, etc.), so it directly outputs the printed information to the window's frame buffer without using complex structures like virtual lines; the other is when the Memory Management Unit (MM) has been initialized, allowing dynamic memory allocation, which enables the use of more complex structures to handle the text information to be printed.

View File

@ -0,0 +1,64 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/libs/unified-init.md
- Translation time: 2025-05-19 01:41:09
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# unified-init Unified Initialization Library
:::{note}
Author: Longjin <longjin@DragonOS.org>
December 25, 2023
:::
## 1. Introduction
This library is located in `kernel/crates/unified-init`.
It provides unified initialization macros to register functions into a unified initialization list. It facilitates unified initialization.
It is important to note that the array of initializers is no_mangle, so its naming should follow the rules of `模块_初始化器` to prevent naming conflicts that could lead to unexpected errors.
## 2. Usage
```rust
use system_error::SystemError;
use unified_init::define_unified_initializer_slice;
use unified_init_macros::unified_init;
/// 初始化函数都将会被放到这个列表中
define_unified_initializer_slice!(INITIALIZER_LIST);
#[unified_init(INITIALIZER_LIST)]
fn init1() -> Result<(), SystemError> {
Ok(())
}
#[unified_init(INITIALIZER_LIST)]
fn init2() -> Result<(), SystemError> {
Ok(())
}
fn main() {
assert_eq!(INITIALIZER_LIST.len(), 2);
}
```
## 3. Development
When testing, you can write test code in `main.rs`,
and then run `cargo expand --bin unified-init-expand` in the current directory to see the code after the proc macro has been expanded.
## 4. Maintainer
Longjin <longjin@DragonOS.org>