DeviceQueue: shared memory queue implementation
[barrelfish] / lib / devif / desc_queue.h
1 /*
2  * Copyright (c) 2016 ETH Zurich.
3  * All rights reserved.
4  *
5  * This file is distributed under the terms in the attached LICENSE file.
6  * If you do not find this file, copies can be found by writing to:
7  * ETH Zurich D-INFK, Universitaetstr. 6, CH-8092 Zurich. Attn: Systems Group.
8  */
9 #ifndef DESCQ_H_
10 #define DESCQ_H_ 1
11
12
13 #include <barrelfish/barrelfish.h>
14 #include <devif/queue_interface.h>
15
16 #define DESCQ_DEFAULT_SIZE 64
17 #define DESCQ_ALIGNMENT 64
18
19 struct descq;
20 /**
21  * @brief initialized a descriptor queue
22  *
23  * @param q                     Return pointer to the descriptor queue
24  * @param shm                   Cap of the shared memory of the queue
25  * @param slots                 Number of slots in the queue
26  *
27  * @returns error on failure or SYS_ERR_OK on success
28  */
29 errval_t descq_init(struct descq** q,
30                     struct capref shm,
31                     size_t slots);
32
33 /**
34  * @brief Destroys a descriptor queue and frees its resources
35  *
36  * @param q                     The descriptor queue
37  *
38  * @returns error on failure or SYS_ERR_OK on success
39  */
40 errval_t descq_destroy(struct descq* q);
41
42 /**
43  * @brief Enqueue a descriptor (as seperate fields) 
44  *        into the descriptor queue
45  *
46  * @param q                     The descriptor queue
47  * @param region_id             Region id of the enqueued buffer
48  * @param buffer_id             Buffer id of the buffer
49  * @param base                  Physical address of hte buffer
50  * @param len                   Lenght of the buffer
51  * @param misc_flags            Miscellaneous flags
52  *
53  * @returns error if queue is full or SYS_ERR_OK on success
54  */
55 errval_t descq_enqueue(struct descq* q,
56                        regionid_t region_id,
57                        bufferid_t buffer_id,
58                        lpaddr_t base,
59                        size_t len,
60                        uint64_t misc_flags);
61
62 /**
63  * @brief Dequeue a descriptor (as seperate fields) 
64  *        from the descriptor queue
65  *
66  * @param q                     The descriptor queue
67  * @param region_id             Return pointer to the region id of 
68  *                              the denqueued buffer
69  * @param buffer_id             Return pointer to the buffer id of the buffer
70  * @param base                  Return pointer to the physical address 
71  *                              of the buffer
72  * @param len                   Return pointer to the lenght of the buffer
73  * @param misc_flags            Return pointer to miscellaneous flags
74  *
75  * @returns error if queue is empty or SYS_ERR_OK on success
76  */
77 errval_t descq_dequeue(struct descq* q,
78                        regionid_t* region_id,
79                        bufferid_t* buffer_id,
80                        lpaddr_t* base,
81                        size_t* len,
82                        uint64_t* misc_flags);
83
84 /**
85  * @brief Writes the local head pointer into the shared memory
86  *        making the state of the queue visible to the other end
87  *
88  * @param q                     The descriptor queue
89  *
90  */
91 void descq_writeout_head(struct descq* q);
92 /**
93  * @brief Writes the local tail pointer into the shared memory
94  *        making the state of the queue visible to the other end
95  *
96  * @param q                     The descriptor queue
97  *
98  */
99 void descq_writeout_tail(struct descq* q);
100
101 /**
102  * @brief Check if the descriptor queue is full
103  *
104  * @param q                     The descriptor queue
105  *
106  * @returns true if the queue is full, otherwise false
107  */
108 bool descq_full(struct descq* q);
109
110 /**
111  * @brief Check if the descriptor queue is empty
112  *
113  * @param q                     The descriptor queue
114  *
115  * @returns true if the queue is empty, otherwise false
116  */
117 bool descq_empty(struct descq* q);
118
119 /**
120  * @brief Returns the number of occupied slots in the queue
121  *
122  * @param q                     The descriptor queue
123  *
124  * @returns the number of occupied slots
125  */
126 size_t descq_full_slots(struct descq* q);
127
128 #endif /* DESCQ_H_ */