Skip to content

Commit

Permalink
Add documentation for both the raw syscall and its high-level wrapper
Browse files Browse the repository at this point in the history
  • Loading branch information
@vinc
vinc committed Nov 3, 2024
1 parent 8bb6856 commit 26d7333
Show file tree
Hide file tree
Showing 2 changed files with 148 additions and 26 deletions.
88 changes: 75 additions & 13 deletions doc/syscalls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -82,12 +132,12 @@ Close a file handle.
## INFO (0x07)

```rust
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:

```rust
struct FileInfo {
Expand All @@ -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
Expand Down Expand Up @@ -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<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)

Expand All @@ -209,11 +267,12 @@ Free memory.
## KIND (0x12)

```rust
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:

```rust
enum FileType {
Expand All @@ -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.
86 changes: 73 additions & 13 deletions www/syscalls.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,67 @@ <h1>MOROS Syscalls</h1>

<p>This list is unstable and subject to change between versions of MOROS.</p>

<p>Any reference to a slice in the arguments (like <code>&amp;str</code> or <code>&amp;[u8]</code>) will be
converted into a pointer and a length before the syscall is made.</p>
<p>Each syscall is documented with its raw interface and its high-level Rust API
wrapper.</p>

<p>Any reference to a slice in the arguments (like <code>&amp;str</code> or <code>&amp;[u8]</code>) will need to
be converted into a pointer and a length for the raw syscall.</p>

<p>Any negative number returned indicates that an error has occurred. In the
higher level API, this will be typically converted to a <code>Result</code> type.</p>
higher-level API, this will be typically converted to an <code>Option</code> or a <code>Result</code>
type.</p>

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

<p>Hello world example in assembly:</p>

<pre><code class="nasm">[bits 64]

section .data
msg: db &quot;Hello, World!&quot;, 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
</code></pre>

<h2>EXIT (0x01)</h2>

<pre><code class="rust">fn exit(code: usize)
<pre><code class="rust">fn exit(code: ExitCode)
</code></pre>

<p>Terminate the calling process.</p>

<p>The code can be one of the following:</p>

<pre><code class="rust">pub enum ExitCode {
Success = 0,
Failure = 1,
UsageError = 64,
DataError = 65,
OpenError = 128,
ReadError = 129,
ExecError = 130,
PageFaultError = 200,
ShellExit = 255,
}
</code></pre>

<p>The <code>ExitCode</code> is converted to a <code>usize</code> for the raw syscall.</p>

<h2>SPAWN (0x02)</h2>

<pre><code class="rust">fn spawn(path: &amp;str, args: &amp;[&amp;str]) -&gt; isize
Expand Down Expand Up @@ -50,7 +98,7 @@ <h2>WRITE (0x04)</h2>

<h2>OPEN (0x05)</h2>

<pre><code class="rust">fn open(path: &amp;str, flags: usize) -&gt; isize
<pre><code class="rust">fn open(path: &amp;str, flags: u8) -&gt; isize
</code></pre>

<p>Open a file and return a file handle.</p>
Expand Down Expand Up @@ -82,12 +130,12 @@ <h2>CLOSE (0x06)</h2>

<h2>INFO (0x07)</h2>

<pre><code class="rust">fn info(path: &amp;str, info: &amp;mut FileInfo) -&gt; isize
<pre><code class="rust">fn info(path: &amp;str) -&gt; Option&lt;FileInfo&gt;
</code></pre>

<p>Get informations on a file.</p>

<p>This syscall will set the following attributes of the given structure:</p>
<p>A <code>FileInfo</code> will be returned when successful:</p>

<pre><code class="rust">struct FileInfo {
kind: FileType,
Expand All @@ -97,6 +145,10 @@ <h2>INFO (0x07)</h2>
}
</code></pre>

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

<h2>DUP (0x08)</h2>

<pre><code class="rust">fn dup(old_handle: usize, new_handle: usize) -&gt; isize
Expand Down Expand Up @@ -170,14 +222,18 @@ <h2>LISTEN (0x0E)</h2>
<pre><code class="rust">fn listen(handle: usize, port: u16) -&gt; isize
</code></pre>

<p>Listen for incoming connections on a socket.</p>
<p>Listen for incoming connections to a socket.</p>

<h2>ACCEPT (0x0F)</h2>

<pre><code class="rust">fn accept(handle: usize, addr: IpAddress) -&gt; isize
<pre><code class="rust">fn accept(handle: usize) -&gt; Result&lt;IpAddress&gt;
</code></pre>

<p>Accept incoming connection on a socket.</p>
<p>Accept an incoming connection to a socket.</p>

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

<h2>ALLOC (0x10)</h2>

Expand All @@ -195,18 +251,22 @@ <h2>FREE (0x11)</h2>

<h2>KIND (0x12)</h2>

<pre><code class="rust">fn kind(handle: usize) -&gt; isize
<pre><code class="rust">fn kind(handle: usize) -&gt; Option&lt;FileType&gt;
</code></pre>

<p>This syscall will return a integer corresponding to the <code>FileType</code> of the given
file handle when successful:</p>
<p>Return the file type of a file handle.</p>

<p>A <code>FileType</code> will be returned when successful:</p>

<pre><code class="rust">enum FileType {
Dir = 0,
File = 1,
Device = 2,
}
</code></pre>

<p>The raw syscall returns an <code>isize</code> that will be converted a <code>FileType</code> if the
number is positive.</p>
<footer><p><a href="/">MOROS</a></footer>
</body>
</html>

0 comments on commit 26d7333

Please sign in to comment.