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 // Define's 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 optionaly 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 visbile 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 410