From 26d7333417b912fad1f2e1f79d492cbeb50ad177 Mon Sep 17 00:00:00 2001 From: Vincent Ollivier Date: Sun, 3 Nov 2024 18:45:53 +0100 Subject: [PATCH] Add documentation for both the raw syscall and its high-level wrapper --- doc/syscalls.md | 88 ++++++++++++++++++++++++++++++++++++++++------- www/syscalls.html | 86 ++++++++++++++++++++++++++++++++++++++------- 2 files changed, 148 insertions(+), 26 deletions(-) diff --git a/doc/syscalls.md b/doc/syscalls.md index e8c23a37..cd9e6a54 100644 --- a/doc/syscalls.md +++ b/doc/syscalls.md @@ -2,20 +2,70 @@ This list is unstable and subject to change between versions of MOROS. -Any reference to a slice in the arguments (like `&str` or `&[u8]`) will be -converted into a pointer and a length before the syscall is made. +Each syscall is documented with its raw interface and its high-level Rust API +wrapper. + +Any reference to a slice in the arguments (like `&str` or `&[u8]`) will need to +be converted into a pointer and a length for the raw syscall. Any negative number returned indicates that an error has occurred. In the -higher level API, this will be typically converted to a `Result` type. +higher-level API, this will be typically converted to an `Option` or a `Result` +type. + +At the lowest level a syscalls follows the System V ABI convention with the +syscall number set in the `RAX` register, and its arguments in the `RDI`, +`RSI`, `RDX`, and `R8` registers. The `RAX` register is used for the return +value. + +Hello world example in assembly: + +```nasm +[bits 64] + +section .data +msg: db "Hello, World!", 10 +len: equ $-msg + +global _start +section .text +_start: + mov rax, 4 ; syscall number for WRITE + mov rdi, 1 ; standard output + mov rsi, msg ; addr of string + mov rdx, len ; size of string + int 0x80 + + mov rax, 1 ; syscall number for EXIT + mov rdi, 0 ; no error + int 0x80 +``` ## EXIT (0x01) ```rust -fn exit(code: usize) +fn exit(code: ExitCode) ``` Terminate the calling process. +The code can be one of the following: + +```rust +pub enum ExitCode { + Success = 0, + Failure = 1, + UsageError = 64, + DataError = 65, + OpenError = 128, + ReadError = 129, + ExecError = 130, + PageFaultError = 200, + ShellExit = 255, +} +``` + +The `ExitCode` is converted to a `usize` for the raw syscall. + ## SPAWN (0x02) ```rust @@ -47,7 +97,7 @@ Return the number of bytes written. ## OPEN (0x05) ```rust -fn open(path: &str, flags: usize) -> isize +fn open(path: &str, flags: u8) -> isize ``` Open a file and return a file handle. @@ -82,12 +132,12 @@ Close a file handle. ## INFO (0x07) ```rust -fn info(path: &str, info: &mut FileInfo) -> isize +fn info(path: &str) -> Option ``` Get informations on a file. -This syscall will set the following attributes of the given structure: +A `FileInfo` will be returned when successful: ```rust struct FileInfo { @@ -98,6 +148,10 @@ struct FileInfo { } ``` +The raw syscall takes the pointer and the length of a mutable reference to a +`FileInfo` that will be overwritten on success and returns an `isize` to +indicate the result of the operation. + ## DUP (0x08) ```rust @@ -180,15 +234,19 @@ NOTE: Only IPv4 is currently supported. fn listen(handle: usize, port: u16) -> isize ``` -Listen for incoming connections on a socket. +Listen for incoming connections to a socket. ## ACCEPT (0x0F) ```rust -fn accept(handle: usize, addr: IpAddress) -> isize +fn accept(handle: usize) -> Result ``` -Accept incoming connection on a socket. +Accept an incoming connection to a socket. + +The raw syscall takes the pointer and the length of a mutable reference to an +`IpAddress` that will be overwritten on success and returns an `isize` +indicating the result of the operation. ## ALLOC (0x10) @@ -209,11 +267,12 @@ Free memory. ## KIND (0x12) ```rust -fn kind(handle: usize) -> isize +fn kind(handle: usize) -> Option ``` -This syscall will return a integer corresponding to the `FileType` of the given -file handle when successful: +Return the file type of a file handle. + +A `FileType` will be returned when successful: ```rust enum FileType { @@ -222,3 +281,6 @@ enum FileType { Device = 2, } ``` + +The raw syscall returns an `isize` that will be converted a `FileType` if the +number is positive. diff --git a/www/syscalls.html b/www/syscalls.html index 318c811e..aea0fab8 100644 --- a/www/syscalls.html +++ b/www/syscalls.html @@ -10,19 +10,67 @@

MOROS Syscalls

This list is unstable and subject to change between versions of MOROS.

-

Any reference to a slice in the arguments (like &str or &[u8]) will be -converted into a pointer and a length before the syscall is made.

+

Each syscall is documented with its raw interface and its high-level Rust API +wrapper.

+ +

Any reference to a slice in the arguments (like &str or &[u8]) will need to +be converted into a pointer and a length for the raw syscall.

Any negative number returned indicates that an error has occurred. In the -higher level API, this will be typically converted to a Result type.

+higher-level API, this will be typically converted to an Option or a Result +type.

+ +

At the lowest level a syscalls follows the System V ABI convention with the +syscall number set in the RAX register, and its arguments in the RDI, + RSI, RDX, and R8 registers. The RAX register is used for the return +value.

+ +

Hello world example in assembly:

+ + 
[bits 64]
+
+section .data
+msg: db "Hello, World!", 10
+len: equ $-msg
+
+global _start
+section .text
+_start:
+  mov rax, 4                ; syscall number for WRITE
+  mov rdi, 1                ; standard output
+  mov rsi, msg              ; addr of string
+  mov rdx, len              ; size of string
+  int 0x80
+
+  mov rax, 1                ; syscall number for EXIT
+  mov rdi, 0                ; no error
+  int 0x80
+

EXIT (0x01)

- 
fn exit(code: usize)
+    
fn exit(code: ExitCode)
 

 
     
Terminate the calling process.

 
+    
The code can be one of the following:

+
+    
pub enum ExitCode {
+    Success        =   0,
+    Failure        =   1,
+    UsageError     =  64,
+    DataError      =  65,
+    OpenError      = 128,
+    ReadError      = 129,
+    ExecError      = 130,
+    PageFaultError = 200,
+    ShellExit      = 255,
+}
+

+
+    
The ExitCode is converted to a usize for the raw syscall.

+
     
SPAWN (0x02)

 
     
fn spawn(path: &str, args: &[&str]) -> isize
@@ -50,7 +98,7 @@ 
WRITE (0x04)

 
     
OPEN (0x05)

 
-    
fn open(path: &str, flags: usize) -> isize
+    
fn open(path: &str, flags: u8) -> isize
 

 
     
Open a file and return a file handle.

@@ -82,12 +130,12 @@ 
CLOSE (0x06)

 
     
INFO (0x07)

 
-    
fn info(path: &str, info: &mut FileInfo) -> isize
+    
fn info(path: &str) -> Option<FileInfo>
 

 
     
Get informations on a file.

 
-    
This syscall will set the following attributes of the given structure:

+    
A FileInfo will be returned when successful:

 
     
struct FileInfo {
     kind: FileType,
@@ -97,6 +145,10 @@ 
INFO (0x07)

 }
 

 
+    
The raw syscall takes the pointer and the length of a mutable reference to a
+    FileInfo that will be overwritten on success and returns an isize to
+indicate the result of the operation.

+
     
DUP (0x08)

 
     
fn dup(old_handle: usize, new_handle: usize) -> isize
@@ -170,14 +222,18 @@ 
LISTEN (0x0E)

     
fn listen(handle: usize, port: u16) -> isize
 

 
-    
Listen for incoming connections on a socket.

+    
Listen for incoming connections to a socket.

 
     
ACCEPT (0x0F)

 
-    
fn accept(handle: usize, addr: IpAddress) -> isize
+    
fn accept(handle: usize) -> Result<IpAddress>
 

 
-    
Accept incoming connection on a socket.

+    
Accept an incoming connection to a socket.

+
+    
The raw syscall takes the pointer and the length of a mutable reference to an
+    IpAddress that will be overwritten on success and returns an isize
+indicating the result of the operation.

 
     
ALLOC (0x10)

 
@@ -195,11 +251,12 @@ 
FREE (0x11)

 
     
KIND (0x12)

 
-    
fn kind(handle: usize) -> isize
+    
fn kind(handle: usize) -> Option<FileType>
 

 
-    
This syscall will return a integer corresponding to the FileType of the given
-file handle when successful:

+    
Return the file type of a file handle.

+
+    
A FileType will be returned when successful:

 
     
enum FileType {
     Dir = 0,
@@ -207,6 +264,9 @@ 
KIND (0x12)

     Device = 2,
 }
 

+
+    
The raw syscall returns an isize that will be converted a FileType if the
+number is positive.