git.barrelfish.org Git - barrelfish/blob - 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_ */