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