xwrust/
lib.rs

1//! XWOS RUST
2//! ========
3//!
4//! # 简介
5//!
6//! XWOS RUST是Rust语言 `#![no_std]` 环境下的XWOS框架，可让用户使用RUST语言开发RTOS的应用。
7//!
8//! 在编写XWOS RUST时，作者充分阅读并参考了RUST语言std库的代码，尽量仿照std库的形式提供API。
9//!
10//!
11//! 传统RUST程序的入口是 `main.rs` 的 `fn main()` ，
12//! XWOS RUST的入口是 `pub unsafe extern "C" fn xwrust_main()` 。
13//!
14//!
15//! 编写XWOS RUST的应用时，需要以下步骤：
16//!
17//! + 1. 在工程目录（例如电路板模块 `bm` 文件夹 或 `$(OEM)` 文件夹）建立一个独立的 [**玄武模块**](../../Docs/TechRefManual/BuildSystem/#玄武模块) ，
18//!   并创建 `makefile` 。
19//!
20//! ```makefile
21//! include $(XWOS_WKSPC_DIR)/XWOS.cfg
22//! include xwbs/functions.mk
23//! include xwbs/xwmo.rust.mk
24//! ```
25//!
26//! + 2. 创建 `Cargo.toml` 。
27//!
28//! ```toml
29//! [package]
30//! name = "rustapp"
31//! version = "0.1.0"
32//! edition = "2021"
33//!
34//! [lib]
35//! name = "rustapp"
36//! crate-type = ["staticlib"]
37//!
38//! [dependencies]
39//! cortex-m = "0.7"
40//! xwrust = {path = "../../../../xwmd/xwrust"}
41//! ```
42//!
43//! + 3. 创建 `.cargo/config.toml` 。
44//!
45//! ```toml
46//! [build]
47//! rustflags = [
48//!  "--cfg", "unix",
49//!  "--cfg", "target_env=\"newlib\"",
50//! ]
51//! target-dir = "target"
52//!
53//! [unstable]
54//! build-std = ["core", "alloc"]
55//! ```
56//!
57//! + 4. 在 `src/lib.rs` 中实现 `pub unsafe extern "C" fn xwrust_main()` 。
58//!
59//! ```rust
60//! #![no_std]
61//!
62//! use xwrust::xwmm::allocator::XwrustAllocator;
63//!
64//! #[global_allocator]
65//! pub static GLOBAL_ALLOCATOR: XwrustAllocator = XwrustAllocator;
66//!
67//! #[no_mangle]
68//! pub unsafe extern "C" fn xwrust_main() {
69//!     // 用户代码
70//! }
71//! ```
72//!
73//! + 5. 在XWOS的C语言入口 `xwos_main()` 中创建一个线程来调用 `xwrust_main()` 。
74//!
75//! ```C
76//! extern void xwrust_main(void);
77//!
78//! #define XWRUST_THD_PRIORITY XWOS_SKD_PRIORITY_DROP(XWOS_SKD_PRIORITY_RT_MAX, 0)
79//! xwer_t xwrust_thd_mainfunc(void * arg);
80//! __xwcc_alignl1cache xwstk_t xwrust_thd_stack[2048U] = {0};
81//! struct xwos_thd xwrust_thd;
82//! xwos_thd_d xwrust_thdd;
83//!
84//! xwer_t xwos_main(void)
85//! {
86//!         xwer_t rc;
87//!         struct xwos_thd_attr attr;
88//!
89//!         xwos_thd_attr_init(&attr);
90//!         attr.name = "xwrust.thd";
91//!         attr.stack = xwrust_thd_stack;
92//!         attr.stack_size = sizeof(xwrust_thd_stack);
93//!         attr.priority = XWRUST_THD_PRIORITY;
94//!         attr.detached = true;
95//!         attr.privileged = true;
96//!         rc = xwos_thd_init(&xwrust_thd, &xwrust_thdd,
97//!                            &attr,
98//!                            xwrust_thd_mainfunc, NULL);
99//! }
100//!
101//! xwer_t xwrust_thd_mainfunc(void * arg)
102//! {
103//!         xwrust_main();
104//! }
105//! ```
106//!
107//!
108//! # XWOS RUST 的功能
109//!
110//! XWOS RUST提供了RTOS的基本功能：
111//!
112//! + [内存管理](crate::xwmm)
113//!   + [全局内存分配器](crate::xwmm::allocator)
114//! + [调度器](crate::xwos::skd)
115//! + [电源管理](crate::xwos::pm)
116//! + [线程](crate::xwos::thd)
117//! + [软件定时器](crate::xwos::swt)
118//! + [锁](crate::xwos::lock)
119//!   + [互斥锁](crate::xwos::lock::mtx)
120//!   + [自旋锁](crate::xwos::lock::spinlock)
121//!   + [顺序锁](crate::xwos::lock::seqlock)
122//! + [同步机制](crate::xwos::sync)
123//!   + [信号量](crate::xwos::sync::sem)
124//!   + [条件量](crate::xwos::sync::cond)
125//!   + [事件标志](crate::xwos::sync::flg)
126//!   + [线程栅栏](crate::xwos::sync::br)
127//!   + [信号选择器](crate::xwos::sync::sel)
128//! + 线程间通讯
129//!   + [消息队列](crate::xwmd::xwmq)
130//!   + [循环队列](crate::xwmd::xwcq)
131//! + 其他
132//!   + [时间](crate::xwtm)
133//!   + [类型](crate::types)
134//!   + [错误码](crate::errno)
135//!   + [位图](crate::xwbmp)
136//!
137//! XWOS RUST所有功能都提供了 [`static`] 创建的方法，如果不使用 [`Arc<T>`], [`Box<T>`] 等，
138//! 即可实现完全静态内存分配的代码。
139//!
140//!
141//! # 返回XWOS首页
142//!
143//! [**XWOS首页**](/)
144//!
145//!
146//! [`static`]: <https://doc.rust-lang.org/std/keyword.static.html>
147//! [`Box<T>`]: <https://doc.rust-lang.org/alloc/boxed/struct.Box.html>
148//! [`Arc<T>`]: <https://doc.rust-lang.org/alloc/sync/struct.Arc.html>
149
150#![no_std]
151#![feature(alloc_error_handler)]
152#![feature(negative_impls)]
153#![feature(generic_const_exprs)]
154#![allow(incomplete_features)]
155
156pub mod cfg;
157
158#[macro_use]
159pub mod macros;
160
161pub mod types;
162
163pub mod errno;
164
165pub mod panic;
166
167#[allow(dead_code)]
168pub mod xwbmp;
169
170pub mod xwtm;
171
172pub mod xwmm;
173
174#[allow(dead_code)]
175pub mod xwos;
176
177#[allow(dead_code)]
178pub mod xwmd;
179
180#[macro_use]
181pub mod xwds;
xwrust/lib.rs

xwrust/
lib.rs
