iPXE
SimpleTextOut.h
Go to the documentation of this file.
00001 /** @file
00002   Simple Text Out protocol from the UEFI 2.0 specification.
00003 
00004   Abstraction of a very simple text based output device like VGA text mode or
00005   a serial terminal. The Simple Text Out protocol instance can represent
00006   a single hardware device or a virtual device that is an aggregation
00007   of multiple physical devices.
00008 
00009 Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
00010 This program and the accompanying materials are licensed and made available under
00011 the terms and conditions of the BSD License that accompanies this distribution.
00012 The full text of the license may be found at
00013 http://opensource.org/licenses/bsd-license.php.
00014 
00015 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00016 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00017 
00018 **/
00019 
00020 #ifndef __SIMPLE_TEXT_OUT_H__
00021 #define __SIMPLE_TEXT_OUT_H__
00022 
00023 FILE_LICENCE ( BSD3 );
00024 
00025 #define EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID \
00026   { \
00027     0x387477c2, 0x69c7, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
00028   }
00029 
00030 ///
00031 /// Protocol GUID defined in EFI1.1.
00032 ///
00033 #define SIMPLE_TEXT_OUTPUT_PROTOCOL   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID
00034 
00035 typedef struct _EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL;
00036 
00037 ///
00038 /// Backward-compatible with EFI1.1.
00039 ///
00040 typedef EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL   SIMPLE_TEXT_OUTPUT_INTERFACE;
00041 
00042 //
00043 // Define's for required EFI Unicode Box Draw characters
00044 //
00045 #define BOXDRAW_HORIZONTAL                  0x2500
00046 #define BOXDRAW_VERTICAL                    0x2502
00047 #define BOXDRAW_DOWN_RIGHT                  0x250c
00048 #define BOXDRAW_DOWN_LEFT                   0x2510
00049 #define BOXDRAW_UP_RIGHT                    0x2514
00050 #define BOXDRAW_UP_LEFT                     0x2518
00051 #define BOXDRAW_VERTICAL_RIGHT              0x251c
00052 #define BOXDRAW_VERTICAL_LEFT               0x2524
00053 #define BOXDRAW_DOWN_HORIZONTAL             0x252c
00054 #define BOXDRAW_UP_HORIZONTAL               0x2534
00055 #define BOXDRAW_VERTICAL_HORIZONTAL         0x253c
00056 #define BOXDRAW_DOUBLE_HORIZONTAL           0x2550
00057 #define BOXDRAW_DOUBLE_VERTICAL             0x2551
00058 #define BOXDRAW_DOWN_RIGHT_DOUBLE           0x2552
00059 #define BOXDRAW_DOWN_DOUBLE_RIGHT           0x2553
00060 #define BOXDRAW_DOUBLE_DOWN_RIGHT           0x2554
00061 #define BOXDRAW_DOWN_LEFT_DOUBLE            0x2555
00062 #define BOXDRAW_DOWN_DOUBLE_LEFT            0x2556
00063 #define BOXDRAW_DOUBLE_DOWN_LEFT            0x2557
00064 #define BOXDRAW_UP_RIGHT_DOUBLE             0x2558
00065 #define BOXDRAW_UP_DOUBLE_RIGHT             0x2559
00066 #define BOXDRAW_DOUBLE_UP_RIGHT             0x255a
00067 #define BOXDRAW_UP_LEFT_DOUBLE              0x255b
00068 #define BOXDRAW_UP_DOUBLE_LEFT              0x255c
00069 #define BOXDRAW_DOUBLE_UP_LEFT              0x255d
00070 #define BOXDRAW_VERTICAL_RIGHT_DOUBLE       0x255e
00071 #define BOXDRAW_VERTICAL_DOUBLE_RIGHT       0x255f
00072 #define BOXDRAW_DOUBLE_VERTICAL_RIGHT       0x2560
00073 #define BOXDRAW_VERTICAL_LEFT_DOUBLE        0x2561
00074 #define BOXDRAW_VERTICAL_DOUBLE_LEFT        0x2562
00075 #define BOXDRAW_DOUBLE_VERTICAL_LEFT        0x2563
00076 #define BOXDRAW_DOWN_HORIZONTAL_DOUBLE      0x2564
00077 #define BOXDRAW_DOWN_DOUBLE_HORIZONTAL      0x2565
00078 #define BOXDRAW_DOUBLE_DOWN_HORIZONTAL      0x2566
00079 #define BOXDRAW_UP_HORIZONTAL_DOUBLE        0x2567
00080 #define BOXDRAW_UP_DOUBLE_HORIZONTAL        0x2568
00081 #define BOXDRAW_DOUBLE_UP_HORIZONTAL        0x2569
00082 #define BOXDRAW_VERTICAL_HORIZONTAL_DOUBLE  0x256a
00083 #define BOXDRAW_VERTICAL_DOUBLE_HORIZONTAL  0x256b
00084 #define BOXDRAW_DOUBLE_VERTICAL_HORIZONTAL  0x256c
00085 
00086 //
00087 // EFI Required Block Elements Code Chart
00088 //
00089 #define BLOCKELEMENT_FULL_BLOCK   0x2588
00090 #define BLOCKELEMENT_LIGHT_SHADE  0x2591
00091 
00092 //
00093 // EFI Required Geometric Shapes Code Chart
00094 //
00095 #define GEOMETRICSHAPE_UP_TRIANGLE    0x25b2
00096 #define GEOMETRICSHAPE_RIGHT_TRIANGLE 0x25ba
00097 #define GEOMETRICSHAPE_DOWN_TRIANGLE  0x25bc
00098 #define GEOMETRICSHAPE_LEFT_TRIANGLE  0x25c4
00099 
00100 //
00101 // EFI Required Arrow shapes
00102 //
00103 #define ARROW_LEFT  0x2190
00104 #define ARROW_UP    0x2191
00105 #define ARROW_RIGHT 0x2192
00106 #define ARROW_DOWN  0x2193
00107 
00108 //
00109 // EFI Console Colours
00110 //
00111 #define EFI_BLACK                 0x00
00112 #define EFI_BLUE                  0x01
00113 #define EFI_GREEN                 0x02
00114 #define EFI_CYAN                  (EFI_BLUE | EFI_GREEN)
00115 #define EFI_RED                   0x04
00116 #define EFI_MAGENTA               (EFI_BLUE | EFI_RED)
00117 #define EFI_BROWN                 (EFI_GREEN | EFI_RED)
00118 #define EFI_LIGHTGRAY             (EFI_BLUE | EFI_GREEN | EFI_RED)
00119 #define EFI_BRIGHT                0x08
00120 #define EFI_DARKGRAY              (EFI_BLACK | EFI_BRIGHT)
00121 #define EFI_LIGHTBLUE             (EFI_BLUE | EFI_BRIGHT)
00122 #define EFI_LIGHTGREEN            (EFI_GREEN | EFI_BRIGHT)
00123 #define EFI_LIGHTCYAN             (EFI_CYAN | EFI_BRIGHT)
00124 #define EFI_LIGHTRED              (EFI_RED | EFI_BRIGHT)
00125 #define EFI_LIGHTMAGENTA          (EFI_MAGENTA | EFI_BRIGHT)
00126 #define EFI_YELLOW                (EFI_BROWN | EFI_BRIGHT)
00127 #define EFI_WHITE                 (EFI_BLUE | EFI_GREEN | EFI_RED | EFI_BRIGHT)
00128 
00129 //
00130 // Macro to accept color values in their raw form to create
00131 // a value that represents both a foreground and background
00132 // color in a single byte.
00133 // For Foreground, and EFI_* value is valid from EFI_BLACK(0x00) to
00134 // EFI_WHITE (0x0F).
00135 // For Background, only EFI_BLACK, EFI_BLUE, EFI_GREEN, EFI_CYAN,
00136 // EFI_RED, EFI_MAGENTA, EFI_BROWN, and EFI_LIGHTGRAY are acceptable
00137 //
00138 // Do not use EFI_BACKGROUND_xxx values with this macro.
00139 //
00140 #define EFI_TEXT_ATTR(Foreground,Background) ((Foreground) | ((Background) << 4))
00141 
00142 #define EFI_BACKGROUND_BLACK      0x00
00143 #define EFI_BACKGROUND_BLUE       0x10
00144 #define EFI_BACKGROUND_GREEN      0x20
00145 #define EFI_BACKGROUND_CYAN       (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_GREEN)
00146 #define EFI_BACKGROUND_RED        0x40
00147 #define EFI_BACKGROUND_MAGENTA    (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_RED)
00148 #define EFI_BACKGROUND_BROWN      (EFI_BACKGROUND_GREEN | EFI_BACKGROUND_RED)
00149 #define EFI_BACKGROUND_LIGHTGRAY  (EFI_BACKGROUND_BLUE | EFI_BACKGROUND_GREEN | EFI_BACKGROUND_RED)
00150 
00151 //
00152 // We currently define attributes from 0 - 7F for color manipulations
00153 // To internally handle the local display characteristics for a particular character,
00154 // Bit 7 signifies the local glyph representation for a character.  If turned on, glyphs will be
00155 // pulled from the wide glyph database and will display locally as a wide character (16 X 19 versus 8 X 19)
00156 // If bit 7 is off, the narrow glyph database will be used.  This does NOT affect information that is sent to
00157 // non-local displays, such as serial or LAN consoles.
00158 //
00159 #define EFI_WIDE_ATTRIBUTE  0x80
00160 
00161 /**
00162   Reset the text output device hardware and optionaly run diagnostics
00163 
00164   @param  This                 The protocol instance pointer.
00165   @param  ExtendedVerification Driver may perform more exhaustive verification
00166                                operation of the device during reset.
00167 
00168   @retval EFI_SUCCESS          The text output device was reset.
00169   @retval EFI_DEVICE_ERROR     The text output device is not functioning correctly and
00170                                could not be reset.
00171 
00172 **/
00173 typedef
00174 EFI_STATUS
00175 (EFIAPI *EFI_TEXT_RESET)(
00176   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00177   IN BOOLEAN                                ExtendedVerification
00178   );
00179 
00180 /**
00181   Write a string to the output device.
00182 
00183   @param  This   The protocol instance pointer.
00184   @param  String The NULL-terminated string to be displayed on the output
00185                  device(s). All output devices must also support the Unicode
00186                  drawing character codes defined in this file.
00187 
00188   @retval EFI_SUCCESS             The string was output to the device.
00189   @retval EFI_DEVICE_ERROR        The device reported an error while attempting to output
00190                                   the text.
00191   @retval EFI_UNSUPPORTED         The output device's mode is not currently in a
00192                                   defined text mode.
00193   @retval EFI_WARN_UNKNOWN_GLYPH  This warning code indicates that some of the
00194                                   characters in the string could not be
00195                                   rendered and were skipped.
00196 
00197 **/
00198 typedef
00199 EFI_STATUS
00200 (EFIAPI *EFI_TEXT_STRING)(
00201   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00202   IN CHAR16                                 *String
00203   );
00204 
00205 /**
00206   Verifies that all characters in a string can be output to the
00207   target device.
00208 
00209   @param  This   The protocol instance pointer.
00210   @param  String The NULL-terminated string to be examined for the output
00211                  device(s).
00212 
00213   @retval EFI_SUCCESS      The device(s) are capable of rendering the output string.
00214   @retval EFI_UNSUPPORTED  Some of the characters in the string cannot be
00215                            rendered by one or more of the output devices mapped
00216                            by the EFI handle.
00217 
00218 **/
00219 typedef
00220 EFI_STATUS
00221 (EFIAPI *EFI_TEXT_TEST_STRING)(
00222   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00223   IN CHAR16                                 *String
00224   );
00225 
00226 /**
00227   Returns information for an available text mode that the output device(s)
00228   supports.
00229 
00230   @param  This       The protocol instance pointer.
00231   @param  ModeNumber The mode number to return information on.
00232   @param  Columns    Returns the geometry of the text output device for the
00233                      requested ModeNumber.
00234   @param  Rows       Returns the geometry of the text output device for the
00235                      requested ModeNumber.
00236 
00237   @retval EFI_SUCCESS      The requested mode information was returned.
00238   @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
00239   @retval EFI_UNSUPPORTED  The mode number was not valid.
00240 
00241 **/
00242 typedef
00243 EFI_STATUS
00244 (EFIAPI *EFI_TEXT_QUERY_MODE)(
00245   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00246   IN UINTN                                  ModeNumber,
00247   OUT UINTN                                 *Columns,
00248   OUT UINTN                                 *Rows
00249   );
00250 
00251 /**
00252   Sets the output device(s) to a specified mode.
00253 
00254   @param  This       The protocol instance pointer.
00255   @param  ModeNumber The mode number to set.
00256 
00257   @retval EFI_SUCCESS      The requested text mode was set.
00258   @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
00259   @retval EFI_UNSUPPORTED  The mode number was not valid.
00260 
00261 **/
00262 typedef
00263 EFI_STATUS
00264 (EFIAPI *EFI_TEXT_SET_MODE)(
00265   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00266   IN UINTN                                  ModeNumber
00267   );
00268 
00269 /**
00270   Sets the background and foreground colors for the OutputString () and
00271   ClearScreen () functions.
00272 
00273   @param  This      The protocol instance pointer.
00274   @param  Attribute The attribute to set. Bits 0..3 are the foreground color, and
00275                     bits 4..6 are the background color. All other bits are undefined
00276                     and must be zero. The valid Attributes are defined in this file.
00277 
00278   @retval EFI_SUCCESS       The attribute was set.
00279   @retval EFI_DEVICE_ERROR  The device had an error and could not complete the request.
00280   @retval EFI_UNSUPPORTED   The attribute requested is not defined.
00281 
00282 **/
00283 typedef
00284 EFI_STATUS
00285 (EFIAPI *EFI_TEXT_SET_ATTRIBUTE)(
00286   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00287   IN UINTN                                  Attribute
00288   );
00289 
00290 /**
00291   Clears the output device(s) display to the currently selected background
00292   color.
00293 
00294   @param  This              The protocol instance pointer.
00295 
00296   @retval  EFI_SUCCESS      The operation completed successfully.
00297   @retval  EFI_DEVICE_ERROR The device had an error and could not complete the request.
00298   @retval  EFI_UNSUPPORTED  The output device is not in a valid text mode.
00299 
00300 **/
00301 typedef
00302 EFI_STATUS
00303 (EFIAPI *EFI_TEXT_CLEAR_SCREEN)(
00304   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL   *This
00305   );
00306 
00307 /**
00308   Sets the current coordinates of the cursor position
00309 
00310   @param  This        The protocol instance pointer.
00311   @param  Column      The position to set the cursor to. Must be greater than or
00312                       equal to zero and less than the number of columns and rows
00313                       by QueryMode ().
00314   @param  Row         The position to set the cursor to. Must be greater than or
00315                       equal to zero and less than the number of columns and rows
00316                       by QueryMode ().
00317 
00318   @retval EFI_SUCCESS      The operation completed successfully.
00319   @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
00320   @retval EFI_UNSUPPORTED  The output device is not in a valid text mode, or the
00321                            cursor position is invalid for the current mode.
00322 
00323 **/
00324 typedef
00325 EFI_STATUS
00326 (EFIAPI *EFI_TEXT_SET_CURSOR_POSITION)(
00327   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00328   IN UINTN                                  Column,
00329   IN UINTN                                  Row
00330   );
00331 
00332 /**
00333   Makes the cursor visible or invisible
00334 
00335   @param  This    The protocol instance pointer.
00336   @param  Visible If TRUE, the cursor is set to be visible. If FALSE, the cursor is
00337                   set to be invisible.
00338 
00339   @retval EFI_SUCCESS      The operation completed successfully.
00340   @retval EFI_DEVICE_ERROR The device had an error and could not complete the
00341                            request, or the device does not support changing
00342                            the cursor mode.
00343   @retval EFI_UNSUPPORTED  The output device is not in a valid text mode.
00344 
00345 **/
00346 typedef
00347 EFI_STATUS
00348 (EFIAPI *EFI_TEXT_ENABLE_CURSOR)(
00349   IN EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL        *This,
00350   IN BOOLEAN                                Visible
00351   );
00352 
00353 /**
00354   @par Data Structure Description:
00355   Mode Structure pointed to by Simple Text Out protocol.
00356 **/
00357 typedef struct {
00358   ///
00359   /// The number of modes supported by QueryMode () and SetMode ().
00360   ///
00361   INT32   MaxMode;
00362 
00363   //
00364   // current settings
00365   //
00366 
00367   ///
00368   /// The text mode of the output device(s).
00369   ///
00370   INT32   Mode;
00371   ///
00372   /// The current character output attribute.
00373   ///
00374   INT32   Attribute;
00375   ///
00376   /// The cursor's column.
00377   ///
00378   INT32   CursorColumn;
00379   ///
00380   /// The cursor's row.
00381   ///
00382   INT32   CursorRow;
00383   ///
00384   /// The cursor is currently visbile or not.
00385   ///
00386   BOOLEAN CursorVisible;
00387 } EFI_SIMPLE_TEXT_OUTPUT_MODE;
00388 
00389 ///
00390 /// The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices.
00391 /// It is the minimum required protocol for any handle supplied as the ConsoleOut
00392 /// or StandardError device. In addition, the minimum supported text mode of such
00393 /// devices is at least 80 x 25 characters.
00394 ///
00395 struct _EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL {
00396   EFI_TEXT_RESET                Reset;
00397 
00398   EFI_TEXT_STRING               OutputString;
00399   EFI_TEXT_TEST_STRING          TestString;
00400 
00401   EFI_TEXT_QUERY_MODE           QueryMode;
00402   EFI_TEXT_SET_MODE             SetMode;
00403   EFI_TEXT_SET_ATTRIBUTE        SetAttribute;
00404 
00405   EFI_TEXT_CLEAR_SCREEN         ClearScreen;
00406   EFI_TEXT_SET_CURSOR_POSITION  SetCursorPosition;
00407   EFI_TEXT_ENABLE_CURSOR        EnableCursor;
00408 
00409   ///
00410   /// Pointer to SIMPLE_TEXT_OUTPUT_MODE data.
00411   ///
00412   EFI_SIMPLE_TEXT_OUTPUT_MODE   *Mode;
00413 };
00414 
00415 extern EFI_GUID gEfiSimpleTextOutProtocolGuid;
00416 
00417 #endif