Nightloader/i386/docs/drivers/textlog.md

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