chersbobers/boredos_mirror
1
0
Fork 0
mirror of https://github.com/BoredDevNL/BoredOS.git synced 2026-05-13 01:48:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: update syscall reference and add installation guides

Browse source
This commit is contained in:
boreddevnl 2026-05-08 21:06:07 +02:00
parent 6e1eb7768d
commit 274ee54814
6 changed files with 232 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
docs/appdev/syscalls.md
View file

@ -15,6 +15,7 @@ Use libc wrappers when possible instead of calling raw syscall numbers directly.
| 3 | `SYS_GUI` | Window manager and drawing commands |
| 4 | `SYS_FS` | Filesystem and fd commands |
| 5 | `SYS_SYSTEM` | System-wide command multiplexer |
| 8 | `SYS_DEBUG_SERIAL` | Debug serial output (kernel only) |
| 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 |
@ -46,6 +47,32 @@ Notes:
| 17 | `FS_CMD_PIPE` | Create pipe |
| 18 | `FS_CMD_FCNTL` | `fcntl` flags ops |
## GUI Command IDs (`SYS_GUI`)
| ID | Macro | Meaning |
|---|---|---|
| 1 | `GUI_CMD_WINDOW_CREATE` | Create a new window |
| 2 | `GUI_CMD_DRAW_RECT` | Draw a rectangle |
| 3 | `GUI_CMD_DRAW_STRING` | Draw a string (TTF) |
| 4 | `GUI_CMD_MARK_DIRTY` | Mark region dirty / dual-buffer commit |
| 5 | `GUI_CMD_GET_EVENT` | Retrieve next GUI event |
| 6 | `GUI_CMD_DRAW_ROUNDED_RECT_FILLED` | Draw filled rounded rectangle |
| 7 | `GUI_CMD_DRAW_IMAGE` | Draw raw image data |
| 8 | `GUI_CMD_GET_STRING_WIDTH` | Get TTF string width |
| 9 | `GUI_CMD_GET_FONT_HEIGHT` | Get TTF font height |
| 10 | `GUI_CMD_DRAW_STRING_BITMAP` | Draw legacy bitmap string |
| 11 | `GUI_CMD_DRAW_STRING_SCALED` | Draw scaled TTF string |
| 12 | `GUI_CMD_GET_STRING_WIDTH_SCALED` | Get scaled TTF string width |
| 13 | `GUI_CMD_GET_FONT_HEIGHT_SCALED` | Get scaled TTF font height |
| 14 | `GUI_CMD_WINDOW_SET_RESIZABLE` | Toggle window resizability |
| 15 | `GUI_CMD_WINDOW_SET_TITLE` | Update window title |
| 16 | `GUI_CMD_SET_FONT` | Load/set window-specific font |
| 18 | `GUI_CMD_DRAW_STRING_SCALED_SLOPED` | Draw sloped/scaled TTF string |
| 50 | `GUI_CMD_GET_SCREEN_SIZE` | Get display resolution |
| 51 | `GUI_CMD_GET_SCREENBUFFER` | Copy screen contents to buffer |
| 52 | `GUI_CMD_SHOW_NOTIFICATION` | Show desktop notification |
| 53 | `GUI_CMD_GET_DATETIME` | Get RTC datetime |
## SYSTEM Command IDs (`SYS_SYSTEM`)
### Desktop and display
@ -65,6 +92,8 @@ Notes:
| 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 |
| 49 | `SYSTEM_CMD_SET_KEYBOARD_LAYOUT` | Set active keyboard layout ID |
| 51 | `SYSTEM_CMD_GET_KEYBOARD_LAYOUT` | Get current keyboard layout ID |
### Time, power, and system state
@ -138,6 +167,21 @@ Notes:
| 76 | `SYSTEM_CMD_GET_ELF_METADATA` | Read full app metadata from an ELF |
| 77 | `SYSTEM_CMD_GET_ELF_PRIMARY_IMAGE` | Read primary icon path from an ELF |
### Disk Management
| ID | Macro | Meaning |
|---|---|---|
| 100 | `SYSTEM_CMD_DISK_GET_COUNT` | Get number of detected disks |
| 101 | `SYSTEM_CMD_DISK_GET_INFO` | Get metadata for a specific disk/partition |
| 102 | `SYSTEM_CMD_DISK_WRITE_GPT` | Write GPT partition table to disk |
| 103 | `SYSTEM_CMD_DISK_WRITE_MBR` | Write MBR partition table to disk |
| 104 | `SYSTEM_CMD_DISK_MKFS_FAT32` | Format a partition as FAT32 |
| 105 | `SYSTEM_CMD_DISK_MOUNT` | Mount a filesystem |
| 106 | `SYSTEM_CMD_DISK_UMOUNT` | Unmount a filesystem |
| 107 | `SYSTEM_CMD_DISK_RESCAN` | Rescan disk for partition changes |
| 108 | `SYSTEM_CMD_DISK_REPLACE_KERNEL` | Copy new kernel to ESP / boot partition |
| 109 | `SYSTEM_CMD_DISK_SYNC` | Flush disk caches for a mountpoint |
## Common Wrapper API (`src/userland/libc/syscall.h`)
Typical wrappers used by apps:

27
docs/installation/README.md Normal file
View file

@ -0,0 +1,27 @@
# BoredOS Installation
## Requirements
- Disk with at least **1 GB** (2,097,152 sectors)
- UEFI firmware
- A running BoredOS live environment (ISO)
## Quick Start (UEFI)
```
boredos_install --uefi /dev/sda
```
After installation, reboot and select the target disk from your firmware boot menu.
## Manual Steps
```
fdisk /dev/sda
mkfs_fat -F 32 -n EFI /dev/sda1
mkfs_fat -F 32 -n BOREDOS /dev/sda2
boredos_install --no-partition --no-format --uefi /dev/sda
```
See `install_guide.md` for a full walkthrough and `internals.md` for a deep dive into how the process works.

73
docs/installation/advanced.md Normal file
View file

@ -0,0 +1,73 @@
# Advanced Installation
## Skipping Steps
All major phases can be skipped independently:
```
boredos_install --no-partition --no-format --uefi /dev/sda
```
The destructive warning is only shown when `--no-partition` AND `--no-format` are both absent.
## `/mnt/boot` Operations
The installer mounts the ESP at `/mnt/boot` and unmounts it when finished.
## FAT32 Limitations
FAT32 does not support Unix file permissions, ownership, or timestamps. These attributes are **not** preserved during installation. This is expected and documented.
## Custom Device Names
Use `--esp-dev` and `--root-dev` to bypass auto-detection:
```
boredos_install --uefi --esp-dev sda1 --root-dev sda2 /dev/sda --no-partition --no-format
```
Provided device names are still validated via `sys_disk_get_info` before use.
### Step 1: Partitioning
Run `fdisk` interactively on your target device.
```bash
fdisk /dev/sda
```
Inside the interactive shell:
1. Type `n` to create a new partition (the ESP).
2. Press Enter for the default start offset (1mb).
3. Enter the size using suffixes like `b`, `mb`, or `gb` (e.g., `512mb` for a 512 MB ESP).
4. Type `n` again for the second partition (the Root).
5. Press Enter for the default start offset (aligned after the ESP).
6. Press Enter for the default size (rest of the disk).
7. Type `w` to write the partition table.
8. Type 'Q' to quit.
> [!NOTE]
> Interactive mode in `fdisk` currently creates standard partitions. When using `boredos_install` later, you may need to specify the ESP device manually with `--esp-dev sda1` if it isn't automatically detected as an EFI System Partition.
### Step 2: Formatting
Initialize the partitions with FAT32. Use the labels `EFI` and `BOREDOS` to match the expected system layout.
```bash
mkfs_fat -F 32 -n EFI /dev/sda1
mkfs_fat -F 32 -n BOREDOS /dev/sda2
```
### Step 3: Installation
The easiest way to perform the file copy and bootloader setup is to use the installer in "copy only" mode. This ensures that hidden flags (like the root detection file) are placed correctly.
```bash
boredos_install --no-partition --no-format --uefi --esp-dev sda1 /dev/sda
```
#### What this step does:
1. **Mounts** `/dev/sda2` to `/mnt` and `/dev/sda1` to `/mnt/boot`.
2. **Identifies** the root by creating an empty file at `/mnt/Library/.boredos_root`.
3. **Copies** the system structure: `/bin`, `/Library`, `/docs`, and `/root` are mirrored to `/mnt`.
4. **Deploys** the kernel and initrd: `boredos.elf` and `initrd.tar` are copied to the ESP (`/mnt/boot/`).
5. **Configures** Limine: Writes a `limine.conf` to the ESP and copies the EFI bootloader to `/mnt/boot/EFI/BOOT/BOOTX64.EFI`.
For a deep dive into why these steps are performed, see the [Installation Internals](internals.md) guide.

31
docs/installation/install_guide.md Normal file
View file

@ -0,0 +1,31 @@
# Install Guide
## UEFI Installation
1. Boot from the BoredOS ISO.
2. Run `boredos_install --uefi /dev/sda`.
3. Type `y` when prompted and press Enter.
4. After completion, reboot and select the disk.
## limine.conf Notes
**UEFI** uses `boot():/boredos.elf` — the `boot():` URL scheme refers to the EFI System Partition.
**Root selection** uses `root=/dev/<partition>` in `cmdline:` to choose the writable root partition (for example `root=/dev/sda2`).
**TOS acceptance** uses `--accept-tos` in `cmdline:` when you want to bypass the prompt.
**Live vs disk override** supports `--live` and `--disk` in `cmdline:`. Use `--live` for ISO/USB live boots and `--disk` for installed systems.
## Options
| Flag | Description |
|---|---|
| `--no-partition` | Skip fdisk (use existing partitions) |
| `--no-format` | Skip mkfs (use existing filesystem) |
| `--no-files` | Skip file copy |
| `--no-bootloader` | Skip limine.conf and EFI file copy |
| `--esp-size N` | ESP size in MB (default: 512) |
| `--esp-dev DEV` | Explicit ESP device name |
| `--root-dev DEV` | Explicit root device name |
| `-y` | Auto-accept the destructive warning |

57
docs/installation/internals.md Normal file
View file

@ -0,0 +1,57 @@
# Installation Internals: How, Why, and What
This document explains the technical details of the BoredOS installation process, the design decisions behind it, and the resulting system layout.
## How the installation works
The BoredOS installation follows a strict five-phase sequence:
1. **Partitioning (GPT/MBR)**: The disk is prepared with a partition table. For UEFI systems, we use GPT (GUID Partition Table) and create at least two partitions: an EFI System Partition (ESP) and a data partition.
2. **Formatting (FAT32)**: Both partitions are formatted with FAT32.
- The ESP is labeled `EFI`.
- The root partition is labeled `BOREDOS`.
3. **Mounting & Flagging**: The root partition is mounted to `/mnt`. A special marker file is created at `/Library/.boredos_root`. This file is used by the kernel during boot to differentiate between a persistent disk and a live ISO/RAM disk.
4. **System Mirroring**: The installer performs a recursive copy of the live system's essential including but not limited to:
- `/bin`: All userland binaries.
- `/Library`: System assets, fonts, icons, and configuration.
- `/docs`: Documentation and manuals.
- `/root`: The default user home directory.
5. **Bootloader Setup**:
- The ESP is mounted to `/mnt/boot`.
- The kernel (`boredos.elf`) and the initial RAM disk (`initrd.tar`) are copied to the root of the ESP.
- The Limine EFI binary is placed at `/EFI/BOOT/BOOTX64.EFI`.
- A `limine.conf` is generated with the correct `root=/dev/sdXX` parameter.
## Why it works this way
### FAT32 for Everything
BoredOS currently uses FAT32 as its primary filesystem for both the boot partition and the root partition.
- **Universal Support**: FAT32 is natively understood by UEFI firmware, making it the only choice for the ESP.
- **Simplicity**: By using FAT32 for the root partition as well, the kernel only needs one robust filesystem driver to handle both boot-time loading and runtime persistent storage.
- **Interoperability**: You can easily mount BoredOS partitions on other operating systems (Windows, Linux, macOS) to transfer files.
### The ESP/Root Split
Even though both use FAT32, we split the disk into two partitions to follow the UEFI specification. The ESP is meant to be small and strictly for bootloader files, while the root partition contains the entire userland. This separation allows for cleaner upgrades and multi-boot scenarios.
### Limine Bootloader
We chose [Limine](https://limine-bootloader.org/) because of its excellent support for modern protocols, its simplicity in configuration, and its lightweight footprint. It handles the transition from UEFI/BIOS environment to the kernel seamlessly.
## What the installation does
After a successful installation, your disk will look like this:
### Partition 1: EFI System Partition (ESP)
- `/boredos.elf`: The actual kernel binary.
- `/initrd.tar`: The basic system image loaded into RAM at boot.
- `/limine.conf`: The bootloader configuration.
- `/EFI/BOOT/BOOTX64.EFI`: The bootloader entry point for UEFI firmware.
### Partition 2: BoredOS Root
- `/bin/`: Executables.
- `/Library/`: System data.
- `.boredos_root`: Hidden marker file.
- `fonts/`, `images/`, `man/`: System resources.
- `/docs/`: System documentation.
- `/root/`: Persistent user files.

33
docs/usage/booting.md
View file

@ -1,33 +0,0 @@
# Booting BoredOS
BoredOS uses the Limine bootloader, which provides a flexible way to configure the boot process and pass parameters to the kernel.
## Boot Parameters
You can modify system behavior at startup by passing specific boot flags.
### Verbose Boot (`-v`)
The `-v` flag enables the kernel console (`kconsole`) during the boot process. When enabled, the kernel will display detailed initialization logs on the screen. By default, this is often disabled in the included configuration for a cleaner "splash-only" boot experience.
#### Toggling Verbose Boot at Runtime
You can enable or disable the verbose boot log directly from the Limine boot menu without modifying the source files:
1. **Select Entry**: When the Limine boot menu appears, highlight the **BoredOS** entry.
2. **Edit**: Press `E` to enter the entry editor.
3. **Modify Flag**: Find the line containing `cmdline: -v`.
- To **Enable**: Remove the `#` character if the line is commented out (change `# cmdline: -v` to `cmdline: -v`).
- To **Disable**: Add a `# ` at the start of the line.
4. **Boot**: Press `F10` to boot using the modified parameters.
#### Persistent Configuration
To change the default behavior permanently, modify the `limine.conf` file in the repository root before building the ISO:
```conf
/BoredOS
protocol: limine
path: boot():/boredos.elf
cmdline: -v
```