BCOS Transition State 1 Specification

BCOS Transition State 1 Specification
Version 1.0
(Preliminary Draft)

Contents

1                Overview
2                CPUs
2.1                BSP
3                Stage 2 Manager
4                Hardware And Firmware
4.1                A20 Gate
4.2                Other Hardware
5                Boot Catalogue
6                Stage 1 Interface
6.1                Stage 1 Interface Function Reference
6.1.1                Function 0x00000000 - Perform Hand-off To Stage 2
6.1.2                Function 0x00000001 - Abort Boot
6.1.3                Function 0x00000002 - Pause
6.1.4                Function 0x00000003 - Create Selector Pair
6.2                Stage 1 Requirements
6.3                Stage 2 Requirements

Tables

Table 2.1      General Registers And Segment Registers
Table 2.2      Boot Flags
Table 2.3      EFLAGS
Table 2.4      Control Registers And Miscellaneous Registers
Table 2.5      CR0 Control Register
Table 5.1      Required Boot Catalogue Entries
Table 5.2      Optional Boot Catalogue Entries

1   Overview

There's several stages used during boot, and several specifications that describe the state the computer must be in before moving from one stage to another. This specification describes what state the computer must be in when the OS's Boot Loader (Stage 1) transfers control to the OS's Stage 2 Manager.

Initially the Stage 2 Manager has no ability to communicate with the user of its own, and relies on one or more Boot Output Modules to display the Boot Log, any error messages, etc. However, it is possible for Stage 2 to encounter some sort of error condition before it has been able to setup any Boot Output Modules. Therefore, to allow Stage 2 to reliably inform the user when any critical errors occur (before it has setup Boot Output Modules), Stage 1 code remains in memory and provides a software interface that Stage 2 code can use. Complete details of this interface are provided in Chapter 6: Stage 1 Interface.

2   CPUs

At boot, one CPU is classified as the BSP (Bootstrap Processor) and any additional CPUs are classified as APs (Application Processors), where all APs are left in a halted state by the BIOS and only the BSP is running. All APs need to remain in this halted state.

2.1   BSP

The BSP shall be in 32-bit protected mode. The contents of the CPU's general registers and segment registers must be as defined in Table 2.1: General Registers And Segment Registers.

Register

Contents

EAX

Boot Flags (see Table 2.2: Boot Flags)

EBX

Reserved (zero)

ECX

Selector for Stage 1 Interface entry point (see Chapter 6: Stage 1 Interface)

EDX

Offset for Stage 1 Interface entry point (see Chapter 6: Stage 1 Interface)

ESI

Physical address of the Boot Catalogue (see Chapter 5: Boot Catalogue)

EDI

Stage 2 code base address

EBP

Reserved (zero)

ESP

Undefined (may contain any value)

Set to 32-bit, "read/execute", CPL=0, limit = 0xFFFFFFFF, base = stage 2 code base address

EIP

Obtained from the Stage 2 code's executable header

Set to 32-bit, "read/write", limit = 0xFFFFFFFF, base = stage 2 code base address

Set to 32-bit, "read/write", limit = 0xFFFFFFFF, base = 0x00000000

Set to 32-bit, "read/write", limit = 0xFFFFFFFF, base = stage 2 code base address

EFLAGS

See Table 2.3: EFLAGS

Table 2.1 - General Registers And Segment Registers

Bit/s

Description

Headless flag (set if video card is present and usable, clear if video card is not present or not usable)

1 to 31

Reserved (clear)

Table 2.2 - Boot Flags

Bit/s

State

0 to 7

Undefined

8 (TF)

Clear (single-stepping disabled)

9 (IF)

Clear (interrupts disabled)

10 to 16

Undefined

17 (VM)

Clear (Virtual-8086 Mode disabled)

18 (AC)

Clear (Alignment Check disabled)

19 to 31

Undefined

Table 2.3 - EFLAGS

The BSP's control registers and miscellaneous registers must be as defined in Table 2.4: Control Registers And Miscellaneous Registers.

Register

Contents

CR0

See Table 2.5: CR0 Control Register

CR1 (if present)

Undefined

CR2

Undefined

CR3

Undefined

CR4 (if present)

All bits clear

IDTR

Set to limit = 0x00000000, base = undefined (to ensure an NMI causes a triple fault/reset)

GDTR

Undefined

LDTR

Undefined

Table 2.4 - Control Registers And Miscellaneous Registers

Bit/s

State

0 (PE)

Set (protected mode enabled)

1 (MP)

Undefined

2 (EM)

Undefined

3 (TS)

Undefined

4 (ET)

Undefined

5 (NE)

Undefined

6 to 15

Undefined

16 (WP)

Undefined

18 (AM)

Undefined

19 to 28

Undefined

29 (NW)

Same state as firmware left it

30 (CD)

Same state as firmware left it

31 (PG)

Undefined

Table 2.5 - CR0 Control Register

All MSRs must be left in the state that the firmware left them in.

All FPU, MMX and SSE registers (if present) are in an undefined state; including the FPU Control Register, the FPU Status Register, the FPU Tag Register, the FPU Last Instruction Pointer register, the FPU Last Data Pointer register, the FPU Operand register and the MXCSR Register.

3   Stage 2 Manager

The Stage 2 Manager must be loaded into physically contiguous pages of RAM. To do this the previous stage allocates enough pages to contain the Stage 2 Manager plus any pages that the Stage 2 Manager needs for uninitialized data (as determined by the "Offset for the end of the uninitialized data area" field in the Platform Header - see BCOS Native Executable File Format Specification, Section 4.4: Uninitialized Area for more information).

Normally, executable files are loaded at address 0x00001000 in the address space. To emulate this (and allow for the Stage 2 Manager to be created using the standard executable file format), the "stage 2 code base address" (which is used for CS, DS, ES and SS segment base addresses) must be 4096 bytes less than the physical address of the Stage 2 Manager. The page at the "stage 2 code base address" shouldn't be allocated as part of the physically contiguous pages of RAM that were allocated for the Stage 2 Manager.

4   Hardware And Firmware

4.1   A20 Gate

For normal operation the A20 gate should be enabled (so that the operating system can access every second MiB of the physical address space); however, a boot loader may deliberately disable the A20 gate for testing purposes, and if the boot loader is unable to enable or disable the A20 gate it must still continue to boot.

The boot loader must correctly report the state of the A20 gate in the Boot Catalogue (even if the boot loader is unable to enable/disable the A20 gate).

4.2   Other Hardware

All other hardware, including interrupt controllers (e.g. the PIC chips), timers, etc; remain in an undefined state (or, any state that Stage 1 code wants them to be in).

5   Boot Catalogue

A valid Boot Catalogue must exist, and must include all of the entries listed in Table 5.1: Required Boot Catalogue Entries. Additional entries listed in Table 5.2: Optional Boot Catalogue Entries are optional, but recommended where possible.

BCOS Boot Catalogue Specification, Section 3.1: Type 0x00000001 - Boot Loader Identification Entry

BCOS Boot Catalogue Specification, Section 3.2: Type 0x00000003 - Trusted Area Entry

BCOS Boot Catalogue Specification, Section 3.7: Type 0x80000001 - Faulty RAM List Entry

BCOS Boot Catalogue Specification, Section 3.8: Type 0x80000002 - Physical Address Space Map Entry

BCOS Boot Catalogue Specification, Section 3.9: Type 0x80000003 - Faulty Page Bitmap Entry

BCOS Boot Catalogue Specification, Section 3.10: Type 0x80000004 - Free Page Bitmap Entry

BCOS Boot Catalogue Specification, Section 3.11: Type 0x80000005 - Boot Script Entry

BCOS Boot Catalogue Specification, Section 3.12: Type 0x80000006 - Boot Image Entry

BCOS Boot Catalogue Specification, Section 3.13: Type 0x80000007 - Boot Log Entry

BCOS Boot Catalogue Specification, Section 3.16: Type 0x80000022 - Boot Script Workspace Entry

Table 5.1 - Required Boot Catalogue Entries

Note that a Trusted Area Entry is required for each area of RAM that must work correctly for the computer to boot reliably.

BCOS Boot Catalogue Specification, Section 3.3: Type 0x00000020 - Selected Video Mode Entry

BCOS Boot Catalogue Specification, Section 3.4: Type 0x00000030 - Motherboard Identification

BCOS Boot Catalogue Specification, Section 3.14: Type 0x80000020 - Primary Monitor EDID Entry

BCOS Boot Catalogue Specification, Section 3.15: Type 0x80000021 - Default Video Mode List Entry

BCOS Boot Catalogue Specification, Section 3.17: Type 0x80000030 - ACPI Data Entry

BCOS Boot Catalogue Specification, Section 3.18: Type 0x80000031 - MP Specification Data Entry

BCOS Boot Catalogue Specification, Section 3.19: Type 0x80000032 - SMBIOS Data Entry

Table 5.2 - Optional Boot Catalogue Entries

6   Stage 1 Interface

At any time before the official hand-off to Stage 2, Stage 2 code must be able to call any of the Stage 1 Interface functions. Stage 1 code must not rely on the contents of any registers not described in the definition of each function, and must preserve the contents of all general registers.

For all Stage 1 Interface functions, on entry EAX contains the function number, and on exit EAX contains returned status (where 0x00000000 means "OK"). All unknown/undefined function numbers return "EAX = 0xFFFFFFFF".

6.1   Stage 1 Interface Function Reference

6.1.1   Function 0x00000000 - Perform Hand-off To Stage 2

Input Parameters:

•	`EAX = 0x00000000`

Output Parameters:

•	`EAX = 0x00000000`
•	`EBX = Physical address of first page of Stage 1 memory to free`
•	`ECX = Number of pages of Stage 1 memory to free`

This function terminates the Stage 1 interface. After this function is used Stage 2 code should free the area of memory (described by the EBX and ECX output parameters) to reclaim memory that was used by Stage 1 code; Stage 2 code can no longer use the Stage 1 Interface; and Stage 2 assumes complete control of all CPUs (including the GDTR and IDTR) and all hardware.

Stage 1 code must ensure that all IRQ sources are masked (disabled) in all interrupt controllers before returning from this function.

6.1.2 Function 0x00000001 - Abort Boot

Input Parameters:

•	`EAX = 0x00000001`
•	`EBX = Physical address of ASCIIZ error string`

No Output Parameters (this function will not return)

This function is used to abort the boot, and inform the user of the reason for failure. If possible, Stage 1 code displays the provided error string preceded by the text "ERROR: ", possibly followed by other text saying that boot has been aborted. For example, if the error string (pointed to by EBX) is "ERROR: Something was wrong!", then Stage 1 code will attempt to display something like:

ERROR: Something was wrong! Boot has been aborted. Please reset or reboot the computer.

Figure 6.1 - Error Message Example

There is no need for Stage 1 code to attempt to add this text to the Boot Log, as the Boot Log is unused when boot has been aborted. In addition to displaying the error message, Stage 1 code may use other ways to indicate that boot was aborted (e.g. making the PC speaker beep).

6.1.3 Function 0x00000002 - Pause

Input Parameters:

•	`EAX = 0x00000002`

Output Parameters:

•	`EAX = 0x00000000`

This function must be called regularly by Stage 2 code. It is used by Stage 1 code time to handle any IRQs in a timely manner; as Stage 1 code may be relying on firmware (and firmware's IRQ handling) to display error messages.

6.1.4 Function 0x00000003 - Create Selector Pair

Input Parameters:

•	`EAX = 0x00000003`
•	`EBX = Base address for selectors`

Output Parameters:

•	`EAX = 0x00000000 if no error, 0x00000001 if all selector pairs are in use`
•	`ECX = Code selector number`
•	`EDX = Data selector number`

This function is used by Stage 2 code to create a pair of selectors in the GDT, which needs to be done when Stage 2 code is starting a module (until Subsection 6.1.1: Function 0x00000000 - Perform Hand-off To Stage 2 is called and the Stage 2 code can use its own GDT). A maximum of 4 selector pairs must be supported by Stage 1 code.

6.2 Stage 1 Requirements

After Stage 2 code has been started (while the Stage 1 Interface remains usable), Stage 1 code must not:

•	Attempt to allocate or free any memory
•	Attempt to read or modify anything in the Boot Catalogue

6.3 Stage 2 Requirements

While the Stage 1 Interface remains usable, Stage 2 code must not:

•	Modify the IDTR
•	Modify the GDTR
•	Access of modify any hardware
•	Access or modify any RAM that has not been allocated
•	Set the IF flag in EFLAGS (to enable interrupts)

While the Stage 1 Interface remains usable, Stage 2 code may:

•	Allocate memory (for any purpose)
•	Attempt to read or modify anything in the Boot Catalogue

Until Subsection 6.1.1: Function 0x00000000 - Perform Hand-off To Stage 2 is called, Stage 2 code's only goal is to perform consistency checks on the Boot Catalogue (to ensure it is usable), find Boot Output Modules (in the Boot Image), determine which Boot Output Modules will be used, allocate memory for any Boot Output Modules that will be used, and initialize those Boot Output Modules. Once any/all Boot Output Modules are ready, Stage 2 code calls Subsection 6.1.1: Function 0x00000000 - Perform Hand-off To Stage 2 and uses those Boot Output Modules to display the Boot Log (and any error messages) while perparing to transfer control to Stage 3.

Generated on Sat Oct 17 03:21:19 2009