Software Integration Guide - Sona TI351

  1. Introduction
    1. Scope
    2. Cautions and Warnings
    3. Build Host Linux Distribution and Version
  2. Host Interface Dependencies
    1. Power On Reset
    2. Power Supply Restrictions
    3. SDIO_WAKE Strapping
    4. UART Handshaking
    5. Wake On Wireless
  3. TI Radio Stack Software
    1. Obtaining Source and Firmware
    2. Backports
    3. Firmware
    4. Supplicant
  4. Sona TI Device Tree Configuration
    1. Requirements
    2. Sample Device Tree
  5. Regulatory Compliance
    1. Regulatory Domain Configuration
  6. Runtime Validation
  7. Yocto Integration
Sona TI351

Introduction

This document details the software integration requirements for the Sona TI351 radio module. Specific integration steps will vary based on the host platform architecture and build system, but the basic integration requirements are common to all platforms. Many platforms use Yocto as the build system, and this document also provides a usage overview for the Ezurio Yocto layer.

Scope

The scope of this document is limited to providing integration requirements for the Sona TI351 radio and a usage overview of the Ezurio Yocto layer that supports it. It is assumed the reader has an understanding of Linux and building Linux software using the build system employed for the host platform on which this radio is utilized.

Cautions and Warnings

Adhere to all cautions and warnings included with all materials. The Sona TI351 radio and DVK can be damaged by electrostatic discharge (ESD); handle accordingly.

Build Host Linux Distribution and Version

This guide was produced using a build host running Ubuntu 22.04. While it is possible to use a different version of Ubuntu or an entirely different Linux distribution, doing so may require a different procedure. Build hosts running distributions other than Ubuntu 22.04 are beyond the scope of this document.

Host Interface Dependencies

Power On Reset

The W_DISABLE1# pin on the Sona TI351 drives the radio reset input. This signal must be controlled by the host platform GPIO.

Power Supply Restrictions

The Sona TI351 SDIO interface operates at 1.8V only. The host platform SDIO interface must operate at 1.8V at all times, including during bus enumeration.

SDIO_WAKE Strapping

The SDIO_WAKE#/HOST_IRQ_WL pin on the Sona TI351 M.2 1216 solder down module is a SenseOnPower pin. This signal is pulled low internally and must be low when the device powers up. It must not be pulled high or driven high by the host platform. The Sona TI351 M.2 2230 plugin module buffers this signal so it does not have the same restriction.

UART Handshaking

The UART interface requires RTS/CTS hardware handshaking.

Wake On Wireless

The SDIO_WAKE# signal is used to implement Wake On Wireless and must be implemented if Wake On Wireless is desired. This signal can also be used as the SDIO interrupt in place of in-band SDIO interrupt. It does not need to be implemented if Wake On Wireless is not required.

TI Radio Stack Software

Ezurio provides a backports package, firmware package and supplicant package to support the Sona TI radio.

Obtaining Source and Firmware

The Sona TI radio software is in evaluation stage. Please contact Ezurio for download instructions.

Backports

The backports package contains the kernel components needed to support the Sona TI351 radio. These include the cc33xx Wi-Fi driver, the cfg80211 driver, the Bluetooth kernel subsystem and bluetooth drivers. The backports package is created based on the latest Ezurio-supported kernel. The backports package supports the use of customer platforms using earlier kernel versions.

The set of components required from backports is specified in a defconfig file. The backports package includes a set of reference defconfigs for the various radios the backports package can support. These files are located in the defconfigs subdirectory in the root of the backports package. The Sona TI351 radio uses the sona_ti reference defconfig.

The kernel components included in the backports package must be the ones that are used on the target platform. Components built into the base kernel will take precedence over corresponding components from the backports package. Therefore it is important to ensure that these components are not marked as built-in ('y') in the base kernel configuration.

  • Wireless device drivers located at Device Drivers/Network device support/Wireless LAN
  • cfg80211 located at Networking support/Wireless
  • Bluetooth core and drivers located at Networking support/Bluetooth subsystem support

Kernel versions 5.19 and higher must include cfg80211 as a module (m) in the base platform kernel configuration. It must not be left out, and must not be included as built-in (y).

  • Networking support->Wireless->cfg80211 - wireless configuration API

Note: The backports package is a subset of kernel components that have been "backported" to earlier kernel versions. It does not include all dependencies needed for operation. Any dependencies must still be provided by the base kernel configuration for full functionality. In particular, the Bluetooth subsystem has dependencies on a number of crypto modules such as CRYPTO_ECDH. These must be explicitly included in the base kernel configuration if they are not already brought in as a dependency of another base kernel component. See the Help for the Bluetooth subsystem support in the Linux kernel menuconfig for a list of the items that are normally selected; these components must be explicitly included if necessary.

The procedure for building the backports package will depend on your build system. Ultimately it involves setting environment variables to specify the target Linux version, CPU architecture and cross compiler. The .config file is built from the desired defconfig, and then the binaries are built. See the following for an example:

set -a
CROSS_COMPILE=${CROSS_COMPILE}
ARCH=${TARGET_CPU}
KLIB_BUILD=${DEV_PATH}/${LINUX_DIR}
set +a
make defconfig-sona_ti
make

This is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

The backports build process will produce the following binaries that are needed to support the Wi-Fi subsystem on the Sona TI351 radio:

cc33xx.ko -------- at ./drivers/net/wireless/ti/cc33xx/
cc33xx_sdio.ko --- at ./drivers/net/wireless/ti/cc33xx/
mac80211 --------- at ./net/mac80211/
cfg80211.ko ------ at ./net/wireless/
compat.ko -------- at ./compat/

The following binaries are needed to support the Bluetooth subsystem on the Sona TI351 radio:

bluetooth.ko ----- at ./net/bluetooth/
btti_uart.ko ----- at ./drivers/bluetooth/
hci_uart.ko ------ at ./drivers/bluetooth/
compat.ko -------- at ./compat/

Verify these binaries are present on the target platform to confirm the backports build process completed successfully.

Firmware

The publicly available Sona TI351 WW (World Wide) firmware package contains radio firmware, power tables and other low level configuration needed for Wi-Fi and Bluetooth radio functionality. This package is compliant in all regions supported by the Sona TI351. See the Regulatory Release notes for a list of countries supported. Optimized country specific firmware packages are available on request. Contact Ezurio if you need optimized support for a specific country.

The firmware packages are provided in a compressed tar file that must be extracted to the root file system of the target device. The tar file contains the path information for each file; Sona TI351 firmware files will be located in /lib/firmware/ti-connectivity. Several files may be soft links to other files for easier maintenance. It is essential that these names and locations be maintained. The file extraction is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

Verify the firmware package contents are present on the target platform in the correct location to confirm the firmware portion of the build process completed successfully.

Supplicant

Supplicant & Network Manager

Ezurio provides the Summit supplicant and Network Manager in source code as part of the Sona TI radio stack. The Summit supplicant is an enhanced version of the open source wpa_supplicant. The Summit supplicant is required for full functionality.

Network Manager is an optional component that handles network configuration at a high level. Ezurio has extended Network Manager to support additional wireless client and AP configuration options in the Summit supplicant.

Building and installing the supplicant and Network Manager is beyond the scope of this document. This is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

Sona TI Device Tree Configuration

Requirements

The Sona TI351 requires proper configuration in the device tree. The following points must be observed:

  • The SDIO host controller node must contain a sub-node for the TI351 Wi-Fi function (function number 2)
  • The SDIO host controller node must enable run-time PM with the cap-power-off-card property
  • The SDIO host controller should limit operation to SD3.0 only (max 50MHz)
  • The SDIO host controller driver should control the W_DISABLE# pin using a device tree regulator referenced by the vmmc-supply property.
    • The regulator should not be configured with the regulator-always-on property because the driver will toggle it in some scenarios
  • The Bluetooth serdev driver, if used, must reference the same device tree regulator used by the Wi-Fi function.

The SDIO interrupt can either be in-band or out of band (OOB) using the HOST_IRQ_WL/SDIO_WAKE# signal. If Wake On Wireless is desired, then the interrupt must be out of band using the HOST_IRQ_WL/SDIO_WAKE# signal. The HOST_IRQ_WL signal is the interrupt output from the M.2 1216 module and is active high. It is inverted on the M.2 2230 carrier board for compliance with the M.2 specification and is exposed on the M.2 2230 module as the active low SDIO_WAKE#.

Sample Device Tree

Here is a sample device tree section demonstrating the above requirements using an M.2 2230 module and OOB interrupt. In this example host GPIO2_6 is connected to the W_DISABLE# pin and host GPIO2_9 is used for SDIO interrupt via SDIO_WAKE#. The interrupt is active low because this is the M.2 2230 module. If this had been the M.2 1216 module the interrupt would be HOST_IRQ_WL and would be active high.

The driver will use the in-band SDIO interrupt if the interrupt properties are not included in the device tree.

/ {
    reg_usdhc1_vmmc: regulator-usdhc1 {
        compatible = "regulator-fixed";
        regulator-name = "WLAN_EN";
        pinctrl-names = "default";
        pinctrl-0 = <&pinctrl_reg_usdhc1_vmmc>;
        regulator-min-microvolt = <3300000>;
        regulator-max-microvolt = <3300000>;
        gpio = <&gpio2 6 GPIO_ACTIVE_HIGH>;
        enable-active-high;
    };
};

&usdhc1 {
    vmmc-supply = <&reg_usdhc1_vmmc>;
    max-frequency = <50000000>;
    cap-power-off-card;

    #address-cells = <1>;
    #size-cells = <0>;

    wlcore: wlcore@2 {
        compatible = "ti,cc33xx";
        reg = <2>;

        // OOB IRQ support if needed
        interrupt-parent = <&gpio2>;
        interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
    };
};

A reference device tree snippet with essential elements to support Bluetooth serdev operation is shown below. Note following:

  • A 'bluetooth' subnode is created in the uart node used to communicate with the Sona TI351. This causes the UART to be managed as a bluetooth serdev client instead of a tty device.
  • The 'compatible' property is set to "ti,cc33xx-bt"
  • The cc33xx-supply property references the same regulator used by the SDIO host controller.
&uart1 {
    bluetooth {
        compatible = "ti,cc33xx-bt";
        cc33xx-supply = <&reg_usdhc1_vmmc>;
        max-speed = <115200>;
    };
};

Regulatory Compliance

Regulatory Domain Configuration

The Sona TI351 is compliant with regulatory requirements in many countries, and holds modular certification in some of them. The parameters needed for compliance are contained in the firmware package. Ezurio provides a World Wide firmware package that is configured to be compliant in all supported countries. See the Regulatory Release notes for the list of supported countries and the channels supported in each of them.

Please contact Ezurio if optimized support for a specific country is required.

Note: Regulatory requirements prohibit allowing any entity, including a professional installer, OEM representative or end user to change any setting that would cause the radio to operate in a non-compliant manner. The target platform must be secured against attempts to change the regulatory configuration to a different region. This is a condition of using the Ezurio modular certification.

Runtime Validation

The Linux kernel will automatically load the Wi-Fi driver as long as the device tree is configured properly.

The Bluetooth interface requires support from a user mode application because it must be enabled via the wifi interface. If using serdev no further initialization is needed. Otherwise btattach (assuming BlueZ Bluetooth stack) is needed to create the HCI interface.

The following user-mode script can be used to start Bluetooth when using either serdev or btattach. This script assumes the tty interface corresponding to the Bluetooth serial port is /dev/ttymxc0. Modify this port as necessary for your platform.

#!/bin/sh

PHY=`ls /sys/class/ieee80211/`

echo "1" > /sys/kernel/debug/ieee80211/$PHY/cc33xx/ble_enable

if [ -c /dev/ttymxc0 ]; then
  sleep 1
  btattach -B /dev/ttymxc0 -P h4 &
fi

Note: There is much documentation online referencing the legacy hciattach and hciconfig utilities that were used with the legacy BlueZ stack (version 4). These utilities are not compatible with the Bluetooth core in modern kernels and can not be used with Ezurio software. The BlueZ5 stack must be used, along with the btattach and bluetoothctl utilities that it provides.

Platform integration can be validated by checking to see if the Wi-Fi and Bluetooth interfaces are available. Low level Wi-Fi interface management is best done using the 'iw' tool. All wireless devices known to the platform can be shown with the 'iw dev' command. If the wireless device appears in the list then it has been properly integrated:

# iw dev
phy#0
        Unnamed/non-netdev interface
                wdev 0x2
                addr a6:34:f1:b3:23:d4
                type P2P-device
        Interface wlan0
                ifindex 6
                wdev 0x1
                addr a4:34:f1:b3:23:d4
                type managed
                multicast TXQ:
                        qsz-byt qsz-pkt flows   drops   marks   overlmt hashcol tx-bytes        tx-packets
                        0       0       0       0       0       0       0       0               0

Low level Bluetooth interface management can be done using the 'bluetoothctl' command. All Bluetooth devices known to the platform can be listed with the 'bluetoothctl list' command. If the Bluetooth device appears in the list then it has been properly integrated:

# bluetoothctl list
Controller A4:34:F1:B3:23:D5 summit [default]

Yocto Integration

Ezurio provides a Yocto layer that includes support for the Sona TI radio. Platforms that use the Yocto build system can use this layer to do much of the integration automatically. This section gives a brief overview of the steps needed to include and use this layer. Please see the README file in the meta-summit-radio layer for more specific details.

The Ezurio Yocto layer is available on gitHub. Clone or copy this into your project sources directory.

Note: The default Github branch contains only a README file listing the branches that should be used for each radio release version. Be sure to use the branch corresponding to the radio release.

cd /my_project/sources/
git clone https://github.com/Ezurio/meta-summit-radio
git checkout <lrd-a.b.0.x>

The meta-summit-radio layer must be referenced in the conf/bblayers.conf file to be recognized by the build system. Due to a breaking syntax change in bitbake introduced in Yocto 3.4, the meta-summit-radio layer has two implementations. Add the appropriate line to your conf/bblayers.conf file depending on your version of Yocto:

BBLAYERS += "${BSPDIR}/sources/meta-summit-radio/meta-summit-radio"
OR
BBLAYERS += "${BSPDIR}/sources/meta-summit-radio/meta-summit-radio-pre-3.4"

Set the preferred provider for the wpa_supplicant to the Summit supplicant by appending the following lines to the build's conf/local.conf file:

PREFERRED_RPROVIDER_wpa-supplicant = "summit-supplicant-ti"
PREFERRED_RPROVIDER_wpa-supplicant-cli = "summit-supplicant-ti-cli"
PREFERRED_RPROVIDER_wpa-supplicant-passphrase = "summit-supplicant-ti-passphrase"

The Ezurio Yocto layer includes support for other Ezurio radio packages as well. Some of these are providers for the wireless-regdb-static package. However, the Sona TI351 should use the upstream wireless regulatory database. The PREFERRED_RPROVIDER for wireless-regdb-static should be set to the upstream component when using Sona TI351 radio.

PREFERRED_RPROVIDER_wireless-regdb-static = "wireless-regdb"

Add the backports, firmware, supplicant and any other desired packages to your Yocto image recipe.

IMAGE_INSTALL:append = " kernel-module-ti-backports"
IMAGE_INSTALL:append = " summit-supplicant-ti"
IMAGE_INSTALL:append = " ti351-firmware"

Warning: Do not use the IMAGE_INSTALL += "xxx" syntax in your conf/local.conf file to add components to your image. If you use the conf/local.conf file instead of modifying an image recipe, use the append syntax above (or the older syntax for Yocto versions prior to 3.4). Use of 'IMAGE_INSTALL +=' syntax in conf/local.conf can cause subtle issues in the final image that can be very difficult to debug.

Configure your kernel to ensure compatibility with the backports package, specifically ensuring that the wireless and Bluetooth subsystems are not built-in to the kernel. See the Backports section for details:

bitbake -c menuconfig virtual/kernel

Now you can bake your final image:

bitbake <image name>