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 * 
  9 * This program is free software; you can redistribute it and/or
 10 * modify it under the terms of the GNU General Public License version 2
 11 * as published by the Free Software Foundation; or, when distributed
 12 * separately from the Linux kernel or incorporated into other
 13 * software packages, subject to the following license:
 14 * 
 15 * Permission is hereby granted, free of charge, to any person obtaining a copy
 16 * of this source file (the "Software"), to deal in the Software without
 17 * restriction, including without limitation the rights to use, copy, modify,
 18 * merge, publish, distribute, sublicense, and/or sell copies of the Software,
 19 * and to permit persons to whom the Software is furnished to do so, subject to
 20 * the following conditions:
 21 * 
 22 * The above copyright notice and this permission notice shall be included in
 23 * all copies or substantial portions of the Software.
 24 * 
 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 26 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 27 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 28 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 29 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 30 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 31 * IN THE SOFTWARE.
 32 */
 33
 34#ifndef __LINUX_PUBLIC_GNTDEV_H__
 35#define __LINUX_PUBLIC_GNTDEV_H__
 36
 37#include <linux/types.h>
 38
 39struct ioctl_gntdev_grant_ref {
 40	/* The domain ID of the grant to be mapped. */
 41	__u32 domid;
 42	/* The grant reference of the grant to be mapped. */
 43	__u32 ref;
 44};
 45
 46/*
 47 * Inserts the grant references into the mapping table of an instance
 48 * of gntdev. N.B. This does not perform the mapping, which is deferred
 49 * until mmap() is called with @index as the offset.
 50 */
 51#define IOCTL_GNTDEV_MAP_GRANT_REF \
 52_IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))
 53struct ioctl_gntdev_map_grant_ref {
 54	/* IN parameters */
 55	/* The number of grants to be mapped. */
 56	__u32 count;
 57	__u32 pad;
 58	/* OUT parameters */
 59	/* The offset to be used on a subsequent call to mmap(). */
 60	__u64 index;
 61	/* Variable IN parameter. */
 62	/* Array of grant references, of size @count. */
 63	struct ioctl_gntdev_grant_ref refs[1];
 64};
 65
 66/*
 67 * Removes the grant references from the mapping table of an instance of
 68 * of gntdev. N.B. munmap() must be called on the relevant virtual address(es)
 69 * before this ioctl is called, or an error will result.
 70 */
 71#define IOCTL_GNTDEV_UNMAP_GRANT_REF \
 72_IOC(_IOC_NONE, 'G', 1, sizeof(struct ioctl_gntdev_unmap_grant_ref))
 73struct ioctl_gntdev_unmap_grant_ref {
 74	/* IN parameters */
 75	/* The offset was returned by the corresponding map operation. */
 76	__u64 index;
 77	/* The number of pages to be unmapped. */
 78	__u32 count;
 79	__u32 pad;
 80};
 81
 82/*
 83 * Returns the offset in the driver's address space that corresponds
 84 * to @vaddr. This can be used to perform a munmap(), followed by an
 85 * UNMAP_GRANT_REF ioctl, where no state about the offset is retained by
 86 * the caller. The number of pages that were allocated at the same time as
 87 * @vaddr is returned in @count.
 88 *
 89 * N.B. Where more than one page has been mapped into a contiguous range, the
 90 *      supplied @vaddr must correspond to the start of the range; otherwise
 91 *      an error will result. It is only possible to munmap() the entire
 92 *      contiguously-allocated range at once, and not any subrange thereof.
 93 */
 94#define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \
 95_IOC(_IOC_NONE, 'G', 2, sizeof(struct ioctl_gntdev_get_offset_for_vaddr))
 96struct ioctl_gntdev_get_offset_for_vaddr {
 97	/* IN parameters */
 98	/* The virtual address of the first mapped page in a range. */
 99	__u64 vaddr;
100	/* OUT parameters */
101	/* The offset that was used in the initial mmap() operation. */
102	__u64 offset;
103	/* The number of pages mapped in the VM area that begins at @vaddr. */
104	__u32 count;
105	__u32 pad;
106};
107
108/*
109 * Sets the maximum number of grants that may mapped at once by this gntdev
110 * instance.
111 *
112 * N.B. This must be called before any other ioctl is performed on the device.
113 */
114#define IOCTL_GNTDEV_SET_MAX_GRANTS \
115_IOC(_IOC_NONE, 'G', 3, sizeof(struct ioctl_gntdev_set_max_grants))
116struct ioctl_gntdev_set_max_grants {
117	/* IN parameter */
118	/* The maximum number of grants that may be mapped at once. */
119	__u32 count;
120};
121
122/*
123 * Sets up an unmap notification within the page, so that the other side can do
124 * cleanup if this side crashes. Required to implement cross-domain robust
125 * mutexes or close notification on communication channels.
126 *
127 * Each mapped page only supports one notification; multiple calls referring to
128 * the same page overwrite the previous notification. You must clear the
129 * notification prior to the IOCTL_GNTALLOC_DEALLOC_GREF if you do not want it
130 * to occur.
131 */
132#define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \
133_IOC(_IOC_NONE, 'G', 7, sizeof(struct ioctl_gntdev_unmap_notify))
134struct ioctl_gntdev_unmap_notify {
135	/* IN parameters */
136	/* Offset in the file descriptor for a byte within the page (same as
137	 * used in mmap). If using UNMAP_NOTIFY_CLEAR_BYTE, this is the byte to
138	 * be cleared. Otherwise, it can be any byte in the page whose
139	 * notification we are adjusting.
140	 */
141	__u64 index;
142	/* Action(s) to take on unmap */
143	__u32 action;
144	/* Event channel to notify */
145	__u32 event_channel_port;
146};
147
148struct gntdev_grant_copy_segment {
149	union {
150		void __user *virt;
151		struct {
152			grant_ref_t ref;
153			__u16 offset;
154			domid_t domid;
155		} foreign;
156	} source, dest;
157	__u16 len;
158
159	__u16 flags;  /* GNTCOPY_* */
160	__s16 status; /* GNTST_* */
161};
162
163/*
164 * Copy between grant references and local buffers.
165 *
166 * The copy is split into @count @segments, each of which can copy
167 * to/from one grant reference.
168 *
169 * Each segment is similar to struct gnttab_copy in the hypervisor ABI
170 * except the local buffer is specified using a virtual address
171 * (instead of a GFN and offset).
172 *
173 * The local buffer may cross a Xen page boundary -- the driver will
174 * split segments into multiple ops if required.
175 *
176 * Returns 0 if all segments have been processed and @status in each
177 * segment is valid.  Note that one or more segments may have failed
178 * (status != GNTST_okay).
179 *
180 * If the driver had to split a segment into two or more ops, @status
181 * includes the status of the first failed op for that segment (or
182 * GNTST_okay if all ops were successful).
183 *
184 * If -1 is returned, the status of all segments is undefined.
185 *
186 * EINVAL: A segment has local buffers for both source and
187 *         destination.
188 * EINVAL: A segment crosses the boundary of a foreign page.
189 * EFAULT: A segment's local buffer is not accessible.
190 */
191#define IOCTL_GNTDEV_GRANT_COPY \
192	_IOC(_IOC_NONE, 'G', 8, sizeof(struct ioctl_gntdev_grant_copy))
193struct ioctl_gntdev_grant_copy {
194	unsigned int count;
195	struct gntdev_grant_copy_segment __user *segments;
196};
197
198/* Clear (set to zero) the byte specified by index */
199#define UNMAP_NOTIFY_CLEAR_BYTE 0x1
200/* Send an interrupt on the indicated event channel */
201#define UNMAP_NOTIFY_SEND_EVENT 0x2
202
203#endif /* __LINUX_PUBLIC_GNTDEV_H__ */