syscall.md

System Calls

This document outlines the system calls provided by the SCore kernel, their corresponding numbers, and their functionalities.

System Call Numbers

The following constants define the unique IDs for each system call.

const SYSCALL_SHUTDOWN: usize = 0;
const SYSCALL_OPEN: usize = 56;
const SYSCALL_CLOSE: usize = 57;
const SYSCALL_READ: usize = 63;
const SYSCALL_WRITE: usize = 64;
const SYSCALL_EXIT: usize = 93;
const SYSCALL_YIELD: usize = 124;
const SYSCALL_GET_TIME: usize = 169;
const SYSCALL_GET_PID: usize = 172;
const SYSCALL_FORK: usize = 220;
const SYSCALL_EXEC: usize = 221;
const SYSCALL_WAITPID: usize = 260; // Note: WAID_PID in original, corrected to WAITPID

System Call Functions

The following functions are the kernel-side handlers for system calls initiated by user applications.

pub fn sys_shutdown() -> ! Shuts down the entire system.

pub fn sys_write(fd: usize, buffer: &[u8]) -> isize Writes data from a buffer in memory to a file specified by the file descriptor fd.

pub fn sys_exit(exit_code: i32) -> ! Exits the current application and reports its exit_code to the parent process.

pub fn sys_yield() -> isize Allows an application to voluntarily yield CPU control, scheduling another application to run.

pub fn sys_get_time() -> isize Gets the current system time (e.g., in milliseconds).

pub fn sys_fork() -> isize Creates a new child process that is a copy of the current process.

pub fn sys_exec(path: &str) -> isize Replaces the current process's address space with a new program loaded from the specified path.

pub fn sys_waitpid(pid: isize, exit_code: *mut i32) -> isize Waits for a child process with the specified pid to terminate, reclaims its resources, and collects its exit code.

pub fn sys_getpid() -> isize Gets the Process ID (PID) of the current process.

pub fn sys_read(fd: usize, buffer: &mut [u8]) -> isize Reads content from a file into a buffer.

pub fn sys_open(path: &str, flags: u32) -> isize Opens a regular file and returns a file descriptor for it.

pub fn sys_close(fd: usize) -> isize Closes a file descriptor.

System Call Implementation

The syscall! macro provides a convenient wrapper for making system calls from user space on the RISC-V architecture. It uses inline assembly to load the system call ID and arguments into the appropriate registers (a7 for the ID, a0-a2 for arguments) and then executes the ecall instruction. This instruction triggers a trap into the kernel, which then handles the request. The return value from the kernel is placed in the a0 register and captured by the macro.

This macro abstracts the low-level assembly details, simplifying the implementation of the user-space library functions that applications use to interact with the kernel.

macro_rules! syscall {
    ($id:expr, $args:expr) => {{
        let mut ret: usize;
        unsafe {
            core::arch::asm!(
                "ecall",
                inlateout("x10") $args[0] => ret, // a0
                in("x11") $args[1],             // a1
                in("x12") $args[2],             // a2
                in("x17") $id                   // a7
            )
        }
        ret as isize
    }};
}