doc/man: Add manpage documenting system startup

diff --git a/doc/man/startup.10 b/doc/man/startup.10
new file mode 100644 (file)
index 0000000..b58aaed
--- /dev/null
+++ b/doc/man/startup.10
@@ -0,0 +1,88 @@
+.TH STARTUP 10 2020-08-27 "0.1" "The Corax Programming Environment"
+
+.SH INTRODUCTION
+The initalization of the Corax operating system takes place in four separate steps. The first and
+last steps are identical to their counterparts in more traditional operating systems. The second
+and third steps are somewhat Corax-specific and will be discussed in more detail in the following
+chapters.
+
+
+.SH THE BOOT PROCESS
+
+The first of the initialization steps in Corax is no different from most other systems. The Corax
+kernel image is loaded by the multiboot-compatible bootloader (typically GRUB), the processor is
+placed in protected mode, and control is transferred to the kernel.
+
+
+.SH KERNEL INITIALIZATION
+
+The kernel initialization starts when the control is transferred from the bootloader code to the
+.IR corax()
+function defined in
+.IR kernel/core/main.c .
+The first thing that the kernel does is to perform architecture-specific initialization. On Intel
+architectures (the only architectures supported at the time of writing) this means that the Global
+Descriptor Table, the Interrupt Descriptor Table, the memory management unit, and the interrupt
+controller (either the i8259 or the APIC, depending on the kernel configuration) will be
+initialized. Architecture-specific initalization is described in more detail in the manpage of the
+respective architecture.
+
+.P
+Once the architecture-specific initialization has finished, the scheduler will be initialized.
+This step is discussed in detail in the manpage of the scheduling algorithm that is set in the
+kernel configuration.
+
+.P
+As soon as the scheduler initialization is complete, the kernel will spawn two processes. The
+first one, the
+.IR _idle
+process, is the process that is executed by processors that don't have anything else to execute.
+In its current implementation, this process does nothing but put the executing processor into a
+low-power state. The second, the
+.IR _init
+process, is responsible for the execution of the ELF binaries that are included in the initial
+filesystem. In its current implementation, it will fork and execute each of the ELF binaries in
+the initfs in the order that they have been declared in, and then put itself to sleep.
+
+
+.SH SYSTEM PROCESS AND DRIVER INITIALIZATION
+
+The processes that have been instantiated from the initfs will then initialize the rest of the
+system that is necessary to be able to execute
+.BR /sbin/init .
+The first system process that will necessarily initiate at this point is the IO process. This is
+because the IO process implements the internals of IO related calls such as
+.IR open() ,
+.IR read() ,
+and
+.IR write() .
+Without the IO process, most calls to standard C library functions would simply not work. The IO
+process also implements the file system, which will be necessary to add device nodes to the
+system. Once the IO process has started, the file system is available and device drivers can be
+started. However, at the time of writing, no device drivers have been implemented yet. This
+section will be updated once the implementation of the rest of the startup process has been
+completed.
+
+
+.SH USER-SPACE INITIALIZATION
+
+This step is again similar to most other UNIX-like operating systems. The init process that is
+included in the initfs (typically it is one of the last processes instantiated through the initial
+filesystem) will read the binary that is located at
+.B /sbin/init
+in the virtual file system and execute it. All further steps depend on the init process that is
+installed on the system.
+
+
+.SH SEE ALSO
+.ad l
+.nh
+.BR kernel (10)
+.BR initfs (10)
+.BR ia32 (10)
+.BR scheduler (10)
+.BR sched_lazy (10)
+.BR init (8)
+
+.SH AUTHOR
+Matthias Kruk