i2stx: I2stx_v1_1

| i2stx Xilinx SDK Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List

Data Structures | Enumerations | Functions
I2stx_v1_1

## Data Structures
struct | XI2s_Tx_LogItem
| This structure is used to store log events. More...
struct | XI2s_Tx_Log
| The I2s Transmitter Log buffer. More...

## Enumerations
enum | XI2s_Tx_ChannelId { XI2S_TX_CHID0 = 0, XI2S_TX_CHID1, XI2S_TX_CHID2, XI2S_TX_CHID3, XI2S_TX_NUM_CHANNELS }
| These constants specify different channel ID's. More...

## Functions
int | XI2s_Tx_CfgInitialize (XI2s_Tx *InstancePtr, XI2stx_Config *CfgPtr, UINTPTR EffectiveAddr)
| This function initializes the I2S Transmitter. More...
void | XI2s_Tx_Enable (XI2s_Tx *InstancePtr, u8 Enable)
| This function enables/disables the I2s Transmitter. More...
void | XI2s_Tx_IntrEnable (XI2s_Tx *InstancePtr, u32 Mask)
| This function enables the specified interrupt of the I2s Transmitter. More...
void | XI2s_Tx_IntrDisable (XI2s_Tx *InstancePtr, u32 Mask)
| This function disables the specified interrupt of the I2s Transmitter. More...
int | XI2s_Tx_SetChMux (XI2s_Tx *InstancePtr, XI2s_Tx_ChannelId ChID, XI2s_Tx_ChMuxInput InputSource)
| This function sets the input source for the specified I2s channel. More...
u32 | XI2s_Tx_SetSclkOutDiv (XI2s_Tx *InstancePtr, u32 MClk, u32 Fs)
| This function calculates the SCLK Output divider value of the I2S timing generator. More...
void | XI2s_Tx_GetAesChStatus (XI2s_Tx *InstancePtr, u8 *AesChStatusBuf)
| This function gets the captured AES Channel Status bits. More...
void | XI2s_Tx_ClrAesChStatRegs (XI2s_Tx *InstancePtr)
| This function clears the captured AES Channel Status bits. More...
void | XI2s_Tx_JustifyEnable (XI2s_Tx *InstancePtr, u8 Enable)
| This function enables/disables the justification. More...
void | XI2s_Tx_Justify (XI2s_Tx *InstancePtr, XI2s_Tx_Justification Justify)
| This function is to enable right/left justification. More...
void | XI2s_Tx_LogWrite (XI2s_Tx *InstancePtr, XI2s_Tx_LogEvt Event, u8 Data)
| This function writes I2S Transmitter logs into the buffer. More...
XI2s_Tx_LogItem * | XI2s_Tx_LogRead (XI2s_Tx *InstancePtr)
| This function returns the next item in the logging buffer. More...
void | XI2s_Tx_LogReset (XI2s_Tx *InstancePtr)
| This function clears the contents of the logging buffer. More...
void | XI2s_Tx_LogDisplay (XI2s_Tx *InstancePtr)
| This function prints the contents of the logging buffer. More...
void | XI2s_Tx_IntrHandler (void *InstancePtr)
| This function is the interrupt handler for the I2S Transmitter driver. More...
int | XI2s_Tx_SetHandler (XI2s_Tx *InstancePtr, XI2s_Tx_HandlerType HandlerType, XI2s_Tx_Callback FuncPtr, void *CallbackRef)
| This function installs an asynchronous callback function for the given HandlerType: More...

## XI2S_Tx_Handlertype
enum | XI2s_Tx_HandlerType { XI2S_TX_HANDLER_AES_BLKCMPLT = 0, XI2S_TX_HANDLER_AES_BLKSYNCERR, XI2S_TX_HANDLER_AES_CHSTSUPD, XI2S_TX_HANDLER_AUD_UNDRFLW, XI2S_TX_NUM_HANDLERS }
| these constants specify different types of handlers and is used to differentiate interrupt requests from the I2s Transmitter peripheral. More...
#define | XI2S_TX_LOG_ITEM_BUFFER_SIZE (256)
| @ name Log Item Buffer Size More...

## XI2s_Tx_LogEvt
enum | XI2s_Tx_LogEvt { XI2S_TX_AES_BLKCMPLT_EVT, XI2S_TX_AES_BLKSYNCERR_EVT, XI2S_TX_AES_CHSTSUPD_EVT, XI2S_TX_AUD_UNDRFLW_EVT, XI2S_TX_LOG_EVT_INVALID }
| These constants specify different types of handlers and is used to differentiate interrupt requests from the I2S Transmitter peripheral. More...

## Macro Definition Documentation

#define XI2S_TX_LOG_ITEM_BUFFER_SIZE (256)

@ name Log Item Buffer Size

## Enumeration Type Documentation

enum XI2s_Tx_ChannelId

These constants specify different channel ID's.

Enumerator
XI2S_TX_CHID0 | Channel 0.
XI2S_TX_CHID1 | Channel 1.
XI2S_TX_CHID2 | Channel 2.
XI2S_TX_CHID3 | Channel 3.
XI2S_TX_NUM_CHANNELS | Number of Channel ID's.

enum XI2s_Tx_HandlerType

these constants specify different types of handlers and is used to differentiate interrupt requests from the I2s Transmitter peripheral.

Enumerator
XI2S_TX_HANDLER_AES_BLKCMPLT | AES Block Complete Handler.
XI2S_TX_HANDLER_AES_BLKSYNCERR | AES Block Sync Error Handler.
XI2S_TX_HANDLER_AES_CHSTSUPD | AES Channel Status Updated Handler.
XI2S_TX_HANDLER_AUD_UNDRFLW | Audio Underflow Detected Handler.
XI2S_TX_NUM_HANDLERS | Number of handler types.

enum XI2s_Tx_LogEvt

These constants specify different types of handlers and is used to differentiate interrupt requests from the I2S Transmitter peripheral.

Enumerator
XI2S_TX_AES_BLKCMPLT_EVT | AES Block Complete Event.
XI2S_TX_AES_BLKSYNCERR_EVT | AES Block Sync Error Event.
XI2S_TX_AES_CHSTSUPD_EVT | AES Channel Status Updated Event.
XI2S_TX_AUD_UNDRFLW_EVT | Audio Underflow Detected Event.
XI2S_TX_LOG_EVT_INVALID | Invalid Log Event.

## Function Documentation

int XI2s_Tx_CfgInitialize | ( | XI2s_Tx * | InstancePtr,
|  | XI2stx_Config * | CfgPtr,
|  | UINTPTR | EffectiveAddr
| ) |  |

This function initializes the I2S Transmitter.

This function must be called prior to using the core. Initialization of the I2S Transmitter includes setting up the instance data, and ensuring the hardware is in a quiescent state.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  CfgPtr | points to the configuration structure associated with the I2s Transmitter.
  EffectiveAddr | is the base address of the device. If address translation is being used, then this parameter must reflect the virtual base address. Otherwise, the physical address should be used.

Returns
  - XST_SUCCESS : if successful.
  - XST_FAILURE : otherwise.

Note
  None.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2s_Tx::IsReady, XI2s_Tx_Enable(), and XI2s_Tx_SelfTest().

Referenced by I2sSelfTestExample(), and I2sTxIntrExample().

void XI2s_Tx_ClrAesChStatRegs | ( | XI2s_Tx * | InstancePtr | ) |

This function clears the captured AES Channel Status bits.

This will clear all the 6 channel status registers.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx core instance.

Returns
  None.

References XI2S_TX_AES_CHSTS0_OFFSET, XI2S_TX_AES_CHSTS1_OFFSET, XI2S_TX_AES_CHSTS2_OFFSET, XI2S_TX_AES_CHSTS3_OFFSET, XI2S_TX_AES_CHSTS4_OFFSET, XI2S_TX_AES_CHSTS5_OFFSET, and XI2s_Tx_WriteReg.

void XI2s_Tx_Enable | ( | XI2s_Tx * | InstancePtr,
|  | u8 | Enable
| ) |  |

This function enables/disables the I2s Transmitter.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  Enable | specifies TRUE/FALSE value to either enable or disable the I2s Transmitter.

Returns
  None.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2s_Tx::IsStarted, XI2S_TX_CORE_CTRL_OFFSET, XI2s_Tx_ReadReg, XI2S_TX_REG_CTRL_EN_MASK, and XI2s_Tx_WriteReg.

Referenced by I2sTxIntrExample(), and XI2s_Tx_CfgInitialize().

void XI2s_Tx_GetAesChStatus | ( | XI2s_Tx * | InstancePtr,
|  | u8 * | AesChStatusBuf
| ) |  |

This function gets the captured AES Channel Status bits.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  AesChStatusBuf | is a pointer to a buffer that is used for writing the AES Channel Status bits, this needs to be allocated by user application

Returns
  None.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_AES_CHSTS0_OFFSET, and XI2s_Tx_ReadReg.

void XI2s_Tx_IntrDisable | ( | XI2s_Tx * | InstancePtr,
|  | u32 | Mask
| ) |  |

This function disables the specified interrupt of the I2s Transmitter.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  Mask | is a bit mask of the interrupts to be disabled.

Returns
  None.

See Also
  XI2stx_HW for the available interrupt masks.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_IRQCTRL_OFFSET, XI2s_Tx_ReadReg, and XI2s_Tx_WriteReg.

void XI2s_Tx_IntrEnable | ( | XI2s_Tx * | InstancePtr,
|  | u32 | Mask
| ) |  |

This function enables the specified interrupt of the I2s Transmitter.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  Mask | is a bit mask of the interrupts to be enabled.

Returns
  None.

See Also
  XI2stx_hw.h for the available interrupt masks.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_IRQCTRL_OFFSET, XI2s_Tx_ReadReg, and XI2s_Tx_WriteReg.

Referenced by I2sTxIntrExample().

void XI2s_Tx_IntrHandler | ( | void * | InstancePtr | ) |

This function is the interrupt handler for the I2S Transmitter driver.

This handler reads the pending interrupt from the I2S Transmitter peripheral, determines the source of the interrupts, clears the interrupts and calls callbacks accordingly.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx instance.

Returns
  None.

Note
  None.

References XI2s_Tx::AesBlkCmpltHandler, XI2s_Tx::AesBlkSyncErrHandler, XI2s_Tx::AudUndrflwHandler, XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2s_Tx::IsReady, XI2S_TX_AES_BLKCMPLT_EVT, XI2S_TX_AES_BLKSYNCERR_EVT, XI2S_TX_AES_CHSTSUPD_EVT, XI2S_TX_AUD_UNDRFLW_EVT, XI2S_TX_INTR_AES_BLKCMPLT_MASK, XI2S_TX_INTR_AES_BLKSYNCERR_MASK, XI2S_TX_INTR_AES_CHSTSUPD_MASK, XI2S_TX_INTR_AUDUNDRFLW_MASK, XI2S_TX_IRQCTRL_OFFSET, XI2S_TX_IRQSTS_OFFSET, XI2s_Tx_LogWrite(), and XI2s_Tx_ReadReg.

void XI2s_Tx_Justify | ( | XI2s_Tx * | InstancePtr,
|  | XI2s_Tx_Justification | Justify
| ) |  |

This function is to enable right/left justification.

Parameters

  InstancePtr | is a pointer to the XI2s Transmitter instance.
  Justify | is a enum to select the left or right justfication. XI2S_TX_JUSTIFY_LEFT : Left justication XI2S_TX_JUSTIFY_RIGHT : Right justification

Returns
  None.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_CORE_CTRL_OFFSET, XI2s_Tx_ReadReg, XI2S_TX_REG_CTRL_LORJF_MASK, and XI2s_Tx_WriteReg.

void XI2s_Tx_JustifyEnable | ( | XI2s_Tx * | InstancePtr,
|  | u8 | Enable
| ) |  |

This function enables/disables the justification.

Parameters

  InstancePtr | is a pointer to the XI2s Transmitter instance.
  Enable | specifies TRUE/FALSE value to either enable or disable the justification.

Returns
  None.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_CORE_CTRL_OFFSET, XI2s_Tx_ReadReg, XI2S_TX_REG_CTRL_JFE_MASK, and XI2s_Tx_WriteReg.

void XI2s_Tx_LogDisplay | ( | XI2s_Tx * | InstancePtr | ) |

This function prints the contents of the logging buffer.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx instance.

Returns
  None.

Note
  None.

References XI2s_Tx::Config, XI2stx_Config::DeviceId, XI2s_Tx_LogItem::Event, XI2S_TX_AES_BLKCMPLT_EVT, XI2S_TX_AES_BLKSYNCERR_EVT, XI2S_TX_AES_CHSTSUPD_EVT, XI2S_TX_AUD_UNDRFLW_EVT, XI2S_TX_LOG_EVT_INVALID, and XI2s_Tx_LogRead().

XI2s_Tx_LogItem* XI2s_Tx_LogRead | ( | XI2s_Tx * | InstancePtr | ) |

This function returns the next item in the logging buffer.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx instance.

Returns
  When the buffer is filled, the next log item is returned. When the buffer is empty, NULL is returned.

Note
  None.

References XI2s_Tx_Log::Head, XI2s_Tx_Log::Items, XI2s_Tx::Log, and XI2s_Tx_Log::Tail.

Referenced by XI2s_Tx_LogDisplay().

void XI2s_Tx_LogReset | ( | XI2s_Tx * | InstancePtr | ) |

This function clears the contents of the logging buffer.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx instance.

Returns
  None.

Note
  None.

References XI2s_Tx_Log::Head, XI2s_Tx_Log::IsEnabled, XI2s_Tx::Log, and XI2s_Tx_Log::Tail.

void XI2s_Tx_LogWrite | ( | XI2s_Tx * | InstancePtr,
|  | XI2s_Tx_LogEvt | Event,
|  | u8 | Data
| ) |  |

This function writes I2S Transmitter logs into the buffer.

Parameters

  InstancePtr | is a pointer to the XI2s_Tx instance.
  Event | is the log event type.
  Data | is the log data.

Returns
  None.

Note
  Log write can be done only if the log is enabled.

References XI2s_Tx_LogItem::Data, XI2s_Tx_LogItem::Event, XI2s_Tx_Log::Head, XI2s_Tx_Log::IsEnabled, XI2s_Tx_Log::Items, XI2s_Tx::Log, XI2s_Tx_Log::Tail, and XI2S_TX_LOG_EVT_INVALID.

Referenced by XI2s_Tx_IntrHandler().

int XI2s_Tx_SetChMux | ( | XI2s_Tx * | InstancePtr,
|  | XI2s_Tx_ChannelId | ChID,
|  | XI2s_Tx_ChMuxInput | InputSource
| ) |  |

This function sets the input source for the specified I2s channel.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  ChID | specifies the I2s channel
  InputSource | specifies the input source

Returns
  - XST_SUCCESS : if successful.
  - XST_FAILURE : if the I2s channel is invalid.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2S_TX_CH01_OFFSET, XI2S_TX_CHMUX_AXIS_01, XI2S_TX_CHMUX_AXIS_23, XI2S_TX_CHMUX_AXIS_45, XI2S_TX_CHMUX_AXIS_67, XI2S_TX_CHMUX_WAVEGEN, XI2S_TX_NUM_CHANNELS, and XI2s_Tx_WriteReg.

Referenced by I2sTxIntrExample().

int XI2s_Tx_SetHandler | ( | XI2s_Tx * | InstancePtr,
|  | XI2s_Tx_HandlerType | HandlerType,
|  | XI2s_Tx_Callback | FuncPtr,
|  | void * | CallbackRef
| ) |  |

This function installs an asynchronous callback function for the given HandlerType:

    HandlerType                              Callback Function
    --------------------------------         -------------------------
    (XI2S_TX_HANDLER_AES_BLKCMPLT)            AesBlkCmpltHandler
    (XI2S_TX_HANDLER_AES_BLKSYNCERR)          AesBlkSyncErrHandler
    (XI2S_TX_HANDLER_AES_CHSTSUPD)            AesChStsUpdHandler
    (XI2S_TX_HANDLER_AUD_UNDRFLW)             AudUndrflwHandler

Parameters

  InstancePtr | is a pointer to the XI2s_Tx core instance.
  HandlerType | specifies the type of handler.
  FuncPtr | is a pointer to the callback function.
  CallbackRef | is a reference pointer passed on actual calling of the callback function.

Returns
  - XST_SUCCESS if callback function installed successfully.
  - XST_INVALID_PARAM when HandlerType is invalid.

Note
  Invoking this function for a handler that already has been installed replaces it with the new handler.

References XI2s_Tx::AesBlkCmpltHandler, XI2s_Tx::AesBlkSyncErrHandler, XI2s_Tx::AudUndrflwHandler, XI2S_TX_HANDLER_AES_BLKCMPLT, XI2S_TX_HANDLER_AES_BLKSYNCERR, XI2S_TX_HANDLER_AES_CHSTSUPD, XI2S_TX_HANDLER_AUD_UNDRFLW, and XI2S_TX_NUM_HANDLERS.

Referenced by I2sTxIntrExample().

u32 XI2s_Tx_SetSclkOutDiv | ( | XI2s_Tx * | InstancePtr,
|  | u32 | MClk,
|  | u32 | Fs
| ) |  |

This function calculates the SCLK Output divider value of the I2S timing generator.

Parameters

  InstancePtr | is a pointer to the I2s Transmitter instance.
  MClk | is the frequency of the MClk.
  Fs | is the sampling frequency of the system. Divider value for the SCLK generation, MCLK/SCLK = SCLKOUT_DIV x 2 i.e. MCLK = 384xFs, SCLK = 48xFs (2x24bits) -> SCLKOUT_DIV = MCLK/SCLK/2 = 4 Valid values are 1 through 15.

Returns
  - XST_FAILURE if SCLK Output divider is not calculated to be a positive integer.
  - XST_SUCCESS, otherwise.

References XI2stx_Config::BaseAddress, XI2s_Tx::Config, XI2stx_Config::DWidth, XI2S_TX_TMR_CTRL_OFFSET, and XI2s_Tx_WriteReg.

Referenced by I2sTxIntrExample().