memview 0.1.3

Introspect and visualize binary memory layouts

memview

Inspect and visualize binary memory layouts from multiple input formats (Intel HEX, S-Record, hexdumps, and raw BIN).
Define a layout once (TOML/YAML), then decode typed fields, verify expectations, and export reports (text/JSON/CSV).

Highlights

• Unified sparse memory model over HEX/SREC/hexdumps/BIN
• Declarative layout: segments, typed fields, expectations
• Typed decoders: u8/u16/u32/u64, bytes(size), bitfield, addr, str(size, encoding)
• Bitfields with configurable bit order: lsb (default) or msb
• Clean CLI: inspect → text/JSON/CSV
• Minimal dependencies; install-anywhere

---

Installation

Requirements

• Python 3.11+

Install

pip install memview

If you’re developing locally with a src/ layout:

pip install -e .

---

Input formats

• Intel HEX (.hex) — parsed with addresses
• S-Record (.srec, .s19, .mot) — parsed with addresses
• Hex dump (xxd / hexdump -C style) — parsed with addresses
• Raw BIN — no addresses; you must pass --base

---

CLI

Inspect a file (layout-aware)

memview inspect fw.hex --layout fw.toml

Choose output format

memview inspect fw.hex --layout fw.toml --format text
memview inspect fw.hex --layout fw.toml --format json
memview inspect fw.hex --layout fw.toml --format csv

BIN requires a base address

memview inspect fw.bin --layout fw.toml --base 0x08000000

Bitfield bit order override (lsb by default)

memview inspect fw.hex --layout fw.toml --bit-order msb

Exit codes

• 0 — success
• 2 — success with issues (e.g., missing bytes, expectation failures)
• 1 — error

---

Layout files

Layouts can be TOML (recommended) or YAML (if PyYAML is installed).

Minimal TOML example

[memory]
fill = 0xFF
# Optional default bit order for bitfields; defaults to "lsb" if omitted
# bit_order = "lsb"  # or "msb"

[[segments]]
name = "header"
base = 0x08000000
size = 64

[[segments]]
name = "app"
base = 0x08000040
size = 0x70000

[[layout]]
name   = "magic"
at     = "header+0x00"
type   = "u32"
endian = "be"

[[layout]]
name = "flags"
at   = "header+0x04"
type = "bitfield"
# field-level override (optional): bit_order = "msb"
bits = [
  { name = "secure", bit = 0 },
  { name = "debug",  bit = 1 },
  { name = "valid",  bit = 7 }
]

[[layout]]
name   = "length"
at     = "header+0x06"
type   = "u16"
endian = "le"

[[layout]]
name   = "entry_point"
at     = "header+0x08"
type   = "addr"
endian = "le"

[[layout]]
name   = "name"
at     = "header+0x0C"
type   = "str"
size   = 8
encoding = "ascii"

[[layout]]
name   = "payload"
at     = "app+0x00"
type   = "bytes"
size   = 256

Address syntax

• Absolute: 0x08000000
• Segment + offset: segmentName+0x04

Types (current)

• Scalars: u8, u16, u32, u64 (with endian = "le" | "be")
• bytes(size = N)
• bitfield with bits = [{name, bit}]
  • Bit numbering is LSB-first by default.
  • Control via memory.bit_order = "lsb"|"msb" or per-field bit_order.
• addr (4 bytes, endianness controllable)
• str(size = N, encoding = "ascii" | "utf8") (trailing NULs trimmed)

Expectations

For integer-like fields you can set expect:

[[layout]]
name   = "magic"
at     = "header+0x00"
type   = "u32"
endian = "be"
expect = 0xABCD1234

If an expectation fails (or bytes are missing), the CLI returns 2 and lists issues.

---

Examples

Intel HEX

memview inspect firmware.hex --layout fw.toml

S-Record

memview inspect firmware.srec --layout fw.toml --format json

Hex dump (xxd / hexdump -C)

memview inspect dump.txt --layout fw.toml --format csv

BIN with explicit base

memview inspect firmware.bin --layout fw.toml --base 0x08000000

---

Output samples

Text

Field              Addr       Type       Value
magic              0x08000000 u32(be)    0xABCD1234
flags              0x08000004 bitfield   {debug=0, secure=1, valid=1}
length             0x08000006 u16(le)    0x0020
entry_point        0x08000008 addr(le)   0x08000040
name               0x0800000C str        TEST
payload            0x08000040 bytes      [256 bytes] sha256=2f5b7b8e2a7f2a8c…

JSON (excerpt)

{
  "fields": [
    {"name":"magic","address":134217728,"type":"u32","value":2882343476,"meta":{"endian":"be"}},
    {"name":"payload","address":134217792,"type":"bytes","value":{"kind":"bytes","len":256,"sha256":"..."},"meta":{"size":256}}
  ],
  "issues": []
}

CSV (first rows)

name,address,type,value,meta
magic,0x08000000,u32,0xABCD1234,{"endian":"be"}
flags,0x08000004,bitfield,{debug=0, secure=1, valid=1},{}
...

---

Programmatic API (preview)

from memview.loaders import load_from_path
from memview.layout import load_layout, inspect

layout = load_layout("fw.toml")
mem, kind = load_from_path("firmware.hex", fill=0xFF)
report = inspect(layout, mem, default_bit_order="lsb")
for f in report.fields:
    print(f.name, hex(f.address), f.type, f.value)

---

Behavior and guarantees

• No base address in layout for BIN. For raw binaries, the start address must be provided on the command line via --base.
• Gaps are filled with --fill during normalization; attempts to read missing bytes for a field are reported as issues.
• Overlapping segments on ingest are rejected.
• Bitfield default is lsb. Precedence:
  1. field-level bit_order
  2. CLI --bit-order
  3. layout memory.bit_order
  4. implicit default lsb

License

MIT © Ioannis D. (devcoons)