2626#include <string.h>
2727#include "target_reset.h"
2828
29- #define VENDOR_TO_FAMILY (x , y ) (x<<8 | y)
29+ //! @brief Creates a family ID from a vendor ID and family index within that vendor.
30+ #define VENDOR_TO_FAMILY (vendor , family ) ((vendor) << 8 | (family))
3031
32+ //! @brief Options for reset.
3133typedef enum _reset_type {
3234 kHardwareReset = 1 ,
3335 kSoftwareReset ,
3436} reset_type_t ;
3537
38+ //! @brief Unique IDs for vendors.
39+ //!
40+ //! The vendor IDs are the same as those used for the _DeviceVendorEnum_ defined for the PDSC file
41+ //! format from CMSIS-Packs. See the [DeviceVendorEnum
42+ //! documentation](https://arm-software.github.io/CMSIS_5/Pack/html/pdsc_family_pg.html#DeviceVendorEnum)
43+ //! for the list of ID values.
3644enum _vendor_ids {
3745 kStub_VendorID = 0 ,
3846 kNXP_VendorID = 11 ,
@@ -44,6 +52,24 @@ enum _vendor_ids {
4452 kRealtek_VendorID = 124 ,
4553};
4654
55+ //! @brief Unique IDs for device families supported by DAPLink.
56+ //!
57+ //! The values of these enums are created with the VENDOR_TO_FAMILY() macro. Vendor IDs come from
58+ //! the #_vendor_ids enumeration. The family index for each ID is simply an integer that is unique
59+ //! within the family.
60+ //!
61+ //! There are several "stub" families defined with a stub vendor. These families are meant to be
62+ //! used for devices that do not require any customized behaviour in order to be successfully
63+ //! controlled by DAPLink. The individual stub families provide some options for what reset type
64+ //! should be used, either hardware or software.
65+ //!
66+ //! To add a new family, first determine if you can simply use one of the stub families. For many
67+ //! devices, the stub families are sufficient and using them reduces complexity.
68+ //!
69+ //! If you do need a new family ID, first check if the vendor is present in #_vendor_ids. If not,
70+ //! add the vendor ID to that enum (see its documentation for the source of vendor ID values).
71+ //! Then pick a unique family index by adding 1 to the highest existing family index within that
72+ //! vendor. For a family with a new vendor, the family index should be 1.
4773typedef enum _family_id {
4874 kStub_HWReset_FamilyID = VENDOR_TO_FAMILY (kStub_VendorID , 1 ),
4975 kStub_SWVectReset_FamilyID = VENDOR_TO_FAMILY (kStub_VendorID , 2 ),
@@ -62,6 +88,7 @@ typedef enum _family_id {
6288 kRenesas_FamilyID = VENDOR_TO_FAMILY (kRenesas_VendorID , 1 ),
6389} family_id_t ;
6490
91+ //! @brief Defines all characteristics of a device family.
6592typedef struct target_family_descriptor {
6693 uint16_t family_id ; /*!< Use to select or identify target family from defined target family or custom ones */
6794 reset_type_t default_reset_type ; /*!< Target family can select predefined reset from kHardwareReset and kSoftwareReset */
@@ -70,22 +97,35 @@ typedef struct target_family_descriptor {
7097 void (* prerun_target_config )(void ); /*!< Target specific initialization */
7198 uint8_t (* target_unlock_sequence )(void ); /*!< Unlock targets that can enter lock state */
7299 uint8_t (* security_bits_set )(uint32_t addr , uint8_t * data , uint32_t size ); /*!< Check security bits in the programmable flash region */
73- uint8_t (* target_set_state )(TARGET_RESET_STATE state ); /*!< Families can customize target debug states in target_reset.h */
74- void (* swd_set_target_reset )(uint8_t asserted ); /*!< Families can customize how to send reset to the target */
75- uint8_t (* validate_bin_nvic )(const uint8_t * buf ); /*!< Validate a bin file to be flash by drag and drop */
76- uint8_t (* validate_hexfile )(const uint8_t * buf ); /*!< Validate a hex file to be flash by drag and drop */
100+ uint8_t (* target_set_state )(TARGET_RESET_STATE state ); /*!< Families can customize target debug states */
101+ void (* swd_set_target_reset )(uint8_t asserted ); /*!< Families can customize how to send reset to the target */
102+ uint8_t (* validate_bin_nvic )(const uint8_t * buf ); /*!< Validate a bin file to be flash by drag and drop */
103+ uint8_t (* validate_hexfile )(const uint8_t * buf ); /*!< Validate a hex file to be flash by drag and drop */
77104 uint32_t apsel ; /*!< APSEL for the family */
78105} target_family_descriptor_t ;
79106
107+ //! @brief The active family used by the board.
108+ //!
109+ //! This global is initialized by init_family() just after DAPLink boots. Normally it matches
110+ //! the family specified by the #board_info_t::family_id field of #g_board_info.
80111extern const target_family_descriptor_t * g_target_family ;
81112
82113#ifdef __cplusplus
83114extern "C" {
84115#endif
85116
117+ //! @brief Initialize g_target_family.
86118void init_family (void );
119+
120+ //! @brief Reset the target into a new state.
121+ //!
122+ //! Used to prepare the target for some operation, or release it for user control.
87123uint8_t target_set_state (TARGET_RESET_STATE state );
124+
125+ //! @brief Controls reset of the target.
88126void swd_set_target_reset (uint8_t asserted );
127+
128+ //! @brief Get the APSEL for the AHB-AP to use for controlling the target.
89129uint32_t target_get_apsel (void );
90130
91131#ifdef __cplusplus
0 commit comments