Nightloader/i386/docs/drivers/textlog.md

142 lines
5.7 KiB
Markdown

# Nightloader Drivers | TextLog
The textlog driver provides text output capabilities to other drivers
and parts of the Nightloader to facilitate debugging.
## Subsystem Identifiers
Every single one of the Nightloader's subsystems has a system-wide
identifier to make it possible to reference that subsystem using a
16 bit tall number (the identifier).
Below, there is a table of all identifiers, sorted by the number.
| Identifier | Name of Subsystem |
| ------------ | ----------------------------------- |
| 1 | Pre-Protected Mode |
| 2 | GDT Creation |
| 3 | Main Boot Sequence |
| 1024 - 2048 | Drivers are from 1024 to 2048 |
| 1024 | TextLog Driver |
| 1025 | ACPI Driver |
| 1026 | ELF Driver * |
| 1030 | USB Interaction Driver * |
| 1031 | PCI Interaction Driver |
| 1032 | PCIe Interaction Driver * |
| 1033 | SATA / AHCI Driver * |
> The development for subsystems with an asterisk hasn't started yet.
## Log Levels
There are several log levels to categorize the severity of an internal
error and for the logger to be able to identify what to show in any
given context of the system. The log levels are given below:
1. PostMortem
A log level of type 'PostMortem' is used when the bootloader has
already crashed and is gathering debug information for a developer
to use to find the error. This should *never* be visible to any
potential user of the Nightloader.
2. Critical
A Critical error is issued right before the bootloader shuts itself
down because it couldn't get the operating system booting anyways.
4. Error
An error occurs if some functionality may not be accessible to the
operating system down the execution chain because of a fault that
happened in the bootloader.
3. Unimplemented
Somewhere between an error and a warning, this log level tells the
developer that a feature that hasn't been implemented yet has to be
implemented for the warning to go away.
5. Warning
A warning is given to indicate something not working as expected to
a degree that a feature would have to be deactivated completely to
avoid erroneous behavior.
6. RequireWorkaround
Notes that a workaround for something that isn't working entirely
as wanted *exists*, and must be used for the bootloader to continue
working correctly.
7. DebugNote
A message for the typical ``printf()`` debugging, just that this
function is a lot more primitive than even the C ``printf()``.
> In cases where a numeric identifier for the log levels is used, the
> numbers from this list should be used.
## Line Structure
A line is stored as 96 bytes of which 80 are used for ASCII characters
while the others are metadata for re-drawing the text. The metadata
footer, as its name implies, is located AFTER the text.
| Offset | Length | Name of Field |
| ------ | --------- | --------------------------- |
| 0 | 80 | ASCII Text Message |
| 80 | 16 | Metadata footer |
| **0** | **96** | **TOTAL DATA AMOUNT** |
The footer of the line is located at the end of the line it describes.
It is like that because then, the first character of the footer can be
a zero and act as a null-terminator for very long lines.
This table describes the layout of the footer structure:
| Offset | Length | Name of Field |
| ------ | --------- | --------------------------- |
| 0 | 1 | Line Null-terminator |
| 1 | 1 | Line unit's length |
| 2 | 1 | Line Structure Index |
| 3 | 1 | Log Level |
| 4 | 2 | Previous Line's Index |
| 6 | 2 | Issuing Subsystem |
| 8 | 1 | Display Pane |
| 9 | 7 | Padding |
| **0** | **16** | **TOTAL DATA AMOUNT** |
The following list contains explanations of the fields. Note that the
number infront of the explanation is NOT the offset of the field but
the index in the list.
1. Line Null Terminator
Null-terminator for the line that is located before this footer.
2. Line unit's length
How long this line is. Only if this contains its maximum value, 80,
the next field will be checked.
3. Line Structure Index
This field is only more than 1 when an entry in the log spans more
than one line and is only 0 if the line slot is unused. It tells
the structure's index in a compound line (line which spans more
than one line structure/slot).
4. Log Level
How important this logging piece is. This decides whether the log
will be shown in a given system context. All valid log levels are
enumerated with their description and context in this document in
[another table](#log-levels).
5. Previous Line's Index
As the lines are rendered from the bottom up, the linked list items
are stored "in reverse", the lowest (newest) item first and going
further until the oldest item is reached.
6. Issuing Subsystem
The Identifier of the subsystem that has issued a given message.
All currently understood identifiers can be found in
[another table](#subsystem-identifiers).
7. Display Pane
Tells into which box on the display the line will be drawn. A pane
can be compared to a window in modern window managers and desktop
environments, just that the windows in this bootloader are *a lot*
more primitive due to disk-space- and code-complexity -constraints.