FreeBSD xen subsystem code
gntdev.h
1
/*-
2
* Copyright (c) 2016 Akshay Jaggi <jaggi@FreeBSD.org>
3
* All rights reserved.
4
*
5
* Redistribution and use in source and binary forms, with or without
6
* modification, are permitted provided that the following conditions
7
* are met:
8
* 1. Redistributions of source code must retain the above copyright
9
* notice, this list of conditions and the following disclaimer.
10
* 2. Redistributions in binary form must reproduce the above copyright
11
* notice, this list of conditions and the following disclaimer in the
12
* documentation and/or other materials provided with the distribution.
13
*
14
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
* SUCH DAMAGE.
25
*
26
* gntdev.h
27
*
28
* Interface to /dev/xen/gntdev.
29
*
30
* This device provides the user with two kinds of functionalities:
31
* 1. Grant Allocation
32
* Allocate a page of our own memory, and share it with a foreign domain.
33
* 2. Grant Mapping
34
* Map a grant allocated by a foreign domain, into our own memory.
35
*
36
*
37
* Grant Allocation
38
*
39
* Steps to allocate a grant:
40
* 1. Do an `IOCTL_GNTDEV_ALLOC_GREF ioctl`, with
41
* - `domid`, as the domain-id of the foreign domain
42
* - `flags`, ORed with GNTDEV_ALLOC_FLAG_WRITABLE if you want the foreign
43
* domain to have write access to the shared memory
44
* - `count`, with the number of pages to share with the foreign domain
45
*
46
* Ensure that the structure you allocate has enough memory to store
47
* all the allocated grant-refs, i.e., you need to allocate
48
* (sizeof(struct ioctl_gntdev_alloc_gref) + (count - 1)*sizeof(uint32_t))
49
* bytes of memory.
50
*
51
* 2. Mmap the address given in `index` after a successful ioctl.
52
* This will give you access to the granted pages.
53
*
54
* Note:
55
* 1. The grant is not removed until all three of the following conditions
56
* are met
57
* - The region is not mmaped. That is, munmap() has been called if
58
* the region was mmapped previously.
59
* - IOCTL_GNTDEV_DEALLOC_GREF ioctl has been performed. After you
60
* perform this ioctl, you can no longer mmap or set notify on
61
* the grant.
62
* - The foreign domain has stopped using the grant.
63
* 2. Granted pages can only belong to one mmap region.
64
* 3. Every page of granted memory is a unit in itself. What this means
65
* is that you can set a unmap notification for each of the granted
66
* pages, individually; you can mmap and dealloc-ioctl a contiguous
67
* range of allocated grants (even if alloc-ioctls were performed
68
* individually), etc.
69
*
70
*
71
* Grant Mapping
72
*
73
* Steps to map a grant:
74
* 1. Do a `IOCTL_GNTDEV_MAP_GRANT_REF` ioctl, with
75
* - `count`, as the number of foreign grants to map
76
* - `refs[i].domid`, as the domain id of the foreign domain
77
* - `refs[i].ref`, as the grant-ref for the grant to be mapped
78
*
79
* 2. Mmap the address given in `index` after a successful ioctl.
80
* This will give you access to the mapped pages.
81
*
82
* Note:
83
* 1. The map hypercall is not made till the region is mmapped.
84
* 2. The unit is defined by the map ioctl. This means that only one
85
* unmap notification can be set on a group of pages that were
86
* mapped together in one ioctl, and also no single mmaping of contiguous
87
* grant-maps is possible.
88
* 3. You can mmap the same grant-map region multiple times.
89
* 4. The grant is not unmapped until both of the following conditions are met
90
* - The region is not mmaped. That is, munmap() has been called for
91
* as many times as the grant was mmapped.
92
* - IOCTL_GNTDEV_UNMAP_GRANT_REF ioctl has been called.
93
* 5. IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR ioctl gives index and count of
94
* a grant-map from the virtual address of the location where the grant
95
* is mmapped.
96
*
97
*
98
* IOCTL_GNTDEV_SET_UNMAP_NOTIFY
99
* This ioctl allows us to set notifications to be made when the grant is
100
* either unmapped (in case of a mapped grant), or when it is ready to be
101
* deallocated by us, ie, the grant is no more mmapped, and the dealloc
102
* ioctl has been called (in case of an allocated grant). OR `action` with
103
* the required notification masks, and fill in the appropriate fields.
104
* - UNMAP_NOTIFY_CLEAR_BYTE clears the byte at `index`, where index is
105
* the address of the byte in file address space.
106
* - UNMAP_NOTIFY_SEND_EVENT sends an event channel notification on
107
* `event_channel_port`
108
* In case of multiple notify ioctls, only the last one survives.
109
*
110
* $FreeBSD$
111
*/
112
113
#ifndef __XEN_GNTDEV_H__
114
#define __XEN_GNTDEV_H__
115
116
#include <sys/types.h>
117
118
#define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \
119
_IOW('E', 0, struct ioctl_gntdev_unmap_notify)
120
struct
ioctl_gntdev_unmap_notify
{
121
/* IN parameters */
122
uint64_t index;
123
uint32_t action;
124
uint32_t event_channel_port;
125
};
126
127
#define UNMAP_NOTIFY_CLEAR_BYTE 0x1
128
#define UNMAP_NOTIFY_SEND_EVENT 0x2
129
130
/*-------------------- Grant Allocation IOCTLs ------------------------------*/
131
132
#define IOCTL_GNTDEV_ALLOC_GREF \
133
_IOWR('E', 1, struct ioctl_gntdev_alloc_gref)
134
struct
ioctl_gntdev_alloc_gref
{
135
/* IN parameters */
136
uint16_t domid;
137
uint16_t flags;
138
uint32_t count;
139
/* OUT parameters */
140
uint64_t index;
141
/* Variable OUT parameter */
142
uint32_t *gref_ids;
143
};
144
145
#define GNTDEV_ALLOC_FLAG_WRITABLE 1
146
147
#define IOCTL_GNTDEV_DEALLOC_GREF \
148
_IOW('E', 2, struct ioctl_gntdev_dealloc_gref)
149
struct
ioctl_gntdev_dealloc_gref
{
150
/* IN parameters */
151
uint64_t index;
152
uint32_t count;
153
};
154
155
/*-------------------- Grant Mapping IOCTLs ---------------------------------*/
156
157
struct
ioctl_gntdev_grant_ref
{
158
uint32_t domid;
159
uint32_t ref;
160
};
161
162
#define IOCTL_GNTDEV_MAP_GRANT_REF \
163
_IOWR('E', 3, struct ioctl_gntdev_map_grant_ref)
164
struct
ioctl_gntdev_map_grant_ref
{
165
/* IN parameters */
166
uint32_t count;
167
uint32_t pad0;
168
/* OUT parameters */
169
uint64_t index;
170
/* Variable IN parameter */
171
struct
ioctl_gntdev_grant_ref
*refs;
172
};
173
174
#define IOCTL_GNTDEV_UNMAP_GRANT_REF \
175
_IOW('E', 4, struct ioctl_gntdev_unmap_grant_ref)
176
struct
ioctl_gntdev_unmap_grant_ref
{
177
/* IN parameters */
178
uint64_t index;
179
uint32_t count;
180
};
181
182
#define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \
183
_IOWR('E', 5, struct ioctl_gntdev_get_offset_for_vaddr)
184
struct
ioctl_gntdev_get_offset_for_vaddr
{
185
/* IN parameters */
186
uint64_t vaddr;
187
/* OUT parameters */
188
uint64_t offset;
189
uint32_t count;
190
};
191
192
#endif
/* __XEN_GNTDEV_H__ */
ioctl_gntdev_alloc_gref
Definition:
gntdev.h:134
ioctl_gntdev_dealloc_gref
Definition:
gntdev.h:149
ioctl_gntdev_get_offset_for_vaddr
Definition:
gntdev.h:184
ioctl_gntdev_grant_ref
Definition:
gntdev.h:157
ioctl_gntdev_map_grant_ref
Definition:
gntdev.h:164
ioctl_gntdev_unmap_grant_ref
Definition:
gntdev.h:176
ioctl_gntdev_unmap_notify
Definition:
gntdev.h:120
xen
gntdev.h
Generated by
1.9.3