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_MEM_MGR_H
11#define LIB_DMA_MEM_MGR_H
12
13/* forward declaration */
14struct dma_mem_mgr;
15
16/// typedef for custom address conversion
17typedef lpaddr_t (*dma_mem_convert_fn)(void *arg,
18                                       lpaddr_t addr,
19                                       size_t size);
20
21/// default memory ranges from 0 to 48 bits
22#define DMA_MEM_RANGE_MIN 0x0
23#define DMA_MEM_RANGE_MAX 0xFFFFFFFFFFFF
24
25/**
26 * \brief initializes the DMA memory region manager
27 *
28 * \param mem_mgr   returned pointer to the mem manager structure
29 * \param range_min minimum allowed memory address
30 * \param range_max maximum allowed memory address
31 *
32 * \returns SYS_ERR_OK on success
33 *          errval on failure
34 */
35errval_t dma_mem_mgr_init(struct dma_mem_mgr **mem_mgr,
36                          lpaddr_t range_min,
37                          lpaddr_t range_max);
38
39/**
40 * \brief sets the address conversion function to be used for translating the
41 *        addresses
42 *
43 * \param mem_mgr   DMA memory manager
44 * \param fn        convert function to be called
45 * \param arg       argument supplied for the convert function
46 */
47void dma_mem_mgr_set_convert_fn(struct dma_mem_mgr *mem_mgr,
48                                dma_mem_convert_fn fn,
49                                void *arg);
50
51/**
52 * \brief registers a memory region to be used for DMA transfers
53 *
54 * \param mem_mgr   DMA memory manager
55 * \param cap       frame capability of the memory region to register
56 *
57 * \returns SYS_ERR_OK on success
58 *          errval on failure
59 */
60errval_t dma_mem_register(struct dma_mem_mgr *mem_mgr,
61                          struct capref cap);
62
63/**
64 * \brief deregisters a memory region that it cannot longer be used for the
65 *        memory manager
66 *
67 * \param mem_mgr   DMA memory manager
68 * \param cap       frame capability of the memory region to register
69 *
70 * \returns SYS_ERR_OK on success
71 *          errval on failure
72 */
73errval_t dma_mem_deregister(struct dma_mem_mgr *mem_mgr,
74                            struct capref cap);
75
76/**
77 * \brief verifies if a addres-length pair lies completely within a
78 *        registered memory region and translates the address
79 *
80 * \param mem_mgr   DMA memory manager
81 * \param addr      address to be looked up
82 * \param bytes     length of the transfer in bytes
83 * \param dma_addr  translated base address (if change in address space)
84 *
85 * \returns SYS_ERR_OK on success
86 *          DMA_ERR_MEM_NOT_REGISTERED if the memory region is not registered
87 *          DMA_ERR_OUT_OF_RANGE if the memory region is out of range
88 */
89errval_t dma_mem_verify(struct dma_mem_mgr *mem_mgr,
90                        lpaddr_t addr,
91                        size_t bytes,
92                        lpaddr_t *dma_addr);
93
94#endif /* LIB_DMA_MEM_UTILS_H */
95