numa: add -numa node,memdev= option
[qemu.git] / include / qemu / fifo8.h
1 #ifndef FIFO_H
2 #define FIFO_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 /* FIFO_H */