target_board.h

00001 /**
00002  * @file    target_board.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_BOARD_H
00023 #define TARGET_BOARD_H
00024 
00025 #include <stdint.h>
00026 #include "target_config.h"
00027 #include "target_family.h"
00028 #include "virtual_fs.h"
00029 
00030 //! @brief Current board info version.
00031 //!
00032 //! - Version 1: Initial version.
00033 enum _board_info_version {
00034     kBoardInfoVersion = 1, //!< The current board info version.
00035 };
00036 
00037 //! @brief Flags for board_info
00038 enum _board_info_flags {
00039     kEnablePageErase  = (1 << 0),            /*!< Enable page programming and sector erase for drag and drop */
00040     kEnableUnderResetConnect  = (1 << 1),    /*!< Enable under reset connection when enabling debug mode */
00041 };
00042 
00043 /*!
00044  * @brief Board customization info.
00045  *
00046  * Each board must have a unique 4-character Board ID. For Mbed OS targets, the Board ID is the same
00047  * as the Mbed Platform ID. These IDs are nominally allocated by Arm in order to guarantee there are
00048  * no conflicts between boards. Please see the DAPLink documentation for more.
00049  *
00050  * The family_id member tells DAPLink which device family the on-board target belongs to. This then
00051  * determines certain behaviours, such as how to reset the target. Family IDs are defined in the
00052  * #family_id_t enumeration.
00053  *
00054  * The board initialization function pointers allow the board to override the routines defined
00055  * by the device family.
00056  */
00057 typedef struct __attribute__((__packed__)) board_info {
00058     uint16_t info_version;              /*!< Version number of the board info */ 
00059     uint16_t family_id;                 /*!< Use to select or identify target family from defined target family or custom ones */
00060     char board_id[5];                   /*!< 4-char board ID plus null terminator */
00061     uint8_t _padding[3];
00062     uint32_t flags;                     /*!< Flags from #_board_info_flags */
00063     target_cfg_t *target_cfg;           /*!< Specific chip configuration for the target and enables MSD when non-NULL */
00064 
00065     //! @name MSD customization
00066     //@{
00067     vfs_filename_t daplink_url_name;    /*!< Customize the URL file name */
00068     vfs_filename_t daplink_drive_name;  /*!< Customize the MSD DAPLink drive name */
00069     char daplink_target_url[64];        /*!< Customize the target url in DETAILS.TXT */
00070     //@}
00071 
00072     //! @name Board initialization customization
00073     //@{
00074     void (*prerun_board_config)(void);                      /*!< Specific board debug/ID related initialization */
00075     void (*swd_set_target_reset)(uint8_t asserted);         /*!< Boards can customize how to send reset to the target with precedence over target family */
00076     uint8_t (*target_set_state)(target_state_t state);  /*!< Boards can customize target debug states with precedence over target family */
00077     uint32_t soft_reset_type;                               /*!< Boards can override software reset type to VECTRESET or SYSRESETREQ */
00078     //@}
00079 } board_info_t;
00080 
00081 //! @brief Information describing the board on which DAPLink is running.
00082 extern const board_info_t g_board_info;
00083 
00084 #ifdef __cplusplus
00085 extern "C" {
00086 #endif
00087 
00088 //! @brief Returns the 4-char ID of the board used by the running firmware.
00089 //!
00090 //! For firmware with no board, the board ID is "0000".
00091 const char * get_board_id(void);
00092 
00093 //! @brief Returns the family ID for the target associated with the board.
00094 //!
00095 //! The family ID will be 0 if there is no board.
00096 uint16_t get_family_id(void);
00097 
00098 //! @brief Whether the board has a valid flash algo.
00099 uint8_t flash_algo_valid(void);
00100 
00101 //! @brief Returns the MSD HTML help filename or a default.
00102 static inline const char * get_daplink_url_name ( void ) { return ((g_board_info.daplink_url_name[0] != 0) ? g_board_info.daplink_url_name : "MBED    HTM"); }
00103 
00104 //! @brief Returns the MSD volume name or a default.
00105 static inline const char * get_daplink_drive_name ( void ) { return ((g_board_info.daplink_drive_name[0] != 0) ? g_board_info.daplink_drive_name : "DAPLINK    "); }
00106 
00107 //! @brief Returns the target information URL or a default.
00108 static inline const char * get_daplink_target_url ( void ) { return ((g_board_info.daplink_target_url[0] != 0) ? g_board_info.daplink_target_url : "https://mbed.org/device/?code=@U?version=@V?target_id=@T"); }
00109 
00110 #ifdef __cplusplus
00111 }
00112 #endif
00113 
00114 #endif