]> git.ipfire.org Git - thirdparty/kernel/stable.git/blame - drivers/xen/gntdev.c
Merge git://git.kernel.org/pub/scm/linux/kernel/git/davem/net
[thirdparty/kernel/stable.git] / drivers / xen / gntdev.c
CommitLineData
ab31523c
GH
1/******************************************************************************
2 * gntdev.c
3 *
4 * Device for accessing (in user-space) pages that have been granted by other
5 * domains.
6 *
7 * Copyright (c) 2006-2007, D G Murray.
8 * (c) 2009 Gerd Hoffmann <kraxel@redhat.com>
1d314567 9 * (c) 2018 Oleksandr Andrushchenko, EPAM Systems Inc.
ab31523c
GH
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20
21#undef DEBUG
22
283c0972
JP
23#define pr_fmt(fmt) "xen:" KBUILD_MODNAME ": " fmt
24
ab31523c
GH
25#include <linux/module.h>
26#include <linux/kernel.h>
27#include <linux/init.h>
28#include <linux/miscdevice.h>
29#include <linux/fs.h>
ab31523c
GH
30#include <linux/uaccess.h>
31#include <linux/sched.h>
6e84f315 32#include <linux/sched/mm.h>
ab31523c
GH
33#include <linux/spinlock.h>
34#include <linux/slab.h>
aab8f11a 35#include <linux/highmem.h>
c5f7c5a9 36#include <linux/refcount.h>
975ef7ff
OA
37#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
38#include <linux/of_device.h>
39#endif
ab31523c
GH
40
41#include <xen/xen.h>
42#include <xen/grant_table.h>
ca47ceaa 43#include <xen/balloon.h>
ab31523c 44#include <xen/gntdev.h>
bdc612dc 45#include <xen/events.h>
a9fd60e2 46#include <xen/page.h>
ab31523c
GH
47#include <asm/xen/hypervisor.h>
48#include <asm/xen/hypercall.h>
ab31523c 49
1d314567 50#include "gntdev-common.h"
932d6562
OA
51#ifdef CONFIG_XEN_GNTDEV_DMABUF
52#include "gntdev-dmabuf.h"
53#endif
1d314567 54
ab31523c
GH
55MODULE_LICENSE("GPL");
56MODULE_AUTHOR("Derek G. Murray <Derek.Murray@cl.cam.ac.uk>, "
57 "Gerd Hoffmann <kraxel@redhat.com>");
58MODULE_DESCRIPTION("User-space granted page access driver");
59
ef91082e 60static int limit = 1024*1024;
ab31523c 61module_param(limit, int, 0644);
ef91082e
DDG
62MODULE_PARM_DESC(limit, "Maximum number of grants that may be mapped by "
63 "the gntdev device");
64
65static atomic_t pages_mapped = ATOMIC_INIT(0);
ab31523c 66
aab8f11a 67static int use_ptemod;
16a1d022 68#define populate_freeable_maps use_ptemod
aab8f11a 69
1d314567
OA
70static int unmap_grant_pages(struct gntdev_grant_map *map,
71 int offset, int pages);
aab8f11a 72
975ef7ff
OA
73static struct miscdevice gntdev_miscdev;
74
ab31523c
GH
75/* ------------------------------------------------------------------ */
76
1d314567
OA
77bool gntdev_account_mapped_pages(int count)
78{
79 return atomic_add_return(count, &pages_mapped) > limit;
80}
81
ab31523c
GH
82static void gntdev_print_maps(struct gntdev_priv *priv,
83 char *text, int text_index)
84{
85#ifdef DEBUG
1d314567 86 struct gntdev_grant_map *map;
ab31523c 87
ef91082e 88 pr_debug("%s: maps list (priv %p)\n", __func__, priv);
ab31523c
GH
89 list_for_each_entry(map, &priv->maps, next)
90 pr_debug(" index %2d, count %2d %s\n",
91 map->index, map->count,
92 map->index == text_index && text ? text : "");
93#endif
94}
95
1d314567 96static void gntdev_free_map(struct gntdev_grant_map *map)
a67baeb7
DV
97{
98 if (map == NULL)
99 return;
100
975ef7ff
OA
101#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
102 if (map->dma_vaddr) {
103 struct gnttab_dma_alloc_args args;
104
105 args.dev = map->dma_dev;
106 args.coherent = !!(map->dma_flags & GNTDEV_DMA_FLAG_COHERENT);
107 args.nr_pages = map->count;
108 args.pages = map->pages;
109 args.frames = map->frames;
110 args.vaddr = map->dma_vaddr;
111 args.dev_bus_addr = map->dma_bus_addr;
112
113 gnttab_dma_free_pages(&args);
114 } else
115#endif
a67baeb7 116 if (map->pages)
ff4b156f 117 gnttab_free_pages(map->count, map->pages);
975ef7ff
OA
118
119#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
120 kfree(map->frames);
121#endif
a67baeb7
DV
122 kfree(map->pages);
123 kfree(map->grants);
124 kfree(map->map_ops);
125 kfree(map->unmap_ops);
126 kfree(map->kmap_ops);
853d0289 127 kfree(map->kunmap_ops);
a67baeb7
DV
128 kfree(map);
129}
130
1d314567 131struct gntdev_grant_map *gntdev_alloc_map(struct gntdev_priv *priv, int count,
975ef7ff 132 int dma_flags)
ab31523c 133{
1d314567 134 struct gntdev_grant_map *add;
a12b4eb3 135 int i;
ab31523c 136
1d314567 137 add = kzalloc(sizeof(*add), GFP_KERNEL);
ab31523c
GH
138 if (NULL == add)
139 return NULL;
140
fc6e0c3b
DC
141 add->grants = kcalloc(count, sizeof(add->grants[0]), GFP_KERNEL);
142 add->map_ops = kcalloc(count, sizeof(add->map_ops[0]), GFP_KERNEL);
143 add->unmap_ops = kcalloc(count, sizeof(add->unmap_ops[0]), GFP_KERNEL);
144 add->kmap_ops = kcalloc(count, sizeof(add->kmap_ops[0]), GFP_KERNEL);
853d0289 145 add->kunmap_ops = kcalloc(count, sizeof(add->kunmap_ops[0]), GFP_KERNEL);
fc6e0c3b 146 add->pages = kcalloc(count, sizeof(add->pages[0]), GFP_KERNEL);
a12b4eb3
SS
147 if (NULL == add->grants ||
148 NULL == add->map_ops ||
149 NULL == add->unmap_ops ||
0930bba6 150 NULL == add->kmap_ops ||
853d0289 151 NULL == add->kunmap_ops ||
a12b4eb3 152 NULL == add->pages)
ab31523c
GH
153 goto err;
154
975ef7ff
OA
155#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
156 add->dma_flags = dma_flags;
157
158 /*
159 * Check if this mapping is requested to be backed
160 * by a DMA buffer.
161 */
162 if (dma_flags & (GNTDEV_DMA_FLAG_WC | GNTDEV_DMA_FLAG_COHERENT)) {
163 struct gnttab_dma_alloc_args args;
164
165 add->frames = kcalloc(count, sizeof(add->frames[0]),
166 GFP_KERNEL);
167 if (!add->frames)
168 goto err;
169
170 /* Remember the device, so we can free DMA memory. */
171 add->dma_dev = priv->dma_dev;
172
173 args.dev = priv->dma_dev;
174 args.coherent = !!(dma_flags & GNTDEV_DMA_FLAG_COHERENT);
175 args.nr_pages = count;
176 args.pages = add->pages;
177 args.frames = add->frames;
178
179 if (gnttab_dma_alloc_pages(&args))
180 goto err;
181
182 add->dma_vaddr = args.vaddr;
183 add->dma_bus_addr = args.dev_bus_addr;
184 } else
185#endif
ff4b156f 186 if (gnttab_alloc_pages(count, add->pages))
ca47ceaa
DDG
187 goto err;
188
a12b4eb3 189 for (i = 0; i < count; i++) {
77c35acb
DDG
190 add->map_ops[i].handle = -1;
191 add->unmap_ops[i].handle = -1;
0930bba6 192 add->kmap_ops[i].handle = -1;
853d0289 193 add->kunmap_ops[i].handle = -1;
a12b4eb3
SS
194 }
195
ab31523c
GH
196 add->index = 0;
197 add->count = count;
c5f7c5a9 198 refcount_set(&add->users, 1);
ab31523c 199
ab31523c
GH
200 return add;
201
202err:
a67baeb7 203 gntdev_free_map(add);
ab31523c
GH
204 return NULL;
205}
206
1d314567 207void gntdev_add_map(struct gntdev_priv *priv, struct gntdev_grant_map *add)
ab31523c 208{
1d314567 209 struct gntdev_grant_map *map;
ab31523c
GH
210
211 list_for_each_entry(map, &priv->maps, next) {
212 if (add->index + add->count < map->index) {
213 list_add_tail(&add->next, &map->next);
214 goto done;
215 }
216 add->index = map->index + map->count;
217 }
218 list_add_tail(&add->next, &priv->maps);
219
220done:
ab31523c
GH
221 gntdev_print_maps(priv, "[new]", add->index);
222}
223
1d314567
OA
224static struct gntdev_grant_map *gntdev_find_map_index(struct gntdev_priv *priv,
225 int index, int count)
ab31523c 226{
1d314567 227 struct gntdev_grant_map *map;
ab31523c
GH
228
229 list_for_each_entry(map, &priv->maps, next) {
230 if (map->index != index)
231 continue;
bdc612dc 232 if (count && map->count != count)
ab31523c
GH
233 continue;
234 return map;
235 }
236 return NULL;
237}
238
1d314567 239void gntdev_put_map(struct gntdev_priv *priv, struct gntdev_grant_map *map)
ab31523c
GH
240{
241 if (!map)
242 return;
a12b4eb3 243
c5f7c5a9 244 if (!refcount_dec_and_test(&map->users))
68b025c8
DDG
245 return;
246
247 atomic_sub(map->count, &pages_mapped);
248
0cc678f8 249 if (map->notify.flags & UNMAP_NOTIFY_SEND_EVENT) {
bdc612dc 250 notify_remote_via_evtchn(map->notify.event);
0cc678f8
DDG
251 evtchn_put(map->notify.event);
252 }
bdc612dc 253
16a1d022 254 if (populate_freeable_maps && priv) {
1401c00e 255 mutex_lock(&priv->lock);
16a1d022 256 list_del(&map->next);
1401c00e 257 mutex_unlock(&priv->lock);
16a1d022
DDG
258 }
259
a67baeb7
DV
260 if (map->pages && !use_ptemod)
261 unmap_grant_pages(map, 0, map->count);
262 gntdev_free_map(map);
ab31523c
GH
263}
264
265/* ------------------------------------------------------------------ */
266
267static int find_grant_ptes(pte_t *pte, pgtable_t token,
268 unsigned long addr, void *data)
269{
1d314567 270 struct gntdev_grant_map *map = data;
ab31523c 271 unsigned int pgnr = (addr - map->vma->vm_start) >> PAGE_SHIFT;
aab8f11a 272 int flags = map->flags | GNTMAP_application_map | GNTMAP_contains_pte;
ab31523c
GH
273 u64 pte_maddr;
274
275 BUG_ON(pgnr >= map->count);
ba5d1012
JF
276 pte_maddr = arbitrary_virt_to_machine(pte).maddr;
277
923b2919
DV
278 /*
279 * Set the PTE as special to force get_user_pages_fast() fall
280 * back to the slow path. If this is not supported as part of
281 * the grant map, it will be done afterwards.
282 */
283 if (xen_feature(XENFEAT_gnttab_map_avail_bits))
284 flags |= (1 << _GNTMAP_guest_avail0);
285
aab8f11a 286 gnttab_set_map_op(&map->map_ops[pgnr], pte_maddr, flags,
ab31523c
GH
287 map->grants[pgnr].ref,
288 map->grants[pgnr].domid);
aab8f11a 289 gnttab_set_unmap_op(&map->unmap_ops[pgnr], pte_maddr, flags,
77c35acb 290 -1 /* handle */);
ab31523c
GH
291 return 0;
292}
293
923b2919
DV
294#ifdef CONFIG_X86
295static int set_grant_ptes_as_special(pte_t *pte, pgtable_t token,
296 unsigned long addr, void *data)
297{
298 set_pte_at(current->mm, addr, pte, pte_mkspecial(*pte));
299 return 0;
300}
301#endif
302
1d314567 303int gntdev_map_grant_pages(struct gntdev_grant_map *map)
ab31523c
GH
304{
305 int i, err = 0;
aab8f11a
DDG
306
307 if (!use_ptemod) {
12996fc3 308 /* Note: it could already be mapped */
77c35acb 309 if (map->map_ops[0].handle != -1)
12996fc3 310 return 0;
aab8f11a 311 for (i = 0; i < map->count; i++) {
38eaeb0f 312 unsigned long addr = (unsigned long)
aab8f11a
DDG
313 pfn_to_kaddr(page_to_pfn(map->pages[i]));
314 gnttab_set_map_op(&map->map_ops[i], addr, map->flags,
315 map->grants[i].ref,
316 map->grants[i].domid);
317 gnttab_set_unmap_op(&map->unmap_ops[i], addr,
77c35acb 318 map->flags, -1 /* handle */);
aab8f11a 319 }
0930bba6
SS
320 } else {
321 /*
322 * Setup the map_ops corresponding to the pte entries pointing
323 * to the kernel linear addresses of the struct pages.
324 * These ptes are completely different from the user ptes dealt
325 * with find_grant_ptes.
326 */
327 for (i = 0; i < map->count; i++) {
0930bba6
SS
328 unsigned long address = (unsigned long)
329 pfn_to_kaddr(page_to_pfn(map->pages[i]));
0930bba6
SS
330 BUG_ON(PageHighMem(map->pages[i]));
331
ee072640
SS
332 gnttab_set_map_op(&map->kmap_ops[i], address,
333 map->flags | GNTMAP_host_map,
0930bba6
SS
334 map->grants[i].ref,
335 map->grants[i].domid);
853d0289
DV
336 gnttab_set_unmap_op(&map->kunmap_ops[i], address,
337 map->flags | GNTMAP_host_map, -1);
0930bba6 338 }
aab8f11a 339 }
ab31523c
GH
340
341 pr_debug("map %d+%d\n", map->index, map->count);
e85fc980
KRW
342 err = gnttab_map_refs(map->map_ops, use_ptemod ? map->kmap_ops : NULL,
343 map->pages, map->count);
ab31523c
GH
344 if (err)
345 return err;
346
347 for (i = 0; i < map->count; i++) {
853d0289 348 if (map->map_ops[i].status) {
ab31523c 349 err = -EINVAL;
853d0289 350 continue;
77c35acb 351 }
853d0289
DV
352
353 map->unmap_ops[i].handle = map->map_ops[i].handle;
354 if (use_ptemod)
355 map->kunmap_ops[i].handle = map->kmap_ops[i].handle;
975ef7ff
OA
356#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
357 else if (map->dma_vaddr) {
358 unsigned long bfn;
359
360 bfn = pfn_to_bfn(page_to_pfn(map->pages[i]));
361 map->unmap_ops[i].dev_bus_addr = __pfn_to_phys(bfn);
362 }
363#endif
ab31523c
GH
364 }
365 return err;
366}
367
1d314567
OA
368static int __unmap_grant_pages(struct gntdev_grant_map *map, int offset,
369 int pages)
ab31523c
GH
370{
371 int i, err = 0;
74528225 372 struct gntab_unmap_queue_data unmap_data;
ab31523c 373
bdc612dc
DDG
374 if (map->notify.flags & UNMAP_NOTIFY_CLEAR_BYTE) {
375 int pgno = (map->notify.addr >> PAGE_SHIFT);
1affa98d
DDG
376 if (pgno >= offset && pgno < offset + pages) {
377 /* No need for kmap, pages are in lowmem */
378 uint8_t *tmp = pfn_to_kaddr(page_to_pfn(map->pages[pgno]));
bdc612dc 379 tmp[map->notify.addr & (PAGE_SIZE-1)] = 0;
bdc612dc
DDG
380 map->notify.flags &= ~UNMAP_NOTIFY_CLEAR_BYTE;
381 }
382 }
383
74528225
JH
384 unmap_data.unmap_ops = map->unmap_ops + offset;
385 unmap_data.kunmap_ops = use_ptemod ? map->kunmap_ops + offset : NULL;
386 unmap_data.pages = map->pages + offset;
387 unmap_data.count = pages;
388
b44166cd
BL
389 err = gnttab_unmap_refs_sync(&unmap_data);
390 if (err)
391 return err;
ab31523c
GH
392
393 for (i = 0; i < pages; i++) {
394 if (map->unmap_ops[offset+i].status)
395 err = -EINVAL;
77c35acb
DDG
396 pr_debug("unmap handle=%d st=%d\n",
397 map->unmap_ops[offset+i].handle,
398 map->unmap_ops[offset+i].status);
399 map->unmap_ops[offset+i].handle = -1;
ab31523c
GH
400 }
401 return err;
402}
403
1d314567
OA
404static int unmap_grant_pages(struct gntdev_grant_map *map, int offset,
405 int pages)
b57c1869
DDG
406{
407 int range, err = 0;
408
409 pr_debug("unmap %d+%d [%d+%d]\n", map->index, map->count, offset, pages);
410
411 /* It is possible the requested range will have a "hole" where we
412 * already unmapped some of the grants. Only unmap valid ranges.
413 */
414 while (pages && !err) {
77c35acb 415 while (pages && map->unmap_ops[offset].handle == -1) {
b57c1869
DDG
416 offset++;
417 pages--;
418 }
419 range = 0;
420 while (range < pages) {
951a0102 421 if (map->unmap_ops[offset+range].handle == -1)
b57c1869 422 break;
b57c1869
DDG
423 range++;
424 }
425 err = __unmap_grant_pages(map, offset, range);
426 offset += range;
427 pages -= range;
428 }
429
430 return err;
431}
432
ab31523c
GH
433/* ------------------------------------------------------------------ */
434
d79647ae
DDG
435static void gntdev_vma_open(struct vm_area_struct *vma)
436{
1d314567 437 struct gntdev_grant_map *map = vma->vm_private_data;
d79647ae
DDG
438
439 pr_debug("gntdev_vma_open %p\n", vma);
c5f7c5a9 440 refcount_inc(&map->users);
d79647ae
DDG
441}
442
ab31523c
GH
443static void gntdev_vma_close(struct vm_area_struct *vma)
444{
1d314567 445 struct gntdev_grant_map *map = vma->vm_private_data;
16a1d022
DDG
446 struct file *file = vma->vm_file;
447 struct gntdev_priv *priv = file->private_data;
ab31523c 448
d79647ae 449 pr_debug("gntdev_vma_close %p\n", vma);
2512f298 450 if (use_ptemod) {
2512f298
DDG
451 /* It is possible that an mmu notifier could be running
452 * concurrently, so take priv->lock to ensure that the vma won't
453 * vanishing during the unmap_grant_pages call, since we will
454 * spin here until that completes. Such a concurrent call will
455 * not do any unmapping, since that has been done prior to
456 * closing the vma, but it may still iterate the unmap_ops list.
457 */
1401c00e 458 mutex_lock(&priv->lock);
2512f298 459 map->vma = NULL;
1401c00e 460 mutex_unlock(&priv->lock);
2512f298 461 }
ab31523c 462 vma->vm_private_data = NULL;
16a1d022 463 gntdev_put_map(priv, map);
ab31523c
GH
464}
465
dab069c6
DV
466static struct page *gntdev_vma_find_special_page(struct vm_area_struct *vma,
467 unsigned long addr)
468{
1d314567 469 struct gntdev_grant_map *map = vma->vm_private_data;
dab069c6
DV
470
471 return map->pages[(addr - map->pages_vm_start) >> PAGE_SHIFT];
472}
473
7cbea8dc 474static const struct vm_operations_struct gntdev_vmops = {
d79647ae 475 .open = gntdev_vma_open,
ab31523c 476 .close = gntdev_vma_close,
dab069c6 477 .find_special_page = gntdev_vma_find_special_page,
ab31523c
GH
478};
479
480/* ------------------------------------------------------------------ */
481
93065ac7
MH
482static bool in_range(struct gntdev_grant_map *map,
483 unsigned long start, unsigned long end)
484{
485 if (!map->vma)
486 return false;
487 if (map->vma->vm_start >= end)
488 return false;
489 if (map->vma->vm_end <= start)
490 return false;
491
492 return true;
493}
494
58a57569
MH
495static int unmap_if_in_range(struct gntdev_grant_map *map,
496 unsigned long start, unsigned long end,
497 bool blockable)
16a1d022
DDG
498{
499 unsigned long mstart, mend;
500 int err;
501
58a57569
MH
502 if (!in_range(map, start, end))
503 return 0;
504
505 if (!blockable)
506 return -EAGAIN;
507
16a1d022
DDG
508 mstart = max(start, map->vma->vm_start);
509 mend = min(end, map->vma->vm_end);
510 pr_debug("map %d+%d (%lx %lx), range %lx %lx, mrange %lx %lx\n",
511 map->index, map->count,
512 map->vma->vm_start, map->vma->vm_end,
513 start, end, mstart, mend);
514 err = unmap_grant_pages(map,
515 (mstart - map->vma->vm_start) >> PAGE_SHIFT,
516 (mend - mstart) >> PAGE_SHIFT);
517 WARN_ON(err);
58a57569
MH
518
519 return 0;
16a1d022
DDG
520}
521
93065ac7 522static int mn_invl_range_start(struct mmu_notifier *mn,
5d6527a7 523 const struct mmu_notifier_range *range)
ab31523c
GH
524{
525 struct gntdev_priv *priv = container_of(mn, struct gntdev_priv, mn);
1d314567 526 struct gntdev_grant_map *map;
93065ac7
MH
527 int ret = 0;
528
5d6527a7 529 if (range->blockable)
93065ac7
MH
530 mutex_lock(&priv->lock);
531 else if (!mutex_trylock(&priv->lock))
532 return -EAGAIN;
ab31523c 533
ab31523c 534 list_for_each_entry(map, &priv->maps, next) {
5d6527a7
JG
535 ret = unmap_if_in_range(map, range->start, range->end,
536 range->blockable);
58a57569 537 if (ret)
93065ac7 538 goto out_unlock;
16a1d022
DDG
539 }
540 list_for_each_entry(map, &priv->freeable_maps, next) {
5d6527a7
JG
541 ret = unmap_if_in_range(map, range->start, range->end,
542 range->blockable);
58a57569 543 if (ret)
93065ac7 544 goto out_unlock;
ab31523c 545 }
93065ac7
MH
546
547out_unlock:
1401c00e 548 mutex_unlock(&priv->lock);
93065ac7
MH
549
550 return ret;
ab31523c
GH
551}
552
ab31523c
GH
553static void mn_release(struct mmu_notifier *mn,
554 struct mm_struct *mm)
555{
556 struct gntdev_priv *priv = container_of(mn, struct gntdev_priv, mn);
1d314567 557 struct gntdev_grant_map *map;
ab31523c
GH
558 int err;
559
1401c00e 560 mutex_lock(&priv->lock);
ab31523c
GH
561 list_for_each_entry(map, &priv->maps, next) {
562 if (!map->vma)
563 continue;
564 pr_debug("map %d+%d (%lx %lx)\n",
565 map->index, map->count,
566 map->vma->vm_start, map->vma->vm_end);
567 err = unmap_grant_pages(map, /* offset */ 0, map->count);
568 WARN_ON(err);
569 }
16a1d022
DDG
570 list_for_each_entry(map, &priv->freeable_maps, next) {
571 if (!map->vma)
572 continue;
573 pr_debug("map %d+%d (%lx %lx)\n",
574 map->index, map->count,
575 map->vma->vm_start, map->vma->vm_end);
576 err = unmap_grant_pages(map, /* offset */ 0, map->count);
577 WARN_ON(err);
578 }
1401c00e 579 mutex_unlock(&priv->lock);
ab31523c
GH
580}
581
b9c0a92a 582static const struct mmu_notifier_ops gntdev_mmu_ops = {
ab31523c 583 .release = mn_release,
ab31523c
GH
584 .invalidate_range_start = mn_invl_range_start,
585};
586
587/* ------------------------------------------------------------------ */
588
589static int gntdev_open(struct inode *inode, struct file *flip)
590{
591 struct gntdev_priv *priv;
592 int ret = 0;
593
594 priv = kzalloc(sizeof(*priv), GFP_KERNEL);
595 if (!priv)
596 return -ENOMEM;
597
598 INIT_LIST_HEAD(&priv->maps);
16a1d022 599 INIT_LIST_HEAD(&priv->freeable_maps);
1401c00e 600 mutex_init(&priv->lock);
ab31523c 601
932d6562 602#ifdef CONFIG_XEN_GNTDEV_DMABUF
fa13e665 603 priv->dmabuf_priv = gntdev_dmabuf_init(flip);
932d6562
OA
604 if (IS_ERR(priv->dmabuf_priv)) {
605 ret = PTR_ERR(priv->dmabuf_priv);
606 kfree(priv);
607 return ret;
608 }
609#endif
610
aab8f11a
DDG
611 if (use_ptemod) {
612 priv->mm = get_task_mm(current);
613 if (!priv->mm) {
614 kfree(priv);
615 return -ENOMEM;
616 }
617 priv->mn.ops = &gntdev_mmu_ops;
618 ret = mmu_notifier_register(&priv->mn, priv->mm);
619 mmput(priv->mm);
ab31523c 620 }
ab31523c
GH
621
622 if (ret) {
623 kfree(priv);
624 return ret;
625 }
626
627 flip->private_data = priv;
975ef7ff
OA
628#ifdef CONFIG_XEN_GRANT_DMA_ALLOC
629 priv->dma_dev = gntdev_miscdev.this_device;
630
631 /*
632 * The device is not spawn from a device tree, so arch_setup_dma_ops
633 * is not called, thus leaving the device with dummy DMA ops.
634 * Fix this by calling of_dma_configure() with a NULL node to set
635 * default DMA ops.
636 */
637 of_dma_configure(priv->dma_dev, NULL, true);
638#endif
ab31523c
GH
639 pr_debug("priv %p\n", priv);
640
641 return 0;
642}
643
644static int gntdev_release(struct inode *inode, struct file *flip)
645{
646 struct gntdev_priv *priv = flip->private_data;
1d314567 647 struct gntdev_grant_map *map;
ab31523c
GH
648
649 pr_debug("priv %p\n", priv);
650
30b03d05 651 mutex_lock(&priv->lock);
ab31523c 652 while (!list_empty(&priv->maps)) {
1d314567
OA
653 map = list_entry(priv->maps.next,
654 struct gntdev_grant_map, next);
68b025c8 655 list_del(&map->next);
16a1d022 656 gntdev_put_map(NULL /* already removed */, map);
ab31523c 657 }
16a1d022 658 WARN_ON(!list_empty(&priv->freeable_maps));
30b03d05 659 mutex_unlock(&priv->lock);
ab31523c 660
932d6562
OA
661#ifdef CONFIG_XEN_GNTDEV_DMABUF
662 gntdev_dmabuf_fini(priv->dmabuf_priv);
663#endif
664
aab8f11a
DDG
665 if (use_ptemod)
666 mmu_notifier_unregister(&priv->mn, priv->mm);
932d6562 667
ab31523c
GH
668 kfree(priv);
669 return 0;
670}
671
672static long gntdev_ioctl_map_grant_ref(struct gntdev_priv *priv,
673 struct ioctl_gntdev_map_grant_ref __user *u)
674{
675 struct ioctl_gntdev_map_grant_ref op;
1d314567 676 struct gntdev_grant_map *map;
ab31523c
GH
677 int err;
678
679 if (copy_from_user(&op, u, sizeof(op)) != 0)
680 return -EFAULT;
681 pr_debug("priv %p, add %d\n", priv, op.count);
682 if (unlikely(op.count <= 0))
683 return -EINVAL;
ab31523c
GH
684
685 err = -ENOMEM;
975ef7ff 686 map = gntdev_alloc_map(priv, op.count, 0 /* This is not a dma-buf. */);
ab31523c
GH
687 if (!map)
688 return err;
ef91082e 689
1d314567 690 if (unlikely(gntdev_account_mapped_pages(op.count))) {
68b025c8 691 pr_debug("can't map: over limit\n");
16a1d022 692 gntdev_put_map(NULL, map);
ab31523c
GH
693 return err;
694 }
695
68b025c8
DDG
696 if (copy_from_user(map->grants, &u->refs,
697 sizeof(map->grants[0]) * op.count) != 0) {
16a1d022
DDG
698 gntdev_put_map(NULL, map);
699 return -EFAULT;
ef91082e
DDG
700 }
701
1401c00e 702 mutex_lock(&priv->lock);
ab31523c
GH
703 gntdev_add_map(priv, map);
704 op.index = map->index << PAGE_SHIFT;
1401c00e 705 mutex_unlock(&priv->lock);
ab31523c 706
68b025c8
DDG
707 if (copy_to_user(u, &op, sizeof(op)) != 0)
708 return -EFAULT;
709
ab31523c
GH
710 return 0;
711}
712
713static long gntdev_ioctl_unmap_grant_ref(struct gntdev_priv *priv,
714 struct ioctl_gntdev_unmap_grant_ref __user *u)
715{
716 struct ioctl_gntdev_unmap_grant_ref op;
1d314567 717 struct gntdev_grant_map *map;
ab31523c
GH
718 int err = -ENOENT;
719
720 if (copy_from_user(&op, u, sizeof(op)) != 0)
721 return -EFAULT;
722 pr_debug("priv %p, del %d+%d\n", priv, (int)op.index, (int)op.count);
723
1401c00e 724 mutex_lock(&priv->lock);
ab31523c 725 map = gntdev_find_map_index(priv, op.index >> PAGE_SHIFT, op.count);
68b025c8
DDG
726 if (map) {
727 list_del(&map->next);
16a1d022
DDG
728 if (populate_freeable_maps)
729 list_add_tail(&map->next, &priv->freeable_maps);
68b025c8
DDG
730 err = 0;
731 }
1401c00e 732 mutex_unlock(&priv->lock);
1f1503ba 733 if (map)
16a1d022 734 gntdev_put_map(priv, map);
ab31523c
GH
735 return err;
736}
737
738static long gntdev_ioctl_get_offset_for_vaddr(struct gntdev_priv *priv,
739 struct ioctl_gntdev_get_offset_for_vaddr __user *u)
740{
741 struct ioctl_gntdev_get_offset_for_vaddr op;
a879211b 742 struct vm_area_struct *vma;
1d314567 743 struct gntdev_grant_map *map;
2512f298 744 int rv = -EINVAL;
ab31523c
GH
745
746 if (copy_from_user(&op, u, sizeof(op)) != 0)
747 return -EFAULT;
748 pr_debug("priv %p, offset for vaddr %lx\n", priv, (unsigned long)op.vaddr);
749
2512f298 750 down_read(&current->mm->mmap_sem);
a879211b
DDG
751 vma = find_vma(current->mm, op.vaddr);
752 if (!vma || vma->vm_ops != &gntdev_vmops)
2512f298 753 goto out_unlock;
a879211b
DDG
754
755 map = vma->vm_private_data;
756 if (!map)
2512f298 757 goto out_unlock;
a879211b 758
ab31523c
GH
759 op.offset = map->index << PAGE_SHIFT;
760 op.count = map->count;
2512f298 761 rv = 0;
ab31523c 762
2512f298
DDG
763 out_unlock:
764 up_read(&current->mm->mmap_sem);
765
766 if (rv == 0 && copy_to_user(u, &op, sizeof(op)) != 0)
ab31523c 767 return -EFAULT;
2512f298 768 return rv;
ab31523c
GH
769}
770
bdc612dc
DDG
771static long gntdev_ioctl_notify(struct gntdev_priv *priv, void __user *u)
772{
773 struct ioctl_gntdev_unmap_notify op;
1d314567 774 struct gntdev_grant_map *map;
bdc612dc 775 int rc;
0cc678f8
DDG
776 int out_flags;
777 unsigned int out_event;
bdc612dc
DDG
778
779 if (copy_from_user(&op, u, sizeof(op)))
780 return -EFAULT;
781
782 if (op.action & ~(UNMAP_NOTIFY_CLEAR_BYTE|UNMAP_NOTIFY_SEND_EVENT))
783 return -EINVAL;
784
0cc678f8
DDG
785 /* We need to grab a reference to the event channel we are going to use
786 * to send the notify before releasing the reference we may already have
787 * (if someone has called this ioctl twice). This is required so that
788 * it is possible to change the clear_byte part of the notification
789 * without disturbing the event channel part, which may now be the last
790 * reference to that event channel.
791 */
792 if (op.action & UNMAP_NOTIFY_SEND_EVENT) {
793 if (evtchn_get(op.event_channel_port))
794 return -EINVAL;
795 }
796
797 out_flags = op.action;
798 out_event = op.event_channel_port;
799
1401c00e 800 mutex_lock(&priv->lock);
bdc612dc
DDG
801
802 list_for_each_entry(map, &priv->maps, next) {
803 uint64_t begin = map->index << PAGE_SHIFT;
804 uint64_t end = (map->index + map->count) << PAGE_SHIFT;
805 if (op.index >= begin && op.index < end)
806 goto found;
807 }
808 rc = -ENOENT;
809 goto unlock_out;
810
811 found:
9960be97
DDG
812 if ((op.action & UNMAP_NOTIFY_CLEAR_BYTE) &&
813 (map->flags & GNTMAP_readonly)) {
814 rc = -EINVAL;
815 goto unlock_out;
816 }
817
0cc678f8
DDG
818 out_flags = map->notify.flags;
819 out_event = map->notify.event;
820
bdc612dc
DDG
821 map->notify.flags = op.action;
822 map->notify.addr = op.index - (map->index << PAGE_SHIFT);
823 map->notify.event = op.event_channel_port;
0cc678f8 824
bdc612dc 825 rc = 0;
0cc678f8 826
bdc612dc 827 unlock_out:
1401c00e 828 mutex_unlock(&priv->lock);
0cc678f8
DDG
829
830 /* Drop the reference to the event channel we did not save in the map */
831 if (out_flags & UNMAP_NOTIFY_SEND_EVENT)
832 evtchn_put(out_event);
833
bdc612dc
DDG
834 return rc;
835}
836
36ae220a 837#define GNTDEV_COPY_BATCH 16
a4cdb556
DV
838
839struct gntdev_copy_batch {
840 struct gnttab_copy ops[GNTDEV_COPY_BATCH];
841 struct page *pages[GNTDEV_COPY_BATCH];
842 s16 __user *status[GNTDEV_COPY_BATCH];
843 unsigned int nr_ops;
844 unsigned int nr_pages;
845};
846
847static int gntdev_get_page(struct gntdev_copy_batch *batch, void __user *virt,
848 bool writeable, unsigned long *gfn)
849{
850 unsigned long addr = (unsigned long)virt;
851 struct page *page;
852 unsigned long xen_pfn;
853 int ret;
854
855 ret = get_user_pages_fast(addr, 1, writeable, &page);
856 if (ret < 0)
857 return ret;
858
859 batch->pages[batch->nr_pages++] = page;
860
861 xen_pfn = page_to_xen_pfn(page) + XEN_PFN_DOWN(addr & ~PAGE_MASK);
862 *gfn = pfn_to_gfn(xen_pfn);
863
864 return 0;
865}
866
867static void gntdev_put_pages(struct gntdev_copy_batch *batch)
868{
869 unsigned int i;
870
871 for (i = 0; i < batch->nr_pages; i++)
872 put_page(batch->pages[i]);
873 batch->nr_pages = 0;
874}
875
876static int gntdev_copy(struct gntdev_copy_batch *batch)
877{
878 unsigned int i;
879
880 gnttab_batch_copy(batch->ops, batch->nr_ops);
881 gntdev_put_pages(batch);
882
883 /*
884 * For each completed op, update the status if the op failed
885 * and all previous ops for the segment were successful.
886 */
887 for (i = 0; i < batch->nr_ops; i++) {
888 s16 status = batch->ops[i].status;
889 s16 old_status;
890
891 if (status == GNTST_okay)
892 continue;
893
894 if (__get_user(old_status, batch->status[i]))
895 return -EFAULT;
896
897 if (old_status != GNTST_okay)
898 continue;
899
900 if (__put_user(status, batch->status[i]))
901 return -EFAULT;
902 }
903
904 batch->nr_ops = 0;
905 return 0;
906}
907
908static int gntdev_grant_copy_seg(struct gntdev_copy_batch *batch,
909 struct gntdev_grant_copy_segment *seg,
910 s16 __user *status)
911{
912 uint16_t copied = 0;
913
914 /*
915 * Disallow local -> local copies since there is only space in
916 * batch->pages for one page per-op and this would be a very
917 * expensive memcpy().
918 */
919 if (!(seg->flags & (GNTCOPY_source_gref | GNTCOPY_dest_gref)))
920 return -EINVAL;
921
922 /* Can't cross page if source/dest is a grant ref. */
923 if (seg->flags & GNTCOPY_source_gref) {
924 if (seg->source.foreign.offset + seg->len > XEN_PAGE_SIZE)
925 return -EINVAL;
926 }
927 if (seg->flags & GNTCOPY_dest_gref) {
928 if (seg->dest.foreign.offset + seg->len > XEN_PAGE_SIZE)
929 return -EINVAL;
930 }
931
932 if (put_user(GNTST_okay, status))
933 return -EFAULT;
934
935 while (copied < seg->len) {
936 struct gnttab_copy *op;
937 void __user *virt;
938 size_t len, off;
939 unsigned long gfn;
940 int ret;
941
942 if (batch->nr_ops >= GNTDEV_COPY_BATCH) {
943 ret = gntdev_copy(batch);
944 if (ret < 0)
945 return ret;
946 }
947
948 len = seg->len - copied;
949
950 op = &batch->ops[batch->nr_ops];
951 op->flags = 0;
952
953 if (seg->flags & GNTCOPY_source_gref) {
954 op->source.u.ref = seg->source.foreign.ref;
955 op->source.domid = seg->source.foreign.domid;
956 op->source.offset = seg->source.foreign.offset + copied;
957 op->flags |= GNTCOPY_source_gref;
958 } else {
959 virt = seg->source.virt + copied;
960 off = (unsigned long)virt & ~XEN_PAGE_MASK;
961 len = min(len, (size_t)XEN_PAGE_SIZE - off);
962
963 ret = gntdev_get_page(batch, virt, false, &gfn);
964 if (ret < 0)
965 return ret;
966
967 op->source.u.gmfn = gfn;
968 op->source.domid = DOMID_SELF;
969 op->source.offset = off;
970 }
971
972 if (seg->flags & GNTCOPY_dest_gref) {
973 op->dest.u.ref = seg->dest.foreign.ref;
974 op->dest.domid = seg->dest.foreign.domid;
975 op->dest.offset = seg->dest.foreign.offset + copied;
976 op->flags |= GNTCOPY_dest_gref;
977 } else {
978 virt = seg->dest.virt + copied;
979 off = (unsigned long)virt & ~XEN_PAGE_MASK;
980 len = min(len, (size_t)XEN_PAGE_SIZE - off);
981
982 ret = gntdev_get_page(batch, virt, true, &gfn);
983 if (ret < 0)
984 return ret;
985
986 op->dest.u.gmfn = gfn;
987 op->dest.domid = DOMID_SELF;
988 op->dest.offset = off;
989 }
990
991 op->len = len;
992 copied += len;
993
994 batch->status[batch->nr_ops] = status;
995 batch->nr_ops++;
996 }
997
998 return 0;
999}
1000
1001static long gntdev_ioctl_grant_copy(struct gntdev_priv *priv, void __user *u)
1002{
1003 struct ioctl_gntdev_grant_copy copy;
1004 struct gntdev_copy_batch batch;
1005 unsigned int i;
1006 int ret = 0;
1007
1008 if (copy_from_user(&copy, u, sizeof(copy)))
1009 return -EFAULT;
1010
1011 batch.nr_ops = 0;
1012 batch.nr_pages = 0;
1013
1014 for (i = 0; i < copy.count; i++) {
1015 struct gntdev_grant_copy_segment seg;
1016
1017 if (copy_from_user(&seg, &copy.segments[i], sizeof(seg))) {
1018 ret = -EFAULT;
1019 goto out;
1020 }
1021
1022 ret = gntdev_grant_copy_seg(&batch, &seg, &copy.segments[i].status);
1023 if (ret < 0)
1024 goto out;
1025
1026 cond_resched();
1027 }
1028 if (batch.nr_ops)
1029 ret = gntdev_copy(&batch);
1030 return ret;
1031
1032 out:
1033 gntdev_put_pages(&batch);
1034 return ret;
1035}
1036
ab31523c
GH
1037static long gntdev_ioctl(struct file *flip,
1038 unsigned int cmd, unsigned long arg)
1039{
1040 struct gntdev_priv *priv = flip->private_data;
1041 void __user *ptr = (void __user *)arg;
1042
1043 switch (cmd) {
1044 case IOCTL_GNTDEV_MAP_GRANT_REF:
1045 return gntdev_ioctl_map_grant_ref(priv, ptr);
1046
1047 case IOCTL_GNTDEV_UNMAP_GRANT_REF:
1048 return gntdev_ioctl_unmap_grant_ref(priv, ptr);
1049
1050 case IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR:
1051 return gntdev_ioctl_get_offset_for_vaddr(priv, ptr);
1052
bdc612dc
DDG
1053 case IOCTL_GNTDEV_SET_UNMAP_NOTIFY:
1054 return gntdev_ioctl_notify(priv, ptr);
1055
a4cdb556
DV
1056 case IOCTL_GNTDEV_GRANT_COPY:
1057 return gntdev_ioctl_grant_copy(priv, ptr);
1058
932d6562
OA
1059#ifdef CONFIG_XEN_GNTDEV_DMABUF
1060 case IOCTL_GNTDEV_DMABUF_EXP_FROM_REFS:
1061 return gntdev_ioctl_dmabuf_exp_from_refs(priv, use_ptemod, ptr);
1062
1063 case IOCTL_GNTDEV_DMABUF_EXP_WAIT_RELEASED:
1064 return gntdev_ioctl_dmabuf_exp_wait_released(priv, ptr);
1065
1066 case IOCTL_GNTDEV_DMABUF_IMP_TO_REFS:
1067 return gntdev_ioctl_dmabuf_imp_to_refs(priv, ptr);
1068
1069 case IOCTL_GNTDEV_DMABUF_IMP_RELEASE:
1070 return gntdev_ioctl_dmabuf_imp_release(priv, ptr);
1071#endif
1072
ab31523c
GH
1073 default:
1074 pr_debug("priv %p, unknown cmd %x\n", priv, cmd);
1075 return -ENOIOCTLCMD;
1076 }
1077
1078 return 0;
1079}
1080
1081static int gntdev_mmap(struct file *flip, struct vm_area_struct *vma)
1082{
1083 struct gntdev_priv *priv = flip->private_data;
1084 int index = vma->vm_pgoff;
c7ebf9d9 1085 int count = vma_pages(vma);
1d314567 1086 struct gntdev_grant_map *map;
aab8f11a 1087 int i, err = -EINVAL;
ab31523c
GH
1088
1089 if ((vma->vm_flags & VM_WRITE) && !(vma->vm_flags & VM_SHARED))
1090 return -EINVAL;
1091
1092 pr_debug("map %d+%d at %lx (pgoff %lx)\n",
1093 index, count, vma->vm_start, vma->vm_pgoff);
1094
1401c00e 1095 mutex_lock(&priv->lock);
ab31523c
GH
1096 map = gntdev_find_map_index(priv, index, count);
1097 if (!map)
1098 goto unlock_out;
aab8f11a 1099 if (use_ptemod && map->vma)
ab31523c 1100 goto unlock_out;
aab8f11a 1101 if (use_ptemod && priv->mm != vma->vm_mm) {
283c0972 1102 pr_warn("Huh? Other mm?\n");
ab31523c
GH
1103 goto unlock_out;
1104 }
1105
c5f7c5a9 1106 refcount_inc(&map->users);
68b025c8 1107
ab31523c
GH
1108 vma->vm_ops = &gntdev_vmops;
1109
30faaafd 1110 vma->vm_flags |= VM_DONTEXPAND | VM_DONTDUMP | VM_MIXEDMAP;
d79647ae
DDG
1111
1112 if (use_ptemod)
e8e937be 1113 vma->vm_flags |= VM_DONTCOPY;
ab31523c
GH
1114
1115 vma->vm_private_data = map;
ab31523c 1116
aab8f11a
DDG
1117 if (use_ptemod)
1118 map->vma = vma;
1119
12996fc3
DDG
1120 if (map->flags) {
1121 if ((vma->vm_flags & VM_WRITE) &&
1122 (map->flags & GNTMAP_readonly))
a93e20a8 1123 goto out_unlock_put;
12996fc3
DDG
1124 } else {
1125 map->flags = GNTMAP_host_map;
1126 if (!(vma->vm_flags & VM_WRITE))
1127 map->flags |= GNTMAP_readonly;
1128 }
ab31523c 1129
1401c00e 1130 mutex_unlock(&priv->lock);
f0a70c88 1131
aab8f11a 1132 if (use_ptemod) {
298d275d 1133 map->pages_vm_start = vma->vm_start;
aab8f11a
DDG
1134 err = apply_to_page_range(vma->vm_mm, vma->vm_start,
1135 vma->vm_end - vma->vm_start,
1136 find_grant_ptes, map);
1137 if (err) {
283c0972 1138 pr_warn("find_grant_ptes() failure.\n");
90b6f305 1139 goto out_put_map;
aab8f11a 1140 }
ab31523c
GH
1141 }
1142
1d314567 1143 err = gntdev_map_grant_pages(map);
90b6f305
DDG
1144 if (err)
1145 goto out_put_map;
f0a70c88 1146
aab8f11a
DDG
1147 if (!use_ptemod) {
1148 for (i = 0; i < count; i++) {
1149 err = vm_insert_page(vma, vma->vm_start + i*PAGE_SIZE,
1150 map->pages[i]);
1151 if (err)
90b6f305 1152 goto out_put_map;
aab8f11a 1153 }
923b2919
DV
1154 } else {
1155#ifdef CONFIG_X86
1156 /*
1157 * If the PTEs were not made special by the grant map
1158 * hypercall, do so here.
1159 *
1160 * This is racy since the mapping is already visible
1161 * to userspace but userspace should be well-behaved
1162 * enough to not touch it until the mmap() call
1163 * returns.
1164 */
1165 if (!xen_feature(XENFEAT_gnttab_map_avail_bits)) {
1166 apply_to_page_range(vma->vm_mm, vma->vm_start,
1167 vma->vm_end - vma->vm_start,
1168 set_grant_ptes_as_special, NULL);
1169 }
1170#endif
aab8f11a
DDG
1171 }
1172
f0a70c88
DDG
1173 return 0;
1174
ab31523c 1175unlock_out:
1401c00e 1176 mutex_unlock(&priv->lock);
ab31523c 1177 return err;
90b6f305 1178
a93e20a8 1179out_unlock_put:
1401c00e 1180 mutex_unlock(&priv->lock);
90b6f305 1181out_put_map:
cf2acf66 1182 if (use_ptemod) {
84e4075d 1183 map->vma = NULL;
cf2acf66
RL
1184 unmap_grant_pages(map, 0, map->count);
1185 }
16a1d022 1186 gntdev_put_map(priv, map);
90b6f305 1187 return err;
ab31523c
GH
1188}
1189
1190static const struct file_operations gntdev_fops = {
1191 .owner = THIS_MODULE,
1192 .open = gntdev_open,
1193 .release = gntdev_release,
1194 .mmap = gntdev_mmap,
1195 .unlocked_ioctl = gntdev_ioctl
1196};
1197
1198static struct miscdevice gntdev_miscdev = {
1199 .minor = MISC_DYNAMIC_MINOR,
1200 .name = "xen/gntdev",
1201 .fops = &gntdev_fops,
1202};
1203
1204/* ------------------------------------------------------------------ */
1205
1206static int __init gntdev_init(void)
1207{
1208 int err;
1209
1210 if (!xen_domain())
1211 return -ENODEV;
1212
6926f6d6 1213 use_ptemod = !xen_feature(XENFEAT_auto_translated_physmap);
aab8f11a 1214
ab31523c
GH
1215 err = misc_register(&gntdev_miscdev);
1216 if (err != 0) {
283c0972 1217 pr_err("Could not register gntdev device\n");
ab31523c
GH
1218 return err;
1219 }
1220 return 0;
1221}
1222
1223static void __exit gntdev_exit(void)
1224{
1225 misc_deregister(&gntdev_miscdev);
1226}
1227
1228module_init(gntdev_init);
1229module_exit(gntdev_exit);
1230
1231/* ------------------------------------------------------------------ */