80x86 Interface SpecificationsProject Map
Stage 2 Display Module Interface Specification
Version 1.0
(Preliminary Draft)
 

Contents

1                Overview
2                Display Module Interface Function Reference
2.1                Function 0x00000000 - Initialize
2.2                Function 0x00000001 - Show Details
2.3                Function 0x00000002 - Update Display
2.4                Function 0x00000003 - Critical Error
2.5                Function 0x00000004 - Change Entry Point



1   Overview

The "Stage 2 Manager" (which controls the second stage of the operating system's boot) uses a few different types of modules. One of these types of modules (Display Modules) used by the Stage 2 Manager are used to allow the end user to view the Boot Log. This allows different types of Display Modules to be used in different situations.

This specification defines the interface between the Stage 2 Manager and the Display Modules. This interface is implemented as a set of functions in the Display Module that are called by the Stage 2 Manager via. the Display Module's entry point.


2   Display Module Interface Function Reference

For all Display Module 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 must return "EAX = 0xFFFFFFFF".


2.1   Function 0x00000000 - Initialize

The Stage 2 Manager calls this function once when it first starts the Display Module.

Input Parameters:

    
•EAX = 0x00000000
•EBX = Offset for the Stage 2 Manager Interface entry point
•ECX = Selector for the Stage 2 Manager Interface entry point
•EDX = Display Module base address

Output Parameters:

    
•EAX = Status

The selector and offset for the Stage 2 Manager Interface entry point can be used by a Display Module to ask the Stage 2 Manager to perform certain actions. See the Stage 2 Manager Interface Specification for details.

If the Display Module returns any value other that 0x00000000, the Stage 2 Manager will terminate the Display Module and free any resources it was using.


2.2   Function 0x00000001 - Show Details

The Stage 2 Manager calls this function after all Display Modules have been initialized, to give them a chance to add their details to the Boot Log.

Input Parameters:

    
•EAX = 0x00000001

Output Parameters:

    
•EAX = Status

For formatting purposes, each line added to the Boot Log by a Display Module should be preceded by 8 space characters.

If the Display Module returns any value other that 0x00000000, the Stage 2 Manager will terminate the Display Module and free any resources it was using.


2.3   Function 0x00000002 - Update Display

The Stage 2 Manager calls this function when the Boot Log has been changed.

Input Parameters:

    
•EAX = 0x00000002
•EBX = Physical address for the start of the Boot Log
•ECX = Physical address for the end of the Boot Log

Output Parameters:

    
•EAX = 0x00000000

The Boot Log consists of a series of UTF-8 bytes. The only control characters allowed within the Boot Log are:

    
•0x01 to indicate that "highlight mode" should be enabled (special control character, not defined by Unicode)
•0x03 to indicate that "highlight mode" should be disabled (special control character, not defined by Unicode)
•0x0A to indicate the start of a new line (standard Unicode/ASCII control character)

All other control characters (excluding 0xA0, no-break space) should be treated as an undisplayable character.

There isn't a terminating zero byte at the end of the series of UTF-8 bytes (the "Physical address for the end of the Boot Log" must be used to determine where the end of the series of UTF-8 bytes are). In addition, the Stage 2 Manager can relocate the entire Boot Log any time that any text is added to the Boot Log (e.g. to increase the amount of memory allocated to store the Boot Log). Because of this, if the Display Module needs to keep track of how much of the Boot Log it has already displayed, then it is recommended that the Display Module keep track of the offset from the start of the Boot Log to the end of the displayed characters, as this offset won't change when the physical address of the Boot Log does change.


2.4   Function 0x00000003 - Critical Error

The Stage 2 Manager calls this function when a critical error occurs. The Display Module must not rely on any functions provided by the Stage 2 Manager after that Stage 2 Manager calls this function - after a critical error there's no guarantee that anything can be done reliably.

Input Parameters:

    
•EAX = 0x00000003
•EBX = Physical address for the zero terminated ASCII error string

Output Parameters:

    
•EAX = 0x00000000

The ASCII error string should be displayed on a new line, followed by some indication that boot has been aborted. For example, the Stage 2 Manager might pass the string "ERROR: Something went wrong!" and the Display Module might display the error message as shown in Figure 2.1: Error Message Example.


ERROR: Something went wrong!

Boot aborted, please reboot.
Figure 2.1 - Error Message Example

The Stage 2 Manager will not call this function until all Display Modules are initialized.


2.5   Function 0x00000004 - Change Entry Point

The Stage 2 Manager calls this function when the entry point for the Stage 2 Manager Interface changes.

Input Parameters:

    
•EAX = 0x00000004
•EBX = Offset for the Stage 2 Manager Interface entry point
•ECX = Selector for the Stage 2 Manager Interface entry point

Output Parameters:

    
•EAX = 0x00000000

Generated on Tue Sep 22 05:34:46 2009