Embedded module TQMa8x - YOCTO Linux BSP documentation

This guide refers to the following hardware and software versions:

• TQMa8x (MCUEXPRESSO_CPU_NAME)
• MCUXpresso SDK MCUEXPRESSO_VERSION
• GCC ARM Embedded, GCC_ARM_VERSION
• Ubuntu 18.04 (Host System)

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

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 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.

1. Download the toolchain gcc-arm-none-eabi-<label gcc_arm_version>GCC_ARM_VERSION</label>-x86_64-linux.tar.bz2
2. Unpack the toolchain archive in /opt/:

tar xvjf gcc-arm-none-eabi-<label gcc_arm_version>GCC_ARM_VERSION</label>-x86_64-linux.tar.bz2 /opt/

The MCUXpresso Software Development Kit (MCUXpresso SDK) provides bare metal source code for execution on the Cortex M4. Apply the steps below to install it.

1. Visit MCUXpresso SDK Builder
2. Select processor MCUEXPRESSO_CPU_NAME
3. Select the version MCUEXPRESSO_VERSION in the right column and press the Build MCUXpresso SDK button.
4. 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 <label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label> && cd <label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>

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_<label mcuexpresso_version_code>MCUEXPRESSO_VERSION_CODE</label>_<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>.tar.gz && rm SDK_<label mcuexpresso_version_code>MCUEXPRESSO_VERSION_CODE</label>_<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>.tar.gz

4. Create GIT repository from current directory and create initial commit.

5. Create new git repository.

$ git init

6. Create new local branch.

$ git checkout -b v<label cortexm_demo_branch>CORTEXM_DEMO_BRANCH</label>

6. Add .gitignore file

$ touch .gitignore

7. Exclude build results to prevent dirty builds.

$ echo "tqma8-cortexm-demos-v<label mcuexpresso_version>MCUEXPRESSO_VERSION</label>-*" > .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 tqma8x-cortexm-demos-<label cortex_m_demo_commit_id>CORTEX_M_DEMO_COMMIT</label>.tar.gz
$ rm  tqma8x--cortexm-demos-<label cortex_m_demo_commit_id>CORTEX_M_DEMO_COMMIT</label>.tar.gz

11. Create a new commit after adding TQ customizations.

$ git add *
$ git commit -m "added support for specific tq-platform"

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 M4 - Hello World Demo manually

$ cd /path/to/<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>
$ . ./sdk_env_tqma8x.sh 
$ cd demo-apps/hello_world/armgcc/
$ ./build_release.sh

Build Cortex M4 - RPMSG PingPong Demo manually

$ cd /path/to/<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>
$ . ./sdk_env_tqma8x.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/<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>
$ make

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/tqma8x-mba8x/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/<label mcuexpresso_cpu_name>MCUEXPRESSO_CPU_NAME</label>
$ git add boards/<platform>/demo_apps/hello_world/hello_world.c
$ git commit -m "changed hello world string"

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

The archive created above is brought into the BSP via the meta-tq layer. The inclusion of custom M4 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

$ <cd path/to>/ci-meta-tq

4. Initialise build environment.

$ . setup-environment <buildspace>

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 </path/to/archive>/tqma8-cortexm-demos-v<label mcuexpresso_version>MCUEXPRESSO</label>-<COMMIT-ID>.tar.gz ./tqma8-cortexm-demos

Example archive name tqma8-cortexm-demos-vMCUEXPRESSO-gc32d0e2b7d

8. Create a bbappend file to customize the original recipe without touch it.

$ nano tqma8-cortexm-demos_v<label mcuexpresso_version>MCUEXPRESSO_VERSION</label>.bbappend

Add the following content to tqma8-cortexm-demos_vMCUEXPRESSO_VERSION.bbappend file.

Content of tqma8-cortexm-demos_vMCUEXPRESSO_VERSION.bbappend:

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SDK_TQ_REV = "<COMMIT-ID>"

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

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

This guide refers to the following hardware and software versions:

• TQMa8x (MIMX8QM6xxxFF)
• MCUXpresso SDK 2.9.0
• GCC ARM Embedded, 9-2020-q2-update
• Ubuntu 18.04 (Host System)

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

The required toolchain version can be found in the SDK release notes (included as PDF): SDK_2_9_0_MIMX8QM6xxxFF\docs\MCUXpresso SDK Release Notes for EVK-MIMX8MP.pdf
The toolchain must be downloaded from the 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.

1. Download the toolchain gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2
2. Unpack the toolchain archive in /opt/:

tar xvjf gcc-arm-none-eabi-9-2020-q2-update-x86_64-linux.tar.bz2 /opt/

The MCUXpresso Software Development Kit (MCUXpresso SDK) provides bare metal source code for execution on the Cortex M4. Apply the steps below to install it.

1. Visit MCUXpresso SDK Builder
2. Select processor MIMX8QM6xxxFF
3. Select the version 2.9.0 in the right column and press the Build MCUXpresso SDK button.
4. 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 MIMX8QM6xxxFF && cd MIMX8QM6xxxFF

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_2_9_0_MIMX8QM6xxxFF.tar.gz && rm SDK_2_9_0_MIMX8QM6xxxFF.tar.gz

4. Create GIT repository from current directory and create initial commit.

5. Create new git repository.

$ git init

6. Create new local branch.

$ git checkout -b v2.9.x

6. Add .gitignore file

$ touch .gitignore

7. Exclude build results to prevent dirty builds.

$ echo "tqma8-cortexm-demos-v2.9.0-*" > .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 tqma8x-cortexm-demos-4eb071e7.tar.gz
$ rm  tqma8x--cortexm-demos-4eb071e7.tar.gz

11. Create a new commit after adding TQ customizations.

$ git add *
$ git commit -m "added support for specific tq-platform"

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 M4 - Hello World Demo manually

$ cd /path/to/MIMX8QM6xxxFF
$ . ./sdk_env_tqma8x.sh 
$ cd demo-apps/hello_world/armgcc/
$ ./build_release.sh

Build Cortex M4 - RPMSG PingPong Demo manually

$ cd /path/to/MIMX8QM6xxxFF
$ . ./sdk_env_tqma8x.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/MIMX8QM6xxxFF
$ make

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/tqma8x-mba8x/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/MIMX8QM6xxxFF
$ git add boards/<platform>/demo_apps/hello_world/hello_world.c
$ git commit -m "changed hello world string"

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

The archive created above is brought into the BSP via the meta-tq layer. The inclusion of custom M4 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

$ <cd path/to>/ci-meta-tq

4. Initialise build environment.

$ . setup-environment <buildspace>

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 </path/to/archive>/tqma8-cortexm-demos-v2.9.0-<COMMIT-ID>.tar.gz ./tqma8-cortexm-demos

Example archive name tqma8-cortexm-demos-v2.9.0-gc32d0e2b7d

8. Create a bbappend file to customize the original recipe without touch it.

$ nano tqma8-cortexm-demos_v2.9.0.bbappend

Add the following content to tqma8-cortexm-demos_v2.9.0.bbappend file.

Content of tqma8-cortexm-demos_v2.9.0.bbappend:

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SDK_TQ_REV = "<COMMIT-ID>"

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

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