diff --git a/Makefile b/Makefile index c4a17491e5..fc10f7cb78 100644 --- a/Makefile +++ b/Makefile @@ -69,7 +69,7 @@ THESEUS_CARGO := $(ROOT_DIR)/tools/theseus_cargo THESEUS_CARGO_BIN := $(THESEUS_CARGO)/bin/theseus_cargo EXTRA_FILES := $(ROOT_DIR)/extra_files LIMINE_DIR := $(ROOT_DIR)/limine-prebuilt -RUST_SOURCE := $(ROOT_DIR)/ports/rust +RUST_SOURCE := $(ROOT_DIR)/ports/rust ### Set up tool names/locations for cross-compiling on a Mac OS / macOS host (Darwin). diff --git a/kernel/libtheseus/Cargo.toml b/kernel/libtheseus/Cargo.toml index dd27c35e45..c9d313ec3c 100644 --- a/kernel/libtheseus/Cargo.toml +++ b/kernel/libtheseus/Cargo.toml @@ -1,6 +1,8 @@ [package] name = "libtheseus" version = "0.1.0" +authors = ["Klim Tsoutsman "] +description = "Implementation of shim functions for std linkage boundary" edition = "2021" [dependencies] diff --git a/kernel/libtheseus/src/lib.rs b/kernel/libtheseus/src/lib.rs index e5338118b5..6f61fcc6ba 100644 --- a/kernel/libtheseus/src/lib.rs +++ b/kernel/libtheseus/src/lib.rs @@ -1,3 +1,7 @@ +//! This crate implements the functions defined in `shim`. +//! +//! See the `shim` crate for more details. + #![no_std] extern crate alloc; @@ -7,8 +11,10 @@ use core::mem; use app_io::{ImmutableRead, ImmutableWrite}; use path::Path; -use theseus_ffi::{Error, FatPointer, FfiOption, FfiResult, FfiSlice, FfiSliceMut, FfiStr, FfiString}; use task::{KillReason, TaskRef}; +use theseus_ffi::{ + Error, FatPointer, FfiOption, FfiResult, FfiSlice, FfiSliceMut, FfiStr, FfiString, +}; const _: theseus_ffi::next_u64 = next_u64; const _: theseus_ffi::getcwd = getcwd; @@ -32,7 +38,7 @@ fn current_task() -> TaskRef { task::get_my_current_task().expect("failed to get current task") } -// Add the libtheseus:: so mod_mgmt knows which crate to search. +// Add the libtheseus:: prefix so mod_mgmt knows which crate to search. #[export_name = "libtheseus::next_u64"] pub extern "C" fn next_u64() -> u64 { @@ -104,8 +110,13 @@ pub unsafe extern "C" fn register_dtor(t: *mut u8, dtor: unsafe extern "C" fn(*m unsafe { thread_local_macro::register_dtor(t, dtor) } } -// TODO: Something better than transmutations. -// TODO: Explain why we shouldn't bother using stabby at least for trait objects. +// TODO: Something better than transmutations? + +// One might naively assume that we are better off using `stabby` trait objects, +// but that means throughtout Theseus we would have to use +// stabby::alloc::sync::Arc and vtable!(Trait), rather than alloc::sync::Arc and +// dyn Trait respectively. The current solution isn't great, but it's only funky +// at the boundary to `shim` and doesn't impact the rest of Theseus. #[export_name = "libtheseus::stdin"] pub extern "C" fn stdin() -> FfiResult { @@ -132,14 +143,20 @@ pub extern "C" fn stderr() -> FfiResult { } #[export_name = "libtheseus::read"] -pub unsafe extern "C" fn read(reader: FatPointer, buf: FfiSliceMut<'_, u8>) -> FfiResult { +pub unsafe extern "C" fn read( + reader: FatPointer, + buf: FfiSliceMut<'_, u8>, +) -> FfiResult { let ptr: *const dyn ImmutableRead = unsafe { mem::transmute(reader) }; let r = unsafe { &*ptr }; FfiResult::from(r.read(buf.into()).map_err(from_core2)) } #[export_name = "libtheseus::write"] -pub unsafe extern "C" fn write(writer: FatPointer, buf: FfiSlice<'_, u8>) -> FfiResult { +pub unsafe extern "C" fn write( + writer: FatPointer, + buf: FfiSlice<'_, u8>, +) -> FfiResult { let ptr: *const dyn ImmutableWrite = unsafe { mem::transmute(writer) }; let r = unsafe { &*ptr }; FfiResult::from(r.write(buf.into()).map_err(from_core2)) diff --git a/libs/theseus_ffi/Cargo.toml b/libs/theseus_ffi/Cargo.toml index 2d70a7a481..bc7dc00405 100644 --- a/libs/theseus_ffi/Cargo.toml +++ b/libs/theseus_ffi/Cargo.toml @@ -1,6 +1,8 @@ [package] name = "theseus_ffi" version = "0.1.0" +authors = ["Klim Tsoutsman "] +description = "Common types for the std linkage boundary" edition = "2021" [dependencies] diff --git a/libs/theseus_ffi/src/lib.rs b/libs/theseus_ffi/src/lib.rs index 6074053306..585132c150 100644 --- a/libs/theseus_ffi/src/lib.rs +++ b/libs/theseus_ffi/src/lib.rs @@ -1,3 +1,5 @@ +//! This crate defines types that are used in both `shim` and `libtheseus`. + #![no_std] #![feature(vec_into_raw_parts, try_trait_v2, never_type, exhaustive_patterns)] #![allow(non_camel_case_types)] diff --git a/shim/Cargo.toml b/shim/Cargo.toml index 9b75b1de85..3671ec66da 100644 --- a/shim/Cargo.toml +++ b/shim/Cargo.toml @@ -1,6 +1,8 @@ [package] name = "theseus-shim" version = "0.1.0" +authors = ["Klim Tsoutsman "] +description = "Declaration of shim functions for std linkage boundary" edition = "2021" [dependencies] diff --git a/shim/src/lib.rs b/shim/src/lib.rs index f3c58fde9d..150191e9f3 100644 --- a/shim/src/lib.rs +++ b/shim/src/lib.rs @@ -1,3 +1,10 @@ +//! Provides Theseus OS functionality without a direct dependency on Theseus +//! kernel crates. +//! +//! It does so by declaring functions that are implemented by the `libtheseus` +//! kernel crate. These functions are referenced as relocations in the dependent +//! (i.e. `std`) object file that `mod_mgmt` then fills in at runtime. + #![no_std] #![feature(extern_types)] @@ -185,7 +192,10 @@ pub fn stderr() -> Result { }) } -// TODO: Mutable reference? +// TODO: Should we be taking a mutable or immutable reference? +// +// Technically, speaking I don't think we need to take a mutable reference, but +// that limits our options in the future. #[inline] pub fn read(reader: &mut Reader, buf: &mut [u8]) -> Result {