View source for Transclusion: FreeRTOS: Introduction to NXP FreeRTOS development

== Overview ==
The FreeRTOS operating system is designed to be compact and task specific. As such, instead of the popular kernel/driver/filesystem/userspace division used by general purpose operating systems, FreeRTOS is just one binary that contains an application and all the relevant kernel code that is necessary to support it. This includes startup code, code that accesses SoC subsystems (drivers), as well as standard kernel functionality such as multitasking, which allows the single-application-per-image model to spawn multiple tasks. In addition to this standard functionality, middleware libraries can be added to the core OS to augment its functionality. For example, the CL-SOM-iMX7 FreeRTOS BSP is augmented with the Open-AMP software stack, which allows the M4 and A7 cores to communicate.

== Project architecture ==
FreeRTOS consists of multiple modular parts:
{| cellpadding="3" border="1" style="border: 1px solid rgb(85, 85, 85); border-collapse: collapse;"
|-
! Unit
! Description
! Location
|-
| kernel
| FreeRTOS kernel
| rtos/FreeRTOS/Source
|-
| CMSIS headers and libraries
| Cortex-M specific support
| platform/CMSIS
|-
| SOC specific definitions
| This BSP only has MCIMX7D definitions
| platform/devices
|-
| Drivers
| All the drivers in the FreeRTOS BSP are stateless
| platform/drivers
|-
| Middleware libraries
| Open-AMP stack, including RPmsg support
| middleware/multicore/open-amp
|-
| Additional utilities
| Contains some printing functions
| platform/utilities
|-
| App code
| Application code and project files
| examples/cl-som-imx7
|}

For development, the focal point is the apps projects, which pick and choose the various pieces of FreeRTOS and combine them with the app code into a single project. A good starting point is to pick an example project and start adding functionality.

== FreeRTOS API reference ==
The CL-SOM-iMX7 FreeRTOS BSP is based on the NXP FreeRTOS BSP. The NXP BSP has some useful documents in the BSP archive, one of which provides a comprehensive documentation of FreeRTOS API. The NXP BSP can be downloaded [http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/i.mx-applications-processors/i.mx-7-processors/i.mx-7dual-processors-heterogeneous-processing-with-dual-arm-cortex-a7-cores-and-cortex-m4-core:i.MX7D?tab=Design_Tools_Tab here] in the Board Support Packages section.

== Multicore development and coexisting with Linux ==
Since Cortex-A7 and Cortex-M4 share both memory and peripherals, it is necessary to isolate or synchronize between these cores to prevent them from interfering with one another. The RDC (Resource Domain Controller) subsystem of iMX7 provides ways to implement this isolation/synchronization on the hardware level, and RDC support is part of the FreeRTOS API. Nevertheless, the general purpose OS that runs on the Cortex-A7 may not be prepared to handle the possibility that a bus or subsystem may be locked from it, or concurrently used by somebody else, and so disabling functionality on the Cortex-A7 OS may be necessary. In the case of Linux, a special device tree can be used to tell Linux not to touch iMX7 subsystems that we expect to be used by FreeRTOS. Such a device tree is provided in the CL-SOM-iMX7 FreeRTOS BSP.

== Building FreeRTOS ==
=== Setup development tools ===
For FreeRTOS development it is possible to use either the [https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads GNU ARM Embedded toolchain], or the [https://developer.arm.com/products/software-development-tools/ds-5-development-studio/downloads ARM DS5 IDE] suite. The FreeRTOS BSP has build scripts/project files for both tools.
==== GNU ARM Embedded toolchain ====
* Create a directory for downloading.
<blockquote><pre>mkdir -p ~/toolchain</pre></blockquote>
* Download the [https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads GNU ARM Embedded toolchain] to the toolchain directory.
* Extract the toolchain archive:
<blockquote><pre>
cd ~/toolchain
tar xvf gcc-arm-none-eabi-6-2017-q1-update-linux.tar.bz2
</pre></blockquote>
* Let the host system know where the toolchain is located
<blockquote><pre>export ARMGCC_DIR=~/toolchain</pre></blockquote>

==== ARM DS5 IDE ====
* Create a directory for downloading.
<blockquote><pre>mkdir -p ~/toolchain</pre></blockquote>
* Download [https://developer.arm.com/products/software-development-tools/ds-5-development-studio/downloads ARM DS5 IDE] to the toolchain directory.
* Extract the downloaded archive:
<blockquote><pre>
cd ~/toolchain
tar xvf DS500-BN-00019-r5p0-27rel1.tgz
</pre></blockquote>
* Run the installation script and follow the instructions
<blockquote><pre>./install.sh</pre></blockquote>

=== Getting FreeRTOS BSP sources ===
* Create a directory for development.
<blockquote><pre>mkdir -p ~/development</pre></blockquote>
* [[#See also|Download]] the FreeRTOS BSP to the development directory.
* Extract the FreeRTOS BSP archive:
<blockquote><pre>
cd ~/development
unzip cl-som-imx7_freertos.zip
</pre></blockquote>
* Extract the BSP source archive inside the BSP package:
<blockquote><pre>
cd cl-som-imx7-freertos/freertos
tar xvf freertos.tar.bz2
</pre></blockquote>

=== Building FreeRTOS ===
In this example we will use the {{cmd|hello_world}} demo project as reference.
==== Invoking build ====
===== GNU ARM Embedded toolchain =====
* Go to the {{filename|armgcc}} folder inside the {{filename|hello_world}} project directory
<blockquote><pre>cd ~/development/cl-som-imx7-freertos/freertos/freertos_source/examples/cl_som_imx7_m4/demo_apps/hello_world/armgcc</pre></blockquote>
* Run the build script for either of build configurations:
** For Debug configuration:<pre>./build_debug.sh</pre>
** For Release configuration:<pre>./build_release.sh</pre>
** For Both (debug and release) configurations:<pre>./build_all.sh</pre>

===== ARM DS5 IDE =====
* Open DS5 IDE
* Go to File->Import
* Select General->Existing Projects into Workspace
* Click Browse and go to {{filename|~/development/cl-som-imx7-freertos/freertos/freertos_source/examples/cl_som_imx7_m4/demo_apps/hello_world/armgcc}} and click OK
* Click Finish

Now you can right click on the project and select the build option.

=== Image location ===
Depending on the tool used, and the selected build target, the built binary will reside in {{filename|~/development/cl-som-imx7-freertos/freertos/freertos_source/examples/cl_som_imx7_m4/demo_apps/hello_world/{armgcc,ds5}/{debug,release}/hello_world.bin}}.