Using EMLIB in a Gecko OS Application

Gecko OS provides an extensive Native C-API ; however, it is inevitable that use cases will arise that cannot be supported with the Gecko OS API alone. For these cases, the application can use the low-level peripheral library, EMLIB, which is included in the Gecko OS SDK. EMLIB includes modules for all peripherals and core features of the MCU. For more information on supported features, see the EMLIB documentation .

Important Note! When calling EMLIB directly, the application bypasses Gecko OS, which could create conflicts between Gecko OS and the application. For this reason, always use the Gecko OS API whenever possible. This document will attempt to identify sources of potential conflicts but does not cover every use case.

Silicon Labs maintains a large number of peripheral examples that use EMLIB at: Silicon Labs EFM32 Peripheral Examples . Note that these examples are not designed for Gecko OS applications. As a result, they require porting to Gecko OS and do not account for the Gecko OS-specific details discussed in this document. The examples in the GitHub link are subdivided by the "series" of the MCU. The WGM160P Wi-Fi/Ethernet Module includes a EFM32GG11 MCU, which is a series 1 MCU. A smaller set of Gecko OS-specific examples that use EMLIB are also available, as discussed in the Examples section of this document.

For a complete list of EFM32GG11 peripherals and details on programming these peripherals, see the EFM32GG11 Data Sheet and the EFM32GG11 Reference Manual .

The information provided here is relevant to Gecko OS version 4.1 and the WGM160P platform. This is subject to change in future versions and on other platforms.

Calling EMLIB from a Gecko OS Application

Calling EMLIB from within a Gecko OS application is simply a matter of including the desired EMLIB header file in the application source code. For example, the following application source code will use the em_system module to read the part information from the MCU and report it to the console.

EMLIB is located within the Gecko OS SDK in the subdirectory <sdk path>/hardware/chips/silicon_labs/emlib .

#include "gos.h"
#include "em_system.h"

/*************************************************************************************************/
void gos_app_init(void)
{
    GOS_LOG("Part Number:    %d", (int)SYSTEM_GetPartNumber());
    GOS_LOG("Part Family:    %d", (int)SYSTEM_GetFamily());
    GOS_LOG("Part Revision:  %d", (int)SYSTEM_GetProdRev());
}

Gecko OS Peripheral Manager

Gecko OS contains a peripheral manager that keeps track of and manages usage of the platform GPIOs. This allows the application to query the usage (GPIO In/Out, System Indicator, ADC, PWM, and so on.) of a particular GPIO and to prevent GPIO conflicts. For more details, see Managing GPIOs and Peripherals .

When using EMLIB from within a Gecko OS application, you are bypassing the peripheral manager which can cause the peripheral manager to lose track of GPIO functions and result in incorrect responses for the related commands and variables. For example, gpio.usage may return incorrect information if you configure a particular GPIO using EMLIB.

Typically, bypassing the peripheral manager by calling EMLIB directly is not an issue but it is helpful to understand the effects on the peripheral manager. Users should be very careful to avoid resource conflicts or other issues.

Gecko OS Peripheral Usage

Gecko OS uses a variety of MCU peripherals to perform tasks. Much of the Gecko OS peripheral usage can be determined by studying the following documentation:

• WGM160P Gecko OS Peripheral Connections
• Managing GPIOs and Peripherals .

In some cases, the Gecko OS peripheral usage is less apparent. Below is a summary of the various WGM160P peripherals and how they are used by Gecko OS.

GPIO - General Purpose Input/Output

The GPIO peripheral is obviously used by Gecko OS to manage and control the GPIO lines. The application should use the native C-API GPIO functions or the command API GPIO commands and variables whenever possible. The application can use EMLIB to control the GPIO peripheral directly if necessary but each case should be given special consideration to avoid potential issues.

CMU - Clock Management Unit

The MCU's CMU peripheral is used extensively by Gecko OS to configure and manage the various MCU clocks. Even so, the CMU is one peripheral that will often be used by an application that is calling EMLIB directly. Typically, this will be required to enable or disable clocks for a given peripheral. The application must understand which peripherals are used by Gecko OS, as described in this document, to determine when it is appropriate to enable or disable a given clock.

TIMER/WTIMER - Timer/Counter

Gecko OS uses the Timer/Counter MCU peripheral, as described in the sub-sections below. If a given timer is not used for any of the purposes described below, it is available for use by an application that calls EMLIB directly. Do not configure, enable, disable or otherwise modify a timer that is used by Gecko OS.

PWM Timers

The Gecko OS Pulse Width Modulation (PWM) function uses MCU timers and associated compare/capture channels. When the application calls the function gos_pwm_update() or sends the command pwm_update , Gecko OS will configure the GPIO, timer and compare/capture channel that is associated with the specified GPIO. The table below summarizes the mapping of the GPIOs with the needed resources. If a PWM is not used for a given I/O, the timer and compare/capture channel is available for other purposes.

UART RX Timers

The Gecko OS UART function configures a "RX Timer" that is used to trigger an interrupt after a specified period of time. The time period is determined by several factors, most importantly, the number of bytes to be read. The purpose of the RX Timer is to prevent the MCU from being unnecessarily interrupted after every received byte. The table below summarizes the timers that are used by the UART function.

LETIMER - Low Energy Timer

Gecko OS uses LETIMER1 as a RTOS timer so it is not available for other purposes.

SYSTICK - System Tick Timer

The MCU's SYSTICK timer is used as the kernel RTOS tick timer. The application should not disable or modify it. Note that the application can register a system tick callback using the Gecko OS function gos_system_set_system_tick_callback() .

CRYOTIMER - Ultra Low Energy Timer/Counter

When the system is instructed to enter shutdown mode and a wakeup timeout is set, Gecko OS configures the MCU's Cryotimer peripheral to generate the wakeup interrupt. The application can use the Cryotimer when shutdown is not active.

WDOG - Watchdog Timer

Watchdog Timer WDOG0 is used as a standard Watchdog function. Watchdog Timer WDOG1 is used as the idle timer for the Powersave feature .

CRYPTO - Crypto Accelerator

Gecko OS uses the MCU Crypto accelerator peripheral extensively. Therefore, the application should never use this peripheral directly. If a cryptography function is needed, the application should use the native C-API cryptography functions or use the mBedTLS library which is included in the Gecko OS SDK.

GPCRC - General Purpose Cyclic Redundancy Check

The general purpose cyclic redundancy check is used by Gecko OS for filesystem verification and by the native C-API CRC functions . The application shouldn't have to use this peripheral directly.

TRNG - True Random Number Generator

The true random number generator peripheral is used for a variety of cryptographic functions. If cryptography is needed, the application should use the native C-API cryptography functions or use the mBedTLS library which is included in the Gecko OS SDK.

EMU - Energy Management Unit

The energy management unit is used by Gecko OS to manage the sleep/awake profile of the system. This peripheral is not available for use by the application. Instead, the application should use available Gecko OS power management API's .

SDIO - SDIO Host controller

The SDIO peripheral is used as the interface between the EFM32GG11 MCU and the Wi-Fi transceiver device (WF200) inside the module. This peripheral is not available for use by the application.

ETH - Ethernet

The Ethernet peripheral is used by Gecko OS to operate the Ethernet interface when enabled. In normal operation, the application shouldn't have to use the Ethernet peripheral directly. However, in some cases this can be useful. For example, when debugging the interface to an Ethernet PHY or when performing Ethernet compliance testing.

DBG - Debug Interface

The debug interface peripheral is used to program and debug the MCU but it is not otherwise used in normal operation. In fact, for production products, the debug interface should be locked, as described in Understanding the Terms Development and Production .

I2C - Inter-Integrated Circuit Interface

There are no I2C devices located inside the WGM160P module. Therefore, the MCU's I2C peripheral is only used if the application calls the I2C Master API or uses the i2c_master_config or i2C_master_open commands from the command API. The application should use the Gecko OS provided API functions and commands unless it is absolutely necessary to do otherwise.

RMU - Reset Management Unit

The Reset Management Unit (RMU) is configured and used by Gecko OS to control the reset behavior of the device. The application should not use this MCU peripheral directly. Doing so may result in undefined behavior.

USART - Universal Synchronous Asynchronous Receiver/Transmitter

The MCU USART peripheral is used by Gecko OS for various communication interfaces. The table below summarizes the resource usage. See the WGM160P Peripheral Connections table for details on the pin mappings. Note that even if calling EMLIB directly, the GPIO mappings for the unused USART channels may not be available. See the Alternate Functionality Overview sections of the EFM32GG11 Datasheet for further details.

MSC - Memory System Controller

Gecko OS uses the Memory System Controller (MSC) to interface to the internal flash memory. This functionality includes getting and setting Gecko OS variables, reading and writing Non-Volatile Memory (NVM), accessing the file system, and performing firmware updates. The application should not use this MCU peripheral directly.

RTCC - Real Time Counter and Calendar

The RTCC peripheral is used by Gecko OS to keep time and perform real time counter functionality. For more details on such functionality, see the Time functions of the Native C API and the Time variables of the command API. The application should not use this MCU peripheral directly.

ADC - Analog to Digital Converter

The MCU ADC0 peripheral is used for all Gecko OS ADC channels. The ADC1 peripheral is not used and is available for use by applications that call EMLIB directly.

APORT - Analog Port

The APORT peripheral is used to connect GPIO pins to ADC0 for the Gecko OS ADC functionality. The table below summarizes the port mappings. An application that calls EMLIB directly can use the APORT peripheral given that doing so does not create any conflicts with the ADC mappings shown below.

LDMA - Linked DMA Controller

Gecko OS uses the LDMA peripheral extensively for many different purposes; however, the application can perform LDMA transactions directly by using the Gecko OS DMA functions in the Native C API. These functions will allocate (and free) a DMA channel that will be exclusively available to the user application. The application must use these functions to prevent DMA channel conflicts with Gecko OS. The gos_dma_alloc() function allows the application to register a callback function that is automatically called whenever the DMA completes. Note that EMLIB functions that affect all channels such as LDMA_Init() should not be called by the application. Doing so may affect the DMA operations within Gecko OS. Below is a simple example that performs a one-time DMA transfer from one buffer to another. A more complete version of this example is found in the examples discussed in the Examples section of this document.

Note! In Gecko OS version 4.1.11 and earlier, the EMLIB component EM_LDMA is not exported in the kernel. Therefore, to use the functions in this library component, it is required to include the source file em_ldma.c in the application project.

#include "gos.h"
#include "em_ldma.h"

#define BUFFER_SIZE         127
#define TRANSFER_SIZE       (BUFFER_SIZE - 1)

// The memory buffers used for the transfer
uint16_t srcBuffer[BUFFER_SIZE];
uint16_t dstBuffer[BUFFER_SIZE];

// dma channel allocated from Gecko OS
gos_dma_channel_t dma_ch;

/*************************************************************************************************/
static void dma_irq_callback( void *arg )
{
  gos_dma_free(dma_ch);
}

/*************************************************************************************************/
void gos_app_init(void)
{
  uint32_t i;

  // Initialize the LDMA configuration structures
  const LDMA_TransferCfg_t transferCfg = LDMA_TRANSFER_CFG_MEMORY();
  const LDMA_Descriptor_t desc = LDMA_DESCRIPTOR_SINGLE_M2M_HALF(srcBuffer, dstBuffer, TRANSFER_SIZE);

  // Initialize the buffers for memory transfer
  for (i = 0; i < BUFFER_SIZE; i++)
  {
    srcBuffer[i] = i;
    dstBuffer[i] = 0;
  }

  // Allocated a DMA channel
  gos_dma_alloc(dma_irq_callback, NULL, &dma_ch);

  GOS_LOG("Requesting DMA transfer on channel %d", dma_ch);

  // Start the memory transfer
  LDMA_StartTransfer(dma_ch, &transferCfg, &desc);
}

Peripherals not Used

The following MCU peripherals are not used directly by Gecko OS and are therefore available for use by the application given that an available GPIO can be mapped to the peripheral. Available GPIO mappings can be determined by reviewing the GPIO Functionality Table and Alternate Functionality Overview sections of the EFM32GG11 Data Sheet .

Note! This list is referring to peripheral usage by the Gecko OS kernel and plugins. There may be other software components that utilize these peripherals. Peripheral usage by each components must be considered individually if a component is included in the project.

• VDAC - Digital to Analog Converter
• OPAMP - Operational Amplifier
• ACMP - Analog Comparator
• IDAC - Current Digital to Analog Converter
• LESENSE - Low Energy Sensor Interface
• PRS - Peripheral Reflex System
• CAN - Controller Area Network
• USB - Universal Serial Bus Controller
• CSEN - Capacitive Sense Module
• QSPI - Quad- and Octal-SPI Flash Controller
• PCNT - Pulse Counter
• EBI - External Bus Interface
• LCD - Liquid Crystal Display Driver
• SMU - Security Management Unit
• LEUART - Low Energy Universal Asynchronous Receiver/Transmitter
• UART - Universal Asynchronous Receiver/ Transmitter
• RTC - Real Time Counter

Interrupts

Many of the MCU peripherals discussed above have an associated IRQ allowing the peripheral to interrupt the MCU. The application can use these IRQ's by calling the function gos_system_set_irq_callback() . The corresponding interrupt must be enabled using the appropriate MCU registers before the callback is triggered.

Important Note! Users should be extremely careful when registering an IRQ callback because it will override any existing IRQ handler. Because Gecko OS uses many IRQs for normal functionality, this could negatively affect the stability of Gecko OS.

Examples

A set of Gecko OS examples that directly call the EMLIB library can be found at: Gecko OS EMLIB Examples .

As discussed previously, a larger set of MCU peripheral examples can be found at: EFM32 EMLIB Peripheral Examples ; however, these examples are not designed for Gecko OS so they must be modified to operate as a Gecko OS application using the considerations discussed in this document.

Resources

• EFM32GG11 Data Sheet
• EFM32GG11 Reference Manual
• Gecko OS EMLIB Peripheral Examples
• EFM32 EMLIB Peripheral Examples
• WGM160P Gecko OS Peripheral Connections
• WGM160P Data Sheet