xref: /illumos-gate/usr/src/boot/efi/include/Protocol/DataHub.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
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