1/*
2 * Copyright 2017, Data61
3 * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 * ABN 41 687 119 230.
5 *
6 * This software may be distributed and modified according to the terms of
7 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 * See "LICENSE_BSD2.txt" for details.
9 *
10 * @TAG(DATA61_BSD)
11 */
12
13#pragma once
14
15#include <autoconf.h>
16#include <sel4utils/gen_config.h>
17
18#if defined(CONFIG_IOMMU)
19
20#include <sel4/sel4.h>
21#include <vka/vka.h>
22#include <vspace/vspace.h>
23#include <platsupport/io.h>
24
25/**
26 * Creates an implementation of a dma manager that is designed to work only in the presence of an IOMMU
27 * Due to its reliance on malloc for actually allocating memory blocks, and because malloc'ed memory is
28 * assumed to be cached, it only supports cached allocations. The basic operation of this allocator is to
29 * malloc block of memory, find the frame capabilities, duplicate and map these into the appropriate
30 * iospaces. It is the responsibility of the user to ensure that whatever frames are used in mapping
31 * the malloc region are of a size that the hardware will accept being mapped into the IOMMU
32 * @param vka Allocation interface used for allocated cslots and any required paging structures for the iospace.
33 *            This interface will be copied
34 * @param vspace Virtual memory manager that needs to contain any mappings used to back malloc.
35 *            This interface will be copied
36 * @param dma_man Pointer to dma manager struct that will be filled out
37 * @param num_iospaces Number of iospaces we wish allocations from this dma manager to be valid in
38 * @param iospaces Pointer to list of cptrs representing the iospaces to map into
39 * @return 0 on success
40 */
41int sel4utils_make_iommu_dma_alloc(vka_t *vka, vspace_t *vspace, ps_dma_man_t *dma_man, unsigned int num_iospaces,
42                                   seL4_CPtr *iospaces);
43
44/**
45 * Variant of ps_dma_alloc that allows the caller to allocate memory in their address space for use
46 * as the dma buffer. This function takes a description of a region of (virtual) memory, and maps
47 * the frames that back the region into the dma manager's iospace such that the iovaddr of each frame
48 * corresponds to its vaddr.
49 *
50 * The intended use case for this function is in environments without a dynamic heap (that is, where
51 * malloc is not backed by a vspace). The dma_man argument must be a pointer to a dma manager that
52 * was created using sel4utils_make_iommu_dma_alloc. The vspace argument to sel4utils_make_iommu_dma_alloc
53 * must be able to resolve vaddrs within the specified buffer to frame caps with its get_cap function.
54 *
55 * This function takes a cookie rather than a dma manager to allow it to be used in the implementation
56 * of a ps_dma_alloc_fn_t.
57 *
58 * @param dma_cookie The cookie of a dma manager initialised with sel4utils_make_iommu_dma_alloc.
59 * @param vaddr A pointer to a region of memory to use as the dma buffer. The vspace given to
60 *              sel4utils_make_iommu_dma_alloc to initialise dma_man must be able to resolve
61 *              addresses in this buffer to frame caps with its get_cap function.
62 * @param size The size of the region of memory pointed to by vaddr.
63 * @return 0 on success
64 */
65int sel4utils_iommu_dma_alloc_iospace(void *dma_cookie, void *vaddr, size_t size);
66#endif /* CONFIG_IOMMU */
67