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