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

Transmit and receive functionality
Configurable data rates
Configurable channel count and word size
Configurable interrupt and callback assignment from TDM events - cyhal_tdm_event_t

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_t      tdm;
    cyhal_tdm_pins_t tx_pins = { .sck = P5_1, .ws = P5_2, .data = P5_3, .mclk = NC };
    cyhal_tdm_config_t config =
    {
        .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)

Initializing as TDM receiver

    #if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)
    cyhal_tdm_t      tdm;
    cyhal_tdm_pins_t rx_pins = { .sck = P5_4, .ws = P5_5, .data = P5_6, .mclk = NC };
    cyhal_tdm_config_t config =
    {
        .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)

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))
    {
        cyhal_tdm_stop_tx(tdm);
    }
}
// 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)
{
    cyhal_tdm_t tdm;
    // 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_enable_event(&tdm, CYHAL_TDM_TX_EMPTY, CYHAL_ISR_PRIORITY_DEFAULT, true);
    cyhal_tdm_write_async(&tdm, tdm_tx_buffer, tdm_tx_buffer_len);
    cyhal_tdm_start_tx(&tdm);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)

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)
{
    cyhal_tdm_t tdm;
    // 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
    cyhal_tdm_enable_event(&tdm, CYHAL_TDM_ASYNC_TX_COMPLETE, CYHAL_ISR_PRIORITY_DEFAULT, true);
    // Configure asynchronous transfers to use DMA to free up the CPU during transfers
    cyhal_tdm_set_async_mode(&tdm, CYHAL_ASYNC_DMA, CYHAL_DMA_PRIORITY_DEFAULT);
    // 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);
    cyhal_tdm_start_tx(&tdm);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_TX)

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)
{
    cyhal_tdm_t tdm;
    // 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
    cyhal_tdm_enable_event(&tdm, CYHAL_TDM_ASYNC_RX_COMPLETE, CYHAL_ISR_PRIORITY_DEFAULT, true);
    // Configure asynchronous transfers to use DMA to free up the CPU during transfers
    cyhal_tdm_set_async_mode(&tdm, CYHAL_ASYNC_DMA, CYHAL_DMA_PRIORITY_DEFAULT);
    active_rx_buffer = rx_buffer0;
    full_rx_buffer   = rx_buffer1;
    cyhal_tdm_read_async(&tdm, active_rx_buffer, BUFFER_SIZE);
    cyhal_tdm_start_rx(&tdm);
}
#endif // if defined(CYHAL_DRIVER_AVAILABLE_TDM_RX)

More Information

Code examples (Github)

PSoC™ 6 MCU: Time Division Multiplexing (TDM)

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

enum 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

enum 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

enum 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]	obj	Pointer to a TDM object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	tx_pins	Pins for TDM transmit. If NULL, transmit functionality will be disabled.
[in]	rx_pins	Pins for TDM receive. If NULL, receive functionality will be disabled.
[in]	config	Initial block configuration
[in]	clk	Clock 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]	obj	Pointer to a TDM object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	cfg	Configuration 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] obj The 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]	obj	The TDM object
[in]	sample_rate_hz	Sample 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] obj The 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] obj The 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] obj The 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] obj The 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] obj The 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] obj The 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]	obj	The TDM object
[out]	data	The buffer for receiving
[in,out]	length	Number 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]	obj	The TDM object
[in]	data	The buffer for sending
[in,out]	length	Number 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] obj The 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] obj The 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] obj The 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] obj The 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]	obj	The TDM object
[out]	rx	The receive buffer.
[in]	rx_length	Number 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]	obj	The TDM object
[in]	tx	The transmit buffer.
[in]	tx_length	The 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]	obj	The TDM object
[in]	mode	The transfer mode
[in]	dma_priority	The 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] obj The 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] obj The 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] obj The 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] obj The 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]	obj	The TDM object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic 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]	obj	The TDM object
[in]	event	The TDM event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True 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]	obj	The TDM object
[in]	output	Which output signal to enable
[out]	source	Pointer 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]	obj	The TDM object
[in]	output	Which output signal to disable

Returns: The status of the disablement

General Description

Features

Quick Start

Code Snippets

Snippet 1: TDM Initialization and Configuration

Snippet 2: TDM Transmit One-shot

Snippet 3: TDM Transmit Streaming

Snippet 4: TDM Receive

More Information

API Reference

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ cyhal_tdm_pins_t

◆ cyhal_tdm_config_t

Enumeration Type Documentation

◆ cyhal_tdm_event_t

◆ cyhal_tdm_output_t

◆ cyhal_tdm_word_select_width_t

Function Documentation

◆ cyhal_tdm_init()

◆ cyhal_tdm_init_cfg()

◆ cyhal_tdm_free()

◆ cyhal_tdm_set_sample_rate()

◆ cyhal_tdm_start_tx()

◆ cyhal_tdm_stop_tx()

◆ cyhal_tdm_clear_tx()

◆ cyhal_tdm_start_rx()

◆ cyhal_tdm_stop_rx()

◆ cyhal_tdm_clear_rx()

◆ cyhal_tdm_read()

◆ cyhal_tdm_write()

◆ cyhal_tdm_is_tx_enabled()

◆ cyhal_tdm_is_rx_enabled()

◆ cyhal_tdm_is_tx_busy()

◆ cyhal_tdm_is_rx_busy()

◆ cyhal_tdm_read_async()

◆ cyhal_tdm_write_async()

◆ cyhal_tdm_set_async_mode()

◆ cyhal_tdm_is_read_pending()

◆ cyhal_tdm_is_write_pending()

◆ cyhal_tdm_abort_read_async()

◆ cyhal_tdm_abort_write_async()

◆ cyhal_tdm_register_callback()

◆ cyhal_tdm_enable_event()

◆ cyhal_tdm_enable_output()

◆ cyhal_tdm_disable_output()