ShellPkg/Application/Shell/ConsoleLogger.h

   1 /** @file
   2   Provides interface to shell console logger.
   3
   4   Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12 **/
  13
  14 #ifndef _CONSOLE_LOGGER_HEADER_
  15 #define _CONSOLE_LOGGER_HEADER_
  16
  17 #include <Uefi.h>
  18
  19 #include <Protocol/SimpleTextOut.h>
  20 #include <Protocol/EfiShell.h>
  21 #include <Protocol/EfiShellParameters.h>
  22
  23 #include <Library/DebugLib.h>
  24 #include <Library/BaseLib.h>
  25 #include <Library/BaseMemoryLib.h>
  26 #include <Library/MemoryAllocationLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/HiiLib.h>
  29 #include <Library/ShellLib.h>
  30
  31 #define CONSOLE_LOGGER_PRIVATE_DATA_SIGNATURE  SIGNATURE_32 ('c', 'o', 'P', 'D')
  32
  33 typedef struct _CONSOLE_LOGGER_PRIVATE_DATA{
  34   UINTN                             Signature;
  35   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL   OurConOut;        ///< the protocol we installed onto the system table
  36   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL   *OldConOut;       ///< old protocol to reinstall upon exiting
  37   EFI_HANDLE                        OldConHandle;     ///< old protocol handle
  38   UINTN                             ScreenCount;      ///< How many screens worth of data to save
  39   CHAR16                            *Buffer;          ///< Buffer to save data
  40   UINTN                             BufferSize;       ///< size of buffer in bytes
  41
  42                                                       //  start row is the top of the screen
  43   UINTN                             OriginalStartRow; ///< What the originally visible start row was
  44   UINTN                             CurrentStartRow;  ///< what the currently visible start row is
  45
  46   UINTN                             RowsPerScreen;    ///< how many rows the screen can display
  47   UINTN                             ColsPerScreen;    ///< how many columns the screen can display
  48
  49   INT32                             *Attributes;      ///< Buffer for Attribute to be saved for each character
  50   UINTN                             AttribSize;       ///< Size of Attributes in bytes
  51
  52   EFI_SIMPLE_TEXT_OUTPUT_MODE       HistoryMode;      ///< mode of the history log
  53   BOOLEAN                           Enabled;          ///< Set to FALSE when a break is requested.
  54   UINTN                             RowCounter;       ///< Initial row of each print job.
  55 } CONSOLE_LOGGER_PRIVATE_DATA;
  56
  57 #define CONSOLE_LOGGER_PRIVATE_DATA_FROM_THIS(a) CR (a, CONSOLE_LOGGER_PRIVATE_DATA, OurConOut, CONSOLE_LOGGER_PRIVATE_DATA_SIGNATURE)
  58
  59 /**
  60   Install our intermediate ConOut into the system table to
  61   keep a log of all the info that is displayed to the user.
  62
  63   @param[in] ScreensToSave  Sets how many screen-worths of data to save.
  64   @param[out] ConsoleInfo   The object to pass into later functions.
  65
  66   @retval EFI_SUCCESS       The operation was successful.
  67   @return other             The operation failed.
  68
  69   @sa ConsoleLoggerResetBuffers
  70   @sa InstallProtocolInterface
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 ConsoleLoggerInstall(
  75   IN CONST UINTN ScreensToSave,
  76   OUT CONSOLE_LOGGER_PRIVATE_DATA **ConsoleInfo
  77   );
  78
  79 /**
  80   Return the system to the state it was before InstallConsoleLogger
  81   was installed.
  82
  83   @param[in,out] ConsoleInfo   The object from the install function.
  84
  85   @retval EFI_SUCCESS     The operation was successful
  86   @return other           The operation failed.  This was from UninstallProtocolInterface.
  87 **/
  88 EFI_STATUS
  89 EFIAPI
  90 ConsoleLoggerUninstall(
  91   IN OUT CONSOLE_LOGGER_PRIVATE_DATA *ConsoleInfo
  92   );
  93
  94 /**
  95   Displays previously logged output back to the screen.
  96
  97   This will scroll the screen forwards and backwards through the log of previous
  98   output.  If Rows is 0 then the size of 1/2 the screen will be scrolled.  If Rows
  99   is (UINTN)(-1) then the size of the screen will be scrolled.
 100
 101   @param[in] Forward      If TRUE then the log will be displayed forwards (scroll to newer).
 102                           If FALSE then the log will be displayed backwards (scroll to older).
 103   @param[in] Rows         Determines how many rows the log should scroll.
 104   @param[in] ConsoleInfo  The pointer to the instance of the console logger information.
 105 **/
 106 EFI_STATUS
 107 EFIAPI
 108 ConsoleLoggerDisplayHistory(
 109   IN CONST BOOLEAN  Forward,
 110   IN CONST UINTN    Rows,
 111   IN CONSOLE_LOGGER_PRIVATE_DATA *ConsoleInfo
 112   );
 113
 114 /**
 115   Function to return to normal output whent he scrolling is complete.
 116   @param[in] ConsoleInfo  The pointer to the instance of the console logger information.
 117
 118   @retval EFI_SUCCESS   The operation was successful.
 119   @return other         The operation failed.  See UpdateDisplayFromHistory.
 120
 121   @sa UpdateDisplayFromHistory
 122 **/
 123 EFI_STATUS
 124 EFIAPI
 125 ConsoleLoggerStopHistory(
 126   IN CONSOLE_LOGGER_PRIVATE_DATA *ConsoleInfo
 127   );
 128
 129 /**
 130   Updates the hidden ConOut to be displaying the correct stuff.
 131   @param[in] ConsoleInfo  The pointer to the instance of the console logger information.
 132
 133   @retval EFI_SUCCESS     The operation was successful.
 134   @return other           The operation failed.
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 UpdateDisplayFromHistory(
 139   IN CONSOLE_LOGGER_PRIVATE_DATA *ConsoleInfo
 140   );
 141
 142 /**
 143   Reset the text output device hardware and optionaly run diagnostics
 144
 145   @param This                 Pointer to EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL
 146   @param ExtendedVerification Indicates that a more extensive test may be performed
 147
 148   @retval EFI_SUCCESS         The text output device was reset.
 149   @retval EFI_DEVICE_ERROR    The text output device is not functioning correctly and
 150                               could not be reset.
 151 **/
 152 EFI_STATUS
 153 EFIAPI
 154 ConsoleLoggerReset (
 155   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 156   IN  BOOLEAN                         ExtendedVerification
 157   );
 158
 159 /**
 160   Write a Unicode string to the output device.
 161
 162   @param[in] This                 Protocol instance pointer.
 163   @param[in] WString              The NULL-terminated Unicode string to be displayed on the output
 164                                   device(s). All output devices must also support the Unicode
 165                                   drawing defined in this file.
 166   @retval EFI_SUCCESS             The string was output to the device.
 167   @retval EFI_DEVICE_ERROR        The device reported an error while attempting to output
 168                                   the text.
 169   @retval EFI_UNSUPPORTED         The output device's mode is not currently in a
 170                                   defined text mode.
 171   @retval EFI_WARN_UNKNOWN_GLYPH  This warning code indicates that some of the
 172                                   characters in the Unicode string could not be
 173                                   rendered and were skipped.
 174 **/
 175 EFI_STATUS
 176 EFIAPI
 177 ConsoleLoggerOutputString(
 178   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 179   IN  CHAR16                          *WString
 180   );
 181
 182 /**
 183   Verifies that all characters in a Unicode string can be output to the
 184   target device.
 185
 186   @param[in] This     Protocol instance pointer.
 187   @param[in] WString  The NULL-terminated Unicode string to be examined for the output
 188                       device(s).
 189
 190   @retval EFI_SUCCESS           The device(s) are capable of rendering the output string.
 191   @retval EFI_UNSUPPORTED       Some of the characters in the Unicode string cannot be
 192                                 rendered by one or more of the output devices mapped
 193                                 by the EFI handle.
 194
 195 **/
 196 EFI_STATUS
 197 EFIAPI
 198 ConsoleLoggerTestString (
 199   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 200   IN  CHAR16                          *WString
 201   );
 202
 203 /**
 204   Returns information for an available text mode that the output device(s)
 205   supports.
 206
 207   @param[in] This               Protocol instance pointer.
 208   @param[in] ModeNumber         The mode number to return information on.
 209   @param[out] Columns           Upon return, the number of columns in the selected geometry
 210   @param[out] Rows              Upon return, the number of rows in the selected geometry
 211
 212   @retval EFI_SUCCESS           The requested mode information was returned.
 213   @retval EFI_DEVICE_ERROR      The device had an error and could not
 214                                 complete the request.
 215   @retval EFI_UNSUPPORTED       The mode number was not valid.
 216 **/
 217 EFI_STATUS
 218 EFIAPI
 219 ConsoleLoggerQueryMode (
 220   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 221   IN  UINTN                            ModeNumber,
 222   OUT UINTN                            *Columns,
 223   OUT UINTN                            *Rows
 224   );
 225
 226 /**
 227   Sets the output device(s) to a specified mode.
 228
 229   @param[in] This               Protocol instance pointer.
 230   @param[in] ModeNumber         The mode number to set.
 231
 232
 233   @retval EFI_SUCCESS           The requested text mode was set.
 234   @retval EFI_DEVICE_ERROR      The device had an error and
 235                                 could not complete the request.
 236   @retval EFI_UNSUPPORTED       The mode number was not valid.
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 ConsoleLoggerSetMode (
 241   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 242   IN  UINTN                            ModeNumber
 243   );
 244
 245 /**
 246   Sets the background and foreground colors for the OutputString () and
 247   ClearScreen () functions.
 248
 249   @param[in] This               Protocol instance pointer.
 250   @param[in] Attribute          The attribute to set. Bits 0..3 are the foreground color, and
 251                                 bits 4..6 are the background color. All other bits are undefined
 252                                 and must be zero. The valid Attributes are defined in this file.
 253
 254   @retval EFI_SUCCESS           The attribute was set.
 255   @retval EFI_DEVICE_ERROR      The device had an error and
 256                                 could not complete the request.
 257   @retval EFI_UNSUPPORTED       The attribute requested is not defined.
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 ConsoleLoggerSetAttribute (
 263   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL *This,
 264   IN  UINTN                           Attribute
 265   );
 266
 267 /**
 268   Clears the output device(s) display to the currently selected background
 269   color.
 270
 271   @param[in] This               Protocol instance pointer.
 272
 273   @retval EFI_SUCCESS           The operation completed successfully.
 274   @retval EFI_DEVICE_ERROR      The device had an error and
 275                                 could not complete the request.
 276   @retval EFI_UNSUPPORTED       The output device is not in a valid text mode.
 277 **/
 278 EFI_STATUS
 279 EFIAPI
 280 ConsoleLoggerClearScreen (
 281   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This
 282   );
 283
 284 /**
 285   Sets the current coordinates of the cursor position.
 286
 287   @param[in] This               Protocol instance pointer.
 288   @param[in] Column             Column to put the cursor in.  Must be between zero and Column returned from QueryMode
 289   @param[in] Row                Row to put the cursor in.  Must be between zero and Row returned from QueryMode
 290
 291   @retval EFI_SUCCESS           The operation completed successfully.
 292   @retval EFI_DEVICE_ERROR      The device had an error and
 293                                 could not complete the request.
 294   @retval EFI_UNSUPPORTED       The output device is not in a valid text mode, or the
 295                                 cursor position is invalid for the current mode.
 296 **/
 297 EFI_STATUS
 298 EFIAPI
 299 ConsoleLoggerSetCursorPosition (
 300   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 301   IN  UINTN                         Column,
 302   IN  UINTN                         Row
 303   );
 304
 305 /**
 306     Makes the cursor visible or invisible
 307
 308   @param[in] This       Protocol instance pointer.
 309   @param[in] Visible    If TRUE, the cursor is set to be visible. If FALSE, the cursor is
 310                         set to be invisible.
 311
 312   @retval EFI_SUCCESS           The operation completed successfully.
 313   @retval EFI_DEVICE_ERROR      The device had an error and could not complete the
 314                                 request, or the device does not support changing
 315                                 the cursor mode.
 316   @retval EFI_UNSUPPORTED       The output device is not in a valid text mode.
 317
 318 **/
 319 EFI_STATUS
 320 EFIAPI
 321 ConsoleLoggerEnableCursor (
 322   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,
 323   IN  BOOLEAN                          Visible
 324   );
 325
 326 /**
 327   Function to update and verify that the current buffers are correct.
 328
 329   @param[in] ConsoleInfo  The pointer to the instance of the console logger information.
 330
 331   This will be used when a mode has changed or a reset ocurred to verify all
 332   history buffers.
 333 **/
 334 EFI_STATUS
 335 EFIAPI
 336 ConsoleLoggerResetBuffers(
 337   IN CONSOLE_LOGGER_PRIVATE_DATA *ConsoleInfo
 338   );
 339
 340 #endif //_CONSOLE_LOGGER_HEADER_
 341