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 capacity. Clients should call fifo8_destroy() 19 * when finished using the fifo. The FIFO is initially empty. 20 */ 21 void fifo8_create(Fifo8 *fifo, uint32_t capacity); 22 23 /** 24 * fifo8_destroy: 25 * @fifo: FIFO to cleanup 26 * 27 * Cleanup a FIFO created with fifo8_create(). Frees memory created for FIFO 28 * storage. The FIFO is no longer usable after this has been called. 29 */ 30 void fifo8_destroy(Fifo8 *fifo); 31 32 /** 33 * fifo8_push: 34 * @fifo: FIFO to push to 35 * @data: data byte to push 36 * 37 * Push a data byte to the FIFO. Behaviour is undefined if the FIFO is full. 38 * Clients are responsible for checking for fullness using fifo8_is_full(). 39 */ 40 void fifo8_push(Fifo8 *fifo, uint8_t data); 41 42 /** 43 * fifo8_push_all: 44 * @fifo: FIFO to push to 45 * @data: data to push 46 * @num: number of bytes to push 47 * 48 * Push a byte array to the FIFO. Behaviour is undefined if the FIFO is full. 49 * Clients are responsible for checking the space left in the FIFO using 50 * fifo8_num_free(). 51 */ 52 void fifo8_push_all(Fifo8 *fifo, const uint8_t *data, uint32_t num); 53 54 /** 55 * fifo8_pop: 56 * @fifo: fifo to pop from 57 * 58 * Pop a data byte from the FIFO. Behaviour is undefined if the FIFO is empty. 59 * Clients are responsible for checking for emptyness using fifo8_is_empty(). 60 * 61 * Returns: The popped data byte. 62 */ 63 uint8_t fifo8_pop(Fifo8 *fifo); 64 65 /** 66 * fifo8_peek: 67 * @fifo: fifo to peek from 68 * 69 * Peek the data byte at the current head of the FIFO. Clients are responsible 70 * for checking for emptyness using fifo8_is_empty(). 71 * 72 * Returns: The peeked data byte. 73 */ 74 uint8_t fifo8_peek(Fifo8 *fifo); 75 76 /** 77 * fifo8_pop_buf: 78 * @fifo: FIFO to pop from 79 * @dest: the buffer to write the data into (can be NULL) 80 * @destlen: size of @dest and maximum number of bytes to pop 81 * 82 * Pop a number of elements from the FIFO up to a maximum of @destlen. 83 * The popped data is copied into the @dest buffer. 84 * Care is taken when the data wraps around in the ring buffer. 85 * 86 * Returns: number of bytes popped. 87 */ 88 uint32_t fifo8_pop_buf(Fifo8 *fifo, uint8_t *dest, uint32_t destlen); 89 90 /** 91 * fifo8_peek_buf: 92 * @fifo: FIFO to read from 93 * @dest: the buffer to write the data into (can be NULL) 94 * @destlen: size of @dest and maximum number of bytes to peek 95 * 96 * Peek a number of elements from the FIFO up to a maximum of @destlen. 97 * The peeked data is copied into the @dest buffer. 98 * Care is taken when the data wraps around in the ring buffer. 99 * 100 * Returns: number of bytes peeked. 101 */ 102 uint32_t fifo8_peek_buf(Fifo8 *fifo, uint8_t *dest, uint32_t destlen); 103 104 /** 105 * fifo8_pop_bufptr: 106 * @fifo: FIFO to pop from 107 * @max: maximum number of bytes to pop 108 * @numptr: pointer filled with number of bytes returned (can be NULL) 109 * 110 * New code should prefer to use fifo8_pop_buf() instead of fifo8_pop_bufptr(). 111 * 112 * Pop a number of elements from the FIFO up to a maximum of @max. The buffer 113 * containing the popped data is returned. This buffer points directly into 114 * the internal FIFO backing store and data (without checking for overflow!) 115 * and is invalidated once any of the fifo8_* APIs are called on the FIFO. 116 * 117 * The function may return fewer bytes than requested when the data wraps 118 * around in the ring buffer; in this case only a contiguous part of the data 119 * is returned. 120 * 121 * The number of valid bytes returned is populated in *@numptr; will always 122 * return at least 1 byte. max must not be 0 or greater than the number of 123 * bytes in the FIFO. 124 * 125 * Clients are responsible for checking the availability of requested data 126 * using fifo8_num_used(). 127 * 128 * Returns: A pointer to popped data. 129 */ 130 const uint8_t *fifo8_pop_bufptr(Fifo8 *fifo, uint32_t max, uint32_t *numptr); 131 132 /** 133 * fifo8_peek_bufptr: read upto max bytes from the fifo 134 * @fifo: FIFO to read from 135 * @max: maximum number of bytes to peek 136 * @numptr: pointer filled with number of bytes returned (can be NULL) 137 * 138 * Peek into a number of elements from the FIFO up to a maximum of @max. 139 * The buffer containing the data peeked into is returned. This buffer points 140 * directly into the FIFO backing store. Since data is invalidated once any 141 * of the fifo8_* APIs are called on the FIFO, it is the caller responsibility 142 * to access it before doing further API calls. 143 * 144 * The function may return fewer bytes than requested when the data wraps 145 * around in the ring buffer; in this case only a contiguous part of the data 146 * is returned. 147 * 148 * The number of valid bytes returned is populated in *@numptr; will always 149 * return at least 1 byte. max must not be 0 or greater than the number of 150 * bytes in the FIFO. 151 * 152 * Clients are responsible for checking the availability of requested data 153 * using fifo8_num_used(). 154 * 155 * Returns: A pointer to peekable data. 156 */ 157 const uint8_t *fifo8_peek_bufptr(Fifo8 *fifo, uint32_t max, uint32_t *numptr); 158 159 /** 160 * fifo8_drop: 161 * @fifo: FIFO to drop bytes 162 * @len: number of bytes to drop 163 * 164 * Drop (consume) bytes from a FIFO. 165 */ 166 void fifo8_drop(Fifo8 *fifo, uint32_t len); 167 168 /** 169 * fifo8_reset: 170 * @fifo: FIFO to reset 171 * 172 * Reset a FIFO. All data is discarded and the FIFO is emptied. 173 */ 174 void fifo8_reset(Fifo8 *fifo); 175 176 /** 177 * fifo8_is_empty: 178 * @fifo: FIFO to check 179 * 180 * Check if a FIFO is empty. 181 * 182 * Returns: True if the fifo is empty, false otherwise. 183 */ 184 bool fifo8_is_empty(Fifo8 *fifo); 185 186 /** 187 * fifo8_is_full: 188 * @fifo: FIFO to check 189 * 190 * Check if a FIFO is full. 191 * 192 * Returns: True if the fifo is full, false otherwise. 193 */ 194 bool fifo8_is_full(Fifo8 *fifo); 195 196 /** 197 * fifo8_num_free: 198 * @fifo: FIFO to check 199 * 200 * Return the number of free bytes in the FIFO. 201 * 202 * Returns: Number of free bytes. 203 */ 204 uint32_t fifo8_num_free(Fifo8 *fifo); 205 206 /** 207 * fifo8_num_used: 208 * @fifo: FIFO to check 209 * 210 * Return the number of used bytes in the FIFO. 211 * 212 * Returns: Number of used bytes. 213 */ 214 uint32_t fifo8_num_used(Fifo8 *fifo); 215 216 extern const VMStateDescription vmstate_fifo8; 217 218 #define VMSTATE_FIFO8_TEST(_field, _state, _test) { \ 219 .name = (stringify(_field)), \ 220 .field_exists = (_test), \ 221 .size = sizeof(Fifo8), \ 222 .vmsd = &vmstate_fifo8, \ 223 .flags = VMS_STRUCT, \ 224 .offset = vmstate_offset_value(_state, _field, Fifo8), \ 225 } 226 227 #define VMSTATE_FIFO8(_field, _state) \ 228 VMSTATE_FIFO8_TEST(_field, _state, NULL) 229 230 #endif /* QEMU_FIFO8_H */ 231