diff --git a/i386/docs/drivers/textlog.md b/i386/docs/drivers/textlog.md new file mode 100644 index 0000000..4162227 --- /dev/null +++ b/i386/docs/drivers/textlog.md @@ -0,0 +1,141 @@ +# 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. +