In Fuchsia, hardware support can be divided per architecture, board and drivers, see RFC-0111: Initial Fuchsia hardware platform specifications. Adding support for a new architecture is not described on this page. This page describes adding support for a new board.
Note that the x64 architecture is considered in itself a board (highly configurable one) hence it is not described here since it is already supported (although its implementation can be improved and support for more configurations that don’t currently work added).
To add support for a new board, first we need to add support for the bringup build product configuration.
To get a bringup build working, you need:
See RFC-0111: Initial Fuchsia hardware platform specifications for the architecture support process.
A new board requires a way to load the kernel, ideally with a bootloader supporting Fuchsia. Also the kernel requires support for at least an early stage debugging mechanism (e.g. serial port), interrupt controller and timers, this in the form of kernel drivers.
The board must include a mechanism to program it (e.g. store contents in flash). This is needed to make updates to the bootloader. The Fuchsia image could be programmed with this mechanism or with support provided by the bootloader.
In this document, the bootloader refers to the final stage bootloader, which is the software component of the boot process that loads the Fuchsia kernel.
There are multiple configurations that would allow a bootloader to load a Fuchsia kernel:
Notes:
In Fuchsia most drivers are in user space, however the ones listed in this section must be present in the kernel.
Some early stage debugging mechanism is required for bringup of a new board, for instance serial port or JTAG. If serial port is the mechanism then a UART driver must be added if not already available in the kernel, for instance here. ARM’s interrupt controller and timer support are also added with drivers, for instance gicv3 and generic timer.
All these drivers need to be configured to be used by the kernel. If the kernel was booted by a bootloader that supports fuchsia, the drivers will be configured in the ZBI, for example in U-Boot here. If the kernel was booted with a boot shim, the drivers will be configured in the shim itself, for instance for the MediaTek 8167 board here.
Notes:
In order to add support for a new board, a new board configuration needs to be added to the build system (gn). For instance for VIM3 the board_bootfs_labels
gn variable (defined here) defines what gets loaded in a bringup (into bootfs) build including the non-kernel drivers described below.
With the addition of the board configuration it is possible to instruct the build system to create an image for the new board. For example: fx set bringup.vim3
followed by fx build
(see fx workflows).
With this in place a bringup build for the new board can be loaded into the target and we can get a shell in the serial port (if the kernel serial port driver was added). The next step is to add a board driver and its corresponding non-kernel drivers for additional functionality.
With kernel support added for the board and build system assembly in place, a board driver (examples here) must be created to, at runtime, add and configure the non-kernel drivers to be used. The board driver describes and configures a board’s HW that can’t be located/configured by probing, which is common in ARM64 based systems.
Notes:
Regular non-kernel drivers can then be added to support the board, for example to support GPIOs, interrupts, clocks, power, storage devices, audio devices, displays, GPUs, etc. For more information see here.
Notes:
Once the bringup builds work, you need to add support for the core build product configuration to create a self-updating system with core system services, connectivity, and metrics reporting.
In order to enable a core build you need to have a working network stack given that this is how the core build allows for system debugging (for instance with fx log
and fx shell
), updates (for instance with fx ota
), and metrics reporting (for instance with fx snapshot
).
Once core builds work, a full system can be integrated by defining a new product configuration. For instance for x64 we already define workstation which includes a web browser and many other features. Similarly new product configurations can be added for other architectures, for instance for ARM64 based systems.