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 ]=====!
Interrupt ID: 0x0E
Error Code: 0b00000000000000000000000000000010
Error Message: Page Fault

Paging Info:
    Page Map: 0x000000000FB0A000

CPU Flags:
    Parity
    Sign

CPU Registers:
    RIP: 0xFFFFFFFF8000027A   RAX: 0x0000100000079838   RBX: 0x0000000000000000
    RCX: 0xFFFFFFFFFFFFFFD8   RDX: 0x0000000000000000   RSI: 0x0000000000000000
    RDI: 0x0000100000079838   RBP: 0xFFFF80000FB1AF10   RSP: 0xFFFF80000FB1AEF0

[ 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.

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.

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.

---

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

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)

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

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_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.

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

NoxOS uses the GDT loaded by limine, because in 64 bit mode a GDT is only needed for backwards compatability.

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.

idt_init() - function (void)

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

proc

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)
prev	thread_T*	The previous thread in the scheduling queue (should only be accessed by the scheduler!)
next	thread_T*	The next thread in the scheduling queue (should only be accessed by the scheduler!)

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.

scheduler.h

scheduler_T - struct

Name	Type	Description
num_threads	uint32_t	Total amount of currently spawned threads
running_thread	thread_T*	A pointer to the currently running thread.
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() - function (void)

Initializes the scheduler and performs a scheduler_start kernel syscall. 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_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_get_current_thread() - function (thread_T*)

Returns a pointer to the currently running thread.

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

This struct holds a buffer for a bitmap and its size. The size is the size of the buffer in bytes, to get the amount of storable bits multiply size with 8.

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_HALT_WHILE(a) - macro

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

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.

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.