diff options
Diffstat (limited to 'DynamicTablesPkg')
| -rw-r--r-- | DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.c | 665 | ||||
| -rw-r--r-- | DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.h | 451 |
2 files changed, 1116 insertions, 0 deletions
diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.c b/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.c new file mode 100644 index 0000000000..419e796e50 --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.c @@ -0,0 +1,665 @@ +/** @file
+ AML Stream.
+
+ Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+
+ SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#include <Stream/AmlStream.h>
+
+/** Initialize a stream.
+
+ @param [in, out] Stream Pointer to the stream to initialize.
+ @param [in] Buffer Buffer to initialize Stream with.
+ Point to the beginning of the Buffer.
+ @param [in] MaxBufferSize Maximum size of Buffer.
+ @param [in] Direction Direction Stream is progressing
+ (forward, backward).
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamInit (
+ IN OUT AML_STREAM * Stream,
+ IN UINT8 * Buffer,
+ IN UINT32 MaxBufferSize,
+ IN EAML_STREAM_DIRECTION Direction
+ )
+{
+ if ((Stream == NULL) ||
+ (Buffer == NULL) ||
+ (MaxBufferSize == 0) ||
+ ((Direction != EAmlStreamDirectionForward) &&
+ (Direction != EAmlStreamDirectionBackward))) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ Stream->Buffer = Buffer;
+ Stream->MaxBufferSize = MaxBufferSize;
+ Stream->Index = 0;
+ Stream->Direction = Direction;
+
+ return EFI_SUCCESS;
+}
+
+/** Clone a stream.
+
+ Cloning a stream means copying all the values of the input Stream
+ in the ClonedStream.
+
+ @param [in] Stream Pointer to the stream to clone.
+ @param [in] ClonedStream Pointer to the stream to initialize.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamClone (
+ IN CONST AML_STREAM * Stream,
+ OUT AML_STREAM * ClonedStream
+ )
+{
+ if (!IS_STREAM (Stream) ||
+ (ClonedStream == NULL)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ ClonedStream->Buffer = Stream->Buffer;
+ ClonedStream->MaxBufferSize = Stream->MaxBufferSize;
+ ClonedStream->Index = Stream->Index;
+ ClonedStream->Direction = Stream->Direction;
+
+ return EFI_SUCCESS;
+}
+
+/** Initialize a sub-stream from a stream.
+
+ A sub-stream is a stream initialized at the current position of the input
+ stream:
+ - the Buffer field points to the current position of the input stream;
+ - the Index field is set to 0;
+ - the MaxBufferSize field is set to the remaining size of the input stream;
+ - the direction is conserved;
+
+ E.g.: For a forward stream:
+ +----------------+----------------+
+ |ABCD.........XYZ| Free Space |
+ +----------------+----------------+
+ ^ ^ ^
+ Stream: Buffer CurrPos EndOfBuff
+ Sub-stream: Buffer/CurrPos EndOfBuff
+
+ @param [in] Stream Pointer to the stream from which a sub-stream is
+ created.
+ @param [in] SubStream Pointer to the stream to initialize.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamInitSubStream (
+ IN CONST AML_STREAM * Stream,
+ OUT AML_STREAM * SubStream
+ )
+{
+ if (!IS_STREAM (Stream) ||
+ (SubStream == NULL)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ if (IS_STREAM_FORWARD (Stream)) {
+ SubStream->Buffer = AmlStreamGetCurrPos (Stream);
+ } else if (IS_STREAM_BACKWARD (Stream)) {
+ SubStream->Buffer = Stream->Buffer;
+ } else {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ SubStream->MaxBufferSize = AmlStreamGetFreeSpace (Stream);
+ SubStream->Index = 0;
+ SubStream->Direction = Stream->Direction;
+
+ return EFI_SUCCESS;
+}
+
+/** Get the buffer of a stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The stream's Buffer.
+ NULL otherwise.
+**/
+UINT8 *
+EFIAPI
+AmlStreamGetBuffer (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return NULL;
+ }
+ return Stream->Buffer;
+}
+
+/** Get the size of Stream's Buffer.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The Size of Stream's Buffer.
+ Return 0 if Stream is invalid.
+**/
+UINT32
+EFIAPI
+AmlStreamGetMaxBufferSize (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return 0;
+ }
+ return Stream->MaxBufferSize;
+}
+
+/** Reduce the maximal size of Stream's Buffer (MaxBufferSize field).
+
+ @param [in] Stream Pointer to a stream.
+ @param [in] Diff Value to subtract to the Stream's MaxBufferSize.
+ 0 < x < MaxBufferSize - Index.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReduceMaxBufferSize (
+ IN AML_STREAM * Stream,
+ IN UINT32 Diff
+ )
+{
+ if (!IS_STREAM (Stream) ||
+ (Diff == 0) ||
+ ((Stream->MaxBufferSize - Diff) <= Stream->Index)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ Stream->MaxBufferSize -= Diff;
+ return EFI_SUCCESS;
+}
+
+/** Get Stream's Index.
+
+ Stream's Index is incremented when writing data, reading data,
+ or moving the position in the Stream.
+ It can be seen as an index:
+ - starting at the beginning of Stream's Buffer if the stream goes forward;
+ - starting at the end of Stream's Buffer if the stream goes backward.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Stream's Index.
+ Return 0 if Stream is invalid.
+**/
+UINT32
+EFIAPI
+AmlStreamGetIndex (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return 0;
+ }
+ return Stream->Index;
+}
+
+/** Get Stream's Direction.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Stream's Direction.
+ Return EAmlStreamDirectionUnknown if Stream is invalid.
+**/
+EAML_STREAM_DIRECTION
+EFIAPI
+AmlStreamGetDirection (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return EAmlStreamDirectionInvalid;
+ }
+ return Stream->Direction;
+}
+
+/** Return a pointer to the current position in the stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The current position in the stream.
+ Return NULL if error.
+**/
+UINT8 *
+EFIAPI
+AmlStreamGetCurrPos (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return NULL;
+ }
+
+ if (IS_STREAM_FORWARD (Stream)) {
+ return Stream->Buffer + Stream->Index;
+ } else if (IS_STREAM_BACKWARD (Stream)) {
+ return Stream->Buffer + (Stream->MaxBufferSize - 1) - Stream->Index;
+ } else {
+ ASSERT (0);
+ return NULL;
+ }
+}
+
+/** Get the space available in the stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Remaining space available in the stream.
+ Zero in case of error or if the stream is at its end.
+**/
+UINT32
+EFIAPI
+AmlStreamGetFreeSpace (
+ IN CONST AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return 0;
+ }
+
+ if (Stream->Index > Stream->MaxBufferSize) {
+ ASSERT (0);
+ return 0;
+ }
+
+ return Stream->MaxBufferSize - Stream->Index;
+}
+
+/** Move Stream by Offset bytes.
+
+ The stream current position is moved according to the stream direction
+ (forward, backward).
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [in] Offset Offset to move the stream of.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamProgress (
+ IN AML_STREAM * Stream,
+ IN UINT32 Offset
+ )
+{
+ if (!IS_STREAM (Stream) ||
+ IS_END_OF_STREAM (Stream) ||
+ (Offset == 0)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ if (AmlStreamGetFreeSpace (Stream) < Offset) {
+ ASSERT (0);
+ return EFI_BUFFER_TOO_SMALL;
+ }
+
+ Stream->Index += Offset;
+
+ return EFI_SUCCESS;
+}
+
+/** Rewind Stream of Offset bytes.
+
+ The stream current position is rewound according to the stream direction
+ (forward, backward). A stream going forward will be rewound backward.
+
+ @param [in] Stream Pointer to a stream.
+ @param [in] Offset Offset to rewind the stream of.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamRewind (
+ IN AML_STREAM * Stream,
+ IN UINT32 Offset
+ )
+{
+ if (!IS_STREAM (Stream) ||
+ (Offset == 0)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ if (AmlStreamGetIndex (Stream) < Offset) {
+ ASSERT (0);
+ return EFI_BUFFER_TOO_SMALL;
+ }
+
+ Stream->Index -= Offset;
+
+ return EFI_SUCCESS;
+}
+
+/** Reset the Stream (move the current position to the initial position).
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReset (
+ IN AML_STREAM * Stream
+ )
+{
+ if (!IS_STREAM (Stream)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ Stream->Index = 0;
+
+ return EFI_SUCCESS;
+}
+
+/** Peek one byte at Stream's current position.
+
+ Stream's position is not moved when peeking.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [out] OutByte Pointer holding the byte value of
+ the stream current position.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamPeekByte (
+ IN AML_STREAM * Stream,
+ OUT UINT8 * OutByte
+ )
+{
+ UINT8 * CurPos;
+
+ if (!IS_STREAM (Stream) ||
+ IS_END_OF_STREAM (Stream) ||
+ (OutByte == NULL)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ CurPos = AmlStreamGetCurrPos (Stream);
+ if (CurPos == NULL) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ *OutByte = *CurPos;
+ return EFI_SUCCESS;
+}
+
+/** Read one byte at Stream's current position.
+
+ The stream current position is moved when reading.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [out] OutByte Pointer holding the byte value of
+ the stream current position.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReadByte (
+ IN AML_STREAM * Stream,
+ OUT UINT8 * OutByte
+ )
+{
+ EFI_STATUS Status;
+
+ if (!IS_STREAM (Stream) ||
+ IS_END_OF_STREAM (Stream) ||
+ (OutByte == NULL)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ // Stream is checked in the function call.
+ Status = AmlStreamPeekByte (Stream, OutByte);
+ if (EFI_ERROR (Status)) {
+ ASSERT (0);
+ return Status;
+ }
+
+ Status = AmlStreamProgress (Stream, 1);
+ ASSERT_EFI_ERROR (Status);
+ return Status;
+}
+
+/** Write Size bytes in the stream.
+
+ If the stream goes backward (toward lower addresses), the bytes written
+ to the stream are not reverted.
+ In the example below, writing "Hello" to the stream will not revert
+ the string. The end of the stream buffer will contain "Hello world!".
+ Stream buffer:
+ +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ | ..... | ' ' | 'w' | 'o' | 'r' | 'l' | 'd' | '!' | '\0' |
+ +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ ^
+ Current position.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [in] Buffer Pointer to the data to write.
+ @param [in] Size Number of bytes to write.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamWrite (
+ IN AML_STREAM * Stream,
+ IN CONST UINT8 * Buffer,
+ IN UINT32 Size
+ )
+{
+ UINT8 * CurrPos;
+
+ if (!IS_STREAM (Stream) ||
+ IS_END_OF_STREAM (Stream) ||
+ (Buffer == NULL) ||
+ (Size == 0)) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ if (AmlStreamGetFreeSpace (Stream) < Size) {
+ ASSERT (0);
+ return EFI_BUFFER_TOO_SMALL;
+ }
+
+ CurrPos = AmlStreamGetCurrPos (Stream);
+
+ // If the Stream goes backward, prepare some space to copy the data.
+ if (IS_STREAM_BACKWARD (Stream)) {
+ CurrPos -= Size;
+ }
+
+ CopyMem (CurrPos, Buffer, Size);
+ Stream->Index += Size;
+
+ return EFI_SUCCESS;
+}
+
+/** Compare Size bytes between Stream1 and Stream2 from their
+ respective current position.
+
+ Stream1 and Stream2 must go in the same direction.
+ Stream1 and Stream2 are left unchanged.
+
+ @param [in] Stream1 First stream to compare.
+ The stream must not be at its end.
+ @param [in] Stream2 Second stream to compare.
+ The stream must not be at its end.
+ @param [in] Size Number of bytes to compare.
+ Must be lower than the minimum remaining space of
+ Stream1 and Stream2.
+ Must be non-zero.
+
+ @retval TRUE If Stream1 and Stream2 have Size bytes equal,
+ from their respective current position.
+ The function completed successfully.
+ @retval FALSE Otherwise.
+**/
+BOOLEAN
+EFIAPI
+AmlStreamCmp (
+ IN CONST AML_STREAM * Stream1,
+ IN CONST AML_STREAM * Stream2,
+ IN UINT32 Size
+ )
+{
+ UINT32 MinSize;
+ UINT8 * CurrPosStream1;
+ UINT8 * CurrPosStream2;
+
+ if (!IS_STREAM (Stream1) ||
+ IS_END_OF_STREAM (Stream1) ||
+ !IS_STREAM (Stream2) ||
+ IS_END_OF_STREAM (Stream2) ||
+ (Stream1->Direction != Stream2->Direction) ||
+ (Size == 0)) {
+ ASSERT (0);
+ return FALSE;
+ }
+
+ // Check the Size is not longer than the remaining size of
+ // Stream1 and Stream2.
+ MinSize = MIN (
+ AmlStreamGetFreeSpace (Stream1),
+ AmlStreamGetFreeSpace (Stream2)
+ );
+ if (MinSize < Size) {
+ ASSERT (0);
+ return FALSE;
+ }
+
+ CurrPosStream1 = AmlStreamGetCurrPos (Stream1);
+ if (CurrPosStream1 == NULL) {
+ ASSERT (0);
+ return FALSE;
+ }
+ CurrPosStream2 = AmlStreamGetCurrPos (Stream2);
+ if (CurrPosStream2 == NULL) {
+ ASSERT (0);
+ return FALSE;
+ }
+
+ if (Stream1->Direction == EAmlStreamDirectionForward) {
+ return (0 == CompareMem (CurrPosStream1, CurrPosStream2, MinSize));
+ }
+
+ // The stream is already pointing on the last byte, thus the (-1).
+ // +---------------------+
+ // BStream | | | | | | | |M|E|T|0|
+ // +---------------------+
+ // ^
+ // CurrPos
+ return (0 == CompareMem (
+ CurrPosStream1 - (MinSize - 1),
+ CurrPosStream2 - (MinSize - 1),
+ MinSize
+ ));
+}
+
+/** Copy Size bytes of the stream's data to DstBuffer.
+
+ For a backward stream, the bytes are copied starting from the
+ current stream position.
+
+ @param [out] DstBuffer Destination Buffer to copy the data to.
+ @param [in] MaxDstBufferSize Maximum size of DstBuffer.
+ Must be non-zero.
+ @param [in] Stream Pointer to the stream to copy the data from.
+ @param [in] Size Number of bytes to copy from the stream
+ buffer.
+ Must be lower than MaxDstBufferSize.
+ Must be lower than Stream's MaxBufferSize.
+ Return success if zero.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamCpyS (
+ OUT CHAR8 * DstBuffer,
+ IN UINT32 MaxDstBufferSize,
+ IN AML_STREAM * Stream,
+ IN UINT32 Size
+ )
+{
+ CHAR8 * StreamBufferStart;
+
+ // Stream is checked in the function call.
+ if ((DstBuffer == NULL) ||
+ (MaxDstBufferSize == 0) ||
+ (Size > MaxDstBufferSize) ||
+ (Size > AmlStreamGetMaxBufferSize (Stream))) {
+ ASSERT (0);
+ return EFI_INVALID_PARAMETER;
+ }
+
+ if (Size == 0) {
+ return EFI_SUCCESS;
+ }
+
+ // Find the address at which the data is starting.
+ StreamBufferStart = (CHAR8*)(IS_STREAM_FORWARD (Stream) ?
+ Stream->Buffer :
+ AmlStreamGetCurrPos (Stream));
+
+ CopyMem (DstBuffer, StreamBufferStart, Size);
+
+ return EFI_SUCCESS;
+}
diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.h b/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.h new file mode 100644 index 0000000000..cd2da89b07 --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.h @@ -0,0 +1,451 @@ +/** @file
+ AML Stream.
+
+ Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+
+ SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef AML_STREAM_H_
+#define AML_STREAM_H_
+
+#include <AmlInclude.h>
+
+/** Stream direction.
+
+ Enum to choose the direction the stream is progressing.
+*/
+typedef enum EAmlStreamDirection {
+ EAmlStreamDirectionInvalid, ///< Invalid AML Stream direction.
+ EAmlStreamDirectionForward, ///< Forward direction.
+ /// The Stream goes toward higher addresses.
+ EAmlStreamDirectionBackward, ///< Forward direction.
+ /// The Stream goes toward lower addresses.
+ EAmlStreamDirectionMax, ///< Max enum.
+} EAML_STREAM_DIRECTION;
+
+/** Stream.
+
+ This structure is used as a wrapper around a buffer. It allows to do common
+ buffer manipulations (read, write, etc.) while preventing buffer overflows.
+*/
+typedef struct AmlStream {
+ /// Pointer to a buffer.
+ UINT8 * Buffer;
+
+ /// Size of Buffer.
+ UINT32 MaxBufferSize;
+
+ /// Index in the Buffer.
+ /// The Index field allows to keep track of how many bytes have been
+ /// read/written in the Buffer, and to retrieve the current stream position.
+ /// 0 <= Index <= MaxBufferSize.
+ /// If Index == MaxBufferSize, no more action is allowed on the stream.
+ UINT32 Index;
+
+ /// The direction the stream is progressing.
+ /// If the stream goes backward (toward lower addresses), the bytes written
+ /// to the stream are not reverted.
+ /// In the example below, writing "Hello" to the stream will not revert
+ /// the string. The end of the stream buffer will contain "Hello world!".
+ /// Similarly, moving the stream position will be done according to the
+ /// direction of the stream.
+ /// Stream buffer:
+ /// +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ /// |-------------- | ' ' | 'w' | 'o' | 'r' | 'l' | 'd' | '!' | '\0' |
+ /// +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ /// ^
+ /// Current position.
+ EAML_STREAM_DIRECTION Direction;
+} AML_STREAM;
+
+/** Check whether a StreamPtr is a valid Stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval TRUE Stream is a pointer to a stream.
+ @retval FALSE Otherwise.
+*/
+#define IS_STREAM(Stream) ( \
+ (((AML_STREAM*)Stream) != NULL) && \
+ (((AML_STREAM*)Stream)->Buffer != NULL))
+
+/** Check whether a Stream is at the end of its buffer.
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval TRUE Stream is a pointer to a non-full stream.
+ @retval FALSE Otherwise.
+*/
+#define IS_END_OF_STREAM(Stream) ( \
+ (((AML_STREAM*)Stream)->Index == \
+ ((AML_STREAM*)Stream)->MaxBufferSize))
+
+/** Check Stream goes forward.
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval TRUE Stream goes forward.
+ @retval FALSE Otherwise.
+*/
+#define IS_STREAM_FORWARD(Stream) ( \
+ ((AML_STREAM*)Stream)->Direction == EAmlStreamDirectionForward)
+
+/** Check Stream goes backward.
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval TRUE Stream goes backward.
+ @retval FALSE Otherwise.
+*/
+#define IS_STREAM_BACKWARD(Stream) ( \
+ ((AML_STREAM*)Stream)->Direction == EAmlStreamDirectionBackward)
+
+/** Initialize a stream.
+
+ @param [in, out] Stream Pointer to the stream to initialize.
+ @param [in] Buffer Buffer to initialize Stream with.
+ Point to the beginning of the Buffer.
+ @param [in] MaxBufferSize Maximum size of Buffer.
+ @param [in] Direction Direction Stream is progressing
+ (forward, backward).
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamInit (
+ IN OUT AML_STREAM * Stream,
+ IN UINT8 * Buffer,
+ IN UINT32 MaxBufferSize,
+ IN EAML_STREAM_DIRECTION Direction
+ );
+
+/** Clone a stream.
+
+ Cloning a stream means copying all the values of the input Stream
+ in the ClonedStream.
+
+ @param [in] Stream Pointer to the stream to clone.
+ @param [in] ClonedStream Pointer to the stream to initialize.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamClone (
+ IN CONST AML_STREAM * Stream,
+ OUT AML_STREAM * ClonedStream
+ );
+
+/** Initialize a sub-stream from a stream.
+
+ A sub-stream is a stream initialized at the current position of the input
+ stream:
+ - the Buffer field points to the current position of the input stream;
+ - the Index field is set to 0;
+ - the MaxBufferSize field is set to the remaining size of the input stream;
+ - the direction is conserved;
+
+ E.g.: For a forward stream:
+ +----------------+----------------+
+ |ABCD.........XYZ| Free Space |
+ +----------------+----------------+
+ ^ ^ ^
+ Stream: Buffer CurrPos EndOfBuff
+ Sub-stream: Buffer/CurrPos EndOfBuff
+
+ @param [in] Stream Pointer to the stream from which a sub-stream is
+ created.
+ @param [in] SubStream Pointer to the stream to initialize.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamInitSubStream (
+ IN CONST AML_STREAM * Stream,
+ OUT AML_STREAM * SubStream
+ );
+
+/** Get the buffer of a stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The stream's Buffer.
+ NULL otherwise.
+**/
+UINT8 *
+EFIAPI
+AmlStreamGetBuffer (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Get the size of Stream's Buffer.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The Size of Stream's Buffer.
+ Return 0 if Stream is invalid.
+**/
+UINT32
+EFIAPI
+AmlStreamGetMaxBufferSize (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Reduce the maximal size of Stream's Buffer (MaxBufferSize field).
+
+ @param [in] Stream Pointer to a stream.
+ @param [in] Diff Value to subtract to the Stream's MaxBufferSize.
+ 0 < x < MaxBufferSize - Index.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReduceMaxBufferSize (
+ IN AML_STREAM * Stream,
+ IN UINT32 Diff
+ );
+
+/** Get Stream's Index.
+
+ Stream's Index is incremented when writing data, reading data,
+ or moving the position in the Stream.
+ It can be seen as an index:
+ - starting at the beginning of Stream's Buffer if the stream goes forward;
+ - starting at the end of Stream's Buffer if the stream goes backward.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Stream's Index.
+ Return 0 if Stream is invalid.
+**/
+UINT32
+EFIAPI
+AmlStreamGetIndex (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Get Stream's Direction.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Stream's Direction.
+ Return EAmlStreamDirectionUnknown if Stream is invalid.
+**/
+EAML_STREAM_DIRECTION
+EFIAPI
+AmlStreamGetDirection (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Return a pointer to the current position in the stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return The current position in the stream.
+ Return NULL if error.
+**/
+UINT8 *
+EFIAPI
+AmlStreamGetCurrPos (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Get the space available in the stream.
+
+ @param [in] Stream Pointer to a stream.
+
+ @return Remaining space available in the stream.
+ Zero in case of error or if the stream is at its end.
+**/
+UINT32
+EFIAPI
+AmlStreamGetFreeSpace (
+ IN CONST AML_STREAM * Stream
+ );
+
+/** Move Stream by Offset bytes.
+
+ The stream current position is moved according to the stream direction
+ (forward, backward).
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [in] Offset Offset to move the stream of.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamProgress (
+ IN AML_STREAM * Stream,
+ IN UINT32 Offset
+ );
+
+/** Rewind Stream of Offset bytes.
+
+ The stream current position is rewound according to the stream direction
+ (forward, backward). A stream going forward will be rewound backward.
+
+ @param [in] Stream Pointer to a stream.
+ @param [in] Offset Offset to rewind the stream of.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamRewind (
+ IN AML_STREAM * Stream,
+ IN UINT32 Offset
+ );
+
+/** Reset the Stream (move the current position to the initial position).
+
+ @param [in] Stream Pointer to a stream.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReset (
+ IN AML_STREAM * Stream
+ );
+
+/** Peek one byte at Stream's current position.
+
+ Stream's position is not moved when peeking.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [out] OutByte Pointer holding the byte value of
+ the stream current position.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamPeekByte (
+ IN AML_STREAM * Stream,
+ OUT UINT8 * OutByte
+ );
+
+/** Read one byte at Stream's current position.
+
+ The stream current position is moved when reading.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [out] OutByte Pointer holding the byte value of
+ the stream current position.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamReadByte (
+ IN AML_STREAM * Stream,
+ OUT UINT8 * OutByte
+ );
+
+/** Write Size bytes in the stream.
+
+ If the stream goes backward (toward lower addresses), the bytes written
+ to the stream are not reverted.
+ In the example below, writing "Hello" to the stream will not revert
+ the string. The end of the stream buffer will contain "Hello world!".
+ Stream buffer:
+ +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ | ..... | ' ' | 'w' | 'o' | 'r' | 'l' | 'd' | '!' | '\0' |
+ +---------------+-----+-----+-----+-----+-----+-----+---- +------+
+ ^
+ Current position.
+
+ @param [in] Stream Pointer to a stream.
+ The stream must not be at its end.
+ @param [in] Buffer Pointer to the data to write.
+ @param [in] Size Number of bytes to write.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamWrite (
+ IN AML_STREAM * Stream,
+ IN CONST UINT8 * Buffer,
+ IN UINT32 Size
+ );
+
+/** Compare Size bytes between Stream1 and Stream2 from their
+ respective current position.
+
+ Stream1 and Stream2 must go in the same direction.
+ Stream1 and Stream2 are left unchanged.
+
+ @param [in] Stream1 First stream to compare.
+ The stream must not be at its end.
+ @param [in] Stream2 Second stream to compare.
+ The stream must not be at its end.
+ @param [in] Size Number of bytes to compare.
+ Must be lower than the minimum remaining space of
+ Stream1 and Stream2.
+ Must be non-zero.
+
+ @retval TRUE If Stream1 and Stream2 have Size bytes equal,
+ from their respective current position.
+ The function completed successfully.
+ @retval FALSE Otherwise.
+**/
+BOOLEAN
+EFIAPI
+AmlStreamCmp (
+ IN CONST AML_STREAM * Stream1,
+ IN CONST AML_STREAM * Stream2,
+ IN UINT32 Size
+ );
+
+/** Copy Size bytes of the stream's data to DstBuffer.
+
+ For a backward stream, the bytes are copied starting from the
+ current stream position.
+
+ @param [out] DstBuffer Destination Buffer to copy the data to.
+ @param [in] MaxDstBufferSize Maximum size of DstBuffer.
+ Must be non-zero.
+ @param [in] Stream Pointer to the stream to copy the data from.
+ @param [in] Size Number of bytes to copy from the stream
+ buffer.
+ Must be lower than MaxDstBufferSize.
+ Must be lower than Stream's MaxBufferSize.
+ Return success if zero.
+
+ @retval EFI_SUCCESS The function completed successfully.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlStreamCpyS (
+ OUT CHAR8 * DstBuffer,
+ IN UINT32 MaxDstBufferSize,
+ IN AML_STREAM * Stream,
+ IN UINT32 Size
+ );
+
+#endif // AML_STREAM_H_
|