[TF-A] [RFC] Proposed location to host the firmware handoff specification.

[Jose Marinho]

Hi Julius,

Thank you for the comments!

As mentioned yesterday, the FW Handoff document is now publicly accessible from [1] -- note that this does not constitute a full document release.
Hopefully we'll be able to use that repo to agree on the open items before we do an initial full release of the document.

> 
> If perhaps the real concern is rather related to
> who controls future spec updates, tag assignments, etc.
> then I think we should address those directly and define clear processes that
> we can all feel comfortable with, rather than implying that the final word on
> these is left to whoever controls the hosting platform.
> 
The proposal is that the tag assignments are handled via a PR to [1].
A PR should provide reasoning for the proposed entry layout as well as a description of the use-case being serviced.
The community is invited to comment on the pull requests. We should aim to have community consensus before merging any PR.

> 
> I really don't see this as likely enough to be worth paying that big upfront cost
> of making the whole structure so much less efficient to start with. I think 8
> bytes are already the most you'd reasonably want to pay for header
> overhead, I find it highly improbable that we'd want to introduce more fields
> later to make that even bigger. If there's desire for optional large annotations
> (e.g. per-entry cryptographic
> hashes) in the future, I'd rather suggest implementing that as "companion
> entries" with special tags that are written right behind the entry they refer
> to, rather than try squeezing it all into a single header structure. If you want
> to leave some room for simple bit flags, I would suggest masking out the high
> byte of the data length field instead (i.e. splitting it into 3 and 1) -- it doesn't
> seem like anyone would want to pass a data item larger than 32 MB in a
> firmware information structure anyway.
> 

It seems sensible that data contained in an entry should not exceed 32MB.
Could we still accommodate the notion of a hdr_size in the TL entry header?
We'd have the following fields on an 8-byte TE header:
  tag_id -- 4 bytes
  hdr_size -- 1 byte
  Data_size -- 3 bytes

If this proposal addresses your concerns, we should create a PR for it to be discussed!

> FWIW I would suggest decoupling the data structure version from the
> document version and only increasing the data structure version when the
> actual structure changes in a meaningful way. Documents may be amended
> to improve clarity or add more detailed explanations that don't always
> require parsers to actually act differently, so increasing version numbers in
> the code for those cases would seem to just unnecessarily confuse things.
> 

The document and the TL version are now separate.
The document version is defined [2].
The TL version is present in the header [3] and shall be incremented when changes are introduced to either the TL header or the entries which a consumer must discover (via the data TL version).

> I think the spec should strongly encourage allocating a global tag
> whenever there might be the slightest possibility that other platforms might
> want to use it later
> 
The document states that any tag in the standard range must be allocated in the spec before being used in code [4] -- what this is really saying is: until a tag id is allocated anyone can request it. So code written assuming a particular standard tag id (absent from the spec) may have to change later if someone in the meantime allocates that tag id for a different entry type.
I believe it’s a per-community policy to prevent code submissions containing standard tag ids until these have been reserved in this spec.
This is the advised policy, but this spec cannot mandate it, rather we must rely on the communities to enforce this.

> I would expect at least some platforms to need the
> flexibility of keeping them separate and therefore think it would be better to
> standardize on that. But if other platforms really think it's important to have
> these inline in the transfer list for their use case, you could offer separate
> tags for both.

For the current set of entries, the data is included within the TL. Note that this does not prevent newer entries from pointing to off-TL data.
Could this be handled on a case-by-case basis, via pull request, after an initial full release of the spec?

Regards,
Jose

[1] https://github.com/FirmwareHandoff/firmware_handoff
[2]https://github.com/FirmwareHandoff/firmware_handoff/blob/1ce91def658a4fe26b95513717e48581df095b7b/source/conf.py#L29
[3] https://github.com/FirmwareHandoff/firmware_handoff/blob/main/source/transfer_list.rst#L76
[4]https://github.com/FirmwareHandoff/firmware_handoff/blame/main/source/transfer_list.rst#L170