[PATCH v1 1/2] Documentation/filesystems: add binderfs

[PATCH v1 1/2] Documentation/filesystems: add binderfs

[Christian Brauner]

This documents the Android binderfs filesystem used to dynamically add and
remove binder devices that are private to each instance.

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
---
/* Changelog */
v1:
- switch from *.txt to *.rst format
---
 Documentation/filesystems/binderfs.rst | 70 ++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 Documentation/filesystems/binderfs.rst

diff --git a/Documentation/filesystems/binderfs.rst b/Documentation/filesystems/binderfs.rst
new file mode 100644
index 000000000000..74a744b42db7
--- /dev/null
+++ b/Documentation/filesystems/binderfs.rst
@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+The Android binderfs Filesystem
+===============================
+
+Android binderfs is a filesystem for the Android binder IPC mechanism.  It
+allows to dynamically add and remove binder devices at runtime.  Binder devices
+located in a new binderfs instance are independent of binder devices located in
+other binderfs instances.  Mounting a new binderfs instance makes it possible
+to get a set of private binder devices.
+
+Mounting binderfs
+-----------------
+
+Android binderfs can be mounted with:
+
+::
+
+  mkdir /dev/binderfs
+  mount -t binder binder /dev/binderfs
+
+at which point a new instance of binderfs will show up at ``/dev/binderfs``.
+In a fresh instance of binderfs no binder devices will be present.  There will
+only be a ``binder-control`` device which serves as the request handler for
+binderfs. Mounting another binderfs instance at a different location will
+create a new and separate instance from all other binderfs mounts.  This is
+identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
+binderfs filesystem can be mounted in user namespaces.
+
+Options
+-------
+max
+  binderfs instances can be mounted with a limit on the number of binder
+  devices that can be allocated. The ``max=<count>`` mount option serves as
+  a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
+  of binder devices can be allocated in this binderfs instance.
+
+Allocating binder Devices
+-------------------------
+
+.. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
+
+To allocate a new binder device in a binderfs instance a request needs to be
+sent through the ``binder-control`` device node.  A request is sent in the form
+of an `ioctl() <ioctl_>`_.
+
+What a program needs to do is to open the ``binder-control`` device node and
+send a ``BINDER_CTL_ADD`` request to the kernel.  Users of binderfs need to
+tell the kernel which name the new binder device should get.  By default a name
+can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
+zero byte.
+
+Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
+binder_device`` with the name to the kernel it will allocate a new binder
+device and return the major and minor number of the new device in the struct
+(This is necessary because binderfs allocates a major device number
+dynamically.).  After the `ioctl() <ioctl_>`_ returns there will be a new
+binder device located under /dev/binderfs with the chosen name.
+
+Deleting binder Devices
+-----------------------
+
+.. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
+.. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
+
+Binderfs binder devices can be deleted via `unlink() <unlink_>`_.  This means
+that the `rm() <rm_>`_ tool can be used to delete them. Note that the
+``binder-control`` device cannot be deleted since this would make the binderfs
+instance unuseable.  The ``binder-control`` device will be deleted when the
+binderfs instance is unmounted and all references to it have been dropped.
-- 
2.19.1

[PATCH v1 2/2] samples: add binderfs sample program

[Christian Brauner]

This adds a simple sample program mounting binderfs and adding, then
removing a binder device.  Hopefully, it will be helpful to users who want
to know how binderfs is supposed to be used.

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
---
/* Changelog */
v1:
- patch introduced

v0:
- patch not present
---
 samples/Kconfig                     |  7 +++
 samples/Makefile                    |  2 +-
 samples/binderfs/Makefile           |  1 +
 samples/binderfs/binderfs_example.c | 83 +++++++++++++++++++++++++++++
 4 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 samples/binderfs/Makefile
 create mode 100644 samples/binderfs/binderfs_example.c

diff --git a/samples/Kconfig b/samples/Kconfig
index ad1ec7016d4c..d19754ccad08 100644
--- a/samples/Kconfig
+++ b/samples/Kconfig
@@ -147,6 +147,13 @@ config SAMPLE_VFIO_MDEV_MBOCHS
 	  Specifically it does *not* include any legacy vga stuff.
 	  Device looks a lot like "qemu -device secondary-vga".
 
+config SAMPLE_ANDROID_BINDERFS
+	bool "Build Android binderfs example"
+	depends on CONFIG_ANDROID_BINDERFS
+	help
+	  Builds a sample program to illustrate the use of the Android binderfs
+	  filesystem.
+
 config SAMPLE_STATX
 	bool "Build example extended-stat using code"
 	depends on BROKEN
diff --git a/samples/Makefile b/samples/Makefile
index bd601c038b86..b1142a958811 100644
--- a/samples/Makefile
+++ b/samples/Makefile
@@ -3,4 +3,4 @@
 obj-$(CONFIG_SAMPLES)	+= kobject/ kprobes/ trace_events/ livepatch/ \
 			   hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/ \
 			   configfs/ connector/ v4l/ trace_printk/ \
-			   vfio-mdev/ statx/ qmi/
+			   vfio-mdev/ statx/ qmi/ binderfs/
diff --git a/samples/binderfs/Makefile b/samples/binderfs/Makefile
new file mode 100644
index 000000000000..01ca9f2529a7
--- /dev/null
+++ b/samples/binderfs/Makefile
@@ -0,0 +1 @@
+obj-$(CONFIG_SAMPLE_ANDROID_BINDERFS) += binderfs_example.o
diff --git a/samples/binderfs/binderfs_example.c b/samples/binderfs/binderfs_example.c
new file mode 100644
index 000000000000..5bbd2ebc0aea
--- /dev/null
+++ b/samples/binderfs/binderfs_example.c
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <sched.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/mount.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+#include <linux/android/binder.h>
+#include <linux/android/binderfs.h>
+
+int main(int argc, char *argv[])
+{
+	int fd, ret, saved_errno;
+	size_t len;
+	struct binderfs_device device = { 0 };
+
+	ret = unshare(CLONE_NEWNS);
+	if (ret < 0) {
+		fprintf(stderr, "%s - Failed to unshare mount namespace\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	ret = mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, 0);
+	if (ret < 0) {
+		fprintf(stderr, "%s - Failed to mount / as private\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	ret = mkdir("/dev/binderfs", 0755);
+	if (ret < 0 && errno != EEXIST) {
+		fprintf(stderr, "%s - Failed to create binderfs mountpoint\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	ret = mount(NULL, "/dev/binderfs", "binder", 0, 0);
+	if (ret < 0) {
+		fprintf(stderr, "%s - Failed to mount binderfs\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	memcpy(device.name, "my-binder", strlen("my-binder"));
+
+	fd = open("/dev/binderfs/binder-control", O_RDONLY | O_CLOEXEC);
+	if (fd < 0) {
+		fprintf(stderr, "%s - Failed to open binder-control device\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	ret = ioctl(fd, BINDER_CTL_ADD, &device);
+	saved_errno = errno;
+	close(fd);
+	errno = saved_errno;
+	if (ret < 0) {
+		fprintf(stderr, "%s - Failed to allocate new binder device\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	printf("Allocated new binder device with major %d, minor %d, and name %s\n",
+	       device.major, device.minor, device.name);
+
+	ret = unlink("/dev/binderfs/my-binder");
+	if (ret < 0) {
+		fprintf(stderr, "%s - Failed to delete binder device\n",
+			strerror(errno));
+		exit(EXIT_FAILURE);
+	}
+
+	/* Cleanup happens when the mount namespace dies. */
+	exit(EXIT_SUCCESS);
+}
-- 
2.19.1

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Jonathan Corbet]

On Fri, 11 Jan 2019 14:40:59 +0100
Christian Brauner <christian@brauner.io> wrote:

> This documents the Android binderfs filesystem used to dynamically add and
> remove binder devices that are private to each instance.
> 
> Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>

Two quick notes:

> ---
> /* Changelog */
> v1:
> - switch from *.txt to *.rst format
> ---
>  Documentation/filesystems/binderfs.rst | 70 ++++++++++++++++++++++++++
>  1 file changed, 70 insertions(+)
>  create mode 100644 Documentation/filesystems/binderfs.rst

You didn't add it to index.rst, so it won't actually become part of the
docs build.

> diff --git a/Documentation/filesystems/binderfs.rst b/Documentation/filesystems/binderfs.rst
> new file mode 100644
> index 000000000000..74a744b42db7
> --- /dev/null
> +++ b/Documentation/filesystems/binderfs.rst
> @@ -0,0 +1,70 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +The Android binderfs Filesystem
> +===============================
> +
> +Android binderfs is a filesystem for the Android binder IPC mechanism.  It
> +allows to dynamically add and remove binder devices at runtime.  Binder devices
> +located in a new binderfs instance are independent of binder devices located in
> +other binderfs instances.  Mounting a new binderfs instance makes it possible
> +to get a set of private binder devices.
> +
> +Mounting binderfs
> +-----------------
> +
> +Android binderfs can be mounted with:
> +
> +::

This can be more readably formatted as:

	Android binderfs can be mounted with::

I've applied the patches, taking the liberty of fixing both of those
things up.  Thanks!

jon

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Christian Brauner]

On Mon, Jan 14, 2019 at 05:24:01PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 14:40:59 +0100
> Christian Brauner <christian@brauner.io> wrote:
> 
> > This documents the Android binderfs filesystem used to dynamically add and
> > remove binder devices that are private to each instance.
> > 
> > Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
> 
> Two quick notes:
> 
> > ---
> > /* Changelog */
> > v1:
> > - switch from *.txt to *.rst format
> > ---
> >  Documentation/filesystems/binderfs.rst | 70 ++++++++++++++++++++++++++
> >  1 file changed, 70 insertions(+)
> >  create mode 100644 Documentation/filesystems/binderfs.rst
> 
> You didn't add it to index.rst, so it won't actually become part of the
> docs build.
> 
> > diff --git a/Documentation/filesystems/binderfs.rst b/Documentation/filesystems/binderfs.rst
> > new file mode 100644
> > index 000000000000..74a744b42db7
> > --- /dev/null
> > +++ b/Documentation/filesystems/binderfs.rst
> > @@ -0,0 +1,70 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +The Android binderfs Filesystem
> > +===============================
> > +
> > +Android binderfs is a filesystem for the Android binder IPC mechanism.  It
> > +allows to dynamically add and remove binder devices at runtime.  Binder devices
> > +located in a new binderfs instance are independent of binder devices located in
> > +other binderfs instances.  Mounting a new binderfs instance makes it possible
> > +to get a set of private binder devices.
> > +
> > +Mounting binderfs
> > +-----------------
> > +
> > +Android binderfs can be mounted with:
> > +
> > +::
> 
> This can be more readably formatted as:
> 
> 	Android binderfs can be mounted with::
> 
> I've applied the patches, taking the liberty of fixing both of those
> things up.  Thanks!

Thanks Jon! Highly appreciated!

Christian

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Matthew Wilcox]

On Mon, Jan 14, 2019 at 05:24:01PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 14:40:59 +0100
> Christian Brauner <christian@brauner.io> wrote:
> > This documents the Android binderfs filesystem used to dynamically add and
> > remove binder devices that are private to each instance.
> 
> You didn't add it to index.rst, so it won't actually become part of the
> docs build.

I think you added it in the wrong place.

From 8167b80c950834da09a9204b6236f238197c197b Mon Sep 17 00:00:00 2001
From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
Date: Tue, 2 Jul 2019 13:54:38 -0400
Subject: [PATCH] docs: Move binderfs to admin-guide

The documentation is more appropriate for the administrator than for
the internal kernel API section it is currently in.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 .../{filesystems => admin-guide}/binderfs.rst          |  0
 Documentation/admin-guide/index.rst                    |  1 +
 Documentation/filesystems/index.rst                    | 10 ----------
 3 files changed, 1 insertion(+), 10 deletions(-)
 rename Documentation/{filesystems => admin-guide}/binderfs.rst (100%)

diff --git a/Documentation/filesystems/binderfs.rst b/Documentation/admin-guide/binderfs.rst
similarity index 100%
rename from Documentation/filesystems/binderfs.rst
rename to Documentation/admin-guide/binderfs.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 8001917ee012..24fbe0568eff 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   binderfs
    pm/index
    thunderbolt
    LSM/index
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d77f6..970c0a3ec377 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -31,13 +31,3 @@ filesystem implementations.
 
    journalling
    fscrypt
-
-Filesystem-specific documentation
-=================================
-
-Documentation for individual filesystem types can be found here.
-
-.. toctree::
-   :maxdepth: 2
-
-   binderfs.rst
-- 
2.20.1

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Christian Brauner]

On Tue, Jul 02, 2019 at 10:57:29AM -0700, Matthew Wilcox wrote:
> On Mon, Jan 14, 2019 at 05:24:01PM -0700, Jonathan Corbet wrote:
> > On Fri, 11 Jan 2019 14:40:59 +0100
> > Christian Brauner <christian@brauner.io> wrote:
> > > This documents the Android binderfs filesystem used to dynamically add and
> > > remove binder devices that are private to each instance.
> > 
> > You didn't add it to index.rst, so it won't actually become part of the
> > docs build.
> 
> I think you added it in the wrong place.
> 
> From 8167b80c950834da09a9204b6236f238197c197b Mon Sep 17 00:00:00 2001
> From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> Date: Tue, 2 Jul 2019 13:54:38 -0400
> Subject: [PATCH] docs: Move binderfs to admin-guide
> 
> The documentation is more appropriate for the administrator than for
> the internal kernel API section it is currently in.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Don't feel very strong about where this ends up. :)

Acked-by: Christian Brauner <christian@brauner.io>

> ---
>  .../{filesystems => admin-guide}/binderfs.rst          |  0
>  Documentation/admin-guide/index.rst                    |  1 +
>  Documentation/filesystems/index.rst                    | 10 ----------
>  3 files changed, 1 insertion(+), 10 deletions(-)
>  rename Documentation/{filesystems => admin-guide}/binderfs.rst (100%)
> 
> diff --git a/Documentation/filesystems/binderfs.rst b/Documentation/admin-guide/binderfs.rst
> similarity index 100%
> rename from Documentation/filesystems/binderfs.rst
> rename to Documentation/admin-guide/binderfs.rst
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 8001917ee012..24fbe0568eff 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
>     ras
>     bcache
>     ext4
> +   binderfs
>     pm/index
>     thunderbolt
>     LSM/index
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 1131c34d77f6..970c0a3ec377 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -31,13 +31,3 @@ filesystem implementations.
>  
>     journalling
>     fscrypt
> -
> -Filesystem-specific documentation
> -=================================
> -
> -Documentation for individual filesystem types can be found here.
> -
> -.. toctree::
> -   :maxdepth: 2
> -
> -   binderfs.rst
> -- 
> 2.20.1
> 

Re: [PATCH v1 1/2] Documentation/filesystems: add binderfs

[Jonathan Corbet]

On Tue, 2 Jul 2019 10:57:29 -0700
Matthew Wilcox <willy@infradead.org> wrote:

> I think you added it in the wrong place.
> 
> From 8167b80c950834da09a9204b6236f238197c197b Mon Sep 17 00:00:00 2001
> From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> Date: Tue, 2 Jul 2019 13:54:38 -0400
> Subject: [PATCH] docs: Move binderfs to admin-guide
> 
> The documentation is more appropriate for the administrator than for
> the internal kernel API section it is currently in.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Fine...applied...

jon