1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
/** @file
Class for arbitrary sized FIFO queues.
Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials are licensed and made available
under the terms and conditions of the BSD License which accompanies this
distribution. The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php.
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#ifndef _FIFO_CLASS_H
#define _FIFO_CLASS_H
#include <Uefi.h>
#include <wchar.h>
#include <Containers/ModuloUtil.h>
#include <sys/types.h>
__BEGIN_DECLS
typedef struct _FIFO_CLASS cFIFO;
/// Constants to select what is counted by the FIFO_NumInQueue function.
typedef enum {
AsElements, ///< Count the number of readable elements in the queue.
AsBytes ///< Count the number of readable bytes in the queue.
} FIFO_ElemBytes;
/** Construct a new instance of a FIFO Queue.
@param[in] NumElements Number of elements to be contained in the new FIFO.
@param[in] ElementSize Size, in bytes, of an element
@retval NULL Unable to create the instance.
@retval NonNULL Pointer to the new FIFO instance.
**/
cFIFO * EFIAPI New_cFIFO(UINT32 NumElements, size_t ElementSize);
/** Add one or more elements to the FIFO.
This function allows one to add one or more elements, as specified by Count,
to the FIFO. Each element is of the size specified when the FIFO object
was instantiated (FIFO.ElementSize).
pElement points to the first byte of the first element to be added.
If multiple elements are to be added, the elements are expected to be
organized as a packed array.
@param[in] Self Pointer to the FIFO instance.
@param[in] pElement Pointer to the element(s) to enqueue (add).
@param[in] Count Number of elements to add.
@retval 0 The FIFO is full.
@retval >=0 The number of elements added to the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_Enqueue) (cFIFO *Self, const void *ElementPointer, size_t Count);
/** Read or copy elements from the FIFO.
This function allows one to read one or more elements, as specified by Count,
from the FIFO. Each element is of the size specified when the FIFO object
was instantiated (FIFO.ElementSize).
pElement points to the destination of the first byte of the first element
to be read. If multiple elements are to be read, the elements are expected
to be organized as a packed array.
@param[in] Self Pointer to the FIFO instance.
@param[out] pElement Pointer to where to store the element(s) read from the FIFO.
@param[in] Count Number of elements to dequeue.
@param[in] Consume If TRUE, consume read elements. Otherwise, preserve.
@retval 0 The FIFO is empty.
@retval >=0 The number of elements read from the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_Dequeue) (cFIFO *Self, void *ElementPointer, size_t Count);
/** Make a copy of the FIFO's data.
The contents of the FIFO is copied out and linearized without affecting the
FIFO contents.
@param[in] Self Pointer to the FIFO instance.
@param[out] ElementPointer Pointer to where to store the elements copied from the FIFO.
@param[in] Count Number of elements to copy.
@retval 0 The FIFO is empty.
@retval >=0 The number of elements copied from the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_Copy) (cFIFO *Self, void *ElementPointer, size_t Count);
/** Test whether the FIFO is empty.
@param[in] Self Pointer to the FIFO instance.
@retval TRUE The FIFO is empty.
@retval FALSE The FIFO is NOT empty.
**/
typedef BOOLEAN (EFIAPI *cFIFO_IsEmpty) (cFIFO *Self);
/** Test whether the FIFO is full.
@param[in] Self Pointer to the FIFO instance.
@retval TRUE The FIFO is full.
@retval FALSE The FIFO is NOT full.
**/
typedef BOOLEAN (EFIAPI *cFIFO_IsFull) (cFIFO *Self);
/** Determine number of items available to read from the FIFO.
The number of items are either the number of bytes, or the number of elements
depending upon the value of the As enumerator.
@param[in] Self Pointer to the FIFO instance.
@param[in] As An enumeration variable whose value determines whether the
returned value is the number of bytes or the number of elements
currently contained by the FIFO.
@retval 0 The FIFO is empty.
@retval >=0 The number of items contained in the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_NumInQueue) (cFIFO *Self, FIFO_ElemBytes As);
/** Determine amount of free space in the FIFO that can be written into.
The number of items are either the number of bytes, or the number of elements
depending upon the value of the As enumerator.
@param[in] Self Pointer to the FIFO instance.
@param[in] As An enumeration variable whose value determines whether the
returned value is the number of bytes or the number of elements
currently available in the FIFO.
@retval 0 The FIFO is full.
@retval >=0 The number of items which can be accepted by the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_FreeSpace) (cFIFO *Self, FIFO_ElemBytes As);
/** Empty the FIFO, discarding up to NumToFlush elements.
@param[in] Self Pointer to the FIFO instance.
@param[in] NumToFlush Number of elements to flush from the FIFO.
If larger than the number of elements in the
FIFO, the FIFO is emptied.
@return Returns the number of elements remaining in the FIFO after the flush.
**/
typedef size_t (EFIAPI *cFIFO_Flush) (cFIFO *Self, size_t NumToFlush);
/** Remove the most recent element from the FIFO.
@param[in] Self Pointer to the FIFO instance.
@return Returns the number of elements remaining in the FIFO.
**/
typedef size_t (EFIAPI *cFIFO_Truncate) (cFIFO *Self);
/** Cleanly delete a FIFO instance.
@param[in] Self Pointer to the FIFO instance.
**/
typedef void (EFIAPI *cFIFO_Delete) (cFIFO *Self);
/** Get the FIFO's current Read Index.
@param[in] Self Pointer to the FIFO instance.
@return The current value of the FIFO's ReadIndex member is returned.
**/
typedef UINT32 (EFIAPI *cFIFO_GetRDex) (cFIFO *Self);
/** Get the FIFO's current Write Index.
@param[in] Self Pointer to the FIFO instance.
@return The current value of the FIFO's WriteIndex member is returned.
**/
typedef UINT32 (EFIAPI *cFIFO_GetWDex) (cFIFO *Self);
/// Structure declaration for FIFO objects.
struct _FIFO_CLASS {
/* ######## Public Functions ######## */
cFIFO_Enqueue Write; ///< Write an element into the FIFO.
cFIFO_Dequeue Read; ///< Read an element from the FIFO.
cFIFO_Copy Copy; ///< Non-destructive copy from FIFO.
cFIFO_IsEmpty IsEmpty; ///< Test whether the FIFO is empty.
cFIFO_IsFull IsFull; ///< Test whether the FIFO is full.
cFIFO_NumInQueue Count; ///< Return the number of elements contained in the FIFO.
cFIFO_FreeSpace FreeSpace; ///< Return the number of available elements in the FIFO.
cFIFO_Flush Flush; ///< Remove the N earliest elements from the FIFO.
cFIFO_Truncate Truncate; ///< Remove the most recent element from the FIFO.
cFIFO_Delete Delete; ///< Delete the FIFO object.
/* ######## Protected Functions ######## */
cFIFO_GetRDex GetRDex; ///< Get a copy of the current Read Index.
cFIFO_GetWDex GetWDex; ///< Get a copy of the current Write Index.
/* ######## PRIVATE Data ######## */
void *Queue; ///< The FIFO's data storage.
UINT32 ElementSize; ///< Number of bytes in an element.
UINT32 NumElements; ///< Number of elements the FIFO can store.
UINT32 ReadIndex; ///< Index of next element to Read.
UINT32 WriteIndex; ///< Index of where next element will be Written.
};
__END_DECLS
#endif /* _FIFO_CLASS_H */
|
