Creating a Project

Each firmware image is associated with a project. To create a new project, simply follow the next few steps:

1. Upload Your Firmware Binary

Open your web browser and navigate to:

bash
http://<host>:<port>

You will see the Metalware home screen:

Click the New Project button. This opens a form for uploading your firmware binary. Select an appropriate name and architecture for your project.

💡

See

Supported Targets for the types of targets and image formats we support.

2. Check the Inferred Configuration

Metalware will try to automatically infer key configuration details from your firmware image:

Vector Table Address

The vector table contains the initial stack pointer and exception handlers and is normally found at the start of ROM.

Memory Map

The inferred memory map should match the memory map in your board’s reference manual.

Review the inferred details on the configuration page:

💡

It is sufficient to get the memory configuration correct enough to successfully create the project. When you submit the form, the tool will check the validity of your memory configuration by executing the firmware (we call this a “dry run” of your firmware).

💡

Without knowing everything about the hardware the firmware runs on, it is common to miss memory regions in the initial configuration while still passing the dry run. This is acceptable as any missing memory regions will be caught during fuzzing and can be easily be added to the project’s configuration later.

Memory Map Guidelines

Each memory region will fall into one of the following categories:

Memory Type	Data Source	Description
ROM	Your firmware image.	Flash and ROM-like memory in your SoC’s memory space.
RAM	Initialized to 0.	Volatile memory (e.g., DRAM, SRAM).
MMIO	Fuzzed.	Memory-mapped I/O for peripherals or secondary memory (e.g., UART, Bluetooth, HSM, Zigbee, external flash).

💡

If your firmware assumes presence of an External Flash (separate from program flash) with a particular configuration loaded, designate that region as MMIO rather than RAM so that fuzzer will handle any values read from NVRAM.

General Guidelines

Define small, distinct MMIO regions for board-specific peripherals (i.e. Nordic’s chip id).

If your firmware interfaces with secondary storage (e.g., external flash, EEPROM, NVRAM) that does not host the firmware image, map that memory region as MMIO.

For Cortex-M only:

Allocate a large, contiguous MMIO region for external peripherals (0x40_000_000 is typical). This is automatically inferred for Cortex-M images.

4. Click “Create Project”

Once you’ve verified the memory maps, click the Create Project button.

Metalware will perform a dry run of your firmware to ensure that the memory map is correctly configured.

✅ Success : If the configuration is correct, you will see a confirmation message in the Status box:

❌ Failure: If there is an error (e.g., a memory segment is too small or missing), you will see an error message similar to the example below:

This error above indicates that the RAM region may be undersized:

We ALREADY have a RAM memory region starting at 0x20000000 of size 0x1000.

Emulator fails to write to unmapped memory address: 0x20005ac4.

Bumping the size of the region to 0x10000 in this case resolves the issue.