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