Add documentation for textlog driver
The textlog driver isn't quite usable yet, but the documentation for is being added with this commit because the driver will be a little more complex; requiring planning which is done using the docs.
This commit is contained in:
parent
f0fcefc5eb
commit
2ad0d26ff4
GPG Key ID:
1358818BAA38B104
|
|
@ -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.
|
||||||
|
|
||||||
Loading…
Reference in New Issue