From 381606266d48ea3d34dcd1ed316325eb167acaab Mon Sep 17 00:00:00 2001 From: Jianxun Zhang Date: Wed, 3 Aug 2016 11:04:17 -0700 Subject: rmc: Add documentation and examples for RMC feature Provide a README for RMC feature. Also check in fingerprints and configuration data for several boards as examples for users. They can be used for validation too. Signed-off-by: Jianxun Zhang Reviewed-by: Saul Wold Signed-off-by: Tom Zanussi --- .../rmc/boards/T100-32bit/BOOTENTRY.CONFIG | 2 + .../rmc/boards/T100-32bit/T100-32bit.fp | Bin 0 -> 116 bytes common/recipes-bsp/rmc/boards/T100-32bit/boot.conf | 4 + .../recipes-bsp/rmc/boards/T100-32bit/install.conf | 4 + .../rmc/boards/minnowmax/BOOTENTRY.CONFIG | 1 + common/recipes-bsp/rmc/boards/minnowmax/boot.conf | 4 + .../recipes-bsp/rmc/boards/minnowmax/minnowmax.fp | Bin 0 -> 143 bytes .../rmc/boards/minnowmaxB3/BOOTENTRY.CONFIG | 1 + .../recipes-bsp/rmc/boards/minnowmaxB3/boot.conf | 4 + .../rmc/boards/minnowmaxB3/minnowmaxB3.fp | Bin 0 -> 148 bytes .../rmc/boards/nucgen6/BOOTENTRY.CONFIG | 2 + .../rmc/boards/nucgen6/INSTALLER.CONFIG | 6 + common/recipes-bsp/rmc/boards/nucgen6/KBOOTPARAM | 1 + common/recipes-bsp/rmc/boards/nucgen6/boot.conf | 4 + common/recipes-bsp/rmc/boards/nucgen6/install.conf | 4 + common/recipes-bsp/rmc/boards/nucgen6/mylib.conf | 7 + common/recipes-bsp/rmc/boards/nucgen6/nuc6.fp | Bin 0 -> 149 bytes documentation/rmc/README | 343 +++++++++++++++++++++ 18 files changed, 387 insertions(+) create mode 100644 common/recipes-bsp/rmc/boards/T100-32bit/BOOTENTRY.CONFIG create mode 100644 common/recipes-bsp/rmc/boards/T100-32bit/T100-32bit.fp create mode 100644 common/recipes-bsp/rmc/boards/T100-32bit/boot.conf create mode 100644 common/recipes-bsp/rmc/boards/T100-32bit/install.conf create mode 100644 common/recipes-bsp/rmc/boards/minnowmax/BOOTENTRY.CONFIG create mode 100644 common/recipes-bsp/rmc/boards/minnowmax/boot.conf create mode 100644 common/recipes-bsp/rmc/boards/minnowmax/minnowmax.fp create mode 100644 common/recipes-bsp/rmc/boards/minnowmaxB3/BOOTENTRY.CONFIG create mode 100644 common/recipes-bsp/rmc/boards/minnowmaxB3/boot.conf create mode 100644 common/recipes-bsp/rmc/boards/minnowmaxB3/minnowmaxB3.fp create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/BOOTENTRY.CONFIG create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/INSTALLER.CONFIG create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/KBOOTPARAM create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/boot.conf create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/install.conf create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/mylib.conf create mode 100644 common/recipes-bsp/rmc/boards/nucgen6/nuc6.fp create mode 100644 documentation/rmc/README diff --git a/common/recipes-bsp/rmc/boards/T100-32bit/BOOTENTRY.CONFIG b/common/recipes-bsp/rmc/boards/T100-32bit/BOOTENTRY.CONFIG new file mode 100644 index 00000000..b2fabe82 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/T100-32bit/BOOTENTRY.CONFIG @@ -0,0 +1,2 @@ +boot.conf +install.conf diff --git a/common/recipes-bsp/rmc/boards/T100-32bit/T100-32bit.fp b/common/recipes-bsp/rmc/boards/T100-32bit/T100-32bit.fp new file mode 100644 index 00000000..86ecea73 Binary files /dev/null and b/common/recipes-bsp/rmc/boards/T100-32bit/T100-32bit.fp differ diff --git a/common/recipes-bsp/rmc/boards/T100-32bit/boot.conf b/common/recipes-bsp/rmc/boards/T100-32bit/boot.conf new file mode 100644 index 00000000..f1578e0f --- /dev/null +++ b/common/recipes-bsp/rmc/boards/T100-32bit/boot.conf @@ -0,0 +1,4 @@ +title T100T(32bit) boot +linux /vmlinuz +initrd /initrd +options LABEL=boot loglevel=8 diff --git a/common/recipes-bsp/rmc/boards/T100-32bit/install.conf b/common/recipes-bsp/rmc/boards/T100-32bit/install.conf new file mode 100644 index 00000000..67e7eb18 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/T100-32bit/install.conf @@ -0,0 +1,4 @@ +title T100T(32bit) install +linux /vmlinuz +initrd /initrd +options LABEL=install-efi diff --git a/common/recipes-bsp/rmc/boards/minnowmax/BOOTENTRY.CONFIG b/common/recipes-bsp/rmc/boards/minnowmax/BOOTENTRY.CONFIG new file mode 100644 index 00000000..cb01ced0 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/minnowmax/BOOTENTRY.CONFIG @@ -0,0 +1 @@ +boot.conf diff --git a/common/recipes-bsp/rmc/boards/minnowmax/boot.conf b/common/recipes-bsp/rmc/boards/minnowmax/boot.conf new file mode 100644 index 00000000..6e789cd8 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/minnowmax/boot.conf @@ -0,0 +1,4 @@ +title Minnow Max boot +linux /vmlinuz +initrd /initrd +options LABEL=boot console=ttyS0,115200n8 diff --git a/common/recipes-bsp/rmc/boards/minnowmax/minnowmax.fp b/common/recipes-bsp/rmc/boards/minnowmax/minnowmax.fp new file mode 100644 index 00000000..3c5a286f Binary files /dev/null and b/common/recipes-bsp/rmc/boards/minnowmax/minnowmax.fp differ diff --git a/common/recipes-bsp/rmc/boards/minnowmaxB3/BOOTENTRY.CONFIG b/common/recipes-bsp/rmc/boards/minnowmaxB3/BOOTENTRY.CONFIG new file mode 100644 index 00000000..cb01ced0 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/minnowmaxB3/BOOTENTRY.CONFIG @@ -0,0 +1 @@ +boot.conf diff --git a/common/recipes-bsp/rmc/boards/minnowmaxB3/boot.conf b/common/recipes-bsp/rmc/boards/minnowmaxB3/boot.conf new file mode 100644 index 00000000..577e5d6a --- /dev/null +++ b/common/recipes-bsp/rmc/boards/minnowmaxB3/boot.conf @@ -0,0 +1,4 @@ +title Minnow Max B3 boot +linux /vmlinuz +initrd /initrd +options LABEL=boot console=ttyS0,115200n8 diff --git a/common/recipes-bsp/rmc/boards/minnowmaxB3/minnowmaxB3.fp b/common/recipes-bsp/rmc/boards/minnowmaxB3/minnowmaxB3.fp new file mode 100644 index 00000000..ad3f0d6d Binary files /dev/null and b/common/recipes-bsp/rmc/boards/minnowmaxB3/minnowmaxB3.fp differ diff --git a/common/recipes-bsp/rmc/boards/nucgen6/BOOTENTRY.CONFIG b/common/recipes-bsp/rmc/boards/nucgen6/BOOTENTRY.CONFIG new file mode 100644 index 00000000..b2fabe82 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/BOOTENTRY.CONFIG @@ -0,0 +1,2 @@ +boot.conf +install.conf diff --git a/common/recipes-bsp/rmc/boards/nucgen6/INSTALLER.CONFIG b/common/recipes-bsp/rmc/boards/nucgen6/INSTALLER.CONFIG new file mode 100644 index 00000000..7d5378b2 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/INSTALLER.CONFIG @@ -0,0 +1,6 @@ +# This file specifies which file or dir RMC will install onto target. +# Note the absolute path is referred from mount points in installation. +efi_entry_dir:root:disk:770:/boot/loader/entries/ +boot.conf:root:disk:770:/boot/loader/entries/rmcboot.conf +mylibdir:root:root:770:/tgt_root/etc/mylib/ +mylib.conf:root:root:660:/tgt_root/etc/mylib/mylib.conf diff --git a/common/recipes-bsp/rmc/boards/nucgen6/KBOOTPARAM b/common/recipes-bsp/rmc/boards/nucgen6/KBOOTPARAM new file mode 100644 index 00000000..27943b49 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/KBOOTPARAM @@ -0,0 +1 @@ +i915.preliminary_hw_support=1 diff --git a/common/recipes-bsp/rmc/boards/nucgen6/boot.conf b/common/recipes-bsp/rmc/boards/nucgen6/boot.conf new file mode 100644 index 00000000..e6ecb029 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/boot.conf @@ -0,0 +1,4 @@ +title NUC Gen6 boot +linux /vmlinuz +initrd /initrd +options LABEL=boot diff --git a/common/recipes-bsp/rmc/boards/nucgen6/install.conf b/common/recipes-bsp/rmc/boards/nucgen6/install.conf new file mode 100644 index 00000000..916bb04b --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/install.conf @@ -0,0 +1,4 @@ +title NUC Gen6 install +linux /vmlinuz +initrd /initrd +options LABEL=install-efi diff --git a/common/recipes-bsp/rmc/boards/nucgen6/mylib.conf b/common/recipes-bsp/rmc/boards/nucgen6/mylib.conf new file mode 100644 index 00000000..fd8357c2 --- /dev/null +++ b/common/recipes-bsp/rmc/boards/nucgen6/mylib.conf @@ -0,0 +1,7 @@ +# This is a demo conf file read by an imagined program or library +# which reads this file at runtime to customize its behavior. +# rmc will deploy it to the location specified in INSTALLER.CONFIG. + +lib.info = "V1.0 for rmc demo" +lib.board = "NUC gen 6" +prog.ui.layout = "minimal" diff --git a/common/recipes-bsp/rmc/boards/nucgen6/nuc6.fp b/common/recipes-bsp/rmc/boards/nucgen6/nuc6.fp new file mode 100644 index 00000000..834f800b Binary files /dev/null and b/common/recipes-bsp/rmc/boards/nucgen6/nuc6.fp differ diff --git a/documentation/rmc/README b/documentation/rmc/README new file mode 100644 index 00000000..ba476b0e --- /dev/null +++ b/documentation/rmc/README @@ -0,0 +1,343 @@ +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) + | |- 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: +To add your boards into RMC feature, simply put this line in your +rmc-db.bbappend: + +RMC_BOARD_DATA_DIRS_append := " ${THISDIR}/my_top_dir" + +RMC db recipe takes all top directories specified in RMC_BOARD_DATA_DIRS to +construct and deploy a central RMC database inside image. The bbclass of the +bare RMC project also provide function for other components to construct their +own RMC database file. Please refer to rmc-db.bbclass for more information. + +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. + + + +Enable RMC Feature +-------------------------------------------------------------------------------- +To Enable RMC feature in build, add the below lines in a conf file: +DISTRO_FEATURES_append = " rmc" +EFI_PROVIDER = "rmc-systemd-boot" + +Note: +Image could be still bootable if you only have either of two lines, but RMC +feature won't be fully functional. + + + +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-systemd-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. + +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 + +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. + + + +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 -- cgit v1.2.3-54-g00ecf