Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) The Android binderfs Filesystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) Android binderfs is a filesystem for the Android binder IPC mechanism.  It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) allows to dynamically add and remove binder devices at runtime.  Binder devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) located in a new binderfs instance are independent of binder devices located in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) other binderfs instances.  Mounting a new binderfs instance makes it possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) to get a set of private binder devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Mounting binderfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Android binderfs can be mounted with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)   mkdir /dev/binderfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)   mount -t binder binder /dev/binderfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) at which point a new instance of binderfs will show up at ``/dev/binderfs``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) In a fresh instance of binderfs no binder devices will be present.  There will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) only be a ``binder-control`` device which serves as the request handler for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) binderfs. Mounting another binderfs instance at a different location will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) create a new and separate instance from all other binderfs mounts.  This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) identical to the behavior of e.g. ``devpts`` and ``tmpfs``. The Android
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) binderfs filesystem can be mounted in user namespaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) max
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)   binderfs instances can be mounted with a limit on the number of binder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)   devices that can be allocated. The ``max=<count>`` mount option serves as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)   a per-instance limit. If ``max=<count>`` is set then only ``<count>`` number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)   of binder devices can be allocated in this binderfs instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) stats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)   Using ``stats=global`` enables global binder statistics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)   ``stats=global`` is only available for a binderfs instance mounted in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)   initial user namespace. An attempt to use the option to mount a binderfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)   instance in another user namespace will return a permission error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Allocating binder Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) .. _ioctl: http://man7.org/linux/man-pages/man2/ioctl.2.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) To allocate a new binder device in a binderfs instance a request needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) sent through the ``binder-control`` device node.  A request is sent in the form
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) of an `ioctl() <ioctl_>`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) What a program needs to do is to open the ``binder-control`` device node and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) send a ``BINDER_CTL_ADD`` request to the kernel.  Users of binderfs need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) tell the kernel which name the new binder device should get.  By default a name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) can only contain up to ``BINDERFS_MAX_NAME`` chars including the terminating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) zero byte.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) Once the request is made via an `ioctl() <ioctl_>`_ passing a ``struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) binder_device`` with the name to the kernel it will allocate a new binder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) device and return the major and minor number of the new device in the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) (This is necessary because binderfs allocates a major device number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) dynamically.).  After the `ioctl() <ioctl_>`_ returns there will be a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) binder device located under /dev/binderfs with the chosen name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Deleting binder Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .. _unlink: http://man7.org/linux/man-pages/man2/unlink.2.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) .. _rm: http://man7.org/linux/man-pages/man1/rm.1.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Binderfs binder devices can be deleted via `unlink() <unlink_>`_.  This means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) that the `rm() <rm_>`_ tool can be used to delete them. Note that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ``binder-control`` device cannot be deleted since this would make the binderfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) instance unuseable.  The ``binder-control`` device will be deleted when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) binderfs instance is unmounted and all references to it have been dropped.