[meta-intel] [PATCHv2 6/7] rmc: document and examples for RMC feature
Tom Zanussi
tom.zanussi at linux.intel.com
Tue Jul 19 11:03:46 PDT 2016
Hi Jianxun,
Just a couple quick comments, still reviewing but wanted to get these
noted...
On 07/18/2016 08:00 PM, Jianxun Zhang wrote:
> Provide a README.rmc for RMC feature in a new directory
> "documentation", also move other README files in top directory
> there.
>
> 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 <jianxun.zhang at linux.intel.com>
> ---
> .../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
> README => documentation/README | 0
> documentation/README.rmc | 332 +++++++++++++++++++++
> README.sources => documentation/README.sources | 0
> 20 files changed, 376 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
> rename README => documentation/README (100%)
> create mode 100644 documentation/README.rmc
> rename README.sources => documentation/README.sources (100%)
>
> 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 0000000..b2fabe8
> --- /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 0000000000000000000000000000000000000000..86ecea7344bfc744f7f9d57f3f1810d6f7ba0db1
> GIT binary patch
> literal 116
> zcmZQ%Ehx%QDNQbk&r8frWe71eFbHvEV8SZOB2boERGgWg$KaV)lA5Ctq^aOolAo&)
> p;;X6P91yAyWo&L at px~fjsAp{K?oq{1&rp<FoLW?tn!<p>1_02dA-n(p
>
> literal 0
> HcmV?d00001
>
> 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 0000000..f1578e0
> --- /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 0000000..67e7eb1
> --- /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 0000000..cb01ced
> --- /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 0000000..6e789cd
> --- /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 0000000000000000000000000000000000000000..3c5a286f33ad2e6b17de3bb610160532ce5d65cf
> GIT binary patch
> literal 143
> zcmZQ%Ehx%QDNQbk&r8frWe9Wh at o|j|^K=bYa5PW|@No=r^AGZ6U_w>po0*rFU+$Ej
> zSd^mR>lnenB2boERGgWg$KaV)lA5Ctq^aOolAo&);;X6P91yCY;A(7PWU8RxpkSzH
> XZ0zn)#Zb>slv<oxRF;~;fWig<I@~II
>
> literal 0
> HcmV?d00001
>
> 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 0000000..cb01ced
> --- /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 0000000..577e5d6
> --- /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 0000000000000000000000000000000000000000..ad3f0d6d7cfdada14a35227643c5c67e0c608f7a
> GIT binary patch
> literal 148
> zcmZQ%Ehx%QDNQbk&r8frW$?|+%gZlM%1<mxQSeQyP;fF<2=H+Xaq|!IWnjXl)Cr>0
> zF at k|bpe(hhI5R(w!85NUHAf>zQ^Bz$KUX8fS5v_`AXGuY)!4$wR6)T(!BEfG*xjRw
> Sp`M{AwK%n?EH#Azg$)3>EG<0%
>
> literal 0
> HcmV?d00001
>
> 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 0000000..b2fabe8
> --- /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 0000000..7d5378b
> --- /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 0000000..27943b4
> --- /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 0000000..e6ecb02
> --- /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 0000000..916bb04
> --- /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 0000000..fd8357c
> --- /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 0000000000000000000000000000000000000000..834f800b63bc9cc2cd42e46059bafaec3701a9a2
> GIT binary patch
> literal 149
> zcmZQ%Ehx%QDNQbk&r8frWl$gl7?@Bs_=P%~Wts*@Ix(;al%*CGXXfWIc;=O)=4b?I
> yDmdpCrD}xuYAR%!>Y5pu8H6f02ZSm(C>ZKl7`S^>G1M~@r52|am8GUIps)do>LySC
>
> literal 0
> HcmV?d00001
>
> diff --git a/README b/documentation/README
> similarity index 100%
> rename from README
> rename to documentation/README
The README and README.sources should remain at the top level.
> diff --git a/documentation/README.rmc b/documentation/README.rmc
Please create a documentation/rmc/ and rename this README.rmc to README.
Although there is only one document so far, if we're creating a new
directory structure for documentation, we can use directory names to
separate documentation for different tools and therefore don't need to
identify the tool using a file extension.
> new file mode 100644
> index 0000000..eb31d22
> --- /dev/null
> +++ b/documentation/README.rmc
> @@ -0,0 +1,332 @@
> +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.entry
> +Install.entry
> +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” as a naming convention. If this config file is not
> +provided, only default entries “boot” and “install” from OE are in boot menu.
> +
> +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 first line tells RMC installer to create a directory “audio” in /etc. If any
> +parent directory doesn’t exist, installer will create it. 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, only default entries “boot” and “install”
> +from OE are in boot menu. 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 line in a conf file:
> +EFI_PROVIDER="rmc-systemd-boot"
> +
This is incorrect now - I know it's corrected by a later patch, but then
please squash it with this text or remove it.
> +
> +
> +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 this
> + line in conf/local.conf:
> + EFI_PROVIDER = "rmc-systemd-boot"
This is now incorrect given the above (and isn't fixed by a later patch).
Thanks,
Tom
More information about the meta-intel
mailing list