From 83708f3ef77d157a4343d520906dda6aec83c840 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Tue, 14 Oct 2025 16:58:54 +0200 Subject: [PATCH 1/2] dasharo-binaries-paths-convention.md: Add MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/kb/dasharo-binaries-paths-convention.md | 94 ++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 docs/kb/dasharo-binaries-paths-convention.md diff --git a/docs/kb/dasharo-binaries-paths-convention.md b/docs/kb/dasharo-binaries-paths-convention.md new file mode 100644 index 0000000000..53edccb38f --- /dev/null +++ b/docs/kb/dasharo-binaries-paths-convention.md @@ -0,0 +1,94 @@ +# Dasharo Binaries Paths Convention + +Dasharo firmware binaries are available to download on [dl.3mdeb.com][dl.3mdeb.com] +and [dlui.dasharo.com][dlui.dasharo.com]. These sources are being managed +- manually +- using semi-manual automation +- fully automated CI + +The objective of this document is to describe a standard convention of the +directory tree and binary names used in Dasharo sources. It will make it easier +to navigate them and find the releases one is in interested in. + +## Directories Convention + +The standardised path to a release directory is as follows: + +`///[_payload]//` + +where: +- `` - hardware vendor, like `novacustom`, `protectli`, `hardkernel`, + `pcengines` +- `` - Precise device model, like `v540tu`, `vp6670`, `odroid-h4`, + `apu4` +- `` - firmware framework, like `coreboot`, `slimbootloader`, `heads` +- `[_payload]` - optional, firmware payload, like `_uefi`, `_heads`, `_seabios` +- `` - Dasharo version, like `v0.9.0`, `v1.7.2-rc1` + +Example, path to the v1.0.0 release binaries for Novacustom V540TU laptop: +- `/novacustom/v540tu/coreboot_uefi/1.0.0/` + +### Motivation + +#### [_payload] + +Historically, the firmware framework and payload were generally not present in +the paths, which looked like `///`. +When the support for new frameworks and payloads appeared, new directories +started to appear, like `//heads//` or +`//slimbootloader//` which made the paths +inconsistent with the older releases. + +To fix this inconsistency issue the framework and (optional) payload will +always be there, even if a platform has only support for a single +framework/payload combination to reduce the ambiguity. + +#### / + +The idea to separate the `` into the vendor and specific models +has a couple reasons behind it: +1. the number of combinations of vendor, microarchitecture and model family + resulted in too many directories on a single level +1. knowing just a model name it could be not that obvious which family + it is supposed to belong to +1. the firmware binaries for all the models from a family could be, or not be + compatible with the whole family, it could also change with releases and + require changing the directory structure +1. it was not clear how to release the firmware for just one device from a + family + +By separating the `vendor` and `model` into independent fields all the issues +above are solved. An additional bonus is that the user searching for the +binaries doesn't need to know technical details like the microarchitecture +of their CPU, just the name of the producer and the model of the device. + +[dl.3mdeb.com]: https://dl.3mdeb.com +[dlui.dasharo.com]: https://dlui.dasharo.com + +## Binary Names Convention + +To reduce the confusion and risk of mixing up binaries and allow for creating +multiple variants of a single binary without inconsistencies, the name of the +binary is also being standardised, and looks like: + +`__[_]_[_extra].` + +where: +- `` - hardware vendor, like `novacustom`, `protectli`, `hardkernel`, + `pcengines` +- `` - Precise device model, like `v540tu`, `vp6670`, `odroid-h4`, + `apu4` +- `` - firmware framework, like `coreboot`, `slimbootloader`, `heads` +- `[_payload]` - optional, firmware payload, like `_uefi`, `_heads`, `_seabios` +- `` - Dasharo version, like `v0.9.0`, `v1.7.2-rc1` +- `[_extra]` - optional additional info, like `_dev_signed`, `_btg_provisioned`, + `_eom` +- `` - `rom` for normal binaries, `cap` for UEFI Capsules, `cab` for + FWUPD cabinets etc. + +### Motivation + +This is especially important for the 3mdeb employees or users which flash their +devices often. Every binary should contain all the information required to +distinguish it from any other binary to reduce the risk of bricking the device +or other mishaps during flashing. From e5115b97614867e8a236ab6cfafb56db4d87c80d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Tue, 14 Oct 2025 18:14:53 +0200 Subject: [PATCH 2/2] dasharo-binaries-paths-convention.md: Add more path examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/kb/dasharo-binaries-paths-convention.md | 24 ++++++++++++++++---- mkdocs.yml | 1 + 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/kb/dasharo-binaries-paths-convention.md b/docs/kb/dasharo-binaries-paths-convention.md index 53edccb38f..b679baf338 100644 --- a/docs/kb/dasharo-binaries-paths-convention.md +++ b/docs/kb/dasharo-binaries-paths-convention.md @@ -23,10 +23,26 @@ where: `apu4` - `` - firmware framework, like `coreboot`, `slimbootloader`, `heads` - `[_payload]` - optional, firmware payload, like `_uefi`, `_heads`, `_seabios` -- `` - Dasharo version, like `v0.9.0`, `v1.7.2-rc1` - -Example, path to the v1.0.0 release binaries for Novacustom V540TU laptop: -- `/novacustom/v540tu/coreboot_uefi/1.0.0/` +- `` - Dasharo version, like `v0.9.0`, `v1.7.2-rc1`, compliant with + the [versioning scheme](https://docs.dasharo.com/dev-proc/versioning/). + +Examples: +- Dasharo (coreboot+Heads) Community Package for Novacustom V540TNx 14th + Gen laptops v1.0.0 + + (historically kept in one path due to compatibility): + + `/novacustom/v540tnd/coreboot_heads/1.0.0/` + + `/novacustom/v540tne/coreboot_heads/1.0.0/` +- Dasharo (coreboot+UEFI) Pro Package for Protectli V1000-series v0.9.3 + + (historically kept in two directories, a common `protectli_vault_jsl` + path, + and in more specific variants like `protectli_vault_jsl_v1210` due to + temporal compatibility): + + `/protectli/v1210/coreboot_uefi/v0.9.3/` + + `/protectli/v1410/coreboot_uefi/v0.9.3/` + + `/protectli/v1610/coreboot_uefi/v0.9.3/` +- Dasharo (coreboot+SeaBIOS) Community Package for PC Engines APU4 v24.08.00.01 + + (unique versioning scheme) + + `/pcengines/apu4/coreboot_seabios/v24.08.00.01/` ### Motivation diff --git a/mkdocs.yml b/mkdocs.yml index f4e5592f32..2811b2f9b5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -506,6 +506,7 @@ nav: - 'Knowledge base': - 'Glossary': glossary.md - 'Dasharo Product Naming Convention': dasharo-naming-convention.md + - 'Dasharo Binaries Path Convention': kb/dasharo-binaries-paths-convention.md - 'Dasharo menu documentation': - 'Overview': dasharo-menu-docs/overview.md - 'Boot Maintenance Manager': dasharo-menu-docs/boot-maintenance-mgr.md