docs: documented format strings
This commit is contained in:
parent
58124b6cdb
commit
74d3e98772
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue