Driver Porting Guide¶

This guide is intended to help customers port the software components required to use the CC33xx MCU with a non-TI microcontroller.
This porting guide is focusing on the Wi-Fi host driver porting. Note that the example applications (e.g. Network Terminal) use TI Drivers, FreeRTOS operating system and LWIP network stack which will require their own ports and are out of the scope of this guide.
More details on the commands listed below can be found through the API reference.

Porting Layer Files¶

The CC33XX MCU SW Package example contains a porting layer that acts as the adaptation layer for the host microcontroller.
When moving to another host platform or operating system these files must be ported.
The following sections will walk through this porting layer in detail. The adaptation layer implementation files can be found inside the WiFi_adaptation_layer/ folder of the example project:

wlan_irq_adapt.c
spi_adapt.c
osi_filesystem.c
osi_freertos.c

In this package, these files are available for the AM243x host.
Many of these files include header files specific to TI microcontrollers, such as ti_drivers_config.h.
These include paths can be removed or replaced for non-TI MCUs.

WLAN Enable/Disable¶

The CC33XX device can be enabled and disabled by controlling the WLAN_EN signal via GPIO output.

`wlan_irq_adapt`_:

TurnOn_WL: Toggles the WLAN_EN signal high, then delays 2 seconds.
TurnOff_WL: Toggles the WLAN_EN signal low.
GetState_WL: Checks the current state of the WLAN_EN signal.

Host Interface¶

The host communication interface is SPI. The porting layer requires functionality for SPI open, close, read, write, and registering an interrupt handler routine for the IRQ signal.

The SPI interface on the host MCU has the following hardware requirements:

Master mode
4 pin mode
Chip select active low
Polarity 0 phase 0
Max frequency: 32000000 Hz
Data block: 32 bits

`spi_adapt`_:

spi_Init: Initialize and open the host MCU SPI module
spi_ReadSync: Read from SPI (blocking)
spi_WriteSync: Write to SPI (blocking)

The host interface also requires an IRQ signal with a registered interrupt and a GPIO to control the CC33xx Enable pin.

`wlan_irq_adapt`_:

wlan_IRQInit: Initialize the GPIO input and register a pin interrupt
wlan_IRQDeinit: Destroy the GPIO interrupt
wlan_IRQEableInt: Enable GPIO interrupt. If working with edge-trigger, this is not required.
wlan_IRQDisableInt: Disable GPIO interrupt. If working with edge-trigger, this is not required.
wlan_IRQClearInt: Clear GPIO interrupt. If working with edge-trigger, this is not required.
wlan_TurnOffWlan: Set the CC33xx enable pin (GPIO) to off state.
wlan_TurnOnWlan: Set the CC33xx enable pin (GPIO) to on state.
wlan_GetStateWlan: Retrieve the CC33xx enable pin (GPIO) state.

OS Abstraction¶

This software package utilizes Free-RTOS, which is included with the MCU-PLUS-AM243X-SDK. The porting layer defines generic “osi” APIs used by the firmware. This allows the firmware to adapt to another RTOS.

`osi_freertos`_:

osi_SyncObjCreate: Create a sync object (e.g. a semaphore or a message queue) where a thread can block and wait for an external event
osi_SyncObjDelete: Delete sync object
osi_SyncObjSignal: Generate a sync signal, or give the sempahore
osi_SyncObjSignalFromISR: Generate a sync signal from the ISR context
osi_SyncObjWait: Wait for a sync signal, or take the semaphore
osi_SyncObjClear: Clear sync object
osi_LockObjCreate: Create a locking object
osi_LockObjDelete: Delete the locking object
osi_LockObjLock: Lock the locking object
osi_LockObjUnlock: Unlock the locking object
osi_MsgQCreate: Create a message queue
osi_MsgQDelete: Delete message queue
osi_MsgQWrite: Post message to queue
osi_MsgQRead: Read message from queue
osi_MsgQCount: Returns the number of messages in the message queue
osi_MsgQIsEmpty: Boolean returns whether the message count in the queue is zero
osi_ThreadCreate: Create a task. In the example, this API uses a legacy osi_TaskCreate.
osi_ThreadDelete: Delete the task. In the example, this API uses a legacy osi_TaskDelete.
osi_EnterCritical: Enter critical section (lock + context switch prevention)
osi_ExitCritical: Exit critical section
assert: Assert function

Memory Management¶

The control block for the host driver requires memory allocation.

`osi_freertos`_:

os_malloc: Allocate dynamic memory
os_realloc: Reallocate dynamic memory
os_realloc_array: Reallocate and zero memory blocks
os_calloc: Allocate and zero memory blocks
os_zalloc: Allocate and zero memory
os_free: Free memory

Timer Mechanism¶

This timestamp mechanism is used to determine timeouts for the host driver.

`osi_freertos`_:

osi_Sleep: Put the thread to sleep (seconds)
osi_uSleep: Put the thread to sleep (microseconds)
osi_GetTimeMS: Get the running tick count (milliseconds)
osi_TimerCreate: Create a timer
osi_TimerDelete: Delete timer
osi_TimerStart: Start timer
osi_TimerStop: Stop timer
osi_TimerGetRemainingTime: Get remaining time

The system tick period for the target host MCU must be set in the define TICK_PERIOD_US at the top of osi_freertos.c.

File System¶

These functions are required for the file management of the host driver. For now the driver only uses the read function to retrieve the pre-installed firmware when downloading it as part of the cc33xx init.

`osi_filesystem`_:

osi_fopen: File open
osi_fclose: File close
osi_fread: File read
osi_write: File write (not used currently)
osi_filelength: Get file size

Asynchronous Event Handler¶

Asynchronous event handlers are used to process aynchronous events from the CC33XX to the host application.
This includes errors, notifications of WLAN connections and disconnections, scans, and more.
The async event handler is implemented by the developer in the application, and it is registered when the application calls Wlan_Start. The event handler should be customized for the application.
In the network_terminal example, the event handler is WlanEventHandler() defined in network_terminal.c.