StdLib: Add terminal type line editing (Interactive IO) for console devices.

Adds a subset of the terminal I/O capabilities described in the Single Unix Specification, V4.
Supports:
    Erase previous character.  Default is Backspace or ^H
    Erase line.  Default is ^U
TAB characters are supported and, by default, are rendered as 8 spaces.  They will still be read as a single TAB character.
Both Canonical and Non-Canonical modes are supported.
If a terminal device is opened with O_TTY_INIT in the mode, the device will be initialized to "sane" values for interactive use.  It will be in Canonical mode, Enter will be translated to NewLine and on output, a NewLine is translated to CRLF.  Echoing will be on, control characters are output as ^X, and TABs are expanded.
See the new <sys/termios.h> file for more information.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by:  daryl.mcdaniel@intel.com
Reviewed-by:    erik.c.bjorge@intel.com
Reviewed-by:    leroy.p.leahy@intel.com
Reviewed-by:    lee.g.rosenbaum@intel.com
Reviewed-by:    jaben.carsey@intel.com





git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@13989 6f19259b-4bc3-4df7-8a09-765794883524

2 files changed, 311 insertions, 0 deletions

diff --git a/StdLib/Include/Containers/Fifo.h b/StdLib/Include/Containers/Fifo.h
new file mode 100644
index 0000000..3b232fe
--- /dev/null
+++ b/StdLib/Include/Containers/Fifo.h
@@ -0,0 +1,206 @@
+/** @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.

+**/

+typedef void        (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 */

diff --git a/StdLib/Include/Containers/ModuloUtil.h b/StdLib/Include/Containers/ModuloUtil.h
new file mode 100644
index 0000000..f98ab0a
--- /dev/null
+++ b/StdLib/Include/Containers/ModuloUtil.h
@@ -0,0 +1,105 @@
+/** @file

+  Utility functions for performing basic math operations constrained within a

+  modulus.

+

+  These functions are intended to simplify small changes to a value which much

+  remain within a specified modulus.  Changes must be less than or equal to

+  the modulus specified by MaxVal.

+

+  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 _MODULO_UTIL_H

+#define _MODULO_UTIL_H

+#include  <Uefi.h>

+#include  <sys/EfiCdefs.h>

+

+__BEGIN_DECLS

+

+/** Counter = (Counter + 1) % MaxVal;

+

+    Counter is always expected to be LESS THAN MaxVal.

+        0 <= Counter < MaxVal

+

+    @param[in]    Counter   The value to be incremented.

+    @param[in]    MaxVal    Modulus of the operation.

+

+    @return   Returns the result of incrementing Counter, modulus MaxVal.

+              If Counter >= MaxVal, returns -1.

+**/

+INT32

+EFIAPI

+ModuloIncrement(

+  UINT32  Counter,

+  UINT32  MaxVal

+  );

+

+/** Counter = (Counter - 1) % MaxVal;

+

+    Counter is always expected to be LESS THAN MaxVal.

+        0 <= Counter < MaxVal

+

+    @param[in]    Counter   The value to be decremented.

+    @param[in]    MaxVal    Modulus of the operation.

+

+    @return   Returns the result of decrementing Counter, modulus MaxVal.

+              If Counter >= MaxVal, returns -1.

+**/

+INT32

+EFIAPI

+ModuloDecrement(

+  UINT32  Counter,

+  UINT32  MaxVal

+  );

+

+/** Counter = (Counter + Increment) % MaxVal;

+

+    @param[in]    Counter   The value to be incremented.

+    @param[in]    Increment The value to add to Counter.

+    @param[in]    MaxVal    Modulus of the operation.

+

+    @return   Returns the result of adding Increment to Counter, modulus MaxVal,

+              or -1 if Increment is larger than MaxVal.

+**/

+INT32

+EFIAPI

+ModuloAdd (

+  UINT32  Counter,

+  UINT32  Increment,

+  UINT32  MaxVal

+  );

+

+/** Increment Counter but don't increment past MaxVal.

+

+    @param[in]    Counter   The value to be decremented.

+    @param[in]    MaxVal    The upper bound for Counter.  Counter < MaxVal.

+

+    @return   Returns the result of incrementing Counter.

+**/

+UINT32

+EFIAPI

+BoundIncrement(

+  UINT32  Counter,

+  UINT32  MaxVal

+  );

+

+/** Decrement Counter but don't decrement past zero.

+

+    @param[in]    Counter   The value to be decremented.

+

+    @return   Returns the result of decrementing Counter.

+**/

+UINT32

+EFIAPI

+BoundDecrement(

+  UINT32  Counter

+  );

+

+__END_DECLS

+#endif  /* _MODULO_UTIL_H */