MdeModulePkg/Universal/Console/GraphicsConsoleDxe/GraphicsConsole.h

   1 /** @file
   2   Header file for GraphicsConsole driver.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _GRAPHICS_CONSOLE_H_
  10 #define _GRAPHICS_CONSOLE_H_
  11
  12 #include <Uefi.h>
  13 #include <Protocol/SimpleTextOut.h>
  14 #include <Protocol/GraphicsOutput.h>
  15 #include <Protocol/UgaDraw.h>
  16 #include <Protocol/DevicePath.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/UefiDriverEntryPoint.h>
  19 #include <Library/UefiLib.h>
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/MemoryAllocationLib.h>
  22 #include <Library/UefiBootServicesTableLib.h>
  23 #include <Library/HiiLib.h>
  24 #include <Library/BaseLib.h>
  25 #include <Library/PcdLib.h>
  26
  27 #include <Guid/MdeModuleHii.h>
  28
  29 #include <Protocol/HiiFont.h>
  30 #include <Protocol/HiiDatabase.h>
  31
  32
  33 extern EFI_COMPONENT_NAME_PROTOCOL   gGraphicsConsoleComponentName;
  34 extern EFI_COMPONENT_NAME2_PROTOCOL  gGraphicsConsoleComponentName2;
  35 extern EFI_DRIVER_BINDING_PROTOCOL   gGraphicsConsoleDriverBinding;
  36 extern EFI_NARROW_GLYPH              gUsStdNarrowGlyphData[];
  37
  38 extern UINT32 mNarrowFontSize;
  39
  40 typedef union {
  41   EFI_NARROW_GLYPH  NarrowGlyph;
  42   EFI_WIDE_GLYPH    WideGlyph;
  43 } GLYPH_UNION;
  44
  45 //
  46 // Device Structure
  47 //
  48 #define GRAPHICS_CONSOLE_DEV_SIGNATURE  SIGNATURE_32 ('g', 's', 't', 'o')
  49
  50 typedef struct {
  51   UINTN   Columns;
  52   UINTN   Rows;
  53   INTN    DeltaX;
  54   INTN    DeltaY;
  55   UINT32  GopWidth;
  56   UINT32  GopHeight;
  57   UINT32  GopModeNumber;
  58 } GRAPHICS_CONSOLE_MODE_DATA;
  59
  60 typedef struct {
  61   UINTN                            Signature;
  62   EFI_GRAPHICS_OUTPUT_PROTOCOL     *GraphicsOutput;
  63   EFI_UGA_DRAW_PROTOCOL            *UgaDraw;
  64   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  SimpleTextOutput;
  65   EFI_SIMPLE_TEXT_OUTPUT_MODE      SimpleTextOutputMode;
  66   GRAPHICS_CONSOLE_MODE_DATA       *ModeData;
  67   EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *LineBuffer;
  68 } GRAPHICS_CONSOLE_DEV;
  69
  70 #define GRAPHICS_CONSOLE_CON_OUT_DEV_FROM_THIS(a) \
  71   CR (a, GRAPHICS_CONSOLE_DEV, SimpleTextOutput, GRAPHICS_CONSOLE_DEV_SIGNATURE)
  72
  73
  74 //
  75 // EFI Component Name Functions
  76 //
  77 /**
  78   Retrieves a Unicode string that is the user readable name of the driver.
  79
  80   This function retrieves the user readable name of a driver in the form of a
  81   Unicode string. If the driver specified by This has a user readable name in
  82   the language specified by Language, then a pointer to the driver name is
  83   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  84   by This does not support the language specified by Language,
  85   then EFI_UNSUPPORTED is returned.
  86
  87   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  88                                 EFI_COMPONENT_NAME_PROTOCOL instance.
  89
  90   @param  Language[in]          A pointer to a Null-terminated ASCII string
  91                                 array indicating the language. This is the
  92                                 language of the driver name that the caller is
  93                                 requesting, and it must match one of the
  94                                 languages specified in SupportedLanguages. The
  95                                 number of languages supported by a driver is up
  96                                 to the driver writer. Language is specified
  97                                 in RFC 4646 or ISO 639-2 language code format.
  98
  99   @param  DriverName[out]       A pointer to the Unicode string to return.
 100                                 This Unicode string is the name of the
 101                                 driver specified by This in the language
 102                                 specified by Language.
 103
 104   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 105                                 This and the language specified by Language was
 106                                 returned in DriverName.
 107
 108   @retval EFI_INVALID_PARAMETER Language is NULL.
 109
 110   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 111
 112   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 113                                 the language specified by Language.
 114
 115 **/
 116 EFI_STATUS
 117 EFIAPI
 118 GraphicsConsoleComponentNameGetDriverName (
 119   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 120   IN  CHAR8                        *Language,
 121   OUT CHAR16                       **DriverName
 122   );
 123
 124
 125 /**
 126   Retrieves a Unicode string that is the user readable name of the controller
 127   that is being managed by a driver.
 128
 129   This function retrieves the user readable name of the controller specified by
 130   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 131   driver specified by This has a user readable name in the language specified by
 132   Language, then a pointer to the controller name is returned in ControllerName,
 133   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 134   managing the controller specified by ControllerHandle and ChildHandle,
 135   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 136   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 137
 138   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 139                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 140
 141   @param  ControllerHandle[in]  The handle of a controller that the driver
 142                                 specified by This is managing.  This handle
 143                                 specifies the controller whose name is to be
 144                                 returned.
 145
 146   @param  ChildHandle[in]       The handle of the child controller to retrieve
 147                                 the name of.  This is an optional parameter that
 148                                 may be NULL.  It will be NULL for device
 149                                 drivers.  It will also be NULL for a bus drivers
 150                                 that wish to retrieve the name of the bus
 151                                 controller.  It will not be NULL for a bus
 152                                 driver that wishes to retrieve the name of a
 153                                 child controller.
 154
 155   @param  Language[in]          A pointer to a Null-terminated ASCII string
 156                                 array indicating the language.  This is the
 157                                 language of the driver name that the caller is
 158                                 requesting, and it must match one of the
 159                                 languages specified in SupportedLanguages. The
 160                                 number of languages supported by a driver is up
 161                                 to the driver writer. Language is specified in
 162                                 RFC 4646 or ISO 639-2 language code format.
 163
 164   @param  ControllerName[out]   A pointer to the Unicode string to return.
 165                                 This Unicode string is the name of the
 166                                 controller specified by ControllerHandle and
 167                                 ChildHandle in the language specified by
 168                                 Language from the point of view of the driver
 169                                 specified by This.
 170
 171   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 172                                 the language specified by Language for the
 173                                 driver specified by This was returned in
 174                                 DriverName.
 175
 176   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 177
 178   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 179                                 EFI_HANDLE.
 180
 181   @retval EFI_INVALID_PARAMETER Language is NULL.
 182
 183   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 184
 185   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 186                                 managing the controller specified by
 187                                 ControllerHandle and ChildHandle.
 188
 189   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 190                                 the language specified by Language.
 191
 192 **/
 193 EFI_STATUS
 194 EFIAPI
 195 GraphicsConsoleComponentNameGetControllerName (
 196   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 197   IN  EFI_HANDLE                                      ControllerHandle,
 198   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 199   IN  CHAR8                                           *Language,
 200   OUT CHAR16                                          **ControllerName
 201   );
 202
 203
 204 /**
 205   Reset the text output device hardware and optionally run diagnostics.
 206
 207   Implements SIMPLE_TEXT_OUTPUT.Reset().
 208   If ExtendedVerification is TRUE, then perform dependent Graphics Console
 209   device reset, and set display mode to mode 0.
 210   If ExtendedVerification is FALSE, only set display mode to mode 0.
 211
 212   @param  This                  Protocol instance pointer.
 213   @param  ExtendedVerification  Indicates that the driver may perform a more
 214                                 exhaustive verification operation of the device
 215                                 during reset.
 216
 217   @retval EFI_SUCCESS          The text output device was reset.
 218   @retval EFI_DEVICE_ERROR     The text output device is not functioning correctly and
 219                                could not be reset.
 220
 221 **/
 222 EFI_STATUS
 223 EFIAPI
 224 GraphicsConsoleConOutReset (
 225   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL    *This,
 226   IN  BOOLEAN                            ExtendedVerification
 227   );
 228
 229 /**
 230   Write a Unicode string to the output device.
 231
 232   Implements SIMPLE_TEXT_OUTPUT.OutputString().
 233   The Unicode string will be converted to Glyphs and will be
 234   sent to the Graphics Console.
 235
 236   @param  This                    Protocol instance pointer.
 237   @param  WString                 The NULL-terminated Unicode string to be displayed
 238                                   on the output device(s). All output devices must
 239                                   also support the Unicode drawing defined in this file.
 240
 241   @retval EFI_SUCCESS             The string was output to the device.
 242   @retval EFI_DEVICE_ERROR        The device reported an error while attempting to output
 243                                   the text.
 244   @retval EFI_UNSUPPORTED         The output device's mode is not currently in a
 245                                   defined text mode.
 246   @retval EFI_WARN_UNKNOWN_GLYPH  This warning code indicates that some of the
 247                                   characters in the Unicode string could not be
 248                                   rendered and were skipped.
 249
 250 **/
 251 EFI_STATUS
 252 EFIAPI
 253 GraphicsConsoleConOutOutputString (
 254   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 255   IN  CHAR16                           *WString
 256   );
 257
 258 /**
 259   Verifies that all characters in a Unicode string can be output to the
 260   target device.
 261
 262   Implements SIMPLE_TEXT_OUTPUT.TestString().
 263   If one of the characters in the *Wstring is neither valid valid Unicode
 264   drawing characters, not ASCII code, then this function will return
 265   EFI_UNSUPPORTED
 266
 267   @param  This    Protocol instance pointer.
 268   @param  WString The NULL-terminated Unicode string to be examined for the output
 269                   device(s).
 270
 271   @retval EFI_SUCCESS      The device(s) are capable of rendering the output string.
 272   @retval EFI_UNSUPPORTED  Some of the characters in the Unicode string cannot be
 273                            rendered by one or more of the output devices mapped
 274                            by the EFI handle.
 275
 276 **/
 277 EFI_STATUS
 278 EFIAPI
 279 GraphicsConsoleConOutTestString (
 280   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 281   IN  CHAR16                           *WString
 282   );
 283
 284 /**
 285   Returns information for an available text mode that the output device(s)
 286   supports
 287
 288   Implements SIMPLE_TEXT_OUTPUT.QueryMode().
 289   It returns information for an available text mode that the Graphics Console supports.
 290   In this driver,we only support text mode 80x25, which is defined as mode 0.
 291
 292   @param  This                  Protocol instance pointer.
 293   @param  ModeNumber            The mode number to return information on.
 294   @param  Columns               The returned columns of the requested mode.
 295   @param  Rows                  The returned rows of the requested mode.
 296
 297   @retval EFI_SUCCESS           The requested mode information is returned.
 298   @retval EFI_UNSUPPORTED       The mode number is not valid.
 299
 300 **/
 301 EFI_STATUS
 302 EFIAPI
 303 GraphicsConsoleConOutQueryMode (
 304   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 305   IN  UINTN                            ModeNumber,
 306   OUT UINTN                            *Columns,
 307   OUT UINTN                            *Rows
 308   );
 309
 310
 311 /**
 312   Sets the output device(s) to a specified mode.
 313
 314   Implements SIMPLE_TEXT_OUTPUT.SetMode().
 315   Set the Graphics Console to a specified mode. In this driver, we only support mode 0.
 316
 317   @param  This                  Protocol instance pointer.
 318   @param  ModeNumber            The text mode to set.
 319
 320   @retval EFI_SUCCESS           The requested text mode is set.
 321   @retval EFI_DEVICE_ERROR      The requested text mode cannot be set because of
 322                                 Graphics Console device error.
 323   @retval EFI_UNSUPPORTED       The text mode number is not valid.
 324
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 GraphicsConsoleConOutSetMode (
 329   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 330   IN  UINTN                            ModeNumber
 331   );
 332
 333 /**
 334   Sets the background and foreground colors for the OutputString () and
 335   ClearScreen () functions.
 336
 337   Implements SIMPLE_TEXT_OUTPUT.SetAttribute().
 338
 339   @param  This                  Protocol instance pointer.
 340   @param  Attribute             The attribute to set. Bits 0..3 are the foreground
 341                                 color, and bits 4..6 are the background color.
 342                                 All other bits are undefined and must be zero.
 343
 344   @retval EFI_SUCCESS           The requested attribute is set.
 345   @retval EFI_DEVICE_ERROR      The requested attribute cannot be set due to Graphics Console port error.
 346   @retval EFI_UNSUPPORTED       The attribute requested is not defined.
 347
 348 **/
 349 EFI_STATUS
 350 EFIAPI
 351 GraphicsConsoleConOutSetAttribute (
 352   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 353   IN  UINTN                            Attribute
 354   );
 355
 356 /**
 357   Clears the output device(s) display to the currently selected background
 358   color.
 359
 360   Implements SIMPLE_TEXT_OUTPUT.ClearScreen().
 361
 362   @param  This                  Protocol instance pointer.
 363
 364   @retval  EFI_SUCCESS      The operation completed successfully.
 365   @retval  EFI_DEVICE_ERROR The device had an error and could not complete the request.
 366   @retval  EFI_UNSUPPORTED  The output device is not in a valid text mode.
 367
 368 **/
 369 EFI_STATUS
 370 EFIAPI
 371 GraphicsConsoleConOutClearScreen (
 372   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This
 373   );
 374
 375 /**
 376   Sets the current coordinates of the cursor position.
 377
 378   Implements SIMPLE_TEXT_OUTPUT.SetCursorPosition().
 379
 380   @param  This        Protocol instance pointer.
 381   @param  Column      The position to set the cursor to. Must be greater than or
 382                       equal to zero and less than the number of columns and rows
 383                       by QueryMode ().
 384   @param  Row         The position to set the cursor to. Must be greater than or
 385                       equal to zero and less than the number of columns and rows
 386                       by QueryMode ().
 387
 388   @retval EFI_SUCCESS      The operation completed successfully.
 389   @retval EFI_DEVICE_ERROR The device had an error and could not complete the request.
 390   @retval EFI_UNSUPPORTED  The output device is not in a valid text mode, or the
 391                            cursor position is invalid for the current mode.
 392
 393 **/
 394 EFI_STATUS
 395 EFIAPI
 396 GraphicsConsoleConOutSetCursorPosition (
 397   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 398   IN  UINTN                            Column,
 399   IN  UINTN                            Row
 400   );
 401
 402
 403 /**
 404   Makes the cursor visible or invisible.
 405
 406   Implements SIMPLE_TEXT_OUTPUT.EnableCursor().
 407
 408   @param  This                  Protocol instance pointer.
 409   @param  Visible               If TRUE, the cursor is set to be visible, If FALSE,
 410                                 the cursor is set to be invisible.
 411
 412   @retval EFI_SUCCESS           The operation completed successfully.
 413
 414 **/
 415 EFI_STATUS
 416 EFIAPI
 417 GraphicsConsoleConOutEnableCursor (
 418   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 419   IN  BOOLEAN                          Visible
 420   );
 421
 422 /**
 423   Test to see if Graphics Console could be supported on the Controller.
 424
 425   Graphics Console could be supported if Graphics Output Protocol or UGADraw
 426   Protocol exists on the Controller. (UGA Draw Protocol could be skipped
 427   if PcdUgaConsumeSupport is set to FALSE.)
 428
 429   @param  This                Protocol instance pointer.
 430   @param  Controller          Handle of device to test.
 431   @param  RemainingDevicePath Optional parameter use to pick a specific child
 432                               device to start.
 433
 434   @retval EFI_SUCCESS         This driver supports this device.
 435   @retval other               This driver does not support this device.
 436
 437 **/
 438 EFI_STATUS
 439 EFIAPI
 440 GraphicsConsoleControllerDriverSupported (
 441   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 442   IN EFI_HANDLE                     Controller,
 443   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 444   );
 445
 446
 447 /**
 448   Start this driver on Controller by opening Graphics Output protocol or
 449   UGA Draw protocol, and installing Simple Text Out protocol on Controller.
 450   (UGA Draw protocol could be skipped if PcdUgaConsumeSupport is set to FALSE.)
 451
 452   @param  This                 Protocol instance pointer.
 453   @param  Controller           Handle of device to bind driver to
 454   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 455                                device to start.
 456
 457   @retval EFI_SUCCESS          This driver is added to Controller.
 458   @retval other                This driver does not support this device.
 459
 460 **/
 461 EFI_STATUS
 462 EFIAPI
 463 GraphicsConsoleControllerDriverStart (
 464   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 465   IN EFI_HANDLE                     Controller,
 466   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 467   );
 468
 469 /**
 470   Stop this driver on Controller by removing Simple Text Out protocol
 471   and closing the Graphics Output Protocol or UGA Draw protocol on Controller.
 472   (UGA Draw protocol could be skipped if PcdUgaConsumeSupport is set to FALSE.)
 473
 474
 475   @param  This              Protocol instance pointer.
 476   @param  Controller        Handle of device to stop driver on
 477   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
 478                             children is zero stop the entire bus driver.
 479   @param  ChildHandleBuffer List of Child Handles to Stop.
 480
 481   @retval EFI_SUCCESS       This driver is removed Controller.
 482   @retval EFI_NOT_STARTED   Simple Text Out protocol could not be found the
 483                             Controller.
 484   @retval other             This driver was not removed from this device.
 485
 486 **/
 487 EFI_STATUS
 488 EFIAPI
 489 GraphicsConsoleControllerDriverStop (
 490   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 491   IN  EFI_HANDLE                     Controller,
 492   IN  UINTN                          NumberOfChildren,
 493   IN  EFI_HANDLE                     *ChildHandleBuffer
 494   );
 495
 496
 497 /**
 498   Locate HII Database protocol and HII Font protocol.
 499
 500   @retval  EFI_SUCCESS     HII Database protocol and HII Font protocol
 501                            are located successfully.
 502   @return  other           Failed to locate HII Database protocol or
 503                            HII Font protocol.
 504
 505 **/
 506 EFI_STATUS
 507 EfiLocateHiiProtocol (
 508   VOID
 509   );
 510
 511
 512 /**
 513   Gets Graphics Console device's foreground color and background color.
 514
 515   @param  This                  Protocol instance pointer.
 516   @param  Foreground            Returned text foreground color.
 517   @param  Background            Returned text background color.
 518
 519   @retval EFI_SUCCESS           It returned always.
 520
 521 **/
 522 EFI_STATUS
 523 GetTextColors (
 524   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 525   OUT EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *Foreground,
 526   OUT EFI_GRAPHICS_OUTPUT_BLT_PIXEL    *Background
 527   );
 528
 529 /**
 530   Draw Unicode string on the Graphics Console device's screen.
 531
 532   @param  This                  Protocol instance pointer.
 533   @param  UnicodeWeight         One Unicode string to be displayed.
 534   @param  Count                 The count of Unicode string.
 535
 536   @retval EFI_OUT_OF_RESOURCES  If no memory resource to use.
 537   @retval EFI_UNSUPPORTED       If no Graphics Output protocol and UGA Draw
 538                                 protocol exist.
 539   @retval EFI_SUCCESS           Drawing Unicode string implemented successfully.
 540
 541 **/
 542 EFI_STATUS
 543 DrawUnicodeWeightAtCursorN (
 544   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 545   IN  CHAR16                           *UnicodeWeight,
 546   IN  UINTN                            Count
 547   );
 548
 549 /**
 550   Flush the cursor on the screen.
 551
 552   If CursorVisible is FALSE, nothing to do and return directly.
 553   If CursorVisible is TRUE,
 554      i) If the cursor shows on screen, it will be erased.
 555     ii) If the cursor does not show on screen, it will be shown.
 556
 557   @param  This                  Protocol instance pointer.
 558
 559   @retval EFI_SUCCESS           The cursor is erased successfully.
 560
 561 **/
 562 EFI_STATUS
 563 FlushCursor (
 564   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This
 565   );
 566
 567 /**
 568   Check if the current specific mode supported the user defined resolution
 569   for the Graphics Console device based on Graphics Output Protocol.
 570
 571   If yes, set the graphic device's current mode to this specific mode.
 572
 573   @param  GraphicsOutput        Graphics Output Protocol instance pointer.
 574   @param  HorizontalResolution  User defined horizontal resolution
 575   @param  VerticalResolution    User defined vertical resolution.
 576   @param  CurrentModeNumber     Current specific mode to be check.
 577
 578   @retval EFI_SUCCESS       The mode is supported.
 579   @retval EFI_UNSUPPORTED   The specific mode is out of range of graphics
 580                             device supported.
 581   @retval other             The specific mode does not support user defined
 582                             resolution or failed to set the current mode to the
 583                             specific mode on graphics device.
 584
 585 **/
 586 EFI_STATUS
 587 CheckModeSupported (
 588   EFI_GRAPHICS_OUTPUT_PROTOCOL  *GraphicsOutput,
 589   IN  UINT32  HorizontalResolution,
 590   IN  UINT32  VerticalResolution,
 591   OUT UINT32  *CurrentModeNumber
 592   );
 593
 594 #endif