Project 11: BMP Header Decoder

Parse BMP headers and report core metadata.

Quick Reference

Attribute Value
Difficulty Level 3: Advanced
Time Estimate 12-20 hours
Main Programming Language C (Alternatives: Rust, Go, Python)
Alternative Programming Languages Rust, Go, Python
Coolness Level Level 3
Business Potential Level 1
Prerequisites Endianness, Fixed offsets
Key Topics file headers, field parsing

1. Learning Objectives

By completing this project, you will:

  1. Translate between representations with explicit rules.
  2. Validate and normalize input at the byte level.
  3. Produce outputs that are deterministic and testable.

2. All Theory Needed (Per-Concept Breakdown)

Endianness

Fundamentals Endianness is the order in which bytes of a multi-byte value are stored or transmitted. Big-endian stores the most significant byte first; little-endian stores the least significant byte first. This matters whenever you parse or serialize binary data. A value like 0x12345678 can be stored as 12 34 56 78 or 78 56 34 12 depending on the specified order. The value is the same; the byte sequence is not.

Deep Dive into the concept Endianness is a representation choice, not a property of the value itself. It is specified by file formats and protocols so that data is interoperable across machines. The Internet uses network byte order (big-endian) as the standard for protocol fields. Many host systems are little-endian, which means you must translate when reading or writing network data.

A useful mental model is to treat a multi-byte integer as a list of bytes. The order of that list is what endianness controls. If you read bytes in the wrong order, you will parse the wrong number even though the raw bytes are correct. This is one of the most common causes of corrupted metadata in binary file parsers.

The safest approach is explicit conversion. When you read a 16-bit or 32-bit field, assemble the value by shifting and ORing bytes in the correct order. When you write, do the inverse. This is more verbose than using a struct cast, but it is correct and portable. You should only use direct struct casts when you can guarantee the file or protocol order matches your host order and when you have controlled padding and alignment.

Endianness also affects how you interpret hexdumps. The dump shows bytes in file order; you must decide whether to treat groups of bytes as little-endian or big-endian values. Good tools show both the raw bytes and the interpreted values to make this explicit.

Mixed-endian formats exist in legacy systems, where 16-bit words are little-endian but 32-bit values are stored as swapped words. These cases are rare, but they underscore the importance of reading specifications and not assuming a default order.

How this fit on projects This concept is a primary pillar for this project and appears again in other projects in this folder.

Definitions & key terms

  • Endianness definition, scope, and usage in this project context.
  • Key vocabulary used throughout the implementation.

Mental model diagram

[Input] -> [Rule/Conversion] -> [Value] -> [Representation]

How it works (step-by-step, with invariants and failure modes)

  1. Identify the input representation and its constraints.
  2. Apply the conversion or interpretation rules.
  3. Validate bounds and emit a canonical output.
  4. Invariant: the underlying value is preserved across representations.
  5. Failure modes: invalid digits, width overflow, or order mismatch.

Minimal concrete example

INPUT: small example value
PROCESS: apply the core rule in this concept
OUTPUT: normalized representation

Common misconceptions

  • Confusing representation with value.
  • Skipping validation because “inputs look right”.

Check-your-understanding questions

  1. Explain the concept in your own words.
  2. Predict the output of a simple conversion scenario.
  3. Why does this concept matter for correct parsing?

Check-your-understanding answers

  1. The concept is the rule set that maps representation to meaning.
  2. The output follows the defined rules and preserves value.
  3. Without it, you will misinterpret bytes or bit fields.

Real-world applications

  • Binary file parsing and validation
  • Protocol field extraction
  • Debugging with hexdumps

Where you’ll apply it

  • In this project, during the core parsing and output steps.
  • Also used in: P01-universal-base-converter, P03-bitwise-logic-calculator, P09-hexdump-clone.

References

  • “Computer Systems: A Programmer’s Perspective” - Ch. 2
  • “Code” by Charles Petzold - Ch. 7-8

Key insights This concept is a repeatable rule that transforms raw bits into reliable meaning.

Summary You can only trust your output when you apply this concept deliberately and consistently.

Homework/Exercises to practice the concept

  1. Do a manual conversion or extraction by hand.
  2. Build a tiny test case and predict the output.

Solutions to the homework/exercises

  1. The manual process should match your tool output.
  2. If the output differs, revisit your assumptions about representation.

3. Project Specification

3.1 What You Will Build

Build a focused tool that takes structured input, applies the project-specific transformations, and emits a precise, verifiable output. Include input validation, clear error messages, and deterministic formatting. Exclude any optional UI features until the core logic is correct.

3.2 Functional Requirements

  1. Validated Input: Reject malformed or out-of-range values.
  2. Deterministic Output: Same input always yields the same output.
  3. Human-Readable Display: Show results in both hex and binary where relevant.

3.3 Non-Functional Requirements

  • Performance: Must handle small files or values instantly.
  • Reliability: Must not crash on invalid inputs.
  • Usability: Outputs must be unambiguous and aligned.

3.4 Example Usage / Output

$ run-tool --example
[expected output goes here]

3.5 Data Formats / Schemas / Protocols

  • Input: simple CLI arguments or a small config file.
  • Output: fixed-width hex, optional binary, and labeled fields.

3.6 Edge Cases

  • Empty input
  • Invalid digits
  • Maximum-width values
  • Unexpected file length

3.7 Real World Outcome

The learner should be able to run the tool and compare output against a known reference with no ambiguity.

3.7.1 How to Run (Copy/Paste)

  • Build commands: make or equivalent
  • Run commands: ./tool --args
  • Working directory: project root

3.7.2 Golden Path Demo (Deterministic)

A known input produces a known output that matches a prewritten test vector.

3.7.3 If CLI: exact terminal transcript

$ ./tool --demo
[result line 1]
[result line 2]

4. Solution Architecture

4.1 High-Level Design

[Input] -> [Parser] -> [Core Logic] -> [Formatter] -> [Output]

4.2 Key Components

Component Responsibility Key Decisions
Parser Validate and normalize input Strict digit validation
Core Logic Apply conversion or extraction rules Keep math explicit
Formatter Render hex/binary/text views Fixed-width alignment

4.4 Data Structures (No Full Code)

  • Fixed-width integer values
  • Byte buffers for file I/O
  • Simple structs for labeled fields

4.4 Algorithm Overview

Key Algorithm: Core Transformation

  1. Parse input into a canonical internal value.
  2. Apply project-specific conversion or extraction rules.
  3. Format the result for display.

Complexity Analysis:

  • Time: O(n) in input size
  • Space: O(1) to O(n) depending on buffering

5. Implementation Guide

5.1 Development Environment Setup

# Use a standard compiler and a minimal build script

5.2 Project Structure

project-root/
├── src/
│   ├── main.ext
│   ├── parser.ext
│   └── formatter.ext
├── tests/
│   └── test_vectors.txt
└── README.md

5.3 The Core Question You’re Answering

“How do I transform a raw representation into a reliable value and show it clearly?”

5.4 Concepts You Must Understand First

  • See the Theory section above and confirm you can explain each concept without notes.

5.5 Questions to Guide Your Design

  1. How will you validate inputs?
  2. How will you normalize outputs for comparison?
  3. How will you handle errors without hiding failures?

5.6 Thinking Exercise

Before coding, draw the data flow from input to output and label every transformation step.

5.7 The Interview Questions They’ll Ask

  1. “How do you validate binary or hex input?”
  2. “How do you detect overflow or width mismatch?”
  3. “Why is deterministic output important?”
  4. “How would you test your tool with known vectors?”

5.8 Hints in Layers

Hint 1: Start by parsing and validating a single fixed-size input.

Hint 2: Implement the core transformation in isolation and test it.

Hint 3: Add formatting after correctness is proven.

Hint 4: Compare outputs against a trusted reference tool.

5.9 Books That Will Help

Topic Book Chapter
Data representation “Computer Systems: A Programmer’s Perspective” Ch. 2
Number systems “Code” by Charles Petzold Ch. 7-8

5.10 Implementation Phases

Phase 1: Foundation (2-4 hours)

Goals:

  • Input parsing
  • Basic validation

Tasks:

  1. Implement digit validation.
  2. Parse into internal value.

Checkpoint: Parse test vectors correctly.

Phase 2: Core Functionality (4-8 hours)

Goals:

  • Core transformation logic
  • Primary output format

Tasks:

  1. Implement core math rules.
  2. Render hex and binary outputs.

Checkpoint: Output matches known results.

Phase 3: Polish & Edge Cases (2-4 hours)

Goals:

  • Error handling
  • Edge cases

Tasks:

  1. Add invalid input tests.
  2. Add max-width tests.

Checkpoint: No crashes on invalid input.

5.11 Key Implementation Decisions

Decision Options Recommendation Rationale
Input format hex/dec/bin support all flexibility
Output width fixed/variable fixed compare easily

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit Tests Validate conversions known vectors
Integration Tests CLI parsing sample files
Edge Case Tests boundaries max/min values

6.2 Critical Test Cases

  1. Zero input: output should be zero in all bases.
  2. Max width: output should not overflow.
  3. Invalid digit: error message, no crash.

6.3 Test Data

inputs: 0, 1, 255, 256
expected: 0x0, 0x1, 0xFF, 0x100

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Wrong base incorrect output re-check digit map
Overflow wrapped values add bounds checks
Misalignment messy output pad columns

7.2 Debugging Strategies

  • Compare against a trusted tool for random inputs.
  • Print intermediate values in binary.

7.3 Performance Traps

  • Avoid reading entire files when streaming is enough.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add binary output padding.
  • Add uppercase/lowercase hex toggles.

8.2 Intermediate Extensions

  • Add batch conversion from a file.
  • Add JSON output mode.

8.3 Advanced Extensions

  • Add big-integer support.
  • Add a reversible binary patch feature.

9. Real-World Connections

9.1 Industry Applications

  • Binary file parsing and validation tools
  • Protocol debugging utilities
  • xxd-like hex tools
  • file-type identification utilities

9.3 Interview Relevance

  • Bit manipulation and data representation questions

10. Resources

10.1 Essential Reading

  • “Computer Systems: A Programmer’s Perspective” - Ch. 2
  • “Code” by Charles Petzold - Ch. 7-8

10.2 Video Resources

  • University lecture on data representation (search by course name)