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
