Improve documentation

[vinc]

No description provided.

[vinc]

This last commit fixes a issue when setting the time. This was working:

> print "2025-01-01 00:00:00" => /dev/clk/rtc
[22.232614] RTC 2025-01-01 00:00:00 +0000

But not this:

> print 2023-03-21 10:00:00 => /dev/clk/rtc

Because the arguments were printed one after the other so the RTC device would not get a buffer containing the whole date and time, instead it would get the date first, then the time, which it couldn't parse to set the date and time. This is an implementation issue and not expected from the user perspective.

The solution was to join all the arguments (with a space) before printing them. We couldn't do this in the past because we couldn't allocate memory from userspace but now we can.

[vinc]

The following command can be used to compare the doc and the high level wrapper of the syscalls:

$ grep -h "fn " doc/syscalls.md src/api/syscall.rs | sed "s/pub fn/fn/g" | sort

It's not clear yet how to document both the raw syscalls and their high level wrappers used in the userspace Rust API.

[vinc]

We can now run the following command to make sure that the syscalls doc is up to date:

$ grep -h "fn " doc/syscalls.md src/api/syscall.rs | grep -v "fn test" | sed "s/pub fn/fn/g" | sed "s/ {//g" | sort | uniq -c
      2 fn accept(handle: usize) -> Result<IpAddress, ()>
      2 fn alloc(size: usize, align: usize) -> *mut u8
      2 fn close(handle: usize)
      2 fn connect(handle: usize, addr: IpAddress, port: u16) -> Result<(), ()>
      2 fn delete(path: &str) -> Result<(), ()>
      2 fn dup(old_handle: usize, new_handle: usize) -> Result<(), ()>
      2 fn exit(code: ExitCode)
      2 fn free(ptr: *mut u8, size: usize, align: usize)
      2 fn info(path: &str) -> Option<FileInfo>
      2 fn kind(handle: usize) -> Option<FileType>
      2 fn listen(handle: usize, port: u16) -> Result<(), ()>
      2 fn open(path: &str, flags: u8) -> Option<usize>
      2 fn poll(list: &[(usize, IO)]) -> Option<(usize, IO)>
      2 fn read(handle: usize, buf: &mut [u8]) -> Option<usize>
      2 fn sleep(seconds: f64)
      2 fn spawn(path: &str, args: &[&str]) -> Result<(), ExitCode>
      2 fn stop(code: usize)
      2 fn write(handle: usize, buf: &[u8]) -> Option<usize>

[vinc]

This commit clarify the code of spawn to show which parts are unreachable!() after the kernel switch to the new child process.

It also simplify its return type and fix an issue where the return code passed by the child on exit would appear to be 0 by the parent at the end of spawn unless a fence is used.

Here we can see exit working correctly when a user space program encounter an error and return a UsageError (64) exit code. The shell has the correct value.