DynamicTablesPkg/Library/Common/AmlLib/Stream/AmlStream.h

   1 /** @file
   2   AML Stream.
   3
   4   Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #ifndef AML_STREAM_H_
  10 #define AML_STREAM_H_
  11
  12 #include <AmlInclude.h>
  13
  14 /** Stream direction.
  15
  16   Enum to choose the direction the stream is progressing.
  17 */
  18 typedef enum EAmlStreamDirection {
  19   EAmlStreamDirectionInvalid,     ///< Invalid AML Stream direction.
  20   EAmlStreamDirectionForward,     ///< Forward direction.
  21                                   ///  The Stream goes toward higher addresses.
  22   EAmlStreamDirectionBackward,    ///< Forward direction.
  23                                   ///  The Stream goes toward lower addresses.
  24   EAmlStreamDirectionMax,         ///< Max enum.
  25 } EAML_STREAM_DIRECTION;
  26
  27 /** Stream.
  28
  29   This structure is used as a wrapper around a buffer. It allows to do common
  30   buffer manipulations (read, write, etc.) while preventing buffer overflows.
  31 */
  32 typedef struct AmlStream {
  33   /// Pointer to a buffer.
  34   UINT8                 * Buffer;
  35
  36   /// Size of Buffer.
  37   UINT32                  MaxBufferSize;
  38
  39   /// Index in the Buffer.
  40   /// The Index field allows to keep track of how many bytes have been
  41   /// read/written in the Buffer, and to retrieve the current stream position.
  42   /// 0 <= Index <= MaxBufferSize.
  43   /// If Index == MaxBufferSize, no more action is allowed on the stream.
  44   UINT32                  Index;
  45
  46   /// The direction the stream is progressing.
  47   /// If the stream goes backward (toward lower addresses), the bytes written
  48   /// to the stream are not reverted.
  49   /// In the example below, writing "Hello" to the stream will not revert
  50   /// the string. The end of the stream buffer will contain "Hello world!".
  51   /// Similarly, moving the stream position will be done according to the
  52   /// direction of the stream.
  53   /// Stream buffer:
  54   ///    +---------------+-----+-----+-----+-----+-----+-----+---- +------+
  55   ///    |-------------- | ' ' | 'w' | 'o' | 'r' | 'l' | 'd' | '!' | '\0' |
  56   ///    +---------------+-----+-----+-----+-----+-----+-----+---- +------+
  57   ///                       ^
  58   ///                Current position.
  59   EAML_STREAM_DIRECTION   Direction;
  60 } AML_STREAM;
  61
  62 /** Check whether a StreamPtr is a valid Stream.
  63
  64   @param  [in]  Stream   Pointer to a stream.
  65
  66   @retval TRUE  Stream is a pointer to a stream.
  67   @retval FALSE Otherwise.
  68 */
  69 #define IS_STREAM(Stream)  (                                                  \
  70           (((AML_STREAM*)Stream) != NULL)                                 &&  \
  71           (((AML_STREAM*)Stream)->Buffer != NULL))
  72
  73 /** Check whether a Stream is at the end of its buffer.
  74
  75   @param  [in]  Stream   Pointer to a stream.
  76
  77   @retval TRUE  Stream is a pointer to a non-full stream.
  78   @retval FALSE Otherwise.
  79 */
  80 #define IS_END_OF_STREAM(Stream)  (                                           \
  81           (((AML_STREAM*)Stream)->Index ==                                    \
  82              ((AML_STREAM*)Stream)->MaxBufferSize))
  83
  84 /** Check Stream goes forward.
  85
  86   @param  [in]  Stream    Pointer to a stream.
  87
  88   @retval TRUE  Stream goes forward.
  89   @retval FALSE Otherwise.
  90 */
  91 #define IS_STREAM_FORWARD(Stream)   (                                         \
  92     ((AML_STREAM*)Stream)->Direction == EAmlStreamDirectionForward)
  93
  94 /** Check Stream goes backward.
  95
  96   @param  [in]  Stream   Pointer to a stream.
  97
  98   @retval TRUE  Stream goes backward.
  99   @retval FALSE Otherwise.
 100 */
 101 #define IS_STREAM_BACKWARD(Stream)   (                                        \
 102     ((AML_STREAM*)Stream)->Direction == EAmlStreamDirectionBackward)
 103
 104 /** Initialize a stream.
 105
 106   @param  [in, out] Stream          Pointer to the stream to initialize.
 107   @param  [in]      Buffer          Buffer to initialize Stream with.
 108                                     Point to the beginning of the Buffer.
 109   @param  [in]      MaxBufferSize   Maximum size of Buffer.
 110   @param  [in]      Direction       Direction Stream is progressing
 111                                     (forward, backward).
 112
 113   @retval EFI_SUCCESS             The function completed successfully.
 114   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 115 **/
 116 EFI_STATUS
 117 EFIAPI
 118 AmlStreamInit (
 119   IN  OUT AML_STREAM              * Stream,
 120   IN      UINT8                   * Buffer,
 121   IN      UINT32                    MaxBufferSize,
 122   IN      EAML_STREAM_DIRECTION     Direction
 123   );
 124
 125 /** Clone a stream.
 126
 127   Cloning a stream means copying all the values of the input Stream
 128   in the ClonedStream.
 129
 130   @param  [in]  Stream          Pointer to the stream to clone.
 131   @param  [in]  ClonedStream    Pointer to the stream to initialize.
 132
 133   @retval EFI_SUCCESS             The function completed successfully.
 134   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 AmlStreamClone (
 139   IN  CONST AML_STREAM    * Stream,
 140   OUT        AML_STREAM   * ClonedStream
 141   );
 142
 143 /** Initialize a sub-stream from a stream.
 144
 145   A sub-stream is a stream initialized at the current position of the input
 146   stream:
 147     - the Buffer field points to the current position of the input stream;
 148     - the Index field is set to 0;
 149     - the MaxBufferSize field is set to the remaining size of the input stream;
 150     - the direction is conserved;
 151
 152   E.g.: For a forward stream:
 153                    +----------------+----------------+
 154                    |ABCD.........XYZ|   Free Space   |
 155                    +----------------+----------------+
 156                    ^                ^                ^
 157   Stream:        Buffer          CurrPos         EndOfBuff
 158   Sub-stream:                Buffer/CurrPos      EndOfBuff
 159
 160   @param  [in]  Stream      Pointer to the stream from which a sub-stream is
 161                             created.
 162   @param  [in]  SubStream   Pointer to the stream to initialize.
 163
 164   @retval EFI_SUCCESS             The function completed successfully.
 165   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 166 **/
 167 EFI_STATUS
 168 EFIAPI
 169 AmlStreamInitSubStream (
 170   IN  CONST AML_STREAM  * Stream,
 171   OUT       AML_STREAM  * SubStream
 172   );
 173
 174 /** Get the buffer of a stream.
 175
 176   @param  [in]  Stream    Pointer to a stream.
 177
 178   @return The stream's Buffer.
 179           NULL otherwise.
 180 **/
 181 UINT8 *
 182 EFIAPI
 183 AmlStreamGetBuffer (
 184   IN  CONST AML_STREAM  * Stream
 185   );
 186
 187 /** Get the size of Stream's Buffer.
 188
 189   @param  [in]  Stream    Pointer to a stream.
 190
 191   @return The Size of Stream's Buffer.
 192           Return 0 if Stream is invalid.
 193 **/
 194 UINT32
 195 EFIAPI
 196 AmlStreamGetMaxBufferSize (
 197   IN  CONST AML_STREAM  * Stream
 198   );
 199
 200 /** Reduce the maximal size of Stream's Buffer (MaxBufferSize field).
 201
 202   @param  [in]  Stream    Pointer to a stream.
 203   @param  [in]  Diff      Value to subtract to the Stream's MaxBufferSize.
 204                           0 < x < MaxBufferSize - Index.
 205
 206   @retval EFI_SUCCESS             The function completed successfully.
 207   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 208 **/
 209 EFI_STATUS
 210 EFIAPI
 211 AmlStreamReduceMaxBufferSize (
 212   IN  AML_STREAM  * Stream,
 213   IN  UINT32        Diff
 214   );
 215
 216 /** Get Stream's Index.
 217
 218   Stream's Index is incremented when writing data, reading data,
 219   or moving the position in the Stream.
 220   It can be seen as an index:
 221    - starting at the beginning of Stream's Buffer if the stream goes forward;
 222    - starting at the end of Stream's Buffer if the stream goes backward.
 223
 224   @param  [in]  Stream    Pointer to a stream.
 225
 226   @return Stream's Index.
 227           Return 0 if Stream is invalid.
 228 **/
 229 UINT32
 230 EFIAPI
 231 AmlStreamGetIndex (
 232   IN  CONST AML_STREAM  * Stream
 233   );
 234
 235 /** Get Stream's Direction.
 236
 237   @param  [in]  Stream    Pointer to a stream.
 238
 239   @return Stream's Direction.
 240           Return EAmlStreamDirectionUnknown if Stream is invalid.
 241 **/
 242 EAML_STREAM_DIRECTION
 243 EFIAPI
 244 AmlStreamGetDirection (
 245   IN  CONST AML_STREAM  * Stream
 246   );
 247
 248 /** Return a pointer to the current position in the stream.
 249
 250   @param  [in]  Stream    Pointer to a stream.
 251
 252   @return The current position in the stream.
 253           Return NULL if error.
 254 **/
 255 UINT8 *
 256 EFIAPI
 257 AmlStreamGetCurrPos (
 258   IN  CONST AML_STREAM  * Stream
 259   );
 260
 261 /** Get the space available in the stream.
 262
 263   @param  [in]  Stream    Pointer to a stream.
 264
 265   @return Remaining space available in the stream.
 266           Zero in case of error or if the stream is at its end.
 267 **/
 268 UINT32
 269 EFIAPI
 270 AmlStreamGetFreeSpace (
 271   IN  CONST AML_STREAM  * Stream
 272   );
 273
 274 /** Move Stream by Offset bytes.
 275
 276   The stream current position is moved according to the stream direction
 277   (forward, backward).
 278
 279   @param  [in]  Stream  Pointer to a stream.
 280                         The stream must not be at its end.
 281   @param  [in]  Offset  Offset to move the stream of.
 282
 283   @retval EFI_SUCCESS             The function completed successfully.
 284   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 285   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 286 **/
 287 EFI_STATUS
 288 EFIAPI
 289 AmlStreamProgress (
 290   IN  AML_STREAM  * Stream,
 291   IN  UINT32        Offset
 292   );
 293
 294 /** Rewind Stream of Offset bytes.
 295
 296   The stream current position is rewound according to the stream direction
 297   (forward, backward). A stream going forward will be rewound backward.
 298
 299   @param  [in]  Stream  Pointer to a stream.
 300   @param  [in]  Offset  Offset to rewind the stream of.
 301
 302   @retval EFI_SUCCESS             The function completed successfully.
 303   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 304   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 305 **/
 306 EFI_STATUS
 307 EFIAPI
 308 AmlStreamRewind (
 309   IN  AML_STREAM  * Stream,
 310   IN  UINT32        Offset
 311   );
 312
 313 /** Reset the Stream (move the current position to the initial position).
 314
 315   @param  [in]  Stream  Pointer to a stream.
 316
 317   @retval EFI_SUCCESS             The function completed successfully.
 318   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 AmlStreamReset (
 323   IN  AML_STREAM  * Stream
 324   );
 325
 326 /** Peek one byte at Stream's current position.
 327
 328   Stream's position is not moved when peeking.
 329
 330   @param  [in]  Stream    Pointer to a stream.
 331                           The stream must not be at its end.
 332   @param  [out] OutByte   Pointer holding the byte value of
 333                           the stream current position.
 334
 335   @retval EFI_SUCCESS           The function completed successfully.
 336   @retval EFI_INVALID_PARAMETER Invalid parameter.
 337   @retval EFI_BUFFER_TOO_SMALL  No space left in the buffer.
 338 **/
 339 EFI_STATUS
 340 EFIAPI
 341 AmlStreamPeekByte (
 342   IN  AML_STREAM  * Stream,
 343   OUT UINT8       * OutByte
 344   );
 345
 346 /** Read one byte at Stream's current position.
 347
 348   The stream current position is moved when reading.
 349
 350   @param  [in]  Stream    Pointer to a stream.
 351                           The stream must not be at its end.
 352   @param  [out] OutByte   Pointer holding the byte value of
 353                           the stream current position.
 354
 355   @retval EFI_SUCCESS           The function completed successfully.
 356   @retval EFI_INVALID_PARAMETER Invalid parameter.
 357   @retval EFI_BUFFER_TOO_SMALL  No space left in the buffer.
 358 **/
 359 EFI_STATUS
 360 EFIAPI
 361 AmlStreamReadByte (
 362   IN  AML_STREAM  * Stream,
 363   OUT UINT8       * OutByte
 364   );
 365
 366 /** Write Size bytes in the stream.
 367
 368   If the stream goes backward (toward lower addresses), the bytes written
 369   to the stream are not reverted.
 370   In the example below, writing "Hello" to the stream will not revert
 371   the string. The end of the stream buffer will contain "Hello world!".
 372   Stream buffer:
 373      +---------------+-----+-----+-----+-----+-----+-----+---- +------+
 374      |         ..... | ' ' | 'w' | 'o' | 'r' | 'l' | 'd' | '!' | '\0' |
 375      +---------------+-----+-----+-----+-----+-----+-----+---- +------+
 376                         ^
 377                  Current position.
 378
 379   @param  [in]  Stream  Pointer to a stream.
 380                         The stream must not be at its end.
 381   @param  [in]  Buffer  Pointer to the data to write.
 382   @param  [in]  Size    Number of bytes to write.
 383
 384   @retval EFI_SUCCESS             The function completed successfully.
 385   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 386   @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
 387 **/
 388 EFI_STATUS
 389 EFIAPI
 390 AmlStreamWrite (
 391   IN        AML_STREAM  * Stream,
 392   IN  CONST UINT8       * Buffer,
 393   IN        UINT32        Size
 394   );
 395
 396 /** Compare Size bytes between Stream1 and Stream2 from their
 397     respective current position.
 398
 399   Stream1 and Stream2 must go in the same direction.
 400   Stream1 and Stream2 are left unchanged.
 401
 402   @param  [in]  Stream1   First stream to compare.
 403                           The stream must not be at its end.
 404   @param  [in]  Stream2   Second stream to compare.
 405                           The stream must not be at its end.
 406   @param  [in]  Size      Number of bytes to compare.
 407                           Must be lower than the minimum remaining space of
 408                           Stream1 and Stream2.
 409                           Must be non-zero.
 410
 411   @retval TRUE  If Stream1 and Stream2 have Size bytes equal,
 412                 from their respective current position.
 413                 The function completed successfully.
 414   @retval FALSE Otherwise.
 415 **/
 416 BOOLEAN
 417 EFIAPI
 418 AmlStreamCmp (
 419   IN  CONST AML_STREAM    * Stream1,
 420   IN  CONST AML_STREAM    * Stream2,
 421   IN        UINT32          Size
 422   );
 423
 424 /** Copy Size bytes of the stream's data to DstBuffer.
 425
 426   For a backward stream, the bytes are copied starting from the
 427   current stream position.
 428
 429   @param  [out] DstBuffer         Destination Buffer to copy the data to.
 430   @param  [in]  MaxDstBufferSize  Maximum size of DstBuffer.
 431                                   Must be non-zero.
 432   @param  [in]  Stream            Pointer to the stream to copy the data from.
 433   @param  [in]  Size              Number of bytes to copy from the stream
 434                                   buffer.
 435                                   Must be lower than MaxDstBufferSize.
 436                                   Must be lower than Stream's MaxBufferSize.
 437                                   Return success if zero.
 438
 439   @retval EFI_SUCCESS           The function completed successfully.
 440   @retval EFI_INVALID_PARAMETER Invalid parameter.
 441 **/
 442 EFI_STATUS
 443 EFIAPI
 444 AmlStreamCpyS (
 445   OUT CHAR8         * DstBuffer,
 446   IN  UINT32          MaxDstBufferSize,
 447   IN  AML_STREAM    * Stream,
 448   IN  UINT32          Size
 449   );
 450
 451 #endif // AML_STREAM_H_