AN1143: Using Micrium OS with Silicon Labs Thread The Silicon Labs Thread SDK provides support for running on top of the Micrium OS kernel, a full-featured RTOS for embedded systems. Support for Micrium is integrated into the AppBuilder in Simplicity Studio. Two concurrency models are available: running the Thread stack and the app together within a single Micrium task, or running them in two separate Micrium tasks. The two-task model is also known as the virtual Network Co-Processor architecture, or vncp for short. This is because the processing and communication between the two tasks is the same as for the host/ncp architecture. The difference is that instead of running on separate processors and passing messages to each other through the serial port, the application and NCP run on the same processor but in different Micrium tasks. Message passing is handled using Micrium message queues, and is transparent to the application. KEY POINTS Micrium OS support for Thread is available in Simplicity Studio in AppBuilder. The app task and Thread stack task can be run together in one thread or in separate threads (known as vncp). EFR32 chips are supported. EM3x chips are not. Micrium OS is supported on the EFR32, but not on the EM3x. For documentation on Micrium OS itself, please see http://doc.micrium.com. silabs.com Building a more connected world. Rev. 0.1
Getting Started 1. Getting Started Integrating Micrium OS into your application is simply a matter of selecting the right set of plugins in the AppBuilder tool within the Simplicity Studio Simplicity IDE. For the single-task model, only a single plugin is needed, Micrium RTOS. For the vncp, several additional plugins are required. Two vncp sample applications (Light vncp and Server vncp) are provided as examples to help get you started. Note: The Micrium RTOS plugin is only supported for EFR32 chips. 1.1 Using Micrium OS with a Single Task For any SoC (System-on-Chip) AppBuilder project, Micrium OS can be added simply by selecting the Micrium RTOS plugin in the Plugins tab for the project. To get to the Plugins tab, create an SoC project or double-click on the ISC file for an existing project in the Project Explorer to open the project in AppBuilder. Figure 1.1. The Micrium RTOS Plugin in Simplicity Studio AppBuilder The plugin brings all the Micrium OS kernel files into your project, along with some integration files. The Micrium OS plugin options allow you to set the call stack size for the application task. The default is 1000 bytes. If you are using the Main plugin from AppBuilder, that is all you need to do. When you run your application, Micrium automatically starts up and launches a single task containing your application and the Thread stack. silabs.com Building a more connected world. Rev. 0.1 2
Getting Started 1.2 Using Micrium OS with Two Tasks: the Virtual NCP model Under some circumstances it is desirable to run the application and the Thread stack in separate Micrium tasks. For example, this would be useful for a multiprotocol application. To support this, AppBuilder provides the virtual NCP or vncp model. As the name implies, the vncp model works for any application that has been written to work as a host communicating with an NCP. The interprocess communication of data and management messages between the two tasks is taken care of by AppBuilder plugins and is transparent to the application. Two AppBuilder sample applications are provided as examples. In Simplicity Studio, select New Project, and use the Wizard to create a new AppBuilder Project using Silicon Labs Thread SDK 2.7 or higher. In the list of sample applications, select either Light vncp or Server vncp. The former is a ZCL-based application, and the latter does not use ZCL. By looking at the Plugins tab, you can see that the vncp sample applications include the following plugins: Micrium RTOS vncp Library HAL vncp Library DHCP vncp Library Manufacturing Library for vncp Thread vncp Stack Library The following plugins should NOT be included, as they are mutually exclusive with the above required plugins: ASH v3 DHCP Library HAL Library HAL NCP Library Host Network Management Idle Sleep Manufacturing Library NCP SPI Link NCP UART Link Thread Stack Library (Silicon Labs TLS and mbed TLS) The vncp Library plugin contains an option for setting the call stack size for the Thread vncp Stack task. If you are using the Main Plugin, when you run your application Micrium OS automatically starts up and launches the application task and the Thread vncp Stack task. silabs.com Building a more connected world. Rev. 0.1 3
vncp Internals 2. vncp Internals This section describes some behind-the-scenes activities in the vncp architecture. These items are all transparent to the application, but knowing about them is useful in gaining a deeper understanding of the system. 2.1 Intertask Communication The vncp model uses the same message-passing mechanism used in the Host/NCP model. TMSP (Thread Management Serial Protocol) is used to serialize management commands and responses between the application and the NCP. Data messages in the form of IPv6 packets are also passed back and forth as they are transmitted and received by the host application. The difference in the vncp model is the layer underneath TMSP. Rather than sending the serialized messages over a serial port (typically using the ASHv3 serial protocol for reliability), the messages are placed in Micrium OS queues, one for management messages and one for data messages in each direction. The two tasks use Micrium semaphores for access control to the queues and to signal each other when messages are ready to be processed by the other side. 2.2 Thread-Safety of the Buffer System The Silicon Labs Thread Stack uses a memory management system that uses a garbage collector to maintain and compactify the heap. The buffer system is exposed to the application, for example in the CoAP APIs. This does not present a problem on an SOC, but on the vncp the application and the stack are running in separate Micrium tasks. In order to ensure that the garbage collector does not run while the application is in the middle of using information stored in the heap, a Micrium mutex is used to lock the heap while the application is running. Each time through the main loop, the application releases the mutex and wakes up the vncp (Thread Stack) task so that it can run the garbage collector. In this way, application code does not need to worry about thread-safety in every place that it is using the memory system. 2.3 API Renaming The Thread API was written to use the same API function names on the SOC and the Host. This allows an application to run on both SoC and Host with minimal modifications. However, in the vncp model, this creates name collisions, because the application and the vncp both use the APIs but on top of different implementations. To work around this, the C preprocessor is used to create different prefixes for the APIs depending on whether they belong to the Thread vncp Stack task or the application task. The application API uses the ember prefix, and the vncp API uses the emapi prefix. silabs.com Building a more connected world. Rev. 0.1 4
Smart. Connected. Energy-Friendly. Products www.silabs.com/products Quality www.silabs.com/quality Support and Community community.silabs.com Disclaimer Silicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and "Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Silicon Labs shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses granted hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent of Silicon Labs. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons. Trademark Information Silicon Laboratories Inc., Silicon Laboratories, Silicon Labs, SiLabs and the Silicon Labs logo, Bluegiga, Bluegiga Logo, Clockbuilder, CMEMS, DSPLL, EFM, EFM32, EFR, Ember, Energy Micro, Energy Micro logo and combinations thereof, "the world s most energy friendly microcontrollers", Ember, EZLink, EZRadio, EZRadioPRO, Gecko, ISOmodem, Micrium, Precision32, ProSLIC, Simplicity Studio, SiPHY, Telegesis, the Telegesis Logo, USBXpress, Zentri, Z-Wave and others are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand names mentioned herein are trademarks of their respective holders. Silicon Laboratories Inc. 400 West Cesar Chavez Austin, TX 78701 USA http://www.silabs.com