IntelFrameworkPkg/Include/Protocol/DataHub.h

   1 /** @file
   2   The data hub protocol is used both by agents wishing to log
   3   data and those wishing to be made aware of all information that
   4   has been logged.
   5
   6 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
   7 This program and the accompanying materials are licensed and made available under
   8 the terms and conditions of the BSD License that accompanies this distribution.
   9 The full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php.
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   @par Revision Reference:
  16   The Data Hub Protocol is defined in Framework for EFI Data Hub Specification
  17   Version 0.9.
  18
  19 **/
  20
  21 #ifndef __DATA_HUB_H__
  22 #define __DATA_HUB_H__
  23
  24 #define EFI_DATA_HUB_PROTOCOL_GUID \
  25   { \
  26     0xae80d021, 0x618e, 0x11d4, {0xbc, 0xd7, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81 } \
  27   }
  28
  29 //
  30 // EFI generic Data Hub Header
  31 //
  32 // A Data Record is an EFI_DATA_RECORD_HEADER followed by RecordSize bytes of
  33 //  data. The format of the data is defined by the DataRecordGuid.
  34 //
  35 // If EFI_DATA_RECORD_HEADER is extended in the future, the Version number and HeaderSize must
  36 //  change.
  37 //
  38 // The logger is responcible for initializing:
  39 //  Version, HeaderSize, RecordSize, DataRecordGuid, DataRecordClass
  40 //
  41 // The Data Hub driver is responcible for initializing:
  42 //   LogTime and LogMonotonicCount.
  43 //
  44 #define EFI_DATA_RECORD_HEADER_VERSION  0x0100
  45 typedef struct {
  46   UINT16    Version;
  47   UINT16    HeaderSize;
  48   UINT32    RecordSize;
  49   EFI_GUID  DataRecordGuid;
  50   EFI_GUID  ProducerName;
  51   UINT64    DataRecordClass;
  52   EFI_TIME  LogTime;
  53   UINT64    LogMonotonicCount;
  54 } EFI_DATA_RECORD_HEADER;
  55
  56 //
  57 // Definition of DataRecordClass. These are used to filter out class types
  58 // at a very high level. The DataRecordGuid still defines the format of
  59 // the data. See the Data Hub Specification for rules on what can and can not be a
  60 // new DataRecordClass
  61 //
  62 #define EFI_DATA_RECORD_CLASS_DEBUG         0x0000000000000001
  63 #define EFI_DATA_RECORD_CLASS_ERROR         0x0000000000000002
  64 #define EFI_DATA_RECORD_CLASS_DATA          0x0000000000000004
  65 #define EFI_DATA_RECORD_CLASS_PROGRESS_CODE 0x0000000000000008
  66
  67 //
  68 // Forward reference for pure ANSI compatability
  69 //
  70 typedef struct _EFI_DATA_HUB_PROTOCOL EFI_DATA_HUB_PROTOCOL;
  71
  72 /**
  73   Logs a data record to the system event log.
  74
  75   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
  76   @param  DataRecordGuid        A GUID that indicates the format of the data passed into RawData.
  77   @param  ProducerName          A GUID that indicates the identity of the caller to this API.
  78   @param  DataRecordClass       This class indicates the generic type of the data record.
  79   @param  RawData               The DataRecordGuid-defined data to be logged.
  80   @param  RawDataSize           The size in bytes of RawData.
  81
  82   @retval EFI_SUCCESS           Data was logged.
  83   @retval EFI_OUT_OF_RESOURCES  Data was not logged due to lack of system resources.
  84
  85 **/
  86 typedef
  87 EFI_STATUS
  88 (EFIAPI *EFI_DATA_HUB_LOG_DATA)(
  89   IN  EFI_DATA_HUB_PROTOCOL   *This,
  90   IN  EFI_GUID                *DataRecordGuid,
  91   IN  EFI_GUID                *ProducerName,
  92   IN  UINT64                  DataRecordClass,
  93   IN  VOID                    *RawData,
  94   IN  UINT32                  RawDataSize
  95   );
  96
  97 /**
  98   Allows the system data log to be searched.
  99
 100   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
 101   @param  MonotonicCount        On input, it specifies the Record to return.
 102                                 An input of zero means to return the first record,
 103                                 as does an input of one.
 104   @param  FilterDriver          If FilterDriver is not passed in a MonotonicCount
 105                                 of zero, it means to return the first data record.
 106                                 If FilterDriver is passed in, then a MonotonicCount
 107                                 of zero means to return the first data not yet read
 108                                 by FilterDriver.
 109   @param  Record                Returns a dynamically allocated memory buffer with
 110                                 a data record that matches MonotonicCount.
 111
 112   @retval EFI_SUCCESS           Data was returned in Record.
 113   @retval EFI_INVALID_PARAMETER FilterDriver was passed in but does not exist.
 114   @retval EFI_NOT_FOUND         MonotonicCount does not match any data record
 115                                 in the system. If a MonotonicCount of zero was
 116                                 passed in, then no data records exist in the system.
 117   @retval EFI_OUT_OF_RESOURCES  Record was not returned due to lack
 118                                 of system resources.
 119   @note  Inconsistent with specification here:
 120          In Framework for EFI Data Hub Specification, Version 0.9, This definition
 121          is named as EFI_DATA_HUB_GET_NEXT_DATA_RECORD. The inconsistency is
 122          maintained for backward compatibility.
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_DATA_HUB_GET_NEXT_RECORD)(
 127   IN EFI_DATA_HUB_PROTOCOL    *This,
 128   IN OUT  UINT64              *MonotonicCount,
 129   IN  EFI_EVENT               *FilterDriver OPTIONAL,
 130   OUT EFI_DATA_RECORD_HEADER  **Record
 131   );
 132
 133 /**
 134   Registers an event to be signaled every time a data record is logged in the system.
 135
 136   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
 137   @param  FilterEvent           The EFI_EVENT to signal whenever data that matches
 138                                 FilterClass is logged in the system.
 139   @param  FilterTpl             The maximum EFI_TPL at which FilterEvent can be
 140                                 signaled. It is strongly recommended that you use
 141                                 the lowest EFI_TPL possible.
 142   @param  FilterClass           FilterEvent will be signaled whenever a bit
 143                                 in EFI_DATA_RECORD_HEADER.DataRecordClass is also
 144                                 set in FilterClass. If FilterClass is zero, no
 145                                 class-based filtering will be performed.
 146   @param  FilterDataRecordGuid  FilterEvent will be signaled whenever
 147                                 FilterDataRecordGuid matches
 148                                 EFI_DATA_RECORD_HEADER.DataRecordGuid.
 149                                 If FilterDataRecordGuid is NULL, then no GUID-based
 150                                 filtering will be performed.
 151
 152   @retval EFI_SUCCESS           The filter driver event was registered
 153   @retval EFI_ALREADY_STARTED   FilterEvent was previously registered and cannot
 154                                 be registered again.
 155   @retval EFI_OUT_OF_RESOURCES  The filter driver event was not registered
 156                                 due to lack of system resources.
 157   @note  Inconsistent with specification here:
 158          In Framework for EFI Data Hub Specification, Version 0.9, This definition
 159          is named as EFI_DATA_HUB_REGISTER_DATA_FILTER_DRIVER. The inconsistency
 160          is maintained for backward compatibility.
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *EFI_DATA_HUB_REGISTER_FILTER_DRIVER)(
 165   IN EFI_DATA_HUB_PROTOCOL    *This,
 166   IN EFI_EVENT                FilterEvent,
 167   IN EFI_TPL                  FilterTpl,
 168   IN UINT64                   FilterClass,
 169   IN EFI_GUID                 *FilterDataRecordGuid OPTIONAL
 170   );
 171
 172 /**
 173   Stops a filter driver from being notified when data records are logged.
 174
 175   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
 176   @param  FilterEvent           The EFI_EVENT to remove from the list of events to be
 177                                 signaled every time errors are logged.
 178
 179   @retval EFI_SUCCESS           The filter driver represented by FilterEvent was shut off.
 180   @retval EFI_NOT_FOUND         FilterEvent did not exist.
 181   @note  Inconsistent with specification here:
 182          In Framework for EFI Data Hub Specification, Version 0.9, This definition
 183          is named as EFI_DATA_HUB_UNREGISTER_DATA_FILTER_DRIVER. The inconsistency
 184          is maintained for backward compatibility.
 185 **/
 186 typedef
 187 EFI_STATUS
 188 (EFIAPI *EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER)(
 189   IN EFI_DATA_HUB_PROTOCOL    *This,
 190   IN EFI_EVENT                FilterEvent
 191   );
 192
 193 /**
 194   This protocol is used to log information and register filter drivers
 195   to receive data records.
 196 **/
 197 struct _EFI_DATA_HUB_PROTOCOL {
 198   ///
 199   /// Logs a data record.
 200   ///
 201   EFI_DATA_HUB_LOG_DATA                 LogData;
 202
 203   ///
 204   /// Gets a data record. Used both to view the memory-based log and to
 205   /// get information about which data records have been consumed by a filter driver.
 206   ///
 207   EFI_DATA_HUB_GET_NEXT_RECORD          GetNextRecord;
 208
 209   ///
 210   /// Allows the registration of an EFI event to act as a filter driver for all data records that are logged.
 211   ///
 212   EFI_DATA_HUB_REGISTER_FILTER_DRIVER   RegisterFilterDriver;
 213
 214   ///
 215   /// Used to remove a filter driver that was added with RegisterFilterDriver().
 216   ///
 217   EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER UnregisterFilterDriver;
 218 };
 219
 220 extern EFI_GUID gEfiDataHubProtocolGuid;
 221
 222 #endif