LXR qemu/include/qemu/fifo8.h

   1#ifndef FIFO_H
   2#define FIFO_H
   3
   4#include "migration/vmstate.h"
   5
   6typedef 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
  23void 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
  33void 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
  44void 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
  57void 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
  69uint8_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 */
  95const 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
 104void 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
 115bool 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
 126bool 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
 137uint32_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
 148uint32_t fifo8_num_used(Fifo8 *fifo);
 149
 150extern 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 /* FIFO_H */
 161