EFI SIMPLE TEXT OUTPUT PROTOCOL
From PhoenixWiki
This protocol is used to control text-based output devices.
Contents |
GUID
#define EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID \
{0x387477c2,0x69c7,0x11d2,0x8e,0x39,0x00,0xa0,0xc9,0x69,0x72,0x3b}
Protocol Interface Structure
#include EFI_PROTOCOL_CONSUMER(SimpleTextOut) extern EFI_GUID gEfiSimpleTextOutProtocolGuid;
typedef struct _EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL {
EFI_TEXT_RESET Reset;
EFI_TEXT_STRING OutputString;
EFI_TEXT_TEST_STRING TestString;
EFI_TEXT_QUERY_MODE QueryMode;
EFI_TEXT_SET_MODE SetMode;
EFI_TEXT_SET_ATTRIBUTE SetAttribute;
EFI_TEXT_CLEAR_SCREEN ClearScreen;
EFI_TEXT_SET_CURSOR_POSITION SetCursorPosition;
EFI_TEXT_ENABLE_CURSOR EnableCursor;
SIMPLE_TEXT_OUTPUT_MODE *Mode;
} EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL;
Members
| Member | Description |
|---|---|
| Reset | Reset the ConsoleOut device. See Reset(). |
| OutputString | Displays the Unicode string on the device at the current cursor location. |
| TestString | Tests to see if the ConsoleOut device supports this Unicode string. |
| QueryMode | Queries information concerning the output device’s supported text mode. |
| SetMode | Sets the current mode of the output device. |
| SetAttribute | Sets the foreground and background color of the text that is output. |
| ClearScreen | Clears the screen with the currently set background color. |
| SetCursorPosition | Sets the current cursor position. |
| EnableCursor | Turns the visibility of the cursor on/off. |
| Mode | Pointer to SIMPLE_TEXT_OUTPUT_MODE data. |
Description
The EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL is used to control text-based output devices. It is the minimum required protocol for any handle supplied as the ConsoleOut or StandardError device. In addition, the minimum supported text mode of such devices is at least 80 x 25 characters.
A video device that only supports graphics mode is required to emulate text mode functionality. Output strings themselves are not allowed to contain any control codes other than those defined in Table 78. Positional cursor placement is done only via the SetCursorPosition() function. It is highly recommended that text output to the StandardError device be limited to sequential string outputs. (That is, it is not recommended to use ClearScreen() or SetCursorPosition() on output messages to StandardError.)
If the output device is not in a valid text mode at the time of the HandleProtocol() call, the device is to indicate that its CurrentMode is –1. On connecting to the output device the caller is required to verify the mode of the output device, and if it is not acceptable to set it to something it can use.
Reset()
Resets the text output device hardware.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_RESET) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN BOOLEAN ExtendedVerification );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| ExtendedVerification | Indicates that the driver may perform a more exhaustive verification operation of the device during reset. |
Description
The Reset() function resets the text output device hardware. The cursor position is set to (0, 0), and the screen is cleared to the default background color for the output device.
As part of initialization process, the firmware/device will make a quick but reasonable attempt to verify that the device is functioning. If the ExtendedVerification flag is TRUE the firmware may take an extended amount of time to verify the device is operating on reset. Otherwise the reset operation is to occur as quickly as possible.
The hardware verification process is not defined by this specification and is left up to the platform firmware or driver to implement.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The text output device was reset. |
| EFI_DEVICE_ERROR | The text output device is not functioning correctly and could not be reset. |
OutputString()
Writes a Unicode string to the output device.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_STRING) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN CHAR16 *String );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| String | The Null-terminated Unicode string to be displayed on the output device(s). All output devices must also support the Unicode drawing characters defined in “Related Definitions.” |
Related Definitions
#define BOXDRAW_HORIZONTAL 0x2500 #define BOXDRAW_VERTICAL 0x2502 #define BOXDRAW_DOWN_RIGHT 0x250c #define BOXDRAW_DOWN_LEFT 0x2510 #define BOXDRAW_UP_RIGHT 0x2514 #define BOXDRAW_UP_LEFT 0x2518 #define BOXDRAW_VERTICAL_RIGHT 0x251c #define BOXDRAW_VERTICAL_LEFT 0x2524 #define BOXDRAW_DOWN_HORIZONTAL 0x252c #define BOXDRAW_UP_HORIZONTAL 0x2534 #define BOXDRAW_VERTICAL_HORIZONTAL 0x253c #define BOXDRAW_DOUBLE_HORIZONTAL 0x2550 #define BOXDRAW_DOUBLE_VERTICAL 0x2551 #define BOXDRAW_DOWN_RIGHT_DOUBLE 0x2552 #define BOXDRAW_DOWN_DOUBLE_RIGHT 0x2553 #define BOXDRAW_DOUBLE_DOWN_RIGHT 0x2554 #define BOXDRAW_DOWN_LEFT_DOUBLE 0x2555 #define BOXDRAW_DOWN_DOUBLE_LEFT 0x2556 #define BOXDRAW_DOUBLE_DOWN_LEFT 0x2557 #define BOXDRAW_UP_RIGHT_DOUBLE 0x2558 #define BOXDRAW_UP_DOUBLE_RIGHT 0x2559 #define BOXDRAW_DOUBLE_UP_RIGHT 0x255a #define BOXDRAW_UP_LEFT_DOUBLE 0x255b #define BOXDRAW_UP_DOUBLE_LEFT 0x255c #define BOXDRAW_DOUBLE_UP_LEFT 0x255d #define BOXDRAW_VERTICAL_RIGHT_DOUBLE 0x255e #define BOXDRAW_VERTICAL_DOUBLE_RIGHT 0x255f #define BOXDRAW_DOUBLE_VERTICAL_RIGHT 0x2560 #define BOXDRAW_VERTICAL_LEFT_DOUBLE 0x2561 #define BOXDRAW_VERTICAL_DOUBLE_LEFT 0x2562 #define BOXDRAW_DOUBLE_VERTICAL_LEFT 0x2563 #define BOXDRAW_DOWN_HORIZONTAL_DOUBLE 0x2564 #define BOXDRAW_DOWN_DOUBLE_HORIZONTAL 0x2565 #define BOXDRAW_DOUBLE_DOWN_HORIZONTAL 0x2566 #define BOXDRAW_UP_HORIZONTAL_DOUBLE 0x2567 #define BOXDRAW_UP_DOUBLE_HORIZONTAL 0x2568 #define BOXDRAW_DOUBLE_UP_HORIZONTAL 0x2569 #define BOXDRAW_VERTICAL_HORIZONTAL_DOUBLE 0x256a #define BOXDRAW_VERTICAL_DOUBLE_HORIZONTAL 0x256b #define BOXDRAW_DOUBLE_VERTICAL_HORIZONTAL 0x256c
#define BLOCKELEMENT_FULL_BLOCK 0x2588 #define BLOCKELEMENT_LIGHT_SHADE 0x2591
#define GEOMETRICSHAPE_UP_TRIANGLE 0x25b2 #define GEOMETRICSHAPE_RIGHT_TRIANGLE 0x25ba #define GEOMETRICSHAPE_DOWN_TRIANGLE 0x25bc #define GEOMETRICSHAPE_LEFT_TRIANGLE 0x25c4
#define ARROW_UP 0x2191 #define ARROW_DOWN 0x2193
Description
The OutputString() function writes a Unicode string to the output device. This is the most basic output mechanism on an output device. The String is displayed at the current cursor location on the output device(s) and the cursor is advanced according to the rules listed below.
| Mnemonic | Unicode | Description |
|---|---|---|
| Null | U+0000 | Ignore the character, and do not move the cursor. |
| BS | U+0008 | If the cursor is not at the left edge of the display, then move the cursor left one column. |
| LF | U+000A | If the cursor is at the bottom of the display, then scroll the display one row, and do not update the cursor position. Otherwise, move the cursor down one row. |
| CR | U+000D | Move the cursor to the beginning of the current row. |
| Other | U+XXXX | Print the character at the current cursor position and move the cursor right one column. If this moves the cursor past the right edge of the display, then the line should wrap to the beginning of the next line. This is equivalent to inserting a CR and an LF. Note that if the cursor is at the bottom of the display, and the line wraps, then the display will be scrolled one line. |
Note: If desired, the system’s NVRAM environment variables may be used at install time to determine the configured locale of the system or the installation procedure can query the user for the proper language support. This is then used to either install the proper EFI image/loader or to configure the installed image’s strings to use the proper text for the selected locale.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The string was output to the device. |
| EFI_DEVICE_ERROR | The device reported an error while attempting to output the text. |
| EFI_UNSUPPORTED | The output device’s mode is not currently in a defined text mode. |
| EFI_WARN_UNKNOWN_GLYPH | This warning code indicates that some of the characters in the Unicode string could not be rendered and were skipped. |
TestString()
Verifies that all characters in a Unicode string can be output to the target device.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_TEST_STRING) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN CHAR16 *String );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| String | The Null-terminated Unicode string to be examined for the output device(s). |
Description
The TestString() function verifies that all characters in a Unicode string can be output to the target device.
This function provides a way to know if the desired character set is present for rendering on the output device(s). This allows the installation procedure (or EFI image) to at least select a letter set that the output devices are capable of displaying. Since the output device(s) may be changed between boots, if the loader cannot adapt to such changes it is recommended that the loader call OutputString() with the text it has and ignore any “unsupported” error codes. The devices(s) that are capable of displaying the Unicode letter set will do so.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The device(s) are capable of rendering the output string. |
| EFI_UNSUPPORTED | Some of the characters in the Unicode string cannot be rendered by one or more of the output devices mapped by the EFI handle. |
QueryMode()
Returns information for an available text mode that the output device(s) supports.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_QUERY_MODE) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN ModeNumber, OUT UINTN *Columns, OUT UINTN *Rows );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| ModeNumber | The mode number to return information on. |
| Columns, Rows | Returns the geometry of the text output device for the request ModeNumber. |
Description
The QueryMode() function returns information for an available text mode that the output device(s) supports.
It is required that all output devices support at least 80x25 text mode. This mode is defined to be mode 0. If the output devices support 80x50, that is defined to be mode 1. All other text dimensions supported by the device will follow as modes 2 and above. If an output device supports modes 2 and above, but does not support 80x50, then querying for mode 1 will return EFI_UNSUPPORTED.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The requested mode information was returned. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request. |
| EFI_UNSUPPORTED | The mode number was not valid. |
SetMode()
Sets the output device(s) to a specified mode.
Prototype
typedef EFI_STATUS (* EFIAPI EFI_TEXT_SET_MODE) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN ModeNumber );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| ModeNumber | The text mode to set. |
Description
The SetMode() function sets the output device(s) to the requested mode. On success the device is in the geometry for the requested mode, and the device has been cleared to the current background color with the cursor at (0,0).
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The requested text mode was set. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request. |
| EFI_UNSUPPORTED | The mode number was not valid. |
SetAttribute()
Sets the background and foreground colors for theOutputString() and ClearScreen() functions.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_SET_ATTRIBUTE) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN Attribute );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| Attribute | The attribute to set. Bits 0..3 are the foreground color, and bits 4..6 are the background color. All other bits are reserved.
#define EFI_BLACK 0x00 #define EFI_BLUE 0x01 #define EFI_GREEN 0x02 #define EFI_CYAN 0x03 #define EFI_RED 0x04 #define EFI_MAGENTA 0x05 #define EFI_BROWN 0x06 #define EFI_LIGHTGRAY 0x07 #define EFI_BRIGHT 0x08 #define EFI_DARKGRAY 0x08 #define EFI_LIGHTBLUE 0x09 #define EFI_LIGHTGREEN 0x0A #define EFI_LIGHTCYAN 0x0B #define EFI_LIGHTRED 0x0C #define EFI_LIGHTMAGENTA 0x0D #define EFI_YELLOW 0x0E #define EFI_WHITE 0x0F #define EFI_BACKGROUND_BLACK 0x00 #define EFI_BACKGROUND_BLUE 0x10 #define EFI_BACKGROUND_GREEN 0x20 #define EFI_BACKGROUND_CYAN 0x30 #define EFI_BACKGROUND_RED 0x40 #define EFI_BACKGROUND_MAGENTA 0x50 #define EFI_BACKGROUND_BROWN 0x60 #define EFI_BACKGROUND_LIGHTGRAY 0x70 #define EFI_TEXT_ATTR(foreground,background) \ ((foreground) | ((background) << 4)) |
Description
The SetAttribute() function sets the background and foreground colors for the OutputString() and ClearScreen() functions.
The color mask can be set even when the device is in an invalid text mode.
Devices supporting a different number of text colors are required to emulate the above colors to the best of the device’s capabilities.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The requested attributes were set. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request. |
ClearScreen()
Clears the output device(s) display to the currently selected background color.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_CLEAR_SCREEN) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
Description
The ClearScreen() function clears the output device(s) display to the currently selected background color. The cursor position is set to (0, 0).
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The operation completed successfully. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request. |
| EFI_UNSUPPORTED | The output device is not in a valid text mode. |
SetCursorPosition()
Sets the current coordinates of the cursor position.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_SET_CURSOR_POSITION) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN Column, IN UINTN Row );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| Column, Row | The position to set the cursor to. Must greater than or equal to zero and less than the number of columns and rows returned by QueryMode(). |
Description
The SetCursorPosition() function sets the current coordinates of the cursor position. The upper left corner of the screen is defined as coordinate (0, 0).
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The operation completed successfully. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request. |
| EFI_UNSUPPORTED | The output device is not in a valid text mode, or the cursor position is invalid for the current mode. |
EnableCursor()
Makes the cursor visible or invisible.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_TEXT_ENABLE_CURSOR) ( IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN BOOLEAN Visible );
Parameters
| Parameter | Description |
|---|---|
| This | A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance. |
| Visible | If TRUE, the cursor is set to be visible. If FALSE, the cursor is set to be invisible. |
Description
The EnableCursor() function makes the cursor visible or invisible.
Status Codes Returned
| Status Code | Description |
|---|---|
| EFI_SUCCESS | The operation completed successfully. |
| EFI_DEVICE_ERROR | The device had an error and could not complete the request or the device does not support changing the cursor mode. |
| EFI_UNSUPPORTED | The output device does not support visibility control of the cursor. |
Copyright (C) 2008-2009 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.
