IntelFrameworkModulePkg/Universal/Console/VgaClassDxe/VgaClass.h

   1 /** @file
   2   Internal include file of the VGA Class 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
  10 #ifndef _VGA_CLASS_H__
  11 #define _VGA_CLASS_H__
  12
  13 #include <FrameworkDxe.h>
  14
  15 #include <Protocol/SimpleTextOut.h>
  16 #include <Protocol/PciIo.h>
  17 #include <Protocol/VgaMiniPort.h>
  18 #include <Protocol/DevicePath.h>
  19
  20 #include <Library/DebugLib.h>
  21 #include <Library/UefiDriverEntryPoint.h>
  22 #include <Library/UefiLib.h>
  23 #include <Library/MemoryAllocationLib.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/ReportStatusCodeLib.h>
  26
  27 #include <IndustryStandard/Pci.h>
  28
  29 //
  30 // Global Variables
  31 //
  32 extern EFI_DRIVER_BINDING_PROTOCOL   gVgaClassDriverBinding;
  33 extern EFI_COMPONENT_NAME_PROTOCOL   gVgaClassComponentName;
  34 extern EFI_COMPONENT_NAME2_PROTOCOL  gVgaClassComponentName2;
  35
  36
  37 //
  38 // Structure for tuple containing mapping among uniocde, PC Ansi and ASCII code.
  39 //
  40 typedef struct {
  41   CHAR16  Unicode;
  42   CHAR8   PcAnsi;
  43   CHAR8   Ascii;
  44 } UNICODE_TO_CHAR;
  45
  46 //
  47 // VGA specific registers
  48 //
  49 #define CRTC_CURSOR_START         0xA
  50 #define CRTC_CURSOR_END           0xB
  51
  52 #define CRTC_CURSOR_LOCATION_HIGH 0xE
  53 #define CRTC_CURSOR_LOCATION_LOW  0xF
  54
  55 #define EFI_MAX_ATTRIBUTE         0x7f
  56
  57 //
  58 // VGA Class Device Structure
  59 //
  60 #define VGA_CLASS_DEV_SIGNATURE SIGNATURE_32 ('V', 'G', 'A', 'C')
  61
  62 typedef struct {
  63   UINTN                            Signature;
  64   EFI_HANDLE                       Handle;
  65   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  SimpleTextOut;
  66   EFI_SIMPLE_TEXT_OUTPUT_MODE      SimpleTextOutputMode;
  67   EFI_VGA_MINI_PORT_PROTOCOL       *VgaMiniPort;
  68   EFI_PCI_IO_PROTOCOL              *PciIo;
  69   EFI_DEVICE_PATH_PROTOCOL         *DevicePath;
  70 } VGA_CLASS_DEV;
  71
  72 #define VGA_CLASS_DEV_FROM_THIS(a)  CR (a, VGA_CLASS_DEV, SimpleTextOut, VGA_CLASS_DEV_SIGNATURE)
  73
  74 //
  75 // Driver Binding Protocol functions
  76 //
  77
  78 /**
  79   Tests to see if this driver supports a given controller.
  80
  81   This function implments EFI_DRIVER_BINDING_PROTOCOL.Supported().
  82   It Checks if this driver supports the controller specified. Any Controller
  83   with VgaMiniPort Protocol and Pci I/O protocol can be supported.
  84
  85   @param  This                A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  86   @param  ControllerHandle    Handle of device to test
  87   @param  RemainingDevicePath Optional parameter use to pick a specific child
  88                               device to start.
  89
  90   @retval EFI_SUCCESS         This driver supports this device.
  91   @retval EFI_ALREADY_STARTED This driver is already running on this device.
  92   @retval EFI_UNSUPPORTED     This driver does not support this device.
  93
  94 **/
  95 EFI_STATUS
  96 EFIAPI
  97 VgaClassDriverBindingSupported (
  98   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  99   IN EFI_HANDLE                   Controller,
 100   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 101   );
 102
 103 /**
 104   Starts the device controller.
 105
 106   This function implments EFI_DRIVER_BINDING_PROTOCOL.Start().
 107   It starts the device specified by Controller with the driver based on PCI I/O Protocol
 108   and VgaMiniPort Protocol. It creates context for device instance and install EFI_SIMPLE_TEXT_OUT_PROTOCOL.
 109
 110   @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 111   @param  ControllerHandle     Handle of device to bind driver to
 112   @param  RemainingDevicePath  Optional parameter use to pick a specific child
 113                                device to start.
 114
 115   @retval EFI_SUCCESS          The device was started.
 116   @retval other                Fail to start the device.
 117
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 VgaClassDriverBindingStart (
 122   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 123   IN EFI_HANDLE                   Controller,
 124   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 125   );
 126
 127 /**
 128   Starts the device controller.
 129
 130   This function implments EFI_DRIVER_BINDING_PROTOCOL.Stop().
 131   It stops this driver on Controller. Support stopping any child handles
 132   created by this driver.
 133
 134   @param  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 135   @param  ControllerHandle  A handle to the device being stopped.
 136   @param  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 137   @param  ChildHandleBuffer An array of child handles to be freed.
 138
 139   @retval EFI_SUCCESS       This driver is removed ControllerHandle
 140   @retval other             This driver was not removed from this device
 141
 142 **/
 143 EFI_STATUS
 144 EFIAPI
 145 VgaClassDriverBindingStop (
 146   IN  EFI_DRIVER_BINDING_PROTOCOL     *This,
 147   IN  EFI_HANDLE                      Controller,
 148   IN  UINTN                           NumberOfChildren,
 149   IN  EFI_HANDLE                      *ChildHandleBuffer OPTIONAL
 150   );
 151
 152 //
 153 // EFI Component Name Functions
 154 //
 155
 156 /**
 157   Retrieves a Unicode string that is the user readable name of the driver.
 158
 159   This function retrieves the user readable name of a driver in the form of a
 160   Unicode string. If the driver specified by This has a user readable name in
 161   the language specified by Language, then a pointer to the driver name is
 162   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 163   by This does not support the language specified by Language,
 164   then EFI_UNSUPPORTED is returned.
 165
 166   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 167                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 168   @param  Language              A pointer to a Null-terminated ASCII string
 169                                 array indicating the language. This is the
 170                                 language of the driver name that the caller is
 171                                 requesting, and it must match one of the
 172                                 languages specified in SupportedLanguages. The
 173                                 number of languages supported by a driver is up
 174                                 to the driver writer. Language is specified
 175                                 in RFC 4646 or ISO 639-2 language code format.
 176   @param  DriverName            A pointer to the Unicode string to return.
 177                                 This Unicode string is the name of the
 178                                 driver specified by This in the language
 179                                 specified by Language.
 180
 181   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 182                                 This and the language specified by Language was
 183                                 returned in DriverName.
 184   @retval EFI_INVALID_PARAMETER Language is NULL.
 185   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 186   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 187                                 the language specified by Language.
 188
 189 **/
 190 EFI_STATUS
 191 EFIAPI
 192 VgaClassComponentNameGetDriverName (
 193   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 194   IN  CHAR8                        *Language,
 195   OUT CHAR16                       **DriverName
 196   );
 197
 198 /**
 199   Retrieves a Unicode string that is the user readable name of the controller
 200   that is being managed by a driver.
 201
 202   This function retrieves the user readable name of the controller specified by
 203   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 204   driver specified by This has a user readable name in the language specified by
 205   Language, then a pointer to the controller name is returned in ControllerName,
 206   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 207   managing the controller specified by ControllerHandle and ChildHandle,
 208   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 209   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 210
 211   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 212                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 213   @param  ControllerHandle      The handle of a controller that the driver
 214                                 specified by This is managing.  This handle
 215                                 specifies the controller whose name is to be
 216                                 returned.
 217   @param  ChildHandle           The handle of the child controller to retrieve
 218                                 the name of.  This is an optional parameter that
 219                                 may be NULL.  It will be NULL for device
 220                                 drivers.  It will also be NULL for a bus drivers
 221                                 that wish to retrieve the name of the bus
 222                                 controller.  It will not be NULL for a bus
 223                                 driver that wishes to retrieve the name of a
 224                                 child controller.
 225   @param  Language              A pointer to a Null-terminated ASCII string
 226                                 array indicating the language.  This is the
 227                                 language of the driver name that the caller is
 228                                 requesting, and it must match one of the
 229                                 languages specified in SupportedLanguages. The
 230                                 number of languages supported by a driver is up
 231                                 to the driver writer. Language is specified in
 232                                 RFC 4646 or ISO 639-2 language code format.
 233   @param  ControllerName        A pointer to the Unicode string to return.
 234                                 This Unicode string is the name of the
 235                                 controller specified by ControllerHandle and
 236                                 ChildHandle in the language specified by
 237                                 Language from the point of view of the driver
 238                                 specified by This.
 239
 240   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 241                                 the language specified by Language for the
 242                                 driver specified by This was returned in
 243                                 DriverName.
 244   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 245   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 246                                 EFI_HANDLE.
 247   @retval EFI_INVALID_PARAMETER Language is NULL.
 248   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 249   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 250                                 managing the controller specified by
 251                                 ControllerHandle and ChildHandle.
 252   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 253                                 the language specified by Language.
 254
 255 **/
 256 EFI_STATUS
 257 EFIAPI
 258 VgaClassComponentNameGetControllerName (
 259   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 260   IN  EFI_HANDLE                                      ControllerHandle,
 261   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 262   IN  CHAR8                                           *Language,
 263   OUT CHAR16                                          **ControllerName
 264   );
 265
 266 //
 267 // Simple Text Output Protocol functions
 268 //
 269 /**
 270   Resets the text output device hardware.
 271
 272   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.Reset().
 273   It resets the text output device hardware. The cursor position is set to (0, 0),
 274   and the screen is cleared to the default background color for the output device.
 275
 276   @param  This                 Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 277   @param  ExtendedVerification Indicates that the driver may perform a more exhaustive
 278                                verification operation of the device during reset.
 279
 280   @retval EFI_SUCCESS          The text output device was reset.
 281   @retval EFI_DEVICE_ERROR     The text output device is not functioning correctly and could not be reset.
 282
 283 **/
 284 EFI_STATUS
 285 EFIAPI
 286 VgaClassReset (
 287   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL     *This,
 288   IN  BOOLEAN                             ExtendedVerification
 289   );
 290
 291 /**
 292   Writes a Unicode string to the output device.
 293
 294   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.OutputString().
 295   It writes a Unicode string to the output device. This is the most basic output mechanism
 296   on an output device.
 297
 298   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 299   @param  String                 The Null-terminated Unicode string to be displayed on the output device(s).
 300
 301   @retval EFI_SUCCESS            The string was output to the device.
 302   @retval EFI_DEVICE_ERROR       The device reported an error while attempting to output the text.
 303   @retval EFI_UNSUPPORTED        The output device's mode is not currently in a defined text mode.
 304   @retval EFI_WARN_UNKNOWN_GLYPH This warning code indicates that some of the characters in
 305                                  the Unicode string could not be rendered and were skipped.
 306 **/
 307 EFI_STATUS
 308 EFIAPI
 309 VgaClassOutputString (
 310   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 311   IN  CHAR16                          *String
 312   );
 313
 314 /**
 315   Verifies that all characters in a Unicode string can be output to the target device.
 316
 317   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.TestString().
 318   It verifies that all characters in a Unicode string can be output to the target device.
 319
 320   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 321   @param  String                 The Null-terminated Unicode string to be examined for the output device(s).
 322
 323   @retval EFI_SUCCESS            The device(s) are capable of rendering the output string.
 324   @retval EFI_UNSUPPORTED        Some of the characters in the Unicode string cannot be rendered by
 325                                  one or more of the output devices mapped by the EFI handle.
 326
 327 **/
 328 EFI_STATUS
 329 EFIAPI
 330 VgaClassTestString (
 331   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 332   IN  CHAR16                          *String
 333   );
 334
 335 /**
 336   Clears the output device(s) display to the currently selected background color.
 337
 338   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.ClearScreen().
 339   The ClearScreen() function clears the output device(s) display to the currently
 340   selected background color. The cursor position is set to (0, 0).
 341
 342   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 343
 344   @retval EFI_SUCESS             The operation completed successfully.
 345   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request.
 346   @retval EFI_UNSUPPORTED        The output device is not in a valid text mode.
 347
 348 **/
 349 EFI_STATUS
 350 EFIAPI
 351 VgaClassClearScreen (
 352   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL    *This
 353   );
 354
 355 /**
 356   Sets the background and foreground colors for theOutputString() and ClearScreen() functions.
 357
 358   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetAttribute().
 359   It sets the background and foreground colors for the OutputString() and ClearScreen() functions.
 360   The color mask can be set even when the device is in an invalid text mode.
 361   Devices supporting a different number of text colors are required to emulate the above colors
 362   to the best of the device's capabilities.
 363
 364   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 365   @param  Attribute              The attribute to set.
 366                                  Bits 0..3 are the foreground color,
 367                                  and bits 4..6 are the background color.
 368
 369   @retval EFI_SUCCESS            The requested attributes were set.
 370   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request.
 371
 372 **/
 373 EFI_STATUS
 374 EFIAPI
 375 VgaClassSetAttribute (
 376   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 377   IN  UINTN                           Attribute
 378   );
 379
 380 /**
 381   Sets the current coordinates of the cursor position.
 382
 383   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetCursorPosition().
 384   It sets the current coordinates of the cursor position.
 385   The upper left corner of the screen is defined as coordinate (0, 0).
 386
 387   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 388   @param  Column                 Column of position to set the cursor to.
 389   @param  Row                    Row of position to set the cursor to.
 390
 391   @retval EFI_SUCCESS            The operation completed successfully.
 392   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request.
 393   @retval EFI_UNSUPPORTED        The output device is not in a valid text mode, or the cursor
 394                                  position is invalid for the current mode.
 395
 396 **/
 397 EFI_STATUS
 398 EFIAPI
 399 VgaClassSetCursorPosition (
 400   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 401   IN  UINTN                           Column,
 402   IN  UINTN                           Row
 403   );
 404
 405 /**
 406   Makes the cursor visible or invisible.
 407
 408   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.EnableCursor().
 409   It makes the cursor visible or invisible.
 410
 411   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 412   @param  Visible                If TRUE, the cursor is set to be visible.
 413                                  If FALSE, the cursor is set to be invisible.
 414
 415   @retval EFI_SUCESS             The operation completed successfully.
 416   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request or the
 417                                  device does not support changing the cursor mode.
 418   @retval EFI_UNSUPPORTED        The output device does not support visibility control of the cursor.
 419
 420 **/
 421 EFI_STATUS
 422 EFIAPI
 423 VgaClassEnableCursor (
 424   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 425   IN  BOOLEAN                         Visible
 426   );
 427
 428 /**
 429   Returns information for an available text mode that the output device(s) supports.
 430
 431   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.QueryMode().
 432   It returns information for an available text mode that the output device(s) supports.
 433   It is required that all output devices support at least 80x25 text mode. This mode is defined to be mode 0.
 434   If the output devices support 80x50, that is defined to be mode 1.
 435
 436   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 437   @param  ModeNumber             The mode number to return information on.
 438   @param  Columns                Columen in current mode number
 439   @param  Rows                   Row in current mode number.
 440
 441   @retval EFI_SUCCESS            The requested mode information was returned.
 442   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request.
 443   @retval EFI_UNSUPPORTED        The mode number was not valid.
 444
 445 **/
 446 EFI_STATUS
 447 EFIAPI
 448 VgaClassQueryMode (
 449   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 450   IN  UINTN                           ModeNumber,
 451   OUT UINTN                           *Columns,
 452   OUT UINTN                           *Rows
 453   );
 454
 455 /**
 456   Sets the output device(s) to a specified mode.
 457
 458   This function implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.QueryMode().
 459   It sets the output device(s) to the requested mode.
 460   On success the device is in the geometry for the requested mode,
 461   and the device has been cleared to the current background color with the cursor at (0,0).
 462
 463   @param  This                   Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL instance.
 464   @param  ModeNumber             The text mode to set.
 465
 466   @retval EFI_SUCCESS            The requested text mode was set.
 467   @retval EFI_DEVICE_ERROR       The device had an error and could not complete the request.
 468   @retval EFI_UNSUPPORTED        The mode number was not valid.
 469
 470 **/
 471 EFI_STATUS
 472 EFIAPI
 473 VgaClassSetMode (
 474   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 475   IN  UINTN                           ModeNumber
 476   );
 477
 478 #endif