target_family.h

00001 /**
00002  * @file    target_family.h
00003  * @brief
00004  *
00005  * DAPLink Interface Firmware
00006  * Copyright (c) 2018-2019, ARM Limited, All Rights Reserved
00007  * SPDX-License-Identifier: Apache-2.0
00008  *
00009  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00010  * not use this file except in compliance with the License.
00011  * You may obtain a copy of the License at
00012  *
00013  * http://www.apache.org/licenses/LICENSE-2.0
00014  *
00015  * Unless required by applicable law or agreed to in writing, software
00016  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00017  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00018  * See the License for the specific language governing permissions and
00019  * limitations under the License.
00020  */
00021 
00022 #ifndef TARGET_FAMILY_H
00023 #define TARGET_FAMILY_H
00024 
00025 #include <stdint.h>
00026 #include <string.h>
00027 
00028 //! @brief Creates a family ID from a vendor ID and family index within that vendor.
00029 #define VENDOR_TO_FAMILY(vendor, family) ((vendor) << 8 | (family))
00030 
00031 //! @brief States into which the target can be placed.
00032 //!
00033 //! These enums are passed to target_set_state() and indicate the desired state into which
00034 //! the target should be reset.
00035 typedef enum _target_state {
00036     RESET_HOLD,              //!< Hold target in reset
00037     RESET_PROGRAM,           //!< Reset target and setup for flash programming
00038     RESET_RUN,               //!< Reset target and run normally
00039     NO_DEBUG,                //!< Disable debug on running target
00040     DEBUG,                   //!< Enable debug on running target
00041     HALT,                    //!< Halt the target without resetting it
00042     RUN,                     //!< Resume the target without resetting it
00043     POST_FLASH_RESET,        //!< Reset target after flash programming
00044     POWER_ON,                //!< Poweron the target
00045     SHUTDOWN,                //!< Poweroff the target
00046 } target_state_t;
00047 
00048 //! @brief Options for reset.
00049 typedef enum _reset_type {
00050     kHardwareReset = 1,
00051     kSoftwareReset,
00052 } reset_type_t;
00053 
00054 //! @brief Unique IDs for vendors.
00055 //!
00056 //! The vendor IDs are the same as those used for the _DeviceVendorEnum_ defined for the PDSC file
00057 //! format from CMSIS-Packs. See the [DeviceVendorEnum
00058 //! documentation](https://arm-software.github.io/CMSIS_5/Pack/html/pdsc_family_pg.html#DeviceVendorEnum)
00059 //! for the list of ID values.
00060 enum _vendor_ids {
00061     kStub_VendorID = 0,
00062     kNXP_VendorID = 11,
00063     kTI_VendorID = 16,
00064     kNordic_VendorID = 54,
00065     kToshiba_VendorID = 92,
00066     kRenesas_VendorID = 117,
00067     kWiznet_VendorID = 122,
00068     kRealtek_VendorID = 124,
00069 };
00070 
00071 //! @brief Unique IDs for device families supported by DAPLink.
00072 //!
00073 //! The values of these enums are created with the VENDOR_TO_FAMILY() macro. Vendor IDs come from
00074 //! the #_vendor_ids enumeration. The family index for each ID is simply an integer that is unique
00075 //! within the family.
00076 //!
00077 //! There are several "stub" families defined with a stub vendor. These families are meant to be
00078 //! used for devices that do not require any customized behaviour in order to be successfully
00079 //! controlled by DAPLink. The individual stub families provide some options for what reset type
00080 //! should be used, either hardware or software.
00081 //!
00082 //! To add a new family, first determine if you can simply use one of the stub families. For many
00083 //! devices, the stub families are sufficient and using them reduces complexity.
00084 //!
00085 //! If you do need a new family ID, first check if the vendor is present in #_vendor_ids. If not,
00086 //! add the vendor ID to that enum (see its documentation for the source of vendor ID values).
00087 //! Then pick a unique family index by adding 1 to the highest existing family index within that
00088 //! vendor. For a family with a new vendor, the family index should be 1.
00089 typedef enum _family_id {
00090     kStub_HWReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 1),
00091     kStub_SWVectReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 2),
00092     kStub_SWSysReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 3),
00093     kNXP_KinetisK_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 1),
00094     kNXP_KinetisL_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 2),
00095     kNXP_Mimxrt_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 3),
00096     kNXP_RapidIot_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 4),
00097     kNXP_KinetisK32W_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 5),
00098     kNordic_Nrf51_FamilyID = VENDOR_TO_FAMILY(kNordic_VendorID, 1),
00099     kNordic_Nrf52_FamilyID = VENDOR_TO_FAMILY(kNordic_VendorID, 2),
00100     kRealtek_Rtl8195am_FamilyID = VENDOR_TO_FAMILY(kRealtek_VendorID, 1),
00101     kTI_Cc3220sf_FamilyID = VENDOR_TO_FAMILY(kTI_VendorID, 1),
00102     kToshiba_Tz_FamilyID = VENDOR_TO_FAMILY(kToshiba_VendorID, 1),
00103     kWiznet_W7500_FamilyID = VENDOR_TO_FAMILY(kWiznet_VendorID, 1),
00104     kRenesas_FamilyID = VENDOR_TO_FAMILY(kRenesas_VendorID, 1),
00105 } family_id_t;
00106 
00107 //! @brief Defines all characteristics of a device family.
00108 typedef struct target_family_descriptor {
00109     uint16_t family_id ;                         /*!< Use to select or identify target family from defined target family or custom ones */
00110     reset_type_t default_reset_type ;            /*!< Target family can select predefined reset from  kHardwareReset and kSoftwareReset */
00111     uint32_t soft_reset_type ;                   /*!< Families can override software reset type to VECTRESET or SYSRESETREQ */
00112     void (*target_before_init_debug )(void);     /*!< Target dependant function before debug initialization */
00113     void (*prerun_target_config )(void);         /*!< Target specific initialization */
00114     uint8_t (*target_unlock_sequence )(void);    /*!< Unlock targets that can enter lock state */
00115     uint8_t (*security_bits_set )(uint32_t addr, uint8_t *data, uint32_t size);  /*!< Check security bits in the programmable flash region */
00116     uint8_t (*target_set_state )(target_state_t state);      /*!< Families can customize target debug states */
00117     void (*swd_set_target_reset )(uint8_t asserted);         /*!< Families can customize how to send reset to the target */
00118     uint8_t (*validate_bin_nvic )(const uint8_t *buf);       /*!< Validate a bin file to be flash by drag and drop */
00119     uint8_t (*validate_hexfile )(const uint8_t *buf);        /*!< Validate a hex file to be flash by drag and drop */
00120     uint32_t apsel ;                             /*!< APSEL for the family */
00121 } target_family_descriptor_t;
00122 
00123 //! @brief The active family used by the board.
00124 //!
00125 //! This global is initialized by init_family() just after DAPLink boots. Normally it matches
00126 //! the family specified by the #board_info_t::family_id field of #g_board_info.
00127 extern const target_family_descriptor_t *g_target_family;
00128 
00129 #ifdef __cplusplus
00130 extern "C" {
00131 #endif
00132 
00133 //! @brief Initialize g_target_family.
00134 void init_family(void);
00135 
00136 //! @brief Reset the target into a new state.
00137 //!
00138 //! Used to prepare the target for some operation, or release it for user control.
00139 uint8_t target_set_state(target_state_t state);
00140 
00141 //! @brief Controls reset of the target.
00142 void swd_set_target_reset(uint8_t asserted);
00143 
00144 //! @brief Get the APSEL for the AHB-AP to use for controlling the target.
00145 uint32_t target_get_apsel(void);
00146 
00147 #ifdef __cplusplus
00148 }
00149 #endif
00150 
00151 #endif