Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/filesystems: add binderfs
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>
[jc: tweaked markup and added to filesystems/index.rst]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Christian Brauner
and committed by
Jonathan Corbet
35283f56
5591a307
+75
+68
Documentation/filesystems/binderfs.rst
+68
Documentation/filesystems/binderfs.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
The Android binderfs Filesystem
4
+
===============================
5
+
6
+
Android binderfs is a filesystem for the Android binder IPC mechanism. It
7
+
allows to dynamically add and remove binder devices at runtime. Binder devices
8
+
located in a new binderfs instance are independent of binder devices located in
9
+
other binderfs instances. Mounting a new binderfs instance makes it possible
10
+
to get a set of private binder devices.
11
+
12
+
Mounting binderfs
13
+
-----------------
14
+
15
+
Android binderfs can be mounted with::
16
+
17
+
mkdir /dev/binderfs
18
+
mount -t binder binder /dev/binderfs
19
+
20
+
at which point a new instance of binderfs will show up at ``/dev/binderfs``.
21
+
In a fresh instance of binderfs no binder devices will be present. There will
22
+
only be a ``binder-control`` device which serves as the request handler for
23
+
binderfs. Mounting another binderfs instance at a different location will
24
+
create a new and separate instance from all other binderfs mounts. This is
25
+
identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
26
+
binderfs filesystem can be mounted in user namespaces.
27
+
28
+
Options
29
+
-------
30
+
max
31
+
binderfs instances can be mounted with a limit on the number of binder
32
+
devices that can be allocated. The ``max=<count>`` mount option serves as
33
+
a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
34
+
of binder devices can be allocated in this binderfs instance.
35
+
36
+
Allocating binder Devices
37
+
-------------------------
38
+
39
+
.. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
40
+
41
+
To allocate a new binder device in a binderfs instance a request needs to be
42
+
sent through the ``binder-control`` device node. A request is sent in the form
43
+
of an `ioctl() <ioctl_>`_.
44
+
45
+
What a program needs to do is to open the ``binder-control`` device node and
46
+
send a ``BINDER_CTL_ADD`` request to the kernel. Users of binderfs need to
47
+
tell the kernel which name the new binder device should get. By default a name
48
+
can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
49
+
zero byte.
50
+
51
+
Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
52
+
binder_device`` with the name to the kernel it will allocate a new binder
53
+
device and return the major and minor number of the new device in the struct
54
+
(This is necessary because binderfs allocates a major device number
55
+
dynamically.). After the `ioctl() <ioctl_>`_ returns there will be a new
56
+
binder device located under /dev/binderfs with the chosen name.
57
+
58
+
Deleting binder Devices
59
+
-----------------------
60
+
61
+
.. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
62
+
.. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
63
+
64
+
Binderfs binder devices can be deleted via `unlink() <unlink_>`_. This means
65
+
that the `rm() <rm_>`_ tool can be used to delete them. Note that the
66
+
``binder-control`` device cannot be deleted since this would make the binderfs
67
+
instance unuseable. The ``binder-control`` device will be deleted when the
68
+
binderfs instance is unmounted and all references to it have been dropped.