From 74d3e98772dabec3b449b8ecdb5949ba72f7f2ce Mon Sep 17 00:00:00 2001 From: antifallobst Date: Sun, 12 Feb 2023 02:31:18 +0100 Subject: [PATCH] docs: documented format strings --- .wiki/Kernel-documentation.md | 136 +++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 3 deletions(-) diff --git a/.wiki/Kernel-documentation.md b/.wiki/Kernel-documentation.md index af17b31..2f92109 100644 --- a/.wiki/Kernel-documentation.md +++ b/.wiki/Kernel-documentation.md @@ -12,13 +12,13 @@ The kernel is booted using the limine boot protocol. --- # General concepts -## kernel initialization +## Kernel initialization The single parts of the kernel are initialized in the following order: - **Global Descriptor Table** - **Page Frame Manager** - **Interrupt Descriptor Table** -## interrupt handling +## Interrupt handling OSDev Wiki: [Interrupts](https://wiki.osdev.org/Interrupts) Unfortunatly the x86 architecture doesn't provide a method to get the ID of the current interrupt. @@ -27,7 +27,7 @@ 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 +## Paging OSDev Wiki: [Paging](https://wiki.osdev.org/Paging) There is a difference between `Virtual Memory Spaces` and the `Physical Memory Space`. @@ -45,6 +45,122 @@ 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. +## 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`. +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** | None | +| **Numeric Specifier Default** | None | +| **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. @@ -459,6 +575,20 @@ Returns the amount of chars a string has before it's null-terminator. Returns **true** when the strings **_a_** and **_b_** are equal. Returns **false** if they aren't equal. +#### `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.