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