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 - 2009, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  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, as does an input of one.
 103   @param  FilterDriver          If FilterDriver is not passed in a MonotonicCount of zero,
 104                                 it means to return the first data record. If FilterDriver is passed in,
 105                                 then a MonotonicCount of zero means to return the first data not yet read
 106                                 by FilterDriver.
 107   @param  Record                Returns a dynamically allocated memory buffer with a data
 108                                 record that matches MonotonicCount.
 109
 110   @retval EFI_SUCCESS           Data was returned in Record.
 111   @retval EFI_INVALID_PARAMETER FilterDriver was passed in but does not exist.
 112   @retval EFI_NOT_FOUND         MonotonicCount does not match any data record
 113                                 in the system. If a MonotonicCount of zero was passed in, then no
 114                                 data records exist in the system.
 115   @retval EFI_OUT_OF_RESOURCES  Record was not returned due to lack
 116                                 of system resources.
 117   @note: Inconsistent with specification here:
 118          In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as
 119          EFI_DATA_HUB_GET_NEXT_DATA_RECORD. The inconsistency is maintained for backward compatibility.
 120 **/
 121 typedef
 122 EFI_STATUS
 123 (EFIAPI *EFI_DATA_HUB_GET_NEXT_RECORD)(
 124   IN EFI_DATA_HUB_PROTOCOL    *This,
 125   IN OUT  UINT64              *MonotonicCount,
 126   IN  EFI_EVENT               *FilterDriver OPTIONAL,
 127   OUT EFI_DATA_RECORD_HEADER  **Record
 128   );
 129
 130 /**
 131   Registers an event to be signaled every time a data record is logged in the system.
 132
 133   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
 134   @param  FilterEvent           The EFI_EVENT to signal whenever data that matches
 135                                 FilterClass is logged in the system.
 136   @param  FilterTpl             The maximum EFI_TPL at which FilterEvent can be signaled.
 137                                 It is strongly recommended that you use the lowest EFI_TPL possible.
 138   @param  FilterClass           FilterEvent will be signaled whenever a bit
 139                                 in EFI_DATA_RECORD_HEADER.DataRecordClass is also set in FilterClass.
 140                                 If FilterClass is zero, no class-based filtering will be performed.
 141   @param  FilterDataRecordGuid  FilterEvent will be signaled whenever
 142                                 FilterDataRecordGuid matches EFI_DATA_RECORD_HEADER.DataRecordGuid.
 143                                 If FilterDataRecordGuid is NULL, then no GUID-based filtering will be performed.
 144
 145   @retval EFI_SUCCESS           The filter driver event was registered
 146   @retval EFI_ALREADY_STARTED   FilterEvent was previously registered and cannot be registered again.
 147   @retval EFI_OUT_OF_RESOURCES  The filter driver event was not registered
 148                                 due to lack of system resources.
 149   @note: Inconsistent with specification here:
 150          In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as
 151          EFI_DATA_HUB_REGISTER_DATA_FILTER_DRIVER. The inconsistency is maintained for backward compatibility.
 152 **/
 153 typedef
 154 EFI_STATUS
 155 (EFIAPI *EFI_DATA_HUB_REGISTER_FILTER_DRIVER)(
 156   IN EFI_DATA_HUB_PROTOCOL    *This,
 157   IN EFI_EVENT                FilterEvent,
 158   IN EFI_TPL                  FilterTpl,
 159   IN UINT64                   FilterClass,
 160   IN EFI_GUID                 *FilterDataRecordGuid OPTIONAL
 161   );
 162
 163 /**
 164   Stops a filter driver from being notified when data records are logged.
 165
 166   @param  This                  The EFI_DATA_HUB_PROTOCOL instance.
 167   @param  FilterEvent           The EFI_EVENT to remove from the list of events to be
 168                                 signaled every time errors are logged.
 169
 170   @retval EFI_SUCCESS           The filter driver represented by FilterEvent was shut off.
 171   @retval EFI_NOT_FOUND         FilterEvent did not exist.
 172   @note: Inconsistent with specification here:
 173          In Framework for EFI Data Hub Specification, Version 0.9, This definition is named as
 174          EFI_DATA_HUB_UNREGISTER_DATA_FILTER_DRIVER. The inconsistency is maintained for backward compatibility.
 175 **/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER)(
 179   IN EFI_DATA_HUB_PROTOCOL    *This,
 180   IN EFI_EVENT                FilterEvent
 181   );
 182
 183 /**
 184   This protocol is used to log information and register filter drivers
 185   to receive data records.
 186 **/
 187 struct _EFI_DATA_HUB_PROTOCOL {
 188   ///
 189   /// Logs a data record.
 190   ///
 191   EFI_DATA_HUB_LOG_DATA                 LogData;
 192
 193   ///
 194   /// Gets a data record. Used both to view the memory-based log and to
 195   /// get information about which data records have been consumed by a filter driver.
 196   ///
 197   EFI_DATA_HUB_GET_NEXT_RECORD          GetNextRecord;
 198
 199   ///
 200   /// Allows the registration of an EFI event to act as a filter driver for all data records that are logged.
 201   ///
 202   EFI_DATA_HUB_REGISTER_FILTER_DRIVER   RegisterFilterDriver;
 203
 204   ///
 205   /// Used to remove a filter driver that was added with RegisterFilterDriver().
 206   ///
 207   EFI_DATA_HUB_UNREGISTER_FILTER_DRIVER UnregisterFilterDriver;
 208 };
 209
 210 extern EFI_GUID gEfiDataHubProtocolGuid;
 211
 212 #endif