1 | /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR MIT) */ |
2 | /****************************************************************************** |
3 | * gntdev.h |
4 | * |
5 | * Interface to /dev/xen/gntdev. |
6 | * |
7 | * Copyright (c) 2007, D G Murray |
8 | * Copyright (c) 2018, Oleksandr Andrushchenko, EPAM Systems Inc. |
9 | * |
10 | * This program is free software; you can redistribute it and/or |
11 | * modify it under the terms of the GNU General Public License version 2 |
12 | * as published by the Free Software Foundation; or, when distributed |
13 | * separately from the Linux kernel or incorporated into other |
14 | * software packages, subject to the following license: |
15 | * |
16 | * Permission is hereby granted, free of charge, to any person obtaining a copy |
17 | * of this source file (the "Software"), to deal in the Software without |
18 | * restriction, including without limitation the rights to use, copy, modify, |
19 | * merge, publish, distribute, sublicense, and/or sell copies of the Software, |
20 | * and to permit persons to whom the Software is furnished to do so, subject to |
21 | * the following conditions: |
22 | * |
23 | * The above copyright notice and this permission notice shall be included in |
24 | * all copies or substantial portions of the Software. |
25 | * |
26 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
27 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
28 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
29 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
30 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
31 | * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
32 | * IN THE SOFTWARE. |
33 | */ |
34 | |
35 | #ifndef __LINUX_PUBLIC_GNTDEV_H__ |
36 | #define __LINUX_PUBLIC_GNTDEV_H__ |
37 | |
38 | #include <linux/types.h> |
39 | |
40 | struct ioctl_gntdev_grant_ref { |
41 | /* The domain ID of the grant to be mapped. */ |
42 | __u32 domid; |
43 | /* The grant reference of the grant to be mapped. */ |
44 | __u32 ref; |
45 | }; |
46 | |
47 | /* |
48 | * Inserts the grant references into the mapping table of an instance |
49 | * of gntdev. N.B. This does not perform the mapping, which is deferred |
50 | * until mmap() is called with @index as the offset. @index should be |
51 | * considered opaque to userspace, with one exception: if no grant |
52 | * references have ever been inserted into the mapping table of this |
53 | * instance, @index will be set to 0. This is necessary to use gntdev |
54 | * with userspace APIs that expect a file descriptor that can be |
55 | * mmap()'d at offset 0, such as Wayland. If @count is set to 0, this |
56 | * ioctl will fail. |
57 | */ |
58 | #define IOCTL_GNTDEV_MAP_GRANT_REF \ |
59 | _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref)) |
60 | struct ioctl_gntdev_map_grant_ref { |
61 | /* IN parameters */ |
62 | /* The number of grants to be mapped. */ |
63 | __u32 count; |
64 | __u32 pad; |
65 | /* OUT parameters */ |
66 | /* The offset to be used on a subsequent call to mmap(). */ |
67 | __u64 index; |
68 | /* Variable IN parameter. */ |
69 | /* Array of grant references, of size @count. */ |
70 | struct ioctl_gntdev_grant_ref refs[1]; |
71 | }; |
72 | |
73 | /* |
74 | * Removes the grant references from the mapping table of an instance of |
75 | * gntdev. N.B. munmap() must be called on the relevant virtual address(es) |
76 | * before this ioctl is called, or an error will result. |
77 | */ |
78 | #define IOCTL_GNTDEV_UNMAP_GRANT_REF \ |
79 | _IOC(_IOC_NONE, 'G', 1, sizeof(struct ioctl_gntdev_unmap_grant_ref)) |
80 | struct ioctl_gntdev_unmap_grant_ref { |
81 | /* IN parameters */ |
82 | /* The offset was returned by the corresponding map operation. */ |
83 | __u64 index; |
84 | /* The number of pages to be unmapped. */ |
85 | __u32 count; |
86 | __u32 pad; |
87 | }; |
88 | |
89 | /* |
90 | * Returns the offset in the driver's address space that corresponds |
91 | * to @vaddr. This can be used to perform a munmap(), followed by an |
92 | * UNMAP_GRANT_REF ioctl, where no state about the offset is retained by |
93 | * the caller. The number of pages that were allocated at the same time as |
94 | * @vaddr is returned in @count. |
95 | * |
96 | * N.B. Where more than one page has been mapped into a contiguous range, the |
97 | * supplied @vaddr must correspond to the start of the range; otherwise |
98 | * an error will result. It is only possible to munmap() the entire |
99 | * contiguously-allocated range at once, and not any subrange thereof. |
100 | */ |
101 | #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \ |
102 | _IOC(_IOC_NONE, 'G', 2, sizeof(struct ioctl_gntdev_get_offset_for_vaddr)) |
103 | struct ioctl_gntdev_get_offset_for_vaddr { |
104 | /* IN parameters */ |
105 | /* The virtual address of the first mapped page in a range. */ |
106 | __u64 vaddr; |
107 | /* OUT parameters */ |
108 | /* The offset that was used in the initial mmap() operation. */ |
109 | __u64 offset; |
110 | /* The number of pages mapped in the VM area that begins at @vaddr. */ |
111 | __u32 count; |
112 | __u32 pad; |
113 | }; |
114 | |
115 | /* |
116 | * Sets the maximum number of grants that may mapped at once by this gntdev |
117 | * instance. |
118 | * |
119 | * N.B. This must be called before any other ioctl is performed on the device. |
120 | */ |
121 | #define IOCTL_GNTDEV_SET_MAX_GRANTS \ |
122 | _IOC(_IOC_NONE, 'G', 3, sizeof(struct ioctl_gntdev_set_max_grants)) |
123 | struct ioctl_gntdev_set_max_grants { |
124 | /* IN parameter */ |
125 | /* The maximum number of grants that may be mapped at once. */ |
126 | __u32 count; |
127 | }; |
128 | |
129 | /* |
130 | * Sets up an unmap notification within the page, so that the other side can do |
131 | * cleanup if this side crashes. Required to implement cross-domain robust |
132 | * mutexes or close notification on communication channels. |
133 | * |
134 | * Each mapped page only supports one notification; multiple calls referring to |
135 | * the same page overwrite the previous notification. You must clear the |
136 | * notification prior to the IOCTL_GNTALLOC_DEALLOC_GREF if you do not want it |
137 | * to occur. |
138 | */ |
139 | #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \ |
140 | _IOC(_IOC_NONE, 'G', 7, sizeof(struct ioctl_gntdev_unmap_notify)) |
141 | struct ioctl_gntdev_unmap_notify { |
142 | /* IN parameters */ |
143 | /* Offset in the file descriptor for a byte within the page (same as |
144 | * used in mmap). If using UNMAP_NOTIFY_CLEAR_BYTE, this is the byte to |
145 | * be cleared. Otherwise, it can be any byte in the page whose |
146 | * notification we are adjusting. |
147 | */ |
148 | __u64 index; |
149 | /* Action(s) to take on unmap */ |
150 | __u32 action; |
151 | /* Event channel to notify */ |
152 | __u32 event_channel_port; |
153 | }; |
154 | |
155 | struct gntdev_grant_copy_segment { |
156 | union { |
157 | void __user *virt; |
158 | struct { |
159 | grant_ref_t ref; |
160 | __u16 offset; |
161 | domid_t domid; |
162 | } foreign; |
163 | } source, dest; |
164 | __u16 len; |
165 | |
166 | __u16 flags; /* GNTCOPY_* */ |
167 | __s16 status; /* GNTST_* */ |
168 | }; |
169 | |
170 | /* |
171 | * Copy between grant references and local buffers. |
172 | * |
173 | * The copy is split into @count @segments, each of which can copy |
174 | * to/from one grant reference. |
175 | * |
176 | * Each segment is similar to struct gnttab_copy in the hypervisor ABI |
177 | * except the local buffer is specified using a virtual address |
178 | * (instead of a GFN and offset). |
179 | * |
180 | * The local buffer may cross a Xen page boundary -- the driver will |
181 | * split segments into multiple ops if required. |
182 | * |
183 | * Returns 0 if all segments have been processed and @status in each |
184 | * segment is valid. Note that one or more segments may have failed |
185 | * (status != GNTST_okay). |
186 | * |
187 | * If the driver had to split a segment into two or more ops, @status |
188 | * includes the status of the first failed op for that segment (or |
189 | * GNTST_okay if all ops were successful). |
190 | * |
191 | * If -1 is returned, the status of all segments is undefined. |
192 | * |
193 | * EINVAL: A segment has local buffers for both source and |
194 | * destination. |
195 | * EINVAL: A segment crosses the boundary of a foreign page. |
196 | * EFAULT: A segment's local buffer is not accessible. |
197 | */ |
198 | #define IOCTL_GNTDEV_GRANT_COPY \ |
199 | _IOC(_IOC_NONE, 'G', 8, sizeof(struct ioctl_gntdev_grant_copy)) |
200 | struct ioctl_gntdev_grant_copy { |
201 | unsigned int count; |
202 | struct gntdev_grant_copy_segment __user *segments; |
203 | }; |
204 | |
205 | /* Clear (set to zero) the byte specified by index */ |
206 | #define UNMAP_NOTIFY_CLEAR_BYTE 0x1 |
207 | /* Send an interrupt on the indicated event channel */ |
208 | #define UNMAP_NOTIFY_SEND_EVENT 0x2 |
209 | |
210 | /* |
211 | * Flags to be used while requesting memory mapping's backing storage |
212 | * to be allocated with DMA API. |
213 | */ |
214 | |
215 | /* |
216 | * The buffer is backed with memory allocated with dma_alloc_wc. |
217 | */ |
218 | #define GNTDEV_DMA_FLAG_WC (1 << 0) |
219 | |
220 | /* |
221 | * The buffer is backed with memory allocated with dma_alloc_coherent. |
222 | */ |
223 | #define GNTDEV_DMA_FLAG_COHERENT (1 << 1) |
224 | |
225 | /* |
226 | * Create a dma-buf [1] from grant references @refs of count @count provided |
227 | * by the foreign domain @domid with flags @flags. |
228 | * |
229 | * By default dma-buf is backed by system memory pages, but by providing |
230 | * one of the GNTDEV_DMA_FLAG_XXX flags it can also be created as |
231 | * a DMA write-combine or coherent buffer, e.g. allocated with dma_alloc_wc/ |
232 | * dma_alloc_coherent. |
233 | * |
234 | * Returns 0 if dma-buf was successfully created and the corresponding |
235 | * dma-buf's file descriptor is returned in @fd. |
236 | * |
237 | * [1] Documentation/driver-api/dma-buf.rst |
238 | */ |
239 | |
240 | #define IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS \ |
241 | _IOC(_IOC_NONE, 'G', 9, \ |
242 | sizeof(struct ioctl_gntdev_dmabuf_exp_from_refs)) |
243 | struct ioctl_gntdev_dmabuf_exp_from_refs { |
244 | /* IN parameters. */ |
245 | /* Specific options for this dma-buf: see GNTDEV_DMA_FLAG_XXX. */ |
246 | __u32 flags; |
247 | /* Number of grant references in @refs array. */ |
248 | __u32 count; |
249 | /* OUT parameters. */ |
250 | /* File descriptor of the dma-buf. */ |
251 | __u32 fd; |
252 | /* The domain ID of the grant references to be mapped. */ |
253 | __u32 domid; |
254 | /* Variable IN parameter. */ |
255 | /* Array of grant references of size @count. */ |
256 | __u32 refs[1]; |
257 | }; |
258 | |
259 | /* |
260 | * This will block until the dma-buf with the file descriptor @fd is |
261 | * released. This is only valid for buffers created with |
262 | * IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS. |
263 | * |
264 | * If within @wait_to_ms milliseconds the buffer is not released |
265 | * then -ETIMEDOUT error is returned. |
266 | * If the buffer with the file descriptor @fd does not exist or has already |
267 | * been released, then -ENOENT is returned. For valid file descriptors |
268 | * this must not be treated as error. |
269 | */ |
270 | #define IOCTL_GNTDEV_DMABUF_EXP_WAIT_RELEASED \ |
271 | _IOC(_IOC_NONE, 'G', 10, \ |
272 | sizeof(struct ioctl_gntdev_dmabuf_exp_wait_released)) |
273 | struct ioctl_gntdev_dmabuf_exp_wait_released { |
274 | /* IN parameters */ |
275 | __u32 fd; |
276 | __u32 wait_to_ms; |
277 | }; |
278 | |
279 | /* |
280 | * Import a dma-buf with file descriptor @fd and export granted references |
281 | * to the pages of that dma-buf into array @refs of size @count. |
282 | */ |
283 | #define IOCTL_GNTDEV_DMABUF_IMP_TO_REFS \ |
284 | _IOC(_IOC_NONE, 'G', 11, \ |
285 | sizeof(struct ioctl_gntdev_dmabuf_imp_to_refs)) |
286 | struct ioctl_gntdev_dmabuf_imp_to_refs { |
287 | /* IN parameters. */ |
288 | /* File descriptor of the dma-buf. */ |
289 | __u32 fd; |
290 | /* Number of grant references in @refs array. */ |
291 | __u32 count; |
292 | /* The domain ID for which references to be granted. */ |
293 | __u32 domid; |
294 | /* Reserved - must be zero. */ |
295 | __u32 reserved; |
296 | /* OUT parameters. */ |
297 | /* Array of grant references of size @count. */ |
298 | __u32 refs[1]; |
299 | }; |
300 | |
301 | /* |
302 | * This will close all references to the imported buffer with file descriptor |
303 | * @fd, so it can be released by the owner. This is only valid for buffers |
304 | * created with IOCTL_GNTDEV_DMABUF_IMP_TO_REFS. |
305 | */ |
306 | #define IOCTL_GNTDEV_DMABUF_IMP_RELEASE \ |
307 | _IOC(_IOC_NONE, 'G', 12, \ |
308 | sizeof(struct ioctl_gntdev_dmabuf_imp_release)) |
309 | struct ioctl_gntdev_dmabuf_imp_release { |
310 | /* IN parameters */ |
311 | __u32 fd; |
312 | __u32 reserved; |
313 | }; |
314 | |
315 | #endif /* __LINUX_PUBLIC_GNTDEV_H__ */ |
316 | |