Porting Rust standard library
| Difficulty level |
|---|
 Beginner |
|
|
Guide
This guide shows how to get the standard library to compile and run for a custom target.
By the end you should be able to compile a project with
cargo +dev-x86_64-unknown-myos r --target x86_64-unknown-myos
Get sources
git clone https://github.com/rust-lang/rust
Configuration
# config.toml
profile = "compiler"
change-id = 125535
[build]
host = ["x86_64-unknown-linux-gnu"]
target = ["x86_64-unknown-linux-gnu", "x86_64-unknown-myos"]
[rust]
incremental = true
Adding the target
Adding a target to the rust compiler takes several files. rustc_target must be told about the new target with a base spec and a target spec. The bootstrap crate must be told that the new target, while not in the downloaded bootstrap compiler, is valid. Also, a test is added for the new target that checks assembly code generation. The test is not strictly necessary, but tidy, the rust compiler's style enforcer, will not pass without it, so it is good practice.
In addition, a _start symbol must be provided to rustc. This can be done in one of two ways. Either rustc can be given a crt0 object file that provides start, or the standard library can be modified to provide it for our target. The CRT option is done in the target files and thus shown here, while the standard library approach is described in the next section.
// compiler/rustc_target/src/spec/base/myos.rs
// Only if using external CRT to provide _start
use crate::spec::crt_objects;
use crate::spec::{Cc, LinkerFlavor, Lld, RelocModel, StackProbeType, TargetOptions};
pub fn opts() -> TargetOptions {
TargetOptions {
os: "myos".into(),
linker: Some("rust-lld".into()),
linker_flavor: LinkerFlavor::Gnu(Cc::No, Lld::Yes),
stack_probes: StackProbeType::Inline,
relocation_model: RelocModel::Static,
// Following two only if using external CRT to provide _start
pre_link_objects: crt_objects::pre_myos(),
post_link_objects: crt_objects::post_myos(),
..Default::default()
}
}
// compiler/rustc_target/src/spec/targets/x86_64_unknown_myos.rs
use crate::spec::{base, PanicStrategy, Target, TargetMetadata};
pub fn target() -> Target {
let mut base = base::myos::opts();
base.cpu = "x86-64".into();
base.disable_redzone = true;
base.panic_strategy = PanicStrategy::Abort;
base.features = "-mmx,-sse,+soft-float".into();
Target {
llvm_target: "x86_64-unknown-none".into(),
pointer_width: 64,
data_layout:
"e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-i128:128-f80:128-n8:16:32:64-S128".into(),
arch: "x86_64".into(),
options: base,
metadata: TargetMetadata {
description: None,
tier: None,
host_tools: None,
std: None,
},
}
}
--- a/compiler/rustc_target/src/spec/base/mod.rs
+++ b/compiler/rustc_target/src/spec/base/mod.rs
@@ -18,6 +18,7 @@
pub(crate) mod linux_ohos;
pub(crate) mod linux_uclibc;
pub(crate) mod msvc;
+pub(crate) mod myos;
pub(crate) mod netbsd;
pub(crate) mod nto_qnx;
pub(crate) mod openbsd;
--- a/compiler/rustc_target/src/spec/mod.rs
+++ b/compiler/rustc_target/src/spec/mod.rs
@@ -1826,6 +1826,8 @@ fn $module() {
("x86_64-unknown-linux-none", x86_64_unknown_linux_none),
+ ("x86_64-unknown-myos", x86_64_unknown_myos),
+
}
--- a/compiler/rustc_target/src/spec/crt_objects.rs
+++ b/compiler/rustc_target/src/spec/crt_objects.rs
@@ -106,6 +106,14 @@ pub(super) fn post_mingw() -> CrtObjects {
all("rsend.o")
}
+pub(super) fn pre_myos() -> CrtObjects {
+ all(<PATH TO CRT0 HERE>)
+}
+
+pub(super) fn post_myos() -> CrtObjects {
+ new(&[])
+}
+
--- a/src/bootstrap/src/core/sanity.rs
+++ b/src/bootstrap/src/core/sanity.rs
@@ -40,6 +40,7 @@ pub struct Finder {
#[cfg(not(feature = "bootstrap-self-test"))]
const STAGE0_MISSING_TARGETS: &[&str] = &[
// just a dummy comment so the list doesn't get onelined
+ "x86_64-unknown-myos",
];
--- a/src/bootstrap/src/lib.rs
+++ b/src/bootstrap/src/lib.rs
@@ -94,7 +94,7 @@
(Some(Mode::Std), "no_sync", None),
/* Extra values not defined in the built-in targets yet, but used in std */
(Some(Mode::Std), "target_env", Some(&["libnx", "p2"])),
- (Some(Mode::Std), "target_os", Some(&["visionos"])),
+ (Some(Mode::Std), "target_os", Some(&["myos", "visionos"])),
(Some(Mode::Std), "target_arch", Some(&["arm64ec", "spirv", "nvptx", "xtensa"])),
(Some(Mode::ToolStd), "target_os", Some(&["visionos"])),
--- a/tests/assembly/targets/targets-elf.rs
+++ b/tests/assembly/targets/targets-elf.rs
@@ -561,6 +561,9 @@
//@ revisions: x86_64_unknown_linux_none
//@ [x86_64_unknown_linux_none] compile-flags: --target x86_64-unknown-linux-none
//@ [x86_64_unknown_linux_none] needs-llvm-components: x86
+//@ revisions: x86_64_unknown_myos
+//@ [x86_64_unknown_myos] compile-flags: --target x86_64-unknown-myos
+//@ [x86_64_unknown_myos] needs-llvm-components: x86
//@ revisions: x86_64_unknown_netbsd
//@ [x86_64_unknown_netbsd] compile-flags: --target x86_64-unknown-netbsd
//@ [x86_64_unknown_netbsd] needs-llvm-components: x86
Adapt library/std
In addition to rustc, std must also be modified to support the target. By default, std will error on build if the OS isn't explicitly supported, so we must add our OS to the list of supported OSes. In addition, we must provide a PAL (Platform Abstraction Layer) to tell std how to interact with our OS.
--- a/library/std/build.rs
+++ b/library/std/build.rs
@@ -48,6 +48,7 @@ fn main() {
|| target_os == "uefi"
|| target_os == "teeos"
|| target_os == "zkvm"
+ || target_os == "myos"
// See src/bootstrap/src/core/build_steps/synthetic_targets.rs
|| env::var("RUSTC_BOOTSTRAP_SYNTHETIC_TARGET").is_ok()
Copy library/std/src/sys/pal/unsupported to library/std/src/sys/pal/myos.
--- a/library/std/src/sys/pal/mod.rs
+++ b/library/std/src/sys/pal/mod.rs
@@ -61,6 +61,9 @@
} else if #[cfg(target_os = "zkvm")] {
mod zkvm;
pub use self::zkvm::*;
+ } else if #[cfg(target_os = "myos")] {
+ mod myos;
+ pub use self::myos::*;
} else {
mod unsupported;
pub use self::unsupported::*;
If using the standard library to provide _start, you will need to add a module to the PAL containing a #[no_mangle] and extern "C" _start function. The following file works as a basic template. Note that you will have to add a mod start; line to the PAL's mod.rs file.
// library/std/src/sys/pal/myos/start.rs
use crate::ffi::{c_char, c_int};
use crate::ptr;
extern "C" {
fn main(argc: c_int, argv: *const *const c_char) -> c_int;
}
#[no_mangle]
#[allow(unused)]
pub extern "C" fn _start() {
unsafe {
main(0, ptr::null());
};
}
If your kernel does not provide a stack in rsp or provides its CLI arguments in a way impossible to read from a C function, you will have to use naked functions to provide _start as assembly.
Add toolchain
rustup toolchain link dev-x86_64-unknown-myos ~/Documents/rust/rust/build/x86_64-unknown-linux-gnu/stage2
Making the standard library functional
Even though both rustc and std know about the target, not even an empty program will run. This is because the standard library requires two things from the OS to be able to initialize. A memory allocator and thread local storage (TLS).
Memory allocator
Implementing a memory allocator is done in the PAL's alloc.rs file and requires implementing the GlobalAlloc trait. The following bump allocator will work to let the stdlib initialize.`
// library/std/src/sys/pal/myos/alloc.rs
use crate::{
alloc::{GlobalAlloc, Layout, System},
ptr,
sync::atomic::{AtomicUsize, Ordering},
};
#[repr(align(4096))]
struct HeapData([u8; 65536]);
static mut HEAP_DATA: HeapData = HeapData([0; 65536]);
static HEAP_USED: AtomicUsize = AtomicUsize::new(0);
#[stable(feature = "alloc_system_type", since = "1.28.0")]
unsafe impl GlobalAlloc for System {
#[inline]
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
if layout.align() > 8 {
return ptr::null_mut();
}
let num_blocks = if layout.size() % 8 == 0 {
layout.size() / 8
} else {
(layout.size() / 8) + 1
};
HEAP_USED.fetch_add(num_blocks, Ordering::Relaxed);
let ptr = unsafe { ptr::addr_of_mut!(HEAP_DATA.0[HEAP_USED.load(Ordering::Relaxed) - num_blocks ]) as *mut u8 };
ptr
}
#[inline]
unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {}
}
Thread local storage
Global statics (easiest, single-threaded only)
|
WARNING: This WILL not work on multi-threaded systems. |
If your OS is single-threaded or you don't want to implement full TLS before adding multithreading to your PAL, Rust can implement TLS via global statics.
--- a/library/std/src/sys/thread_local/mod.rs
+++ b/library/std/src/sys/thread_local/mod.rs
@@ -7,7 +7,7 @@
// "static" is for single-threaded platforms where a global static is sufficient.
cfg_if::cfg_if! {
- if #[cfg(any(all(target_family = "wasm", not(target_feature = "atomics")), target_os = "uefi"))] {
+ if #[cfg(any(all(target_family = "wasm", not(target_feature = "atomics")), target_os = "uefi", target_os = "myos"))] {
#[doc(hidden)]
mod static_local;
#[doc(hidden)]
OS APIs (slow, easier than ELF native)
This option is slower than the other multi-threaded compatible version, but is easier to implement, requiring only to implement the functions in the PAL's thread_local_key.rs file. The key is a value unique to a TLS variable, though shared amongst threads. This is rustc's default method of doing TLS.
Native ELF TLS (fastest)
This option is the fastest way of doing TLS, but requires more complex suport from the OS. To implement it, see the linked wiki article on TLS. Enabling it in rustc is done by adding a target option for your OS.
--- a/compiler/rustc_target/src/spec/base/myos.rs
+++ b/compiler/rustc_target/src/spec/base/myos.rs
@@ -10,6 +10,7 @@ pub fn opts() -> TargetOptions {
relocation_model: RelocModel::Static,
pre_link_objects: crt_objects::pre_myos(),
post_link_objects: crt_objects::post_myos(),
+ has_thread_local: true,
..Default::default()
}
}
Basic printing
With memory allocation and TLS in place, the Rust stdlib is now functional enough to not crash. However, it's fairly useless as no IO functions work. Adding print output is a natural next step, and will also allow easier debugging of panics.
Adding print support is fairly simple given the architecture of the PAL, and merly requires filling out the Write implementations of stdout/err in stdio.rs. In addition, the panic_output function shoudl be set to the desired output stream for panic messages, usually stderr.
Example code is provided below. The given code assumes syscalls are done with interrupt 0x80 with the number in rax and the first parameter in rcx, and syscall 0 takes a byte to write to some text output device. You will probably need to change the syscall number and parameters for your OS, but this should work as a basic starting point.
--- a/library/std/src/sys/pal/myos/stdio.rs
+++ b/library/std/src/sys/pal/myos/stdio.rs
@@ -1,3 +1,4 @@
+use crate::arch::asm;
use crate::io;
pub struct Stdin;
@@ -24,6 +25,11 @@ pub const fn new() -> Stdout {
impl io::Write for Stdout {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+ for byte in buf {
+ unsafe {
+ asm!("int 0x80", in("rax") 0, in ("rcx") *byte as u64);
+ };
+ }
Ok(buf.len())
}
@@ -40,6 +46,11 @@ pub const fn new() -> Stderr {
impl io::Write for Stderr {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+ for byte in buf {
+ unsafe {
+ asm!("int 0x80", in("rax") 0, in ("rcx") *byte as u64);
+ };
+ }
Ok(buf.len())
}
@@ -54,6 +65,6 @@ pub fn is_ebadf(_err: &io::Error) -> bool {
true
}
-pub fn panic_output() -> Option<Vec<u8>> {
- None
+pub fn panic_output() -> Option<impl io::Write> {
+ Some(Stderr::new())
}
Now you should be able to compile and run the default Rust hello world program for your target and see it print to screen.
Runtime
Integrating a crate
If you use a crate for the runtime (e.g. myos_rt), you can add it as a dependency to the standard library:
[target.'cfg(target_os = "myos")'.dependencies]
myos_rt = { version = "*", features = ["rustc-dep-of-std"] }
The rustc-dep-of-std feature is necessary since libcore et al. don't exist yet.
Modify the Cargo.toml of your runtime library to include the feature and propagate it up, e.g.:
[dependencies]
cfg-if = "1.0"
core = { version = "1.0.0", optional = true, package = "rustc-std-workspace-core" }
compiler_builtins = { version = "0.1", optional = true }
[features]
rustc-dep-of-std = [
"core",
"compiler_builtins",
"cfg-if/rustc-dep-of-std"
]
Do keep in mind that the same crate with different feature flags are seen as different crates by the compiler. This means that if you any globals in the runtime crate and have a project that uses both stdlib and your runtime crate there will be two separate sets of those globals. One way to work around this is by giving these globals an explicit name with #[export_name = "__rt_whatever"] and weakly linking them with #[linkage = "weak"].
Troubleshooting
error[E0463]: can't find crate for `compiler_builtins`
Add compiler_builtins as a dependency for the crates you use in stdlib, e.g.:
[dependencies]
core = { version = "1.0.0", optional = true, package = "rustc-std-workspace-core" }
compiler_builtins = { version = "*", optional = true } # <--
[features]
rustc-dep-of-std = [
"core",
"compiler_builtins/rustc-dep-of-std", # <--
]