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