1# Ueventd 2------- 3Ueventd manages `/dev`, sets permissions for `/sys`, and handles firmware uevents. It has default 4behavior described below, along with a scripting language that allows customizing this behavior, 5built on the same parser as init. 6 7Ueventd has one generic customization parameter, the size of rcvbuf_size for the ueventd socket. It 8is customized by the `uevent_socket_rcvbuf_size` parameter, which takes the format of 9 10 uevent_socket_rcvbuf_size <size> 11For example 12 13 uevent_socket_rcvbuf_size 16M 14Sets the uevent socket rcvbuf_size to 16 megabytes. 15 16## Importing configuration files 17-------------------------------- 18Ueventd reads /system/etc/ueventd.rc, all other files are imported via the `import` command, which 19takes the format of 20 21 import <path> 22This command parses an ueventd config file, extending the current configuration. If _path_ is a 23directory, each file in the directory is parsed as a config file. It is not recursive, nested 24directories will not be parsed. Imported files are parsed after the current file has been parsed. 25 26## /dev 27---- 28Ueventd listens to the kernel uevent sockets and creates/deletes nodes in `/dev` based on the 29incoming add/remove uevents. It defaults to using `0600` mode and `root` user/group. It always 30creates the nodes with the SELabel from the current loaded SEPolicy. It has three default behaviors 31for the node path: 32 33 1. Block devices are created as `/dev/block/<basename uevent DEVPATH>`. There are symlinks created 34 to this node at `/dev/block/<type>/<parent device>/<basename uevent DEVPATH>`, 35 `/dev/block/<type>/<parent device>/by-name/<uevent PARTNAME>`, and `/dev/block/by-name/<uevent 36 PARTNAME>` if the device is a boot device. 37 2. USB devices are created as `/dev/<uevent DEVNAME>` if `DEVNAME` was specified for the uevent, 38 otherwise as `/dev/bus/usb/<bus_id>/<device_id>` where `bus_id` is `uevent MINOR / 128 + 1` and 39 `device_id` is `uevent MINOR % 128 + 1`. 40 3. All other devices are created as `/dev/<basename uevent DEVPATH>` 41 42Whether a device is considered a "boot device" is a bit complicated. 43 44 - The recommended way to specify the boot device is to provide the "partition UUID" containing the 45 kernel (or, really, any parition on the boot device) and then boot device is the block device 46 containing that partition. This is passed via `androidboot.boot_part_uuid` which can be provided 47 either via the kernel bootconfig or via the kernel commandline. As an example, you could set 48 `androidboot.boot_part_uuid=12345678-abcd-ef01-0234-6789abcdef01`. 49 - Though using `boot_part_uuid` is preferred, you can also specify the boot device via 50 `androidboot.boot_device` or `androidboot.boot_devices`. These can be passed via the kernel 51 bootconfig or the kernel command line. It is also possible to pass this via device tree by 52 creating a `boot_devices` property in the Android firmware node. In most cases the `boot_device` 53 is the sysfs path (without the `/sys/devices` or `/sys/devices/platform` prefix) to the closest 54 parent of the block device that's on the "platform" bus. As an example, if the block device is 55 `/sys/devices/platform/soc@0/7c4000.mmc/mmc_host/mmc1/mmc1:0001/block/mmcblk1` then the 56 `boot_device` is `soc@0/7c4000.mmc` since we strip off the `/sys/devices/platform` and nothing 57 past the `7c4000.mmc` directory represents a device on the "platform" bus. In the case that none 58 of the parents are on the "platform" bus there are special rules for block devices under PCI 59 and VBD (Virtual Block Device). NOTE: sysfs paths for block devices are not guaranteed to be 60 stable between kernel versions, which is one of the reasons why it is suggested to use 61 `boot_part_uuid` instead of `boot_devices`. ALSO NOTE: If more than one device matches (either 62 because multiple `boot_devices` were listed or because there was more than one block device 63 under the found sysfs directory) and these multiple matching devices provide some of the same 64 named partitions then the behavior is unspecified. 65 - There is a further fallback to determine "boot devices" via the vstab, but providing at least 66 `boot_devices` has been required since Android 12 so this further fallback will not be described 67 here. 68 69The permissions can be modified using a ueventd.rc script and a line that beings with `/dev`. These 70lines take the format of 71 72 devname mode uid gid [options] 73For example 74 75 /dev/null 0666 root root 76When `/dev/null` is created, its mode will be set to `0666`, its user to `root` and its group to 77`root`. 78 79The path can be modified using a ueventd.rc script and a `subsystem` and/or `driver` section. 80There are three options to set for a subsystem or driver: the name, which device name to use, 81and which directory to place the device in. The section takes the below format of 82 83 subsystem <subsystem_name> 84 devname uevent_devname|uevent_devpath 85 [dirname <directory>] 86 87`subsystem_name` is used to match the uevent `SUBSYSTEM` value. 88 89`devname` takes one of three options: 90 1. `uevent_devname` specifies that the name of the node will be the uevent `DEVNAME` 91 2. `uevent_devpath` specifies that the name of the node will be basename uevent `DEVPATH` 92 3. `sys_name` specifies that the name of the node will be the contents of `/sys/DEVPATH/name` 93 94`dirname` is an optional parameter that specifies a directory within `/dev` where the node will be 95created. 96 97For example 98 99 subsystem sound 100 devname uevent_devpath 101 dirname /dev/snd 102indicates that all uevents with `SUBSYSTEM=sound` will create nodes as `/dev/snd/<basename uevent 103DEVPATH>`. 104 105The `driver` section has the exact same structure as a `subsystem` section, but 106will instead match the `DRIVER` value in a `bind`/`unbind` uevent. However, the 107`driver` section will be ignored for block devices. 108 109## /sys 110---- 111Ueventd by default takes no action for `/sys`, however it can be instructed to set permissions for 112certain files in `/sys` when matching uevents are generated. This is done using a ueventd.rc script 113and a line that begins with `/sys`. These lines take the format of 114 115 nodename attr mode uid gid [options] 116For example 117 118 /sys/devices/system/cpu/cpu* cpufreq/scaling_max_freq 0664 system system 119When a uevent that matches the pattern `/sys/devices/system/cpu/cpu*` is sent, the matching sysfs 120attribute, `cpufreq/scaling_max_freq`, will have its mode set to `0664`, its user to to `system` and 121its group set to `system`. 122 123## Path matching 124---------------- 125The path for a `/dev` or `/sys` entry can contain a `*` anywhere in the path. 1261. If the only `*` appears at the end of the string or if the _options_ parameter is set to 127`no_fnm_pathname`, ueventd matches the entry by `fnmatch(entry_path, incoming_path, 0)` 1282. Otherwise, ueventd matches the entry by `fnmatch(entry_path, incoming_path, FNM_PATHNAME)` 129 130See the [man page for fnmatch](https://www.man7.org/linux/man-pages/man3/fnmatch.3.html) for more 131details. 132 133## Firmware loading 134---------------- 135Ueventd by default serves firmware requests by searching through a list of firmware directories 136for a file matching the uevent `FIRMWARE`. It then forks a process to serve this firmware to the 137kernel. 138 139`/apex/*/etc/firmware` is also searched after a list of firmware directories. 140 141The list of firmware directories is customized by a `firmware_directories` line in a ueventd.rc 142file. This line takes the format of 143 144 firmware_directories <firmware_directory> [ <firmware_directory> ]* 145For example 146 147 firmware_directories /etc/firmware/ /odm/firmware/ /vendor/firmware/ /firmware/image/ 148Adds those 4 directories, in that order to the list of firmware directories that will be tried by 149ueventd. Note that this option always accumulates to the list; it is not possible to remove previous 150entries. 151 152Ueventd will wait until after `post-fs` in init, to keep retrying before believing the firmwares are 153not present. 154 155The exact firmware file to be served can be customized by running an external program by a 156`external_firmware_handler` line in a ueventd.rc file. This line takes the format of 157 158 external_firmware_handler <devpath> <user [group]> <path to external program> 159 160The handler will be run as the given user, or if a group is provided, as the given user and group. 161 162For example 163 164 external_firmware_handler /devices/leds/red/firmware/coeffs.bin system /vendor/bin/led_coeffs.bin 165Will launch `/vendor/bin/led_coeffs.bin` as the system user instead of serving the default firmware 166for `/devices/leds/red/firmware/coeffs.bin`. 167 168The `devpath` argument may include asterisks (`*`) to match multiple paths. For example, the string 169`/dev/*/red` will match `/dev/leds/red` as well as `/dev/lights/red`. The pattern matching follows 170the rules of the fnmatch() function. 171 172Ueventd will provide the uevent `DEVPATH` and `FIRMWARE` to this external program on the environment 173via environment variables with the same names. Ueventd will use the string written to stdout as the 174new name of the firmware to load. It will still look for the new firmware in the list of firmware 175directories stated above. It will also reject file names with `..` in them, to prevent leaving these 176directories. If stdout cannot be read, or the program returns with any exit code other than 177`EXIT_SUCCESS`, or the program crashes, the default firmware from the uevent will be loaded. 178 179Ueventd will additionally log all messages sent to stderr from the external program to the serial 180console after the external program has exited. 181 182If the kernel command-line argument `firmware_class.path` is set, this path 183will be used first by the kernel to search for the firmware files. If found, 184ueventd will not be called at all. See the 185[kernel documentation](https://www.kernel.org/doc/html/v5.10/driver-api/firmware/fw_search_path.html) 186for more details on this feature. 187 188## Coldboot 189-------- 190Ueventd must create devices in `/dev` for all devices that have already sent their uevents before 191ueventd has started. To do so, when ueventd is started it does what it calls a 'coldboot' on `/sys`, 192in which it writes 'add' to every 'uevent' file that it finds in `/sys/class`, `/sys/block`, and 193`/sys/devices`. This causes the kernel to regenerate the uevents for these paths, and thus for 194ueventd to create the nodes. 195 196For boot time purposes, this is done in parallel across a set of child processes. `ueventd.cpp` in 197this directory contains documentation on how the parallelization is done. 198 199There is an option to parallelize the restorecon function during cold boot as well. It is 200recommended that devices use genfscon for labeling sysfs nodes. However, some devices may benefit 201from enabling the parallelization option: 202 203 parallel_restorecon enabled 204 205Do parallel restorecon to speed up boot process, subdirectories under `/sys` 206can be sliced by ueventd.rc, and run on multiple process. 207 parallel_restorecon_dir <directory> 208 209For example 210 parallel_restorecon_dir /sys 211 parallel_restorecon_dir /sys/devices 212 parallel_restorecon_dir /sys/devices/platform 213 parallel_restorecon_dir /sys/devices/platform/soc 214