iPXE
SimpleTextOut.h
Go to the documentation of this file.
1 /** @file
2  Simple Text Out protocol from the UEFI 2.0 specification.
3 
4  Abstraction of a very simple text based output device like VGA text mode or
5  a serial terminal. The Simple Text Out protocol instance can represent
6  a single hardware device or a virtual device that is an aggregation
7  of multiple physical devices.
8 
9 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
10 SPDX-License-Identifier: BSD-2-Clause-Patent
11 
12 **/
13 
14 #ifndef __SIMPLE_TEXT_OUT_H__
15 #define __SIMPLE_TEXT_OUT_H__
16 
17 FILE_LICENCE ( BSD2_PATENT );
18 
19 #define EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID \
20  { \
21  0x387477c2, 0x69c7, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
22  }
23 
24 ///
25 /// Protocol GUID defined in EFI1.1.
26 ///
27 #define SIMPLE_TEXT_OUTPUT_PROTOCOL EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID
28 
30 
31 ///
32 /// Backward-compatible with EFI1.1.
33 ///
35 
36 //
37 // Defines for required EFI Unicode Box Draw characters
38 //
39 #define BOXDRAW_HORIZONTAL 0x2500
40 #define BOXDRAW_VERTICAL 0x2502
41 #define BOXDRAW_DOWN_RIGHT 0x250c
42 #define BOXDRAW_DOWN_LEFT 0x2510
43 #define BOXDRAW_UP_RIGHT 0x2514
44 #define BOXDRAW_UP_LEFT 0x2518
45 #define BOXDRAW_VERTICAL_RIGHT 0x251c
46 #define BOXDRAW_VERTICAL_LEFT 0x2524
47 #define BOXDRAW_DOWN_HORIZONTAL 0x252c
48 #define BOXDRAW_UP_HORIZONTAL 0x2534
49 #define BOXDRAW_VERTICAL_HORIZONTAL 0x253c
50 #define BOXDRAW_DOUBLE_HORIZONTAL 0x2550
51 #define BOXDRAW_DOUBLE_VERTICAL 0x2551
52 #define BOXDRAW_DOWN_RIGHT_DOUBLE 0x2552
53 #define BOXDRAW_DOWN_DOUBLE_RIGHT 0x2553
54 #define BOXDRAW_DOUBLE_DOWN_RIGHT 0x2554
55 #define BOXDRAW_DOWN_LEFT_DOUBLE 0x2555
56 #define BOXDRAW_DOWN_DOUBLE_LEFT 0x2556
57 #define BOXDRAW_DOUBLE_DOWN_LEFT 0x2557
58 #define BOXDRAW_UP_RIGHT_DOUBLE 0x2558
59 #define BOXDRAW_UP_DOUBLE_RIGHT 0x2559
60 #define BOXDRAW_DOUBLE_UP_RIGHT 0x255a
61 #define BOXDRAW_UP_LEFT_DOUBLE 0x255b
62 #define BOXDRAW_UP_DOUBLE_LEFT 0x255c
63 #define BOXDRAW_DOUBLE_UP_LEFT 0x255d
64 #define BOXDRAW_VERTICAL_RIGHT_DOUBLE 0x255e
65 #define BOXDRAW_VERTICAL_DOUBLE_RIGHT 0x255f
66 #define BOXDRAW_DOUBLE_VERTICAL_RIGHT 0x2560
67 #define BOXDRAW_VERTICAL_LEFT_DOUBLE 0x2561
68 #define BOXDRAW_VERTICAL_DOUBLE_LEFT 0x2562
69 #define BOXDRAW_DOUBLE_VERTICAL_LEFT 0x2563
70 #define BOXDRAW_DOWN_HORIZONTAL_DOUBLE 0x2564
71 #define BOXDRAW_DOWN_DOUBLE_HORIZONTAL 0x2565
72 #define BOXDRAW_DOUBLE_DOWN_HORIZONTAL 0x2566
73 #define BOXDRAW_UP_HORIZONTAL_DOUBLE 0x2567
74 #define BOXDRAW_UP_DOUBLE_HORIZONTAL 0x2568
75 #define BOXDRAW_DOUBLE_UP_HORIZONTAL 0x2569
76 #define BOXDRAW_VERTICAL_HORIZONTAL_DOUBLE 0x256a
77 #define BOXDRAW_VERTICAL_DOUBLE_HORIZONTAL 0x256b
78 #define BOXDRAW_DOUBLE_VERTICAL_HORIZONTAL 0x256c
79 
80 //
81 // EFI Required Block Elements Code Chart
82 //
83 #define BLOCKELEMENT_FULL_BLOCK 0x2588
84 #define BLOCKELEMENT_LIGHT_SHADE 0x2591
85 
86 //
87 // EFI Required Geometric Shapes Code Chart
88 //
89 #define GEOMETRICSHAPE_UP_TRIANGLE 0x25b2
90 #define GEOMETRICSHAPE_RIGHT_TRIANGLE 0x25ba
91 #define GEOMETRICSHAPE_DOWN_TRIANGLE 0x25bc
92 #define GEOMETRICSHAPE_LEFT_TRIANGLE 0x25c4
93 
94 //
95 // EFI Required Arrow shapes
96 //
97 #define ARROW_LEFT 0x2190
98 #define ARROW_UP 0x2191
99 #define ARROW_RIGHT 0x2192
100 #define ARROW_DOWN 0x2193
101 
102 //
103 // EFI Console Colours
104 //
105 #define EFI_BLACK 0x00
106 #define EFI_BLUE 0x01
107 #define EFI_GREEN 0x02
108 #define EFI_CYAN (EFI_BLUE | EFI_GREEN)
109 #define EFI_RED 0x04
110 #define EFI_MAGENTA (EFI_BLUE | EFI_RED)
111 #define EFI_BROWN (EFI_GREEN | EFI_RED)
112 #define EFI_LIGHTGRAY (EFI_BLUE | EFI_GREEN | EFI_RED)
113 #define EFI_BRIGHT 0x08
114 #define EFI_DARKGRAY (EFI_BLACK | EFI_BRIGHT)
115 #define EFI_LIGHTBLUE (EFI_BLUE | EFI_BRIGHT)
116 #define EFI_LIGHTGREEN (EFI_GREEN | EFI_BRIGHT)
117 #define EFI_LIGHTCYAN (EFI_CYAN | EFI_BRIGHT)
118 #define EFI_LIGHTRED (EFI_RED | EFI_BRIGHT)
119 #define EFI_LIGHTMAGENTA (EFI_MAGENTA | EFI_BRIGHT)
120 #define EFI_YELLOW (EFI_BROWN | EFI_BRIGHT)
121 #define EFI_WHITE (EFI_BLUE | EFI_GREEN | EFI_RED | EFI_BRIGHT)
122 
123 //
124 // Macro to accept color values in their raw form to create
125 // a value that represents both a foreground and background
126 // color in a single byte.
127 // For Foreground, and EFI_* value is valid from EFI_BLACK(0x00) to
128 // EFI_WHITE (0x0F).
129 // For Background, only EFI_BLACK, EFI_BLUE, EFI_GREEN, EFI_CYAN,
130 // EFI_RED, EFI_MAGENTA, EFI_BROWN, and EFI_LIGHTGRAY are acceptable
131 //
132 // Do not use EFI_BACKGROUND_xxx values with this macro.
133 //
134 #define EFI_TEXT_ATTR(Foreground, Background) ((Foreground) | ((Background) << 4))
135 
136 #define EFI_BACKGROUND_BLACK 0x00
137 #define EFI_BACKGROUND_BLUE 0x10
138 #define EFI_BACKGROUND_GREEN 0x20
139 #define EFI_BACKGROUND_CYAN (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_GREEN)
140 #define EFI_BACKGROUND_RED 0x40
141 #define EFI_BACKGROUND_MAGENTA (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_RED)
142 #define EFI_BACKGROUND_BROWN (EFI_BACKGROUND_GREEN | EFI_BACKGROUND_RED)
143 #define EFI_BACKGROUND_LIGHTGRAY (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_GREEN | EFI_BACKGROUND_RED)
144 
145 //
146 // We currently define attributes from 0 - 7F for color manipulations
147 // To internally handle the local display characteristics for a particular character,
148 // Bit 7 signifies the local glyph representation for a character. If turned on, glyphs will be
149 // pulled from the wide glyph database and will display locally as a wide character (16 X 19 versus 8 X 19)
150 // If bit 7 is off, the narrow glyph database will be used. This does NOT affect information that is sent to
151 // non-local displays, such as serial or LAN consoles.
152 //
153 #define EFI_WIDE_ATTRIBUTE 0x80
154 
155 /**
156  Reset the text output device hardware and optionally run diagnostics
157 
158  @param This The protocol instance pointer.
159  @param ExtendedVerification Driver may perform more exhaustive verification
160  operation of the device during reset.
161 
162  @retval EFI_SUCCESS The text output device was reset.
163  @retval EFI_DEVICE_ERROR The text output device is not functioning correctly and
164  could not be reset.
165 
166 **/
167 typedef
171  IN BOOLEAN ExtendedVerification
172  );
173 
174 /**
175  Write a string to the output device.
176 
177  @param This The protocol instance pointer.
178  @param String The NULL-terminated string to be displayed on the output
179  device(s). All output devices must also support the Unicode
180  drawing character codes defined in this file.
181 
182  @retval EFI_SUCCESS The string was output to the device.
183  @retval EFI_DEVICE_ERROR The device reported an error while attempting to output
184  the text.
185  @retval EFI_UNSUPPORTED The output device's mode is not currently in a
186  defined text mode.
187  @retval EFI_WARN_UNKNOWN_GLYPH This warning code indicates that some of the
188  characters in the string could not be
189  rendered and were skipped.
190 
191 **/
192 typedef
196  IN CHAR16 *String
197  );
198 
199 /**
200  Verifies that all characters in a string can be output to the
201  target device.
202 
203  @param This The protocol instance pointer.
204  @param String The NULL-terminated string to be examined for the output
205  device(s).
206 
207  @retval EFI_SUCCESS The device(s) are capable of rendering the output string.
208  @retval EFI_UNSUPPORTED Some of the characters in the string cannot be
209  rendered by one or more of the output devices mapped
210  by the EFI handle.
211 
212 **/
213 typedef
217  IN CHAR16 *String
218  );
219 
220 /**
221  Returns information for an available text mode that the output device(s)
222  supports.
223 
224  @param This The protocol instance pointer.
225  @param ModeNumber The mode number to return information on.
226  @param Columns Returns the geometry of the text output device for the
227  requested ModeNumber.
228  @param Rows Returns the geometry of the text output device for the
229  requested ModeNumber.
230 
231  @retval EFI_SUCCESS The requested mode information was returned.
232  @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
233  @retval EFI_UNSUPPORTED The mode number was not valid.
234 
235 **/
236 typedef
240  IN UINTN ModeNumber,
241  OUT UINTN *Columns,
242  OUT UINTN *Rows
243  );
244 
245 /**
246  Sets the output device(s) to a specified mode.
247 
248  @param This The protocol instance pointer.
249  @param ModeNumber The mode number to set.
250 
251  @retval EFI_SUCCESS The requested text mode was set.
252  @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
253  @retval EFI_UNSUPPORTED The mode number was not valid.
254 
255 **/
256 typedef
260  IN UINTN ModeNumber
261  );
262 
263 /**
264  Sets the background and foreground colors for the OutputString () and
265  ClearScreen () functions.
266 
267  @param This The protocol instance pointer.
268  @param Attribute The attribute to set. Bits 0..3 are the foreground color, and
269  bits 4..6 are the background color. All other bits are undefined
270  and must be zero. The valid Attributes are defined in this file.
271 
272  @retval EFI_SUCCESS The attribute was set.
273  @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
274  @retval EFI_UNSUPPORTED The attribute requested is not defined.
275 
276 **/
277 typedef
281  IN UINTN Attribute
282  );
283 
284 /**
285  Clears the output device(s) display to the currently selected background
286  color.
287 
288  @param This The protocol instance pointer.
289 
290  @retval EFI_SUCCESS The operation completed successfully.
291  @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
292  @retval EFI_UNSUPPORTED The output device is not in a valid text mode.
293 
294 **/
295 typedef
299  );
300 
301 /**
302  Sets the current coordinates of the cursor position
303 
304  @param This The protocol instance pointer.
305  @param Column The position to set the cursor to. Must be greater than or
306  equal to zero and less than the number of columns and rows
307  by QueryMode ().
308  @param Row The position to set the cursor to. Must be greater than or
309  equal to zero and less than the number of columns and rows
310  by QueryMode ().
311 
312  @retval EFI_SUCCESS The operation completed successfully.
313  @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
314  @retval EFI_UNSUPPORTED The output device is not in a valid text mode, or the
315  cursor position is invalid for the current mode.
316 
317 **/
318 typedef
322  IN UINTN Column,
323  IN UINTN Row
324  );
325 
326 /**
327  Makes the cursor visible or invisible
328 
329  @param This The protocol instance pointer.
330  @param Visible If TRUE, the cursor is set to be visible. If FALSE, the cursor is
331  set to be invisible.
332 
333  @retval EFI_SUCCESS The operation completed successfully.
334  @retval EFI_DEVICE_ERROR The device had an error and could not complete the
335  request, or the device does not support changing
336  the cursor mode.
337  @retval EFI_UNSUPPORTED The output device is not in a valid text mode.
338 
339 **/
340 typedef
344  IN BOOLEAN Visible
345  );
346 
347 /**
348  @par Data Structure Description:
349  Mode Structure pointed to by Simple Text Out protocol.
350 **/
351 typedef struct {
352  ///
353  /// The number of modes supported by QueryMode () and SetMode ().
354  ///
356 
357  //
358  // current settings
359  //
360 
361  ///
362  /// The text mode of the output device(s).
363  ///
365  ///
366  /// The current character output attribute.
367  ///
369  ///
370  /// The cursor's column.
371  ///
373  ///
374  /// The cursor's row.
375  ///
377  ///
378  /// The cursor is currently visible or not.
379  ///
382 
383 ///
384 /// The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices.
385 /// It is the minimum required protocol for any handle supplied as the ConsoleOut
386 /// or StandardError device. In addition, the minimum supported text mode of such
387 /// devices is at least 80 x 25 characters.
388 ///
391 
394 
398 
402 
403  ///
404  /// Pointer to SIMPLE_TEXT_OUTPUT_MODE data.
405  ///
407 };
408 
410 
411 #endif
EFI_TEXT_TEST_STRING TestString
int INT32
Definition: ProcessorBind.h:99
EFI_TEXT_SET_CURSOR_POSITION SetCursorPosition
128 bit buffer containing a unique identifier value.
Definition: Base.h:215
EFI_STATUS(EFIAPI * EFI_TEXT_CLEAR_SCREEN)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This)
Clears the output device(s) display to the currently selected background color.
unsigned char BOOLEAN
INT32 Attribute
The current character output attribute.
EFI_STATUS(EFIAPI * EFI_TEXT_QUERY_MODE)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN ModeNumber, OUT UINTN *Columns, OUT UINTN *Rows)
Returns information for an available text mode that the output device(s) supports.
unsigned short CHAR16
EFI_STATUS(EFIAPI * EFI_TEXT_SET_MODE)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN ModeNumber)
Sets the output device(s) to a specified mode.
FILE_LICENCE(BSD2_PATENT)
EFI_GUID gEfiSimpleTextOutProtocolGuid
The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices.
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL SIMPLE_TEXT_OUTPUT_INTERFACE
Backward-compatible with EFI1.1.
Definition: SimpleTextOut.h:34
EFI_TEXT_SET_ATTRIBUTE SetAttribute
EFI_STATUS(EFIAPI * EFI_TEXT_SET_CURSOR_POSITION)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN Column, IN UINTN Row)
Sets the current coordinates of the cursor position.
#define OUT
Definition: mlx_utils.h:29
INT32 Mode
The text mode of the output device(s).
EFI_SIMPLE_TEXT_OUTPUT_MODE * Mode
Pointer to SIMPLE_TEXT_OUTPUT_MODE data.
EFI_STATUS(EFIAPI * EFI_TEXT_TEST_STRING)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN CHAR16 *String)
Verifies that all characters in a string can be output to the target device.
#define EFIAPI
EFI_STATUS(EFIAPI * EFI_TEXT_STRING)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN CHAR16 *String)
Write a string to the output device.
EFI_TEXT_CLEAR_SCREEN ClearScreen
INT32 CursorColumn
The cursor's column.
UINT64 UINTN
Unsigned value of native width.
EFI_TEXT_ENABLE_CURSOR EnableCursor
#define IN
Definition: mlx_utils.h:28
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:31
EFI_STATUS(EFIAPI * EFI_TEXT_ENABLE_CURSOR)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN BOOLEAN Visible)
Makes the cursor visible or invisible.
INT32 CursorRow
The cursor's row.
EFI_STATUS(EFIAPI * EFI_TEXT_RESET)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN BOOLEAN ExtendedVerification)
Reset the text output device hardware and optionally run diagnostics.
INT32 MaxMode
The number of modes supported by QueryMode () and SetMode ().
EFI_STATUS(EFIAPI * EFI_TEXT_SET_ATTRIBUTE)(IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This, IN UINTN Attribute)
Sets the background and foreground colors for the OutputString () and ClearScreen () functions.
BOOLEAN CursorVisible
The cursor is currently visible or not.