From bb187faf79217b0e862bd844566d992d9071fa5c Mon Sep 17 00:00:00 2001 From: boreddevnl Date: Tue, 14 Apr 2026 10:59:52 +0200 Subject: [PATCH] DOC: small user manual --- docs/README.md | 10 +++++++++- docs/usage/booting.md | 33 +++++++++++++++++++++++++++++++++ docs/usage/desktop.md | 35 +++++++++++++++++++++++++++++++++++ docs/usage/launching_apps.md | 31 +++++++++++++++++++++++++++++++ docs/usage/lumos.md | 29 +++++++++++++++++++++++++++++ docs/usage/terminal.md | 33 +++++++++++++++++++++++++++++++++ limine.conf | 1 + src/core/kconsole.c | 2 +- src/core/kutils.c | 14 ++++++++++++++ src/core/kutils.h | 1 + src/core/main.c | 10 ++++++++++ src/sys/idt.c | 8 ++++---- src/sys/smp.c | 28 +++++++++++++--------------- 13 files changed, 214 insertions(+), 21 deletions(-) create mode 100644 docs/usage/booting.md create mode 100644 docs/usage/desktop.md create mode 100644 docs/usage/launching_apps.md create mode 100644 docs/usage/lumos.md create mode 100644 docs/usage/terminal.md diff --git a/docs/README.md b/docs/README.md index 8b5bbbd..a44df9d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,7 @@ --- -Welcome to the internal documentation for BoredOS! This directory contains detailed guides on how the OS functions, how to build it, and how to develop applications for it. +Welcome to the documentation for BoredOS! This directory contains detailed guides on how the OS functions, how to build it, and how to develop applications for it. ## 📚 Table of Contents @@ -32,4 +32,12 @@ The SDK and toolchain guides for creating your own `.elf` userland binaries. - [`Example Apps`](appdev/examples/README.md): A collection of sample C applications ranging from basic terminal output to advanced TCP networking. - [`Grapher`](appdev/grapher.md): Full reference for the built-in mathematical graphing application — equation syntax, keyboard controls, architecture, and configuration. +### 4. [Usage](usage/) +General guides on how to interact with the OS. +- [`Booting`](usage/booting.md): How to use the Limine bootloader and toggle kernel boot flags like `-v`. +- [`Desktop`](usage/desktop.md): Window management, shortcuts, and desktop interaction. +- [`Lumos`](usage/lumos.md): Using the system-wide search (`Shift + Ctrl + Space`). +- [`Terminal`](usage/terminal.md): Command line interface, redirection, and common commands. +- [`Launching Apps`](usage/launching_apps.md): Ways to launch files and applications, plus a software overview. + --- diff --git a/docs/usage/booting.md b/docs/usage/booting.md new file mode 100644 index 0000000..3377d10 --- /dev/null +++ b/docs/usage/booting.md @@ -0,0 +1,33 @@ +# 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 +``` diff --git a/docs/usage/desktop.md b/docs/usage/desktop.md new file mode 100644 index 0000000..7a1c3c4 --- /dev/null +++ b/docs/usage/desktop.md @@ -0,0 +1,35 @@ +# Using the Desktop + +The BoredOS desktop environment is designed to be intuitive while providing powerful window management and icons for quick access to your files and applications. + +## Window Management + +BoredOS uses a stacking window manager (BoredWM) that allows you to overlap and organize multiple windows. + +### Basic Actions +- **Focus**: Click anywhere on a window to bring it to the front and make it the active window. +- **Move**: Click and drag the **title bar** (the top bar of the window) to reposition it on the screen. +- **Close**: Click the red traffic light close button in the top-left corner of the window. + +### System-wide Shortcuts +BoredOS includes several global shortcuts to help you manage your workflow: +- **`Ctrl + P`**: Take a screenshot. The image will be saved to `/root/Desktop` as `screenshot.jpg`. +- **`Shift + Ctrl + Space`**: Toggle **Lumos** search (see the [Lumos guide](lumos.md)). + +## Desktop Icons + +Your desktop represents the contents of the `/root/Desktop` directory. + +- **Launching**: Double-click an icon to open the file or launch the application. +- **Snapping**: Icons automatically snap to a grid for a clean look. You can toggle "Snap to Grid" and "Auto Align" in the [Settings app](../launching_apps.md). +- **Context Menu**: Right-click on the desktop background to create new files, folders, or refresh the layout. + +## The Bottom Dock + +The dock at the bottom of the screen provides quick shortcuts to your most-used applications, with for example: +- **Files**: Browse the entire filesystem. +- **Terminal**: Access the command-line interface. +- **Calculator / Notepad / Grapher**: Essential productivity tools. + +--- +[Return to Documentation Index](../README.md) diff --git a/docs/usage/launching_apps.md b/docs/usage/launching_apps.md new file mode 100644 index 0000000..64fa4db --- /dev/null +++ b/docs/usage/launching_apps.md @@ -0,0 +1,31 @@ +# Launching Applications + +BoredOS provides several ways to launch applications and files, depending on your preferred workflow. + +## 1. Using the File Explorer + +The File Explorer is the primary way to navigate the filesystem and launch any `.elf` binary or associated document. + +1. Open the **Explorer** from the dock or desktop. +2. Navigate to `/bin` for system applications or your own user folders. +3. **Double-click** any executable (`.elf`) to run it. +4. Standard files (like `.jpg` or `.txt`) will automatically open in their default viewer. + +## 2. Desktop Shortcuts and Icons + +Commonly used applications are placed directly on the desktop. + +- Simply **Double-click** any icon on the desktop to launch it. +- You can also create desktop shortcuts by right-clicking on a file and selecting **"Create Shortcut"**. + +## 3. Using Lumos (Global Search) + +For the fastest access, use **Lumos** to search and launch by name: + +1. Press **`Shift + Ctrl + Space`**. +2. Type the name of the app (e.g., "DOOM.elf"). +3. Press **Enter** to launch. + + +--- +[Return to Documentation Index](../README.md) diff --git a/docs/usage/lumos.md b/docs/usage/lumos.md new file mode 100644 index 0000000..d9b472a --- /dev/null +++ b/docs/usage/lumos.md @@ -0,0 +1,29 @@ +# Lumos: System Search + +**Lumos** is the powerful, system-wide search and launch assistant for BoredOS. It allows you to find applications, documents, and system files instantly without navigating through folders. + +## Opening Lumos + +To activate Lumos at any time, use the global keyboard shortcut: + +**`Shift + Ctrl + Space`** + +The Lumos search modal will appear in the center of your screen, ready for input. + +## Features + +- **Fuzzy Searching**: You don't need to type the exact name. Lumos uses fuzzy matching to find the most relevant results as you type. +- **Deep Indexing**: Lumos indexes files across the entire system. +- **Quick Launch**: Once you find what you're looking for, launching it is as simple as pressing `Enter`. + +## Navigation + +When the Lumos window is open: +- **Type**: Just start typing to filter results. +- **Arrow Keys (Up/Down)**: Move the selection highlight through the list of results. +- **Enter**: Launch the selected file or application. +- **Backspace**: Delete characters in your search query. +- **Escape**: Close Lumos and return to the desktop. + +--- +[Return to Documentation Index](../README.md) diff --git a/docs/usage/terminal.md b/docs/usage/terminal.md new file mode 100644 index 0000000..223d472 --- /dev/null +++ b/docs/usage/terminal.md @@ -0,0 +1,33 @@ +# Terminal & Command Line + +The BoredOS Terminal provides a powerful command-line interface (CLI) for advanced users and developers. It supports standard Unix-like features and provides direct access to the kernel's system calls. + +## The Shell + +The default shell in BoredOS is a custom-built, lightweight command processor integrated into the Window Manager. It features: +- **ANSI Color Support**: Rich text output with colors and styles. +- **Command History**: Use the **Up** and **Down** arrow keys to navigate through your previous commands (up to 64 history entries). +- **Output Redirection**: + - `command > file`: Write output to a new file (or overwrite existing). + - `command >> file`: Append output to an existing file. +- **Piping**: + - `command1 | command2`: Pass the output of the first command as input to the second. + +## Common Commands + +Below are some of the most used commands available in `/bin`: + +| Command | Description | +| :--- | :--- | +| `ls` | List files and directories in the current path. | +| `cd` | Change the current working directory. | +| `cat` | Display the contents of a file. | +| `ls` | List directory contents. | +| `rm` | Remove a file. | +| `mkdir` | Create a new directory. | +| `man` | View the manual for a specific command (e.g., `man ls`). | +| `sysfetch` | Display system and hardware information. | + + +--- +[Return to Documentation Index](../README.md) diff --git a/limine.conf b/limine.conf index be1fc5f..5b25025 100644 --- a/limine.conf +++ b/limine.conf @@ -13,3 +13,4 @@ backdrop: 000000 /BoredOS protocol: limine path: boot():/boredos.elf + # cmdline: -v diff --git a/src/core/kconsole.c b/src/core/kconsole.c index 8bed8bb..6b8e244 100644 --- a/src/core/kconsole.c +++ b/src/core/kconsole.c @@ -15,7 +15,7 @@ static uint32_t text_color = 0xFFFFFFFF; // White void kconsole_init(void) { cursor_x = 10; cursor_y = 10; - kconsole_active = true; + kconsole_active = false; // Initial clear screen during boot graphics_clear_back_buffer(0x00000000); diff --git a/src/core/kutils.c b/src/core/kutils.c index 2b39e04..fa69362 100644 --- a/src/core/kutils.c +++ b/src/core/kutils.c @@ -155,3 +155,17 @@ void k_beep_process(void) { } } +char *k_strstr(const char *haystack, const char *needle) { + if (!*needle) return (char *)haystack; + for (; *haystack; haystack++) { + const char *h = haystack; + const char *n = needle; + while (*h && *n && *h == *n) { + h++; + n++; + } + if (!*n) return (char *)haystack; + } + return NULL; +} + diff --git a/src/core/kutils.h b/src/core/kutils.h index 939cccb..a49e772 100644 --- a/src/core/kutils.h +++ b/src/core/kutils.h @@ -26,5 +26,6 @@ void k_reboot(void); void k_shutdown(void); void k_beep(int freq, int ms); void k_beep_process(void); +char *k_strstr(const char *haystack, const char *needle); #endif diff --git a/src/core/main.c b/src/core/main.c index 1bbe5e3..fdc61ff 100644 --- a/src/core/main.c +++ b/src/core/main.c @@ -70,6 +70,7 @@ static volatile struct limine_bootloader_info_request bootloader_info_request = .revision = 0 }; +__attribute__((used, section(".requests"))) static volatile struct limine_kernel_file_request kernel_file_request = { .id = LIMINE_KERNEL_FILE_REQUEST, .revision = 0 @@ -229,6 +230,15 @@ void kmain(void) { struct limine_framebuffer *fb = framebuffer_request.response->framebuffers[0]; graphics_init(fb); kconsole_init(); + + // Check for verbose boot flag + if (kernel_file_request.response != NULL && kernel_file_request.response->kernel_file != NULL) { + const char *cmdline = kernel_file_request.response->kernel_file->cmdline; + if (cmdline != NULL && k_strstr(cmdline, "-v") != NULL) { + kconsole_set_active(true); + } + } + log_ok("Graphics and Console ready"); if (memmap_request.response != NULL) { diff --git a/src/sys/idt.c b/src/sys/idt.c index e533cfd..a3b95ee 100644 --- a/src/sys/idt.c +++ b/src/sys/idt.c @@ -140,12 +140,12 @@ static void pic_remap(void) { static void pit_setup(void) { uint16_t divisor = 1193182 / 60; // ~60Hz - // Send command byte - outb(0x43, 0x36); // Channel 0, lobyte/hibyte, mode 3 (square wave), binary + // Mode 2: Rate Generator (more appropriate for periodic interrupts) + outb(0x43, 0x34); io_wait(); // Channel 0, lobyte/hibyte, mode 2, binary // Send divisor - outb(0x40, divisor & 0xFF); - outb(0x40, (divisor >> 8) & 0xFF); + outb(0x40, divisor & 0xFF); io_wait(); + outb(0x40, (divisor >> 8) & 0xFF); io_wait(); } void idt_init(void) { diff --git a/src/sys/smp.c b/src/sys/smp.c index c2942b2..24bba10 100644 --- a/src/sys/smp.c +++ b/src/sys/smp.c @@ -31,27 +31,24 @@ static inline void wrmsr(uint32_t msr, uint64_t value) { } static uint32_t read_lapic_id(void) { - uint32_t eax, ebx, ecx, edx; - asm volatile("cpuid" : "=a"(eax), "=b"(ebx), "=c"(ecx), "=d"(edx) : "a"(1)); - return (ebx >> 24) & 0xFF; + extern uint64_t hhdm_offset; + volatile uint32_t *lapic = (volatile uint32_t *)(hhdm_offset + 0xFEE00000ULL); + return (lapic[0x020 / 4] >> 24) & 0xFF; } uint32_t smp_this_cpu_id(void) { - if (total_cpus <= 1 || !cpu_states) return 0; - - // Use GS-based self-pointer to get the structure first - cpu_state_t *state = NULL; - // Safely check GS:0. If GS is not set or base is 0, this should be handled carefully. - // In BoredOS, if GS is not set, this might still fault depending on address space. - // However, the cpu_states check above covers the most likely early-boot failure. - asm volatile("movq %%gs:0, %0" : "=r"(state) : : "memory"); - if (state) return state->cpu_id; + if (!cpu_states || total_cpus == 0) return 0; uint32_t lapic = read_lapic_id(); + if (lapic == bsp_lapic_id) return 0; + cpu_state_t *state = NULL; + asm volatile("movq %%gs:0, %0" : "=r"(state) : : "memory"); + if (state && state->lapic_id == lapic) return state->cpu_id; for (uint32_t i = 0; i < total_cpus; i++) { - if (cpu_states[i].lapic_id == lapic) return i; + if (cpu_states[i].online && cpu_states[i].lapic_id == lapic) return i; } - return 0; // Fallback to BSP + + return 0; } uint32_t smp_cpu_count(void) { @@ -126,7 +123,8 @@ static void ap_entry(struct limine_smp_info *info) { void smp_init_bsp(void) { static cpu_state_t bsp_state_static = {0}; bsp_state_static.cpu_id = 0; - bsp_state_static.lapic_id = read_lapic_id(); + bsp_lapic_id = read_lapic_id(); + bsp_state_static.lapic_id = bsp_lapic_id; bsp_state_static.self = &bsp_state_static; bsp_state_static.online = true;