From 6c6c850ad62d6fdc73828057339be1dc7df37c8e Mon Sep 17 00:00:00 2001 From: darylm503 Date: Tue, 11 Dec 2012 21:19:14 +0000 Subject: 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 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 --- StdLib/Include/Containers/Fifo.h | 206 +++++++++++++++++++++++++++++++++ StdLib/Include/Containers/ModuloUtil.h | 105 +++++++++++++++++ StdLib/Include/sys/termios.h | 154 +++++++++++++++++++++++- 3 files changed, 464 insertions(+), 1 deletion(-) create mode 100644 StdLib/Include/Containers/Fifo.h create mode 100644 StdLib/Include/Containers/ModuloUtil.h (limited to 'StdLib/Include') diff --git a/StdLib/Include/Containers/Fifo.h b/StdLib/Include/Containers/Fifo.h new file mode 100644 index 0000000000..3b232fec23 --- /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.
+ 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 +#include +#include +#include + +__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 0000000000..f98ab0aea9 --- /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.
+ 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 +#include + +__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 */ diff --git a/StdLib/Include/sys/termios.h b/StdLib/Include/sys/termios.h index 13e15d2fad..e144d521f5 100644 --- a/StdLib/Include/sys/termios.h +++ b/StdLib/Include/sys/termios.h @@ -215,19 +215,171 @@ struct termios { #include __BEGIN_DECLS + +/** Get input baud rate. + + Extracts the input baud rate from the termios structure pointed to by the + pTermios argument. + + @param[in] pTermios A pointer to the termios structure from which to extract + the input baud rate. + + @return The value of the input speed is returned exactly as it is contained + in the termios structure, without interpretation. +**/ speed_t cfgetispeed (const struct termios *); + +/** Get output baud rate. + + Extracts the output baud rate from the termios structure pointed to by the + pTermios argument. + + @param[in] pTermios A pointer to the termios structure from which to extract + the output baud rate. + + @return The value of the output speed is returned exactly as it is contained + in the termios structure, without interpretation. +**/ speed_t cfgetospeed (const struct termios *); + +/** Set input baud rate. + + Replaces the input baud rate, in the termios structure pointed to by the + pTermios argument, with the value of NewSpeed. + + @param[out] pTermios A pointer to the termios structure into which to set + the input baud rate. + @param[in] NewSpeed The new input baud rate. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EINVAL - The value of NewSpeed is outside the range of + possible speed values as specified in . +**/ int cfsetispeed (struct termios *, speed_t); + +/** Set output baud rate. + + Replaces the output baud rate, in the termios structure pointed to by the + pTermios argument, with the value of NewSpeed. + + @param[out] pTermios A pointer to the termios structure into which to set + the output baud rate. + @param[in] NewSpeed The new output baud rate. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EINVAL - The value of NewSpeed is outside the range of + possible speed values as specified in . +**/ int cfsetospeed (struct termios *, speed_t); + +/** Get the parameters associated with an interactive IO device. + + Get the parameters associated with the device referred to by + fd and store them into the termios structure referenced by pTermios. + + @param[in] fd The file descriptor for an open interactive IO device. + @param[out] pTermios A pointer to a termios structure into which to store + attributes of the interactive IO device. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EBADF - The fd argument is not a valid file descriptor. + * ENOTTY - The file associated with fd is not an interactive IO device. +**/ int tcgetattr (int, struct termios *); + +/** Set the parameters associated with an interactive IO device. + + Set the parameters associated with the device referred to by + fd to the values in the termios structure referenced by pTermios. + + Behavior is modified by the value of the OptAct parameter: + * TCSANOW: The change shall occur immediately. + * TCSADRAIN: The change shall occur after all output written to fd is + transmitted. This action should be used when changing parameters which + affect output. + * TCSAFLUSH: The change shall occur after all output written to fd is + transmitted, and all input so far received but not read shall be + discarded before the change is made. + + @param[in] fd The file descriptor for an open interactive IO device. + @param[in] OptAct Currently has no effect. + @param[in] pTermios A pointer to a termios structure into which to retrieve + attributes to set in the interactive IO device. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EBADF - The fd argument is not a valid file descriptor. + * ENOTTY - The file associated with fd is not an interactive IO device. +**/ int tcsetattr (int, int, const struct termios *); + +/** Transmit pending output. + + + @param[in] fd The file descriptor for an open interactive IO device. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EBADF - The fd argument is not a valid file descriptor. + * ENOTTY - The file associated with fd is not an interactive IO device. + * EINTR - A signal interrupted tcdrain(). + * ENOTSUP - This function is not supported. +**/ int tcdrain (int); + +/** Suspend or restart the transmission or reception of data. + + This function will suspend or resume transmission or reception of data on + the file referred to by fd, depending on the value of Action. + + @param[in] fd The file descriptor of an open interactive IO device (terminal). + @param[in] Action The action to be performed: + * TCOOFF - Suspend output. + * TCOON - Resume suspended output. + * TCIOFF - If fd refers to an IIO device, transmit a + STOP character, which is intended to cause the + terminal device to stop transmitting data. + * TCION - If fd refers to an IIO device, transmit a + START character, which is intended to cause the + terminal device to start transmitting data. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EBADF - The fd argument is not a valid file descriptor. + * ENOTTY - The file associated with fd is not an interactive IO device. + * EINVAL - The Action argument is not a supported value. + * ENOTSUP - This function is not supported. +**/ int tcflow (int, int); + +/** Discard non-transmitted output data, non-read input data, or both. + + + @param[in] fd The file descriptor for an open interactive IO device. + @param[in] QueueSelector The IO queue to be affected: + * TCIFLUSH - If fd refers to a device open for input, flush + pending input. Otherwise error EINVAL. + * TCOFLUSH - If fd refers to a device open for output, + flush pending output. Otherwise error EINVAL. + * TCIOFLUSH - If fd refers to a device open for both + input and output, flush pending input and output. + Otherwise error EINVAL. + + @retval 0 The operation completed successfully. + @retval -1 An error occured and errno is set to indicate the error. + * EBADF - The fd argument is not a valid file descriptor. + * ENOTTY - The file associated with fd is not an interactive IO device. + * EINVAL - The QueueSelector argument is not a supported value. + * ENOTSUP - This function is not supported. +**/ int tcflush (int, int); + //int tcsendbreak (int, int); //pid_t tcgetsid (int); - //void cfmakeraw (struct termios *); //int cfsetspeed (struct termios *, speed_t); __END_DECLS -- cgit v1.2.3