920ff98645
StdLib\Include\Containers\Fifo.h
Change return type of cFIFO_Truncate to size_t. Makes declaration match definition.
Update comment to describe what is returned.
StdLib\LibC\Uefi\InteractiveIO\IIOutilities.c
Change return type of IIO_CursorDelta to int. Makes declaration match definition.
Change other types from INT32 to int, for consistency.
Update comment for returned values.
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: daryl.mcdaniel@intel.com
Reviewed-by: erik.c.bjorge@intel.com
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@14060 6f19259b-4bc3-4df7-8a09-765794883524
209 lines
8.6 KiB
C
209 lines
8.6 KiB
C
/** @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 */
|