===== Building Cortex M@cortex_type@ Examples with MCUXpresso =====
This guide refers to the following hardware and software versions:
* @mod_name@ (@mcuexpresso_cpu_name@)
* MCUXpresso SDK @mcuexpresso_version@
* GCC ARM Embedded, @gcc_arm_version@
* Ubuntu 18.04 (Host System)
\\
==== Preparing Development Host ====
=== Host System Tools ===
The MCUXpresso SDK requires cmake to build binaries therefore it must be installed on your development host.
To install it on a Ubuntu based host execute the command below.
$ sudo apt-get install cmake
# Check the version >= 3.0.x
$ cmake --version
\\
===GCC Arm Embedded Toolchain===
The required toolchain version can be found in the SDK release notes (included as PDF):
SDK_@mcuexpresso_version_code@_@mcuexpresso_cpu_name@\docs\MCUXpresso SDK Release Notes for @nxp_evk_name@.pdf
\\
The toolchain must be downloaded from the [[https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads|ARMDeveloper website]].
This is the actual toolset (in other words, compiler, linker, and so on).\\ The GCC toolchain should be the latest supported version as described in the MCUXpresso SDK Release Notes.
\\
- Download the toolchain [[https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads|gcc-arm-none-eabi-@gcc_arm_version@-x86_64-linux.tar.bz2]]
- Unpack the toolchain archive in /opt/:
To write in /opt/ higher permissions are required!
tar xvjf gcc-arm-none-eabi-@gcc_arm_version@-x86_64-linux.tar.bz2 -C /opt/
\\
===MCUXpresso SDK===
The MCUXpresso Software Development Kit (MCUXpresso SDK) provides bare metal source code for execution on the Cortex M@cortex_type@.
Apply the steps below to install it.
The download of the SDK requires an account with NXP
- Visit [[https://mcuxpresso.nxp.com/en/select|MCUXpresso SDK Builder]]
- Select processor @mcuexpresso_cpu_name@
- Select the version @mcuexpresso_version@ in the right column and press the Build MCUXpresso SDK button.
- After "building" the SDK, download the ZIP archive via the **Download SDK** button
**SDK Setup**\\
\\
1. Unzip previously downloaded SDK archive, afterwards create and Enter new
$ mkdir @mcuexpresso_cpu_name@ && cd @mcuexpresso_cpu_name@
2. Copy downloaded SDK archive into the folder created before
$ cp path/to/downloaded/SDK-Archive ./
3. Unpack the SDK and delete the archive afterwards.
$ tar xvf SDK_@mcuexpresso_version_code@_@mcuexpresso_cpu_name@.tar.gz && rm SDK_@mcuexpresso_version_code@_@mcuexpresso_cpu_name@.tar.gz
4. Create GIT repository from current directory and create initial commit.
Creating a repository is mandatory for the build process with the demo makefile.
5. Create new git repository.
$ git init
6. Create new local branch.
$ git checkout -b v@cortexm_demo_branch@
6. Add .gitignore file
$ touch .gitignore
7. Exclude build results to prevent dirty builds.
$ echo "tqma8-cortexm-demos-v@mcuexpresso_version@-*" > .gitignore
8. Add all files to the repository.
$ git add -A
9. Create initial git commit.
$ git commit -m "initial commit"
10. Unpack and apply the TQM module-specific data in the MCUXpresso SDK root directory and remove the archive afterwards.
$ tar xvf @mod_name_code@-cortexm-demos-@cortex_m_demo_commit_id@.tar.gz
$ rm @mod_name_code@--cortexm-demos-@cortex_m_demo_commit_id@.tar.gz
11. Create a new commit after adding TQ customizations.
$ git add *
$ git commit -m "added support for specific tq-platform"
\\
==== Build demos and create archive ====
It is possible to build the applications manually. We recommend the use of the Makefile (make), because this creates an archive with the demos, which can be integrated into the BSP.
\\
\\
**Build Cortex M@cortex_type@ - Hello World Demo manually**
$ cd /path/to/@mcuexpresso_cpu_name@
$ . ./sdk_env_@mod_name_code@.sh
$ cd demo-apps/hello_world/armgcc/
$ ./build_release.sh
\\
**Build Cortex M@cortex_type@ - RPMSG PingPong Demo manually**
$ cd /path/to/@mcuexpresso_cpu_name@
$ . ./sdk_env_@mod_name_code@.sh
$ cd multicore_examples/rpmsg_lite_pingpong_rtos/linux_remote/armgcc/
$ ./build_release.sh
\\
**Build archive for BSP integration**\\
Navigate to SDK root path and build archive using the make command.
$ cd /path/to/@mcuexpresso_cpu_name@
$ make
\\
==== Build customized demos and create archive ====
The following example shows how to customize and rebuild the HelloWorld demo.
1. Change to the HelloWorld Demo folder in the SDK
$ cd path/to/sdk/boards/@mod_name_code@-@mb_name_code@/demo_apps/hello_world/
2. Open the file hello_world.c
$ nano hello_world.c
3. Change **//PRINTF("hello world.\r\n");//** to **//PRINTF("hello customer.\r\n");//** in line 44 and save the file finally.\\
\\
4. Change to the root path of the SDK and commit new changes
$ cd /path/to/@mcuexpresso_cpu_name@
$ git add boards//demo_apps/hello_world/hello_world.c
$ git commit -m "changed hello world string"
\\
After the adaption, a new commit must be created so that the new archive differs from the original one by the commit ID in the file name
e.g.
5. Build demo binaries and create archive for the BSP integration
Please check that there are no uncommited changes in your git repository. If so, please commit all your changes.
$ make
==== BSP Integration ====
The archive created above is brought into the BSP via the meta-tq layer. The inclusion of custom M@cortex_type@ binaries can be solved via a separate layer.
\\
1. Create new layer and create the appropriate folder structure.\\
2. Navigate to the BSP root (ci-meta-tq) directory
$ /ci-meta-tq
4. Initialise build environment.
$ . setup-environment
5. If not already existing, create a custom Yocto meta layer e.g. meta-custom.
$ bitbake-layers create-layer ../sources/meta-custom
6. Create the following path in the Yocto meta layer that should contain the customized demo recipe, in this case the meta-custom layer is used and navigate to it.
$ mkdir -p ../sources/meta-custom/recipes-bsp/tqma8-cortexm-demos
$ cd ../sources/meta-custom/recipes-bsp/tqma8-cortexm-demos
7. Create folder **tqma8-cortexm-demos** and store the demo archive created before
$ mkdir tqma8-cortexm-demos
$ cp /tqma8-cortexm-demos-v@mcuexpresso_version@-.tar.gz ./tqma8-cortexm-demos
Example archive name **tqma8-cortexm-demos-v@mcuexpresso_version@-gc32d0e2b7d**
\\
\\
8. Create a bbappend file to customize the original recipe without touch it.
$ nano tqma8-cortexm-demos_v@mcuexpresso_version@.bbappend
Add the following content to tqma8-cortexm-demos_v@mcuexpresso_version@.bbappend file.
The variable value of **SDK_TQ_REV** must match to the git commit id of the custom build tqma0-cortexm-demos archive.
e.g.
SDK_TQ_REV = "gc32d0e2b7d"
Content of tqma8-cortexm-demos_v@mcuexpresso_version@.bbappend:
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SDK_TQ_REV = ""
\\
==== Include own layer in the build-envirentment ====
The meta-custom layer must be added to the bblayers.conf file, otherwise the recipes in this layer will not be used for the build.
$ cd /path/to/ci-meta-tq/buildspace
$ echo 'BBLAYERS += "${BSPDIR}/sources/meta-custom"' >> conf/bblayers.conf
\\
==== Build image with new CortexM demos ====
1. Clear previous tqma8-cortexm-demos build results
bitbake -c cleansstate tqma8-cortexm-demos
2. Rebuild image e.g. tq-image-weston
$ bitbake tq-image-weston