The C and C++ Include Header Files

/usr/include/xen/gntdev.h


$ cat -n /usr/include/xen/gntdev.h

     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 *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 *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__ */