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