Provide a README.rmc.distro for rmc-distro. 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 <[email protected]> --- README.rmc.distro | 261 +++++++++++++++++++++ .../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 common/recipes-bsp/rmc/rmc-distro.bb | 2 +- 19 files changed, 306 insertions(+), 1 deletion(-) create mode 100644 README.rmc.distro 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 diff --git a/README.rmc.distro b/README.rmc.distro new file mode 100644 index 0000000..f32d856 --- /dev/null +++ b/README.rmc.distro @@ -0,0 +1,261 @@ +RMC Disro +-------------------------------------------------------------------------------- +Table of Contents + +Introduction +Usage +Enable +Examples +Troubleshooting + + + +Introduction: +-------------------------------------------------------------------------------- +RMC Distro feature fills functionality gaps between a build for a generic +machine like intel-corei7-64 and boards which require board-specific quirks and +configurations. These 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 to be specified for a type of board in kernel cmdline + - default audio 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. + +The effect is identical as what a conventional image customized for a type of +board (depending on the way to deploy image). + +This feature is based on RMC project and two modified software components (RMC +clients): + +systemd-boot EFI bootloader: +We modified systemd-boot so that it queries board-specific boot entries and show +them in boot menu. + +It also queries a global kernel command line fragment from RMC. If there is such +fragment in RMC database for the running board, bootloader appends it to the end +of kernel commandline to all of boot entries, regardless if an entry is got from +ESP or RMC database. + +OE EFI installer: +The existing installer is modified to call RMC tool in installation stage. It +queries board-specific files from RMC database and deploy data to file systems. + +The below depicts the usage and configuration files. You can also find several +examples in common/recipes-bsp/rmc/boards/. The "Examples" section in this file +depicts expected results when running rmc-distro image on these boards. + + + +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-distro.bbappend bbappend file to rmc 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 + |- board_file_2 + |- ...more files + +Note 0: +To add your boards into rmc distro image, you simply put this line in +your rmc-distro.bbappend: + +RMC_DISTRO_BOARD_DIRS_append := " ${THISDIR}/my_top_dir" + +RMC distro will take all top directories specified in RMC_DISTRO_BOARD_DIRS when +constructing a central RMC database in distro 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-native.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 RMC distro image 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 +-------------------------------------------------------------------------------- +To Enable RMC distro feature in build, add the below line in a conf file: +EFI_PROVIDER="rmc-distro" + + + +Examples +-------------------------------------------------------------------------------- +We checked in configuration data in common/recipes-bsp/rmc/boards/ for several +boards, to help users to understand the rmc distro feature. These examples are +also used for validation purposes. For any example you find not working as this +section depicts, it should be treated as a bug to be fixed. + +A single rmc distro image shall be used in validation with examples of same +architecture, 32 or 64 bit X86. It is invalid to prove rmc distro feature with +different images even if they are built for the same architecture. + +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. + +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 + +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 RMC image or installation +lives when you have multiple boot options in BIOS. + +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. + +Thanks + +Jianxun Zhang <[email protected]> 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@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@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@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/common/recipes-bsp/rmc/rmc-distro.bb b/common/recipes-bsp/rmc/rmc-distro.bb index 2fbe5bb..7144379 100644 --- a/common/recipes-bsp/rmc/rmc-distro.bb +++ b/common/recipes-bsp/rmc/rmc-distro.bb @@ -10,7 +10,7 @@ LICENSE = "MIT" inherit rmc-native -RMC_DISTRO_BOARD_DIRS ?= "" +RMC_DISTRO_BOARD_DIRS_append := " ${THISDIR}/boards/" RMC_DB_DIR = "${WORKDIR}/db" do_generate_rmc_db () { -- 2.7.4 -- _______________________________________________ meta-intel mailing list [email protected] https://lists.yoctoproject.org/listinfo/meta-intel
