Remove blank for function typedef, it will break generating doxygen document.
[mirror_edk2.git] / 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