Cypress Firmware Deliverables in Mbed OS – KBA228252

Version 25

    Author: VivekK_11           Version: *A

     

    Translation - Japanese: Mbed OSで提供されるサイプレス ファームウェア – KBA228252 - Community Translated (JA)

     

    Question:

    This article provides details on the firmware deliverables from Cypress in Mbed™ OS. Figure 1 shows the architecture of Mbed OS (Source: Mbed OS Documentation). For a general overview of Mbed OS, refer to the documentation at https://os.mbed.com/docs/.

     

    Figure 1

    This article provides details on relevant components highlighted in orange color in Figure 1 that are provided by Cypress. Specifically, the following firmware deliverables are covered:

    • Hardware Abstraction Layer (HAL)

    • Board Support Package (BSP)

    • Wi-Fi and BLE Implementation

     

    1. Hardware Abstraction Layer (HAL)

    Mbed OS provides a Hardware Abstraction Layer (HAL) for the microcontrollers it runs on, so that developers can focus on writing C/C++ applications that call functionality available on a range of hardware. This includes driver for common peripherals like Digital/Analog I/O pins, I2C, UART, SPI, Quad SPI, PWM, etc. See https://os.mbed.com/docs/mbed-os/latest/apis/drivers.html for details on using Driver APIs. See https://os.mbed.com/docs/mbed-os/latest/tutorials/index.html for examples for using driver APIs. Figure 2 shows how Cypress PSoC 6 MCU HAL, Mbed HAL, and Mbed OS drivers are related in an Mbed OS application.

     

    Figure 2

     

    1.1 PSoC 6 MCU Peripheral Driver Library

    Mbed OS provides a Hardware Abstraction Layer (HAL) for the microcontrollers it runs on, so that developers can focus on writing C/C++ applications that call functionality available on a range of hardware. This includes driver for common peripherals like Digital/Analog I/O pins, I2C, UART, SPI, Quad SPI, PWM, etc. See https://os.mbed.com/docs/mbed-os/latest/apis/drivers.html for details on using Driver APIs. See https://os.mbed.com/docs/mbed-os/latest/tutorials/index.html for examples for using driver APIs. Figure 2 shows how Cypress PSoC 6 MCU HAL, Mbed HAL, and Mbed OS drivers are related in an Mbed OS application.

     

    1.2 PSoC 6 HAL

    PSoC 6 MCU HAL provides a high-level interface for interacting with PSoC 6 MCU peripherals. This interface abstracts chip-specific details. If any chip-specific functionality is necessary, or performance is critical, the low-level functions provided in PSoC 6 MCU PDL can be used directly. PSoC 6 MCU HAL is present in  mbed-os\targets\ TARGET_Cypress\TARGET_PSOC6\psoc6csp directory.

     

    1.3 Mbed HAL

    To enable seamless porting of application code between different Arm® Cortex®-M-based devices, Mbed OS provides an Mbed HAL layer for using different peripherals. TheMbed HAL API (header files) is available in the \mbed-os\hal directory. The equivalent Mbed HAL API implementation (source files) for PSoC 6 MCU is provided by Cypress in the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6 directory. The Cypress implementation of the Mbed HAL relies mostly on the PSoC 6 MCU HAL APIs, and where necessary the PSoC 6 MCU PDL APIs.

     

    1.4 Mbed Drivers

    Mbed OS provides a C++ wrapper for commonly used MCU peripherals and functionalities. These are available in \mbed-os\drivers directory.

     

    2. Board Support Package

    In Mbed OS, a ‘target’ refers to the hardware development kit. Cypress provides the Target Implementation, also known as a Board Support Package (BSP), for all the Mbed OS-enabled kits from Cypress. Details of BSP are provided below.

     

    2.1 Targets List

    The list of targets (BSPs) supported in Mbed OS by all the partners, and the respective target configurations is available in the file mbed-os\targets\targets.json. This file includes the Cypress targets supported in Mbed OS as well. For more information on the target configuration parameters in this file, see https://os.mbed.com/docs/mbed-os/latest/reference/adding-and-configuring-targets.html.

     

    2.2 Target-Specific Board Support Package

    Cypress target BSPs are available in \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6 directory. Each target has a directory in the format TARGET_TARGETNAME. For example, CY8CKIT-062-WiFi-BT target folder is TARGET_CY8CKIT_062_WiFi_BT as shown in Figure 3.

     

    Figure 3

     

    Files, Folder in Target ImplementationDetails

    cybsp.c, cybsp.h

    Contains the Initialization function cybsp_init() for the target that initializes the device clock, power and peripheral interconnect settings.
    cybsp_types.hContains definitions for the on-board components like LEDs and buttons. These definitions are used in the BSP initialization code. In addition, these definitions are used in PinNames.h and PeripheralNames.h files available inside the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6 to map pin and peripheral names used by Mbed OS to PSoC 6 MCU pins.

    design.modus file and Generated Source folder

    The design.modus file is used internally by BSP files for BSP configuration. It is responsible for holding the hardware configuration information of PSoC 6 MCU host as used on the target hardware. This file can be viewed and modified, if needed in the "Device Configurator" tool from ModusToolbox. The configuration files generated from design.modus are stored in the Generated Source folder.

    PeripheralPins.c

    Contains the mapping of the PSoC 6 MCU Host pins, block instance name, and the specific functionality of the pin in relation to that block instance (Like P1[0] is mapped to UART_0 Instance and serves as UART_RX pin).
    device folderContains the startup code and linker scripts for different toolchains

     

     

    2.3 PSoC 6 MCU CM0+ CPU Image

    Cypress provides precompiled application images that are executed on Cortex M0+ core of the dual-CPU PSoC 6 MCU. These images are in the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6\psoc6cm0p folder. The images are provided as C arrays ready to be compiled as part of the Cortex M4 application. The Cortex M0+ application code is placed into the internal flash by the Cortex M4 linker script. The details of the different CM0+ image types are provided below.

     

    • COMPONENT_CM0P_SLEEP: This folder contains CM0+ image that starts the CM4 core at CY_CORTEX_M4_APPL_ADDR =0x10002000 and puts

     

    • COMPONENT_CM0P_CRYPTO: This folder contains CM0+ image that starts crypto server on CM0+ core, starts CM4 core at CY_CORTEX_M4_APPL_ADDR = 0x1000A000 and puts CM0+ core into a Deep Sleep mode.ReadMe

     

    • COMPONENT_CM0P_BLESS: This folder contains CM0+ image that starts BLE controller on CM0+ core, starts CM4 core at CY_CORTEX_M4_APPL_ADDR = 0x10020000 and puts CM0+ core into a Deep Sleep mode. This CM0+ image takes 128 KB of Flash and 12 KB of SRAM. The CM0+ core handles BLE host requests in addition to the system call operations like Flash memory programming. Separate images are provided inside the \TARGET_CM0P_SLEEP folder for the different PSoC 6 MCU families. Refer to the ReadMe

     

    • COMPONENT_CM0P_SECURE: This folder contains CM0+ image that starts CM4 core at address corresponding to Secure Boot policy, sets required security settings, initializes and executes code of Protected Register Access driver, puts CM0+ core into a Deep Sleep mode. This CM0+ image is applicable only when using Targets containing PSoC 64 MCUs. This is the default and only image supported by the PSoC 64 MCU based targets.

     

    These CM0P images are provided as Mbed OS Components that can be added using mbed_app.json in the application as shown in the example below that adds the CM0P_CRYPTO component and removes the default CM0P_SLEEP component.

    "target_overrides": {

        "*": {

            "target.component_add": "CM0P_CRYPTO"

            "target.component_remove": "CM0P_SLEEP"

        }

    }

     

    2.4 Reserved Resources

    As part of Mbed OS startup, BSP reserves some resources automatically. The details of these resources are captured in the table below.

     

    Resource

    Details

    SDIO

    A SDIO block or UDBs implementing the SDIO interface (in case of CY8C62x7 family) is reserved by the BSP for targets supporting Wi-Fi such as CY8CPROTO-062-4343W, CY8CKIT-062S2-43012 etc. The SDIO block reserved for the purpose correspond to the SDIO pins that connect to the CYW43xx device in the board. For instance, in CY8CPROTO-062-4343W, it is the SDIO_0 or SDHC_0 block that correspond to Port 2 SDIO pins connected to the on-board CYW4343W device.

     

    In addition, the SDIO pins are reserved as part of the initialization.

    TCPWM

    A timer based on the TCPWM block is reserved by the Mbed OS us_ticker timer for counting µs ticks. The TCPWM block allocation is handled by PSoC 6 Timer HAL and the Hardware manager.

    In addition, a peripheral clock is reserved by the us_ticker for clocking the TCPWM block at 1 MHz.

    QSPI

    A Quad-SPI block is reserved by the BSP when MBED_CONF_TARGET_XIP_ENABLE is true. This is to reserve the QSPI block for XIP mode of operation. The QSPI block reserved for the purpose correspond to the QSPI pins that connect to the external memory in the board. For instance, in CY8CPROTO-062-4343W, it is the QSPI_0 block that correspond to the Port 11/12 QSPI pins connected to the on-board external memory.

     

    In addition, the QSPI pins are reserved as part of the initialization.

     

    In addition, if needed, application can reserve resources immediately after cybsp_init by using the cy_mbed_post_bsp_init_hook. This function is called immediately after cybsp_init. A default empty, weak definition of the function exists in cybsp.c, which can be overridden by redefining the function in the application code.

    3. Wi-Fi and BLE Implementation

    Figure 4 shows the layers of the Wi-Fi and BLE protocol implementation in a PSoC 6 MCU and CYW43xxx based solution in Mbed OS.

    Figure 4

    The WLAN subsystem of CYW43xxx communicates with PSoC 6 MCU through the SDIO interface. SDIO interface consists of 6 signals – SDIO_CMD, SDIO_CLK, and SDIO_DATA [3:0]. The WLAN susbsytem on CYW43xxx includes the 802.11 physical layer (PHY) and the 802.11 Media Access Control (MAC) layer. The upper layers of the Wi-Fi protocol including the network stack, and the higher layer protocols (IP, TCP/UDP, HTTP, MQTT etc) are handled in PSoC 6 MCU.

    The Bluetooth (BT) subsystem of CYW43xxx communicates with PSoC 6 MCU through the HCI UART interface with flow control enabled (TX, RX, RTS, CTS). The Bluetooth susbsytem on CYW43xxx implements the controller portion of the BLE stack which includes the radio and the link layer. The Host portion of the BLE stack, BLE profiles, and the application code reside on PSoC 6 MCU.

    In addition to the SDIO and UART interfaces, there are also six control signals between the PSoC 6 MCU and CYW43xxx devices. These include the power control signals (WL_REG_ON, BT_REG_ON), CYW43xxx device wakeup signals (WL_DEV_WAKE, HOST_DEV_WAKE), and PSoC 6 MCU host wakeup signals (WL_HOST_WAKE, BT_HOST_WAKE). See the CYW43xxx device datasheet for details on these control signals, SDIO, and UART interfaces.

    The following sections provide details on the Cypress firmware deliverables relevant to Wi-Fi and BLE.

    3.1.1 Wi-Fi Host Driver (WHD)
    Wi-Fi Host Driver (WHD) is the driver firmware running on the host MCU (PSoC 6 MCU) that uses the underlying communication interface (typically, but not restricted to, SDIO interface) to interface with the WLAN subsystem of the CYW43xxx device. WHD provides WLAN APIs which can be used by upper layers of the host MCU software framework. These include APIs for functionality such as scan, join, and SoftAP. Cypress provides the WHD firmware as part of Mbed OS in the mbed-os\targets\TARGET_Cypress\TARGET_PSOC6\TARGET_WHD folder.

    In addition to the driver firmware, the WHD folder also contains other resources as listed below.

     

    3.1.2 Ethernet MAC (EMAC)

    The WHD to Mbed Ethernet MAC (EMAC) driver interface is maintained in the mbed-os\features\netsocket\emac-drivers\TARGET_WHD folder. See https://os.mbed.com/docs/mbed-os/v5.13/porting/ethernet-port.html more details on the EMAC driver for WiFi.

     

    3.1.3 LWIP Network Stack

    Each board that supports Wi-Fi connectivity needs to be added to the mbed-os\features\lwipstack\mbed_lib.json file with appropriate settings. The LWIP stack settings for the Cypress kits with Wi-Fi functionality have been added to this file.

     

    3.1.4 Network Socket APIs

    The application programming interface for IP networking is the Socket API. The Socket API relates to OSI layer 4, the transport layer. In Mbed OS, the Socket API is abstracted, and supports various protocols such as TCP and UDP. For information on Mbed OS Network Socket APIs, refer to https://os.mbed.com/docs/mbed-os/latest/apis/network-socket.html.

     

    3.1.5 NetworkInterface APIs

    A socket requires a NetworkInterface instance to indicate which NetworkInterface the socket should be created on. The NetworkInterface provides a network stack that implements the underlying socket operations. NetworkInterface is also the controlling API that the application uses to specify the network configuration. For information on Mbed OS Network Interface APIs, refer to https://os.mbed.com/docs/mbed-os/latest/apis/network-interfaces.html.

     

    3.2 BLE Firmware Deliverables

    CYW43xxx Wi-Fi/BT combo devices (CYW43012, CYW4343W) contain the dual-mode Bluetooth radio and controller functionality. The Bluetooth subsystem in these combo devices interface with a PSoC 6 MCU Host thorugh the HCI UART interface, and the BLE host stack runs on PSoC 6 MCU. Mbed OS does not support Classic Bluetooth. The abstraction layer between the Cypress BLE implementation and the Cordio BLE stack are located in mbed-os\features\FEATURE_BLE\targets\TARGET_Cypress.

    Arm Mbed BLE, also called BLE_API, is the Bluetooth Low Energy software solution for Mbed OS. Developers can use it to create new BLE-enabled applications. Mbed OS’s BLE_API interfaces with the BLE controller on the platform. It hides the BLE stack’s complexity behind C++ abstractions and is compatible with all BLE-enabled Mbed platforms. For more information on the BLE APIs, see https://os.mbed.com/docs/mbed-os/latest/apis/ble.html.