[meta-intel] [PATCHv5 06/10] rmc: document and examples for RMC feature

Tom Zanussi tom.zanussi at linux.intel.com
Thu Aug 4 12:05:08 PDT 2016 

On 08/04/2016 01:30 PM, Jianxun Zhang wrote:
> 
>> On Aug 4, 2016, at 10:45 AM, Tom Zanussi <tom.zanussi at linux.intel.com> wrote:
>>
>> 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:

[....]

>>>>> +
>>>>> +
>>>>> +
>>>>> +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.
>>
> 
> Just kindly remind you the installer. The current design in OE ties up installer and bootloader. If we apply the idea of discussion on bootloader to installer case and you want RMC image not to “override” original installer, we get 2^3 = 8… I think we gonna either have a single distro feature which you disapprove or break functions into a component basis in README. Any cases in the middle ground is asking trouble.
> 
> I think I should do something to redesign these parts in OE if people accept my thoughts.
> 

By two options, I just meant: if you set DISTRO_FEATURES_append = " rmc"
(or whatever the right switch ends up being), the
bootloader/installer/whatever enables the rmc functionality built in to
it.  If " rmc" is not set, or if " rmc" is set but those components
don't have rmc support, it doesn't (i.e. as if the original unmodified
functionality was specified).

Tom

>> 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