182 lines
16 KiB
Markdown
182 lines
16 KiB
Markdown
# SysABI
|
|
|
|
Syscalls are a way for programms to communicate with the kernel.
|
|
|
|
To perform a syscall, you need to populate the following registers:
|
|
|
|
| Register | Value |
|
|
|----------|-----------------|
|
|
| rax | The syscalls ID |
|
|
| rdi | Argument 1 |
|
|
| rsi | Argument 2 |
|
|
| rdx | Argument 3 |
|
|
| rcx | Argument 4 |
|
|
|
|
Then you need to call interrupt `0x80`.
|
|
|
|
libnx provides abstractions for all syscalls.
|
|
|
|
---
|
|
|
|
The following calls should be implemented to some degree in noxos 1.0.
|
|
|
|
# Categories
|
|
## Files
|
|
| ID | Name | Description | Arg1 | Arg2 | Arg3 | Arg4 | Result | Status |
|
|
|--------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|--------|------|-------------|--------|-------------|
|
|
| 0x0001 | `nx_fs_open` | Opens the file at the _len_ bytes long path _path_ and writes a file descriptor to the referenced file into _fd_ (which needs to be a pointer). | path | len | *fd | | status | Implemented |
|
|
| 0x0002 | `nx_fs_close` | Closes the file which is indicated by descriptor _fd_. This should always be called, otherwise the OS will have to unload files without knowledge of usage. | fd | | | | status | Implemented |
|
|
| 0x0003 | `nx_fs_read` | Reads at most _n_ bytes from a file given as descriptor _fd_ and at a specific position _offset_ into a given memory region _mem_. | fd | offset | mem | n | status | Implemented |
|
|
| 0x0004 | `nx_fs_write` | Writes _n_ bytes from a given memory region _mem_ into the file referenced by _fd_ at the given position _offset_, not inserting but either overwriting existing content or appending to the file. | fd | offset | mem | n | status | Implemented |
|
|
| 0x0005 | `nx_fs_delete` | Completely delete the file or folder at a given path _path_, which is _len_ bytes long. | path | len | | | status | Implemented |
|
|
| 0x0006 | `nx_fs_list` | List all files and/or directories at the _len_ bytes long path _path_ and write their NULL-separated names into _mem_. When _mem_ is NULL, _needed_mem_ (which needs to be a pointer to an 32-bit integer) is filled with the appropriate value. | path | len | mem | *needed_mem | status | Implemented |
|
|
| 0x0007 | `nx_fs_info` | Writes the information about the files attribute _attr_ into mem. Types of attributes are described below. | fd | attr | mem | | status | N/A |
|
|
|
|
**Note:** The _len_ argument of paths isn't used at the moment, rather than using _len_, _path_ needs to be Null-Terminated.
|
|
|
|
## Memory
|
|
| ID | Name | Description | Arg1 | Arg2 | Arg3 | Arg4 | Result | Status |
|
|
|--------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|------|-------|------|--------|-------------|
|
|
| 0x0101 | `nx_mem_alloc` | Maps _n_ 4KB pages to address _addr_. You can provide a bitmap of flags with the _flags_ argument. Which flags can be used, is described below. | addr | n | flags | | status | Implemented |
|
|
| 0x0102 | `nx_mem_free` | Unmaps _n_ 4KB pages at address _addr_. | addr | n | | | status | Implemented |
|
|
| 0x0103 | `nx_mem_label` | Gives a memory region a file descriptor, called a label, which can then be used for example for executing executable data in that memory region in a new process | addr | len | *fd | | status | N/A |
|
|
| 0x0104 | `nx_mem_unlabel` | Takes the file descriptor away from a memory region. | fd | | | | status | N/A |
|
|
|
|
## Processes
|
|
| ID | Name | Description | Arg1 | Arg2 | Arg3 | Arg4 | Result | Status |
|
|
|--------|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|--------|----------|------|------|--------|--------|
|
|
| 0x0201 | `nx_proc_create` | Creates a new process with the configuration _conf_ (which format is described below) and writes its process id to _pid_. | *conf | *pid | | | status | N/A |
|
|
| 0x0202 | `nx_proc_signal_send` | Send the signal _signal_ to _pid_. See below for a list of signals. | pid | signal | | | status | N/A |
|
|
| 0x0203 | `nx_proc_signal_set_handler` | Sets a handler for the signal _signal_ in the current process. Not all signals can have a handler. Look at the list for more information. | signal | *handler | | | status | N/A |
|
|
| 0x0204 | `nx_proc_thread_create` | Spawns a new thread for the current process. The starting point is defined by _addr_. The threads' ID is written into _tid_. | addr | *tid | | | status | N/A |
|
|
| 0x0205 | `nx_proc_thread_start` | Starts the current processes' thread with thread id _tid_. | tid | | | | status | N/A |
|
|
| 0x0206 | `nx_proc_thread_pause` | Pauses the current processes' thread with thread id _tid_. | tid | | | | status | N/A |
|
|
| 0x0207 | `nx_proc_thread_kill` | Kills the current processes' thread with thread id _tid_. | tid | | | | status | N/A |
|
|
|
|
## Drivers
|
|
| ID | Name | Description | Arg1 | Arg2 | Arg3 | Arg4 | Result | Status |
|
|
|--------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|------|-------|------|--------|--------|
|
|
| 0x0301 | `nx_drv_register` | Registers the executable at the _n_ bytes long _path_ as driver with the configuration _conf_. The format of the conf struct can be found below. | path | len | *conf | | status | N/A |
|
|
| 0x0302 | `nx_drv_create_command_buffer` | This has to be called from a driver. Registers _addr_ as command queue buffer with the length _len_, which has to be greater or equal 16384. If _addr_ is NULL or not aligned to 32 bytes or _len_ is less than 16384, the kernel will map a command queue buffer into the drivers address space, which is of length _len_ but at least 16384. The address to the registered buffer will be returned. | addr | len | | | addr | N/A |
|
|
| 0x0303 | `nx_drv_flush_command_buffer` | This has to be called from a driver. Flushes the command queue buffer at _addr_. | addr | | | | status | N/A |
|
|
|
|
## Kernel
|
|
These syscalls can only be called from the kernel process.
|
|
If another process calls them, they will just return without doing anything.
|
|
|
|
| ID | Name | Description | Arg1 | Arg2 | Arg3 | Arg4 | Result | Status |
|
|
|--------|-----------------------------|------------------------------------------------------------------------------------------------------|------|------|------|------|--------|-------------|
|
|
| 0xFF01 | `nx_kernel_scheduler_start` | Starts the kernel scheduler. The current execution point will be the kernel processes' first thread. | | | | | | Implemented |
|
|
| 0xFF02 | `nx_kernel_panic` | Causes a kernel panic. With _msg_ as error message. | msg | | | | | Implemented |
|
|
|
|
---
|
|
|
|
## Appendixes
|
|
|
|
### Types of file attributes
|
|
|
|
| ID | Name | Description | Data Type | Status |
|
|
|-----|---------------|--------------------------------------------|-----------|--------|
|
|
| 0 | `permissions` | Who has what permission to access the file | uint16_t | N/A |
|
|
| 1 | `size` | The files size in bytes | uint64_t | N/A |
|
|
|
|
---
|
|
|
|
### Memory mapping flags
|
|
|
|
| Bit | Name | Description |
|
|
|-----|-----------|-------------------------------------------|
|
|
| 0 | `write` | Enables write access to the mapped pages. |
|
|
| 1 | `no_exec` | Prevents execution of the mapped pages. |
|
|
|
|
---
|
|
|
|
### Process configuration
|
|
|
|
**header:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|--------------------------|-----------------|--------------------------------------------------------------------------------|
|
|
| 0x01 | privilege_level | Specifies the privilege level the process runs on. (described below) |
|
|
| 0x80 | name | The processes' name (ascii). |
|
|
| 0x08 | executable | A file descriptor to the executable the process will be loaded from. |
|
|
| 0x04 | num_inherit_fds | The amount of file descriptors that will be inherited to the process. |
|
|
| 0x0F * `num_inherit_fds` | inherit_fds | The file descriptors that will be inherited to the process. (described below) |
|
|
|
|
**header.privilege_level:**
|
|
|
|
| Value | Name | Description |
|
|
|-------|-----------|-------------------------------------------------------------------------|
|
|
| 0 | as_parent | The new process will spawn with the same privilege level as its parent. |
|
|
| 1 | default | The new process will spawn with default user permissions. |
|
|
|
|
**header.inherit_fds:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|---------------|-----------|--------------------------------------------------------------------------------|
|
|
| 0x08 | at_parent | The file descriptor, the parent process wants to inherit. |
|
|
| 0x08 | at_child | The file descriptor in the new child process. Same as `at_parent` if set to 0. |
|
|
|
|
|
|
### Process signals
|
|
- __SIGSTART__: starts the process
|
|
- __SIGPAUSE__: pauses the process
|
|
- __SIGKILL__: kills the process and destroys the processes data structures
|
|
- __SIGEXIT__: send by the kernel before stopping the process - handler implementation possible
|
|
- __SIGPFAULT__: sends when the process access memory it is not permitted to. Followed by SIGEXIT - handler implementation possible
|
|
- __SIGMATHFAULT__: sends when the process does stuff like dividing by zero. Followed by SIGEXIT - handler implementation possible
|
|
|
|
---
|
|
|
|
### Driver configuration
|
|
|
|
**header:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|---------------|--------------------|------------------------------------------------------------------------------|
|
|
| 0x01 | transport_protocol | Specifies the protocol over which the driver communicates. (described below) |
|
|
| 0x02 | length | Specifies the length of the `specific_config` section. |
|
|
| `length` | specific_config | Configuration specific to the transport protocol. (described below) |
|
|
|
|
|
|
**header.transport_protocol:**
|
|
|
|
| Value | Name | Description |
|
|
|-------|--------|------------------------------------------------------------------------------------------|
|
|
| 0 | PCI(e) | The driver connects to devices on the _Peripheral Component Interconnect (express)_ Bus. |
|
|
| 1 | USB | The driver connects to devices on the _Universal Serial Bus_. |
|
|
| 2 | FS | The driver provides filesystem functionalities. |
|
|
|
|
|
|
**header.specific_config.pci:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|-------------------------|----------------|-----------------------------------------------------------------------------|
|
|
| 0x01 | enable_progif | If set to zero, the progif entry will be ignored. |
|
|
| 0x01 | class | The PCI class code, the driver supports. |
|
|
| 0x01 | subclass | The PCI subclass code, the driver supports. |
|
|
| 0x01 | progif | The PCI ProgIF code, the driver supports. |
|
|
| 0x02 | num_device_ids | The amount of device ids the driver can handle. |
|
|
| 0x04 * `num_device_ids` | device_ids | An array containing all device ids the driver can handle. (described below) |
|
|
|
|
|
|
**header.specific_config.pci.device_id:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|---------------|-----------|----------------------------|
|
|
| 0x02 | vendor_id | The devices PCI vendor ID. |
|
|
| 0x02 | device_id | The devices PCI device ID. |
|
|
|
|
|
|
**header.specific_config.usb:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|---------------|-------------|-----------------------------------------|
|
|
| 0x01 | min_version | The minimum required major USB version. |
|
|
|
|
**header.specific_config.fs:**
|
|
|
|
| Length(bytes) | Name | Description |
|
|
|---------------|----------|-------------------------------------------------------------------------|
|
|
| 0x0F | gpt_guid | The gpt GUID of the file system type that the driver handles. |
|
|
| 0x01 | mbr_type | The mbr partition type of the file system type that the driver handles. | |