moto_rt/
lib.rs

1//! Motor OS Runtime Library. It is a stub/proxy to Motor OS Runtime VDSO
2//! (Virtual Dynamic Shared Object) which is loaded into every userspace process.
3//!
4//! The Runtime API surface is explicitly designed to provide Rust standard
5//! library PAL (platform abstraction layer); while it may evolve later into
6//! a more universal Runtime API (e.g. to be used in Go runtime, Java runtime,
7//! libc, etc.), at the moment only supporting Rust Standard Library PAL
8//! is on the roadmap.
9//!
10//! Note: RT.VDSO is a "fat" runtime: it creates an IO thread to interact with
11//!       sys-io, and stdio threads to provide stdin/stdout/stderr abstractions,
12//!       if needed.
13//!
14//! While it is possible to do everything RT.VDSO does by directly interacting
15//! with the OS kernel and sys-io, there are two main benefits of using a VDSO
16//! and this RT library as its proxy:
17//! - simplified integration with Rust Standard Library: instead of a "fat"
18//!   Motor OS PAL that needs heavy maintenance, this "thin" RT library
19//!   is designed to be relatively stable, even if the underlying system code
20//!   and runtime undergo extensive changes;
21//! - OS/runtime updates are automatically picked up by existing/compiled
22//!   binaries without recompilation; while this is common in Windows and Linux
23//!   with dll/so libraries, this benefit is worth mentioning here, as
24//!   Motor OS, which is based on Rust, does not support dynamic libraries,
25//!   as Rust does not support them "natively" (as in rdylib).
26#![no_std]
27#![feature(linkage)]
28
29// Mod error is the only one currently shared b/w the kernel and the userspace.
30#[macro_use]
31pub mod error;
32pub use error::*;
33
34// Constants from moto-sys: we replicate them here to avoid depending on moto-sys.
35// NOTE: do not change these numbers unless they are also changed in moto-sys!
36#[doc(hidden)]
37pub const MOTO_SYS_CUSTOM_USERSPACE_REGION_START: u64 = (1_u64 << 45) + (1_u64 << 40);
38#[doc(hidden)]
39const MOTO_SYS_CUSTOM_USERSPACE_REGION_END: u64 =
40    MOTO_SYS_CUSTOM_USERSPACE_REGION_START + (1_u64 << 40);
41#[doc(hidden)]
42const MOTO_SYS_PAGE_SIZE_SMALL: u64 = 4096;
43
44// At this address rt.vdso object will be mapped/loaded into every process/binary.
45#[doc(hidden)]
46pub const RT_VDSO_START: u64 = MOTO_SYS_CUSTOM_USERSPACE_REGION_END - (1_u64 << 32); // 4GB for RT_VDSO.
47
48// At this address rt.vdso bytes will be mapped/loaded into every process/binary.
49// NOTE: this is a temporary arrangement; when process start is moved to sys-io (or another binary),
50//       having the bytes in every process will no longer be needed.
51#[doc(hidden)]
52pub const RT_VDSO_BYTES_ADDR: u64 = RT_VDSO_START - (1_u64 << 32); // 4GB for RT_VDSO.
53
54// At this address the loader will initialize RtVdsoVtable.
55#[doc(hidden)]
56pub const RT_VDSO_VTABLE_VADDR: u64 = RT_VDSO_START - MOTO_SYS_PAGE_SIZE_SMALL;
57
58// Rust's dependency on libc runs deep, without these many binaries fail to link.
59#[cfg(feature = "libc")]
60pub mod libc;
61
62#[cfg(not(feature = "base"))]
63pub mod alloc;
64#[cfg(not(feature = "base"))]
65pub mod fs;
66#[cfg(not(feature = "base"))]
67pub mod futex;
68#[cfg(not(feature = "base"))]
69pub mod mutex;
70#[cfg(not(feature = "base"))]
71pub mod net;
72
73#[cfg(not(feature = "base"))]
74#[allow(nonstandard_style)]
75pub mod netc;
76
77#[cfg(not(feature = "base"))]
78pub mod poll;
79#[cfg(not(feature = "base"))]
80pub mod process;
81#[cfg(not(feature = "base"))]
82pub mod thread;
83#[cfg(not(feature = "base"))]
84pub mod time;
85#[cfg(not(feature = "base"))]
86pub mod tls;
87
88pub mod spinlock;
89
90#[cfg(not(feature = "base"))]
91pub use futex::*;
92
93#[cfg(not(feature = "base"))]
94use core::sync::atomic::{AtomicU64, Ordering};
95
96/// Runtime FD (file descriptor). While Motor OS uses SysHandle
97/// for file objects internally, Rust defines std::os::fd::RawFd
98/// as c_int, so we have to follow suit to make our lives easier.
99#[cfg(not(feature = "base"))]
100pub type RtFd = i32;
101// Use posix constants: stdio is a posix construct anyway.
102#[cfg(not(feature = "base"))]
103pub const FD_STDIN: RtFd = 0;
104#[cfg(not(feature = "base"))]
105pub const FD_STDOUT: RtFd = 1;
106#[cfg(not(feature = "base"))]
107pub const FD_STDERR: RtFd = 2;
108
109#[cfg(not(feature = "base"))]
110pub const RT_VERSION: u64 = 16;
111
112/// The main VDSO vtable. Versioning happens via passing RT_VERSION
113/// constant to vdso_entry. In theory, the VDSO object can support
114/// multiple versions, so that older binaries may run on newer versions
115/// of Motor OS. In practice this flexibility is postponed until
116/// later, probably until Motor OS becomes an officially supported
117/// Rust target.
118#[cfg(not(feature = "base"))]
119#[doc(hidden)]
120#[repr(C)]
121pub struct RtVdsoVtable {
122    // This function is called to initialize this VTable
123    // (i.e. all fields other than vdso_entry and vdso_bytes_sz).
124    // Initialized by the loader/parent.
125    pub vdso_entry: AtomicU64,
126
127    // The size of vdso bytes (the address is fixed at RT_VDSO_BYTES_ADDR).
128    // Initialized by the loader/parent.
129    pub vdso_bytes_sz: AtomicU64,
130
131    // Memory management.
132    pub alloc: AtomicU64,
133    pub alloc_zeroed: AtomicU64,
134    pub realloc: AtomicU64,
135    pub dealloc: AtomicU64,
136    pub release_handle: AtomicU64,
137
138    // Time management.
139    pub time_instant_now: AtomicU64,
140    pub time_ticks_to_nanos: AtomicU64,
141    pub time_nanos_to_ticks: AtomicU64,
142    pub time_ticks_in_sec: AtomicU64,
143    pub time_abs_ticks_to_nanos: AtomicU64,
144
145    // Futex.
146    pub futex_wait: AtomicU64,
147    pub futex_wake: AtomicU64,
148    pub futex_wake_all: AtomicU64,
149
150    // Process-related.
151    pub proc_args: AtomicU64,
152    pub proc_get_full_env: AtomicU64,
153    pub proc_getenv: AtomicU64,
154    pub proc_setenv: AtomicU64,
155    pub proc_spawn: AtomicU64,
156    pub proc_kill: AtomicU64,
157    pub proc_wait: AtomicU64,
158    pub proc_status: AtomicU64,
159    pub proc_exit: AtomicU64,
160
161    // Thread Local Storage.
162    pub tls_create: AtomicU64,
163    pub tls_set: AtomicU64,
164    pub tls_get: AtomicU64,
165    pub tls_destroy: AtomicU64,
166
167    // Thread management.
168    pub thread_spawn: AtomicU64,
169    pub thread_sleep: AtomicU64,
170    pub thread_yield: AtomicU64,
171    pub thread_set_name: AtomicU64,
172    pub thread_join: AtomicU64,
173
174    // Filesystem.
175    pub fs_is_terminal: AtomicU64,
176    pub fs_open: AtomicU64,
177    pub fs_close: AtomicU64,
178    pub fs_get_file_attr: AtomicU64,
179    pub fs_fsync: AtomicU64,
180    pub fs_datasync: AtomicU64,
181    pub fs_truncate: AtomicU64,
182    pub fs_read: AtomicU64,
183    pub fs_read_vectored: AtomicU64,
184    pub fs_write: AtomicU64,
185    pub fs_write_vectored: AtomicU64,
186    pub fs_flush: AtomicU64,
187    pub fs_seek: AtomicU64,
188    pub fs_mkdir: AtomicU64,
189    pub fs_unlink: AtomicU64,
190    pub fs_rename: AtomicU64,
191    pub fs_rmdir: AtomicU64,
192    pub fs_rmdir_all: AtomicU64,
193    pub fs_set_perm: AtomicU64,
194    pub fs_set_file_perm: AtomicU64,
195    pub fs_stat: AtomicU64,
196    pub fs_canonicalize: AtomicU64,
197    pub fs_copy: AtomicU64,
198    pub fs_opendir: AtomicU64,
199    pub fs_closedir: AtomicU64,
200    pub fs_readdir: AtomicU64,
201    pub fs_getcwd: AtomicU64,
202    pub fs_chdir: AtomicU64,
203    pub fs_duplicate: AtomicU64,
204
205    // Networking.
206    pub dns_lookup: AtomicU64,
207    pub net_bind: AtomicU64,
208    pub net_listen: AtomicU64,
209    pub net_accept: AtomicU64,
210    pub net_tcp_connect: AtomicU64,
211    pub net_udp_connect: AtomicU64,
212    pub net_socket_addr: AtomicU64,
213    pub net_peer_addr: AtomicU64,
214    pub net_setsockopt: AtomicU64,
215    pub net_getsockopt: AtomicU64,
216    pub net_peek: AtomicU64,
217    pub net_udp_recv_from: AtomicU64,
218    pub net_udp_peek_from: AtomicU64,
219    pub net_udp_send_to: AtomicU64,
220    pub net_udp_multicast_op_v4: AtomicU64,
221    pub net_udp_multicast_op_v6: AtomicU64,
222
223    // Polling.
224    pub poll_new: AtomicU64,
225    pub poll_add: AtomicU64,
226    pub poll_set: AtomicU64,
227    pub poll_del: AtomicU64,
228    pub poll_wait: AtomicU64,
229    pub poll_wake: AtomicU64,
230
231    // Some utilities.
232    pub log_to_kernel: AtomicU64,
233    pub log_backtrace: AtomicU64,
234    pub fill_random_bytes: AtomicU64,
235    pub num_cpus: AtomicU64,
236    pub internal_helper: AtomicU64,
237    pub current_exe: AtomicU64,
238}
239
240#[cfg(not(feature = "base"))]
241const _SIZE_CHECK: () = assert!(size_of::<RtVdsoVtable>() <= 4096);
242
243#[cfg(not(feature = "base"))]
244#[doc(hidden)]
245impl RtVdsoVtable {
246    pub fn get() -> &'static Self {
247        // Safety: sys-io is supposed to have taken care of this.
248        unsafe {
249            (RT_VDSO_VTABLE_VADDR as usize as *const RtVdsoVtable)
250                .as_ref()
251                .unwrap_unchecked()
252        }
253    }
254}
255
256#[cfg(not(feature = "base"))]
257#[doc(hidden)]
258pub fn init() {
259    assert_ne!(0, RtVdsoVtable::get().vdso_entry.load(Ordering::Acquire));
260    let vdso_entry: extern "C" fn(u64) = unsafe {
261        core::mem::transmute(
262            RtVdsoVtable::get().vdso_entry.load(Ordering::Relaxed) as usize as *const (),
263        )
264    };
265
266    vdso_entry(RT_VERSION)
267}
268
269#[cfg(feature = "rustc-dep-of-std")]
270#[linkage = "weak"]
271#[unsafe(no_mangle)]
272pub extern "C" fn motor_runtime_start() {
273    // This function is a weak symbol because sys-io re-defines
274    // motor_runtime_start(): sys-io is loaded by the kernel and has its
275    // own runtime initialization dance that is different from all other
276    // userspace processes.
277    init();
278}
279
280#[cfg(feature = "rustc-dep-of-std")]
281#[doc(hidden)]
282pub fn start() {
283    // Called by Rust stdlib in motor_start (sys/pal/motor/mod.rs)
284    // before main is called.
285    motor_runtime_start();
286}
287
288#[cfg(not(feature = "base"))]
289pub fn fill_random_bytes(bytes: &mut [u8]) {
290    let vdso_fill_random_bytes: extern "C" fn(*mut u8, usize) = unsafe {
291        core::mem::transmute(
292            RtVdsoVtable::get()
293                .fill_random_bytes
294                .load(Ordering::Relaxed) as usize as *const (),
295        )
296    };
297
298    vdso_fill_random_bytes(bytes.as_mut_ptr(), bytes.len())
299}
300
301/// The number of CPUs available.
302#[cfg(not(feature = "base"))]
303pub fn num_cpus() -> usize {
304    // Although num_cpus in part KernelStaticPage in sys-io crate
305    // and theoretically available without calling into the VDSO,
306    // we want to keep moto-rt lean and mean and not depend on
307    // extra crates, so we plump num_cpus() through vdso.
308    let vdso_num_cpus: extern "C" fn() -> usize = unsafe {
309        core::mem::transmute(
310            RtVdsoVtable::get().num_cpus.load(Ordering::Relaxed) as usize as *const (),
311        )
312    };
313
314    vdso_num_cpus()
315}
316
317#[cfg(not(feature = "base"))]
318#[doc(hidden)]
319pub fn internal_helper(a0: u64, a1: u64, a2: u64, a3: u64, a4: u64, a5: u64) -> u64 {
320    // This is an internal helper used during development and testing of the VDSO.
321    // Useful as it allows an extra 'poke' into the VDSO without changing moto-rt/stdlib.
322    //
323    // May panic in a release version, so should not be used for anything other than
324    // during VDSO development.
325    let vdso_internal_helper: extern "C" fn(u64, u64, u64, u64, u64, u64) -> u64 = unsafe {
326        core::mem::transmute(
327            RtVdsoVtable::get().internal_helper.load(Ordering::Relaxed) as usize as *const (),
328        )
329    };
330
331    vdso_internal_helper(a0, a1, a2, a3, a4, a5)
332}
moto_rt/lib.rs

moto_rt/
lib.rs
