Abanu Kernel Documentation¶
Building Abanu¶
Abanu can be build platform independent. However, we support primary an unix build environment. For Windows Users, we offer a Step by Step guide.
Building on Linux¶
You need some packages:
git
version control systembuild-essential
Build toolswget
for downloading additional ressorcesnasm
Assemblermtools
Creating FAT disk imagesgrub-*
for creating boot images with bootloader. It will not affect your current system. We need the binaries for the disk creation.xorriso
Disk creation
You can install them all via:
sudo apt-get install -y --no-install-recommends git get nasm qemu-system-x86 mtools xorriso grub-common grub-pc-bin grub-efi-amd64-bin grub-efi-ia32-bin
If you want to debug Abanu, you also need gdb
.
Download and build:
git clone --recursive https://github.com/abanu-org/abanu.git
cd abanu
make
To run the kernel, just execute ./abctl run qemu x86-grub-vbe
.
To debug the kernel, run ./abctl debug qemu-kernel
Building on Windows¶
The Quick way¶
If you want only start run Abanu, just get the sources, open Abanu.sln in Visual Studio, compile whole solution launch the default project (Abanu.Tools.Build
). However, this is
only a shortcut. If you want debug Abanu, you may need the following steps.
Install the Windows Subsystem for Linux¶
Before installing any Linux distros for WSL, you must ensure that the “Windows Subsystem for Linux” optional feature is enabled:
- Open PowerShell as Administrator and run:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
- Restart your computer when prompted.
Visit Microsoft App Store, and Download the App Debian
Populate the Debian System with Packages:
# run as root
apt-get update && apt-get install -y wget
wget -qO- https://raw.githubusercontent.com/abanu-org/abanu/master/build/debian/install | bash -s
This will take a while. After that, you have a fully featured build environment.
Enabling Graphical Unix Applications¶
To launch graphical applications like Geany or Qalculate, you need XLaunch / VcXsrv Windows X Server. We can do this all via command line:
In Windows, install the packet manager chocolatey. Open a PowerShell with Administrator rights and run:
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
Install the package VcXsrv:
choco install -y vcxsrv
You can launch now XLaunch
from Start menu. Simply follow the wizard without making changes.
Open the Debian app and finish the install instructions. When command prompt is ready, start a dedicated Terminal:
export DISPLAY=:0 && xfce4-terminal &
Now you can run unix applications even with graphical user interface.
Additional Tools for Windows:¶
choco install -y git
Download and build Abanu¶
git clone --recursive https://github.com/abanu-org/abanu.git
cd abanu
./abctl configure packages
./abctl build all
Now you can run abanu in qemu:
./abctl debug qemu-kernel
TODO¶
- Compiler:
- - STACK_TOP configurable- Patch for ProgramHeader [DONE]- Insert Comment for explanation why needing Running InitializeAssembly() manually [DONE]- Adding more DWARF sections to debug local variables.
- Kernel:
- - Check Permission of all SysCalls, like GetPhysicalMemory- Don’t run all apps with full IOCPL permissions- Add interprocess synchronization mechanisms like mutex and semaphore.- no kernel panic if user apps is crashing- Switch from Text Mode to Graphics Mode without boot loader, if booted in text mode.- Add x64 support
- Services:
- - avoid using “unsafe” keyword.- Using more ref structs.- Finalize File-System Interface- Free Handles on User app quit- Ext2-Driver- Network stack- Basic USB-Support- Move ConsoleHost to central Service- Multiplexing ConsoleHost for multiple clients / allow multiple virtual consoles
- Libs:
- Implement Memory-/Allocation-friendly Dictionary “KDictionary”.Porting “newlib” with basic SysCalls.
- Apps:
- Simple Command Line InterpreterPorting true, false, cat, readline and echo, as native c apps for proof of concept unix app tests, based on newlib.
- Tools:
- Adding automated testsOptimize Argument parsing of abctl to allow optional parameters (–name value) and bulk actions (build a,b,c)Attaching “Networkdisk” to all kinds of qemu runs.Add helper function to abctl to start/stop HostCommunication.exe
About this documentation¶
This document focuses on style-guide and a short reference. It is a kind of coding standards applied to documentation files. It is not about documentation content.
HTML, Online | https://docs.abanu.org/en/latest |
https://readthedocs.org/projects/abanu/downloads/pdf/latest | |
HTML, as Zip | https://readthedocs.org/projects/abanu/downloads/htmlzip/latest |
RestructuredText with Sphinx directives¶
This documentation uses Python-sphinx [1], which itself uses reStructuredText [2] syntax.
Filenames¶
Use only lowercase alphanumeric characters and -
(minus) symbol.
Suffix filenames with the .rst
extension, so GitHub can render them.
Whitespaces¶
Blank lines¶
Two blank lines before overlined sections, i.e. before H1 and H2. One blank line before other sections. See Headings for an example.
One blank line to separate directives.
Some text before.
.. note::
Some note.
Exception: directives can be written without blank lines if they are only one line long.
.. note:: A short note.
Line length¶
Technically, there’s no limitation. But if possible, limit all lines to a maximum of 120 characters.
Headings¶
Please stick to this order of heading adornments:
=
with overline for document title:============== Document title ==============
=
for chapters:Chapters ========
-
for sections:Section -------
~
for subsections:Subsection ~~~~~~~~~~
If you need more than heading level 4 (i.e. H5 or H6), then you should consider creating a new document.
There should be only one H1 in a document.
Note
See also Sphinx’s documentation about sections [3].
Code blocks and text boxes¶
Use the code-block
directive and specify the programming language. As
an example:
.. code-block:: python
import this
Text boxes:
.. note::
Note (blue box). possible values: attention, caution, danger, error, hint, important, note, tip, warning, admonition.
Every type has its own color.
will look like:
Note
Note (blue box). possible values: attention, caution, danger, error, hint, important, note, tip, warning, admonition. Every type has its own color.
Links and references¶
Use links and references footnotes with the target-notes
directive.
As an example:
=============
Some document
=============
Link without Reference: `Example <http://www.example.com>`__
Some text which includes links to `Example website`_ and many other links.
`Example website`_ can be referenced multiple times.
(... document content...)
And at the end of the document...
References
----------
.. target-notes::
.. _`Example website`: http://www.example.com/
Tables¶
Table as CSV
.. csv-table:: Title of CSV table
:header: "Column 1", "Column 2", "Column 3"
"Sample Row 1", Cell, Cell
"Sample Row 2", Cell, "Cell with multiple Words"
You can skip quotes, of cell content contains only a single word
Table as flat list
.. list-table:: Title of table as flat list
:header-rows: 1
* - Column 1
- Column 2
- Column 3
* - Row 1
- Cell
- Cell
* - Row 2
- Cell
- Cell
:header-rows:
defines the number of header rows. Skip this line, if you do not need a header.
Diagrams¶
.. graphviz::
digraph foo {
"bar" -> "baz";
}
Troubleshooting¶
Why is my document not linked within the table of contents?
- put the filename into index.rst. Omit the
.rst
extension. - The document requires at least one section. Section names are the label that are used for the table of content.
After committing, the documentation will not update
- The build process of the documentation takes round about 1-2 minutes.
- You can check the status here: Builds
- Check the status if the build fails
Documentation is updating, but some content is missing or malformed
- There might be some parsing errors or warnings.
Go to Builds and click on
Raw view
. Check the build output for warnings and fix them.