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