rimage: readme.md: update for rimage architecture and markdown rendering#10663
rimage: readme.md: update for rimage architecture and markdown rendering#10663lgirdwood wants to merge 1 commit intothesofproject:mainfrom
Conversation
No need to set a hard limit of 80 chars and add include information about the build flow and manifest structure. Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
lgirdwood
requested review from
dbaluta,
kv2019i,
lbetlej,
mmaka1 and
plbossart
as code owners
There was a problem hiding this comment.
Pull request overview
Updates tools/rimage documentation to better describe rimage’s architecture and rendering on GitHub, and to remove the previous hard-wrapping style.
Changes:
- Reflows existing README prose into longer single-line paragraphs (no ~80-col wrapping).
- Adds a “Deep Dive” section describing ELF-to-image conversion flow, output artifacts, and manifest structure.
- Adds Mermaid diagrams for the build flow and manifest layout.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 1. **CSS Header** (`struct css_header`): Cryptographic Signature Structure. Defines the fundamental size, modulus, public key, and RSA signatures used to authenticate the firmware image on the CSME/DSP side. | ||
| 2. **CSE Header** (`struct cse_header`): Converged Security Engine Header. A directory mapping security partitions to the ADSP firmware metadata. | ||
| 3. **Firmware Descriptor** (`struct sof_man_fw_desc`): |
There was a problem hiding this comment.
The README references struct css_header and struct cse_header, but the code defines versioned/typed structs (e.g., struct css_header_v1_8/_v2_5 and struct CsePartitionDirHeader/_v2_5). Update these names (or describe them generically) to keep the documentation aligned with the actual types.
| 1. **CSS Header** (`struct css_header`): Cryptographic Signature Structure. Defines the fundamental size, modulus, public key, and RSA signatures used to authenticate the firmware image on the CSME/DSP side. | |
| 2. **CSE Header** (`struct cse_header`): Converged Security Engine Header. A directory mapping security partitions to the ADSP firmware metadata. | |
| 3. **Firmware Descriptor** (`struct sof_man_fw_desc`): | |
| 1. **CSS Header** (CSS header struct, e.g. `struct css_header_v1_8`, `struct css_header_v2_5`): Cryptographic Signature Structure. Defines the fundamental size, modulus, public key, and RSA signatures used to authenticate the firmware image on the CSME/DSP side. | |
| 2. **CSE Header** (CSE partition directory header struct, e.g. `struct CsePartitionDirHeader`, `struct CsePartitionDirHeader_v2_5`): Converged Security Engine Header. A directory mapping security partitions to the ADSP firmware metadata. | |
| 3. **Firmware Descriptor** (`struct sof_man_fw_desc` and versioned variants): |
| --oneline in the SOF commit message. Find some good (and less good) | ||
| commit message examples for submodule updates at | ||
| https://github.com/thesofproject/sof/commits/main/rimage | ||
| First, push the tomlc99 commits you want to be tested to any branch of your tomlc99 fork on Github. Do _not_ submit an tomlc99 pull request yet. |
There was a problem hiding this comment.
Use consistent capitalization for the GitHub brand name ("GitHub"), including in this sentence.
| Nothing here is actually specific to SOF and tomlc99; you can apply the same test logic to any submodule and parent on Github. In fact the same logic applies to submodule alternatives. Github is the only requirement. | ||
|
|
There was a problem hiding this comment.
Use consistent capitalization for the GitHub brand name (currently "Github" appears multiple times in this paragraph).
| --oneline in the SOF commit message. Find some good (and less good) | ||
| commit message examples for submodule updates at | ||
| https://github.com/thesofproject/sof/commits/main/rimage | ||
| First, push the tomlc99 commits you want to be tested to any branch of your tomlc99 fork on Github. Do _not_ submit an tomlc99 pull request yet. |
There was a problem hiding this comment.
Grammar: use "a tomlc99 pull request" (not "an tomlc99 pull request").
| Note your tomlc99 fork must have been created using the actual "fork" button on Github so Github is aware of the connection with the upstream tomlc99 repo. In the top-left corner you should see `forked from thesofproject/tomlc99` under the name of your fork. If not then search the Internet for "re-attach detached github fork". | ||
|
|
||
| Then, **pretend** these tomlc99 commits have already been accepted and merged (they have been neither) and submit to SOF a draft pull request that updates the main SOF branch with your brand new tomlc99 commits to test. The only SOF commit in this SOF TEST pull request is an SOF commit that updates the tomlc99 pointer to the SHA of your last tomlc99 commit. If you're not sure how to do this then you must go back to the previous section and practice submodules more. | ||
|
|
||
| Submit this SOF pull request as a Github _draft_ so reviewers are _not_ notified. Starting every pull request as a draft is always a good idea but in this case this particular SOF pull request can be especially confusing because it points at commits in a different repo and commits that are not merged yet. So you _really_ don't want to bother busy reviewers (here's a secret: some of the reviewers don't like submodules either). You can freely switch back and forth between draft and ready status and should indeed switch to draft if you forgot at submission time but you can never "un-notify" reviewers. | ||
|
|
||
| Github has very good support for submodules and will display your SOF TEST pull request better than what the git command line can show. For instance Github will list your tomlc99 changes directly in the SOF Pull Request. So if something looks unexpected on Github then it means you did something wrong. Stop immediately (except for switching to draft if you forgot) and ask the closest git guru for help. |
There was a problem hiding this comment.
Use consistent capitalization for the GitHub brand name in this paragraph ("Github" appears multiple times).
There was a problem hiding this comment.
Capitalization fixed, thanks.
| E --> F | ||
| F --> G["Copy .text, .rodata, .bss to Image Buffer"] | ||
| G --> H["Hash Module Segments (SHA-256 / SHA-384)"] | ||
| H --> I["Finalize Manifest Headers (CSS/CSE/FW Desc)"] |
There was a problem hiding this comment.
The build-flow diagram says ".bss" is copied into the image buffer, but the implementation only copies loadable text/rodata sections; BSS is represented as a segment size/VA and not copied from the ELF (see man_module_create() in src/manifest.c). Update the diagram/step text to avoid implying BSS bytes are copied into the output image.
There was a problem hiding this comment.
Removed .bss from diagram, thanks.
| A[FW Image Manifest] | ||
| A --> B[1. CSS Header] | ||
| A --> C[2. CSE Header] | ||
| A --> D[3. Firmware Descriptor] | ||
| A --> E[4. Module Entries Array] | ||
| A --> F[5. ADSP Extension Metadata] |
There was a problem hiding this comment.
The manifest-structure diagram/text lists the CSS header before the CSE partition directory, but for v1.8+/v2.5 manifests the CSE partition dir header is at offset 0 and the CSS header follows (see struct fw_image_manifest_v1_8/_v2_5 in src/include/rimage/manifest.h). Consider reordering the diagram or clarifying that ordering differs by manifest version.
There was a problem hiding this comment.
Added a clarification note for v1.8+/v2.5 manifest permutations!
No need to set a hard limit of 80 chars and add include information about the build flow and manifest structure.