Skip to content

Commit e92f150

Browse files
flitflit
committed
Docs: add string customisation; cleanup PORT_TARGET_FAMILY.md.
1 parent e97b46a commit e92f150

File tree

2 files changed

+59
-152
lines changed

2 files changed

+59
-152
lines changed

‎docs/PORT_TARGET_FAMILY.md‎

Lines changed: 8 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ static uint8_t security_bits_set(uint32_t addr, uint8_t *data, uint32_t size)
5858
}
5959

6060
const target_family_descriptor_t g_target_family = {
61+
.version = kTargetFamilyVersion,
6162
.family_id = myFamilyID,
6263
.default_reset_type = kHardwareReset,
6364
.target_before_init_debug = target_before_init_debug,
@@ -67,106 +68,9 @@ const target_family_descriptor_t g_target_family = {
6768
};
6869
```
6970
70-
The target family api is located in `source/target/target_family.h` and target_reset file can customize the function apis according to the family specification. Family id is a combination of vendor id and an incrementing id. There are predefined family id stubs that can be used for generic reset types; kStub_HWReset_FamilyID, kStub_SWVectReset_FamilyID and kStub_SWSysReset_FamilyID.
71+
The target family api is located in `source/target/target_family.h` and target_reset file can customize the function apis according to the family specification. Family id is a combination of vendor id and an incrementing id. There are predefined family id stubs that can be used for generic reset types; `kStub_HWReset_FamilyID`, `kStub_SWVectReset_FamilyID`, and `kStub_SWSysReset_FamilyID`.
7172
72-
```c
73-
/**
74-
* @file target_family.h
75-
* @brief
76-
*
77-
* DAPLink Interface Firmware
78-
* Copyright (c) 2018-2019, ARM Limited, All Rights Reserved
79-
* SPDX-License-Identifier: Apache-2.0
80-
*
81-
* Licensed under the Apache License, Version 2.0 (the "License"); you may
82-
* not use this file except in compliance with the License.
83-
* You may obtain a copy of the License at
84-
*
85-
* http://www.apache.org/licenses/LICENSE-2.0
86-
*
87-
* Unless required by applicable law or agreed to in writing, software
88-
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
89-
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
90-
* See the License for the specific language governing permissions and
91-
* limitations under the License.
92-
*/
93-
94-
#ifndef TARGET_FAMILY_H
95-
#define TARGET_FAMILY_H
96-
97-
#include <stdint.h>
98-
#include <string.h>
99-
#include "target_reset.h"
100-
101-
#define VENDOR_TO_FAMILY(x, y) (x<<8 | y)
102-
103-
typedef enum _reset_type {
104-
kHardwareReset=1,
105-
kSoftwareReset,
106-
} reset_type_t;
107-
108-
enum _vendor_ids {
109-
kStub_VendorID = 0,
110-
kNXP_VendorID = 11,
111-
kTI_VendorID = 16,
112-
kNordic_VendorID = 54,
113-
kToshiba_VendorID = 92,
114-
kRenesas_VendorID = 117,
115-
kWiznet_VendorID = 122,
116-
kRealtek_VendorID = 124,
117-
};
118-
119-
typedef enum _family_id {
120-
kStub_HWReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 1),
121-
kStub_SWVectReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 2),
122-
kStub_SWSysReset_FamilyID = VENDOR_TO_FAMILY(kStub_VendorID, 3),
123-
kNXP_KinetisK_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 1),
124-
kNXP_KinetisL_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 2),
125-
kNXP_Mimxrt_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 3),
126-
kNXP_RapidIot_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 4),
127-
kNXP_KinetisK32W_FamilyID = VENDOR_TO_FAMILY(kNXP_VendorID, 5),
128-
kNordic_Nrf51_FamilyID = VENDOR_TO_FAMILY(kNordic_VendorID, 1),
129-
kNordic_Nrf52_FamilyID = VENDOR_TO_FAMILY(kNordic_VendorID, 2),
130-
kRealtek_Rtl8195am_FamilyID = VENDOR_TO_FAMILY(kRealtek_VendorID, 1),
131-
kTI_Cc3220sf_FamilyID = VENDOR_TO_FAMILY(kTI_VendorID, 1),
132-
kToshiba_Tz_FamilyID = VENDOR_TO_FAMILY(kToshiba_VendorID, 1),
133-
kWiznet_W7500_FamilyID = VENDOR_TO_FAMILY(kWiznet_VendorID, 1),
134-
kRenesas_FamilyID = VENDOR_TO_FAMILY(kRenesas_VendorID, 1),
135-
} family_id_t;
136-
137-
typedef struct target_family_descriptor {
138-
uint16_t family_id; /*!< Use to select or identify target family from defined target family or custom ones */
139-
reset_type_t default_reset_type; /*!< Target family can select predefined reset from kHardwareReset and kSoftwareReset */
140-
uint32_t soft_reset_type; /*!< Families can override software reset type to VECTRESET or SYSRESETREQ */
141-
void (*target_before_init_debug)(void); /*!< Target dependant function before debug initialization */
142-
void (*prerun_target_config)(void); /*!< Target specific initialization */
143-
uint8_t (*target_unlock_sequence)(void); /*!< Unlock targets that can enter lock state */
144-
uint8_t (*security_bits_set)(uint32_t addr, uint8_t *data, uint32_t size); /*!< Check security bits in the programmable flash region */
145-
uint8_t (*target_set_state)(TARGET_RESET_STATE state); /*!< Families can customize target debug states in target_reset.h */
146-
void (*swd_set_target_reset)(uint8_t asserted); /*!< Families can customize how to send reset to the target */
147-
uint8_t (*validate_bin_nvic)(const uint8_t *buf); /*!< Validate a bin file to be flash by drag and drop */
148-
uint8_t (*validate_hexfile)(const uint8_t *buf); /*!< Validate a hex file to be flash by drag and drop */
149-
} target_family_descriptor_t;
150-
151-
extern const target_family_descriptor_t *g_target_family;
152-
153-
#ifdef __cplusplus
154-
extern "C" {
155-
#endif
156-
157-
void init_family(void);
158-
uint8_t target_family_valid(void);
159-
uint8_t target_set_state(TARGET_RESET_STATE state);
160-
void swd_set_target_reset(uint8_t asserted);
161-
162-
#ifdef __cplusplus
163-
}
164-
#endif
165-
166-
#endif
167-
```
168-
169-
A flash algorithm blob is needed to program the target MCUs internal (or external) flash memory. This blob contains position independent functions for erasing, reading and writing to the flash controller. Flash algorithm blobs are created from the [FlashAlgo project.](https://github.com/mbedmicro/FlashAlgo) An example blob is shown below and would be added to `source/family/<mfg>/<targetname>/flash_blob.c`
73+
A flash algorithm blob is needed to program the target MCUs internal (or external) flash memory. This blob contains position independent functions for erasing, reading and writing to the flash controller. Flash algorithm blobs are created from the [FlashAlgo project.](https://github.com/pyocd/FlashAlgo). An example blob is shown below and would be added to `source/family/<mfg>/<targetname>/flash_blob.c`
17074
17175
```c
17276
/**
@@ -193,28 +97,7 @@ A flash algorithm blob is needed to program the target MCUs internal (or externa
19397
#include "flash_blob.h"
19498
19599
static const uint32_t targetname_blob[] = {
196-
0xE00ABE00, 0x062D780D, 0x24084068, 0xD3000040, 0x1E644058, 0x1C49D1FA, 0x2A001E52, 0x4770D1F2,
197-
0x4770ba40, 0x4770bac0, 0x4c0cb510, 0xf04068a0, 0x60a00001, 0x301af246, 0xf44f6560, 0x60e07040,
198-
0x20012100, 0xf83ef000, 0x65612100, 0xf02168a1, 0x60a10101, 0xbf182800, 0xbd102001, 0x400c0000,
199-
0x4684b510, 0xf44f2300, 0xf8505180, 0x1f092b04, 0x1c52d002, 0xe001d0f9, 0xd0131c50, 0x68a04c0c,
200-
0x0001f040, 0xf8c460a0, 0x2001c010, 0x200260e0, 0x210060e0, 0xf0002001, 0x4603f815, 0xf02068a0,
201-
0x60a00001, 0xbf142b00, 0x20002001, 0x0000bd10, 0x400c0000, 0xf6414902, 0x63c83071, 0x47702000,
202-
0x400c0000, 0x4b14b410, 0xc050f8df, 0x201cf8dc, 0x0f16f012, 0xf8dcd014, 0xf0200008, 0xf8cc0005,
203-
0xf0120008, 0xbf1e0f02, 0x0001f06f, 0x4770bc10, 0x0f04f012, 0xf04fbf1e, 0xbc1030ff, 0xe0074770,
204-
0x428a4002, 0xbc10d102, 0x47702000, 0xd1dd1e5b, 0xf06fbc10, 0x47700002, 0x00989680, 0x400c0000,
205-
0x4df0e92d, 0x1cc84604, 0x0603f020, 0x46904859, 0xf0416881, 0x60810101, 0xd9732e07, 0x0f07f014,
206-
0xf8d8d011, 0x61041000, 0x60c22201, 0x21086181, 0x210060c1, 0xf7ff4610, 0x2800ffb5, 0x1d24d17e,
207-
0x0810f108, 0x484b1f36, 0xf0416881, 0x60810104, 0xbf882e07, 0x0a02f06f, 0xf504d966, 0x46015080,
208-
0x010bf36f, 0x42b11b09, 0x4635bf8e, 0x000bf36f, 0xf0151b05, 0xbf180f04, 0x46471f2d, 0x20012100,
209-
0xff90f7ff, 0xd13b2800, 0xe0e8f8df, 0x4010f8ce, 0xf8ce2001, 0xf857000c, 0xf8ce0b04, 0xf8570018,
210-
0xf8ce0b04, 0x20080018, 0x000cf8ce, 0x0208f1a5, 0xd9332a07, 0x0b08f04f, 0x46dc482f, 0x101cf8de,
211-
0x0f16f011, 0xf8ded012, 0xf0200008, 0xf8ce0005, 0xf0110008, 0xbf180f02, 0x0001f06f, 0xf011d10f,
212-
0xbf180f04, 0x30fff04f, 0xe007d109, 0x010bea01, 0xd1014561, 0xe0022000, 0xd1df1e40, 0xb1104650,
213-
0xe00bb9e0, 0xf857e01c, 0xf8ce0b04, 0xf8570018, 0xf8ce0b04, 0x3a080018, 0xd8cb2a07, 0xeb081b76,
214-
0x442c0885, 0xd8982e07, 0x20012100, 0xff3af7ff, 0x4810b920, 0xf0216881, 0xe0000104, 0x6081e00f,
215-
0x480cb186, 0x1000f8d8, 0x22016104, 0x618160c2, 0x60c12108, 0x46102100, 0xff24f7ff, 0x2001b110,
216-
0x8df0e8bd, 0x68814803, 0x0101f021, 0x20006081, 0x8df0e8bd, 0x400c0000, 0x00989680, 0x68814803,
217-
0x0105f021, 0x20006081, 0x00004770, 0x400c0000, 0x00000000,
100+
0xE00ABE00, /* ... */, 0x00000000,
218101
};
219102
220103
/**
@@ -283,48 +166,21 @@ The last required file is the target MCU description file `source/family/<mfg>/<
283166
#include "flash_blob.c"
284167

285168
target_cfg_t target_device = {
169+
.version = kTargetConfigVersion,
286170
.sectors_info = sectors_info,
287171
.sector_info_length = (sizeof(sectors_info))/(sizeof(sector_info_t)),
288172
.flash_regions[0].start = 0x00000000,
289173
.flash_regions[0].end = 0x00200000,
290174
.flash_regions[0].flags = kRegionIsDefault,
291-
.flash_regions[0].flash_algo = (program_target_t *) &flash,
175+
.flash_regions[0].flash_algo = (program_target_t *) &flash,
292176
.ram_regions[0].start = 0x1fff0000,
293177
.ram_regions[0].end = 0x20030000,
294178
};
295179
```
296-
Complete target configuration api is located in `source/target/target_config.h`
297-
```c
298-
enum _region_flags {
299-
kRegionIsDefault = (1 << 0), //out of bounds regions will use the same flash algo if this is set
300-
kRegionIsSecure = (1 << 1)
301-
};
302180

181+
Complete target configuration api is located in `source/target/target_config.h`
303182

304-
typedef struct region_info {
305-
uint32_t start;
306-
uint32_t end;
307-
uint32_t flags;
308-
uint8_t alias_index; /*!<use with flags; will point to a different index if there is an alias region */
309-
program_target_t *flash_algo; /*!< A pointer to the flash algorithm structure */
310-
} region_info_t;
311-
312-
/**
313-
@struct target_cfg_t
314-
@brief The firmware configuration struct has unique about the chip its running on.
315-
*/
316-
typedef struct target_cfg {
317-
uint32_t version; /*!< Target configuration version */
318-
const sector_info_t* sectors_info; /*!< Sector start and length list */
319-
int sector_info_length; /*!< Sector start and length list total */
320-
region_info_t flash_regions[MAX_EXTRA_FLASH_REGION]; /*!< Flash regions */
321-
region_info_t ram_regions[MAX_EXTRA_RAM_REGION]; /*!< RAM regions */
322-
uint8_t erase_reset; /*!< Reset after performing an erase */
323-
const char *rt_board_id; /*!< If assigned, this is a flexible board ID */
324-
uint16_t rt_family_id; /*!< If assigned, this is a flexible board ID */
325-
} target_cfg_t;
326-
```
327183
At this point these target specific files could be added to a board build and developed.
328184

329185
# Supported Target Families
330-
A HIC can target all supported families available and a post build script can modify a board's family id to point to the correct family. See [Porting board guide](PORT_BOARD.md)
186+
A HIC can target all supported families available and a post build script can modify a board's family id to point to the correct family. See [Porting board guide](PORT_BOARD.md)

‎docs/string_customization.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Customizing DAPLink strings
2+
3+
There are a number of strings reported by DAPLink through USB descriptors, CMSIS-DAP, and USB MSD. These
4+
can be configured by a build or set in board and target info.
5+
6+
Preprocessor macros should be set in the yaml records for either the board, found under `./records/board`,
7+
or the HIC, found under `./records/hic_hal`.
8+
9+
10+
## USB descriptor strings
11+
12+
**USB product string**: \
13+
Macro: `USB_PROD_STR` \
14+
The value of this macro _must_ include the string "CMSIS-DAP". Otherwise debuggers will not recognize
15+
the USB device. An example is the string used for micro:bit, "BBC micro:bit CMSIS-DAP".
16+
17+
18+
## MSD strings
19+
20+
**MSD volume name**: \
21+
Struct member: `board_info::daplink_drive_name`
22+
23+
**URL file name**: \
24+
Struct member: `board_info::daplink_url_name`
25+
26+
**URL file contents**: \
27+
Struct member: `board_info::daplink_target_url`
28+
29+
30+
## CMSIS-DAP string
31+
32+
**CMSIS-DAP product name**: \
33+
Macro: `CMSIS_DAP_VENDOR_NAME` \
34+
Not usually set.
35+
36+
**CMSIS-DAP product name**: \
37+
Macro: `CMSIS_DAP_PRODUCT_NAME` \
38+
Defaults to "DAPLink".
39+
40+
**CMSIS-DAP v2.1 target device vendor**: \
41+
Struct member: `target_family_descriptor::target_vendor`
42+
43+
**CMSIS-DAP v2.1 target device name**: \
44+
Struct member: `target_family_descriptor::target_part_number`
45+
46+
**CMSIS-DAP v2.1 target board vendor**: \
47+
Struct member: `board_info::board_vendor`
48+
49+
**CMSIS-DAP v2.1 target board name**: \
50+
Struct member: `board_info::board_name`
51+

0 commit comments

Comments
 (0)