add docs for syscalls. make syscall code kind-of cleaner

1 files changed, 264 insertions, 0 deletions

diff --git a/doc/syscall.md b/doc/syscall.md
new file mode 100644
index 0000000..9304785
--- /dev/null
+++ b/doc/syscall.md
@@ -0,0 +1,264 @@
+## Jove syscalls
+
+Every syscall in Jove is passed to the kernel via a `JOVE_OBJ_MESSAGE` object.
+
+To pass a message object to the kernel, the message object must be close to the root directory of the calling PCB.
+
+To resolve the message object, the kernel requires an object path and a path length encoded in argument registers.
+
+On x86_64, the encoding is as follows:
+
+|          | Message Path | Message Path Length |
+|----------|--------------|---------------------|
+| Register |      rdi     |         rsi         |
+
+If the message path exceeds the width of the message path register, the kernel will return `-EBADPATH`.
+
+If the message path does not point to a `JOVE_OBJ_MESSAGE` object, the kernel will return `-EBADOBJ`.
+
+If the message path points to an object locked by a mutex, the kernel will return `-EBUSY`.
+
+
+### Syscall header
+
+| Size (bytes) | 2       | 2                      | path_len * 2 |
+|--------------|---------|------------------------|--------------|
+| Data         | Call ID | Path length (path_len) | Target path  |
+
+All system calls must start with these bytes at the start of the passed message object.
+
+1. `Call ID`: ID of the system call to invoke.
+2. `Path length`: Length of the target path.
+3. `Object path`: Path to the target object starting from the PCB's root directory.
+
+If the target path length exceeds the width of the message object, the kernel will return `-ETOOSMALL`.
+
+If the target path points to a `JOVE_OBJ_NONE` object, the kernel will return `-EBADOBJ`.
+
+If the target object does not support the call id, the kernel will return `-EBADCALL`.
+
+Further behavior is specified by the target syscall specification.
+
+Target syscalls may have further required bytes in the message.
+
+If the syscall does not have the correct permissions for the syscall, the kernel will return `-ENOPERM`.
+
+
+### JOVE_OBJ_UNTYPED
+
+| Syscall                 | Permissions Required              |
+|-------------------------|-----------------------------------|
+| SYSCALL_UNTYPED_ADDRESS | JOVE_PERM_READ                    |
+| SYSCALL_UNTYPED_SIZE    | JOVE_PERM_READ                    |
+| SYSCALL_UNTYPED_SPLIT   | JOVE_PERM_WRITE, JOVE_PERM_MUTATE |
+| SYSCALL_UNTYPED_MERGE   | JOVE_PERM_WRITE, JOVE_PERM_MUTATE |
+| SYSCALL_UNTYPED_RETYPE  | JOVE_PERM_WRITE, JOVE_PERM_MUTATE |
+
+#### SYSCALL_UNTYPED_ADDRESS
+
+Returns the physical address of the untyped memory span.
+
+#### SYSCALL_UNTYPED_SIZE
+
+Returns the size of the untyped memory span.
+
+#### SYSCALL_UNTYPED_SPLIT
+
+Splits the untyped memory span into the destination path sized by the split size.
+
+| Data         | Split size     | Destination Path Length | Destination Path |
+|--------------|----------------|-------------------------|------------------|
+| Size (bytes) | sizeof(size_t) |            2            |   path_len * 2   |
+
+
+If the split size exceeds the size of the target untyped, the kernel will return `-ETOOBIG`.
+
+If the split size is less than `JOVE_UNTYPED_MINSIZE`, the kernel will return `-ETOOSMALL`.
+
+If the destination path length exceeds the size of the message, the kernel will return `-EBADPATH`.
+
+If the destination path does not point to a `JOVE_OBJ_NONE` object, the kernel will return `-EBADOBJ`.
+
+#### SYSCALL_UNTYPED_MERGE
+
+Merges two adjacent untyped memory spans into one untyped memory span at the first untyped object.
+
+| Data         | Untyped Path Length | Untyped Path |
+|--------------|---------------------|--------------|
+| Size (bytes) |          2          | path_len * 2 |
+
+
+If the untyped path length exceeds the size of the message, the kernel will return `-EBADPATH`.
+
+If the untyped path does not point to a `JOVE_OBJ_NONE` object, the kernel will return `-EBADOBJ`.
+
+
+### JOVE_OBJ_OBJDIR
+
+| Syscall                | Permissions Required |
+|------------------------|----------------------|
+| SYSCALL_OBJDIR_OBJTYPE | JOVE_PERM_READ       |
+
+#### SYSCALL_OBJDIR_OBJTYPE
+
+Returns the object type at the given entry index.
+
+| Data         | Entry Index |
+|--------------|-------------|
+| Size (bytes) |      2      |
+
+If the message is too small to hold the payload, the kernel will return `-ETOOSMALL`.
+
+If the entry index exceeds `JOVE_OBJDIR_ENTRIES`, the kernel returns `-EOOB`.
+
+
+### JOVE_OBJ_PAGEDIR
+
+| Syscall                     |        Target Permissions       |                Subject Permissions                | Subject Conditional Permissions |
+|-----------------------------|:-------------------------------:|:-------------------------------------------------:|:-------------------------------:|
+| SYSCALL_PAGEDIR_MAP_FRAME   | JOVE_PERM_READ, JOVE_PERM_WRITE | JOVE_PERM_MUTATE                                  | JOVE_PERM_READ, JOVE_PERM_WRITE |
+| SYSCALL_PAGEDIR_MAP_TABLE   | JOVE_PERM_READ, JOVE_PERM_WRITE | JOVE_PERM_READ, JOVE_PERM_WRITE, JOVE_PERM_MUTATE |                                 |
+| SYSCALL_PAGEDIR_MAP_SHMEM   | JOVE_PERM_READ, JOVE_PERM_WRITE |                                                   | JOVE_PERM_READ, JOVE_PERM_WRITE |
+| SYSCALL_PAGEDIR_UNMAP_FRAME | JOVE_PERM_READ, JOVE_PERM_WRITE |                                                   |                                 |
+| SYSCALL_PAGEDIR_UNMAP_TABLE | JOVE_PERM_READ, JOVE_PERM_WRITE |                                                   |                                 |
+| SYSCALL_PAGEDIR_UNMAP_SHMEM | JOVE_PERM_READ, JOVE_PERM_WRITE |                                                   |                                 |
+
+
+#### SYSCALL_PAGEDIR_MAP_FRAME
+
+Attempts to map a given untyped memory span to the given virtual address with passed permissions.
+
+| Data         | Page flags | Untyped Path Length | Virtual address   | Untyped Path |
+|--------------|------------|---------------------|-------------------|--------------|
+| Size (bytes) |      1     |          2          | sizeof(void*)     | path_len * 2 |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the untyped path does not point to a `JOVE_OBJ_UNTYPED` object, the kernel will return `-EBADOBJ`.
+
+If the untyped object is not aligned to `0x1000` bytes, the kernel will return `-EALIGN`.
+
+If the untyped object is not exactly `0x1000` bytes wide, the kernel will return `-EBADSIZE`.
+
+If the untyped object does not have `JOVE_PERM_MUTATE` and `JOVE_PERM_READ`, the kernel will return `-ENOPERM`.
+
+If the untyped object does not have `JOVE_PERM_WRITE` and the passed flags include the writeable bit, the kernel will return `-ENOPERM.`.
+
+If the virtual address does not have enough page table structures to support the page mapping, the kernel will return `-ENOMAP`.
+
+If the virtual address already has a page mapping, the kernel will return `-EHASMAP`.
+
+Successful mapping replaces the untyped object with a `JOVE_OBJ_NONE` object and returns `0`.
+
+
+#### SYSCALL_PAGEDIR_MAP_TABLE
+
+Attempts to map a given untyped memory span as a table for mapping further page frames onto `virtual address`.
+
+| Data         | Virtual address | Untyped Path Length | Untyped Path |
+|--------------|-----------------|---------------------|--------------|
+| Size (bytes) |  sizeof(void*)  |          2          | path_len * 2 |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the untyped path does not point to a `JOVE_OBJ_UNTYPED` object, the kernel will return `-EBADOBJ`.
+
+If the untyped object is not aligned to `0x1000` bytes, the kernel will return `-EALIGN`.
+
+If the untyped object is not exactly `0x1000` bytes wide, the kernel will return `-EBADSIZE`.
+
+If the untyped object does not have `JOVE_PERM_MUTATE`, `JOVE_PERM_READ`, and `JOVE_PERM_WRITE`, the kernel will return `-ENOPERM`.
+
+If the virtual address already has enough tables to allocate a page frame onto them, the kernel will return `-EHASMAP`.
+
+Successful mapping replaces the untyped object with a `JOVE_OBJ_NONE` object and returns `0`.
+
+
+#### SYSCALL_PAGEDIR_MAP_SHMEM
+
+Attempts to map a shared memory page at `virtual address`. Does not consume the shared memory object.
+
+| Data         | Page flags | Page offset | Shared Memory Path Length | Virtual address | Shared Memory Path |
+|--------------|------------|-------------|---------------------------|-----------------|--------------------|
+| Size (bytes) |      1     |      1      |             2             |  sizeof(void*)  |    path_len * 2    |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the shmem path does not point to a `JOVE_OBJ_SHMEMORY` object, the kernel will return `-EBADOBJ`.
+
+If the shmem object does not have `JOVE_PERM_READ`, the kernel will return `-ENOPERM`.
+
+If the shmem object does not have `JOVE_PERM_WRITE` and the passed flags include the writeable bit, the kernel will return `-ENOPERM.`.
+
+If the virtual address does not have enough page table structures to support the page mapping, the kernel will return `-ENOMAP`.
+
+If the virtual address already has a page mapping, the kernel will return `-EHASMAP`.
+
+Successful mapping returns `0`.
+
+
+#### SYSCALL_PAGEDIR_UNMAP_FRAME
+
+Attempts to remove an untyped memory mapping from the page table at `virtual address`.
+
+| Data         | Virtual address | Destination Path Length | Destination Path |
+|--------------|-----------------|-------------------------|------------------|
+| Size (bytes) |  sizeof(void*)  |            2            |   path_len * 2   |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the destination path does not point to a `JOVE_OBJ_NONE` object, the kernel will return `-EFULL`.
+
+If the virtual address does not have a page mapping, the kernel will return `-ENOMAP`.
+
+If the virtual address does not map to an untyped page frame, the kernel will return `-EBADARG`.
+
+Successful unmapping fills the destination path with a page-sized `JOVE_OBJ_UNTYPED` object with correct permissions and return 0.
+
+
+#### SYSCALL_PAGEDIR_UNMAP_TABLE
+
+Attempts to remove a page table mapping from the page directory heirarchy at `virtual address`
+
+| Data         | Virtual address | Destination Path Length | Destination Path |
+|--------------|-----------------|-------------------------|------------------|
+| Size (bytes) |  sizeof(void*)  |            2            |   path_len * 2   |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the destination path does not point to a `JOVE_OBJ_NONE` object, the kernel will return `-EFULL`.
+
+If the table mapping the virtual address has any occupied entries, the kernel will return `-EHASMAP`.
+
+If no table mapping exists for this virtual address, the kernel will return `-ENOMAP`.
+
+Successful unmapping fills the destination path with a page-sized `JOVE_OBJ_UNTYPED` object with correct permissions and return 0.
+
+
+#### SYSCALL_PAGEDIR_UNMAP_SHMEM
+
+Attempts to unmap a shared memory page at `virtual address`.
+
+| Data         | Virtual address |
+|--------------|-----------------|
+| Size (bytes) |  sizeof(void*)  |
+
+If the message is too small for the syscall payload, the kernel will return `-ETOOSMALL`.
+
+If the virtual address exceeds `JOVE_USER_MEMORY_LIMIT`, the kernel will return `-EOOB`.
+
+If the virtual address does not have a page frame associated with it, the kernel will return `-ENOMAP`.
+
+If the page frame pointed to by virtual address does not correspond to a shared memory frame, the kernel will return `-EBADOBJ`.
+
+Successful unmapping returns `0`.