Embedding EC firmware

[Andy Pont]

Hello,

I have a binary file that is the firmware for the embedded controller on 
the laptop platform that I am working on.  In the regular BIOS provided 
by the hardware vendor this 128KB binary is located at offset 0x400000 
in the BIOS image.

Is there any documentation or instructions anywhere on how I include 
this into the Coreboot image that I am creating?

-Andy.

[Duncan Laurie]

On Fri, Oct 2, 2020 at 3:51 AM Andy Pont  wrote:
> Hello,
>
> I have a binary file that is the firmware for the embedded controller on
> the laptop platform that I am working on.  In the regular BIOS provided
> by the hardware vendor this 128KB binary is located at offset 0x400000
> in the BIOS image.
>
> Is there any documentation or instructions anywhere on how I include
> this into the Coreboot image that I am creating?

Hi Andy,

You can enable CONFIG_HAVE_EC_BIN and define CONFIG_EC_BIN_PATH (
https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...)
to point to the EC binary and the build system will use ifdtool to inject
the binary at the EC region that is defined in the descriptor. (
https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...
)

If you are creating a descriptor layout from scratch you will need to
define the EC region in FLREG8: (example from google/drallion mainboard,
which matches the layout in chromeos.fmd)
00000000:00000fff fd
00438000:01ffffff bios
00101000:00433fff me
00434000:00437fff pd
00001000:00100fff ec

As well as likely a pointer to the actual start of the EC binary in the
image.  This part is not really documented by Intel and is likely EC vendor
specific.  The Drallion example has 2 pointers starting at offset 0 of the
descriptor, one for default loading and a second for a backup in case the
first one is corrupt or fails to boot:

00000000:  10 00 00 f7 10 08 00 5f
In this example bits [22:0] correspond to bits [30:8] of the address, so
the EC is always on a 256 byte boundary.  bits [31:24] contain a CRC8-ITU
checksum of bits [0-23].

If you're working with an unknown EC it is probably best to try and copy
what is in the existing image, including the location of the EC image in
flash as the firmware may expect to execute out of that specific address
region and not tolerate relocation.

-duncan

[Andy Pont]

Duncan wrote...
> You can enable CONFIG_HAVE_EC_BIN and define CONFIG_EC_BIN_PATH 
> (https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...) 
> to point to the EC binary and the build system will use ifdtool to 
> inject the binary at the EC region that is defined in the descriptor. 
> (https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...)
>
> If you are creating a descriptor layout from scratch you will need to 
> define the EC region in FLREG8: (example from google/drallion 
> mainboard, which matches the layout in chromeos.fmd)
> 00000000:00000fff fd
> 00438000:01ffffff bios
> 00101000:00433fff me
> 00434000:00437fff pd
> 00001000:00100fff ec

I have the binary file for the original system BIOS for this platform 
and so have manage to use ifdtool to extract the 4KB flash descriptor 
which I am in the process of adding to the image with 
CONFIG_HAVE_IFD_BIN and CONFIG_IFD_BIN_PATH.  Does that save me having 
to worry about anything other than defining the CONFIG_HAVE_EC_BIN and 
CONFIG_EC_BIN_PATH values?

-Andy.

[Duncan Laurie]

On Fri, Oct 2, 2020 at 8:40 AM Andy Pont  wrote:
> Duncan wrote...
>
> You can enable CONFIG_HAVE_EC_BIN and define CONFIG_EC_BIN_PATH (
> https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...)
> to point to the EC binary and the build system will use ifdtool to inject
> the binary at the EC region that is defined in the descriptor. (
> https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/master/src...
> )
>
> If you are creating a descriptor layout from scratch you will need to
> define the EC region in FLREG8: (example from google/drallion mainboard,
> which matches the layout in chromeos.fmd)
> 00000000:00000fff fd
> 00438000:01ffffff bios
> 00101000:00433fff me
> 00434000:00437fff pd
> 00001000:00100fff ec
>
> I have the binary file for the original system BIOS for this platform and
> so have manage to use ifdtool to extract the 4KB flash descriptor which I
> am in the process of adding to the image with CONFIG_HAVE_IFD_BIN and
> CONFIG_IFD_BIN_PATH.  Does that save me having to worry about anything
> other than defining the CONFIG_HAVE_EC_BIN and CONFIG_EC_BIN_PATH values?

Yes that should hopefully make it straightforward.

-duncan
>

[Andy Pont]

Duncan wrote...
> > I have the binary file for the original system BIOS for this platform 
> > and so have manage to use ifdtool to extract the 4KB flash descriptor 
> > which I am in the process of adding to the image with 
> > CONFIG_HAVE_IFD_BIN and CONFIG_IFD_BIN_PATH.  Does that save me having 
> > to worry about anything other than defining the CONFIG_HAVE_EC_BIN and 
> > CONFIG_EC_BIN_PATH values?
>
> Yes that should hopefully make it straightforward.

If only things were that easy!  When I try this, I get a build error:

IFDTOOL    ec.bin -> coreboot.pre
     Platform is: cnl
     File build/coreboot.pre is 16777216 bytes
     Region EC is disabled in target. Not injecting.
     src/southbridge/intel/common/firmware/Makefile.inc:31: recipe for 
target 'add_intel_firmware' failed
     make: *** [add_intel_firmware] Error 1

I’m not sure where the “Platform is: cnl” is coming from.  I have 
defined a custom mainboard but it is derived from Intel’s Coffee Lake / 
Comet Lake not from Cannon Lake which is the closest thing I can find 
for “cnl”.

My board specific configuration options include:

select MAINBOARD_USES_IFD_EC_REGION
     select HAVE_IFD_BIN
     select EC_SDC_IT8987
     select HAVE_EC_BIN

These look correct to me but am happy to informed otherwise!

-Andy.

[Felix Held]

Hi Andy!

Does the EC firmware of your system reside in the IFD EC partition or in 
the IFD BIOS partition? The former doesn't seem to be the case, since 
ifdtool complains about nor IFD EC region being present in the IFD. For 
the latter have a look at 51nb/x210 and mb/amd/mandolin where an FMAP EC 
section is defined in the board's fmd file and the EC firmware is put 
into that section via cbfstool; see the Makefile.inc of the nb51 EC 
support or the Mandolin board for that.

Regards
Felix

[Andy Pont]

Hi Felix...
> Does the EC firmware of your system reside in the IFD EC partition or in the IFD BIOS partition? The former doesn't seem to be the case, since ifdtool complains about nor IFD EC region being present in the IFD. For the latter have a look at 51nb/x210 and mb/amd/mandolin where an FMAP EC section is defined in the board's fmd file and the EC firmware is put into that section via cbfstool; see the Makefile.inc of the nb51 EC support or the Mandolin board for that.

When I extracted the IFD from the existing platform BIOS this is what it 
reports…

File flash.bin is 16777216 bytes
   Flash Region 0 (Flash Descriptor): 00000000 - 00000fff
   Flash Region 1 (BIOS): 00400000 - 00ffffff
   Flash Region 2 (Intel ME): 00001000 - 003fffff
   Flash Region 3 (GbE): 07fff000 - 00000fff (unused)
   Flash Region 4 (Platform Data): 07fff000 - 00000fff (unused)
   Flash Region 5 (Reserved): 07fff000 - 00000fff (unused)
   Flash Region 6 (Reserved): 07fff000 - 00000fff (unused)
   Flash Region 7 (Reserved): 07fff000 - 00000fff (unused)
   Flash Region 8 (EC): 07fff000 - 00000fff (unused)

Looking at the contents of flash.bin then the EC firmware is located at 
offset 0x400000 which would appear to put it at the start of the IFD 
BIOS partition.  Looks like the example of the mandolin board is going 
to be the one to follow.

Thanks for the pointer in the right direction!

-Andy.

[Felix Held]

Hi Andy!
> Flash Region 1 (BIOS): 00400000 - 00ffffff
>    Flash Region 8 (EC): 07fff000 - 00000fff (unused)
>
> Looking at the contents of flash.bin then the EC firmware is located at 
> offset 0x400000 which would appear to put it at the start of the IFD 
> BIOS partition.

Yep, the EC firmware is at the beginning of the BIOS partition then, 
which isn't too unusual. Some of the first bytes of the flash within the 
IFD section are likely some sort of pointer or jump to the beginning of 
the EC firmware; sometimes the pointer case it's not an offset in bytes, 
but in 256 or 4096 bytes. There might also be some sort of magic bytes 
or checksum in the first few bytes so that the EC can detect if the 
flash probably contains a valid firmware image for the EC, so it doesn't 
just load random bytes when the flash doesn't contain the EC firmware.
> Looks like the example of the mandolin board is going 
> to be the one to follow.

You probably want to take the x210's fmd file as a starting point 
though, since that one is for an Intel system and leaves space for the 
IFD/ME/GBE partition; you'll probably need to adjust the sizes and 
offsets. The Makefile part is a bit clearer on the Mandolin board, but 
it does basically the same as the x210's EC driver.

Regards
Felix