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