Arrow
Repostiory containing DAPLink source code with Reset Pin workaround for HANI_IOT board.
Upstream: https://github.com/ARMmbed/DAPLink
docs/DEVELOPERS-GUIDE.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?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Pawel Zarembski |
0:01f31e923fe2 | 1 | # DAPLink Developers Guide |
| Pawel Zarembski |
0:01f31e923fe2 | 2 | |
| Pawel Zarembski |
0:01f31e923fe2 | 3 | ## Setup |
| Pawel Zarembski |
0:01f31e923fe2 | 4 | DAPLink sources can be compiled using Keil MDK-ARM or mbed cli tool with arm compiler, which could be run both on Linux and Windows. See [here](AUTOMATED_TESTS.md) for test instructions on both OS and Mac. |
| Pawel Zarembski |
0:01f31e923fe2 | 5 | |
| Pawel Zarembski |
0:01f31e923fe2 | 6 | Install the necessary tools listed below. Skip any step where a compatible tool already exists. |
| Pawel Zarembski |
0:01f31e923fe2 | 7 | |
| Pawel Zarembski |
0:01f31e923fe2 | 8 | * Install [Python 2, 2.7.11 or above](https://www.python.org/downloads/) . Add to PATH. |
| Pawel Zarembski |
0:01f31e923fe2 | 9 | * Install [Git](https://git-scm.com/downloads) . Add to PATH. |
| Pawel Zarembski |
0:01f31e923fe2 | 10 | * Install [Keil MDK-ARM](https://www.keil.com/download/product/), preferably version 5. Set environment variable "UV4" to |
| Pawel Zarembski |
0:01f31e923fe2 | 11 | the absolute path of the UV4 executable if you don't install to the default location. Note that "UV4" is what's used for |
| Pawel Zarembski |
0:01f31e923fe2 | 12 | both MDK versions 4 and 5. This step can be skipped if you plan to use mbed cli, but you still need Arm Compiler 5, and |
| Pawel Zarembski |
0:01f31e923fe2 | 13 | MDK is required to debug. |
| Pawel Zarembski |
0:01f31e923fe2 | 14 | * Install virtualenv in your global Python installation eg: `pip install virtualenv`. |
| Pawel Zarembski |
0:01f31e923fe2 | 15 | |
| Pawel Zarembski |
0:01f31e923fe2 | 16 | |
| Pawel Zarembski |
0:01f31e923fe2 | 17 | **Step 1.** Initial setup. |
| Pawel Zarembski |
0:01f31e923fe2 | 18 | |
| Pawel Zarembski |
0:01f31e923fe2 | 19 | Get the sources and create a virtual environment |
| Pawel Zarembski |
0:01f31e923fe2 | 20 | |
| Pawel Zarembski |
0:01f31e923fe2 | 21 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 22 | $ git clone https://github.com/mbedmicro/DAPLink |
| Pawel Zarembski |
0:01f31e923fe2 | 23 | $ cd DAPLink |
| Pawel Zarembski |
0:01f31e923fe2 | 24 | $ pip install virtualenv |
| Pawel Zarembski |
0:01f31e923fe2 | 25 | $ virtualenv venv |
| Pawel Zarembski |
0:01f31e923fe2 | 26 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 27 | |
| Pawel Zarembski |
0:01f31e923fe2 | 28 | **Step 2.** One-time mbed-cli setup. |
| Pawel Zarembski |
0:01f31e923fe2 | 29 | |
| Pawel Zarembski |
0:01f31e923fe2 | 30 | This step is only required once if you are planning to use the mbed-cli build method. |
| Pawel Zarembski |
0:01f31e923fe2 | 31 | |
| Pawel Zarembski |
0:01f31e923fe2 | 32 | First run step 3 below to activate the virtual environment. Then execute these commands. |
| Pawel Zarembski |
0:01f31e923fe2 | 33 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 34 | $ mbed deploy |
| Pawel Zarembski |
0:01f31e923fe2 | 35 | $ mbed config root . |
| Pawel Zarembski |
0:01f31e923fe2 | 36 | $ mbed config ARM_PATH <FULL_PATH_TO_ARMCC_FOLDER> |
| Pawel Zarembski |
0:01f31e923fe2 | 37 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 38 | |
| Pawel Zarembski |
0:01f31e923fe2 | 39 | |
| Pawel Zarembski |
0:01f31e923fe2 | 40 | ## Activate virtual environment |
| Pawel Zarembski |
0:01f31e923fe2 | 41 | **Step 3.** Activate the virtual environment and update requirements. This is necessary when you open a new shell. **This should be done every time you pull new changes** |
| Pawel Zarembski |
0:01f31e923fe2 | 42 | |
| Pawel Zarembski |
0:01f31e923fe2 | 43 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 44 | $ venv/Scripts/activate (For Linux) |
| Pawel Zarembski |
0:01f31e923fe2 | 45 | $ venv/Scripts/activate.bat (For Windows) |
| Pawel Zarembski |
0:01f31e923fe2 | 46 | $ pip install -r requirements.txt |
| Pawel Zarembski |
0:01f31e923fe2 | 47 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 48 | |
| Pawel Zarembski |
0:01f31e923fe2 | 49 | |
| Pawel Zarembski |
0:01f31e923fe2 | 50 | ## Build |
| Pawel Zarembski |
0:01f31e923fe2 | 51 | **This should be done every time you pull new changes** |
| Pawel Zarembski |
0:01f31e923fe2 | 52 | |
| Pawel Zarembski |
0:01f31e923fe2 | 53 | There are two ways to build DAPLink. You can generate Keil MDK project files and build within MDK. MDK is also used to debug DAPLink running on the interface chip. Or, you can use the `mbedcli_compile.py` script to build projects from the command line without requiring MDK. |
| Pawel Zarembski |
0:01f31e923fe2 | 54 | |
| Pawel Zarembski |
0:01f31e923fe2 | 55 | |
| Pawel Zarembski |
0:01f31e923fe2 | 56 | **Step 4.1.** For MDK progen compilation. |
| Pawel Zarembski |
0:01f31e923fe2 | 57 | |
| Pawel Zarembski |
0:01f31e923fe2 | 58 | This command generates MDK project files under the `projectfiles/uvision` directory. |
| Pawel Zarembski |
0:01f31e923fe2 | 59 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 60 | $ progen generate -t uvision |
| Pawel Zarembski |
0:01f31e923fe2 | 61 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 62 | |
| Pawel Zarembski |
0:01f31e923fe2 | 63 | To only generate one specific project, use a command like this: |
| Pawel Zarembski |
0:01f31e923fe2 | 64 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 65 | progen generate -f projects.yaml -p stm32f103xb_stm32f746zg_if -t uvision |
| Pawel Zarembski |
0:01f31e923fe2 | 66 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 67 | These options to `progen` set the parameters: |
| Pawel Zarembski |
0:01f31e923fe2 | 68 | - `-f` for the input projects file |
| Pawel Zarembski |
0:01f31e923fe2 | 69 | - `-p` for the project name |
| Pawel Zarembski |
0:01f31e923fe2 | 70 | - `-t` to specify the IDE name |
| Pawel Zarembski |
0:01f31e923fe2 | 71 | |
| Pawel Zarembski |
0:01f31e923fe2 | 72 | |
| Pawel Zarembski |
0:01f31e923fe2 | 73 | **Step 4.2.** For mbed-cli project compilation |
| Pawel Zarembski |
0:01f31e923fe2 | 74 | |
| Pawel Zarembski |
0:01f31e923fe2 | 75 | This command will build all projects: |
| Pawel Zarembski |
0:01f31e923fe2 | 76 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 77 | $ tools/mbedcli_compile.py |
| Pawel Zarembski |
0:01f31e923fe2 | 78 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 79 | |
| Pawel Zarembski |
0:01f31e923fe2 | 80 | To build only a subset of projects, add the project name(s) to the end of the command line. Valid project names are listed |
| Pawel Zarembski |
0:01f31e923fe2 | 81 | in the usage text shown with `--help`. The first time you build after each pull you should add `--clean` to perform a |
| Pawel Zarembski |
0:01f31e923fe2 | 82 | complete re-build. |
| Pawel Zarembski |
0:01f31e923fe2 | 83 | |
| Pawel Zarembski |
0:01f31e923fe2 | 84 | ## Contribute |
| Pawel Zarembski |
0:01f31e923fe2 | 85 | We would love to have your changes! Pull requests should be made once a changeset is [rebased onto Master](https://www.atlassian.com/git/tutorials/merging-vs-rebasing/workflow-walkthrough). See the [contributing guide](../CONTRIBUTING.md) for detailed requirements and guidelines for contributions. |
| Pawel Zarembski |
0:01f31e923fe2 | 86 | |
| Pawel Zarembski |
0:01f31e923fe2 | 87 | ## Mbed-cli compile environment |
| Pawel Zarembski |
0:01f31e923fe2 | 88 | |
| Pawel Zarembski |
0:01f31e923fe2 | 89 | ### Features |
| Pawel Zarembski |
0:01f31e923fe2 | 90 | - Support both Python 2.x and 3.x versions. |
| Pawel Zarembski |
0:01f31e923fe2 | 91 | - Can compile a list of projects or the all of the projects. |
| Pawel Zarembski |
0:01f31e923fe2 | 92 | - Can generate the release directory with one command. |
| Pawel Zarembski |
0:01f31e923fe2 | 93 | |
| Pawel Zarembski |
0:01f31e923fe2 | 94 | ### Prerequisite |
| Pawel Zarembski |
0:01f31e923fe2 | 95 | mbed-cli is included in `requirements.txt`, so it will be installed automatically when configuring |
| Pawel Zarembski |
0:01f31e923fe2 | 96 | your development environment using the steps described above. |
| Pawel Zarembski |
0:01f31e923fe2 | 97 | |
| Pawel Zarembski |
0:01f31e923fe2 | 98 | ### `tools/mbedcli_compile.py` script |
| Pawel Zarembski |
0:01f31e923fe2 | 99 | Arguments |
| Pawel Zarembski |
0:01f31e923fe2 | 100 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 101 | positional arguments: |
| Pawel Zarembski |
0:01f31e923fe2 | 102 | projects Selectively compile only the firmware specified |
| Pawel Zarembski |
0:01f31e923fe2 | 103 | otherwise all projects |
| Pawel Zarembski |
0:01f31e923fe2 | 104 | |
| Pawel Zarembski |
0:01f31e923fe2 | 105 | optional arguments: |
| Pawel Zarembski |
0:01f31e923fe2 | 106 | -h, --help show this help message and exit |
| Pawel Zarembski |
0:01f31e923fe2 | 107 | --release Create a release with the yaml version file |
| Pawel Zarembski |
0:01f31e923fe2 | 108 | --build-folder BUILD_FOLDER |
| Pawel Zarembski |
0:01f31e923fe2 | 109 | Release directory to grab files from |
| Pawel Zarembski |
0:01f31e923fe2 | 110 | --release-folder RELEASE_FOLDER |
| Pawel Zarembski |
0:01f31e923fe2 | 111 | Directory to create and place files in |
| Pawel Zarembski |
0:01f31e923fe2 | 112 | --toolchain TOOLCHAIN |
| Pawel Zarembski |
0:01f31e923fe2 | 113 | Toolchain directory if present |
| Pawel Zarembski |
0:01f31e923fe2 | 114 | --clean Rebuild or delete build folder before compile |
| Pawel Zarembski |
0:01f31e923fe2 | 115 | -v Pass verbosity level to mbed compile -vv for more |
| Pawel Zarembski |
0:01f31e923fe2 | 116 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 117 | Valid projects are listed on help. |
| Pawel Zarembski |
0:01f31e923fe2 | 118 | |
| Pawel Zarembski |
0:01f31e923fe2 | 119 | Generate files needed by mbed-cli |
| Pawel Zarembski |
0:01f31e923fe2 | 120 | * `custom_profile.json` lists toolchain profile or compile flags parsed from the yaml files |
| Pawel Zarembski |
0:01f31e923fe2 | 121 | * `custom_targets.json` contains platform information for specific hics. |
| Pawel Zarembski |
0:01f31e923fe2 | 122 | * `.mbedignore` filters all files not needed for the project. |
| Pawel Zarembski |
0:01f31e923fe2 | 123 | |
| Pawel Zarembski |
0:01f31e923fe2 | 124 | ## Port |
| Pawel Zarembski |
0:01f31e923fe2 | 125 | There are three defined ways in which DAPLink can be extended. These are adding target support, adding board support and adding HIC support. Details on porting each of these can be found below. |
| Pawel Zarembski |
0:01f31e923fe2 | 126 | |
| Pawel Zarembski |
0:01f31e923fe2 | 127 | * [Adding a new target](PORT_TARGET_FAMILY.md) |
| Pawel Zarembski |
0:01f31e923fe2 | 128 | * [Adding a new board](PORT_BOARD.md) |
| Pawel Zarembski |
0:01f31e923fe2 | 129 | * [Adding a new HIC](PORT_HIC.md) |
| Pawel Zarembski |
0:01f31e923fe2 | 130 | |
| Pawel Zarembski |
0:01f31e923fe2 | 131 | |
| Pawel Zarembski |
0:01f31e923fe2 | 132 | ## Test |
| Pawel Zarembski |
0:01f31e923fe2 | 133 | DAPLink has an extensive set of automated tests written in Python. They are used for regression testing, but you can use them to validate your DAPLink port. Details are [here](AUTOMATED_TESTS.md) |
| Pawel Zarembski |
0:01f31e923fe2 | 134 | |
| Pawel Zarembski |
0:01f31e923fe2 | 135 | An option to search for the daplink firmware build in uvision and mbedcli build folders. |
| Pawel Zarembski |
0:01f31e923fe2 | 136 | `python test/run_test.py --projecttool mbedcli ...` or `python test/run_test.py --projecttool uvision ...`. |
| Pawel Zarembski |
0:01f31e923fe2 | 137 | |
| Pawel Zarembski |
0:01f31e923fe2 | 138 | ## Release |
| Pawel Zarembski |
0:01f31e923fe2 | 139 | |
| Pawel Zarembski |
0:01f31e923fe2 | 140 | ### Release using uvision |
| Pawel Zarembski |
0:01f31e923fe2 | 141 | |
| Pawel Zarembski |
0:01f31e923fe2 | 142 | DAPLink contains scripts to automate most of the steps of building a release. In addition to building the release, these scripts also save relevant build information such as git SHA and python tool versions so the same build can be reproduced. The recommended steps for creating a release are below. |
| Pawel Zarembski |
0:01f31e923fe2 | 143 | |
| Pawel Zarembski |
0:01f31e923fe2 | 144 | * Create a tag with the correct release version and push it to github |
| Pawel Zarembski |
0:01f31e923fe2 | 145 | * Clean the repo you will be building from by running 'git clean -xdf' followed by 'git reset --hard' |
| Pawel Zarembski |
0:01f31e923fe2 | 146 | * Run the script ``build_release_uvision.bat`` to create all builds. |
| Pawel Zarembski |
0:01f31e923fe2 | 147 | * All release deliverables will be created and stored in 'uvision_release'. Save this wherever your builds are stored. |
| Pawel Zarembski |
0:01f31e923fe2 | 148 | |
| Pawel Zarembski |
0:01f31e923fe2 | 149 | Note: A previous build can be reproduced by using the ``build_requirements.txt`` of that build. |
| Pawel Zarembski |
0:01f31e923fe2 | 150 | To do this add the additional argument ``build_requirements.txt`` when calling ``build_release_uvision.bat`` in step 2. |
| Pawel Zarembski |
0:01f31e923fe2 | 151 | This will install and build with the exact version of the python packages used to create that build. |
| Pawel Zarembski |
0:01f31e923fe2 | 152 | |
| Pawel Zarembski |
0:01f31e923fe2 | 153 | ### Release using mbedcli |
| Pawel Zarembski |
0:01f31e923fe2 | 154 | |
| Pawel Zarembski |
0:01f31e923fe2 | 155 | If the project list is not specify, all interface and booloader projects will be compiled. If `--release_version` is given, a folder (`firmware` on default or specified by `--release_folder`, to be concatenated with the version number), will be generated with the bin, update.yml and zip file containing the bins for release |
| Pawel Zarembski |
0:01f31e923fe2 | 156 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 157 | $ venv/Scripts/activate |
| Pawel Zarembski |
0:01f31e923fe2 | 158 | $ pip install -r requirements3.txt |
| Pawel Zarembski |
0:01f31e923fe2 | 159 | $ tools/mbedcli_compile.py --release_version 0250 --release_folder firmware |
| Pawel Zarembski |
0:01f31e923fe2 | 160 | ``` |
| Pawel Zarembski |
0:01f31e923fe2 | 161 | |
| Pawel Zarembski |
0:01f31e923fe2 | 162 | There is an intermediate step in uvision environment in creating a release directory. This step is not needed in mbedcli environment but to make this equivalent directory invoke |
| Pawel Zarembski |
0:01f31e923fe2 | 163 | `copy_release_files.py --project-tool mbedcli` |
| Pawel Zarembski |
0:01f31e923fe2 | 164 | To make a release directory from the step above. |
| Pawel Zarembski |
0:01f31e923fe2 | 165 | `package_release_files.py SRC_DIR DEST_DIR VERSION_NUMBER --toolchain ARM` |
| Pawel Zarembski |
0:01f31e923fe2 | 166 | |
| Pawel Zarembski |
0:01f31e923fe2 | 167 | ## MDK |
| Pawel Zarembski |
0:01f31e923fe2 | 168 | If you want to use the MDK (uVision) IDE to work with the DAPLink code, you must launch it in the right environment. The project will fail to build otherwise. To launch uVision properly, use ``tools/launch_uvision.bat`` |
| Pawel Zarembski |
0:01f31e923fe2 | 169 | |
| Pawel Zarembski |
0:01f31e923fe2 | 170 | This script can take arguments to override default virtual environment and python packages to be installed. For example `tools\launch_uvision.bat other_env other_requirements.txt` |