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