Merge tag 'libnvdimm-fixes-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel...
[sfrench/cifs-2.6.git] / 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.