Functions

General Description

This section describes the CSDIDAC Function Prototypes.

Functions
cy_en_csdidac_status_t	Cy_CSDIDAC_Init (const cy_stc_csdidac_config_t *config, cy_stc_csdidac_context_t *context)
	Captures the CSD HW block and configures it to the default state. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_DeInit (cy_stc_csdidac_context_t *context)
	Stops the middleware operation and releases the CSD HW block. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_WriteConfig (const cy_stc_csdidac_config_t *config, cy_stc_csdidac_context_t *context)
	Updates the CSDIDAC middleware with the desired configuration. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_Wakeup (const cy_stc_csdidac_context_t *context)
	Provides a delay required for the CSD HW block to settle after a wakeup from CPU / System Deep Sleep. More...
cy_en_syspm_status_t	Cy_CSDIDAC_DeepSleepCallback (cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
	The callback function to prepare the CSDIDAC before entering CPU / System Deep Sleep. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_Save (cy_stc_csdidac_context_t *context)
	Saves the state of the CSDIDAC middleware so the functionality can be restored later. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_Restore (cy_stc_csdidac_context_t *context)
	Resumes the middleware operation if the Cy_CSDIDAC_Save() function was called previously. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_OutputEnable (cy_en_csdidac_choice_t ch, int32_t current, cy_stc_csdidac_context_t *context)
	Enables an IDAC output with a specified current. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_OutputEnableExt (cy_en_csdidac_choice_t outputCh, cy_en_csdidac_polarity_t polarity, cy_en_csdidac_lsb_t lsbIndex, uint32_t idacCode, cy_stc_csdidac_context_t *context)
	Enables an IDAC output with the specified polarity, LSB, and IDAC code. More...
cy_en_csdidac_status_t	Cy_CSDIDAC_OutputDisable (cy_en_csdidac_choice_t ch, cy_stc_csdidac_context_t *context)
	Disables a specified IDAC output. More...

Function Documentation

Cy_CSDIDAC_Init()

cy_en_csdidac_status_t Cy_CSDIDAC_Init	(	const cy_stc_csdidac_config_t *	config,
		cy_stc_csdidac_context_t *	context
	)

Captures the CSD HW block and configures it to the default state.

This function is called by the application program prior to calling any other middleware function.

Initializes the CSDIDAC middleware. Acquires, locks, and initializes the CSD HW block by using the low-level CSD driver. The function performs the following tasks:

• Verifies the input parameters. The CY_CSDIDAC_BAD_PARAM is returned if verification fails.
• Acquires and locks the CSD HW block for use of the CSDIDAC, if the CSD HW block is in a free state.
• If the CSD HW block is acquired, it is initialized with the CSDIDAC middleware by the default configuration. The output pins are not connected to the CSD HW block. The outputs are disabled and CY_CSDIDAC_SUCCESS is returned.

To connect an output pin and enable an output current, the Cy_CSDIDAC_OutputEnable() or Cy_CSDIDAC_OutputEnableExt() functions are used. If there is no CSD HW block, the CY_CSDIDAC_HW_BUSY status is returned, and the CSDIDAC middleware waits for the CSD HW block to be in the idle state to initialize.

Parameters

config	The pointer to the configuration structure cy_stc_csdidac_config_t that contains the CSDIDAC middleware initial configuration data generated by the CSD personality of the ModusToolbox Device Configurator tool.
context	The pointer to the CSDIDAC context structure cy_stc_csdidac_context_t passed by the user. After the initialization, this structure contains both CSDIDAC configuration and internal data. It is used during the whole CSDIDAC operation.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.
• CY_CSDIDAC_HW_LOCKED - The CSD HW block is already in use by other middleware.
• CY_CSDIDAC_HW_FAILURE - The CSD HW block failure.
• CY_CSDIDAC_BAD_CONFIGURATION - The CSDIDAC configuration structure initialization issue.

Cy_CSDIDAC_DeInit()

cy_en_csdidac_status_t Cy_CSDIDAC_DeInit

(

cy_stc_csdidac_context_t *

context

)

Stops the middleware operation and releases the CSD HW block.

If any output channel is enabled, it will be disabled and disconnected.

After the CSDIDAC middleware is stopped, the CSD HW block may be reconfigured by the application program or other middleware for any other usage.

When the middleware operation is stopped by the Cy_CSDIDAC_DeInit() function, a subsequent call of the Cy_CSDIDAC_Init() function repeats the initialization process. However, to implement Time-multiplexed mode (sharing the CSD HW Block between multiple middleware), the Cy_CSDIDAC_Save() and Cy_CSDIDAC_Restore() functions are used instead of the Cy_CSDIDAC_DeInit() and Cy_CSDIDAC_Init() functions.

Parameters

context

The pointer to the CSDIDAC context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.
• CY_CSDIDAC_HW_LOCKED - The CSD HW block is already in use by other middleware.
• CY_CSDIDAC_HW_FAILURE - A CSD HW block failure.

Cy_CSDIDAC_WriteConfig()

cy_en_csdidac_status_t Cy_CSDIDAC_WriteConfig	(	const cy_stc_csdidac_config_t *	config,
		cy_stc_csdidac_context_t *	context
	)

Updates the CSDIDAC middleware with the desired configuration.

This function sets the desired CSDIDAC middleware configuration. The function performs the following:

• Verifies the input parameters
• Verifies whether the CSD HW block is captured by the CSDIDAC middleware and that there are no active IDAC outputs.
• Initializes the CSD HW block registers with data passed through the config parameter of this function if the above verifications are successful.
• Returns the status code regarding the function execution result.

Parameters

config	The pointer to the CSDIDAC configuration structure to be updated.
context	The pointer to the CSDIDAC context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.
• CY_CSDIDAC_HW_BUSY - Any IDAC output is enabled. The operation cannot be completed.
• CY_CSDIDAC_HW_LOCKED - The CSD HW block is already in use by other middleware.
• CY_CSDIDAC_BAD_CONFIGURATION - The CSDIDAC configuration structure initialization issue.

Cy_CSDIDAC_Wakeup()

cy_en_csdidac_status_t Cy_CSDIDAC_Wakeup

(

const cy_stc_csdidac_context_t *

context

)

Provides a delay required for the CSD HW block to settle after a wakeup from CPU / System Deep Sleep.

This function provides a delay after exiting CPU / System Deep Sleep. After the CSD HW block has been powered off, an extra delay is required to establish the CSD HW block correct operation.

Parameters

context

The pointer to the CSDIDAC context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL.

Cy_CSDIDAC_DeepSleepCallback()

cy_en_syspm_status_t Cy_CSDIDAC_DeepSleepCallback	(	cy_stc_syspm_callback_params_t *	callbackParams,
		cy_en_syspm_callback_mode_t	mode
	)

The callback function to prepare the CSDIDAC before entering CPU / System Deep Sleep.

This function handles CPU active to CPU / System Deep Sleep power mode transition for the CSDIDAC middleware. Calling this function directly from the application program is not recommended. Instead, Cy_SysPm_CpuEnterDeepSleep() is used for CPU active to CPU / System Deep Sleep power mode transition of the device.

Note

After the CPU Deep Sleep transition, the device automatically goes to System Deep Sleep if all conditions are fulfilled: another core is in CPU Deep Sleep, all the peripherals are ready to System Deep Sleep, etc. (see details in the device TRM).

For the CSDIDAC middleware correct operation during CPU active to CPU / System Deep Sleep mode transition, a callback to this API is registered using the Cy_SysPm_RegisterCallback() function with CY_SYSPM_DEEPSLEEP type. After the callback is registered, this function is called by the Cy_SysPm_CpuEnterDeepSleep() function to prepare the middleware for the device power mode transition.

When this function is called with CY_SYSPM_CHECK_READY as an input, this function returns CY_SYSPM_SUCCESS if no output is enabled. Otherwise, CY_SYSPM_FAIL is returned. If CY_SYSPM_FAIL status is returned, a device cannot change power mode. To provide such a transition, the application program disables all the enabled IDAC outputs.

Parameters

callbackParams	Refer to the description of the cy_stc_syspm_callback_params_t type in the Peripheral Driver Library documentation.
mode	Refer to the description of the cy_en_syspm_callback_mode_t type in the Peripheral Driver Library documentation.

Returns

Returns the status of the operation requested by the mode parameter:

• CY_SYSPM_SUCCESS - CPU / System Deep Sleep power mode can be entered.
• CY_SYSPM_FAIL - CPU / System Deep Sleep power mode cannot be entered.

Cy_CSDIDAC_Save()

cy_en_csdidac_status_t Cy_CSDIDAC_Save

(

cy_stc_csdidac_context_t *

context

)

Saves the state of the CSDIDAC middleware so the functionality can be restored later.

This function, along with Cy_CSDIDAC_Restore(), is specifically designed to support time multiplexing of the CSD HW block between multiple middleware. When the CSD HW block is shared by more than one middleware, this function can be used to save the current state of the CSDIDAC middleware and the CSD HW block prior to releasing the CSD HW block for use by other middleware.

This function performs the following operations:

• Saves the current configuration of the CSD HW block and CSDIDAC middleware.
• Configures the output pins to the default state and disconnects them from the CSD HW block. Releases the CSD HW block.

Parameters

context

The pointer to the CSDIDAC context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed. The operation is not completed.
• CY_CSDIDAC_HW_LOCKED - The CSD HW block is already in use by other middleware. The CSDIDAC middleware cannot save the state without the initialization or restore operation.
• CY_CSDIDAC_HW_FAILURE - A CSD HW block failure.

Cy_CSDIDAC_Restore()

cy_en_csdidac_status_t Cy_CSDIDAC_Restore

(

cy_stc_csdidac_context_t *

context

)

Resumes the middleware operation if the Cy_CSDIDAC_Save() function was called previously.

This function, along with the Cy_CSDIDAC_Save() function, is specifically designed to support the CSD HW block time-multiplexing among multiple middleware. When the CSD HW block is shared by more than one middleware, this function can be used to restore the CSD HW block previous state and the CSDIDAC middleware saved using the Cy_CSDIDAC_Save() function.

This function performs the Cy_CSDIDAC_Init() function, part tasks namely captures the CSD HW block. Use the Cy_CSDIDAC_Save() and Cy_CSDIDAC_Restore() functions to implement Time-multiplexed mode instead of using the Cy_CSDIDAC_DeInit() and Cy_CSDIDAC_Init() functions.

Parameters

context

The pointer to the CSDIDAC middleware context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.
• CY_CSDIDAC_HW_LOCKED - The CSD HW block is already in use by another middleware.
• CY_CSDIDAC_HW_FAILURE - The CSD HW block failure.

Cy_CSDIDAC_OutputEnable()

cy_en_csdidac_status_t Cy_CSDIDAC_OutputEnable	(	cy_en_csdidac_choice_t	ch,
		int32_t	current,
		cy_stc_csdidac_context_t *	context
	)

Enables an IDAC output with a specified current.

This function performs the following:

• Verifies the input parameters.
• Identifies LSB and IDAC code required to generate the specified output current and configures the CSD HW block accordingly.
• Configures and enables the CSDIDAC specified output and returns the status code.

Parameters

ch	The CSDIDAC supports two outputs (A and B), this parameter specifies the output to be enabled.
current	A current value for an IDAC output in nA with a sign. If the parameter is positive, a sourcing current is generated. If the parameter is negative, the sinking current is generated. The middleware identifies LSB and code values required to achieve the specified output current. The middleware chooses the minimum possible LSB to generate the current to minimize a quantization error. NOTE! the quantization error in the output current based on the LSB size (37.5/ 75/300/600/2400/4800 nA). For instance, if this function is called to set 123456 nA, the actual output current is rounded to the nearest value of multiple to 2400 nA, i.e 122400 nA. The absolute value of this parameter is in the range from 0x00u to CY_CSDIDAC_MAX_CURRENT_NA.
context	The pointer to the CSDIDAC middleware context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.

Cy_CSDIDAC_OutputEnableExt()

cy_en_csdidac_status_t Cy_CSDIDAC_OutputEnableExt	(	cy_en_csdidac_choice_t	outputCh,
		cy_en_csdidac_polarity_t	polarity,
		cy_en_csdidac_lsb_t	lsbIndex,
		uint32_t	idacCode,
		cy_stc_csdidac_context_t *	context
	)

Enables an IDAC output with the specified polarity, LSB, and IDAC code.

This function performs the following:

• Verifies the input parameters.
• Configures and enables the specified output of CSDIDAC and returns the status code.

Parameters

outputCh	CSDIDAC supports two outputs, this parameter specifies the output to be enabled.
polarity	The polarity to be set for the specified IDAC.
lsbIndex	The LSB to be set for the specified IDAC.
idacCode	The code value for the specified IDAC in the range from 0 u to CY_CSDIDAC_MAX_CODE.
context	The pointer to the CSDIDAC middleware context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.

Cy_CSDIDAC_OutputDisable()

cy_en_csdidac_status_t Cy_CSDIDAC_OutputDisable	(	cy_en_csdidac_choice_t	ch,
		cy_stc_csdidac_context_t *	context
	)

Disables a specified IDAC output.

The function performs the following:

• Verifies the input parameters.
• Disables the specified output of CSDIDAC and returns the status code.

Parameters

ch	The channel to disconnect.
context	The pointer to the CSDIDAC middleware context structure cy_stc_csdidac_context_t.

Returns

The function returns the status of its operation.

• CY_CSDIDAC_SUCCESS - The operation is performed successfully.
• CY_CSDIDAC_BAD_PARAM - The input pointer is NULL or an invalid parameter is passed.