91f3d5e853753b6f24e25d52cb71a9066e16f856
[barrelfish] / include / devif / queue_interface.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 QUEUE_INTERFACE_H_
10 #define QUEUE_INTERFACE_H_ 1
11
12
13 #include <barrelfish/barrelfish.h>
14
15 #define DEVQ_BUF_FLAG_TX 0x1
16 #define DEVQ_BUF_FLAG_RX 0x2
17 #define DEVQ_BUF_FLAG_TX_LAST 0x4
18
19
20
21 typedef uint32_t regionid_t;
22 typedef uint32_t bufferid_t;
23
24
25 struct devq;
26 struct region_pool;
27
28 // For convinience reason buffer descritpion in one struct
29 struct devq_buf{
30     regionid_t rid; // 4
31     bufferid_t bid; // 8
32     lpaddr_t addr; // 16
33     size_t len; // 24
34     uint64_t flags; // 32
35 };
36
37 /*
38  * ===========================================================================
39  * Datapath functions
40  * ===========================================================================
41  */
42 /*
43  *
44  * @brief enqueue a buffer into the device queue
45  *
46  * @param q             The device queue to call the operation on
47  * @param region_id     Id of the memory region the buffer belongs to
48  * @param base          Physical address of the start of the enqueued buffer
49  * @param lenght        Lenght of the enqueued buffer
50  * @param misc_flags    Any other argument that makes sense to the device queue
51  * @param buffer_id     Return pointer to buffer id of the enqueued buffer 
52  *                      buffer_id is assigned by the interface
53  *
54  * @returns error on failure or SYS_ERR_OK on success
55  *
56  */
57 errval_t devq_enqueue(struct devq *q,
58                       regionid_t region_id,
59                       lpaddr_t base,
60                       size_t length,
61                       uint64_t misc_flags,
62                       bufferid_t* buffer_id);
63
64 /**
65  * @brief dequeue a buffer from the device queue
66  *
67  * @param q             The device queue to call the operation on
68  * @param region_id     Return pointer to the id of the memory 
69  *                      region the buffer belongs to
70  * @param base          Return pointer to the physical address of 
71  *                      the of the buffer
72  * @param lenght        Return pointer to the lenght of the dequeue buffer
73  * @param buffer_id     Reutrn pointer to the buffer id of the dequeued buffer 
74  * @param misc_flags    Return value from other endpoint
75  *
76  * @returns error on failure or SYS_ERR_OK on success
77  *
78  */
79
80 errval_t devq_dequeue(struct devq *q,
81                       regionid_t* region_id,
82                       lpaddr_t* base,
83                       size_t* length,
84                       bufferid_t* buffer_id,
85                       uint64_t* misc_flags);
86
87 /*
88  * ===========================================================================
89  * Control Path
90  * ===========================================================================
91  */
92
93 /**
94  * @brief Add a memory region that can be used as buffers to 
95  *        the device queue
96  *
97  * @param q              The device queue to call the operation on
98  * @param cap            A Capability for some memory
99  * @param region_id      Return pointer to a region id that is assigned
100  *                       to the memory
101  *
102  * @returns error on failure or SYS_ERR_OK on success
103  *
104  */
105 errval_t devq_register(struct devq *q,
106                        struct capref cap,
107                        regionid_t* region_id);
108
109 /**
110  * @brief Remove a memory region 
111  *
112  * @param q              The device queue to call the operation on
113  * @param region_id      The region id to remove from the device 
114  *                       queues memory
115  * @param cap            The capability to the removed memory
116  *
117  * @returns error on failure or SYS_ERR_OK on success
118  *
119  */
120 errval_t devq_deregister(struct devq *q,
121                          regionid_t region_id,
122                          struct capref* cap);
123
124 /**
125  * @brief Send a notification about new buffers on the queue
126  *
127  * @param q      The device queue to call the operation on
128  *
129  * @returns error on failure or SYS_ERR_OK on success
130  *
131  */
132 errval_t devq_notify(struct devq *q);
133
134 /**
135  * @brief Enforce coherency between of the buffers in the queue
136  *        by either flushing the cache or invalidating it
137  *
138  * @param q      The device queue to call the operation on
139  *
140  * @returns error on failure or SYS_ERR_OK on success
141  *
142  */
143 errval_t devq_prepare(struct devq *q);
144
145 /**
146  * @brief Send a control message to the device queue
147  *
148  * @param q          The device queue to call the operation on
149  * @param request    The type of the control message*
150  * @param value      The value for the request
151  *
152  * @returns error on failure or SYS_ERR_OK on success
153  *
154  */
155 errval_t devq_control(struct devq *q,
156                       uint64_t request,
157                       uint64_t value);
158
159 #endif /* QUEUE_INTERFACE_H_ */