383 lines
16 KiB
Plaintext
383 lines
16 KiB
Plaintext
Runtime Machine Configuration (RMC)
|
|
--------------------------------------------------------------------------------
|
|
Table of Contents
|
|
|
|
Introduction
|
|
Usage
|
|
Enable RMC Feature
|
|
Examples
|
|
Troubleshooting
|
|
When you (don't) need RMC feature
|
|
|
|
|
|
Introduction:
|
|
--------------------------------------------------------------------------------
|
|
RMC Project - a light-weight project provide developers a mechanism to keep
|
|
their software implementation board-type agnostic, yet still able to customize
|
|
software behavior according to the type of a running board at runtime. Recipes
|
|
and bbclasses are available for other components to reuse to construct their own
|
|
RMC database.
|
|
|
|
RMC Feature - An end-to-end solution based on RMC project to have a generic
|
|
image capable to apply board-type-specific quirks and configurations for a board
|
|
at runtime. It consists of a modified bootloader (systemd-boot), an updated EFI
|
|
installer, recipes, bbclass and RMC project.
|
|
|
|
RMC feature supports special customizations cannot be covered by conventional
|
|
auto-detection features based on probing a hardware module because they happen
|
|
at a board or a product level. For example:
|
|
- tty console for kernel log output in kernel cmdline
|
|
- default audio route configuration
|
|
- network configuration
|
|
- UI layout
|
|
- requirement to software driven by a mechanical design
|
|
- or static configuration bits for a physical bus that doesn't support to
|
|
identify devices or their presence at runtime
|
|
|
|
An image with the feature has ability to configure supported boards with data
|
|
associated only to a type of board to get full functionality of the target at
|
|
runtime, yet still with a single image.
|
|
|
|
Effect after installation is identical to what a conventional image specially
|
|
customized for a type of board (depending on the way to deploy image).
|
|
|
|
Main functions of RMC Feature:
|
|
|
|
Show board-specific boot entries in boot menu and boot system with configuration
|
|
(boot title, boot options, etc) in a selected boot entry.
|
|
|
|
Support a "global" kernel boot command line fragment which is effective for all
|
|
boot entries.
|
|
|
|
Deploy file blobs and create directories specific to the type of running board.
|
|
|
|
Beside from this document, you can also find several built-in examples in
|
|
common/recipes-bsp/rmc/boards/. Refer to "Examples" section.
|
|
|
|
You can also add new board types in your layer via a simple variable.
|
|
|
|
|
|
|
|
Usage
|
|
--------------------------------------------------------------------------------
|
|
Developers are suggested to organize all board-specific files in their own layer
|
|
following this example, so that RMC recipes can pick up them correctly in build.
|
|
|
|
- my_top_dir/ Top directory of your board (Note 0)
|
|
|- rmc-db.bbappend bbappend file to rmc-db recipe at a lower level
|
|
|- rmc/
|
|
|- target_board_1/ subdirectory of a board.
|
|
| |- board1.fp fingerprint file must be provided (NOTE 1)
|
|
| |- BOOTENTRY.CONFIG optional config file for boot entries. (NOTE 2)
|
|
| |- INSTALLER.CONFIG optional config file for installer. (NOTE 3)
|
|
| |- POSTINSTALL.sh optional script hook for installer (NOTE 4)
|
|
| |- board_file_1 A file blob specific to the type of board
|
|
| |- board_file_2 An another file specific to the type of board
|
|
| |- ...more files
|
|
|- target_board_2/ subdirectory of another board.
|
|
|- board_2_v2.fp fingerprint file for board 2.
|
|
|- BOOTENTRY.CONFIG
|
|
|- INSTALLER.CONFIG
|
|
|- board_file_1
|
|
|- ...more files
|
|
|
|
Note 0:
|
|
Developers are expected to use variable RMC_BOARD_DATA_DIRS to specify data of
|
|
boards packed into RMC database file generated in a build. The default value of
|
|
the variable in meta-intel specifies a group of boards. They work as examples
|
|
and necessary quirks for these boards to function properly. Developers can
|
|
override, append to the default boards with data of their own boards in the
|
|
database file, or even disable the generation of the database file.
|
|
|
|
For example, in your local.conf file:
|
|
|
|
This line adds your boards along with the default boards into RMC database file,
|
|
assuming you have a directory named "rmc" which has a subdirectory for each
|
|
board:
|
|
|
|
RMC_BOARD_DATA_DIRS_append = " /path_of/rmc"
|
|
|
|
This line directs RMC to pack data of your boards only, without data of the
|
|
default boards in meta-intel:
|
|
|
|
RMC_BOARD_DATA_DIRS = "/path_of/rmc"
|
|
|
|
And this line disables database generation:
|
|
|
|
RMC_BOARD_DATA_DIRS = ""
|
|
|
|
Please also refer to the "Example 1" in this document.
|
|
|
|
Subdirectory is not supported in a board's directory.
|
|
|
|
Note 1:
|
|
Fingerprint files must be provided and with ".fp" at the end of their names.
|
|
Fingerprint can be obtained by running RMC tool on your board. An easy way is to
|
|
live-boot USB stick flashed with any image enabled this feature on your board,
|
|
then run this command:
|
|
|
|
# rmc -F -o my_board.fp
|
|
|
|
Or you will need to build RMC tool for the architecture of your board, 32 or
|
|
64 bit x86, from RMC project.
|
|
|
|
You can run RMC tool without any argument to get usage and examples.
|
|
|
|
DO NOT NAME ANY FILE ENDING WITH '.fp' IF IT IS NOT A RMC FINGERPRINT FILE.
|
|
|
|
If you do need a .fp file deployed onto target, please rename it in source and
|
|
specify the real name of file on target in INSTALLER.CONFIG.
|
|
|
|
Note 2:
|
|
At runtime, RMC bootloader tries to fetch this file specific to the board at run
|
|
time, then tries to fetch each boot entry file specified in BOOTENTRY.CONFIG and
|
|
show them in boot menu options. The format of this file is very simple. Each
|
|
line is the name of a boot entry file:
|
|
|
|
boot.conf
|
|
Install.conf
|
|
myrmcboot.conf
|
|
|
|
Name of a boot entry file is defined by developer so it can be anything. But the
|
|
name of config file is what RMC bootloader looks up in RMC database, so it must
|
|
be named BOOTENTRY.CONFIG.
|
|
|
|
Bootloader skips loading entry conf files from disk once any entry is loaded
|
|
from RMC database.
|
|
|
|
Note 3:
|
|
At runtime, RMC installer tries to fetch INSTALLER.CONFIG file specific to the
|
|
board, then tries to fetch each file specified in this config file, and then
|
|
deploy the file onto target with its permissions, UID, GID and other attributes
|
|
also specified in this config file if file for the board can be retrieved from
|
|
RMC database. The format of this file is (# is for comment line)
|
|
|
|
# name:uid:gid:mode:path_on_target
|
|
# to create a directory, add a “/” at the end of path_on_target:
|
|
audio_policy:0:0:600:/etc/audio/
|
|
audio_def_policy:0:0:600:/etc/audio/audio_policy
|
|
|
|
The above example creates /etc/audio directory first, then fetch a file named
|
|
“audio_def_policy” from RMC database for the board, then copy it to /etc/audio/
|
|
with a new name “audio_policy”.
|
|
|
|
If this config file is not provided, No data in RMC database is deployed to the
|
|
target.
|
|
|
|
Some steps defined by developers could not be supported on a filesystem.
|
|
Installer simply ignores any errors in RMC deployment stage.
|
|
|
|
The name of this config file is what installer looks up first, so it must be
|
|
INSTALLER.CONFIG.
|
|
|
|
Note 4:
|
|
At the end of RMC deployment during installation, RMC installer queries a script
|
|
file POSTINSTALL.sh from RMC database file, and execute it when query is
|
|
successful on the running board. This hook provides developers almost ultimate
|
|
flexibility to retouch what have been deployed on the target. There are some
|
|
steps still can override results from this hook for boot entries and KBOOTPARAM.
|
|
|
|
|
|
|
|
Enable RMC Feature
|
|
--------------------------------------------------------------------------------
|
|
To enable the RMC feature please add the following variables to your local.conf.
|
|
|
|
DISTRO_FEATURES_append = " rmc"
|
|
EFI_PROVIDER = "rmc-boot"
|
|
|
|
The default EFI bootloader used with RMC is systemd-boot. To change the default
|
|
bootloader please overwrite the RMC_BOOTLOADER variable in your local.conf
|
|
|
|
Note:
|
|
Image could be still bootable if you only have either of two lines, but RMC
|
|
feature could not be fully functional, depending on the availability of the
|
|
database file, installer and the rmc tool.
|
|
|
|
Examples
|
|
--------------------------------------------------------------------------------
|
|
We checked in configuration data in common/recipes-bsp/rmc/boards/ for several
|
|
boards, to help users to understand the RMC feature. These examples are also for
|
|
validation. For any example you find not working as what this section depicts,
|
|
it should be treated as a bug to be fixed.
|
|
|
|
To test this feature with examples, enable it and build an image first, then
|
|
boot the built image on supported boards. Examples are always built in when the
|
|
feature is enabled, except for the EXAMPLE 1.
|
|
|
|
EXAMPLE 1: Support a new board type:
|
|
(1) enable the feature and do a build to get a live-boot image by adding these
|
|
lines in conf/local.conf:
|
|
DISTRO_FEATURES_append = " rmc"
|
|
EFI_PROVIDER = "rmc-boot"
|
|
|
|
(2) flash the image to a USB stick and boot it on your board
|
|
|
|
(3) in super user mode, run "rmc -F -o my_board.fp"
|
|
|
|
(4) create directories in your host "mkdir -p my_top_dir/my_rmc/my_board"
|
|
|
|
(5) copy my_board.fp from target to my_top_dir/my_rmc/my_board/ on host
|
|
|
|
(6) create a file my_top_dir/my_rmc/my_board/KBOOTPARAM, put some fake
|
|
and harmless options in a single line, say, "loglevel=7"
|
|
|
|
(7) create a file my_top_dir/rmc-db.bbappend, put this single line in it:
|
|
RMC_BOARD_DATA_DIRS_append := " ${THISDIR}/my_rmc"
|
|
From parent directory of my_top_dir, the tree should look like:
|
|
my_top_dir/
|
|
my_rmc/
|
|
my_board/
|
|
KBOOTPARAM
|
|
my_board.fp
|
|
rmc-db.bbappend
|
|
Later, you can add more board directories in my_rmc directory.
|
|
|
|
(8) modify build configuration to add my_top_dir into build, for example, put
|
|
this line in a bblayers.conf:
|
|
BBFILES += "/full/path/of/my_top_dir/rmc-db.bbappend"
|
|
|
|
(9) build image again then boot it on your board
|
|
|
|
(10) Once you login to shell, new options should be effective, run this command
|
|
"cat /proc/cmdline" to verify the result.
|
|
|
|
EXAMPLE 2: Board-specific boot entry
|
|
MinnowBoard MAX and B3 version:
|
|
common/recipes-bsp/rmc/boards/minnowmax
|
|
common/recipes-bsp/rmc/boards/minnowmaxB3
|
|
|
|
We have found two identities (type of board) exist for the "same" Minnow Max
|
|
hardware, so they have to be treated as two different types of hardware. The two
|
|
examples show you a boot entry specific to a type of board. Titles shown in boot
|
|
menu have different names according to the type of running board, "Minnow Max
|
|
boot" or "Minnow Max B3 boot". in /proc/cmdline, "console=ttyS0,115200n8" shall
|
|
be there. Kernel prints logs from 6-pin FTDI serial port on Minnow Max(s). This
|
|
console setting is in board-specific entries, so you won't see it effective if
|
|
you select default "boot" entry to boot the device.
|
|
|
|
EXAMPLE 3: Board-specific boot entry, global kernel cmdline and installer
|
|
NUC Gen 6:
|
|
common/recipes-bsp/rmc/boards/nucgen6
|
|
This is a combo example with all supported configuration data for NUC Gen 6
|
|
product. It shows two boot entries in bootloader menu when you boot image on NUC
|
|
Gen 6 product, with "NUC Gen6" in entry titles. There shall no any "console=" in
|
|
/proc/cmdline when you boot with either of two "NUC Gen6"entries. We designed it
|
|
this way because there is no accessible tty port on NUC Gen 6 with housing. The
|
|
post-install hook is also provided in this example.
|
|
|
|
This example also includes a global kernel cmdline fragment KBOOTPARAM. Content
|
|
of KBOOTPARAM shall be at the end of /proc/cmdline no matter which boot entry
|
|
you selected to boot NUC Gen6.
|
|
|
|
INSTALLER.CONFIG directs installer to create a directory and deploy a file in it
|
|
when install the image on NUC Gen6.
|
|
|
|
Choose "NUC Gen6 install" boot entry to boot shall start installation. Once
|
|
the device reboots after installation, we can verify the configurations.
|
|
|
|
The boot entry "NUC Gen6 boot" shall be shown in boot menu.
|
|
|
|
The content of KBOOTPARAM shall be in /proc/cmdline too.
|
|
|
|
A directory /etc/mylib/ is created and a file "mylib.conf" is there. The content
|
|
of that file shall be what we put in mylib.conf in
|
|
common/recipes-bsp/rmc/boards/nucgen6
|
|
|
|
POSTINSTALL.sh shows how we get rid of an error message caused by no serial
|
|
console available on NUC Gen 6, without creating another static board
|
|
configuration.
|
|
|
|
EXAMPLE 4: For validation only
|
|
T100 (32bit):
|
|
common/recipes-bsp/rmc/boards/T100-32bit
|
|
This example is provided for validation on 32 bit X86 architecture. It doesn't
|
|
provide any new function not mentioned in above examples.
|
|
|
|
EXAMPLE 5: RMC for quark
|
|
Galileo Gen 2
|
|
common/recipes-bsp/rmc/boards/Galileo2
|
|
This example doesn't show any feature not covered in the above examples. Note
|
|
RMC only supports hddimg image format so far. Please refer to the section II.c
|
|
in README in meta-intel for how to boot Galileo with images in hddimg format.
|
|
Bootloader should show a board-specific boot option "Galileo Gen 2 boot" when
|
|
the board boots off.
|
|
|
|
Troubleshooting
|
|
--------------------------------------------------------------------------------
|
|
Issue: Cannot obtain RMC fingerprint for a board
|
|
|
|
RMC tool requires UEFI BIOS and SMBIOS support in firmware. It doesn't support
|
|
other type of firmware, e.g. legacy BIOS. It also requires EFI driver enabled
|
|
in Linux kernel.
|
|
|
|
Issue: Configuration for a board seems not effective at runtime.
|
|
|
|
Check if board is booted from the storage where the image or installation lives
|
|
when you have multiple boot options in BIOS. On some old hardwares it is not
|
|
that obvious as you assume. A build image can support boot from both of legacy
|
|
and UEFI mode, but RMC only works with UEFI boot so far.
|
|
|
|
Make sure configuration files (BOOTENTRY.CONFIG, INSTALLER.CONFIG and,
|
|
KBOOTPARAM ...) are properly named in the board directory.
|
|
|
|
Make sure configuration files have correct contents.
|
|
|
|
Some file attributes could not be supported by targeted file system. Installer
|
|
cannot setup file blobs as you wish. It simply move to the next step if a step
|
|
fails.
|
|
|
|
Kernel command line can be customized globally with KBOOTPARAM or just in a boot
|
|
entry for the type of board. They have different effective scopes.
|
|
|
|
If no any board-specific configuration becomes effective on your board but it
|
|
works on other boards of same product, you can run rmc tool to obtain
|
|
fingerprint file on your board and compare it with fingerprint of a working
|
|
board. It is possible they have different firmware versions and unluckily, some
|
|
information for fingerprint changes between two versions. You can update BIOS
|
|
on every board to the same BIOS version if it is feasible. Otherwise you have
|
|
to treat them as two different type of boards. We could extend rmc design to
|
|
allow multiple fingerprints in a board directory as a workaround.
|
|
|
|
Issue: RMC reports error because it cannot find fingerprint when building image.
|
|
|
|
Make sure you have a fingerprint file. Its name must be ended with '.fp'. You
|
|
can put a fingerprint file in a board directory and provide data later.
|
|
|
|
Issue: Any problems the above troubleshooting cannot help
|
|
|
|
Please report it to us. Extra information like the type of your board or a dump
|
|
file from dmidecode tool is helpful. We will investigate the problem and keep
|
|
improving this feature.
|
|
|
|
|
|
|
|
|
|
When you (don't) need RMC feature
|
|
--------------------------------------------------------------------------------
|
|
RMC feature is designed to as generic as possible, in order to support a large
|
|
number of types of boards. And it shall be designed not to break things when it
|
|
is disabled. These considerations help users to decide if they really need or
|
|
enable it.
|
|
|
|
If you are satisfied with a dedicated build target and image for each board in
|
|
your development cycle (source, build, validation, release, etc), you don't need
|
|
this feature.
|
|
|
|
If you have a generic build for multiple type of boards and features supported
|
|
by that build meet your needs to functionality on all of boards, you don't need
|
|
to have this feature or you can disable it until you need to check in the first
|
|
board's data, in order to apply a quirk or customization only for that board.
|
|
|
|
If you want this feature but have concerns to see more and more boards' finger-
|
|
prints and data in a generic project, you can have another layer to hold all of
|
|
board-specific data to split them from a generic layer at source level. Another
|
|
suggestion is always seeking chances not to clone or copy a common configuration
|
|
to each board's directory.
|
|
|
|
|
|
|
|
Thanks
|
|
|
|
Jianxun Zhang <jianxun.zhang@linux.intel.com>
|