1 /******************************************************************************
4 * Device for creating grant references (in user-space) that may be shared
7 * This program is distributed in the hope that it will be useful,
8 * but WITHOUT ANY WARRANTY; without even the implied warranty of
9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 * GNU General Public License for more details.
12 * You should have received a copy of the GNU General Public License
13 * along with this program; if not, write to the Free Software
14 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 * This driver exists to allow userspace programs in Linux to allocate kernel
19 * memory that will later be shared with another domain. Without this device,
20 * Linux userspace programs cannot create grant references.
22 * How this stuff works:
23 * X -> granting a page to Y
24 * Y -> mapping the grant from X
26 * 1. X uses the gntalloc device to allocate a page of kernel memory, P.
27 * 2. X creates an entry in the grant table that says domid(Y) can access P.
28 * This is done without a hypercall unless the grant table needs expansion.
29 * 3. X gives the grant reference identifier, GREF, to Y.
30 * 4. Y maps the page, either directly into kernel memory for use in a backend
31 * driver, or via a the gntdev device to map into the address space of an
32 * application running in Y. This is the first point at which Xen does any
33 * tracking of the page.
34 * 5. A program in X mmap()s a segment of the gntalloc device that corresponds
35 * to the shared page, and can now communicate with Y over the shared page.
38 * NOTE TO USERSPACE LIBRARIES:
39 * The grant allocation and mmap()ing are, naturally, two separate operations.
40 * You set up the sharing by calling the create ioctl() and then the mmap().
41 * Teardown requires munmap() and either close() or ioctl().
43 * WARNING: Since Xen does not allow a guest to forcibly end the use of a grant
44 * reference, this device can be used to consume kernel memory by leaving grant
45 * references mapped by another domain when an application exits. Therefore,
46 * there is a global limit on the number of pages that can be allocated. When
47 * all references to the page are unmapped, it will be freed during the next
51 #include <linux/atomic.h>
52 #include <linux/module.h>
53 #include <linux/miscdevice.h>
54 #include <linux/kernel.h>
55 #include <linux/init.h>
56 #include <linux/slab.h>
58 #include <linux/device.h>
60 #include <linux/uaccess.h>
61 #include <linux/types.h>
62 #include <linux/list.h>
63 #include <linux/highmem.h>
67 #include <xen/grant_table.h>
68 #include <xen/gntalloc.h>
69 #include <xen/events.h>
71 static int limit
= 1024;
72 module_param(limit
, int, 0644);
73 MODULE_PARM_DESC(limit
, "Maximum number of grants that may be allocated by "
74 "the gntalloc device");
76 static LIST_HEAD(gref_list
);
77 static DEFINE_SPINLOCK(gref_lock
);
81 uint16_t pgoff
:12; /* Bits 0-11: Offset of the byte to clear */
82 uint16_t flags
:2; /* Bits 12-13: Unmap notification flags */
83 int event
; /* Port (event channel) to notify */
86 /* Metadata on a grant reference. */
87 struct gntalloc_gref
{
88 struct list_head next_gref
; /* list entry gref_list */
89 struct list_head next_file
; /* list entry file->list, if open */
90 struct page
*page
; /* The shared page */
91 uint64_t file_index
; /* File offset for mmap() */
92 unsigned int users
; /* Use count - when zero, waiting on Xen */
93 grant_ref_t gref_id
; /* The grant reference number */
94 struct notify_info notify
; /* Unmap notification */
97 struct gntalloc_file_private_data
{
98 struct list_head list
;
102 static void __del_gref(struct gntalloc_gref
*gref
);
104 static void do_cleanup(void)
106 struct gntalloc_gref
*gref
, *n
;
107 list_for_each_entry_safe(gref
, n
, &gref_list
, next_gref
) {
113 static int add_grefs(struct ioctl_gntalloc_alloc_gref
*op
,
114 uint32_t *gref_ids
, struct gntalloc_file_private_data
*priv
)
117 LIST_HEAD(queue_gref
);
118 LIST_HEAD(queue_file
);
119 struct gntalloc_gref
*gref
;
121 readonly
= !(op
->flags
& GNTALLOC_FLAG_WRITABLE
);
123 for (i
= 0; i
< op
->count
; i
++) {
124 gref
= kzalloc(sizeof(*gref
), GFP_KERNEL
);
127 list_add_tail(&gref
->next_gref
, &queue_gref
);
128 list_add_tail(&gref
->next_file
, &queue_file
);
130 gref
->file_index
= op
->index
+ i
* PAGE_SIZE
;
131 gref
->page
= alloc_page(GFP_KERNEL
|__GFP_ZERO
);
135 /* Grant foreign access to the page. */
136 gref
->gref_id
= gnttab_grant_foreign_access(op
->domid
,
137 pfn_to_mfn(page_to_pfn(gref
->page
)), readonly
);
138 if (gref
->gref_id
< 0) {
142 gref_ids
[i
] = gref
->gref_id
;
145 /* Add to gref lists. */
146 spin_lock(&gref_lock
);
147 list_splice_tail(&queue_gref
, &gref_list
);
148 list_splice_tail(&queue_file
, &priv
->list
);
149 spin_unlock(&gref_lock
);
154 spin_lock(&gref_lock
);
155 gref_size
-= (op
->count
- i
);
157 list_for_each_entry(gref
, &queue_file
, next_file
) {
158 /* __del_gref does not remove from queue_file */
162 /* It's possible for the target domain to map the just-allocated grant
163 * references by blindly guessing their IDs; if this is done, then
164 * __del_gref will leave them in the queue_gref list. They need to be
165 * added to the global list so that we can free them when they are no
168 if (unlikely(!list_empty(&queue_gref
)))
169 list_splice_tail(&queue_gref
, &gref_list
);
170 spin_unlock(&gref_lock
);
174 static void __del_gref(struct gntalloc_gref
*gref
)
176 if (gref
->notify
.flags
& UNMAP_NOTIFY_CLEAR_BYTE
) {
177 uint8_t *tmp
= kmap(gref
->page
);
178 tmp
[gref
->notify
.pgoff
] = 0;
181 if (gref
->notify
.flags
& UNMAP_NOTIFY_SEND_EVENT
)
182 notify_remote_via_evtchn(gref
->notify
.event
);
184 gref
->notify
.flags
= 0;
186 if (gref
->gref_id
> 0) {
187 if (gnttab_query_foreign_access(gref
->gref_id
))
190 if (!gnttab_end_foreign_access_ref(gref
->gref_id
, 0))
195 list_del(&gref
->next_gref
);
198 __free_page(gref
->page
);
203 /* finds contiguous grant references in a file, returns the first */
204 static struct gntalloc_gref
*find_grefs(struct gntalloc_file_private_data
*priv
,
205 uint64_t index
, uint32_t count
)
207 struct gntalloc_gref
*rv
= NULL
, *gref
;
208 list_for_each_entry(gref
, &priv
->list
, next_file
) {
209 if (gref
->file_index
== index
&& !rv
)
212 if (gref
->file_index
!= index
)
224 * -------------------------------------
226 * -------------------------------------
228 static int gntalloc_open(struct inode
*inode
, struct file
*filp
)
230 struct gntalloc_file_private_data
*priv
;
232 priv
= kzalloc(sizeof(*priv
), GFP_KERNEL
);
235 INIT_LIST_HEAD(&priv
->list
);
237 filp
->private_data
= priv
;
239 pr_debug("%s: priv %p\n", __func__
, priv
);
247 static int gntalloc_release(struct inode
*inode
, struct file
*filp
)
249 struct gntalloc_file_private_data
*priv
= filp
->private_data
;
250 struct gntalloc_gref
*gref
;
252 pr_debug("%s: priv %p\n", __func__
, priv
);
254 spin_lock(&gref_lock
);
255 while (!list_empty(&priv
->list
)) {
256 gref
= list_entry(priv
->list
.next
,
257 struct gntalloc_gref
, next_file
);
258 list_del(&gref
->next_file
);
260 if (gref
->users
== 0)
264 spin_unlock(&gref_lock
);
269 static long gntalloc_ioctl_alloc(struct gntalloc_file_private_data
*priv
,
270 struct ioctl_gntalloc_alloc_gref __user
*arg
)
273 struct ioctl_gntalloc_alloc_gref op
;
276 pr_debug("%s: priv %p\n", __func__
, priv
);
278 if (copy_from_user(&op
, arg
, sizeof(op
))) {
283 gref_ids
= kzalloc(sizeof(gref_ids
[0]) * op
.count
, GFP_TEMPORARY
);
289 spin_lock(&gref_lock
);
290 /* Clean up pages that were at zero (local) users but were still mapped
291 * by remote domains. Since those pages count towards the limit that we
292 * are about to enforce, removing them here is a good idea.
295 if (gref_size
+ op
.count
> limit
) {
296 spin_unlock(&gref_lock
);
300 gref_size
+= op
.count
;
301 op
.index
= priv
->index
;
302 priv
->index
+= op
.count
* PAGE_SIZE
;
303 spin_unlock(&gref_lock
);
305 rc
= add_grefs(&op
, gref_ids
, priv
);
309 /* Once we finish add_grefs, it is unsafe to touch the new reference,
310 * since it is possible for a concurrent ioctl to remove it (by guessing
311 * its index). If the userspace application doesn't provide valid memory
312 * to write the IDs to, then it will need to close the file in order to
313 * release - which it will do by segfaulting when it tries to access the
316 if (copy_to_user(arg
, &op
, sizeof(op
))) {
320 if (copy_to_user(arg
->gref_ids
, gref_ids
,
321 sizeof(gref_ids
[0]) * op
.count
)) {
332 static long gntalloc_ioctl_dealloc(struct gntalloc_file_private_data
*priv
,
336 struct ioctl_gntalloc_dealloc_gref op
;
337 struct gntalloc_gref
*gref
, *n
;
339 pr_debug("%s: priv %p\n", __func__
, priv
);
341 if (copy_from_user(&op
, arg
, sizeof(op
))) {
343 goto dealloc_grant_out
;
346 spin_lock(&gref_lock
);
347 gref
= find_grefs(priv
, op
.index
, op
.count
);
349 /* Remove from the file list only, and decrease reference count.
350 * The later call to do_cleanup() will remove from gref_list and
351 * free the memory if the pages aren't mapped anywhere.
353 for (i
= 0; i
< op
.count
; i
++) {
354 n
= list_entry(gref
->next_file
.next
,
355 struct gntalloc_gref
, next_file
);
356 list_del(&gref
->next_file
);
366 spin_unlock(&gref_lock
);
371 static long gntalloc_ioctl_unmap_notify(struct gntalloc_file_private_data
*priv
,
374 struct ioctl_gntalloc_unmap_notify op
;
375 struct gntalloc_gref
*gref
;
380 if (copy_from_user(&op
, arg
, sizeof(op
)))
383 index
= op
.index
& ~(PAGE_SIZE
- 1);
384 pgoff
= op
.index
& (PAGE_SIZE
- 1);
386 spin_lock(&gref_lock
);
388 gref
= find_grefs(priv
, index
, 1);
394 if (op
.action
& ~(UNMAP_NOTIFY_CLEAR_BYTE
|UNMAP_NOTIFY_SEND_EVENT
)) {
399 gref
->notify
.flags
= op
.action
;
400 gref
->notify
.pgoff
= pgoff
;
401 gref
->notify
.event
= op
.event_channel_port
;
404 spin_unlock(&gref_lock
);
408 static long gntalloc_ioctl(struct file
*filp
, unsigned int cmd
,
411 struct gntalloc_file_private_data
*priv
= filp
->private_data
;
414 case IOCTL_GNTALLOC_ALLOC_GREF
:
415 return gntalloc_ioctl_alloc(priv
, (void __user
*)arg
);
417 case IOCTL_GNTALLOC_DEALLOC_GREF
:
418 return gntalloc_ioctl_dealloc(priv
, (void __user
*)arg
);
420 case IOCTL_GNTALLOC_SET_UNMAP_NOTIFY
:
421 return gntalloc_ioctl_unmap_notify(priv
, (void __user
*)arg
);
430 static void gntalloc_vma_close(struct vm_area_struct
*vma
)
432 struct gntalloc_gref
*gref
= vma
->vm_private_data
;
436 spin_lock(&gref_lock
);
438 if (gref
->users
== 0)
440 spin_unlock(&gref_lock
);
443 static struct vm_operations_struct gntalloc_vmops
= {
444 .close
= gntalloc_vma_close
,
447 static int gntalloc_mmap(struct file
*filp
, struct vm_area_struct
*vma
)
449 struct gntalloc_file_private_data
*priv
= filp
->private_data
;
450 struct gntalloc_gref
*gref
;
451 int count
= (vma
->vm_end
- vma
->vm_start
) >> PAGE_SHIFT
;
454 pr_debug("%s: priv %p, page %lu+%d\n", __func__
,
455 priv
, vma
->vm_pgoff
, count
);
457 if (!(vma
->vm_flags
& VM_SHARED
)) {
458 printk(KERN_ERR
"%s: Mapping must be shared.\n", __func__
);
462 spin_lock(&gref_lock
);
463 gref
= find_grefs(priv
, vma
->vm_pgoff
<< PAGE_SHIFT
, count
);
466 pr_debug("%s: Could not find grant reference",
471 vma
->vm_private_data
= gref
;
473 vma
->vm_flags
|= VM_RESERVED
;
474 vma
->vm_flags
|= VM_DONTCOPY
;
475 vma
->vm_flags
|= VM_PFNMAP
| VM_PFN_AT_MMAP
;
477 vma
->vm_ops
= &gntalloc_vmops
;
479 for (i
= 0; i
< count
; i
++) {
481 rv
= vm_insert_page(vma
, vma
->vm_start
+ i
* PAGE_SIZE
,
486 gref
= list_entry(gref
->next_file
.next
,
487 struct gntalloc_gref
, next_file
);
492 spin_unlock(&gref_lock
);
496 static const struct file_operations gntalloc_fops
= {
497 .owner
= THIS_MODULE
,
498 .open
= gntalloc_open
,
499 .release
= gntalloc_release
,
500 .unlocked_ioctl
= gntalloc_ioctl
,
501 .mmap
= gntalloc_mmap
505 * -------------------------------------
506 * Module creation/destruction.
507 * -------------------------------------
509 static struct miscdevice gntalloc_miscdev
= {
510 .minor
= MISC_DYNAMIC_MINOR
,
511 .name
= "xen/gntalloc",
512 .fops
= &gntalloc_fops
,
515 static int __init
gntalloc_init(void)
522 err
= misc_register(&gntalloc_miscdev
);
524 printk(KERN_ERR
"Could not register misc gntalloc device\n");
528 pr_debug("Created grant allocation device at %d,%d\n",
529 MISC_MAJOR
, gntalloc_miscdev
.minor
);
534 static void __exit
gntalloc_exit(void)
536 misc_deregister(&gntalloc_miscdev
);
539 module_init(gntalloc_init
);
540 module_exit(gntalloc_exit
);
542 MODULE_LICENSE("GPL");
543 MODULE_AUTHOR("Carter Weatherly <carter.weatherly@jhuapl.edu>, "
544 "Daniel De Graaf <dgdegra@tycho.nsa.gov>");
545 MODULE_DESCRIPTION("User-space grant reference allocator driver");