DragonOS-Community/DragonOS
4
1
Fork 0
mirror of https://github.com/DragonOS-Community/DragonOS.git synced 2025-06-19 04:56:30 +00:00
Code Issues Releases Wiki Activity

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

269
docs/.translation_cache.json Normal file
View File

@ -0,0 +1,269 @@
{
"en:kernel/memory_management/index.rst": {
"hash": "e394aa123a0030c0ec4276485fc764b7"
},
"en:kernel/debug/index.rst": {
"hash": "6dc058a954b8620162e8293faa4959b2"
},
"en:kernel/libs/index.rst": {
"hash": "d8667f36cbfe9d9f532737a3fbe39f2d"
},
"en:kernel/process_management/index.rst": {
"hash": "b200476562e580ee97d8a3ffe19d5605"
},
"en:kernel/libs/unified-init.md": {
"hash": "28374260f0134386d53392156d749733"
},
"en:kernel/process_management/load_binary.md": {
"hash": "b7d462c7c6573ecab186c535346d6609"
},
"en:kernel/core_api/index.rst": {
"hash": "7889b9dd1b120f09f3b7feaa2dbb3c41"
},
"en:kernel/process_management/kthread.md": {
"hash": "0ce92c5a05a0e78dfceb89c215294e28"
},
"en:kernel/debug/traceback.md": {
"hash": "f22fcde87181fe9bb5ba97f133506ca1"
},
"en:kernel/core_api/casting.md": {
"hash": "b86564a0d602dfad61ab0893de43a8f8"
},
"en:kernel/memory_management/intro.md": {
"hash": "777fe6a902720949596f5a35bdf26372"
},
"en:kernel/syscall/index.rst": {
"hash": "d94e7cff4242362399e96051df1e7aad"
},
"en:kernel/libs/lib_ui/scm.md": {
"hash": "a03d756677c64b1247cfe40b6d73f1b1"
},
"en:kernel/libs/id-allocation.md": {
"hash": "5789b9d1fe4f8f72848412f6e766e099"
},
"en:kernel/memory_management/allocate-memory.md": {
"hash": "9a5c0ec57bae0576c30fbab60407f178"
},
"en:kernel/locking/index.rst": {
"hash": "299b0ccecf4ef174fffcce4731a98728"
},
"en:kernel/sched/index.rst": {
"hash": "76ca73ed6d47a4207d2ca193b88eae0b"
},
"en:kernel/locking/locks.md": {
"hash": "5514ff361db4677d2b4fa522852aaeea"
},
"en:kernel/sched/cfs.md": {
"hash": "7c89ba1c0416ec346f2982b3139cc819"
},
"en:kernel/core_api/notifier_chain.md": {
"hash": "5d21aad4640544ad49348d3cd2e8a386"
},
"en:kernel/filesystem/index.rst": {
"hash": "52dd12d566da2003602ee21c4a3d007f"
},
"en:kernel/ktest/index.rst": {
"hash": "5a4565952877c82b9a0ed3b67103c141"
},
"en:kernel/filesystem/vfs/api.md": {
"hash": "1b0b3fe0cc2918cc2c53a5af392a96ff"
},
"en:kernel/filesystem/vfs/index.rst": {
"hash": "d0de5d78a2105a1ecfe4ef137c18f7f5"
},
"en:kernel/debug/profiling-kernel-with-dadk.md": {
"hash": "966d07272ad19e1afbdc64bb6cfcea73"
},
"en:kernel/filesystem/unionfs/index.rst": {
"hash": "7ee4201508b51b4c5ac9e3b520472cd6"
},
"en:kernel/core_api/atomic.md": {
"hash": "ff17c6b902baddffff32cb9f70ddefcb"
},
"en:kernel/libs/lib_ui/textui.md": {
"hash": "dc914079508390cf7544b5b9c7ef7e4f"
},
"en:kernel/sched/rust_waiting.md": {
"hash": "6777e758cd796a356c8789f4306911ae"
},
"en:kernel/locking/rwlock.md": {
"hash": "457db706fcf5f4a7e45d15d496a29605"
},
"en:kernel/configuration/index.rst": {
"hash": "77a375890e3abf508ea1147da0e92a50"
},
"en:kernel/filesystem/kernfs.md": {
"hash": "da5cf8148a5ab38c6d0efd9ada8a0a29"
},
"en:kernel/container/namespaces/index.rst": {
"hash": "60c3b1e0726791677414064c2a98e848"
},
"en:kernel/filesystem/vfs/design.md": {
"hash": "16577686b5f5b15a5cfb25f379e01a03"
},
"en:kernel/syscall/syscall_table.rst": {
"hash": "dc34f86b55c62bdd1777a97eb7e6bd26"
},
"en:kernel/filesystem/unionfs/overlayfs.md": {
"hash": "2eba6973dc429ea15ad6ac8f47bfa187"
},
"en:kernel/container/index.rst": {
"hash": "624e76dd31081ef9304da582d835992f"
},
"en:kernel/container/namespaces/mnt_namespace.md": {
"hash": "19af9b11f162c0e4be4725d8458fd253"
},
"en:kernel/memory_management/mmio.md": {
"hash": "e956a9cd454416578996f955cd905a08"
},
"en:kernel/cpu_arch/x86_64/index.rst": {
"hash": "ff36e992e4dee15f740259d545e161e2"
},
"en:kernel/sched/rt.md": {
"hash": "913a29f3bccbf0c10a093fd558100e8d"
},
"en:kernel/cpu_arch/index.rst": {
"hash": "72efe542c7854926ac0f33287345b856"
},
"en:kernel/ipc/index.rst": {
"hash": "bbc40e0a41a1467dbdd42196c443f1ef"
},
"en:kernel/boot/index.rst": {
"hash": "8fe854f9c48d4e2e3fee0cf7f3526dfe"
},
"en:kernel/container/namespaces/pid_namespace.md": {
"hash": "7b78f405306356aec439bfd5bad69967"
},
"en:kernel/cpu_arch/x86_64/usb_legacy_support.md": {
"hash": "a0c3300d1641f613777d631578e0ea58"
},
"en:kernel/sched/kernel_timer.md": {
"hash": "95bf320a3e748c7bb41150940fee0e77"
},
"en:kernel/configuration/arch.md": {
"hash": "a024ea920cdb719454beaae1eb9e09e9"
},
"en:kernel/filesystem/sysfs.md": {
"hash": "68d5270491432d41b254c750d59aca89"
},
"en:kernel/core_api/softirq.md": {
"hash": "c931f3fcfca7d8d10cd16a8b68e6274a"
},
"en:community/ChangeLog/index.rst": {
"hash": "aa1979d81b79f64b12962f885a6820af"
},
"en:kernel/trace/index.rst": {
"hash": "944a5b865100258ec7957a4cbedd7251"
},
"en:kernel/configuration/config.md": {
"hash": "dff794c4f3bfb4c3d66e6d0fa8f7c495"
},
"en:kernel/sched/core.md": {
"hash": "f449acec9b9ad36c4a75e8594d38e44d"
},
"en:kernel/filesystem/overview.md": {
"hash": "44499f7673a0c68c53b12882258b9f5c"
},
"en:kernel/boot/bootloader.md": {
"hash": "e6f65060560663ca2ce4d56d750332d8"
},
"en:kernel/ipc/signal.md": {
"hash": "abe911dac525b44fe083752a1e6bbdc7"
},
"en:kernel/locking/mutex.md": {
"hash": "a82fa540acd44a93f5cb3c069d5584da"
},
"en:kernel/boot/cmdline.md": {
"hash": "3d17446c60b72e9cadf82002520ebbf9"
},
"en:community/code_contribution/index.rst": {
"hash": "38b6fe56ee739723a662cd1fec7a194a"
},
"en:community/contact/index.rst": {
"hash": "1fbd4c64558614101f195681b92a179e"
},
"en:kernel/locking/spinlock.md": {
"hash": "b97729ffa1d19fb131a85c72c2411146"
},
"en:kernel/trace/kprobe.md": {
"hash": "7e92cda81dfc19881d45e7cc0606f8c6"
},
"en:introduction/mirrors.md": {
"hash": "e5b572a5f5abca55e9ffcbc9827ce6f7"
},
"en:community/ChangeLog/V0.1.x/V0.1.8.md": {
"hash": "8c26796807713751958810efecaedebd"
},
"en:community/ChangeLog/V0.1.x/V0.1.7.md": {
"hash": "c74fe7a6db6d59d3d6d5116d4c4e0ceb"
},
"en:community/ChangeLog/V0.1.x/V0.1.9.md": {
"hash": "bf42117b62c4739a8101b33390b5a4c7"
},
"en:community/code_contribution/rust-coding-style.md": {
"hash": "db7eddfe4d16166ebe28def72f63fbb6"
},
"en:community/ChangeLog/V0.1.x/V0.1.1.md": {
"hash": "d94351167179beb0bb1b1f3bb82da2ff"
},
"en:userland/appdev/index.rst": {
"hash": "78e6747475981b5cc17cd206c135ca4f"
},
"en:userland/appdev/c-cpp-quick-start.md": {
"hash": "0101f8fa98a0536d43ff897145d4a43d"
},
"en:community/code_contribution/c-coding-style.md": {
"hash": "ea3c95cc032e4fa7cde32a56359ab328"
},
"en:community/code_contribution/conventional-commit.md": {
"hash": "31666b2ee98f5fe3698ae234b6ef0f00"
},
"en:userland/appdev/rust-quick-start.md": {
"hash": "6366c994d75086098469d8ea02555b88"
},
"en:kernel/debug/debug-kernel-with-gdb.md": {
"hash": "ab7904f52dcf35d0675e48fe8e88ec9a"
},
"en:community/ChangeLog/V0.1.x/V0.1.3.md": {
"hash": "c302428982363f627bedda89c1ab9232"
},
"en:introduction/index.rst": {
"hash": "a7c445abd29ce6817b098787f69902b7"
},
"en:kernel/sched/c_waiting.md": {
"hash": "bb2435e3905e8e71eca8f6a583e31d94"
},
"en:introduction/build_system.md": {
"hash": "fafac4210fb49c9e160b46c2101df238"
},
"en:community/ChangeLog/V0.1.x/V0.1.4.md": {
"hash": "5720af929320997f8824bcdfd3a17bdd"
},
"en:kernel/trace/eBPF.md": {
"hash": "62f8451a2e9e851a67266bf8cbb0fc6d"
},
"en:community/ChangeLog/V0.1.x/V0.1.6.md": {
"hash": "5517b35f61f5b89d8e825a399581ea0f"
},
"en:introduction/features.md": {
"hash": "75d47fcb0d83487b28957dace1e24578"
},
"en:community/ChangeLog/V0.1.x/V0.1.5.md": {
"hash": "898444d989993df55486ca8d454efbb6"
},
"en:community/ChangeLog/V0.1.x/V0.1.0.md": {
"hash": "26fef9a12925fdcc4729f363ae5b2614"
},
"en:community/ChangeLog/V0.1.x/V0.1.2.md": {
"hash": "41afa92fde268ffd547a3e4326fba1cd"
},
"en:community/ChangeLog/V0.1.x/V0.1.10.md": {
"hash": "7a292c40f822e371ea650f3157857844"
},
"en:kernel/core_api/kernel_api.md": {
"hash": "8b840ec6af5782d8f793f746b1061ed9"
},
"en:index.rst": {
"hash": "8ca31b793978d962c65df867b3261860"
}
}

6
docs/community/contact/index.rst
View File

@ -1,7 +1,7 @@
.. _get_contact_with_community:
与社区建立联系
====================================
====================================================================
联系方式
-------------------------
@ -18,7 +18,7 @@ DragonOS官网： https://DragonOS.org
赞助及捐赠
-------------------------
---------------------------------------------------------
DragonOS是一个开源项目，我们欢迎任何形式的赞助和捐赠，您的捐赠将用于DragonOS的开发和维护，以及社区的运营。
@ -28,7 +28,7 @@ DragonOS是一个开源项目，我们欢迎任何形式的赞助和捐赠，您
- 联系社区负责人，沟通具体的赞助方式等。联系方式：longjin@dragonos.org
财务及捐赠信息公开
-------------------------
---------------------------------------------------------
DragonOS社区的捐赠信息将按年进行公开。赞助商、赞助者信息将在收到赞助后，15天内进行公开。

1
docs/conf.py
View File

@ -47,6 +47,7 @@ templates_path = ['_templates']
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'zh_CN'
locale_dirs = ['locale/'] # path is example but recommended.
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.

22
docs/index.rst
View File

@ -3,9 +3,22 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. Note: __EXCLUDE_IN_TRANSLATED_START
欢迎来到DragonOS的文档！
====================================
.. raw:: html
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Translations</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="locales/en/index.html">English</a></li>
</ul>
</div>
.. Note: __EXCLUDE_IN_TRANSLATED_END
.. toctree::
:maxdepth: 1
:caption: 入门
@ -52,6 +65,13 @@
community/contact/index
community/ChangeLog/index
.. Note: __EXCLUDE_IN_TRANSLATED_START
.. toctree::
:maxdepth: 1
:caption: Translations
locales/en/index
Indices and tables
==================
@ -59,3 +79,5 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. Note: __EXCLUDE_IN_TRANSLATED_END

2
docs/kernel/trace/eBPF.md
View File

@ -18,7 +18,7 @@ eBPF 从根本上改变了这个方式。通过允许在操作系统中运行沙
## eBPF的运行流程
![image-20240909165945192](./ebpf_flow.png)
![image-20240909165945192](/kernel/trace/ebpf_flow.png)
如图所示，eBPF程序的运行过程分为三个主要步骤：

2
docs/kernel/trace/kprobe.md
View File

@ -14,7 +14,7 @@ kprobes技术依赖硬件架构相关的支持，主要包括CPU的异常处理
## kprobe工作流程
<img src="./kprobe_flow.png" style="zoom: 67%;" alt="xxx"/>
<img src="/kernel/trace/kprobe_flow.png" style="zoom: 67%;" alt="xxx"/>

304
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.0.md Normal file
View File

@ -0,0 +1,304 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.0.md
- Translation time: 2025-05-19 01:48:03
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.0
:::{note}
Author of this document: Longjin <longjin@RinGoTek.cn>
November 6, 2022
:::
## Preface
&emsp;&emsp;DragonOS has been under development since January 15, 2022, and has now gone through nearly 300 days. In these many days and nights, it's hard to count how much time has been spent on DragonOS development. I have basically given all my free time to DragonOS, and the estimated total working hours have already exceeded 1000 hours. It feels very rewarding to be able to release the first version.
&emsp;&emsp;Since July 2022, a number of friends and mentors from six universities or companies have joined the development of DragonOS. I was very happy about this. I think, with everyone's joint efforts, we can create an operating system that is truly practical! We have held 14 discussion meetings. I believe, with everyone's joint efforts, in the future, we will be able to create an independent, open, server-oriented open-source operating system that can be used in production environments.
&emsp;&emsp;Although DragonOS is currently just a toy-level operating system, it's "only slightly more difficult than a undergraduate graduation project." However, please don't underestimate it. Its internal architecture design targets Linux 5.18 and later distributions. Although it has not yet reached the level of Linux, we are working hard to catch up. Thanks to the relevant resources of Linux, DragonOS has learned a lot of design ideas from Linux during its architecture design. The related components have considered scalability and portability as much as possible.
&emsp;&emsp;A journey of a thousand miles begins with a single step. The release of DragonOS V0.1.0 is a new beginning. **I hope, in the next ten years, we can work together with many partners, and by 2032, build DragonOS into a practical, widely used open-source operating system in the server field!**
&emsp;&emsp;**A hundred boats race, the ones who row first win; in the middle stream, the brave win.** I believe, with the continuous efforts of the community developers in the coming time, our goal will become a reality!
## Special Thanks
&emsp;&emsp;At the time of the release of DragonOS V0.1.0, I would like to express my sincere gratitude to my teachers, predecessors, and school!
- **Teacher Yao Zhicheng from Dali Town Central Primary School, Nanhai District, Foshan City**: You are the guide who introduced me to computers and taught me programming. Ten years ago, when we talked, you said, "Our country currently does not have an independent and mature operating system." This sentence planted the seed of my dream. You cultivated my love for computers, so I chose the major of software engineering. Thank you for your guidance back then, I will never forget your kindness!
- **Shimen Experimental School, Nanhai District, Foshan City**: During the three years I studied at Shimen Experimental School, I am very grateful for the school's "Strength-based Education" philosophy. Under the guidance of the teachers, I was able to fully develop my personality and talents, and achieved good results. During the three years at Shimen Experimental School, I learned C++, Java, and simple algorithms, and I developed several Android apps, accumulating nearly 6,000 lines of code.
- **Shimen Middle School, Nanhai District, Foshan City**: "The road is long and the task is heavy, never forget to strive" is the school motto of Shimen Middle School. I think this motto should also become the motto of each new generation of youth. During the three years at Shimen Middle School, the education of national sentiment had a great impact on me. I think, as new generation of youth, we should shoulder the responsibility of the times, strive hard, and work for the development of the country, the strength of the nation, and the future of humanity!
- **South China University of Technology**: "Broad learning, careful thinking, clear discernment, and firm action" – at SCUT, I received further learning and development. I broadened my horizons, learned to communicate with many people. Moreover, in the School of Software, I met a group of conscientious and responsible teachers. I am very grateful for the support of the school, which supported us in establishing the project group. I believe, with the support of the school, DragonOS can achieve better development and go further!
- **Professor Wang Guohua from the School of Software, South China University of Technology**: Professor Wang is my teacher for the course "Operating System". Under her guidance, I gained a deeper understanding of the principles of operating systems, and participated in the "Pan-Delta+ University Students' Computer Works Competition". In the Guangdong provincial selection in June 2022, DragonOS won the first prize and the Best Innovation Award.
- **Professor Tang Feng from the School of Software, South China University of Technology**: Professor Tang is our project group's on-campus mentor. Under her careful guidance, we will continue to move forward, keep our direction, and continuously build an open-source community. I sincerely thank Professor Tang for her guidance!
- **[Yaotian Feng](https://github.com/Codetector1374)**: I met this very capable person on Bilibili. He answered many of my questions. Many times, after I had debugged for several days without any idea, a few words from him would wake me up and help me find the path to solve the problem. He also shared with me the places where I might fall into traps, allowing me to have a psychological expectation when about to fall into a trap, so I wouldn't feel so uncomfortable, ha ha.
## Contributors List
The release of DragonOS V0.1.0 could not have been achieved without the joint efforts of the following friends:
- Longjin <longjin@RinGoTek.cn>
- zzy666-hw <zzy666@mail.ustc.edu.cn>
- Guan Jinquan <guanjinquan@DragonOS.org>
- Zhou Yuzhe <zhouyuzhe@DragonOS.org>
- kkkkkong <kongweichao@DragonOS.org>
- houmkh <jiaying.hou@qq.com>
- wang904 <1234366@qq.com>
- Liric Mechan <i@liric.cn>
- Mustang <handsomepd@qq.com>
- Eugene <caima12138@foxmail.com>
- kun <1582068144@qq.com>
- zhujikuan <1335289286@qq.com>
- Alloc Alice <1548742234@qq.com>
## Sponsors List
Thank you to the following students for their donations. We will keep working hard!
- TerryLeeSCUT
- Wu
- slientbard
## Kernel
### Some Standards and Specifications Followed
- Bootloader: Multiboot2
- System Interface: POSIX 2008
### Hardware Architecture
- Currently supports running on x86-64 architecture processors
### Bootloader
- Uses Grub 2.06 as the bootloader
### Memory Management
- Implemented a bitmap-based page allocator
- Implemented a slab allocator for allocating small, aligned memory blocks
- Abstracted VMA (Virtual Memory Area)
- Implemented VMA reverse mapping mechanism
- Implemented MMIO address space auto-mapping mechanism
### Multi-core
- Supports multi-core boot. That is, after DragonOS starts, it will start the AP processor. However, to simplify the implementation of other kernel modules, currently, there are no tasks running on the AP processor.
- Roughly implemented the IPI (Inter-Processor Interrupt) framework
### Process Management
- Supports process creation and recycling
- Kernel threads
- Kthread mechanism
- User-space and kernel-space process/thread fork/vfork (note that user-space fork and kernel-space fork have some differences; kernel-space fork is more complex)
- exec allows a process to execute a new executable file
- Process timer sleep (sleep) (supports high-precision sleep with spin/rdtsc, supports sleep via context switching)
### Synchronization Primitives
- spinlock spin lock
- mutex mutex
- atomic atomic variable
- wait_queue wait queue
- semaphore semaphore
### Scheduling Related
- CFS scheduler
- Single-core scheduling (multi-core load balancing is temporarily not supported)
- completion "completion" mechanism, allowing a process to wait for a task to complete
### IPC (Inter-Process Communication)
- Anonymous pipe
### File System
- Basic functionality of the VFS virtual file system
- FAT32 file system (does not support deleting folders)
- devfs device file system. Currently, only the keyboard file is registered.
- rootfs root file system, provides support for other pseudo-file systems before the real disk file system is mounted
- Mount point abstraction. Currently, file system mounting is implemented, and all mount points are managed in a stack-like manner (optimization is needed in the future)
### Exception and Interrupt Handling
- Handling of processor exceptions
- Support for APIC
- Softirq soft interrupt mechanism
- Ability to trace the kernel stack
### Kernel Data Structures
- Ordinary binary tree
- kfifo first-in-first-out buffer
- Circular linked list
- IDR mapping data structure
- IDA ID allocation data component
### Screen Display
- VESA VBE display chip driver
- Implemented a screen manager, supporting multiple display frameworks to be registered with the screen manager
- Implemented a TextUI text interface framework, capable of rendering text to the screen. Also reserves support for scrollable pages and multiple display windows
- printk
### Kernel Utility Library
- String operation library
- ELF executable file support component
- Basic math library
- CRC function library
### Software Portability
- Ported the LZ4 compression library (V1.9.3), laying the foundation for future page compression mechanisms
### Kernel Testing
- ktest unit test framework
- Supports outputting screen content to a file via serial port (COM1)
### Driver Support
- IDE hard disk
- AHCI hard disk (SATA Native)
- ACPI Advanced Power Configuration module
- PCI bus driver
- XHCI host controller driver (USB 3.0)
- PS/2 keyboard
- PS/2 mouse
- HPET high-precision timer
- RTC clock
- Local APIC timer
- UART serial port (supports RS-232)
- VBE display
- Virtual tty device
### System Calls
DragonOS currently has a total of 22 valid system calls.
- SYS_PUT_STRING Print characters to the screen
- SYS_OPEN Open a file
- SYS_CLOSE Close a file
- SYS_READ Read from a file
- SYS_WRITE Write to a file
- SYS_LSEEK Adjust the file pointer
- SYS_FORK Fork system call
- SYS_VFORK Vfork system call
- SYS_BRK Adjust the heap size to a specified value
- SYS_SBRK Adjust the heap size by a relative value
- SYS_REBOOT Reboot (this system call will be removed after sysfs is improved; please do not rely on this system call excessively)
- SYS_CHDIR Change the working directory of the process
- SYS_GET_DENTS Get metadata of directory entries
- SYS_EXECVE Let the current process execute a new program file
- SYS_WAIT4 Wait for a process to exit
- SYS_EXIT Exit the current process
- SYS_MKDIR Create a directory
- SYS_NANOSLEEP Nanosecond-level sleep (up to 1 second), capable of high-precision sleep when less than 500ns
- SYS_CLOCK Get the current CPU time
- SYS_PIPE Create a pipe
- SYS_MSTAT Get the current memory status information of the system
- SYS_UNLINK_AT Delete a directory or delete a file link
### Rust Support
- Implemented a simple "hello world" in Rust. Plan to gradually shift to using Rust for development in the next version.
## User Environment
### LibC
&emsp;&emsp;LibC is the bridge between applications and the operating system. DragonOS's LibC implements some simple functions.
- malloc heap memory allocator
- Basic math library
- A few simple functions related to files
- pipe
- fork/vfork
- clock
- sleep
- printf
### Shell Command Line Programs
- Based on simple string matching parsing (not done through the compilation course's method, so it's simple and crude)
- Supported commands: ls, cd, mkdir, exec, about, rmdir, rm, cat, touch, reboot
### User-space Driver Programs
- User-space keyboard driver
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code in the following ways:
### Get via Git
- You can visit [https://github.com/fslongjin/DragonOS/releases](https://github.com/fslongjin/DragonOS/releases) to download the release code and the compiled, runnable disk image.
- We also have a mirror repository on gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To solve the problem of slow and unstable access to GitHub in China, and to make it convenient for developers to download the code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the DragonOS code archive and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
## Open Source Code Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source protocol. Everyone who can obtain the DragonOS source code and related software products (including but not limited to binary copies and documents) will enjoy the rights granted by us through the GPLv2 protocol, and you must also comply with the obligations stipulated in the protocol.
This is a rather strict protocol that protects the healthy development of open source software and prevents it from being encroached upon.
For most people with good intentions, you will not violate our open source protocol.
We encourage the free spread and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others, nor do they violate the GPLv2 protocol.
Please pay special attention to the fact that those who violate the open source protocol, especially **commercial closed-source use and any plagiarism or academic misconduct**, will be held seriously accountable. (This is the easiest scenario to violate our open source protocol.)
Also, please note that according to the requirements of the GPLv2 protocol, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 protocol and must indicate that it is based on DragonOS. It must also ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must make sure that the DragonOS developers can obtain the source code of your modified version through the same way from public channels, otherwise you will violate the GPLv2 protocol.
For detailed information about the protocol, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 protocol, **only the English original version has legal effect**. Any translated version is for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, some open source projects' designs were referenced, or parts of their code were introduced, or they were inspired by them. Below are the list of these open source projects. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - 《A Design and Implementation of a 64-bit Operating System》Tian Yu; People's Posts and Telecommunications Press
- chcore - 《Modern Operating Systems: Design and Implementation》Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT

358
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.1.md Normal file
View File

@ -0,0 +1,358 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.1.md
- Translation time: 2025-05-19 01:41:56
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.1
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
November 27, 2022
:::
## Contributors List
The DragonOS V0.1.1 version was contributed by the following team members:
- Longjin <longjin@RinGoTek.cn>
- Zhou Yuzhe <zhouyuzhe@DragonOS.org>
## Sponsors List
Thank you to the following individuals for their support. We will continue to strive for excellence!
- David Wen
- TerryLeeSCUT
- Wu
- slientbard
Among them, we are especially grateful to **David Wen** for his sponsorship of RMB 1000 to the DragonOS project! We will carefully record each donation and ensure that it is used appropriately.
## Update Content - Kernel
- Added Rust FFI (#_translated_label__77_en)
- Ported kmalloc and printk to Rust
- Rust macros for kdebug, kinfo, kwarn, kBUG, kerror
- Bugfix: Fixed the issue where the process PCB was not removed from the list when it was reclaimed
- Directory structure optimization: Moved asm.h and cmpxchg.h
- Signal sending
- procfs: View process status
- Resolved the issue of disk image permission errors during the first compilation
- Moved fork-related code to fork.c
## Update Content - User Environment
- Shell: Added the kill command, which can send signals to a target process. However, since the signal mechanism is still not fully implemented, the target process cannot currently respond to this signal.
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can download the release code and the compiled, runnable disk image from [https://github.com/fslongjin/DragonOS/releases](https://github.com/fslongjin/DragonOS/releases).
- We also have a mirror repository on Gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To address the slow and unstable access to GitHub in China, and to make it easier for developers to download the code for each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the compressed package of DragonOS code and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and corresponding software products (including but not limited to binary copies and documentation) will enjoy the rights granted by us through the GPLv2 license, and you must also comply with the obligations stipulated in the agreement.
This is a rather strict license that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 license.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source use and any plagiarism or academic misconduct**, will be subject to serious accountability. (This is the most common scenario where the open source license is violated.)
Also, please note that according to the requirements of the GPLv2 license, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 license and must clearly indicate that it is based on DragonOS. It is also necessary to ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must make it possible for the developers of DragonOS to obtain the source code of your modified version through public channels, otherwise you will violate the GPLv2 license.
For detailed information about the agreement, please read the **LICENSE** file in the project root directory. Please note that according to the requirements of the GPLv2 license, **only the English original version is legally binding**. Any translated version is for reference only.
:::
### Open Source Software Usage
&emsp;&emsp;During the development of DragonOS, we have referenced the design of some open source projects, or introduced parts of their code, or been inspired by them. Below is a list of these open source projects. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - 《A Design and Implementation of a 64-bit Operating System》 by Tian Yu; People's Posts and Telecommunications Press
- chcore - 《Modern Operating Systems: Design and Implementation》 by Chen Haibo and Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
## All Commit Records of the Current Version
```text
commit d65ade9c5909076747bd00966a398fe27fbd290d
Author: DaJiYuQia <88259094+DaJiYuQia@users.noreply.github.com>
Date: Sun Nov 27 14:21:31 2022 +0800
Patch procf (#95)
* debug color problem
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 6cb769c423b09e88fea1763210200a716477be0a
Author: login <longjin@ringotek.cn>
Date: Sun Nov 27 14:17:36 2022 +0800
将include目录下的rust代码转移到他们应当属于的模块中 (#96)
* 将include目录下的rust代码转移到他们应当属于的模块下。
commit 27a97abd2474b03ad09b562e5ed11e1fdae8eb32
Author: DaJiYuQia <88259094+DaJiYuQia@users.noreply.github.com>
Date: Sat Nov 26 17:34:00 2022 +0800
Patch procf (#90)
* 1234
* 123
* 合并master
* procfs
* 1
* procfs展示进程基本信息
* modified code
* 恢复权限
* 恢复权限
#恢复权限
* modify permission
* 删除run.sh
* 解决第一次编译时磁盘镜像权限错误的问题
* 恢复.vscode/c_cpp_properties.json
* 删除process.c中错误的do_fork
* remake procfs
* 修改一些变量名
* 修改类型
* modified
* data_puts缓冲区溢出后return
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit ad23fcddf893d7f92d2bf3efdb66e969416d2852
Author: login <longjin@ringotek.cn>
Date: Wed Nov 23 21:34:35 2022 +0800
bugfix: 修复进程退出时未释放signal和sighand && 增加赞赏者名单：David Wen (#93)
* bugfix: 修复进程退出时未释放signal和sighand的bug
* 增加赞赏者名单：David Wen
commit 0274cd6eeec01885232e7418a501857cb76da69e
Author: login <longjin@ringotek.cn>
Date: Wed Nov 23 20:43:18 2022 +0800
修正drop signal结构体的box对象的的问题 (#92)
* fix: exit signal and exit sighand
commit c8025a88798dc57ecc5d7f20ad69de695445638f
Author: login <longjin@ringotek.cn>
Date: Wed Nov 23 20:18:22 2022 +0800
new:在fork时拷贝signal和sighand (#91)
* refcount初始化
* new: 实现copy_sighand
del: 删除sighand_struct的wqh, 待将来有需要时，替换成rust版本的
* new: 拷贝signal
bugfix: 解决拷贝sighand时的uaf问题
commit 66f67c6a95b8aad85cfd2146a86e5e3e6a3568e7
Author: login <longjin@ringotek.cn>
Date: Wed Nov 23 11:38:20 2022 +0800
signal的发送（暂时父子进程之间共享信号及相应的结构体） (#89)
* 解决由于spinlock.h中包含preempt_enable()带来的循环include问题
* new: 初步实现signal的数据结构
* new:signal相关数据结构
* fix: 解决bindings.rs报一堆警告的问题
* new: rust下的kdebug kinfo kwarn kBUG kerror宏
* 移动asm.h和cmpxchg.h
* new: signal的发送（暂时只支持父子进程共享信号及处理函数）
commit 3d729e2069e01ee07525ff83167566dac5322a40
Author: login <longjin@ringotek.cn>
Date: Fri Nov 18 17:59:33 2022 +0800
bugfix: 修复进程pcb被回收时，未将其从链表中删除的问题 (#87)
* bugfix: 修复进程pcb被回收时，未将其从链表中删除的问题
new: pcb相关api文档
* 将文档加入目录
commit 0bfe94f46be9bdde1ade81a20e803aa2aafd2964
Author: login <longjin@ringotek.cn>
Date: Fri Nov 18 16:32:15 2022 +0800
new: rust下的kdebug kinfo kwarn kBUG kerror宏 (#86)
* new: rust下的kdebug kinfo kwarn kBUG kerror宏
commit c6174797dcf3427f38bfa0f4bd3e039c319f7c5b
Author: login <longjin@ringotek.cn>
Date: Thu Nov 17 20:29:29 2022 +0800
fix: 解决bindings.rs报了很多警告的问题 (#85)
* fix: 解决bindings.rs报一堆警告的问题
commit cffd7144fbed84f9775e89d7b99602c6ccc5a510
Author: login <longjin@ringotek.cn>
Date: Wed Nov 16 15:18:03 2022 +0800
signal相关数据结构&代码结构优化 (#84)
* 解决由于spinlock.h中包含preempt_enable()带来的循环include问题
* new: 初步实现signal的数据结构
commit fb6c29d01d4cf92368efec08c01e419c2a941f7d
Author: login <longjin@ringotek.cn>
Date: Sun Nov 13 16:43:58 2022 +0800
port kmalloc and printk to rust (#83)
* 暂时移除cbindgen
* 将lib文件夹更名为libs文件夹（解决rust的冲突）
* 实现了全局的allocator
* 实现了printk宏
* new: 完善了printk的颜色
commit 82d2e446a401e7eee57a847f48a6d162931170c3
Author: login <longjin@ringotek.cn>
Date: Sat Nov 12 15:25:54 2022 +0800
new: 暂时移除cbindgen (#82)
commit 2aaf7808efe44ecfaadd51ae4f8892e667108578
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 22:21:44 2022 +0800
在内核中引入cbindgen，生成rust-C的FFI (#81)
* 解决codeql失败问题
* new: 为内核引入cbindgen
commit 2813126e3190c9b3c1a836a647b259a7adbe0cf3
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:35:37 2022 +0800
新增rust ffi (#77)
* 引入cargo
* 取消对Cargo.lock的跟踪
* 解决vscode报错问题
* new: rust的代码能够调用c语言的printk_color
* 1、将原本run.sh的工作拆解，变为几个不同的make命令
2、在docker镜像中编译rust
* 更改workflow
* update workflow
* new: 解决workflow无法通过编译的问题
commit 5e023cf7911333eb05bfe65704dce4b01fa4d0a7
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:21:45 2022 +0800
Update makefile.yml
commit e44795008f7e34d2068cf28dcedbcb91f5ccd66b
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:18:13 2022 +0800
Update makefile.yml (#80)
commit ec5fb84b61c313824cc2199ab64e3af4b7e5f895
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:08:09 2022 +0800
Update makefile.yml
commit 6d9dff5f1ff347ea780a0249e54eef356cdcaaea
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:07:48 2022 +0800
Revert "Update makefile.yml (#78)" (#79)
This reverts commit badc7d238f2341e844a90be3e357e5dd77a447fc.
commit badc7d238f2341e844a90be3e357e5dd77a447fc
Author: login <longjin@ringotek.cn>
Date: Fri Nov 11 15:05:52 2022 +0800
Update makefile.yml (#78)
```

1075
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.10.md Normal file
View File

File diff suppressed because it is too large Load Diff

333
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.2.md Normal file
View File

@ -0,0 +1,333 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.2.md
- Translation time: 2025-05-19 01:42:16
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.2
:::{note}
Author: Long Jin <longjin@RinGoTek.cn>
December 17, 2022
:::
## Contributors
The DragonOS V0.1.2 version has been contributed by the following developers:
- Long Jin <longjin@ringotek.cn>
- Wu Yujian <wuyujian@DragonOS.org>
- Gou Ngai <sujintao@DragonOS.org>
- Huang Ting <huangting@DragonOS.org>
- Wang Wencong <1297389017@qq.com>
## Sponsors
Thank you to the following individuals for their support. We will continue to strive hard!
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- TerryLeeSCUT
- Wu
- slientbard
Among them, we are especially grateful to **Seele.Clover** for contributing RMB 500 to the DragonOS project! We will carefully record every sponsorship and ensure that it is used appropriately.
## Update Content - Kernel
- Remove rust_helloworld file (#_translated_label__113_en)
- Signal: Allow users to register signal handler functions, enabling custom handlers. (#_translated_label__112_en)
- Support for the kill command
- Allow users to customize signal handling functions
- Add two new system calls: `SYS_SIGACTION`, `SYS_RT_SIGRETURN`
- libc adds `signal()`, `sigaction()` functions.
- Currently only supports the old version of sighandler, i.e., signal handler functions with only one parameter of type `void handler(int signum)`. The other type of signal handler function `void handler(int signum, siginfo_t *info, void* data)` does not currently support passing the third parameter.
- Add a custom stdint.h file in the kernel code (#_translated_label__109_en)
- Adjust the script for compiling grub (#_translated_label__108_en)
- Add 32-bit and 64-bit UEFI boot support (#_translated_label__105_en)(#_translated_label__101_en)
- Use compiled installed grub-2.06 to solve the problem of compilation failure due to incorrect grub version on the client.
- Add a timekeeping module (#_translated_label__106_en)
- Bugfix: Fix the issue where the rtc clock forgot to process the day field when converting to BCD code (#_translated_label__104_en)
- New: Development process documentation (completed half)
- bootstrap.sh solves the problem of slow rust download
- Update the "Build System" documentation
- procfs->status adds display of preempt and virtual runtime (#_translated_label__100_en)
- ffz function: get the first bit that is 0 in a u64 (#_translated_label__100_en)
- Solve the problem of local_irq_restore not being able to get the correct rflags value due to compiler optimization
- Refactor the serial port driver using Rust (#_translated_label__99_en)
## Update Content - User Environment
- about app: Display the current git commit sha1 and build time (#_translated_label__114_en)
- shell: Fix the error in the shell's exec command when concatenating absolute paths (#_translated_label__114_en)
- shell: Add "&" background execution option for the exec command (#_translated_label__100_en)
- New: Test app for signal
- Adjust the libc directory and add cargo as the Rust package manager
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can download the release code and the compiled, runnable disk image from [https://github.com/fslongjin/DragonOS/releases](https://github.com/fslongjin/DragonOS/releases).
- We also have a mirror repository on gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To solve the problem of slow and unstable access to GitHub in China, and to make it convenient for developers to download the code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the DragonOS source code package and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and corresponding software products (including but not limited to binary copies and documents) can enjoy the rights granted by us through the GPLv2 protocol, while you also need to comply with the obligations stipulated in the protocol.
This is a rather strict protocol that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source protocol.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 protocol.
Please pay special attention to the fact that violations of the open source protocol, especially **commercial closed-source use and any plagiarism or academic misconduct**, will be subject to serious accountability. (This is the easiest scenario to violate our open source protocol.)
Also, please note that according to the requirements of the GPLv2 protocol, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 protocol and clearly indicate that it is based on DragonOS. It must also ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must make sure that the developers of DragonOS can obtain the source code of your modified version through public channels in the same way, otherwise you will violate the GPLv2 protocol.
For detailed information about the protocol, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 protocol, **only the English original version is legally binding**. Any translated version is for reference only.
:::
### Open Source Software Usage
&emsp;&emsp;During the development of DragonOS, we have referenced some open source projects' designs, or introduced parts of their code, or been inspired by them. We list them below. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - 《A Design and Implementation of a 64-bit Operating System》 by Tian Yu; People's Posts and Telecommunications Press
- chcore - 《Modern Operating Systems: Design and Implementation》 by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
## All Commit Records of the Current Version
```text
commit 7a818da88a1c7a1760de7671141b0ce1ca4e3dde
Author: login <longjin@ringotek.cn>
Date: Sat Dec 17 17:49:12 2022 +0800
Patch about auto gen version string (#114)
* new: about app中，显示当前构建的git commit sha1以及构建时间
* bugfix: 修复shell的exec命令对绝对路径的拼接错误问题
commit 83a7aaa46bbc411c43d4fc099c6c8884efbe4771
Author: login <longjin@ringotek.cn>
Date: Sat Dec 17 16:31:50 2022 +0800
删除rust_helloworld文件 (#113)
commit 6efd4740336205c9bfdd8b164e667cee2f38781e
Author: login <longjin@ringotek.cn>
Date: Sat Dec 17 16:27:50 2022 +0800
允许用户自定义信号处理函数 (#112)
* new: 用户注册信号处理函数，能够进入自定义的handler
* 修复忘了传信号的数字给用户的处理函数的bug
* new:sigreturn
* 删除注释
commit 0e0c187484281768391e131495f0655e40d70cf7
Author: login <longjin@ringotek.cn>
Date: Fri Dec 16 16:20:09 2022 +0800
在内核代码中加入自定义的stdint.h文件 (#109)
commit d02e6ea4112ad520aa4090ff73cdf592e14c0a82
Author: login <longjin@ringotek.cn>
Date: Wed Dec 14 20:01:55 2022 +0800
调整编译grub的脚本的部分 (#108)
1、bugfix: 修复编译grub的脚本的部分错误
2、将grub下载源替换为tuna
3、优化写入磁盘镜像的脚本
4、将bios文件夹改名为legacy
commit 38b341b8aa671f75ac26d05059aa2e9a09e653b7
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Wed Dec 14 16:58:49 2022 +0800
新增32位uefi启动 (#105)
* 新增32位uefi启动
* 修复小bug
* 增加grub本地编译安装
* 增加本地grub编译安装脚本
* 修正小错误
* 修复空文件夹不上传的bug
commit 01876902fbf6ed43992cc7d153bd8c505cb5224b
Author: Gou Ngai <94795048+AlbertSanoe@users.noreply.github.com>
Date: Wed Dec 14 15:13:54 2022 +0800
增加了timekeeping模块 (#106)
* 增加了timekeeping模块
* 格式化文档和细节更改
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 728aca308917a7d4d0ba10fe8174e9408d77a9a6
Author: login <longjin@ringotek.cn>
Date: Sun Dec 11 22:59:47 2022 +0800
bugfix: 修复rtc时钟对BCD码进行转换的时候，忘了处理day字段的问题 (#104)
commit 237e95c6ddce72d72ae7fedfeca412fab82b3622
Author: wwc-15172310230 <78997674+wwc-15172310230@users.noreply.github.com>
Date: Sun Dec 11 22:22:10 2022 +0800
调整user下libs的libc目录结构 (#103)
* 调整user下libs的libc目录结构
* 修正.gitignore文件的问题
* 修复无法编译的问题
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 2291ffdece1dc5a703602f79f74df8a4854d215b
Author: login <longjin@ringotek.cn>
Date: Sun Dec 11 20:09:58 2022 +0800
文档更新 (#102)
* new: 开发过程文档（完成了一半）
* bootstrap.sh解决下载rust慢的问题
* 更新“构建系统”文档
commit 7f439c5ddbd2ecffc112149d16983975f523052c
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Fri Dec 9 16:08:54 2022 +0800
增加uefi启动 (#101)
* 增加uefi启动
* 修改脚本
* uefi修改
* 删除错误的注释
* 修正写入磁盘镜像的脚本
* 修改X86_64为x86_64
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 1a2eaa402f05f82aaeebe1e03824534a0a425d4d
Author: login <longjin@ringotek.cn>
Date: Thu Dec 8 22:59:51 2022 +0800
signal的处理(kill命令)以及一些其他的改进 (#100)
* 将entry.S中冗余的ret_from_syscall代码删除，改为jmp Restore_all
* new: 增加判断pt_regs是否来自用户态的函数
* new: rust的cli和sti封装
* 将原有的判断pt_regs是否来自用户态的代码，统一改为调用user_mode函数
* ffz函数：获取u64中的第一个值为0的bit
* spinlock增加 spinlock irq spin_unlock_irq
* 临时解决显示刷新线程迟迟不运行的问题
* 更改ffi_convert的生命周期标签
* new: 测试signal用的app
* 解决由于编译器优化导致local_irq_restore无法获取到正确的rflags的值的问题
* new: exec命令增加"&"后台运行选项
* procfs->status增加显示preempt和虚拟运行时间
* 更改引用计数的FFIBind2Rust trait中的生命周期标签
* new: signal处理(kill)
* 更正在review中发现的一些细节问题
commit f8b55f6d3fcbf152a1cb6d6fc722bf1607418b28
Author: TingHuang <92705854+TingSHub@users.noreply.github.com>
Date: Tue Dec 6 22:15:03 2022 +0800
Patch uart (#99)
* 添加UART驱动相关文件
* 添加驱动核心文件，将rust编写的驱动代码加入Package中
* 添加glib.h文件生成rust代码，添加uart驱动代码
* 添加串口发送及接收相关代码
* 添加字符串发送函数,未实现具体功能
* 为调用uart驱动的代码添加rust接口
* 添加字符串发送函数，修改C语言调用接口
* 添加rust串口驱动
* 添加uart.h头文件，将串口端口类型改为enum
* 添加注释，规范代码
commit 036acc52ce9d0fb9e7d92768ff74939a29c07f32
Author: login <longjin@ringotek.cn>
Date: Tue Nov 29 21:46:13 2022 +0800
将entry.S中冗余的ret_from_syscall代码删除，改为jmp Restore_all (#98)
* 将entry.S中冗余的ret_from_syscall代码删除，改为jmp Restore_all
```

504
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.3.md Normal file
View File

@ -0,0 +1,504 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.3.md
- Translation time: 2025-05-19 01:41:49
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.3
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
January 8, 2023
:::
## Contributors
The DragonOS V0.1.3 version was contributed by the following individuals:
- Longjin <longjin@RinGoTek.cn>
- Wu Yujian <wuyujian@DragonOS.org>
- Guan Jinquan <guanjinquan@DragonOS.org>
- Gou Ngai <sujintao@DragonOS.org>
## Sponsors
Thank you to the following individuals for their support. We will continue to strive for excellence!
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- TerryLeeSCUT
- Wu
- slientbard
## Update Content - Kernel
- syscall: new: Add getpid system call (#_translated_label__120_en)
- signal: update: Add all signals except SIGKILL to SigQueue (#_translated_label__120_en)
- rtc: refactor: Refactor RTC driver using Rust (#_translated_label__118_en)
- doc: new: Add documentation for signal (#_translated_label__126_en)
- Spinlock: new: Add Rust-written RawSpinlock (#_translated_label__127_en)
- arch: update: Change the path of the arch module in lib.rs, so that other modules can use the code in arch without specifying arch::x86_64 (#_translated_label__128_en)
- mm: bugfix: Fix the bug where ZONE_NORMAL_INDEX was always 0 during initialization of the page allocator (#_translated_label__129_en)
- scheduler: new: Refactor CFS scheduler using Rust (#_translated_label__131_en)
- smp: Remove the HPET interrupt forwarding function that has been deprecated in smp (#_translated_label__131_en)
- process: bugfix: Fix the issue where the init process forgot to set the fs and gs registers. (#_translated_label__132_en)
- vfs: update: Rename the VFS folder to vfs (#_translated_label__133_en)
- lockref: new: Add Rust version of lockref (#_translated_label__135_en)
- cpu: new: Rust wrapper for cpu_relax(), using the pause instruction to let the CPU rest for a while, reducing idle power consumption. (#_translated_label__135_en)
- Refactor softirq mechanism using Rust (#_translated_label__138_en)
## Update Content - User Environment
- libc: bugfix: Always register sigkill when registering signal handlers (#_translated_label__120_en)
- libc: new: Add raise, kill, abort (#_translated_label__120_en)
- libc: new: Add an arch folder, and add crt0, crti, crtn files under it (#_translated_label__134_en)
- libc: new: Add `fflush()`, `fprintf()`, `stdin`, `stdout`, `stderr`, `ferror()`, `fopen()`, `fclose()`, `putchar()`, `puts()` (#_translated_label__136_en)
- libc: new: Simply add `fopen()` for handling the mode parameter. Please note that it does not fully comply with POSIX, and is inconsistent with Linux. It will be improved when using Rust in the future. (#_translated_label__141_en)
- Porting: new: Add porting and build scripts for gmp, mpfr, and mpc (#_translated_label__136_en)
- Porting: new: Add cross-compilation build scripts for gcc and binutils, as well as patches for gcc-11.3.0 and binutils-2.38 (in the DragonOS-community repository) (#_translated_label__136_en)
- compile: update: Update the include path for the compiler, so that includes do not need the `<libc/src/include/>` prefix (#_translated_label__124_en)
## Update Content - Others
- bugfix: Fix the bug where Docker installation would exit abnormally (#_translated_label__116_en)
- new: Add a new GCC bare-metal compiler targeting x86_64-elf, and use it to compile DragonOS (#_translated_label__111_en)
- update: Update the Docker build image to version `dragonos/dragonos-dev:v1.2`, and support building this build image from a Dockerfile (#_translated_label__111_en)
- bugfix: Fix the bug where the MBR disk image did not set the boot flag (#_translated_label__111_en)
- update: Update the GitHub workflow, add cache, and speed up build checks
- bugfix: Fix the error message when downloading grub2.06 (#_translated_label__125_en)
## Update Content - Software Porting
- new: gcc 11.3.0 userland cross-compiler, commit: `64a5b1cbf28e3305560e166c1b6624e99745c720`, repository: [https://github.com/DragonOS-Community/gcc](https://github.com/DragonOS-Community/gcc)
- new: binutils 2.38 cross-compile tools, commit: `a0ae560e0065862a9867b9e1f8364749ef38d99e`, repository: [https://github.com/DragonOS-Community/binutils](https://github.com/DragonOS-Community/binutils)
- new: gmp 6.2.1, commit: `dd9eee5778fb6027fafa4fe850aff21b1a71c18e`, repository: [https://github.com/DragonOS-Community/gmp-6.2.1](https://github.com/DragonOS-Community/gmp-6.2.1)
- new: mpfr 4.1.1, commit: `fa8e30cdc2e838fdd82b60fec31fcfc5e118aad6`, repository: [https://github.com/DragonOS-Community/mpfr](https://github.com/DragonOS-Community/mpfr)
- new: mpc 1.2.1, (can be ported without applying patches), repository: [https://github.com/DragonOS-Community/mpc](https://github.com/DragonOS-Community/mpc)
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can download the release code and the compiled, runnable disk image from [https://github.com/fslongjin/DragonOS/releases](https://github.com/fslongjin/DragonOS/releases).
- We also have a mirror repository on Gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To address the slow and unstable access to GitHub in China, and to make it convenient for developers to download the code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the DragonOS source code archive and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and corresponding software products (including but not limited to binary copies and documentation) can enjoy the rights granted by us through the GPLv2 protocol, while you also need to comply with the obligations stipulated in the protocol.
This is a rather strict protocol that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 protocol.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source usage and any acts of plagiarism or academic misconduct**, will be subject to serious accountability. (This is the easiest scenario to violate our open source license.)
Also, please note that according to the requirements of the GPLv2 protocol, software modified or developed based on DragonOS must also be open-sourced under the GPLv2 protocol and must indicate that it is based on DragonOS. It must also ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must allow the DragonOS developers to obtain the source code of your modified version through the same method from public channels; otherwise, you will violate the GPLv2 protocol.
For detailed information about the protocol, please read the **LICENSE** file in the root directory of the project. Please note that, according to the requirements of the GPLv2 protocol, **only the English original version has legal effect**. Any translated version is for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, we have referenced the design of some open source projects, or introduced parts of their code, or been inspired by them. Below is a list of these open source projects. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - "A Design and Implementation of a 64-bit Operating System" by Tian Yu; People's Posts and Telecommunications Press
- chcore - "Modern Operating Systems: Design and Implementation" by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
## All Commit Records of the Current Version
```text
commit a8b621c8d1fe77251b8e4eafe258dc0ee7366dd5
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 15:47:44 2023 +0800
修正由于libc中具有crti.S和crtn.S，造成的与x86_64-elf-gcc不兼容的问题 (#144)
commit 9358ff0f6f7daa18d6fab4497de025736b3d6725
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 15:06:52 2023 +0800
Add v0.1.3 changelog (#143)
* new: 0.1.3发行日志
* 新增输出指定时间范围内的贡献者名单的脚本
* 更新bootloader文档
* update: 简介文档
* new: 镜像站文档
* update: 功能特性文档
commit fd91905f022b3ceaa59e666d1ff42d91fb8d40ef
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 11:38:59 2023 +0800
解决编译gcc、binutils的脚本中，变量名称错误的问题 (#142)
commit 62e4613978193aaf5d949a331df0398f2d085a30
Author: Gou Ngai <94795048+AlbertSanoe@users.noreply.github.com>
Date: Sat Jan 7 23:15:37 2023 +0800
使用rust重构softirq机制；解决Rtc驱动的编译警告问题 (#138)
* 使用rust重构softirq机制
* 解决Rtc驱动的编译警告问题
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit e9fdc57bf878f1bc5cc5743dfaeeaef743439291
Author: login <longjin@ringotek.cn>
Date: Sat Jan 7 22:36:49 2023 +0800
简单添加了fopen对mode参数的处理。请注意，它没有完全遵循posix，也与Linux的不一致，将来使用Rust的时候完善它。 (#141)
commit 2224c93ea968bc74621f7e124b4aca04875b3e6a
Author: guanjinquan <1666320330@qq.com>
Date: Fri Jan 6 21:29:23 2023 +0800
完善libc，构建了OS-specific工具链，编译了基于gcc-11.3.0的DragonOS userland compiler，移植了mpfr,gmp,mpc库 (#134)
* 修改include路径
* 添加了创建libsysapi.a和/bin/sysroot/usr/include/+lib/的代码
* 修补.gitignore
* 删除多余项
* 优化脚本可读性
* 新增crt0 crti crtn
* 编译binutils所需的东西
* fflush()和fprintf()的简单实现
* 应用程序启动前，调用初始化libc的函数
* 自动创建sysroot
* 添加了stderr的初始化
* 修改了stderr的初始化
* 内核添加对stdio的简略处理
* 格式化代码
* 修正打开stdio文件描述符的问题
* bugfix: 修复fprintf忘记释放buf的问题
* 修复shell错误地把入口设置为main而不是_start的问题
* 新增__cxa_atexit (gcc要求libc提供这个）
* 增加putchar puts
* 更新写入磁盘镜像的脚本，默认无参数时，使用legacy方式安装
* 更新编译脚本
* stdio增加eof的定义
* 新增extern cplusplus
* mpfr gmp mpc 构建脚本
* 更新libsysapi.a为libc.a
* 加上ferror fopen fclose
* 更新移植的软件的构建脚本
* 更改build_gcc_toolchain.sh中的-save参数名为-save-cache
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 61de2cdc3f29cdc6c441f128119e01e003e6f3ca
Author: login <longjin@ringotek.cn>
Date: Tue Jan 3 23:09:25 2023 +0800
新增rust版本的lockref (#135)
* new:Rust封装cpu_relax(),通过pause指令，让cpu休息一会儿。降低空转功耗
* new: Rust版本的lockref
* Rust的RawSpinlock新增is_locked()和set_value()方法。
* lockref文档
commit 2726f101b4cc787bbd36a69afffb0112f3a6567f
Author: login <longjin@ringotek.cn>
Date: Tue Jan 3 21:01:56 2023 +0800
删除无用的cfs.h (#136)
commit 587086d3f299f7394559d547c828191be20cfc11
Author: login <longjin@ringotek.cn>
Date: Sun Jan 1 16:53:57 2023 +0800
1、在文件系统目录下增加mod.rs 2、将VFS的路径改为vfs(#133)
2、将VFS的路径改为vfs
commit 843e442971a47693f37a5f8d3452c383f7325359
Author: login <longjin@ringotek.cn>
Date: Sat Dec 31 18:43:05 2022 +0800
修复init进程忘记设定fs gs寄存器的问题。 (#132)
commit 74bde36e014ff501241bf40dd83653db47a2c8e4
Author: guanjinquan <1666320330@qq.com>
Date: Sat Dec 31 17:35:39 2022 +0800
Patch porting gcc v2 (#124)
* 更改编译器的Include路径，使得include时不需要加`<libc/src/include/>`前缀
* 修改include路径
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit d4f3de93a23e4bd4f000a3663768d47d094bf188
Author: login <longjin@ringotek.cn>
Date: Sat Dec 31 17:26:12 2022 +0800
使用Rust重构CFS调度器 (#131)
* 新建调度器的文件
* 把softirq vector移动到c文件中（原来在.h)
* 将进程切换方式改为“中断返回时切换”
* new:使用rust重构CFS
* 删除已经在smp中废弃的HPET中断转发函数
* 代码格式化
* 删除多余的dunce依赖
commit 156949680c83f2d7e3b21ed68b11698b88eaf396
Author: login <longjin@ringotek.cn>
Date: Sat Dec 31 13:47:49 2022 +0800
bugfix:修复当使用sched()运行调度器，在切换进程的时候，由于不在中断上下文内，导致当前进程的上下文丢失的问题。 (#130)
bugfix:修复当使用sched()运行调度器，在切换进程的时候，由于不在中断上下文内，导致当前进程的上下文丢失的问题。
bugfix:修复切换进程的宏的汇编代码的损坏部分，未声明rax寄存器，从而导致的编译器未定义行为问题。
commit 882f0b7e7498dbff8de527b2b9159b7f6e6359c9
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Wed Dec 28 19:35:17 2022 +0800
修复内存bug与grub安装脚本的错误 (#129)
* 修复内存bug与grub安装脚本的错误
* 修改小bug
commit adc1846b06fb862caed049f435fc0061488a6ff9
Author: login <longjin@ringotek.cn>
Date: Mon Dec 26 13:13:12 2022 +0800
内核：在lib.rs中，将arch模块的路径进行更改，使得其他模块使用arch的代码时，不需要指定arch::x86_64 (#128)
commit ac643d420b22f9d454ecefccd51ed34a9664586b
Author: login <longjin@ringotek.cn>
Date: Sun Dec 25 23:53:35 2022 +0800
new:新增rust写的RawSpinlock (#127)
commit 998390210549b47e6bdcc3fdab49eff4086ad18b
Author: login <longjin@ringotek.cn>
Date: Sat Dec 24 23:30:26 2022 +0800
新增signal文档 (#126)
* 新增signal文档
commit a7f5ca7b67160557abf84a1169dd60093220aeb0
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Sat Dec 24 23:29:36 2022 +0800
修复下载grub2.06时的提示错误 (#125)
* 修复grub下载显示提示显示错误
commit 82762007da41148e1ed1df465211eb5c8ba2c15e
Author: login <longjin@ringotek.cn>
Date: Fri Dec 23 18:11:47 2022 +0800
Update makefile.yml
commit b975025ec8854ca232152f4ee44cc2226891a34c
Author: login <longjin@ringotek.cn>
Date: Fri Dec 23 11:45:19 2022 +0800
Update makefile.yml
commit ad2bb74d949bfcb2935e43ac7b261d7ecce23389
Author: login <longjin@ringotek.cn>
Date: Fri Dec 23 11:21:22 2022 +0800
Update makefile.yml
commit 6b7776d189ab5f19fbab20d6c5c9ed3ab20c7ab6
Author: login <longjin@ringotek.cn>
Date: Fri Dec 23 10:59:15 2022 +0800
修正smp的makefile中没有替换AS的问题
commit beb12a188b6c6bc4196796ac2ae1ecd7d8ed8223
Author: login <longjin@ringotek.cn>
Date: Fri Dec 23 10:57:39 2022 +0800
Update makefile.yml
commit d65c527730e5c8a75f6dad0f996c093040699ee3
Author: login <longjin@ringotek.cn>
Date: Thu Dec 22 22:58:28 2022 +0800
Update makefile.yml (#121)
commit 5ed4cd460200cb19aae8c3c67dfd77e1e9f0e105
Author: guanjinquan <75822481+guanjinquan@users.noreply.github.com>
Date: Thu Dec 22 21:09:12 2022 +0800
Patch gcc toolchain (#111)
* 添加了GCC_cross_compile——tool_chain
* - 解决环境变量路径拼接时，多了`/`的问题
- apt安装时增加-y,不需用户确认
* 解决添加环境变量的命令有误的问题
* 修正编译错误时，还会执行下一步的问题
* new: 编译完成后清理临时文件
* 更新makefile
* 调整：把grub安装在 $HOME/opt/dragonos-grub下
* new: 新增dockerfile
* 将镜像源换成中科大的（原因是清华的总是ban掉用于构建镜像的服务器的ip）
* 修改为基于debian bullseye构建
* 取消指定版本
* 修复MBR磁盘镜像未设置启动标志的bug
* 取消在docker中安装grub
* 安装grub的过程改到客户机上进行
* bootstrap.sh 添加--no-docker
* 使用新版的docker编译镜像
* 修补, 添加了一些关于gcc的check
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit ba0d93d8b26034abc54bcaf3f0ff04863bbd076e
Author: Gou Ngai <94795048+AlbertSanoe@users.noreply.github.com>
Date: Mon Dec 19 15:04:37 2022 +0800
refactor rtc module in rust (#118)
* 用rust重构rtc模块
* refactor the rtc module by rust
* rtc-updated
* rtc-updated-4
* rtc
commit c588d6f77f4b38939701b946228218ea81a7c8dc
Author: login <longjin@ringotek.cn>
Date: Mon Dec 19 15:03:44 2022 +0800
Patch add abort func (#120)
* 对于除了sigkill以外的信号，也加入队列
* bugfix:libc中，注册信号处理函数时，总是注册sigkill的问题
* 增加getpid系统调用
* 增加了raise、kill、abort
commit 47f0d12a1f1a1aa11be8e751ecdbf76f0cb596d9
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Mon Dec 19 14:53:51 2022 +0800
修复docker安装时异常退出的bug (#119)
* 修复docker安装时异常退出的bug
* 修复grub编译脚本的小bug
commit 978043e47d1143ca2d5cf22b20793f032e8eb5a5
Author: login <longjin@ringotek.cn>
Date: Sun Dec 18 15:09:15 2022 +0800
修复当系统中不存在dosfstools时，无法正确格式化磁盘镜像的问题 (#117)
* 修复当系统中不存在dosfstools时，无法正确格式化磁盘镜像的问题
commit f9127772dc372a2e607388fdd6818d3f9c4c6d28
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Sat Dec 17 23:43:23 2022 +0800
修复docker安装时异常退出的bug (#116)
```

279
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.4.md Normal file
View File

@ -0,0 +1,279 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.4.md
- Translation time: 2025-05-19 01:42:41
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.4
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
February 4, 2023
:::
## Contributors List
The DragonOS V0.1.4 version was contributed by the following developers:
- Longjin <longjin@RinGoTek.cn>
- Gou Ngai <sujintao@DragonOS.org>
- Kong Weichao <kongweichao@DragonOS.org>
- Hou Jiaying <houjiaying@DragonOS.org>
## Sponsors List
Thank you to the following individuals for their support. We will continue to strive for excellence!
- David Wen (2000 RMB)
- [Seele.Clover](https://github.com/seeleclover) (500 RMB)
- Ye Jinyi (100 RMB)
- Lin (50 RMB)
- Albert (9.99 RMB)
- TerryLeeSCUT (6.66 RMB)
- slientbard (6.66 RMB)
- Wu (2.00 RMB)
- [Other anonymous contributors] (1.00 RMB)
## Update Content - Kernel
- Spinlock: new: Added SpinLock with guards, supporting compile-time checking of lock usage. (#_translated_label__148_en)
- Spinlock: feature: Added lock_irqsave and unlock_irqrestore for raw spin lock (#_translated_label__151_en)
- Mutex: new: Rust version of Mutex (#_translated_label__157_en)
- doc: new: Rust code style document (#_translated_label__161_en)
- WaitQueue: new: Rust version of WaitQueue (#_translated_label__162_en)
- WaitQueue: update: For the C version of wait_queue, changed to immediate wake-up (#_translated_label__158_en)
- block io: new: Block IO scheduler. When there are multiple cores, the IO scheduler runs on core 1. (#_translated_label__158_en)
- smp: bugfix: Start apic_timer for AP cores, making them able to run scheduling (#_translated_label__158_en)
- smp: new: Added kick_cpu function, supporting making a specific core run the scheduler immediately (#_translated_label__158_en)
- smp: new: Added process migration functionality between cores (#_translated_label__158_en)
- scheduler: new: Added real-time process scheduler (supporting FIFO and RR strategies) (#_translated_label__139_en)
- scheduler: update: CFS scheduler sets a separate IDLE process pcb (pid is 0) for each core (#_translated_label__158_en)
- scheduler: bugfix: When process_wakeup, reset the virtual runtime for CFS processes. Solves the problem of other processes starving due to small virtual runtime of sleeping processes. (#_translated_label__158_en)
- process: new: Added migrate_to field in pcb (#_translated_label__158_en)
## Update Content - User Environment
None
## Update Content - Others
None
## Update Content - Software Porting
None
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can visit [https://github.com/fslongjin/DragonOS/releases](https://github.com/fslongjin/DragonOS/releases) to download the release code, as well as the compiled and runnable disk image.
- We also have a mirror repository on gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To solve the problem of slow and unstable access to GitHub in China, and to make it convenient for developers to download the code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can get the DragonOS code package and the compiled and runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and corresponding software products (including but not limited to binary copies and documents) will enjoy the rights granted by us through the GPLv2 license, and you must also comply with the obligations stipulated in the agreement.
This is a rather strict license that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others and do not violate the GPLv2 license.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source use and any acts of plagiarism or academic misconduct**, will be subject to serious accountability. (This is the easiest scenario to violate our open source license.)
Also, please note that according to the requirements of the GPLv2 license, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 license and must clearly indicate that it is based on DragonOS. It must also ensure that users of these modified versions can conveniently obtain the original version of DragonOS.
You must make it possible for the DragonOS developers to obtain the source code of your modified version through public channels in the same way, otherwise you will violate the GPLv2 license.
For detailed information about the license, please read the **LICENSE** file in the root directory of the project. Please note that according to the GPLv2 license, **only the English original version is legally binding**. Any translated version is for reference only.
:::
### Open Source Software Usage
&emsp;&emsp;During the development of DragonOS, we have referenced the design of some open source projects, or introduced parts of their code, or been inspired by them. Below is a list of these open source projects. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - "A Design and Implementation of a 64-bit Operating System" by Tian Yu; People's Posts and Telecommunications Press
- chcore - "Modern Operating Systems: Design and Implementation" by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
## All Commit Records of the Current Version
```text
commit f6ba114bb0420e848ef7fc844c96c0d7a0552d93
Author: houmkh <100781004+houmkh@users.noreply.github.com>
Date: Sat Feb 4 12:31:15 2023 +0800
Block IO Scheduler (#158)
* Block io调度器
* process_wakeup时，对cfs的进程，重设虚拟运行时间。解决由于休眠的进程，其虚拟运行时间过小，导致其他进程饥饿的问题
* 1、为AP核启动apic_timer,使其能够运行调度
2、增加kick_cpu功能，支持让某个特定核心立即运行调度器
3、wait_queue的唤醒，改为立即唤醒。
4、增加进程在核心间迁移的功能
5、CFS调度器为每个核心设置单独的IDLE进程pcb（pid均为0）
6、pcb中增加migrate_to字段
7、当具有多核时，io调度器在核心1上运行。
* io调度器文件位置修改
* 修改io的makefile
* 更新makefile中的变量名
* 修改io调度器函数名
---------
Co-authored-by: login <longjin@ringotek.cn>
commit 151251b50b7ed55596edd32ffec49a4041010e2a
Author: login <longjin@ringotek.cn>
Date: Tue Jan 31 19:27:02 2023 +0800
Patch add rust waitqueue (#162)
* new: rust版本的waitqueue
* new:等待队列的文档
commit 3c369b1430e8d571bcc74a8ef7fefc1c4cae5dd2
Author: login <longjin@ringotek.cn>
Date: Mon Jan 30 15:43:42 2023 +0800
new:新增rust代码风格 (#161)
commit c28bd540ac856cd9d8d5597852af8f2588a660e4
Author: login <longjin@ringotek.cn>
Date: Mon Jan 30 15:10:24 2023 +0800
更新赞助者名单 (#160)
* 更新赞赏者列表
commit 935f40ec174fec217aed4553d45996327443bc0e
Author: login <longjin@ringotek.cn>
Date: Tue Jan 17 21:30:16 2023 +0800
new: Rust版本的Mutex (#157)
commit d8a064128a8a06b90ff4c7b87c193518d9572641
Author: Gou Ngai <94795048+AlbertSanoe@users.noreply.github.com>
Date: Mon Jan 16 19:58:50 2023 +0800
Raw spin lock 增加lock_irqsave、unlock_irqrestore(#151)
Raw spin lock 增加lock_irqsave、unlock_irqrestore
commit 06b09f34ed64a006a80ae8df383e3c8b176f02e0
Author: kong <45937622+kkkkkong@users.noreply.github.com>
Date: Sat Jan 14 22:38:05 2023 +0800
Patch sched rust (#139)
* update
* 添加rt调度器的rust初步实现
* 完善rt调度逻辑
* 调试rt调度器
* 修改sched的返回值
* cargo fmt 格式化
* 删除无用代码，修补rt bug
* 删除无用的代码，和重复的逻辑
* 软中断bugfix
* 删除一些代码
* 添加kthread_run_rt文档
* 解决sphinix警告_static目录不存在的问题
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit ec53d23ed03347854189d92b7e175f309779321b
Author: login <longjin@ringotek.cn>
Date: Sat Jan 14 10:35:49 2023 +0800
new: 新增具有守卫的自旋锁SpinLock，支持编译期对锁的使用进行检查。 (#148)
commit 41474ba3df99b6822ce452dc94dc53a4da62cba1
Author: login <longjin@ringotek.cn>
Date: Tue Jan 10 22:07:41 2023 +0800
更新Readme中关于DragonOS的介绍部分 (#146)
commit 8ad2e358fd3b05eed2919de50640682e51687fb5
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 15:51:59 2023 +0800
更新about app中的版本号 (#145)
* 更新about app中的版本号
commit a8b621c8d1fe77251b8e4eafe258dc0ee7366dd5
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 15:47:44 2023 +0800
修正由于libc中具有crti.S和crtn.S，造成的与x86_64-elf-gcc不兼容的问题 (#144)
commit 9358ff0f6f7daa18d6fab4497de025736b3d6725
Author: login <longjin@ringotek.cn>
Date: Sun Jan 8 15:06:52 2023 +0800
Add v0.1.3 changelog (#143)
* new: 0.1.3发行日志
* 新增输出指定时间范围内的贡献者名单的脚本
* 更新bootloader文档
* update: 简介文档
* new: 镜像站文档
* update: 功能特性文档
```

321
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.5.md Normal file
View File

@ -0,0 +1,321 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.5.md
- Translation time: 2025-05-19 01:44:14
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.5
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
March 13, 2023
:::
## Contributors List
The DragonOS V0.1.5 version is contributed by the following developers:
- Longjin <longjin@DragonOS.org>
- Guan Jinquan <guanjinquan@DragonOS.org>
- Su Jintao <sujintao@DragonOS.org>
- Kong Weichao <kongweichao@DragonOS.org>
- Hou Jiaying <houjiaying@DragonOS.org>
- Wu Yujian <wuyujian@DragonOS.org>
- Zhou Yuzhe <zhouyuzhe@DragonOS.org>
- Satin Wuker <74630829+SatinWuker@users.noreply.github.com>
## Sponsors List
Thank you to the following contributors for their support. We will keep working hard!
- Wan Xiaolan
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- [FindWangHao](https://github.com/FindWangHao)
- Ye Jinyi
- Lin
- Albert
- [TerryLeeSCUT · GitHub](https://github.com/TerryLeeSCUT)
- slientbard
- Wu
## Update Content - Kernel
- scheduler: doc: Real-time process scheduler documentation (#_translated_label__163_en)
- scheduler: rt: RTQueue now uses a doubly linked list for storage (#_translated_label__174_en)
- scheduler: load balance: Multi-core load balancing (#_translated_label__193_en)
- Semaphore: new: Added a Rust implementation of the semaphore (#_translated_label__183_en)
- mm: refactor: Refactored the MMIO address allocator (#_translated_label__184_en)
- RwLock: new: Added a Rust implementation of the read-write lock (#_translated_label__186_en)
- driver: update: Improved PCI functionality (#_translated_label__194_en)
- driver: new: VirtIO network card driver (still has issues) (#_translated_label__194_en)
- driver: refactor: Rust version of the AHCI driver (#_translated_label__198_en)
- block io: delete: Removed the Block IO scheduler. (#_translated_label__196_en)
- filesystem: refactor: New version of VFS (#_translated_label__198_en)
- filesystem: refactor: New version of ProcFS (#_translated_label__198_en)
- filesystem: refactor: New version of DevS (#_translated_label__198_en)
- filesystem: new: RamFS memory file system (#_translated_label__198_en)
- filesystem: new: FAT12/FAT16/FAT32 file system (#_translated_label__198_en)
- filesystem: new: New device and block device abstraction (#_translated_label__198_en)
## Update Content - User Environment
- libc: Adjusted, all apps are now directly linked to libc.a, instead of going through the "search.o" process (#_translated_label__171_en)
## Update Content - Others
- bootstrap: Fixed the issue with Ubuntu2210 not being able to compile GRUB correctly, and properly install QEMU (#_translated_label__176_en)
- toolchain: Added a Rust bare bone toolchain (#_translated_label__197_en)
## Update Content - Software Porting
None
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can download the release code and the compiled, runnable disk image by visiting [https://github.com/DragonOS-Community/DragonOS/releases](https://github.com/DragonOS-Community/DragonOS/releases).
- We also have a mirror repository on Gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To address the slow and unstable access to GitHub in China, and to make it easier for developers to download the code for each version of DragonOS, we have specifically set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the DragonOS source code archive and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and related software products (including but not limited to binary copies and documentation) is entitled to the rights granted by us through the GPLv2 license, and you must also comply with the obligations stipulated in the agreement.
This is a rather strict license that protects the healthy development of open-source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open-source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 license.
Please pay special attention to the fact that violations of the open-source license, especially **commercial closed-source usage and any acts of plagiarism or academic misconduct**, will be subject to serious accountability. (This is the most common scenario where the open-source license is violated.)
Also, please note that according to the requirements of the GPLv2 license, any software that is modified or developed based on DragonOS must also be open-sourced under the GPLv2 license and must clearly indicate that it is based on DragonOS. It is also necessary to ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must make it possible for the DragonOS developers to obtain the source code of your modified version through public channels, otherwise you will violate the GPLv2 license.
For detailed information about the license, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 license, **only the English original version has legal effect**. Any translated versions are for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, some open-source projects were referenced, or parts of their code were introduced, or they inspired us. Below is a list of these open-source projects. We sincerely thank the contributors of these open-source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - 《A Design and Implementation of a 64-bit Operating System》 by Tian Yu; People's Posts and Telecommunications Press
- chcore - 《Modern Operating Systems: Design and Implementation》 by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
- redox - https://gitlab.redox-os.org/redox-os/redox - MIT
## All Commit Records of the Current Version
```text
commit 84407d360511c7699938a0f245ae33ff76f16b17
Author: login <longjin@DragonOS.org>
Date: Mon Mar 13 00:26:04 2023 +0800
bugfix：解决touch命令失败的问题 (#199)
* bug fix : 解决touch命令失败的问题
commit 004e86ff19727df303c23b42c7a271b9214c6898
Author: login <longjin@DragonOS.org>
Date: Sun Mar 12 22:36:11 2023 +0800
新版文件系统重构完成 (#198)
1.重构：VFS
2. 重构：ProcFS
3. 重构：DevFS
4. 重构：FAT32
5. 重构：AHCI驱动
6. 新增：RamFS
7. 新增：MountFS
8. 新增：FAT12
9. 新增：FAT16
10. 重构：设备抽象
Co-authored-by: guanjinquan <1666320330@qq.com>
Co-authored-by: DaJiYuQia <88259094+DaJiYuQia@users.noreply.github.com>
commit 17041e0e307eaf9e8d8ddbddfa186cd1f10f1bc0
Author: login <longjin@DragonOS.org>
Date: Sun Mar 12 21:04:37 2023 +0800
添加rust的bare bone工具链 (#197)
commit 26d84a31393c50063ff416bc509316e8d342028c
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Sat Mar 11 21:09:50 2023 +0800
新增VirtIO网卡驱动 (#194)
* 修复内存bug与grub安装脚本的错误
* 修改小bug
* PCI增加功能与virtio-net驱动
* little fix
* virtio-net小修改
commit 1d48996375149279a721777b2c600e1b5c3ee1b5
Author: kong <45937622+kkkkkong@users.noreply.github.com>
Date: Sat Mar 11 18:17:35 2023 +0800
多核负载均衡(#193)
* feat(sched)：CPU负载检测初步实现
* fix(smp):调整smp中的apic的头文件声明
* fix(smp):简单的负载均衡算法实现
* fix(sched):抽离负载均衡方法
* fix(sched):修改rt中的运行队列bug，调整负载均衡逻辑
* fix(process):移除无用测试代码
* reformat code
commit ef9f9732b09f78d7192f1d0dd3b41be655fb0914
Author: houmkh <100781004+houmkh@users.noreply.github.com>
Date: Thu Mar 9 23:31:25 2023 +0800
修复了mmio buddy的bug (#189)
* 修改buddy_query
commit c1396d277115b371d09ad6d39a1c419f9224ffd0
Author: Gou Ngai <sujintao@dragonos.org>
Date: Mon Mar 6 11:28:32 2023 +0800
Rwlock文档 (#186)
* Rwlock文档
commit a7eb62a47a8d701b90a14f83cc9028cfed07c268
Author: houmkh <100781004+houmkh@users.noreply.github.com>
Date: Mon Mar 6 11:21:29 2023 +0800
修改mmio－buddy代码结构和函数名 (#184)
* 修改mmio-buddy结构和函数名
commit c2481452f81750ec02adec627ab2edbc93d9cd9c
Author: houmkh <100781004+houmkh@users.noreply.github.com>
Date: Sat Mar 4 18:36:55 2023 +0800
rust重构mmio_buddy和mmio (#178)
* rust重构mmio_buddy和mmio
* mmio-buddy文档
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit f1284c35717a2f9f8cee7cecfc835ba1d23a1161
Author: Gou Ngai <sujintao@dragonos.org>
Date: Sat Mar 4 17:47:17 2023 +0800
新增了rust实现的信号量 (#181)
* 新增了rust实现的信号量
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 83b9512c1c1e8289000084adcafddebee6a23f16
Author: Gou Ngai <sujintao@dragonos.org>
Date: Sat Mar 4 16:54:42 2023 +0800
新增了rust实现的信号量 (#183)
* 新增了rust实现的信号量
commit e532a536a0b244f4590e6eb7910084bd63049704
Author: login <longjin@ringotek.cn>
Date: Thu Mar 2 22:50:07 2023 +0800
添加赞助者：FengWangHao (#179)
commit b66beefd4e9ead61ee55f335246ebeb8277d3011
Author: login <longjin@ringotek.cn>
Date: Mon Feb 27 01:00:35 2023 +0800
解决ubuntu2210版本无法正确编译grub，以及正确安装qemu的问题 (#176)
commit 4177d0327c3eacdc606f0b22f99f208fd48cfff3
Author: kong <45937622+kkkkkong@users.noreply.github.com>
Date: Mon Feb 20 17:03:37 2023 +0800
RTQueue改用双向链表存储(#174)
* RTQueue改用双向链表存储
commit 2bf5ee0e3cac3a91dee6a13b71c86a9477c07d9b
Author: login <longjin@ringotek.cn>
Date: Sat Feb 11 13:04:24 2023 +0800
修改libc的编译相关内容(#171)
1.将libc的include文件夹分为export和internal
2.将所有app都直接链接libc.a,而不是都执行一遍"搜索.o"的过程
commit 90b077f9d3ecd48ca46f8bbb32363620db6ddbe6
Author: kong <45937622+kkkkkong@users.noreply.github.com>
Date: Thu Feb 9 15:24:37 2023 +0800
Sched rt doc (#163)
* update
* 完善调度器文档
* 更新RT调度器文档
* 更新实时调度文档
commit 009f92d50fe2e52e425bce397801d3fa204daecd
Author: Satin Wuker <74630829+SatinWuker@users.noreply.github.com>
Date: Tue Feb 7 19:29:09 2023 -0800
fix typos 改正README_EN的错别字和语法错误 (#167)
```

319
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.6.md Normal file
View File

@ -0,0 +1,319 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.6.md
- Translation time: 2025-05-19 01:44:51
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.6
:::{note}
Author: Longjin <longjin@DragonOS.org>
April 2, 2023
:::
## Contributors List
The DragonOS V0.1.6 version was contributed by the following developers:
- Longjin <longjin@DragonOS.org>
- Guan Jinquan <guanjinquan@DragonOS.org>
- Su Jintao <sujintao@DragonOS.org>
- Hou Jiaying <houjiaying@DragonOS.org>
- Wu Yujian <wuyujian@DragonOS.org>
- Mork <91721145+MorkCarpenter@users.noreply.github.com>
- WaferJay <17383312+WaferJay@users.noreply.github.com>
- HoshuChiu <129569557+HoshuChiu@users.noreply.github.com>
## Sponsors List
Thank you to the following individuals for their support. We will continue to strive for excellence!
- Wan Xiaolan
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- [FindWangHao](https://github.com/FindWangHao)
- Ye Jinyi
- Lin
- Albert
- [TerryLeeSCUT · GitHub](https://github.com/TerryLeeSCUT)
- slientbard
- Wu
- Anonymous Kind-hearted Person
## Update Content - Kernel
- softirq: Refactored softirq (#_translated_label__223_en)
- timer: Refactored system timer (#_translated_label__223_en)
- stdio: Added tty device for standard input and output (#_translated_label__202_en) (#_translated_label__217_en)
- lib: First set of keyboard scan code state machine (#_translated_label__216_en) (#_translated_label__219_en)
- syscall: Added dup and dup2 system calls (#_translated_label__224_en)
- syscall: Added SystemError enum type to make error handling clearer (#_translated_label__205_en)
- driver: Added support for x87 floating-point processor (#_translated_label__212_en)
- driver: VirtIO network card can now send and receive data normally (#_translated_label__204_en)
- filesystem: Fixed FAT32 judgment logic, resolving the issue where the system could not boot normally when the file system was FAT12/16. (#_translated_label__211_en)
- filesystem: Added VFS document and modified document configuration (#_translated_label__209_en)
- textui: Fixed the issue where the process scheduler did not run when "processes output characters continuously" due to textui locking and changes in preempt_count. (#_translated_label__203_en)
- scheduler: Solved the issue of double locking in cpu_queue caused by not disabling interrupts during sched_enqueue outside of interrupt context. (#_translated_label__201_en)
## Update Content - User Environment
### New Repositories
- Added a sub-project: [dsc](https://github.com/DragonOS-Community/dsc.git)
- Transplanted relic: [DragonOS-relibc](https://github.com/DragonOS-Community/relibc.git)
## Update Content - Others
- build: Added an option for using VNC as the image output for QEMU (#_translated_label__222_en)
## Update Content - Software Porting
None
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can download the release code and the compiled, runnable disk image from [https://github.com/DragonOS-Community/DragonOS/releases](https://github.com/DragonOS-Community/DragonOS/releases).
- We also have a mirror repository on gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To address the slow and unstable access to GitHub in China, and to make it convenient for developers to download the code for each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the DragonOS source code archive and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the DragonOS source code and corresponding software products (including but not limited to binary copies and documentation) can enjoy the rights granted by us through the GPLv2 protocol, while you also need to comply with the obligations stipulated in the protocol.
This is a rather strict protocol that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 protocol.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source usage and any acts of plagiarism or academic misconduct**, will be subject to serious accountability. (This is the most common scenario of violating our open source license.)
Also, please note that according to the requirements of the GPLv2 protocol, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 protocol and must indicate that it is based on DragonOS. It is also necessary to ensure that users of these modified versions can easily access the original version of DragonOS.
You must make sure that the DragonOS developers can obtain the source code of your modified version through public channels in the same way, otherwise you will violate the GPLv2 protocol.
For detailed information about the protocol, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 protocol, **only the English original version has legal effect**. Any translated version is for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, some open source projects were referenced, or parts of their code were introduced, or they inspired us. The following list shows them. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - "Design and Implementation of a 64-bit Operating System" by Tian Yu; People's Posts and Telecommunications Press
- chcore - "Modern Operating Systems: Design and Implementation" by Chen Haibo and Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
- redox - https://gitlab.redox-os.org/redox-os/redox - MIT
## All Commit Records of the Current Version
```text
commit bacd691c9ef0502b5cc618aad50517f9e59df5e0
Author: login <longjin@DragonOS.org>
Date: Sun Apr 2 17:09:33 2023 +0800
软中断&定时器重构 (#223)
* 软中断&定时器重构
Co-authored-by: houmkh<houjiaying@DragonOS.org>
* 修改timer的clock()
* 删除debug信息
---------
Co-authored-by: houmkh <1119644616@qq.com>
commit 6d345b774223b0daaf0ee629c7fb595a1912a9e2
Author: HoshuChiu <129569557+HoshuChiu@users.noreply.github.com>
Date: Sun Apr 2 15:55:24 2023 +0800
添加了qemu使用VNC作为图像输出的选项 (#222)
* 添加了qemu使用VNC作为图像输出的选项
* 设置vnc端口为5900
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 2b771e32f5795e0fdda458e3bb2651ef6b9673ac
Author: Gou Ngai <sujintao@dragonos.org>
Date: Sun Apr 2 15:43:53 2023 +0800
Add dup,dup2 (#224)
* dup,dup2
* fix: sys_dup2语义与posix不一致的问题
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit d7b31a969ff091224a4929496f0278d024f78c77
Author: Gou Ngai <sujintao@dragonos.org>
Date: Fri Mar 31 18:23:58 2023 +0800
Patch keyboard capslock alt (#219)
* keyboard-alt-capslock
* 解决键盘输入'%'字符的时候无法回显的bug
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 20e3152e1eea97f87d644c3023391e172bc83c93
Author: login <longjin@DragonOS.org>
Date: Fri Mar 31 12:54:37 2023 +0800
将TTY与stdio进行连接,实现基本的stdio功能 (#217)
* 将stdio与tty接上
commit 5fb12ce447710edf8566f250655a06cb27519fca
Author: Gou Ngai <sujintao@dragonos.org>
Date: Thu Mar 30 18:19:02 2023 +0800
第一套键盘扫描码的状态机 (#216)
第一套键盘扫描码的状态机
---------
Co-authored-by: guanjinquan <1666320330@qq.com>
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 676b8ef62e1a0a1e52d65b40c53c1636a2954040
Author: Mork <91721145+MorkCarpenter@users.noreply.github.com>
Date: Wed Mar 29 21:24:11 2023 +0800
部分函数从返回值为Result<<>,i32>修改为Result<<>,SystemError> (#210)
* 将Result<<>,i32>替换为Result<<>,SystemError>
* bugfix: 显示双缓冲区初始化的时候，连续注册了两次Video Softirq的问题。
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 64aea4b3494bee7375e1c1ee5739c9fab0db0cb7
Author: Gou Ngai <sujintao@dragonos.org>
Date: Tue Mar 28 20:44:26 2023 +0800
增加x87FPU支持 (#212)
* remove `ret_from_syscall`
*修复ps2键盘驱动程序inode在进程fork的时候导致死锁的问题.
*更新: VFS每次拷贝文件描述符的时候,都会去调用inode的open函数
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 2286eda6526ed1b46afd79b47dc701034b9e903d
Author: WaferJay <17383312+WaferJay@users.noreply.github.com>
Date: Mon Mar 27 09:32:43 2023 +0800
修正了FAT32判断逻辑，解决了文件系统为FAT12/16时系统无法正常启动的问题。 (#211)
* fix(fat): fix determination of fat type casue crash if fs is fat12/16
* refactor(fat): split BiosParameterBlock.validate() into BiosParameterBlockFAT32.validate() and BiosParameterBlockLegacy.validate()
* 调整“最大允许的簇号”的常量放置的位置。
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 45b8371173b070028457f7ee64be33f68b4f9ada
Author: login <longjin@DragonOS.org>
Date: Sat Mar 25 14:51:16 2023 +0800
新增VFS文档，以及修改文档配置 (#209)
* 1.新增vfs设计文档
2.修改文档版权标志为"2022-2023, DragonOS Community"
3.修改电脑版文档页面的宽度为90%
* layout.html末尾加空行
commit 73c607aaddf6e4634cad179a81d3f1bc589f7220
Author: YJwu2023 <119829947+YJwu2023@users.noreply.github.com>
Date: Sat Mar 18 20:43:37 2023 +0800
VirtIO网卡能够正常发送、接收数据 (#204)
* virtio-net小修改
* 移动volatile.rs到libs文件夹
* 使用virtio-drivers 0.3.0
* bugfix: 初始化BAR之后，未正确设置command register的问题
---------
Co-authored-by: longjin <longjin@dragonos.org>
commit 4454d1a2dd1f1078750151c028a794cfd9a04a1b
Author: login <longjin@DragonOS.org>
Date: Sat Mar 18 20:26:05 2023 +0800
新增SystemError枚举类型，使得错误处理更清晰 (#205)
commit 0d48c3c9c21a2dd470d0e1e58b507db60e0887bb
Author: login <longjin@DragonOS.org>
Date: Thu Mar 16 19:48:59 2023 +0800
new: tty设备（尚未与stdio接上） (#202)
commit 790d45764090bce3bbfb96b42b2818100a8cef9a
Author: login <longjin@DragonOS.org>
Date: Wed Mar 15 11:42:41 2023 +0800
修复由于textui加锁，更改了preempt_count导致“进程长时间连续输出字符”的情况下，进程调度器不运行的问题。 (#203)
commit c2e757d8cbeed01b16f48bea48ed8447685e6f1a
Author: login <longjin@DragonOS.org>
Date: Mon Mar 13 22:22:23 2023 +0800
解决由于在中断上下文以外，sched_enqueue时，未关中断导致cpu_queue双重加锁的问题 (#201)
```

359
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.7.md Normal file
View File

@ -0,0 +1,359 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.7.md
- Translation time: 2025-05-19 01:43:50
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.7
:::{note}
Author: Longjin <longjin@DragonOS.org>
April 24, 2023
:::
## Contributors List
The DragonOS V0.1.7 version was contributed by the following contributors:
- Longjin <longjin@DragonOS.org>
- Guan Jinquan <guanjinquan@DragonOS.org>
- Huang Ting <huangting@DragonOS.org>
- Hou Jiaying <houjiaying@DragonOS.org>
- Wu Yujian <wuyujian@DragonOS.org>
- Su Jintao <sujintao@DragonOS.org>
- Zhou Hanjie <zhouhanjie@DragonOS.org>
- HoshuChiu <129569557+HoshuChiu@users.noreply.github.com>
- Bullet <93781792+GP-Bullet@users.noreply.github.com>
## Sponsors List
Thank you to the following individuals for their support. We will continue to work hard!
- Wan Xiaolan
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- [FindWangHao](https://github.com/FindWangHao)
- [ferchiel](https://github.com/ferchiel)
- Ye Jinyi
- Lin
- Albert
- [TerryLeeSCUT · GitHub](https://github.com/TerryLeeSCUT)
- slientbard
- Wu
- Anonymous Kind-hearted Person
## Update Content - Kernel
- scheduler: Change CFSqueue from Vec to Red-Black Tree (#_translated_label__229_en)
- new: lazy_init (#_translated_label__230_en) (#_translated_label__236_en)
- pci: pci restructure + pcie support (#_translated_label__235_en)
- net: Add network subsystem, and support programming in user space (#_translated_label__237_en) (#_translated_label__247_en)
- mm: Adjust brk system call to make parameters and return values consistent with Linux (#_translated_label__238_en)
- Modify errno to be consistent with relicb (#_translated_label__234_en)
- pci: Fix the issue of not being able to get MCFG table with ecam (#_translated_label__241_en)
- libs: DowncastArc and its docs (#_translated_label__244_en)
- softirq: Add timer and softirq documentation, modify the C-oriented interface of softirq (#_translated_label__245_en)
- spinlock: Fix the issue of forgetting to restore rflags in spinlock (#_translated_label__247_en)
- waitqueue: Add wakeup_all and sleep_without_schedule functions (#_translated_label__247_en)(#_translated_label__253_en)
- filesystem: Change the PollStatus structure to use the bitflags library (#_translated_label__247_en)
- filesystem: Add iovec support (brute-force implementation) (#_translated_label__247_en)
- filesystem: Add SysFS (#_translated_label__250_en) (#_translated_label__254_en)
- driver: Improve device driver model according to sysfs (#_translated_label__254_en)
- pipe: Pipe restructure (#_translated_label__253_en)
- irq: Add IrqArch abstraction and IrqFlagsGuard to simplify the process of disabling and restoring interrupts (#_translated_label__253_en)
## Update Content - User Environment
### New Repositories
- New subproject: [dsc](https://github.com/DragonOS-Community/dsc.git)
- New subproject: [DADK](https://github.com/DragonOS-Community/DADK.git) DragonOS Application Development Kit
### [DragonOS-relibc](https://github.com/DragonOS-Community/relibc.git)
- Add sys_dup and sys_dup2 support (#_translated_label__2_en)
- Add the original libc memory allocator, fix alignment issues. (#_translated_label__6_en) (#_translated_label__7_en)
- Configure network-related system calls (#_translated_label__8_en)
- Fix the issue of errno not working properly due to DragonOS not supporting TLS (thread local storage). (#_translated_label__8_en)
## Update Content - Others
- build: Fix Issue#220; restore VNC port number to 5900 (#_translated_label__243_en)
- bootstrap: Solve the problem of not being able to directly use the one-click initialization script for installation when using zsh to build DragonOS (#_translated_label__252_en)
## Update Content - Software Porting
None
## Source Code and Release Image Download
&emsp;&emsp;You can obtain the source code through the following ways:
### Get via Git
- You can visit [https://github.com/DragonOS-Community/DragonOS/releases](https://github.com/DragonOS-Community/DragonOS/releases) to download the release code and the compiled, runnable disk image.
- We also have a mirror repository on gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To solve the problem of slow and unstable access to GitHub in China, and to make it convenient for developers to download the code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can get the compressed package of DragonOS code and the compiled, runnable disk image through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://mirrors.DragonOS.org.cn](https://mirrors.DragonOS.org.cn)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the source code of DragonOS and the corresponding software products (including but not limited to binary copies and documents) can enjoy the rights granted by us through the GPLv2 license, and you must also comply with the obligations stipulated in the agreement.
This is a rather strict license that protects the healthy development of open source software and prevents it from being encroached upon.
For most well-intentioned people, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others or violate the GPLv2 license.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source use and any acts of plagiarism or academic misconduct**, will be subject to serious accountability. (This is the most common scenario where the open source license is violated.)
Also, please note that according to the requirements of the GPLv2 license, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 license and must indicate that it is based on DragonOS. It is also necessary to ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must make it possible for the developers of DragonOS to obtain the source code of your modified version through the same way from public channels, otherwise you will violate the GPLv2 license.
For detailed information about the license, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 license, **only the English original version has legal effect**. Any translated version is for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, some open source projects' designs were referenced, or parts of their code were introduced, or they were inspired by them. The following list shows them. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - "A Design and Implementation of a 64-bit Operating System" by Tian Yu; People's Posts and Telecommunications Press
- chcore - "Modern Operating Systems: Design and Implementation" by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
- redox - https://gitlab.redox-os.org/redox-os/redox - MIT
## All Commit Records of the Current Version
```text
commit e0de0fd6a52199753a3127cfbb5d12f0a1555aae
Author: TingHuang <92705854+TingSHub@users.noreply.github.com>
Date: Sun Apr 23 22:55:57 2023 +0800
根据sysfs完善设备驱动模型 & 添加sysfs官方文档 (#254)
* 根据sysfs完善设备驱动模型
* 添加sysfs官方文档
commit f678331a3315b7847f08ab32b42d5bf49a9f3a6a
Author: hanjiezhou <zhouhanjie@dragonos.org>
Date: Sun Apr 23 21:05:10 2023 +0800
匿名管道重构&增加IrqArch trait以及IrqFlags及其守卫 (#253)
* 实现匿名管道
* 增加IrqArch trait以及IrqFlags及其守卫
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 8a1e95abb5e4df5e872bb452efc26c9e9631157d
Author: Bullet <93781792+GP-Bullet@users.noreply.github.com>
Date: Fri Apr 21 23:36:54 2023 +0800
解决使用zsh在构建DragonOS时，无法直接使用一键初始化脚本进行安装的问题 (#252)
commit dd9f1fc1a42406461e6f0d38cce1e56e22a1a15f
Author: TingHuang <92705854+TingSHub@users.noreply.github.com>
Date: Fri Apr 21 16:03:42 2023 +0800
新增SysFS (#250)
* 添加sysfs
* 注册sysfs
* 添加sysfs相关
* 添加rust-anlyzer辅助配置
* 将设备与sysfs相关联
* 添加单独的文件管理sysfs下的文件夹
commit cde5492f725681ed89abe1e6eb088e05d943d793
Author: login <longjin@DragonOS.org>
Date: Wed Apr 19 18:05:02 2023 +0800
新增网络socket的系统调用接口 (#247)
1.修复spinlock忘记恢复rflags的问题
2.WaitQueue增加wakeup_all的功能
3.完善tcp,udp,raw socket
4.把PollStatus结构体改为使用bitflags
5.新增iovec结构体
6.完成网络的系统调用
7.在bootstrap里面添加dnsmasq bridge-utils iptables
---------
Co-authored-by: guanjinquan <1666320330@qq.com>
commit 8fd71f277271ae68e648f290c67f187b030feae0
Author: houmkh <1119644616@qq.com>
Date: Mon Apr 17 17:17:06 2023 +0800
增加定时器和软中断文档，修改了softirq面向c的接口 (#245)
* 增加定时器和软中断文档
* 修改softirq对c的接口和文档
* 修改文档格式
commit 77c928f6ce3192c79ea42ab7bcba2713e289f73b
Author: login <longjin@DragonOS.org>
Date: Sun Apr 16 20:29:04 2023 +0800
new: DowncastArc and its docs (#244)
commit 7149abaa49a4ca70f0e42ad3b61fdfd6a941a092
Author: HoshuChiu <129569557+HoshuChiu@users.noreply.github.com>
Date: Sun Apr 16 14:47:51 2023 +0800
修复Issue#220；vnc的端口号恢复5900 (#243)
* 修复Issue#220
* qemu-vnc端口号恢复为5900
commit 5c1e552cc7f0a6ad75c8a1fa2928e3b9cc619657
Author: YJwu2023 <yujianwu2019@gmail.com>
Date: Fri Apr 14 12:21:08 2023 +0800
修复ecam无法获取MCFG table的问题 (#241)
commit 79a452ce8f27ad9c7283ac0bcf4078ed6fa018d7
Author: houmkh <1119644616@qq.com>
Date: Tue Apr 11 17:05:33 2023 +0800
修改errno,使其与relibc的保持一致 (#234)
修改errno,使其与relibc的保持一致
commit ac48398d3f17f24ff9b5da5e400ce912d05f0ba2
Author: login <longjin@DragonOS.org>
Date: Tue Apr 11 16:54:14 2023 +0800
调整brk系统调用，使得参数、返回值与Linux一致 (#238)
* 新增用于测试relibc的app
* 为适配relibc,修改do_execve中关于用户栈的内容的设置
* 调整brk系统调用，使得参数、返回值与Linux一致
commit 13776c114b15c406b1e0aaeeb71812ea6e471d2e
Author: login <longjin@DragonOS.org>
Date: Mon Apr 10 20:22:39 2023 +0800
增加对dhcpv4的支持（tcp、udp socket已写好，但由于缺少epoll机制，尚未完整测试） (#237)
* 为virtio网卡完成smoltcp的phy层配置
* raw socket
* 初步写完udp和tcp socket
* 能够正常通过dhcp获取ipv4地址（具有全局iface btree)
---------
Co-authored-by: guanjinquan <1666320330@qq.com>
commit 78bf93f02f84bf5e024ddfb559f040e68ce39ccf
Author: YJwu2023 <yujianwu2019@gmail.com>
Date: Sun Apr 9 12:30:02 2023 +0800
pci重构+pcie支持 (#235)
* pci重构+pcie支持
* pci重构测试完成
* 修正makefile的问题
* 小修改
* 修改函数名字
commit 5c9a63df836eedaca33c8c4c600b7aaeb2caf9a6
Author: login <longjin@DragonOS.org>
Date: Sat Apr 8 23:53:53 2023 +0800
Patch add lazy init (#236)
* 修正并发安全问题
commit 766127209ee49465a8086cfd0bec90d8b79a96c0
Author: login <longjin@DragonOS.org>
Date: Thu Apr 6 19:01:30 2023 +0800
new: lazy_init (#230)
commit e0dfd4d5d70d1b50fc7ad3ed4bf84b7ba6dad19d
Author: hanjiezhou <zhouhanjie@dragonos.org>
Date: Thu Apr 6 00:50:14 2023 +0800
修改CFSqueue从Vec变成红黑树 (#229)
使用了由tickbh编写的rbtree： https://github.com/tickbh/rbtree-rs/blob/master/src/lib.rs
Co-authored-by: tickbh <tickdream125@hotmail.com>
commit 2a7d773d3d39f1cb3d59d6baa817c896c6fd52d1
Author: TingHuang <92705854+TingSHub@users.noreply.github.com>
Date: Wed Apr 5 13:02:05 2023 +0800
新增设备驱动模型，为设备和驱动提供高层视图 (#227)
* 添加base mod
* 添加设备驱动模型相关文件
* 删除单独的mod文件，使用mod.rs，修改一些格式上的问题
* 移动驱动错误类型到该文件
* 修改一些格式上的问题
commit 5d00b1852818dd4b25952fd6a30deb20e7c7df53
Author: login <longjin@DragonOS.org>
Date: Wed Apr 5 00:53:35 2023 +0800
修复显示刷新线程的空指针问题 (#228)
```

570
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.8.md Normal file
View File

@ -0,0 +1,570 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/V0.1.x/V0.1.8.md
- Translation time: 2025-05-19 01:43:47
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# V0.1.8
:::{note}
Author: Long Jin <longjin@DragonOS.org>
August 16, 2023
:::
## Contributors
The DragonOS V0.1.8 version was contributed by the following developers:
- Long Jin <longjin@DragonOS.org>
- Hou Jiaying <houjiaying@DragonOS.org>
- Wu Yujian <wuyujian@DragonOS.org>
- Huang Ting <huangting@DragonOS.org>
- Kong Weichao <kongweichao@DragonOS.org>
- Cai Jiaxin <caijiaxin@DragonOS.org>
- Chi Kejin <chikejhian@DragonOS.org>
- zhaoyao73 <dragonlinux@gmail.com>
- Zhou Hanjie <zhouhanjie@DragonOS.org>
- Bullet <93781792+GP-Bullet@users.noreply.github.com>
- Sakura Momoka <89176634+TihayaKousaka@users.noreply.github.com>
- Tptogiar <2528891112@qq.com>
## Sponsors
Thank you to the following contributors for their support. We will continue to work hard!
- Wan Xiaolan
- David Wen
- [Seele.Clover](https://github.com/seeleclover)
- [FindWangHao](https://github.com/FindWangHao)
- [ferchiel](https://github.com/ferchiel)
- Ye Jinyi
- Lin
- Albert
- [TerryLeeSCUT · GitHub](https://github.com/TerryLeeSCUT)
- slientbard
- Wu
- Anonymous enthusiastic person
## Update Content - Kernel
### New Features
- refactor: Refactor system call module (#_translated_label__267_en)
- feature: Add AlignBox and int_like macros (#_translated_label__272_en)
- refactor: Rewrite new IPI function & kick_cpu function (#_translated_label__274_en)
- feature: Implement gettimeofday() system call and clocksource+timekeeping sub-module (#_translated_label__278_en)
- refactor: Reconstruct PCI device interrupts and remove USB-related code (#_translated_label__285_en)
- feature: Register serial device, create character device framework (#_translated_label__290_en)
- refactor: New memory management module (#_translated_label__303_en)
- feature: New binary loader, elf parser (#_translated_label__303_en)
- feature: Add ListenTable to detect port occupation (#_translated_label__291_en)
- feature: Replace local_irq_save with IrqFlagsGuard implementation (#_translated_label__317_en)
- feature: Implement system call Fstat (#_translated_label__295_en)
- feature: Implement kernel notifier chain (#_translated_label__316_en)
- feature: Add fcntl system call (#_translated_label__323_en)
- feature: Add support for per CPU variables (#_translated_label__327_en)
- feature: Spinlock guard adds leak, spinlock adds force unlock function (#_translated_label__329_en)
### Bug Fixes
- bugfix: Fix the issue of not being able to read stdin normally (#_translated_label__264_en)
- bugfix: Fix the memory overflow problem when the buffer address passed to the AHCI driver is a user buffer (temporarily solved by allocating a kernel buffer) (#_translated_label__265_en)
- bugfix: Solve the bug caused by the improper assembly of local_irq_save and local_irq_restore functions affecting stack behavior (#_translated_label__303_en)
- bugfix: Solve the error of local_irq_save not disabling interrupts (#_translated_label__303_en)
- bugfix: Solve the error in arch_try_cmpxchg for pointer handling (#_translated_label__307_en)
- bugfix: Fix the exception error in wait4 (#_translated_label__312_en)
- bugfix: Fix the issue of null device and zero device not being able to open and not behaving as expected (#_translated_label__314_en)
- bugfix: Fix the bug in FAT file system not correctly extending file size (#_translated_label__323_en)
- bugfix: Fix the use after free issue caused by not using ManuallyDrop in some places of rwlock (#_translated_label__329_en)
## Update Content - User Environment
### New Features
- feature: Add new HTTP server (#_translated_label__265_en)
### Bug Fixes
- bugfix: Solve the issue of the init segment linking error caused by crt*.o not being sorted in ascending order during linking (#_translated_label__265_en)
## Update Content - Others
- bugfix: Fix the toolchain and resolve errors caused by the new Rust compiler (#_translated_label__258_en)
- feature: Makefile: Add make help command in the root directory (#_translated_label__271_en)
- doc: Update GitHub issue template (#_translated_label__277_en)
- bugfix: Fix the issue where the relibc header file could not recognize the __dragonos__ definition (#_translated_label__315_en)
- feature: Set the remote for the kernel and relibc to the DragonOS Git mirror site to prevent compilation failure due to domestic network issues (#_translated_label__318_en)
- feature: Automatic installation and update of dadk (#_translated_label__319_en)
## Update Content - Software Porting
- feature: Ported sqlite3 (#_translated_label__323_en)
## Source Code and Release Mirror Download
&emsp;&emsp;You can obtain the source code through the following methods:
### Get via Git
- You can visit [https://github.com/DragonOS-Community/DragonOS/releases](https://github.com/DragonOS-Community/DragonOS/releases) to download the source code of the release version, as well as the compiled and runnable disk image.
- We also have a mirror repository on Gitee for download: [https://gitee.com/DragonOS/DragonOS](https://gitee.com/DragonOS/DragonOS)
### Get via DragonOS Software Mirror Site
&emsp;&emsp;To address the slow and unstable access to GitHub in China, and to make it convenient for developers to download the source code of each version of DragonOS, we have specially set up a mirror site. You can access the mirror site through the following address:
&emsp;&emsp;You can obtain the source code package and the compiled and runnable disk image of DragonOS through the mirror site.
- [https://mirrors.DragonOS.org](https://mirrors.DragonOS.org)
- [https://git.mirrors.DragonOS.org](https://git.mirrors.DragonOS.org)
- Domestic mirror acceleration: [https://mirrors.ringotek.cn/](https://mirrors.ringotek.cn/)
## Open Source Declaration
:::{note}
To promote the healthy development of the DragonOS project, DragonOS is released under the GPLv2 open source license. Anyone who can obtain the source code of DragonOS and the corresponding software products (including but not limited to binary copies and documentation) will enjoy the rights granted by us through the GPLv2 license, and you must also comply with the obligations stipulated in the license.
This is a very strict license that protects the healthy development of open source software and prevents it from being infringed.
For most people with good intentions, you will not violate our open source license.
We encourage the free dissemination and promotion of DragonOS, but please ensure that all actions do not infringe on the legitimate rights and interests of others and do not violate the GPLv2 license.
Please pay special attention to the fact that violations of the open source license, especially **commercial closed-source use and any plagiarism or academic misconduct**, will be subject to serious accountability. (This is the easiest scenario to violate our open source license.)
Also, please note that according to the requirements of the GPLv2 license, any software modified or developed based on DragonOS must also be open-sourced under the GPLv2 license and must indicate that it is based on DragonOS. It must also ensure that users of these modified versions can easily obtain the original version of DragonOS.
You must ensure that the developers of DragonOS can obtain the source code of your modified version through the same way from public channels. Otherwise, you will violate the GPLv2 license.
For detailed information about the license, please read the **LICENSE** file in the root directory of the project. Please note that according to the requirements of the GPLv2 license, **only the English original version has legal effect**. Any translated version is for reference only.
:::
### Usage of Open Source Software
&emsp;&emsp;During the development of DragonOS, some open source projects were referenced, or parts of their code were introduced, or they were inspired by them. The following list shows them. We sincerely thank the contributors of these open source projects!
Format: <Project Name> - <Link> - <Open Source License>
- Linux - https://git.kernel.org/ - GPLv2
- skiftOS - https://github.com/skiftOS/skift - MIT
- FYSOS - https://github.com/fysnet/FYSOS - [FYSOS' License](https://github.com/fysnet/FYSOS/blob/9a8968e3d6600de34539c028c843f4c06d134039/license.txt)
- LemonOS - https://github.com/LemonOSProject/LemonOS.git - BSD 2-Clause License
- LZ4 - https://github.com/lz4/lz4 - BSD 2-Clause license
- SerenityOS - https://github.com/SerenityOS/serenity.git - BSD 2-Clause license
- MINE - 《A Design and Implementation of a 64-bit Operating System》 by Tian Yu; People's Posts and Telecommunications Press
- chcore - 《Modern Operating Systems: Design and Implementation》 by Chen Haibo, Xia Yubin; Machinery Industry Press
- SimpleKernel - https://github.com/Simple-XX/SimpleKernel - MIT
- rcore-fs - https://github.com/rcore-os/rcore-fs.git - MIT
- redox - https://gitlab.redox-os.org/redox-os/redox - MIT
## All Commit Records of the Current Version
```text
commit 40176b1c6603d487b7eb66fb81e641f0932ab90a
Author: longjin <longjin@RinGoTek.cn>
Date: Tue Aug 15 15:06:57 2023 +0000
删除无用代码,并把about app的版本号更新为0.1.8
commit 67b481888770c6469f572f244a4f97e42da77d1f
Author: houmkh <1119644616@qq.com>
Date: Mon Aug 14 12:18:46 2023 +0800
移动fstat (#330)
* 移动fstat
commit 90a0a49048fdaf5e31320d0c87f8bed8db1bd882
Author: LoGin <longjin@DragonOS.org>
Date: Mon Aug 14 01:24:49 2023 +0800
修正rwlock有的地方由于未使用ManuallyDrop导致的use after free && spinlock守卫新增leak,spinlock新增force unlock功能.(#329)
1.修正rwlock有的地方由于未使用ManuallyDrop导致的use after free
2. spinlock守卫新增leak,spinlock新增force unlock功能.
commit c3dad0011d331d782670e14723aa48e98fbac787
Author: LoGin <longjin@DragonOS.org>
Date: Sun Aug 13 16:28:24 2023 +0800
添加per cpu变量支持 (#327)
commit 42c97fa7f4fee7eeefeda5d2b7ed14f598a58493
Author: LoGin <longjin@DragonOS.org>
Date: Tue Aug 8 23:45:04 2023 +0800
删除旧的libELF (#324)
commit 6d81180b3b7328466b976b69c5f7782aa66d8a89
Author: LoGin <longjin@DragonOS.org>
Date: Tue Aug 8 23:39:22 2023 +0800
移植sqlite3,并修复一些bug (#323)
* bugfix: 程序加载器映射内存时，计算要映射的大小不正确的问题。
* 修正brk系统调用不符合规范的地方
* bugfix: 修正fat文件系统未能正确的扩展文件大小的bug
* 增加fcntl系统调用
* 移植sqlite3
commit 26887c6334cdca2d13ad71dec27fb69faa0a57be
Author: LoGin <longjin@DragonOS.org>
Date: Mon Aug 7 01:38:52 2023 +0800
bugfix: 解决取消低地址映射时，错误的把重映射的物理页释放，从而导致的use after free问题。 (#321)
commit 729a96ef47f473d535d8317a2ace5ba141fd282a
Author: Xshine <gshine@m.scnu.edu.cn>
Date: Sun Aug 6 12:53:47 2023 +0800
实现内核通知链 notifier chain (#316)
* 实现通知链块结构
* 实现通知链的基本功能
* 实现 atomic notifier chain
* 实现 blocking notifier chain
* 使用 rust 范式完成功能
* 支持回调次数 nr_to_call
* 移动至 libs 目录
* 完善通知链相关方法
* 修正相关格式
* 文档编写
* 更改文档路径
commit be63f3b2b6b472daa3ee17180aa607409cb9d182
Author: houmkh <1119644616@qq.com>
Date: Sat Aug 5 18:52:46 2023 +0800
实现系统调用Fstat (#295)
* fstat
* 修改syscall.rs中的verify_area
commit 9550910ae1de900e0291a84d268e8873fa142902
Author: Chiichen <39649411+Chiichen@users.noreply.github.com>
Date: Sat Aug 5 18:30:55 2023 +0800
替换 local_irq_save 为 IrqFlagsGuard 实现 (#317)
commit abf3f634bf7e13e829556e962e7c73a85d163335
Author: LoGin <longjin@DragonOS.org>
Date: Sat Aug 5 15:30:06 2023 +0800
自动安装、更新dadk (#319)
* auto install/auto update dadk
commit d6fd9c1e8025dd679339f9156477cb7d26d3db0d
Author: LoGin <longjin@DragonOS.org>
Date: Sat Aug 5 15:04:08 2023 +0800
设置内核、relibc的远程为dragonos的git镜像站，防止国内网络问题导致编译失败 (#318)
commit 1a62e7767c1215f9668915b42de770e7993711bf
Author: LoGin <longjin@DragonOS.org>
Date: Wed Aug 2 18:11:05 2023 +0800
解决relibc的头文件没能识别__dragonos__定义的问题 (#315)
commit 06500303303ec14711b4f995e2058e12703f0f2c
Author: LoGin <longjin@DragonOS.org>
Date: Wed Aug 2 17:33:16 2023 +0800
修正null设备以及zero设备无法open、行为不符合预期的问题 (#314)
commit 4da3758acf0327d429dfce3d313b50c2e0fc7723
Author: Chiichen <39649411+Chiichen@users.noreply.github.com>
Date: Wed Aug 2 14:29:59 2023 +0800
修复了wait4的异常报错 (#312)
* 修复了wait4的异常报错
commit 821bb9a2dcfd28f9878d53ba722bdf164cf00f69
Author: Xshine <caijiaxin@dragonos.org>
Date: Fri Jul 28 17:51:05 2023 +0800
增加 ListenTable 来检测端口占用 (#291)
* 增加 ListenTable 来检测端口占用
* 使用Arc封装GlobalSocketHandle
* 删除 listen 处的端口检测逻辑，延至实现端口复用时完成
* 设立两张表，分别记录TCP和UDP的端口占用
* 实现 meatadata 相关逻辑
* 实现socket关闭时，端口在表中移除
* 使用端口管理器重构端口记录表
* 修正与RawSocket相关的端口管理逻辑
* 补充测试文件
* 修正 unbind_port 在逻辑错误
* 修正格式问题
---------
Co-authored-by: longjin <longjin@RinGoTek.cn>
commit 7cc4a02c7ff7bafd798b185beb7b0c2986b9f32f
Author: zhaoyao73 <zhaoyao73@users.noreply.github.com>
Date: Fri Jul 28 03:44:45 2023 -0400
fix arch_try_cmpxchg macro declaration (#307)
fix arch_try_cmpxchg in atomic_cmpxchg
Co-authored-by: Yao Zhao <dragonlinux@gmail.com>
commit a30434f5201ca4c60b9515c8c23444fea3b5a8c6
Author: zhaoyao73 <zhaoyao73@users.noreply.github.com>
Date: Tue Jul 25 10:02:42 2023 -0400
fix some script bugs (#304)
add arch linux prerequisited packages
Co-authored-by: Yao Zhao <dragonlinux@gmail.com>
commit 40fe15e0953f989ccfeb74826d61621d43dea6bb
Author: LoGin <longjin@DragonOS.org>
Date: Sat Jul 22 16:27:02 2023 +0800
新的内存管理模块 (#303)
&emsp;&emsp;实现了具有优秀架构设计的新的内存管理模块，对内核空间和用户空间的内存映射、分配、释放、管理等操作进行了封装，使得内核开发者可以更加方便地进行内存管理。
&emsp;&emsp;内存管理模块主要由以下类型的组件组成：
- **硬件抽象层（MemoryManagementArch）** - 提供对具体处理器架构的抽象，使得内存管理模块可以在不同的处理器架构上运行
- **页面映射器（PageMapper）**- 提供对虚拟地址和物理地址的映射，以及页表的创建、填写、销毁、权限管理等操作。分为两种类型：内核页表映射器（KernelMapper）和用户页表映射器（位于具体的用户地址空间结构中）
- **页面刷新器（PageFlusher）** - 提供对页表的刷新操作（整表刷新、单页刷新、跨核心刷新）
- **页帧分配器（FrameAllocator）** - 提供对页帧的分配、释放、管理等操作。具体来说，包括BumpAllocator、BuddyAllocator
- **小对象分配器** - 提供对小内存对象的分配、释放、管理等操作。指的是内核里面的SlabAllocator （SlabAllocator的实现目前还没有完成）
- **MMIO空间管理器** - 提供对MMIO地址空间的分配、管理操作。（目前这个模块待进一步重构）
- **用户地址空间管理机制** - 提供对用户地址空间的管理。
- VMA机制 - 提供对用户地址空间的管理，包括VMA的创建、销毁、权限管理等操作
- 用户映射管理 - 与VMA机制共同作用，管理用户地址空间的映射
- **系统调用层** - 提供对用户空间的内存管理系统调用，包括mmap、munmap、mprotect、mremap等
- **C接口兼容层** - 提供对原有的C代码的接口，是的C代码能够正常运行。
除上面的新增内容以外，其它的更改内容：
- 新增二进制加载器，以及elf的解析器
- 解决由于local_irq_save、local_irq_restore函数的汇编不规范导致影响栈行为的bug。
- 解决local_irq_save未关中断的错误。
- 修复sys_gettimeofday对timezone参数的处理的bug
---------
Co-authored-by: kong <kongweichao@dragonos.org>
commit bb5f098a864cee36b7d2c1ab9c029c0280d94a8a
Author: LoGin <longjin@DragonOS.org>
Date: Sat Jul 22 16:24:55 2023 +0800
Revert "新的内存管理模块 (#301)" (#302)
This reverts commit d8ad0a5e7724469abd5cc3cf271993538878033e.
commit d8ad0a5e7724469abd5cc3cf271993538878033e
Author: LoGin <longjin@DragonOS.org>
Date: Sat Jul 22 16:22:17 2023 +0800
新的内存管理模块 (#301)
&emsp;&emsp;实现了具有优秀架构设计的新的内存管理模块，对内核空间和用户空间的内存映射、分配、释放、管理等操作进行了封装，使得内核开发者可以更加方便地进行内存管理。
&emsp;&emsp;内存管理模块主要由以下类型的组件组成：
- **硬件抽象层（MemoryManagementArch）** - 提供对具体处理器架构的抽象，使得内存管理模块可以在不同的处理器架构上运行
- **页面映射器（PageMapper）**- 提供对虚拟地址和物理地址的映射，以及页表的创建、填写、销毁、权限管理等操作。分为两种类型：内核页表映射器（KernelMapper）和用户页表映射器（位于具体的用户地址空间结构中）
- **页面刷新器（PageFlusher）** - 提供对页表的刷新操作（整表刷新、单页刷新、跨核心刷新）
- **页帧分配器（FrameAllocator）** - 提供对页帧的分配、释放、管理等操作。具体来说，包括BumpAllocator、BuddyAllocator
- **小对象分配器** - 提供对小内存对象的分配、释放、管理等操作。指的是内核里面的SlabAllocator （SlabAllocator的实现目前还没有完成）
- **MMIO空间管理器** - 提供对MMIO地址空间的分配、管理操作。（目前这个模块待进一步重构）
- **用户地址空间管理机制** - 提供对用户地址空间的管理。
- VMA机制 - 提供对用户地址空间的管理，包括VMA的创建、销毁、权限管理等操作
- 用户映射管理 - 与VMA机制共同作用，管理用户地址空间的映射
- **系统调用层** - 提供对用户空间的内存管理系统调用，包括mmap、munmap、mprotect、mremap等
- **C接口兼容层** - 提供对原有的C代码的接口，是的C代码能够正常运行。
除上面的新增内容以外，其它的更改内容：
- 新增二进制加载器，以及elf的解析器
- 解决由于local_irq_save、local_irq_restore函数的汇编不规范导致影响栈行为的bug。
- 解决local_irq_save未关中断的错误。
- 修复sys_gettimeofday对timezone参数的处理的bug
commit 0663027b111ffb6ff93becd60ffef1e2b8fbd4c6
Author: TingHuang <92705854+TingSHub@users.noreply.github.com>
Date: Wed Jul 12 12:49:45 2023 +0800
注册串口设备，创建字符设备框架(#290)
* 按照rust规范修改两个函数名称
* 修改一些函数句柄以符合rust规范
* 添加字符设备相关
* 添加字符设备相关文件
* 添加字符设备驱动框架代码
* 将串口注册
* 规范代码
commit cc36cf4a186be834e6c2ab857b9b9501ddb8b1eb
Author: YJwu2023 <yujianwu2019@gmail.com>
Date: Sat Jul 8 17:22:42 2023 +0800
PCI设备中断重构，删去USB相关代码 (#285)
* 修复ecam无法获取MCFG table的问题
* 完善pcie
* 完善irq的错误检测机制
commit 2311e2f30048d09250afc3e2e4e7029627996655
Author: 櫻井桃華 <89176634+TihayaKousaka@users.noreply.github.com>
Date: Fri Jul 7 22:50:46 2023 +0800
修改makefile通过编译 (#287)
commit 36fd013004ee0bd5fc7cfb452ba22531a83a859c
Author: houmkh <1119644616@qq.com>
Date: Sat Jun 17 22:48:15 2023 +0800
实现gettimeofday()系统调用和clocksource+timekeeping子模块 (#278)
- 实现gettimeofday()系统调用
- 实现clocksource+timekeeping子模块部分功能
- 实现了timespec转换成日期时间
commit a55ac7b928a6ca08483bbb3355bea55f1446ccab
Author: LoGin <longjin@DragonOS.org>
Date: Tue Jun 6 17:44:54 2023 +0800
Update issue templates (#277)
commit 5f57834372f6cb720ba14103effa4799e195a963
Author: Tptogiar <2528891112@qq.com>
Date: Tue Jun 6 16:41:02 2023 +0800
Makefile: 根目录下添加make help命令 (#271)
* Makefile: 根目录下添加make help命令
* Makefile: 补充根目录Makefile的help命令
commit aa0367d69e15989684109c5b454e85da9ecb1975
Author: LoGin <longjin@DragonOS.org>
Date: Tue May 30 10:21:11 2023 +0800
新的ipi功能&kick_cpu功能的重写 (#274)
commit bb24249faabc5006784aa98ca17b4cbdcb788c65
Author: LoGin <longjin@DragonOS.org>
Date: Sun May 28 23:00:37 2023 +0800
添加AlignBox和int_like宏 (#272)
commit ab5c8ca46db8e7d4793a9791292122b0b9684274
Author: login <longjin@DragonOS.org>
Date: Wed May 24 17:05:33 2023 +0800
重构系统调用模块 (#267)
* 完成系统调用模块重构
* 更新github workflow
commit 660a04cef803fd73e9b294b30a96421b021a4b9b
Author: login <longjin@DragonOS.org>
Date: Sat May 13 21:17:12 2023 +0800
新增http server (#265)
* 1.修复了当传入ahci驱动的缓冲区地址为用户缓冲区时,产生的内存越界问题.(采用分配内核缓冲区的方式临时解决)
2.新增http server
* 把libssl-dev添加到bootstrap.sh
* http_server增加对父级相对路径的安全检查，防止访问系统内的其他文件
* 检查空指针情况
* 解决由于链接时，crt*.o未按照升序排列导致init段链接错误的问题
commit 49249f4ec94fad7baf923aed68d9a7b2da3de3d4
Author: Bullet <93781792+GP-Bullet@users.noreply.github.com>
Date: Sat May 13 09:55:24 2023 +0800
把调度器实例的裸指针改为Option (#262)
commit bfafc102798ab1968ccf6b04315d8d3359a70ca8
Author: login <longjin@DragonOS.org>
Date: Thu May 11 17:41:42 2023 +0800
修复读取stdin时，无法正常读取的问题。 (#264)
commit 7285c927d95bb4b5c692c51a8f86c47009d07667
Author: login <longjin@DragonOS.org>
Date: Thu May 11 16:17:58 2023 +0800
添加dadk支持 (#263)
* 引入dadk，使用dadk0.1.1来编译test-relibc程序
* 由于gitee仓库体积限制导致无法继续使用gitee上的rust索引，因此更换为清华源
* github workflow的环境中，安装dadk
* Auto configure dragonos rust toolchain
commit b11bb1b25676f528ec1b0e1da0af82b4652f70c4
Author: login <longjin@DragonOS.org>
Date: Sun May 7 22:20:33 2023 +0800
固定编译工具链、修复由于新版rust编译器问题导致的报错。 (#258)
* 固定编译工具链、修复由于新版rust编译器问题导致的报错。
* 完善github workflow环境配置
```

2326
docs/locales/en/community/ChangeLog/V0.1.x/V0.1.9.md Normal file
View File

File diff suppressed because it is too large Load Diff

32
docs/locales/en/community/ChangeLog/index.rst Normal file
View File

@ -0,0 +1,32 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/ChangeLog/index.rst
- Translation time: 2025-05-19 01:41:22
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Release Notes
=====================
This is the release log for DragonOS, which records the update content of every version of DragonOS.
.. toctree::
:maxdepth: 1
V0.1.x/V0.1.10
V0.1.x/V0.1.9
V0.1.x/V0.1.8
V0.1.x/V0.1.7
V0.1.x/V0.1.6
V0.1.x/V0.1.5
V0.1.x/V0.1.4
V0.1.x/V0.1.3
V0.1.x/V0.1.2
V0.1.x/V0.1.1
V0.1.x/V0.1.0

173
docs/locales/en/community/code_contribution/c-coding-style.md Normal file
View File

@ -0,0 +1,173 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/code_contribution/c-coding-style.md
- Translation time: 2025-05-19 01:42:01
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# C Language Code Style
&emsp;&emsp;This document will briefly introduce the C language code style used in DragonOS. It is completely normal for each person to have their own code style. However, for the maintainability of an open-source project, we hope to establish some code standards so that every developer, including you, can feel more comfortable when reading the code. A project filled with various code styles is difficult to maintain.
&emsp;&emsp;We propose some recommendations here, and we hope you will follow them as much as possible. These recommendations are similar to those of Linux, but with some differences. DragonOS uses Linux's style for variable naming; for indentation, DragonOS uses Microsoft's style.
## 0. Code Formatter
&emsp;&emsp;Before we present the following recommendations, we recommend that you use the `C/C++ Extension Pack` plugin in Visual Studio Code as a code formatter during development. These plugins provide good auto-formatting functionality, ensuring that your code's basic format meets DragonOS's requirements.
&emsp;&emsp;Pressing `Ctrl+shift+I` or your set code formatting shortcut frequently while coding can help you maintain good code formatting consistently.
## 1. Indentation
&emsp;&emsp;The width of a tab is equal to 4 spaces. Code indentation is based on the tab width (usually 4 characters in most editors).
&emsp;&emsp;This makes your code more readable and helps better identify the control structures in the code. This can avoid many unnecessary troubles!
For example: In a switch statement, place the switch and case on the same indentation level. And indent each case's code by one tab to the right. This improves code readability.
```c
switch (cmd)
{
case AHCI_CMD_READ_DMA_EXT:
pack->blk_pak.end_handler = NULL;
pack->blk_pak.cmd = AHCI_CMD_READ_DMA_EXT;
break;
case AHCI_CMD_WRITE_DMA_EXT:
pack->blk_pak.end_handler = NULL;
pack->blk_pak.cmd = AHCI_CMD_WRITE_DMA_EXT;
break;
default:
pack->blk_pak.end_handler = NULL;
pack->blk_pak.cmd = cmd;
break;
}
```
## 2. Line Breaks
&emsp;&emsp;We recommend that each line should not exceed 120 characters. If it does, unless there is a necessary reason, it should be split into two lines.
&emsp;&emsp;When breaking lines, we need to indent the second line by one level from the first line's starting part to indicate that it is a sub-line. Using the code formatting shortcut can quickly accomplish this.
&emsp;&emsp;For log strings, we do not recommend breaking them into multiple lines for easier retrieval.
&emsp;&emsp;For code line breaks, do not try to place several statements on the same line, as this provides no benefit to code readability:
```c
// 错误示范(1)
if(a) return 1;
// 错误示范(2)
if(b)
do_a(),do_b();
```
## 3. Braces and Spaces
### 3.1 Braces
&emsp;&emsp;The placement of braces is a matter of personal preference, mainly due to habit rather than technical reasons. We recommend placing the opening and closing braces on new lines, as shown below:
```c
while(i<10)
{
++i;
}
```
&emsp;&emsp;This rule applies to all code blocks.
&emsp;&emsp;The reason for this choice is that, in some editors, placing the braces in this way will result in **a semi-transparent vertical line appearing in the editor, with the line ends being the braces**. This helps developers better understand the hierarchical relationships of the code blocks.
Let's demonstrate this with some examples:
&emsp;&emsp;In the following code block, we need to note that the `else if` statement should be on a new line, not after the previous `}`. This is because we require `{` to be at the start of each line and maintain the indentation level.
```c
if (*fmt == '*')
{
++fmt;
}
else if (is_digit(*fmt))
{
field_width = skip_and_atoi(&fmt);
}
```
&emsp;&emsp;When there are multiple simple statements in a loop, braces should be used.
```c
while (condition)
{
if (test)
do_something();
}
```
&emsp;&emsp;When there is only one simple statement, we do not need to use braces.
```c
if(a)
return 1;
```
### 3.2 Spaces
&emsp;&emsp;For most keywords, we need to add a space after them to improve code readability.
&emsp;&emsp;Please add a space after all of these keywords:
```c
if, switch, case, for, do, while
```
&emsp;&emsp;Keywords such as sizeof, typeof, alignof, and __attribute__ do not require a space after them, as they are used like functions.
&emsp;&emsp;For pointer-type variables, the asterisk should be close to the variable name rather than the type name. As shown below:
```c
char *a;
void *func(char* s, int **p);
```
&emsp;&emsp;Use a space on both sides of most binary and ternary operators, as shown below:
```c
= + - < > * / % | & ^ <= >= == != ? :
```
&emsp;&emsp;There is no space after these unary operators:
```c
& * + - ~ ! sizeof typeof alignof __attribute__ defined
```
&emsp;&emsp;Special cases: no space is needed before or after the following operators:
```c
++ -- . ->
```
## 4. Naming
&emsp;&emsp;DragonOS does not use the camelCase naming convention for function names, but instead uses concise and clear names like `tmp`.
&emsp;&emsp;Note that this refers to our entire project not using the camelCase naming convention. It does not mean that programmers can use obscure abbreviations for variable names.
&emsp;&emsp;For global variables or globally visible functions and structures, we need to follow the following naming conventions:
- The name should be easy to understand and not ambiguous. For example, for a function that calculates folder size, we recommend using `count_folder_size()` instead of `cntfs()`, which can confuse others.
- For global, non-static names, unless there is a special need, the naming should follow the format: `模块名缩写前缀_函数/变量名`. This naming convention helps others distinguish which module the name belongs to and reduces the risk of naming conflicts.
- Global names that do not need to be visible to other code files must be prefixed with the `static` modifier.
&emsp;&emsp;For local variables within functions, the naming convention should be concise. Long names for local variables have little significance.
[Document not completed, to be continued]

62
docs/locales/en/community/code_contribution/conventional-commit.md Normal file
View File

@ -0,0 +1,62 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/code_contribution/conventional-commit.md
- Translation time: 2025-05-19 01:41:57
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Code Commit Guidelines
&emsp;&emsp;This document will briefly introduce the code commit guidelines for the DragonOS GitHub repository, mainly providing the naming conventions based on Conventional Commit, as well as a brief introduction to the DragonOS Bot.
## Conventional Commit (Conventional Commit)
&emsp;&emsp;For detailed specifications on Conventional Commit, please refer to the website [Conventional Commit/Conventional Commit](https://www.conventionalcommits.org/zh-hans/v1.0.0/). At the end of this section, we will provide examples (taken from the [Conventional Commit/Conventional Commit](https://www.conventionalcommits.org/zh-hans/v1.0.0/) website), which are optional to read. We make the following special notes:
1. Since the DragonOS kernel ensures external usability primarily through system call interfaces, and up to now (April 22, 2024), considering the software ecosystem, DragonOS has chosen to implement system calls consistent with Linux. Therefore, there is no special explanation for `破坏性变更(BREAKING CHANGES)`, or in the current development environment, there will not be any destructive changes that significantly affect users. Therefore, unless there is a special need, the DragonOS kernel should not use `feat!` to indicate destructive changes. (Outside the kernel, such as dadk, the guidelines still apply.)
2. The DragonOS community strictly follows a squash-based workflow, so we do not require each individual commit in a PR to conform to [Conventional Commit/Conventional Commit](https://www.conventionalcommits.org/zh-hans/v1.0.0/). However, we still strongly recommend using it.
3. Regarding scope: If not specified otherwise, the scope should be the name of the submodule/system/directory. For example, if the code change is adding a feature in `kernel/src/driver/net`, it should be named as `feat(driver/net):`; if it is in `kernel/src/mm/allocator`, it should be named as `feat(mm)`. In short, the scope should be as short as possible to indicate the module it belongs to. Most of the time, it should not use more than two levels of scope identifiers. For example, `fix(x86_64/driver/apic)` is incorrect and should be named as `fix(x86_64/apic)`.
4. In the DragonOS kernel code repository, `issue checker` will perform a simple review of the title format. If it does not conform to the format, it will be marked as `ambiguous`. Contributors are advised to modify it as needed.
5. Use lowercase.
### Examples
#### Commit message with a description and a footnote indicating a breaking change
```
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
```
#### Commit message with the ! character to alert about a breaking change
```
feat!: send an email to the customer when a product is shipped
```
#### Commit message with scope and a breaking change !
```
feat(api)!: send an email to the customer when a product is shipped
```
#### Commit message with ! and BREAKING CHANGE footnote
```
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
```
#### Commit message without a body
```
docs: correct spelling of CHANGELOG
```
#### Commit message with scope
```
feat(lang): add polish language
```
## DragonOS Bot
&emsp;&emsp;DragonOS uses triagebot to implement automatic labeling and reviewer assignment. Contributors can also interact with triagebot through some commands. For more details, see [triagebot](https://forge.rust-lang.org/triagebot/index.html)

29
docs/locales/en/community/code_contribution/index.rst Normal file
View File

@ -0,0 +1,29 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/code_contribution/index.rst
- Translation time: 2025-05-19 01:41:37
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Contributing to Development
====================================
DragonOS community warmly welcomes your participation! While learning technology is important, the following documents will help you understand what DragonOS community needs.
Reading these documents will help you get involved in development and make your code merge into the mainline more quickly.
.. toctree::
:maxdepth: 1
how-to-contribute <https://community.dragonos.org/contributors/>
c-coding-style
rust-coding-style
conventional-commit

107
docs/locales/en/community/code_contribution/rust-coding-style.md Normal file
View File

@ -0,0 +1,107 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/code_contribution/rust-coding-style.md
- Translation time: 2025-05-19 01:41:39
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Rust Language Code Style
&emsp;&emsp;This document will introduce the Rust language code style used in DragonOS. As development progresses, these styles may change, but we will strive to maintain consistency in the style.
## 1. Naming
&emsp;&emsp;This section is based on the naming conventions from the Rust language bible, [Naming Guide](https://course.rs/practice/naming.html). For parts not mentioned in this document, please refer to the [Naming Guide](https://course.rs/practice/naming.html) in the Rust language bible.
## 2. Formatting
### 2.1 Indentation
&emsp;&emsp;Please use the `cargo fmt` command to format the code before submitting it.
### 2.2 Function Return Values
&emsp;&emsp;Although Rust allows returning the value of the last line of a function, this approach can reduce code readability. Therefore, we recommend using the `return` statement as the last line of the function, rather than directly returning the value.
```rust
// 不推荐
fn foo() -> i32 {
1 + 2
}
// 推荐
fn foo() -> i32 {
return 1 + 2;
}
```
### 2.3 Error Handling
&emsp;&emsp;DragonOS uses returning POSIX error codes as the **inter-module error handling** method. To ensure consistency in error handling code across modules, we recommend returning the `SystemError` type when an error occurs. This approach is especially beneficial when calling functions across modules, as it allows direct return of a generic error code, thereby reducing the coupling of error handling code.
```rust
// 函数跨越模块边界时（由其他模块调用当前函数），不推荐
fn foo() -> Result<(), CustomErr> {
if 1 + 2 == 3 {
return Ok(());
} else {
return Err(CustomErr::error);
}
}
// 函数跨越模块边界时（由其他模块调用当前函数），推荐
fn foo() -> Result<(), SystemError> {
if 1 + 2 == 3 {
return Ok(());
} else {
return Err(SystemError::EINVAL);
}
}
```
&emsp;&emsp;Within **modules**, you can either use a custom error enum or return the `SystemError` type. However, we recommend using a custom error enum for error handling within modules, as it makes the error handling code clearer.
&emsp;&emsp;**TODO**: Convert existing code that uses i32 as an error code to use `SystemError`.
## 3. Comments
&emsp;&emsp;The commenting style in DragonOS is consistent with the official Rust style. We also recommend adding as many meaningful comments as possible in your code to help others understand your code. Additionally, variable and function declarations should follow the naming conventions mentioned in Section 1, making them "self-documenting."
### 3.1 Function Comments
&emsp;&emsp;Function comments should include the following:
- The function's purpose
- The function's parameters
- The function's return value
- The function's error handling
- Any side effects or other information that needs to be explained
&emsp;&emsp;The format for function comments is as follows:
```rust
/// # 函数的功能
///
/// 函数的详细描述
///
/// ## 参数
///
/// - 参数1: 参数1的说明
/// - 参数2: 参数2的说明
/// - ...
///
/// ## 返回值
/// - Ok(返回值类型): 返回值的说明
/// - Err(错误值类型): 错误的说明
///
/// ## Safety
///
/// 函数的安全性说明
```

45
docs/locales/en/community/contact/index.rst Normal file
View File

@ -0,0 +1,45 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: community/contact/index.rst
- Translation time: 2025-05-19 02:14:46
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
.. _translated_label__get_contact_with_community_en:
Get in Touch with the Community
====================================================================
Contact Information
-------------------------
Community Public Email: contact@DragonOS.org
Community Management Staff Information: https://community.dragonos.org/governance/staff-info.html
Development Discussion QQ Group: 115763565
DragonOS Official Website: https://DragonOS.org
To learn about development updates and tasks, please visit the DragonOS forum: https://bbs.dragonos.org.cn
Sponsorship and Donations
---------------------------------------------------------
DragonOS is an open-source project, and we welcome any form of sponsorship and donations. Your donations will be used for the development and maintenance of DragonOS, as well as the operation of the community.
You can sponsor or donate through the following methods:
- Visit the DragonOS official website at https://DragonOS.org, click the "Sponsor" button in the top right corner, and make a donation.
- Contact the community leader to discuss specific sponsorship methods. Contact information: longjin@dragonos.org
Financial and Donation Transparency
---------------------------------------------------------
The donation information of the DragonOS community will be made public annually. Sponsorship details and sponsor information will be made public within 15 days after receiving the donation.

62
docs/locales/en/index.rst Normal file
View File

@ -0,0 +1,62 @@
English
==========================================
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: index.rst
- Translation time: 2025-05-19 02:12:15
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
.. DragonOS documentation master file, created by
sphinx-quickstart on Fri Jun 17 23:12:00 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. toctree::
:maxdepth: 1
:caption: Getting Started
introduction/index
introduction/build_system
introduction/mirrors
.. toctree::
:maxdepth: 1
:caption: Kernel Layer
kernel/configuration/index
kernel/boot/index
kernel/core_api/index
kernel/locking/index
kernel/process_management/index
kernel/sched/index
kernel/ipc/index
kernel/memory_management/index
kernel/filesystem/index
kernel/debug/index
kernel/ktest/index
kernel/cpu_arch/index
kernel/container/index
kernel/libs/index
kernel/trace/index
kernel/syscall/index
.. toctree::
:maxdepth: 1
:caption: Userland Layer
userland/appdev/index
.. toctree::
:maxdepth: 1
:caption: DragonOS Community
community/code_contribution/index
community/contact/index
community/ChangeLog/index

294
docs/locales/en/introduction/build_system.md Normal file
View File

@ -0,0 +1,294 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/build_system.md
- Translation time: 2025-05-19 01:44:01
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Building DragonOS
## 1. Introduction
&emsp;&emsp;Regardless of which method you use to compile DragonOS in the following sections, you must first follow the steps in this section to initialize your development environment.
&emsp;&emsp;Before you start, you need a computer running Linux or macOS with an X86-64 processor architecture.
&emsp;&emsp;For Linux distributions, it is recommended to use newer distributions such as Ubuntu 22, Debian, or Arch Linux, which can save you a lot of trouble.
### 1.1 Downloading the DragonOS Source Code
Use `https` to clone:
```shell
git clone https://github.com/DragonOS-Community/DragonOS.git
cd DragonOS
# 使用镜像源更新子模块
make update-submodules-by-mirror
```
For convenience in subsequent development, we recommend using `ssh` to clone (please configure your GitHub SSH Key first) to avoid cloning failures due to network issues:
Use `ssh` to clone (please configure your GitHub SSH Key first):
```shell
# 使用ssh克隆
git clone git@github.com:DragonOS-Community/DragonOS.git
cd DragonOS
# 使用镜像源更新子模块
make update-submodules-by-mirror
```
## 2. Installation Using One-Click Initialization Script (Recommended)
&emsp;&emsp;We provide a one-click initialization script that can install everything with a single command. Just run the following command in the terminal:
```shell
cd DragonOS
cd tools
bash bootstrap.sh # 这里请不要加上sudo, 因为需要安装的开发依赖包是安装在用户环境而非全局环境
```
:::{note}
The one-click configuration script currently supports the following systems:
- Ubuntu/Debian/Deepin/UOS and other derivatives based on Debian
- Gentoo, due to the characteristics of the Gentoo system, when Gentoo encounters USE or circular dependency issues, please handle them according to the emerge prompt information. Official dependency handling examples [GentooWiki](https://wiki.gentoo.org/wiki/Handbook:AMD64/Full/Working/zh-cn#.E5.BD.93_Portage_.E6.8A.A5.E9.94.99.E7.9A.84.E6.97.B6.E5.80.99)
We welcome you to improve the build script for other systems!
:::
**If the one-click initialization script runs normally and outputs the final "Congratulations" interface (as shown below), please close the current terminal and then reopen it.**
```shell
|-----------Congratulations!---------------|
| |
| 你成功安装了DragonOS所需的依赖项! |
| |
| 请关闭当前终端, 并重新打开一个终端 |
| 然后通过以下命令运行: |
| |
| make run |
| |
|------------------------------------------|
```
**Then, please directly jump to {ref}`编译命令讲解 <_build_system_command>` for reading!**
## 3. Manual Installation
### 3.1 Dependency List
&emsp;&emsp;If the automatic installation script does not support your operating system, you need to manually install the required packages. The following is the list of dependencies:
&emsp;&emsp;Among the following dependencies, except for `docker-ce` and `Rust及其工具链`, the rest can be installed using the system's built-in package manager. For the installation of Docker and Rust, please refer to the following sections.
- docker-ce
- llvm-dev
- libclang-dev
- clang
- gcc-multilib
- qemu qemu-system qemu-kvm
- build-essential
- fdisk
- lsb-release
- git
- dosfstools
- unzip
- Rust and its toolchain
**Please note that if your Linux system is running in a virtual machine, please make sure to enable the Intel VT-x or AMD-V option in the processor settings of your VMware/Virtual Box virtual machine, otherwise DragonOS will not be able to run.**
:::{note}
*In some Linux distributions, the Qemu built from the software repository may be incompatible with DragonOS due to an outdated version. If you encounter this issue, uninstall Qemu and reinstall it by compiling from source.*
Download the Qemu source code from this address: https://download.qemu.org/
After decompression, enter the source code directory and execute the following command:
```shell
# 安装编译依赖项
sudo apt install -y autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \
gawk build-essential bison flex texinfo gperf libtool patchutils bc \
zlib1g-dev libexpat-dev pkg-config libglib2.0-dev libpixman-1-dev libsdl2-dev \
git tmux python3 python3-pip ninja-build
./configure --enable-kvm
make -j 8
sudo make install
# 编译安装完成
```
Please note that the compiled QEMU will be linked via VNC mode, so you also need to install a VNC viewer on your computer to connect to the QEMU virtual machine.
:::
### 3.2 Installing Docker
&emsp;&emsp;You can download and install docker-ce from the Docker official website.
> For detailed information, please visit: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
### 3.3 Installing Rust
:::{warning}
**[Common Misconception]**: If you plan to compile using Docker, although the Docker image already includes a Rust compilation environment, to enable code hints in VSCode using Rust-Analyzer and for the `make clean` command to run normally, you still need to install the Rust environment on your client machine.
:::
&emsp;&emsp;You can install Rust by entering the following command in the terminal.
```shell
# 这两行用于换源，加速Rust的安装过程
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
# 安装Rust
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly
# 把Rustup加到环境变量
echo "export PATH=\"\$HOME/.cargo/bin:\$PATH\"" >> ~/.bashrc
source ~/.cargo/env
source "$HOME/.cargo/env"
# 更换cargo的索引源
touch ~/.cargo/config
echo -e "[source.crates-io] \n \
registry = \"https://github.com/rust-lang/crates.io-index\" \n \
\n \
replace-with = 'dragonos-gitee' \n \
[source.dragonos-gitee] \n \
registry = \"https://gitee.com/DragonOS/crates.io-index.git\" \n \
" > ~/.cargo/config
# 安装DragonOS所需的工具链
cargo install cargo-binutils
rustup toolchain install nightly
rustup default nightly
rustup component add rust-src
rustup component add llvm-tools-preview
rustup target add x86_64-unknown-none
# Rust安装完成
```
**At this point, the public dependencies have been installed. You can proceed to read the subsequent sections according to your needs.**
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
## 4. Building from Docker (Not Recommended)
&emsp;&emsp;DragonOS provides a Docker compilation environment for developers to run DragonOS. However, since the coding process still needs to be performed on the client machine, you need to install the Rust compilation environment on your client machine.
&emsp;&emsp;This section assumes that all operations are performed under Linux.
### 4.1 Installing QEMU Virtual Machine
&emsp;&emsp;In this section, we recommend installing QEMU via the command line:
```shell
sudo apt install -y qemu qemu-system qemu-kvm
```
### 4.2 Creating a Disk Image
&emsp;&emsp;First, you need to use the `create_hdd_image.sh` script in the `tools` folder to create a virtual disk image. You need to run this command in the `tools` folder.
```shell
bash create_hdd_image.sh
```
### 4.3 Running DragonOS
&emsp;&emsp;If everything goes well, this will be the final step to run DragonOS. You just need to execute the following command in the DragonOS root directory to run DragonOS.
```shell
make run-docker
```
&emsp;&emsp;Wait a moment, DragonOS will be started.
&emsp;&emsp;After the QEMU virtual machine is started, you need to input the letter `c` in the console and press Enter. This will start the virtual machine.
:::{note}
1. During the first compilation, since it requires downloading Rust-related indexes (hundreds of MB in size), it will take some time. Please be patient!
2. Entering commands may require adding `sudo`
:::
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
## 5. Other Notes
### 5.1 Creating a Disk Image
&emsp;&emsp;First, you need to run `tools/create_hdd_image.sh` with **normal user** permissions to create a disk image file for DragonOS. This script will automatically complete the creation of the disk image and move it to the `bin/` directory.
&emsp;&emsp;Please note that due to permission issues, you must run this script with **normal user** permissions. (After running, the system may prompt you to enter a password when you need to elevate permissions.)
### 5.2 Compiling and Running DragonOS
1. Install the compilation and runtime environment
2. Enter the DragonOS folder
3. Input `make run` to compile and write to the disk image, and run
&emsp;&emsp;After the QEMU virtual machine is started, you need to input the letter `c` in the console and press Enter. This will start the virtual machine.
:::{note}
During the first compilation, since it requires downloading Rust-related indexes (hundreds of MB in size), it will take some time. Please be patient!
:::
**For the usage of the compilation command, please refer to: {ref}`编译命令讲解 <_build_system_command>`**
(_translated_label___build_system_command_en)=
## 6. Explanation of Compilation Commands
- Local compilation, no execution: `make all -j 您的CPU核心数`
- Local compilation, write to disk image, no execution: `make build`
- Local compilation, write to disk image, and run in QEMU: `make run`
- Local compilation, write to disk image, and run in headless mode:
`make run-nographic`
- Docker compilation, write to disk image: `make docker`
- Docker compilation, write to disk image, and run in QEMU: `make run-docker`
- Start directly from an existing disk image without compilation: `make qemu`
- Start directly from an existing disk image without compilation (headless mode): `make qemu-nographic`
- Clean up compiled files: `make clean`
- Compile documentation: `make docs` (requires manual installation of sphinx and dependencies in `requirements.txt`)
- Clean up documentation: `make clean-docs`
- Format code: `make fmt`
:::{note}
If you need to run DragonOS in VNC, add the `-vnc` suffix to the above command. For example: `make run-vnc`
The QEMU virtual machine will listen on port 5900 for VNC connections. You can connect to the QEMU virtual machine using a VNC viewer or Remmina.
:::
## 7. Compiling for riscv64
Since DragonOS has not been fully ported to riscv64 yet, the compilation needs to be done as follows:
1. Modify `env.mk` and `.vscode/settings.json`
Change the value of `ARCH` in `env.mk` to `riscv64`, and in `setting.json`, comment out `"rust-analyzer.cargo.target": "x86_64-unknown-none",` and change it to the line enabling riscv64.
2. Restart rust-analyzer
3. Clean up the compilation cache
Due to the differences between x86_64 and riscv64 architectures, there may be compilation issues caused by cache. Ensure that you clean up the cache before running.
```shell
make clean
```
4. Compile and run for riscv64
```shell
# 下载DragonStub
git submodule update --init --recursive --force
make run
```
Please note that since you are running QEMU in the console, when you want to exit, input `Ctrl+A` and press `X` to do so.

154
docs/locales/en/introduction/features.md Normal file
View File

@ -0,0 +1,154 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/features.md
- Translation time: 2025-05-19 01:42:30
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
(_translated_label___genreal_features_en)=
# Features of DragonOS
## Specifications
- [x] Bootloader: Multiboot2
- [x] Interface: POSIX 2008
## Kernel Layer
### Memory Management
- [x] Page Frame Allocator
- [x] Small Object Allocator
- [x] VMA (Virtual Memory Area)
- [x] Automatic MMIO Address Space Allocation
- [x] Page Mapper
- [x] Hardware Abstraction Layer
- [x] Independent User Address Space Management Mechanism
- [x] C Interface Compatibility Layer
### Multicore
- [x] Multicore Boot
- [x] IPI (Inter-Processor Interrupt) Framework
### Process Management
- [x] Process Creation
- [x] Process Reclamation
- [x] Kernel Threads
- [x] Fork
- [x] Exec
- [x] Process Sleep (Supports High-Precision Sleep)
- [x] Kthread Mechanism
- [x] Extensible Binary Loader
#### Synchronization Primitives
- [x] Mutex
- [x] Semaphore
- [x] Atomic Variables
- [x] Spinlock
- [x] Wait Queue
### Scheduling
- [x] CFS Scheduler
- [x] Real-Time Scheduler (FIFO, RR)
- [x] Single-Core Scheduling
- [x] Multi-Core Scheduling
- [x] Load Balancing
### IPC (Inter-Process Communication)
- [x] Anonymous Pipe
- [x] Signal
### File System
- [x] VFS (Virtual File System)
- [x] FAT12/16/32
- [x] Devfs
- [x] RamFS
- [x] Procfs
- [x] Sysfs
### Exception and Interrupt Handling
- [x] APIC
- [x] Softirq (Soft Interrupt)
- [x] Kernel Stack Traceback
### Kernel Utility Library
- [x] String Operation Library
- [x] ELF Executable Support
- [x] printk
- [x] Basic Math Library
- [x] Screen Manager
- [x] TextUI Framework
- [x] CRC Function Library
- [x] Notification Chain
### System Calls
&emsp;&emsp;[See System Call Documentation](https://docs.dragonos.org/zh_CN/latest/syscall_api/index.html)
### Test Framework
- [x] ktest
### Drivers
- [x] ACPI (Advanced Configuration and Power Interface) Module
- [x] IDE Hard Disk
- [x] AHCI Hard Disk
- [x] PCI, PCIe Bus
- [x] XHCI (USB 3.0)
- [x] PS/2 Keyboard
- [x] PS/2 Mouse
- [x] HPET (High Precision Event Timer)
- [x] RTC (Real-Time Clock)
- [x] Local APIC Timer
- [x] UART Serial Port
- [x] VBE (Video BIOS Extension) Display
- [x] VirtIO Network Card
- [x] x87 FPU
- [x] TTY Terminal
- [x] Floating Point Processor
## User Layer
### LibC
- [x] Basic System Calls
- [x] Basic Standard Library Functions
- [x] Partial Mathematical Functions
### Shell Command Line Programs
- [x] Parsing Based on String Matching
- [x] Basic Commands
### Http Server
- A simple Http Server written in C, capable of running static websites.
## Software Portability
- [x] GCC 11.3.0 (Currently only supports x86_64 Cross Compiler) [https://github.com/DragonOS-Community/gcc](https://github.com/DragonOS-Community/gcc)
- [x] binutils 2.38 (Currently only supports x86_64 Cross Compiler) [https://github.com/DragonOS-Community/binutils](https://github.com/DragonOS-Community/binutils)
- [x] gmp 6.2.1 [https://github.com/DragonOS-Community/gmp-6.2.1](https://github.com/DragonOS-Community/gmp-6.2.1)
- [x] mpfr 4.1.1 [https://github.com/DragonOS-Community/mpfr](https://github.com/DragonOS-Community/mpfr)
- [x] mpc 1.2.1 [https://github.com/DragonOS-Community/mpc](https://github.com/DragonOS-Community/mpc)
- [x] relibc [https://github.com/DragonOS-Community/relibc](https://github.com/DragonOS-Community/relibc)
- [x] sqlite3

34
docs/locales/en/introduction/index.rst Normal file
View File

@ -0,0 +1,34 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/index.rst
- Translation time: 2025-05-19 01:41:59
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Introduction to DragonOS
====================================
DragonOS, the Dragon Operating System, is a 64-bit operating system designed for lightweight cloud computing scenarios. It features a fully self-developed kernel and provides Linux binary compatibility. Developed using the Rust programming language, it offers enhanced reliability. Currently, DragonOS ranks among the top three in the Rust operating system field on GitHub.
The DragonOS open-source community was established in July 2022. It is completely neutral in commercial matters. Our goal is to build a fully independent, open-source, high-performance, and highly reliable server operating system, **to create a fully self-controlled digital future!**
DragonOS has an excellent and well-designed architecture. Compared to other systems of similar size, DragonOS supports virtualization and has certain advantages in areas such as device model and scheduling subsystems. Currently, we are actively promoting cloud platform support, RISC-V support, as well as the porting of compilers and application software. We aim to achieve large-scale application in production environments within five years.
DragonOS is currently developing rapidly under the drive of the community. At present, DragonOS has already implemented about 1/4 of the Linux interface. In the future, we will provide 100% compatibility with Linux and introduce new features.
The goal of DragonOS is to build a fully independent, open-source, high-performance, and highly reliable server operating system, providing a completely self-controlled core power for the country's digital infrastructure construction.
As a community-driven open-source operating system, in order to promote the development of the open-source community and avoid potential infringement by commercial companies that do not comply with open-source agreements, we have decided to open the source code under the GPLv2 license, using a strict open-source agreement to protect DragonOS.
You may be interested in the features that have already been implemented in DragonOS. You can visit here: :ref:`功能特性 <_genreal_features>`
.. toctree::
:maxdepth: 1
features

22
docs/locales/en/introduction/mirrors.md Normal file
View File

@ -0,0 +1,22 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: introduction/mirrors.md
- Translation time: 2025-05-19 01:41:42
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# DragonOS Mirror Site
You can download the source code and other files of DragonOS from the following mirror sites:
- [DragonOS Mirror Site https://mirrors.dragonos.org/](https://mirrors.dragonos.org/)
- [DragonOS Domestic Mirror Site (RinGoTek)](https://mirrors.RinGoTek.cn)
- [Git Mirror Site](https://git.mirrors.dragonos.org/)

48
docs/locales/en/kernel/boot/bootloader.md Normal file
View File

@ -0,0 +1,48 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/boot/bootloader.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)
:::
# Bootloader
## X86_64
- [x] multiboot2
- [x] HVM/PVH
### HVM/PVH Boot on x86_64
In the DragonOS note segment, there is a PVH header that allows QEMU to boot the DragonOS kernel using the ``-kernel`` parameter.
## RISC-V 64
DragonOS's boot process on RISC-V 64 is as follows:
opensbi --> uboot --> DragonStub --> kernel
This boot process decouples the DragonOS kernel from specific hardware boards, enabling the same binary file to boot and run on different hardware boards.
## Kernel Boot Callbacks
DragonOS abstracts the kernel bootloader, which is represented by the trait ``BootCallbacks``.
Different bootloaders implement the corresponding callback to initialize the kernel's bootParams or other data structures.
When the kernel boots, it automatically registers callbacks based on the type of bootloader. And at the appropriate time, it calls these callback functions.
## References
- [Multiboot2 Specification](http://git.savannah.gnu.org/cgit/grub.git/tree/doc/multiboot.texi?h=multiboot2)
- [GNU GRUB Manual 2.06](https://www.gnu.org/software/grub/manual/grub/grub.html)
- [UEFI/Legacy Boot - yujianwu - DragonOS Community](https://bbs.dragonos.org/forum.php?mod=viewthread&tid=46)

123
docs/locales/en/kernel/boot/cmdline.md Normal file
View File

@ -0,0 +1,123 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/boot/cmdline.md
- Translation time: 2025-05-19 01:41:48
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Kernel Boot Command Line Parameters
:::{note}
Author:
- Longjin <longjin@DragonOS.org>
:::
## Overview
&emsp;&emsp;The DragonOS kernel boot command line parameter parsing module aims to provide support for parsing kernel boot command line parameters similar to Linux, enabling more flexible behavior for the kernel. This module allows the kernel to receive and parse command line parameters at boot time, and execute corresponding callback functions or set environment variables based on the type of parameters.
:::{note}
Callback functions are not supported temporarily.
:::
## Design
### Parameter Types
Kernel boot command line parameters are divided into three types:
- Arg type
- KV type
- EarlyKV type
#### Arg Type
Arg type parameters have only a name and no value. They are divided into the following two types:
- ArgNormal: The default value is `false`. If the parameter is present in the command line, it will be set to `true`.
- ArgInv: The default value is `true`. If the parameter is present in the command line, it will be set to `false`.
#### KV Type
KV type parameters are represented in the command line as `name=value`, `value` separated by commas. Kernel modules can provide default values for these parameters.
#### EarlyKV Type
EarlyKV type parameters are similar to KV type parameters, but they are parsed before memory management initialization.
### Module Flags
Module flags are similar to `usbprobe.xxxx`.
### Parameter Declaration
Provides macros to declare kernel command line parameters.
### procfs Support
:::{note}
TODO: Display the current kernel's boot command line parameters under `/proc/cmdline`.
:::
## Macros for Declaring Kernel Boot Command Line Parameters
### Arg Type Parameter Declaration
```rust
kernel_cmdline_param_arg!(varname, name, default_bool, inv);
```
- `varname`: The variable name of the parameter
- `name`: The name of the parameter
- `default_bool`: The default value
- `inv`: Whether to invert
### KV Type Parameter Declaration
```rust
kernel_cmdline_param_kv!(varname, name, default_str);
```
- `varname`: The variable name of the parameter
- `name`: The name of the parameter
- `default_str`: The default value
### KV Type Parameter Declaration Before Memory Management Initialization
```rust
kernel_cmdline_param_early_kv!(varname, name, default_str);
```
- `varname`: The variable name of the parameter
- `name`: The name of the parameter
- `default_str`: The default value
## Example
The following example demonstrates how to declare and use KV type parameters:
```rust
kernel_cmdline_param_kv!(ROOTFS_PATH_PARAM, root, "");
if let Some(rootfs_dev_path) = ROOTFS_PATH_PARAM.value_str() {
.......
} else {
.......
};
```
### Usage
1. In the kernel code, use the `kernel_cmdline_param_kv!` macro to declare the required KV type parameters.
2. During kernel initialization, retrieve the parameter value through the `value_str()` or `value_bool()` method of the parameter.
3. Execute corresponding operations based on the parameter value.
By following these steps, developers can flexibly use kernel boot command line parameters to control kernel behavior.
## TODO
- Support displaying the current kernel's boot command line parameters under `/proc/cmdline` (requires procfs refactoring)
- Support setting callback functions to set parameter values

22
docs/locales/en/kernel/boot/index.rst Normal file
View File

@ -0,0 +1,22 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/boot/index.rst
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Bootloader
====================================
.. toctree::
:maxdepth: 1
:caption: Contents
bootloader
cmdline

45
docs/locales/en/kernel/configuration/arch.md Normal file
View File

@ -0,0 +1,45 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/configuration/arch.md
- Translation time: 2025-05-19 01:41:24
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Target Architecture Configuration
## Supported Architectures
- x86_64
- riscv64
## Architecture-Specific Configuration
In order to support the debugging functionality of VSCode, we need to modify the following line in the `.vscode/settings.json` file:
```
"rust-analyzer.cargo.target": "riscv64gc-unknown-none-elf",
// "rust-analyzer.cargo.target": "x86_64-unknown-none",
```
If you want to compile for the x86_64 architecture, enable the x86_64 line and comment out the others.
If you want to compile for the riscv64 architecture, enable the riscv64 line and comment out the others.
At the same time, we also need to modify the environment variable configuration in the makefile:
Please modify the following line in the `env.mk` file:
```Makefile
ifeq ($(ARCH), )
# ！！！！在这里设置ARCH，可选x86_64和riscv64
# !!!!!!!如果不同时调整这里以及vscode的settings.json，那么自动补全和检查将会失效
export ARCH=riscv64
endif
```
Please note that changing the architecture requires a recompilation, so please run `make clean` to clean up the compilation results. Then run `make run` to proceed.

114
docs/locales/en/kernel/configuration/config.md Normal file
View File

@ -0,0 +1,114 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/configuration/config.md
- Translation time: 2025-05-19 01:41:17
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Kernel Compilation Configuration Guide
## Principle
&emsp;&emsp;Within the kernel directory, the kernel configuration is set using `kernel.config`. This file is parsed in a manner similar to a TOML file, and then the configuration of each module's `d.config` is parsed to determine the status of features.
## Example
**kernel.config**
```toml
[[module.include]]
name = "init"
path = "src/init/"
enable = "y"
description = ""
[[module.include]]
name = "mm"
path = "src/mm/"
enable = "y"
description = ""
```
- **[[module.include]]:** Adds the module to the include list
- **name:** Module name
- **path:** Module path, where the `d.config` file is located
- **enable:**
- **y:** Enabled, parse the `d.config` file of the module
- **n:** Disabled, do not parse
- **description:** Description of the module
**src/mm/d.config**
```toml
[module]
name = "mm"
description = ""
[[module.include]]
name = "allocator"
path = "src/mm/allocator/"
enable = "y"
description = ""
[[module.features]]
name = "mm_debug"
enable = "y"
description = ""
```
- **[module]:** Current module
- **name:** Name of the current module
- **description:** Description of the module
- **[[module.include]]:** Modules included in the current module, same as in `kernel.config`
- **[[module.features]]:** Features in the current module
- **name:** Feature name
- **enable:** Whether the feature is enabled
- **y:** Enabled
- **n:** Disabled
- **description:** Description of the feature
*The following are the `d.config` files of other modules:*
**src/mm/allocator/d.config**
```toml
[module]
name = "allocator"
description = ""
[[module.features]]
name = "allocator_debug"
enable = "y"
description = ""
```
**src/init/d.config**
```toml
[module]
name = "init"
description = ""
[[module.features]]
name = "init_debug"
enable = "y"
description = ""
```
All features enabled in the `d.config` files of the activated modules will be ultimately generated into the `D.config` file in the kernel directory. That is, `D.config` is the final kernel compilation configuration, as follows:
**D.config**
```
init_debug = y
allocator_debug = y
mm_debug = y
```

22
docs/locales/en/kernel/configuration/index.rst Normal file
View File

@ -0,0 +1,22 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/configuration/index.rst
- Translation time: 2025-05-19 01:41:17
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Kernel Compilation Configuration
====================================
.. toctree::
:maxdepth: 1
:caption: Contents
config
arch

26
docs/locales/en/kernel/container/index.rst Normal file
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/container/index.rst
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Containerization
====================================
This is the documentation related to containerization in DragonOS.
It mainly includes namespace, overlayfs, and cgroup
.. toctree::
:maxdepth: 2
namespaces/index
../filesystem/unionfs/index

28
docs/locales/en/kernel/container/namespaces/index.rst Normal file
View File

@ -0,0 +1,28 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/container/namespaces/index.rst
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Namespaces
====================================
DragonOS's namespaces currently support pid_namespace and mnt_namespace, and more features are expected to be added in the future.
Namespaces are an important component in the process of containerization.
Since the current OS is single-user, user_namespace is globally static.
.. toctree::
:maxdepth: 1
pid_namespace
mnt_namespace

33
docs/locales/en/kernel/container/namespaces/mnt_namespace.md Normal file
View File

@ -0,0 +1,33 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/container/namespaces/mnt_namespace.md
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Mount Namespace
## Underlying Architecture
pcb -> nsproxy -> mnt_namespace
Each mounted file system has its own independent mount point, which is represented in the data structure as a red-black tree of mounts. Each namespace has its own independent mounts, so mounting and unmounting file systems will not affect others.
## System Call Interface
- clone
- CLONE_NEWNS is used to create a new MNT namespace. It provides an independent file system mount point.
- unshare
- After calling unshare() with the CLONE_NEWPID flag, all subsequent child processes will run in the new namespace.
- setns
- Adds the process to the specified namespace.
- chroot
- Changes the current process's root directory to the specified path, providing file system isolation.

38
docs/locales/en/kernel/container/namespaces/pid_namespace.md Normal file
View File

@ -0,0 +1,38 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/container/namespaces/pid_namespace.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)
:::
# Process Namespace
:::{note} Author: Cao Fengyi 1553389239@qq.com
October 30, 2024
:::
`pid_namespace` is a type of namespace in the kernel that is used to achieve process isolation. It allows processes running in different namespaces to have independent views of process IDs (PIDs).
## Underlying Architecture
pcb -> nsproxy -> pid_namespace
- `pid_namespace` contains an independent set of process allocators and an orphan process reaper, which independently manages PIDs within the namespace.
- Detailed information about processes is stored in the proc file system. The information corresponding to a specific PID is located within the `pid_namespace`, recording information related to the `pid_namespace`.
- The limitations imposed by `pid_namespace` are controlled and managed by `ucount`.
## System Call Interface
- `clone`
- `CLONE_NEWPID` is used to create a new PID namespace. When this flag is used, the child process will run in the new PID namespace, with the process ID starting from 1.
- `unshare`
- After calling `unshare()` with the `CLONE_NEWPID` flag, all subsequent child processes will run within the new namespace.
- `getpid`
- Calling `getpid()` within a namespace returns the process ID of the process within the current PID namespace.

112
docs/locales/en/kernel/core_api/atomic.md Normal file
View File

@ -0,0 +1,112 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/atomic.md
- Translation time: 2025-05-19 01:41:25
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Atomic Variables
## Introduction
&emsp;&emsp;DragonOS implements atomic variables of type `atomic_t`. Atomic variables are implemented using architecture-specific atomic operation instructions. The specific implementation is located in `kernel/common/atomic.h`.
## API
&emsp;&emsp; Note that all the following APIs are atomic operations.
### `inline void atomic_add(atomic_t *ato, long val)`
#### Description
&emsp;&emsp; Atomically adds a specified value to the atomic variable.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
**val**
&emsp;&emsp; The value to be added to the variable.
### `inline void atomic_sub(atomic_t *ato, long val)`
#### Description
&emsp;&emsp; Atomically subtracts a specified value from the atomic variable.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
**val**
&emsp;&emsp; The value to be subtracted from the variable.
### `void atomic_inc(atomic_t *ato)`
#### Description
&emsp;&emsp; Atomically increments the atomic variable by 1.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
### `void atomic_dec(atomic_t *ato)`
#### Description
&emsp;&emsp; Atomically decrements the atomic variable by 1.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
### `inline void atomic_set_mask(atomic_t *ato, long mask)`
#### Description
&emsp;&emsp; Performs a bitwise OR operation between the atomic variable and the mask variable.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
**mask**
&emsp;&emsp; The variable used for the OR operation with the atomic variable.
### `inline void atomic_clear_mask(atomic_t *ato, long mask)`
#### Description
&emsp;&emsp; Performs a bitwise AND operation between the atomic variable and the mask variable.
#### Parameters
**ato**
&emsp;&emsp; The atomic variable object.
**mask**
&emsp;&emsp; The variable used for the AND operation with the atomic variable.

77
docs/locales/en/kernel/core_api/casting.md Normal file
View File

@ -0,0 +1,77 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/casting.md
- 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)
:::
# Type Conversion Library API
&emsp;&emsp;The kernel provides some functions to help you convert between different types. These include the following types:
- Numeric type conversion (using the `num-traits` library)
- Arc type conversion
&emsp;&emsp;All functions not specially marked are implemented in `kernel/src/libs/casting.rs`.
## 1. Numeric Type Conversion
### 1.1 Conversion Between Integer Types and Enum Types
&emsp;&emsp;You can use macros provided by the `num-traits` library to convert between enum types and integer types.
The SystemError enum type uses this approach, and you can find its usage in `kernel/src/syscall/mod.rs`.
&emsp;&emsp;It first inherits the `FromPrimitive, ToPrimitive` two traits, and then performs the conversion like this:
```rust
impl SystemError {
/// @brief 把posix错误码转换为系统错误枚举类型。
pub fn from_posix_errno(errno: i32) -> Option<SystemError> {
// posix 错误码是小于0的
if errno >= 0 {
return None;
}
return <Self as FromPrimitive>::from_i32(-errno);
}
/// @brief 把系统错误枚举类型转换为负数posix错误码。
pub fn to_posix_errno(&self) -> i32 {
return -<Self as ToPrimitive>::to_i32(self).unwrap();
}
}
```
&emsp;&emsp;These two functions well illustrate how to use these two traits.
## 2. Arc Type Conversion
### 2.1 Conversion from Arc<dyn U> to Arc<T>
&emsp;&emsp;When we need to convert an `Arc<dyn U>` to a specific type pointer of `Arc<T>`, we need to implement the `DowncastArc` trait for `U`. This trait is defined in `kernel/src/libs/casting.rs`. It requires `trait U` to implement the `Any + Sync + Send` trait.
&emsp;&emsp;To implement the `DowncastArc` trait for `trait U: Any + Send + Sync`, you need to do the following:
```rust
impl DowncastArc for dyn U {
fn as_any_arc(self: Arc<Self>) -> Arc<dyn Any> {
return self;
}
}
```
&emsp;&emsp;Using the `DowncastArc` trait, we can convert like this:
```rust
let arc: Arc<dyn U> = ...;
let arc_t: Arc<T> = arc.downcast_arc::<T>().unwrap();
```
&emsp;&emsp;If the specific type of `arc` is not `Arc<T>`, then `downcast_arc::<T>()` will return `None`.

28
docs/locales/en/kernel/core_api/index.rst Normal file
View File

@ -0,0 +1,28 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/index.rst
- Translation time: 2025-05-19 01:41:08
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Core API Documentation
====================================
This is the core API documentation for DragonOS.
.. toctree::
:maxdepth: 1
:caption: Kernel Utility Library
kernel_api
atomic
casting
notifier_chain
softirq

630
docs/locales/en/kernel/core_api/kernel_api.md Normal file
View File

@ -0,0 +1,630 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/kernel_api.md
- Translation time: 2025-05-19 01:43:39
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# DragonOS Kernel Core API
## Circular Linked List Management Functions
&emsp;&emsp;Circular linked list is one of the important data structures in the kernel. It is included in `kernel/common/list.h`.
### `void list_init(struct List *list)`
#### Description
&emsp;&emsp;Initialize a List structure so that its prev and next pointers point to itself.
#### Parameters
**list**
&emsp;&emsp;The List structure to be initialized.
### `void list_add(struct List *entry, struct List *node)`
#### Description
&emsp;&emsp;Insert the node after the entry.
#### Parameters
**entry**
&emsp;&emsp;An existing node in the circular linked list.
**node**
&emsp;&emsp;The node to be inserted.
### `void list_append(struct List *entry, struct List *node)`
#### Description
&emsp;&emsp;Insert the node before the entry.
#### Parameters
**entry**
&emsp;&emsp;An existing node in the circular linked list.
**node**
&emsp;&emsp;The node to be inserted.
### `void list_del(struct List *entry)`
#### Description
&emsp;&emsp;Remove the node from the list.
#### Parameters
**entry**
&emsp;&emsp;The node to be removed.
### `list_del_init(struct List *entry)`
#### Description
&emsp;&emsp;Remove the node from the list and re-initialize the entry using list_init().
#### Parameters
**entry**
&emsp;&emsp;The node to be removed.
### `bool list_empty(struct List *entry)`
#### Description
&emsp;&emsp;Check if the list is empty.
#### Parameters
**entry**
&emsp;&emsp;A node in the list.
### `struct List *list_prev(struct List *entry)`
#### Description
&emsp;&emsp;Get the previous node of the entry.
#### Parameters
**entry**
&emsp;&emsp;A node in the list.
### `struct List *list_next(struct List *entry)`
#### Description
&emsp;&emsp;Get the next node of the entry.
#### Parameters
**entry**
&emsp;&emsp;A node in the list.
### `void list_replace(struct List *old, struct List *new)`
#### Description
&emsp;&emsp;Replace the old node in the list with the new node.
#### Parameters
**old**
&emsp;&emsp;The node to be removed.
**new**
&emsp;&emsp;The new node to be inserted into the list.
(_translated_label___list_entry_en)=
### `list_entry(ptr, type, member)`
#### Description
&emsp;&emsp;This macro can get the address of the structure that contains the List pointed to by ptr.
#### Parameters
**ptr**
&emsp;&emsp;Pointer to the List structure.
**type**
&emsp;&emsp;The type of the structure that contains the List.
**member**
&emsp;&emsp;The name of the List structure member in the structure that contains the List.
### `list_first_entry(ptr, type, member)`
#### Description
&emsp;&emsp;Get the first element in the list. Please note that this macro requires the list to be non-empty, otherwise it will cause an error.
#### Parameters
&emsp;&emsp;Same as {ref}`list_entry() <_list_entry>`
### `list_first_entry_or_null(ptr, type, member)`
#### Description
&emsp;&emsp;Get the first element in the list. If the list is empty, return NULL.
#### Parameters
&emsp;&emsp;Same as {ref}`list_entry() <_list_entry>`
### `list_last_entry(ptr, type, member)`
#### Description
&emsp;&emsp;Get the last element in the list. Please note that this macro requires the list to be non-empty, otherwise it will cause an error.
#### Parameters
&emsp;&emsp;Same as {ref}`list_entry() <_list_entry>`
### `list_last_entry_or_full(ptr, type, member)`
#### Description
&emsp;&emsp;Get the last element in the list. If the list is empty, return NULL.
#### Parameters
&emsp;&emsp;Same as {ref}`list_entry() <_list_entry>`
(_translated_label___list_next_entry_en)=
### `list_next_entry(pos, member)`
#### Description
&emsp;&emsp;Get the next element in the list.
#### Parameters
**pos**
&emsp;&emsp;Pointer to the outer structure.
**member**
&emsp;&emsp;The name of the List structure member in the outer structure.
### `list_prev_entry(pos, member)`
#### Description
&emsp;&emsp;Get the previous element in the list.
#### Parameters
&emsp;&emsp;Same as {ref}`list_next_entry() <_list_next_entry>`
(_translated_label___list_for_each_en)=
### `list_for_each(ptr, head)`
#### Description
&emsp;&emsp;Traverse the entire list (from front to back).
#### Parameters
**ptr**
&emsp;&emsp;Pointer to the List structure.
**head**
&emsp;&emsp;Pointer to the head node of the list (struct List*).
### `list_for_each_prev(ptr, head)`
#### Description
&emsp;&emsp;Traverse the entire list (from back to front).
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each() <_list_for_each>`
(_translated_label___list_for_each_safe_en)=
### `list_for_each_safe(ptr, n, head)`
#### Description
&emsp;&emsp;Traverse the entire list from front to back (supports deletion of the current list node).
&emsp;&emsp;This macro uses a temporary variable to prevent errors that may occur during iteration if the current ptr node is deleted.
#### Parameters
**ptr**
&emsp;&emsp;Pointer to the List structure.
**n**
&emsp;&emsp;Pointer to store the temporary value (List type).
**head**
&emsp;&emsp;Pointer to the head node of the list (struct List*).
### `list_for_each_prev_safe(ptr, n, head)`
#### Description
&emsp;&emsp;Traverse the entire list from back to front (supports deletion of the current list node).
&emsp;&emsp;This macro uses a temporary variable to prevent errors that may occur during iteration if the current ptr node is deleted.
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_safe() <_list_for_each_safe>`
(_translated_label___list_for_each_entry_en)=
### `list_for_each_entry(pos, head, member)`
#### Description
&emsp;&emsp;Iterate through the list of a given type from the beginning.
#### Parameters
**pos**
&emsp;&emsp;Pointer to a structure of the specific type.
**head**
&emsp;&emsp;Pointer to the head node of the list (struct List*).
**member**
&emsp;&emsp;The name of the List member in the structure pointed to by pos.
### `list_for_each_entry_reverse(pos, head, member)`
#### Description
&emsp;&emsp;Iterate through the list of a given type in reverse order.
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_entry() <_list_for_each_entry>`
### `list_for_each_entry_safe(pos, n, head, member)`
#### Description
&emsp;&emsp;Iterate through the list of a given type from the beginning (supports deletion of the current list node).
#### Parameters
**pos**
&emsp;&emsp;Pointer to a structure of the specific type.
**n**
&emsp;&emsp;Pointer to store the temporary value (same type as pos).
**head**
&emsp;&emsp;Pointer to the head node of the list (struct List*).
**member**
&emsp;&emsp;The name of the List member in the structure pointed to by pos.
### `list_prepare_entry(pos, head, member)`
#### Description
&emsp;&emsp;Prepare a 'pos' structure for {ref}`list_for_each_entry_continue() <_list_for_each_entry_continue>`.
#### Parameters
**pos**
&emsp;&emsp;Pointer to a structure of the specific type, used as the starting point for iteration.
**head**
&emsp;&emsp;Pointer to the struct List structure to start iteration from.
**member**
&emsp;&emsp;The name of the List member in the structure pointed to by pos.
(_translated_label___list_for_each_entry_continue_en)=
### `list_for_each_entry_continue(pos, head, member)`
#### Description
&emsp;&emsp;Continue iterating through the list from the next element of the specified position.
#### Parameters
**pos**
&emsp;&emsp;Pointer to a structure of the specific type. This pointer is used as the iteration pointer.
**head**
&emsp;&emsp;Pointer to the struct List structure to start iteration from.
**member**
&emsp;&emsp;The name of the List member in the structure pointed to by pos.
### `list_for_each_entry_continue_reverse(pos, head, member)`
#### Description
&emsp;&emsp;Iterate through the list in reverse order, starting from the previous element of the specified position.
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_entry_continue() <_list_for_each_entry_continue>`
### `list_for_each_entry_from(pos, head, member)`
#### Description
&emsp;&emsp;Continue iterating through the list from the specified position.
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_entry_continue() <_list_for_each_entry_continue>`
(_translated_label___list_for_each_entry_safe_continue_en)=
### `list_for_each_entry_safe_continue(pos, n, head, member)`
#### Description
&emsp;&emsp;Continue iterating through the list from the next element of the specified position (supports deletion of the current list node).
#### Parameters
**pos**
&emsp;&emsp;Pointer to a structure of the specific type. This pointer is used as the iteration pointer.
**n**
&emsp;&emsp;Pointer to store the temporary value (same type as pos).
**head**
&emsp;&emsp;Pointer to the struct List structure to start iteration from.
**member**
&emsp;&emsp;The name of the List member in the structure pointed to by pos.
### `list_for_each_entry_safe_continue_reverse(pos, n, head, member)`
#### Description
&emsp;&emsp;Iterate through the list in reverse order, starting from the previous element of the specified position (supports deletion of the current list node).
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_entry_safe_continue() <_list_for_each_entry_safe_continue>`
### `list_for_each_entry_safe_from(pos, n, head, member)`
#### Description
&emsp;&emsp;Continue iterating through the list from the specified position (supports deletion of the current list node).
#### Parameters
&emsp;&emsp;Same as {ref}`list_for_each_entry_safe_continue() <_list_for_each_entry_safe_continue>`
---
## Basic C Function Library
&emsp;&emsp;Kernel programming differs from application layer programming; you will not be able to use functions from LibC. To address this, the kernel implements some commonly used C language functions, trying to make their behavior as close as possible to standard C library functions. It is important to note that the behavior of these functions may differ from standard C library functions, so it is recommended to carefully read the following documentation, which will be helpful to you.
### String Operations
#### `int strlen(const char *s)`
##### Description
&emsp;&emsp;Measure and return the length of the string.
##### Parameters
**src**
&emsp;&emsp;Source string.
#### `long strnlen(const char *src, unsigned long maxlen)`
##### Description
&emsp;&emsp;Measure and return the length of the string. If the string length is greater than maxlen, return maxlen.
##### Parameters
**src**
&emsp;&emsp;Source string.
**maxlen**
&emsp;&emsp;Maximum length.
#### `long strnlen_user(const char *src, unsigned long maxlen)`
##### Description
&emsp;&emsp;Measure and return the length of the string. If the string length is greater than maxlen, return maxlen.
&emsp;&emsp;This function performs address space validation, requiring the src string to be from user space. If the source string is from kernel space, it will return 0.
##### Parameters
**src**
&emsp;&emsp;Source string, located in user space.
**maxlen**
&emsp;&emsp;Maximum length.
#### `char *strncpy(char *dst, const char *src, long count)`
##### Description
&emsp;&emsp;Copy a string of count bytes and return the dst string.
##### Parameters
**src**
&emsp;&emsp;Source string.
**dst**
&emsp;&emsp;Destination string.
**count**
&emsp;&emsp;Length of the source string to copy.
#### `char *strcpy(char *dst, const char *src)`
##### Description
&emsp;&emsp;Copy the source string and return the dst string.
##### Parameters
**src**
&emsp;&emsp;Source string.
**dst**
&emsp;&emsp;Destination string.
#### `long strncpy_from_user(char *dst, const char *src, unsigned long size)`
##### Description
&emsp;&emsp;Copy a string of count bytes from user space to kernel space, and return the size of the copied string.
&emsp;&emsp;This function performs address space validation to prevent address space overflow issues.
##### Parameters
**src**
&emsp;&emsp;Source string.
**dst**
&emsp;&emsp;Destination string.
**size**
&emsp;&emsp;Length of the source string to copy.
#### `int strcmp(char *FirstPart, char *SecondPart)`
##### Description
  Compare the sizes of two strings.
***Return Value***
| Situation | Return Value |
| ----------------------- | --- |
| FirstPart == SecondPart | 0 |
| FirstPart > SecondPart | 1 |
| FirstPart < SecondPart | -1 |
##### Parameters
**FirstPart**
&emsp;&emsp;First string.
**SecondPart**
&emsp;&emsp;Second string.
### Memory Operations
#### `void *memcpy(void *dst, const void *src, uint64_t size)`
##### Description
&emsp;&emsp;Copy memory from src to dst.
##### Parameters
**dst**
&emsp;&emsp;Pointer to the destination address.
**src**
&emsp;&emsp;Pointer to the source address.
**size**
&emsp;&emsp;Size of data to be copied.
#### `void *memmove(void *dst, const void *src, uint64_t size)`
##### Description
&emsp;&emsp;Similar to `memcpy()`, but this function prevents data from being incorrectly overwritten when the source and destination memory regions overlap.
##### Parameters
**dst**
&emsp;&emsp;Pointer to the destination address.
**src**
&emsp;&emsp;Pointer to the source address.
**size**
&emsp;&emsp;Size of data to be copied.

48
docs/locales/en/kernel/core_api/notifier_chain.md Normal file
View File

@ -0,0 +1,48 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/notifier_chain.md
- Translation time: 2025-05-19 01:41:30
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Notifier Chain Notification Chain
## 1. Overview of Principles
&emsp;&emsp;The notification chain is an event notification mechanism between subsystems within the kernel or between modules within a subsystem. Essentially, a notification chain is a list of event handling functions. Each notification chain is associated with a specific type of event (e.g., reboot event). When a specific event occurs, the corresponding callback functions in the event's notification chain are called, allowing the subsystem/module to respond to the event and perform the appropriate processing.
&emsp;&emsp;The notification chain is somewhat similar to the subscription mechanism. It can be understood as: there is a "notifier" that maintains a list, and the "subscriber" registers its callback function into this list ("subscriber" can also unregister its callback function). When an event occurs that needs to be notified, the "notifier" traverses all the callback functions in the list and calls them, allowing all registered "subscribers" to respond and handle the event accordingly.
## 2. Core Features
### 2.1 Registering Callback Functions
&emsp;&emsp;The callback function is encapsulated into a specific structure and registered into the designated notification chain. The related method is `register`, which is used by the "subscriber".
### 2.2 Unregistering Callback Functions
&emsp;&emsp;The callback function is removed from the designated notification chain, i.e., it is deleted from the notification chain. The related method is `unregister`, which is used by the "subscriber".
### 2.3 Event Notification
&emsp;&emsp;When an event occurs, the notification chain related to that event performs the event notification through this method. `call_chain` This method traverses all elements in the notification chain and calls the registered callback functions in sequence. This method is used by the "notifier".
## 3. Types of Notification Chains
&emsp;&emsp;Each type of notification chain has corresponding `register`, `unregister`, and `call_chain` interfaces, with functions as described in the core features above.
- `AtomicNotifierChain`: Atomic notification chain, cannot sleep, recommended for use in interrupt context.
- `BlockingNotifierChain`: Blocking notification chain, can sleep, recommended for use in process context.
- `RawNotifierChain`: Raw notification chain, the caller is responsible for thread safety.
## 4. Other Issues
&emsp;&emsp;`BlockingNotifierChain` does not currently support the sleeping functionality.

178
docs/locales/en/kernel/core_api/softirq.md Normal file
View File

@ -0,0 +1,178 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/core_api/softirq.md
- Translation time: 2025-05-19 01:41:38
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Soft Interrupt
&emsp;&emsp;Software interrupt, also known as the bottom half of an interrupt, is used to delay the processing of work that was not completed by the hard interrupt (the top half of the interrupt). Dividing the interrupt into two stages can effectively solve the problems of long interrupt handling time and interrupt loss.
## 1. Design Philosophy
&emsp;&emsp;Each CPU has its own pending status. Soft interrupts are "initiated by which CPU, executed by which CPU", and the pending status of each CPU is not shared. The same soft interrupt vector can run concurrently on multiple cores.
&emsp;&emsp;When we need to register a new soft interrupt, we need to implement the `SoftirqVec` feature for the soft interrupt handler, and then call the `register_softirq` function to register the soft interrupt handler within the soft interrupt mechanism.
&emsp;&emsp;Please note that due to the reentrancy and concurrency of soft interrupts, the soft interrupt handler must ensure thread safety itself.
## 2. Soft Interrupt Vector Number
```rust
pub enum SoftirqNumber {
/// 时钟软中断信号
TIMER = 0,
/// 帧缓冲区刷新软中断
VideoRefresh = 1,
}
```
## 3. Soft Interrupt API
### 3.1. SoftirqVec Feature
```rust
pub trait SoftirqVec: Send + Sync + Debug {
fn run(&self);
}
```
&emsp;&emsp;The feature that the soft interrupt handler needs to implement. It needs to implement the `run` function to handle the soft interrupt. When the soft interrupt is executed, the `run` function will be called.
### 3.2. Softirq API
#### 3.2.1. Register Soft Interrupt Vector
```rust
pub fn register_softirq(&self,
softirq_num: SoftirqNumber,
handler: Arc<dyn SoftirqVec>,
) -> Result<i32, SystemError>
```
- Parameters:
- softirq_num: Interrupt vector number
- handler: The structure corresponding to the interrupt function, which needs to point to a structure variable that implements the `SoftirqVec` feature
- Return:
- Ok(i32): 0
- Err(SystemError): Error code
#### 3.2.2. Unregister Soft Interrupt Vector
```rust
pub fn unregister_softirq(&self, softirq_num: SoftirqNumber)
```
- Parameters:
- softirq_num: Interrupt vector number
#### 3.2.3. Execute Soft Interrupt
```rust
pub fn do_softirq(&self)
```
- Purpose: Execute the soft interrupt function (**only called after hard interrupt execution**)
#### 3.2.4. Clear the Pending Flag of Soft Interrupt
```rust
pub unsafe fn clear_softirq_pending(&self, softirq_num: SoftirqNumber)
```
- Purpose: Clear the pending flag of the specified soft interrupt on the current CPU. Please note that this function is unsafe because it directly modifies the pending flag without locking.
- Parameters:
- softirq_num: Interrupt vector number
#### 3.2.5. Mark Soft Interrupt as to be Executed
```rust
pub fn raise_softirq(&self, softirq_num: SoftirqNumber)
```
- Purpose: Mark the specified soft interrupt as to be executed on the current CPU
- Parameters:
- softirq_num: Interrupt vector number
### 3.3. Usage Example
```rust
#[derive(Debug)]
/// SoftirqExample中断结构体
pub struct SoftirqExample {
running: AtomicBool,
}
/// SoftirqExample中断需要处理的逻辑
fn softirq_example_func() {
println!("addressed SoftirqExample");
}
impl SoftirqVec for SoftirqExample {
fn run(&self) {
if self.set_run() == false {
return;
}
softirq_example_func();
self.clear_run();
}
}
impl SoftirqExample {
pub fn new() -> SoftirqExample {
SoftirqExample {
running: AtomicBool::new(false),
}
}
fn set_run(&self) -> bool {
let x = self
.running
.compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed);
if x.is_ok() {
return true;
} else {
return false;
}
}
fn clear_run(&self) {
self.running.store(false, Ordering::Release);
}
}
fn main() {
let softirq_example = Arc::new(SoftirqExample::new());
let softirq_num = 2;
// 注册SoftirqExample中断
softirq_vectors()
.register_softirq(SoftirqNumber::from(softirq_num as u64), softirq_example)
.expect("failed to register SoftirqExample");
// 标志SoftirqExample中断需要执行
softirq_vectors().raise_softirq(SoftirqNumber::from(softirq_num as u64));
// 标志SoftirqExample中断不需要执行
softirq_vectors().clear_softirq_pending(SoftirqNumber::from(softirq_num as u64));
// 解注册SoftirqExample中断
softirq_vectors().unregister_softirq(SoftirqNumber::from(softirq_num as u64));
}
```

23
docs/locales/en/kernel/cpu_arch/index.rst Normal file
View File

@ -0,0 +1,23 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/cpu_arch/index.rst
- Translation time: 2025-05-19 01:41:20
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Processor Architecture
====================================
This section of the documentation provides descriptions of some programming implementation details related to the processor architecture.
.. toctree::
:maxdepth: 1
:caption: Contents
x86_64/index

21
docs/locales/en/kernel/cpu_arch/x86_64/index.rst Normal file
View File

@ -0,0 +1,21 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/cpu_arch/x86_64/index.rst
- Translation time: 2025-05-19 01:41:18
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
x86-64 Related Documentation
====================================
.. toctree::
:maxdepth: 1
:caption: Contents
usb_legacy_support

24
docs/locales/en/kernel/cpu_arch/x86_64/usb_legacy_support.md Normal file
View File

@ -0,0 +1,24 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/cpu_arch/x86_64/usb_legacy_support.md
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# USB Legacy Support
## Introduction
&emsp;&emsp;USB Legacy Support refers to the support provided by the BIOS for USB mice and USB keyboards. On computers that support and enable USB Legacy Support, the USB mouse and keyboard are simulated by the BIOS, making them appear to the operating system as if they were PS/2 mice and keyboards.
## Related
- When initializing the USB controller, its USB Legacy Support should be disabled.

375
docs/locales/en/kernel/debug/debug-kernel-with-gdb.md Normal file
View File

@ -0,0 +1,375 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/debug/debug-kernel-with-gdb.md
- Translation time: 2025-05-19 01:41:41
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# How to Use GDB to Debug the Kernel
## Introduction
&emsp;&emsp;GDB is a powerful open-source debugging tool that can help you better diagnose and fix errors in programs.
&emsp;&emsp;It provides a rich set of features that allow you to check the execution status of a program, track the execution flow of code, view and modify the values of variables, analyze memory states, and more. It can be used in conjunction with a compiler to allow you to access debugging information during the debugging process.
&emsp;&emsp;This tutorial will guide you on how to use `rust-gdb` to debug the kernel in DragonOS, including how to start debugging and the corresponding debugging commands.
:::{note}
If you are already familiar with the various commands of `rust-gdb`, you only need to read the first part of this tutorial.
:::
---
## 1. Getting Started
### 1.1 Preparation
&emsp;&emsp;Before you start debugging the kernel, you need to enable debug mode in /Kernel/Cargo.toml by changing `debug = false` to `debug = true` in the Cargo.toml file.
```shell
debug = false
```
&emsp;&emsp;**Change to**
```shell
debug = true
```
### 1.2 Running DragonOS
&emsp;&emsp;After the preparation is complete, you can compile and run DragonOS to proceed with the subsequent debugging work.
&emsp;&emsp;Open a terminal in the root directory of DragonOS and use `make run` to start compiling and running DragonOS. For more help with compilation commands, see
> [Building DragonOS](https://docs.dragonos.org/zh_CN/latest/introduction/build_system.html).
### 1.3 Running GDB
&emsp;&emsp;Once DragonOS has started running, you can start debugging with GDB.
&emsp;&emsp;**You only need to open a new terminal and run `make gdb` to start the GDB debugger.**
```shell
❯ make gdb
rust-gdb -n -x tools/.gdbinit
GNU gdb (Ubuntu 12.1-0ubuntu1~22.04) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
--Type <RET> for more, q to quit, c to continue without paging--
```
:::{note}
If you see the above information, input `c` and press Enter.
:::
---
## 2. Debugging
### 2.1 Start
&emsp;&emsp;After completing the above steps, you can start debugging.
```shell
For help, type "help".
Type "apropos word" to search for commands related to "word".
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0xffff8000001f8f63 in ?? ()
(gdb)
```
:::{note}
The output information from GDB, `0xffff8000001f8f63 in ?? ()`, indicates that DragonOS is still in the process of booting.
:::
&emsp;&emsp;**Input `continue` or `c` to continue the program execution.**
```shell
For help, type "help".
Type "apropos word" to search for commands related to "word".
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0xffff8000001f8f63 in ?? ()
(gdb) continue
Continuing.
```
&emsp;&emsp;While DragonOS is running, you can press `Ctrl+C` at any time to send an interrupt signal to view the current state of the kernel.
```shell
(gdb) continue
Continuing.
^C
Thread 1 received signal SIGINT, Interrupt.
0xffff800000140c21 in io_in8 (port=113) at common/glib.h:136
136 __asm__ __volatile__("inb %%dx, %0 \n\t"
(gdb)
```
### 2.2 Setting Breakpoints and Watchpoints
&emsp;&emsp;Setting breakpoints and watchpoints is the most fundamental step in program debugging.
- **Setting Breakpoints**
&emsp;&emsp;You can use the `break` or `b` command to set a breakpoint.
&emsp;&emsp;Regarding the usage of `break` or `b` commands:
```shell
b <line_number> #在当前活动源文件的相应行号打断点
b <file>:<line_number> #在对应文件的相应行号打断点
b <function_name> #为一个命名函数打断点
```
- **Setting Watchpoints**
&emsp;&emsp;You can use the `watch` command to set a watchpoint.
```shell
watch <variable> # 设置对特定变量的监视点,将在特定变量发生变化的时候触发断点
watch <expression> # 设置对特定表达式的监视点，比如watch *(int*)0x12345678会在内存地址0x12345678处
# 的整数值发生更改时触发断点。
```
- **Managing Breakpoints and Watchpoints**
&emsp;&emsp;Once we have set breakpoints, how can we view all the breakpoint information?
&emsp;&emsp;You can use `info b`, `info break`, or `info breakpoints` to view all breakpoint information:
```shell
(gdb) b 309
Breakpoint 12 at 0xffff8000001f8f16: file /home/heyicong/.cargo/registry/src/mirrors.tuna.tsinghua.edu.cn-df7c3c540f42cdbd/thingbuf-0.1.4/src/lib.rs, line 315.
(gdb) watch slots
Watchpoint 13: slots
(gdb) info b
Num Type Disp Enb Address What
12 breakpoint keep y 0xffff8000001f8f16 in thingbuf::Core::pop_ref<u8>
at /home/heyicong/.cargo/registry/src/mirrors.tuna.tsinghua.edu.cn-df7c3c540f42cdbd/thingbuf-0.1.4/src/lib.rs:315
13 watchpoint keep y slots
(gdb)
```
&emsp;&emsp;In the above information, the breakpoint with number 12 is the one we set in line 309 of the active source file. If its `Address` is `<MULTIPLE>`, it indicates that there are identical breakpoints at multiple addresses. This is very common in loops. The breakpoint with number 13 is the watchpoint we set for the `slots` variable.
&emsp;&emsp;We can perform operations on breakpoints or watchpoints using the following commands:
```shell
delete <breakpoint#> # 或 d <breakpoint#> 删除对应编号的断点，在您不再需要使用这个断点的时候可以通过此命令删除断点
delete <watchpoint#> # 或 d <watchpoint##> 删除对应编号的监视点，在您不再需要使用这个监视点的时候可以通过此命令删除监视点
disable <breakpoint#> # 禁用对应编号的断点，这适合于您只是暂时不需要使用这个断点时使用，当您禁用一个断点，下
# 次程序运行到该断点处将不会停下来
disable <watchpoint#> # 禁用对应编号的监视点，这适合于您只是暂时不需要使用这个监视点时使用
enable <breakpoint#> # 启用对应编号的断点
enable <watchpoint#> # 启用对应编号的监视点
#clear命令
clear # 清除当前活动源文件的断点以及监视点
clear <point_number> # 清除对应编号的所有断点或监视点，这与delete行为是一致的
clear <file> # 清除指定文件的所有断点与监视点
```
## 2.3 Viewing Variables and Memory
- **print and display**
&emsp;&emsp;You can use `print` or `p` to print variable values.
&emsp;&emsp;The `print` command is used to print the value of a variable or expression. It allows you to view the data in the program during debugging.
```shell
print <variable> # 打印对应变量名的值，例如：print my_variable 或者 p my_variable
print <expression> # 打印合法表达式的值，例如：print a+b 或者 p a+b
# 示例输出
(gdb) print order
$3 = core::sync::atomic::Ordering::SeqCst
```
```{note}
如果您不仅想打印值，还想显示更多详细信息（例如类型信息），可以使用ptype命令。
```
&emsp;&emsp;You can use the `display` command to continuously track variables or expressions. The `display` command is used to set expressions that need to be tracked and displayed every time the program stops. It is similar to the print command, but unlike print, the display command automatically prints the value of the specified expression every time the program stops, without requiring manual input of a command.
```shell
display <variable> # 打印对应变量名的值，例如：display my_variable
display <expression> # 打印合法表达式的值，例如：display a+b
# 示例输出
(gdb) display order
1: order = core::sync::atomic::Ordering::SeqCst #其中1表示display编号，
#您可以通过info display命令来查看所有display编号
```
```{note}
一旦您设置了display命令，每当程序停止（例如，在断点处停止）时，GDB将自动打印指定表达式的值。
display命令非常有用，因为它允许您在调试过程中持续监视表达式的值，而无需每次都手动输入print命令。它特别适用于那些您希望持续跟踪的变量或表达式。
```
&emsp;&emsp;**To cancel an already set display command and stop automatically displaying the value of an expression, you can use the undisplay command:**
```shell
undisplay <display编号> # 如果不指定<display编号>，则将取消所有已设置的display命令，
# 您可以通过info display命令来查看所有display编号
```
```{note}
请注意，print和display命令只会在程序暂停执行时评估变量或表达式的值。如果程序正在运行，您需要通过设置断点或使用其他调试命令来暂停程序，然后才能使用print命令查看数据的值,display命令设置的值将会在程序暂停时自动输出。
```
- **Output Format**
&emsp;&emsp;You can set the output format to get more information you need, for example: `print /a var`
> Refer to [GDB Cheat Sheet](https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf)
```shell
Format
a Pointer.
c Read as integer, print as character.
d Integer, signed decimal.
f Floating point number.
o Integer, print as octal.
s Try to treat as C string.
t Integer, print as binary (t = „two“).
u Integer, unsigned decimal.
x Integer, print as hexadecimal.
```
### 2.4 Viewing the Call Stack
- **Viewing the Call Stack**
&emsp;&emsp;When the program is paused at a breakpoint, how should you trace the program's behavior?
&emsp;&emsp;You can use the `backtarce` command to view the call stack. The `backtrace` command is used to print the backtrace information of the current call stack. It displays all the active function call chains during program execution, including the function names, parameters, and line numbers in the source files.
```shell
# 示例输出
(gdb) backtrace
#0 function1 (arg1=10, arg2=20) at file1.c:15
#1 function2 () at file2.c:25
#2 xx () at xx.c:8
```
&emsp;&emsp;Each line of backtrace information starts with #<frame_number>, indicating the frame number. Then comes the function name and parameter list, followed by the source file name and line number.
By viewing the backtrace information, you can understand in which functions the program is executing and the position of each function in the call stack. This is very useful for debugging the program and locating problems.
- **Switching the Stack**
&emsp;&emsp;You can use the `frame` or `f` command to switch to the corresponding stack frame to get more information and perform operations.
```shell
frame <frame_number>
f <frame_number>
```
&emsp;&emsp;In addition to simply executing the backtrace command, you can also use some options to customize the output of the backtrace information. For example:
```shell
backtrace full #显示完整的符号信息，包括函数参数和局部变量。
backtrace <frame_count> #限制回溯信息的帧数，只显示指定数量的帧。
backtrace <frame_start>-<frame_end> #指定要显示的帧范围。
backtrace thread <thread_id> #显示指定线程的回溯信息。
```
### 2.5 Multi-core
&emsp;&emsp;When debugging the kernel, you may need to view the running status of each core.
&emsp;&emsp;You can use the `info threads` command to view the running status of each core.
```shell
(gdb) info threads
Id Target Id Frame
1 Thread 1.1 (CPU#0 [halted ]) 0xffff800000140a3e in Start_Kernel () at main.c:227
* 2 Thread 1.2 (CPU#1 [running]) thingbuf::Core::pop_ref<u8> ()
at /home/heyicong/.cargo/registry/src/mirrors.tuna.tsinghua.edu.cn-df7c3c540f42cdbd/thingbuf-0.1.4/src/lib.rs:315
(gdb)
```
&emsp;&emsp;You can use the `thread <thread_id>` command to switch to the context of a specific core to view and debug the status of that core. For example:
```shell
(gdb) thread 1
[Switching to thread 1 (Thread 1.1)]
#0 0xffff800000140a3e in Start_Kernel () at main.c:227
227 hlt();
```
### 2.6 More
&emsp;&emsp;Next, I will introduce more commands that you may find useful during debugging:
```shell
step #或者s,逐行执行程序，并进入到函数调用中。可以在step命令后加执行次数，例：step 3 表示要连续执行3个步骤
step <function> #进入指定的函数，并停止在函数内的第一行。
next #或者n,逐行执行程序，但跳过函数调用，直接执行函数调用后的下一行代码。
#它允许你在不进入函数内部的情况下执行代码，从而快速跳过函数调用的细节。
#同样，next也可以在命令后加执行次数
finish #用于从当前函数中一直执行到函数返回为止，并停在调用该函数的地方。
#它允许你快速执行完当前函数的剩余部分，并返回到调用函数的上下文中。
continue #用于继续程序的执行，直到遇到下一个断点或
#程序正常结束或者程序暂停。
quit #退出调试
list #或者l，显示当前活动源文件源代码的片段，以及当前执行的位置。
list <filename>:<function> #显示<filename>文件里面的<funtion>函数的源代码片段
list <filename>:<line_number> #显示<filename>文件里面的<line_number>附近的源代码片段
list <first>,<last> #显示当前活动源文件的<first>至<last>之间的源代码片段
set listsize <count> #设置list命令显示的源代码行数。默认情况下，list命令显示当前行和其周围的几行代码。
info args #显示当前函数的参数及其值
info breakpoints #显示断点以及监视点信息
info display #显示当前设置的display列表
info locals #显示当前函数/栈帧中的局部变量及其值
info sharedlibrary #显示当前已加载的共享库（shared library）信息
info signals #显示当前程序所支持的信号信息。它可以列出程序可以接收和处理的不同信号的列表。
info threads #显示各个核心/线程信息，它可以列出当前正在运行的核心/线程以及它们的状态。
show directories #显示当前源代码文件的搜索路径列表。这些搜索路径决定了GDB在查找源代码文件时的搜索范围。
show listsize #显示打印源代码时的上下文行数。它确定了在使用list命令（或其简写形式l）时显示的源代码行数。
whatis variable_name #查看给定变量或表达式的类型信息。它可以帮助你了解变量的数据类型。
ptype #显示给定类型或变量的详细类型信息。它可以帮助你了解类型的结构和成员。
#相较于whatis命令，ptype命令更加详细。
set var <variable_name>=<value> #设置变量值
return <expression> #强制使当前函数返回设定值
```
---
## Conclusion
&emsp;&emsp;Now, you can use rust-gdb to debug the DragonOS kernel code.
> You can refer to the GDB command documentation for more help: [GDB Cheat Sheet](https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf)

25
docs/locales/en/kernel/debug/index.rst Normal file
View File

@ -0,0 +1,25 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/debug/index.rst
- 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>`_
Kernel Debug Module
====================================
This is the documentation for the kernel debug module of DragonOS.
.. toctree::
:maxdepth: 1
:caption: Contents
traceback
debug-kernel-with-gdb
profiling-kernel-with-dadk

109
docs/locales/en/kernel/debug/profiling-kernel-with-dadk.md Normal file
View File

@ -0,0 +1,109 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/debug/profiling-kernel-with-dadk.md
- Translation time: 2025-05-19 01:41:49
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Performance Analysis of the Kernel Using DADK
## 1. Overview
This document will teach you how to use DADK to perform performance analysis on the DragonOS kernel, in order to identify and resolve potential performance bottlenecks.
### 1.1 Preparation
::: {note}
Before you start, please ensure that you have installed DADK and have set up the compilation environment for the DragonOS kernel.
:::
### 1.2 What is a Flame Graph?
If you haven't heard of flame graphs before, you can read this article: [How to Read Flame Graphs? - Ruanyifeng](https://www.ruanyifeng.com/blog/2017/09/flame-graph.html)
In simple terms, a flame graph is an SVG image generated from performance sampling results, used to display the call stack of the CPU.
![](https://web-static2.dragonos.org.cn//longjin/flame2.svg?imageSlim)
The x-axis represents the number of samples. If a function occupies a wider width on the x-axis, it means it was sampled more frequently, indicating longer execution time. Note that the x-axis does not represent time, but rather all call stacks are merged and sorted alphabetically.
A flame graph is used to identify which function at the top level occupies the largest width. If there is a "plateau" (flat area), it indicates that the function may have performance issues.
Colors have no special meaning, as flame graphs represent the CPU's busy level, so warm tones are generally chosen.
## 2. Configuring the DragonOS Kernel
Since performance analysis requires detailed symbol table data, we need to configure the kernel compilation as follows:
In `kernel/Cargo.toml`'s `[profile.release]` section, set the following two options:
```toml
[profile.release]
debug = true
opt-level = 1
```
This will ensure that the compiled kernel includes symbol table data, making it easier for us to perform performance analysis.
## 3. Using DADK for Performance Analysis
### 3.1 Booting the Kernel
First, we need to boot the DragonOS kernel.
```shell
# 使用你喜欢的方式启动内核，例如：
make run
# 或者
make build && make qemu-nographic
```
### 3.2 Running Your Workload
After booting the kernel, we need to run some workloads in order to perform performance analysis.
This can be an application or something else. Even you can choose to do nothing and simply observe the call stack of the DragonOS kernel when it is idle.
### 3.3 Starting DADK for Performance Analysis
In the DragonOS project directory, run the following command:
```shell
dadk profile sample --format flamegraph --output flame.svg --interval 200ms --duration 20s --cpu-mask 0x1
```
The above command will perform performance analysis on the DragonOS kernel and generate a flame graph.
Detailed explanation:
- `--format flamegraph`: Specifies the output format as a flame graph.
- `--output flame.svg`: Specifies the output filename as `flame.svg`.
- `--interval 200ms`: Specifies the sampling interval as 200ms.
- `--duration 20s`: Specifies the sampling duration as 20 seconds.
- `--cpu-mask 0x1`: Specifies the CPU to be sampled as CPU 0. (This is a bitmask, meaning if you want to sample CPU 0 and 1, the cpu-mask would be 0x3)
*For more parameters, please refer to `dadk profile sample --help`.*
::: {note}
Since sampling will pause vCPU, the sampling time should not be too short, otherwise it may affect the normal operation of the system.
:::
After waiting for a while, you will get a `flame.svg` file.
### 3.4 Analyzing the Flame Graph
Open the `flame.svg` file in a browser, and you will see a flame graph.
You can click on a function in the flame graph to view its call stack.
**You can right-click the image below and open it in a new tab to experience the interactive effects.**
![](https://web-static2.dragonos.org.cn//longjin/flame2.svg?imageSlim)

50
docs/locales/en/kernel/debug/traceback.md Normal file
View File

@ -0,0 +1,50 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/debug/traceback.md
- Translation time: 2025-05-19 01:41:10
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Kernel Stack Traceback
## Introduction
&emsp;&emsp;The functionality of the kernel stack traceback is located in the `kernel/debug/traceback/` folder. It provides traceback capabilities for the kernel mode, printing the call stack to the screen.
---
## API
### `void traceback(struct pt_regs * regs)`
#### Purpose
&emsp;&emsp;This interface is defined in `kernel/debug/traceback/traceback.h`, which will perform a traceback on the given kernel stack and print the trace results to the screen.
#### Parameters
##### regs
&emsp;&emsp;The first stack frame of the kernel stack to start the tracing (i.e., the bottom of the stack)
---
## Implementation Principle
&emsp;&emsp;After the kernel is linked for the first time, the Makefile will run the `kernel/debug/kallsyms` program to extract the symbol table of the kernel file, and then generate `kernel/debug/kallsyms.S`. The rodata segment of this file stores the symbol table of the functions in the text segment. Then, this file will be compiled into `kallsyms.o`. Finally, the Makefile will again call the `ld` command to link the kallsyms.o into the kernel file.
&emsp;&emsp;When the `traceback` function is called, it will traverse the symbol table to find the corresponding symbols and output them.
---
## Future Development Directions
- Add the capability to write to a log file

29
docs/locales/en/kernel/filesystem/index.rst Normal file
View File

@ -0,0 +1,29 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/index.rst
- Translation time: 2025-05-19 01:41:15
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
File System
====================================
The file system module of DragonOS consists of VFS (Virtual File System) and specific file systems.
todo: Due to the refactoring of the file system module, the documentation is temporarily unavailable and will be completed by April 10, 2023.
.. toctree::
:maxdepth: 1
:caption: Contents
overview
vfs/index
sysfs
kernfs
unionfs/index

37
docs/locales/en/kernel/filesystem/kernfs.md Normal file
View File

@ -0,0 +1,37 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/kernfs.md
- Translation time: 2025-05-19 01:41:15
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# KernFS
:::{note}
Maintainer:
- Long Jin <longjin@dragonos.org>
:::
## 1. Introduction
&emsp;&emsp;KernFS is a pseudo file system that acts as a container for other kernel file systems, providing a file interface to users. Its core functionality is that when files in KernFS are read/written or trigger callback points, the predefined callback functions will be invoked, triggering operations on other kernel file systems.
&emsp;&emsp;This design decouples the basic operations of SysFS and file systems. KernFS serves as the carrier of SysFS, allowing SysFS to focus more on the management of KObjects, resulting in more elegant code.
&emsp;&emsp;In the future, the kernel subsystem of DragonOS or other kernel file systems can use KernFS as a carrier for file system operations, decoupling the system management logic from specific file system operations.
## 2. Usage
&emsp;&emsp;Taking SysFS as an example, a new KernFS instance is created as the file system interface for SysFS, and then it is mounted under the directory `/sys`. Then, sysfs implements the upper-layer logic to manage KObjects. Each upper-layer KObject must include a KernFSInode. By setting the PrivateData of KernFSInode, KernFS can retrieve the corresponding KObject or sysfs attribute based on the Inode. Furthermore, when creating a KernFSInode, different callbacks are passed to the specific Inode, enabling "different Inodes to trigger different callback behaviors when read or written."
&emsp;&emsp;When a callback occurs, KernFS passes the callback information and private information to the callback function, allowing the callback function to retrieve the corresponding KObject or sysfs attribute based on the input information, thus achieving the high-level functionality provided by sysfs.
&emsp;&emsp;From the above description, we can see that KernFS achieves the purpose of "decoupling specific file operations from high-level management logic" by storing the callback functions and callback information of the upper-layer file systems.

107
docs/locales/en/kernel/filesystem/overview.md Normal file
View File

@ -0,0 +1,107 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/overview.md
- Translation time: 2025-05-19 01:41:36
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
:::{note}
Author of this article: Long Jin
Email: <longjin@DragonOS.org>
:::
# Overview
&emsp;&emsp;In this article, we will introduce the architecture design of the DragonOS file system.
## Overview
&emsp;&emsp;As shown in the following diagram, the file system-related mechanisms of DragonOS mainly include the following parts:
- System call interface
- Virtual File System (VFS)
- File abstraction (File)
- Mount file system (MountFS)
- Specific file systems
```text
┌─────────────────────────────────────────────────┐
│ │
Syscall: │ sys_open, sys_read, sys_write, sys_close, │
│ │
│ sys_lseek, etc.. │
│ │
└───────────────────────┬─────────────────────────┘
│
│
VFS: ┌──────▼─────┐
│ │
│ File │
│ │
└──────┬─────┘
│
┌────────▼────────┐
│ │
│ MountFS │
│ │
└────┬────────────┘
│
Filesystems: ┌─────────────┼─────────────┬────────────┐
│ │ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼────┐ ┌─────▼─────┐
│ │ │ │ │ │ │ │
│ FAT │ │ DevFS │ │ ProcFS │ │ RamFS │
│ │ │ │ │ │ │ │
└───────────┘ └───────────┘ └──────────┘ └───────────┘
```
## System Call Interface
&emsp;&emsp;The file system-related system call interfaces of DragonOS mainly include the following:
- `sys_open`: Open file
- `sys_read`: Read file
- `sys_write`: Write file
- `sys_close`: Close file
- `sys_lseek`: Set file pointer position
- `sys_mkdir`: Create directory
- `sys_unlink_at`: Delete file or directory (distinguish between file and directory by parameter `flag`)
- `sys_ioctl`: Control device (not implemented)
- `sys_fstat`: Get file status (not implemented)
- `sys_fsync`: Synchronize file (not implemented)
- `sys_ftruncate`: Truncate file (not implemented)
- `sys_fchmod`: Modify file permissions (not implemented)
- Other system call interfaces (not implemented)
&emsp;&emsp;For the specific meaning of the interfaces, you can refer to the relevant documentation of Linux.
## Virtual File System (VFS)
&emsp;&emsp;VFS is the core of the DragonOS file system, providing a unified set of file system interfaces, allowing DragonOS to support various different file systems. The main functions of VFS include:
- Provide a unified file system interface
- Provide file system mounting and unmounting mechanism (MountFS)
- Provide file abstraction (File)
- Provide file system abstraction (FileSystem)
- Provide IndexNode abstraction
- Provide file system caching and synchronization mechanism (not implemented yet)
&emsp;&emsp;For detailed introduction of VFS, please see [DragonOS Virtual File System](vfs/index.rst).
## Specific File Systems
&emsp;&emsp;The file systems currently supported by DragonOS include:
- FAT file system (FAT12, FAT16, FAT32)
- DevFS
- ProcFS
- RamFS

124
docs/locales/en/kernel/filesystem/sysfs.md Normal file
View File

@ -0,0 +1,124 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/sysfs.md
- Translation time: 2025-05-19 01:41:50
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# SysFS
:::{note}
Author: Huang Ting
Email: <huangting@DragonOS.org>
:::
## 1. SysFS and Device Driver Model
### 1.1. The relationship between devices, drivers, buses, etc., is complex
&emsp;&emsp;If you want the kernel to run smoothly, you must code these functionalities for each module. This will make the kernel very bloated and redundant. The idea of the device model is to abstract these codes into a shared framework for all modules. This not only makes the code concise, but also allows device driver developers to avoid the headache of this essential but burdensome task, and focus their limited energy on implementing the differences of the devices.
&emsp;&emsp;The device model provides a template, an optimal approach and process that has been proven. This reduces unnecessary errors during the development process and clears the way for future maintenance.
### 1.2. sysfs is a memory-based file system, its role is to provide kernel information in the form of files for user programs to use.
&emsp;&emsp;sysfs can be seen as a file system similar to proc, devfs, and devpty. This file system is virtual and can make it easier to manage system devices. It can generate a hierarchical view of all system hardware, similar to the proc file system that provides process and status information. sysfs organizes the devices and buses connected to the system into a hierarchical file structure, which can be accessed from user space, exporting kernel data structures and their attributes to user space.
## 2. Device Driver Model in DragonOS
### 2.1. The basic elements are composed of devices and drivers
#### 2.1.1. Device
```rust
/// @brief: 所有设备都应该实现该trait
pub trait Device: Any + Send + Sync + Debug {}
```
&emsp;&emsp;DragonOS uses a global device manager to manage all devices in the system.
```rust
/// @brief Device管理器
#[derive(Debug, Clone)]
pub struct DeviceManager {
devices: BTreeMap<IdTable, Arc<dyn Device>>, // 所有设备
sys_info: Option<Arc<dyn IndexNode>>, // sys information
}
```
#### 2.1.2. Driver
```rust
/// @brief: 所有驱动驱动都应该实现该trait
pub trait Driver: Any + Send + Sync + Debug {}
```
&emsp;&emsp;Similarly, drivers also use a global driver manager for management.
```rust
/// @brief: 驱动管理器
#[derive(Debug, Clone)]
pub struct DriverManager {
drivers: BTreeMap<IdTable, Arc<dyn Driver>>, // 所有驱动
sys_info: Option<Arc<dyn IndexNode>>, // sys information
}
```
### 2.2. Bus
&emsp;&emsp;Bus is a type of device, and it also needs a driver to initialize. Due to the special nature of buses, a global bus manager is used for management.
```rust
/// @brief: 总线驱动trait，所有总线驱动都应实现该trait
pub trait BusDriver: Driver {}
/// @brief: 总线设备trait，所有总线都应实现该trait
pub trait Bus: Device {}
/// @brief: 总线管理结构体
#[derive(Debug, Clone)]
pub struct BusManager {
buses: BTreeMap<IdTable, Arc<dyn Bus>>, // 总线设备表
bus_drvs: BTreeMap<IdTable, Arc<dyn BusDriver>>, // 总线驱动表
sys_info: Option<Arc<dyn IndexNode>>, // 总线inode
}
```
&emsp;&emsp;As can be seen, each manager contains a sys_info. The device model establishes a connection with sysfs through this member, and sys_info points to the unique inode in sysfs. For a device, it corresponds to the devices folder under sysfs, and the same applies to other components.
## 3. How to Develop Drivers
&emsp;&emsp;Taking the platform bus as an example, the platform bus is a virtual bus that can match devices and drivers mounted on it and drive the devices. This bus is a type of device and also a type of bus. When programming, you need to create an instance of this device and implement the Device trait and Bus trait for the device instance to indicate that this structure is a bus device. At the same time, the matching rules on the bus should be implemented. Different buses have different matching rules. This bus uses a matching table for matching, and both devices and drivers should have a matching table, indicating the devices supported by the driver and the drivers supported by the device.
```rust
pub struct CompatibleTable(BTreeSet<&'static str>);
```
&emsp;&emsp;For a bus device, you need to call bus_register to register the bus into the system and visualize it in sysfs.
```rust
/// @brief: 总线注册，将总线加入全局总线管理器中，并根据id table在sys/bus和sys/devices下生成文件夹
/// @parameter bus: Bus设备实体
/// @return: 成功:() 失败:DeviceError
pub fn bus_register<T: Bus>(bus: Arc<T>) -> Result<(), DeviceError> {
BUS_MANAGER.add_bus(bus.get_id_table(), bus.clone());
match sys_bus_register(&bus.get_id_table().to_name()) {
Ok(inode) => {
let _ = sys_bus_init(&inode);
return device_register(bus);
}
Err(_) => Err(DeviceError::RegisterError),
}
}
```
&emsp;&emsp;From the source code of bus_register, we can see that this function not only generates a bus folder under sysfs/bus, but also internally calls device_register. This function adds the bus to the device manager and generates a device folder under sys/devices.

23
docs/locales/en/kernel/filesystem/unionfs/index.rst Normal file
View File

@ -0,0 +1,23 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/unionfs/index.rst
- Translation time: 2025-05-19 01:41:16
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Union Filesystem
====================================
Union Filesystem:
OverlayFS merges multiple filesystems (referred to as "layers") into a single logical filesystem, allowing users to see a unified directory structure.
.. toctree::
:maxdepth: 1
overlayfs

46
docs/locales/en/kernel/filesystem/unionfs/overlayfs.md Normal file
View File

@ -0,0 +1,46 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/unionfs/overlayfs.md
- Translation time: 2025-05-19 01:41:18
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# overlayfs
OverlayFS is currently the most widely used union file system, with a simple principle and convenient usage, mainly used in containers.
In Docker, OverlayFS is one of the default storage drivers. Docker creates an independent upper directory for each container, while all containers share the same lower image file. This design makes resource sharing between containers more efficient and reduces storage requirements.
## Architecture Design
OverlayFS has two layers and a virtual merged layer.
- **Lower Layer (Lower Layer)**: Usually a read-only file system. It can contain multiple layers.
- **Upper Layer (Upper Layer)**: A writable layer. All write operations are performed on this layer.
- **Merged Layer (Merged Layer)**: The logical view of the upper and lower layers is merged, and the final file system presented to the user is shown.
## Working Principle
- **Read Operation**:
- OverlayFS will first read the file from the Upper Layer. If the file does not exist in the upper layer, it will read the content from the Lower Layer.
- **Write Operation**:
- If a file is located in the Lower Layer and an attempt is made to write to it, the system will copy it up to the Upper Layer and then write to it in the upper layer. If the file already exists in the Upper Layer, it will be directly written to that layer.
- **Delete Operation**:
- When deleting a file, OverlayFS creates a whiteout entry in the upper layer, which hides the file in the lower layer.
## Copy-up
- **Copy-on-Write (Write-time Copy)**
When a file in the lower layer is modified, it is copied to the upper layer (called copy-up). All subsequent modifications will be performed on the copied file in the upper layer.
## Implementation Logic
The implementation is achieved by building `ovlInode` to implement the `indexnode` trait to represent the inode of the upper or lower layer. Specific operations related to files and directories are handled accordingly.

16
docs/locales/en/kernel/filesystem/vfs/api.md Normal file
View File

@ -0,0 +1,16 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/vfs/api.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)
:::
# VFS API Documentation

72
docs/locales/en/kernel/filesystem/vfs/design.md Normal file
View File

@ -0,0 +1,72 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/vfs/design.md
- Translation time: 2025-05-19 01:41:33
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
:::{note}
Author of this article: Long Jin
Email: <longjin@DragonOS.org>
:::
# Design
&emsp;&emsp;The architecture design of VFS is shown in the following diagram:
```text
┌─────────┐
│ │
│ read │
File │ │
│ write │
│ │ │
│ │ ioctl │
│ │ │
│ │ lseek │
│ │ │
│ │ etc.. │
│ └─────────┘
│
▼ ┌──────────────────────────────────────────────────────────────────────────────┐
MountFS │ Maintain the mount tree and handle the mounting of file systems. │
│ │ In particular, it handles the "crossing file system boundaries" condition │
│ │ while doing "lookup" or "find" operations. │
│ └──────────────────────────────────────────────────────────────────────────────┘
│
│
│
Filesystems: │
│
▼ ┌────────────────────────────────────────────────────────────────────┐
xxxFSInode │ Implement corresponding operations based on different file systems │
└────────────────────────────────────────────────────────────────────┘
```
## 1. File
&emsp;&emsp;The File structure is the most basic abstraction in VFS, representing an opened file. Whenever a process opens a file, a File structure is created to maintain the state information of that file.
## 2. Traits
&emsp;&emsp;For each specific file system, the following traits must be implemented:
- FileSystem: Indicates that a struct is a file system
- IndexNode: Indicates that a struct is an index node
&emsp;&emsp;Generally, there is a one-to-one relationship between FileSystem and IndexNode, meaning that one file system corresponds to one type of IndexNode. However, for some special file systems, such as DevFS, different IndexNodes may exist based on different device types. Therefore, there is a one-to-many relationship between FileSystem and IndexNode.
## 3. MountFS
&emsp;&emsp;Although MountFS implements the FileSystem and IndexNode traits, it is not itself a "file system," but rather a mechanism used to mount different file systems onto the same file system tree.
All file systems that need to be mounted onto the file system tree must go through MountFS to complete the mounting process. In other words, each file system structure in the mount tree is wrapped with a MountFS structure.
&emsp;&emsp;For most operations, MountFS simply forwards the operation to the specific file system without any processing. At the same time, to support cross-file system operations, such as searching in a directory tree, each lookup or find operation will go through the corresponding method of MountFSInode to determine whether the current inode is a mount point and handle it specially. If the operation is found to cross the boundary of a specific file system, MountFS will forward the operation to the next file system and perform an inode replacement. This functionality is implemented by wrapping a regular Inode structure with a MountFSInode structure.

33
docs/locales/en/kernel/filesystem/vfs/index.rst Normal file
View File

@ -0,0 +1,33 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/filesystem/vfs/index.rst
- 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>`_
VFS Virtual File System
====================================
In DragonOS, VFS acts as an adapter, hiding the differences between specific file systems and providing a unified file operation interface abstraction to the outside.
VFS is the core of the file system in DragonOS. It provides a set of unified file system interfaces, enabling DragonOS to support various different file systems. The main functions of VFS include:
- Providing a unified file system interface
- Providing mount and unmount mechanisms for file systems (MountFS)
- Providing file abstraction (File)
- Providing file system abstraction (FileSystem)
- Providing IndexNode abstraction
- Providing caching and synchronization mechanisms for file systems (not yet implemented)
.. toctree::
:maxdepth: 1
:caption: Directory
design
api

23
docs/locales/en/kernel/ipc/index.rst Normal file
View File

@ -0,0 +1,23 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/ipc/index.rst
- Translation time: 2025-05-19 01:41:19
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Inter-Process Communication
====================================
This is the documentation for DragonOS Inter-Process Communication (IPC).
.. toctree::
:maxdepth: 1
signal

97
docs/locales/en/kernel/ipc/signal.md Normal file
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/ipc/signal.md
- Translation time: 2025-05-19 01:41:43
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Signal Signal
:::{note}
This document Maintainer: Longjin
Email: <longjin@RinGoTek.cn>
:::
&emsp;&emsp;Signals are a mechanism for inter-process communication. When a signal is sent to a specific process, it can trigger a specific behavior (such as exiting the program or running a signal handler). Signals are asynchronous notifications sent to a process or a specific thread within the same process, used to notify it that an event has occurred. Common uses of signals include interrupting, suspending, terminating, or ending a process. When sending a signal, the operating system interrupts the normal execution flow of the target process to deliver the signal. Execution can be interrupted at any non-atomic instruction. If the process has previously registered a signal handler, the handler routine is executed. Otherwise, the default signal handler is executed.
&emsp;&emsp;Signals are similar to interrupts, with the difference being that interrupts are mediated by the CPU and handled by the kernel, while signals are generated within the kernel (and can also be generated through system calls) and are handled by the default handlers of individual processes or the kernel.
## 1. Overview of Signal Handling
### 1.1 Signal Sending
&emsp;&emsp;When process A wants to send a signal to process B, it uses the `kill(pid, signal)` interface to send the signal. Then, it enters the `sys_kill()` function in the kernel for processing. The kernel will then add the signal to the `sigpending` in the target process's PCB.
Illustration:
```text
┌────────────┐
│ Process A: │
│ │
│ sys_kill │
└──────┬─────┘
│
│
┌──────▼──────┐ ┌────────────────────┐
│ Send Signal ├────►Add to sigpending of│
└─────────────┘ │ process B. │
└────────────────────┘
```
### 1.2 Signal Handling
&emsp;&emsp;When a process exits the kernel mode, it jumps into the `do_signal()` function to check if there are any signals that need to be handled. If there are, the signal handling process is initiated.
Signal handling process illustration:
```text
┌───────────────────────┐
│ Process B: │
│ ◄─────────────────────────────────┐
│ Return from syscall...│ │
└─────────┬─────────────┘ │
│ │
│ │
│ ┌────────────────┐ │
┌─────▼─────┐ default │ │ │
│ do_signal ├────────► │ stop process B.│ │
└─────┬─────┘ action │ │ │
│ └────────────────┘ │
│ custom action │
┌──────▼───────┐ │
│ setup signal │ │
│ frame │ │
└──────┬───────┘ │
│jump to │
┌──────▼───────┐ ┌────────────┐ sys_sigreturn ┌────────┴────────┐
│ userland ├─►sa_restorer ├──────────────►│Restore the stack│
│ sig handler │ └────────────┘ │ frame. │
└──────────────┘ └─────────────────┘
```
- If the kernel checks and finds that the process has not specified a signal handler and the signal handling action is not "ignore", the process will be terminated.
- If the kernel finds that the signal is not ignored, it will:
- Save the current kernel stack
- Set up the user-mode stack frame for signal handling
- Return to user mode and execute the signal handler
- After the signal handler finishes, it will enter the __sa_restorer__ provided by libc, initiating the `sys_sigreturn()` system call to return to kernel mode
- The kernel restores the kernel stack before handling the signal.
- The signal handling process ends, and the kernel continues with the process of returning to user mode.
- If the kernel finds that the current signal is being ignored, it checks the next signal.
- If no signals need to be handled, it returns to user mode.
## 2. Other Issues
&emsp;&emsp;None at present.

26
docs/locales/en/kernel/ktest/index.rst Normal file
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/ktest/index.rst
- Translation time: 2025-05-19 01:41:16
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Kernel Testing
====================================
This chapter will introduce how to test the kernel, including manual testing and automated testing.
We need to perform thorough testing on the kernel as much as possible, so that we can better ensure the stability of the kernel and reduce the difficulty of debugging other modules.
Setting up comprehensive test cases can help us detect problems as much as possible, preventing us from being "stabbed" by hidden bugs in existing modules when writing new modules.
Since it is difficult to debug using tools like GDB, manual testing in the kernel is more challenging compared to testing applications.
For some modules, we can write code for unit testing and output error messages. Unfortunately, not all modules can be unit tested. For example, common modules such as memory management and process management cannot be unit tested.

26
docs/locales/en/kernel/libs/id-allocation.md Normal file
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.

26
docs/locales/en/kernel/libs/index.rst Normal file
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

97
docs/locales/en/kernel/libs/lib_ui/scm.md Normal file
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.

44
docs/locales/en/kernel/libs/lib_ui/textui.md Normal file
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.

64
docs/locales/en/kernel/libs/unified-init.md Normal file
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>

26
docs/locales/en/kernel/locking/index.rst Normal file
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/locking/index.rst
- Translation time: 2025-05-19 01:41:08
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
Locks
====================================
This is the documentation explaining the lock variables in DragonOS.
.. toctree::
:maxdepth: 1
locks
spinlock
mutex
rwlock

63
docs/locales/en/kernel/locking/locks.md Normal file
View File

@ -0,0 +1,63 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/locking/locks.md
- Translation time: 2025-05-19 01:41:26
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Types of Locks and Their Rules
## Introduction
&emsp;&emsp;The DragonOS kernel implements several types of locks, which can be broadly categorized into two types:
- Sleepable locks
- Spin locks
## Types of Locks
### Sleepable Locks
&emsp;&emsp;Sleepable locks can only be acquired in a context that is preemptible.
&emsp;&emsp;In DragonOS, the following sleepable locks are implemented:
- semaphore
- mutex_t
### Spin Locks
- spinlock_t
- {ref}`RawSpinLock <_spinlock_doc_rawspinlock>` (Rust version of spinlock_t, but incompatible with spinlock_t)
- {ref}`SpinLock <_spinlock_doc_spinlock>` —— Built on top of RawSpinLock, it wraps a guard, binding the lock and the data it protects into a single structure. This allows for compile-time checks to prevent accessing data without holding the lock.
&emsp;&emsp;When a process acquires a spin lock, it changes the lock count in the PCB, thereby implicitly disabling preemption. To provide more flexible operations, spinlock also provides the following methods:
| Suffix | Description |
|----------------------|--------------------------------------------------------|
| _irq() | Disable interrupts when acquiring the lock, enable them when releasing |
| _irqsave()/_irqrestore() | Save the interrupt state when acquiring the lock, and restore it when releasing |
## Detailed Introduction
### Detailed Introduction to Spin Locks
&emsp;&emsp;For a detailed introduction to spin locks, please refer to the document: {ref}`自旋锁 <_spinlock_doc>`
### Semaphore
&emsp;&emsp;A semaphore is implemented based on a counter.
&emsp;&emsp;When the available resources are insufficient, a process attempting to perform a down operation on the semaphore will be put to sleep until the resources become available.
### Mutex
&emsp;&emsp;Please refer to {ref}`Mutex文档 <_mutex_doc>`

185
docs/locales/en/kernel/locking/mutex.md Normal file
View File

@ -0,0 +1,185 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/locking/mutex.md
- Translation time: 2025-05-19 01:41:16
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
(_translated_label___mutex_doc_en)=
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
:::
# Mutex (Mutual Exclusion)
&emsp;&emsp;A mutex is a lightweight synchronization primitive, with only two states: locked and idle.
&emsp;&emsp;When a mutex is occupied, any process attempting to lock it will be put to sleep until the resource becomes available.
## 1. Features
- Only one task can hold the mutex at a time.
- Recursive locking and unlocking are not allowed.
- Mutex can only be operated through its API.
- Mutex cannot be used in hard interrupts or soft interrupts.
## 2. Definition
&emsp;&emsp;The mutex is defined in `lib/mutex.rs`, as shown below:
```rust
/// @brief Mutex互斥量结构体
/// 请注意！由于Mutex属于休眠锁，因此，如果您的代码可能在中断上下文内执行，请勿采用Mutex！
#[derive(Debug)]
pub struct Mutex<T> {
/// 该Mutex保护的数据
data: UnsafeCell<T>,
/// Mutex内部的信息
inner: SpinLock<MutexInner>,
}
#[derive(Debug)]
struct MutexInner {
/// 当前Mutex是否已经被上锁(上锁时，为true)
is_locked: bool,
/// 等待获得这个锁的进程的链表
wait_list: LinkedList<&'static mut process_control_block>,
}
```
## 3. Usage
&emsp;&emsp;Similar to SpinLock, the Rust version of Mutex has a guard. When using it, you need to transfer the ownership of the data to be protected to the Mutex. Moreover, the guard can only be generated after a successful lock, so at any moment, each Mutex can have at most one guard.
&emsp;&emsp;When you need to read or modify the data protected by the Mutex, you should first use the `lock()` method of the Mutex. This method returns a `MutexGuard`. You can use the member functions of the protected data to perform some operations, or directly read or write the protected data. (This is equivalent to obtaining a mutable reference to the protected data.)
&emsp;&emsp;A complete example is shown in the code below:
```rust
let x :Mutex<Vec<i32>>= Mutex::new(Vec::new());
{
let mut g :MutexGuard<Vec<i32>>= x.lock();
g.push(1);
g.push(2);
g.push(2);
assert!(g.as_slice() == [1, 2, 2] || g.as_slice() == [2, 2, 1]);
// 在此处，Mutex是加锁的状态
debug!("x={:?}", x);
}
// 由于上方的变量`g`，也就是Mutex守卫的生命周期结束，自动释放了Mutex。因此，在此处，Mutex是放锁的状态
debug!("x={:?}", x);
```
&emsp;&emsp;For variables inside a structure, we can use Mutex to perform fine-grained locking, that is, wrap the member variables that need to be locked in detail with Mutex, for example:
```rust
pub struct a {
pub data: Mutex<data_struct>,
}
```
&emsp;&emsp;Of course, we can also lock the entire structure:
```rust
struct MyStruct {
pub data: data_struct,
}
/// 被全局加锁的结构体
pub struct LockedMyStruct(Mutex<MyStruct>);
```
## 4. API
### 4.1. new - Initialize Mutex
#### Prototype
```rust
pub const fn new(value: T) -> Self
```
#### Description
&emsp;&emsp;The `new()` method is used to initialize a Mutex. This method requires a protected data as a parameter. It returns a Mutex.
### 4.2. lock - Lock
#### Prototype
```rust
pub fn lock(&self) -> MutexGuard<T>
```
#### Description
&emsp;&emsp;Lock the Mutex, returns the guard of the Mutex. You can use this guard to operate the protected data.
&emsp;&emsp;If the Mutex is already locked, this method will block the current process until the Mutex is released.
### 4.3. try_lock - Try to Lock
#### Prototype
```rust
pub fn try_lock(&self) -> Result<MutexGuard<T>, i32>
```
#### Description
&emsp;&emsp;Try to lock the Mutex. If the lock fails, the current process will not be added to the waiting queue. If the lock is successful, it returns the guard of the Mutex; if the Mutex is already locked, it returns `Err(错误码)`.
## 5. C Version of Mutex (Will be deprecated in the future)
&emsp;&emsp;The mutex is defined in `common/mutex.h`. Its data type is as follows:
```c
typedef struct
{
atomic_t count; // 锁计数。1->已解锁。 0->已上锁,且有可能存在等待者
spinlock_t wait_lock; // mutex操作锁，用于对mutex的list的操作进行加锁
struct List wait_list; // Mutex的等待队列
} mutex_t;
```
### 5.1. API
#### mutex_init
**`void mutex_init(mutex_t *lock)`**
&emsp;&emsp;Initialize a mutex object.
#### mutex_lock
**`void mutex_lock(mutex_t *lock)`**
&emsp;&emsp;Lock a mutex object. If the mutex is currently held by another process, the current process will enter a sleep state.
#### mutex_unlock
**`void mutex_unlock(mutex_t *lock)`**
&emsp;&emsp;Unlock a mutex object. If there are other processes in the mutex's waiting queue, the next process will be awakened.
#### mutex_trylock
**`void mutex_trylock(mutex_t *lock)`**
&emsp;&emsp;Try to lock a mutex object. If the mutex is currently held by another process, it returns 0. Otherwise, the lock is successful and returns 1.
#### mutex_is_locked
**`void mutex_is_locked(mutex_t *lock)`**
&emsp;&emsp;Determine if the mutex is already locked. If the given mutex is in a locked state, it returns 1; otherwise, it returns 0.

216
docs/locales/en/kernel/locking/rwlock.md Normal file
View File

@ -0,0 +1,216 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/locking/rwlock.md
- Translation time: 2025-05-19 01:41:57
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# RwLock Read-Write Lock
:::{note}
Author: sujintao
Email: <sujintao@dragonos.org>
:::
## 1. Introduction
&emsp;&emsp;A read-write lock is a mechanism used in a concurrent environment to protect shared data among multiple processes. Compared to a regular spinlock, a read-write lock divides access to shared data into two types: read access and write access. Read access to shared data is controlled by a read lock, while write access to shared data is controlled by a write lock. The design of a read-write lock allows for multiple "readers" (read-only access) and a single "writer" (write access) to coexist simultaneously. For shared data that is mostly read-only, using a read-write lock to control access can improve performance to some extent.
## 2. Implementation of Read-Write Lock in DragonOS
### 2.1 Mechanism of Read-Write Lock
&emsp;&emsp;The purpose of a read-write lock is to maintain the consistency of shared variables in a multi-threaded system. Data is wrapped in an RwLock data structure, and all access and modification must be done through this structure. Each process that accesses shared data will obtain a guard. A read-only process obtains a READER (reader guard), while a process that needs to modify a shared variable obtains a WRITER (writer guard). As a "shadow" of the RwLock, threads perform access and modification operations based on the guard.
&emsp;&emsp;In practice, in addition to READER and WRITER, a read-write lock also introduces an UPGRADER. This is a guard that lies between READER and WRITER. The role of the UPGRADER is to prevent WRITER starvation. When a process obtains an UPGRADER, it treats it as a READER. However, the UPGRADER can be upgraded, and after upgrading, it becomes a WRITER guard, allowing write operations on shared data.
&emsp;&emsp;All guards satisfy the RAII mechanism native to Rust. When the scope of a guard ends, the guard will automatically release.
### 2.2 Relationship Between Read-Write Lock Guards
&emsp;&emsp;At any given time, multiple READERS can exist, meaning that multiple processes can access shared data simultaneously. However, only one WRITER can exist at a time, and when a process obtains a WRITER, no READERS or UPGRADERS can exist. A process can obtain an UPGRADER only if there are no existing UPGRADERS or WRITERS. However, once a process obtains an UPGRADER, it cannot successfully apply for a READER.
### 2.3 Design Details
#### 2.3.1 RwLock Data Structure
```rust
pub struct RwLock<T> {
lock: AtomicU32,//原子变量
data: UnsafeCell<T>,
}
```
#### 2.3.2 READER Guard Data Structure
```rust
pub struct RwLockReadGuard<'a, T: 'a> {
data: *const T,
lock: &'a AtomicU32,
}
```
#### 2.3.3 UPGRADER Guard Data Structure
```rust
pub struct RwLockUpgradableGuard<'a, T: 'a> {
data: *const T,
inner: &'a RwLock<T>,
}
```
#### 2.3.4 WRITER Guard Data Structure
```rust
pub struct RwLockWriteGuard<'a, T: 'a> {
data: *mut T,
inner: &'a RwLock<T>,
}
```
#### 2.3.5 Introduction to the lock Structure in RwLock
The lock is a 32-bit atomic variable AtomicU32, and its bit allocation is as follows:
```
UPGRADER_BIT WRITER_BIT
^ ^
OVERFLOW_BIT +------+ +-------+
^ | |
| | |
+-+--+--------------------------------------------------------+-+--+-+--+
| | | | |
| | | | |
| | The number of the readers | | |
| | | | |
+----+--------------------------------------------------------+----+----+
31 30 2 1 0
```
&emsp;&emsp;(From right to left) The 0th bit represents whether WRITER is valid. If WRITER_BIT = 1, it indicates that a process has obtained a WRITER guard. If UPGRADER_BIT = 1, it indicates that a process has obtained an UPGRADER guard. Bits 2 to 30 are used to represent the number of processes that have obtained READER guards in binary form. The 31st bit is an overflow detection bit. If OVERFLOW_BIT = 1, new requests for obtaining READER guards will be rejected.
## 3. Main APIs of Read-Write Lock
### 3.1 Main APIs of RwLock
```rust
///功能: 输入需要保护的数据类型data,返回一个新的RwLock类型.
pub const fn new(data: T) -> Self
```
```rust
///功能: 获得READER守卫
pub fn read(&self) -> RwLockReadGuard<T>
```
```rust
///功能: 尝试获得READER守卫
pub fn try_read(&self) -> Option<RwLockReadGuard<T>>
```
```rust
///功能: 获得WRITER守卫
pub fn write(&self) -> RwLockWriteGuard<T>
```
```rust
///功能: 尝试获得WRITER守卫
pub fn try_write(&self) -> Option<RwLockWriteGuard<T>>
```
```rust
///功能: 获得UPGRADER守卫
pub fn upgradeable_read(&self) -> RwLockUpgradableGuard<T>
```
```rust
///功能: 尝试获得UPGRADER守卫
pub fn try_upgradeable_read(&self) -> Option<RwLockUpgradableGuard<T>>
```
### 3.2 Main APIs of the WRITER Guard RwLockWriteGuard
```rust
///功能: 将WRITER降级为READER
pub fn downgrade(self) -> RwLockReadGuard<'rwlock, T>
```
```rust
///功能: 将WRITER降级为UPGRADER
pub fn downgrade_to_upgradeable(self) -> RwLockUpgradableGuard<'rwlock, T>
```
### 3.3 Main APIs of the UPGRADER Guard RwLockUpgradableGuard
```rust
///功能: 将UPGRADER升级为WRITER
pub fn upgrade(mut self) -> RwLockWriteGuard<'rwlock, T>
```
```rust
///功能: 将UPGRADER降级为READER
pub fn downgrade(self) -> RwLockReadGuard<'rwlock, T>
```
## 4. Usage Examples
```rust
static LOCK: RwLock<u32> = RwLock::new(100 as u32);
fn t_read1() {
let guard = LOCK.read();
let value = *guard;
let readers_current = LOCK.reader_count();
let writers_current = LOCK.writer_count();
println!(
"Reader1: the value is {value}
There are totally {writers_current} writers, {readers_current} readers"
);
}
fn t_read2() {
let guard = LOCK.read();
let value = *guard;
let readers_current = LOCK.reader_count();
let writers_current = LOCK.writer_count();
println!(
"Reader2: the value is {value}
There are totally {writers_current} writers, {readers_current} readers"
);
}
fn t_write() {
let mut guard = LOCK.write();
*guard += 100;
let writers_current = LOCK.writer_count();
let readers_current = LOCK.reader_count();
println!(
"Writers: the value is {guard}
There are totally {writers_current} writers, {readers_current} readers",
guard = *guard
);
let read_guard=guard.downgrade();
let value=*read_guard;
println!("After downgraded to read_guard: {value}");
}
fn t_upgrade() {
let guard = LOCK.upgradeable_read();
let value = *guard;
let readers_current = LOCK.reader_count();
let writers_current = LOCK.writer_count();
println!(
"Upgrader1 before upgrade: the value is {value}
There are totally {writers_current} writers, {readers_current} readers"
);
let mut upgraded_guard = guard.upgrade();
*upgraded_guard += 100;
let writers_current = LOCK.writer_count();
let readers_current = LOCK.reader_count();
println!(
"Upgrader1 after upgrade: the value is {temp}
There are totally {writers_current} writers, {readers_current} readers",
temp = *upgraded_guard
);
let downgraded_guard=upgraded_guard.downgrade_to_upgradeable();
let value=*downgraded_guard;
println!("value after downgraded: {value}");
let read_guard=downgraded_guard.downgrade();
let value_=*read_guard;
println!("value after downgraded to read_guard: {value_}");
}
fn main() {
let r2=thread::spawn(t_read2);
let r1 = thread::spawn(t_read1);
let t1 = thread::spawn(t_write);
let g1 = thread::spawn(t_upgrade);
r1.join().expect("r1");
t1.join().expect("t1");
g1.join().expect("g1");
r2.join().expect("r2");
}
```

118
docs/locales/en/kernel/locking/spinlock.md Normal file
View File

@ -0,0 +1,118 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/locking/spinlock.md
- Translation time: 2025-05-19 01:43:03
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
(_translated_label___spinlock_doc_en)=
:::{note}
Author: Longjin <longjin@RinGoTek.cn>
:::
# Spinlock
## 1. Introduction
&emsp;&emsp;A spinlock is a type of lock used for synchronization in multi-threaded environments. Threads repeatedly check if the lock variable is available. Since the thread remains in a running state during this process, it is a form of busy waiting. Once a spinlock is acquired, the thread will hold onto it until it is explicitly released.
&emsp;&emsp;DragonOS implements spinlocks in the `kernel/src/lib/spinlock.rs` file. Based on slight differences in functional characteristics, two types of spinlocks, `RawSpinLock` and `SpinLock`, are provided.
(_translated_label___spinlock_doc_rawspinlock_en)=
## 2. RawSpinLock - Raw Spinlock
&emsp;&emsp;`RawSpinLock` is a raw spinlock, whose data part contains an AtomicBool, implementing the basic functionality of a spinlock. Its locking and unlocking require manual determination of the corresponding timing, meaning that, like spinlocks used in other languages, you need to first call the `lock()` method, and then manually call the `unlock()` method when leaving the critical section. We do not explicitly inform the compiler of which data the spinlock is protecting.
&emsp;&emsp;RawSpinLock provides programmers with very flexible control over locking and unlocking. However, due to its excessive flexibility, it is easy to make mistakes when using it. Common issues include "accessing critical section data without locking", "forgetting to unlock", and "double unlocking". The compiler cannot check for these issues, and they can only be discovered at runtime.
:::{warning}
`RawSpinLock` is not binary compatible with the C version of `spinlock_t`. If you need to operate on the C version of `spinlock_t` for temporary compatibility reasons, please use the operation functions for the C version of spinlock_t provided in `spinlock.rs`.
However, for newly developed features, please do not use the C version of `spinlock_t`, as it will be removed as code refactoring progresses.
:::
(_translated_label___spinlock_doc_spinlock_en)=
## 3. SpinLock - Spinlock with Guard
&emsp;&emsp;`SpinLock` is an encapsulation of `RawSpinLock`, enabling compile-time checks for issues such as "accessing critical section data without locking", "forgetting to unlock", and "double unlocking"; it also supports internal mutability of data.
&emsp;&emsp;Its struct prototype is as follows:
```rust
#[derive(Debug)]
pub struct SpinLock<T> {
lock: RawSpinlock,
/// 自旋锁保护的数据
data: UnsafeCell<T>,
}
```
### 3.1. Usage
&emsp;&emsp;You can initialize a SpinLock like this:
```rust
let x = SpinLock::new(Vec::new());
```
&emsp;&emsp;When initializing this SpinLock, you must pass the data you want to protect into the SpinLock, which will then manage it.
&emsp;&emsp;When you need to read or modify data protected by SpinLock, please first use the `lock()` method of SpinLock. This method will return a `SpinLockGuard`. You can use the member functions of the protected data to perform some operations, or directly read and write the protected data. (This is equivalent to obtaining a mutable reference to the protected data.)
&emsp;&emsp;The complete example is shown in the code below:
```rust
let x :SpinLock<Vec<i32>>= SpinLock::new(Vec::new());
{
let mut g :SpinLockGuard<Vec<i32>>= x.lock();
g.push(1);
g.push(2);
g.push(2);
assert!(g.as_slice() == [1, 2, 2] || g.as_slice() == [2, 2, 1]);
// 在此处，SpinLock是加锁的状态
debug!("x={:?}", x);
}
// 由于上方的变量`g`，也就是SpinLock守卫的生命周期结束，自动释放了SpinLock。因此，在此处，SpinLock是放锁的状态
debug!("x={:?}", x);
```
&emsp;&emsp;For variables inside a struct, we can use SpinLock to perform fine-grained locking, that is, wrap the member variables that need to be locked in SpinLock, for example:
```rust
pub struct a {
pub data: SpinLock<data_struct>,
}
```
&emsp;&emsp;Of course, we can also lock the entire struct:
```rust
struct MyStruct {
pub data: data_struct,
}
/// 被全局加锁的结构体
pub struct LockedMyStruct(SpinLock<MyStruct>);
```
### 3.2. Principle
&emsp;&emsp;`SpinLock` can achieve compile-time checking because it introduces a `SpinLockGuard` as a guard. When writing code, we ensure that only after calling the `lock()` method of `SpinLock` to acquire the lock can a `SpinLockGuard` be generated. Moreover, whenever we want to access protected data, we must obtain a guard. We also implement the `Drop` trait for `SpinLockGuard`; when the guard's lifetime ends, the lock will be automatically released. There is no other way to release the lock. Therefore, we can know that, in a context, as long as the `SpinLockGuard`'s lifetime has not ended, it has the right to access the critical section data, and the data access is safe.
### 3.3. Existing Issues
#### 3.3.1. Double Locking
&emsp;&emsp;Please note that the compile-time checks supported by `SpinLock` are not omnipotent. It currently cannot detect the issue of "double locking" at compile time. Consider this scenario: function A acquires the lock, and then function B attempts to lock again, which results in a "double locking" issue. This kind of problem cannot be detected at compile time.
&emsp;&emsp;To address this issue, we recommend the following programming approach:
- If function B needs to access data within the critical section, function B should receive a parameter of type `&SpinLockGuard`, which is obtained by function A. In this way, function B can access the data within the critical section.

42
docs/locales/en/kernel/memory_management/allocate-memory.md Normal file
View File

@ -0,0 +1,42 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/memory_management/allocate-memory.md
- Translation time: 2025-05-19 01:41:13
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Memory Allocation Guide
&emsp;&emsp;This document will explain how to perform memory allocation within the kernel. Before starting, please understand a basic point: DragonOS's kernel manages memory using 4KB pages and has a buddy allocator and a slab allocator. It also has specific management mechanisms for both user space and kernel space.
## 1. Safe Memory Allocation
&emsp;&emsp;By default, KernelAllocator is bound as the global memory allocator. It automatically selects between using the slab allocator or the buddy allocator based on the size of the memory requested. Therefore, in the kernel, using Rust's native memory allocation functions or creating an `Box` object, etc., is safe.
## 2. Manual Management of Page Frames
:::{warning}
**Please be extremely cautious!** Manually managing page frames bypasses Rust's memory safety mechanisms, which may lead to memory leaks or memory errors.
:::
&emsp;&emsp;In some cases, we need to manually allocate page frames. For example, when we need to create a new page table or a new address space within the kernel. In such situations, we need to manually allocate page frames. Using the `LockedFrameAllocator`'s `allocate()` function can allocate contiguous page frames in physical address space. Please note that since the underlying implementation uses the buddy allocator, the number of page frames must be a power of two, and the maximum size should not exceed 1GB.
&emsp;&emsp;When you need to release page frames, you can use the `LockedFrameAllocator`'s `deallocate()` function or the `deallocate_page_frames()` function to release contiguous page frames in physical address space.
&emsp;&emsp;When you need to map page frames, you can use the `KernelMapper::lock()` function to obtain a kernel mapper object and then perform the mapping. Since KernelMapper is an encapsulation of PageMapper, once you obtain a KernelMapper, you can use the PageMapper-related interfaces to manage the mapping in the kernel space.
:::{warning}
**Never** use KernelMapper to map memory in user address space. This would cause that part of memory to be detached from the user address space management, leading to memory errors.
:::
## 3. Allocating Memory for User Programs
&emsp;&emsp;In the kernel, you can use the user address space structure (`AddressSpace`) and its functions such as `mmap()`, `map_anonymous()`, etc., to allocate memory for user programs. These functions will automatically map the user program's memory into the user address space and automatically create VMA structures. You can use the `AddressSpace`'s `munmap()` function to unmap the user program's memory from the user address space and destroy the VMA structure. Functions such as `mprotect()` can be used for adjusting permissions.

27
docs/locales/en/kernel/memory_management/index.rst Normal file
View File

@ -0,0 +1,27 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/memory_management/index.rst
- Translation time: 2025-05-19 01:41:10
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
.. _translated_label__memory_management_module_en:
====================================
Memory Management
====================================
This section explains the design and implementation principles of the memory management module, along with the corresponding interfaces.
.. toctree::
:maxdepth: 1
intro
allocate-memory
mmio

34
docs/locales/en/kernel/memory_management/intro.md Normal file
View File

@ -0,0 +1,34 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/memory_management/intro.md
- 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)
:::
# Introduction to the Memory Management Module
## 1. Overview
&emsp;&emsp;DragonOS implements a memory management module with excellent architectural design, encapsulating operations such as memory mapping, allocation, release, and management for both kernel space and user space. This allows kernel developers to more conveniently perform memory management tasks.
&emsp;&emsp;The memory management module of DragonOS is mainly composed of the following types of components:
- **Hardware Abstraction Layer (MemoryManagementArch)** - Provides abstraction for specific processor architectures, enabling the memory management module to run on different processor architectures.
- **Page Mapper (PageMapper)** - Provides mapping between virtual addresses and physical addresses, as well as operations for creating, filling, destroying, and managing page tables. It is divided into two types: Kernel Page Table Mapper (KernelMapper) and User Page Table Mapper (located within the specific user address space structure).
- **Page Flusher (PageFlusher)** - Provides operations for flushing page tables (full table flush, single page flush, cross-core flush).
- **Frame Allocator (FrameAllocator)** - Provides operations for allocating, releasing, and managing page frames. Specifically, it includes BumpAllocator and BuddyAllocator.
- **Small Object Allocator** - Provides operations for allocating, releasing, and managing small memory objects. This refers to the SlabAllocator within the kernel (the implementation of SlabAllocator is currently not completed).
- **MMIO Space Manager** - Provides operations for allocating and managing MMIO address spaces. (This module is pending further refactoring.)
- **User Address Space Management Mechanism** - Provides management of user address spaces.
- **VMA Mechanism** - Provides management of user address spaces, including creation, destruction, and permission management of VMA.
- **User Mapping Management** - Works together with the VMA mechanism to manage mappings in user address spaces.
- **System Call Layer** - Provides system calls for the user-space memory management system, including mmap, munmap, mprotect, mremap, etc.
- **C Interface Compatibility Layer** - Provides interfaces for existing C code, enabling C code to run normally.

204
docs/locales/en/kernel/memory_management/mmio.md Normal file
View File

@ -0,0 +1,204 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/memory_management/mmio.md
- Translation time: 2025-05-19 01:41:34
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# MMIO
MMIO stands for "Memory-Mapped I/O," and it is widely used for interaction with hardware devices.
## Address Space Management
DragonOS implements a mechanism for managing MMIO address spaces. This section will introduce them.
### Why is Automatic Allocation of MMIO Address Space Needed?
&emsp;&emsp;Since many devices on a computer require MMIO address space, and the demand for MMIO address space varies among different devices connected to each computer, manually specifying an MMIO address for each device type would lead to significant waste of virtual address space and increase system complexity. Moreover, we will need to handle exception handling functions for different virtual memory regions in the future. Therefore, we need a mechanism that can automatically allocate MMIO address space.
### What Features Does This Mechanism Provide?
- Allocates MMIO virtual address space ranging from 4K to 1GB for drivers
- Adds these virtual address spaces to VMA for unified management
- Allows batch release of these address spaces
### How Is This Mechanism Implemented?
&emsp;&emsp;This mechanism essentially uses the buddy system to maintain MMIO virtual address space. In `mm/mm.h`, the MMIO virtual address space range is specified, which starts at `0xffffa10000000000` and covers a 1TB space. In other words, the buddy system maintains this 1TB virtual address space for MMIO.
### Address Space Allocation Process
1. Initialize the MMIO-mapping module, creating 512 1GB `__mmio_buddy_addr_region` blocks in the MMIO buddy system.
2. The driver uses `mmio_create` to request address space allocation.
3. `mmio_create` aligns the requested address space size to the nearest power of 2 and allocates memory address space from the buddy.
4. Create a VMA and mark it as `VM_IO|VM_DONTCOPY`. MMIO VMA is only bound under `initial_mm` and will not be copied.
5. Allocation is complete.
Once the MMIO address space is allocated, it behaves like a regular VMA and can be operated using mmap series functions.
### MMIO Mapping Process
&emsp;&emsp;After obtaining the virtual address space, when we attempt to map memory into this address space, we can call the `mm_map` function to map this region.
&emsp;&emsp;This function performs special handling for MMIO VMA mapping. That is: it creates a `Page` structure and the corresponding `anon_vma`. Then, it fills the corresponding physical address into the page table.
### Releasing MMIO Virtual Address Space
&emsp;&emsp;When a device is unmounted, the driver can call the `mmio_release` function to release the specified MMIO address space.
&emsp;&emsp;During the release process, `mmio_release` performs the following steps:
1. Remove the MMIO region's mapping from the page table.
2. Release the MMIO region's VMA.
3. Return the address space back to the MMIO buddy system.
## Buddy Algorithm for MMIO
### Definition of Buddy
&emsp;&emsp;Two memory blocks are considered buddy memory blocks if they satisfy the following three conditions:
1. The sizes of the two memory blocks are the same.
2. The memory addresses of the two memory blocks are contiguous.
3. The two memory blocks are derived from the same larger block of memory.
### Buddy Algorithm
&emsp;&emsp;The buddy algorithm is used to manage and organize the allocation and recycling of large contiguous memory blocks to reduce external fragmentation during system runtime. In the buddy system, each memory block size is $2^n$ bytes. In DragonOS, the buddy system memory pool maintains a total of 1TB of contiguous storage space, with the largest memory block size being $1G$ (i.e., $2^{30}B$) and the smallest memory block size being $4K$ (i.e., $2^{12}B$).
&emsp;&emsp;The core idea of the buddy algorithm is that when an application requests memory, it always allocates the smallest memory block larger than the requested size, and the allocated memory block size is $2^nB$. (e.g., if an application requests $3B$ of memory, there is no integer $n$ such that $2^n = 3$, and $3 \in [2^1, 2^2]$, so the system will allocate a $2^2B$ memory block to the application, and the memory request is successfully completed.)
&emsp;&emsp;What if there is no such "suitable" memory block in the buddy system? The system will first look for a larger memory block. If found, it will split the larger memory block into suitable memory blocks to allocate to the application. (e.g., if an application requests $3B$ of memory, and the system's smallest memory block larger than $3B$ is $16B$, then the $16B$ block will be split into two $8B$ blocks. One is placed back into the memory pool, and the other is further split into two $4B$ blocks. One of the $4B$ blocks is placed back into the memory pool, and the other is allocated to the application. Thus, the memory request is successfully completed.)
&emsp;&emsp;If the system cannot find a larger memory block, it will attempt to merge smaller memory blocks until the required size is met. (e.g., if an application requests $3B$ of memory, and the system checks the memory pool and finds only two $2B$ memory blocks, the system will merge these two $2B$ blocks into a $4B$ block and allocate it to the application. Thus, the memory request is successfully completed.)
&emsp;&emsp;Finally, if the system cannot find a large enough memory block and is unable to successfully merge smaller blocks, it will notify the application that there is not enough memory to allocate.
### Data Structures of the Buddy Algorithm
```
MmioBuddyMemPool
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ pool_start_addr │
│ │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ pool_size │
│ │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ │
│ free_regions │
│ │
│ ┌────────────┐ │
│ │ │ ┌───────┐ ┌────────┐ │
│ │ ┌────────┬─┼────►│ ├────►│ │ │
│ │ │ list │ │ │ vaddr │ │ vaddr │ │
│ │ │ │◄├─────┤ │◄────┤ │ │
│ MmioFreeRegionList├────────┤ │ └───────┘ └────────┘ │
│ │ │num_free│ │ │
│ │ └────────┘ │ MmioBuddyAddrRegion │
│ MMIO_BUDDY_MIN_EXP - 12 │ 0 │ │
│ ├────────────┤ │
│ │ 1 │ │
│ ├────────────┤ │
│ │ 2 │ │
│ ├────────────┤ │
│ │ 3 │ │
│ ├────────────┤ │
│ │ ... │ │
│ ├────────────┤ │
│ │ ... │ │
│ ├────────────┤ │
│ MMIO_BUDDY_MAX_EXP - 12 │ 18 │ │
│ └────────────┘ │
│ │
│ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
```rust
/// 最大的内存块为1G，其幂为30
const MMIO_BUDDY_MAX_EXP: u32 = PAGE_1G_SHIFT;
/// 最小的内存块为4K，其幂为12
const MMIO_BUDDY_MIN_EXP: u32 = PAGE_4K_SHIFT;
/// 内存池数组的大小为18
const MMIO_BUDDY_REGION_COUNT: u32 = MMIO_BUDDY_MAX_EXP - MMIO_BUDDY_MIN_EXP + 1;
/// buddy内存池
pub struct MmioBuddyMemPool {
/// 内存池的起始地址
pool_start_addr: u64,
/// 内存池大小：初始化为1TB
pool_size: u64,
/// 空闲内存块链表数组
/// MMIO_BUDDY_REGION_COUNT = MMIO_BUDDY_MAX_EXP - MMIO_BUDDY_MIN_EXP + 1
free_regions: [SpinLock<MmioFreeRegionList>; MMIO_BUDDY_REGION_COUNT as usize],
}
/// 空闲内存块链表结构体
pub struct MmioFreeRegionList {
/// 存储了空闲内存块信息的结构体的链表
list: LinkedList<Box<MmioBuddyAddrRegion>>,
/// 当前链表空闲块的数量
num_free: i64,
}
/// mmio伙伴系统内部的地址区域结构体
pub struct MmioBuddyAddrRegion {
/// 内存块的起始地址
vaddr: u64,
}
```
### Design Philosophy
&emsp;&emsp;In DragonOS, the `MmioBuddyMemPool` structure is used as the data structure for the buddy (for convenience of expression, the buddy algorithm is referred to as buddy) memory pool. It records the starting address (pool_start_addr) of the memory pool and the total size of memory blocks in the memory pool (pool_size). It also maintains a bidirectional linked list array (free_regions) of size `MMIO_BUDDY_REGION_COUNT`. Each linked list in `free_regions` maintains several free memory blocks (MmioBuddyAddrRegion).
&emsp;&emsp;The index of `free_regions` is related to the size of the memory block. Since each memory block size is $2^{n}$ bytes, we can let $exp = n$. The conversion formula between index and exp is as follows: $index = exp - 12$. For example, a memory block of size $2^{12}$ bytes has $exp = 12$, and using the above formula, we get $index = 12 - 12 = 0$, so this memory block is stored in `free_regions[0].list`. Through this conversion formula, each time we take or release a memory block of size $2^n$, we only need to operate on `free_regions[n -12]`. In DragonOS, the largest memory block size in the buddy memory pool is $1G = 2^{30} bytes$, and the smallest is $4K = 2^{12} bytes$, so $index \in [0, 18]$.
&emsp;&emsp;As a memory allocation mechanism, the buddy serves all processes. To solve the problem of synchronizing the linked list data in free_regions among different processes, the linked list type in `free_regions` uses a SpinLock (denoted as {ref}`自旋锁 <_spinlock_doc_spinlock>`) to protect the free memory block linked list (MmioFreeRegionList). `MmioFreeRegionList` encapsulates a linked list (list) that actually stores information about free memory blocks and the corresponding list length (num_free). With the use of a spinlock, only one process can modify a particular linked list at the same time, such as taking elements from the list (memory allocation) or inserting elements into the list (memory release).
&emsp;&emsp;The element type in `MmioFreeRegionList` is the `MmioBuddyAddrRegion` structure, which records the starting address (vaddr) of the memory block.
### Internal APIs of the Buddy Algorithm
**P.S. The following functions are all members of the MmioBuddyMemPool structure. A global reference of type MmioBuddyMemPool has already been created in the system, denoted as `MMIO_POOL`. To use the following functions, please use them in the form of `MMIO_POOL.xxx()`, which does not require passing self.**
| **Function Name** | **Description** |
|:----------------------------------------------------------------- |:--------------------------------------------------------- |
| __create_region(&self, vaddr) | Pass the virtual address to create a new memory block address structure |
| __give_back_block(&self, vaddr, exp) | Return the memory block at address vaddr with exponent exp back to the buddy |
| __buddy_split(&self, region, exp, list_guard) | Split the given memory block of size $2^{exp}$ into two and insert the memory blocks of size $2^{exp-1}$ into the list |
| __query_addr_region(&self, exp, list_guard) | Request a memory block of size $2^{exp}$ from the buddy |
| mmio_buddy_query_addr_region(&self, exp) | A wrapper for query_addr_region, **please use this function instead of __query_addr_region** |
| __buddy_add_region_obj(&self, region, list_guard) | Add a memory block to the specified address space list |
| __buddy_block_vaddr(&self, vaddr, exp) | Calculate the virtual memory address of the buddy block based on the address and memory block size |
| __pop_buddy_block( &self, vaddr, exp, list_guard) | Find and pop the buddy block of the specified memory block |
| __buddy_pop_region( &self, list_guard) | Retrieve a memory region from the specified free list |
| __buddy_merge(&self, exp, list_guard, high_list_guard) | Merge all memory blocks of size $2^{exp}$ |
| __buddy_merge_blocks(&self, region_1, region_2, exp, high_list_guard) | Merge two **already removed from the list** memory blocks |
### External APIs of the Buddy Algorithm
| **Function Name** | **Description** |
| ----------------------------------------------- | ------------------------------------------- |
| __mmio_buddy_init() | Initialize the buddy system, **called in mmio_init(), do not call it arbitrarily** |
| __exp2index(exp) | Convert the exponent $exp$ of $2^{exp}$ to the index in the memory pool's array |
| mmio_create(size, vm_flags, res_vaddr, res_length) | Create an MMIO region with size aligned to the requested size, and bind its VMA to initial_mm |
| mmio_release(vaddr, length) | Cancel the mapping of MMIO at address vaddr with size length and return it to the buddy |

21
docs/locales/en/kernel/process_management/index.rst Normal file
View File

@ -0,0 +1,21 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/process_management/index.rst
- 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>`_
Process Management Module
====================================
.. toctree::
:maxdepth: 1
kthread
load_binary

30
docs/locales/en/kernel/process_management/kthread.md Normal file
View File

@ -0,0 +1,30 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/process_management/kthread.md
- Translation time: 2025-05-19 01:41:23
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# kthread Kernel Threads
&emsp;&emsp;The kernel thread module is implemented in `process/kthread.rs`, providing support for kernel threads and related functionalities. Kernel threads act as the "avatars" of the kernel, enhancing the system's parallelism and fault tolerance capabilities.
## Principles
&emsp;&emsp;Each kernel thread runs in kernel mode, executing its specific tasks.
&emsp;&emsp;The creation of a kernel thread is achieved by calling the `KernelThreadMechanism::create()` or `KernelThreadMechanism::create_and_run()` function, which sends a creation task to the `kthreadd` daemon thread. In other words, the creation of a kernel thread is ultimately handled by `kthread_daemon`.
&emsp;&emsp;After a kernel thread is created, it defaults to a sleeping state. To wake it up, the `ProcessManager::wakeup` function should be used.
&emsp;&emsp;When other kernel modules wish to stop a kernel thread, they can call the `KernelThreadMechanism::stop()` function to wait for the thread to exit, then obtain the return value and clean up the thread's PCB (Process Control Block).
&emsp;&emsp;Kernel threads should frequently check the result of `KernelThreadMechanism::should_stop()` to determine whether they should exit. When it is detected that the thread needs to exit, it can return a return code to terminate itself. (Note: resource cleanup is important)

30
docs/locales/en/kernel/process_management/load_binary.md Normal file
View File

@ -0,0 +1,30 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/process_management/load_binary.md
- Translation time: 2025-05-19 01:41:18
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Loader
## 1. Binary Program Loading
&emsp;&emsp;In this section, you will learn about the principles of the binary loader in DragonOS.
&emsp;&emsp;When DragonOS loads a binary program, it performs a "probe-load" process.
&emsp;&emsp;During the probe phase, DragonOS reads the file header and sequentially calls the probe functions of each binary loader to determine whether the binary program is suitable for that loader. If it is suitable, the loader will be used to load the program.
&emsp;&emsp;During the load phase, DragonOS uses the aforementioned loader to load the program. The loader will map the various segments of the binary program into memory and obtain the entry address of the binary program.
:::{note}
Currently, DragonOS does not support dynamic linking, so all binary programs are statically linked. And only the ELF loader is temporarily supported.
:::

202
docs/locales/en/kernel/sched/c_waiting.md Normal file
View File

@ -0,0 +1,202 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/c_waiting.md
- Translation time: 2025-05-19 01:43:09
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# APIs Related to "Waiting" (C Language)
:::{warning}
As the kernel evolves, we will gradually replace the C language waiting mechanism with the Rust language waiting mechanism. During this process, we will retain both the C and Rust waiting mechanisms to allow for comparison during development.
Once the timing is ripe, we will gradually remove the C language waiting mechanism.
:::
&emsp;&emsp; If several processes need to wait for an event to occur before they can be executed, a "waiting" mechanism is required to achieve process synchronization.
## I. wait_queue Waiting Queue
&emsp;&emsp; wait_queue is a process synchronization mechanism, known as "waiting queue" in Chinese. It can suspend the current process and wake them up when the time is ripe, by another process.
&emsp;&emsp; When you need to wait for an event to complete, using the wait_queue mechanism can reduce the overhead of process synchronization. Compared to overusing spinlocks and semaphores, or repeatedly calling usleep(1000) functions for synchronization, wait_queue is an efficient solution.
:::{warning}
The implementation of the wait_queue in `wait_queue.h` does not have an independent queue head and does not consider locking the wait_queue. Therefore, in later development, the queue head implementation in `wait_queue_head_t` was added, which is essentially a linked list plus a spinlock. It is compatible with the queue `wait_queue_node_t` in `wait_queue.h`. When you use `struct wait_queue_head` as the queue head, you can still use the functions to add nodes to the waiting queue.
:::
### Simple Usage
&emsp;&emsp; The usage of a waiting queue mainly includes the following parts:
- Creating and initializing a waiting queue
- Using the `wait_queue_sleep_on_` series of functions to suspend the current process. Processes that are suspended later will be placed at the end of the queue.
- Using the `wait_queue_wakeup()` function to wake up processes waiting in the waiting queue and add them to the scheduling queue
&emsp;&emsp; To use wait_queue, you need to `#include<common/wait_queue.h>`, and create a `wait_queue_node_t` type variable as the head of the waiting queue. This structure contains only two member variables:
```c
typedef struct
{
struct List wait_list;
struct process_control_block *pcb;
} wait_queue_node_t;
```
&emsp;&emsp; For the waiting queue, there is a good naming method:
```c
wait_queue_node_t wq_keyboard_interrupt_received;
```
&emsp;&emsp; This naming convention increases code readability and makes it easier to understand what the code is waiting for.
### Initializing the Waiting Queue
&emsp;&emsp; The function `wait_queue_init(wait_queue_node_t *wait_queue, struct process_control_block *pcb)` provides the functionality to initialize a wait_queue node.
&emsp;&emsp; When you initialize the queue head, you only need to pass the pointer to the wait_queue head node, and set the second parameter to NULL.
### Inserting a Node into the Waiting Queue
&emsp;&emsp; You can use the following functions to suspend the current process and insert it into the specified waiting queue. These functions have similar overall functions, but differ in some details.
| Function Name | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| wait_queue_sleep_on() | Suspends the current process and sets the suspension state to PROC_UNINTERRUPTIBLE |
| wait_queue_sleep_on_unlock() | Suspends the current process and sets the suspension state to PROC_UNINTERRUPTIBLE. After the current process is inserted into the waiting queue, it unlocks the given spinlock |
| wait_queue_sleep_on_interriptible() | Suspends the current process and sets the suspension state to PROC_INTERRUPTIBLE |
### Waking Up a Process from the Waiting Queue
&emsp;&emsp; You can use the `void wait_queue_wakeup(wait_queue_node_t * wait_queue_head, int64_t state);` function to wake up the first process in the specified waiting queue that has a suspension state matching the specified `state`.
&emsp;&emsp; If there are no matching processes, no process will be woken up, as if nothing happened.
------------------------------------------------------------
&emsp;&emsp;
&emsp;&emsp;
&emsp;&emsp;
## II. wait_queue_head Waiting Queue Head
&emsp;&emsp; The data structure is defined as follows:
```c
typedef struct
{
struct List wait_list;
spinlock_t lock; // 队列需要有一个自旋锁,虽然目前内部并没有使用,但是以后可能会用.
} wait_queue_head_t;
```
&emsp;&emsp; The usage logic of the waiting queue head is the same as the waiting queue itself, because it is also a node of the waiting queue (just with an additional lock). The functions of wait_queue_head are basically the same as those of wait_queue, except that they include the string \*\*\*\_with\_node\_\*\*\*.
&emsp;&emsp; Meanwhile, the wait_queue.h file provides many macros that can make your work easier.
### Provided Macros
| Macro | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| DECLARE_WAIT_ON_STACK(name, pcb) | Declare a wait_queue node on the stack, and bind the pcb-represented process to this node |
| DECLARE_WAIT_ON_STACK_SELF(name) | Declare a wait_queue node on the stack, and bind the current process (i.e., the process itself) to this node |
| DECLARE_WAIT_ALLOC(name, pcb) | Use `kzalloc` to declare a wait_queue node, and bind the pcb-represented process to this node. Remember to use kfree to release the space |
| DECLARE_WAIT_ALLOC_SELF(name) | Use `kzalloc` to declare a wait_queue node, and bind the current process (i.e., the process itself) to this node. Remember to use kfree to release the space |
### Creating a Waiting Queue Head
&emsp;&emsp; You can directly call the macro
```c
DECLARE_WAIT_QUEUE_HEAD(m_wait_queue_head); // 在栈上声明一个队列头变量
```
&emsp;&emsp; Or manually declare
```c
struct wait_queue_head_t m_wait_queue_head = {0};
wait_queue_head_init(&m_wait_queue_head);
```
### Inserting a Node into the Waiting Queue
| Function Name | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| wait_queue_sleep_with_node(wait_queue_head_t *head, wait_queue_node_t *wait_node) | Pass in a waiting queue node, and set the suspension state of the node to PROC_UNINTERRUPTIBLE |
| wait_queue_sleep_with_node_unlock(wait_queue_head_t *q, wait_queue_node_t *wait, void *lock) | Pass in a waiting queue node, suspend the process pointed to by the node's pcb, and set the suspension state to PROC_UNINTERRUPTIBLE. After the current process is inserted into the waiting queue, unlock the given spinlock |
| wait_queue_sleep_with_node_interriptible(wait_queue_head_t *q, wait_queue_node_t *wait) | Pass in a waiting queue node, suspend the process pointed to by the node's pcb, and set the suspension state to PROC_INTERRUPTIBLE |
### Waking Up a Process from the Waiting Queue
&emsp;&emsp; The `wait_queue_wakeup` function in `wait_queue.h` directly kfree's the wait_node node. For stack-based wait_node, you can choose `wait_queue_wakeup_on_stack(wait_queue_head_t *q, int64_t state)` to wake up the queue head node in the queue.
------------------------------------------------------------
&emsp;&emsp;
&emsp;&emsp;
&emsp;&emsp;
## III. completion Completion Count
### Simple Usage
&emsp;&emsp; The usage of completion mainly includes the following parts:
- Declare a completion (can be on the stack, using kmalloc, or using an array)
- Use wait_for_completion to wait for the event to complete
- Use complete to wake up the waiting processes
&emsp;&emsp; Waiting operation
```c
void wait_fun() {
DECLARE_COMPLETION_ON_STACK(comp); // 声明一个completion
// .... do somethind here
// 大部分情况是你使用kthread_run()创建了另一个线程
// 你需要把comp变量传给这个线程, 然后当前线程就会等待他的完成
if (!try_wait_for_completion(&comp)) // 进入等待
wait_for_completion(&comp);
}
```
&emsp;&emsp; Completion operation
```c
void kthread_fun(struct completion *comp) {
// ...... 做一些事 .......
// 这里你确定你完成了目标事件
complete(&comp);
// 或者你使用complete_all
complete_all(&comp);
}
```
### More Usage
&emsp;&emsp; In the kernel/sched/completion.c folder, you can see several functions starting with __test__, which are test code for the completion module and cover most of the completion functions. You can refer to these functions to learn how to use them.
### Initializing Completion
&emsp;&emsp; The function `completion_init(struct completion *x)` provides the functionality to initialize a completion. When you use `DECLARE_COMPLETION_ON_STACK` to create (on the stack), it will be automatically initialized.
### Completion-related wait series functions
| Function Name | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| wait_for_completion(struct completion *x) | Suspends the current process and sets the suspension state to PROC_UNINTERRUPTIBLE. |
| wait_for_completion_timeout(struct completion *x, long timeout) | Suspends the current process and sets the suspension state to PROC_UNINTERRUPTIBLE. After waiting for timeout time (jiffies time slice), the process is automatically awakened. |
| wait_for_completion_interruptible(struct completion *x) | Suspends the current process and sets the suspension state to PROC_INTERRUPTIBLE. |
| wait_for_completion_interruptible_timeout(struct completion *x, long timeout) | Suspends the current process and sets the suspension state to PROC_INTERRUPTIBLE. After waiting for timeout time (jiffies time slice), the process is automatically awakened. |
| wait_for_multicompletion(struct completion x[], int n)| Suspends the current process and sets the suspension state to PROC_UNINTERRUPTIBLE. (Waiting for the completion of the array's completions) |
### Completion-related complete series functions
| Function Name | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| complete(struct completion *x) | Indicates that an event has been completed, and wakes up one process from the waiting queue |
| complete_all(struct completion *x) | Indicates that the events related to this completion are marked as permanently completed, and wakes up all processes in the waiting queue |
### Other Functions for Querying Information
| Function Name | Explanation |
| ----------------------------------- | ---------------------------------------------------------------- |
| completion_done(struct completion *x) | Checks if the completion's done variable is greater than 0. If it is, returns true; otherwise, returns false. Adding this function before waiting may accelerate the process? (Not tested experimentally yet, needs further verification) |
| try_wait_for_completion(struct completion *x) | Checks if the completion's done variable is greater than 0. If it is, returns true (and decrements done by 1); otherwise, returns false. Adding this function before waiting may accelerate the process? (This function has the same logic as `completion_done`, but actively decrements the completion's done variable by 1) |

43
docs/locales/en/kernel/sched/cfs.md Normal file
View File

@ -0,0 +1,43 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/cfs.md
- Translation time: 2025-05-19 01:41:13
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# APIs Related to the Completely Fair Scheduler
&emsp;&emsp; CFS (Completely Fair Scheduler), as the name suggests, is a fully fair scheduler. CFS is one of the mainline schedulers and is also one of the most typical O(1) schedulers.
## Structure Introduction
- `_translated_label__`CompletelyFairScheduler``
&emsp;&emsp; ``CompletelyFairScheduler``实现了``Scheduler``trait，他是完全调度算法逻辑的主要实施者。
- ``FairSchedEntity``
- **重要字段**
- ``cfs_rq``: 它指向了自己所在的完全公平调度队列。
- ``my_cfs_rq``: 为一个``Option``变量，当该实体作为一个单独进程时，这个值为``None``，但是若这个实体为一个组，那这个变量必需为这个组内的私有调度队列。这个``cfs_rq``还可以继续往下深入，就构成了上述的树型结构。
- ``pcb``: 它指向了当前实体对应的``PCB``，同样，若当前实体为一个组，则这个``Weak``指针不指向任何值。
&emsp;&emsp;``FairSchedEntity``是完全公平调度器中最重要的结构体，他代表一个实体单位，它不止表示一个进程，它还可以是一个组或者一个用户，但是它在cfs队列中所表示的就单单是一个调度实体。这样的设计可以为上层提供更多的思路，比如上层可以把不同的进程归纳到一个调度实体从而实现组调度等功能而不需要改变调度算法。
&emsp;&emsp;在cfs中，整体的结构是**一棵树**，每一个调度实体作为``cfs_rq``中的一个节点，若该调度实体不是单个进程（它可能是一个进程组），则在该调度实体中还需要维护一个自己的``cfs_rq``，这样的嵌套展开后，每一个叶子节点就是一个单独的进程。需要理解这样一棵树，**在后续文档中会以这棵树为核心讲解**。
&emsp;&emsp;该结构体具体的字段意义请查阅源代码。这里提及几个重要的字段：
- ``CfsRunQueue``
&emsp;&emsp;``CfsRunQueue``完全公平调度算法中管理``FairSchedEntity``的队列，它可以挂在总的``CpuRunQueue``下，也可以作为子节点挂在``FairSchedEntity``上，详见上文``FairSchedEntity``。
- **重要字段**
- ``entities``: 存储调度实体的红黑树
- ``current`_en`: The entity currently running

79
docs/locales/en/kernel/sched/core.md Normal file
View File

@ -0,0 +1,79 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/core.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)
:::
# APIs Related to Process Scheduler
&emsp;&emsp; This section defines the APIs related to process scheduling in DragonOS, which are the interfaces for the system to perform process scheduling. It also abstracts the Scheduler trait to allow specific scheduler implementations.
## Introduction to Scheduler
&emsp;&emsp; Generally, a system handles multiple requests at the same time, but its resources are limited and prioritized. Scheduling is the method used to coordinate each request's usage of these resources.
## Overall Architecture
&emsp;&emsp; The entire scheduling subsystem is organized in a **tree structure**, with each CPU managing such a tree. Each CPU's ``CpuRunQueue``即可以理解为树的根节点。每个``CpuRunQueue``下会管理着不同调度策略的子树，根据不同的调度策略深入到对应子树中实施调度。大体结构如下：
- CpuRunQueue
- Cfs
- CfsRunQueue
- FairSchedEntity
- CfsRunQueue
- ...（嵌套）
- Rt
- ...
- Idle
- ...
- RR
- ...
- ...
&emsp;&emsp;基于这个结构，调度子系统能够更轻松地解耦以及添加其他调度策略。
&emsp;&emsp;
## 重要结构
- ``Scheduler:``
&emsp;&emsp;``Scheduler``是各个调度算法提供给上层的接口，实现不同的调度算法，只需要向外提供这样一组接口即可。
- ``CpuRunQueue:``
&emsp;&emsp;``CpuRunQueue``为总的CPU运行队列，他会根据不同的调度策略来进行调度。他作为调度子系统的根节点来组织调度。
- **重要字段**
- ``lock``: 过程锁，因为在深入到具体调度策略后的调度过程中还会需要访问``CpuRunQueue``中的信息，在cfs中保存了``CpuRunQueue``对象，我们需要确保在整体过程上锁后，子对象中不需要二次加锁即可访问，所以过程锁比较适合这个场景，若使用对象锁，则在对应调度策略中想要访问``CpuRunQueue``中的信息时需要加锁，但是最外层已经将``CpuRunQueue``对象上锁，会导致内层永远拿不到锁。对于该字段，详见[CpuRunQueue的self_lock方法及其注释](https://code.dragonos.org.cn/xref/DragonOS/kernel/src/sched/mod.rs?r=dd8e74ef0d7f91a141bd217736bef4fe7dc6df3d#360)。
- ``cfs``: Cfs调度器的根节点，往下伸展为一棵子树，详见完全公平调度文档。
- ``current``: 当前在CPU上运行的进程。
- ``idle``: 当前CPU的Idle进程。
## 调度流程
&emsp;&emsp;一次有效的调度分两种情况，第一是主动调用``__schedule``或者``schedule``函数进行调度，第二是通过时钟中断，判断当前运行的任务时间是否到期。
- **主动调度**
- ``__schedule``和``schedule``函数：
- ``__schedule``:真正执行调度。会按照当前调度策略来选择下一个任务执行。
- ``schedule``: ``__schedule``的上层封装，它需要该任务在内核中的所有资源释放干净才能进行调度，即判断当前进程的``preempt_count``是否为0，若不为0则会**panic**。
- 参数：这两个函数都需要提供一个参数：``SchedMode``。用于控制此次调度的行为,可选参数主要有以下两个：
- ``SchedMode::SM_NONE``: 标志当前进程没有被抢占而是主动让出，他**不会**被再次加入队列，直到有其他进程主动唤醒它，这个标志位主要用于信号量、等待队列以及一些主动唤醒场景的实现。
- ``SchedMode::SM_PREEMPT``:标志当前是被**抢占**运行的，他**会**再次被加入调度队列等待下次调度，通俗来说：它是被别的进程抢占了运行时间，有机会运行时他会继续执行。
- **时钟调度**
&emsp;&emsp;时钟中断到来的时候，调度系统会进行更新，包括判断是否需要下一次调度。以下为主要的函数调用栈：
- ``LocalApicTimer::handle_irq``: 中断处理函数
- ``ProcessManager::update_process_times``: 更新当前进程的时钟信息（统计运行时等）
- ``scheduler_tick``: 调度子系统tick入口
- ``CompletelyFairScheduler::tick``: 以cfs为例，此为cfs调度算法的tick入口
- ``CfsRunQueue::entity_tick``: 对所有调度实体进行tick
- ``CfsRunQueue::update_current``: 更新当前运行任务的运行时间及判断是否到期
- ``CfsRunQueue::account_cfs_rq_runtime``: 计算当前队列的运行时间
- ``CpuRunQueue::resched_current``: 若上一步计算的时间超时则到这一步，这里会设置进程标志为``NEED_SCHEDULE``.
- 退出中断：退出中断时检查当前进程是否存在标志位``NEED_SCHEDULE``，若存在则调用``__schedule`` performs scheduling.

28
docs/locales/en/kernel/sched/index.rst Normal file
View File

@ -0,0 +1,28 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/index.rst
- Translation time: 2025-05-19 01:41:10
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
====================================
DragonOS Scheduling
====================================
This is the documentation related to process scheduling in DragonOS.
.. toctree::
:maxdepth: 1
c_waiting
rust_waiting
core
cfs
rt
kernel_timer

184
docs/locales/en/kernel/sched/kernel_timer.md Normal file
View File

@ -0,0 +1,184 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/kernel_timer.md
- Translation time: 2025-05-19 01:41:48
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Kernel Timer
## 1. Introduction
&emsp;&emsp;The kernel timer is a type of timer within the kernel. The working mechanism of the kernel timer is: adding the timer to a queue and setting the expiration time for each timer. When the timer expires, the function corresponding to the timer is executed.
## 2. Design Concept
&emsp;&emsp;The timer type is a structure of `Timer`, and `Timer` is composed of `SpinLock<InnerTimer>`. A global queue `TIMER_LIST` with element type `Arc<Timer>` is used to store the timers created by the system. When creating a timer, you should call `Timer::new(timer_func,expire_jiffies)`, where timer_func is the function to be executed by the timer, expire_jiffies is the expiration time of the timer, and the type of `timer_func` parameter is a structure that implements the `TimerFunction` characteristic. After creating the timer, you should use `Timer::activate()` to insert the timer into `TIMER_LIST`.
&emsp;&emsp;**If you only want the current PCB to sleep for a certain period, you should call `schedule_timeout(timeout)`, and timeout specifies the duration of the PCB sleep.**
## 3. Features That the Timer Should Implement
&emsp;&emsp;The function to be executed by the timer should implement the `TimerFunction` characteristic, and its definition is as follows:
```rust
/// 定时器要执行的函数的特征
pub trait TimerFunction: Send + Sync {
fn run(&mut self);
}
```
&emsp;&emsp;A typical implementation method is: creating a zero-length structure, implementing the `TimerFunction` characteristic, and then implementing the operation to be performed by the timer in the `run` function.
## 4. Timer API
### 4.1. Timer API
#### 4.1.1. Create a Timer
```rust
pub fn new(timer_func: Box<dyn TimerFunction>, expire_jiffies: u64) -> Arc<Self>
```
**Parameters**
- timer_func: A structure corresponding to the function that the timer needs to execute, which implements the `TimerFunction` characteristic
- expire_jiffies: The expiration time of the timer (unit: **jiffies**)
**Return**
- Pointer to the timer structure
#### 4.1.2. Insert the Timer into the Timer List
```rust
pub fn activate(&self)
```
### 4.2. Other APIs
&emsp;&emsp;**If you want to use the following functions in a .c module, please add rs_ before the function name.**
#### 4.2.1. Make the Process Sleep for a Certain Period
```rust
pub fn schedule_timeout(mut timeout: i64) -> Result<i64, SystemError>
```
**Function**
&emsp;&emsp;Make the process sleep for timeout jiffies
**Parameters**
- timeout: The time to sleep (unit: **jiffies**)
**Return Value**
- Ok(i64): Remaining time to sleep (unit: **jiffies**)
- Err(SystemError): Error code
#### 4.2.2. Get the Expiration Time of the First Timer in the Queue
```rust
pub fn timer_get_first_expire() -> Result<u64, SystemError>
```
**Function**
&emsp;&emsp;Get the expiration time of the first timer in the queue, i.e., the expiration time of the earliest expiring timer
**Return Value**
- Ok(i64): Expiration time of the earliest expiring timer (unit: **jiffies**)
- Err(SystemError): Error code
#### 4.2.3. Get the Current System Time
```rust
pub fn clock() -> u64
```
**Function**
&emsp;&emsp;Get the current system time (unit: **jiffies**)
#### 4.2.4. Calculate the Timer Time Slice Corresponding to the Next n Milliseconds or Microseconds
##### 4.2.4.1. Milliseconds
```rust
pub fn next_n_ms_timer_jiffies(expire_ms: u64) -> u64
```
**Function**
&emsp;&emsp;Calculate the timer time slice corresponding to the next n **milliseconds**
**Parameters**
- expire_ms: n milliseconds
**Return Value**
&emsp;&emsp;The corresponding timer time slice (unit: **milliseconds**)
##### 4.2.4.2. Microseconds
```rust
pub fn next_n_us_timer_jiffies(expire_us: u64) -> u64
```
**Function**
&emsp;&emsp;Calculate the timer time slice corresponding to the next n **microseconds**
**Parameters**
- expire_ms: n microseconds
**Return Value**
&emsp;&emsp;The corresponding timer time slice (unit: **microseconds**)
## 5. Creating a Timer Instance
```rust
struct TimerExample {
/// 结构体的成员对应函数的形参
example_parameter: i32,
}
impl TimerExample {
pub fn new(para: i32) -> Box<TimerExample> {
return Box::new(TimerExample {
example_parameter: para,
});
}
}
/// 为结构体实现TimerFunction特性
impl TimerFunction for TimerExample {
/// TimerFunction特性中的函数run
fn run(&mut self) {
// 定时器需要执行的操作
example_func(self.example_parameter);
}
}
fn example_func(para: i32) {
println!("para is {:?}", para);
}
fn main() {
let timer_example: Box<TimerExample> = TimerExample::new(1);
// 创建一个定时器
let timer: Arc<Timer> = Timer::new(timer_example, 1);
// 将定时器插入队列
timer.activate();
}
```

71
docs/locales/en/kernel/sched/rt.md Normal file
View File

@ -0,0 +1,71 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/rt.md
- Translation time: 2025-05-19 01:41:17
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# APIs Related to Real-Time Process Scheduler
&emsp;&emsp; RT (Real-Time Scheduler), real-time scheduler. Real-time scheduling is a method of allocating CPU resources to complete real-time processing tasks.
&emsp;&emsp; In DragonOS, processes are divided into two categories: "real-time processes" and "normal processes". Real-time processes have higher priority than normal processes. If there are real-time processes in the current system's execution queue, the RT scheduler will prioritize selecting a real-time process. If there are multiple real-time processes in the queue, the scheduler will select the one with the highest priority to execute.
## 1. Introduction to RTQueue
&emsp;&emsp; RTQueue is a scheduling queue used to store real-time processes with a state of running. Each CPU maintains its own RTQueue, and it primarily uses Vec as the main storage structure to implement this.
### 1.1 Main Functions
1. enqueue(): Add the PCB to the queue
2. dequeue(): Remove the PCB from the queue
## 2. Introduction to SchedulerRT
&emsp;&emsp; RT Scheduler class, which mainly implements the initialization and scheduling function of the RT scheduler.
### 2.1 Main Functions
1. pick_next_task_rt(): Get the first PCB that needs to be executed on the current CPU
2. sched(): Implementation of the sched() function for the Scheduler trait. This function handles the logic for scheduling real-time processes and returns the PCB to be executed next. If no suitable PCB is found, it returns None.
3. enqueue(): Also an implementation of the sched() function for the Scheduler trait, which adds a PCB to the scheduler's scheduling queue
### 2.2 Kernel Scheduling Policies
&emsp;&emsp; Currently, the main scheduling policies in DragonOS are SCHED_NORMAL policy | SCHED_FIFO policy | SCHED_RT policy. The specific scheduling policies are as follows:
1. SCHED_NORMAL policy:
SCHED_NORMAL is an "absolute fair scheduling policy", and processes using this policy are scheduled using CFS.
2. SCHED_FIFO policy:
SCHED_FIFO is a "real-time process scheduling policy", which is a first-in-first-out scheduling strategy. This policy does not involve the CPU time slice mechanism. Without a higher-priority process, the process can only wait for other processes to release CPU resources. In the SCHED_FIFO policy, the running time of the process scheduled by the scheduler is not limited and can run for an arbitrary length of time.
3. SCHED_RR policy:
SCHED_RR is a "real-time process scheduling policy", which uses a time-slice rotation mechanism. The time_slice of the corresponding process will decrease during execution. Once the process uses up its CPU time slice, it will be added to the execution queue of the same priority on the same CPU. At the same time, the CPU resource is released, and the CPU usage will be allocated to the next process to execute.
## 3. Q&A
&emsp;&emsp; Several commonly used methods
1. How to create a real-time process
```c
struct process_control_block *pcb_name = kthread_run_rt(&fn_name, NULL, "test create rt pcb");
```
Where kthread_run_rt is a macro for creating a kernel real-time thread
2. Meaning of fields related to real-time processes in the PCB
1. policy: The scheduling policy of the real-time process, currently SCHED_FIFO and SCHED_RR
2. priority: The priority of the real-time process, ranging from 0 to 99. The larger the number, the higher the priority
3. rt_time_slice: The time slice of the real-time process. The default is 100, which decreases as the CPU runs. When rt_time_slice reaches 0, the time slice is reset to its initial value, and the process is added to the execution queue
3. How real-time processes are stored in the queue
- Currently, Vec is used to store the processes. Due to the specific implementation logic, the enqueue and dequeue operations are performed at the end of the queue. Therefore, the following phenomenon may occur: when there are multiple real-time processes with the same priority waiting to run, a starvation phenomenon may occur. That is, the process that ran out of its time slice will be executed next, causing starvation among the processes with the same priority waiting.
4. Todo
1. Use a doubly linked list (or other methods) to store the queue of real-time processes to solve the above starvation issue
2. Currently, the real-time scheduling is for a single CPU. It needs to be implemented for multiple CPUs
3. Implement the bandwidth allocation ratio between real-time processes and normal processes
4. Achieve load balancing between multiple CPUs

94
docs/locales/en/kernel/sched/rust_waiting.md Normal file
View File

@ -0,0 +1,94 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/sched/rust_waiting.md
- Translation time: 2025-05-19 01:41:21
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# APIs Related to "Waiting" (Rust Language)
&emsp;&emsp; If several processes need to wait for a certain event to occur before they can be executed, a "waiting" mechanism is required to achieve process synchronization.
## 1. WaitQueue Waiting Queue
&emsp;&emsp; WaitQueue is a process synchronization mechanism, known as "Waiting Queue" in Chinese. It can suspend the current process and, when the time is ripe, another process can wake them up.
&emsp;&emsp; When you need to wait for an event to complete, using the WaitQueue mechanism can reduce the overhead of process synchronization. Compared to abusing spinlocks and semaphores, or repeatedly using functions like usleep(1000), WaitQueue is an efficient solution.
### 1.1 Using WaitQueue
&emsp;&emsp; Using WaitQueue is very simple, requiring just three steps:
1. Initialize a WaitQueue object.
2. Call the API related to suspending the current process and suspend it.
3. When the event occurs, another process calls the API related to waking up the WaitQueue to wake up a process.
&emsp;&emsp; Here is a simple example:
### 1.1.1 Initializing a WaitQueue Object
&emsp;&emsp; Initializing a WaitQueue object is very simple; you just need to call `WaitQueue::INIT`.
```rust
let mut wq = WaitQueue::INIT;
```
### 1.1.2 Suspending the Process
&emsp;&emsp; You can suspend the current process as follows:
```rust
wq.sleep();
```
&emsp;&emsp; The current process will be suspended until another process calls `wq.wakeup()`.
### 1.1.3 Waking Up the Process
&emsp;&emsp; You can wake up a process as follows:
```rust
// 唤醒等待队列头部的进程（如果它的state & PROC_INTERRUPTIBLE 不为0）
wq.wakeup(PROC_INTERRUPTIBLE);
// 唤醒等待队列头部的进程（如果它的state & PROC_UNINTERRUPTIBLE 不为0）
wq.wakeup(PROC_UNINTERRUPTIBLE);
// 唤醒等待队列头部的进程（无论它的state是什么）
wq.wakeup((-1) as u64);
```
### 1.2 APIs
### 1.2.1 Suspending the Process
&emsp;&emsp; You can use the following functions to suspend the current process and insert it into the specified waiting queue. These functions have similar overall functionality, but differ in some details.
| Function Name | Explanation |
| --------------------------------------- | ---------------------------------------------------------------- |
| sleep() | Suspend the current process and set its state to `PROC_INTERRUPTIBLE` |
| sleep_uninterruptible() | Suspend the current process and set its state to `PROC_UNINTERRUPTIBLE` |
| sleep_unlock_spinlock() | Suspend the current process and set its state to `PROC_INTERRUPTIBLE`. After inserting the current process into the waiting queue, unlock the given spinlock |
| sleep_unlock_mutex() | Suspend the current process and set its state to `PROC_INTERRUPTIBLE`. After inserting the current process into the waiting queue, unlock the given Mutex |
| sleep_uninterruptible_unlock_spinlock() | Suspend the current process and set its state to `PROC_UNINTERRUPTIBLE`. After inserting the current process into the waiting queue, unlock the given spinlock |
| sleep_uninterruptible_unlock_mutex() | Suspend the current process and set its state to `PROC_UNINTERRUPTIBLE`. After inserting the current process into the waiting queue, unlock the given Mutex |
### 1.2.2 Waking Up the Process
&emsp;&emsp; You can use the `wakeup(state)` function to wake up the first process in the waiting queue. If the process's state, after performing a bitwise AND operation with the given state, results in a non-zero value, it will be woken up.
&emsp;&emsp; Return value: Returns `true` if a process is woken up, otherwise returns `false`.
### 1.2.3 Other APIs
| Function Name | Explanation |
| ------------- | ------------------ |
| len() | Returns the number of processes in the waiting queue |

23
docs/locales/en/kernel/syscall/index.rst Normal file
View File

@ -0,0 +1,23 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/syscall/index.rst
- Translation time: 2025-05-19 01:41:08
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
.. _translated_label__syscall_en:
System Calls
====================================
.. toctree::
:maxdepth: 1
:caption: Contents
syscall_table

107
docs/locales/en/kernel/syscall/syscall_table.rst Normal file
View File

@ -0,0 +1,107 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/syscall/syscall_table.rst
- Translation time: 2025-05-19 01:41:32
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
System Call Table Implementation Plan
=====================================
.. note::
Author: longjin <longjin@dragonos.org>
Date: 2025/05/13
Overview
--------
.. mermaid::
:align: center
:caption: System Call Table Architecture
classDiagram
class Syscall {
<<trait>>
+num_args() usize
+handle(args, from_user) Result<usize, SystemError>
+entry_format(args) Vec<FormattedSyscallParam>
}
class SyscallHandle {
+nr: usize
+inner_handle: &dyn Syscall
}
class SyscallTable {
-entries: [Option<&SyscallHandle>; 512]
+get(nr) Option<&dyn Syscall>
}
Syscall <|.. SysXXXXXXHandle
SyscallHandle "1" *-- "1" Syscall
SyscallTable "1" *-- "512" SyscallHandle
Compared to the original approach of dispatching system calls in a single large match statement, this approach uses a trait-based and system call table-based implementation. The main advantages include:
- Reduced stack memory usage: Avoids a single large function consuming excessive stack space
- Support for parameter printing: Through a unified parameter formatting interface
- Better extensibility: Adding new system calls does not require modifying the dispatch logic
Core Design
-----------
Syscall Trait
~~~~~~~~~~~~~
All system call handler functions must implement the `Syscall` trait:
.. code-block:: rust
pub trait Syscall: Send + Sync + 'static {
fn num_args(&self) -> usize;
fn handle(&self, args: &[usize], from_user: bool) -> Result<usize, SystemError>;
fn entry_format(&self, args: &[usize]) -> Vec<FormattedSyscallParam>;
}
- `num_args()`: Returns the number of arguments required by the system call
- `handle()`: Executes the actual system call handling
- `entry_format()`: Formats the parameters for debugging printing
SyscallHandle
~~~~~~~~~~~~~
The `SyscallHandle` struct associates a system call number with its handler:
.. code-block:: rust
pub struct SyscallHandle {
pub nr: usize, // System call number
pub inner_handle: &'static dyn Syscall, // Handler function
pub name: &'static str,
}
SyscallTable
~~~~~~~~~~~~
The `SyscallTable` manages all system calls:
- Fixed size of 512 entries
- Initialized at compile time
- Allows quick lookup of the handler function by system call number
Usage
-----
Implementing a System Call
~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Define the implementation of `Syscall` for the specific system call
2. Register the system call in the system call table
3. Load all registered system calls during system initialization

332
docs/locales/en/kernel/trace/eBPF.md Normal file
View File

@ -0,0 +1,332 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/trace/eBPF.md
- Translation time: 2025-05-19 01:41:41
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# eBPF
> Author: Chen Linfeng
>
> Email: chenlinfeng25@outlook.com
## Overview
eBPF is a revolutionary technology that originated from the Linux kernel. It allows sandboxed programs to run in privileged contexts (such as the operating system kernel). It is used to extend the kernel's functionality in a secure and efficient manner without modifying the kernel source code or loading kernel modules.
Historically, due to the kernel's privileged position in supervising and controlling the entire system, the operating system has been an ideal place for implementing observability, security, and networking features. At the same time, due to the kernel's core position and high requirements for stability and security, the kernel has been difficult to iterate quickly. Therefore, traditionally, the innovation speed at the operating system level has been slower compared to features implemented outside the operating system itself.
eBPF fundamentally changes this approach. By allowing sandboxed programs to run within the operating system, application developers can run eBPF programs to add additional functionality to the operating system at runtime. Then, with the help of JIT compilers and verification engines, the operating system ensures that these programs are as secure and efficient as natively compiled programs. This has sparked a wave of eBPF-based projects covering a wide range of use cases, including next-generation network implementations, observability, and security features.
## eBPF in DragonOS
Adding eBPF support to a new OS requires understanding the eBPF runtime process. Typically, eBPF needs user-space tools and kernel-related infrastructure to function properly. Since a new OS usually is compatible with Linux applications, this can further simplify the porting work of user-space tools. As long as the kernel implements the relevant system calls and features, it can work with existing tools to support eBPF.
## eBPF Execution Process
![image-20240909165945192](/kernel/trace/ebpf_flow.png)
As shown in the figure, the execution process of an eBPF program is divided into three main steps:
1. Source code -> Binary
1. Users can write eBPF programs in Python/C/Rust and compile the source code into a binary program using the relevant toolchain.
2. In this step, users need to reasonably use helper functions to enrich the functionality of the eBPF program.
2. Loading eBPF program
1. User-space tool libraries encapsulate the system call interfaces provided by the kernel to simplify the user's work. After preprocessing, user-space tools make system calls to request the kernel to load the eBPF program.
1. The kernel first verifies the eBPF program to check its correctness and legality, and also performs further processing on the program.
1. The kernel attaches the eBPF program to the kernel's mount points (kprobe/uprobe/trace_point) based on the user's request.
1. During kernel operation, when these mount points are triggered by specific events, the eBPF program is executed.
3. Data Interaction
1. eBPF programs can collect information from the kernel, and user tools can selectively retrieve this information.
2. eBPF programs can directly output information to a file, and user tools can read and parse the content of the file to obtain the information.
3. eBPF programs share and exchange data between the kernel and user space through Maps.
## User-space Support
There are many user-space eBPF tool libraries, such as C's libbpf, Python's bcc, and Rust's Aya. Overall, the processing flow of these tools is similar. DragonOS currently supports eBPF programs written with the [Aya](https://github.com/aya-rs/aya) framework. As an example, the user-space tool processing flow for Aya is as follows:
1. Provide helper functions and Map abstractions for eBPF usage, making it easier to implement eBPF programs.
2. Process the compiled eBPF program, call system calls to create Maps, and obtain corresponding file descriptors.
3. Update the values of Maps (.data) as needed.
4. Modify the relevant instructions of the eBPF program based on relocation information.
5. Handle bpf to bpf calls in the eBPF program according to the kernel version.
6. Load the eBPF program into the kernel.
7. Package system calls and provide a large number of functions to help access eBPF information and interact with the kernel.
DragonOS's support for the Aya library is not complete. By trimming the Aya library, we have implemented a smaller [tiny-aya](https://github.com/DragonOS-Community/tiny-aya). To ensure future compatibility with Aya, tiny-aya only modifies the core tool aya in Aya. Some functions have been disabled because the system calls or files they require are not yet implemented in DragonOS.
### Tokio
Aya requires an asynchronous runtime. With the addition of some system calls and fixes for some errors, DragonOS now supports a basic Tokio runtime.
### Using Aya to Create an eBPF Program
As described in the [official documentation](https://aya-rs.dev/book/start/development/) provided by Aya, users only need to install the corresponding Rust toolchain according to its process to create an eBPF project based on a template. Taking the current implementation of `syscall_ebf` as an example, this program counts the number of system calls and stores them in a HashMap.
```
├── Cargo.toml
├── README.md
├── syscall_ebpf
├── syscall_ebpf-common
├── syscall_ebpf-ebpf
└── xtask
```
The project structure in the user/app directory is as follows:
- `syscall_ebpf-ebpf` is the directory for implementing eBPF code, which will be compiled into bytecode.
- `syscall_ebpf-common` is a common library, convenient for information exchange between the kernel and user space.
- `syscall_ebpf` is the user-space program, responsible for loading the eBPF program and retrieving data generated by the eBPF program.
- `xtask` is a command-line tool, convenient for users to compile and run user-space programs.
To run user-space programs in DragonOS, the project created using the template cannot be used directly:
1. This project does not meet DragonOS's requirements for the structure of user programs, but this can be easily modified.
2. Because DragonOS's support for the Tokio runtime is not yet complete, the usage method needs to be slightly modified.
```
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
```
3. Because the support for Aya is not complete, the project's dependencies on aya and aya-log need to be replaced with the implementations in tiny-aya.
```
[dependencies]
aya = { git = "https://github.com/DragonOS-Community/tiny-aya.git" }
aya-log = { git = "https://github.com/DragonOS-Community/tiny-aya.git" }
```
With slight modifications, eBPF programs can be implemented using the existing tools of Aya.
## Kernel-space Support
Kernel-space support mainly consists of three parts:
1. kprobe implementation: located in directory `kernel/crates/kprobe`
2. rbpf runtime: located in directory `kernel/crates/rbpf`
3. System call support
4. Helper function support
### rbpf
Previously, rbpf was used to run some simple eBPF programs. To run more complex programs, it needs to be modified.
1. Add support for bpf to bpf calls: by adding new stack abstractions and saving and restoring necessary register data.
2. Disable unnecessary internal memory checks, which are usually handled by the kernel's verifier.
3. Add data structures with ownership to avoid limitations on lifetimes.
### System Calls
All eBPF-related system calls are concentrated in `bpf()`, and they are further distinguished by the parameter `cmd`. The current support is as follows:
```rust
pub fn bpf(cmd: bpf_cmd, attr: &bpf_attr) -> Result<usize> {
let res = match cmd {
// Map related commands
bpf_cmd::BPF_MAP_CREATE => map::bpf_map_create(attr),
bpf_cmd::BPF_MAP_UPDATE_ELEM => map::bpf_map_update_elem(attr),
bpf_cmd::BPF_MAP_LOOKUP_ELEM => map::bpf_lookup_elem(attr),
bpf_cmd::BPF_MAP_GET_NEXT_KEY => map::bpf_map_get_next_key(attr),
bpf_cmd::BPF_MAP_DELETE_ELEM => map::bpf_map_delete_elem(attr),
bpf_cmd::BPF_MAP_LOOKUP_AND_DELETE_ELEM => map::bpf_map_lookup_and_delete_elem(attr),
bpf_cmd::BPF_MAP_LOOKUP_BATCH => map::bpf_map_lookup_batch(attr),
bpf_cmd::BPF_MAP_FREEZE => map::bpf_map_freeze(attr),
// Program related commands
bpf_cmd::BPF_PROG_LOAD => prog::bpf_prog_load(attr),
// Object creation commands
bpf_cmd::BPF_BTF_LOAD => {
error!("bpf cmd {:?} not implemented", cmd);
return Err(SystemError::ENOSYS);
}
ty => {
unimplemented!("bpf cmd {:?} not implemented", ty)
}
};
res
}
```
Among these, the command for creating a Map is further细分 to determine the specific Map type. Currently, we have added support for general Maps:
```rust
bpf_map_type::BPF_MAP_TYPE_ARRAY
bpf_map_type::BPF_MAP_TYPE_PERCPU_ARRAY
bpf_map_type::BPF_MAP_TYPE_PERF_EVENT_ARRAY
bpf_map_type::BPF_MAP_TYPE_HASH
bpf_map_type::BPF_MAP_TYPE_PERCPU_HASH
bpf_map_type::BPF_MAP_TYPE_QUEUE
bpf_map_type::BPF_MAP_TYPE_STACK
bpf_map_type::BPF_MAP_TYPE_LRU_HASH
bpf_map_type::BPF_MAP_TYPE_LRU_PERCPU_HASH
bpf_map_type::BPF_MAP_TYPE_CPUMAP
| bpf_map_type::BPF_MAP_TYPE_DEVMAP
| bpf_map_type::BPF_MAP_TYPE_DEVMAP_HASH => {
error!("bpf map type {:?} not implemented", map_meta.map_type);
Err(SystemError::EINVAL)?
}
```
All Maps implement the defined interface, which is referenced from the Linux implementation:
```rust
pub trait BpfMapCommonOps: Send + Sync + Debug + CastFromSync {
/// Lookup an element in the map.
///
/// See https://ebpf-docs.dylanreimerink.nl/linux/helper-function/bpf_map_lookup_elem/
fn lookup_elem(&mut self, _key: &[u8]) -> Result<Option<&[u8]>> {
Err(SystemError::ENOSYS)
}
/// Update an element in the map.
///
/// See https://ebpf-docs.dylanreimerink.nl/linux/helper-function/bpf_map_update_elem/
fn update_elem(&mut self, _key: &[u8], _value: &[u8], _flags: u64) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Delete an element from the map.
///
/// See https://ebpf-docs.dylanreimerink.nl/linux/helper-function/bpf_map_delete_elem/
fn delete_elem(&mut self, _key: &[u8]) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// For each element in map, call callback_fn function with map,
/// callback_ctx and other map-specific parameters.
///
/// See https://ebpf-docs.dylanreimerink.nl/linux/helper-function/bpf_for_each_map_elem/
fn for_each_elem(&mut self, _cb: BpfCallBackFn, _ctx: *const u8, _flags: u64) -> Result<u32> {
Err(SystemError::ENOSYS)
}
/// Look up an element with the given key in the map referred to by the file descriptor fd,
/// and if found, delete the element.
fn lookup_and_delete_elem(&mut self, _key: &[u8], _value: &mut [u8]) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// perform a lookup in percpu map for an entry associated to key on cpu.
fn lookup_percpu_elem(&mut self, _key: &[u8], cpu: u32) -> Result<Option<&[u8]>> {
Err(SystemError::ENOSYS)
}
/// Get the next key in the map. If key is None, get the first key.
///
/// Called from syscall
fn get_next_key(&self, _key: Option<&[u8]>, _next_key: &mut [u8]) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Push an element value in map.
fn push_elem(&mut self, _value: &[u8], _flags: u64) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Pop an element value from map.
fn pop_elem(&mut self, _value: &mut [u8]) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Peek an element value from map.
fn peek_elem(&self, _value: &mut [u8]) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Freeze the map.
///
/// It's useful for .rodata maps.
fn freeze(&self) -> Result<()> {
Err(SystemError::ENOSYS)
}
/// Get the first value pointer.
fn first_value_ptr(&self) -> *const u8 {
panic!("value_ptr not implemented")
}
}
```
The system call that connects eBPF and kprobe is [`perf_event_open`](https://man7.org/linux/man-pages/man2/perf_event_open.2.html). This system call is very complex in Linux, so DragonOS does not implement it according to Linux. Currently, only two functions are supported:
```rust
match args.type_ {
// Kprobe
// See /sys/bus/event_source/devices/kprobe/type
perf_type_id::PERF_TYPE_MAX => {
let kprobe_event = kprobe::perf_event_open_kprobe(args);
Box::new(kprobe_event)
}
perf_type_id::PERF_TYPE_SOFTWARE => {
// For bpf prog output
assert_eq!(args.config, perf_sw_ids::PERF_COUNT_SW_BPF_OUTPUT);
assert_eq!(
args.sample_type,
Some(perf_event_sample_format::PERF_SAMPLE_RAW)
);
let bpf_event = bpf::perf_event_open_bpf(args);
Box::new(bpf_event)
}
}
```
- One of them, `PERF_TYPE_SOFTWARE`, is used to create software-defined events, and `PERF_COUNT_SW_BPF_OUTPUT` ensures that this event is used to collect the output of bpf.
- `PERF_TYPE_MAX` usually indicates the creation of kprobe/uprobe events, which is one of the ways users can use kprobe. Users can bind an eBPF program to this event.
Similarly, different events of perf also implement the defined interface:
```rust
pub trait PerfEventOps: Send + Sync + Debug + CastFromSync + CastFrom {
fn mmap(&self, _start: usize, _len: usize, _offset: usize) -> Result<()> {
panic!("mmap not implemented for PerfEvent");
}
fn set_bpf_prog(&self, _bpf_prog: Arc<File>) -> Result<()> {
panic!("set_bpf_prog not implemented for PerfEvent");
}
fn enable(&self) -> Result<()> {
panic!("enable not implemented");
}
fn disable(&self) -> Result<()> {
panic!("disable not implemented");
}
fn readable(&self) -> bool {
panic!("readable not implemented");
}
}
```
This interface is currently not stable.
### Helper Function Support
User-space tools communicate with the kernel through system calls to set up and exchange eBPF data. In the kernel, the execution of eBPF programs also requires the help of the kernel. A standalone eBPF program is not very useful, so it calls the kernel-provided `helper` functions to access kernel resources.
Most of the currently supported `helper` functions are related to Map operations:
```rust
/// Initialize the helper functions.
pub fn init_helper_functions() {
let mut map = BTreeMap::new();
unsafe {
// Map helpers::Generic map helpers
map.insert(1, define_func!(raw_map_lookup_elem));
map.insert(2, define_func!(raw_map_update_elem));
map.insert(3, define_func!(raw_map_delete_elem));
map.insert(164, define_func!(raw_map_for_each_elem));
map.insert(195, define_func!(raw_map_lookup_percpu_elem));
// map.insert(93,define_func!(raw_bpf_spin_lock);
// map.insert(94,define_func!(raw_bpf_spin_unlock);
// Map helpers::Perf event array helpers
map.insert(25, define_func!(raw_perf_event_output));
// Probe and trace helpers::Memory helpers
map.insert(4, define_func!(raw_bpf_probe_read));
// Print helpers
map.insert(6, define_func!(trace_printf));
// Map helpers::Queue and stack helpers
map.insert(87, define_func!(raw_map_push_elem));
map.insert(88, define_func!(raw_map_pop_elem));
map.insert(89, define_func!(raw_map_peek_elem));
}
BPF_HELPER_FUN_SET.init(map);
}
```

24
docs/locales/en/kernel/trace/index.rst Normal file
View File

@ -0,0 +1,24 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: kernel/trace/index.rst
- Translation time: 2025-05-19 01:41:20
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Kernel Tracing Mechanism
====================================
The kernel tracing mechanism consists of many functionalities, such as kprobe, uprobe, tracepoint, ftrace, and eBPF, which is used to extend the observability of the kernel. The kernel currently supports kprobe and eBPF. This chapter will introduce these two mechanisms.
.. toctree::
:maxdepth: 1
:caption: Contents
eBPF
kprobe

64
docs/locales/en/kernel/trace/kprobe.md Normal file
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/trace/kprobe.md
- Translation time: 2025-05-19 01:54:55
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# kprobe
> Author: Chen Linfeng
> Email: chenlinfeng25@outlook.com
## Overview
The Linux kprobes debugging technology is a lightweight kernel debugging technique specifically designed by kernel developers to facilitate tracking the execution status of kernel functions. Using kprobes technology, kernel developers can dynamically insert probe points in most specified functions of the kernel to collect the required debugging status information, with minimal impact on the original execution flow of the kernel.
The kprobes technology relies on hardware architecture support, mainly including CPU exception handling and single-step debugging mechanisms. The former is used to cause the program's execution flow to enter the user-registered callback function, while the latter is used for single-step execution of the probed instruction. It is worth noting that on some architectures, the hardware does not support the single-step debugging mechanism, which can be resolved through software simulation methods (such as RISC-V).
## kprobe Workflow
<img src="/kernel/trace/kprobe_flow.png" style="zoom: 67%;" alt="xxx"/>
1. After registering a kprobe, each registered kprobe corresponds to a kprobe structure, which records the location of the probe point and the original instruction at that location.
2. The location of the probe point is replaced with an exception instruction. When the CPU executes to this location, it will enter an exception state. On x86_64, the instruction is int3 (if the kprobe is optimized, the instruction is jmp).
3. When the exception instruction is executed, the system checks whether it is an exception installed by kprobe. If it is, the pre_handler of the kprobe is executed. Then, using the CPU's single-step debugging (single-step) feature, the relevant registers are set, and the next instruction is set to the original instruction at the probe point, returning from the exception state.
4. The system enters the exception state again. The previous step has set the single-step related registers, so the original instruction is executed and the system will enter the exception state again. At this point, the single-step is cleared, and the post_handler is executed, and the system safely returns from the exception state.
5. When unloading the kprobe, the original instruction at the probe point is restored.
The kernel currently supports x86 and riscv64. Since riscv64 does not have a single-step execution mode, we use the break exception to simulate it. When saving the probe point instruction, we additionally fill in a break instruction, allowing the execution of the original instruction to trigger the break exception again on the riscv64 architecture.
## kprobe Interfaces
```rust
pub fn register_kprobe(kprobe_info: KprobeInfo) -> Result<LockKprobe, SystemError>;
pub fn unregister_kprobe(kprobe: LockKprobe) -> Result<(), SystemError>;
impl KprobeBasic {
pub fn call_pre_handler(&self, trap_frame: &dyn ProbeArgs)
pub fn call_post_handler(&self, trap_frame: &dyn ProbeArgs)
pub fn call_fault_handler(&self, trap_frame: &dyn ProbeArgs)
pub fn call_event_callback(&self, trap_frame: &dyn ProbeArgs)
pub fn update_event_callback(&mut self, callback: Box<dyn CallBackFunc>)
pub fn disable(&mut self)
pub fn enable(&mut self)
pub fn is_enabled(&self) -> bool
pub fn symbol(&self) -> Option<&str>
}
```
- `call_pre_handler` Calls the user-defined callback function before the probe point instruction is executed.
- `call_post_handler` Calls the user-defined callback function after the probe point instruction has been executed in single-step mode.
- `call_fault_handler` Calls the user-defined callback function if the first two callback functions fail.
- `call_event_callback` Used to call eBPF-related callback functions, usually called in the same way as `call_post_handler` after the probe point instruction is executed in single-step mode.
- `update_event_callback` Used to update the callback function during runtime.
- `disable` and `enable` are used to dynamically disable the kprobe. After calling `disable`, the kprobe will not execute the callback function when triggered.
- `symbol` Returns the function name of the probe point.

32
docs/locales/en/userland/appdev/c-cpp-quick-start.md Normal file
View File

@ -0,0 +1,32 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: userland/appdev/c-cpp-quick-start.md
- Translation time: 2025-05-19 01:41:49
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Developing C/C++ Applications for DragonOS
## Compilation Environment
&emsp;&emsp;DragonOS has partial binary compatibility with Linux, so you can use the musl-gcc compiler from Linux. However, since DragonOS does not currently support dynamic linking, you need to add the compilation parameter `-static`.
For example, you can use the following command:
```shell
musl-gcc -static -o hello hello.c
```
to compile a hello.c file.
When porting existing programs, you may need to configure `CFLAGS`, `LDFLAGS`, and `CPPFLAGS` to ensure correct compilation. Please refer to the actual requirements.
## Configuring DADK
Please refer to: [Quick Start | DADK](https://docs.dragonos.org.cn/p/dadk/user-manual/quickstart.html)

24
docs/locales/en/userland/appdev/index.rst Normal file
View File

@ -0,0 +1,24 @@
.. note:: AI Translation Notice
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: userland/appdev/index.rst
- Translation time: 2025-05-19 02:13:34
- Translation model: `Qwen/Qwen3-8B`
Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
Application Development Documentation
===================================================
.. toctree::
:maxdepth: 1
:caption: Contents
rust-quick-start
c-cpp-quick-start
Quick Start to Package an Application to DragonOS Using DADK <https://docs.dragonos.org.cn/p/dadk/user-manual/quickstart.html>
DADK Complete Documentation <https://docs.dragonos.org.cn/p/dadk/>

51
docs/locales/en/userland/appdev/rust-quick-start.md Normal file
View File

@ -0,0 +1,51 @@
:::{note}
**AI Translation Notice**
This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
- Source document: userland/appdev/rust-quick-start.md
- Translation time: 2025-05-19 01:41:52
- Translation model: `Qwen/Qwen3-8B`
Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
:::
# Quick Start Guide for Rust Application Development
## Compilation Environment
&emsp;&emsp;DragonOS has partial binary compatibility with Linux, so you can use the Rust compiler for Linux to compile.
## Project Configuration
### Creating from a Template
:::{note}
This feature requires dadk version 0.2.0 or higher. For older versions, please refer to the historical DragonOS documentation.
:::
1. Use the `bootstrap.sh` script in the tools directory of DragonOS to initialize the environment.
2. Enter `cargo install cargo-generate` in the terminal.
3. Enter the following command in the terminal:
```shell
cargo generate --git https://github.com/DragonOS-Community/Rust-App-Template
```
To create the project. If your network is slow, please use a mirror site.
```shell
cargo generate --git https://git.mirrors.dragonos.org/DragonOS-Community/Rust-App-Template
```
4. Use `cargo run` to run the project.
5. In the `user/dadk/config` directory of DragonOS, refer to the template [userapp_config.toml](https://github.com/DragonOS-Community/DADK/blob/main/dadk-config/templates/config/userapp_config.toml) to create a compilation configuration, and install it to the `/` directory of DragonOS.
(When using the compilation command options of dadk, please use the `make install` configuration in the Makefile for compilation and installation)
6. Compile DragonOS to install.
### Manual Configuration
If you need to port other libraries or programs to DragonOS, please refer to the configuration in the template.
Since DragonOS currently does not support dynamic linking, you need to specify `-C target-feature=+crt-static -C link-arg=-no-pie` in RUSTFLAGS.

2
docs/requirements.txt
View File

@ -3,3 +3,5 @@ myst-parser==0.18.0
sphinx-rtd-theme
sphinxcontrib-mermaid==1.0.0
git+https://git.mirrors.dragonos.org.cn/DragonOS-Community/sphinx-multiversion.git@5858b75#egg=sphinx-multiversion
openai~=1.79
tqdm~=4.65.0

2
docs/userland/appdev/index.rst
View File

@ -1,5 +1,5 @@
应用程序开发文档
====================================
===================================================
.. toctree::

467
tools/doc_translator.py Normal file
View File

@ -0,0 +1,467 @@
#!/usr/bin/env python3
"""
DragonOS文档自动翻译工具
Usage:
在DragonOS源码根目录下运行此脚本。
需要先进入docs目录，执行命令安装依赖包。
pip install -r requirements.txt
接着先声明以下变量：
export OPENAI_API_KEY=your_api_key
export OPENAI_MODEL=your_model_name (推荐qwen3的4b以上的)
export OPENAI_BASE_URL=your_openai_base_url
export MAX_WORKERS=your_max_workers (推荐2-20)
然后运行：
python3 tools/doc_translator.py
"""
import os
import re
import hashlib
import json
from pathlib import Path
import threading
from typing import List, Dict, Tuple
import openai
import datetime
import time
from tqdm import tqdm
# 配置
def get_env_var(name, required=False, default=None):
"""从环境变量获取配置"""
value = os.getenv(name, default)
if required and not value:
raise ValueError(f"环境变量 {name} 未设置")
return value
CONFIG = {
"source_dir": "docs", # 源文档目录
"target_languages": {
"en": "English",
},
"dirs_exclude": ["_build", "locales"], # 排除的目录
"model": get_env_var("OPENAI_MODEL", default="qwen3:4b"), # 模型名称
# API地址
"base_url": get_env_var("OPENAI_BASE_URL", default="http://localhost:11434/v1"),
"chunk_size": 1000, # 分块大小(tokens)
"cache_file": "docs/.translation_cache.json", # 翻译缓存文件
"max_workers": int(get_env_var("MAX_WORKERS", default="1")), # 并行工作数
# 元数据模板
"meta_templates": {
".rst": (
".. note:: AI Translation Notice\n\n"
" This document was automatically translated by `{model}` model, for reference only.\n\n"
" - Source document: {original_path}\n\n"
" - Translation time: {timestamp}\n\n"
" - Translation model: `{model}`\n\n"
"\n Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_\n\n"
),
".md": (
":::{note}\n"
"**AI Translation Notice**\n\n"
"This document was automatically translated by `{model}` model, for reference only.\n\n"
"- Source document: {original_path}\n\n"
"- Translation time: {timestamp}\n\n"
"- Translation model: `{model}`\n\n"
"Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)\n\n"
":::\n\n"
)
}
}
class LabelManager:
"""管理文档标签和引用"""
def __init__(self, lang: str):
self.label_map = {}
self.prefix = "_translated_label_"
self.lang = lang
def register_label(self, original_label: str) -> str:
"""注册新标签并返回映射后的标签"""
if original_label not in self.label_map:
new_label = f"{self.prefix}_{original_label}_{self.lang}"
self.label_map[original_label] = new_label
return self.label_map[original_label]
def get_all_labels(self) -> Dict[str, str]:
"""获取所有标签映射"""
return self.label_map
class DocumentTranslator:
def __init__(self):
self._cache_lock = threading.Lock()
self._cache = self._load_cache()
self.fail_count = 0
try:
self.client = openai.OpenAI(
base_url=CONFIG["base_url"],
# 这是故意把key的获取写在这里的。防止哪个二货直接print CONFIG导致key泄露。
api_key=get_env_var("OPENAI_API_KEY", default="ollama"),
)
except Exception as e:
raise RuntimeError(f"OpenAI客户端初始化失败: {str(e)}")
def _load_cache(self) -> Dict:
"""加载翻译缓存"""
if os.path.exists(CONFIG["cache_file"]):
with open(CONFIG["cache_file"], "r", encoding="utf-8") as f:
try:
return json.load(f)
except json.JSONDecodeError:
pass
return {}
def _save_cache(self):
"""保存翻译缓存"""
with self._cache_lock:
with open(CONFIG["cache_file"], "w", encoding="utf-8") as f:
json.dump(self._cache, f, ensure_ascii=False, indent=2)
def _get_cache_key(self, filepath: str, lang: str) -> str:
"""生成缓存键(包含语言代码)"""
rel_path = os.path.relpath(filepath, CONFIG["source_dir"])
return f"{lang}:{rel_path}"
def _split_into_chunks(self, text: str) -> List[str]:
"""将文本分块"""
# 按段落分割
paragraphs = re.split(r"\n\s*\n", text)
chunks = []
current_chunk = []
current_size = 0
for para in paragraphs:
para_size = len(para.split())
if current_size + para_size > CONFIG["chunk_size"] and current_chunk:
chunks.append("\n\n".join(current_chunk))
current_chunk = []
current_size = 0
current_chunk.append(para)
current_size += para_size
if current_chunk:
chunks.append("\n\n".join(current_chunk))
return chunks
def _process_rst_labels(self, text: str, label_manager: LabelManager) -> str:
"""处理reStructuredText标签"""
def replace_label(match):
original_label = match.group(1)
new_label = label_manager.register_label(original_label)
return f'.. {new_label}:'
# 处理标签定义
text = re.sub(r'\.\.\s+_([^:]+):', replace_label, text)
# 处理标签引用
text = re.sub(r'(?<!\w)`([^`]+)`(?!\w)',
lambda m: f'`{label_manager.register_label(m.group(1))}`',
text)
return text
def _process_md_labels(self, text: str, label_manager: LabelManager) -> str:
"""处理Markdown标签"""
# 处理显式标签定义 {#label}
text = re.sub(r'\{#([^}]+)\}',
lambda m: f'{{#{label_manager.register_label(m.group(1))}}}',
text)
# 处理显式标签定义 (label)=
text = re.sub(r'\(([^)]+)\)=',
lambda m: f'({label_manager.register_label(m.group(1))})=',
text)
# 处理标签引用 [text](#label)
text = re.sub(r'\[([^\]]+)\]\(#([^)]+)\)',
lambda m: f'[{m.group(1)}](#{label_manager.register_label(m.group(2))})',
text)
# 处理裸标签引用 #label
text = re.sub(r'(?<!\w)#([\w-]+)(?!\w)',
lambda m: f'#{label_manager.register_label(m.group(1))}',
text)
return text
def _generate_unique_label_for_lang(self, text: str, lang: str) -> str:
# 处理标签
label_manager = LabelManager(lang)
text = self._process_rst_labels(text, label_manager)
text = self._process_md_labels(text, label_manager)
return text
def _preserve_special_format(self, text: str) -> Tuple[str, Dict]:
"""保留特殊格式"""
preserved = {}
# 排除不需要翻译的块
exclude_blocks = re.findall(
r'\.\. Note: __EXCLUDE_IN_TRANSLATED_START.*?\.\. Note: __EXCLUDE_IN_TRANSLATED_END',
text, re.DOTALL)
for block in exclude_blocks:
text = text.replace(block, '')
# 处理多行代码块
code_blocks = re.findall(r"```.*?\n.*?```", text, re.DOTALL)
for i, block in enumerate(code_blocks):
placeholder = f"__CODE_BLOCK_{i}__"
preserved[placeholder] = block
text = text.replace(block, placeholder)
# 处理内联代码块
inline_code = re.findall(r"`[^`]+`", text)
for i, code in enumerate(inline_code):
placeholder = f"__INLINE_CODE_{i}__"
preserved[placeholder] = code
text = text.replace(code, placeholder)
return text, preserved
def _restore_special_format(self, text: str, preserved: Dict) -> str:
"""恢复特殊格式"""
# 先恢复内联代码块
for placeholder, content in preserved.items():
if placeholder.startswith("__INLINE_CODE_"):
text = text.replace(placeholder, content)
# 然后恢复多行代码块
for placeholder, content in preserved.items():
if placeholder.startswith("__CODE_BLOCK_"):
text = text.replace(placeholder, content)
return text
def _remove_thinking(self, text: str) -> str:
"""Remove <think> tags from text"""
return re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
def _translate_chunk(self, args: Tuple[str, str]) -> str:
"""翻译单个文本块(内部方法，用于并行处理)"""
chunk, lang = args
retry = 3
while retry > 0:
try:
lang_name = CONFIG["target_languages"].get(lang, "English")
prompt = f"你是一个专业的文档翻译助手，请将以下中文技术文档准确翻译成{lang_name}，保持技术术语的正确性和格式不变。"
# disable qwen3's thinking mode
if "qwen3" in CONFIG["model"].lower():
prompt += "\n/no_think\n"
chunk += "\n/no_think\n"
response = self.client.chat.completions.create(
extra_body={"enable_thinking": False},
model=CONFIG["model"],
messages=[
{"role": "system", "content": prompt},
{"role": "user", "content": chunk}
],
temperature=0.3,
)
content = response.choices[0].message.content
return self._remove_thinking(content)
except Exception as e:
retry -= 1
if retry == 0:
print("翻译失败: {e}，放弃重试。")
return None
print(f"翻译出错: {e}, retrying... ({retry})")
time.sleep(2)
def translate_text(self, text: str, lang: str) -> str:
"""使用openai接口翻译文本
Args:
text: 要翻译的文本
lang: 目标语言代码
"""
chunks = self._split_into_chunks(text)
translated_chunks = []
for chunk in chunks:
translated_chunk = self._translate_chunk((chunk, lang))
if translated_chunk:
translated_chunks.append(translated_chunk)
return "\n\n".join(translated_chunks)
def process_file(self, filepath: str, lang: str = "en"):
"""处理单个文件
Args:
filepath: 源文件路径
lang: 目标语言代码 (默认'en')
"""
rel_path = os.path.relpath(filepath, CONFIG["source_dir"])
target_path = os.path.join(
CONFIG["source_dir"], "locales", lang, rel_path)
# 检查文件是否已存在且未修改
cache_key = self._get_cache_key(filepath, lang)
file_hash = hashlib.md5(open(filepath, "rb").read()).hexdigest()
target_file_exists = os.path.exists(target_path)
with self._cache_lock:
if cache_key in self._cache and self._cache[cache_key]["hash"] == file_hash and target_file_exists:
print(f"文件未修改，跳过: {rel_path} (语言: {lang})")
return
print(f"正在处理: {rel_path}")
# 读取文件内容
with open(filepath, "r", encoding="utf-8") as f:
content = f.read()
# 保留特殊格式
content, preserved = self._preserve_special_format(content)
content = self._generate_unique_label_for_lang(content, lang)
# 分块翻译
translated_content = self.translate_text(
content, lang)
if not translated_content:
print(f"翻译失败！{filepath}")
self.fail_count += 1
return
# 恢复特殊格式
translated_content = self._restore_special_format(
translated_content, preserved)
# 创建目标目录
os.makedirs(os.path.dirname(target_path), exist_ok=True)
# 写入翻译结果
with open(target_path, "w", encoding="utf-8") as f:
# 添加翻译元数据
file_ext = os.path.splitext(filepath)[1]
template = CONFIG["meta_templates"].get(file_ext, "")
if template:
timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
original_path = os.path.relpath(filepath, CONFIG["source_dir"])
meta_content = template.format(
note="{note}",
model=CONFIG["model"],
timestamp=timestamp,
original_name=os.path.basename(filepath),
original_path=original_path
)
translated_content = meta_content + translated_content
f.write(translated_content)
f.write("\n")
# 更新缓存
with self._cache_lock:
self._cache[cache_key] = {
"hash": file_hash,
}
self._save_cache()
print(f"文件 {rel_path} 已成功翻译为 {lang} 并保存到 {target_path}")
def add_language_root_title(self, lang):
"""为每个语言的文档添加标题"""
lang_root_doc_path = os.path.join(
CONFIG["source_dir"], "locales", lang, "index.rst")
if not os.path.exists(lang_root_doc_path):
raise FileNotFoundError(f"未找到 {lang} 的标题文件: {lang_root_doc_path}")
print(f"正在为 {CONFIG['target_languages'][lang]} 添加标题...")
# Read existing content first
with open(lang_root_doc_path, "r", encoding="utf-8") as f:
content = f.read()
lang_v = CONFIG["target_languages"][lang]
if content.startswith(lang_v):
print(f"{lang_v} 的标题已存在，跳过...")
return
# Then write new content (this clears the file)
with open(lang_root_doc_path, "w", encoding="utf-8") as f:
f.write(
f"{lang_v}\n==========================================\n{content}")
print(f"标题已添加到 {lang_root_doc_path}")
def run(self):
"""运行翻译流程"""
print("Collecting all files...")
all_files = []
for root, dirs, files in os.walk(CONFIG["source_dir"], topdown=True):
# 只在根目录应用排除逻辑
if root == CONFIG["source_dir"]:
dirs[:] = [d for d in dirs if d not in CONFIG["dirs_exclude"]]
for file in files:
if file.endswith((".rst", ".md")):
all_files.append(os.path.join(root, file))
total_files = len(all_files)
print(
f"Total {total_files} files to translate in {len(CONFIG['target_languages'])} languages.")
total_tasks = total_files * len(CONFIG["target_languages"])
# 外层进度条：语言
lang_pbar = tqdm(CONFIG["target_languages"].items(),
desc="Overall progress",
unit="lang",
position=0)
for lang_k, lang_v in lang_pbar:
lang_pbar.set_description(f"Translating to {lang_v}")
# 并行处理文件
from concurrent.futures import ThreadPoolExecutor, as_completed
# 包装处理函数便于调试之类的
def process_file_wrapper(file_path):
self.process_file(file_path, lang_k)
return file_path
# 创建线程池
with ThreadPoolExecutor(max_workers=CONFIG["max_workers"]) as executor:
# 提交所有文件处理任务
futures = [executor.submit(
process_file_wrapper, path) for path in all_files]
# 创建进度条
file_pbar = tqdm(total=len(all_files),
desc=f"Files in {lang_v}",
unit="file",
position=1,
leave=False)
# 更新进度条
for future in as_completed(futures):
file_pbar.update(1)
future.result() # 获取结果（如果有异常会在这里抛出）
file_pbar.close()
self.add_language_root_title(lang_k)
lang_pbar.close()
print(
f"\n翻译完成！ Succ: {total_tasks-self.fail_count}, Fail: {self.fail_count}")
if __name__ == "__main__":
print("Starting translation process...")
print("WORKERS: ", CONFIG["max_workers"])
print("LANGUAGES: ", CONFIG["target_languages"])
print("SOURCE_DIR: ", CONFIG["source_dir"])
print("MODEL: ", CONFIG["model"])
translator = DocumentTranslator()
translator.run()