[PATCH] 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@xxxxxxxxxx>
---
 Documentation/filesystems/binderfs.txt | 109 +++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 Documentation/filesystems/binderfs.txt

diff --git a/Documentation/filesystems/binderfs.txt b/Documentation/filesystems/binderfs.txt
new file mode 100644
index 000000000000..9c47eb33dd6a
--- /dev/null
+++ b/Documentation/filesystems/binderfs.txt
@@ -0,0 +1,109 @@
+
+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
+-------
+
+Android binderfs does currently not support mount options.
+
+Allocating binder Devices
+-------------------------
+
+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(2).  Hereâs an example program:
+
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+#include <linux/android/binder_ctl.h>
+
+int main(int argc, char *argv[])
+{
+        int fd, ret, saved_errno;
+        size_t len;
+        struct binderfs_device device = { 0 };
+
+        if (argc != 3)
+                exit(EXIT_FAILURE);
+
+        len = strlen(argv[2]);
+        if (len > BINDERFS_MAX_NAME)
+                exit(EXIT_FAILURE);
+
+        memcpy(device.name, argv[2], len);
+
+        fd = open(argv[1], O_RDONLY | O_CLOEXEC);
+        if (fd < 0) {
+                printf("%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) {
+                printf("%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);
+
+        exit(EXIT_SUCCESS);
+}
+
+What this program simply does is to open the binder-control device node and
+sending 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(2) 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 at boot.).  After
+the ioctl(2) returns there will be a new binder device located under
+/dev/binderfs with the chosen name.
+
+Deleting binder Devices
+-----------------------
+
+Binderfs binder devices can be deleted via unlink(2).  This means that the
+rm(1) 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