diff --git a/AGENTS.md b/AGENTS.md index cc02a2c..c59cbae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,6 +66,7 @@ when W110 puts the regions in zooms of their own, their groups get a note instea ## Recipes - Show sizes: view.defaults.labels.size: true - Boundary + prev end: view.defaults.labels.address: both +- Hide addresses: view.defaults.labels.address: none - Zoom into a region: view.expand: [region_id] - Title a column: view.columns: [{ id: a, root: flash, title: Flash }] - Title a zoom: view.expand: [{ region: flash, title: Flash }] diff --git a/README.md b/README.md index a5568b7..280389e 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,7 @@ scripts and agents. | [nrf52840_boot_chain.yaml](examples/nrf52840_boot_chain.yaml) | Chained zooms, column `range`, per-column labels and scale, `start_of_next` | | [riscv64_soc.yaml](examples/riscv64_soc.yaml) | 64-bit addresses, `collapse_reserved_over`, relative heights, style options | | [rtos_mpu_ram.yaml](examples/rtos_mpu_ram.yaml) | `check_alignment`, `fill_gaps: none`, `depth`, two columns of one memory | +| [ota_package_format.yaml](examples/ota_package_format.yaml) | A file format instead of memory: `address: none`, byte sizes, a zoom to the left | To render them all into `build/`: diff --git a/examples/ota_package_format.yaml b/examples/ota_package_format.yaml new file mode 100644 index 0000000..eef871b --- /dev/null +++ b/examples/ota_package_format.yaml @@ -0,0 +1,42 @@ +# File format, not memory: an OTA update package as it is sent to the device. +# Only the order and size of the fields matter, so the addresses (file offsets) are hidden. +version: 1 +figure: { title: "OTA update package format", legend: true } + +memory: + regions: + - id: package + name: Update package + start: 0 + size: 256K + children: # placed sequentially from offset 0 + - id: header + name: Header + size: 64 + color: "#e07a5f" + children: + - { id: magic, name: Magic "OTA1", size: 4 } + - { id: fmt_version, name: Format version, size: 2 } + - { id: flags, name: Flags, size: 2 } + - { id: img_version, name: Image version, size: 4 } + - { id: payload_size, name: Payload size, size: 4 } + - { id: payload_hash, name: Payload SHA-256, size: 32 } + - { id: header_crc, name: Header CRC32, size: 4 } + - { id: hdr_reserved, name: Reserved, size: auto } + - { id: manifest, name: Manifest, size: 448, color: "#f2cc8f", note: "CBOR, padded" } + - { id: signature, name: Signature, size: 512, color: "#9fb3c8", note: "RSA-4096 over header + manifest" } + - { id: payload, name: Payload, size: auto, color: "#81b29a", note: "LZ4-compressed image" } + +view: + defaults: + labels: + address: none # offsets do not matter here, only order and size + size: true + scale: { mode: weighted, min_height: 30 } + columns: # zoom on the left, as the notes take the right + - { id: header_col, root: header, title: Header fields, lane: 0, offset: 40 } + - { id: package_col, root: package, title: Package, lane: 1 } + expand: + - { region: header, from: package_col, to: header_col } + +style: { palette: color } diff --git a/memmap/layout/labels.py b/memmap/layout/labels.py index c957bf9..151da21 100644 --- a/memmap/layout/labels.py +++ b/memmap/layout/labels.py @@ -51,9 +51,11 @@ def build_labels( blocks: list[Block], band_starts: set[int], mode: str, address_bits: int ) -> list[AddressLabel]: """All address labels of one column, bottom to top. In a column with bands only the band - boundaries, the column ends and overridden edges are labelled.""" + boundaries, the column ends and overridden edges are labelled. With mode `none` only the + overridden edges are.""" labels: list[AddressLabel] = [] last_address = 2**address_bits - 1 + hidden = mode == "none" def add(values: list[tuple[int, str, str]], edge: int, region: str) -> None: """Turn (value, role, placement) entries into labels on `edge`.""" @@ -65,13 +67,16 @@ def add(values: list[tuple[int, str, str]], edge: int, region: str) -> None: if not blocks: return labels - add([(blocks[0].start, "start", "center")], 0, blocks[0].node.id) + if not hidden: + add([(blocks[0].start, "start", "center")], 0, blocks[0].node.id) for index, lower in enumerate(blocks): upper = blocks[index + 1] if index + 1 < len(blocks) else None top_of_space = upper is None and lower.end == last_address if lower.top_label is not None: values = _override_values(lower, upper, lower.top_label, top_of_space) + elif hidden: + values = [] elif upper is None: values = [(lower.end, "end", "center")] elif band_starts and upper.start not in band_starts: diff --git a/memmap/schema.py b/memmap/schema.py index f007d60..db8a8f4 100644 --- a/memmap/schema.py +++ b/memmap/schema.py @@ -245,11 +245,12 @@ class Memory(Model): class Labels(Model): """Address and size labels.""" - address: Literal["start", "both"] = Field( + address: Literal["start", "both", "none"] = Field( default="start", description=( "What an internal edge prints: the boundary, or boundary and previous end. An edge " - "with unfilled space at it always prints both." + "with unfilled space at it always prints both. none prints no addresses, except on " + "edges with a top_label override." ), examples=["both"], ) diff --git a/tests/golden/example_ota_package.svg b/tests/golden/example_ota_package.svg new file mode 100644 index 0000000..00c1af6 --- /dev/null +++ b/tests/golden/example_ota_package.svg @@ -0,0 +1,48 @@ + + + +OTA update package format + + +Header fields +Package + +Magic "OTA1" +4 B + +Format version +2 B + +Flags +2 B + +Image version +4 B + +Payload size +4 B + +Payload SHA-256 +32 B + +Header CRC32 +4 B + +Reserved +12 B + +Header +64 B + +Manifest +448 B +CBOR, padded + +Signature +512 B +RSA-4096 over header + manifest + +Payload +255 KB +LZ4-compressed image + diff --git a/tests/test_cli.py b/tests/test_cli.py index cc2bb98..60a8fb0 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -293,6 +293,7 @@ def test_group_help_points_to_the_guide(): [ ["view.defaults.labels.size=true"], ["view.defaults.labels.address=both"], + ["view.defaults.labels.address=none"], ["view.columns[0]={id: a, root: /}", "view.expand=[flash]"], ["view.columns[0]={id: a, root: flash, title: Flash}"], ["view.columns[0]={id: a, root: /}", "view.expand=[{region: flash, title: Flash}]"], diff --git a/tests/test_golden.py b/tests/test_golden.py index 9f6e804..b5d68a9 100644 --- a/tests/test_golden.py +++ b/tests/test_golden.py @@ -23,6 +23,7 @@ "example_nrf52840": (ROOT / "examples" / "nrf52840_boot_chain.yaml", []), "example_riscv64": (ROOT / "examples" / "riscv64_soc.yaml", []), "example_rtos_mpu": (ROOT / "examples" / "rtos_mpu_ram.yaml", []), + "example_ota_package": (ROOT / "examples" / "ota_package_format.yaml", []), "column_titles": ( EXPANDED, ["view.columns[1].title=Peripherals", "view.columns[2].title=Code area"], diff --git a/tests/test_labels.py b/tests/test_labels.py index 6040a27..cdbde6d 100644 --- a/tests/test_labels.py +++ b/tests/test_labels.py @@ -29,6 +29,7 @@ def address_labels(result, column=None): "0x0000 4400", "0x0000 43FF", "0x0000 4FFF", ], + "none": [], } # fmt: skip @@ -90,6 +91,22 @@ def test_top_label_override(top_label, strings): assert labels == expected +def test_none_keeps_only_overridden_edges(): + sets = ["view.defaults.labels.address=none", "view.overrides=[{region: b, top_label: end}]"] + assert address_labels(run(MODES, sets)) == ["0x0000 3FFF"] + + +def test_none_leaves_no_room_for_addresses(): + layout = drawn(run(MODES, ["view.defaults.labels.address=none"])).columns[0] + assert layout.left_gutter == 0 + + +def test_none_hides_addresses_in_one_column_only(): + result = run(ROOT / "examples" / "stm32f303_fig8.yaml", ["view.columns[2].labels.address=none"]) + assert address_labels(result, "code_detail") == [] + assert address_labels(result, "periph_detail") + + def test_override_forces_a_label_on_an_edge_bands_would_skip(): sets = ["view.columns[0].bands=16K", "view.overrides=[{region: b, top_label: end}]"] assert address_labels(run(MODES, sets)) == ["0x0000 1000", "0x0000 3FFF", "0x0000 4FFF"]