0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 The Android binderfs Filesystem
0004 ===============================
0005
0006 Android binderfs is a filesystem for the Android binder IPC mechanism. It
0007 allows to dynamically add and remove binder devices at runtime. Binder devices
0008 located in a new binderfs instance are independent of binder devices located in
0009 other binderfs instances. Mounting a new binderfs instance makes it possible
0010 to get a set of private binder devices.
0011
0012 Mounting binderfs
0013 -----------------
0014
0015 Android binderfs can be mounted with::
0016
0017 mkdir /dev/binderfs
0018 mount -t binder binder /dev/binderfs
0019
0020 at which point a new instance of binderfs will show up at ``/dev/binderfs``.
0021 In a fresh instance of binderfs no binder devices will be present. There will
0022 only be a ``binder-control`` device which serves as the request handler for
0023 binderfs. Mounting another binderfs instance at a different location will
0024 create a new and separate instance from all other binderfs mounts. This is
0025 identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
0026 binderfs filesystem can be mounted in user namespaces.
0027
0028 Options
0029 -------
0030 max
0031 binderfs instances can be mounted with a limit on the number of binder
0032 devices that can be allocated. The ``max=<count>`` mount option serves as
0033 a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
0034 of binder devices can be allocated in this binderfs instance.
0035
0036 stats
0037 Using ``stats=global`` enables global binder statistics.
0038 ``stats=global`` is only available for a binderfs instance mounted in the
0039 initial user namespace. An attempt to use the option to mount a binderfs
0040 instance in another user namespace will return a permission error.
0041
0042 Allocating binder Devices
0043 -------------------------
0044
0045 .. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
0046
0047 To allocate a new binder device in a binderfs instance a request needs to be
0048 sent through the ``binder-control`` device node. A request is sent in the form
0049 of an `ioctl() <ioctl_>`_.
0050
0051 What a program needs to do is to open the ``binder-control`` device node and
0052 send a ``BINDER_CTL_ADD`` request to the kernel. Users of binderfs need to
0053 tell the kernel which name the new binder device should get. By default a name
0054 can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
0055 zero byte.
0056
0057 Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
0058 binder_device`` with the name to the kernel it will allocate a new binder
0059 device and return the major and minor number of the new device in the struct
0060 (This is necessary because binderfs allocates a major device number
0061 dynamically.). After the `ioctl() <ioctl_>`_ returns there will be a new
0062 binder device located under /dev/binderfs with the chosen name.
0063
0064 Deleting binder Devices
0065 -----------------------
0066
0067 .. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
0068 .. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
0069
0070 Binderfs binder devices can be deleted via `unlink() <unlink_>`_. This means
0071 that the `rm() <rm_>`_ tool can be used to delete them. Note that the
0072 ``binder-control`` device cannot be deleted since this would make the binderfs
0073 instance unusable. The ``binder-control`` device will be deleted when the
0074 binderfs instance is unmounted and all references to it have been dropped.
0075
0076 Binder features
0077 ---------------
0078
0079 Assuming an instance of binderfs has been mounted at ``/dev/binderfs``, the
0080 features supported by the binder driver can be located under
0081 ``/dev/binderfs/features/``. The presence of individual files can be tested
0082 to determine whether a particular feature is supported by the driver.
0083
0084 Example::
0085
0086 cat /dev/binderfs/features/oneway_spam_detection
0087 1
