Hi Andy,

Micrium OS, including its network stack, is now free to use on Silicon Labs hardware.

In order to have access, you will need to have your development kit registered.

Regards,

Janos

Hi Andy,

Micrium OS, including its network stack, is now free to use on Silicon Labs hardware.

In order to have access, you will need to have your development kit registered.

Regards,

Janos

If you are running in a multi-threaded environment in which you have more than one task making use of a peripheral driver such as USART, SPI, I2C, etc., you should consider making it thread-safe.

The Micrium OS kernel offers a variety of services designed to protect shared resources. In our case, let’s make use of the Mutual Exclusion Semaphore also known as mutex. Why a mutex? Because we want our resource (peripheral driver) to be accessed only by one task at a time. Regular semaphores present a vulnerability with priority-inversion. Mutexes, on the other hand, are implemented in a way that priority inversions are prevented by using priority inheritance.

For this exercise, you will be editing files from the Gecko SDK, which is not recommended therefore do this with caution.

In the peripheral driver file that you want to protect, include the following file:

#include  <kernel/include/os.h>

Now we have to declare a global variable for our mutex, for example, if you want to protect the SPI you could declare it as follows:

OS_MUTEX  SPI_Mutex;

With the mutex now declared, you need to invoke the kernel call to create it. My recommendation is to make this in the initialization function of the peripheral driver that you are using. You create the mutex by calling:

OSMutexCreate(&SPI_Mutex, “SPI Mutex”, &err);

Notice how the function requires an error argument, just declare RTOS_ERR  err locally and pass it on.

Always make sure to check the error returned, if it’s not RTOS_ERR_NONE then something went wrong.

The mutex is now created and registered with the kernel. Now you will need to wrap around the driver calls that your application is using with:

void foo () {

  RTOS_ERR  err;

  OSMutexPend(&SPI_Mutex,            /* Pointer to the mutex */
               0,                    /* No timeout */
               OS_OPT_PEND_BLOCKING, /* Block if not available */
               DEF_NULL,             /*Timestamp not used */
              &err);

  if (err.Code != RTOS_ERR_NONE) {
      /* handle error */
  }

  /* peripheral driver function code */
  ...
  ...
  ...

  OSMutexPost(&SPI_Mutex,
               OS_OPT_POST_NONE,
              &err);

  if (err.Code != RTOS_ERR_NONE) {
      /* handle error */
  }
}

Please make sure to check the returned errors. A common one is RTOS_ERR_NOT_READY, this happens when the pend or post calls are made before the kernel is in its running state (after the call to OSStart()).

If the driver initialization function can potentially be called multiple times from more than one task, my recommendation is to also protect it.

With this setup, you can be sure that your peripheral is only being accessed by one task at a time.

Beware also that some drivers have abort functions, you have to be careful with this and not lock your system on a mutex pend. For more information on how to protect a resource using Micrium OS please visit https://doc.micrium.com/display/OSUM50600/Resource+Management+Using+the+Kernel

If you are running in a multi-threaded environment in which you have more than one task making use of a peripheral driver such as USART, SPI, I2C, etc., you should consider making it thread-safe.

The Micrium OS kernel offers a variety of services designed to protect shared resources. In our case, let’s make use of the Mutual Exclusion Semaphore also known as mutex. Why a mutex? Because we want our resource (peripheral driver) to be accessed only by one task at a time. Regular semaphores present a vulnerability with priority-inversion. Mutexes, on the other hand, are implemented in a way that priority inversions are prevented by using priority inheritance.

For this exercise, you will be editing files from the Gecko SDK, which is not recommended therefore do this with caution.

In the peripheral driver file that you want to protect, include the following file:

#include  <kernel/include/os.h>

Now we have to declare a global variable for our mutex, for example, if you want to protect the SPI you could declare it as follows:

OS_MUTEX  SPI_Mutex;

With the mutex now declared, you need to invoke the kernel call to create it. My recommendation is to make this in the initialization function of the peripheral driver that you are using. You create the mutex by calling:

OSMutexCreate(&SPI_Mutex, “SPI Mutex”, &err);

Notice how the function requires an error argument, just declare RTOS_ERR  err locally and pass it on.

Always make sure to check the error returned, if it’s not RTOS_ERR_NONE then something went wrong.

The mutex is now created and registered with the kernel. Now you will need to wrap around the driver calls that your application is using with:

void foo () {

  RTOS_ERR  err;

  OSMutexPend(&SPI_Mutex,            /* Pointer to the mutex */
               0,                    /* No timeout */
               OS_OPT_PEND_BLOCKING, /* Block if not available */
               DEF_NULL,             /*Timestamp not used */
              &err);

  if (err.Code != RTOS_ERR_NONE) {
      /* handle error */
  }

  /* peripheral driver function code */
  ...
  ...
  ...

  OSMutexPost(&SPI_Mutex,
               OS_OPT_POST_NONE,
              &err);

  if (err.Code != RTOS_ERR_NONE) {
      /* handle error */
  }
}

Please make sure to check the returned errors. A common one is RTOS_ERR_NOT_READY, this happens when the pend or post calls are made before the kernel is in its running state (after the call to OSStart()).

If the driver initialization function can potentially be called multiple times from more than one task, my recommendation is to also protect it.

With this setup, you can be sure that your peripheral is only being accessed by one task at a time.

Beware also that some drivers have abort functions, you have to be careful with this and not lock your system on a mutex pend. For more information on how to protect a resource using Micrium OS please visit https://doc.micrium.com/display/OSUM50600/Resource+Management+Using+the+Kernel

The example is also in 2.5, it's found in:

C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\app\mcu_example\SLSTK3701A_EFM32GG11\micriumos_dynamic

Hi vimalzxc,

You could take a look at the dynamic tick example in:

C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.6\app\mcu_example\SLSTK3701A_EFM32GG11\micriumos_dynamic

That'll show you how to put the MCU in sleep mode with Micrium OS.

Regards,

Janos

Hi Michel,

When you went through the instructions in https://www.silabs.com/community/blog.entry.html/2018/06/08/adding_micrium_oson-06qC, did you make sure your "micrium_os" folder looks exactly as it is listed in Figure 8? Take a closer look at the ports folder since I suspect you might be including more than you need. Also, make sure your file "rtos_description.h" matches with the one in the instructions too.

Regards,

Janos

This blog should serve as a guide to adding Micrium OS on a Flex Gecko and get at least one task running on the device.

I will now share with you my experience while going through this exercise.

Getting Started

I decided to perform a clean installation of Simplicity Studio in order to avoid conflicts inflicted by software updates over time. After installing the tool, before even attempting to add anything, I first had to make sure that I had the necessary SDKs. Here's what I installed:

• 32-bit MCU SDK - 5.7.0
• Micrium OS - 5.6.0
• Flex SDK - 2.5.0.0

I then mounted a Flex Gecko, EFR32FG12 in my case, onto a Wireless Started Kit Mainboard (BRD4001A). After that, I connected it to the PC using the provided USB cable.

Simplicity Studio recognized a Flex Gecko connected to a WSTK and displayed the link to examples from the Flex SDK (see Figure 1).

Loading a Basic Flex SDK Example

As a starting point, I decided to go with the "RAIL: Simple RAIL without HAL" example from the Flex SDK.

You can find this by expanding the list of projects under the "Silicon Labs Flex SDK Examples" link:

Then find and click the example shown in Figure 3 to add it to your workspace:

After the example loads on your workspace, you might get a notice as shown in Figure 4. Just click "OK".

You will then be presented with simple_rail_without_hal.isc opened where you can configure RAIL. In my case, I left everything in its default values and simply clicked on "Generate" as shown in Figure 5.

At this point, you should now be set with a basic Flex Gecko example that builds and runs. However, I did find that the default project settings have compiler optimization set to "Optimize for size (-Os)" which will eventually make debugging the project rather difficult. Therefore, I switched optimizations to "None (-O0)".

Adding Micrium OS to the Workspace

Now that you have a basic Flex Gecko example that builds and runs, let's go ahead and start adding the Micrium OS source files into the workspace.

First, locate the Micrium OS directory, it should be in:

C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.5\platform\micrium_os

Now drag and drop the "micrium_os" folder into your project (simple_rail_without_hal) in Simplicity Studio. When doing this, make sure that you have "Copy files and folders" selected before clicking "OK" as shown in Figure 7.

You will then have to remove all the unnecessary files that get added with Micrium OS (this was tedious).

Here's how your "micrium_os" folder should end up looking:

Finally, the compiler needs to know where to look for the header files so we have to add two compiler include paths to the project settings:

"${workspace_loc:/${ProjName}/micrium_os}"
"${workspace_loc:/${ProjName}/micrium_os/cfg}"

Configuring Micrium OS

Now that you have Micrium OS as part of your project, let's go ahead and make some minor adjustments to the default Micrium OS configuration.

1. Open rtos_description.h located in your project under "micrium_os/cfg/"
2. Replace the contents of the file with one below:

/***************************************************************************//**
 * @file
 * @brief RTOS Description - Configuration Template File
 *******************************************************************************
 * # License
 * <b>Copyright 2018 Silicon Laboratories Inc. www.silabs.com</b>
 *******************************************************************************
 *
 * The licensor of this software is Silicon Laboratories Inc.  Your use of this
 * software is governed by the terms of Silicon Labs Master Software License
 * Agreement (MSLA) available at
 * www.silabs.com/about-us/legal/master-software-license-agreement.  This
 * software is distributed to you in Source Code format and is governed by the
 * sections of the MSLA applicable to Source Code.
 *
 ******************************************************************************/

/********************************************************************************************************
 ********************************************************************************************************
 *                                               MODULE
 ********************************************************************************************************
 *******************************************************************************************************/

#ifndef  _RTOS_DESCRIPTION_H_
#define  _RTOS_DESCRIPTION_H_

/********************************************************************************************************
 ********************************************************************************************************
 *                                             INCLUDE FILES
 ********************************************************************************************************
 *******************************************************************************************************/

#include  <common/include/rtos_opt_def.h>

/********************************************************************************************************
 ********************************************************************************************************
 *                                       ENVIRONMENT DESCRIPTION
 ********************************************************************************************************
 *******************************************************************************************************/

#define  RTOS_CPU_SEL                                       RTOS_CPU_SEL_ARM_V7_M

#define  RTOS_TOOLCHAIN_SEL                                 RTOS_TOOLCHAIN_GNU

#define  RTOS_INT_CONTROLLER_SEL                            RTOS_INT_CONTROLLER_ARMV7_M

/********************************************************************************************************
 ********************************************************************************************************
 *                                       RTOS MODULES DESCRIPTION
 ********************************************************************************************************
 *******************************************************************************************************/

//                                                                 ---------------------- KERNEL ----------------------
#define  RTOS_MODULE_KERNEL_AVAIL


/********************************************************************************************************
 ********************************************************************************************************
 *                                             MODULE END
 ********************************************************************************************************
 *******************************************************************************************************/

#endif // End of rtos_description.h module include.

Modifying main.c

We'll be making modifications to the default main.c generated by the "RAIL: Simple RAIL without HAL" example.

Micrium OS requires the following include paths in main.c so go ahead and add them as shown below:

#include  <cpu/include/cpu.h>
#include  <kernel/include/os.h>
#include  <common/include/common.h>
#include  <common/include/rtos_utils.h>
#include  <common/source/kal/kal_priv.h>  /* Private file, use should be limited */

We'll be modifying main.c to initialize Micrium OS and create a start task. For that, you'll need to specify a task stack size and a priority. We typically do this by defining them as constants and passing those in the call to OSTaskCreate().

The start task also requires its own Stack and Task Control Block (OS_TCB) as well as its function prototype. Therefore, add the following to main.c:

#define  START_TASK_PRIO              21u
#define  START_TASK_STK_SIZE         512u
                                                                
static  CPU_STK  StartTaskStk[START_TASK_STK_SIZE];  /* Start Task Stack. */
static  OS_TCB   StartTaskTCB;                       /* Start Task TCB.   */

static  void  StartTask (void  *p_arg);

Here's the body of the StartTask function where the kernel tick gets initialize and as well as the Common module. Note that the function includes an infinite loop at the end with a time delay of 1 second. This is done to yield CPU time to other tasks that are or will eventually run on your system. You can copy and paste the following in your main.c:

static  void  StartTask (void  *p_arg)
{
  RTOS_ERR    err;
  CPU_INT32U  cpu_freq;
  CPU_INT32U  cnts;

  // Prevent compiler warning.
  PP_UNUSED_PARAM(p_arg);                                     

  // Determine SysTick reference freq.
  cpu_freq =  SystemCoreClockGet();
  // Cal. SysTick counts between two OS tick interrupts.
  cnts     = (cpu_freq / (CPU_INT32U)KAL_TickRateGet());

  // Init uC/OS periodic time src (SysTick).
  OS_CPU_SysTickInit(cnts);

#if (OS_CFG_STAT_TASK_EN == DEF_ENABLED)
  // Initialize CPU Usage.
  OSStatTaskCPUUsageInit(&err);
  // Check error code.
  APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), ;);
#endif

#ifdef CPU_CFG_INT_DIS_MEAS_EN
  // Initialize interrupts disabled measurement.
  CPU_IntDisMeasMaxCurReset();
#endif

  // Call common module initialization example.
  Common_Init(&err);
  APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);

  while (DEF_ON) {
	  // Delay Start Task execution for 1000 OS Ticks from now.
      OSTimeDly(1000, OS_OPT_TIME_DLY, &err);
      // Check error code.
      APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), ;);
  }
}

Let's now modify main() to initialize the CPU, the kernel create the Start Task, and start the OS. Here's how main() should end up looking:

int main(void)
{
  RTOS_ERR  err;

  CHIP_Init();
  initRadio();

  CPU_Init();

  // Initialize the Kernel.
  OSInit(&err);
  // Check error code.
  APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), 1);

  // Create the Start Task.
  OSTaskCreate(&StartTaskTCB,
               "Start Task",
                StartTask,
                DEF_NULL,
                START_TASK_PRIO,
               &StartTaskStk[0],
               (START_TASK_STK_SIZE / 10u),
                START_TASK_STK_SIZE,
                0u,
                0u,
                DEF_NULL,
               (OS_OPT_TASK_STK_CLR),
               &err);
  // Check error code.
  APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), 1);

  // Start the kernel.
  OSStart(&err);
  // Check error code.
  APP_RTOS_ASSERT_DBG((RTOS_ERR_CODE_GET(err) == RTOS_ERR_NONE), 1);

  return (1);
}

Finally, since Micrium OS makes use of an assembly-optimized memory copy function, you must enable it in common_cfg.h

#define  LIB_MEM_CFG_MEM_COPY_OPTIMIZE_ASM_EN    DEF_ENABLED

You are now set to build and run the project. You can put a breakpoint on the Start Task inside the while loop and notice that you'll be hitting that every second (or as specified by the delay you configure in OSTimeDly()).

Please do understand that this is a very basic guide that resembles more a hack rather than an official solution from Silicon Labs. Hopefully, Micrium OS can be part of the Flex SDK in the future, but in the meantime, this is a start.

I hope this was useful to you. Feel free to post any comments or questions regarding this blog post.