Notes about devices

A system describes the common peculiarities that are shared across the different devices and platforms. Options may be present to describe systemic differences or evolutionary changes in those systems' design.

Generally, a system describes the most basic requirements to boot devices, without caring for details that are platform-specific or device-specific.

When talking about a system, they are commonly referred as $system-based. For example, asus-z00t is an android-based system. Its system.type is android.

Examples of systems:

A platform describes the common features of a SoC^[1] disregarding the system it is used with. It is entirely expected that a single platform is used with a variety of systems.

The platform should set as few global options as possible, the most likely, and lone, option set should be the system used (e.g. aarch64-linux). A platform will also toggle quirks on and off, which are deficiencies that must be worked around specific to the platform.

Lastly, as an implementation detail, it is preferred to keep the platforms as precisely as possible, making a distinct platform even if it is technically the same as another one (e.g. Rockchip RK3399 ⇆ Rockchip OP-1). This allows better differentiation if, in the end, there is a tiny difference.

The names used should be the technical names, as best as possible. This is why the Qualcomm Snapdragon 615 is named Qualcomm MSM8939.

Examples of platforms:

A device is a somewhat specific description of a model of an appliance or a machine. Generally speaking, when a single build boots on two different SKUs without differentiation, they are the same device.

The oneplus-oneplus3 and oneplus-oneplus3t is a single device. Conversely, the google-taimen and google-walleye are distinct devices requiring a different kernel build (or software handling via kernel modules). The actual line where devices stop being devices and start becoming families is undefined, and undefinable. Though following the same kernel build boots them is likely a good differentiator.

When describing a device, a device is made by or for an OEM (e.g. ASUS, Google), has a name (e.g. Zenfone 2 Laser, Pixel 2), and generally has a codename (e.g. z00t, walleye). When talking about a device, it’s better to use the $oem-$codename pair (e.g. asus-z00t), as it describes the exact device more appropriately. Some OEMs re-use device names (e.g. Moto G). Additionally, those codenames are generally used to talk about the devices with Android ROM development, it ends up being useful to find resources about the device.

Examples of devices:

First of all, families are optional. Most devices will directly be implemented without a family in sight.

A family is best described as an incomplete device. Most of the device’s properties will be defined by the family, and only the last details will be described by the device.

Following from the previous example, google-walleye and google-taimen are different devices of the same family. They both are made by the same OEM, and share most configuration. The main differences here are the display size, and the kernel build used.

Examples of families: