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 */ 209