Hardware Abstraction Layer (HAL)
TDM (Time Division Multiplexed)

General Description

High level interface for interacting with the Time Division Multiplexed controller (TDM).

The TDM protocol is a asynchronous serial interface protocol. This driver supports both transmit and receive modes of operation. The communication frequency, sample rate, word size, and number of channels can all be configured.

Note
Certain platforms may not support all of the functionality and configuration options provided by this driver. Please refer to implementation specific documentation for details on available options.

Features

Quick Start

Initialize an TDM instance using the cyhal_tdm_init and provide the transmit (tx) and/or receive (rx) pins. Call cyhal_tdm_start_tx and/or cyhal_tdm_start_rx to enable transmit and/or receive functionality as desired.
See Snippet 1: TDM Initialization and Configuration for example initialization as transmit or receive.

Note
The clock parameter (const cyhal_clock_t *clk) is optional and can be set to NULL to generate and use an available clock resource with a default frequency.

The sclk frequency is determined as sclk = sample_rate_hz * channel_length * num_channels. The input clock must be a multiple of this sclk frequency; see the implementation specific documentation for the supported multipliers.

It is possible to use either only TX functionality, only RX functionality, or both RX and TX functionality at the same time. If RX and TX are both in use, the same sample rate, channel length, channel count, channel mask, word length, and sclk frequency will be used for both.

Code Snippets

Note
Error checking is omitted for clarity

Snippet 1: TDM Initialization and Configuration

This snippet initializes an TDM resource for transmit or receive and assigns the pins.

Initializing as TDM transmitter

#if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
cyhal_tdm_pins_t tx_pins = { .sck = P5_1, .ws = P5_2, .data = P5_3, .mclk = NC };
{
.is_tx_slave = false,
.tx_ws_width = CYHAL_TDM_WS_SINGLE,
.is_rx_slave = false,
.rx_ws_width = CYHAL_TDM_WS_SINGLE,
.mclk_hz = 0,
.channel_length = 32,
.num_channels = 8,
.channel_mask = 0xFF, // All 8 channels enabled
.word_length = 32,
.sample_rate_hz = 44000
};
cy_rslt_t result = cyhal_tdm_init(&tdm, &tx_pins, NULL, &config, NULL);
CY_ASSERT(CY_RSLT_SUCCESS == result);
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
Shared data between i2s and tdm.
Definition: cyhal_hw_types.h:361
@ NC
No Connect/Invalid Pin.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:53
@ P5_2
Port 5 Pin 2.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:70
@ P5_1
Port 5 Pin 1.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:69
@ P5_3
Port 5 Pin 3.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:71
bool is_tx_slave
Configure TX to operate as slave (true) or master (false)
Definition: cyhal_tdm.h:201
cyhal_gpio_t sck
Clock pin.
Definition: cyhal_tdm.h:185
cy_rslt_t cyhal_tdm_init(cyhal_tdm_t *obj, const cyhal_tdm_pins_t *tx_pins, const cyhal_tdm_pins_t *rx_pins, const cyhal_tdm_config_t *config, cyhal_clock_t *clk)
Initialize the TDM peripheral.
@ CYHAL_TDM_WS_SINGLE
Single SCK cycle.
Definition: cyhal_tdm.h:194
TDM Configuration.
Definition: cyhal_tdm.h:199
Pins to use for one TDM direction.
Definition: cyhal_tdm.h:184
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

Initializing as TDM receiver

#if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)
cyhal_tdm_pins_t rx_pins = { .sck = P5_4, .ws = P5_5, .data = P5_6, .mclk = NC };
{
.is_tx_slave = false,
.tx_ws_width = CYHAL_TDM_WS_SINGLE,
.is_rx_slave = false,
.rx_ws_width = CYHAL_TDM_WS_SINGLE,
.mclk_hz = 0,
.channel_length = 32,
.num_channels = 8,
.channel_mask = 0xFF, // All 8 channels enabled
.word_length = 32,
.sample_rate_hz = 44000
};
cy_rslt_t result = cyhal_tdm_init(&tdm, NULL, &rx_pins, &config, NULL);
CY_ASSERT(CY_RSLT_SUCCESS == result);
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)
@ P5_4
Port 5 Pin 4.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:72
@ P5_6
Port 5 Pin 6.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:74
@ P5_5
Port 5 Pin 5.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:73

Snippet 2: TDM Transmit One-shot

This snippet shows how to transmit data using cyhal_tdm_write_async when the entire sample is available at once.

#if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
static void tdm_event_handler_transmit_one_shot(void* arg, cyhal_tdm_event_t event)
{
// When we registered the callback, we set 'arg' to point to the tdm object
cyhal_tdm_t* tdm = (cyhal_tdm_t*)arg;
if (0u != (event & CYHAL_TDM_TX_EMPTY))
{
}
}
// Data to transmit, defined e.g. an array stored in flash
extern const uint32_t* tdm_tx_buffer;
extern const size_t tdm_tx_buffer_len;
//--------------------------------------------------------------------------------------------------
// snippet_cyhal_tdm_async_transmit_one_shot
//--------------------------------------------------------------------------------------------------
static void snippet_cyhal_tdm_async_transmit_one_shot(void)
{
// Initialize the object as shown in Snippet 1
// Register a callback and set the callback argument to be a pointer to the tdm object, so that
// we can easily reference it from the callback handler.
cyhal_tdm_register_callback(&tdm, &tdm_event_handler_transmit_one_shot, &tdm);
// Subscribe to the TX Empty event so that we can stop the interface when the transfer is
// complete
cyhal_tdm_write_async(&tdm, tdm_tx_buffer, tdm_tx_buffer_len);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
#define CYHAL_ISR_PRIORITY_DEFAULT
Priority that is applied by default to all drivers when initialized.
Definition: cyhal_hw_types.h:114
void cyhal_tdm_register_callback(cyhal_tdm_t *obj, cyhal_tdm_event_callback_t callback, void *callback_arg)
Register a TDM callback handler.
cy_rslt_t cyhal_tdm_stop_tx(cyhal_tdm_t *obj)
Stops transmitting data.
cy_rslt_t cyhal_tdm_start_tx(cyhal_tdm_t *obj)
Starts transmitting data.
cyhal_tdm_event_t
TDM events.
Definition: cyhal_tdm.h:146
cy_rslt_t cyhal_tdm_write_async(cyhal_tdm_t *obj, const void *tx, size_t tx_length)
Start TDM asynchronous write.
void cyhal_tdm_enable_event(cyhal_tdm_t *obj, cyhal_tdm_event_t event, uint8_t intr_priority, bool enable)
Configure TDM events.
@ CYHAL_TDM_TX_EMPTY
TX HW Buffer is empty.
Definition: cyhal_tdm.h:152

Snippet 3: TDM Transmit Streaming

This snippet shows how to transmit data using cyhal_tdm_write_async when sample data is being continuously loaded and transmitted (e.g. streaming over the network).

#if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
// We use a dual buffer system so that one buffer can be transmitting while the other is being
// filled
#define BUFFER_SIZE 128u
static const uint32_t tx_buffer0[BUFFER_SIZE];
static const uint32_t tx_buffer1[BUFFER_SIZE];
static const uint32_t* active_tx_buffer;
static const uint32_t* next_tx_buffer;
//--------------------------------------------------------------------------------------------------
// tdm_event_handler_transmit_streaming
//--------------------------------------------------------------------------------------------------
static void tdm_event_handler_transmit_streaming(void* arg, cyhal_tdm_event_t event)
{
// When we registered the callback, we set 'arg' to point to the tdm object
cyhal_tdm_t* tdm = (cyhal_tdm_t*)arg;
if (0u != (event & CYHAL_TDM_ASYNC_TX_COMPLETE))
{
// Flip the active and the next tx buffers
const uint32_t* temp = active_tx_buffer;
active_tx_buffer = next_tx_buffer;
next_tx_buffer = temp;
// Start writing the next buffer while the just-freed one is repopulated
cyhal_tdm_write_async(tdm, active_tx_buffer, BUFFER_SIZE);
// Load the next set of data into next_tx_buffer
}
}
//--------------------------------------------------------------------------------------------------
// snippet_cyhal_tdm_async_transmit_streaming
//--------------------------------------------------------------------------------------------------
static void snippet_cyhal_tdm_async_transmit_streaming(void)
{
// Initialize the object as shown in Snippet 1
// Register a callback and set the callback argument to be a pointer to the tdm object, so that
// we can easily reference it from the callback handler.
cyhal_tdm_register_callback(&tdm, &tdm_event_handler_transmit_streaming, &tdm);
// Subscribe to the async complete event so that we can queue up another transfer when this one
// completes
// Configure asynchronous transfers to use DMA to free up the CPU during transfers
// Populate initial data in the two tx buffers (e.g. by streaming over the network)
active_tx_buffer = tx_buffer0;
next_tx_buffer = tx_buffer1;
cyhal_tdm_write_async(&tdm, active_tx_buffer, BUFFER_SIZE);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)
@ CYHAL_ASYNC_DMA
Use DMA if available.
Definition: cyhal_general_types.h:112
#define CYHAL_DMA_PRIORITY_DEFAULT
Default DMA channel priority.
Definition: cyhal_dma_impl.h:66
cy_rslt_t cyhal_tdm_set_async_mode(cyhal_tdm_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority)
Set the mechanism that is used to perform TDM asynchronous transfers.
@ CYHAL_TDM_ASYNC_TX_COMPLETE
Pending async transmit is complete (but the HW buffer may still contain unsent data)
Definition: cyhal_tdm.h:158

Snippet 4: TDM Receive

This snippet shows how to receive data using cyhal_tdm_read_async.

#if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)
// We use a dual buffer system so that one buffer can be filling while the other is being processed
#define BUFFER_SIZE 128u
static uint32_t rx_buffer0[BUFFER_SIZE];
static uint32_t rx_buffer1[BUFFER_SIZE];
static uint32_t* active_rx_buffer;
static uint32_t* full_rx_buffer;
//--------------------------------------------------------------------------------------------------
// tdm_event_handler_receive
//--------------------------------------------------------------------------------------------------
static void tdm_event_handler_receive(void* arg, cyhal_tdm_event_t event)
{
// When we registered the callback, we set 'arg' to point to the tdm object
cyhal_tdm_t* tdm = (cyhal_tdm_t*)arg;
if (0u != (event & CYHAL_TDM_ASYNC_RX_COMPLETE))
{
// Flip the active and the next rx buffers
uint32_t* temp = active_rx_buffer;
active_rx_buffer = full_rx_buffer;
full_rx_buffer = temp;
// Start reading into the next buffer while the just-filled one is being processed
cyhal_tdm_read_async(tdm, active_rx_buffer, BUFFER_SIZE);
// Process the data in the full_rx_buffer
}
}
//--------------------------------------------------------------------------------------------------
// snippet_cyhal_tdm_async_receive
//--------------------------------------------------------------------------------------------------
static void snippet_cyhal_tdm_async_receive(void)
{
// Initialize the object as shown in Snippet 1
// Register a callback and set the callback argument to be a pointer to the tdm object, so that
// we can easily reference it from the callback handler.
cyhal_tdm_register_callback(&tdm, &tdm_event_handler_receive, &tdm);
// Subscribe to the async complete event so that we can queue up another transfer when this one
// completes
// Configure asynchronous transfers to use DMA to free up the CPU during transfers
active_rx_buffer = rx_buffer0;
full_rx_buffer = rx_buffer1;
cyhal_tdm_read_async(&tdm, active_rx_buffer, BUFFER_SIZE);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)
cy_rslt_t cyhal_tdm_start_rx(cyhal_tdm_t *obj)
Starts receiving data.
cy_rslt_t cyhal_tdm_read_async(cyhal_tdm_t *obj, void *rx, size_t rx_length)
Start TDM asynchronous read.
@ CYHAL_TDM_ASYNC_RX_COMPLETE
Pending async receive is complete.
Definition: cyhal_tdm.h:170

More Information

Code examples (Github)

API Reference

 TDM HAL Results
 TDM specific return codes.
 

Data Structures

struct  cyhal_tdm_pins_t
 Pins to use for one TDM direction. More...
 
struct  cyhal_tdm_config_t
 TDM Configuration. More...
 

Typedefs

typedef void(* cyhal_tdm_event_callback_t) (void *callback_arg, cyhal_tdm_event_t event)
 Handler for TDM event callbacks.
 

Enumerations

enum  cyhal_tdm_event_t {
  CYHAL_TDM_TX_NOT_FULL = 1 << 0 ,
  CYHAL_TDM_TX_HALF_EMPTY = 1 << 1 ,
  CYHAL_TDM_TX_EMPTY = 1 << 2 ,
  CYHAL_TDM_TX_OVERFLOW = 1 << 3 ,
  CYHAL_TDM_TX_UNDERFLOW = 1 << 4 ,
  CYHAL_TDM_ASYNC_TX_COMPLETE = 1 << 5 ,
  CYHAL_TDM_RX_NOT_EMPTY = 1 << 6 ,
  CYHAL_TDM_RX_HALF_FULL = 1 << 7 ,
  CYHAL_TDM_RX_FULL = 1 << 8 ,
  CYHAL_TDM_RX_OVERFLOW = 1 << 9 ,
  CYHAL_TDM_RX_UNDERFLOW = 1 << 10 ,
  CYHAL_TDM_ASYNC_RX_COMPLETE = 1 << 11
}
 TDM events. More...
 
enum  cyhal_tdm_output_t {
  CYHAL_TDM_TRIGGER_RX_HALF_FULL ,
  CYHAL_TDM_TRIGGER_TX_HALF_EMPTY
}
 Selections for TDM output signals
More...
 
enum  cyhal_tdm_word_select_width_t {
  CYHAL_TDM_WS_SINGLE ,
  CYHAL_TDM_WS_FULL
}
 Word select pulse width. More...
 

Functions

cy_rslt_t cyhal_tdm_init (cyhal_tdm_t *obj, const cyhal_tdm_pins_t *tx_pins, const cyhal_tdm_pins_t *rx_pins, const cyhal_tdm_config_t *config, cyhal_clock_t *clk)
 Initialize the TDM peripheral. More...
 
cy_rslt_t cyhal_tdm_init_cfg (cyhal_tdm_t *obj, const cyhal_tdm_configurator_t *cfg)
 Initialize the TDM peripheral using a configurator generated configuration struct. More...
 
void cyhal_tdm_free (cyhal_tdm_t *obj)
 Deinitialize the tdm object. More...
 
cy_rslt_t cyhal_tdm_set_sample_rate (cyhal_tdm_t *obj, uint32_t sample_rate_hz)
 Set the TDM sample rate. More...
 
cy_rslt_t cyhal_tdm_start_tx (cyhal_tdm_t *obj)
 Starts transmitting data. More...
 
cy_rslt_t cyhal_tdm_stop_tx (cyhal_tdm_t *obj)
 Stops transmitting data. More...
 
cy_rslt_t cyhal_tdm_clear_tx (cyhal_tdm_t *obj)
 Clears the tx hardware buffer. More...
 
cy_rslt_t cyhal_tdm_start_rx (cyhal_tdm_t *obj)
 Starts receiving data. More...
 
cy_rslt_t cyhal_tdm_stop_rx (cyhal_tdm_t *obj)
 Stops receiving data. More...
 
cy_rslt_t cyhal_tdm_clear_rx (cyhal_tdm_t *obj)
 Clears the rx hardware buffer. More...
 
cy_rslt_t cyhal_tdm_read (cyhal_tdm_t *obj, void *data, size_t *length)
 Read data synchronously. More...
 
cy_rslt_t cyhal_tdm_write (cyhal_tdm_t *obj, const void *data, size_t *length)
 Send data synchronously. More...
 
bool cyhal_tdm_is_tx_enabled (cyhal_tdm_t *obj)
 Checks if the transmit functionality is enabled for the specified TDM peripheral (regardless of whether data is currently queued for transmission). More...
 
bool cyhal_tdm_is_rx_enabled (cyhal_tdm_t *obj)
 Checks if the receive functionality is enabled for the specified TDM peripheral (regardless of whether any unread data has been received). More...
 
bool cyhal_tdm_is_tx_busy (cyhal_tdm_t *obj)
 Checks if the specified TDM peripheral is transmitting data, including if a pending async transfer is waiting to write more data to the transmit buffer. More...
 
bool cyhal_tdm_is_rx_busy (cyhal_tdm_t *obj)
 Checks if the specified TDM peripheral has received data that has not yet been read out of the hardware buffer. More...
 
cy_rslt_t cyhal_tdm_read_async (cyhal_tdm_t *obj, void *rx, size_t rx_length)
 Start TDM asynchronous read. More...
 
cy_rslt_t cyhal_tdm_write_async (cyhal_tdm_t *obj, const void *tx, size_t tx_length)
 Start TDM asynchronous write. More...
 
cy_rslt_t cyhal_tdm_set_async_mode (cyhal_tdm_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority)
 Set the mechanism that is used to perform TDM asynchronous transfers. More...
 
bool cyhal_tdm_is_read_pending (cyhal_tdm_t *obj)
 Checks if the specified TDM peripheral is in the process of reading data from the hardware buffer into RAM. More...
 
bool cyhal_tdm_is_write_pending (cyhal_tdm_t *obj)
 Checks if the specified TDM peripheral is in the process of writing data into the hardware buffer. More...
 
cy_rslt_t cyhal_tdm_abort_read_async (cyhal_tdm_t *obj)
 Abort TDM asynchronous read. More...
 
cy_rslt_t cyhal_tdm_abort_write_async (cyhal_tdm_t *obj)
 Abort TDM asynchronous write. More...
 
void cyhal_tdm_register_callback (cyhal_tdm_t *obj, cyhal_tdm_event_callback_t callback, void *callback_arg)
 Register a TDM callback handler. More...
 
void cyhal_tdm_enable_event (cyhal_tdm_t *obj, cyhal_tdm_event_t event, uint8_t intr_priority, bool enable)
 Configure TDM events. More...
 
cy_rslt_t cyhal_tdm_enable_output (cyhal_tdm_t *obj, cyhal_tdm_output_t output, cyhal_source_t *source)
 Enables the specified output signal. More...
 
cy_rslt_t cyhal_tdm_disable_output (cyhal_tdm_t *obj, cyhal_tdm_output_t output)
 Disables the specified output signal. More...
 

Data Structure Documentation

◆ cyhal_tdm_pins_t

struct cyhal_tdm_pins_t
Data Fields
cyhal_gpio_t sck Clock pin.
cyhal_gpio_t ws Word select.
cyhal_gpio_t data Data pin (sdo or sdi)
cyhal_gpio_t mclk Mclk input pin. Set to NC if an internal clock source should be used.

◆ cyhal_tdm_config_t

struct cyhal_tdm_config_t
Data Fields
bool is_tx_slave Configure TX to operate as slave (true) or master (false)
cyhal_tdm_word_select_width_t tx_ws_width Word select pulse width for TX direction.
bool is_rx_slave Configure RX to operate as slave (true) or master (false)
cyhal_tdm_word_select_width_t rx_ws_width Word select pulse width for RX direction.
uint32_t mclk_hz Frequency, in hertz, of the master clock if it is provided by an external pin.

If at least one mclk pin is not NC, this must be nonzero. If both mclk pins are NC, this must be zero.

uint8_t channel_length Number of bits in each channel.

See the implementation specific documentation for supported values.

uint8_t num_channels Number of channels.

Must be a value between 1 and 32. Not all implementations support all channel counts; see the implementation specific documentation for details.

uint32_t channel_mask Determines which channels are enabled.

Disabled channels still participate in the time slicing, but the contents of a disabled channel are silently discarded (for Rx) or sent as all 0's (for Tx). This is a mask, with each bit corresponding to the enabled state of one channel. Not all implementations permit masking of arbitrary channel combinations. See the implementation specific documentation for details.

uint8_t word_length Number of bits in each word.

Must be less than or equal to channel_length. If word_length < 32, the excess bits will be padded with 0's.

uint32_t sample_rate_hz Sample rate in Hz.

Enumeration Type Documentation

◆ cyhal_tdm_event_t

TDM events.

Enumerator
CYHAL_TDM_TX_NOT_FULL 

TX HW Buffer is not full.

CYHAL_TDM_TX_HALF_EMPTY 

TX HW Buffer is half empty.

CYHAL_TDM_TX_EMPTY 

TX HW Buffer is empty.

CYHAL_TDM_TX_OVERFLOW 

Attempt to write when TX HW Buffer is full.

CYHAL_TDM_TX_UNDERFLOW 

Interface ready to transfer data but HW TX buffer is empty.

CYHAL_TDM_ASYNC_TX_COMPLETE 

Pending async transmit is complete (but the HW buffer may still contain unsent data)

CYHAL_TDM_RX_NOT_EMPTY 

RX HW Buffer is not Empty.

CYHAL_TDM_RX_HALF_FULL 

RX HW Buffer is half full.

CYHAL_TDM_RX_FULL 

RX HW Buffer is FULL.

CYHAL_TDM_RX_OVERFLOW 

Attempt to write when RX HW Buffer is full.

CYHAL_TDM_RX_UNDERFLOW 

Attempt to read when HW RX buffer is empty.

CYHAL_TDM_ASYNC_RX_COMPLETE 

Pending async receive is complete.

◆ cyhal_tdm_output_t

Selections for TDM output signals

Enumerator
CYHAL_TDM_TRIGGER_RX_HALF_FULL 

An output signal should be triggered when the receive buffer is half full.

CYHAL_TDM_TRIGGER_TX_HALF_EMPTY 

An output signal should be triggered when the transmit buffer is half empty.

◆ cyhal_tdm_word_select_width_t

Word select pulse width.

Enumerator
CYHAL_TDM_WS_SINGLE 

Single SCK cycle.

CYHAL_TDM_WS_FULL 

Full channel length.

Function Documentation

◆ cyhal_tdm_init()

cy_rslt_t cyhal_tdm_init ( cyhal_tdm_t obj,
const cyhal_tdm_pins_t tx_pins,
const cyhal_tdm_pins_t rx_pins,
const cyhal_tdm_config_t config,
cyhal_clock_t clk 
)

Initialize the TDM peripheral.

It sets the default parameters for TDM peripheral, and configures its specifieds pins. If only one direction is to be used, then the pins for the other direction need not be specified (i.e. they may be set to NC). For example, if only RX is needed, tx_sck, tx_ws, and tx_sdo may all be set to NC. If one pin is specified for a direction, all pins for that direction must be specified.

Parameters
[out]objPointer to a TDM object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]tx_pinsPins for TDM transmit. If NULL, transmit functionality will be disabled.
[in]rx_pinsPins for TDM receive. If NULL, receive functionality will be disabled.
[in]configInitial block configuration
[in]clkClock source to use for this instance. If NULL, a dedicated clock divider will be allocated for this instance.
Returns
The status of the init request

◆ cyhal_tdm_init_cfg()

cy_rslt_t cyhal_tdm_init_cfg ( cyhal_tdm_t obj,
const cyhal_tdm_configurator_t cfg 
)

Initialize the TDM peripheral using a configurator generated configuration struct.

Parameters
[out]objPointer to a TDM object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]cfgConfiguration structure generated by a configurator.
Returns
The status of the init request

◆ cyhal_tdm_free()

void cyhal_tdm_free ( cyhal_tdm_t obj)

Deinitialize the tdm object.

Parameters
[in,out]objThe tdm object

◆ cyhal_tdm_set_sample_rate()

cy_rslt_t cyhal_tdm_set_sample_rate ( cyhal_tdm_t obj,
uint32_t  sample_rate_hz 
)

Set the TDM sample rate.

Parameters
[in]objThe TDM object
[in]sample_rate_hzSample rate in Hz
Returns
The status of the set sample rate request

◆ cyhal_tdm_start_tx()

cy_rslt_t cyhal_tdm_start_tx ( cyhal_tdm_t obj)

Starts transmitting data.

Transmission will continue until it is stopped by calling cyhal_tdm_stop_tx.

Parameters
[in]objThe TDM object
Returns
The status of the start request.

◆ cyhal_tdm_stop_tx()

cy_rslt_t cyhal_tdm_stop_tx ( cyhal_tdm_t obj)

Stops transmitting data.

This immediately terminates data transmission.

Parameters
[in]objThe TDM object
Returns
The status of the stop request.

◆ cyhal_tdm_clear_tx()

cy_rslt_t cyhal_tdm_clear_tx ( cyhal_tdm_t obj)

Clears the tx hardware buffer.

Parameters
[in]objThe tdm peripheral
Returns
The status of the clear request

◆ cyhal_tdm_start_rx()

cy_rslt_t cyhal_tdm_start_rx ( cyhal_tdm_t obj)

Starts receiving data.

Data will continue to be received until it is stopped by calling cyhal_tdm_stop_rx.

Parameters
[in]objThe TDM object
Returns
The status of the start request.

◆ cyhal_tdm_stop_rx()

cy_rslt_t cyhal_tdm_stop_rx ( cyhal_tdm_t obj)

Stops receiving data.

This immediately terminates data receipt.

Parameters
[in]objThe TDM object
Returns
The status of the stop request.

◆ cyhal_tdm_clear_rx()

cy_rslt_t cyhal_tdm_clear_rx ( cyhal_tdm_t obj)

Clears the rx hardware buffer.

Parameters
[in]objThe tdm peripheral
Returns
The status of the clear request

◆ cyhal_tdm_read()

cy_rslt_t cyhal_tdm_read ( cyhal_tdm_t obj,
void *  data,
size_t *  length 
)

Read data synchronously.

This will read the number of words specified by the length parameter, or the number of words that are currently available in the receive buffer, whichever is less, then return. The value pointed to by length will be updated to reflect the number of words that were actually read.

Parameters
[in]objThe TDM object
[out]dataThe buffer for receiving
[in,out]lengthNumber of words to (as configured in cyhal_tdm_config_t.word_length) read, updated with the number actually read
Returns
The status of the read request
Note
Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.
Returns
The status of the write request

◆ cyhal_tdm_write()

cy_rslt_t cyhal_tdm_write ( cyhal_tdm_t obj,
const void *  data,
size_t *  length 
)

Send data synchronously.

This will write either length words or until the write buffer is full, whichever is less, then return. The value pointed to by length will be updated to reflect the number of words that were actually written.

Note
This function only queues data into the write buffer; it does not block until the data has all been sent out over the wire.
Parameters
[in]objThe TDM object
[in]dataThe buffer for sending
[in,out]lengthNumber of words to write (as configured in cyhal_tdm_config_t.word_length, updated with the number actually written
Returns
The status of the write request
Note
Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.

◆ cyhal_tdm_is_tx_enabled()

bool cyhal_tdm_is_tx_enabled ( cyhal_tdm_t obj)

Checks if the transmit functionality is enabled for the specified TDM peripheral (regardless of whether data is currently queued for transmission).

The transmit functionality can be enabled by calling cyhal_tdm_start_tx and disabled by calling cyhal_tdm_stop_tx

Parameters
[in]objThe TDM peripheral to check
Returns
Whether the TDM transmit function is enabled.

◆ cyhal_tdm_is_rx_enabled()

bool cyhal_tdm_is_rx_enabled ( cyhal_tdm_t obj)

Checks if the receive functionality is enabled for the specified TDM peripheral (regardless of whether any unread data has been received).

The receive functionality can be enabled by calling cyhal_tdm_start_rx and disabled by calling cyhal_tdm_stop_rx

Parameters
[in]objThe TDM peripheral to check
Returns
Whether the TDM receive function is enabled.

◆ cyhal_tdm_is_tx_busy()

bool cyhal_tdm_is_tx_busy ( cyhal_tdm_t obj)

Checks if the specified TDM peripheral is transmitting data, including if a pending async transfer is waiting to write more data to the transmit buffer.

Parameters
[in]objThe TDM peripheral to check
Returns
Whether the TDM is still transmitting

◆ cyhal_tdm_is_rx_busy()

bool cyhal_tdm_is_rx_busy ( cyhal_tdm_t obj)

Checks if the specified TDM peripheral has received data that has not yet been read out of the hardware buffer.

This includes if an async read transfer is pending.

Parameters
[in]objThe TDM peripheral to check
Returns
Whether the TDM is still transmitting

◆ cyhal_tdm_read_async()

cy_rslt_t cyhal_tdm_read_async ( cyhal_tdm_t obj,
void *  rx,
size_t  rx_length 
)

Start TDM asynchronous read.

This will transfer rx_length words into the buffer pointed to by rx in the background. When the requested quantity of data has been read, the CYHAL_TDM_ASYNC_RX_COMPLETE event will be raised. See cyhal_tdm_register_callback and cyhal_tdm_enable_event.

cyhal_tdm_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer.

Note
Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.
Parameters
[in]objThe TDM object
[out]rxThe receive buffer.
[in]rx_lengthNumber of words (as configured in cyhal_tdm_config_t.word_length) to read.
Returns
The status of the read_async request

◆ cyhal_tdm_write_async()

cy_rslt_t cyhal_tdm_write_async ( cyhal_tdm_t obj,
const void *  tx,
size_t  tx_length 
)

Start TDM asynchronous write.

This will transfer tx_length words into the tx buffer in the background. When the requested quantity of data has been queued in the transmit buffer, the CYHAL_TDM_ASYNC_TX_COMPLETE event will be raised. See cyhal_tdm_register_callback and cyhal_tdm_enable_event.

cyhal_tdm_set_async_mode can be used to control whether this uses DMA or a SW (CPU-driven) transfer.

Note
Each word will be aligned to the next largest power of 2. For example, if the word length is 16 bits, each word will consume two bytes. But if the word length is 20, each word will consume 32 bytes.
Parameters
[in]objThe TDM object
[in]txThe transmit buffer.
[in]tx_lengthThe number of words to transmit.
Returns
The status of the transfer_async request

◆ cyhal_tdm_set_async_mode()

cy_rslt_t cyhal_tdm_set_async_mode ( cyhal_tdm_t obj,
cyhal_async_mode_t  mode,
uint8_t  dma_priority 
)

Set the mechanism that is used to perform TDM asynchronous transfers.

The default is SW.

Warning
The effect of calling this function while an async transfer is pending is undefined.
Parameters
[in]objThe TDM object
[in]modeThe transfer mode
[in]dma_priorityThe priority, if DMA is used. Valid values are the same as for cyhal_dma_init. If DMA is not selected, the only valid value is CYHAL_DMA_PRIORITY_DEFAULT, and no guarantees are made about prioritization.
Returns
The status of the set mode request

◆ cyhal_tdm_is_read_pending()

bool cyhal_tdm_is_read_pending ( cyhal_tdm_t obj)

Checks if the specified TDM peripheral is in the process of reading data from the hardware buffer into RAM.

Note
: This only checks whether there is an ongoing transfer (e.g. via cyhal_tdm_read_async) into RAM from the TDM peripheral's hardware buffer. It does not check whether unread data exists in the hardware buffer.
Parameters
[in]objThe TDM peripheral to check
Returns
Whether an asynchronous read operation is still in progress

◆ cyhal_tdm_is_write_pending()

bool cyhal_tdm_is_write_pending ( cyhal_tdm_t obj)

Checks if the specified TDM peripheral is in the process of writing data into the hardware buffer.

Note
: This only checks whether there is an ongoing transfer (e.g. via cyhal_tdm_transfer_async) from RAM into the TDM peripheral's hardware buffer. It does not check whether unwritten data exists in the hardware buffer.
Parameters
[in]objThe TDM peripheral to check
Returns
Whether an asynchronous write operation is still in progress

◆ cyhal_tdm_abort_read_async()

cy_rslt_t cyhal_tdm_abort_read_async ( cyhal_tdm_t obj)

Abort TDM asynchronous read.

This function does not perform any validation before aborting the transfer. Any validation which is required is the responsibility of the application.

Parameters
[in]objThe TDM object
Returns
The status of the abort_async_read request

◆ cyhal_tdm_abort_write_async()

cy_rslt_t cyhal_tdm_abort_write_async ( cyhal_tdm_t obj)

Abort TDM asynchronous write.

This function does not perform any validation before aborting the transfer. Any validation which is required is the responsibility of the application.

Parameters
[in]objThe TDM object
Returns
The status of the abort_async_write request

◆ cyhal_tdm_register_callback()

void cyhal_tdm_register_callback ( cyhal_tdm_t obj,
cyhal_tdm_event_callback_t  callback,
void *  callback_arg 
)

Register a TDM callback handler.

This function will be called when one of the events enabled by cyhal_tdm_enable_event occurs.

Parameters
[in]objThe TDM object
[in]callbackThe callback handler which will be invoked when the interrupt fires
[in]callback_argGeneric argument that will be provided to the callback when called

◆ cyhal_tdm_enable_event()

void cyhal_tdm_enable_event ( cyhal_tdm_t obj,
cyhal_tdm_event_t  event,
uint8_t  intr_priority,
bool  enable 
)

Configure TDM events.

When an enabled event occurs, the function specified by cyhal_tdm_register_callback will be called.

Parameters
[in]objThe TDM object
[in]eventThe TDM event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on specified events, False to turn off

◆ cyhal_tdm_enable_output()

cy_rslt_t cyhal_tdm_enable_output ( cyhal_tdm_t obj,
cyhal_tdm_output_t  output,
cyhal_source_t source 
)

Enables the specified output signal.

Parameters
[in]objThe TDM object
[in]outputWhich output signal to enable
[out]sourcePointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.
Returns
The status of the output enable

◆ cyhal_tdm_disable_output()

cy_rslt_t cyhal_tdm_disable_output ( cyhal_tdm_t obj,
cyhal_tdm_output_t  output 
)

Disables the specified output signal.

Parameters
[in]objThe TDM object
[in]outputWhich output signal to disable
Returns
The status of the disablement