BINLens is now documented, tested, manually validated on STM32-style HEX/BIN inputs, and prepared for the v1.0 GitHub release.

Output Polish

Updated the CLI report for stable terminal output:

• clearer input summary
• consistent region, gap, overlap, entropy, and vector-table sections
• -v now clearly exposes source chunks and entropy windows
• --heatmap renders a compact entropy view
• unknown input formats now include the input path in the error message

Generated the requested screenshot:

• devlogs/ss.png

The PNG is rendered from real binlens output against testfiles/STM32-DEMO.hex.

Hardening

Cleaned up invalid-input behavior:

• case-insensitive --format
• case-insensitive .hex, .ihex, and .bin extension inference
• explicit rejection for overly long input paths
• clearer help text for --base and -v
• raw BIN size guard before allocation

Validated common error cases:

• invalid entropy chunk size
• invalid format
• bad Intel HEX checksum
• missing input file

Documentation

Updated:

• README.md
• PRD.md
• ARCHITECTURE.md
• CONTRIBUTING.md

Added:

• TESTING.md

The docs now describe the actual v1 behavior instead of the early scaffold state.

Test Corpus

The fixture set now covers:

• minimal Intel HEX
• extended linear address
• extended segment address
• bad checksum
• record after EOF
• STM32-like vector table image

The test workflow is documented in TESTING.md.

Manual Validation

Validated real STM32 HEX:

testfiles/STM32-DEMO.hex

Converted it to raw BIN with objcopy and validated:

build/manual/STM32-DEMO.bin

Both paths detected:

• address span 0x08000000 - 0x08001E2F
• high-confidence vector table at 0x08000000
• reset handler target inside loaded firmware
• entropy heatmap output

Build Checks

Native Windows GCC:

test_bin_loader: ok
test_entropy: ok
test_hex_parser: ok
test_memmap: ok
test_smoke: ok
test_vector_table: ok

Docker Linux:

make clean
make test
make

Docker/Zig macOS check:

• Mach-O x86_64 binary produced
• Mach-O arm64 binary produced

Docker initially had a Desktop engine error and was recovered by restarting Docker Desktop.

Release State

Released on GitHub with compiled binaries for Windows and Linux.
https://github.com/DevaanshPathak/BINLens/releases/tag/v1.0

BIN Loading and Memory Map

Implemented raw .bin loading:

• opens files in binary mode
• maps bytes at --base
• stores the image as one source chunk
• handles empty files
• rejects address overflow
• reports file errors with diagnostics

Extended BlFirmwareImage with owned analysis data:

• reconstructed regions
• gaps
• overlaps

Implemented bl_memmap_reconstruct:

• sorts source chunks by address
• merges adjacent chunks
• merges overlapping chunks while preserving first-seen bytes
• records sparse gaps
• records overlaps as identical or conflicting

CLI output now includes:

• input metadata
• source chunks with -v
• memory regions
• gaps
• overlaps

Added tests:

• test_bin_loader.c
• test_memmap.c

Covered base-address mapping, overflow rejection, adjacent merge, sparse gaps, identical overlaps, and conflicting overlaps.

Entropy and Cortex-M Analysis

Implemented Shannon entropy without requiring -lm, keeping the Makefile dependency-free.

Entropy is now reported:

• per reconstructed region
• per fixed-size chunk in verbose mode
• as an ASCII heatmap with --heatmap

--entropy-chunk controls the chunk size.

Implemented Cortex-M vector table detection:

• checks common aliases like 0x00000000 and 0x08000000
• reads initial SP and reset handler as little-endian words
• validates SRAM stack range
• validates stack alignment
• validates Thumb reset bit
• checks whether reset target lands in loaded firmware
• reports confidence score: none, low, medium, high

Added STM32-like fixture:

• tests/fixtures/stm32_vector.ihex

Added tests:

• test_entropy.c
• test_vector_table.c

Covered known entropy values, heatmap symbols, high-confidence vector detection, missing-vector behavior, and an end-to-end STM32-like HEX sample.

Verification

Native GCC build passed with:

-std=c11 -Wall -Wextra -Wpedantic

Tests passed:

test_bin_loader: ok
test_entropy: ok
test_hex_parser: ok
test_memmap: ok
test_smoke: ok
test_vector_table: ok

Docker POSIX path passed:

make clean
make test
make

Current State

The MVP analysis path is now feature-complete for:

• Intel HEX parsing
• raw BIN loading
• memory layout reconstruction
• gap and overlap reporting
• per-region entropy
• chunk entropy
• ASCII heatmap
• Cortex-M vector table detection

Remaining stretch work includes JSON output, richer heuristics, section guessing, and comparison mode.

Started building BINLens

Initial Modules

Added headers and implementation files for the planned architecture:

• cli
• diagnostic
• firmware_image
• hex_parser
• bin_loader
• memmap
• entropy
• vector_table
• format
• main

Most analysis modules are still scaffolded. The implemented path at this point is Intel HEX parsing and basic CLI summary output.

Firmware Image Model

Implemented an owned source-chunk model:

• BlFirmwareImage now owns parsed chunks.
• BlSourceChunk stores:
  • start address,
  • end address,
  • byte length,
  • copied byte buffer,
  • origin path,
  • origin line.
• The firmware image tracks:
  • chunk count,
  • total loaded bytes,
  • lowest loaded address,
  • highest loaded address.

This gives later work enough structure for memory reconstruction, overlap detection, entropy analysis, and vector table detection.

Intel HEX Parser

Implemented parsing for the Week 1 record scope:

• 00 data record.
• 01 end-of-file record.
• 02 extended segment address.
• 04 extended linear address.
• 05 start linear address.

Parser behavior now includes:

• required leading colon validation,
• header and data hex validation,
• record length validation,
• checksum validation,
• EOF validation,
• data-after-EOF rejection,
• unsupported record type diagnostics,
• line-numbered error messages,
• start linear address metadata capture.

Checksum failures now report both the record checksum and computed checksum.

CLI Progress

The CLI now:

• parses --help,
• parses --version,
• accepts --format, --base, --entropy-chunk, --heatmap, --no-color, and --verbose,
• infers .hex and .ihex as Intel HEX,
• runs the Intel HEX parser,
• prints a basic input summary.

Example successful output from a real STM32 demo HEX file:

BINLens 0.1.0-dev

Input
  File:          ..\testfiles\STM32-DEMO.hex
  Format:        Intel HEX
  Records:       486
  Data records:  483
  Bytes loaded:  7728
  Chunks:        483
  Address span:  0x08000000 - 0x08001E2F
  Start linear:  0x08000131

--heatmap is currently accepted but does not produce heatmap output yet.