[meta-intel] [PATCHv5 06/10] rmc: document and examples for RMC feature
Tom Zanussi
tom.zanussi at linux.intel.com
Thu Aug 4 10:45:53 PDT 2016
On 08/04/2016 12:39 PM, Jianxun Zhang wrote:
>
>> On Aug 4, 2016, at 7:43 AM, Tom Zanussi <tom.zanussi at linux.intel.com> wrote:
>>
>> On 08/03/2016 01:04 PM, Jianxun Zhang wrote:
>>> 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 <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
>>> 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 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/documentation/rmc/README b/documentation/rmc/README
>>> new file mode 100644
>>> index 0000000..ba476b0
>>> --- /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.
>>> +
>>
>> In what way? Please explain. What do you mean by it 'could still be
>> bootable'. Under what conditions? And please explain what it means
>> that the 'RMC feature won't be fully functional'. Which parts will be
>> functional and which parts won’t?
>>
> I will amend this in README, but it is a bit complex now.
>
> Now we have 2 switches, so we have to cover 2^2 = 4 possibilities. I tested these but think it is too overwhelming to user if we have lengthy sections to explain result from each of them.
>
> Actually, the more we say in this section here, the more possibly users gonna say “hey, man, why don’t just tell us how to fully enable/disable this thing?!”.
>
The other option is to just fix it, so that there are only two options,
as it should be. But I guess it won't happen overnight, so needs to be
documented as long as this situation exists.
Tom
> I will file a bug to amend README to make it shorter, within 150 lines somehow. I believe we will have more talk on this topic.
>
>> Thanks,
>>
>> Tom
>>
>>> +
>>> +
>>> +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 at linux.intel.com>
>>>
>>
>
More information about the meta-intel
mailing list