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/BUILD_OUTPUT.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 # DAPLink Build Output
Pawel Zarembski 0:01f31e923fe2 2
Pawel Zarembski 0:01f31e923fe2 3 ## Variants
Pawel Zarembski 0:01f31e923fe2 4
Pawel Zarembski 0:01f31e923fe2 5 Building a DAPLink target produces several variants of the build output. Files with the following names will be located in the project build directory after a successful build.
Pawel Zarembski 0:01f31e923fe2 6
Pawel Zarembski 0:01f31e923fe2 7 ``*_if.bin``
Pawel Zarembski 0:01f31e923fe2 8
Pawel Zarembski 0:01f31e923fe2 9 - Base file created by build, should not be used.
Pawel Zarembski 0:01f31e923fe2 10
Pawel Zarembski 0:01f31e923fe2 11 ``*_if_crc.bin``
Pawel Zarembski 0:01f31e923fe2 12
Pawel Zarembski 0:01f31e923fe2 13 - Preferred image for new boards. Does not work with some old bootloaders due to the vector table validation
Pawel Zarembski 0:01f31e923fe2 14
Pawel Zarembski 0:01f31e923fe2 15 ``*_if_crc.hex``
Pawel Zarembski 0:01f31e923fe2 16
Pawel Zarembski 0:01f31e923fe2 17 - Same as "``*_if_crc.bin``" just in hex form.
Pawel Zarembski 0:01f31e923fe2 18
Pawel Zarembski 0:01f31e923fe2 19 ``*_if_crc_legacy_0x5000.bin``
Pawel Zarembski 0:01f31e923fe2 20
Pawel Zarembski 0:01f31e923fe2 21 - Image required for existing boards with a bootloader built for an application starting at 0x5000.
Pawel Zarembski 0:01f31e923fe2 22
Pawel Zarembski 0:01f31e923fe2 23 ``*_if_crc_legacy_0x8000.bin``
Pawel Zarembski 0:01f31e923fe2 24
Pawel Zarembski 0:01f31e923fe2 25 - Image required for existing boards with a bootloader built for an application starting at 0x8000.
Pawel Zarembski 0:01f31e923fe2 26
Pawel Zarembski 0:01f31e923fe2 27 The ``tools/post_compute_crc.py`` script is automatically run on the build output. It produces the variants listed above by modifying the output images in several ways.
Pawel Zarembski 0:01f31e923fe2 28
Pawel Zarembski 0:01f31e923fe2 29 The image ``*_if_crc_legacy_0x5000.bin`` is a copy of ``*_if_crc_legacy_0x8000.bin`` but with 0x3000 bytes of extra padding pre-pended to the image. The first 0x40 bytes are an exact copy of the vector table and the remaining 0x2FC0 bytes are filled with 0xFF. This makes an image that can be loaded onto bootloaders with the old offset (0x5000) without requiring a complete rebuild.
Pawel Zarembski 0:01f31e923fe2 30
Pawel Zarembski 0:01f31e923fe2 31 Not all targets will produce the legacy output files.
Pawel Zarembski 0:01f31e923fe2 32
Pawel Zarembski 0:01f31e923fe2 33 ## Image structure
Pawel Zarembski 0:01f31e923fe2 34
Pawel Zarembski 0:01f31e923fe2 35 Aside from the code itself, the following are the important features of a DAPLink binary image. The ``post_compute_crc.py`` script adds the checksum and CRC into the images.
Pawel Zarembski 0:01f31e923fe2 36
Pawel Zarembski 0:01f31e923fe2 37 ### Vector table
Pawel Zarembski 0:01f31e923fe2 38
Pawel Zarembski 0:01f31e923fe2 39 All images must begin with a valid NVIC vector table.
Pawel Zarembski 0:01f31e923fe2 40
Pawel Zarembski 0:01f31e923fe2 41 The vector table is defined by the ``startup_MCUNAME.S`` file for each of the HIC HALs. The build info fields below are set directly in the vector table definition.
Pawel Zarembski 0:01f31e923fe2 42
Pawel Zarembski 0:01f31e923fe2 43 ### Checksum
Pawel Zarembski 0:01f31e923fe2 44
Pawel Zarembski 0:01f31e923fe2 45 The first 7 vectors from the NVIC vector table (offsets 0x00-0x18) are checksummed. The two's complement of the checksum is stored in the unused, reserved vector at offset 0x1C. This checksum is required for certain NXP MCUs in order to boot. For other MCUs, the checksum is ignored.
Pawel Zarembski 0:01f31e923fe2 46
Pawel Zarembski 0:01f31e923fe2 47 ### Build info fields
Pawel Zarembski 0:01f31e923fe2 48
Pawel Zarembski 0:01f31e923fe2 49 The vector table for DAPLink images contains several build info fields. These fields are placed in the unused, reserved vector table entries starting at offset 0x20.
Pawel Zarembski 0:01f31e923fe2 50
Pawel Zarembski 0:01f31e923fe2 51 The information here is as follows (in order):
Pawel Zarembski 0:01f31e923fe2 52
Pawel Zarembski 0:01f31e923fe2 53 * ``DAPLINK_BUILD_KEY``
Pawel Zarembski 0:01f31e923fe2 54 * Key used to indicate if the image is bootloader or interface.
Pawel Zarembski 0:01f31e923fe2 55 * ``DAPLINK_HIC_ID``
Pawel Zarembski 0:01f31e923fe2 56 * Key used to determine hardware compatibility.
Pawel Zarembski 0:01f31e923fe2 57 * This ensures that for example a bootloader update mean for a k20dx could never be loaded on a kl26z or any other chip
Pawel Zarembski 0:01f31e923fe2 58 * ``DAPLINK_VERSION``
Pawel Zarembski 0:01f31e923fe2 59 * Software version.
Pawel Zarembski 0:01f31e923fe2 60 * Meant for checking for incompatible legacy versions.
Pawel Zarembski 0:01f31e923fe2 61 * Currently it is not used for this purpose and is just displayed in ``details.txt``.
Pawel Zarembski 0:01f31e923fe2 62
Pawel Zarembski 0:01f31e923fe2 63 This change caused a problem with some old bootloaders, which require the 3 vector table entries starting at 0x20 to be set to 0. To overcome this the build scripts create the legacy images which zero out 0x20 and recompute the checksum. If you compare ``*_if_crc.bin`` and ``*_if_crc_legacy_0x8000.bin`` you should be able to see this difference.
Pawel Zarembski 0:01f31e923fe2 64
Pawel Zarembski 0:01f31e923fe2 65 The corresponding struct in the code for these fields is ``daplink_info_t``, defined in ``daplink.h``. Constants with the valid values for these fields are also defined in ``daplink.h``.
Pawel Zarembski 0:01f31e923fe2 66
Pawel Zarembski 0:01f31e923fe2 67 ### CRC
Pawel Zarembski 0:01f31e923fe2 68
Pawel Zarembski 0:01f31e923fe2 69 A CRC-32 is computed over the base output file (``*_if.bin``) and stored in the last 4 bytes of the image in little endian byte order. This produces the ``*_if_crc.bin`` file.
Pawel Zarembski 0:01f31e923fe2 70
Pawel Zarembski 0:01f31e923fe2 71 At the moment the interface CRC isn't actually enforced so existing and interface images without a CRC can still be loaded.
Pawel Zarembski 0:01f31e923fe2 72