Skip to main content

Firmware

Atlas provides several ready-to-use packages of firmware objects called coreimages to make it easy to get started with virtual devices.

The coreimage format for MCU firmware is explained in our MCU Firmware Packages article.

The coreimage package format for Linux firmware is explained in our Linux Firmware Packages article.

In addition to stock coreimages, you can create your own custom coreimage packages to run on virtual devices, which you can upload through the web interface or using our REST or Python SDK.

General Boot Flow​

Models in Atlas are generally configured to boot either with a Linux coreimage or an MCU coreimage. A Linux format coreimage implies a boot flow that closely resembles the boot flow found on a board starting at the hand off from a second stage boot loader to the Linux kernel. Specifically this means that the board does not start at the reset vector, but at the entry to the Linux kernel. The coreimage package uploaded to the board is required to contain a firmware object that is generally an ELF format executable that is loaded into memory. The loader then the PC to the entry point mimicking the behavior of most boot loaders.

The MCU flow implies that the board starts from the reset vector with the option of appearing to start from a debugger. In practice during software development most micro-controller boards are booted from a debugger that dynamically loads the binary into FLASH and/or RAM rather than using an external flash programmer - so the user flow has been optimized for this use-case.

To use this flow, the coreimage package uploaded to the board is required to contain a file named "firmware" that will be loaded into the device prior to the simulated MCU power-on-reset (PoR) event. This file is usually an ELF, but may also be a nested zip archive, Motorola SREC, or Intel HEX file format. This binary should be built in such a way to include code for the MCU's Vector Table, as the MCU will read from it during PoR to set its stack pointer (SP) and program counter (PC).

The use-case defined above is intended to mimic the workflow of real hardware with an attached debugger that does the work of provisioning and releasing the target under test. To mimic the boot flow of a board without a simulated debugger we recommend using a flattened image of the boot storage device as the Firmware Object, the storage for boot device can then either be omitted, contain a second identical copy, or contains 0xFF filling all bytes of the storage.

General Coreimage Package Structure​

All coreimages used by Atlas shares a general structure: a firmware object, zero or more storage objects, zero or more platform specific files, and a description file. All of these are packaged together into a zip archive that is uploaded via web interface or REST API.

Firmware Objects​

Every firmware package must contain a firmware object, generally named either "firmware" or "kernel". This must be one of:

  1. an ELF format executable
  2. Linux kernel image
  3. a “hex” file in Motorola SREC or Intel "ihex” (HEX) format
  4. a zip archive containing multiple firmware objects with names and load addresses defined in a required text file “load.txt”
  5. a flat binary image (that is loaded in accordance with the platform defaults)

If the firmware object is an ELF file or Linux kernel or HEX file it is loaded into memory as if loaded by a boot loader at the addresses defined in the file format. If the firmware object is a zip file it is assumed to contain an load.txt that contains a lists of file names and memory offsets. Each file is them memcpy'd into RAM at the address specified without any additional processing. An example load.txt:

name:rom-image.wic.nopt        load:0x11000000
name:encrypted_blob.bin        load:0x31000000
name:encrypted_blob2.bin       load:0x31080000

Use of flat binary images is discouraged as few systems provide sufficient documentation to fully specify the file format. The most common configuration is a flat dump of all memory using the addressing found in the power on reset state, consult your board docs for incomplete data.

Storage Objects​

Many systems include some number of non-volatile storage devices, such as FLASH, eMMC, SD-CARD, or hard drive. The specific names and sizes are documented in the "Details" entry for the device. This will also document which files are required and which optional and what the default values are for optional files.

Platform Specific Files​

In most cases where a Linux boot flow is used a device tree blob, or DTB, is a required platform file. Additionally, a few Linux platforms also require a system.map file. Over time Atlas will be migrating away from the use of the Linux kernel image and replacing it with a bootloader binary that can be more reasonably called "firmware".

Coreimage Packages and Individual File Usage​

Atlas support upload of both coreimage packages and individual firmware objects. The most common flow for uploading a coreimage package is documented in the web interface example. In summary, coreimage packages, and only coreimage packages, can be uploaded on the create new device page. To upload one or more individual firmware objects, storage objects, or platform specific files, choose a standard coreimage and on the next screen of device creation select advanced options. This will open a page where you can access "Firmware" and "Storage" tabs and upload individual files to the specific locations defined by the model.