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.

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

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

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.

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.