LinuxLists.cc - [PATCH 1/7] General notification queue with user mmap()'able ring buffer

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Tue, May 28, 2019 at 05:01:55PM +0100, David Howells wrote:
> Implement a misc device that implements a general notification queue as a
> ring buffer that can be mmap()'d from userspace.

"general" but just for filesystems, right? :(

> Each entry has a 1-slot header that describes it:
>
> struct watch_notification {
> __u32 type:24;
> __u32 subtype:8;
> __u32 info;
> };

This doesn't match the structure definition in the documentation, so
something is out of sync.

> The type indicates the source (eg. mount tree changes, superblock events,
> keyring changes, block layer events) and the subtype indicates the event
> type (eg. mount, unmount; EIO, EDQUOT; link, unlink). The info field
> indicates a number of things, including the entry length, an ID assigned to
> a watchpoint contributing to this buffer, type-specific flags and meta
> flags, such as an overrun indicator.
>
> Supplementary data, such as the key ID that generated an event, are
> attached in additional slots.

I'm all for a "generic" event system for the kernel (heck, Solaris has
had one for decades), but it keeps getting shot down every time it comes
up. What is different about this one?

> --- a/drivers/misc/Kconfig
> +++ b/drivers/misc/Kconfig
> @@ -4,6 +4,19 @@
>
> menu "Misc devices"
>
> +config WATCH_QUEUE
> + bool "Mappable notification queue"
> + default n

Nit, not needed.

> + depends on MMU
> + help
> + This is a general notification queue for the kernel to pass events to
> + userspace through a mmap()'able ring buffer. It can be used in
> + conjunction with watches for mount topology change notifications,
> + superblock change notifications and key/keyring change notifications.
> +
> + Note that in theory this should work fine with NOMMU, but I'm not
> + sure how to make that work.
> +
> config SENSORS_LIS3LV02D
> tristate
> depends on INPUT
> diff --git a/drivers/misc/Makefile b/drivers/misc/Makefile
> index b9affcdaa3d6..bf16acd9f8cc 100644
> --- a/drivers/misc/Makefile
> +++ b/drivers/misc/Makefile
> @@ -3,6 +3,7 @@
> # Makefile for misc devices that really don't fit anywhere else.
> #
>
> +obj-$(CONFIG_WATCH_QUEUE) += watch_queue.o
> obj-$(CONFIG_IBM_ASM) += ibmasm/
> obj-$(CONFIG_IBMVMC) += ibmvmc.o
> obj-$(CONFIG_AD525X_DPOT) += ad525x_dpot.o
> diff --git a/drivers/misc/watch_queue.c b/drivers/misc/watch_queue.c
> new file mode 100644
> index 000000000000..39a09ea15d97
> --- /dev/null
> +++ b/drivers/misc/watch_queue.c
> @@ -0,0 +1,877 @@
> +/* User-mappable watch queue
> + *
> + * Copyright (C) 2018 Red Hat, Inc. All Rights Reserved.

You didn't touch the code this year?

> + * Written by David Howells ([email protected])
> + *
> + * This program is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU General Public Licence
> + * as published by the Free Software Foundation; either version
> + * 2 of the Licence, or (at your option) any later version.

Please drop the boiler plate text and use a SPDX tag, checkpatch should
have caught this. I don't want to have to go and change it again.

> + *
> + * See Documentation/watch_queue.rst
> + */
> +
> +#define pr_fmt(fmt) "watchq: " fmt
> +#include <linux/module.h>
> +#include <linux/init.h>
> +#include <linux/sched.h>
> +#include <linux/slab.h>
> +#include <linux/printk.h>
> +#include <linux/miscdevice.h>
> +#include <linux/fs.h>
> +#include <linux/mm.h>
> +#include <linux/pagemap.h>
> +#include <linux/poll.h>
> +#include <linux/uaccess.h>
> +#include <linux/vmalloc.h>
> +#include <linux/file.h>
> +#include <linux/security.h>
> +#include <linux/cred.h>
> +#include <linux/watch_queue.h>
> +
> +#define DEBUG_WITH_WRITE /* Allow use of write() to record notifications */

debugging code left in?

> +
> +MODULE_DESCRIPTION("Watch queue");
> +MODULE_AUTHOR("Red Hat, Inc.");
> +MODULE_LICENSE("GPL");
> +
> +struct watch_type_filter {
> + enum watch_notification_type type;
> + __u32 subtype_filter[1]; /* Bitmask of subtypes to filter on */
> + __u32 info_filter; /* Filter on watch_notification::info */
> + __u32 info_mask; /* Mask of relevant bits in info_filter */
> +};
> +
> +struct watch_filter {
> + union {
> + struct rcu_head rcu;
> + unsigned long type_filter[2]; /* Bitmask of accepted types */
> + };
> + u32 nr_filters; /* Number of filters */
> + struct watch_type_filter filters[];
> +};
> +
> +struct watch_queue {
> + struct rcu_head rcu;
> + struct address_space mapping;
> + const struct cred *cred; /* Creds of the owner of the queue */
> + struct watch_filter __rcu *filter;
> + wait_queue_head_t waiters;
> + struct hlist_head watches; /* Contributory watches */
> + refcount_t usage;

Usage of what, this structure? Or something else?

> + spinlock_t lock;
> + bool defunct; /* T when queues closed */
> + u8 nr_pages; /* Size of pages[] */
> + u8 flag_next; /* Flag to apply to next item */
> +#ifdef DEBUG_WITH_WRITE
> + u8 debug;
> +#endif
> + u32 size;
> + struct watch_queue_buffer *buffer; /* Pointer to first record */
> +
> + /* The mappable pages. The zeroth page holds the ring pointers. */
> + struct page **pages;
> +};

> +EXPORT_SYMBOL(__post_watch_notification);

_GPL for new apis? (I have to ask...)

> +static long watch_queue_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
> +{
> + struct watch_queue *wqueue = file->private_data;
> + struct inode *inode = file_inode(file);
> + long ret;
> +
> + switch (cmd) {
> + case IOC_WATCH_QUEUE_SET_SIZE:
> + if (wqueue->buffer)
> + return -EBUSY;
> + inode_lock(inode);
> + ret = watch_queue_set_size(wqueue, arg);
> + inode_unlock(inode);
> + return ret;
> +
> + case IOC_WATCH_QUEUE_SET_FILTER:
> + inode_lock(inode);
> + ret = watch_queue_set_filter(
> + inode, wqueue,
> + (struct watch_notification_filter __user *)arg);
> + inode_unlock(inode);
> + return ret;
> +
> + default:
> + return -EOPNOTSUPP;

-ENOTTY is the correct "not a valid ioctl" error value, right?

> + }
> +}

> +/**
> + * put_watch_queue - Dispose of a ref on a watchqueue.
> + * @wqueue: The watch queue to unref.
> + */
> +void put_watch_queue(struct watch_queue *wqueue)
> +{
> + if (refcount_dec_and_test(&wqueue->usage))
> + kfree_rcu(wqueue, rcu);

Why not just use a kref?

> +}
> +EXPORT_SYMBOL(put_watch_queue);

> +int add_watch_to_object(struct watch *watch, struct watch_list *wlist)
> +{
> + struct watch_queue *wqueue = rcu_access_pointer(watch->queue);
> + struct watch *w;
> +
> + hlist_for_each_entry(w, &wlist->watchers, list_node) {
> + if (watch->id == w->id)
> + return -EBUSY;
> + }
> +
> + rcu_assign_pointer(watch->watch_list, wlist);
> +
> + spin_lock_bh(&wqueue->lock);
> + refcount_inc(&wqueue->usage);
> + hlist_add_head(&watch->queue_node, &wqueue->watches);
> + spin_unlock_bh(&wqueue->lock);
> +
> + hlist_add_head(&watch->list_node, &wlist->watchers);
> + return 0;
> +}
> +EXPORT_SYMBOL(add_watch_to_object);

Naming nit, shouldn't the "prefix" all be the same for these new
functions?

watch_queue_add_object()? watch_queue_put()? And so on?

> +static int __init watch_queue_init(void)
> +{
> + int ret;
> +
> + ret = misc_register(&watch_queue_dev);
> + if (ret < 0)
> + pr_err("Failed to register %d\n", ret);
> + return ret;
> +}
> +fs_initcall(watch_queue_init);
> +
> +static void __exit watch_queue_exit(void)
> +{
> + misc_deregister(&watch_queue_dev);
> +}
> +module_exit(watch_queue_exit);

module_misc_device()?

> --- /dev/null
> +++ b/include/linux/watch_queue.h
> @@ -0,0 +1,86 @@
> +/* User-mappable watch queue
> + *
> + * Copyright (C) 2018 Red Hat, Inc. All Rights Reserved.
> + * Written by David Howells ([email protected])
> + *
> + * This program is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU General Public Licence
> + * as published by the Free Software Foundation; either version
> + * 2 of the Licence, or (at your option) any later version.

Again, SPDX headers please.

> --- /dev/null
> +++ b/include/uapi/linux/watch_queue.h
> @@ -0,0 +1,82 @@
> +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */

Yeah!!!

No copyright? :(

> +#ifndef _UAPI_LINUX_WATCH_QUEUE_H
> +#define _UAPI_LINUX_WATCH_QUEUE_H
> +
> +#include <linux/types.h>
> +#include <linux/ioctl.h>
> +
> +#define IOC_WATCH_QUEUE_SET_SIZE _IO('s', 0x01) /* Set the size in pages */
> +#define IOC_WATCH_QUEUE_SET_FILTER _IO('s', 0x02) /* Set the filter */
> +
> +enum watch_notification_type {
> + WATCH_TYPE_META = 0, /* Special record */
> + WATCH_TYPE_MOUNT_NOTIFY = 1, /* Mount notification record */
> + WATCH_TYPE_SB_NOTIFY = 2, /* Superblock notification */
> + WATCH_TYPE_KEY_NOTIFY = 3, /* Key/keyring change notification */
> + WATCH_TYPE_BLOCK_NOTIFY = 4, /* Block layer notifications */
> +#define WATCH_TYPE___NR 5
> +};
> +
> +enum watch_meta_notification_subtype {
> + WATCH_META_SKIP_NOTIFICATION = 0, /* Just skip this record */
> + WATCH_META_REMOVAL_NOTIFICATION = 1, /* Watched object was removed */
> +};
> +
> +/*
> + * Notification record
> + */
> +struct watch_notification {
> + __u32 type:24; /* enum watch_notification_type */
> + __u32 subtype:8; /* Type-specific subtype (filterable) */
> + __u32 info;
> +#define WATCH_INFO_OVERRUN 0x00000001 /* Event(s) lost due to overrun */
> +#define WATCH_INFO_ENOMEM 0x00000002 /* Event(s) lost due to ENOMEM */
> +#define WATCH_INFO_RECURSIVE 0x00000004 /* Change was recursive */
> +#define WATCH_INFO_LENGTH 0x000001f8 /* Length of record / sizeof(watch_notification) */
> +#define WATCH_INFO_IN_SUBTREE 0x00000200 /* Change was not at watched root */
> +#define WATCH_INFO_TYPE_FLAGS 0x00ff0000 /* Type-specific flags */
> +#define WATCH_INFO_FLAG_0 0x00010000
> +#define WATCH_INFO_FLAG_1 0x00020000
> +#define WATCH_INFO_FLAG_2 0x00040000
> +#define WATCH_INFO_FLAG_3 0x00080000
> +#define WATCH_INFO_FLAG_4 0x00100000
> +#define WATCH_INFO_FLAG_5 0x00200000
> +#define WATCH_INFO_FLAG_6 0x00400000
> +#define WATCH_INFO_FLAG_7 0x00800000
> +#define WATCH_INFO_ID 0xff000000 /* ID of watchpoint */
> +};
> +
> +#define WATCH_LENGTH_SHIFT 3
> +
> +struct watch_queue_buffer {
> + union {
> + /* The first few entries are special, containing the
> + * ring management variables.
> + */
> + struct {
> + struct watch_notification watch; /* WATCH_TYPE_SKIP */
> + volatile __u32 head; /* Ring head index */
> + volatile __u32 tail; /* Ring tail index */

A uapi structure that has volatile in it? Are you _SURE_ this is
correct?

That feels wrong to me... This is not a backing-hardware register, it's
"just memory" and slapping volatile on it shouldn't be the correct
solution for telling the compiler to not to optimize away reads/flushes,
right? You need a proper memory access type primitive for that to work
correctly everywhere I thought.

We only have 2 users of volatile in include/uapi, one for WMI structures
that are backed by firmware (seems correct), and one for DRM which I
have no idea how it works as it claims to be a lock. Why is this new
addition the correct way to do this that no other ring-buffer that was
mmapped has needed to?

thanks,

greg k-h

2019-05-28 17:37:38

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Greg KH <[email protected]> wrote:

> > Implement a misc device that implements a general notification queue as a
> > ring buffer that can be mmap()'d from userspace.
>
> "general" but just for filesystems, right? :(

Whatever gave you that idea? You can watch keyrings events, for example -
they're not exactly filesystems. I've added the ability to watch for mount
topology changes and superblock events because those are something I've been
asked to do. I've added something for block events because I've recently had
a problem with trying to recover data from a dodgy disk in that every time the
disk goes offline, the ddrecover goes "wheeeee!" as it just sees a lot of
EIO/ENODATA at a great rate of knots because it doesn't know the driver is now
ignoring the disk.

I don't know what else people might want to watch, but I've tried to make it
as generic as possible so as not to exclude it if possible.

> This doesn't match the structure definition in the documentation, so
> something is out of sync.

Ah, yes - I need to update that doc, thanks.

> I'm all for a "generic" event system for the kernel (heck, Solaris has
> had one for decades), but it keeps getting shot down every time it comes
> up. What is different about this one?

Without studying all the other ones, I can't say - however, I need to add
something for keyrings and I would prefer to make something generic.

> > +#define DEBUG_WITH_WRITE /* Allow use of write() to record notifications */
>
> debugging code left in?

I'll switch it to #undef. I want to leave the code in there for testing
purposes. Possibly I should make it a Kconfig option.

> > + refcount_t usage;
>
> Usage of what, this structure? Or something else?

This is the number of usages of this struct (references to if you prefer). I
can add a comment to this effect.

> > +EXPORT_SYMBOL(__post_watch_notification);
>
> _GPL for new apis? (I have to ask...)

No.

> > + return -EOPNOTSUPP;
>
> -ENOTTY is the correct "not a valid ioctl" error value, right?

fs/ioctl.c does both, but I can switch it if it makes you happier.

> > +void put_watch_queue(struct watch_queue *wqueue)
> > +{
> > + if (refcount_dec_and_test(&wqueue->usage))
> > + kfree_rcu(wqueue, rcu);
>
> Why not just use a kref?

Why use a kref? It seems like an effort to be a C++ base class, but without
the C++ inheritance bit. Using kref doesn't seem to gain anything. It's just
a wrapper around refcount_t - so why not just use a refcount_t?

kref_put() could potentially add an unnecessary extra stack frame and would
seem to be best avoided, though an optimising compiler ought to be able to
inline if it can.

Are you now on the convert all refcounts to krefs path?

> > +EXPORT_SYMBOL(add_watch_to_object);
>
> Naming nit, shouldn't the "prefix" all be the same for these new
> functions?
>
> watch_queue_add_object()? watch_queue_put()? And so on?

Naming is fun. watch_queue_add_object - that suggests something different to
what the function actually does. I'll think about adjusting the names.

> > +module_exit(watch_queue_exit);
>
> module_misc_device()?

warthog>git grep module_misc_device -- Documentation/
warthog1>

> > +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
>
> Yeah!!!

Blech.

> > + struct {
> > + struct watch_notification watch; /* WATCH_TYPE_SKIP */
> > + volatile __u32 head; /* Ring head index */
> > + volatile __u32 tail; /* Ring tail index */
>
> A uapi structure that has volatile in it? Are you _SURE_ this is
> correct?
>
> That feels wrong to me... This is not a backing-hardware register, it's
> "just memory" and slapping volatile on it shouldn't be the correct
> solution for telling the compiler to not to optimize away reads/flushes,
> right? You need a proper memory access type primitive for that to work
> correctly everywhere I thought.
>
> We only have 2 users of volatile in include/uapi, one for WMI structures
> that are backed by firmware (seems correct), and one for DRM which I
> have no idea how it works as it claims to be a lock. Why is this new
> addition the correct way to do this that no other ring-buffer that was
> mmapped has needed to?

Yeah, I understand your concern with this.

The reason I put the volatiles in is that the kernel may be modifying the head
pointer on one CPU simultaneously with userspace modifying the tail pointer on
another CPU.

Note that userspace does not need to enter the kernel to find out if there's
anything in the buffer or to read stuff out of the buffer. Userspace only
needs to enter the kernel, using poll() or similar, to wait for something to
appear in the buffer.

David

2019-05-28 19:43:58

by Jann Horn

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Tue, May 28, 2019 at 6:03 PM David Howells <[email protected]> wrote:
> Implement a misc device that implements a general notification queue as a
> ring buffer that can be mmap()'d from userspace.
[...]
> +receive notifications from the kernel. This is can be used in conjunction

typo: s/is can/can/

[...]
> +Overview
> +========
> +
> +This facility appears as a misc device file that is opened and then mapped and
> +polled. Each time it is opened, it creates a new buffer specific to the
> +returned file descriptor. Then, when the opening process sets watches, it
> +indicates that particular buffer it wants notifications from that watch to be
> +written into. Note that there are no read() and write() methods (except for

s/that particular buffer/the particular buffer/

> +debugging). The user is expected to access the ring directly and to use poll
> +to wait for new data.
[...]
> +/**
> + * __post_watch_notification - Post an event notification
> + * @wlist: The watch list to post the event to.
> + * @n: The notification record to post.
> + * @cred: The creds of the process that triggered the notification.
> + * @id: The ID to match on the watch.
> + *
> + * Post a notification of an event into a set of watch queues and let the users
> + * know.
> + *
> + * If @n is NULL then WATCH_INFO_LENGTH will be set on the next event posted.
> + *
> + * The size of the notification should be set in n->info & WATCH_INFO_LENGTH and
> + * should be in units of sizeof(*n).
> + */
> +void __post_watch_notification(struct watch_list *wlist,
> + struct watch_notification *n,
> + const struct cred *cred,
> + u64 id)
> +{
> + const struct watch_filter *wf;
> + struct watch_queue *wqueue;
> + struct watch *watch;
> +
> + rcu_read_lock();
> +
> + hlist_for_each_entry_rcu(watch, &wlist->watchers, list_node) {
> + if (watch->id != id)
> + continue;
> + n->info &= ~(WATCH_INFO_ID | WATCH_INFO_OVERRUN);
> + n->info |= watch->info_id;
> +
> + wqueue = rcu_dereference(watch->queue);
> + wf = rcu_dereference(wqueue->filter);
> + if (wf && !filter_watch_notification(wf, n))
> + continue;
> +
> + post_one_notification(wqueue, n, cred);
> + }
> +
> + rcu_read_unlock();
> +}
> +EXPORT_SYMBOL(__post_watch_notification);
[...]
> +static vm_fault_t watch_queue_fault(struct vm_fault *vmf)
> +{
> + struct watch_queue *wqueue = vmf->vma->vm_file->private_data;
> + struct page *page;
> +
> + page = wqueue->pages[vmf->pgoff];

I don't see you setting any special properties on the VMA that would
prevent userspace from extending its size via mremap() - no
VM_DONTEXPAND or VM_PFNMAP. So I think you might get an out-of-bounds
access here?

> + get_page(page);
> + if (!lock_page_or_retry(page, vmf->vma->vm_mm, vmf->flags)) {
> + put_page(page);
> + return VM_FAULT_RETRY;
> + }
> + vmf->page = page;
> + return VM_FAULT_LOCKED;
> +}
> +
> +static void watch_queue_map_pages(struct vm_fault *vmf,
> + pgoff_t start_pgoff, pgoff_t end_pgoff)
> +{
> + struct watch_queue *wqueue = vmf->vma->vm_file->private_data;
> + struct page *page;
> +
> + rcu_read_lock();
> +
> + do {
> + page = wqueue->pages[start_pgoff];

Same as above.

> + if (trylock_page(page)) {
> + vm_fault_t ret;
> + get_page(page);
> + ret = alloc_set_pte(vmf, NULL, page);
> + if (ret != 0)
> + put_page(page);
> +
> + unlock_page(page);
> + }
> + } while (++start_pgoff < end_pgoff);
> +
> + rcu_read_unlock();
> +}
[...]
> +static int watch_queue_mmap(struct file *file, struct vm_area_struct *vma)
> +{
> + struct watch_queue *wqueue = file->private_data;
> +
> + if (vma->vm_pgoff != 0 ||
> + vma->vm_end - vma->vm_start > wqueue->nr_pages * PAGE_SIZE ||
> + !(pgprot_val(vma->vm_page_prot) & pgprot_val(PAGE_SHARED)))
> + return -EINVAL;

This thing should probably have locking against concurrent
watch_queue_set_size()?

> + vma->vm_ops = &watch_queue_vm_ops;
> +
> + vma_interval_tree_insert(vma, &wqueue->mapping.i_mmap);
> + return 0;
> +}
> +
> +/*
> + * Allocate the required number of pages.
> + */
> +static long watch_queue_set_size(struct watch_queue *wqueue, unsigned long nr_pages)
> +{
> + struct watch_queue_buffer *buf;
> + u32 len;
> + int i;
> +
> + if (nr_pages == 0 ||
> + nr_pages > 16 || /* TODO: choose a better hard limit */
> + !is_power_of_2(nr_pages))
> + return -EINVAL;
> +
> + wqueue->pages = kcalloc(nr_pages, sizeof(struct page *), GFP_KERNEL);
> + if (!wqueue->pages)
> + goto err;
> +
> + for (i = 0; i < nr_pages; i++) {
> + wqueue->pages[i] = alloc_page(GFP_KERNEL | __GFP_ZERO);
> + if (!wqueue->pages[i])
> + goto err_some_pages;
> + wqueue->pages[i]->mapping = &wqueue->mapping;
> + SetPageUptodate(wqueue->pages[i]);
> + }
> +
> + buf = vmap(wqueue->pages, nr_pages, VM_MAP, PAGE_SHARED);
> + if (!buf)
> + goto err_some_pages;
> +
> + wqueue->buffer = buf;
> + wqueue->nr_pages = nr_pages;
> + wqueue->size = ((nr_pages * PAGE_SIZE) / sizeof(struct watch_notification));
> +
> + /* The first four slots in the buffer contain metadata about the ring,
> + * including the head and tail indices and mask.
> + */
> + len = sizeof(buf->meta) / sizeof(buf->slots[0]);
> + buf->meta.watch.info = len << WATCH_LENGTH_SHIFT;
> + buf->meta.watch.type = WATCH_TYPE_META;
> + buf->meta.watch.subtype = WATCH_META_SKIP_NOTIFICATION;
> + buf->meta.tail = len;
> + buf->meta.mask = wqueue->size - 1;
> + smp_store_release(&buf->meta.head, len);

Why is this an smp_store_release()? The entire buffer should not be visible to
userspace before this setup is complete, right?

> + return 0;
> +
> +err_some_pages:
> + for (i--; i >= 0; i--) {
> + ClearPageUptodate(wqueue->pages[i]);
> + wqueue->pages[i]->mapping = NULL;
> + put_page(wqueue->pages[i]);
> + }
> +
> + kfree(wqueue->pages);
> + wqueue->pages = NULL;
> +err:
> + return -ENOMEM;
> +}
[...]
> +
> +/*
> + * Set parameters.
> + */
> +static long watch_queue_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
> +{
> + struct watch_queue *wqueue = file->private_data;
> + struct inode *inode = file_inode(file);
> + long ret;
> +
> + switch (cmd) {
> + case IOC_WATCH_QUEUE_SET_SIZE:
> + if (wqueue->buffer)
> + return -EBUSY;

The preceding check occurs without any locks held and therefore has no
reliable effect. It should probably be moved below the
inode_lock(...).

> + inode_lock(inode);
> + ret = watch_queue_set_size(wqueue, arg);
> + inode_unlock(inode);
> + return ret;
> +
> + case IOC_WATCH_QUEUE_SET_FILTER:
> + inode_lock(inode);
> + ret = watch_queue_set_filter(
> + inode, wqueue,
> + (struct watch_notification_filter __user *)arg);
> + inode_unlock(inode);
> + return ret;
> +
> + default:
> + return -EOPNOTSUPP;
> + }
> +}
[...]
> +static void free_watch(struct rcu_head *rcu)
> +{
> + struct watch *watch = container_of(rcu, struct watch, rcu);
> +
> + put_watch_queue(rcu_access_pointer(watch->queue));

This should be rcu_dereference_protected(..., 1).

> +/**
> + * remove_watch_from_object - Remove a watch or all watches from an object.
> + * @wlist: The watch list to remove from
> + * @wq: The watch queue of interest (ignored if @all is true)
> + * @id: The ID of the watch to remove (ignored if @all is true)
> + * @all: True to remove all objects
> + *
> + * Remove a specific watch or all watches from an object. A notification is
> + * sent to the watcher to tell them that this happened.
> + */
> +int remove_watch_from_object(struct watch_list *wlist, struct watch_queue *wq,
> + u64 id, bool all)
> +{
> + struct watch_notification n;
> + struct watch_queue *wqueue;
> + struct watch *watch;
> + int ret = -EBADSLT;
> +
> + rcu_read_lock();
> +
> +again:
> + spin_lock(&wlist->lock);
> + hlist_for_each_entry(watch, &wlist->watchers, list_node) {
> + if (all ||
> + (watch->id == id && rcu_access_pointer(watch->queue) == wq))
> + goto found;
> + }
> + spin_unlock(&wlist->lock);
> + goto out;
> +
> +found:
> + ret = 0;
> + hlist_del_init_rcu(&watch->list_node);
> + rcu_assign_pointer(watch->watch_list, NULL);
> + spin_unlock(&wlist->lock);
> +
> + n.type = WATCH_TYPE_META;
> + n.subtype = WATCH_META_REMOVAL_NOTIFICATION;
> + n.info = watch->info_id | sizeof(n);
> +
> + wqueue = rcu_dereference(watch->queue);
> + post_one_notification(wqueue, &n, wq ? wq->cred : NULL);
> +
> + /* We don't need the watch list lock for the next bit as RCU is
> + * protecting everything from being deallocated.

Does "everything" mean "the wqueue" or more than that?

> + */
> + if (wqueue) {
> + spin_lock_bh(&wqueue->lock);
> +
> + if (!hlist_unhashed(&watch->queue_node)) {
> + hlist_del_init_rcu(&watch->queue_node);
> + put_watch(watch);
> + }
> +
> + spin_unlock_bh(&wqueue->lock);
> + }
> +
> + if (wlist->release_watch) {
> + rcu_read_unlock();
> + wlist->release_watch(wlist, watch);
> + rcu_read_lock();
> + }
> + put_watch(watch);
> +
> + if (all && !hlist_empty(&wlist->watchers))
> + goto again;
> +out:
> + rcu_read_unlock();
> + return ret;
> +}
> +EXPORT_SYMBOL(remove_watch_from_object);
> +
> +/*
> + * Remove all the watches that are contributory to a queue. This will
> + * potentially race with removal of the watches by the destruction of the
> + * objects being watched or the distribution of notifications.
> + */
> +static void watch_queue_clear(struct watch_queue *wqueue)
> +{
> + struct watch_list *wlist;
> + struct watch *watch;
> + bool release;
> +
> + rcu_read_lock();
> + spin_lock_bh(&wqueue->lock);
> +
> + /* Prevent new additions and prevent notifications from happening */
> + wqueue->defunct = true;
> +
> + while (!hlist_empty(&wqueue->watches)) {
> + watch = hlist_entry(wqueue->watches.first, struct watch, queue_node);
> + hlist_del_init_rcu(&watch->queue_node);
> + spin_unlock_bh(&wqueue->lock);
> +
> + /* We can't do the next bit under the queue lock as we need to
> + * get the list lock - which would cause a deadlock if someone
> + * was removing from the opposite direction at the same time or
> + * posting a notification.
> + */
> + wlist = rcu_dereference(watch->watch_list);
> + if (wlist) {
> + spin_lock(&wlist->lock);
> +
> + release = !hlist_unhashed(&watch->list_node);
> + if (release) {
> + hlist_del_init_rcu(&watch->list_node);
> + rcu_assign_pointer(watch->watch_list, NULL);
> + }
> +
> + spin_unlock(&wlist->lock);
> +
> + if (release) {
> + if (wlist->release_watch) {
> + rcu_read_unlock();
> + /* This might need to call dput(), so
> + * we have to drop all the locks.
> + */
> + wlist->release_watch(wlist, watch);

How are you holding a reference to `wlist` here? You got the reference through
rcu_dereference(), you've dropped the RCU read lock, and I don't see anything
that stabilizes the reference.

> + rcu_read_lock();
> + }
> + put_watch(watch);
> + }
> + }
> +
> + put_watch(watch);
> + spin_lock_bh(&wqueue->lock);
> + }
> +
> + spin_unlock_bh(&wqueue->lock);
> + rcu_read_unlock();
> +}
> +
> +/*
> + * Release the file.
> + */
> +static int watch_queue_release(struct inode *inode, struct file *file)
> +{
> + struct watch_filter *wfilter;
> + struct watch_queue *wqueue = file->private_data;
> + int i, pgref;
> +
> + watch_queue_clear(wqueue);
> +
> + if (wqueue->pages && wqueue->pages[0])
> + WARN_ON(page_ref_count(wqueue->pages[0]) != 1);

Is there a reason why there couldn't still be references to the pages
from get_user_pages()/get_user_pages_fast()?

> + if (wqueue->buffer)
> + vfree(wqueue->buffer);
> + for (i = 0; i < wqueue->nr_pages; i++) {
> + ClearPageUptodate(wqueue->pages[i]);
> + wqueue->pages[i]->mapping = NULL;
> + pgref = page_ref_count(wqueue->pages[i]);
> + WARN(pgref != 1,
> + "FREE PAGE[%d] refcount %d\n", i, page_ref_count(wqueue->pages[i]));
> + __free_page(wqueue->pages[i]);
> + }
> +
> + wfilter = rcu_access_pointer(wqueue->filter);

Again, rcu_dereference_protected(..., 1).

> + if (wfilter)
> + kfree_rcu(wfilter, rcu);
> + kfree(wqueue->pages);
> + put_cred(wqueue->cred);
> + put_watch_queue(wqueue);
> + return 0;
> +}
> +
> +#ifdef DEBUG_WITH_WRITE
> +static ssize_t watch_queue_write(struct file *file,
> + const char __user *_buf, size_t len, loff_t *pos)
> +{
> + struct watch_notification *n;
> + struct watch_queue *wqueue = file->private_data;
> + ssize_t ret;
> +
> + if (!wqueue->buffer)
> + return -ENOBUFS;
> +
> + if (len & ~WATCH_INFO_LENGTH || len == 0 || !_buf)
> + return -EINVAL;
> +
> + n = memdup_user(_buf, len);
> + if (IS_ERR(n))
> + return PTR_ERR(n);
> +
> + ret = -EINVAL;
> + if ((n->info & WATCH_INFO_LENGTH) != len)
> + goto error;
> + n->info &= (WATCH_INFO_LENGTH | WATCH_INFO_TYPE_FLAGS | WATCH_INFO_ID);

Should the non-atomic modification of n->info (and perhaps also the
following uses of ->debug) be protected by some lock?

> + if (post_one_notification(wqueue, n, file->f_cred))
> + wqueue->debug = 0;
> + else
> + wqueue->debug++;
> + ret = len;
> + if (wqueue->debug > 20)
> + ret = -EIO;
> +
> +error:
> + kfree(n);
> + return ret;
> +}
> +#endif
[...]
> +#define IOC_WATCH_QUEUE_SET_SIZE _IO('s', 0x01) /* Set the size in pages */
> +#define IOC_WATCH_QUEUE_SET_FILTER _IO('s', 0x02) /* Set the filter */

Should these ioctl numbers be registered in
Documentation/ioctl/ioctl-number.txt?

2019-05-28 22:29:59

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Jann Horn <[email protected]> wrote:

> I don't see you setting any special properties on the VMA that would
> prevent userspace from extending its size via mremap() - no
> VM_DONTEXPAND or VM_PFNMAP. So I think you might get an out-of-bounds
> access here?

Should I just set VM_DONTEXPAND in watch_queue_mmap()? Like so:

vma->vm_flags |= VM_DONTEXPAND;

> > +static void watch_queue_map_pages(struct vm_fault *vmf,
> > + pgoff_t start_pgoff, pgoff_t end_pgoff)
> ...
>
> Same as above.

Same solution as above? Or do I need ot check start/end_pgoff too?

> > +static int watch_queue_mmap(struct file *file, struct vm_area_struct *vma)
> > +{
> > + struct watch_queue *wqueue = file->private_data;
> > +
> > + if (vma->vm_pgoff != 0 ||
> > + vma->vm_end - vma->vm_start > wqueue->nr_pages * PAGE_SIZE ||
> > + !(pgprot_val(vma->vm_page_prot) & pgprot_val(PAGE_SHARED)))
> > + return -EINVAL;
>
> This thing should probably have locking against concurrent
> watch_queue_set_size()?

Yeah.

static int watch_queue_mmap(struct file *file,
struct vm_area_struct *vma)
{
struct watch_queue *wqueue = file->private_data;
struct inode *inode = file_inode(file);
u8 nr_pages;

inode_lock(inode);
nr_pages = wqueue->nr_pages;
inode_unlock(inode);

if (nr_pages == 0 ||
...
return -EINVAL;

> > + smp_store_release(&buf->meta.head, len);
>
> Why is this an smp_store_release()? The entire buffer should not be visible to
> userspace before this setup is complete, right?

Yes - if I put the above locking in the mmap handler. OTOH, it's a one-off
barrier...

> > + if (wqueue->buffer)
> > + return -EBUSY;
>
> The preceding check occurs without any locks held and therefore has no
> reliable effect. It should probably be moved below the
> inode_lock(...).

Yeah, it can race. I'll move it into watch_queue_set_size().

> > +static void free_watch(struct rcu_head *rcu)
> > +{
> > + struct watch *watch = container_of(rcu, struct watch, rcu);
> > +
> > + put_watch_queue(rcu_access_pointer(watch->queue));
>
> This should be rcu_dereference_protected(..., 1).

That shouldn't be necessary. rcu_access_pointer()'s description says:

* It is also permissible to use rcu_access_pointer() when read-side
* access to the pointer was removed at least one grace period ago, as
* is the case in the context of the RCU callback that is freeing up
* the data, ...

It's in an rcu callback function, so accessing the __rcu pointers in the RCU'd
struct should be fine with rcu_access_pointer().

> > + /* We don't need the watch list lock for the next bit as RCU is
> > + * protecting everything from being deallocated.
>
> Does "everything" mean "the wqueue" or more than that?

Actually, just 'wqueue' and its buffer. 'watch' is held by us once we've
dequeued it as we now own the ref 'wlist' had on it. 'wlist' and 'wq' must be
pinned by the caller.

> > + if (release) {
> > + if (wlist->release_watch) {
> > + rcu_read_unlock();
> > + /* This might need to call dput(), so
> > + * we have to drop all the locks.
> > + */
> > + wlist->release_watch(wlist, watch);
>
> How are you holding a reference to `wlist` here? You got the reference through
> rcu_dereference(), you've dropped the RCU read lock, and I don't see anything
> that stabilizes the reference.

The watch record must hold a ref on the watched object if the watch_list has a
->release_watch() method. In the code snippet above, the watch record now
belongs to us because we unlinked it under the wlist->lock some lines prior.

However, you raise a good point, and I think the thing to do is to cache
->release_watch from it and not pass wlist into (*release_watch)(). We don't
need to concern ourselves with cleaning up *wlist as it will be cleaned up
when the target object is removed.

Keyrings don't have a ->release_watch method and neither does the block-layer
notification stuff.

> > + if (wqueue->pages && wqueue->pages[0])
> > + WARN_ON(page_ref_count(wqueue->pages[0]) != 1);
>
> Is there a reason why there couldn't still be references to the pages
> from get_user_pages()/get_user_pages_fast()?

I'm not sure. I'm not sure what to do if there are. What do you suggest?

> > + n->info &= (WATCH_INFO_LENGTH | WATCH_INFO_TYPE_FLAGS | WATCH_INFO_ID);
>
> Should the non-atomic modification of n->info

n's an unpublished copy of some userspace data that's local to the function
instance. There shouldn't be any way to race with it at this point.

> (and perhaps also the
> following uses of ->debug) be protected by some lock?
>
> > + if (post_one_notification(wqueue, n, file->f_cred))
> > + wqueue->debug = 0;
> > + else
> > + wqueue->debug++;
> > + ret = len;
> > + if (wqueue->debug > 20)
> > + ret = -EIO;

It's for debugging purposes, so the non-atomiticity doesn't matter. I'll
#undef the symbol to disable the code.

> > +#define IOC_WATCH_QUEUE_SET_SIZE _IO('s', 0x01) /* Set the size in pages */
> > +#define IOC_WATCH_QUEUE_SET_FILTER _IO('s', 0x02) /* Set the filter */
>
> Should these ioctl numbers be registered in
> Documentation/ioctl/ioctl-number.txt?

Quite possibly. I'm not sure where's best to actually allocate it. I picked
's' out of the air.

David

2019-05-28 23:13:43

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Tue, May 28, 2019 at 06:30:20PM +0100, David Howells wrote:
> Greg KH <[email protected]> wrote:
>
> > > Implement a misc device that implements a general notification queue as a
> > > ring buffer that can be mmap()'d from userspace.
> >
> > "general" but just for filesystems, right? :(
>
> Whatever gave you that idea? You can watch keyrings events, for example -
> they're not exactly filesystems. I've added the ability to watch for mount
> topology changes and superblock events because those are something I've been
> asked to do. I've added something for block events because I've recently had
> a problem with trying to recover data from a dodgy disk in that every time the
> disk goes offline, the ddrecover goes "wheeeee!" as it just sees a lot of
> EIO/ENODATA at a great rate of knots because it doesn't know the driver is now
> ignoring the disk.
>
> I don't know what else people might want to watch, but I've tried to make it
> as generic as possible so as not to exclude it if possible.

Ok, let me try to dig up some older proposals to see if this fits into
the same model to work with them as well.

> > > + refcount_t usage;
> >
> > Usage of what, this structure? Or something else?
>
> This is the number of usages of this struct (references to if you prefer). I
> can add a comment to this effect.

I think you answer this later on with the kref comment :)

> > > + return -EOPNOTSUPP;
> >
> > -ENOTTY is the correct "not a valid ioctl" error value, right?
>
> fs/ioctl.c does both, but I can switch it if it makes you happier.

It does.

> > > +void put_watch_queue(struct watch_queue *wqueue)
> > > +{
> > > + if (refcount_dec_and_test(&wqueue->usage))
> > > + kfree_rcu(wqueue, rcu);
> >
> > Why not just use a kref?
>
> Why use a kref? It seems like an effort to be a C++ base class, but without
> the C++ inheritance bit. Using kref doesn't seem to gain anything. It's just
> a wrapper around refcount_t - so why not just use a refcount_t?
>
> kref_put() could potentially add an unnecessary extra stack frame and would
> seem to be best avoided, though an optimising compiler ought to be able to
> inline if it can.

If kref_put() is on your fast path, you have worse problems (kfree isn't
fast, right?)

Anyway, it's an inline function, how can it add an extra stack frame?
Don't try to optimize something that isn't needed yet.

> Are you now on the convert all refcounts to krefs path?

"now"? Remember, I wrote kref all those years ago, everyone should use
it. It saves us having to audit the same pattern over and over again.
And, even nicer, it uses a refcount now, and as you are trying to
reference count an object, it is exactly what this was written for.

So yes, I do think it should be used here, unless it is deemed to not
fit the pattern/usage model.

> > > +EXPORT_SYMBOL(add_watch_to_object);
> >
> > Naming nit, shouldn't the "prefix" all be the same for these new
> > functions?
> >
> > watch_queue_add_object()? watch_queue_put()? And so on?
>
> Naming is fun. watch_queue_add_object - that suggests something different to
> what the function actually does. I'll think about adjusting the names.

Ok, just had to say something. It's your call, and yes, naming is hard.

> > > +module_exit(watch_queue_exit);
> >
> > module_misc_device()?
>
> warthog>git grep module_misc_device -- Documentation/
> warthog1>

Do I have to document all helper macros? Anyway, it saves you
boilerplate code, but if built in, it's at the module init level, not
the fs init level, like you are asking for here. So that might not
work, it's your call.

> > > + struct {
> > > + struct watch_notification watch; /* WATCH_TYPE_SKIP */
> > > + volatile __u32 head; /* Ring head index */
> > > + volatile __u32 tail; /* Ring tail index */
> >
> > A uapi structure that has volatile in it? Are you _SURE_ this is
> > correct?
> >
> > That feels wrong to me... This is not a backing-hardware register, it's
> > "just memory" and slapping volatile on it shouldn't be the correct
> > solution for telling the compiler to not to optimize away reads/flushes,
> > right? You need a proper memory access type primitive for that to work
> > correctly everywhere I thought.
> >
> > We only have 2 users of volatile in include/uapi, one for WMI structures
> > that are backed by firmware (seems correct), and one for DRM which I
> > have no idea how it works as it claims to be a lock. Why is this new
> > addition the correct way to do this that no other ring-buffer that was
> > mmapped has needed to?
>
> Yeah, I understand your concern with this.
>
> The reason I put the volatiles in is that the kernel may be modifying the head
> pointer on one CPU simultaneously with userspace modifying the tail pointer on
> another CPU.
>
> Note that userspace does not need to enter the kernel to find out if there's
> anything in the buffer or to read stuff out of the buffer. Userspace only
> needs to enter the kernel, using poll() or similar, to wait for something to
> appear in the buffer.

And how does the tracing and perf ring buffers do this without needing
volatile? Why not use the same type of interface they provide, as it's
always good to share code that has already had all of the nasty corner
cases worked out.

Anyway, I don't want you to think I don't like this code/idea overall, I
do. I just want to see it be something that everyone can use, and use
easily, as it has been something lots of people have been asking for for
a long time.

thanks,

greg k-h

2019-05-28 23:25:10

by Jann Horn

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 12:28 AM David Howells <[email protected]> wrote:
> Jann Horn <[email protected]> wrote:
> > I don't see you setting any special properties on the VMA that would
> > prevent userspace from extending its size via mremap() - no
> > VM_DONTEXPAND or VM_PFNMAP. So I think you might get an out-of-bounds
> > access here?
>
> Should I just set VM_DONTEXPAND in watch_queue_mmap()? Like so:
>
> vma->vm_flags |= VM_DONTEXPAND;

Yeah, that should work.

> > > +static void watch_queue_map_pages(struct vm_fault *vmf,
> > > + pgoff_t start_pgoff, pgoff_t end_pgoff)
> > ...
> >
> > Same as above.
>
> Same solution as above? Or do I need ot check start/end_pgoff too?

Same solution.

> > > +static int watch_queue_mmap(struct file *file, struct vm_area_struct *vma)
> > > +{
> > > + struct watch_queue *wqueue = file->private_data;
> > > +
> > > + if (vma->vm_pgoff != 0 ||
> > > + vma->vm_end - vma->vm_start > wqueue->nr_pages * PAGE_SIZE ||
> > > + !(pgprot_val(vma->vm_page_prot) & pgprot_val(PAGE_SHARED)))
> > > + return -EINVAL;
> >
> > This thing should probably have locking against concurrent
> > watch_queue_set_size()?
>
> Yeah.
>
> static int watch_queue_mmap(struct file *file,
> struct vm_area_struct *vma)
> {
> struct watch_queue *wqueue = file->private_data;
> struct inode *inode = file_inode(file);
> u8 nr_pages;
>
> inode_lock(inode);
> nr_pages = wqueue->nr_pages;
> inode_unlock(inode);
>
> if (nr_pages == 0 ||
> ...
> return -EINVAL;

Looks reasonable.

> > > + smp_store_release(&buf->meta.head, len);
> >
> > Why is this an smp_store_release()? The entire buffer should not be visible to
> > userspace before this setup is complete, right?
>
> Yes - if I put the above locking in the mmap handler. OTOH, it's a one-off
> barrier...
>
> > > + if (wqueue->buffer)
> > > + return -EBUSY;
> >
> > The preceding check occurs without any locks held and therefore has no
> > reliable effect. It should probably be moved below the
> > inode_lock(...).
>
> Yeah, it can race. I'll move it into watch_queue_set_size().

Sounds good.

> > > +static void free_watch(struct rcu_head *rcu)
> > > +{
> > > + struct watch *watch = container_of(rcu, struct watch, rcu);
> > > +
> > > + put_watch_queue(rcu_access_pointer(watch->queue));
> >
> > This should be rcu_dereference_protected(..., 1).
>
> That shouldn't be necessary. rcu_access_pointer()'s description says:
>
> * It is also permissible to use rcu_access_pointer() when read-side
> * access to the pointer was removed at least one grace period ago, as
> * is the case in the context of the RCU callback that is freeing up
> * the data, ...
>
> It's in an rcu callback function, so accessing the __rcu pointers in the RCU'd
> struct should be fine with rcu_access_pointer().

Aah, whoops, you're right, I missed that paragraph in the
documentation of rcu_access_pointer().

> > > + /* We don't need the watch list lock for the next bit as RCU is
> > > + * protecting everything from being deallocated.
> >
> > Does "everything" mean "the wqueue" or more than that?
>
> Actually, just 'wqueue' and its buffer. 'watch' is held by us once we've
> dequeued it as we now own the ref 'wlist' had on it. 'wlist' and 'wq' must be
> pinned by the caller.
>
> > > + if (release) {
> > > + if (wlist->release_watch) {
> > > + rcu_read_unlock();
> > > + /* This might need to call dput(), so
> > > + * we have to drop all the locks.
> > > + */
> > > + wlist->release_watch(wlist, watch);
> >
> > How are you holding a reference to `wlist` here? You got the reference through
> > rcu_dereference(), you've dropped the RCU read lock, and I don't see anything
> > that stabilizes the reference.
>
> The watch record must hold a ref on the watched object if the watch_list has a
> ->release_watch() method. In the code snippet above, the watch record now
> belongs to us because we unlinked it under the wlist->lock some lines prior.

Ah, of course.

> However, you raise a good point, and I think the thing to do is to cache
> ->release_watch from it and not pass wlist into (*release_watch)(). We don't
> need to concern ourselves with cleaning up *wlist as it will be cleaned up
> when the target object is removed.
>
> Keyrings don't have a ->release_watch method and neither does the block-layer
> notification stuff.
>
> > > + if (wqueue->pages && wqueue->pages[0])
> > > + WARN_ON(page_ref_count(wqueue->pages[0]) != 1);
> >
> > Is there a reason why there couldn't still be references to the pages
> > from get_user_pages()/get_user_pages_fast()?
>
> I'm not sure. I'm not sure what to do if there are. What do you suggest?

I would use put_page() instead of manually freeing it; I think that
should be enough? I'm not entirely sure though.

> > > + n->info &= (WATCH_INFO_LENGTH | WATCH_INFO_TYPE_FLAGS | WATCH_INFO_ID);
> >
> > Should the non-atomic modification of n->info
>
> n's an unpublished copy of some userspace data that's local to the function
> instance. There shouldn't be any way to race with it at this point.

Ah, derp. Yes.

2019-05-29 16:08:45

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Greg KH <[email protected]> wrote:

> > kref_put() could potentially add an unnecessary extra stack frame and would
> > seem to be best avoided, though an optimising compiler ought to be able to
> > inline if it can.
>
> If kref_put() is on your fast path, you have worse problems (kfree isn't
> fast, right?)
>
> Anyway, it's an inline function, how can it add an extra stack frame?

The call to the function pointer. Hopefully the compiler will optimise that
away for an inlineable function.

> > Are you now on the convert all refcounts to krefs path?
>
> "now"? Remember, I wrote kref all those years ago,

Yes - and I thought it wasn't a good idea at the time. But this is the first
time you've mentioned it to me, let alone pushed to change to it, that I
recall.

> everyone should use
> it. It saves us having to audit the same pattern over and over again.
> And, even nicer, it uses a refcount now, and as you are trying to
> reference count an object, it is exactly what this was written for.
>
> So yes, I do think it should be used here, unless it is deemed to not
> fit the pattern/usage model.

kref_put() enforces a very specific destructor signature. I know of places
where that doesn't work because the destructor takes more than one argument
(granted that this is not the case here). So why does kref_put() exist at
all? Why not kref_dec_and_test()?

Why doesn't refcount_t get merged into kref, or vice versa? Having both would
seem redundant.

Mind you, I've been gradually reverting atomic_t-to-refcount_t conversions
because it seems I'm not allowed refcount_inc/dec_return() and I want to get
at the point refcount for tracing purposes.

> > > > +module_exit(watch_queue_exit);
> > >
> > > module_misc_device()?
> >
> > warthog>git grep module_misc_device -- Documentation/
> > warthog1>
>
> Do I have to document all helper macros?

If you add an API, documenting it is your privilege ;-) It's an important
test of the API - if you can't describe it, it's probably wrong.

Now I will grant that you didn't add that function...

> Anyway, it saves you boilerplate code, but if built in, it's at the module
> init level, not the fs init level, like you are asking for here. So that
> might not work, it's your call.

Actually, I probably shouldn't have a module exit function. It can't be a
module as it's called by core code. I'll switch to builtin_misc_device().

> And how does the tracing and perf ring buffers do this without needing
> volatile? Why not use the same type of interface they provide, as it's
> always good to share code that has already had all of the nasty corner
> cases worked out.

I've no idea how trace does it - or even where - or even if. As far as I can
see, grepping for mmap in kernel/trace/*, there's no mmap support.

Reading Documentation/trace/ring-buffer-design.txt the trace subsystem has
some sort of transient page fifo which is a lot more complicated than what I
want and doesn't look like it'll be mmap'able.

Looking at the perf ring buffer, there appears to be a missing barrier in
perf_aux_output_end():

rb->user_page->aux_head = rb->aux_head;

should be:

smp_store_release(&rb->user_page->aux_head, rb->aux_head);

It should also be using smp_load_acquire(). See
Documentation/core-api/circular-buffers.rst

And a (partial) patch has been proposed: https://lkml.org/lkml/2018/5/10/249

David

2019-05-29 17:48:54

by Jann Horn

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 6:07 PM David Howells <[email protected]> wrote:
> Greg KH <[email protected]> wrote:
> > everyone should use
> > it. It saves us having to audit the same pattern over and over again.
> > And, even nicer, it uses a refcount now, and as you are trying to
> > reference count an object, it is exactly what this was written for.
> >
> > So yes, I do think it should be used here, unless it is deemed to not
> > fit the pattern/usage model.
>
> kref_put() enforces a very specific destructor signature. I know of places
> where that doesn't work because the destructor takes more than one argument
> (granted that this is not the case here). So why does kref_put() exist at
> all? Why not kref_dec_and_test()?
>
> Why doesn't refcount_t get merged into kref, or vice versa? Having both would
> seem redundant.
>
> Mind you, I've been gradually reverting atomic_t-to-refcount_t conversions
> because it seems I'm not allowed refcount_inc/dec_return() and I want to get
> at the point refcount for tracing purposes.

Yeeech, that's horrible, please don't do that.

Does this mean that refcount_read() isn't sufficient for what you want
to do with tracing (because for some reason you actually need to know
the values atomically at the time of increment/decrement)?

2019-05-29 21:04:52

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Jann Horn <[email protected]> wrote:

> Does this mean that refcount_read() isn't sufficient for what you want
> to do with tracing (because for some reason you actually need to know
> the values atomically at the time of increment/decrement)?

Correct. There's a gap and if an interrupt or something occurs, it's
sufficiently big for the refcount trace to go weird.

I've seen it in afs/rxrpc where the incoming network packets that are part of
the rxrpc call flow disrupt the refcounts noted in trace lines.

David

2019-05-29 23:11:27

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 05:06:40PM +0100, David Howells wrote:
> Greg KH <[email protected]> wrote:
>
> > > kref_put() could potentially add an unnecessary extra stack frame and would
> > > seem to be best avoided, though an optimising compiler ought to be able to
> > > inline if it can.
> >
> > If kref_put() is on your fast path, you have worse problems (kfree isn't
> > fast, right?)
> >
> > Anyway, it's an inline function, how can it add an extra stack frame?
>
> The call to the function pointer. Hopefully the compiler will optimise that
> away for an inlineable function.

The function pointer only gets called for the last "put", and then kfree
will be called so you should not have to worry about speed/stack frames
at that point in time.

> > > Are you now on the convert all refcounts to krefs path?
> >
> > "now"? Remember, I wrote kref all those years ago,
>
> Yes - and I thought it wasn't a good idea at the time. But this is the first
> time you've mentioned it to me, let alone pushed to change to it, that I
> recall.

I bring up using a kref any time I see a usage that could use it as it
makes it easier for people to understand and "know" you are doing your
reference counting for your object "correctly". It's an abstraction
that is used to make it easier for us developers to understand.
Otherwise you have to hand-roll the same logic here. Yes, refcounts
have made it easier to do it in your own (which was their goal), but you
still don't have to do it "on your own".

Anyway, I'll not push the issue here, if you want to stick to a
refcount_t, that's enough for now. We can worry about changing this
later after you have debugged all the corner conditions :)

> > everyone should use
> > it. It saves us having to audit the same pattern over and over again.
> > And, even nicer, it uses a refcount now, and as you are trying to
> > reference count an object, it is exactly what this was written for.
> >
> > So yes, I do think it should be used here, unless it is deemed to not
> > fit the pattern/usage model.
>
> kref_put() enforces a very specific destructor signature. I know of places
> where that doesn't work because the destructor takes more than one argument
> (granted that this is not the case here). So why does kref_put() exist at
> all? Why not kref_dec_and_test()?

The destructor only takes one object pointer as you are finally freeing
that object. What more do you need/want to "know" at that point in
time?

What would kref_dec_and_test() be needed for?

> Why doesn't refcount_t get merged into kref, or vice versa? Having both would
> seem redundant.

kref uses refcount_t and provides a different functionality on top of
it. Not all uses of a refcount in the kernel is for object lifecycle
reference counting, as you know :)

> Mind you, I've been gradually reverting atomic_t-to-refcount_t conversions
> because it seems I'm not allowed refcount_inc/dec_return() and I want to get
> at the point refcount for tracing purposes.

That's not good, we should address that independently as you are loosing
functionality/protection when doing that.

thanks,

greg k-h

2019-05-29 23:13:40

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 05:06:40PM +0100, David Howells wrote:
> Greg KH <[email protected]> wrote:
> > And how does the tracing and perf ring buffers do this without needing
> > volatile? Why not use the same type of interface they provide, as it's
> > always good to share code that has already had all of the nasty corner
> > cases worked out.
>
> I've no idea how trace does it - or even where - or even if. As far as I can
> see, grepping for mmap in kernel/trace/*, there's no mmap support.
>
> Reading Documentation/trace/ring-buffer-design.txt the trace subsystem has
> some sort of transient page fifo which is a lot more complicated than what I
> want and doesn't look like it'll be mmap'able.
>
> Looking at the perf ring buffer, there appears to be a missing barrier in
> perf_aux_output_end():
>
> rb->user_page->aux_head = rb->aux_head;
>
> should be:
>
> smp_store_release(&rb->user_page->aux_head, rb->aux_head);
>
> It should also be using smp_load_acquire(). See
> Documentation/core-api/circular-buffers.rst
>
> And a (partial) patch has been proposed: https://lkml.org/lkml/2018/5/10/249

So, if that's all that needs to be fixed, can you use the same
buffer/code if that patch is merged?

thanks,

greg k-h

2019-05-30 09:52:14

by Andrea Parri

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

> > Looking at the perf ring buffer, there appears to be a missing barrier in
> > perf_aux_output_end():
> >
> > rb->user_page->aux_head = rb->aux_head;
> >
> > should be:
> >
> > smp_store_release(&rb->user_page->aux_head, rb->aux_head);
> >
> > It should also be using smp_load_acquire(). See
> > Documentation/core-api/circular-buffers.rst
> >
> > And a (partial) patch has been proposed: https://lkml.org/lkml/2018/5/10/249
>
> So, if that's all that needs to be fixed, can you use the same
> buffer/code if that patch is merged?

That's about one year old...: let me add the usual suspects in Cc: ;-)
since I'm not sure what the plan was (or if I'm missing something) ...

Speaking of ring buffer implementations (and relatively "old" patches),
here's another quite interesting:

https://lkml.kernel.org/r/[email protected]

Thanks,
Andrea

2019-05-31 08:38:26

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Thu, May 30, 2019 at 11:50:39AM +0200, Andrea Parri wrote:
> > > Looking at the perf ring buffer, there appears to be a missing barrier in
> > > perf_aux_output_end():
> > >
> > > rb->user_page->aux_head = rb->aux_head;
> > >
> > > should be:
> > >
> > > smp_store_release(&rb->user_page->aux_head, rb->aux_head);
> > >
> > > It should also be using smp_load_acquire(). See
> > > Documentation/core-api/circular-buffers.rst
> > >
> > > And a (partial) patch has been proposed: https://lkml.org/lkml/2018/5/10/249
> >
> > So, if that's all that needs to be fixed, can you use the same
> > buffer/code if that patch is merged?
>
> That's about one year old...: let me add the usual suspects in Cc: ;-)
> since I'm not sure what the plan was (or if I'm missing something) ...

The AUX crud is 'special' and smp_store_release() doesn't really help in
many cases. Notable, AUX is typically used in combination with a
hardware writer. The driver is in charge of odering here, the generic
code doesn't know what the appropriate barrier (if any) is and would
have to resort to the most expensive/heavy one available.

Also see the comment right above this function:

"It is the
pmu driver's responsibility to observe ordering rules of the hardware,
so that all the data is externally visible before this is called."

2019-05-31 08:48:45

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 05:06:40PM +0100, David Howells wrote:

> Looking at the perf ring buffer, there appears to be a missing barrier in
> perf_aux_output_end():
>
> rb->user_page->aux_head = rb->aux_head;
>
> should be:
>
> smp_store_release(&rb->user_page->aux_head, rb->aux_head);

I've answered that in another email; the aux bit is 'magic'.

> It should also be using smp_load_acquire(). See
> Documentation/core-api/circular-buffers.rst

We use the control dependency instead, as described in the comment of
perf_output_put_handle():

* kernel user
*
* if (LOAD ->data_tail) { LOAD ->data_head
* (A) smp_rmb() (C)
* STORE $data LOAD $data
* smp_wmb() (B) smp_mb() (D)
* STORE ->data_head STORE ->data_tail
* }
*
* Where A pairs with D, and B pairs with C.
*
* In our case (A) is a control dependency that separates the load of
* the ->data_tail and the stores of $data. In case ->data_tail
* indicates there is no room in the buffer to store $data we do not.
*
* D needs to be a full barrier since it separates the data READ
* from the tail WRITE.
*
* For B a WMB is sufficient since it separates two WRITEs, and for C
* an RMB is sufficient since it separates two READs.

Userspace can choose to use smp_load_acquire() over the first smp_rmb()
if that is efficient for the architecture (for w ahole bunch of archs
load-acquire would end up using mb() while rmb() is adequate and
cheaper).

2019-05-31 11:17:53

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Wed, May 29, 2019 at 10:02:43PM +0100, David Howells wrote:
> Jann Horn <[email protected]> wrote:
>
> > Does this mean that refcount_read() isn't sufficient for what you want
> > to do with tracing (because for some reason you actually need to know
> > the values atomically at the time of increment/decrement)?
>
> Correct. There's a gap and if an interrupt or something occurs, it's
> sufficiently big for the refcount trace to go weird.
>
> I've seen it in afs/rxrpc where the incoming network packets that are part of
> the rxrpc call flow disrupt the refcounts noted in trace lines.

Can you re-iterate the exact problem? I konw we talked about this in the
past, but I seem to have misplaced those memories :/

FWIW I agree that kref is useless fluff, but I've long ago given up on
that fight.

2019-05-31 12:04:43

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Peter Zijlstra <[email protected]> wrote:

> Can you re-iterate the exact problem? I konw we talked about this in the
> past, but I seem to have misplaced those memories :/

Take this for example:

void afs_put_call(struct afs_call *call)
{
struct afs_net *net = call->net;
int n = atomic_dec_return(&call->usage);
int o = atomic_read(&net->nr_outstanding_calls);

trace_afs_call(call, afs_call_trace_put, n + 1, o,
__builtin_return_address(0));

ASSERTCMP(n, >=, 0);
if (n == 0) {
...
}
}

I am printing the usage count in the afs_call tracepoint so that I can use it
to debug refcount bugs. If I do it like this:

void afs_put_call(struct afs_call *call)
{
int n = refcount_read(&call->usage);
int o = atomic_read(&net->nr_outstanding_calls);

trace_afs_call(call, afs_call_trace_put, n, o,
__builtin_return_address(0));

if (refcount_dec_and_test(&call->usage)) {
...
}
}

then there's a temporal gap between the usage count being read and the actual
atomic decrement in which another CPU can alter the count. This can be
exacerbated by an interrupt occurring, a softirq occurring or someone enabling
the tracepoint.

I can't do the tracepoint after the decrement if refcount_dec_and_test()
returns false unless I save all the values from the object that I might need
as the object could be destroyed any time from that point on. In this
particular case, that's just call->debug_id, but it could be other things in
other cases.

Note that I also can't touch the afs_net object in that situation either, and
the outstanding calls count that I record will potentially be out of date -
but there's not a lot I can do about that.

David

2019-05-31 12:45:10

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Greg KH <[email protected]> wrote:

> > kref_put() enforces a very specific destructor signature. I know of places
> > where that doesn't work because the destructor takes more than one argument
> > (granted that this is not the case here). So why does kref_put() exist at
> > all? Why not kref_dec_and_test()?
>
> The destructor only takes one object pointer as you are finally freeing
> that object. What more do you need/want to "know" at that point in
> time?

Imagine that I have an object that's on a list rooted in a namespace and that
I have a lot of these objects. Imagine further that any time I want to put a
ref on one of these objects, it's in a context that has the namespace pinned.
I therefore don't need to store a pointer to the namespace in every object
because I can pass that in to the put function

Indeed, I can still access the namespace even after the decrement didn't
reduce the usage count to 0 - say for doing statistics.

> What would kref_dec_and_test() be needed for?

Why do you need kref_put() to take a destructor function pointer? Why cannot
that be replaced with, say:

static inline bool __kref_put(struct kref *k)
{
return refcount_dec_and_test(&k->refcount);
}

and then one could do:

void put_foo(struct foo_net *ns, struct foo *f)
{
if (__kref_put(&f->refcount)) {
// destroy foo
}
}

that way the destruction code does not have to be offloaded into its own
function and you still have your pattern to look for.

For tracing purposes, I could live with something like:

static inline
bool __kref_put_return(struct kref *k, unsigned int *_usage)
{
return refcount_dec_and_test_return(&k->refcount, _usage);
}

and then I could do:

void put_foo(struct foo_net *ns, struct foo *f)
{
unsigned int u;
bool is_zero = __kref_put_return(&f->refcount, &u);

trace_foo_refcount(f, u);
if (is_zero) {
// destroy foo
}
}

then it could be made such that you can disable the ability of
refcount_dec_and_test_return() to pass back a useful refcount value if you
want a bit of extra speed.

Or even if refcount_dec_return() is guaranteed to return 0 if the count hits
the floor and non-zero otherwise and there's a config switch to impose a
stronger guarantee that it will return a value that's appropriately
transformed to look as if I was using atomic_dec_return().

Similarly for refcount_inc_return() - it could just return gibberish unless
the same config switch is enabled.

Question for AMD/Intel guys: I'm curious if LOCK DECL faster than LOCK XADD -1
on x86_64?

> > Why doesn't refcount_t get merged into kref, or vice versa? Having both
> > would seem redundant.
>
> kref uses refcount_t and provides a different functionality on top of
> it. Not all uses of a refcount in the kernel is for object lifecycle
> reference counting, as you know :)

I do? I can't think of one offhand. Not that I'm saying you're wrong on
that - there's an awful lot of kernel.

David

2019-05-31 13:29:26

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Fri, May 31, 2019 at 01:02:15PM +0100, David Howells wrote:
> Peter Zijlstra <[email protected]> wrote:
>
> > Can you re-iterate the exact problem? I konw we talked about this in the
> > past, but I seem to have misplaced those memories :/
>
> Take this for example:
>
> void afs_put_call(struct afs_call *call)
> {
> struct afs_net *net = call->net;
> int n = atomic_dec_return(&call->usage);
> int o = atomic_read(&net->nr_outstanding_calls);
>
> trace_afs_call(call, afs_call_trace_put, n + 1, o,
> __builtin_return_address(0));
>
> ASSERTCMP(n, >=, 0);
> if (n == 0) {
> ...
> }
> }
>
> I am printing the usage count in the afs_call tracepoint so that I can use it
> to debug refcount bugs. If I do it like this:
>
> void afs_put_call(struct afs_call *call)
> {
> int n = refcount_read(&call->usage);
> int o = atomic_read(&net->nr_outstanding_calls);
>
> trace_afs_call(call, afs_call_trace_put, n, o,
> __builtin_return_address(0));
>
> if (refcount_dec_and_test(&call->usage)) {
> ...
> }
> }
>
> then there's a temporal gap between the usage count being read and the actual
> atomic decrement in which another CPU can alter the count. This can be
> exacerbated by an interrupt occurring, a softirq occurring or someone enabling
> the tracepoint.
>
> I can't do the tracepoint after the decrement if refcount_dec_and_test()
> returns false unless I save all the values from the object that I might need
> as the object could be destroyed any time from that point on.

Is it not the responsibility of the task that affects the 1->0
transition to actually free the memory?

That is, I'm expecting the '...' in both cases above the include the
actual freeing of the object. If this is not the case, then @usage is
not a reference count.

(and it has already been established that refcount_t doesn't work for
usage count scenarios)

Aside from that, is the problem that refcount_dec_and_test() returns a
boolean (true - last put, false - not last) instead of the refcount
value? This does indeed make it hard to print the exact count value for
the event.

2019-05-31 14:22:03

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Peter Zijlstra <[email protected]> wrote:

> Is it not the responsibility of the task that affects the 1->0
> transition to actually free the memory?
>
> That is, I'm expecting the '...' in both cases above the include the
> actual freeing of the object. If this is not the case, then @usage is
> not a reference count.

Yes. The '...' does the freeing. It seemed unnecessary to include the code
ellipsised there since it's not the point of the discussion, but if you want
the full function:

void afs_put_call(struct afs_call *call)
{
struct afs_net *net = call->net;
int n = atomic_dec_return(&call->usage);
int o = atomic_read(&net->nr_outstanding_calls);

trace_afs_call(call, afs_call_trace_put, n + 1, o,
__builtin_return_address(0));

ASSERTCMP(n, >=, 0);
if (n == 0) {
ASSERT(!work_pending(&call->async_work));
ASSERT(call->type->name != NULL);

if (call->rxcall) {
rxrpc_kernel_end_call(net->socket, call->rxcall);
call->rxcall = NULL;
}
if (call->type->destructor)
call->type->destructor(call);

afs_put_server(call->net, call->server);
afs_put_cb_interest(call->net, call->cbi);
afs_put_addrlist(call->alist);
kfree(call->request);

trace_afs_call(call, afs_call_trace_free, 0, o,
__builtin_return_address(0));
kfree(call);

o = atomic_dec_return(&net->nr_outstanding_calls);
if (o == 0)
wake_up_var(&net->nr_outstanding_calls);
}
}

You can see the kfree(call) in there.
Peter Zijlstra <[email protected]> wrote:

> (and it has already been established that refcount_t doesn't work for
> usage count scenarios)

?

Does that mean struct kref doesn't either?

> Aside from that, is the problem that refcount_dec_and_test() returns a
> boolean (true - last put, false - not last) instead of the refcount
> value? This does indeed make it hard to print the exact count value for
> the event.

That is the problem, yes - well, one of them: refcount_inc() doesn't either.

David

2019-05-31 14:56:59

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Greg KH <[email protected]> wrote:

> So, if that's all that needs to be fixed, can you use the same
> buffer/code if that patch is merged?

I really don't know. The perf code is complex, partially in hardware drivers
and is tricky to understand - though a chunk of that is the "aux" buffer part;
PeterZ used words like "special" and "magic" and the comments in the code talk
about the hardware writing into the buffer.

__perf_output_begin() does not appear to be SMP safe. It uses local_cmpxchg()
and local_add() which on x86 lack the LOCK prefix.

stracing the perf command on my test machine, it calls perf_event_open(2) four
times and mmap's each fd it gets back. I'm guessing that each one maps a
separate buffer for each CPU.

So to use watch_queue based on perf's buffering, you would have to have a
(2^N)+1 pages-sized buffer for each CPU. So that would be a minimum of 64K of
unswappable memory for my desktop machine, say). Multiply that by each
process that wants to listen for events...

What I'm aiming for is something that has a single buffer used by all CPUs for
each instance of /dev/watch_queue opened and I'd also like to avoid having to
allocate the metadata page and the aux buffer to save space. This is locked
memory and cannot be swapped.

Also, perf has to leave a gap in the ring because it uses CIRC_SPACE(), though
that's a minor detail that I guess can't be fixed now.

I'm also slightly concerned that __perf_output_begin() doesn't check if
rb->user->tail has got ahead of rb->user->head or that it's lagging too far
behind. I doubt it's a serious problem for the kernel since it won't write
outside of the buffer, but userspace might screw up. I think the worst that
will happen is that userspace will get confused.

One thing I would like is to waive the 2^N size requirement. I understand
*why* we do that, but I wonder how expensive DIV instructions are for
relatively small divisors.

David

2019-05-31 16:47:44

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

On Fri, May 31, 2019 at 03:20:12PM +0100, David Howells wrote:
> Peter Zijlstra <[email protected]> wrote:

> > (and it has already been established that refcount_t doesn't work for
> > usage count scenarios)
>
> ?
>
> Does that mean struct kref doesn't either?

Indeed, since kref is just a pointless wrapper around refcount_t it does
not either.

The main distinction between a reference count and a usage count is that
0 means different things. For a refcount 0 means dead. For a usage count
0 is merely unused but valid.

Incrementing a 0 refcount is a serious bug -- use-after-free (and hence
refcount_t will refuse this and splat), for a usage count this is no
problem.

Now, it is sort-of possible to merge the two, by basically stating
something like: usage = refcount - 1. But that can get tricky and people
have not really liked the result much for the few times I tried.

2019-05-31 17:14:45

[permalink] [raw]

Subject: Re: [PATCH 1/7] General notification queue with user mmap()'able ring buffer

Peter Zijlstra <[email protected]> wrote:

> > > (and it has already been established that refcount_t doesn't work for
> > > usage count scenarios)
> >
> > ?
> >
> > Does that mean struct kref doesn't either?
>
> Indeed, since kref is just a pointless wrapper around refcount_t it does
> not either.
>
> The main distinction between a reference count and a usage count is that
> 0 means different things. For a refcount 0 means dead. For a usage count
> 0 is merely unused but valid.

Ah - I consider the terms interchangeable.

Take Documentation/filesystems/vfs.txt for instance:

dget: open a new handle for an existing dentry (this just increments
the usage count)

dput: close a handle for a dentry (decrements the usage count). ...

...

d_lookup: look up a dentry given its parent and path name component
It looks up the child of that given name from the dcache
hash table. If it is found, the reference count is incremented
and the dentry is returned. The caller must use dput()
to free the dentry when it finishes using it.

Here we interchange the terms.

Or https://www.kernel.org/doc/gorman/html/understand/understand013.html
which seems to interchange the terms in reference to struct page.

David

2019-06-17 16:25:43