[Patch] Documentation for Bootloader, Kernel, VGA, CI Github Actions and Multiboot (#20)

Author: Mrgoblings

README.md

@@ -1,4 +1,65 @@
 # AnasOS
-an operatin system
 
-Curently in development.
+AnasOS is a lightweight operating system developed as a graduation project. The primary goal is to create a functional OS from scratch using modern technologies.
+
+## Download
+
+You can download the latest release of AnasOS, including the `iso.zip` file, from the [releases page](https://github.com/Mrgoblings/AnasOS/releases).
+
+## Technologies Used
+
+- **Rust**: The core of the operating system is written in Rust for safety and performance.
+- **Assembly**: Utilized for low-level system programming.
+- **Makefile**: Used for managing build automation.
+
+## Building the OS
+
+If you want to build AnasOS yourself, please follow these instructions for a Debian-based Linux distribution:
+
+1. **Clone the repository**:
+
+```sh
+git clone https://github.com/Mrgoblings/AnasOS.git
+cd AnasOS
+```
+
+2. **Install dependencies**:
+
+```sh
+sudo apt update
+sudo apt install -y nasm grub-pc-bin grub-common make mtools xorriso
+rustup update nightly
+rustup target add x86_64-unknown-none --toolchain nightly
+rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu
+```
+
+3. **Build & Run the OS in qemu**:
+
+```sh
+make
+```
+
+## Documentation
+
+For more detailed instructions and documentation, please refer to the [docs/](docs/) directory. There is a README file that explains everything needed for the OS.
+
+## References
+
+Here are some tutorials and resources that were used in the creation of AnasOS:
+
+- [ Writing an OS in Rust from Philipp Oppermann's blog](https://os.phil-opp.com/)
+- [Write Your Own 64-bit Operating System Kernel by CodePulse](https://www.youtube.com/playlist?list=PLZQftyCk7_SeZRitx5MjBKzTtvk0pHMtp)
+- [Making an OS (x86) by Daedalus Community](https://www.youtube.com/playlist?list=PLm3B56ql_akNcvH8vvJRYOc7TbYhRs19M)
+- [Operating Systems by OliveStem](https://www.youtube.com/playlist?list=PL2EF13wm-hWAglI8rRbdsCPq_wRpYvQQy)
+- [Stack Unwinding](https://www.bogotobogo.com/cplusplus/stackunwinding.php)
+- [Rust Standard Library Runtime](https://github.com/rust-lang/rust/blob/bb4d1491466d8239a7a5fd68bd605e3276e97afb/src/libstd/rt.rs#L32-L73)
+- [Name Mangling](https://en.wikipedia.org/wiki/Name_mangling)
+- [Calling Convention](https://en.wikipedia.org/wiki/Calling_convention)
+- [Cross Compilation with Clang](https://clang.llvm.org/docs/CrossCompilation.html#target-triple)
+- [Multiboot Specification](https://wiki.osdev.org/Multiboot)
+- [GNU GRUB Multiboot](https://www.gnu.org/software/grub/manual/multiboot/multiboot.html#OS-image-format)
+- [Paging in Operating System](https://www.geeksforgeeks.org/paging-in-operating-system/)
+
+## Author and Licensing
+
+AnasOS is developed by Emil Momchev. The project is licensed under the [MIT License](LICENSE). When distributing, mention the author and the repository.

docs/README.md

@@ -0,0 +1,98 @@
+# AnasOS Documentation
+
+Welcome to the AnasOS documentation. This document will guide you through the various components of the AnasOS operating system, including the multiboot configuration, kernel, window manager, and applications.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [File Structure](#file-structure)
+3. [Multiboot Configuration](#multiboot-configuration)
+4. [Bootloader](#bootloader)
+4. [Kernel](#kernel)
+5. [Window Manager](#window-manager)
+6. [Applications](#applications)
+7. [Technologies Used](#technologies-used)
+8. [CI with GitHub Actions](#ci-with-github-actions)
+9. [Requirements](#requirements)
+
+## Introduction
+
+AnasOS is a custom operating system designed for educational purposes as part of a 12th-grade thesis project. This documentation provides detailed information about the different parts of the OS and how they work together. AnasOS is built for the **_x86_64_** architecture, chosen over ARM due to the availability of more and better resources on the topic.
+
+## Technologies Used
+
+- **Rust**: The core of the operating system is written in Rust for safety and performance.
+- **NASM**: The assembler used for writing assembly code for the bootloader.
+- **Makefile**: Used for managing build automation.
+- **GRUB**: The bootloader used for loading the kernel.
+- **QEMU**: The emulator used for testing the operating system.
+- **GitHub Actions**: Used for continuous integration and deployment.
+
+## File Structure
+
+Below is the file structure for the AnasOS documentation:
+
+```
+/docs
+    ├── README.md
+    ├── applications
+    │   ├── README.md
+    │   ├── browser.md
+    │   └── terminal.md
+    ├── bootloader
+    │   ├── README.md
+    │   ├── header.md
+    │   ├── boot.md
+    │   └── boot-64.md
+    ├── ci-github-actions
+    │   ├── README.md
+    │   ├── header.md
+    │   ├── boot.md
+    │   └── boot-64.md
+    ├── kernel
+    │   ├── README.md
+    │   └── kernel.md
+    ├── multiboot
+    │   ├── README.md
+    │   └── multiboot.md
+    └── window-manager
+        ├── README.md
+        └── window_manager.md
+```
+
+## Multiboot Configuration
+
+The multiboot configuration is responsible for initializing the hardware and loading the kernel into memory. Detailed documentation about the multiboot configuration can be found [here](multiboot/).
+
+## Bootloader
+
+The bootloader is a critical component that initializes the system and loads the kernel into memory. It is responsible for setting up the environment so that the kernel can execute properly. Detailed documentation about the bootloader can be found [here](bootloader/).
+
+## Kernel
+
+The kernel is the core component of AnasOS, managing system resources and providing essential services. Detailed documentation about the kernel can be found [here](kernel/).
+
+## Window Manager
+
+The window manager **WILL** handle the graphical user interface and window management. Detailed documentation about the window manager will be available [here](window-manager/).
+
+## Applications
+
+AnasOS **WILL** include two main applications: a [browser](applications/browser.md) and a [terminal](applications/terminal.md). Detailed documentation about these applications will be available [here](applications/).
+
+## CI with GitHub Actions
+
+GitHub Actions is used for continuous integration (CI) to automate the build, testing, and release processes of AnasOS. This ensures that every change is verified, the system remains stable, and new versions are released efficiently. The workflows are defined in the `.github/workflows` directory, with detailed documentation available in the [here](ci-github-actions/).
+
+## Requirements
+
+Before fully testing the OS, ensure you have the following requirements installed:
+
+- **Rust**: Install Rust from [rust-lang.org](https://www.rust-lang.org/).
+- **NASM**: Install NASM from [nasm.us](https://www.nasm.us/).
+- **GRUB**: Install GRUB using your package manager.
+- **QEMU**: Install QEMU from [qemu.org](https://www.qemu.org/).
+- **Make**: Ensure Make is installed on your system.
+
+
+You can install the required packages on Debian-based Linux distributions using `apt` with the example from the [main README](../) file

docs/applications/README.md

@@ -0,0 +1,9 @@
+# Applications
+
+## Available Applications
+
+### Browser
+For more information, see [Browser](browser.md).
+
+### Terminal
+For more information, see [Terminal](terminal.md).

docs/applications/browser.md

@@ -0,0 +1,3 @@
+# Browser Application
+
+Coming soon. Not yet implemented.

docs/applications/terminal.md

@@ -0,0 +1,3 @@
+# Terminal Application
+
+Coming soon. Not yet implemented.

docs/bootloader/README.md

@@ -0,0 +1,46 @@
+# AnasOS Bootloader Documentation
+
+## Overview
+
+The AnasOS bootloader is a critical component of the AnasOS operating system. Written in NASM assembly, it is responsible for initializing the system and transitioning the CPU from real mode to 64-bit long mode. This document provides an overview of the bootloader's functionality and its role in the boot process.
+
+## Boot Files
+
+The bootloader consists of three main files:
+- **header.asm**: Contains the Multiboot2 header required for bootloader compatibility. More in the [header.md](header.md)
+- **boot.asm**: The main bootloader code, responsible for the entire boot process including setting up the stack, checking Multiboot compatibility, enabling paging, and handling errors More in the [boot.md](boot.md)
+- **boot-64.asm**: Handles the transition to 64-bit long mode. More in the [boot-64.md](boot-64.md)
+
+## Integration with the Kernel
+
+The bootloader is tightly integrated with the AnasOS kernel. The build process is managed by a `build.rs` script, which automates the compilation and linking of the bootloader and kernel object files into a single binary.
+
+### Build Process
+
+The `build.rs` script performs the following steps:
+1. **Assemble Bootloader**: The NASM assembler is used to compile the bootloader assembly files into object files.
+    ```sh
+    nasm -f elf64 header.asm -o header.o
+    nasm -f elf64 boot.asm -o boot.o
+    nasm -f elf64 boot-64.asm -o boot-64.o
+    ```
+2. **Link Object Files**: The object files are linked together with the kernel object files to create a single binary.
+    ```sh
+    ld -n -o bootloader.bin -T linker.ld header.o boot.o boot-64.o kernel.o
+    ```
+
+### Bootloader Compilation
+
+To compile only the bootloader manually, you would typically run the following commands:
+```sh
+nasm -f elf64 header.asm -o header.o
+nasm -f elf64 boot.asm -o boot.o
+nasm -f elf64 boot-64.asm -o boot-64.o
+ld -n -o bootloader.bin -T linker.ld header.o boot.o boot-64.o
+```
+
+For simplicity, there is a Makefile in the `anasos-kernel/bootloader` folder that handles this compilation. This Makefile is a simplified version of the main Makefile from the root folder, but its purpose is to compile correctly and run the newly created ISO from the bootloader with QEMU.
+
+## Conclusion
+
+The AnasOS bootloader is a sophisticated piece of software that ensures a smooth transition from the initial power-on state to a fully operational 64-bit environment. Its careful design and implementation in NASM assembly make it a reliable foundation for the AnasOS operating system.

docs/bootloader/boot-64.md

@@ -0,0 +1,71 @@
+# BOOT-64.ASM Documentation
+
+## Introduction
+This document provides a detailed explanation of the `BOOT-64.ASM` file, which is responsible for initializing the CPU in 64-bit long mode. After jumping into 64-bit mode, it's essential to set up the CPU environment correctly to ensure proper operation. The code is written in assembly language and is crucial for setting up the environment before the operating system kernel takes over. This documentation aims to explain each instruction and its purpose.
+
+## Code Explanation
+
+### Section: Setting Up Long Mode
+```assembly
+GLOBAL long_mode_start 
+EXTERN _start
+
+SECTION .text
+BITS 64
+long_mode_start:
+    ; load null to all data segment registers (needed for the cpu to work as intended)
+    MOV ax, 0
+    MOV ss, ax
+    MOV ds, ax
+    MOV es, ax
+    MOV fs, ax
+    MOV gs, ax
+
+    CALL _start
+
+    HLT
+```
+
+#### Detailed Breakdown
+
+1. **GLOBAL long_mode_start**
+   - Makes the `long_mode_start` label available to other files, allowing them to reference this entry point.
+
+2. **EXTERN _start**
+   - Declares an external symbol `_start`, which is the main function of the Rust kernel. This is where the kernel's execution begins.
+
+3. **SECTION .text**
+   - Defines the beginning of a code section named `.text`, where the executable code resides.
+
+4. **BITS 64**
+   - Informs the assembler that the following code is intended for 64-bit mode.
+
+5. **long_mode_start:**
+   - A label marking the entry point of the long mode setup code. At this point, the system has just transitioned into 64-bit mode.
+
+6. **MOV ax, 0**
+   - Loads the value `0` into the `AX` register to prepare for initializing the segment registers.
+
+7. **MOV ss, ax**
+   - Sets the `SS` (Stack Segment) register to `0`. In 64-bit mode, all segment registers need to be set to `0` for the CPU to function properly, ensuring correct memory addressing.
+
+8. **MOV ds, ax**
+   - Sets the `DS` (Data Segment) register to `0`, which is necessary for proper data access.
+
+9. **MOV es, ax**
+   - Sets the `ES` (Extra Segment) register to `0`.
+
+10. **MOV fs, ax**
+    - Sets the `FS` (Additional Data Segment) register to `0`.
+
+11. **MOV gs, ax**
+    - Sets the `GS` (Additional Data Segment) register to `0`. Initializing all these registers prevents segmentation errors and ensures the CPU operates as expected.
+
+12. **CALL _start**
+    - Calls the `_start` function, transferring control to the Rust kernel's main function.
+
+13. **HLT**
+    - Halts the CPU, typically used if there is nothing else to execute.
+
+## Conclusion
+The `BOOT-64.ASM` file is a critical component in the boot process of an operating system. After entering 64-bit long mode, setting all segment registers to `0` is essential for the CPU to function properly. This setup prepares the environment for the kernel's main function `_start` to take over. Each instruction serves a specific purpose to ensure the CPU operates correctly and transitions smoothly to the kernel.