Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add flattened device tree/devicetree blobs specification #467

Merged
merged 24 commits into from
Aug 18, 2021
Merged

add flattened device tree/devicetree blobs specification #467

Changes from 3 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
453d819
add flattened device tree/devicetree blobs specification
armijnhemel Apr 3, 2021
e5596d5
dtb: add doc-ref to text versions of the specifications, add extra
armijnhemel Apr 3, 2021
efc6f28
dtb: add orig-ids, rename some ids, add xref, add more docs
armijnhemel Apr 3, 2021
41345e4
dtb: add links to example files, describe where on Linux systems files
armijnhemel Apr 3, 2021
f68d07c
dtb: add some applications that use DTB
armijnhemel Apr 7, 2021
5f5ba2f
dtb: clarify which strings are encoded in a subset of ASCII
armijnhemel Apr 7, 2021
ce10d84
dtb: fixes according to KSY style guide
armijnhemel Apr 8, 2021
0ea5632
dtb: use short(er) Git hash in doc-ref
armijnhemel Apr 8, 2021
7fc9eff
dtb: remove superfluous encoding lines
armijnhemel Apr 8, 2021
c4551e5
dtb: rewrite offsets to comply with style guide
armijnhemel Apr 8, 2021
1215a2b
dtb: style fixes, add instance to unlock some more data
armijnhemel Apr 8, 2021
5b83d43
dtb: process memory block
armijnhemel Apr 12, 2021
b3b6979
dtb: add `-webide-representation` to `fdt_begin_node`
generalmimon Jul 18, 2021
41155f6
dtb: remove `.rst` link from `doc` and `doc-ref`
generalmimon Jul 19, 2021
4d87410
dtb: use `*` instead of `-` for list bullets in `/doc`
generalmimon Aug 4, 2021
a8331ca
dtb: move from `database/` to `hardware/`
generalmimon Aug 18, 2021
4e11912
dtb: add `serialization` to `/meta/tags`
generalmimon Aug 18, 2021
ca73d6c
dtb: reorder `/types` so it makes more sense
generalmimon Aug 18, 2021
87ab85b
dtb: rename `{boundary_ => }padding`
generalmimon Aug 18, 2021
856a5c4
dtb: rename `{last => min}_compatible_version`
generalmimon Aug 18, 2021
c048a09
dtb: link to the HTML version of the specification instead of PDF
generalmimon Aug 18, 2021
8037492
dtb: drop field name prefixes
generalmimon Aug 18, 2021
65f9e70
dtb: minor `/doc` fixes
generalmimon Aug 18, 2021
45d9065
dtb: add more info to `/doc`
generalmimon Aug 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions database/dtb.ksy
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
meta:
id: dtb
title: Flattened Devicetree Format
file-extension: dtb
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
xref:
- wikidata: Q16960371
generalmimon marked this conversation as resolved.
Show resolved Hide resolved
license: CC0-1.0
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
endian: be
doc: |
Also referred to as Devicetree Blob (DTB). It is a flat
binary encoding of data (primarily devicetree data, although
other data is possible as well).

The encoding of strings used in the specification is actually a subset of ASCII:

https://github.com/devicetree-org/devicetree-specification/blob/master/source/chapter2-devicetree-basics.rst
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
doc-ref:
- https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.3
- https://github.com/devicetree-org/devicetree-specification/blob/ba2aa679679fc4fedf67130f18a6f0ecc4cf0382/source/flattened-format.rst
generalmimon marked this conversation as resolved.
Show resolved Hide resolved
- https://elinux.org/images/f/f4/Elc2013_Fernandes.pdf
seq:
- id: magic
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
contents: [0xd0, 0x0d, 0xfe, 0xed]
-orig-id: magic
- id: total_size
type: u4
-orig-id: totalsize
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
- id: structure_block_offset
type: u4
-orig-id: off_dt_struct
- id: strings_block_offset
type: u4
-orig-id: off_dt_strings
- id: memory_reservation_block_offset
type: u4
-orig-id: off_mem_rsvmap
- id: version
type: u4
-orig-id: version
- id: last_compatible_version
Copy link
Member

@generalmimon generalmimon Aug 4, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This name is misleading, at least to me - if I see last compatible version I imagine the latest one (i.e. the one that came last), not the lowest or earliest. However, it's clear that the spec intended the exact opposite:

last_comp_version
This field shall contain the lowest version of the devicetree data structure with which the version used is backwards compatible. So, for the structure as defined in this document (version 17), this field shall contain 16 because version 17 is backwards compatible with version 16, but not earlier versions. As per section 5.1, a DTSpec boot program should provide a devicetree in a format which is backwards compatible with version 16, and thus this field shall always contain 16.

I'm not sure why did the spec authors choose last_ adjective in the name. Probably when you imagine the latest version as the "first", then you go further into the version history and declare the oldest compatible version as the "last" that would the current version be compatible with (if we went beyond the "last", any older versions would no longer work). However, this concept seems to be upside down - I guess it's natural that "last" should mean latest (the last one that has been released so far) and the "first" would mean the initial version, i.e. the oldest version. In this justification for the spec's naming that I came up with, I needed to reverse the timeline and the role of "first" and "last" pointers (we go back in time).

Does first_compatible_version, oldest_compatible_version, lowest_compatible_version or min_compatible_version make more sense? Which one would you choose?

type: u4
valid:
max: version
-orig-id: last_comp_version
- id: boot_cpuid_phys
type: u4
-orig-id: boot_cpuid_phys
- id: strings_block_size
type: u4
-orig-id: size_dt_strings
- id: structure_block_size
type: u4
-orig-id: size_dt_struct
instances:
memory_reservation_block:
pos: memory_reservation_block_offset
size: structure_block_offset - memory_reservation_block_offset
structure_block:
pos: structure_block_offset
size: strings_block_offset - structure_block_offset
type: fdt_block
strings_block:
pos: strings_block_offset
size: strings_block_size
type: strings
types:
strings:
seq:
- id: strings
type: strz
encoding: ASCII
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
repeat: eos
fdt_node:
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
seq:
- id: token_type
type: u4
enum: fdt
- id: fdt_node_body
Copy link
Member

@generalmimon generalmimon Apr 8, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO just body is enough - prepending the superior type name is unnecessary.

sed -i 's/fdt_node_body/body/g' dtb.ksy

type:
switch-on: token_type
cases:
fdt::begin_node: fdt_begin_node
fdt::prop: fdt_prop
fdt_block:
seq:
- id: fdt_nodes
type: fdt_node
repeat: until
repeat-until: _.token_type == fdt::end
fdt_begin_node:
seq:
- id: name
type: strz
encoding: ASCII
armijnhemel marked this conversation as resolved.
Show resolved Hide resolved
- id: boundary_padding
size: (- _io.pos) % 4
fdt_prop:
seq:
- id: length
type: u4
-orig-id: len
- id: name_offset
type: u4
-orig-id: nameoff
- id: property
size: length
- id: boundary_padding
size: (- _io.pos) % 4
enums:
fdt:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't there a more meaningful enum name? I guess that fdt is an abbreviation of Flattened Devicetree Format, not something like token type.

Please don't forget about

kaitai_struct_formats/database/dtb.ksy

Lines 88 to 90 in c4551e5

- id: token_type
type: u4
enum: fdt

if you rename it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the word token here, maybe just type?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason I called it token is because they are called that in the documentation:

https://github.com/devicetree-org/devicetree-specification/blob/v0.3/source/flattened-format.rst#lexical-structure

The five token types are as follows:

Perhaps because they are in an element fdt_note it can indeed be just token. @generalmimon any thoughts?

0x00000001: begin_node
0x00000002: end_node
0x00000003: prop
0x00000004: nop
0x00000009: end