From b1f45b90cd76ae2e86e9cf815bd610c3358e708a Mon Sep 17 00:00:00 2001 From: boreddevnl Date: Sun, 19 Apr 2026 23:58:01 +0200 Subject: [PATCH] doc: improve sdk_reference Added all the syscalls by number and what they do, i also added all the headers inside of libc --- docs/appdev/libc_reference.md | 184 ++++++++++++++++++++++++++++ docs/appdev/sdk_reference.md | 222 +++++----------------------------- docs/appdev/syscalls.md | 146 ++++++++++++++++++++++ 3 files changed, 360 insertions(+), 192 deletions(-) create mode 100644 docs/appdev/libc_reference.md create mode 100644 docs/appdev/syscalls.md diff --git a/docs/appdev/libc_reference.md b/docs/appdev/libc_reference.md new file mode 100644 index 0000000..1f715e7 --- /dev/null +++ b/docs/appdev/libc_reference.md @@ -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. diff --git a/docs/appdev/sdk_reference.md b/docs/appdev/sdk_reference.md index 2fed154..92fd65a 100644 --- a/docs/appdev/sdk_reference.md +++ b/docs/appdev/sdk_reference.md @@ -1,214 +1,52 @@

Userland SDK Reference

-

Comprehensive manual for custom libc and system calls in BoredOS.

+

Overview and entry point for BoredOS userland development.

--- -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 +#include +#include +#include +#include ``` -### 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 +#include ``` -### `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; -``` diff --git a/docs/appdev/syscalls.md b/docs/appdev/syscalls.md new file mode 100644 index 0000000..9b7e924 --- /dev/null +++ b/docs/appdev/syscalls.md @@ -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.