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 <[email protected]>
---
/* 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
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 <[email protected]>
---
/* 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
On Fri, 11 Jan 2019 14:40:59 +0100
Christian Brauner <[email protected]> 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 <[email protected]>
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
On Mon, Jan 14, 2019 at 05:24:01PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 14:40:59 +0100
> Christian Brauner <[email protected]> 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 <[email protected]>
>
> 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
On Mon, Jan 14, 2019 at 05:24:01PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 14:40:59 +0100
> Christian Brauner <[email protected]> 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)" <[email protected]>
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) <[email protected]>
---
.../{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
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 <[email protected]> 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)" <[email protected]>
> 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) <[email protected]>
Don't feel very strong about where this ends up. :)
Acked-by: Christian Brauner <[email protected]>
> ---
> .../{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
>
On Tue, 2 Jul 2019 10:57:29 -0700
Matthew Wilcox <[email protected]> wrote:
> I think you added it in the wrong place.
>
> From 8167b80c950834da09a9204b6236f238197c197b Mon Sep 17 00:00:00 2001
> From: "Matthew Wilcox (Oracle)" <[email protected]>
> 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) <[email protected]>
Fine...applied...
jon