kernel/.wiki/Kernel-documentation.md

Kernel Documentation

The kernel is booted using the limine boot protocol.

Directory structure

• boot - all stuff related to booting / jumping into the kernel
• drivers - everything from the graphics driver, to the FS drivers
• mm - memory management stuff like page frames and page maps
• platform - universal API to the platform specific code in the subdirs
• proc - all the process/thread related stuff like the scheduler
• utils - utilities like type definitions, math functions, high-level memory management

---

General concepts

Kernel initialization

The single parts of the kernel are initialized in the following order:

• Page Frame Manager
• Interrupts
  • [IDT] Interrupt Descriptor Table
  • [PIC] Programmable Interrupt Controller
• Paging
• Kernel Heap
• Graphics Renderer
• Scheduler

Interrupt handling

OSDev Wiki: Interrupts

Unfortunatly the x86 architecture doesn't provide a method to get the ID of the current interrupt. To solve this problem, there is a simple assembly function for every interrupt used by NoxOS. This function pushes its ID on the stack. After that it calls a common Interrupt handler, this handler will generate the current cpu_state_T and call the C interrupt handler implementation. The C implementation returns a cpu_state_T that will then be loaded.

Paging

OSDev Wiki: Paging

There is a difference between Virtual Memory Spaces and the Physical Memory Space. The Physical memory space is how the data lies directly in the RAM.

Virtual memory spaces are a bit more tricky. To understand them, we have to understand first, that the physical memory space is divided into so-called pages / page frames. These pages have a size of 4KB.

A virtual memory space is a table of page mappings. Per default there are no pages mapped to such a table. When the OS maps a page to a page table, it says: "This page is now accessible from this virtual space, at this address". When the Computer is in paging mode, only mapped pages are accessible. Now every Process gets its own page table and tada: we have successfully isolated the processes from each other, because every process can only access the data that it needs to access.

Panic screen

When a fatal / not recoverable error occurs, the kernel panics. It logs panic information and then halts forever. Such a panic log can look like the following one:

[  Error  ] !=====[ KERNEL PANIC ]=====!
Error Message: Division Error
Interrupt ID: 0x00
Error Code: 0b00000000000000000000000000000000

Paging Info:
    Page Map: 0x000000000FAE9000

CPU Flags:
    Parity
    Sign
    Interrupt Enable

CPU Registers:
    RIP: 0xFFFFFFFF80002745   RAX: 0x0000000000000001   RBX: 0x0000000000000000
    RCX: 0x0000000000000000   RDX: 0x0000000000000000   RSI: 0x000000000001F980
    RDI: 0x00001000005DF7A0   RBP: 0xFFFF80000FAF9F40   RSP: 0xFFFF80000FAF9F30

Call Stack:
    0xFFFFFFFF80000000+033F  ->  _start
    0xFFFFFFFF8000274D+0078  ->  kmain
    0xFFFFFFFF80002732+0013  ->  test
[ Warning ] !=====[ HALTING SYSTEM ]=====!

but what does it say?

In most cases, a panic occurs while handling an interrupt. If this is the case, we will have the state of the cpu while it was interrupted. This cpu state provides us very much information.

Interrup ID tells us, which interrupt caused the panic. In this case the ID is 0x0E, a Page Fault Exception.

Error Code is a binary representation of the 32 least significant bits of the error code pushed by some interrupts. If an interrupt pushes no error code, this will be just zeros. In our example the code tells us, that the error happened because of a write attempt to a not present page.

Error Message tells us, what happened.

Paging Info contains all information about paging. At the moment, this is just the physical address of the loaded page map.

CPU Flags contains information about which bits are set in the CPU status register. If this block doesn't appear, there are no bits set.

CPU Registers contains the data, in the main cpu registers. This is probably the most interesting block, because you get very detailed information out of here, if you know what each of these registers does in the cpu.

Call Stack lists the current function call chain, starting from the least recent call. The big hex number is the base of the function and the small hex number is the offset, where the next function was called. After the -> follows the name of the function.

Panic without interrupt

If the panic wasn't caused by an interrupt, it has no cpu_state, and because of that it has no detailed info about the execution state. In this rare case, you will get the following message:

No detailed Information available (cpu_state null reference)

The Error Message could still be helpful, but good luck finding that bug.

Memory Layout

NoxOS uses a higher half kernel, this means, that the kernels executable is mapped above 0x800000000000. All kernel and bootloader resources are also mapped in the higher half. This leaves the lower half for process specific mappings

Process Memory Isolation

Every process has its own virtual memory space (page map). This space contains always the following mappings (except in the kernels main process):

Name	Address	Permissions
Process executable	0x0000010000000000	as defined in ELF
Thread data (stack, etc.)	0x0000010100000000	Read/Write
Kernel executable	0xFFFFFFFF80000000	Read/Exec
Kernel Heap	0xFFFFFFFFF0000000	Read/Write

Thread data

Every thread has a Thread Data region, that contains thread specific stuff like a stack.

The first threads Thread Data region is at 0x0000010100000000, the seconds at 0x0000010200000000 and so on.

In this setup, every Thread Data region has a virtual size of 4GB.

Context switching

Switching between threads is a bit tricky, when the threads stacks are in different page maps. When performing a context switch, the memory region 0x0000010000000000 <--> 0x0000020000000000 is dirty mapped (the PML4 entries are copied) from the next processes' into the kernels page map. This region contains all Thread Data regions and the processes' executable mappings. Due to this dirty mapping the next interrupt handler can always access the current processes' or threads' data.

Syscalls

NoxOS will use interrupt based syscalls. To perform a syscall, write its ID into the rax register and call interrupt 0x80.

Example:

mov rax, 0x0000
int 0x80

The syscalls are grouped into groups and their ID consists of a group-ID (first two digits) and a syscall-ID (last two digits).

Syscall groups

• Misc - 0x00
• File - 0x01
• Proc - 0x02
• Kernel - 0xFF

Misc Syscalls - 0x00--

File Syscalls - 0x01--

Proc Syscalls - 0x02--

Kernel Syscalls - 0xFF--

The kernel syscalls can only be called by the kernel process and its childs. All other processes, won't be able to use this functions.

ID	Name	Description
0xFF00	scheduler_start	Initializes the Kernels main thread from the current cpu_state. This is used to start multithreading

Format strings

Format strings are strings that are formatted at runtime. They are created by defining a pattern, like the following one:

"Name: %s / ID: %d"

And giving it arguments at runtime, let's use the following ones for our example:

"Main Process", 42

This would format to that:

Name: Main Process / ID: 42

As you see, %s and %d are placeholders. Placeholders consist of a % sign followed by one or two letters. When formatting the string, the placeholders are replaced with the arguments. The first placeholder is replaced with the first argument, the second with the second and so on.

Numeric specifier

If you put a . followed by a number right after the percentage sign of a placeholder, you will set the Numeric specifier. If the . is followed by an astrix, the numeric specifier is passed as its own argument. Some placeholders use this numeric specifier to configure their output. If you don't set a numeric specifier, the placeholders, that would use it will use a default value instead.

Arguments

Make sure, that the arguments you pass, are really of the right type. If you e.g. pass a negative value of type int32_t like -1312, the formatter will have problems with that, because the int32_t representation of that number is as an int64_t a positive number.

Placeholders

%s - string

Argument Type	string_t
Numeric Specifier Use	Specifies the maximum length the string can have
Numeric Specifier Default	String Length
Description	Inserts a string

%c - char

Argument Type	char
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a character

%u - unsigned decimal

Argument Type	uint64_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts an unsigned integer

%d - signed decimal

Argument Type	int64_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a signed integer

%x - hexadecimal

Argument Type	uint64_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a 64 bit hex integer

variants

%xb - byte hexadecimal

Argument Type	uint8_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a 8 bit hex integer

%xw - word hexadecimal

Argument Type	uint16_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a 16 bit hex integer

%xd - dword hexadecimal

Argument Type	uint32_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a 32 bit hex integer

%xq - qword hexadecimal

This variant is the %x standard.

Argument Type	uint64_t
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts a 64 bit hex integer

%? - boolean

Argument Type	bool
Numeric Specifier Use	None
Numeric Specifier Default	None
Description	Inserts true or false

%b - binary

Argument Type	uint64_t
Numeric Specifier Use	The amount of bits that are shown
Numeric Specifier Default	64
Description	Inserts the binary string of the given number

%% - mask

This is not a really a placeholder, but you can use this to mask the % sign, so it will be interpreted as just a % instead of a placeholder.

Executables

NoxOS uses the ELF executable format, which is the linux/unix standard. Further information can be found in the Syscalls and drivers/elf/elf.h documentation.

---

DISCLAIMER: Only the headers are documented, because documenting the whole code itself would be very time intensive and the headers as 'public' API are the most important to document.

boot

boot_info.h

The goal of this file is to provide a universal struct of information needed by the kernel at start time. At the moment this information is very limine specific, but the goal is to make it easy to add support for other boot protocols.

boot_info_T - struct

Name	Description
framebuffer	struct with information about the graphics buffer
terminal	bootloader terminal / graphical log
memory_map	information about the memory layout / regions
kernel_file	The unparsed kernel ELF file
rsdp	Root System Description Pointer

limine.h

This header provides the API to "communicate" with the limine bootloader. More information can be found on the limine project's GitHub.

drivers

elf/elf.h

elf_executable_T - struct

This struct holds the parsed data of an ELF executable.

Name	Type	Description
header	elf_header_T	The header of the elf file
num_symbols	uint64_t	The size of symbols
symbols	symbol_T*	An array containing all symbols of the elf file
num_mappings	uint64_t	The size of mappings
mappings	elf_mapping_T*	An array containing the mappings needed to load the elf file
string_table	void*	A copy of the elf files .strtab section, all strings are referenced here to have them available even if the elf file is closed

elf_executable_temp_T - struct

This struct is used while generating an elf_executable_T. It holds parse-time information about the elf file.

Name	Type	Description
executable	elf_executable_T*	A pointer to the final elf_executable_T
symbol_table	elf_section_T*	A pointer to .symtab in buffer
section_header_string_table	elf_section_T*	A pointer to .shstrtab in buffer
buffer	uint8_t*	The buffer where the executable is loaded from

elf_executable_create(buffer) - function (elf_executable_T*)

Generates an elf_executable_T from an elf file loaded to buffer and returns a pointer to it.

elf_executable_destruct(executable) - function (void)

Frees all memory allocated for executable.

elf/header.h

The enums in this header describe the possible values that a field of the elf header can have.

elf_target_architecture_E - enum

Field in header: identity[4]

elf_endianness_E - enum

Field in header: identity[5]

elf_sysabi_E - enum

Field in header: identity[7]

elf_object_type_E - enum

Field in header: type

elf_instruction_set_E - enum

Field in header: isa

elf_header_T - struct

Name	Type	Description
identity	uint8_t[16]	Information like the used endian and the SysABI is stored in here
type	uint16_t	The type of the elf file -> elf_object_type_E
isa	uint16_t	The used instruction set -> elf_instruction_set_E
version	uint32_t	ELF version
address_entry_point	uint64_t	The start point for program execution
offset_program_header	uint64_t	The position of the program header array in the file
offset_section_header	uint64_t	The position of the section header array in the file
flags	uint32_t	Architecture dependent, can be ignored
len_header	uint16_t	The size of this header
len_program_header_entry	uint16_t	The size of one program header
num_program_header_entries	uint16_t	The amount of program headers
len_section_header_entry	uint16_t	The size of one section header
num_section_header_entries	uint16_t	The amount of section headers
string_section_index	uint16_t	The section header index of the .shstrtab section

g_elf_target_architecture_strings - global variable

An array of strings matching elf_target_architecture_E.

g_elf_endianness_strings - global variable

An array of strings matching elf_endianess_E.

g_elf_sysabi_strings - global variable

An array of strings matching elf_sysabi_E.

g_elf_object_type_strings - global variable

An array of strings matching elf_object_type_E.

g_elf_instruction_set_strings - global variable

An array of strings matching elf_instruction_set_E.

elf_init_kernel_exec(boot_info) - function (void) [Will be replaced in near future]

Loads the kernel elf into g_kernel_executable.

g_kernel_executable - global variable [Will be replaced in near future]

Holds the parsed kernel executable.

This will be removed, when processes are implemented, because then this can be accessed via the kernel process control struct.

elf/mapping.h

elf_mapping_T - struct

A mapping describes an area of memory, that should be copied from the elf file into the RAM and how/where it should be mapped.

Name	Type	Description
offset_file	uint64_t	The mappings' start in the elf file
offset_virtual	uint64_t	The mappings' start in memory
length_file	uint64_t	The mappings' size in the elf file
length_virtual	uint64_t	The mappings' size in memory, if this is bigger than length_file the remaining space will be filled with zeros

elf_mappings_apply(mappings, num_mappings, buffer, base, page_map) - function (void)

Maps all mappings into page_map and copies the related data from buffer (elf file) to the mapped memory. base specifies where the mappings should start in the virtual address space.

elf/section.h

elf_section_type_E - enum

• Null - These sections can be ignored
• Program Data - These link to segments, if I remember right
• Symbol Table - Here are all the executables' symbols stored
• String Table - Here are all strings stored
• RelocationA - Contains relocation information
• Hash - Symbol Table hash table
• Dynamic Link - This provides information for the dynamic linker
• Note - notes that were created by the compiler / toolchain
• Nobits - Nulled data like .bss

elf_section_T - struct

Name	Type	Description
name_offset	uint32_t	The offset of the sections name in .shstrtab
type	uint32_t	The type of the section -> elf_section_type_E
flags	uint64_t	Sections attribute flags
virtual_address	uint64_t	The address where the section should be mapped to (if it's not 0)
offset	uint64_t	The sections offset in the file
length	uint64_t	The size of the section
link	uint32_t	Type specific link to another section
info	uint32_t	Type specific information
alignment	uint64_t	If the section is aligned, this value specifies the alignment
entry_size	uint64_t	The size of the sections entries

g_elf_section_type_strings - global variable

An array of strings matching elf_section_type_E.

elf/segment.h

elf_segment_type_E - enum

• Null - Unused segment
• Load - Segment that should be included into mappings
• Dynamic - Segments of this type contain dynamic linking information
• Interpreter - This holds a path to an interpreter
• Note - These segments hold notes by the compiler / toolchain
• Program Header Table - This points to the table that is holding the segment headers
• TLS - This holds a Thread Local Storage template

elf_segment_T - struct

Name	Type	Description
type	uint32_t	The segments type -> elf_segment_type_E
flags	uint32_t	The segments flags (Read / Write / Execute)
offset	uint64_t	The segments position in the elf file
address_virtual	uint64_t	Where the segment should be mapped in the virtual address space
address_physical	uint64_t	Not used in the System V ABI
length_file	uint64_t	The segments size in the file
length_memory	uint64_t	The size of the area that should be mapped for the segment
align	uint64_t	The segments alignment (has to be a power of 2)

g_elf_segment_type_strings - global variable

An array of strings matching elf_segment_type_E.

elf/symbol.h

ELF_SYMBOL_TYPE(info) - macro

Extracts the elf_symbol_type_E from the symbols info value.

elf_symbol_type_E - enum

• None - Unspecified type
• Object - Data objects like variables, arrays, etc.
• Func - Function
• Section - Associated section
• File - The path to the source file associated with the object
• Common - Uninitialized common blocks
• TLS - Thread Local Storage

elf_symbol_T - struct

Name	Type	Description
name_offset	The offset of the symbols name in .strtab
info	Information about the symbol (type, bind)
other	Information about the symbol (visibility)
related_section_index	The index of the symbols related section
value	Value, in most cases this is an address
length	The size of the symbol (e.g. num bytes if the symbol is an array)

fs/ramfs.h

Warning: This is a filesystem specific driver, by this it should only be accessed by the vfs.

The ramfs (ram-filesystem) is not a filesystem in the common sense. All data that is stored in ramfs is stored in the virtual file systems cache. This means that all data in ramfs is temporary and erased after a reboot.

ramfs_file_delete(node) - function (void)

Frees the files cache space. This won't delete the node in the vfs.

ramfs_file_write(node, size, buffer_in) - function (void)

If this file has some cache space allocated, it will be freed. Then there will be some cache space (size bytes) allocated and size bytes from buffer_in copied into the cache.

This use of the vfs cache isn't a great solution and should be reworked.

ramfs_file_read(node, size, buffer_out) - function (void)

Copies size bytes from the files' cache to buffer_out. This won't copy more bytes than the allocated cache space is big.

fs/ustar.h

The USTAR 'filesystem' is probably more common known as tar-archive. It is a really simple concept, where a file consists of a header block followed by data blocks. These blocks are aligned at 512 bytes.

OSDev Wiki: USTAR

ustar_type_E - enum

The types an entry can have:

• File
• Hardlink
• Symlink
• Char Device
• Block Device
• Directory
• Pipe

ustar_header_T - struct [packed / 512B aligned]

Name	Type	Description
name	char[100]	The name of the entry
mode	uint64_t	file mode (permissions, etc)
owner_id	uint64_t	The owners ID
group_id	uint64_t	The groups ID
size	char[12]	The size of the entry, represented as a string of an octal number (dafuq)
last_modification	char[12]	The unix-timestamp, when the entry was modified the last time
checksum	uint64_t	I think this is a weird checksum of the header
type	uint8_t	The type (ustar_type_E) of the entry, represented as ascii numbers (dafuq)
name_linked	char[100]	The path to the linked entry, if this is a link-entry
indicator	char[6]	This needs to be ustar
version	uint16_t	The version of the tar command, that created the archive
owner_user_name	char[32]	The name of the file owner
owner_group_name	char[32]	The name of the file group
device_major	uint64_t	The devices major number
device_minor	uint64_t	The devices minor number
name_prefix	char[155]	If this is not null, this acts as a prefix for name

fs/vfs.h

VFS stands for Virtual File System and is an abstraction, that kinda merges all mounted filesystems into one. It provides a general API for dealing with files, and handles all fs specific stuff in the background. This VFS is node based, meaning, that every file, directory, mount point, etc is represented as a node in memory. Nodes have a type and a fs. Nodes can have children and next and previous nodes.

Example node relations:

+-----------+
| Root Node | <---------+
+-----------+           |
    |                   |
[Childs]            [Parent]
    |     +-------------+---------------+
    v    /              |                \
+-------+            +-------+            +-------+
| Child | --[Next]-> | Child | --[Next]-> | Child |
|   1   | <-[Prev]-- |   2   | <-[Prev]-- |   3   |  ...
+-------+            +-------+            +-------+
    |
[Childs]
    |     
    v   
   ...

If a node is accessed it is linked as the first node in the childs order, to make name resolving process faster.

VFS_MAX_NAME_LENGTH - macro

The maximum length of a nodes name. Bigger names will be cut of at the end.

fs_type_E - enum

This enum specifies all supported filesystems:

• RAMFS - A filesystem, that is bound very tight to the vfs and is completely in the RAM.

vfs_node_type_E - enum

This enum specifies all types a node can have:

• Directory - A directory can contain other nodes
• File - A file can hold data
• Mount Point - A mount point is like a directory, but in the vfs backend this resolves to the root of a filesystem
• Block Device - Neither used nor implemented yet

fs_T - struct

This struct specifies a filesystem instance.

Name	Type	Description
type	fs_type_E	The type of the filesystem
root_node	vfs_node_T*	A pointer to the vfs node of the filesystems root directory

vfs_node_cache_T - struct

The current node caching system is just a small placeholder that will be reworked soon.

Name	Type	Description
buffer	void*	The actual buffer, where data is cached
buffer_size	uint64_t	The size of buffer
reclaimable	bool	Not used atm, but could be important after refactor
node	vfs_node_T*	The node, that the cache belongs to

vfs_node_T - struct

Name	Type	Description
name	char[]	The name of the node
type	vfs_node_type_E	The type of the node
cache	vfs_node_cache_T	The nodes cache segment
size	uint64_t	The nodes size
specific	void*	General purpose pointer (details below)
filesystem	fs_T*	The filesystem this node actually lies in
prev	vfs_node_T*	The previous node
next	vfs_node_T*	The next node
parent	vfs_node_T*	The parent node (has to be dir or mount point)
childs	vfs_node_T*	The first child node

specific

The usage of this value is specific to th nodes type:

• Directories: NULL
• Files: NULL
• Mount points: a pointer to the mounted filesystem.
• Block devices: NULL

g_root_fs - global variable

The systems root filesystem. Every node resolve will start at this filesystem.

vfs_node_cache_create(node, size) - function (vfs_node_cache_T*)

Allocates a size bytes big cache segment for node.

vfs_node_cache_destruct(node_cache) - function (void)

Frees node_cache and its buffer.

vfs_node_create(parent, name, type, specific) - function (vfs_node_T*)

Allocates a node with the given parameters. The nodes fs value is inherited from parent, or from parent's specific value if parent is a mount point.

vfs_node_destruct(node) - function (void)

Recursively destructs node and all it's children.

vfs_node_dump_info(node, indent) - function (void)

Prints the complete directory structure starting at node. indent is used for the recursive calls and should be set to 0.

vfs_node_resolve_child(node, child_name) - function (vfs_node_T*)

Searches node for a child named child_name. Returns the first matching child or NULL if no matching child was found.

vfs_file_create(filesystem, path) - function (vfs_node_T*)

Creates a file at path in filesystem and returns a pointer to it. The directory in path needs to exist and the filename needs to not exist.

vfs_file_delete(file) - function (void)

Deletes file.

vfs_file_write(file, position, size, buffer_in) - function (void)

Writes size bytes from buffer_in at position into file.

Warning: the current ramfs implementation will ignore position!

vfs_file_read(file, position, size, buffer_out) - function (void)

Reads size bytes from file at position into buffer_out.

Warning: the current ramfs implementation will ignore position!

vfs_directory_create(filesystem, path) - function (vfs_node_T*)

Creates a directory at path in filesystem and returns a pointer to it. The directory in path needs to exist and the name of the new directory (after the last /) needs to not exist.

vfs_directory_delete(directory) - function (void) [not implemented yet]

Deletes a directory.

vfs_init(boot_info) - function (void)

Initializes the VFS. In future this will also unpack the initial ramdisk into the temp directory.

vfs_resolve_path(filesystem, path) - function (vfs_node_T*)

Returns the node at path or NULL if path is invalid.

vfs_unpack_archive_ustar(filesystem, archive) - function (void)

This will unpack a USTAR-archive (archive) at filesystem's root.

graphics/color.h

color_palette_E - enum

Indexes for g_color_palette

• Grey Dark
• Pink
• Signal Green
• Orange
• Blue
• Purple
• Green
• Grey Light
• Red

color_argb_T - struct

Name	Type	Description
alpha	uint8_t	Transparency value of the color
red	uint8_t	Red value of the color
green	uint8_t	Green value of the color
blue	uint8_t	Blue value of the color

color_argb_blend_alpha(background, foreground) - function (color_argb_T)

Blends background and foreground with the alpha value of foreground.

g_color_palette - global variable

An array of standard colors. This array is indexed using color_palette_E.

graphics/font.h

font_T - struct

Name	Type	Description
width	uint8_t	The width of each char (in pixels)
height	uint8_t	The height of each char (in pixels)
glyph_size	uint8_t	The amount of bytes a char takes in the buffer
buffer	uint8_t*	The buffer, where the char bitmaps lay

g_font - global variable

A global usable 8x8 font.

graphics/framebuffer.h

framebuffer_T - struct

Name	Type	Description
address	void*	The address of the framebuffer
width	uint64_t	The pixel width of the framebuffer
height	uint64_t	The pixel height of the framebuffer
pitch	uint64_t	The number of bytes in each row
bits_per_pixel	uint16_t	The amount of bits a pixel consumes in the buffer
bytes_per_pixel	uint8_t	The amount of bytes a pixel consumes in the buffer
shift_red	uint8_t	How many bits the red value is shifted in a pixel
shift_green	uint8_t	How many bits the green value is shifted in a pixel
shift_blue	uint8_t	How many bits the blue value is shifted in a pixel

graphics/renderer.h

graphics_buffer_layer_E - enum

• Standard - The layer, where almost everything should be on
• Overlay - This layer should be used for stuff like a mouse cursor, that should always be visible

graphics_buffer_T - struct

Name	Type	Description
buffer	color_argb_T*	The buffer, where all the pixels are stored
width	uint32_t	The width of the buffer
height	uint32_t	The height of the buffer
pos_x	uint32_t	The buffers x offset (from the top-left corner) in the renderers main buffer
pos_y	uint32_t	The buffers y offset (from the top-left corner) in the renderers main buffer
blocked	bool	Thread safety block variable
render	bool	Controls, if the buffer will be rendered or not
layer	graphics_buffer_layer_E	The layer, on which the buffer will be rendered
prev	graphics_buffer_T*	The previous buffer in the rendering queue
next	graphics_buffer_T*	The next buffer in the rendering queue

graphics_renderer_T - struct

Name	Type	Description
framebuffer	framebuffer_T	The systems framebuffer (requested from bootloader)
back_buffer	uint32_t*	The buffer, where the final image is calculated, before sending it to the framebuffer
buffer_size	uint64_t	The size of back_buffer (in bytes)
graphics_buffer_layers	graphics_buffer_T**	List of pointers to the first graphics_buffer of every layer
font	font_T	The font, all graphics buffers use to draw chars (could be moved to graphics_buffer_T)
initialized	bool	Indicates whether the renderer is initialized or not
blocked	bool	Blocking variable that is used for thread safety in graphics_renderer_update

graphics_buffer_request(pos_x, pos_y, width, height, layer) - function (graphics_buffer_T*)

Allocates a graphics buffer and pushes it on top of the rendering queue of layer.

graphics_buffer_show(graphics_buffer) - function (void)

Enables rendering for this buffer. Every created buffer will be rendered by default.

graphics_buffer_hide(graphics_buffer) - function (void)

Disables rendering for this buffer.

graphics_buffer_destruct(graphics_buffer) - function (void)

Removes graphics_buffer from the rendering queue and frees its memory allocations.

graphics_buffer_shift_up(graphics_buffer, shift) - function (void)

Shifts graphics_buffer's content shift rows up.

graphics_buffer_set_pixel(graphics_buffer, x, y, color) - function (void)

Sets a pixel with the given color at position(x | y) in graphics_buffer. x and y are graphics buffer relative.

graphics_buffer_get_pixel(graphics_buffer, x, y) - function (color_argb_T)

Returns the color of the pixel at position(x | y) in graphics_buffer.

graphics_buffer_draw_char(graphics_buffer, x, y, color, chr) - function (void)

Draws a character (chr) at position(x | y) in graphics_buffer. The position is the top-left corner of the char.

graphics_buffer_draw_string(graphics_buffer, x, y, color, string) - function (position_T)

Draws string at position(x | y) in graphics_buffer. The position is the top-left corner of the string. Returns the position after the last char of the string.

graphics_renderer_init(boot_info) - function (void)

Initializes the global graphics renderer. Needs a pointer to boot_info to extract information about the framebuffer.

graphics_renderer_update() - function (void)

Updates the renderers back_buffer and swaps it into the framebuffer. To update the back_buffer, it iterates over the rendering queue and copies every buffer to the back_buffer. If there are overlapping graphics_buffers, it alpha-blends them.

graphics_renderer_get_top_buffer(layer) - function (graphics_buffer_T*)

Returns a pointer to the graphics_buffer, that is on top of the rendering queue of layer.

graphics_renderer_get_width() - function (uint32_t)

Returns the width of the framebuffer.

graphics_renderer_get_height() - function (uint32_t)

Returns the height of the framebuffer.

time/pit.h

PIT_CHANNEL_0_PORT - macro

The IO port, where channel 0 of the PIT (which is capable of firing IRQs) can be configured.

PIT_DIVISOR - macro

The standard divisor nox_os loads into channel 0 of the PIT. 32768 fires an interrupt every ~27ms, what is perfect for preemptive multithreading.

pit_set_divisor(divisor) - function (void)

Loads divisor into channel 0 of the PIT. If divisor is smaller than 100, it will be set to 100.

mm

region.h

The first 4 digits can be ignored, they are ignored by the MMU, but for clarity / readability reasons they are FFFF in the kernel space. See General Concepts / Memory Layout and General Concepts / Process Memory Isolation for more details.

Name	Start	Description
MEM_REGION_PROCESS	0x0000000000000000	This is the start of the process space
MEM_REGION_PROCESS_EXEC	0x0000010000000000	Every processes' executable will be mapped here
MEM_REGION_PROCESS_THREAD_BASE	0x0000010100000000	The start of the Thread Data regions
MEM_REGION_KERNEL	0xFFFF800000000000	This is the start of the kernel space
MEM_REGION_KERNEL_STACK_DUMMY	0xFFFFF00000000000	This area is used when preparing a threads' stack
MEM_REGION_KERNEL_HEAP	0xFFFFF80000000000	The kernels' heap begins here
MEM_REGION_KERNEL_THREAD_BASE	0xFFFFFF0000000000	The kernel processes' Thread Data regions
MEM_REGION_KERNELEXEC	0xFFFFFFFF80000000	The kernel executable is mapped here

MEM_REGION_THREAD_OFFSET - macro

This time the threads id specifies its offset in its processes' Thread Data region.

KERNEL_START_ADDRESS - macro

Returns the address of _kernel_start.

KERNEL_END_ADDRESS - macro

Returns the address of _kernel_end.

_kernel_start - global variable

This symbol is inserted by the linker at the beginning of the kernel. To access its value use the KERNEL_START_ADDRESS macro.

_kernel_end - global variable

This symbol is inserted by the linker at the end of the kernel. To access its value use the KERNEL_END_ADDRESS macro.

heap.h

heap_segment_T - struct

This is the header for each heap segment. It holds its status information and a pointer to the next and previous segments. It lies in memory, directly before the accessible buffer of the segment.

heap_T - struct

This struct describes a heap. The area between start and end is filled with heap segments.

heap_init(heap*, base) - function (void)

Initializes heap at base (virtual address). It will automatically map some page frames to that address.

heap_memory_allocate(heap*, size) - function (void)

Returns a pointer to a free usable memory location, that has at least the given size. It will return NULL and log an error, if the heap is corrupted. Because this function iterates over the complete heap to find a free segment, it is slow.

heap_memory_free(heap*, address) - function (void)

Frees a with heap_memory_allocate created heap segment, and makes it usable again. Does nothing, if the address doesn't point to a valid heap segment.

heap_dump_segments(heap*) - function (void)

Logs a complete list, of all heap segments. Useful, when debugging / testing the heap.

heap_destruct(heap*) - function (void)

Invalidates all segments of a heap, frees all used page frames and unmaps them.

memory_map.h

memory_map_get_total_memory_size(boot_info*) - function (uint64_t)

Calculates the total amount of memory available, by iterating over the memory map. The size is stored in a static variable, so no matter how often you call this function, the size will only be calculated once. It returns the total amount of memory in bytes.

page_frame.h

This header provides the functions for basic interactions with pages (in the physical memory space).

pframe_manager_init() - function (void)

Initializes the page frame manager, needs to be called once at kernel init.

pframe_reserve(address) - function (void) [Thread Safe]

Blocks a page, so it can't be requested or anything else. If the page is already blocked by anything else, e.g. by a request, it won't be reserved.

pframe_reserve_multi(address, n) - function (void) [Thread Safe]

Reserves the page at the given address, plus n pages after that page.

pframe_unreserve(address) - function (void) [Thread Safe]

Unreserves a reserved page and makes it accessible again.

pframe_unreserve_multi(address, n) - function (void) [Thread Safe]

Unreserves the page at the given address, plus n pages after that page.

pframe_request() - function (void*) [Thread Safe]

Returns the physical address of a page. This is kind of the low level version of malloc.

pframe_free(address) - function (void) [Thread Safe]

Needs a valid page address produced by pframe_request() as argument. Invalidates the address and frees it, so it can be requested again. This is kind of the low level version of free.

pframe_free_multi(address, n) - function (void) [Thread Safe]

Frees the page at the given address, plus n pages after that page.

page_map.h

VIRTUAL_ADDRESS_MAX - macro

The highest mappable virtual address. 4 level page maps have a maximum address space of 256TB.

page_map_flag_E - enum

• Present - This indicates if the entry is used or should be ignored. Automatically set when mapping a page.
• Read & Write - A mapped Page is always readable. This flag allows writing to that page.
• User Super - If set, user mode access to the page is allowed.
• Write Through - Enables Write Through Caching for this page.
• Cache Disabled - If this bit is set, the page won't be cached.
• Accessed - Set by the CPU, when this PDE or PTE was read. Won't be reset by the CPU.
• Dirty - Set when the page has been modified.
• Larger Pages - When this bit is set in a PDE or PTE, the entry points to a 1GB or 2MB page.
• Custom 1 - 3 - Not used in NoxOS.
• No Execute - When this bit is set, the CPU won't execute code that lies in that page.

page_map_T - struct [page aligned]

This struct contains 512 entries. These entries contain an address and flags. The addresses link like this:

• PML4 --> Page Directory or 1GB Page
• Page Directory --> Page Table or 2MB Page
• Page Table --> 4KB Page

A pointer to a page_map_T can be loaded into cr3 to load this pagemap.

page_map_create() - function (page_map_T*)

Allocates a page_map_T and returns a pointer to it.

page_map_fetch_current() - function (page_map_T*) [ASM implementation]

This function will return the page map, that is currently loaded. To achieve this, it just reads the cr3 value.

page_map_load(page_map*) - function (void) [ASM implementation]

Loads the given page map. To achieve this, it writes the cr3 value.

page_map_map_memory(page_map*, virtual_address, physical_address, flags) - function (void)

This maps physical_address to virtual_address in page_map. The flags will be applied to the page mapping / page table entry. It always applies the Present flag.

page_map_unmap_memory(page_map*, virtual_address) - function (void)

Removes a page mapping from the page_map. Page map structure intern pages won't be checked if they're still needed or not.

page_map_get_physical_address(page_map*, virtual_address) - function (void*)

Returns the physical address of the page, that is mapped to virtual_address.

page_map_destruct(page_map*) - function (void)

Clears a page map and frees all page map structure intern pages.

page_map_dump_info(page_map) - function (void)

Logs information about page_map, including a map of all mapped regions. A region is a block of continuously mapped pages.

page_map_entry_set_flags(entry, uint64_t flags) - function (void)

This will set the provided flags to a page map entry.

page_map_entry_get_flag(entry, page_map_flag_E flag) - function (bool)

Returns if the given flag is set in the page map entry, or not.

page_map_entry_set_address(entry, void* address) - function (void)

This will set the provided address to a page map entry.

page_map_entry_get_address(entry) - function (void*)

This will read and return the address set in the page map entry.

paging_init() - function (void)

Initializes paging. This reads the current page map set by the kernel and writes it to g_kernel_page_map.

g_kernel_page_map - global variable

The kernels page map. This page map is provided by the bootloader and read from cr3 at paging_init.

stack.h

stack_dump_call_info(rip, symbol) - function (void)

Logs information about a call. Give this function the rip of the call and the related symbol, to make it happy.

stack_trace_call_stack(rbp) - function (void)

Analyses the stack and recursively dumps information about all calls until it hits a call to _start.

platform

cpu.h

This header contains stuff directly related to the CPU.

OSDev Wiki: x86 CPU Registers

cpu_state_T - struct

• cr3 - Control register 3, holds the current page table
• rax - General purpose register
• rbx - General purpose register
• rcx - General purpose register
• rdx - General purpose register
• rsi - General purpose register
• rdi - General purpose register
• rbp - The Bottom of the current stack frame
• interrupt_id - The ID of the interrupt, that captured the cpu state
• error_code - Some exceptions such as the Page fault push more detailed information into here
• rip - The current instruction address
• crs - Segment selector of the associated IDT descriptor
• flags - The CPU's FLAGS register, a status bitmap
• rsp - The Top of the current stack frame
• ss - Not totally sure, what this does, but it has to do with security rings

This struct defines a complete CPU state, that can be saved and restored. It is saved when the CPU fires an interrupt and restored by the interrupt handler when it's finished. This allows multithreading and exception analysis.

cpu_flags_E - enum

• CPU_FLAG_CARRY
• CPU_FLAG_PARITY
• CPU_FLAG_AUXILIARY
• CPU_FLAG_ZERO
• CPU_FLAG_SIGN
• CPU_FLAG_TRAP
• CPU_FLAG_INTERRUPT_ENABLE
• CPU_FLAG_DIRECTION
• CPU_FLAG_OVERFLOW
• CPU_FLAG_IO_PRIVILEGE_0
• CPU_FLAG_IO_PRIVILEGE_1
• CPU_FLAG_NESTED_TASK
• CPU_FLAG_RESUME
• CPU_FLAG_VIRTUAL_8086
• CPU_FLAG_ALIGNMENT_CHECK
• CPU_FLAG_VIRTUAL_INTERRUPT
• CPU_FLAG_VIRTUAL_INTERRUPT_PENDING
• CPU_FLAG_CPUID

exceptions.h

OSDev Wiki: Exceptions

exception_type_E - enum

These are just the definitions of the CPU-exception interrupt IDs.

g_exception_type_strings - global variable

This array of strings defines the names of the Exceptions.

exception_handle(cpu_state) - function (cpu_state_T*)

If an interrupt is an exception, the interrupt handler will call this function to handle the exception. At the moment it will just panic, but in far future this could get expanded for page swapping, etc.

gdt.h

OSDev Wiki: Global Descriptor Table

gdt_selector_E - enum

• Null
• Kernel Code - Readable
• Kernel Data - Readable + Writable
• User Null
• User Code - Readable
• User Data - Readable + Writable

gdt_descriptor_T - struct [packed]

Name	Type	Description
size	uint16_t	The tables size in bytes (-1)
offset	uint64_t	The virtual address, where the table lies in memory

gdt_entry_T - struct [packed]

Name	Type	Description
limit0	uint16_t	Can be ignored in long mode
base0	uint16_t	Can be ignored in long mode
base1	uint8_t	Can be ignored in long mode
access	uint8_t	Specifies permissions (details in osdev wiki)
limit1_flags	uint8_t	The first 4 bits can be ignored and the last 4 specify flags
base2	uint8_t	Can be ignored in long mode

gdt_T - struct [packed / page aligned]

Name	Type	Description
null	gdt_entry_T	The entry for GDT_SELECTOR_NULL
kernel_code	gdt_entry_T	The entry for GDT_SELECTOR_KERNEL_CODE
kernel_data	gdt_entry_T	The entry for GDT_SELECTOR_KERNEL_DATA
user_null	gdt_entry_T	The entry for GDT_SELECTOR_USER_NULL
user_code	gdt_entry_T	The entry for GDT_SELECTOR_USER_CODE
user_data	gdt_entry_T	The entry for GDT_SELECTOR_USER_DATA

g_default_gdt - global variable

The systems GDT.

gdt_init - function (void)

Populates and loads g_default_gdt. This will also set all the data segment registers to 0x10 (Kernel Data) and cs to 0x08 (Kernel Code).

interrupts.h

This header contains all the stuff, needed to init and handle Interrupts.

idt_register_T - struct [packed]

This struct is very similar to the GDT descriptor. It holds the size and address of the Table, where the interrupt handlers are looked up.

idt_descriptor_entry_T - struct

This struct stores information about one interrupt handler. The osdev wiki explains this more detailed.

g_idt_register - global variable

The default IDT configuration loaded when the IDT gets initialized.

g_handling_interrupt - global variable

When the system isn't handling an interrupt this is set to 0. If this is greater than 0 the system is currently handling an interrupt,

idt_init() - function (void)

This function fills all the interrupt gates (handlers) into the IDT and loads it.

proc

The general processing structure is a bit more complex, so I've split the schematics into multiple parts.

Processes Schematic:

+----------------+
| Kernel Process | <----+
| [Threads]      |      |
+----------------+      |
         |           [Parent]
      [Childs]          |
         |     +--------+--------+
         v    /                   \
   +-----------+            +-----------+
   | Process 1 | --[Next]-> | Process 2 |
   | [Threads] | <-[Prev]-- | [Threads] | . . .
   +-----------+            +-----------+
         |                        |
      [Childs]                 [Childs]
         |                        |
         v                        v
       . . .                    . . .

Thread Schematics (processes view):

+---------+
| Process | <-------+
+---------+         |
     |          [Process]
 [Threads]          |
     |     +--------+--------+
     v    /                   \
+----------+                 +----------+
| Thread 1 | --[LocalNext]-> | Thread 2 |
|          | <-[LocalPrev]-- |          | . . .
+----------+                 +----------+

Thread schematics (schedulers view):

    [RunningThread]
           |
           v
      +----------+                  +----------+                  +----------+
+---> | Thread 1 | --[GlobalNext]-> | Thread 2 | --[GlobalNext]-> | Thread 3 | . . . ----+
| +-- |          | <-[GlobalPrev]-- |          | <-[GlobalPrev]-- |          | . . . <-+ |
| |   +----------+                  +----------+                  +----------+         | |
| |                                                                                    | |
| +------------------------------------[GlobalPrev]------------------------------------+ |
+--------------------------------------[GlobalNext]--------------------------------------+

thread.h

thread_T - struct

Name	Type	Description
state	cpu_state_T*	The last saved state of the thread ( -> context switching)
cpu_time	uint64_t	The amount of cpu time the thread had. (currently the amount of context switches the thread had)
stack	void*	The bottom of the threads stack
stack_size	uint32_t	The size of the threads stack (in bytes)
process	process_T*	The process, to which the thread belongs to
global_prev	thread_T*	The previous thread in the scheduling queue (should only be accessed by the scheduler!)
global_next	thread_T*	The next thread in the scheduling queue (should only be accessed by the scheduler!)
local_prev	thread_T*	The previous thread of process (should only be accessed by the scheduler!)
local_next	thread_T*	The next thread of process (should only be accessed by the scheduler!)
local_id	uint32_t	The threads id in its process

thread_spawn(function) - function (thread_T*)

Allocates a thread_T and registers it in the scheduler. The thread starts execution at function. The for the thread allocated stack has a size of 16 KB (4 Pages). The thread still needs to be started with a thread_start call. Returns a pointer to the created thread.

thread_spawn_from_state(state) - function (thread_T*)

Allocates a thread_T and registers it in the scheduler. The threads' cpu_state is copied from state. This won't allocate a stack for the stack. The thread still needs to be started with a thread_start call. Returns a pointer to the created thread. This function should be avoided.

thread_start(thread) - function (void)

Starts/unpauses thread.

thread_pause(thread) - function (void)

Pauses thread.

thread_kill(thread) - function (void)

Kills thread. The threads stack and thread_T structure will be freed.

process.h

MAX_THREADS_PER_PROCESS - macro

The maximum amount of threads a process can have. This limitation is just for the bitmap, the overall processing structure would be capable of processes with unlimited threads, in theory.

THREAD_ID_INVALID - macro

If process_get_thread_id returns this, the process can't spawn one more thread.

pid_t - typedef

A typedef for uint32_t, used for process identification. Such an identification number is also called pid.

processes_standard_E - enum

These are standard pids

• None - This pid is invalid, like NULL is an invalid pointer
• Kernel - The kernels' main process

process_T - struct

Name	Type	Description
name	char[128]	The processes' name
id	pid_t	The process-identification number
chunk	void*	A pointer to the chunk, where the process is stored in
chunk_id	uint32_t	The processes id inside of its chunk
page_map	page_map_T*	The processes page map.
executable	elf_executable_T*	The processes executable
num_threads	uint32_t	The amount of spawned threads, that belong to the process
threads	void*	A pointer to the processes' first thread
thread_ids	bitmap_T	This bitmap keeps track of the local thread ids the process has
parent	process_T*	The process, that spawned this process
childs	process_T*	A pointer to the processes' first child process
prev	process_T*	The previous process
next	process_T*	The next process

process_kernel_spawn(executable) - function (void)

Spawns the kernels' main process.

Warning: this should only be called once, when initializing the scheduler!

process_spawn(parent, name, executable, buffer) - function (pid_t)

Spawns a process named name as child of parent and returns its pid. The process gets its own page map with the mappings specified in executable. In order to apply these mappings, this function needs the buffer where the executable was loaded from.

process_get_thread_id(process) - function (int32_t)

Searches for a free thread id in the process. If it finds one it returns it, else it returns THREAD_ID_INVALID.

process_clear_thread_id(process, id) - function (void)

Frees the thread id and makes it request-able again.

process_kill_pid(pid) - function (void)

Resolves the pids process and performs process_kill on it.

process_kill(process) - function (void)

Kills process and all of its threads and child processes. This will also destruct the executable and page_map associated with process.

scheduler.h

scheduler_processes_chunk_T - struct

These chunks are a combination of static array and linked list. They store the process_T pointer for each valid pid_T.

Name	Type	Description
processes	process_T**	The array of process pointers
processes_bitmap	bitmap_T	If a bit in this bitmap is set, the processes entry with the same index is valid
num_free_pids	uint32_t	The amount of free slots in this chunk
prev	scheduler_processes_chunk_T*	The previous chunk
next	scheduler_processes_chunk_T*	The next chunk

scheduler_T - struct

Name	Type	Description
num_threads	uint32_t	Total amount of currently spawned threads
num_processes	uint32_t	Total amount of currently spawned processes
running_thread	thread_T*	A pointer to the currently running thread.
processes	scheduler_processes_chunk_T*	The first processes store chunk
blocked	bool	Set to true, while switching the context. Thread safety mechanism.
initialized	bool	Set to true, if the scheduler is initialized and started.

scheduler_init(boot_info) - function (void)

Initializes the scheduler and performs a scheduler_start kernel syscall. boot_info is needed in to spawn the kernels' main process. After this function, the whole kernel is in scheduling mode.

scheduler_start(state) - function (cpu_state_T*)

Creates and starts a thread from state. It returns the result of a context switch, I forgot, why I did it like that. This is basically the backend for the scheduler_start kernel syscall.

scheduler_is_initialized() - function (bool)

Returns if the scheduler is initialized (and running) or not.

scheduler_dump_info(process, indent) - function (void)

This recursively lists information(pid, name, threads) for all child processes of process. indent is used intern for the recursive calls and should be set to 0 initially.

scheduler_register_thread(thread) - function (thread_T*)

Registers thread in the scheduler.

scheduler_pause_thread(thread) - function (void)

Pauses thread, by removing it from the scheduling queue.

Potential Bug: if thread was the currently running thread, this could cause issues, because it's prev and next values are nulled.

scheduler_start_thread(thread) - function (void)

Starts thread, by linking it into the scheduling queue.

scheduler_kill_thread(thread) - function (void)

Pauses and unregisters thread.

scheduler_register_process(process) - function (pid_t)

Reqisters process and returns its pid.

scheduler_kill_process(process) - function (void)

Kills process and its threads and childs.

scheduler_get_process(pid) - function (process_T*)

Returns the process_T pointer that is associated with pid.

scheduler_get_current_thread() - function (thread_T*)

Returns a pointer to the currently running thread.

scheduler_get_current_process() - function (process_T*)

Returns a pointer to the currently running threads process.

scheduler_switch_context(state) - function (cpu_state_T*)

Saves state in the running threads state value and increments their cpu_time value. Then it sets the next thread as the running thread and returns its state. This needs to be called from an interrupt handler, for the returned state to be loaded.

utils

bitmap.h

Provides functionalities to create, destruct and work with bitmaps.

bitmap_T - struct

Name	Type	Description
size	uint32_t	The size of buffer (in bytes)
size_bits	uint32_t	The amount of storable bits
buffer	uint8_t*	The buffer, where the bits are stored

bitmap_init_from_buffer(buffer, size) - function (bitmap_T)

Creates a bitmap object from a given buffer and size

bitmap_init(size) - function (bitmap_T)

Allocates memory to hold a bitmap in the given size and returns a bitmap_T with that buffer and size.

bitmap_destruct(bitmap*) - function (void)

Frees the memory of the given bitmap created with bitmap_init.

bitmap_set(bitmap*, index, value) - function (bool)

Sets the bit at the given index in the given bitmap to the given boolean value. Returns false, if the index is out of the bitmaps size bounds. Returns true, if the operation was successful.

bitmap_get(bitmap*, index) - function (bool)

Returns the boolean value stored at the given index in the given bitmap. Always returns false, if the index is out of the bitmaps size bounds.

core.h

All the utils, which I didn't know how to name.

CORE_INTERRUPTABLE_HALT_WHILE(a) - macro

This halts until a is true. Used when working with blocking variables in e.g. thread safe functions. To avoid deadlocks, this macro won't halt, while the system is handling an interrupt.

CORE_HALT_WHILE(a) - macro

This halts until a is true. Used when working with blocking variables in e.g. thread safe functions.

Warning: When a function containing this macro is used while handling an interrupt, this could cause deadlocks, think about using CORE_INTERRUPTABLE_HALT_WHILE instead.

CORE_HALT_FOREVER - macro

This halts forever and warns about this in the log.

io.h

Provides basic Input/Output functionalities.

io_out_byte(port, data) - function (void)

Writes one byte of data to port. This is a wrapper around the assembly outb instruction.

io_in_byte(port) - function (uint8_t)

Reads one byte from port and returns it. This is a wrapper around the assembly inb instruction.

io_wait() - function (void)

Waits one IO cycle. Should be used to give the devices enough time to respond.

logger.h

Functionalities to write logs to QEMU's serial port.

log_level_E - enum

• None - Logs just the message without a prefix
• Info - General information, that could be useful
• Debug - Should only be used to find bugs and removed (or commented out) after the bug is found
• Warning - Used for warnings and not important errors
• Error - Used for Fatal Errors / Will be printed to the screen (graphics driver is not Implemented yet)

log(log_level, string, ...) - function (void)

Logs the given string to QEMU's log port, the string is prefixed with the log type. Format strings are supported.

math.h

Mathematical functions, definitions, etc.

MAX(a, b) - macro

Returns the bigger one of the given values.

MIN(a, b) - macro

Returns the smaller one of the given values.

CEIL_TO(a, b) - macro

Aligns a upwards to b. Example: CEIL_TO(13, 8) would return 16, because 16 is the next higher multiple of 8 after 13.

FLOOR_TO(a, b) - macro

Aligns a downwards to b. Example: FLOOR_TO(13, 8) would return 8, because 8 is the next smaller multiple of 8 before 13.

position_T - struct

Name	Description
x	X coordinate of the position
y	Y coordinate of the position

pow(base, exponent) - function (uint64_t)

Returns the power of base ^ exponent.

abs(number) - function (uint64_t)

Returns the absolute value of number.

octal_string_to_int(string, size) - function (uint64_t)

Converts a base-8 string with length size into an integer and returns it.

memory.h

Basic memory functionalities.

memory_copy(source, destination, num) - function (void)

Copies num bytes from source to destination. On linux this function is called memcpy.

memory_set(destination, data, num) - function (void)

Sets num bytes at destination to data. On linux this function is called memset.

memory_compare(a, b, num) - function (bool)

Compares the first num bytes at a and b. Returns false if there is a different byte. Returns true if the data is the same. There is a similar function on linux called memcmp.

memory_allocate(size) - function (void*)

Returns the address to a buffer, that is at least size bytes big. On linux this function is called malloc.

memory_free(address) - function (void)

Free the buffer at address and make it reallocatable , this buffer needs to be a buffer, that was created with memory_allocate. On linux this function is called free.

memory_allocator_init(base) - function (void)

This initializes the heap, where memory_allocate allocates memory.

memory_hexdump(address, num) - function (void)

Logs num bytes from address as 8 byte rows. The data is represented in hexadecimal and ascii.

panic.h

Ahhhhh - the kernel is burning!

panic(state, message) - function (void)

This prints out the error message, a stack backtrace (planned) and a register dump (planned). After that, the kernel halts forever. This function is called, when a fatal error occurs

stdtypes.h

Standard type definitions, that are used almost everywhere.

uint8_t - typedef

8-bit wide unsigned int.

Range: 0 - 255

int8_t - typedef

8-bit wide signed int.

Range: -128 - 127

uint16_t - typedef

16-bit wide unsigned int.

Range: 0 - 65536

int16_t - typedef

16-bit wide signed int.

Range: -32768 - 32767

uint32_t - typedef

32-bit wide unsigned int.

Range: 0 - 4294967296

int32_t - typedef

32-bit wide signed int.

Range: -2147483648 - 2147483647

uint64_t - typedef

64-bit wide unsigned int.

Range: 0 - 18446744073709551616

int64_t - typedef

64-bit wide signed int.

Range: -9223372036854775808 - 9223372036854775807

bool - typedef

Boolean type, can hold a logical value true or false.

true - macro

Logical true value.

false - macro

Logical false value

NULL - macro

A pointer to nowhere.

string.h

string_t - typedef

A null-terminated array of chars.

string_length(string) - function (uint32_t)

Returns the amount of chars a string has before it's null-terminator.

string_compare(a, b) - function (bool)

Returns true when the strings a and b are equal. Returns false if they aren't equal.

string_find_next(string, chr) - function (uint32_t)

Returns the index of the next character that matches chr in string.

string_find_last(string, chr) - function (uint32_t)

Returns the index of the last character that matches chr in string.

variadic_format_size(string, args) - function (uint64_t)

Returns how long a format string with the given pattern (string) and args would be. Useful to create a big enough buffer before formatting a string.

format_size(string, ...) - function (uint64_t)

This calls variadic_format_size, but instead of giving it a va_list you can give this function the actual arguments.

variadic_format(output, string, args) - function (void)

Formats string with args and writes the product to output. The rules for format strings are specified on top of this document in the General concepts block.

format(output, string, ...) - function (void)

This calls variadic_format, but instead of giving it a va_list you can give this function the actual arguments.

string_unsigned_dec_to_alpha(string, value) - function (void)

Converts the unsigned integer in value to an alphanumeric string. The representation is decimal. This string will be written into string.

string_dec_to_alpha(string, value) - function (void)

Converts the signed integer in value to an alphanumeric string. If it is negative it will be prefixed with a hyphen. The representation is decimal. This string will be written into string.

string_hex_8bit_to_alpha(string, value) - function (void)

Converts the byte in value to an alphanumeric string. The representation is hexadecimal. This string will be written into string.

string_hex_16bit_to_alpha(string, value) - function (void)

Converts the word(16-bits) in value to an alphanumeric string. The representation is hexadecimal. This string will be written into string.

string_hex_32bit_to_alpha(string, value) - function (void)

Converts the dword(32-bits) in value to an alphanumeric string. The representation is hexadecimal. This string will be written into string.

string_hex_64bit_to_alpha(string, value) - function (void)

Converts the qword(64-bits) in value to an alphanumeric string. The representation is hexadecimal. This string will be written into string.

string_bin_to_alpha(string, num_bits, value) - function (void)

Converts the data in value to an alphanumeric string. The representation is binary. num_bits specifies how many bits, starting at the least significant bit, will be converted. This string will be written into string.

string_bool_to_alpha(string, value) - function (void)

Converts the boolean in value to an alphanumeric string. The representation is true or false. This string will be written into string.

string_is_char_text(chr) - function (bool)

Returns whether the char (chr) contains text(a-z, A-Z, 0-9, special chars) or not.

string_is_char_number(chr) - function (bool)

Returns whether the char (chr) is a number(0-9) or not.

string_is_char_alpha(chr) - function (bool)

Returns whether the char (chr) is alphanumeric(a-z, A-Z, 0-9) or not.

string_is_char_uppercase(chr) - function (bool)

Returns whether the char (chr) is uppercase(A-Z) or not.

string_is_char_lowercase(chr) - function (bool)

Returns whether the char (chr) is lowercase(a-z) or not.

symbol.h

symbol_type_E - enum

• Function
• Variable
• Unknown

symbol_T - struct

Name	Type	Description
name	string_t	The name of the symbol (e.g. the name of the kernels entry symbol would be _start
type	symbol_type_E	The symbols type (elf types like File are of type Unknown)
address	uint64_t	The symbols address

symbol_resolve_from_name(symbols, num_symbols, name); - function (symbol_T*)

This searches symbols for a symbol with a matching name.

symbol_resolve_from_rip(symbols, num_symbols, rip); - function (symbol_T*)

Give it a list of symbols and an instruction pointer (rip) and it will return the symbol (function), where rip lays in.