On 12/12/20 12:29 AM, Heinrich Schuchardt wrote:

Dear all,

we have discussed that a protocol is needed to fix-up device trees loaded by GRUB or other boot managers.

In the U-Boot code we have actually the following actions for device-trees:

• load the device-tree to memory
• copy the device-tree to an allocated memory region which

has 12 KiB free space for device-tree fix-ups

• do the actual fix-ups, i.e. add new nodes or change properties
• reserve memory according to the /reserved-memory node and the

memory reservation block as EfiBootServicesData or as   EfiReservedMemoryType for no-map regions

• install the device-tree as configuration table

So I think the usage of a DT fix-up protocol could take the following steps:

• GRUB loads the device-tree allocating sufficient memory for fix-ups
• GRUB calls the protocol a fist time to add extra nodes and properties
• GRUB applies its own device-tree fix-ups
• GRUB calls the protocol a second time which

- reserves memory according to the /reserved-memory node   - installs the device-tree as configuration table

One could join both service calls if GRUB applies its own fix-ups first. But maybe GRUB wants to analyze U-Boot's fix-ups before committing its own ones.

So lets define a bit-field to pass to the fix-up protocol:

/* Add nodes and update properties */ #define EFI_DT_APPLY_FIXUPS    0x00000001 /*  * Reserve memory according to the /reserved-memory node  * and the memory reservation block  */ #define EFI_DT_RESERVE_MEMORY  0x00000002 /* Install the device-tree as configuration table */ #define EFI_DT_INSTALL_TABLE   0x00000004

Here is the rest of the proposed protocol definition:

#define EFI_DT_FIXUP_PROTOCOL_GUID \  { 0xe617d64c, 0xfe08, 0x46da, \  { 0xf4, 0xdc, 0xbb, 0xd5, 0x87, 0x0c, 0x73, 0x00 } }

typedef struct _EFI_DT_FIXUP_PROTOCOL { EFI_DT_FIXUP fixup; } EFI_DT_FIXUP_PROTOCOL;

typedef EFI_STATUS (EFIAPI *EFI_DT_FIXUP) (     IN EFI_DT_FIXUP_PROTOCOL *This,     IN VOID                  *Fdt,     IN OUT UINTN             *BufferSize,     IN UINT32                Flags,     );

This:       Pointer to the protocol Fdt:        Buffer with the device-tree. This shall be memory             of type EfiACPIReclaimMemory if Flags contains             EFI_DT_INSTALL_TABLE. BufferSize: Pointer to the size of the buffer including             trailing unused bytes for fix-ups.             If the buffer size is too small,             the required buffer size is returned. Flags:      Bitmap containing at least one of the values             EFI_DT_APPLY_FIXUPS, EFI_DT_RESERVE_MEMORY,             EFI_DT_INSTALL_TABLE. Indicates the actions             to be applied to the device-tree.

The selected actions indicated in Flags are applied in the sequence:

• Add nodes and update properties.
• Reserve memory according to the /reserved-memory node

and the memory reservation block

• Install the device-tree as configuration table

Memory is reserved as EfiBootServicesData if the reservation does not carry the no-map property and as EfiReservedMemoryType if it is marked as no-map.

If *BufferSize exceeds the value of the totalsize field header of device-tree header upon entry to the service, the totalsize field is set to *BufferSize.

Return values:

EFI_INVALID_PARAMETER - This is NULL or does not point to a valid                         EFI_DT_FIXUP_PROTOCOL implementation. EFI_INVALID_PARAMETER - Fdt or BufferSize is NULL EFI_INVALID_PARAMETER - *Fdt is not a valid device-tree                         (e.g. incorrect value of magic) EFI_INVALID_PARAMETER - Invalid value of Flags (zero or unknown bit) EFI_BUFFER_TOO_SMALL  - The buffer is too small to apply the fix-ups. EFI_SUCCESS           - All steps succeeded

If EFI_BUFFER_TOO_SMALL is returned, the device-tree is unmodified and *BufferSize is updated with the required buffer size for the provided device-tree.

The required buffer size when called with EFI_DT_APPLY_FIXUPS should enforce at least 4 KiB unused space for additional fix-ups by the operating system or the caller. The available space in the device-tree shall be determined using the device-tree header fields:

Available = header->totalsize               - header->off_dt_strings               - header->size_dt_strings;

(The strings block is always last in the flattened device-tree. There might be more space between blocks but not all device-tree libraries can use it.)

The required buffer size when called without EFI_DT_APPLY_FIXUPS shall be the value of the totalsize field of the flattened device tree header.

If any other error code is returned, the state of the device-tree is undefined. The caller should discard the buffer content.

The extent to which the validity of the device-tree is checked is implementation dependent. But a buffer without the correct value of the magic field of the flattened device tree header should always be rejected.

The protocol implementation is not required to check if the device-tree is in memory of type EfiACPIReclaimMemory.

Looking forward to your feedback.

I have created a git repository for the spec:

https://github.com/U-Boot-EFI/EFI_DT_FIXUP_PROTOCOL

We can discuss it via issues or pull requests.

Next step will be implementing this in a U-Boot fork.

Best regards

Heinrich