1 files changed, 343 insertions, 0 deletions

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 <jianxun.zhang@linux.intel.com>