EFI SIMPLE TEXT OUTPUT PROTOCOL

From PhoenixWiki

Jump to: navigation, search

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.

Personal tools