Documentation/admin-guide/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 stats
  37   Using ``stats=global`` enables global binder statistics.
  38   ``stats=global`` is only available for a binderfs instance mounted in the
  39   initial user namespace. An attempt to use the option to mount a binderfs
  40   instance in another user namespace will return a permission error.
  41
  42 Allocating binder Devices
  43 -------------------------
  44
  45 .. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
  46
  47 To allocate a new binder device in a binderfs instance a request needs to be
  48 sent through the ``binder-control`` device node.  A request is sent in the form
  49 of an `ioctl() <ioctl_>`_.
  50
  51 What a program needs to do is to open the ``binder-control`` device node and
  52 send a ``BINDER_CTL_ADD`` request to the kernel.  Users of binderfs need to
  53 tell the kernel which name the new binder device should get.  By default a name
  54 can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
  55 zero byte.
  56
  57 Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
  58 binder_device`` with the name to the kernel it will allocate a new binder
  59 device and return the major and minor number of the new device in the struct
  60 (This is necessary because binderfs allocates a major device number
  61 dynamically.).  After the `ioctl() <ioctl_>`_ returns there will be a new
  62 binder device located under /dev/binderfs with the chosen name.
  63
  64 Deleting binder Devices
  65 -----------------------
  66
  67 .. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
  68 .. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
  69
  70 Binderfs binder devices can be deleted via `unlink() <unlink_>`_.  This means
  71 that the `rm() <rm_>`_ tool can be used to delete them. Note that the
  72 ``binder-control`` device cannot be deleted since this would make the binderfs
  73 instance unusable.  The ``binder-control`` device will be deleted when the
  74 binderfs instance is unmounted and all references to it have been dropped.
  75
  76 Binder features
  77 ---------------
  78
  79 Assuming an instance of binderfs has been mounted at ``/dev/binderfs``, the
  80 features supported by the binder driver can be located under
  81 ``/dev/binderfs/features/``. The presence of individual files can be tested
  82 to determine whether a particular feature is supported by the driver.
  83
  84 Example::
  85
  86         cat /dev/binderfs/features/oneway_spam_detection
  87         1