include/qemu/fifo8.h

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