mirror of
https://github.com/BoredDevNL/BoredOS.git
synced 2026-05-15 10:48:38 +00:00
doc: improve sdk_reference
Added all the syscalls by number and what they do, i also added all the headers inside of libc
This commit is contained in:
boreddevnl
parent
4280c3a802
commit
b1f45b90cd
3 changed files with 360 additions and 192 deletions
184
docs/appdev/libc_reference.md
Normal file
184
docs/appdev/libc_reference.md
Normal file
|
|
@ -0,0 +1,184 @@
|
|||
# libc Reference
|
||||
|
||||
This page documents the current BoredOS userland libc surface from `src/userland/libc/`.
|
||||
|
||||
BoredOS libc is a compact implementation focused on the APIs used by in-tree apps. It is not a full glibc replacement.
|
||||
|
||||
## Header Overview
|
||||
|
||||
| Header | Focus |
|
||||
|---|---|
|
||||
| `stdlib.h` | allocation, conversion, process helpers |
|
||||
| `string.h` | memory/string primitives |
|
||||
| `stdio.h` | `FILE*` and formatted I/O |
|
||||
| `unistd.h` | POSIX-like fd/process calls |
|
||||
| `fcntl.h` | open/fcntl flags, `dup`, `pipe` |
|
||||
| `input.h` | keyboard keycode constants |
|
||||
| `signal.h` | signal handlers and masks |
|
||||
| `sys/stat.h` | `stat`/`fstat` and file mode bits |
|
||||
| `sys/types.h` | core typedefs (`pid_t`, `ssize_t`, ...) |
|
||||
| `sys/wait.h` | `waitpid` and wait macros |
|
||||
| `errno.h` | errno values |
|
||||
| `time.h` | time/date utilities |
|
||||
| `math.h` | floating-point math helpers |
|
||||
| `libui.h` | GUI/window drawing API |
|
||||
|
||||
## stdlib.h
|
||||
|
||||
Implemented core functions:
|
||||
- Memory: `malloc`, `free`, `calloc`, `realloc`
|
||||
- Memory aliases: `memset`, `memcpy`
|
||||
- Conversions: `atoi`, `itoa`, `strtod`, `abs`
|
||||
- Output: `puts`, `printf`
|
||||
- Process/environment: `exit`, `_exit`, `sleep`, `chdir`, `getcwd`, `access`, `system`, `getenv`, `abort`
|
||||
|
||||
Notes:
|
||||
- `sleep` is millisecond-based and maps to kernel sleep command.
|
||||
- `system` is a stub-style helper in this libc, not a full shell launcher equivalent.
|
||||
|
||||
## string.h
|
||||
|
||||
Implemented C string/memory set includes:
|
||||
- Memory: `memmove`, `memcmp`, `memcpy`, `memset`, `memchr`
|
||||
- Search: `strchr`, `strrchr`, `strpbrk`, `strstr`
|
||||
- Span: `strspn`, `strcspn`
|
||||
- Compare: `strcmp`, `strncmp`, `strcasecmp`, `strncasecmp`, `strcoll`
|
||||
- Build/copy: `strlen`, `strcpy`, `strcat`, `strdup`
|
||||
- Errors: `strerror`
|
||||
|
||||
## stdio.h
|
||||
|
||||
Provided API includes:
|
||||
- Stream open/close: `fopen`, `freopen`, `fclose`
|
||||
- Read/write: `fread`, `fwrite`, `fgets`, `fputs`, `getc`, `fputc`, `putchar`
|
||||
- Positioning: `fseek`, `ftell`, `filelength`
|
||||
- Formatting: `fprintf`, `vfprintf`, `snprintf`, `vsnprintf`, `sprintf`, `sscanf`
|
||||
- Stream state: `feof`, `ferror`, `clearerr`, `fflush`, `ungetc`
|
||||
- Temp/filesystem helpers: `remove`, `rename`, `tmpfile`, `tmpnam`
|
||||
|
||||
## unistd.h
|
||||
|
||||
Provided POSIX-like interfaces:
|
||||
- FD I/O: `read`, `write`, `close`, `lseek`, `isatty`
|
||||
- Filesystem: `unlink`
|
||||
- Exec family: `execv`, `execve`, `execvp`, `execl`, `execlp`, `execle`
|
||||
- Process wait: `waitpid`
|
||||
|
||||
Also defines:
|
||||
- `SEEK_SET`, `SEEK_CUR`, `SEEK_END`
|
||||
- `F_OK`, `X_OK`, `W_OK`, `R_OK`
|
||||
|
||||
## fcntl.h
|
||||
|
||||
Flags and fd control:
|
||||
- Open flags: `O_RDONLY`, `O_WRONLY`, `O_RDWR`, `O_CREAT`, `O_EXCL`, `O_TRUNC`, `O_APPEND`, `O_NONBLOCK`, `O_ACCMODE`
|
||||
- fcntl ops: `F_GETFL`, `F_SETFL`
|
||||
- FD flag: `FD_CLOEXEC` (declared)
|
||||
|
||||
Functions:
|
||||
- `open`
|
||||
- `fcntl`
|
||||
- `dup`
|
||||
- `dup2`
|
||||
- `pipe`
|
||||
|
||||
## input.h
|
||||
|
||||
Defines keyboard/control keycode constants used by apps that process
|
||||
|
||||
Current constants include:
|
||||
- Arrow keys: `KEY_UP`, `KEY_DOWN`, `KEY_LEFT`, `KEY_RIGHT`
|
||||
- Controls: `KEY_ENTER`, `KEY_BACKSPACE`, `KEY_ESCAPE`, `KEY_SPACE`, `KEY_ALT`, `KEY_CTRL_L`, `KEY_TAB`
|
||||
|
||||
## signal.h
|
||||
|
||||
Current signal surface:
|
||||
- Basic handler API: `signal`, `raise`, `kill`
|
||||
- POSIX-style API: `sigaction`, `sigprocmask`, `sigpending`
|
||||
- Types: `sighandler_t`, `sigset_t`, `struct sigaction`
|
||||
- Constants: `SIGINT`, `SIGTERM`, `SIGKILL`, `SIG_DFL`, `SIG_IGN`, `SIG_ERR`
|
||||
- Mask ops: `SIG_BLOCK`, `SIG_UNBLOCK`, `SIG_SETMASK`
|
||||
- Action flags: `SA_RESTART`, `SA_NODEFER`, `SA_RESETHAND`
|
||||
|
||||
## ctype.h
|
||||
|
||||
Character classification and case conversion:
|
||||
- `isdigit`, `isalpha`, `isalnum`, `isspace`
|
||||
- `isupper`, `islower`, `isxdigit`
|
||||
- `iscntrl`, `ispunct`, `isprint`, `isgraph`
|
||||
- `tolower`, `toupper`
|
||||
|
||||
## locale.h
|
||||
|
||||
Locale stubs and conventions:
|
||||
- `struct lconv`
|
||||
- `setlocale`
|
||||
- `localeconv`
|
||||
- `LC_ALL`
|
||||
|
||||
## limits.h
|
||||
|
||||
Integer and floating-point limit macros:
|
||||
- `CHAR_BIT`, `INT_MIN`, `INT_MAX`, `UINT_MAX`
|
||||
- `LONG_MIN`, `LONG_MAX`, `ULONG_MAX`
|
||||
- `LLONG_MIN`, `LLONG_MAX`, `ULLONG_MAX`
|
||||
- `DBL_MAX`
|
||||
|
||||
## setjmp.h
|
||||
|
||||
Non-local jump support:
|
||||
- `jmp_buf`
|
||||
- `setjmp`
|
||||
- `longjmp`
|
||||
|
||||
## time.h
|
||||
|
||||
Time/date APIs and types:
|
||||
- Types: `time_t`, `clock_t`, `struct tm`
|
||||
- Constants: `CLOCKS_PER_SEC`
|
||||
- Functions: `time`, `clock`, `localtime`, `gmtime`, `strftime`, `mktime`
|
||||
|
||||
## libui.h
|
||||
|
||||
Windowing and drawing API used by GUI apps:
|
||||
- Window/event: `ui_window_create`, `ui_get_event`, `ui_mark_dirty`, `ui_window_set_title`, `ui_window_set_resizable`
|
||||
- Drawing: `ui_draw_rect`, `ui_draw_rounded_rect_filled`, `ui_draw_string`, `ui_draw_string_bitmap`, `ui_draw_image`
|
||||
- Text metrics/scaled text: `ui_get_string_width`, `ui_get_font_height`, `ui_draw_string_scaled`, `ui_draw_string_scaled_sloped`, `ui_get_string_width_scaled`, `ui_get_font_height_scaled`
|
||||
- System UI helpers: `ui_get_screen_size`, `ui_set_font`
|
||||
|
||||
## sys/stat.h and sys/types.h
|
||||
|
||||
`sys/stat.h` provides:
|
||||
- `struct stat`
|
||||
- `stat`, `fstat`, `mkdir`
|
||||
- mode/type macros (`S_IFREG`, `S_IFDIR`, `S_ISREG`, `S_ISDIR`, permission bits)
|
||||
|
||||
Note:
|
||||
- `access` is declared in `stdlib.h` in this libc.
|
||||
|
||||
`sys/types.h` provides:
|
||||
- `ssize_t`, `off_t`, `mode_t`, `pid_t`, `uid_t`, `gid_t`
|
||||
|
||||
## sys/wait.h
|
||||
|
||||
- `waitpid`
|
||||
- `WNOHANG`
|
||||
- status macros: `WEXITSTATUS`, `WIFEXITED`, `WTERMSIG`, `WIFSIGNALED`
|
||||
|
||||
## errno.h
|
||||
|
||||
Defined errno values include:
|
||||
- Generic/input: `EINVAL`, `EDOM`, `ERANGE`, `E2BIG`
|
||||
- File/path: `ENOENT`, `EEXIST`, `EISDIR`, `ENOTDIR`, `EBADF`
|
||||
- Runtime/state: `ENOMEM`, `EACCES`, `EIO`, `EAGAIN`, `EINTR`, `ECHILD`, `EBUSY`, `EPIPE`, `ESPIPE`, `ENOSYS`, `ENOTSUP`
|
||||
|
||||
## Relationship to raw syscalls
|
||||
|
||||
- libc high-level I/O and process APIs are backed by wrappers in `src/userland/libc/syscall.c`.
|
||||
- Full syscall command IDs and multiplexer details are documented in `docs/appdev/syscalls.md`.
|
||||
|
||||
## Practical Guidance
|
||||
|
||||
- Prefer libc APIs (`open`, `read`, `write`, `waitpid`, `sigaction`) for portability inside BoredOS userland.
|
||||
- Use raw wrapper calls from `syscall.h` only for capabilities that do not yet have higher-level libc wrappers.
|
||||
- Avoid numeric `sys_system(...)` command literals in app code; use `SYSTEM_CMD_*` macros.
|
||||
|
|
@ -1,214 +1,52 @@
|
|||
<div align="center">
|
||||
<h1>Userland SDK Reference</h1>
|
||||
<p><em>Comprehensive manual for custom libc and system calls in BoredOS.</em></p>
|
||||
<p><em>Overview and entry point for BoredOS userland development.</em></p>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
BoredOS provides a custom `libc` implementation necessary for writing userland applications (`.elf` binaries). By avoiding a full-blown standard library like `glibc`, the OS ensures a minimal executable footprint tailored strictly to the existing kernel features.
|
||||
BoredOS provides a compact userland SDK for building `.elf` applications.
|
||||
This page is the high-level map; detailed API references now live in dedicated pages.
|
||||
|
||||
All headers are located in `src/userland/libc/` (standard functions) and `src/wm/` (UI and widgets).
|
||||
- `stdlib.h`: Memory, strings, and basic I/O.
|
||||
- `math.h`: Freestanding floating-point math library.
|
||||
- `libui.h`: Core window and drawing API.
|
||||
- `libwidget.h`: High-level UI components.
|
||||
## SDK Structure
|
||||
|
||||
## Standard Library (`stdlib.h` & `string.h`)
|
||||
Primary headers are in `src/userland/libc/` and UI helpers are in `src/wm/`.
|
||||
|
||||
The standard library wrappers provide memory management, string manipulation, and basic IO formatting without needing direct syscalls.
|
||||
- `stdlib.h`, `string.h`, `stdio.h`, `unistd.h`: core libc surface
|
||||
- `syscall.h`: raw syscall wrappers and command constants
|
||||
- `libui.h`: window creation, drawing, and event polling
|
||||
- `libwidget.h`: higher-level reusable widgets
|
||||
- `math.h`: freestanding math helpers
|
||||
|
||||
### Memory Allocation
|
||||
* `void* malloc(size_t size);` - Allocate a block of memory on the heap.
|
||||
* `void free(void* ptr);` - Free a previously allocated memory block.
|
||||
* `void* calloc(size_t nmemb, size_t size);` - Allocate and zero-out a block of memory for an array.
|
||||
* `void* realloc(void* ptr, size_t size);` - Resize an existing memory block.
|
||||
## Detailed References
|
||||
|
||||
### Memory Manipulation (`string.h`)
|
||||
* `void* memset(void *s, int c, size_t n);` - Fill a block of memory with a specific byte.
|
||||
* `void* memcpy(void *dest, const void *src, size_t n);` - Copy memory from source to destination.
|
||||
* `void* memmove(void *dest, const void *src, size_t n);` - Safely copy overlapping memory blocks.
|
||||
* `int memcmp(const void *s1, const void *s2, size_t n);` - Compare two memory blocks.
|
||||
- [`libc Reference`](libc_reference.md): current libc headers and implemented APIs
|
||||
- [`Syscalls`](syscalls.md): syscall numbers, FS/SYSTEM command IDs, and wrappers
|
||||
- [`UI API`](ui_api.md): drawing and event APIs
|
||||
- [`Widget API`](widget_api.md): common widgets and interaction helpers
|
||||
|
||||
### String Utilities
|
||||
* `size_t strlen(const char *s);` - Get the length of a string.
|
||||
* `int strcmp(const char *s1, const char *s2);` - Compare two strings lexicographically.
|
||||
* `char* strcpy(char *dest, const char *src);` - Copy a string to a destination buffer.
|
||||
* `char* strcat(char *dest, const char *src);` - Concatenate two strings.
|
||||
|
||||
### Conversion and Formatting
|
||||
* `int atoi(const char *nptr);` - String to integer conversion.
|
||||
* `void itoa(int n, char *buf);` - Integer to string conversion.
|
||||
|
||||
### Input / Output
|
||||
* `void puts(const char *s);` - Print a string followed by a newline to the standard output.
|
||||
* `void printf(const char *fmt, ...);` - Formatted print to standard output (supports `%d`, `%s`, `%x`, etc.).
|
||||
|
||||
### Process Control
|
||||
* `void exit(int status);` - Terminate the current process.
|
||||
* `void sleep(int ms);` - Pause execution for a specified number of milliseconds.
|
||||
|
||||
---
|
||||
|
||||
## Math Library (`math.h`)
|
||||
|
||||
BoredOS ships a freestanding floating-point math library in `libc/math.h`. It uses pure arithmetic — Taylor series, Newton-Raphson, and range-reduction — with no dependency on a host `libm` or hardware math intrinsics. It is automatically linked into every userland ELF.
|
||||
## Typical Include Set
|
||||
|
||||
```c
|
||||
#include "math.h"
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
#include <stdio.h>
|
||||
#include <unistd.h>
|
||||
#include <syscall.h>
|
||||
```
|
||||
|
||||
### Constants
|
||||
For GUI apps:
|
||||
|
||||
| Constant | Value | Description |
|
||||
|---|---|---|
|
||||
| `M_PI` | 3.14159… | π |
|
||||
| `M_E` | 2.71828… | Euler's number |
|
||||
| `M_LN2` | 0.69315… | Natural log of 2 |
|
||||
| `M_SQRT2` | 1.41421… | √2 |
|
||||
| `HUGE_VAL` | ~+∞ | Overflow sentinel |
|
||||
|
||||
### Functions
|
||||
|
||||
#### Absolute value & remainder
|
||||
* `double fabs(double x);` — Absolute value.
|
||||
* `double fmod(double x, double y);` — Floating-point remainder. Returns `0` when `y == 0`.
|
||||
|
||||
#### Rounding
|
||||
* `double floor(double x);` — Largest integer ≤ x.
|
||||
* `double ceil(double x);` — Smallest integer ≥ x.
|
||||
|
||||
#### Trigonometry *(arguments in radians)*
|
||||
* `double sin(double x);` — Sine. Range-reduced to `[-π, π]` then computed via 8-term Taylor series.
|
||||
* `double cos(double x);` — Cosine. Computed via `sin(x + π/2)`.
|
||||
* `double tan(double x);` — Tangent. Returns sentinel `1e15` near poles.
|
||||
|
||||
#### Exponential & logarithm
|
||||
* `double sqrt(double x);` — Square root via Newton-Raphson (25 iterations). Returns `0` for `x ≤ 0`.
|
||||
* `double log(double x);` — Natural logarithm (ln). Returns `-1e30` for `x ≤ 0`.
|
||||
* `double log2(double x);` — Base-2 logarithm.
|
||||
* `double log10(double x);` — Base-10 logarithm.
|
||||
* `double exp(double x);` — e^x. Saturates to `1e300` for `x > 700`, `0` for `x < -700`.
|
||||
* `double pow(double base, double exponent);` — General power. Integer exponents use fast binary exponentiation; fractional exponents use `exp(e * log(b))`.
|
||||
|
||||
#### Hyperbolic
|
||||
* `double sinh(double x);` — Hyperbolic sine.
|
||||
* `double cosh(double x);` — Hyperbolic cosine.
|
||||
* `double tanh(double x);` — Hyperbolic tangent.
|
||||
|
||||
#### Utility
|
||||
* `double hypot(double x, double y);` — `sqrt(x² + y²)` without intermediate overflow.
|
||||
* `double fmin(double a, double b);` — Minimum of two values.
|
||||
* `double fmax(double a, double b);` — Maximum of two values.
|
||||
* `double fclamp(double x, double lo, double hi);` — Clamps `x` into `[lo, hi]`.
|
||||
|
||||
> [!NOTE]
|
||||
> The implementation file is named `libc/libmath.c` (not `libc/math.c`) to avoid a name collision with the `math` CLI calculator app in userland. The public header is still included as `#include "math.h"`.
|
||||
|
||||
For advanced operations, `syscall.h` provides direct wrappers into the kernel.
|
||||
|
||||
### Process & System Info
|
||||
* `void sys_exit(int status);` - Raw exit syscall.
|
||||
* `int sys_write(int fd, const char *buf, int len);` - Write to a file descriptor (usually fd 1 for stdout).
|
||||
* `void* sys_sbrk(int incr);` - Expand or shrink the process data segment (used internally by `malloc`).
|
||||
* `void sys_kill(int pid);` - Send a kill signal to a process.
|
||||
* `void sys_yield(void);` - Yield the remainder of the process's timeslice to the scheduler.
|
||||
* `int sys_system(int cmd, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4);` - Execute a privileged system command (e.g., reboot, shutdown, beep).
|
||||
* `int sys_get_os_info(os_info_t *info);` - Populate an `os_info_t` struct with version and environment details.
|
||||
* `uint64_t sys_get_shell_config(const char *key);` - Retrieve internal shell configuration values.
|
||||
* `void sys_set_text_color(uint32_t color);` - Set the raw CLI text output color.
|
||||
|
||||
### File System API (VFS)
|
||||
Interacting with files and directories using the Virtual File System.
|
||||
* `int sys_open(const char *path, const char *mode);` - Open a file, returning a file descriptor.
|
||||
* `int sys_read(int fd, void *buf, uint32_t len);` - Read from an open file.
|
||||
* `int sys_write_fs(int fd, const void *buf, uint32_t len);` - Write to an open file.
|
||||
* `void sys_close(int fd);` - Close an open file descriptor.
|
||||
* `int sys_seek(int fd, int offset, int whence);` - Reposition the file offset.
|
||||
* `uint32_t sys_tell(int fd);` - Get the current file offset.
|
||||
* `uint32_t sys_size(int fd);` - Get the total file size.
|
||||
* `int sys_delete(const char *path);` - Delete a file.
|
||||
* `int sys_mkdir(const char *path);` - Create a new directory.
|
||||
* `int sys_exists(const char *path);` - Check if a path exists on the filesystem.
|
||||
* `int sys_getcwd(char *buf, int size);` - Get the current working directory string.
|
||||
* `int sys_chdir(const char *path);` - Change the current working directory.
|
||||
* `int sys_list(const char *path, FAT32_FileInfo *entries, int max_entries);` - List directory contents into an array of `FAT32_FileInfo` structs.
|
||||
* `int sys_get_file_info(const char *path, FAT32_FileInfo *info);` - Retrieve metadata for a specific file.
|
||||
|
||||
### Networking Stack API
|
||||
BoredOS includes lwIP for hardware TCP/UDP networking.
|
||||
|
||||
#### Configuration and Status
|
||||
* `int sys_network_init(void);` - Initialize the network stack.
|
||||
* `int sys_network_is_initialized(void);` - Check stack status.
|
||||
* `int sys_network_dhcp_acquire(void);` - Request an IP configuration from a DHCP server.
|
||||
* `int sys_network_has_ip(void);` - Check if the system has a valid IP address.
|
||||
* `int sys_network_get_mac(net_mac_address_t *mac);` - Get the physical MAC address of the NIC.
|
||||
* `int sys_network_get_nic_name(char *name_out);` - Get the name of the active network interface card.
|
||||
* `int sys_network_get_ip(net_ipv4_address_t *ip);` - Get current local IPv4 address.
|
||||
* `int sys_network_set_ip(const net_ipv4_address_t *ip);` - Manually assign a static IP.
|
||||
* `int sys_network_get_gateway(net_ipv4_address_t *ip);` - Get the default gateway IP.
|
||||
* `int sys_network_get_dns(net_ipv4_address_t *ip);` - Get the primary DNS server IP.
|
||||
* `int sys_set_dns_server(const net_ipv4_address_t *ip);` - Set the primary DNS server.
|
||||
* `int sys_get_dns_server(net_ipv4_address_t *ip);` - Retrieve configured DNS server.
|
||||
* `int sys_network_get_stat(int stat_type);` - Get network statistics (packets in/out, drops, etc.).
|
||||
* `void sys_network_force_unlock(void);` - Force release of network stack locks (use with caution).
|
||||
|
||||
#### Communication
|
||||
* `int sys_icmp_ping(const net_ipv4_address_t *dest_ip);` - Send an ICMP echo request.
|
||||
* `int sys_udp_send(const net_ipv4_address_t *dest_ip, uint16_t dest_port, uint16_t src_port, const void *data, size_t data_len);` - Send a raw UDP datagram.
|
||||
* `int sys_dns_lookup(const char *name, net_ipv4_address_t *out_ip);` - Resolve a hostname to an IPv4 address.
|
||||
* `int sys_tcp_connect(const net_ipv4_address_t *ip, uint16_t port);` - Establish a TCP connection to a remote host.
|
||||
* `int sys_tcp_send(const void *data, size_t len);` - Send data over an active TCP socket.
|
||||
* `int sys_tcp_recv(void *buf, size_t max_len);` - Receive data from a TCP socket (blocking).
|
||||
* `int sys_tcp_recv_nb(void *buf, size_t max_len);` - Receive data from a TCP socket (non-blocking).
|
||||
* `int sys_tcp_close(void);` - Close the active TCP socket.
|
||||
|
||||
---
|
||||
|
||||
## Core Data Structures
|
||||
|
||||
### `os_info_t`
|
||||
Contains detailed build and version information about the OS.
|
||||
```c
|
||||
typedef struct {
|
||||
char os_name[64];
|
||||
char os_version[64];
|
||||
char os_codename[64];
|
||||
char kernel_name[64];
|
||||
char kernel_version[64];
|
||||
char build_date[64];
|
||||
char build_time[64];
|
||||
char build_arch[64];
|
||||
} os_info_t;
|
||||
#include <libui.h>
|
||||
#include <libwidget.h>
|
||||
```
|
||||
|
||||
### `FAT32_FileInfo`
|
||||
Represents a filesystem entry.
|
||||
```c
|
||||
typedef struct {
|
||||
char name[256];
|
||||
uint32_t size;
|
||||
uint8_t is_directory;
|
||||
uint32_t start_cluster;
|
||||
uint16_t write_date;
|
||||
uint16_t write_time;
|
||||
} FAT32_FileInfo;
|
||||
```
|
||||
## Build and Packaging
|
||||
|
||||
- Add app source under `src/userland/` (CLI, GUI, or games subfolder).
|
||||
- Ensure it is included in the userland build rules/targets.
|
||||
- Build from repo root with `make`.
|
||||
- Built binaries are copied into initrd under `/bin` by the top-level `Makefile`.
|
||||
|
||||
### `ProcessInfo`
|
||||
Provides status information for an active process.
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t pid;
|
||||
char name[64];
|
||||
uint64_t ticks;
|
||||
size_t used_memory;
|
||||
} ProcessInfo;
|
||||
```
|
||||
|
||||
### IP / MAC Addresses
|
||||
Wrappers for raw byte arrays.
|
||||
```c
|
||||
typedef struct { uint8_t bytes[6]; } net_mac_address_t;
|
||||
typedef struct { uint8_t bytes[4]; } net_ipv4_address_t;
|
||||
```
|
||||
|
|
|
|||
146
docs/appdev/syscalls.md
Normal file
146
docs/appdev/syscalls.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# Syscall Reference
|
||||
|
||||
This page documents the current syscall surface in BoredOS as implemented in:
|
||||
- `src/sys/syscall.h` (kernel command IDs)
|
||||
- `src/userland/libc/syscall.h` (userland wrappers)
|
||||
|
||||
Use libc wrappers when possible instead of calling raw syscall numbers directly.
|
||||
|
||||
## Top-Level Syscall Numbers
|
||||
|
||||
| Number | Name | Purpose |
|
||||
|---|---|---|
|
||||
| 0 | `SYS_EXIT` (userland header) | Terminate current process |
|
||||
| 1 | `SYS_WRITE` | Write to stdout/tty path |
|
||||
| 3 | `SYS_GUI` | Window manager and drawing commands |
|
||||
| 4 | `SYS_FS` | Filesystem and fd commands |
|
||||
| 5 | `SYS_SYSTEM` | System-wide command multiplexer |
|
||||
| 9 | `SYS_SBRK` (userland header) | Heap break management |
|
||||
| 10 | `SYS_KILL` (userland header) | Kill process by PID |
|
||||
| 60 | `SYS_EXIT` (kernel header) | Internal kernel syscall number map |
|
||||
|
||||
Notes:
|
||||
- Some numbers differ between kernel and userland headers for historical reasons. For app code, rely on wrapper functions in `src/userland/libc/syscall.c`.
|
||||
- `SYS_GUI`, `SYS_FS`, and `SYS_SYSTEM` are command multiplexers.
|
||||
|
||||
## FS Command IDs (`SYS_FS`)
|
||||
|
||||
| ID | Macro | Meaning |
|
||||
|---|---|---|
|
||||
| 1 | `FS_CMD_OPEN` | Open file |
|
||||
| 2 | `FS_CMD_READ` | Read from fd |
|
||||
| 3 | `FS_CMD_WRITE` | Write to fd |
|
||||
| 4 | `FS_CMD_CLOSE` | Close fd |
|
||||
| 5 | `FS_CMD_SEEK` | Seek in file |
|
||||
| 6 | `FS_CMD_TELL` | Current offset |
|
||||
| 7 | `FS_CMD_LIST` | Directory listing |
|
||||
| 8 | `FS_CMD_DELETE` | Delete file |
|
||||
| 9 | `FS_CMD_SIZE` | File size |
|
||||
| 10 | `FS_CMD_MKDIR` | Create directory |
|
||||
| 11 | `FS_CMD_EXISTS` | Path exists check |
|
||||
| 12 | `FS_CMD_GETCWD` | Get cwd |
|
||||
| 13 | `FS_CMD_CHDIR` | Change cwd |
|
||||
| 14 | `FS_CMD_GET_INFO` | File metadata |
|
||||
| 15 | `FS_CMD_DUP` | `dup` fd |
|
||||
| 16 | `FS_CMD_DUP2` | `dup2` fd |
|
||||
| 17 | `FS_CMD_PIPE` | Create pipe |
|
||||
| 18 | `FS_CMD_FCNTL` | `fcntl` flags ops |
|
||||
|
||||
## SYSTEM Command IDs (`SYS_SYSTEM`)
|
||||
|
||||
### Desktop and display
|
||||
|
||||
| ID | Macro | Meaning |
|
||||
|---|---|---|
|
||||
| 1 | `SYSTEM_CMD_SET_BG_COLOR` | Set desktop background color |
|
||||
| 2 | `SYSTEM_CMD_SET_BG_PATTERN` | Set desktop background pattern |
|
||||
| 3 | `SYSTEM_CMD_SET_WALLPAPER` | Legacy wallpaper command slot |
|
||||
| 4 | `SYSTEM_CMD_SET_DESKTOP_PROP` | Set desktop behavior property |
|
||||
| 5 | `SYSTEM_CMD_SET_MOUSE_SPEED` | Set mouse speed |
|
||||
| 7 | `SYSTEM_CMD_GET_DESKTOP_PROP` | Get desktop property |
|
||||
| 8 | `SYSTEM_CMD_GET_MOUSE_SPEED` | Get mouse speed |
|
||||
| 9 | `SYSTEM_CMD_GET_WALLPAPER_THUMB` | Legacy wallpaper thumb slot |
|
||||
| 10 | `SYSTEM_CMD_CLEAR_SCREEN` | Clear text console |
|
||||
| 29 | `SYSTEM_CMD_SET_TEXT_COLOR` | Set console text color |
|
||||
| 31 | `SYSTEM_CMD_SET_WALLPAPER_PATH` | Set wallpaper from path |
|
||||
| 40 | `SYSTEM_CMD_SET_FONT` | Set active font |
|
||||
| 47 | `SYSTEM_CMD_SET_RESOLUTION` | Set display mode |
|
||||
|
||||
### Time, power, and system state
|
||||
|
||||
| ID | Macro | Meaning |
|
||||
|---|---|---|
|
||||
| 11 | `SYSTEM_CMD_RTC_GET` | Read RTC datetime |
|
||||
| 12 | `SYSTEM_CMD_REBOOT` | Reboot machine |
|
||||
| 13 | `SYSTEM_CMD_SHUTDOWN` | Power off machine |
|
||||
| 14 | `SYSTEM_CMD_BEEP` | PC speaker beep |
|
||||
| 15 | `SYSTEM_CMD_GET_MEM_INFO` | Return total/used memory |
|
||||
| 16 | `SYSTEM_CMD_GET_TICKS` | Return scheduler/WM tick count |
|
||||
| 28 | `SYSTEM_CMD_GET_SHELL_CONFIG` | Read shell config value |
|
||||
| 32 | `SYSTEM_CMD_RTC_SET` | Set RTC datetime |
|
||||
| 41 | `SYSTEM_CMD_SET_RAW_MODE` | Terminal raw-mode control |
|
||||
| 43 | `SYSTEM_CMD_YIELD` | Yield scheduler timeslice |
|
||||
| 46 | `SYSTEM_CMD_SLEEP` | Sleep current process |
|
||||
|
||||
### Network
|
||||
|
||||
| ID | Macro | Meaning |
|
||||
|---|---|---|
|
||||
| 6 | `SYSTEM_CMD_NETWORK_INIT` | Init networking |
|
||||
| 17 | `SYSTEM_CMD_PCI_LIST` | PCI device list access |
|
||||
| 18 | `SYSTEM_CMD_NETWORK_DHCP` | DHCP acquire |
|
||||
| 19 | `SYSTEM_CMD_NETWORK_GET_MAC` | Read NIC MAC |
|
||||
| 20 | `SYSTEM_CMD_NETWORK_GET_IP` | Read IPv4 |
|
||||
| 21 | `SYSTEM_CMD_NETWORK_SET_IP` | Set static IPv4 |
|
||||
| 22 | `SYSTEM_CMD_UDP_SEND` | Send UDP packet |
|
||||
| 23 | `SYSTEM_CMD_NETWORK_GET_STATS` | Network stats |
|
||||
| 24 | `SYSTEM_CMD_NETWORK_GET_GATEWAY` | Read gateway |
|
||||
| 25 | `SYSTEM_CMD_NETWORK_GET_DNS` | Read DNS server |
|
||||
| 26 | `SYSTEM_CMD_ICMP_PING` | ICMP ping |
|
||||
| 27 | `SYSTEM_CMD_NETWORK_IS_INIT` | Network initialized flag |
|
||||
| 30 | `SYSTEM_CMD_NETWORK_HAS_IP` | Has IPv4 address flag |
|
||||
| 33 | `SYSTEM_CMD_TCP_CONNECT` | TCP connect |
|
||||
| 34 | `SYSTEM_CMD_TCP_SEND` | TCP send |
|
||||
| 35 | `SYSTEM_CMD_TCP_RECV` | TCP recv (blocking) |
|
||||
| 36 | `SYSTEM_CMD_TCP_CLOSE` | TCP close |
|
||||
| 37 | `SYSTEM_CMD_DNS_LOOKUP` | DNS lookup |
|
||||
| 38 | `SYSTEM_CMD_SET_DNS` | Set DNS server |
|
||||
| 39 | `SYSTEM_CMD_NET_UNLOCK` | Force net lock release |
|
||||
| 42 | `SYSTEM_CMD_TCP_RECV_NB` | TCP recv (non-blocking) |
|
||||
| 48 | `SYSTEM_CMD_NETWORK_GET_NIC_NAME` | NIC name |
|
||||
|
||||
### Process, tty, signals
|
||||
|
||||
| ID | Macro | Meaning |
|
||||
|---|---|---|
|
||||
| 50 | `SYSTEM_CMD_PARALLEL_RUN` | Dispatch parallel job |
|
||||
| 60 | `SYSTEM_CMD_TTY_CREATE` | Create tty |
|
||||
| 61 | `SYSTEM_CMD_TTY_READ_OUT` | Read tty output buffer |
|
||||
| 62 | `SYSTEM_CMD_TTY_WRITE_IN` | Write tty input buffer |
|
||||
| 63 | `SYSTEM_CMD_TTY_READ_IN` | Read input for current tty |
|
||||
| 64 | `SYSTEM_CMD_SPAWN` | Spawn process |
|
||||
| 65 | `SYSTEM_CMD_TTY_SET_FG` | Set tty foreground PID |
|
||||
| 66 | `SYSTEM_CMD_TTY_GET_FG` | Get tty foreground PID |
|
||||
| 67 | `SYSTEM_CMD_TTY_KILL_FG` | Kill tty foreground PID |
|
||||
| 68 | `SYSTEM_CMD_TTY_KILL_ALL` | Kill tty process group |
|
||||
| 69 | `SYSTEM_CMD_TTY_DESTROY` | Destroy tty |
|
||||
| 70 | `SYSTEM_CMD_EXEC` | Exec replace current process |
|
||||
| 71 | `SYSTEM_CMD_WAITPID` | Wait/reap child |
|
||||
| 72 | `SYSTEM_CMD_KILL_SIGNAL` | Send signal |
|
||||
| 73 | `SYSTEM_CMD_SIGACTION` | Set/get handler |
|
||||
| 74 | `SYSTEM_CMD_SIGPROCMASK` | Signal mask ops |
|
||||
| 75 | `SYSTEM_CMD_SIGPENDING` | Get pending signals |
|
||||
|
||||
## Common Wrapper API (`src/userland/libc/syscall.h`)
|
||||
|
||||
Typical wrappers used by apps:
|
||||
- Process/system: `sys_exit`, `sys_yield`, `sys_spawn`, `sys_exec`, `sys_waitpid`, `sys_kill_signal`
|
||||
- Filesystem: `sys_open`, `sys_read`, `sys_write_fs`, `sys_close`, `sys_seek`, `sys_tell`, `sys_size`, `sys_list`
|
||||
- Network: `sys_network_init`, `sys_network_dhcp_acquire`, `sys_udp_send`, `sys_tcp_connect`, `sys_tcp_recv_nb`, `sys_dns_lookup`
|
||||
- TTY: `sys_tty_create`, `sys_tty_read_out`, `sys_tty_write_in`, `sys_tty_set_fg`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Do not hardcode numeric command IDs in app code.
|
||||
- Prefer high-level libc calls (`open`, `read`, `waitpid`, `sigaction`) where available.
|
||||
- Use `syscall.h` macros when a raw `sys_system` call is still needed.
|
||||
Loading…
Reference in a new issue