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
16#define DEVQ_FLAG_LAST (1UL << 30)
17
18typedef uint32_t regionid_t;
19typedef uint32_t bufferid_t;
20typedef uint64_t genoffset_t;
21
22
23struct devq;
24struct region_pool;
25
26// For convinience reason buffer descritpion in one struct
27struct devq_buf{
28    genoffset_t offset; // 8
29    genoffset_t length; // 16
30    genoffset_t valid_data; // 24
31    genoffset_t valid_length; // 32
32    uint64_t flags; // 40
33    regionid_t rid; // 44
34};
35
36/*
37 * ===========================================================================
38 * Datapath functions
39 * ===========================================================================
40 */
41/*
42 *
43 * @brief enqueue a buffer into the device queue
44 *
45 * @param q             The device queue to call the operation on
46 * @param region_id     Id of the memory region the buffer belongs to
47 * @param offset        Offset into the region i.e. where the buffer starts
48 *                      that is enqueued
49 * @param lenght        Lenght of the enqueued buffer
50 * @param valid_data    Offset into the buffer where the valid data of this buffer
51 *                      starts
52 * @param valid_length  Length of the valid data of this buffer
53 * @param misc_flags    Any other argument that makes sense to the device queue
54 *
55 * @returns error on failure or SYS_ERR_OK on success
56 *
57 */
58errval_t devq_enqueue(struct devq *q,
59                      regionid_t region_id,
60                      genoffset_t offset,
61                      genoffset_t lenght,
62                      genoffset_t valid_data,
63                      genoffset_t valid_lenght,
64                      uint64_t misc_flags);
65
66/**
67 * @brief dequeue a buffer from the device queue
68 *
69 * @param q             The device queue to call the operation on
70 * @param region_id     Return pointer to the id of the memory
71 *                      region the buffer belongs to
72 * @param region_offset Return pointer to the offset into the region where
73 *                      this buffer starts.
74 * @param lenght        Return pointer to the lenght of the dequeue buffer
75 * @param valid_data    Return pointer to an offset into the buffer where the
76 *                      valid data of this buffer starts
77 * @param valid_length  Return pointer to the length of the valid data of
78 *                      this buffer
79 * @param misc_flags    Return value from other endpoint
80 *
81 * @returns error on failure or SYS_ERR_OK on success
82 *
83 */
84errval_t devq_dequeue(struct devq *q,
85                      regionid_t* region_id,
86                      genoffset_t* offset,
87                      genoffset_t* langht,
88                      genoffset_t* valid_data,
89                      genoffset_t* valid_length,
90                      uint64_t* misc_flags);
91
92/*
93 * ===========================================================================
94 * Control Path
95 * ===========================================================================
96 */
97
98/**
99 * @brief Add a memory region that can be used as buffers to
100 *        the device queue
101 *
102 * @param q              The device queue to call the operation on
103 * @param cap            A Capability for some memory
104 * @param region_id      Return pointer to a region id that is assigned
105 *                       to the memory
106 *
107 * @returns error on failure or SYS_ERR_OK on success
108 *
109 */
110errval_t devq_register(struct devq *q,
111                       struct capref cap,
112                       regionid_t* region_id);
113
114/**
115 * @brief Remove a memory region
116 *
117 * @param q              The device queue to call the operation on
118 * @param region_id      The region id to remove from the device
119 *                       queues memory
120 * @param cap            The capability to the removed memory
121 *
122 * @returns error on failure or SYS_ERR_OK on success
123 *
124 */
125errval_t devq_deregister(struct devq *q,
126                         regionid_t region_id,
127                         struct capref* cap);
128
129/**
130 * @brief Send a notification about new buffers on the queue
131 *
132 * @param q      The device queue to call the operation on
133 *
134 * @returns error on failure or SYS_ERR_OK on success
135 *
136 */
137errval_t devq_notify(struct devq *q);
138
139/**
140 * @brief Enforce coherency between of the buffers in the queue
141 *        by either flushing the cache or invalidating it
142 *
143 * @param q      The device queue to call the operation on
144 *
145 * @returns error on failure or SYS_ERR_OK on success
146 *
147 */
148errval_t devq_prepare(struct devq *q);
149
150/**
151 * @brief Send a control message to the device queue
152 *
153 * @param q          The device queue to call the operation on
154 * @param request    The type of the control message*
155 * @param value      The value for the request
156 *
157 * @returns error on failure or SYS_ERR_OK on success
158 *
159 */
160errval_t devq_control(struct devq *q,
161                      uint64_t request,
162                      uint64_t value,
163                      uint64_t *result);
164
165
166 /**
167  * @brief destroys the device queue
168  *
169  * @param q           The queue state to free (and the device queue to be
170                       shut down)
171  *
172  * @returns error on failure or SYS_ERR_OK on success
173  */
174errval_t devq_destroy(struct devq *q);
175
176void devq_set_state(struct devq *q, void *state);
177void * devq_get_state(struct devq *q);
178
179#endif /* QUEUE_INTERFACE_H_ */
180