diff options
| -rw-r--r-- | README.rst | 38 |
1 files changed, 27 insertions, 11 deletions
@@ -1,32 +1,48 @@ TeachOS Kernel ============== -The TeachOS kernel for the core of the operating system. +TeachOS is a modern kernel with a focus on clean design and simplicity. +It is not highly optimized like production grade kernels, but instead aims to be understandable. It is implemented in assembly and C++, where the amount of assembly is kept to a minimum. The primary design goal of the kernel is to be teachable and useful as part of the operating systems lecture track at OST. -Therefore, subsystems might not be implemented in a runtime performance optimal way but rather to be understandable and clear. Development ----------- Development happens primarily on Linux. -Other platforms (e.g. Windows, macOS) may allow building of the kernel as well, however at the time of this writing they are not officially supported. +Other platforms (e.g. Windows, macOS) may allow building of the kernel as well, however at the time of writing they are not officially supported. Required Tools ~~~~~~~~~~~~~~ -In order to build the kernel, the following tools are required: +A precompiled toolchain, targeting only x86-64 as of the time of writing, is available in the `Devconainers <https://gitlab.ost.ch/teachos/devcontainers>`_ repository. +The toolchain is provided both as a downloadable, self-contained archive and an Ubuntu Linux based Docker image. +When using the downloadable archive, care must be taken to make the contained executables available in the user's or system path. +Also, when using the downloadable archive, further required tools, like CMake, QEMU, Ninja, xorisso, grub, etc. must be installed separately. -- Docker to run the development container -- Visual Studio Code for development +The primary IDE used for development is VSCodium. +A configuration of runnable tasks, debugging settings, etc. as well as suggested extensions is provided. +Other IDEs might work, especially Visual Studio Code related ones, but no support is provided. -Setup -~~~~~ +Repository Structure +~~~~~~~~~~~~~~~~~~~~ -Open this directory in Visual Studio Code and then reopen the project in the development container +The code is grouped into separate "sub-packages", according to the following rules: + +- ``arch``: The root of all platform-dependent code. +- ``kapi``: The Kernel API, implemented by either the kernel itself, or the platform, used by both. +- ``kernel``: The root of all platform-independent code +- ``libs``: Support libraries, like the TeachOS Standard Library, or Multiboot2 support. + +When implementing new features, drivers, or infrastructure, care must be taken as to where to place the new code. +In general, platform-dependent code, like CPU access, MMU configuration, privilege handling etc., should be placed in the relevant folder under the ``arch`` root. +Platform independent-code, like generic memory allocation or scheduling algorithms, or generic drivers for hardware like PCIe devices, should be placed under the ``kernel`` root. Launching ~~~~~~~~~ -The build systems ships with a target (`bootable-iso`) that creates an ISO image containing a GRUB setup, capable of booting the kernel. -Additionally, the development container includes GDB and QEMU making it possible to run the configured GDB launch configuration to debug the kernel.
\ No newline at end of file +The default build target generates a bootable image. +On x86-64 for example, this image takes the form of a bootable, grub2 based ISO image. +These images are designed to be booted in QEMU, and should theoretically also be bootable on real hardware. +However, note that not warranty is provided, and the kernel code may irreparably destroy any physical hardware if booted on a real system. +The VSCodium IDE configuration provides a launch task using QEMU, available for debugging (via F5) and direct launch as a task.
\ No newline at end of file |