ACPR/android_system_core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
android_system_core/init/README.ueventd.md
Douglas Anderson e9de310061 init: Add the ability to find the boot device by partition UUID 
The current mechanism for specifying boot devices on Android systems
involves passing a set of "boot_devices" though command line,
bootconfig, or device tree.

The bootdevices are specified as strings and, in general, need to
match a sysfs path but without the "/sys/devices" or
"/sys/devices/platform" prefix. The sysfs path is generally the path
to the closest parent of the block device that is a "platform" device.

As an example, if the sysfs path of the expected boot device is:
  /sys/devices/platform/soc@0/7c4000.mmc/mmc_host/mmc1/mmc1:0001/block/mmcblk1

The bootloader would specify it as "soc@0/7c4000.mmc" since:
* We strip off "/sys/devices/platform/"
* As we move up directories, we don't find one whose subsystem is
  "platform" until we get up to
  "/sys/devices/platform/soc@0/7c4000.mmc".

The current mechanism is a bit brittle. Specifically:
* The sysfs path isn't _really_ stable and can change across kernel
  upgrades. For instance, during one kernel upgrade the device tree
  for a product changed so that the root node changed from "soc" to
  "soc@0" and this changed all sysfs paths. In the past device tree
  folks have asserted that we shouldn't rely on dts node names to stay
  consistent, yet those node names are used to construct sysfs paths.
* For some devices, like USB, the path of the closest "platform"
  device tends to be the path of the USB controller. This means that
  if two USB disks are plugged in we can't guarantee which one will be
  identified as the boot device.

Add a new method of finding the boot device by passing the partition
UUID that we loaded the kernel from. Using the partition UUID to
identify the boot device is standard on Linux. You can see this
because when you're not using an initramfs you can use the syntax
"root=PARTUUID=<valid-uuid-id>[/PARTNROFF=n]" to specify the root.
Using the same idea for Android's boot code makes sense.

With this new method for finding the boot device, we can make the code
much more specific about matching sysfs paths. Once we find the sysfs
path for the kernel we can make sure that all of the other boot
partition share the same "scsi" or "mmc" parent instead of going all
the way to the closest platform device. In the above example, this
means that we'd make sure that all boot devices are found under this
sysfs node:
  /sys/devices/platform/soc@0/7c4000.mmc/mmc_host/mmc1/mmc1:0001/block/mmcblk1
...instead of just making sure they are under:
  /sys/devices/platform/soc@0/7c4000.mmc

There is the question of what we should do if the bootloader passes
_both_ an old style "boot_devices" and also a partition UUID. In this
case, we'll issue a warning and then ignore the old "boot_devices".
Considering it a warning rather than an error could allow switching to
the "boot_part_uuid" method even if an old bootloader is still
hardcoding some old "boot_devices".

NOTE: Using partition UUID won't cause any security problems even
though someone _could_ plug in an external device crafted to have the
same UUID as the normal boot device's kernel partition. We already
have "verity" in the system making sure our filesystems are not
tampered with and this would also protect us from booting a tampered
disk. That means that the worst someone could do in this case would be
to confuse the system and make the device non-bootable. Chromebooks
have been using the partition UUID to find the root filesystems for
years and this has never been a problem.

NOTE: this new method relies on the commit ("init: Add partition_uuid
to Uevent") which in turn relies upstream kernel commit 74f4a8dc0dd8
("block: add partition uuid into uevent as "PARTUUID"").

Bug: 316324155
Test: Use partition UUID to boot

Change-Id: If824cb700ca3696a442a28e6ad02d7c522c3b495
2024-11-06 13:03:15 -08:00

11 KiB
Raw Blame History

Ueventd

Ueventd manages /dev, sets permissions for /sys, and handles firmware uevents. It has default behavior described below, along with a scripting language that allows customizing this behavior, built on the same parser as init.

Ueventd has one generic customization parameter, the size of rcvbuf_size for the ueventd socket. It is customized by the uevent_socket_rcvbuf_size parameter, which takes the format of

uevent_socket_rcvbuf_size <size>

For example

uevent_socket_rcvbuf_size 16M

Sets the uevent socket rcvbuf_size to 16 megabytes.

Importing configuration files

Ueventd reads /system/etc/ueventd.rc, all other files are imported via the import command, which takes the format of

import <path>

This command parses an ueventd config file, extending the current configuration. If path is a directory, each file in the directory is parsed as a config file. It is not recursive, nested directories will not be parsed. Imported files are parsed after the current file has been parsed.

/dev

Ueventd listens to the kernel uevent sockets and creates/deletes nodes in /dev based on the incoming add/remove uevents. It defaults to using 0600 mode and root user/group. It always creates the nodes with the SELabel from the current loaded SEPolicy. It has three default behaviors for the node path:

  1. Block devices are created as /dev/block/<basename uevent DEVPATH>. There are symlinks created to this node at /dev/block/<type>/<parent device>/<basename uevent DEVPATH>, /dev/block/<type>/<parent device>/by-name/<uevent PARTNAME>, and /dev/block/by-name/<uevent PARTNAME> if the device is a boot device.
  2. USB devices are created as /dev/<uevent DEVNAME> if DEVNAME was specified for the uevent, otherwise as /dev/bus/usb/<bus_id>/<device_id> where bus_id is uevent MINOR / 128 + 1 and device_id is uevent MINOR % 128 + 1.
  3. All other devices are created as /dev/<basename uevent DEVPATH>

Whether a device is considered a "boot device" is a bit complicated.

  • The recommended way to specify the boot device is to provide the "partition UUID" containing the kernel (or, really, any parition on the boot device) and then boot device is the block device containing that partition. This is passed via androidboot.boot_part_uuid which can be provided either via the kernel bootconfig or via the kernel commandline. As an example, you could set androidboot.boot_part_uuid=12345678-abcd-ef01-0234-6789abcdef01.
  • Though using boot_part_uuid is preferred, you can also specify the boot device via androidboot.boot_device or androidboot.boot_devices. These can be passed via the kernel bootconfig or the kernel command line. It is also possible to pass this via device tree by creating a boot_devices property in the Android firmware node. In most cases the boot_device is the sysfs path (without the /sys/devices or /sys/devices/platform prefix) to the closest parent of the block device that's on the "platform" bus. As an example, if the block device is /sys/devices/platform/soc@0/7c4000.mmc/mmc_host/mmc1/mmc1:0001/block/mmcblk1 then the boot_device is soc@0/7c4000.mmc since we strip off the /sys/devices/platform and nothing past the 7c4000.mmc directory represents a device on the "platform" bus. In the case that none of the parents are on the "platform" bus there are special rules for block devices under PCI and VBD (Virtual Block Device). NOTE: sysfs paths for block devices are not guaranteed to be stable between kernel versions, which is one of the reasons why it is suggested to use boot_part_uuid instead of boot_devices. ALSO NOTE: If more than one device matches (either because multiple boot_devices were listed or because there was more than one block device under the found sysfs directory) and these multiple matching devices provide some of the same named partitions then the behavior is unspecified.
  • There is a further fallback to determine "boot devices" via the vstab, but providing at least boot_devices has been required since Android 12 so this further fallback will not be described here.

The permissions can be modified using a ueventd.rc script and a line that beings with /dev. These lines take the format of

devname mode uid gid [options]

For example

/dev/null 0666 root root

When /dev/null is created, its mode will be set to 0666, its user to root and its group to root.

The path can be modified using a ueventd.rc script and a subsystem section. There are three to set for a subsystem: the subsystem name, which device name to use, and which directory to place the device in. The section takes the below format of

subsystem <subsystem_name>
  devname uevent_devname|uevent_devpath
  [dirname <directory>]

subsystem_name is used to match uevent SUBSYSTEM value

devname takes one of three options

  1. uevent_devname specifies that the name of the node will be the uevent DEVNAME
  2. uevent_devpath specifies that the name of the node will be basename uevent DEVPATH
  3. sys_name specifies that the name of the node will be the contents of /sys/DEVPATH/name

dirname is an optional parameter that specifies a directory within /dev where the node will be created.

For example

subsystem sound
  devname uevent_devpath
  dirname /dev/snd

Indicates that all uevents with SUBSYSTEM=sound will create nodes as /dev/snd/<basename uevent DEVPATH>.

/sys

Ueventd by default takes no action for /sys, however it can be instructed to set permissions for certain files in /sys when matching uevents are generated. This is done using a ueventd.rc script and a line that begins with /sys. These lines take the format of

nodename attr mode uid gid [options]

For example

/sys/devices/system/cpu/cpu* cpufreq/scaling_max_freq 0664 system system

When a uevent that matches the pattern /sys/devices/system/cpu/cpu* is sent, the matching sysfs attribute, cpufreq/scaling_max_freq, will have its mode set to 0664, its user to to system and its group set to system.

Path matching

The path for a /dev or /sys entry can contain a * anywhere in the path.

  1. If the only * appears at the end of the string or if the options parameter is set to no_fnm_pathname, ueventd matches the entry by fnmatch(entry_path, incoming_path, 0)
  2. Otherwise, ueventd matches the entry by fnmatch(entry_path, incoming_path, FNM_PATHNAME)

See the man page for fnmatch for more details.

Firmware loading

Ueventd by default serves firmware requests by searching through a list of firmware directories for a file matching the uevent FIRMWARE. It then forks a process to serve this firmware to the kernel.

/apex/*/etc/firmware is also searched after a list of firmware directories.

The list of firmware directories is customized by a firmware_directories line in a ueventd.rc file. This line takes the format of

firmware_directories <firmware_directory> [ <firmware_directory> ]*

For example

firmware_directories /etc/firmware/ /odm/firmware/ /vendor/firmware/ /firmware/image/

Adds those 4 directories, in that order to the list of firmware directories that will be tried by ueventd. Note that this option always accumulates to the list; it is not possible to remove previous entries.

Ueventd will wait until after post-fs in init, to keep retrying before believing the firmwares are not present.

The exact firmware file to be served can be customized by running an external program by a external_firmware_handler line in a ueventd.rc file. This line takes the format of

external_firmware_handler <devpath> <user [group]> <path to external program>

The handler will be run as the given user, or if a group is provided, as the given user and group.

For example

external_firmware_handler /devices/leds/red/firmware/coeffs.bin system /vendor/bin/led_coeffs.bin

Will launch /vendor/bin/led_coeffs.bin as the system user instead of serving the default firmware for /devices/leds/red/firmware/coeffs.bin.

The devpath argument may include asterisks (*) to match multiple paths. For example, the string /dev/*/red will match /dev/leds/red as well as /dev/lights/red. The pattern matching follows the rules of the fnmatch() function.

Ueventd will provide the uevent DEVPATH and FIRMWARE to this external program on the environment via environment variables with the same names. Ueventd will use the string written to stdout as the new name of the firmware to load. It will still look for the new firmware in the list of firmware directories stated above. It will also reject file names with .. in them, to prevent leaving these directories. If stdout cannot be read, or the program returns with any exit code other than EXIT_SUCCESS, or the program crashes, the default firmware from the uevent will be loaded.

Ueventd will additionally log all messages sent to stderr from the external program to the serial console after the external program has exited.

If the kernel command-line argument firmware_class.path is set, this path will be used first by the kernel to search for the firmware files. If found, ueventd will not be called at all. See the kernel documentation for more details on this feature.

Coldboot

Ueventd must create devices in /dev for all devices that have already sent their uevents before ueventd has started. To do so, when ueventd is started it does what it calls a 'coldboot' on /sys, in which it writes 'add' to every 'uevent' file that it finds in /sys/class, /sys/block, and /sys/devices. This causes the kernel to regenerate the uevents for these paths, and thus for ueventd to create the nodes.

For boot time purposes, this is done in parallel across a set of child processes. ueventd.cpp in this directory contains documentation on how the parallelization is done.

There is an option to parallelize the restorecon function during cold boot as well. It is recommended that devices use genfscon for labeling sysfs nodes. However, some devices may benefit from enabling the parallelization option:

parallel_restorecon enabled

Do parallel restorecon to speed up boot process, subdirectories under /sys can be sliced by ueventd.rc, and run on multiple process. parallel_restorecon_dir

For example parallel_restorecon_dir /sys parallel_restorecon_dir /sys/devices parallel_restorecon_dir /sys/devices/platform parallel_restorecon_dir /sys/devices/platform/soc