Open-CMSIS-Packs: Crank Software Example

[#1]

GOAL

Learn how to import CMSIS packs into existing projects. In this particular project, CMSIS packs from Crank will be used alongside the freertos_hello example obtained from the MIMXRT1060-EVKB SDK.

Note: This walkthrough was adapted from Crank Software's guide included with their CMSIS Pack.

ENVIRONMENT

This guide requires MCUXpresso IDE v11.9.1 or latest. MIMXRT1060-EVK SDK version 2.16 or latest.

PROCEDURE

1. Import the freertos_hello example into the workspace. Be sure to set the library type to Newlib (semihost).

2. Rename the project to freertos_sbengine.

3. Add drivers to the project. Right click on the project and select SDK Management -> Manage SDK Components.

NOTE: Select Keep Existing and do not replace the FreeRTOSConfig.h file when prompted after adding the following components:

• Under Drivers -> Device -> SDK Drivers, select:

1. cache
2. elcdif
3. pxp

• Under Board Components -> Device -> SDK Drivers, select:

1. ft5406_rt

• Under Software Components -> Device -> SDK Drivers, select:

1. video-common

4. Add additional components to the project.

• Add the gt911 driver if required by your display. This driver can be found in the MIMXRT1060-EVKB SDK.

Navigate to components/gt911:

Copy the fsl_gt911.c and fsl_gt911.h into the touchpanel directory in the project:

• Change the memory manager configuration from the default used by FreeRTOS.

Remove the heap_4.c from the project folder. This is found in freertos/freertos-kernel/portable/MemMang.

Add the heap_3.c into the project folder freertos/FreeRTOS/portable/MemMang. This file can be found in the MIMXRT1060-EVKB SDK.

5. Download the Crank Software pack from Arm Keil | CMSIS Packs.

6. Import the Crank Software pack into MCUXpresso IDE.

7. The Crank Software pack is a graphics bundle that contains six components:

1. Board
2. Display
3. Memory
4. Runtime Libraries
5. Runtime Source
6. Task

For this walkthrough, we will add all the components except the Runtime Source component. This component is intended for custom changes.

To add the components, right click on the project and select SDK Management -> Add Open-CMSIS Components:

Once the components are selected press Ctrl + s to save the components in the project.

8. Resolve conflicts from the previous freertos_hello project configuration.

• The Board component from the Crank Software pack includes a rewrite of pin_mux.c. Navigate to the board directory of the project and remove the pin_mux.c and pin_mux.h files.

• MCUXPresso will automatically add the libraries from the runtime engine into the linker settings. In the project settings remove all the Storyboard engine libraries and plugins.

To do this, right click on the project and select Properties. Remove all of the items found under C/C++ Build -> Settings -> Miscellaneous -> Other Objects.

• Switch from a managed linker configuration to using the linker file included in the CMSIS pack. In the project settings, navigate to the MCU Linker -> Managed Linker Script. Uncheck the Manage Linker Script option and change the Linker script and Script path.

Linker script = MIMXRT1062xxxxx_flexspi_nor.ld

Script path=
${cmsis_pack_root}/CrankSoftware/iMXRT10xx/8.1.0/configuration/rt1060/

Note: The path will vary depending on where the user saved the pack.

• Copy sbengine_task_pxp_template.c and sbengine_plugins_template.h from the RTE -> Graphics folder into the source folder of the project. Rename these files to remove template  from the name.

The project source folder should now look like this:

• Exclude the sbengine_task_pxp_template.c and sbengine_plugins_template.h files in the RTE -> Graphics folder from the build. 

9. Configure and export a Model C/C++ Header from Storyboard Designer. Create a new project and name it sbengine_model.

• For this example, I will use a display size of 480x272, color depth RGB 565, and Freetype font manager.

• Once the model has been exported, add the header file to the source directory of the project.

Note: For more information about exporting models from Storyboard Designer visit:

Crank Storyboard - Exporting and Running on your Embedded Target.

10. Integrating the Storyboard Engine requires modifications to the following:

• FreeRTOSConfig.h file

Locate this file in the source folder of the project and make the following changes:

#define configFRTOS_MEMORY_SCHEME 4
#define configUSE_TIME_SLICING 0
#define configENABLE_BACKWARD_COMPATIBILITY 0
#define configTICK_RATE_HZ ((TickType_t)200)
#define configUSE_NEWLIB_REENTRANT 0

To this:
#define configFRTOS_MEMORY_SCHEME 3
#define configUSE_TIME_SLICING 1
#define configENABLE_BACKWARD_COMPATIBILITY 1
#define configTICK_RATE_HZ ((TickType_t)1000)
#define configUSE_NEWLIB_REENTRANT 1

• Preprocessor Defines

Right click on the project and select Properties -> C/C++ Build -> Settings -> MCU C Compiler. Add the following defines to the “Defined symbols (-D)” pane:

SKIP_SYSCLK_INIT
XIP_BOOT_HEADER_DCD_ENABLE=1
GRE_TARGET_OS_freertos
GRE_TARGET_CPU_cortexm7
GRE_TARGET_TOOLCHAIN_mcuxpresso
GRE_FEATURE_VFS_RESOURCES

Change the SDK_DEBUGCONSOLE define from:

SDK_DEBUGCONSOLE=0

to

SDK_DEBUGCONSOLE=1

If you are using the gt911 touch driver, you will also need to add the following preprocessor define:
SDK_I2C_BASED_COMPONENT_USED=1

• Library paths.

Right click on the project and select Properties -> C/C++ Build -> Settings -> MCU Linker -> Libraries.

1. In the Library Search path (-L) pane add:

   "${cmsis_pack_root}/CrankSoftware/iMXRT10xx/8.1.0/storyboard/runtime/freertos-mcuxpresso-cortexm7-swrender-DFP-obj/lib"

   "${cmsis_pack_root}/CrankSoftware/iMXRT10xx/8.1.0/storyboard/runtime/freertos-mcuxpresso-cortexm7-swrender-DFP-obj/plugins”

   Note: The path will vary depending on where the user saved the pack.

2. This guide uses the complete configuration of the engine. Therefore, all of the following libraries need to be added in the Libraries pane (-l). 

gre
greal
sbimage
sbvfs
gre-plugin-animation
gre-plugin-lua
gre-plugin-poly
gre-plugin-circle

gre-plugin-timer
gre-plugin-logger
gre-plugin-screen-path
gre-plugin-greio
gre-plugin-sbimage-soil
gre-plugin-fio_vfs
render-plugin-swrender
logging-util
greio
sblua
soil
swrmgr
swrender

font-plugin-freetype
sbfreetype
sbpng
sbz

Note: The library order matters. Add the libraries in the order listed above and click Apply and Close

11. Recall that this project was originally the freertos_hello example from the SDK. Therefore, modifications need to be made to the freertos_hello.c file to support the changes for this application.

• Ensure that the following headers are included:

#include "board.h"
#include "peripherals.h"

• The define for the hello_task_priority is no longer needed and can be removed. 

• Place the following definitions outside of the main function:

void sbengine_main_task(void *argument);

void sbengine_input_task(void *argument);

• Add the following two additional functions to the initialization sequence in the main() function:

BOARD_InitSemcPins()

BOARD_InitBootPeripherals().

• Replace the hello_task code:

if (xTaskCreate(hello_task, "Hello_task", configMINIMAL_STACK_SIZE + 10,
NULL, hello_task_PRIORITY, NULL) != pdPASS)

with:

if (xTaskCreate(sbengine_main_task, "sbengine", 8192, NULL,
configMAX_PRIORITIES / 2, NULL) != pdPASS)

• Add the Storyboard Input handling task creation code block before the call to VTaskStartScheduler:

if (xTaskCreate(sbengine_input_task, "StoryboardInput", 2048, NULL,
configMAX_PRIORITIES / 2, NULL) != pdPASS)
{
PRINTF("Task creation failed!.\r\n");
while (1);
}

The source code should now look like this:

/* FreeRTOS kernel includes. */

#include "FreeRTOS.h"

#include "task.h"

#include "queue.h"

#include "timers.h"

/* Freescale includes. */

#include "fsl_device_registers.h"

#include "fsl_debug_console.h"

#include "pin_mux.h"

#include "clock_config.h"

#include "board.h"

#include "peripherals.h"

/*******************************************************************************

* Definitions

******************************************************************************/

void sbengine_main_task(void *argument);

void sbengine_input_task(void *argument);

/*******************************************************************************

* Code

******************************************************************************/

/*!

* @brief Application entry point.

*/

int main(void)

{

/* Init board hardware. */

BOARD_ConfigMPU();

BOARD_InitBootPins();

BOARD_InitSemcPins();

BOARD_InitBootPeripherals();

BOARD_InitBootClocks();

BOARD_InitDebugConsole();

if (xTaskCreate(sbengine_main_task, "sbengine", 8192, NULL,

configMAX_PRIORITIES / 2, NULL) != pdPASS)

{

PRINTF("Task creation failed!.\r\n");

while (1)

;

}

if(xTaskCreate(sbengine_input_task, "StoryboardInput", 2048, NULL, configMAX_PRIORITIES / 2, NULL) != pdPASS)

{

PRINTF("Task creation failed!.\r\n");

while(1);

}

vTaskStartScheduler();

for (;;)

;

}

NOTE: Check that the line: #include sbengine_model.h in the sbengine_task_pxp.c  file matches the name of the exported header file from Storyboard.

The project should now build: