BloomPatched

A target description file (TDF) is an XML file that describes a particular target. All targets that are supported by Bloom will have an associated TDF in Bloom's codebase. They can be found in src/Targets/TargetDescriptionFiles.

The data held by TDFs is fundamental to Bloom's operation. The following is an incomplete list of the data extracted from TDFs:

Memory address space descriptions (including sections, offsets and sizes)
Register descriptions (including offsets and sizes)
Parameters for debug interfaces
Target signatures
Package variant descriptions
Package pinouts

Given that Bloom currently only supports AVR8 targets, we only possess TDFs for AVR8 targets.

TDFs are distributed with Bloom. They are copied to the build directory (${CMAKE_BINARY_DIR}/resources/TargetDescriptionFiles/) at build time and included in the distributed packages (DEB, RPM, etc). Upon copying the TDFs, we also generate a JSON mapping of AVR8 target IDs to TDF file paths. This mapping is also distributed with Bloom and can be found in the ${CMAKE_BINARY_DIR}/resources/TargetDescriptionFiles/AVR directory, with the name Mapping.json. The mapping is used by Bloom, at runtime, to resolve the appropriate TDF from an AVR8 target signature. The TDF file paths in the mapping are relative to Bloom's resource directory. See the Avr8::Avr8(...) constructor for more. See build/scripts/Avr8TargetDescriptionFiles.php for the script that performs the copying and generation of the JSON mapping.

TDF format

AVR8 TDFs were initially taken from the Microchip Packs Repository (https://packs.download.microchip.com/). Some changes were made to the format, to better suit Bloom's requirements.

TODO: Explain the TDF format. For now, developers can gain an understanding of the format by viewing a TDF.

TDF parsing

The src/Targets/TargetDescription/ directory contains the necessary code and data structures to parse and represent generic TDFs, with the Targets::TargetDescription::TargetDescriptionFile class being the entry point.

Extending the TargetDescriptionFile class for TDFs with formats that are specific to certain target families and/orarchitectures

AVR8 TDFs describe certain constructs in a way that may not be employed by other target families. For example, AVR8 PORT registers are described in a <module> node of the TDF. This method is currently considered to be specific to AVR8 TDFs. For that reason, we extend the Targets::TargetDescription::TargetDescriptionFile class to better represent TDFs for particular target families or architectures. For AVR8 targets, we use the Targets::Microchip::Avr::Avr8Bit::TargetDescription::TargetDescriptionFile class to represent AVR8 TDFs.

It would be good to keep in mind that as and when support for other target families and architectures is implemented, we may use the constructs that were initially specific to AVR8 TDFs, in other TDFs. In this case, those constructs will likely be moved into the generic Targets::TargetDescription::TargetDescriptionFile class.

TDF validation

In order to ensure that every TDF in Bloom's codebase is in the correct format, and meets the minimum requirements to be of use to Bloom, we perform validation on each TDF at build time, just before creating the mapping file. If even one TDF fails validation, the build is aborted. This validation takes place in the build/scripts/Avr8TargetDescriptionFiles.php script.

There is also a separate script for AVR8 TDF validation, for developers to invoke manually, outside of builds, when needed: build/scripts/ValidateAvr8TargetDescriptionFiles.php. This script will only perform TDF validation.