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