Documentation (#56)

* Begin docs overhaul

* Add documentation on the kernel's structure and the ISR component

* Filesystem scope

* More docs writing

* Add some requirements

* Update index

README.md

@@ -13,19 +13,18 @@ _(1) MCH2025 is a preliminary name, MCH2025 is an event that will be organised b
 
 
 
-# Contributing
+# [Documentation](./docs/README.md)
 
-We are an open-source project, so we can always use more hands!
-If you're looking for things to help with, look for the [issues with the PoC (Proof of Concept) milestone](https://github.com/badgeteam/BadgerOS/issues/33).
-**We are currently using the ESP32-C6 for development.**
 
-Make sure to check out the [style guide](docs/styleguide.md) so your code can fit right in.
-If you're unsure where to put your code, look into the [project structure](docs/project-structure.md).
 
-If you're not sure what to do but want to help, message us:
-- [robotman2412](https://t.me/robotman2412) on telegram
+# Contributing
+We are an open-source project, so we can always use more hands!
+If you're new to this project and want to help, message us:
+- [RobotMan2412](https://t.me/robotman2412) on telegram
 - [Badge.team](https://t.me/+StQpEWyhnb96Y88p) telegram group
 
+After that, see [Project structure](./docs/project_structure.md) for reference about how this project works.
+
 
 
 # Prerequisites

docs/README.md

@@ -1,3 +1,20 @@
 # BadgerOS documentation
-- [C code style guide](styleguide.md)
-- [Project structure](project-structure.md)
+<!-- SPDX-License-Identifier: MIT -->
+<!--
+## For BadgerOS end users
+For information about how BadgerOS' official applications and interface work, see [BadgerOS user guide](./user_guide.md).
+-->
+
+## For contributors
+For information about the structure of the project, including building, tools and folder structure, see [Project structure](./project_structure.md).
+
+## For BadgerOS kernel developers
+For information about the internal structure and API of the BadgerOS kernel, see [Kernel documentation](./kernel/README.md).
+
+<!--
+## For BadgerOS application developers
+For information about the APIs available to application developers, see [BadgerOS API](./api/README.md).
+
+## For all BadgerOS developers
+-->
+For project plan and requirements, see [Project requirements](./project_requirements.md).

docs/kernel/README.md

@@ -0,0 +1,54 @@
+# Kernel documentation
+This page is intended for BadgerOS kernel developers.
+It details the internal kernel APIs and structures.
+
+## Index
+- [List of kernel components](#list-of-kernel-components)
+- [Component interaction overview](#component-interaction-overview)
+- [Components and their purpose](#components-and-their-purpose)
+
+
+# List of kernel components
+These links provide more detail on the scope and requirements per component and their APIs (when implemented).
+- [Hardware abstraction layer](./hal.md)
+- [Scheduler](./scheduler.md)
+- [Process management](./process.md)
+- [Memory management](./memory.md)
+- [Filesystems](./filesystems.md)
+- [Traps and interrupts](./isr.md)
+
+
+# Component interaction overview
+Components in the rows use APIs from components in the columns.
+|       | HAL   | Sched | Proc  | Mem   | FS    | Trap  |
+| :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| HAL   |       |       |       |       |       |       |
+| Sched |       |       |       |       |       |   x   |
+| Proc  |       |   x   |       |   x   |   x   |       |
+| Mem   |       |       |       |       |       |       |
+| FS    |   x   |       |       |       |       |       |
+| Trap  |       |   x   |       |       |       |       |
+
+
+# Components and their purpose
+## Hardware abstraction layer
+The hardware abstraction layer, or HAL for short, provides a generic interface to various hardware functions, including GPIO, I²C, SPI, FLASH, etc.
+Other components can then use the HAL to perform the same operations on different hardware without the need for porting them.
+Take filesystems for example, where one type of filesystem can be stored on almost any kind of media without the need for explicit support from the filesystem driver.
+
+## Scheduler
+The scheduler manages distribution of CPU time between threads running on the same system. BadgerOS implements a [preemptive scheduler](https://en.wikipedia.org/wiki/Preemption_(computing)); the scheduler takes back control after a predetermined time so one process cannot freeze the entire computer.
+
+## Process management
+The process management API manages the creation and termination of processes and assigning resources to processes. All resources given to a process are accounted by the process management API so they can be reclaimed when the process exits.
+The process API has tight relationships with the scheduler and memory management because both threads and memory are resources integral to the existance of processes.
+
+## Memory management
+All the memory available to the system is handled centrally by the memory manager. The memory manager is responsible for accounting the available memory and distributing said memory between processes, kernel-side caches, kernel stacks and kernel data structures.
+Memory management also includes the configuration of virtual memory or memory protection, whichever is applicable.
+
+## Filesystems
+The filesystem component is reponsible for managing all the mounted filesystems. It abstracts the filesystem details away, leaving only a generic interface that applies to all types of filesystem.
+
+## Traps and interrupts
+Traps and interrupts are low-level mechanisms of the CPU used for error conditions and events respectively. Traps can be illegal instruction, memory access fault, system calls, etc. while interrupts are generated by other hardware like timers, GPIO, SPI, I²C or inter-CPU communication.

docs/kernel/filesystems.md

@@ -0,0 +1,78 @@
+# Filesystems
+The filesystem component is reponsible for managing all the mounted filesystems. It abstracts the filesystem details away, leaving only a generic interface that applies to all types of filesystem.
+
+Currently responsible: Joyce (Quantumcatgirl).
+
+## Index
+- [Scope](#scope)
+- [Dependents](#dependents)
+- [Dependencies](#dependencies)
+- [Data types](#data-types)
+- [API](#api)
+
+
+# Scope
+BadgerOS will initially support both a RAM filesystem, also called RAMFS, and a FAT filesystem. It supports FAT before EXT2/3/4 as a compromise to allow mounting the filesystem from Windows or MacOS without the need for additional software. In the future, EXT2/3/4 *may* be supported, but there are higher priorities than that.
+
+Most filesystems will be stored on nonvolatile physical media. This physical media is abstracted from the filesystem implementation by the block device API. The block device API is similar to the HAL in purpose, but not dependant on the target platform.
+
+## API scope
+- API support for UNIX permissions
+- API support for reading and writing
+- API support for sybolic links (TODO)
+- API support for hard links (TODO)
+
+## FAT filesystem scope
+- Support for FAT12, FAT16 and FAT32 (TODO)
+- Support for [long filename](https://en.wikipedia.org/wiki/Long_filename) entries (TODO)
+- Support for reading and writing (TODO)
+- Support for formatting (TODO)
+
+## RAM filesystem scope
+- Support for UNIX permissions
+- Support for reading and writing
+- Support for device special files (TODO)
+- Support for symbolic links (TODO)
+- Support for hard links
+
+## Block device scope
+- Support for reading, writing and erasing blocks
+- Support for block size and total size detection
+
+
+# Dependents
+## [Process management](./process.md)
+The process management component uses filesystems to load executable files to start programs.
+
+
+# Dependencies
+## [Hardware abstraction layer](./hal.md)
+The block device part of the filesystems component uses the HAL to abstract the implementation details of communication with the storage media.
+
+
+# Data types
+TODO.
+
+
+# API
+Because of the multiple abstractions present in the filesystems, the API is split into 5 parts:
+- High-level filesystem API: `fs_*`
+- Filesystem abstraction layer: `vfs_*`
+- Filesystem implementations: `vfs_fat_*`, `vfs_ramfs_*`, etc.
+- Block device abstraction layer: `blkdev_*`
+- Block device implementations: `blkdev_ram_*`, etc.
+
+## High-level filesystem API
+The high-level filesystem API translates traditional file operations into calls to the filesystem abstraction layer that more directly represent operations on the filesystem.
+
+The high-level filesystem API also converts multiple file handles per logical file into one single handle so individual filesystem implementations only need to manage one handle per file / directory.
+
+## Filesystem abstraction layer
+The filesystem abstraction layer defines which functions each filesystem needs to implement and forwards every function call directly to the implementation.
+
+The filesystem abstraction layer and the filesystem implementation only manage one handle per file, so they only need to synchronize accesses between different files not symbolic or hard linked.
+
+## Block device abstraction layer
+The block device abstraction layer implements caches and some common utilities for accessing block devices. It calls the block device implementations for read, write and erase commands, which handle the uncached accesses.
+
+The block device API does synchronize multiple accesses to the same partition, which is the taks of the filesystem implementation.

docs/kernel/hal.md

@@ -0,0 +1,62 @@
+# Hardware abstraction layer
+The hardware abstraction layer, or HAL for short, provides a generic interface to various hardware functions, including GPIO, I²C, SPI, FLASH, etc.
+Other components can then use the HAL to perform the same operations on different hardware without the need for porting them.
+Take filesystems for example, where one type of filesystem can be stored on almost any kind of media without the need for explicit support from the filesystem driver.
+
+Currently responsible: Julian (RobotMan2412).
+
+## Index
+- [Scope](#scope)
+- [Dependents](#dependents)
+- [Dependencies](#dependencies)
+- [Data types](#data-types)
+- [API](#api)
+
+
+# Scope
+The HAL needs to provide an abstract interface that can perform all actions that BagderOS needs it to. There will abstractions for:
+- GPIO
+    - Digital I/O
+    - PWM outputs
+    - ADC
+    - DAC
+- I²C
+- UART
+- SPI
+- I²S
+- FLASH
+
+## GPIO scope
+The GPIOs need to be able to function as digital I/Os and all alternate functions provided by the hardware for which there is a driver (I²C, UART, SPI, etc.). The GPIO API also needs to be able to tell whether a pin is currently in use by one of such alternate functions. At least one GPIO input pin needs to support interrupts.
+
+## I²C scope
+The I²C HAL needs to support master, slave, 10-bit addressing and interrupts.
+
+## UART scope
+The UART HAL needs to support baudrate configuration and interrupts.
+
+## SPI scope
+The SPI HAL needs to support DMA, one-wire SPI, two-wire SPI and interrupts.
+
+## I²S scope
+TODO: Depends on sound architecture
+
+## FLASH scope
+The FLASH HAL needs to support FLASH MMUs (if present), reading, erasing and writing.
+
+
+# Dependents
+## [Filesystems](./filesystems.md)
+The block device drivers from the filesystems component depend on the HAL to abstract communications with physical storage media.
+
+
+# Dependencies
+The HAL does not depend on other components.
+
+
+# Data types
+TODO.
+
+
+# API
+TODO.

docs/kernel/isr.md

@@ -0,0 +1,72 @@
+# Traps and interrupts
+Traps and interrupts are low-level mechanisms of the CPU used for error conditions and events respectively. Traps can be illegal instruction, memory access fault, system calls, etc. while interrupts are generated by other hardware like timers, GPIO, SPI, I²C or inter-CPU communication.
+
+Currently responsible: Julian (RobotMan2412).
+
+## Index
+- [Scope](#scope)
+- [Dependents](#dependents)
+- [Dependencies](#dependencies)
+- [Data types](#data-types)
+- [API](#api)
+
+
+# Scope
+The interrupt service routine, or ISR for short, handles these CPU events and converts them into events in the kernel. A limited amount of code can run inside an interrupt, with the exception of system calls, which are run on the kernel thread associated with the process.
+
+
+# Dependents
+## [Scheduler](./scheduler.md)
+The scheduler calls `isr_ctx_switch_set` to inform the ISR which context to run next. This context can be kernel side (either kernel thread or kernel side of user thread) or user side (user side of user thread).
+
+
+# Dependencies
+## [Scheduler](./scheduler.md)
+When a trap or interrupt happens, the ISR can call `sched_request_switch_from_isr` to ask the scheduler if a context switch is in order and if so, to which context.
+When a system call happens, the ISR calls `sched_raise_from_isr` to "raise" the privileges to kernel mode and run specified kernel code in the thread.
+
+
+# Data types
+## isr_ctx_t
+The ISR context is a CPU-specific data structure that stores the execution context for a side of a thread; kernel threads have one ISR contexts while user threads have one each for their kernel and user sides.
+
+Aside from the CPU-specific fields, which should not be accessed by code that is not CPU-specific, there are two general fields:
+
+### Field: `sched_thread_t *thread`
+Pointer to owning `sched_thread_t`.
+Used by the ISR itself to call the scheduler with the appropriate thread handle.
+
+### Field: `bool is_kernel_thread`
+Thread is a kernel thread.
+If true, the thread is run in M-mode, otherwise it is run in U-mode.
+
+M-mode (or kernel-mode) contexts are (run as) the kernel, inheriting all the privileges associated. U-mode (or user-mode) contexts are for user code and their privileges are strictly regulated by the kernel.
+
+The scheduler uses this field to indicate in which privilege mode the context should be run.
+
+
+# API
+## `static inline isr_ctx_t *isr_ctx_get();`
+Get the current [ISR context](#isr_ctx_t).
+
+Used by the scheduler and error handling functions as a CPU-specific way to get information about the execution state.
+
+## `static inline isr_ctx_t *isr_ctx_switch_get();`
+Get the outstanding context switch target, if any.
+
+Can be used to query which ISR context is set to be switched to. If NULL, the current context is kept when the ISR returns.
+
+## `static inline void isr_ctx_switch_set(isr_ctx_t *switch_to);`
+Set the context switch target to switch to before exiting the trap/interrupt handler.
+
+Used by the scheduler in response to a call to `sched_request_switch_from_isr`.
+
+## `void isr_ctx_dump(isr_ctx_t const *ctx);`
+Print a register dump given isr_ctx_t.
+
+Used by error handlers to print the execution state when either the kernel panics or a user thread raises an exception.
+
+## `void kernel_cur_regs_dump();`
+Print a register dump of the current registers.
+
+Used by error handlers when the kernel panics.

docs/kernel/memory.md

@@ -0,0 +1,33 @@
+# Memory management
+All the memory available to the system is handled centrally by the memory manager. The memory manager is responsible for accounting the available memory and distributing said memory between processes, kernel-side caches, kernel stacks and kernel data structures.
+Memory management also includes the configuration of virtual memory or memory protection, whichever is applicable.
+
+Currently responsible: Hein-Pieter van Braam (HP).
+
+## Index
+- [Scope](#scope)
+- [Dependents](#dependents)
+- [Dependencies](#dependencies)
+- [Data types](#data-types)
+- [API](#api)
+
+
+# Scope
+Memory management is in charge of allocating and protecting all the memory available to the system. Various systems in the kernel and applications can request memory for various purposes. The memory allocator decides how much memory at what addresses to assign to applications or the kernel. This information is then relayed to memory protection for the application or kernel respectively.
+
+
+# Dependents
+## [Process management](./process.md)
+The process management component relays requests for memory from the processes to the memory management component.
+
+
+# Dependencies
+The memory allocator does not depend on other components.
+
+
+# Data types
+TODO.
+
+
+# API
+TODO.

docs/kernel/process.md

@@ -0,0 +1,31 @@
+# Document title
+Description
+
+Currently responsible: Name (Nickname).
+
+## Index
+- [Scope](#scope)
+- [Dependents](#dependents)
+- [Dependencies](#dependencies)
+- [Data types](#data-types)
+- [API](#api)
+
+
+# Scope
+Scope
+
+
+# Dependents
+
+
+
+# Dependencies
+
+
+
+# Data types
+TODO.
+
+
+# API
+TODO.