Hi Alper,
On Thu, 3 Aug 2023 at 14:29, Alper Nebi Yasak alpernebiyasak@gmail.com wrote:
On 2023-07-20 22:56 +03:00, Simon Glass wrote:
With this version I have done with a generic name, in this case 'data', as suggested by Alper Nebi Yasak. This may be controversial, but we may as well have the dicussion now. I assume that there are no other ongoing attempts to define the layout of firmware in devicetree.
Signed-off-by: Simon Glass sjg@chromium.org
Changes in v2:
- Reworked significantly based on Alper's comments
dtschema/schemas/firmware/binman/entry.yaml | 80 +++++++++++++++++++++ dtschema/schemas/firmware/image.yaml | 77 ++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 dtschema/schemas/firmware/binman/entry.yaml create mode 100644 dtschema/schemas/firmware/image.yaml
diff --git a/dtschema/schemas/firmware/binman/entry.yaml
b/dtschema/schemas/firmware/binman/entry.yaml
new file mode 100644 index 0000000..d50f96d --- /dev/null +++ b/dtschema/schemas/firmware/binman/entry.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Google LLC
+%YAML 1.2 +--- +$id: http://devicetree.org/schemas/firmware/image/entry.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml#
+title: Image entry
+maintainers:
- Simon Glass sjg@chromium.org
+description: |
- The entry node specifies a single entry in the firmware image.
- Entries have a specific type, such as "u-boot" or "atf-bl31". This
is provided
- using compatible = "data,<type>".
- Note: This definition is intended to be hierarchical, so that
entries can
- appear in other entries. Schema for that is TBD.
+properties:
- $nodename:
- pattern: "^[-a-z]+(-[0-9]+)?$"
- compatible:
- $ref: /schemas/types.yaml#/definitions/string
- offset:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: |
Provides the offset of this entry from the start of its parent
section.
This may be omitted in the description provided by Binman, in
which case
the value is calculated as part of image packing.- size:
- $ref: /schemas/types.yaml#/definitions/uint32
- description: |
Provides the size of this entry in bytes.This may be omitted in the description provided by Binman, in
which case
the value is calculated as part of image packing.So AFAIU, binman will take none/one/both of "offset" and "size" as inputs and will pass them to the output unmodified, instead adding a "reg" pair of their calculated final values?
Is there a schema-computational way to ensure that "reg" has to contain the same values as "offset" and "size"? Or is that not a restriction at all and "reg" overrides the others?
Probably we can do that in Python. But I don't expect people would use 'reg' in the image description as it is a pain.
- reg:
- description: |
Defines the offset and size of this entry, with reference to its
parent
image / section.Note This is typically omitted in the description provided to
Binman,
since the value is calculated as part of image packing. Separateproperties are provided for the size and offset of an entry, so
that it is
easy to specify none, one or both. The `reg` property is the
only one that
needs to be looked at once the image has been built.Do we not need a $ref for "reg"? Is there anything applicable?
Not from what I can tell. I think it is special?
BTW, I'm not that familiar with device-tree interpretation, I occasionally saw 'reg' being used as an <offset size> pair, and was mostly just asking if it's appropriate.
(Also TIL "ranges", and I'm imagining ranges = <0 $size 4G-$size 4G>; as an end-at-4gb replacement/generalization :P, but I know, later, later.)
Right, that is an x86-ism but is pretty helpful as it is otherwise widely confusing to deal with these addresses.
+required:
- compatible
+additionalProperties: false
+examples:
- |
- firmware {
image {compatible = "data,image";#address-cells = <1>;$size-cells = <1>;u-boot@0 {compatible = "data,u-boot";reg = <0 0xa0000>;};atf-bl31@0x100000 {compatible = "data,atf-bl31";reg = <0x100000 0x20000>;};};- };
diff --git a/dtschema/schemas/firmware/image.yaml
b/dtschema/schemas/firmware/image.yaml
new file mode 100644 index 0000000..949b067 --- /dev/null +++ b/dtschema/schemas/firmware/image.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Google LLC
+%YAML 1.2 +--- +$id: http://devicetree.org/schemas/firmware/image.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml#
+title: Binman firmware layout
+maintainers:
- Simon Glass sjg@chromium.org
+description: |
- The image node provides a layout for firmware, used when packaging
firmware
- from multiple projects. For now it just supports a very simple set of
- features, as a starting point for discussion.
- The Binman tool processes this node to produce a final image which
can be
- loaded into suitable storage device. Documentation is at:
- https://u-boot.readthedocs.io/en/latest/develop/package/binman.html
- The current image-description format is here:
https://u-boot.readthedocs.io/en/latest/develop/package/binman.html#image-de...
- It is desirable to reference the image from the storage-device node,
perhaps
- using an image-desc property:
- spiflash@0 {
compatible = "spidev", "jedec,spi-nor";image-desc = <&image>;Bikeshedding, but maybe "layout" or "data,layout" would be nicer.
OK
- };
- Note that the intention is to change Binman to use whatever schema
is agreed
- here.
+properties:
- $nodename:
- const: binman
Doesn't match the example, and I guess you mean "^[-a-z]+(-[0-9]+)?$" like the entry one.
Right.
- compatible:
- const: data,image
- "#address-cells":
- const: 1
- "#size-cells":
- const: 1
+required:
- compatible
- "#address-cell"
- "#size-cells"
+additionalProperties: false
+examples:
- |
- firmware {
image {compatible = "data,image";#address-cells = <1>;$size-cells = <1>;u-boot@0 {compatible = "data,u-boot";reg = <0 0xa0000>;};atf-bl31@0x100000 {compatible = "data,atf-bl31";reg = <0x100000 0x20000>;};};- };
Regards, Simon