universalscalablefirmware/documentation

documentation's Issues

coreboot is not a bootloader

coreboot is not a bootloader as depicted in the .

PS: Issue #33 asks for a definition of the term bootloader.

Inappropriate structure definition prefix "PLD_"

In https://edk2.groups.io/g/devel/message/76229?p=,,,20,0,0,0::Created,,UNIVERSAL_PAYLOAD,20,2,0,83304942, Mike Kinney recommended using UNIVERSAL_PAYLOAD or PAYLOAD as the structure definition prefix because "PLD" sometimes is interpreted as Programmable Logic Device.

"PAYLOAD_" prefix works for me.

Comments?

Name images descriptively

Looking at source/images, the names are of the form imageXX.jpg, making it very hard to find an image and deduce the content. It’d be great, if you renamed the images.

Opening image license?

Nice image at the start of this documentation, but what's the source? Do we have permission to use it?

Payload principle

"The payload should elide strong dependencies on the payload launching code (e.g., coreboot versus EDKII versus slimboot)."

The argument that somehow slimboot's payload interface using HOBs is somehow more universal or independent than coreboot tables is disingenuous. They essentially achieve the same. Currently coreboot supports a lot more payloads than slimboot so why not make coreboot tables the standard over HOBs?

Need Payload Data alignment field in Payload Header

UEFI Payload as a payload instance that requires the payload data (FV) be put in page aligned address.
But without the declaration in header, bootloader may put it to a non-aligned address.

I found this gap when using below payload layout.

UPL_FV:
FILE FREEFORM = 86d53a55-b604-402e-94a4-ac7220dd5c7b {
SECTION GUIDED EE4E5898-3914-4259-9D6E-DC7BD79403CF PROCESSING_REQUIRED = TRUE {
SECTION RAW = e:\work\payload_poc\tools\UPL.bin
}
}

FSP-R (FSP runtime)

Coreboot is very careful about not having a runtime, for good reasons. How is a closed source binary runtime suddenly a good idea?

confusing on image format, entrypoint definition and parameter passing in X64.

Current 0.75 spec uses definition below:

1. image format is ELF.

2. Entrypoint is cdecl
   typedef
   VOID
   (__cdecl *PAYLOAD_ENTRY) (
   EFI_HOB_HANDOFF_INFO_TABLE *HobList
   );

3. Parameter passing is RCX.
   RCX holds the address of the HOB list for the 64bit payload.

Only if we use VS to build PE image, with _cdecl convention, the parameter is RCX.
However, if we use GCC to build ELF image, with _cdecl convention, the parameter is RDI, not RCX.
If we use GCC and we want RCX, we need use attribute((ms_abi)), instead of _cdecl.

sFSP-at-reset

Why is this needed?
64-bit x86 support already exists in coreboot and is not Intel specific IP so there is no need for this to be inside a closed source binary.
The rationale behind FSP is to abstract Intel specific IP, but this is just not the case with the reset vector and early code as every x86 CPU from the last 25 years booted with the same early code in coreboot.

make ACPI support a payload responsibility

I see from the current state of the spec that building an ACPI table is part of the work that a bootloader should do and that it's considered part of the handoff state to the payload. Asking a few questions around this I learn that this arises from the wish for [some] payloads to support Windows boot (which absolutely requires ACPI) and yet avoid putting some of the very platform specific knowledge into the payload that is more readily handled in the bootloader phase.

I'd like to suggest that making the bootloader do full ACPI support may be an unreasonable burden to address the requirement. An alternate design might be to export the platform specifics from the bootloader and enable the payload to assemble a complete ACPI table if that is necessary for its purposes.

The typical means of export appears from the spec to be HOB list entries. For the kinds of information that would need to end up in an ACPI table it seems more logical to ask the bootloader to provide information in HOBs but to leverage the ACPI individual table entry formats to do that. So imagine a self-describing HOB (see issue #9), that wraps a single table that follows the ACPI defined format for the information that it contains. Multiply that by the number of tables required to convey the platform specific information. Allow the payload to search the HOB list for ACPI-looking things that it can then assemble into a full ACPI table structure.

At the heart of the matter, if there's a perception that the bootloader has to spit out a fully conforming ACPI table structure, RSDT and all, then I believe that's worth re-examining to see if we can avoid the burden of full ACPI compliance in bootloaders that want to support the range of conforming payloads. That particularly applies to bootloaders that are unlikely to be used in the context of payloads that can boot Windows.

HOBS should be self-describing structures

HOBS should not be binary blobs with no way to determine what is in them.

Protobufs might be overkill but some form of self-describing structure is essential.

FSP loading SMM

The industry is moving away from SMM for security and performance reasons.
So as little SMM as possible is desirable and if it is required then having it open source so it can be audited is a must for security.
Moving SMM loading into FSP is therefore a huge security setback.
What is the rationale behind this proposal?

Need clear term for payload, payload data

Today the spec uses "Image" for payload and uses "actual payload" for the payload data.
It's a bit confusing.
I suggest:

1. Use "Payload" for the entire image including payload header and the data
2. Use "Payload Data" for the data portion, excluding the payloader header, reloc header, auth header.

Field name in payload header can be changed accordingly.

recommend to support E820 style memory map reporting mechanism

Current 0.75 spec only allows the resource hob style reporting. It is not so convenience to let payload parse the information.

I recommend we have E820 style reporting - an array of E820 entries. It is much simpler.

Payload handoff: PCI root bridge, redundant + not general enough

https://universalscalablefirmware.github.io/documentation/2_universal_payload.html#pci-root-bridges

This section talks about handing of information about PCI root bridge and what resources (IO & MEM) it is decoding.

It has the following issues:

1. There is a complete overlap with ACPI on this information.
2. It does not accurately represent PCI root bridges. On AMD hardware more than one, non-continuous range above and below 4G can decode memory. I haven't really checked to be sure but I vaguely remember that xeon_sp hardware can actually do the same but is typically not configured that way (or FSP at least never does that). Even on client hardware you have the flexibility to put for instance PCI memory below and above the MMCONF space.

Universal Payload Loaded Image Section

This section seems to mean that a runtime linker is required to load the payload?

Consider using an existing image format over a custom one

Instead of defining a completely new image header for payloads, I would much prefer to use an already-existing format, such as ELF (Executable and Linkable Format). Using mature, widely-used formats is simpler and eliminates the problems that may arise when defining a new image format, such as endianness. Given that TianoCore can already be built as an ELF executable, it shouldn't be too hard to switch payload build systems to generate ELF objects.

Terminology: Define term *bootloader*

The term bootloader is used, but not defined. It seems to be used differently, from what I am used to. (The program originally in the MBR. For example, GRUB is a bootloader.)