arch: Added x86-next crate

Signed-off-by: Ioan-Cristian CÎRSTEA <ioan.cirstea@oxidos.io>

Author: IoanCristianCirstea

arch/x86-next/Cargo.toml

@@ -0,0 +1,17 @@
+# Licensed under the Apache License, Version 2.0 or the MIT License.
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+# Copyright Tock Contributors 2024.
+
+[package]
+name = "x86-next"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+
+[dependencies]
+kernel = { path = "../../kernel" }
+tock-cells = { path = "../../libraries/tock-cells" }
+tock-registers = { path = "../../libraries/tock-register-interface" }
+
+[lints]
+workspace = true

arch/x86-next/README.md

@@ -0,0 +1,8 @@
+x86 Architecture Support Components
+===================================
+
+This crate includes low-level code for x86 32-bit CPU architectures.
+
+This crate implements flat segmentation for memory management. The entire address space of 4Gb is contained in a single unbroken ("flat") memory segment.
+
+Virtual memory is used as an MPU with a 4KB section granularity.

arch/x86-next/src/boundary/boundary_impl.rs

@@ -0,0 +1,190 @@
+// Licensed under the Apache License, Version 2.0 or the MIT License.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// Copyright Tock Contributors 2024.
+
+use core::fmt::Write;
+
+use crate::registers::bits32::eflags::{EFlags, EFLAGS};
+
+use kernel::process::FunctionCall;
+use kernel::syscall::{ContextSwitchReason, Syscall, SyscallReturn, UserspaceKernelBoundary};
+use kernel::ErrorCode;
+
+use crate::interrupts::{IDT_RESERVED_EXCEPTIONS, SYSCALL_VECTOR};
+use crate::segmentation::{USER_CODE, USER_DATA};
+
+use super::UserContext;
+
+/// Defines the usermode-kernelmode ABI for x86 platforms.
+pub struct Boundary;
+
+impl Default for Boundary {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Boundary {
+    /// Minimum required size for initial process memory.
+    ///
+    /// Need at least 5 dwords of initial stack space for CRT 0:
+    ///
+    /// - 1 dword for initial upcall return address (although this will be zero for init_fn)
+    /// - 4 dwords of scratch space for invoking memop syscalls
+    const MIN_APP_BRK: u32 = 5 * core::mem::size_of::<usize>() as u32;
+
+    /// Constructs a new instance of `SysCall`.
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl UserspaceKernelBoundary for Boundary {
+    type StoredState = UserContext;
+
+    fn initial_process_app_brk_size(&self) -> usize {
+        Self::MIN_APP_BRK as usize
+    }
+
+    unsafe fn initialize_process(
+        &self,
+        accessible_memory_start: *const u8,
+        app_brk: *const u8,
+        state: &mut Self::StoredState,
+    ) -> Result<(), ()> {
+        if (app_brk as u32 - accessible_memory_start as u32) < Self::MIN_APP_BRK {
+            return Err(());
+        }
+
+        // We pre-allocate 16 bytes on the stack for initial upcall arguments.
+        let esp = (app_brk as u32) - 16;
+
+        let mut eflags = EFlags::new();
+        eflags.0.modify(EFLAGS::FLAGS_IF::SET);
+
+        state.eax = 0;
+        state.ebx = 0;
+        state.ecx = 0;
+        state.edx = 0;
+        state.esi = 0;
+        state.edi = 0;
+        state.ebp = 0;
+        state.esp = esp;
+        state.eip = 0;
+        state.eflags = eflags.0.get();
+        state.cs = USER_CODE.bits() as u32;
+        state.ss = USER_DATA.bits() as u32;
+        state.ds = USER_DATA.bits() as u32;
+        state.es = USER_DATA.bits() as u32;
+        state.fs = USER_DATA.bits() as u32;
+        state.gs = USER_DATA.bits() as u32;
+
+        Ok(())
+    }
+
+    unsafe fn set_syscall_return_value(
+        &self,
+        _accessible_memory_start: *const u8,
+        _app_brk: *const u8,
+        state: &mut Self::StoredState,
+        return_value: SyscallReturn,
+    ) -> Result<(), ()> {
+        kernel::utilities::arch_helpers::encode_syscall_return_trd104(
+            &kernel::utilities::arch_helpers::TRD104SyscallReturn::from_syscall_return(
+                return_value,
+            ),
+            &mut state.ebx,
+            &mut state.ecx,
+            &mut state.edx,
+            &mut state.edi,
+        );
+
+        Ok(())
+    }
+
+    unsafe fn set_process_function(
+        &self,
+        _accessible_memory_start: *const u8,
+        _app_brk: *const u8,
+        state: &mut Self::StoredState,
+        upcall: FunctionCall,
+    ) -> Result<(), ()> {
+        state.ebx = upcall.argument0 as u32;
+        state.ecx = upcall.argument1 as u32;
+        state.edx = upcall.argument2 as u32;
+        state.edi = upcall.argument3.as_usize() as u32;
+
+        // The next time we switch to this process, we will directly jump to the upcall. When the
+        // upcall issues `ret`, it will return to wherever the yield syscall was invoked.
+        state.eip = upcall.pc.addr() as u32;
+
+        Ok(())
+    }
+
+    unsafe fn switch_to_process(
+        &self,
+        _accessible_memory_start: *const u8,
+        _app_brk: *const u8,
+        state: &mut Self::StoredState,
+    ) -> (ContextSwitchReason, Option<*const u8>) {
+        // Sanity check: don't try to run a faulted app
+        if state.exception != 0 || state.err_code != 0 {
+            let stack_ptr = state.esp as *mut u8;
+            return (ContextSwitchReason::Fault, Some(stack_ptr));
+        }
+
+        let mut err_code = 0;
+        let int_num = unsafe { super::switch_to_user(state, &mut err_code) };
+
+        let reason = match int_num as u8 {
+            0..IDT_RESERVED_EXCEPTIONS => {
+                state.exception = int_num as u8;
+                state.err_code = err_code;
+                ContextSwitchReason::Fault
+            }
+
+            SYSCALL_VECTOR => {
+                let num = state.eax as u8;
+
+                let arg0 = state.ebx;
+                let arg1 = state.ecx;
+                let arg2 = state.edx;
+                let arg3 = state.edi;
+
+                Syscall::from_register_arguments(
+                    num,
+                    arg0 as usize,
+                    (arg1 as usize).into(),
+                    (arg2 as usize).into(),
+                    (arg3 as usize).into(),
+                )
+                .map_or(ContextSwitchReason::Fault, |syscall| {
+                    ContextSwitchReason::SyscallFired { syscall }
+                })
+            }
+            _ => ContextSwitchReason::Interrupted,
+        };
+
+        let stack_ptr = state.esp as *const u8;
+
+        (reason, Some(stack_ptr))
+    }
+
+    unsafe fn print_context(
+        &self,
+        _accessible_memory_start: *const u8,
+        _app_brk: *const u8,
+        state: &Self::StoredState,
+        writer: &mut dyn Write,
+    ) {
+        let _ = writeln!(writer, "{}", state);
+    }
+
+    fn store_context(
+        &self,
+        _state: &Self::StoredState,
+        _out: &mut [u8],
+    ) -> Result<usize, ErrorCode> {
+        unimplemented!()
+    }
+}

arch/x86-next/src/boundary/context.rs

@@ -0,0 +1,86 @@
+// Licensed under the Apache License, Version 2.0 or the MIT License.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// Copyright Tock Contributors 2024.
+
+use core::fmt::{self, Display, Formatter};
+
+use crate::registers::irq::EXCEPTIONS;
+
+/// Stored CPU state of a user-mode app
+///
+/// This struct stores the complete CPU state of a user-mode Tock application on x86.
+///
+/// We access this struct from several assembly routines to perform context switching between user
+/// and kernel mode. For this reason, it is **critical** that the struct have a deterministic layout
+/// in memory. We use `#[repr(C)]` for this.
+#[repr(C)]
+#[derive(Default)]
+pub struct UserContext {
+    pub eax: u32,    // Offset:  0
+    pub ebx: u32,    // Offset:  4
+    pub ecx: u32,    // Offset:  8
+    pub edx: u32,    // Offset: 12
+    pub esi: u32,    // Offset: 16
+    pub edi: u32,    // Offset: 20
+    pub ebp: u32,    // Offset: 24
+    pub esp: u32,    // Offset: 28
+    pub eip: u32,    // Offset: 32
+    pub eflags: u32, // Offset: 36
+    pub cs: u32,     // Offset: 40
+    pub ss: u32,     // Offset: 44
+    pub ds: u32,     // Offset: 48
+    pub es: u32,     // Offset: 52
+    pub fs: u32,     // Offset: 56
+    pub gs: u32,     // Offset: 60
+
+    /// If the process triggers a CPU exception, this field will be populated with the
+    /// exception number. Otherwise this field must remain as zero.
+    pub exception: u8,
+
+    /// If the process triggers a CPU exception with an associated error code, this field will be
+    /// populated with the error code value. Otherwise this field must remain zero.
+    pub err_code: u32,
+}
+
+impl Display for UserContext {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        writeln!(f)?;
+        writeln!(f, " CPU Registers:")?;
+        writeln!(f)?;
+        writeln!(f, "  EAX: {:#010x}      EBX: {:#010x}", self.eax, self.ebx)?;
+        writeln!(f, "  ECX: {:#010x}      EDX: {:#010x}", self.ecx, self.edx)?;
+        writeln!(f, "  ESI: {:#010x}      EDI: {:#010x}", self.esi, self.edi)?;
+        writeln!(f, "  EBP: {:#010x}      ESP: {:#010x}", self.ebp, self.esp)?;
+        writeln!(
+            f,
+            "  EIP: {:#010x}   EFLAGS: {:#010x}",
+            self.eip, self.eflags
+        )?;
+        writeln!(
+            f,
+            "   CS:     {:#06x}       SS:     {:#06x}",
+            self.cs, self.ss
+        )?;
+        writeln!(
+            f,
+            "   DS:     {:#06x}       ES:     {:#06x}",
+            self.ds, self.es
+        )?;
+        writeln!(
+            f,
+            "   FS:     {:#06x}       GS:     {:#06x}",
+            self.fs, self.gs
+        )?;
+
+        if self.exception != 0 || self.err_code != 0 {
+            writeln!(f)?;
+            if let Some(msg) = EXCEPTIONS.get(self.exception as usize) {
+                writeln!(f, " Exception: {}", msg)?;
+            } else {
+                writeln!(f, " Exception Number: {}", self.exception)?;
+            }
+            writeln!(f, " Error code: {:#010x}", self.err_code)?;
+        }
+        Ok(())
+    }
+}

arch/x86-next/src/boundary/mod.rs

@@ -0,0 +1,88 @@
+// Licensed under the Apache License, Version 2.0 or the MIT License.
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+// Copyright Tock Contributors 2024.
+
+//! Usermode-kernelmode boundary for the x86 architecture
+//!
+//! This module defines the boundary between user and kernel modes on the x86 architecture,
+//! including syscall/upcall calling conventions as well as process initialization.
+//!
+//! In contrast with other embedded architectures like ARM or RISC-V, x86 does _not_ have very many
+//! general purpose registers to spare. The ABI defined here draws heavily from the `cdecl` calling
+//! convention by using the stack instead of registers to pass data between user and kernel mode.
+//!
+//! ## System Calls
+//!
+//! System calls are dispatched from user- to kernel-mode using interrupt number 0x40. The system
+//! call class number is stored in EAX.
+//!
+//! ECX and EDX are treated as caller-saved registers, which means their values should be considered
+//! undefined after the return of a system call. The kernel itself will backup and restore ECX/EDX,
+//! however they may get clobbered if an upcall is pushed.
+//!
+//! Arguments and return values are passed via the user-mode stack in reverse order (similar to
+//! `cdecl`). The caller must _always_ push 4 values to the stack, even for system calls which have
+//! less than 4 arguments. This is because the kernel may return up to 4 values.
+//!
+//! As with `cdecl`, the caller is responsible for incrementing ESP to clean up the stack frame
+//! after the system call returns.
+//!
+//! The following assembly snippet shows how to invoke the `yield` syscall:
+//!
+//! ```text
+//! push    0           # arg 4: unused
+//! push    0           # arg 3: unused
+//! push    0           # arg 2: unused
+//! push    1           # arg 1: yield-wait
+//! mov     eax, 0      # class: yield
+//! int     0x40
+//! add     esp, 16     # clean up stack
+//! ```
+//!
+//! ## Yielding and Upcalls
+//!
+//! Upcalls are expected to be standard `cdecl` functions. The kernel will write arguments and a
+//! return value to the stack before jumping to an upcall.
+//!
+//! The return address pushed by the kernel will point to the instruction immediately following the
+//! `yield` syscall which led to the upcall. This means when the upcall finishes and returns, the
+//! app will continue executing wherever it left off when `yield` was called, without context
+//! switching back to kernel.
+//!
+//! The app should have allocated 16 bytes of stack space for arguments to/return values from the
+//! `yield` syscall (see above). Since `yield` does not actually return anything, this stack space
+//! is repurposed to store the upcall arguments. This way when an upcall returns, the app only needs
+//! to clean up 16 bytes of stack space; in this sense, the ABI of `yield` is no different than any
+//! other syscall.
+//!
+//! ## Process Initialization
+//!
+//! Tock treats process entry points just like upcalls, except they are never expected to return.
+//! For x86, this means the process entry point should use the `cdecl` function.
+//!
+//! For x86, we allocate an initial stack of 36 bytes before calling this upcall. The top 20 bytes
+//! are used to invoke the entry point itself: 16 for arguments, and 4 for a return address (which
+//! should never be used).
+//!
+//! The remaining 16 bytes are free for use by the entry point. This is exactly enough stack space
+//! to invoke system calls. In most cases, the first task of the app entry point will be to allocate
+//! itself a larger stack.
+
+mod context;
+use context::UserContext;
+
+mod boundary_impl;
+pub use self::boundary_impl::Boundary;
+
+#[cfg(target_arch = "x86")]
+mod switch_to_user;
+
+#[cfg(target_arch = "x86")]
+mod return_from_user;
+
+extern "cdecl" {
+    /// Performs a context switch to the given process.
+    ///
+    /// See _switch_to_user.s_ for complete details.
+    fn switch_to_user(context: *mut UserContext, error_code: *mut u32) -> u32;
+}