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