Gitiles
Code Review Sign In
git01.mediatek.com / filogic / uboot / 86e06aec214e2fc9ff0d6f79a4593ba89bce566a / . / include / xen / interface / io / ring.h
blob: 3c5c87deda9968da3cc1f35e4c66e512e73d9593 [file] [log] [blame]
Oleksandr Andrushchenko7fd47cc2020-08-06 12:42:46 +0300[diff] [blame]1/* SPDX-License-Identifier: MIT
2 *
3 * ring.h
4 *
5 * Shared producer-consumer ring macros.
6 *
7 * Tim Deegan and Andrew Warfield November 2004.
8 */
9
10#ifndef __XEN_PUBLIC_IO_RING_H__
11#define __XEN_PUBLIC_IO_RING_H__
12
13/*
14 * When #include'ing this header, you need to provide the following
15 * declaration upfront:
16 * - standard integers types (u8, u16, etc)
17 * They are provided by stdint.h of the standard headers.
18 *
19 * In addition, if you intend to use the FLEX macros, you also need to
20 * provide the following, before invoking the FLEX macros:
21 * - size_t
22 * - memcpy
23 * - grant_ref_t
24 * These declarations are provided by string.h of the standard headers,
25 * and grant_table.h from the Xen public headers.
26 */
27
28#include <xen/interface/grant_table.h>
29
30typedef unsigned int RING_IDX;
31
32/* Round a 32-bit unsigned constant down to the nearest power of two. */
33#define __RD2(_x) (((_x) & 0x00000002) ? 0x2 : ((_x) & 0x1))
34#define __RD4(_x) (((_x) & 0x0000000c) ? __RD2((_x) >> 2) << 2 : __RD2(_x))
35#define __RD8(_x) (((_x) & 0x000000f0) ? __RD4((_x) >> 4) << 4 : __RD4(_x))
36#define __RD16(_x) (((_x) & 0x0000ff00) ? __RD8((_x) >> 8) << 8 : __RD8(_x))
37#define __RD32(_x) (((_x) & 0xffff0000) ? __RD16((_x) >> 16) << 16 : __RD16(_x))
38
39/*
40 * Calculate size of a shared ring, given the total available space for the
41 * ring and indexes (_sz), and the name tag of the request/response structure.
42 * A ring contains as many entries as will fit, rounded down to the nearest
43 * power of two (so we can mask with (size-1) to loop around).
44 */
45#define __CONST_RING_SIZE(_s, _sz) \
46 (__RD32(((_sz) - offsetof(struct _s##_sring, ring)) / \
47 sizeof(((struct _s##_sring *)0)->ring[0])))
48/*
49 * The same for passing in an actual pointer instead of a name tag.
50 */
51#define __RING_SIZE(_s, _sz) \
52 (__RD32(((_sz) - (long)(_s)->ring + (long)(_s)) / sizeof((_s)->ring[0])))
53
54/*
55 * Macros to make the correct C datatypes for a new kind of ring.
56 *
57 * To make a new ring datatype, you need to have two message structures,
58 * let's say request_t, and response_t already defined.
59 *
60 * In a header where you want the ring datatype declared, you then do:
61 *
62 * DEFINE_RING_TYPES(mytag, request_t, response_t);
63 *
64 * These expand out to give you a set of types, as you can see below.
65 * The most important of these are:
66 *
67 * mytag_sring_t - The shared ring.
68 * mytag_front_ring_t - The 'front' half of the ring.
69 * mytag_back_ring_t - The 'back' half of the ring.
70 *
71 * To initialize a ring in your code you need to know the location and size
72 * of the shared memory area (PAGE_SIZE, for instance). To initialise
73 * the front half:
74 *
75 * mytag_front_ring_t front_ring;
76 * SHARED_RING_INIT((mytag_sring_t *)shared_page);
77 * FRONT_RING_INIT(&front_ring, (mytag_sring_t *)shared_page, PAGE_SIZE);
78 *
79 * Initializing the back follows similarly (note that only the front
80 * initializes the shared ring):
81 *
82 * mytag_back_ring_t back_ring;
83 * BACK_RING_INIT(&back_ring, (mytag_sring_t *)shared_page, PAGE_SIZE);
84 */
85
86#define DEFINE_RING_TYPES(__name, __req_t, __rsp_t) \
87 \
88/* Shared ring entry */ \
89union __name##_sring_entry { \
90 __req_t req; \
91 __rsp_t rsp; \
92}; \
93 \
94/* Shared ring page */ \
95struct __name##_sring { \
96 RING_IDX req_prod, req_event; \
97 RING_IDX rsp_prod, rsp_event; \
98 union { \
99 struct { \
100 u8 smartpoll_active; \
101 } netif; \
102 struct { \
103 u8 msg; \
104 } tapif_user; \
105 u8 pvt_pad[4]; \
106 } pvt; \
107 u8 __pad[44]; \
108 union __name##_sring_entry ring[1]; /* variable-length */ \
109}; \
110 \
111/* "Front" end's private variables */ \
112struct __name##_front_ring { \
113 RING_IDX req_prod_pvt; \
114 RING_IDX rsp_cons; \
115 unsigned int nr_ents; \
116 struct __name##_sring *sring; \
117}; \
118 \
119/* "Back" end's private variables */ \
120struct __name##_back_ring { \
121 RING_IDX rsp_prod_pvt; \
122 RING_IDX req_cons; \
123 unsigned int nr_ents; \
124 struct __name##_sring *sring; \
125}; \
126 \
127/* Syntactic sugar */ \
128typedef struct __name##_sring __name##_sring_t; \
129typedef struct __name##_front_ring __name##_front_ring_t; \
130typedef struct __name##_back_ring __name##_back_ring_t
131
132/*
133 * Macros for manipulating rings.
134 *
135 * FRONT_RING_whatever works on the "front end" of a ring: here
136 * requests are pushed on to the ring and responses taken off it.
137 *
138 * BACK_RING_whatever works on the "back end" of a ring: here
139 * requests are taken off the ring and responses put on.
140 *
141 * N.B. these macros do NO INTERLOCKS OR FLOW CONTROL.
142 * This is OK in 1-for-1 request-response situations where the
143 * requestor (front end) never has more than RING_SIZE()-1
144 * outstanding requests.
145 */
146
147/* Initialising empty rings */
148#define SHARED_RING_INIT(_s) do { \
149 (_s)->req_prod = (_s)->rsp_prod = 0; \
150 (_s)->req_event = (_s)->rsp_event = 1; \
151 (void)memset((_s)->pvt.pvt_pad, 0, sizeof((_s)->pvt.pvt_pad)); \
152 (void)memset((_s)->__pad, 0, sizeof((_s)->__pad)); \
153} while (0)
154
155#define FRONT_RING_INIT(_r, _s, __size) do { \
156 (_r)->req_prod_pvt = 0; \
157 (_r)->rsp_cons = 0; \
158 (_r)->nr_ents = __RING_SIZE(_s, __size); \
159 (_r)->sring = (_s); \
160} while (0)
161
162#define BACK_RING_INIT(_r, _s, __size) do { \
163 (_r)->rsp_prod_pvt = 0; \
164 (_r)->req_cons = 0; \
165 (_r)->nr_ents = __RING_SIZE(_s, __size); \
166 (_r)->sring = (_s); \
167} while (0)
168
169/* How big is this ring? */
170#define RING_SIZE(_r) \
171 ((_r)->nr_ents)
172
173/* Number of free requests (for use on front side only). */
174#define RING_FREE_REQUESTS(_r) \
175 (RING_SIZE(_r) - ((_r)->req_prod_pvt - (_r)->rsp_cons))
176
177/* Test if there is an empty slot available on the front ring.
178 * (This is only meaningful from the front. )
179 */
180#define RING_FULL(_r) \
181 (RING_FREE_REQUESTS(_r) == 0)
182
183/* Test if there are outstanding messages to be processed on a ring. */
184#define RING_HAS_UNCONSUMED_RESPONSES(_r) \
185 ((_r)->sring->rsp_prod - (_r)->rsp_cons)
186
187#ifdef __GNUC__
188#define RING_HAS_UNCONSUMED_REQUESTS(_r) ({ \
189 unsigned int req = (_r)->sring->req_prod - (_r)->req_cons; \
190 unsigned int rsp = RING_SIZE(_r) - \
191 ((_r)->req_cons - (_r)->rsp_prod_pvt); \
192 req < rsp ? req : rsp; \
193})
194#else
195/* Same as above, but without the nice GCC ({ ... }) syntax. */
196#define RING_HAS_UNCONSUMED_REQUESTS(_r) \
197 ((((_r)->sring->req_prod - (_r)->req_cons) < \
198 (RING_SIZE(_r) - ((_r)->req_cons - (_r)->rsp_prod_pvt))) ? \
199 ((_r)->sring->req_prod - (_r)->req_cons) : \
200 (RING_SIZE(_r) - ((_r)->req_cons - (_r)->rsp_prod_pvt)))
201#endif
202
203/* Direct access to individual ring elements, by index. */
204#define RING_GET_REQUEST(_r, _idx) \
205 (&((_r)->sring->ring[((_idx) & (RING_SIZE(_r) - 1))].req))
206
207/*
208 * Get a local copy of a request.
209 *
210 * Use this in preference to RING_GET_REQUEST() so all processing is
211 * done on a local copy that cannot be modified by the other end.
212 *
213 * Note that https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58145 may cause this
214 * to be ineffective where _req is a struct which consists of only bitfields.
215 */
216#define RING_COPY_REQUEST(_r, _idx, _req) do { \
217 /* Use volatile to force the copy into _req. */ \
218 *(_req) = *(volatile typeof(_req))RING_GET_REQUEST(_r, _idx); \
219} while (0)
220
221#define RING_GET_RESPONSE(_r, _idx) \
222 (&((_r)->sring->ring[((_idx) & (RING_SIZE(_r) - 1))].rsp))
223
224/* Loop termination condition: Would the specified index overflow the ring? */
225#define RING_REQUEST_CONS_OVERFLOW(_r, _cons) \
226 (((_cons) - (_r)->rsp_prod_pvt) >= RING_SIZE(_r))
227
228/* Ill-behaved frontend determination: Can there be this many requests? */
229#define RING_REQUEST_PROD_OVERFLOW(_r, _prod) \
230 (((_prod) - (_r)->rsp_prod_pvt) > RING_SIZE(_r))
231
232#define RING_PUSH_REQUESTS(_r) do { \
233 xen_wmb(); /* back sees requests /before/ updated producer index */ \
234 (_r)->sring->req_prod = (_r)->req_prod_pvt; \
235} while (0)
236
237#define RING_PUSH_RESPONSES(_r) do { \
238 xen_wmb(); /* front sees resps /before/ updated producer index */ \
239 (_r)->sring->rsp_prod = (_r)->rsp_prod_pvt; \
240} while (0)
241
242/*
243 * Notification hold-off (req_event and rsp_event):
244 *
245 * When queueing requests or responses on a shared ring, it may not always be
246 * necessary to notify the remote end. For example, if requests are in flight
247 * in a backend, the front may be able to queue further requests without
248 * notifying the back (if the back checks for new requests when it queues
249 * responses).
250 *
251 * When enqueuing requests or responses:
252 *
253 * Use RING_PUSH_{REQUESTS,RESPONSES}_AND_CHECK_NOTIFY(). The second argument
254 * is a boolean return value. True indicates that the receiver requires an
255 * asynchronous notification.
256 *
257 * After dequeuing requests or responses (before sleeping the connection):
258 *
259 * Use RING_FINAL_CHECK_FOR_REQUESTS() or RING_FINAL_CHECK_FOR_RESPONSES().
260 * The second argument is a boolean return value. True indicates that there
261 * are pending messages on the ring (i.e., the connection should not be put
262 * to sleep).
263 *
264 * These macros will set the req_event/rsp_event field to trigger a
265 * notification on the very next message that is enqueued. If you want to
266 * create batches of work (i.e., only receive a notification after several
267 * messages have been enqueued) then you will need to create a customised
268 * version of the FINAL_CHECK macro in your own code, which sets the event
269 * field appropriately.
270 */
271
272#define RING_PUSH_REQUESTS_AND_CHECK_NOTIFY(_r, _notify) do { \
273 RING_IDX __old = (_r)->sring->req_prod; \
274 RING_IDX __new = (_r)->req_prod_pvt; \
275 xen_wmb(); /* back sees requests /before/ updated producer index */ \
276 (_r)->sring->req_prod = __new; \
277 xen_mb(); /* back sees new requests /before/ we check req_event */ \
278 (_notify) = ((RING_IDX)(__new - (_r)->sring->req_event) < \
279 (RING_IDX)(__new - __old)); \
280} while (0)
281
282#define RING_PUSH_RESPONSES_AND_CHECK_NOTIFY(_r, _notify) do { \
283 RING_IDX __old = (_r)->sring->rsp_prod; \
284 RING_IDX __new = (_r)->rsp_prod_pvt; \
285 xen_wmb(); /* front sees resps /before/ updated producer index */ \
286 (_r)->sring->rsp_prod = __new; \
287 xen_mb(); /* front sees new resps /before/ we check rsp_event */ \
288 (_notify) = ((RING_IDX)(__new - (_r)->sring->rsp_event) < \
289 (RING_IDX)(__new - __old)); \
290} while (0)
291
292#define RING_FINAL_CHECK_FOR_REQUESTS(_r, _work_to_do) do { \
293 (_work_to_do) = RING_HAS_UNCONSUMED_REQUESTS(_r); \
294 if (_work_to_do) \
295 break; \
296 (_r)->sring->req_event = (_r)->req_cons + 1; \
297 xen_mb(); \
298 (_work_to_do) = RING_HAS_UNCONSUMED_REQUESTS(_r); \
299} while (0)
300
301#define RING_FINAL_CHECK_FOR_RESPONSES(_r, _work_to_do) do { \
302 (_work_to_do) = RING_HAS_UNCONSUMED_RESPONSES(_r); \
303 if (_work_to_do) \
304 break; \
305 (_r)->sring->rsp_event = (_r)->rsp_cons + 1; \
306 xen_mb(); \
307 (_work_to_do) = RING_HAS_UNCONSUMED_RESPONSES(_r); \
308} while (0)
309
310/*
311 * DEFINE_XEN_FLEX_RING_AND_INTF defines two monodirectional rings and
312 * functions to check if there is data on the ring, and to read and
313 * write to them.
314 *
315 * DEFINE_XEN_FLEX_RING is similar to DEFINE_XEN_FLEX_RING_AND_INTF, but
316 * does not define the indexes page. As different protocols can have
317 * extensions to the basic format, this macro allow them to define their
318 * own struct.
319 *
320 * XEN_FLEX_RING_SIZE
321 * Convenience macro to calculate the size of one of the two rings
322 * from the overall order.
323 *
324 * $NAME_mask
325 * Function to apply the size mask to an index, to reduce the index
326 * within the range [0-size].
327 *
328 * $NAME_read_packet
329 * Function to read data from the ring. The amount of data to read is
330 * specified by the "size" argument.
331 *
332 * $NAME_write_packet
333 * Function to write data to the ring. The amount of data to write is
334 * specified by the "size" argument.
335 *
336 * $NAME_get_ring_ptr
337 * Convenience function that returns a pointer to read/write to the
338 * ring at the right location.
339 *
340 * $NAME_data_intf
341 * Indexes page, shared between frontend and backend. It also
342 * contains the array of grant refs.
343 *
344 * $NAME_queued
345 * Function to calculate how many bytes are currently on the ring,
346 * ready to be read. It can also be used to calculate how much free
347 * space is currently on the ring (XEN_FLEX_RING_SIZE() -
348 * $NAME_queued()).
349 */
350
351#ifndef XEN_PAGE_SHIFT
352/* The PAGE_SIZE for ring protocols and hypercall interfaces is always
353 * 4K, regardless of the architecture, and page granularity chosen by
354 * operating systems.
355 */
356#define XEN_PAGE_SHIFT 12
357#endif
358#define XEN_FLEX_RING_SIZE(order) \
359 (1UL << ((order) + XEN_PAGE_SHIFT - 1))
360
361#define DEFINE_XEN_FLEX_RING(name) \
362static inline RING_IDX name##_mask(RING_IDX idx, RING_IDX ring_size) \
363{ \
364 return idx & (ring_size - 1); \
365} \
366 \
367static inline unsigned char *name##_get_ring_ptr(unsigned char *buf, \
368 RING_IDX idx, \
369 RING_IDX ring_size) \
370{ \
371 return buf + name##_mask(idx, ring_size); \
372} \
373 \
374static inline void name##_read_packet(void *opaque, \
375 const unsigned char *buf, \
376 size_t size, \
377 RING_IDX masked_prod, \
378 RING_IDX *masked_cons, \
379 RING_IDX ring_size) \
380{ \
381 if (*masked_cons < masked_prod || \
382 size <= ring_size - *masked_cons) { \
383 memcpy(opaque, buf + *masked_cons, size); \
384 } else { \
385 memcpy(opaque, buf + *masked_cons, ring_size - *masked_cons); \
386 memcpy((unsigned char *)opaque + ring_size - *masked_cons, buf, \
387 size - (ring_size - *masked_cons)); \
388 } \
389 *masked_cons = name##_mask(*masked_cons + size, ring_size); \
390} \
391 \
392static inline void name##_write_packet(unsigned char *buf, \
393 const void *opaque, \
394 size_t size, \
395 RING_IDX *masked_prod, \
396 RING_IDX masked_cons, \
397 RING_IDX ring_size) \
398{ \
399 if (*masked_prod < masked_cons || \
400 size <= ring_size - *masked_prod) { \
401 memcpy(buf + *masked_prod, opaque, size); \
402 } else { \
403 memcpy(buf + *masked_prod, opaque, ring_size - *masked_prod); \
404 memcpy(buf, (unsigned char *)opaque + (ring_size - *masked_prod), \
405 size - (ring_size - *masked_prod)); \
406 } \
407 *masked_prod = name##_mask(*masked_prod + size, ring_size); \
408} \
409 \
410static inline RING_IDX name##_queued(RING_IDX prod, \
411 RING_IDX cons, \
412 RING_IDX ring_size) \
413{ \
414 RING_IDX size; \
415 \
416 if (prod == cons) \
417 return 0; \
418 \
419 prod = name##_mask(prod, ring_size); \
420 cons = name##_mask(cons, ring_size); \
421 \
422 if (prod == cons) \
423 return ring_size; \
424 \
425 if (prod > cons) \
426 size = prod - cons; \
427 else \
428 size = ring_size - (cons - prod); \
429 return size; \
430} \
431 \
432struct name##_data { \
433 unsigned char *in; /* half of the allocation */ \
434 unsigned char *out; /* half of the allocation */ \
435}
436
437#define DEFINE_XEN_FLEX_RING_AND_INTF(name) \
438struct name##_data_intf { \
439 RING_IDX in_cons, in_prod; \
440 \
441 u8 pad1[56]; \
442 \
443 RING_IDX out_cons, out_prod; \
444 \
445 u8 pad2[56]; \
446 \
447 RING_IDX ring_order; \
448 grant_ref_t ref[]; \
449}; \
450DEFINE_XEN_FLEX_RING(name)
451
452#endif /* __XEN_PUBLIC_IO_RING_H__ */
453
454/*
455 * Local variables:
456 * mode: C
457 * c-file-style: "BSD"
458 * c-basic-offset: 4
459 * tab-width: 8
460 * indent-tabs-mode: nil
461 * End:
462 */