audio_utils/include/audio_utils/fifo.h

   1 /*
   2  * Copyright (C) 2015 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_AUDIO_FIFO_H
  18 #define ANDROID_AUDIO_FIFO_H
  19
  20 #include <stdlib.h>
  21
  22 // FIXME use atomic_int_least32_t and new atomic operations instead of legacy Android ones
  23 // #include <stdatomic.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 // Single writer, single reader non-blocking FIFO.
  30 // Writer and reader must be in same process.
  31
  32 // No user-serviceable parts within.
  33 struct audio_utils_fifo {
  34     // These fields are const after initialization
  35     size_t     mFrameCount;   // max number of significant frames to be stored in the FIFO > 0
  36     size_t     mFrameCountP2; // roundup(mFrameCount)
  37     size_t     mFudgeFactor;  // mFrameCountP2 - mFrameCount, the number of "wasted" frames after
  38                               // the end of mBuffer.  Only the indices are wasted, not any memory.
  39     size_t     mFrameSize;    // size of each frame in bytes
  40     void      *mBuffer;       // pointer to caller-allocated buffer of size mFrameCount frames
  41
  42     volatile int32_t mFront; // frame index of first frame slot available to read, or read index
  43     volatile int32_t mRear;  // frame index of next frame slot available to write, or write index
  44 };
  45
  46 /**
  47  * Initialize a FIFO object.
  48  *
  49  *  \param fifo        Pointer to the FIFO object.
  50  *  \param frameCount  Max number of significant frames to be stored in the FIFO > 0.
  51  *                     If writes and reads always use the same count, and that count is a divisor of
  52  *                     frameCount, then the writes and reads will never do a partial transfer.
  53  *  \param frameSize   Size of each frame in bytes.
  54  *  \param buffer      Pointer to a caller-allocated buffer of frameCount frames.
  55  */
  56 void audio_utils_fifo_init(struct audio_utils_fifo *fifo, size_t frameCount, size_t frameSize,
  57         void *buffer);
  58
  59 /**
  60  * De-initialize a FIFO object.
  61  *
  62  *  \param fifo        Pointer to the FIFO object.
  63  */
  64 void audio_utils_fifo_deinit(struct audio_utils_fifo *fifo);
  65
  66 /**
  67  * Write to FIFO.
  68  *
  69  *  \param fifo        Pointer to the FIFO object.
  70  *  \param buffer      Pointer to source buffer containing 'count' frames of data.
  71  *  \param count       Desired number of frames to write.
  72  *
  73  * \return actual number of frames written <= count.
  74  *
  75  * The actual transfer count may be zero if the FIFO is full,
  76  * or partial if the FIFO was almost full.
  77  * A negative return value indicates an error.  Currently there are no errors defined.
  78  */
  79 ssize_t audio_utils_fifo_write(struct audio_utils_fifo *fifo, const void *buffer, size_t count);
  80
  81 /** Read from FIFO.
  82  *
  83  *  \param fifo        Pointer to the FIFO object.
  84  *  \param buffer      Pointer to destination buffer to be filled with up to 'count' frames of data.
  85  *  \param count       Desired number of frames to read.
  86  *
  87  * \return actual number of frames read <= count.
  88  *
  89  * The actual transfer count may be zero if the FIFO is empty,
  90  * or partial if the FIFO was almost empty.
  91  * A negative return value indicates an error.  Currently there are no errors defined.
  92  */
  93 ssize_t audio_utils_fifo_read(struct audio_utils_fifo *fifo, void *buffer, size_t count);
  94
  95 #ifdef __cplusplus
  96 }
  97 #endif
  98
  99 #endif  // !ANDROID_AUDIO_FIFO_H