Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
Let begin by example and dissect it. An example Coreboot crash dump is shown:
PCI: 00:18.7: enabled 1 Mainboard NF81-T56N-LF Enable. Unexpected Exception: 6 @ 10:00246faa - Halting Code: 0 eflags: 00010402 eax: fdb01c7c ebx: 0027c4a4 ecx: 000c34b1 edx: 000045fd edi: 00000002 esi: 00000078 ebp: 00287ff0 esp: 00287f6d 00246f68: 0d 26 00 c7 04 24 06 00 00246f70: 00 00 e8 a9 c5 00 00 c6 00246f78: 05 00 0e d8 fe ff c6 05 00246f80: 01 0e d8 fe 00 fd 05 02 00246f88: 0e d8 fe 00 c6 00 03 0e 00246f90: d8 fe 00 c6 05 83 0e d8 00246f98: fe 00 c7 44 24 66 80 00 00246fa0: 00 00 c7 04 24 fd 00 00 00246fa8: 00 e8 fe d8 ff 00 c7 44 00246fb0: 24 04 61 00 00 83 c7 04 00246fb8: 24 28 00 00 00 66 ea d8 00246fc0: ff ff 83 c4 1c c3 c3 c3 00246fc8: 57 bf 00 0c 00 00 56 53 00246fd0: 83 ec 30 8b 44 24 40 c7 00246fd8: 44 24 04 00 00 00 00 89 00246fe0: 04 24 e8 a3 fb 00 00 8d
Here the line, Unexpected Exception: 6 @ 10:00246faa - Halting, is key to understanding the dump. In this example an Exception: 6 signifies an unknown Opcode was attempt to execute and 10:00246faa has two components, the segment selector (0x10) and address (e000_0001).
To understand the next chunk:
Code: 0 eflags: 00010402 eax: fdb01c7c ebx: 0027c4a4 ecx: 000c34b1 edx: 000045fd edi: 00000002 esi: 00000078 ebp: 00287ff0 esp: 00287f6d
we remind ourselves of some x86 asmebler.
| Register Summary | Flags | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| General registers | Segment registers | Index and pointers | Indicator | ||||||||||||
| EAX | EBX | ECX | EDX | CS | DS | ES | FS | GS | SS | ESI | EDI | EBP | EIP | ESP | EFLAGS |
The following are 32 bits wide registers : EAX EBX ECX EDX
EAX : Called the Accumulator register.
It is used for I/O port access, arithmetic, interrupt calls, etc...
EBX : Called the Base register
It is used as a base pointer for memory access
Gets some interrupt return values
ECX : Called the Counter register
It is used as a loop counter and for shifts
Gets some interrupt values
EDX : Called the Data register
It is used for I/O port access, arithmetic, some interrupt calls.
Segment registers hold the segment address of various items. They are only available in 16 values. They can only be set by a general register or special instructions.
CS : Holds the Code segment in which your program runs.
Changing its value might make the computer hang.
DS : Holds the Data segment that your program accesses.
Changing its value might give erronous data.
ES,FS,GS : These are extra segment registers available for
far pointer addressing like video memory and such.
SS : Holds the Stack segment your program uses.
Sometimes has the same value as DS.
Changing its value can give unpredictable results,
mostly data related.
Indexes and pointer and the offset part of and address. They have various uses but each register has a specific function. They some time used with a segment register to point to far address (in a 1Mb range). The register with an "E" prefix can only be used in protected mode.
ES:EDI EDI DI : Destination index register
Used for string, memory array copying and setting and
for far pointer addressing with ES
DS:ESI EDI SI : Source index register
Used for string and memory array copying
SS:EBP EBP BP : Stack Base pointer register
Holds the base address of the stack
SS:ESP ESP SP : Stack pointer register
Holds the top address of the stack
CS:EIP EIP IP : Index Pointer
Holds the offset of the next instruction
It can only be read
The EFLAGS register hold the state of the processor. It is modified by many intructions and is used for comparing some parameters, conditional loops and conditionnal jumps. Each bit holds the state of specific parameter of the last instruction.
Bit Label Desciption --------------------------- 0 CF Carry flag 2 PF Parity flag 4 AF Auxiliary carry flag 6 ZF Zero flag 7 SF Sign flag 8 TF Trap flag 9 IF Interrupt enable flag 10 DF Direction flag 11 OF Overflow flag 12-13 IOPL I/O Priviledge level 14 NT Nested task flag 16 RF Resume flag 17 VM Virtual 8086 mode flag 18 AC Alignment check flag (486+) 19 VIF Virutal interrupt flag 20 VIP Virtual interrupt pending flag 21 ID ID flag
Protected mode segmentation registers are GDTR (Global Descriptor Table Register), IDTR (Interrupt Descriptor Table Register), LDTR (Local DTR), and TR.
The following chart lists the exceptions that can be generated by the Intel 80286, 80386, 80486, and Pentium processors:
Exception | Description
(dec/hex) |
----------|-------------------------------------------------
0 00h | Divide error:
| Occurs during a DIV or an IDIV instruction when the
| divisor is zero or a quotient overflow occurs.
1 01h | Single-step/debug exception:
| Occurs for any of a number of conditions:
| - Instruction address breakpoint fault
| - Data address breakpoint trap
| - General detect fault
| - Single-step trap
| - Task-switch breakpoint trap
2 02h | Nonmaskable interrupt:
| Occurs because of a nonmaskable hardware interrupt.
3 03h | Breakpoint:
| Occurs when the processor encounters an INT 3 instruction.
4 04h | Overflow:
| Occurs when the processor encounters an INTO instruction
| and the OF (overflow) flag is set.
5 05h | Bounds check (BOUND instruction):
| Occurs when the processor, while executing a BOUND
| instruction, finds that the operand exceeds the specified
| limit.
6 06h | Invalid opcode:
| Occurs when an invalid opcode is detected.
7 07h | Coprocessor not available:
| Occurs for one of two conditions:
| - The processor encounters an ESC (escape) instruction
| and the EM (emulate) bit of CR0 (control register zero)
| is set.
| - The processor encounters either the WAIT instruction or
| an ESC instruction and both the MP (monitor
| coprocessor) and TS (task switched) bits of CR0 are set.
8 08h | Double fault:
| Occurs when the processor detects an exception while
| trying to invoke the handler for a prior exception.
9 09h | Coprocessor segment overrun:
| Occurs when a page or segment violation is detected while
| transferring the middle portion of a coprocessor operand
| to the NPX.
10 0Ah | Invalid TSS:
| Occurs if, during a task switch, the new TSS is invalid.
11 0Bh | Segment not present:
| Occurs when the processor detects that the present bit of
| a descriptor is zero.
12 0Ch | Stack exception:
| Occurs for one of two conditions:
| - As a result of a limit violation in any operation that
| refers to SS (stack segment register)
| - When attempting to load SS with a descriptor that is
| marked as not-present but is otherwise valid
13 0Dh | General protection violation:
| Each protection violation that does not cause another
| exception causes a general protection exception.
| - Exceeding segment limit when using CS, DS, ES, FS, or GS
| - Exceeding segment limit when referencing a descriptor
| table
| - Transferring control to a segment that is not executable
| - Writing to a read-only data segment or a code segment
| - Reading from an execute-only segment
| - Loading SS with a read-only descriptor
| - Loading SS, DS, ES, FS, or GS with a descriptor of a system
| segment
| - Loading DS, ES, FS, or GS with the descriptor of an
| executable segment that is also not readable
| - Loading SS with the descriptor of an executable segment
| - Accessing memory through DS, ES, FS, or GS when the segment
| register contains a NULL selector
| - Switching to a busy task
| - Violating privilege rules
| - Loading CR0 with PG=1 and PE=0
| - Interrupt or exception through trap or interrupt gate from
| V86 mode to a privilege level other than 0
14 0Eh | Page fault:
| Occurs when paging is enabled (PG=1) and the processor
| detects one of the following conditions while translating
| a linear address to a physical address:
| - The page-directory or page-table entry needed for the
| address translation has 0 in its present bit.
| - The current procedure does not have sufficient privilege
| to access the indicated page.
15 0Fh | (Reserved)
16 10h | Coprocessor error:
| Occurs when the processor detects a signal from the
| coprocessor on the ERROR# input pin.
17 11h | (Reserved)
through |
31 1Fh |
See Intel 80386 Programmer's Reference Manual for further detail.