Fifo.h@ 61103

Last change on this file since 61103 was 58464, checked in by vboxsync, 9 years ago
EFI/Firmware: Export new files and directories.
Property svn:eol-style set to `native`
File size: 8.4 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/StdLib/Include/Containers/Fifo.h@ 61103

Download in other formats: