include/qemu/fifo8.h

   1 #ifndef QEMU_FIFO8_H
   2 #define QEMU_FIFO8_H
   3
   4
   5 typedef struct {
   6     /* All fields are private */
   7     uint8_t *data;
   8     uint32_t capacity;
   9     uint32_t head;
  10     uint32_t num;
  11 } Fifo8;
  12
  13 /**
  14  * fifo8_create:
  15  * @fifo: struct Fifo8 to initialise with new FIFO
  16  * @capacity: capacity of the newly created FIFO
  17  *
  18  * Create a FIFO of the specified size. Clients should call fifo8_destroy()
  19  * when finished using the fifo. The FIFO is initially empty.
  20  */
  21
  22 void fifo8_create(Fifo8 *fifo, uint32_t capacity);
  23
  24 /**
  25  * fifo8_destroy:
  26  * @fifo: FIFO to cleanup
  27  *
  28  * Cleanup a FIFO created with fifo8_create(). Frees memory created for FIFO
  29   *storage. The FIFO is no longer usable after this has been called.
  30  */
  31
  32 void fifo8_destroy(Fifo8 *fifo);
  33
  34 /**
  35  * fifo8_push:
  36  * @fifo: FIFO to push to
  37  * @data: data byte to push
  38  *
  39  * Push a data byte to the FIFO. Behaviour is undefined if the FIFO is full.
  40  * Clients are responsible for checking for fullness using fifo8_is_full().
  41  */
  42
  43 void fifo8_push(Fifo8 *fifo, uint8_t data);
  44
  45 /**
  46  * fifo8_push_all:
  47  * @fifo: FIFO to push to
  48  * @data: data to push
  49  * @size: number of bytes to push
  50  *
  51  * Push a byte array to the FIFO. Behaviour is undefined if the FIFO is full.
  52  * Clients are responsible for checking the space left in the FIFO using
  53  * fifo8_num_free().
  54  */
  55
  56 void fifo8_push_all(Fifo8 *fifo, const uint8_t *data, uint32_t num);
  57
  58 /**
  59  * fifo8_pop:
  60  * @fifo: fifo to pop from
  61  *
  62  * Pop a data byte from the FIFO. Behaviour is undefined if the FIFO is empty.
  63  * Clients are responsible for checking for emptyness using fifo8_is_empty().
  64  *
  65  * Returns: The popped data byte.
  66  */
  67
  68 uint8_t fifo8_pop(Fifo8 *fifo);
  69
  70 /**
  71  * fifo8_pop_buf:
  72  * @fifo: FIFO to pop from
  73  * @max: maximum number of bytes to pop
  74  * @num: actual number of returned bytes
  75  *
  76  * Pop a number of elements from the FIFO up to a maximum of max. The buffer
  77  * containing the popped data is returned. This buffer points directly into
  78  * the FIFO backing store and data is invalidated once any of the fifo8_* APIs
  79  * are called on the FIFO.
  80  *
  81  * The function may return fewer bytes than requested when the data wraps
  82  * around in the ring buffer; in this case only a contiguous part of the data
  83  * is returned.
  84  *
  85  * The number of valid bytes returned is populated in *num; will always return
  86  * at least 1 byte. max must not be 0 or greater than the number of bytes in
  87  * the FIFO.
  88  *
  89  * Clients are responsible for checking the availability of requested data
  90  * using fifo8_num_used().
  91  *
  92  * Returns: A pointer to popped data.
  93  */
  94 const uint8_t *fifo8_pop_buf(Fifo8 *fifo, uint32_t max, uint32_t *num);
  95
  96 /**
  97  * fifo8_reset:
  98  * @fifo: FIFO to reset
  99  *
 100  * Reset a FIFO. All data is discarded and the FIFO is emptied.
 101  */
 102
 103 void fifo8_reset(Fifo8 *fifo);
 104
 105 /**
 106  * fifo8_is_empty:
 107  * @fifo: FIFO to check
 108  *
 109  * Check if a FIFO is empty.
 110  *
 111  * Returns: True if the fifo is empty, false otherwise.
 112  */
 113
 114 bool fifo8_is_empty(Fifo8 *fifo);
 115
 116 /**
 117  * fifo8_is_full:
 118  * @fifo: FIFO to check
 119  *
 120  * Check if a FIFO is full.
 121  *
 122  * Returns: True if the fifo is full, false otherwise.
 123  */
 124
 125 bool fifo8_is_full(Fifo8 *fifo);
 126
 127 /**
 128  * fifo8_num_free:
 129  * @fifo: FIFO to check
 130  *
 131  * Return the number of free bytes in the FIFO.
 132  *
 133  * Returns: Number of free bytes.
 134  */
 135
 136 uint32_t fifo8_num_free(Fifo8 *fifo);
 137
 138 /**
 139  * fifo8_num_used:
 140  * @fifo: FIFO to check
 141  *
 142  * Return the number of used bytes in the FIFO.
 143  *
 144  * Returns: Number of used bytes.
 145  */
 146
 147 uint32_t fifo8_num_used(Fifo8 *fifo);
 148
 149 extern const VMStateDescription vmstate_fifo8;
 150
 151 #define VMSTATE_FIFO8_TEST(_field, _state, _test) {                  \
 152     .name         = (stringify(_field)),                             \
 153     .field_exists = (_test),                                         \
 154     .size         = sizeof(Fifo8),                                   \
 155     .vmsd         = &vmstate_fifo8,                                  \
 156     .flags        = VMS_STRUCT,                                      \
 157     .offset       = vmstate_offset_value(_state, _field, Fifo8),     \
 158 }
 159
 160 #define VMSTATE_FIFO8(_field, _state)                                \
 161     VMSTATE_FIFO8_TEST(_field, _state, NULL)
 162
 163 #endif /* QEMU_FIFO8_H */