--- /dev/null
+/** @file\r
+ Class for arbitrary sized FIFO queues.\r
+\r
+ Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials are licensed and made available\r
+ under the terms and conditions of the BSD License which accompanies this\r
+ distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php.\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+**/\r
+#ifndef _FIFO_CLASS_H\r
+#define _FIFO_CLASS_H\r
+#include <Uefi.h>\r
+#include <wchar.h>\r
+#include <Containers/ModuloUtil.h>\r
+#include <sys/types.h>\r
+\r
+__BEGIN_DECLS\r
+\r
+typedef struct _FIFO_CLASS cFIFO;\r
+\r
+/// Constants to select what is counted by the FIFO_NumInQueue function.\r
+typedef enum {\r
+ AsElements, ///< Count the number of readable elements in the queue.\r
+ AsBytes ///< Count the number of readable bytes in the queue.\r
+} FIFO_ElemBytes;\r
+\r
+/** Construct a new instance of a FIFO Queue.\r
+\r
+ @param[in] NumElements Number of elements to be contained in the new FIFO.\r
+ @param[in] ElementSize Size, in bytes, of an element\r
+\r
+ @retval NULL Unable to create the instance.\r
+ @retval NonNULL Pointer to the new FIFO instance.\r
+**/\r
+cFIFO * EFIAPI New_cFIFO(UINT32 NumElements, size_t ElementSize);\r
+\r
+/** Add one or more elements to the FIFO.\r
+\r
+ This function allows one to add one or more elements, as specified by Count,\r
+ to the FIFO. Each element is of the size specified when the FIFO object\r
+ was instantiated (FIFO.ElementSize).\r
+\r
+ pElement points to the first byte of the first element to be added.\r
+ If multiple elements are to be added, the elements are expected to be\r
+ organized as a packed array.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[in] pElement Pointer to the element(s) to enqueue (add).\r
+ @param[in] Count Number of elements to add.\r
+\r
+ @retval 0 The FIFO is full.\r
+ @retval >=0 The number of elements added to the FIFO.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_Enqueue) (cFIFO *Self, const void *ElementPointer, size_t Count);\r
+\r
+/** Read or copy elements from the FIFO.\r
+\r
+ This function allows one to read one or more elements, as specified by Count,\r
+ from the FIFO. Each element is of the size specified when the FIFO object\r
+ was instantiated (FIFO.ElementSize).\r
+\r
+ pElement points to the destination of the first byte of the first element\r
+ to be read. If multiple elements are to be read, the elements are expected\r
+ to be organized as a packed array.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[out] pElement Pointer to where to store the element(s) read from the FIFO.\r
+ @param[in] Count Number of elements to dequeue.\r
+ @param[in] Consume If TRUE, consume read elements. Otherwise, preserve.\r
+\r
+ @retval 0 The FIFO is empty.\r
+ @retval >=0 The number of elements read from the FIFO.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_Dequeue) (cFIFO *Self, void *ElementPointer, size_t Count);\r
+\r
+/** Make a copy of the FIFO's data.\r
+ The contents of the FIFO is copied out and linearized without affecting the\r
+ FIFO contents.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[out] ElementPointer Pointer to where to store the elements copied from the FIFO.\r
+ @param[in] Count Number of elements to copy.\r
+\r
+ @retval 0 The FIFO is empty.\r
+ @retval >=0 The number of elements copied from the FIFO.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_Copy) (cFIFO *Self, void *ElementPointer, size_t Count);\r
+\r
+/** Test whether the FIFO is empty.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+\r
+ @retval TRUE The FIFO is empty.\r
+ @retval FALSE The FIFO is NOT empty.\r
+**/\r
+typedef BOOLEAN (EFIAPI *cFIFO_IsEmpty) (cFIFO *Self);\r
+\r
+/** Test whether the FIFO is full.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+\r
+ @retval TRUE The FIFO is full.\r
+ @retval FALSE The FIFO is NOT full.\r
+**/\r
+typedef BOOLEAN (EFIAPI *cFIFO_IsFull) (cFIFO *Self);\r
+\r
+/** Determine number of items available to read from the FIFO.\r
+\r
+ The number of items are either the number of bytes, or the number of elements\r
+ depending upon the value of the As enumerator.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[in] As An enumeration variable whose value determines whether the\r
+ returned value is the number of bytes or the number of elements\r
+ currently contained by the FIFO.\r
+\r
+ @retval 0 The FIFO is empty.\r
+ @retval >=0 The number of items contained in the FIFO.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_NumInQueue) (cFIFO *Self, FIFO_ElemBytes As);\r
+\r
+/** Determine amount of free space in the FIFO that can be written into.\r
+\r
+ The number of items are either the number of bytes, or the number of elements\r
+ depending upon the value of the As enumerator.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[in] As An enumeration variable whose value determines whether the\r
+ returned value is the number of bytes or the number of elements\r
+ currently available in the FIFO.\r
+\r
+ @retval 0 The FIFO is full.\r
+ @retval >=0 The number of items which can be accepted by the FIFO.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_FreeSpace) (cFIFO *Self, FIFO_ElemBytes As);\r
+\r
+/** Empty the FIFO, discarding up to NumToFlush elements.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+ @param[in] NumToFlush Number of elements to flush from the FIFO.\r
+ If larger than the number of elements in the\r
+ FIFO, the FIFO is emptied.\r
+\r
+ @return Returns the number of elements remaining in the FIFO after the flush.\r
+**/\r
+typedef size_t (EFIAPI *cFIFO_Flush) (cFIFO *Self, size_t NumToFlush);\r
+\r
+/** Remove the most recent element from the FIFO.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+**/\r
+typedef void (EFIAPI *cFIFO_Truncate) (cFIFO *Self);\r
+\r
+/** Cleanly delete a FIFO instance.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+**/\r
+typedef void (EFIAPI *cFIFO_Delete) (cFIFO *Self);\r
+\r
+/** Get the FIFO's current Read Index.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+\r
+ @return The current value of the FIFO's ReadIndex member is returned.\r
+**/\r
+typedef UINT32 (EFIAPI *cFIFO_GetRDex) (cFIFO *Self);\r
+\r
+/** Get the FIFO's current Write Index.\r
+\r
+ @param[in] Self Pointer to the FIFO instance.\r
+\r
+ @return The current value of the FIFO's WriteIndex member is returned.\r
+**/\r
+typedef UINT32 (EFIAPI *cFIFO_GetWDex) (cFIFO *Self);\r
+\r
+/// Structure declaration for FIFO objects.\r
+struct _FIFO_CLASS {\r
+ /* ######## Public Functions ######## */\r
+ cFIFO_Enqueue Write; ///< Write an element into the FIFO.\r
+ cFIFO_Dequeue Read; ///< Read an element from the FIFO.\r
+ cFIFO_Copy Copy; ///< Non-destructive copy from FIFO.\r
+ cFIFO_IsEmpty IsEmpty; ///< Test whether the FIFO is empty.\r
+ cFIFO_IsFull IsFull; ///< Test whether the FIFO is full.\r
+ cFIFO_NumInQueue Count; ///< Return the number of elements contained in the FIFO.\r
+ cFIFO_FreeSpace FreeSpace; ///< Return the number of available elements in the FIFO.\r
+ cFIFO_Flush Flush; ///< Remove the N earliest elements from the FIFO.\r
+ cFIFO_Truncate Truncate; ///< Remove the most recent element from the FIFO.\r
+ cFIFO_Delete Delete; ///< Delete the FIFO object.\r
+\r
+ /* ######## Protected Functions ######## */\r
+ cFIFO_GetRDex GetRDex; ///< Get a copy of the current Read Index.\r
+ cFIFO_GetWDex GetWDex; ///< Get a copy of the current Write Index.\r
+\r
+ /* ######## PRIVATE Data ######## */\r
+ void *Queue; ///< The FIFO's data storage.\r
+ UINT32 ElementSize; ///< Number of bytes in an element.\r
+ UINT32 NumElements; ///< Number of elements the FIFO can store.\r
+ UINT32 ReadIndex; ///< Index of next element to Read.\r
+ UINT32 WriteIndex; ///< Index of where next element will be Written.\r
+};\r
+\r
+__END_DECLS\r
+#endif /* _FIFO_CLASS_H */\r
projects / mirror_edk2.git / blobdiff