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## /dev 17---- 18Ueventd listens to the kernel uevent sockets and creates/deletes nodes in `/dev` based on the 19incoming add/remove uevents. It defaults to using `0600` mode and `root` user/group. It always 20creates the nodes with the SELabel from the current loaded SEPolicy. It has three default behaviors 21for the node path: 22 23 1. Block devices are created as `/dev/block/<basename uevent DEVPATH>`. There are symlinks created 24 to this node at `/dev/block/<type>/<parent device>/<basename uevent DEVPATH>`, 25 `/dev/block/<type>/<parent device>/by-name/<uevent PARTNAME>`, and `/dev/block/by-name/<uevent 26 PARTNAME>` if the device is a boot device. 27 2. USB devices are created as `/dev/<uevent DEVNAME>` if `DEVNAME` was specified for the uevent, 28 otherwise as `/dev/bus/usb/<bus_id>/<device_id>` where `bus_id` is `uevent MINOR / 128 + 1` and 29 `device_id` is `uevent MINOR % 128 + 1`. 30 3. All other devices are created as `/dev/<basename uevent DEVPATH>` 31 32The permissions can be modified using a ueventd.rc script and a line that beings with `/dev`. These 33lines take the format of 34 35 devname mode uid gid 36For example 37 38 /dev/null 0666 root root 39When `/dev/null` is created, its mode will be set to `0666`, its user to `root` and its group to 40`root`. 41 42The path can be modified using a ueventd.rc script and a `subsystem` section. There are three to set 43for a subsystem: the subsystem name, which device name to use, and which directory to place the 44device in. The section takes the below format of 45 46 subsystem <subsystem_name> 47 devname uevent_devname|uevent_devpath 48 [dirname <directory>] 49 50`subsystem_name` is used to match uevent `SUBSYSTEM` value 51 52`devname` takes one of two options 53 1. `uevent_devname` specifies that the name of the node will be the uevent `DEVNAME` 54 2. `uevent_devpath` specified that the name of the node will be basename uevent `DEVPATH` 55 56`dirname` is an optional parameter that specifies a directory within `/dev` where the node will be 57created. 58 59For example 60 61 subsystem sound 62 devname uevent_devpath 63 dirname /dev/snd 64Indicates that all uevents with `SUBSYSTEM=sound` will create nodes as `/dev/snd/<basename uevent 65DEVPATH>`. 66 67## /sys 68---- 69Ueventd by default takes no action for `/sys`, however it can be instructed to set permissions for 70certain files in `/sys` when matching uevents are generated. This is done using a ueventd.rc script 71and a line that begins with `/sys`. These lines take the format of 72 73 nodename attr mode uid gid 74For example 75 76 /sys/devices/system/cpu/cpu* cpufreq/scaling_max_freq 0664 system system 77When a uevent that matches the pattern `/sys/devices/system/cpu/cpu*` is sent, the matching sysfs 78attribute, `cpufreq/scaling_max_freq`, will have its mode set to `0664`, its user to to `system` and 79its group set to `system`. 80 81Note that `*` matches as a wildcard and can be used anywhere in a path. 82 83## Firmware loading 84---------------- 85Ueventd by default serves firmware requests by searching through a list of firmware directories 86for a file matching the uevent `FIRMWARE`. It then forks a process to serve this firmware to the 87kernel. 88 89The list of firmware directories is customized by a `firmware_directories` line in a ueventd.rc 90file. This line takes the format of 91 92 firmware_directories <firmware_directory> [ <firmware_directory> ]* 93For example 94 95 firmware_directories /etc/firmware/ /odm/firmware/ /vendor/firmware/ /firmware/image/ 96Adds those 4 directories, in that order to the list of firmware directories that will be tried by 97ueventd. Note that this option always accumulates to the list; it is not possible to remove previous 98entries. 99 100Ueventd will wait until after `post-fs` in init, to keep retrying before believing the firmwares are 101not present. 102 103The exact firmware file to be served can be customized by running an external program by a 104`external_firmware_handler` line in a ueventd.rc file. This line takes the format of 105 106 external_firmware_handler <devpath> <user name to run as> <path to external program> 107For example 108 109 external_firmware_handler /devices/leds/red/firmware/coeffs.bin system /vendor/bin/led_coeffs.bin 110Will launch `/vendor/bin/led_coeffs.bin` as the system user instead of serving the default firmware 111for `/devices/leds/red/firmware/coeffs.bin`. 112 113Ueventd will provide the uevent `DEVPATH` and `FIRMWARE` to this external program on the environment 114via environment variables with the same names. Ueventd will use the string written to stdout as the 115new name of the firmware to load. It will still look for the new firmware in the list of firmware 116directories stated above. It will also reject file names with `..` in them, to prevent leaving these 117directories. If stdout cannot be read, or the program returns with any exit code other than 118`EXIT_SUCCESS`, or the program crashes, the default firmware from the uevent will be loaded. 119 120Ueventd will additionally log all messages sent to stderr from the external program to the serial 121console after the external program has exited. 122 123## Coldboot 124-------- 125Ueventd must create devices in `/dev` for all devices that have already sent their uevents before 126ueventd has started. To do so, when ueventd is started it does what it calls a 'coldboot' on `/sys`, 127in which it writes 'add' to every 'uevent' file that it finds in `/sys/class`, `/sys/block`, and 128`/sys/devices`. This causes the kernel to regenerate the uevents for these paths, and thus for 129ueventd to create the nodes. 130 131For boot time purposes, this is done in parallel across a set of child processes. `ueventd.cpp` in 132this directory contains documentation on how the parallelization is done. 133 134There is an option to parallelize the restorecon function during cold boot as well. This should only 135be done for devices that do not use genfscon, which is the recommended method for labeling sysfs 136nodes. To enable this option, use the below line in a ueventd.rc script: 137 138 parallel_restorecon enabled 139