diff --git a/src/Targets/Microchip/AVR/AVR8/TargetDescription/TargetDescriptionFile.hpp b/src/Targets/Microchip/AVR/AVR8/TargetDescription/TargetDescriptionFile.hpp index c757b0e3..105f9a1a 100644 --- a/src/Targets/Microchip/AVR/AVR8/TargetDescription/TargetDescriptionFile.hpp +++ b/src/Targets/Microchip/AVR/AVR8/TargetDescription/TargetDescriptionFile.hpp @@ -15,6 +15,8 @@ namespace Bloom::Targets::Microchip::Avr::Avr8Bit::TargetDescription * given a target signature. See directory "build/resources/TargetDescriptionFiles". * The generation of the JSON mapping, is done by a PHP script: * "build/scripts/CopyAvrPartFilesAndCreateMapping.php". This script is invoked via a custom command, at build time. + * + * For more information of TDFs, see src/Targets/TargetDescription/README.md */ class TargetDescriptionFile: public Targets::TargetDescription::TargetDescriptionFile { @@ -80,6 +82,7 @@ namespace Bloom::Targets::Microchip::Avr::Avr8Bit::TargetDescription std::optional getCpuRegisterGroup() const; std::optional getBootLoadRegisterGroup() const; std::optional getEepromRegisterGroup() const; + std::optional getStatusRegister() const; std::optional getStackPointerRegister() const; std::optional getStackPointerHighRegister() const; diff --git a/src/Targets/TargetDescription/README.md b/src/Targets/TargetDescription/README.md new file mode 100644 index 00000000..86def879 --- /dev/null +++ b/src/Targets/TargetDescription/README.md @@ -0,0 +1,59 @@ +## Target description files + +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 some of the +data extracted from TDFs: + +- Target signatures +- Parameters for debug interfaces +- Memory address space descriptions (including sections, offsets and sizes) +- Register descriptions (including offsets and sizes) +- 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 distribution directory +(`build/resources/TargetDescriptionFiles/`) at build time and included in the Debian installation package. Upon copying +the TDFs, we also generate a JSON mapping of AVR8 target signatures to TDF file paths. This mapping is also +distributed with Bloom and can be found in the `build/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 executable path. +See `Avr8::loadTargetDescriptionFile()` 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 to the format have been made 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 `Bloom::Targets::TargetDescription::TargetDescriptionFile` class being the entry +point. + +#### Extending the TargetDescriptionFile class for TDFs with formats that are specific to certain target families and/or architectures + +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 `` node of the TDF. This method is currently considered to be specific +to AVR8 TDFs. For that reason, we extend the `Bloom::Targets::TargetDescription::TargetDescriptionFile` class to better +represent TDFs for particular target families or architectures. For AVR8 targets, we use the +`Bloom::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 `Bloom::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. 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` diff --git a/src/Targets/TargetDescription/TargetDescriptionFile.hpp b/src/Targets/TargetDescription/TargetDescriptionFile.hpp index 8c1ccc64..f310648f 100644 --- a/src/Targets/TargetDescription/TargetDescriptionFile.hpp +++ b/src/Targets/TargetDescription/TargetDescriptionFile.hpp @@ -29,6 +29,8 @@ namespace Bloom::Targets::TargetDescription * or target family. For example, the Targets::Microchip::Avr::Avr8Bit::TargetDescription::TargetDescriptionFile * class inherits from this class, to represent TDFs for AVR8 targets. The derived class provides access to * additional data that is only found in AVR8 TDFs (such as AVR target signature, AVR Family, etc). + * + * For more information of TDFs, see src/Targets/TargetDescription/README.md */ class TargetDescriptionFile {