Arrow / Mbed OS DAPLink Reset

Repostiory containing DAPLink source code with Reset Pin workaround for HANI_IOT board.

Upstream: https://github.com/ARMmbed/DAPLink

docs/PORT_BOARD.md@0:01f31e923fe2, 2020-04-07 (annotated)

Committer:
Pawel Zarembski
Date:
Tue Apr 07 12:55:42 2020 +0200
Revision:
0:01f31e923fe2
hani: DAPLink with reset workaround

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Pawel Zarembski 0:01f31e923fe2 1 # Adding A New Board
Pawel Zarembski 0:01f31e923fe2 2 A board is composed of a Hardware Interface Circuit and target MCU. To create a new board build a description needs to be added to `projects.yaml`. The yaml descriptions are used to create modules that can be inherited. Create a new board build by adding the product name and the required modules. eg: if the HIC is OpenSDA based on the NXP MK20D50 MCU
Pawel Zarembski 0:01f31e923fe2 3
Pawel Zarembski 0:01f31e923fe2 4 ```yaml
Pawel Zarembski 0:01f31e923fe2 5 k20dx_myboardname_if:
Pawel Zarembski 0:01f31e923fe2 6 - *module_if
Pawel Zarembski 0:01f31e923fe2 7 - *module_hic_k20dx
Pawel Zarembski 0:01f31e923fe2 8 - records/board/myboardname.yaml
Pawel Zarembski 0:01f31e923fe2 9 ```
Pawel Zarembski 0:01f31e923fe2 10
Pawel Zarembski 0:01f31e923fe2 11 Next create a new file in the `records/board` directory called myboardname.yaml. This file defines the target family MCU and allows overrideable board parameters to be configured. The target family MCU in this example exists and is a Nordic nRF51822 (16k RAM variant). More than one target/family can be added to the project and the family can be retargeted by family ID. See `Post-build Board ID and Family ID` section.
Pawel Zarembski 0:01f31e923fe2 12
Pawel Zarembski 0:01f31e923fe2 13 ```yaml
Pawel Zarembski 0:01f31e923fe2 14 common:
Pawel Zarembski 0:01f31e923fe2 15 sources:
Pawel Zarembski 0:01f31e923fe2 16 board:
Pawel Zarembski 0:01f31e923fe2 17 - source/board/myboardname.c
Pawel Zarembski 0:01f31e923fe2 18 family:
Pawel Zarembski 0:01f31e923fe2 19 - source/family/nordic/nrf51822/target_16.c
Pawel Zarembski 0:01f31e923fe2 20 - source/family/nordic/target_reset_nrf51.c
Pawel Zarembski 0:01f31e923fe2 21 ```
Pawel Zarembski 0:01f31e923fe2 22
Pawel Zarembski 0:01f31e923fe2 23 This assumes there is already target support present in the codebase. If adding a new target family is needed, additional steps in [Porting target family guide](PORT_TARGET_FAMILY.md) will be needed. If the target support exists `source/board/myboardname.c` needs creation with a BOARD ID. If you're developing a custom or non-official Mbed platform, then can use any BOARD ID and the `mbedls` [mocking feature](https://github.com/ARMmbed/mbed-os-tools/blob/master/packages/mbed-ls/README.md#mocking-renaming-platforms).
Pawel Zarembski 0:01f31e923fe2 24 ```c
Pawel Zarembski 0:01f31e923fe2 25 /**
Pawel Zarembski 0:01f31e923fe2 26 * @file myboard.c
Pawel Zarembski 0:01f31e923fe2 27 * @brief board_info api for my board
Pawel Zarembski 0:01f31e923fe2 28 *
Pawel Zarembski 0:01f31e923fe2 29 * DAPLink Interface Firmware
Pawel Zarembski 0:01f31e923fe2 30 * Copyright (c) 2009-2019, ARM Limited, All Rights Reserved
Pawel Zarembski 0:01f31e923fe2 31 * SPDX-License-Identifier: Apache-2.0
Pawel Zarembski 0:01f31e923fe2 32 *
Pawel Zarembski 0:01f31e923fe2 33 * Licensed under the Apache License, Version 2.0 (the "License"); you may
Pawel Zarembski 0:01f31e923fe2 34 * not use this file except in compliance with the License.
Pawel Zarembski 0:01f31e923fe2 35 * You may obtain a copy of the License at
Pawel Zarembski 0:01f31e923fe2 36 *
Pawel Zarembski 0:01f31e923fe2 37 * http://www.apache.org/licenses/LICENSE-2.0
Pawel Zarembski 0:01f31e923fe2 38 *
Pawel Zarembski 0:01f31e923fe2 39 * Unless required by applicable law or agreed to in writing, software
Pawel Zarembski 0:01f31e923fe2 40 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
Pawel Zarembski 0:01f31e923fe2 41 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Pawel Zarembski 0:01f31e923fe2 42 * See the License for the specific language governing permissions and
Pawel Zarembski 0:01f31e923fe2 43 * limitations under the License.
Pawel Zarembski 0:01f31e923fe2 44 */
Pawel Zarembski 0:01f31e923fe2 45
Pawel Zarembski 0:01f31e923fe2 46 #include "target_family.h"
Pawel Zarembski 0:01f31e923fe2 47 #include "target_board.h"
Pawel Zarembski 0:01f31e923fe2 48
Pawel Zarembski 0:01f31e923fe2 49 const board_info_t g_board_info = {
Pawel Zarembski 0:01f31e923fe2 50 .board_id = "0x240",
Pawel Zarembski 0:01f31e923fe2 51 .family_id = kStub_HWReset_FamilyID,
Pawel Zarembski 0:01f31e923fe2 52 .flags = kEnablePageErase|kEnableUnderResetConnect,
Pawel Zarembski 0:01f31e923fe2 53 .target_cfg = &target_device,
Pawel Zarembski 0:01f31e923fe2 54 };
Pawel Zarembski 0:01f31e923fe2 55 ```
Pawel Zarembski 0:01f31e923fe2 56 The complete fields of board_info api with description is in `source/target/target_board.h`.
Pawel Zarembski 0:01f31e923fe2 57 ```c
Pawel Zarembski 0:01f31e923fe2 58 // Flags for board_info
Pawel Zarembski 0:01f31e923fe2 59 enum {
Pawel Zarembski 0:01f31e923fe2 60 kEnablePageErase = 1, /*!< Enable page programming and sector erase for drag and drop */
Pawel Zarembski 0:01f31e923fe2 61 kEnableUnderResetConnect = 1<<1, /*!< Enable under reset connection when enabling debug mode */
Pawel Zarembski 0:01f31e923fe2 62 };
Pawel Zarembski 0:01f31e923fe2 63
Pawel Zarembski 0:01f31e923fe2 64 typedef struct __attribute__((__packed__)) board_info {
Pawel Zarembski 0:01f31e923fe2 65 uint16_t infoVersion; /*!< Version number of the board */
Pawel Zarembski 0:01f31e923fe2 66 uint16_t family_id; /*!< Use to select target family from defined target family ids */
Pawel Zarembski 0:01f31e923fe2 67 char board_id[5]; /*!< 4-char board ID plus null terminator */
Pawel Zarembski 0:01f31e923fe2 68 uint8_t _padding[3];
Pawel Zarembski 0:01f31e923fe2 69 uint32_t flags; /*!< Combination of kEnablePageErase and kEnableUnderResetConnect */
Pawel Zarembski 0:01f31e923fe2 70 target_cfg_t *target_cfg; /*!< Specific chip configuration for the target and enables MSD when non-NULL */
Pawel Zarembski 0:01f31e923fe2 71
Pawel Zarembski 0:01f31e923fe2 72 // fields used by MSD
Pawel Zarembski 0:01f31e923fe2 73 vfs_filename_t daplink_url_name; /*!< Customize the URL file name */
Pawel Zarembski 0:01f31e923fe2 74 vfs_filename_t daplink_drive_name; /*!< Customize the MSD DAPLink drive name */
Pawel Zarembski 0:01f31e923fe2 75 char daplink_target_url[64]; /*!< Customize the target url in DETAILS.TXT */
Pawel Zarembski 0:01f31e923fe2 76
Pawel Zarembski 0:01f31e923fe2 77 // some specific board initilization
Pawel Zarembski 0:01f31e923fe2 78 void (*prerun_board_config)(void); /*!< Specific board debug/ID related initialization */
Pawel Zarembski 0:01f31e923fe2 79 void (*swd_set_target_reset)(uint8_t asserted); /*!< Boards can customize how to send reset to the target precedence over target family */
Pawel Zarembski 0:01f31e923fe2 80 uint8_t (*target_set_state)(TARGET_RESET_STATE state); /*!< Boards can customize target debug states in target_reset.h precedence over target family */
Pawel Zarembski 0:01f31e923fe2 81 uint32_t soft_reset_type; /*!< Boards can override software reset type to VECTRESET or SYSRESETREQ */
Pawel Zarembski 0:01f31e923fe2 82 } board_info_t;
Pawel Zarembski 0:01f31e923fe2 83 ```
Pawel Zarembski 0:01f31e923fe2 84 Now running `progen generate -t uvision` will create project files including the new board that can be developed and debugged. Complete development guide is in [Developers Guide](DEVELOPERS-GUIDE.md). For more information about the yaml format [see the project_generator documentation.](https://github.com/project-generator/project_generator/wiki/Getting_started)
Pawel Zarembski 0:01f31e923fe2 85
Pawel Zarembski 0:01f31e923fe2 86 ### Adding Board to Automated Tests
Pawel Zarembski 0:01f31e923fe2 87 Update `test/info.py` so the new board has at least one configuration in SUPPORTED_CONFIGURATIONS
Pawel Zarembski 0:01f31e923fe2 88 ```python
Pawel Zarembski 0:01f31e923fe2 89 SUPPORTED_CONFIGURATIONS = [
Pawel Zarembski 0:01f31e923fe2 90 # Board ID Family ID Firmware Bootloader Target
Pawel Zarembski 0:01f31e923fe2 91 ...
Pawel Zarembski 0:01f31e923fe2 92 ( 0x0240, VENDOR_TO_FAMILY('NXP', 1), 'k20dx_frdmk64f_if', 'k20dx_bl', 'FRDM-K64F' ),
Pawel Zarembski 0:01f31e923fe2 93 ...
Pawel Zarembski 0:01f31e923fe2 94 ]
Pawel Zarembski 0:01f31e923fe2 95 ```
Pawel Zarembski 0:01f31e923fe2 96 Configration Fields
Pawel Zarembski 0:01f31e923fe2 97 * Board ID - The ID assigned to the board type.
Pawel Zarembski 0:01f31e923fe2 98 * Family ID - Use to select or identify target family from defined target family or custom ones. Note that common or stub families are supported which supports hw_reset, sw_vectreset or sw_sysreset. More details in [Porting target family guide](PORT_TARGET_FAMILY.md).
Pawel Zarembski 0:01f31e923fe2 99 * Firmware - The name of the firmware as shown in projects.yaml.
Pawel Zarembski 0:01f31e923fe2 100 * Bootloader - The name of the bootloader firmware as shown in projects.yaml. Only required on HICs with a DAPLink bootloader.
Pawel Zarembski 0:01f31e923fe2 101 * Target - Name of the target for this board.
Pawel Zarembski 0:01f31e923fe2 102 * If this is an mbed official board then the target should match the name in the mbed platform page URL. For example the K64F is located at https://developer.mbed.org/platforms/FRDM-K64F/ so it would have the target name `FRDM-K64F`. Using this naming convention allows the automated tests to use the RESTful Compile API. the automated tests will build the target UART application on-the-fly in the cloud using the RESTful Compile API, download it to the PC, then download the resulting image to the target.
Pawel Zarembski 0:01f31e923fe2 103 * If it is not, you will need to build the UART application yourself and supply it to `test/run_tests.py` via --targetdir. In this case, the target is the application image filename sans extension.
Pawel Zarembski 0:01f31e923fe2 104
Pawel Zarembski 0:01f31e923fe2 105 You may need to update one or more other dictionaries. See comments in the code for guidance.
Pawel Zarembski 0:01f31e923fe2 106
Pawel Zarembski 0:01f31e923fe2 107 See [Automated Tests](AUTOMATED_TESTS.md) for more information related to automated testing.
Pawel Zarembski 0:01f31e923fe2 108
Pawel Zarembski 0:01f31e923fe2 109 # Post-build Board ID and Family ID
Pawel Zarembski 0:01f31e923fe2 110 Board ID and Family ID can be overwritten by `tools/post_build_scpript.py`. This is helpful for supporting existing families and adding board IDs to the database without the need to compile DAPLink. Board ID can uniquely identify the target board while family ID can select which target family to support.
Pawel Zarembski 0:01f31e923fe2 111 ```
Pawel Zarembski 0:01f31e923fe2 112 usage: post_build_script.py [-h] [--board-id BOARD_ID] [--family-id FAMILY_ID]
Pawel Zarembski 0:01f31e923fe2 113 [--bin-offset BIN_OFFSET]
Pawel Zarembski 0:01f31e923fe2 114 input output
Pawel Zarembski 0:01f31e923fe2 115
Pawel Zarembski 0:01f31e923fe2 116 post Build tool for Board ID, Family ID and CRC generation
Pawel Zarembski 0:01f31e923fe2 117
Pawel Zarembski 0:01f31e923fe2 118 positional arguments:
Pawel Zarembski 0:01f31e923fe2 119 input Hex or bin file to read from.
Pawel Zarembski 0:01f31e923fe2 120 output Output base file name to write crc, board_id and
Pawel Zarembski 0:01f31e923fe2 121 family_id.
Pawel Zarembski 0:01f31e923fe2 122
Pawel Zarembski 0:01f31e923fe2 123 optional arguments:
Pawel Zarembski 0:01f31e923fe2 124 -h, --help show this help message and exit
Pawel Zarembski 0:01f31e923fe2 125 --board-id BOARD_ID board id to for the target in hex
Pawel Zarembski 0:01f31e923fe2 126 --family-id FAMILY_ID
Pawel Zarembski 0:01f31e923fe2 127 family id to for the target in hex
Pawel Zarembski 0:01f31e923fe2 128 --bin-offset BIN_OFFSET
Pawel Zarembski 0:01f31e923fe2 129 binary offset in hex
Pawel Zarembski 0:01f31e923fe2 130 ```
Pawel Zarembski 0:01f31e923fe2 131 Note however that run time board id and family id can be present in the code and DAPLink will use this if it has non-zero value. From `source/hic_hal_target_config.h`
Pawel Zarembski 0:01f31e923fe2 132 ```
Pawel Zarembski 0:01f31e923fe2 133 /**
Pawel Zarembski 0:01f31e923fe2 134 @struct target_cfg_t
Pawel Zarembski 0:01f31e923fe2 135 @brief The firmware configuration struct has unique about the chip its running on.
Pawel Zarembski 0:01f31e923fe2 136 */
Pawel Zarembski 0:01f31e923fe2 137 ...
Pawel Zarembski 0:01f31e923fe2 138 typedef struct target_cfg {
Pawel Zarembski 0:01f31e923fe2 139 ...
Pawel Zarembski 0:01f31e923fe2 140 const char *rt_board_id; /*!< If assigned, this is a flexible board ID */
Pawel Zarembski 0:01f31e923fe2 141 uint16_t rt_family_id; /*!< If assigned, this is a flexible board ID */
Pawel Zarembski 0:01f31e923fe2 142 } target_cfg_t;
Pawel Zarembski 0:01f31e923fe2 143 ...
Pawel Zarembski 0:01f31e923fe2 144 ```