1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * DMABUF Heaps Allocation Infrastructure
4  *
5  * Copyright (C) 2011 Google, Inc.
6  * Copyright (C) 2019 Linaro Ltd.
7  */
8 
9 #ifndef DMA_HEAPS_H
10 #define DMA_HEAPS_H
11 
12 #include <linux/cdev.h>
13 #include <linux/types.h>
14 
15 struct dma_heap;
16 
17 /**
18  * struct dma_heap_ops - ops to operate on a given heap
19  * @allocate:        allocate dmabuf and return struct dma_buf ptr
20  * @get_pool_size:    if heap maintains memory pools, get pool size in bytes
21  *
22  * allocate returns dmabuf on success, ERR_PTR(-errno) on error.
23  */
24 struct dma_heap_ops {
25     struct dma_buf *(*allocate)(struct dma_heap *heap, unsigned long len, unsigned long fd_flags,
26                                 unsigned long heap_flags);
27     long (*get_pool_size)(struct dma_heap *heap);
28 };
29 
30 /**
31  * struct dma_heap_export_info - information needed to export a new dmabuf heap
32  * @name:    used for debugging/device-node name
33  * @ops:    ops struct for this heap
34  * @priv:    heap exporter private data
35  *
36  * Information needed to export a new dmabuf heap.
37  */
38 struct dma_heap_export_info {
39     const char *name;
40     const struct dma_heap_ops *ops;
41     void *priv;
42 };
43 
44 /**
45  * dma_heap_get_drvdata() - get per-heap driver data
46  * @heap: DMA-Heap to retrieve private data for
47  *
48  * Returns:
49  * The per-heap data for the heap.
50  */
51 void *dma_heap_get_drvdata(struct dma_heap *heap);
52 
53 /**
54  * dma_heap_get_dev() - get device struct for the heap
55  * @heap: DMA-Heap to retrieve device struct from
56  *
57  * Returns:
58  * The device struct for the heap.
59  */
60 struct device *dma_heap_get_dev(struct dma_heap *heap);
61 
62 /**
63  * dma_heap_get_name() - get heap name
64  * @heap: DMA-Heap to retrieve private data for
65  *
66  * Returns:
67  * The char* for the heap name.
68  */
69 const char *dma_heap_get_name(struct dma_heap *heap);
70 
71 /**
72  * dma_heap_add - adds a heap to dmabuf heaps
73  * @exp_info:        information needed to register this heap
74  */
75 struct dma_heap *dma_heap_add(const struct dma_heap_export_info *exp_info);
76 
77 /**
78  * dma_heap_put - drops a reference to a dmabuf heaps, potentially freeing it
79  * @heap:        heap pointer
80  */
81 void dma_heap_put(struct dma_heap *heap);
82 
83 /**
84  * dma_heap_find - Returns the registered dma_heap with the specified name
85  * @name: Name of the heap to find
86  *
87  * NOTE: dma_heaps returned from this function MUST be released
88  * using dma_heap_put() when the user is done.
89  */
90 struct dma_heap *dma_heap_find(const char *name);
91 
92 /**
93  * dma_heap_buffer_alloc - Allocate dma-buf from a dma_heap
94  * @heap:    dma_heap to allocate from
95  * @len:    size to allocate
96  * @fd_flags:    flags to set on returned dma-buf fd
97  * @heap_flags:    flags to pass to the dma heap
98  *
99  * This is for internal dma-buf allocations only.
100  */
101 struct dma_buf *dma_heap_buffer_alloc(struct dma_heap *heap, size_t len, unsigned int fd_flags,
102                                       unsigned int heap_flags);
103 
104 /** dma_heap_buffer_free - Free dma_buf allocated by dma_heap_buffer_alloc
105  * @dma_buf:    dma_buf to free
106  *
107  * This is really only a simple wrapper to dma_buf_put()
108  */
109 void dma_heap_buffer_free(struct dma_buf *);
110 
111 /**
112  * dma_heap_bufferfd_alloc - Allocate dma-buf fd from a dma_heap
113  * @heap:    dma_heap to allocate from
114  * @len:    size to allocate
115  * @fd_flags:    flags to set on returned dma-buf fd
116  * @heap_flags:    flags to pass to the dma heap
117  */
118 int dma_heap_bufferfd_alloc(struct dma_heap *heap, size_t len, unsigned int fd_flags, unsigned int heap_flags);
119 #endif /* _DMA_HEAPS_H */
120