Generate Android boot images with binman
Subsystems (3)
v3 cover Generate Android boot images with binman
U-Boot is seeing increasing adoption on pocket computers, many of which (sadly) have fused bootloader chains. Many of these bootloaders have a very rigid definition of what a "valid" downstream payload looks like. Sometimes it's just a boring old v0/v2 Android boot image. Sometimes it's something decidedly more grotesque.
To date, this last-mile packaging step has been trapped in downstream CI pipelines, blogposts, documentation, etc. This patch series aims to gather up all that esoterica and institutional knowledge and codify it in U-Boot's build system, using binman.
Put differently: an overwhelming majority of these pocket computer devices have a "canonical" payload format that U-Boot currently has no support for. Let's fix that.
The first patches in this series introduce an android_boot etype. To begin with, this is a "typical" abootimg, as defined by canonical AOSP sources and reference fastboot/mkbootimg implementation. There's plenty of devices out there with a sane(-ish, nothing in Android-land is ever truly sane) bootloader that will happily chain a U-Boot rolled into the kernel section of an abootimg.
With that out of the way, the cursed bootloaders are next to be supported. Binman etypes for Qualcomm's "QCDT" and Samsung's "DTBH" formats are implemented. These are non-standard vendor-specific devicetree containers, which the previous bootloader uses to pick a FDT to boot the downstream with.
In both cases, these vendor-specific formats are tacked on to the end of a v0 abootimg, with the header_version being hijacked to encode the length of this following payload. Thus, the android_boot etype is retrofitted to allow these shenanigans.
Binman configs that produce flashable boot artifacts are introduced for the following devices:
* google-sargo (vanilla v2)
* oneplus-fajita (vanilla v2)
* samsung-a5u-eur (QCDT v0)
* samsung-gt510 (QCDT v0)
* samsung-j7xelte (DTBH v0)
I also successfully tested a vanilla v0 on my samsung-expressltexx, in conjunction with the qcom-armv7 series already on the list. However, since that work is still in-flight and the expressltexx DTS is downstream, I opted not to include it here.
Note that, I dropped the commits that introduce this support for Qualcomm devices, as it was NAK'd by "Qualcomm". I still think this is worth inclusion upstream for a couple of reasons:
* It's still useful for Exynos devices.
* If/when other non-qcom devices with fused Android bootloaders come along, it will likely be useful there as well.
* Downstreams can easily carry DTSI overlays for qcom devices to take advantage of this new native U-Boot support there.
* Maybe the hard position against binman will change/soften on the Qualcomm side, in which case we can simply start dropping in DTSIs to add support for those devices.
---
Changes in v3:
- android_boot etype:
- collapse _GetOptionalEntryData into _GetEntryData
- use self.Raise consistently for sane errors
- clean up and expand tests for 100% coverage
- fix docstring examples formatting
- remove unnecessary restriction on os-version in conjunction with
vendor-dt
- introduce Entry_Android_vendor_dt_table shared base class for
QCDT+DTBH.
- qcdt+dtbh etypes:
- formalize header/record format/size constants
- rework tests and hit 100% coverage
- binman:
- fix support for listing multiple names to binman test
- add fnmatch globbing support to binman test
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- Rebase on next
- Drop all qcom-related work as it has been NAK'd from mach-snapdragon
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Sam Day (10):
binman: support running multiple tests
binman: test name globbing support
binman: section: add AlignUp+PadToAlignment helpers
binman: Android boot image support .gitignore: ignore binman-generated blobs
binman: android_boot: vendor-dt support
binman: Add QCDT support
binman: Add DTBH support
arch: arm: exynos: add j7xelte binman config
configs: exynos-mobile: pull in binman
.gitignore | 1 + arch/arm/dts/exynos-mobile.dtsi | 5 + arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi | 26 ++ arch/arm/mach-exynos/Kconfig | 1 + configs/exynos-mobile_defconfig | 1 + tools/binman/android_vendor_dt_table.py | 104 ++++++ tools/binman/cmdline.py | 2 +- tools/binman/etype/android_boot.py | 376 +++++++++++++++++++++ tools/binman/etype/dtbh.py | 108 ++++++ tools/binman/etype/qcdt.py | 80 +++++ tools/binman/etype/section.py | 9 + tools/binman/ftest.py | 365 ++++++++++++++++++++ tools/binman/main.py | 8 +- tools/binman/test/android_boot_chonky_cells.dts | 13 + tools/binman/test/android_boot_dtb_in_v0.dts | 12 + tools/binman/test/android_boot_invalid_addr.dts | 13 + .../binman/test/android_boot_invalid_pagesize.dts | 11 + tools/binman/test/android_boot_invalid_subnode.dts | 12 + tools/binman/test/android_boot_missing_kernel.dts | 9 + .../test/android_boot_oversized_bootname.dts | 12 + .../test/android_boot_unsupported_version.dts | 11 + tools/binman/test/android_boot_v0.dts | 34 ++ .../test/android_boot_v0_pagesize_too_smol.dts | 12 + tools/binman/test/android_boot_v2.dts | 50 +++ tools/binman/test/android_boot_v2_missing_dtb.dts | 12 + .../test/android_boot_v2_pagesize_too_smol.dts | 13 + tools/binman/test/android_boot_v2_vendor_dt.dts | 14 + tools/binman/test/android_boot_vendor_dt.dts | 27 ++ tools/binman/test/dtbh.dts | 22 ++ tools/binman/test/dtbh_bad_model_info.dts | 20 ++ tools/binman/test/dtbh_invalid_pagesize.dts | 12 + tools/binman/test/dtbh_missing_model_info.dts | 16 + tools/binman/test/dtbh_missing_payload.dts | 15 + tools/binman/test/dtbh_missing_subnodes.dts | 10 + tools/binman/test/dtbh_multi.dts | 29 ++ tools/binman/test/dtbh_multiple_dtbs.dts | 22 ++ tools/binman/test/dtbh_page_size_from_abootimg.dts | 30 ++ tools/binman/test/dtbh_special_subnodes.dts | 11 + tools/binman/test/qcdt.dts | 36 ++ tools/binman/test/qcdt_bad_msm_id.dts | 17 + tools/binman/test/qcdt_invalid_pagesize.dts | 12 + tools/binman/test/qcdt_missing_msm_id.dts | 12 + tools/binman/test/qcdt_missing_payload.dts | 14 + tools/binman/test/qcdt_missing_subnodes.dts | 13 + tools/binman/test/qcdt_multiple_dtbs.dts | 34 ++ tools/binman/test/qcdt_page_size_from_abootimg.dts | 33 ++ tools/binman/test/qcdt_zero_pagesize.dts | 12 + tools/u_boot_pylib/test_util.py | 25 +- 48 files changed, 1724 insertions(+), 12 deletions(-)
---
base-commit: e91911169bc737ee4a79963a1cba8db2aab7c1c0
change-id: 20260604-android-binman-ad7a43f4e99d
Best regards,
Signature · 1 line
Sam Day <[email protected]>
PATCH v3 1/10 binman: support running multiple tests
The helptext for binman test suggests that this was already supported, but it wasn't properly wired up.
--- tools/binman/main.py | 8 ++++---- tools/u_boot_pylib/test_util.py | 23 ++++++++++++++++------- 2 files changed, 20 insertions(+), 11 deletions(-)
tools/binman/main.py +4 -4
@@ -58,8 +58,8 @@ def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - args: List of positional args provided to binman. This can hold a test - name to execute (as in 'binman test testSections', for example) + args: List of positional args provided to binman. This can hold test + names to execute (as in 'binman test testSections', for example) toolpath: List of paths to use for tools """ from binman import bintool_test
@@ -72,13 +72,13 @@ def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): from binman import image_test import doctest - test_name = args and args[0] or None + test_names = args or None # Run the entry tests first ,since these need to be the first to import the # 'entry' module. result = test_util.run_test_suites( 'binman', debug, verbosity, False, test_preserve_dirs, processes, - test_name, toolpath, + test_names, toolpath, [bintool_test.TestBintool, entry_test.TestEntry, ftest.TestFunctional, fdt_test.TestFdt, elf_test.TestElf, image_test.TestImage, cbfs_util_test.TestCbfs, fip_util_test.TestFip])
tools/u_boot_pylib/test_util.py +16 -7
@@ -157,7 +157,7 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - test_name: Name of test to run, or None for all + test_name: Name of test, or list of test names, to run; None for all toolpath: List of paths to use for tools class_and_module_list: List of test classes (type class) and module names (type str) to run
@@ -182,12 +182,19 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, resultclass=FullTextTestResult, ) - if use_concurrent and processes != 1 and not test_name: + if isinstance(test_name, str): + test_names = [test_name] + else: + test_names = list(test_name or []) + test_name_set = set(test_names) + + if use_concurrent and processes != 1 and not test_names: suite = ConcurrentTestSuite(suite, fork_for_tests(processes or multiprocessing.cpu_count())) for module in class_and_module_list: - if isinstance(module, str) and (not test_name or test_name == module): + if (isinstance(module, str) and + (not test_names or module in test_name_set)): suite.addTests(doctest.DocTestSuite(module)) for module in class_and_module_list:
@@ -197,15 +204,17 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, if hasattr(module, 'setup_test_args'): setup_test_args = getattr(module, 'setup_test_args') setup_test_args(preserve_indir=test_preserve_dirs, - preserve_outdirs=test_preserve_dirs and test_name is not None, + preserve_outdirs=test_preserve_dirs and bool(test_names), toolpath=toolpath, verbosity=verbosity, no_capture=no_capture) - if test_name: + if test_names: # Since Python v3.5 If an ImportError or AttributeError occurs # while traversing a name then a synthetic test that raises that # error when run will be returned. Check that the requested test # exists, otherwise these errors are included in the results. - if test_name in loader.getTestCaseNames(module): - suite.addTests(loader.loadTestsFromName(test_name, module)) + module_test_names = loader.getTestCaseNames(module) + for name in test_names: + if name in module_test_names: + suite.addTests(loader.loadTestsFromName(name, module)) else: suite.addTests(loader.loadTestsFromTestCase(module))
Signature · 1 line
2.54.0
Re: [PATCH v3 01/10] binman: support running multiple tests
Hi Sam,
Quoted 8 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: support running multiple tests
The helptext for binman test suggests that this was already supported, but it wasn't properly wired up.
tools/binman/main.py| 8 ++++----tools/u_boot_pylib/test_util.py | 23 ++++++++++++++++------- 2 files changed, 20 insertions(+), 11 deletions(-)
This looks good.
tools/u_boot_pylib/test_util.py def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, · line 161
Quoted 8 lines
tools/u_boot_pylib/test_util.py +1
-1@@ -157,7 +157,7 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - test_name: Name of test to run, or None for all + test_name: Name of test, or list of test names, to run; None for all toolpath: List of paths to use for tools
Since the parameter now accepts a list, please rename it to test_names and update the four other callers (tools/patman/__main__.py, tools/dtoc/main.py, tools/buildman/main.py, tools/u_boot_pylib/__main__.py, tools/dtoc/test_fdt.py) at the same time. The isinstance() branch then goes away too.
tools/u_boot_pylib/test_util.py def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, · line 189
Quoted 11 lines
tools/u_boot_pylib/test_util.py +5
-1@@ -182,12 +182,19 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, resultclass=FullTextTestResult, ) - if use_concurrent and processes != 1 and not test_name: + if isinstance(test_name, str): + test_names = [test_name] + else: + test_names = list(test_name or []) + test_name_set = set(test_names)
test_name_set is dead by the end of patch 2, which replaces 'module in test_name_set' with _match_name(module). Please fold the two patches so this set is never introduced, or skip building it here and just use 'in test_names' until patch 2 replaces the check.
tools/binman/main.py def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): · line 62
Quoted 9 lines
tools/binman/main.py +2
-2@@ -58,8 +58,8 @@ def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - args: List of positional args provided to binman. This can hold a test - name to execute (as in 'binman test testSections', for example) + args: List of positional args provided to binman. This can hold test + names to execute (as in 'binman test testSections', for example)
While you are here, the line above ("If a single test is selected (in args[0]) it also preserves the output directory for this test") is now stale - preserve_outdirs fires for any number of selected tests. Same comment for the matching docstring in run_test_suites(). Please tidy both up.
Regards,
Simon
Re: [PATCH v3 01/10] binman: support running multiple tests
In reply to Sam DayHi Sam,
Quoted 4 lines · On 6/10/26 3:27 AM, Sam Day via B4 Relay wrote:
From: Sam Day <[email protected]>
The helptext for
binman testsuggests that this was already supported, but it wasn't properly wired up.
Thank you! I was bothered by it too many times but didn't bother looking into it too much.
We do need your Signed-off-by here though, see https://docs.u-boot-project.org/en/latest/develop/process.html#review-process-git-tags
Quoted 10 lines
--- tools/binman/main.py | 8 ++++---- tools/u_boot_pylib/test_util.py | 23 ++++++++++++++++------- 2 files changed, 20 insertions(+), 11 deletions(-)tools/binman/main.py +0
-0
tools/binman/main.py def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): · line 62
Quoted 7 lines
tools/binman/main.py +2
-2@@ -58,8 +58,8 @@ def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - args: List of positional args provided to binman. This can hold a test - name to execute (as in 'binman test testSections', for example) + args: List of positional args provided to binman. This can hold test + names to execute (as in 'binman test testSections', for example)
issue: this is (already currently) misleading documentation
It's passed as is to run_test_suites() as test_name argument, so it's really only (a list of) tests we can pass. Can you please have a separate commit which updates this to reflect the actual intended usage of that parameter? Then base your other patches on top.
Quoted 24 lines
tools/binman/main.py +2
-2toolpath: List of paths to use for tools """ from binman import bintool_test@@ -72,13 +72,13 @@ def RunTests(debug, verbosity, processes, test_preserve_dirs, args, toolpath): from binman import image_test import doctest - test_name = args and args[0] or None + test_names = args or None # Run the entry tests first ,since these need to be the first to import the # 'entry' module. result = test_util.run_test_suites( 'binman', debug, verbosity, False, test_preserve_dirs, processes, - test_name, toolpath, + test_names, toolpath, [bintool_test.TestBintool, entry_test.TestEntry, ftest.TestFunctional, fdt_test.TestFdt, elf_test.TestElf, image_test.TestImage, cbfs_util_test.TestCbfs, fip_util_test.TestFip])tools/u_boot_pylib/test_util.py +0
-0
tools/u_boot_pylib/test_util.py def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, · line 160
Quoted 5 lines
tools/u_boot_pylib/test_util.py +1
-1@@ -157,7 +157,7 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, the output directory for this test. Both directories are displayed on the command line. processes: Number of processes to use to run tests (None=same as #CPUs) - test_name: Name of test to run, or None for all + test_name: Name of test, or list of test names, to run; None for all
question: what happens if we have an empty list?
I'm assuming we want the same as if we were to pass None?
tools/u_boot_pylib/test_util.py def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, · line 188
Quoted 12 lines
tools/u_boot_pylib/test_util.py +4
-1toolpath: List of paths to use for tools class_and_module_list: List of test classes (type class) and module names (type str) to run@@ -182,12 +182,19 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, resultclass=FullTextTestResult, ) - if use_concurrent and processes != 1 and not test_name: + if isinstance(test_name, str): + test_names = [test_name] + else: + test_names = list(test_name or [])
issue: no magic stuff based on the type of the argument
Please only support a list of test names. We need to update all callers of run_test_suites but then you'll quickly realize they all share the same pattern as binman, the caller expects multiple test names, but only passes the first one.
Cheers,
Quentin
PATCH v3 2/10 binman: test name globbing support
In reply to Sam DayThis makes invocations like binman test testAndroid* possible. It also composes well with the previous commit that adds support for multiple test names: binman test 'testAndroid*' 'testQcdt*' also works as you'd expect.
--- tools/binman/cmdline.py | 2 +- tools/u_boot_pylib/test_util.py | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-)
tools/binman/cmdline.py +1 -1
@@ -201,7 +201,7 @@ controlled by a description in the board device tree.''' 'preserve the output directory if a single test is run (pass ' 'test name at the end of the command line') test_parser.add_argument('tests', nargs='*', - help='Test names to run (omit for all)') + help='Test names/patterns to run (omit for all)') tool_parser = subparsers.add_parser('tool', help='Check bintools') tool_parser.add_argument('-l', '--list', action='store_true',
tools/u_boot_pylib/test_util.py +7 -5
@@ -4,6 +4,7 @@ # import doctest +import fnmatch import glob import multiprocessing import os
@@ -186,7 +187,9 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, test_names = [test_name] else: test_names = list(test_name or []) - test_name_set = set(test_names) + + def _match_name(name): + return any(fnmatch.fnmatchcase(name, pattern) for pattern in test_names) if use_concurrent and processes != 1 and not test_names: suite = ConcurrentTestSuite(suite,
@@ -194,7 +197,7 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, for module in class_and_module_list: if (isinstance(module, str) and - (not test_names or module in test_name_set)): + (not test_names or _match_name(module))): suite.addTests(doctest.DocTestSuite(module)) for module in class_and_module_list:
@@ -211,9 +214,8 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, # while traversing a name then a synthetic test that raises that # error when run will be returned. Check that the requested test # exists, otherwise these errors are included in the results. - module_test_names = loader.getTestCaseNames(module) - for name in test_names: - if name in module_test_names: + for name in loader.getTestCaseNames(module): + if _match_name(name): suite.addTests(loader.loadTestsFromName(name, module)) else: suite.addTests(loader.loadTestsFromTestCase(module))
Signature · 1 line
2.54.0
Re: [PATCH v3 02/10] binman: test name globbing support
Quoted 10 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: test name globbing support
This makes invocations like binman test testAndroid* possible. It also composes well with the previous commit that adds support for multiple test names: binman test 'testAndroid*' 'testQcdt*' also works as you'd expect.
tools/binman/cmdline.py| 2 +-tools/u_boot_pylib/test_util.py | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-)
Re: [PATCH v3 02/10] binman: test name globbing support
In reply to Sam DayHi Sam,
Quoted 6 lines · On 6/10/26 3:27 AM, Sam Day via B4 Relay wrote:
From: Sam Day <[email protected]>
This makes invocations like
binman test testAndroid*possible. It also composes well with the previous commit that adds support for multiple test names:binman test 'testAndroid*' 'testQcdt*'also works as you'd expect.
issue: missing Signed-off-by
I'm assuming it applies to the rest of the series, so won't repeat it.
Quoted 10 lines
--- tools/binman/cmdline.py | 2 +- tools/u_boot_pylib/test_util.py | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-)tools/binman/cmdline.py +0
-0
tools/binman/cmdline.py controlled by a description in the board device tree.''' · line 204
Quoted 5 lines
tools/binman/cmdline.py +1
-1@@ -201,7 +201,7 @@ controlled by a description in the board device tree.''' 'preserve the output directory if a single test is run (pass ' 'test name at the end of the command line') test_parser.add_argument('tests', nargs='*', - help='Test names to run (omit for all)') + help='Test names/patterns to run (omit for all)')
issue: insufficient information
What kind of patterns? A hint at fnmatchcase() would be enough for me.
Quoted 16 lines
tools/binman/cmdline.py +0
-0tool_parser = subparsers.add_parser('tool', help='Check bintools') tool_parser.add_argument('-l', '--list', action='store_true',tools/u_boot_pylib/test_util.py +1
-0@@ -4,6 +4,7 @@ # import doctest +import fnmatch import glob import multiprocessing import os
tools/u_boot_pylib/test_util.py def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, · line 193
Quoted 8 lines
tools/u_boot_pylib/test_util.py +3
-1@@ -186,7 +187,9 @@ def run_test_suites(toolname, debug, verbosity, no_capture, test_preserve_dirs, test_names = [test_name] else: test_names = list(test_name or []) - test_name_set = set(test_names) + + def _match_name(name): + return any(fnmatch.fnmatchcase(name, pattern) for pattern in test_names)
issue: please do not mix function definition and code
Move _match_name at the beginning of the function.
todo: please update buildman argparse args.terms description
buildman will too gain support for patterns as it calls this function as well.
Cheers,
Quentin
PATCH v3 3/10 binman: section: add AlignUp+PadToAlignment helpers
In reply to Sam DayIn the following commits we will be introducing new etypes derived from Entry_section which need to align values and pad data. To avoid duplication we introduce the shared helpers here.
--- tools/binman/etype/section.py | 9 +++++++++ 1 file changed, 9 insertions(+)
tools/binman/etype/section.py +9 -0
@@ -1040,3 +1040,12 @@ class Entry_section(Entry): for entry in entries.values(): return entry.read_elf_segments() return None + + def AlignUp(self, value, align): + """Return value aligned to given power of 2""" + return (value + align - 1) & ~(align - 1) + + + def PadToAlignment(self, data, align): + """Null-pads given data to given power of 2""" + return data + b'\0' * (self.AlignUp(len(data), align) - len(data))
Signature · 1 line
2.54.0
Re: [PATCH v3 03/10] binman: section: add AlignUp+PadToAlignment helpers
Hi Sam,
Quoted 11 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: section: add AlignUp+PadToAlignment helpers
In the following commits we will be introducing new etypes derived from
Entry_sectionwhich need to align values and pad data. To avoid duplication we introduce the shared helpers here.
tools/binman/etype/section.py| 9 +++++++++1 file changed, 9 insertions(+)
tools/binman/etype/section.py class Entry_section(Entry): · line 1042
Quoted 3 lines
tools/binman/etype/section.py +3
-0@@ -1040,3 +1040,12 @@ class Entry_section(Entry): + def AlignUp(self, value, align): + """Return value aligned to given power of 2""" + return (value + align - 1) & ~(align - 1)
We already have tools.align() in u_boot_pylib which does exactly this, and it is used widely in binman - please drop AlignUp() and have the qcdt/dtbh/android_boot callers use tools.align() directly.
tools/binman/etype/section.py class Entry_section(Entry): · line 1043
Quoted 6 lines
tools/binman/etype/section.py +4
-0@@ -1040,3 +1040,12 @@ class Entry_section(Entry): + + def PadToAlignment(self, data, align): + """Null-pads given data to given power of 2""" + return data + b'\0' * (self.AlignUp(len(data), align) - len(data))
This is a one-liner over tools.align() + tools.get_bytes():
data + tools.get_bytes(0, tools.align(len(data), align) - len(data))
I'd rather not add a method on Entry_section just for this - neither helper uses self, and the new etypes are the only callers. If you do want a shared helper, please put it in u_boot_pylib/tools.py as a plain function (e.g. pad_align()) alongside align() and get_bytes(), and use snake_case to match the convention there.
Also, stray double blank line between the two new methods.
Regards,
Simon
PATCH v3 4/10 binman: Android boot image support
In reply to Sam DayIntroduce initial support for Android boot images (abootimgs).
The AOSP implementation was used as a reference for this work.
We start with just v0 and v2 support. v1/v3/v4 are deliberately left unimplemented for now as no use-case has been found for them yet.
Since we're targeting U-Boot use cases here, a couple of things were omitted from this impl, namely "second" and recovery_dtbo support.
--- tools/binman/etype/android_boot.py | 285 +++++++++++++++++++++ tools/binman/ftest.py | 148 +++++++++++ tools/binman/test/android_boot_chonky_cells.dts | 13 + tools/binman/test/android_boot_dtb_in_v0.dts | 12 + tools/binman/test/android_boot_invalid_addr.dts | 13 + .../binman/test/android_boot_invalid_pagesize.dts | 11 + tools/binman/test/android_boot_invalid_subnode.dts | 12 + tools/binman/test/android_boot_missing_kernel.dts | 9 + .../test/android_boot_oversized_bootname.dts | 12 + .../test/android_boot_unsupported_version.dts | 11 + tools/binman/test/android_boot_v0.dts | 34 +++ .../test/android_boot_v0_pagesize_too_smol.dts | 12 + tools/binman/test/android_boot_v2.dts | 50 ++++ tools/binman/test/android_boot_v2_missing_dtb.dts | 12 + .../test/android_boot_v2_pagesize_too_smol.dts | 13 + tools/binman/test/android_boot_v2_vendor_dt.dts | 14 + 16 files changed, 661 insertions(+)
tools/binman/etype/android_boot.py new file +285 -0
@@ -0,0 +1,285 @@ +# SPDX-License-Identifier: GPL-2.0+ +# Entry-type module for Android boot images + +import hashlib +import struct + +from binman.entry import Entry +from binman.etype.section import Entry_section +from dtoc import fdt_util + + +BOOT_MAGIC = b'ANDROID!' +BOOT_NAME_SIZE = 16 +BOOT_ARGS_SIZE = 512 +IMAGE_ID_SIZE = 32 +BOOT_EXTRA_ARGS_SIZE = 1024 + +BOOT_IMAGE_HEADER_V0 = '<{}s10I{}s{}s{}s'.format(len(BOOT_MAGIC), + BOOT_NAME_SIZE, + BOOT_ARGS_SIZE, + IMAGE_ID_SIZE) +BOOT_IMAGE_HEADER_V0_SIZE = struct.calcsize(BOOT_IMAGE_HEADER_V0) +BOOT_IMAGE_HEADER_V2 = (BOOT_IMAGE_HEADER_V0 + + '{}sIQIIQ'.format(BOOT_EXTRA_ARGS_SIZE)) +BOOT_IMAGE_HEADER_V2_SIZE = struct.calcsize(BOOT_IMAGE_HEADER_V2) + + +class Entry_android_boot(Entry_section): + """Android boot image + + This creates an Android v0 or v2 boot image. + + A kernel payload, optional ramdisk payload can be supplied. A DTB payload + can also be provided when header_version == v2. + + Properties / Entry arguments: + - header-version: Android boot image header version, must be 0 or 2, + defaults to 0 + - page-size: Image page size, defaults to 2048 + - base: Base address added to the offsets below, defaults to 0x10000000 + - kernel-offset: Kernel load offset from base, defaults to 0x00008000 + - ramdisk-offset: Ramdisk load offset from base, defaults to 0x01000000 + - tags-offset: ATAGS/FDT offset from base, defaults to 0x00000100 + - dtb-offset: DTB load offset from base, defaults to 0x01f00000 + - os-version: Encoded Android OS version and patch level, defaults to 0 + - boot-name: Android boot image board name + - cmdline: Android boot command line + + This entry uses the following subnodes: + - kernel: section containing the executable payload + - dtb: section containing the DTB payload, used by header version 2 only + - ramdisk: optional section containing a ramdisk payload + + Example:: + A v2 abootimg with control FDT placed in the DTB section: + + android-boot { + header-version = <2>; + page-size = <4096>; + base = <0x12345678>; + kernel-offset = <0xCAFED00D>; + ramdisk-offset = <0xBEEFBABE>; + tags-offset = <0xFEEDDEAD>; + dtb-offset = <0x06660666>; + cmdline = "foo bar"; + + kernel { + u-boot-nodtb { + # Many Android bootloaders support gzipped kernels + compress = "gzip"; + }; + }; + + dtb { + u-boot-dtb { + }; + }; + }; + + Example:: + A v0 abootimg with embedded control FDT (v0 doesn't support DTBs) and + an empty ramdisk (some bootloaders insist on a ramdisk being present): + + android-boot { + header-version = <0>; + page-size = <2048>; + base = <0x80200000>; + + kernel { + u-boot { + no-expanded; + }; + }; + + ramdisk { + fill { + size = <1>; + }; + }; + }; + """ + + def ReadNode(self): + super().ReadNode() + self.header_version = fdt_util.GetInt(self._node, 'header-version', 0) + self.page_size = fdt_util.GetInt(self._node, 'page-size', 2048) + self.base = self._GetIntCells('base', 0x10000000) + self.kernel_offset = self._GetIntCells('kernel-offset', 0x00008000) + self.ramdisk_offset = self._GetIntCells('ramdisk-offset', 0x01000000) + self.tags_offset = self._GetIntCells('tags-offset', 0x00000100) + self.dtb_offset = self._GetIntCells('dtb-offset', 0x01f00000) + self.os_version = fdt_util.GetInt(self._node, 'os-version', 0) + self.boot_name = fdt_util.GetString(self._node, 'boot-name', '') + self.cmdline = fdt_util.GetString(self._node, 'cmdline', '') + + if self.header_version not in (0, 2): + self.Raise('Only Android boot image header versions 0 and 2 are ' + 'supported') + if self.page_size <= 0 or self.page_size & (self.page_size - 1): + self.Raise('page-size must be a power of two') + if 'kernel' not in self._entries: + self.Raise("Missing required subnode 'kernel'") + + if self.header_version == 0: + if self.page_size < BOOT_IMAGE_HEADER_V0_SIZE: + self.Raise('page-size must fit the Android boot image header') + if 'dtb' in self._entries: + self.Raise("Subnode 'dtb' requires header-version 2") + else: + # v2 + if self.page_size < BOOT_IMAGE_HEADER_V2_SIZE: + self.Raise('page-size must fit the Android boot image header') + if 'dtb' not in self._entries: + self.Raise("Missing required subnode 'dtb'") + + def ReadEntries(self): + for node in self._node.subnodes: + if node.name not in ('kernel', 'ramdisk', 'dtb'): + self.Raise("Unexpected subnode '%s'" % node.name) + + entry = Entry.Create(self, node, etype='section', + expanded=self.GetImage().use_expanded, + missing_etype=self.GetImage().missing_etype) + entry.ReadNode() + entry.SetPrefix(self._name_prefix) + self._entries[node.name] = entry + + def _GetIntCells(self, propname, default): + prop = self._node.props.get(propname) + if not prop: + return default + + values = prop.value if isinstance(prop.value, list) else [prop.value] + if len(values) > 2: + self.Raise("Property '%s' must contain one or two cells" % + propname) + + value = 0 + for cell in values: + value = value << 32 | fdt_util.fdt32_to_cpu(cell) + + return value + + def _GetAddr(self, offset, name, size=32): + addr = self.base + offset + if addr >= 1 << size: + self.Raise('%s address %#x does not fit in %d bits' % + (name, addr, size)) + + return addr + + def _CheckFit(self, name, data, size): + if len(data) > size: + self.Raise('%s is %d bytes, maximum is %d' % + (name, len(data), size)) + + return data + b'\0' * (size - len(data)) + + @staticmethod + def _BootId(*payloads): + digest = hashlib.sha1() + for data in payloads: + digest.update(data) + digest.update(struct.pack('<I', len(data))) + + return digest.digest() + b'\0' * 12 + + def _SplitCmdline(self): + cmdline = self.cmdline.encode('ascii') + b'\0' + return (self._CheckFit('cmdline', cmdline[:BOOT_ARGS_SIZE], + BOOT_ARGS_SIZE), + self._CheckFit('extra-cmdline', cmdline[BOOT_ARGS_SIZE:], + BOOT_EXTRA_ARGS_SIZE)) + + def _GetEntryData(self, name, required, default=None): + entry = self._entries.get(name) + if not entry and default is not None: + return default + return entry.GetData(required) + + def _BuildV0SectionData(self, required): + kernel = self._GetEntryData('kernel', required) + ramdisk = self._GetEntryData('ramdisk', required, b'') + if not required and (kernel is None or vendor_dt is None or + ramdisk is None): + return None + + boot_name = self._CheckFit('boot-name', self.boot_name.encode('ascii'), + BOOT_NAME_SIZE) + cmdline = self._CheckFit('cmdline', self.cmdline.encode('ascii'), + BOOT_ARGS_SIZE) + + boot_id_payloads = [kernel, ramdisk, b''] + image_id = self._BootId(*boot_id_payloads) + + header = struct.pack(BOOT_IMAGE_HEADER_V0, + BOOT_MAGIC, + len(kernel), + self._GetAddr(self.kernel_offset, 'kernel'), + len(ramdisk), + self._GetAddr(self.ramdisk_offset, 'ramdisk'), + 0, # second_len + 0, # second_offset + self._GetAddr(self.tags_offset, 'tags'), + self.page_size, + self.header_version, + self.os_version, + boot_name, + cmdline, + image_id) + + image = bytearray() + image += self.PadToAlignment(header, self.page_size) + image += self.PadToAlignment(kernel, self.page_size) + image += self.PadToAlignment(ramdisk, self.page_size) + + return bytes(image) + + def _BuildV2SectionData(self, required): + kernel = self._GetEntryData('kernel', required) + dtb = self._GetEntryData('dtb', required) + ramdisk = self._GetEntryData('ramdisk', required, b'') + if not required and (kernel is None or dtb is None): + return None + + boot_name = self._CheckFit('boot-name', self.boot_name.encode('ascii'), + BOOT_NAME_SIZE) + cmdline, extra_cmdline = self._SplitCmdline() + image_id = self._BootId(kernel, ramdisk, b'', b'', dtb) + + header = struct.pack(BOOT_IMAGE_HEADER_V2, + BOOT_MAGIC, + len(kernel), + self._GetAddr(self.kernel_offset, 'kernel'), + len(ramdisk), + self._GetAddr(self.ramdisk_offset, 'ramdisk'), + 0, # second_len + 0, # second_offset + self._GetAddr(self.tags_offset, 'tags'), + self.page_size, + self.header_version, + self.os_version, + boot_name, + cmdline, + image_id, + extra_cmdline, + 0, # recovery_dtbo_len + 0, # recovery_dtbo_offset + BOOT_IMAGE_HEADER_V2_SIZE, + len(dtb), + self._GetAddr(self.dtb_offset, 'dtb', size=64)) + + image = bytearray() + image += self.PadToAlignment(header, self.page_size) + image += self.PadToAlignment(kernel, self.page_size) + image += self.PadToAlignment(ramdisk, self.page_size) + image += self.PadToAlignment(dtb, self.page_size) + + return bytes(image) + + def BuildSectionData(self, required): + if self.header_version == 0: + return self._BuildV0SectionData(required) + + return self._BuildV2SectionData(required)
tools/binman/ftest.py +148 -0
154 lines not on this page · raw message
tools/binman/test/android_boot_chonky_cells.dts new file +13 -0
@@ -0,0 +1,13 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + base = <0xDEADBEEF 0xCAFED00D 0xDECAF>; + + kernel {}; + }; + }; +};
tools/binman/test/android_boot_dtb_in_v0.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + kernel {}; + dtb {}; + }; + }; +};
tools/binman/test/android_boot_invalid_addr.dts new file +13 -0
@@ -0,0 +1,13 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + kernel-offset = <0xDEADBEEF 0xCAFED00D>; + + kernel {}; + }; + }; +};
tools/binman/test/android_boot_invalid_pagesize.dts new file +11 -0
@@ -0,0 +1,11 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + page-size = <2049>; + }; + }; +};
tools/binman/test/android_boot_invalid_subnode.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + kernel {}; + bacon {}; + }; + }; +};
tools/binman/test/android_boot_missing_kernel.dts new file +9 -0
@@ -0,0 +1,9 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot {}; + }; +};
tools/binman/test/android_boot_oversized_bootname.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + boot-name = "this is decidedly longer than 16 bytes"; + kernel {}; + }; + }; +};
tools/binman/test/android_boot_unsupported_version.dts new file +11 -0
@@ -0,0 +1,11 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + header-version = <1>; + }; + }; +};
tools/binman/test/android_boot_v0.dts new file +34 -0
@@ -0,0 +1,34 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + /* confirm that android-boot can be referenced before it's built */ + collection { + content = <&abootimg>; + }; + + abootimg: android-boot { + header-version = <0>; + page-size = <0x800>; + base = <0x80200000>; + cmdline = "foo"; + + kernel { + u-boot { + no-expanded; + }; + }; + + ramdisk { + fill { + size = <1>; + }; + }; + }; + }; +};
tools/binman/test/android_boot_v0_pagesize_too_smol.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + page-size = <32>; + kernel {}; + }; + }; +};
tools/binman/test/android_boot_v2.dts new file +50 -0
50 lines not on this page · raw message
tools/binman/test/android_boot_v2_missing_dtb.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + header-version = <2>; + kernel {}; + }; + }; +};
tools/binman/test/android_boot_v2_pagesize_too_smol.dts new file +13 -0
@@ -0,0 +1,13 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + header-version = <2>; + page-size = <32>; + kernel {}; + }; + }; +};
tools/binman/test/android_boot_v2_vendor_dt.dts new file +14 -0
@@ -0,0 +1,14 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + header-version = <2>; + kernel {}; + dtb {}; + vendor-dt {}; + }; + }; +};
Signature · 1 line
2.54.0
Re: [PATCH v3 04/10] binman: Android boot image support
Hi Sam,
Quoted 41 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: Android boot image support
Introduce initial support for Android boot images (abootimgs).
The AOSP implementation was used as a reference for this work.
We start with just v0 and v2 support. v1/v3/v4 are deliberately left unimplemented for now as no use-case has been found for them yet.
Since we're targeting U-Boot use cases here, a couple of things were omitted from this impl, namely 'second' and
recovery_dtbosupport.Signed-off-by Sam Day <[email protected]>
tools/binman/etype/android_boot.py| 285 +++++++++++++++++++++tools/binman/ftest.py | 148 +++++++++++ tools/binman/test/android_boot_chonky_cells.dts | 13 + tools/binman/test/android_boot_dtb_in_v0.dts | 12 + tools/binman/test/android_boot_invalid_addr.dts | 13 + .../binman/test/android_boot_invalid_pagesize.dts | 11 + tools/binman/test/android_boot_invalid_subnode.dts | 12 + tools/binman/test/android_boot_missing_kernel.dts | 9 + .../test/android_boot_oversized_bootname.dts | 12 + .../test/android_boot_unsupported_version.dts | 11 + tools/binman/test/android_boot_v0.dts | 34 +++ .../test/android_boot_v0_pagesize_too_smol.dts | 12 + tools/binman/test/android_boot_v2.dts | 50 ++++ tools/binman/test/android_boot_v2_missing_dtb.dts | 12 + .../test/android_boot_v2_pagesize_too_smol.dts | 13 + tools/binman/test/android_boot_v2_vendor_dt.dts | 14 + 16 files changed, 661 insertions(+)tools/binman/etype/android_boot.py +6
-0@@ -0,0 +1,285 @@ + def _BuildV0SectionData(self, required): + kernel = self._GetEntryData('kernel', required) + ramdisk = self._GetEntryData('ramdisk', required, b'') + if not required and (kernel is None or vendor_dt is None or + ramdisk is None): + return None
...
tools/binman/test/android_boot_v2_vendor_dt.dts line 6
Quoted 8 lines
tools/binman/test/android_boot_v2_vendor_dt.dts +6
-0@@ -0,0 +1,14 @@ + android-boot { + header-version = <2>; + kernel {}; + dtb {}; + vendor-dt {}; + };
This fixture and the corresponding testAndroidBootV2VendorDt() in ftest.py belong in patch 6 - they exercise the vendor-dt subnode which this patch does not yet recognise. Against this commit alone, ReadEntries() raises "Unexpected subnode 'vendor-dt'" rather than the message the test asserts on. Also vendor_dt is not defined yet...please bisect-check the series.
tools/binman/etype/android_boot.py line 4
Quoted 6 lines
tools/binman/etype/android_boot.py +4
-0@@ -0,0 +1,285 @@ +BOOT_IMAGE_HEADER_V0 = '<{}s10I{}s{}s{}s'.format(len(BOOT_MAGIC), + BOOT_NAME_SIZE, + BOOT_ARGS_SIZE, + IMAGE_ID_SIZE)
Continuation lines are over-indented past the opening paren. Please align with the '(' or drop to a single hanging indent.
tools/binman/etype/android_boot.py line 2
Quoted 4 lines
tools/binman/etype/android_boot.py +2
-0@@ -0,0 +1,285 @@ + boot_id_payloads = [kernel, ramdisk, b''] + image_id = self._BootId(*boot_id_payloads)
The v2 path passes the payloads inline to _BootId() - please do the same here for consistency; the temporary list doesn't seem worth it.
Regards,
Simon
PATCH v3 5/10 .gitignore: ignore binman-generated blobs
In reply to Sam DayThe new android_boot etype is causing these /comp*u-boot-nodtb artifacts to be generated, which aren't currently picked up by any ignore rules. This issue only occurs when doing in-tree builds, but it's still worth fixing regardless.
--- .gitignore | 1 + 1 file changed, 1 insertion(+)
.gitignore +1 -0
@@ -84,6 +84,7 @@ fit-dtb.blob* /test/fdt_overlay/test-fdt-overlay-stacked.dtbo.S /test/fdt_overlay/test-fdt-overlay.dtbo.S capsule_esl_file +/comp.*.u-boot-nodtb # # Generated include files
Signature · 1 line
2.54.0
PATCH v3 6/10 binman: android_boot: vendor-dt support
In reply to Sam DayThere's many Android bootloaders out there that expect non-standard abootimgs. Samsung and Qualcomm, and likely many others. This quirk has been codified in the widely used osm0sis fork/rewrite of mkbootimg.
Presumably, these vendor-specific abootimgs were conceived before the v2 format was widely available or specified. The evidence for this is their hijacking of the header_version field to specify the length of a payload that follows the main abootimg.
At least QCDT and DTBH (both of which will be implemented as binman etypes in following commits) use this approach.
--- tools/binman/etype/android_boot.py | 41 ++++++++++++++++++++++++++-- tools/binman/ftest.py | 15 ++++++++++ tools/binman/test/android_boot_vendor_dt.dts | 27 ++++++++++++++++++ 3 files changed, 81 insertions(+), 2 deletions(-)
tools/binman/etype/android_boot.py +39 -2
@@ -33,6 +33,9 @@ class Entry_android_boot(Entry_section): A kernel payload, optional ramdisk payload can be supplied. A DTB payload can also be provided when header_version == v2. + Vendor-specific payloads are also supported. These are non-standard + v0 images with a special DT container format appended. + Properties / Entry arguments: - header-version: Android boot image header version, must be 0 or 2, defaults to 0
@@ -50,6 +53,7 @@ class Entry_android_boot(Entry_section): - kernel: section containing the executable payload - dtb: section containing the DTB payload, used by header version 2 only - ramdisk: optional section containing a ramdisk payload + - vendor-dt: legacy vendor DT payload, used by header version 0 only Example:: A v2 abootimg with control FDT placed in the DTB section:
@@ -112,6 +116,7 @@ class Entry_android_boot(Entry_section): self.os_version = fdt_util.GetInt(self._node, 'os-version', 0) self.boot_name = fdt_util.GetString(self._node, 'boot-name', '') self.cmdline = fdt_util.GetString(self._node, 'cmdline', '') + self.vendor_dt_node = self._node.FindNode('vendor-dt') if self.header_version not in (0, 2): self.Raise('Only Android boot image header versions 0 and 2 are '
@@ -132,9 +137,15 @@ class Entry_android_boot(Entry_section): self.Raise('page-size must fit the Android boot image header') if 'dtb' not in self._entries: self.Raise("Missing required subnode 'dtb'") + if self.vendor_dt_node: + self.Raise("Subnode 'vendor-dt' requires header-version 0") def ReadEntries(self): for node in self._node.subnodes: + if node.name == 'vendor-dt': + self._ReadVendorDtEntries(node) + continue + if node.name not in ('kernel', 'ramdisk', 'dtb'): self.Raise("Unexpected subnode '%s'" % node.name)
@@ -145,6 +156,14 @@ class Entry_android_boot(Entry_section): entry.SetPrefix(self._name_prefix) self._entries[node.name] = entry + def _ReadVendorDtEntries(self, vendor_dt_node): + entry = Entry.Create(self, vendor_dt_node, etype='section', + expanded=self.GetImage().use_expanded, + missing_etype=self.GetImage().missing_etype) + entry.ReadNode() + entry.SetPrefix(self._name_prefix) + self._entries[vendor_dt_node.name] = entry + def _GetIntCells(self, propname, default): prop = self._node.props.get(propname) if not prop:
@@ -198,8 +217,14 @@ class Entry_android_boot(Entry_section): return default return entry.GetData(required) + def _BuildVendorDt(self, required): + if not self.vendor_dt_node: + return b'' + return self._GetEntryData('vendor-dt', required) + def _BuildV0SectionData(self, required): kernel = self._GetEntryData('kernel', required) + vendor_dt = self._BuildVendorDt(required) ramdisk = self._GetEntryData('ramdisk', required, b'') if not required and (kernel is None or vendor_dt is None or ramdisk is None):
@@ -211,8 +236,18 @@ class Entry_android_boot(Entry_section): BOOT_ARGS_SIZE) boot_id_payloads = [kernel, ramdisk, b''] + if self.vendor_dt_node: + boot_id_payloads.append(vendor_dt) image_id = self._BootId(*boot_id_payloads) + overloaded_header_version = self.header_version + if self.vendor_dt_node: + # vendor DTs overload the header_version field to store the length + # of the appended payload. Hopefully AOSP abootimg never progresses + # to v8192-ish or we might have some real specificity problems on + # our hands. + overloaded_header_version = len(vendor_dt) + header = struct.pack(BOOT_IMAGE_HEADER_V0, BOOT_MAGIC, len(kernel),
@@ -223,7 +258,7 @@ class Entry_android_boot(Entry_section): 0, # second_offset self._GetAddr(self.tags_offset, 'tags'), self.page_size, - self.header_version, + overloaded_header_version, self.os_version, boot_name, cmdline,
@@ -233,6 +268,7 @@ class Entry_android_boot(Entry_section): image += self.PadToAlignment(header, self.page_size) image += self.PadToAlignment(kernel, self.page_size) image += self.PadToAlignment(ramdisk, self.page_size) + image += self.PadToAlignment(vendor_dt, self.page_size) return bytes(image)
@@ -240,7 +276,8 @@ class Entry_android_boot(Entry_section): kernel = self._GetEntryData('kernel', required) dtb = self._GetEntryData('dtb', required) ramdisk = self._GetEntryData('ramdisk', required, b'') - if not required and (kernel is None or dtb is None): + if not required and (kernel is None or dtb is None or + ramdisk is None): return None boot_name = self._CheckFit('boot-name', self.boot_name.encode('ascii'),
tools/binman/ftest.py +15 -0
@@ -5746,6 +5746,21 @@ fdt fdtmap Extract the devicetree blob from the fdtmap self.assertIn("Subnode 'vendor-dt' requires header-version 0", str(exc.exception)) + def testAndroidBootVendorDt(self): + """Test that android-boot can embed an arbitrary vendor-dt section""" + data = self._DoReadFile('android_boot_vendor_dt.dts') + header = struct.unpack_from('<8s10I16s512s32s', data, 0) + page_size = 2048 + vendor_dt_offset = page_size * 3 + vendor_dt = b'howdy' + self.assertEqual(len(vendor_dt), header[9]) + self.assertEqual(0, header[10]) + self.assertEqual(self._AndroidBootId(U_BOOT_DATA, b'\0', b'', + vendor_dt), header[13]) + self.assertEqual(vendor_dt + b'\0' * (page_size - len(vendor_dt)), + data[vendor_dt_offset:vendor_dt_offset + page_size]) + self.assertEqual(vendor_dt_offset + page_size, len(data)) + def testFitFdtOper(self): """Check handling of a specified FIT operation""" entry_args = {
tools/binman/test/android_boot_vendor_dt.dts new file +27 -0
@@ -0,0 +1,27 @@ +// SPDX-License-Identifier: GPL-2.0+ +/dts-v1/; +/ { + #address-cells = <1>; + #size-cells = <1>; + binman { + android-boot { + header-version = <0>; + kernel { + u-boot { + no-expanded; + }; + }; + ramdisk { + fill { + size = <1>; + }; + }; + vendor-dt { + text { + size = <5>; + text = "howdy"; + }; + }; + }; + }; +};
Signature · 1 line
2.54.0
Re: [PATCH v3 06/10] binman: android_boot: vendor-dt support
Hi Sam,
Quoted 25 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman:
android_boot: vendor-dt supportThere's many Android bootloaders out there that expect non-standard abootimgs. Samsung and Qualcomm, and likely many others. This quirk has been codified in the widely used osm0sis fork/rewrite of mkbootimg.
Presumably, these vendor-specific abootimgs were conceived before the v2 format was widely available or specified. The evidence for this is their hijacking of the
header_versionfield to specify the length of a payload that follows the main abootimg.At least QCDT and DTBH (both of which will be implemented as binman etypes in following commits) use this approach.
Signed-off-by Sam Day <[email protected]>
tools/binman/etype/android_boot.py| 41 ++++++++++++++++++++++++++--tools/binman/ftest.py | 15 ++++++++++ tools/binman/test/android_boot_vendor_dt.dts | 27 ++++++++++++++++++ 3 files changed, 81 insertions(+), 2 deletions(-)tools/binman/etype/android_boot.py +0
-0@@ -198,8 +217,14 @@ class Entry_android_boot(Entry_section): return default
tools/binman/etype/android_boot.py class Entry_android_boot(Entry_section): · line 227
Quoted 10 lines
tools/binman/etype/android_boot.py +6
-0return entry.GetData(required) + def _BuildVendorDt(self, required): + if not self.vendor_dt_node: + return b'' + return self._GetEntryData('vendor-dt', required) + def _BuildV0SectionData(self, required): kernel = self._GetEntryData('kernel', required) + vendor_dt = self._BuildVendorDt(required)
Since _ReadVendorDtEntries already stores the section under self._entries['vendor-dt'], this helper is just a thin wrapper. I think you can drop _BuildVendorDt and write:
vendor_dt = self._GetEntryData('vendor-dt', required, b'')
which mirrors how ramdisk is handled just below. What do you think?
Quoted 6 lines
tools/binman/etype/android_boot.py +1
-0@@ -211,8 +236,18 @@ class Entry_android_boot(Entry_section): BOOT_ARGS_SIZE) boot_id_payloads = [kernel, ramdisk, b''] + if self.vendor_dt_node:
tools/binman/etype/android_boot.py class Entry_android_boot(Entry_section): · line 249
Quoted 10 lines
tools/binman/etype/android_boot.py +8
-0+ boot_id_payloads.append(vendor_dt) image_id = self._BootId(*boot_id_payloads) + overloaded_header_version = self.header_version + if self.vendor_dt_node: + # vendor DTs overload the header_version field to store the length + # of the appended payload. Hopefully AOSP abootimg never progresses + # to v8192-ish or we might have some real specificity problems on + # our hands. + overloaded_header_version = len(vendor_dt)
Stray double space after the '=' on the assignment. Worth noting in the docstring that the vendor-dt subnode is itself a section, with a small example showing how to compose this with the QCDT/DTBH etypes added later.
Regards,
Simon
PATCH v3 7/10 binman: Add QCDT support
In reply to Sam DayThis vendor-specific format is used by many bootloaders on older qcom SoCs, such as msm8916. It's a container for N FDTs. Each one is contained in a record that includes metadata about the platform/variant it targets. The previous bootloader picks the "right" record based on this metadata.
This initial impl targets a streamlined v2 path, with no support for different versions or multiple qcom,msm-id/qcom,board-id tuples. If/when that's needed it will be implemented in a follow-up.
In the following commit, support for DTBH will also be introduced. Because QCDT and DTBH share a lot of common behaviour, this commit also introduces a Entry_Android_vendor_dt_table base class.
This impl was based on the lk2nd/CAF LK dtbTool script.
--- tools/binman/android_vendor_dt_table.py | 104 +++++++++++++++++++++ tools/binman/etype/android_boot.py | 31 ++++++ tools/binman/etype/qcdt.py | 80 ++++++++++++++++ tools/binman/ftest.py | 96 +++++++++++++++++++ tools/binman/test/qcdt.dts | 36 +++++++ tools/binman/test/qcdt_bad_msm_id.dts | 17 ++++ tools/binman/test/qcdt_invalid_pagesize.dts | 12 +++ tools/binman/test/qcdt_missing_msm_id.dts | 12 +++ tools/binman/test/qcdt_missing_payload.dts | 14 +++ tools/binman/test/qcdt_missing_subnodes.dts | 13 +++ tools/binman/test/qcdt_multiple_dtbs.dts | 34 +++++++ tools/binman/test/qcdt_page_size_from_abootimg.dts | 33 +++++++ tools/binman/test/qcdt_zero_pagesize.dts | 12 +++ 13 files changed, 494 insertions(+)
tools/binman/android_vendor_dt_table.py new file +104 -0
@@ -0,0 +1,104 @@ +# SPDX-License-Identifier: GPL-2.0+ + +from binman.entry import Entry +from binman.etype.section import Entry_section +from dtoc import fdt_util + + +class Entry_Android_vendor_dt_table(Entry_section): + """Base class for legacy Android vendor DT table entries""" + + @staticmethod + def _DtbEntryName(node): + return '_dtb_%s' % node.name + + def ReadNode(self): + super().ReadNode() + self._page_size = fdt_util.GetInt(self._node, 'page-size') + if (self._page_size is not None and + (self._page_size <= 0 or + self._page_size & (self._page_size - 1))): + self.Raise('page-size must be a power of two') + + def _GetPayloadSubnodes(self, node): + return [subnode for subnode in node.subnodes + if not self.IsSpecialSubnode(subnode)] + + def ReadEntries(self): + for node in self._node.subnodes: + if self.IsSpecialSubnode(node): + continue + + payloads = self._GetPayloadSubnodes(node) + if len(payloads) > 1: + self.Raise("subnode '%s': must contain exactly one DTB " + "payload subnode" % node.name) + if not payloads: + continue + + entry = Entry.Create(self, payloads[0], + expanded=self.GetImage().use_expanded, + missing_etype=self.GetImage().missing_etype) + entry.ReadNode() + entry.SetPrefix(self._name_prefix) + self._entries[self._DtbEntryName(node)] = entry + + def _GetPageSize(self): + if self._page_size is not None: + return self._page_size + + section = self.section + while section: + if section.etype == 'android-boot': + return section.page_size + section = section.section + + return 2048 + + def _GetU32Cells(self, node, propname): + prop = node.props.get(propname) + if not prop: + self.Raise("subnode '%s': Missing required property '%s'" % + (node.name, propname)) + + values = prop.value if isinstance(prop.value, list) else [prop.value] + return [fdt_util.fdt32_to_cpu(value) for value in values] + + def _GetU32Tuple(self, node, propname, width): + values = self._GetU32Cells(node, propname) + if len(values) != width: + self.Raise("subnode '%s': Property '%s' must contain exactly " + "%d cells" % (node.name, propname, width)) + + return tuple(values) + + def _GetDtbData(self, node, required): + entry = self._entries.get(self._DtbEntryName(node)) + if not entry: + self.Raise("subnode '%s': Missing required DTB payload subnode" % + node.name) + + data = entry.GetData(required) + if data is None and not required: + return None + + return data + + def _GetDtbRecordData(self, node, required): + return self._GetDtbData(node, required) + + def _ReadDtbRecords(self, required, read_record): + records = [] + for node in self._node.subnodes: + if self.IsSpecialSubnode(node): + continue + + data = self._GetDtbRecordData(node, required) + if data is None and not required: + return None + records.append(read_record(node, data)) + + if not records: + self.Raise('Missing required DTB subnodes') + + return records
tools/binman/etype/android_boot.py +31 -0
@@ -102,6 +102,37 @@ class Entry_android_boot(Entry_section): }; }; }; + + Example:: + A legacy QCDT abootimg, the kind msm8916 bootloaders expect: + + android-boot { + base = <0x80000000>; + + kernel { + u-boot { + no-expanded; + }; + }; + + ramdisk { + fill { + size = <1>; + }; + }; + + vendor-dt { + qcdt { + dtb-0 { + qcom,msm-id = <206 0>; + qcom,board-id = <0xce08ff01 1>; + + u-boot-dtb { + }; + }; + }; + }; + }; """ def ReadNode(self):
tools/binman/etype/qcdt.py new file +80 -0
80 lines not on this page · raw message
tools/binman/ftest.py +96 -0
102 lines not on this page · raw message
tools/binman/test/qcdt.dts new file +36 -0
@@ -0,0 +1,36 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + /* confirm that qcdt can be referenced before it's built */ + collection { + content = <&qcdt>; + }; + + qcdt: qcdt { + hash { + }; + + dtb-0 { + qcom,msm-id = <0xce 0>; + qcom,board-id = <0xce08ff01 1>; + + u-boot-dtb { + }; + }; + + dtb-1 { + qcom,msm-id = <0xcf 1>; + qcom,board-id = <0xce08ff02 2>; + + u-boot-dtb { + }; + }; + }; + }; +};
tools/binman/test/qcdt_bad_msm_id.dts new file +17 -0
@@ -0,0 +1,17 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + qcdt { + dtb-0 { + qcom,msm-id = <0xce 0 1>; + qcom,board-id = <0xce08ff01 1>; + }; + }; + }; +};
tools/binman/test/qcdt_invalid_pagesize.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + qcdt { + page-size = <2049>; + dtb-0 {}; + }; + }; +};
tools/binman/test/qcdt_missing_msm_id.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + qcdt { + dtb-0 { + }; + }; + }; +};
tools/binman/test/qcdt_missing_payload.dts new file +14 -0
@@ -0,0 +1,14 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + qcdt { + dtb-0 { + qcom,msm-id = <0xce 0>; + qcom,board-id = <0xce08ff01 1>; + }; + }; + }; +};
tools/binman/test/qcdt_missing_subnodes.dts new file +13 -0
@@ -0,0 +1,13 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + qcdt { + }; + }; +};
tools/binman/test/qcdt_multiple_dtbs.dts new file +34 -0
@@ -0,0 +1,34 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + qcdt { + page-size = <0x100>; + + dtb-0 { + qcom,msm-id = <0xce 0>; + qcom,board-id = <0xce08ff01 1>; + + fill { + size = <1>; + fill-byte = [11]; + }; + }; + + dtb-1 { + qcom,msm-id = <0xcf 2>; + qcom,board-id = <0xce08ff02 3>; + + fill { + size = <1>; + fill-byte = [22]; + }; + }; + }; + }; +};
tools/binman/test/qcdt_page_size_from_abootimg.dts new file +33 -0
@@ -0,0 +1,33 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <1>; + #size-cells = <1>; + + binman { + android-boot { + page-size = <4096>; + + kernel { + fill { + size = <1>; + }; + }; + + vendor-dt { + qcdt { + dtb-0 { + qcom,msm-id = <0 0>; + qcom,board-id = <0 0>; + + fill { + size = <1>; + }; + }; + }; + }; + }; + }; +};
tools/binman/test/qcdt_zero_pagesize.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + qcdt { + page-size = <0>; + dtb-0 {}; + }; + }; +};
Signature · 1 line
2.54.0
Re: [PATCH v3 07/10] binman: Add QCDT support
Hi Sam,
Quoted 38 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: Add QCDT support
This vendor-specific format is used by many bootloaders on older qcom SoCs, such as msm8916. It's a container for N FDTs. Each one is contained in a record that includes metadata about the platform/variant it targets. The previous bootloader picks the 'right' record based on this metadata.
This initial impl targets a streamlined v2 path, with no support for different versions or multiple qcom,msm-id/qcom,board-id tuples. If/when that's needed it will be implemented in a follow-up.
In the following commit, support for DTBH will also be introduced. Because QCDT and DTBH share a lot of common behaviour, this commit also introduces a
Entry_Android_vendor_dt_tablebase class.This impl was based on the lk2nd/CAF LK dtbTool script.
Signed-off-by Sam Day <[email protected]>
tools/binman/android_vendor_dt_table.py| 104 +++++++++++++++++++++tools/binman/etype/android_boot.py | 31 ++++++ tools/binman/etype/qcdt.py | 80 ++++++++++++++++ tools/binman/ftest.py | 96 +++++++++++++++++++ tools/binman/test/qcdt.dts | 36 +++++++ tools/binman/test/qcdt_bad_msm_id.dts | 17 ++++ tools/binman/test/qcdt_invalid_pagesize.dts | 12 +++ tools/binman/test/qcdt_missing_msm_id.dts | 12 +++ tools/binman/test/qcdt_missing_payload.dts | 14 +++ tools/binman/test/qcdt_missing_subnodes.dts | 13 +++ tools/binman/test/qcdt_multiple_dtbs.dts | 34 +++++++ tools/binman/test/qcdt_page_size_from_abootimg.dts | 33 +++++++ tools/binman/test/qcdt_zero_pagesize.dts | 12 +++ 13 files changed, 494 insertions(+)
tools/binman/android_vendor_dt_table.py line 2
Quoted 2 lines
tools/binman/android_vendor_dt_table.py +2
-0@@ -0,0 +1,104 @@ +class Entry_Android_vendor_dt_table(Entry_section): + """Base class for legacy Android vendor DT table entries"""
The capital A breaks the naming convention every other entry type follows (Entry_section, Entry_android_boot).
I'm not 100% sure about the best way to do this base class - but let's run with what you have and see how it goes. We can always tweak later, e.g. if someone else does a similar thing.
tools/binman/android_vendor_dt_table.py line 11
Quoted 13 lines
tools/binman/android_vendor_dt_table.py +11
-0@@ -0,0 +1,104 @@ + def ReadEntries(self): + for node in self._node.subnodes: + if self.IsSpecialSubnode(node): + continue + + payloads = self._GetPayloadSubnodes(node) + if len(payloads) > 1: + self.Raise("subnode '%s': must contain exactly one DTB " + "payload subnode" % node.name) + if not payloads: + continue
The qcdt docstring advertises dtb-* subnodes, but nothing here enforces the name - any non-special subnode is treated as a DTB record. Either enforce the dtb- prefix so a typo produces a clear error, or drop the implication from the docs.
Also, silently skipping a record node with no payload subnode means the missing-payload error only surfaces later in _GetDtbData() - raising at ReadEntries time would give a more obvious error location.
tools/binman/etype/qcdt.py line 7
Quoted 9 lines
tools/binman/etype/qcdt.py +7
-0@@ -0,0 +1,80 @@ + Properties / Entry arguments: + - page-size: QCDT page size, defaults to 2048, unless there's a parent + android-boot node with an explicit page-size + + This entry uses the following subnodes: + - dtb-*: DTB records, each containing qcom,msm-id, qcom,board-id and + exactly one DTB payload entry
The docs do not mention that QCDT_VERSION is hardcoded to 2, nor do they describe what qcom,msm-id and qcom,board-id actually mean (platform_id/soc_rev and variant_id/hw_subtype). Since the etype rejects malformed values with a specific cell-count error, users will need this info to author a working DTS. Please flesh out the docstring.
tools/binman/etype/qcdt.py line 8
Quoted 10 lines
tools/binman/etype/qcdt.py +8
-0@@ -0,0 +1,80 @@ + def BuildSectionData(self, required): + page_size = self._GetPageSize() + dtbs = self._ReadDtbRecords(required, self._ReadDtbRecord) + if dtbs is None: + return None + + size = QCDT_HEADER_SIZE + len(dtbs) * QCDT_RECORD_SIZE + dtb_offset = self.AlignUp(size, page_size)
Just to check - page_size falls back to 2048 when no explicit setting and no parent android-boot is found. There is no validation that page_size is at least QCDT_HEADER_SIZE + N*QCDT_RECORD_SIZE; if a caller sets a tiny page-size and many DTBs, the first dtb_offset overflows into the page allocated for the header. Worth a sanity check, matching the V0/V2 header-size checks in android_boot.
Regards,
Simon
PATCH v3 8/10 binman: Add DTBH support
In reply to Sam DayDTBH, used by Samsung S-BOOT bootloaders, is similar to QCDT. That is, it's a multi-record container that carries vendor-specific magic values to assist the previous bootloader in picking the appropriate FDT for the booting device.
dtbTool-exynos was used as a reference for this implementation.
--- tools/binman/etype/android_boot.py | 23 +++++ tools/binman/etype/dtbh.py | 108 +++++++++++++++++++++ tools/binman/ftest.py | 106 ++++++++++++++++++++ tools/binman/test/dtbh.dts | 22 +++++ tools/binman/test/dtbh_bad_model_info.dts | 20 ++++ tools/binman/test/dtbh_invalid_pagesize.dts | 12 +++ tools/binman/test/dtbh_missing_model_info.dts | 16 +++ tools/binman/test/dtbh_missing_payload.dts | 15 +++ tools/binman/test/dtbh_missing_subnodes.dts | 10 ++ tools/binman/test/dtbh_multi.dts | 29 ++++++ tools/binman/test/dtbh_multiple_dtbs.dts | 22 +++++ tools/binman/test/dtbh_page_size_from_abootimg.dts | 30 ++++++ tools/binman/test/dtbh_special_subnodes.dts | 11 +++ 13 files changed, 424 insertions(+)
tools/binman/etype/android_boot.py +23 -0
@@ -127,6 +127,29 @@ class Entry_android_boot(Entry_section): qcom,msm-id = <206 0>; qcom,board-id = <0xce08ff01 1>; + u-boot-dtb { + }; + }; + }; + }; + }; + + Example:: + A legacy DTBH abootimg, the kind some Samsung bootloaders expect: + + android-boot { + kernel { + u-boot-nodtb { + }; + }; + + vendor-dt { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <123>; + model_info-hw_rev_end = <321>; + u-boot-dtb { }; };
tools/binman/etype/dtbh.py new file +108 -0
108 lines not on this page · raw message
tools/binman/ftest.py +106 -0
112 lines not on this page · raw message
tools/binman/test/dtbh.dts new file +22 -0
@@ -0,0 +1,22 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + /* confirm that dtbh can be referenced before it's built */ + collection { + content = <&dtbh>; + }; + + dtbh: dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <123>; + model_info-hw_rev_end = <321>; + + u-boot-dtb {}; + }; + }; + }; +};
tools/binman/test/dtbh_bad_model_info.dts new file +20 -0
@@ -0,0 +1,20 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + #address-cells = <2>; + #size-cells = <1>; + + binman { + dtbh { + dtb-0 { + model_info-chip = <7870 1>; + model_info-hw_rev = <6>; + model_info-hw_rev_end = <6>; + + u-boot-dtb {}; + }; + }; + }; +};
tools/binman/test/dtbh_invalid_pagesize.dts new file +12 -0
@@ -0,0 +1,12 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + page-size = <2049>; + dtb-0 {}; + }; + }; +};
tools/binman/test/dtbh_missing_model_info.dts new file +16 -0
@@ -0,0 +1,16 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + dtb-0 { + model_info-hw_rev = <6>; + model_info-hw_rev_end = <6>; + + u-boot-dtb {}; + }; + }; + }; +};
tools/binman/test/dtbh_missing_payload.dts new file +15 -0
@@ -0,0 +1,15 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <6>; + model_info-hw_rev_end = <6>; + }; + }; + }; +};
tools/binman/test/dtbh_missing_subnodes.dts new file +10 -0
@@ -0,0 +1,10 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + }; + }; +};
tools/binman/test/dtbh_multi.dts new file +29 -0
@@ -0,0 +1,29 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + page-size = <0x100>; + platform = <0x1234>; + subtype = <0x56789abc>; + + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <123>; + model_info-hw_rev_end = <321>; + + u-boot-dtb {}; + }; + + dtb-1 { + model_info-chip = <7871>; + model_info-hw_rev = <124>; + model_info-hw_rev_end = <322>; + + u-boot-dtb {}; + }; + }; + }; +};
tools/binman/test/dtbh_multiple_dtbs.dts new file +22 -0
@@ -0,0 +1,22 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <6>; + model_info-hw_rev_end = <6>; + + fill { + size = <1>; + }; + text { + text = "x"; + }; + }; + }; + }; +};
tools/binman/test/dtbh_page_size_from_abootimg.dts new file +30 -0
@@ -0,0 +1,30 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + android-boot { + page-size = <4096>; + + kernel { + fill { + size = <1>; + }; + }; + + vendor-dt { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <6>; + model_info-hw_rev_end = <6>; + + u-boot-dtb { + }; + }; + }; + }; + }; + }; +};
tools/binman/test/dtbh_special_subnodes.dts new file +11 -0
@@ -0,0 +1,11 @@ +// SPDX-License-Identifier: GPL-2.0+ + +/dts-v1/; + +/ { + binman { + dtbh { + hash {}; + }; + }; +};
Signature · 1 line
2.54.0
Re: [PATCH v3 08/10] binman: Add DTBH support
Hi Sam,
Quoted 29 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
binman: Add DTBH support
DTBH, used by Samsung S-BOOT bootloaders, is similar to QCDT. That is, it's a multi-record container that carries vendor-specific magic values to assist the previous bootloader in picking the appropriate FDT for the booting device.
dtbTool-exynos was used as a reference for this implementation.
Signed-off-by Sam Day <[email protected]>
tools/binman/etype/android_boot.py| 23 +++++tools/binman/etype/dtbh.py | 108 +++++++++++++++++++++ tools/binman/ftest.py | 106 ++++++++++++++++++++ tools/binman/test/dtbh.dts | 22 +++++ tools/binman/test/dtbh_bad_model_info.dts | 20 ++++ tools/binman/test/dtbh_invalid_pagesize.dts | 12 +++ tools/binman/test/dtbh_missing_model_info.dts | 16 +++ tools/binman/test/dtbh_missing_payload.dts | 15 +++ tools/binman/test/dtbh_missing_subnodes.dts | 10 ++ tools/binman/test/dtbh_multi.dts | 29 ++++++ tools/binman/test/dtbh_multiple_dtbs.dts | 22 +++++ tools/binman/test/dtbh_page_size_from_abootimg.dts | 30 ++++++ tools/binman/test/dtbh_special_subnodes.dts | 11 +++ 13 files changed, 424 insertions(+)
tools/binman/etype/dtbh.py line 3
Quoted 3 lines
tools/binman/etype/dtbh.py +3
-0@@ -0,0 +1,108 @@ +# Fixed per-record "space delimiter" used by dtbTool-exynos. +# It's unclear what the 0x20 magic actually means, if anything. +DTBH_RECORD_SPACE = 0x20
Did you try probing a real S-BOOT to see if it cares? If it really is ignored, please say so explicitly ('S-BOOT appears to ignore this field; dtbTool-exynos emits 0x20 so we do too').
tools/binman/etype/dtbh.py line 2
Quoted 4 lines
tools/binman/etype/dtbh.py +2
-0@@ -0,0 +1,108 @@ +DTBH_MAGIC = b'DTBH' +DTBH_VERSION = 2
Just to check, are there older DTBH versions in the wild we might need to support, or is v2 the only thing S-BOOT will accept? A one-line comment would help future readers.
Regards,
Simon
PATCH v3 9/10 arch: arm: exynos: add j7xelte binman config
In reply to Sam DayNote that, as of this commit, j7xelte does not yet exist in U-Boot's upstream DTS tree. It was accepted into next so it should appear here eventually.
--- arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +26 -0
@@ -0,0 +1,26 @@ +// SPDX-License-Identifier: GPL-2.0 + +/ { + binman { + filename = "u-boot-samsung-j7xelte.img"; + + android-boot { + /* S-BOOT ignores offsets, so they are not provided here */ + kernel { + u-boot-nodtb { }; + }; + + vendor-dt { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <0>; + model_info-hw_rev_end = <255>; + + u-boot-dtb { }; + }; + }; + }; + }; + }; +};
Signature · 1 line
2.54.0
Re: [PATCH v3 09/10] arch: arm: exynos: add j7xelte binman config
Quoted 18 lines · On 2026-06-10 11:27 +10:00, Sam Day via B4 Relay wrote:
From: Sam Day <[email protected]>
Note that, as of this commit, j7xelte does not yet exist in U-Boot's upstream DTS tree. It was accepted into next so it should appear here eventually.
Signed-off-by Sam Day <[email protected]>--- arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +0
-0
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi line 1
Quoted 1 line
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +1
-0@@ -0,0 +1,26 @@ +// SPDX-License-Identifier: GPL-2.0
No copyright notice?
Quoted 25 lines
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +25
-0+ +/ { + binman { + filename = "u-boot-samsung-j7xelte.img"; + + android-boot { + /* S-BOOT ignores offsets, so they are not provided here */ + kernel { + u-boot-nodtb { }; + }; + + vendor-dt { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <0>; + model_info-hw_rev_end = <255>; + + u-boot-dtb { }; + }; + }; + }; + }; + }; +};
Re: [PATCH v3 09/10] arch: arm: exynos: add j7xelte binman config
In reply to Sam DayQuoted 5 lines · On 2026-06-10 11:27 +10:00, Sam Day via B4 Relay wrote:
From: Sam Day <[email protected]>
Note that, as of this commit, j7xelte does not yet exist in U-Boot's upstream DTS tree. It was accepted into next so it should appear here eventually.
The description seems lacking. A concise documentation for this build process would be nice, and the same must also be mentioned in doc/board/samsung/exynos-mobile.rst.
Quoted 39 lines
Signed-off-by Sam Day <[email protected]>--- arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+)arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +26
-0@@ -0,0 +1,26 @@ +// SPDX-License-Identifier: GPL-2.0 + +/ { + binman { + filename = "u-boot-samsung-j7xelte.img"; + + android-boot { + /* S-BOOT ignores offsets, so they are not provided here */ + kernel { + u-boot-nodtb { }; + }; + + vendor-dt { + dtbh { + dtb-0 { + model_info-chip = <7870>; + model_info-hw_rev = <0>; + model_info-hw_rev_end = <255>; + + u-boot-dtb { }; + }; + }; + }; + }; + }; +};
Re: [PATCH v3 09/10] arch: arm: exynos: add j7xelte binman config
In reply to Sam DayHi Sam,
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi
Quoted 17 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
arch: arm: exynos: add j7xelte binman config
Note that, as of this commit, j7xelte does not yet exist in U-Boot's upstream DTS tree. It was accepted into next so it should appear here eventually.
Signed-off-by Sam Day <[email protected]>
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi| 26 ++++++++++++++++++++++++++1 file changed, 26 insertions(+)arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +0
-0
As already mentioned the commit message only explains the caveat but does not say what the patch does. Please add a sentence describing the change - i.e. that this wires up binman to produce a DTBH+abootimg flashable for the j7xelte's S-BOOT.
Just to check, is exynos7870-j7xelte.dts in the tree somewhere or is that coming later?
Regards,
Simon
Re: [PATCH v3 09/10] arch: arm: exynos: add j7xelte binman config
Quoted 27 lines · Simon Glass
Hi Sam,
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi
Quoted 17 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
arch: arm: exynos: add j7xelte binman config
Note that, as of this commit, j7xelte does not yet exist in U-Boot's upstream DTS tree. It was accepted into next so it should appear here eventually.
Signed-off-by Sam Day <[email protected]>
arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi| 26 ++++++++++++++++++++++++++1 file changed, 26 insertions(+)arch/arm/dts/exynos7870-j7xelte-u-boot.dtsi new file +0
-0As already mentioned the commit message only explains the caveat but does not say what the patch does. Please add a sentence describing the change - i.e. that this wires up binman to produce a DTBH+abootimg flashable for the j7xelte's S-BOOT.
Quoted 2 lines
Just to check, is
exynos7870-j7xelte.dtsin the tree somewhere or is that coming later?
It's in next now, so it should be there by v7.2.x.
Quoted 5 lines
Reviewed-by Simon Glass <[email protected]>Regards,
Simon
PATCH v3 10/10 configs: exynos-mobile: pull in binman
In reply to Sam DayAll Exynos7 mobile devices need abootimg+DTBH wrapping to be bootable from the fused S-BOOT bootloader. So we enable binman everywhere. Ideally we'll have full coverage of these devices with binman configs in the overlay DTSIs but, for now, we ensure there's a placeholder node. That way no existing devices will regress their cleanly buildable state.
--- arch/arm/dts/exynos-mobile.dtsi | 5 +++++ arch/arm/mach-exynos/Kconfig | 1 + configs/exynos-mobile_defconfig | 1 + 3 files changed, 7 insertions(+)
arch/arm/dts/exynos-mobile.dtsi new file +5 -0
@@ -0,0 +1,5 @@ +// SPDX-License-Identifier: GPL-2.0 +/ { + binman { + }; +};
arch/arm/mach-exynos/Kconfig +1 -0
@@ -255,6 +255,7 @@ endif config TARGET_EXYNOS_MOBILE bool "Samsung Exynos Generic Boards (for mobile devices)" select ARM64 + select BINMAN select BOARD_EARLY_INIT_F select CLK_EXYNOS select LINUX_KERNEL_IMAGE_HEADER
configs/exynos-mobile_defconfig +1 -0
@@ -32,6 +32,7 @@ CONFIG_EFI_PARTITION=y CONFIG_OF_UPSTREAM=y CONFIG_OF_UPSTREAM_BUILD_VENDOR=y CONFIG_OF_BOARD=y +CONFIG_DEVICE_TREE_INCLUDES="exynos-mobile.dtsi" CONFIG_BLKMAP=y CONFIG_BUTTON_REMAP_PHONE_KEYS=y CONFIG_CLK_EXYNOS7870=y
Signature · 1 line
2.54.0
Re: [PATCH v3 10/10] configs: exynos-mobile: pull in binman
Quoted 22 lines · On 2026-06-10 11:27 +10:00, Sam Day via B4 Relay wrote:
From: Sam Day <[email protected]>
All Exynos7 mobile devices need abootimg+DTBH wrapping to be bootable from the fused S-BOOT bootloader. So we enable binman everywhere. Ideally we'll have full coverage of these devices with binman configs in the overlay DTSIs but, for now, we ensure there's a placeholder node. That way no existing devices will regress their cleanly buildable state.
Reviewed-by Simon Glass <[email protected]>Signed-off-by Sam Day <[email protected]>--- arch/arm/dts/exynos-mobile.dtsi | 5 +++++ arch/arm/mach-exynos/Kconfig | 1 + configs/exynos-mobile_defconfig | 1 + 3 files changed, 7 insertions(+)arch/arm/dts/exynos-mobile.dtsi new file +0
-0
arch/arm/dts/exynos-mobile.dtsi line 1
Quoted 1 line
arch/arm/dts/exynos-mobile.dtsi new file +1
-0@@ -0,0 +1,5 @@ +// SPDX-License-Identifier: GPL-2.0
No copyright notice?
Quoted 21 lines
arch/arm/dts/exynos-mobile.dtsi new file +4
-0+/ { + binman { + }; +};arch/arm/mach-exynos/Kconfig +1
-0@@ -255,6 +255,7 @@ endif config TARGET_EXYNOS_MOBILE bool "Samsung Exynos Generic Boards (for mobile devices)" select ARM64 + select BINMAN select BOARD_EARLY_INIT_F select CLK_EXYNOS select LINUX_KERNEL_IMAGE_HEADERconfigs/exynos-mobile_defconfig +0
-0
configs/exynos-mobile_defconfig CONFIG_EFI_PARTITION=y · line 35
Quoted 4 lines
configs/exynos-mobile_defconfig +1
-0@@ -32,6 +32,7 @@ CONFIG_EFI_PARTITION=y CONFIG_OF_UPSTREAM=y CONFIG_OF_UPSTREAM_BUILD_VENDOR=y CONFIG_OF_BOARD=y +CONFIG_DEVICE_TREE_INCLUDES="exynos-mobile.dtsi"
What about, instead of this you add an empty binman node to the other existing devices? I have tested it with on7xelte and j6lte and it works as intended.
After this is pulled in, I will submit a patch for binman changes for those devices, so there's no need of a new .dtsi file.
Alternatively, this series can carry said changes for those devices in a future revision if you want. Up to you.
Quoted 3 lines
configs/exynos-mobile_defconfig +0
-0CONFIG_BLKMAP=y CONFIG_BUTTON_REMAP_PHONE_KEYS=y CONFIG_CLK_EXYNOS7870=y
Hi Sam,
Quoted 11 lines · On 2026-06-10T01:27:41, Sam Day via B4 Relay…
Binman configs that produce flashable boot artifacts are introduced for the following devices:
* google-sargo (vanilla v2)
* oneplus-fajita (vanilla v2)
* samsung-a5u-eur (QCDT v0)
* samsung-gt510 (QCDT v0)
* samsung-j7xelte (DTBH v0)To date, this last-mile packaging step has been trapped in downstream CI pipelines, blogposts, documentation, etc.
Please add a short doc page under doc/ describing the android_boot/QCDT/DTBH entries from a board-porter's perspective - what to put in the -u-boot.dtsi, how to flash the resulting image, and which devices it has been tested on. The per-etype docstrings are great as reference but a narrative intro would help adopters.
Regards,
Simon