diff options
Diffstat (limited to 'documentation/rmc/README')
| -rw-r--r-- | documentation/rmc/README | 382 |
1 files changed, 0 insertions, 382 deletions
diff --git a/documentation/rmc/README b/documentation/rmc/README deleted file mode 100644 index eaa763e1..00000000 --- a/documentation/rmc/README +++ /dev/null @@ -1,382 +0,0 @@ -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> |