doryan/BloomPatched
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tidying comments in abstract target class

Browse Source
This commit is contained in:
Nav
2021-10-21 19:49:29 +01:00
parent 086d5e45b9
commit f7222efc13
1 changed files with 25 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
src/Targets/Target.hpp
View File

@@ -7,14 +7,16 @@
#include <set> #include <set>
#include <map> #include <map>
#include "src/DebugToolDrivers/DebugTool.hpp"
#include "src/ApplicationConfig.hpp" #include "src/ApplicationConfig.hpp"
#include "TargetDescriptor.hpp" #include "TargetDescriptor.hpp"
#include "TargetState.hpp" #include "TargetState.hpp"
#include "TargetRegister.hpp" #include "TargetRegister.hpp"
#include "TargetMemory.hpp" #include "TargetMemory.hpp"
#include "TargetBreakpoint.hpp" #include "TargetBreakpoint.hpp"
#include "src/DebugToolDrivers/DebugTool.hpp"
namespace Bloom::Targets namespace Bloom::Targets
{ {
/** /**
@@ -25,7 +27,7 @@ namespace Bloom::Targets
* A single implementation of this interface can represent a single target, or an entire family of targets. * A single implementation of this interface can represent a single target, or an entire family of targets.
* For an example, see the Avr8 implementation. The Avr8 target class was written in a way that would allow it to * For an example, see the Avr8 implementation. The Avr8 target class was written in a way that would allow it to
* work, to *at least* the point of target promotion, for all AVR8 targets. For more on target promotion, see the * work, to *at least* the point of target promotion, for all AVR8 targets. For more on target promotion, see the
* Target::promote() method. * Target::promote() function.
*/ */
class Target class Target
{ {
@@ -41,24 +43,24 @@ namespace Bloom::Targets
/** /**
* There are three stages of configuration for targets. * There are three stages of configuration for targets.
* *
* preActivationConfigure() - The first stage is just before target activation (Target::activate() being called). * preActivationConfigure() - The first stage is just before target activation (Target::activate() being
* At this point, we will not have interacted with the target in any way. This method should cover any * called). At this point, we will not have interacted with the target in any way. This function should cover
* configuration that can be done without the target being activated. It should also cover any configuration * any configuration that can be done without the target being activated. It should also cover any configuration
* that is required in order for us to successfully activate the target. For an example, we use this method in * that is required in order for us to successfully activate the target. For an example, we use this function
* the Avr8 target class to configure the debug tool with the correct physical interface and config variant * in the Avr8 target class to configure the debug tool with the correct physical interface and config variant
* parameters (taken from the user's settings, via the TargetConfig instance). Without these being configured, * parameters (taken from the user's settings, via the TargetConfig object). Without these being configured,
* the debug tool would not be able to interface with the AVR8 target, and thus target activation would fail. * the debug tool would not be able to interface with the AVR8 target, and thus target activation would fail.
* *
* postActivationConfigure() - The second stage is right after target activation (successful invocation of * postActivationConfigure() - The second stage is right after target activation (successful invocation of
* Target::activate()). At this point, we will have established a connection with the target and so interaction * Target::activate()). At this point, we will have established a connection with the target and so interaction
* with the target is permitted here. We use this method in the Avr8 target class to extract the target signature * with the target is permitted here. We use this function in the Avr8 target class to extract the target
* from the target's memory, which we then use to find & load the correct target description file. * signature from the target's memory, which we then use to find & load the correct target description file.
* *
* postPromotionConfigure() - The final stage of configuration occurs just after the target instance has been * postPromotionConfigure() - The final stage of configuration occurs just after the target instance has been
* promoted to a different class. See the Target::promote() method for more in this. * promoted to a different class. See the Target::promote() function for more on this.
* *
* If any of the three configuration methods throw an exception, the exception will be treated as a fatal error. * If any of the three configuration functions throw an exception, the exception will be treated as a fatal
* In response, the TargetController will shutdown, along with the rest of Bloom. * error. In response, the TargetController will shutdown, along with the rest of Bloom.
* *
* @param targetConfig * @param targetConfig
*/ */
@@ -69,10 +71,10 @@ namespace Bloom::Targets
virtual void postPromotionConfigure() = 0; virtual void postPromotionConfigure() = 0;
/** /**
* This method should attempt to establish a connection with the target, and put it in a state where debugging * This function should attempt to establish a connection with the target, and put it in a state where
* can be performed. This method will be called after Target::preActivationConfigure(). * debugging can be performed. This function will be called after Target::preActivationConfigure().
* *
* If an exception is thrown from this method, the TargetController will treat it as a fatal error, and thus * If an exception is thrown from this function, the TargetController will treat it as a fatal error, and thus
* will shutdown, along with the rest of Bloom. * will shutdown, along with the rest of Bloom.
*/ */
virtual void activate() = 0; virtual void activate() = 0;
@@ -82,7 +84,7 @@ namespace Bloom::Targets
* *
* This is typically called on TargetController shutdown, but keep in mind that it's called regardless of * This is typically called on TargetController shutdown, but keep in mind that it's called regardless of
* whether or not Target::activate() was previously called. In other words, the TargetController will always * whether or not Target::activate() was previously called. In other words, the TargetController will always
* call this method on shutdown, even if the TargetController did not call Target::activate() before it began * call this function on shutdown, even if the TargetController did not call Target::activate() before it began
* shutting down. The reason behind this is to give the target a chance to deactivate in cases where the call * shutting down. The reason behind this is to give the target a chance to deactivate in cases where the call
* to Target::activate() failed and thus triggered a shutdown (via an exception being thrown from * to Target::activate() failed and thus triggered a shutdown (via an exception being thrown from
* Target::activate()). * Target::activate()).
@@ -90,7 +92,7 @@ namespace Bloom::Targets
virtual void deactivate() = 0; virtual void deactivate() = 0;
/** /**
* Should check if the given debugTool is compatible with the target. Returning false in this method will * Should check if the given debugTool is compatible with the target. Returning false in this function will
* prevent Bloom from attempting to use the selected debug tool with the selected target. An InvalidConfig * prevent Bloom from attempting to use the selected debug tool with the selected target. An InvalidConfig
* exception will be raised and Bloom will shutdown. * exception will be raised and Bloom will shutdown.
* *
@@ -105,7 +107,7 @@ namespace Bloom::Targets
virtual bool isDebugToolSupported(DebugTool* debugTool) = 0; virtual bool isDebugToolSupported(DebugTool* debugTool) = 0;
/** /**
* Assuming the Target::isDebugToolSupported() check passed, this method will be called shortly after, by the * Assuming the Target::isDebugToolSupported() check passed, this function will be called shortly after, by the
* TargetController. * TargetController.
* *
* @param debugTool * @param debugTool
@@ -139,13 +141,13 @@ namespace Bloom::Targets
* own, if required, where they could promote to a class that's not only specific to an AVR8 family, but to a * own, if required, where they could promote to a class that's not only specific to an AVR8 family, but to a
* particular target model (for example, a target class that was written specifically for the ATmega328P target). * particular target model (for example, a target class that was written specifically for the ATmega328P target).
* *
* This method should attempt to promote the current target class to one that is more specific to the connected * This function should attempt to promote the current target class to one that is more specific to the
* target, with the information it currently holds on the target. * connected target, with the information it currently holds on the target.
* *
* If this method fails to promote the target, it should return an std::unique_ptr(nullptr). * If this function fails to promote the target, it should return an std::unique_ptr(nullptr).
* *
* After activating the target, assuming the first call to Target::supportsPromotion() returns true, the * After activating the target, assuming the first call to Target::supportsPromotion() returns true, the
* TargetController will enter a loop, where it will repeatedly call this method and update the target * TargetController will enter a loop, where it will repeatedly call this function and update the target
* instance, until at least one of the following conditions are met: * instance, until at least one of the following conditions are met:
* - The call to Target::supportsPromotion() on the current target instance returns false * - The call to Target::supportsPromotion() on the current target instance returns false
* - The call to Target::promote() on the current target instance returns an std::unique_ptr(nullptr) * - The call to Target::promote() on the current target instance returns an std::unique_ptr(nullptr)