1/* 2 * Copyright (c) 2014 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, Universitaetsstrasse 6, CH-8092 Zurich. Attn: Systems Group. 8 */ 9 10#ifndef LIB_DMA_DEVICE_H 11#define LIB_DMA_DEVICE_H 12 13struct dma_device; 14struct dma_channel; 15 16/** 17 * Device State Enumeration 18 */ 19typedef enum dma_dev_st { 20 DMA_DEV_ST_INVALID, ///< this device structure is invalid 21 DMA_DEV_ST_UNINITIALIZED, ///< device has not been initialized yet 22 DMA_DEV_ST_CHAN_ENUM, ///< device is doing channel enumeration 23 DMA_DEV_ST_RUNNING, ///< device is operational 24 DMA_DEV_ST_SUSPENDED, ///< device is suspended state 25 DMA_DEV_ST_ERR ///< an error occurred 26} dma_dev_st_t; 27 28 29/* 30 * ---------------------------------------------------------------------------- 31 * device initialization / termination 32 * ---------------------------------------------------------------------------- 33 */ 34 35/** 36 * \brief terminates the device operation and frees up the allocated resources 37 * 38 * \param dev IOAT DMA device to shutdown 39 * 40 * \returns SYS_ERR_OK on success 41 * errval on error 42 */ 43errval_t dma_device_shutdown(struct dma_device *dev); 44 45/** 46 * \brief requests access to a IOAT DMA device from the IOAT device manager 47 * and initializes the device. 48 * 49 * \param dev returns a pointer to the device structure 50 * 51 * \returns SYS_ERR_OK on success 52 * errval on error 53 */ 54errval_t dma_device_acquire(struct dma_device **dev); 55 56/** 57 * \brief terminates the device operation and frees up the allocated resources 58 * and releases the device and returns it to the IOAT device manager. 59 * 60 * \param dev IOAT DMA device to be released 61 * 62 * \returns SYS_ERR_OK on success 63 * errval on error 64 */ 65errval_t dma_device_release(struct dma_device *dev); 66 67/** 68 * \brief polls the channels of the IOAT DMA device 69 * 70 * \param dev IOAT DMA device 71 * 72 * \returns SYS_ERR_OK on success 73 * DMA_ERR_DEVICE_IDLE if there is nothing completed on the channels 74 * errval on error 75 */ 76errval_t dma_device_poll_channels(struct dma_device *dev); 77 78/* 79 * ---------------------------------------------------------------------------- 80 * Getters / Setters 81 * ---------------------------------------------------------------------------- 82 */ 83 84/** 85 * \brief gets the ID of the DMA device 86 * 87 * \param dev DMA device 88 * 89 * \returns DMA device ID 90 */ 91dma_dev_id_t dma_device_get_id(struct dma_device *dev); 92 93/** 94 * \brief gets the DMA device type of the DMA device 95 * 96 * \param dev DMA device 97 * 98 * \returns DMA device type 99 */ 100dma_dev_id_t dma_device_get_type(struct dma_device *dev); 101 102/** 103 * \brief gets the state of the DMA device 104 * 105 * \param dev DMA device 106 * 107 * \returns DMA device state 108 */ 109dma_dev_st_t dma_device_get_state(struct dma_device *dev); 110 111 112/** 113 * \brief gets the virtual address of the mapped MMIO register space 114 * 115 * \param dev DMA device 116 * 117 * \returns MMIO register vbase 118 */ 119void *dma_device_get_mmio_vbase(struct dma_device *dev); 120 121 122/** 123 * \brief gets the number of channels this device has 124 * 125 * \param dev DMA device 126 * 127 * \returns DMA channel count 128 */ 129uint8_t dma_device_get_channel_count(struct dma_device *dev); 130 131/** 132 * \brief obtains the channel associated with the given index 133 * 134 * \param dev DMA device 135 * 136 * \returns DMA channel if index exists 137 * NULL if index exceeds channel count 138 */ 139struct dma_channel *dma_device_get_channe_by_idx(struct dma_device *dev, 140 uint8_t idx); 141 142/** 143 * \brief gets a DMA channel from this device in a round robin fashion 144 * 145 * \param dev DMA device 146 * 147 * \returns DMA channel 148 */ 149struct dma_channel *dma_device_get_channel(struct dma_device *dev); 150 151 152/* 153 * ---------------------------------------------------------------------------- 154 * Interrupt management 155 * ---------------------------------------------------------------------------- 156 */ 157 158/** 159 * \brief enables the interrupts for the device 160 * 161 * \param dev IOAT DMA device 162 * \param type interrupt type 163 * \param handler interrupt handler function 164 * \param arg argument supplied to the handler function 165 */ 166errval_t dma_device_intr_enable(struct dma_device *dev, 167 dma_irq_t type, 168 dma_irq_fn_t handler, 169 void *arg); 170 171/** 172 * \brief disables the interrupts for the device 173 * 174 * \param dev IOAT DMA device 175 */ 176void dma_device_intr_disable(struct dma_device *dev); 177 178/** 179 * \brief sets the interrupt delay for the device 180 * 181 * \param dev IOAT DMA device 182 * \param usec interrupt delay in microseconds 183 */ 184void dma_device_set_intr_delay(struct dma_device *dev, 185 uint16_t usec); 186 187 188#endif /* LIB_DMA_CHANNEL_H */ 189