Generic DAC Driver. More...

Collaboration diagram for DAC Driver:

Detailed Description

Generic DAC Driver.

This module implements a generic DAC (Digital to Analog Converter) driver.

Precondition: In order to use the MAC driver the HAL_USE_DAC option must be enabled in halconf.h.

Macros
#define	DAC_MAX_CHANNELS 2
	Maximum number of DAC channels per unit. More...

DAC configuration options
#define	DAC_USE_WAIT TRUE
	Enables synchronous APIs. More...

#define	DAC_USE_MUTUAL_EXCLUSION TRUE
	Enables the `dacAcquireBus()` and `dacReleaseBus()` APIs. More...

Low level driver helper macros
#define	_dac_wait_s(dacp) osalThreadSuspendS(&(dacp)->thread)
	Waits for operation completion. More...

#define	_dac_reset_i(dacp) osalThreadResumeI(&(dacp)->thread, MSG_RESET)
	Resumes a thread waiting for a conversion completion. More...

#define	_dac_reset_s(dacp) osalThreadResumeS(&(dacp)->thread, MSG_RESET)
	Resumes a thread waiting for a conversion completion. More...

#define	_dac_wakeup_isr(dacp)
	Wakes up the waiting thread. More...

#define	_dac_timeout_isr(dacp)
	Wakes up the waiting thread with a timeout message. More...

#define	_dac_isr_half_code(dacp)
	Common ISR code, half buffer event. More...

#define	_dac_isr_full_code(dacp)
	Common ISR code, full buffer event. More...

#define	_dac_isr_error_code(dacp, err)
	Common ISR code, error event. More...

Configuration options
#define	PLATFORM_DAC_USE_DAC1 FALSE
	DAC1 CH1 driver enable switch. More...

Typedefs
typedef uint32_t	dacchannel_t
	Type of a DAC channel index. More...

typedef struct DACDriver	DACDriver
	Type of a structure representing an DAC driver. More...

typedef uint16_t	dacsample_t
	Type representing a DAC sample. More...

typedef void(*	daccallback_t) (DACDriver dacp, dacsample_t buffer, size_t n)
	DAC notification callback type. More...

typedef void(*	dacerrorcallback_t) (DACDriver *dacp, dacerror_t err)
	DAC error callback type. More...

Data Structures
struct	DACConversionGroup
	DAC Conversion group structure. More...

struct	DACConfig
	Driver configuration structure. More...

struct	DACDriver
	Structure representing a DAC driver. More...

Functions
void	dacInit (void)
	DAC Driver initialization. More...

void	dacObjectInit (DACDriver *dacp)
	Initializes the standard part of a `DACDriver` structure. More...

void	dacStart (DACDriver dacp, const DACConfig config)
	Configures and activates the DAC peripheral. More...

void	dacStop (DACDriver *dacp)
	Deactivates the DAC peripheral. More...

void	dacPutChannelX (DACDriver *dacp, dacchannel_t channel, dacsample_t sample)
	Outputs a value directly on a DAC channel. More...

void	dacStartConversion (DACDriver dacp, const DACConversionGroup grpp, dacsample_t *samples, size_t depth)
	Starts a DAC conversion. More...

void	dacStartConversionI (DACDriver dacp, const DACConversionGroup grpp, dacsample_t *samples, size_t depth)
	Starts a DAC conversion. More...

void	dacStopConversion (DACDriver *dacp)
	Stops an ongoing conversion. More...

void	dacStopConversionI (DACDriver *dacp)
	Stops an ongoing conversion. More...

msg_t	dacConvert (DACDriver dacp, const DACConversionGroup grpp, dacsample_t *samples, size_t depth)
	Performs a DAC conversion. More...

void	dacAcquireBus (DACDriver *dacp)
	Gains exclusive access to the DAC bus. More...

void	dacReleaseBus (DACDriver *dacp)
	Releases exclusive access to the DAC bus. More...

void	dac_lld_init (void)
	Low level DAC driver initialization. More...

void	dac_lld_start (DACDriver *dacp)
	Configures and activates the DAC peripheral. More...

void	dac_lld_stop (DACDriver *dacp)
	Deactivates the DAC peripheral. More...

void	dac_lld_put_channel (DACDriver *dacp, dacchannel_t channel, dacsample_t sample)
	Outputs a value directly on a DAC channel. More...

void	dac_lld_start_conversion (DACDriver *dacp)
	Starts a DAC conversion. More...

void	dac_lld_stop_conversion (DACDriver *dacp)
	Stops an ongoing conversion. More...

Enumerations

Variables
DACDriver	DACD1
	DAC1 driver identifier. More...

Macro Definition Documentation

#define DAC_USE_WAIT TRUE

Enables synchronous APIs.

Note: Disabling this option saves both code and data space.

Definition at line 47 of file hal_dac.h.

#define DAC_USE_MUTUAL_EXCLUSION TRUE

Enables the dacAcquireBus() and dacReleaseBus() APIs.

Note: Disabling this option saves both code and data space.

Definition at line 55 of file hal_dac.h.

#define _dac_wait_s ( dacp ) osalThreadSuspendS(&(dacp)->thread)

Waits for operation completion.

This function waits for the driver to complete the current operation.

Precondition: An operation must be running while the function is invoked.

Note: No more than one thread can wait on a DAC driver using this function.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 102 of file hal_dac.h.

#define _dac_reset_i ( dacp ) osalThreadResumeI(&(dacp)->thread, MSG_RESET)

Resumes a thread waiting for a conversion completion.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 111 of file hal_dac.h.

Referenced by dacStopConversionI().

#define _dac_reset_s ( dacp ) osalThreadResumeS(&(dacp)->thread, MSG_RESET)

Resumes a thread waiting for a conversion completion.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 120 of file hal_dac.h.

Referenced by dacStopConversion().

#define _dac_wakeup_isr ( dacp )

Value:

{                                             \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(dacp)->thread, MSG_OK);                               \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 129 of file hal_dac.h.

#define _dac_timeout_isr ( dacp )

Value:

{                                            \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(dacp)->thread, MSG_TIMEOUT);                          \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread with a timeout message.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 142 of file hal_dac.h.

#define _dac_isr_half_code ( dacp )

Value:

{                                          \
  if ((dacp)->grpp->end_cb != NULL) {                                       \
    (dacp)->grpp->end_cb(dacp, (dacp)->samples, (dacp)->depth / 2);         \
  }                                                                         \
}

Common ISR code, half buffer event.

This code handles the portable part of the ISR code:

Callback invocation.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 168 of file hal_dac.h.

#define _dac_isr_full_code ( dacp )

Value:

{                                          \
  if ((dacp)->grpp->end_cb != NULL) {                                       \
    if ((dacp)->depth > 1) {                                                \
      /* Invokes the callback passing the 2nd half of the buffer.*/         \
      size_t half = (dacp)->depth / 2;                                      \
      size_t half_index = half * (dacp)->grpp->num_channels;                \
      (dacp)->grpp->end_cb(dacp, (dacp)->samples + half_index, half);       \
    }                                                                       \
    else {                                                                  \
      /* Invokes the callback passing the whole buffer.*/                   \
      (dacp)->grpp->end_cb(dacp, (dacp)->samples, (dacp)->depth);           \
    }                                                                       \
  }                                                                         \
}

Common ISR code, full buffer event.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 188 of file hal_dac.h.

#define _dac_isr_error_code	(	dacp,
		err
	)

Value:

{                                    \
  dac_lld_stop_conversion(dacp);                                            \
  if ((dacp)->grpp->error_cb != NULL) {                                     \
    (dacp)->state = DAC_ERROR;                                              \
    (dacp)->grpp->error_cb(dacp, err);                                      \
    if ((dacp)->state == DAC_ERROR)                                         \
      (dacp)->state = DAC_READY;                                            \
  }                                                                         \
  (dacp)->grpp = NULL;                                                      \
  _dac_timeout_isr(dacp);                                                   \
}

Common ISR code, error event.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread timeout signaling, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	err	platform dependent error code

Function Class:Not an API, this function is for internal use only.

Definition at line 218 of file hal_dac.h.

#define DAC_MAX_CHANNELS 2

Maximum number of DAC channels per unit.

Definition at line 37 of file hal_dac_lld.h.

Referenced by dacPutChannelX().

#define PLATFORM_DAC_USE_DAC1 FALSE

DAC1 CH1 driver enable switch.

If set to TRUE the support for DAC1 channel 1 is included.

Note: The default is FALSE.

Definition at line 53 of file hal_dac_lld.h.

Typedef Documentation

typedef uint32_t dacchannel_t

Type of a DAC channel index.

Definition at line 68 of file hal_dac_lld.h.

typedef struct DACDriver DACDriver

Type of a structure representing an DAC driver.

Definition at line 73 of file hal_dac_lld.h.

typedef uint16_t dacsample_t

Type representing a DAC sample.

Definition at line 78 of file hal_dac_lld.h.

typedef void(* daccallback_t) (DACDriver *dacp, dacsample_t *buffer, size_t n)

DAC notification callback type.

Parameters

[in]	dacp	pointer to the `DACDriver` object triggering the
[in]	buffer	pointer to the next semi-buffer to be filled
[in]	n	number of buffer rows available starting from `buffer` callback

Definition at line 98 of file hal_dac_lld.h.

typedef void(* dacerrorcallback_t) (DACDriver *dacp, dacerror_t err)

DAC error callback type.

Parameters

[in]	dacp	pointer to the `DACDriver` object triggering the callback
[in]	err	DAC error code

Definition at line 107 of file hal_dac_lld.h.

Enumeration Type Documentation

enum dacstate_t

Driver state machine possible states.

Enumerator
DAC_UNINIT	Not initialized.
DAC_STOP	Stopped.
DAC_READY	Ready.
DAC_ACTIVE	Exchanging data.
DAC_COMPLETE	Asynchronous operation complete.
DAC_ERROR	Error.

Definition at line 70 of file hal_dac.h.

enum dacerror_t

Possible DAC failure causes.

Note: Error codes are architecture dependent and should not relied upon.

Enumerator
DAC_ERR_DMAFAILURE	DMA operations failure.
DAC_ERR_UNDERFLOW	DAC overflow condition.

Definition at line 85 of file hal_dac_lld.h.

Function Documentation

void dacInit ( void )

DAC Driver initialization.

Note: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 56 of file hal_dac.c.

References dac_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void dacObjectInit ( DACDriver * dacp )

Initializes the standard part of a DACDriver structure.

Parameters

[out] dacp pointer to the DACDriver object

Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 68 of file hal_dac.c.

References DACDriver::config, DAC_STOP, DACDriver::mutex, osalMutexObjectInit(), DACDriver::state, and DACDriver::thread.

Referenced by dac_lld_init().

Here is the call graph for this function:

void dacStart	(	DACDriver *	dacp,
		const DACConfig *	config
	)

Configures and activates the DAC peripheral.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	config	pointer to the `DACConfig` object, it can be `NULL` if the low level driver implementation supports a default configuration

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 93 of file hal_dac.c.

References DACDriver::config, dac_lld_start(), DAC_READY, DAC_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and DACDriver::state.

Here is the call graph for this function:

void dacStop ( DACDriver * dacp )

Deactivates the DAC peripheral.

Note: Deactivating the peripheral also enforces a release of the slave select line.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 118 of file hal_dac.c.

References DACDriver::config, dac_lld_stop(), DAC_READY, DAC_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and DACDriver::state.

Here is the call graph for this function:

void dacPutChannelX	(	DACDriver *	dacp,
		dacchannel_t	channel,
		dacsample_t	sample
	)

Outputs a value directly on a DAC channel.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	channel	DAC channel number
[in]	sample	value to be output

Function Class:This is an X-Class API, this function can be invoked from any context.

Definition at line 143 of file hal_dac.c.

References dac_lld_put_channel(), DAC_MAX_CHANNELS, DAC_READY, osalDbgAssert, osalDbgCheck, and DACDriver::state.

Here is the call graph for this function:

void dacStartConversion	(	DACDriver *	dacp,
		const DACConversionGroup *	grpp,
		dacsample_t *	samples,
		size_t	depth
	)

Starts a DAC conversion.

Starts an asynchronous conversion operation.

Note: The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	grpp	pointer to a `DACConversionGroup` object
[in]	samples	pointer to the samples buffer
[in]	depth	buffer depth (matrix rows number). The buffer depth must be one or an even number.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 167 of file hal_dac.c.

References dacStartConversionI(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

void dacStartConversionI	(	DACDriver *	dacp,
		const DACConversionGroup *	grpp,
		dacsample_t *	samples,
		size_t	depth
	)

Starts a DAC conversion.

Starts an asynchronous conversion operation.

Postcondition: The callbacks associated to the conversion group will be invoked on buffer fill and error events.

Note: The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	grpp	pointer to a `DACConversionGroup` object
[in]	samples	pointer to the samples buffer
[in]	depth	buffer depth (matrix rows number). The buffer depth must be one or an even number.

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 195 of file hal_dac.c.

References DAC_ACTIVE, DAC_COMPLETE, DAC_ERROR, dac_lld_start_conversion(), DAC_READY, DACDriver::depth, DACDriver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, DACDriver::samples, and DACDriver::state.

Referenced by dacConvert(), and dacStartConversion().

Here is the call graph for this function:

void dacStopConversion ( DACDriver * dacp )

Stops an ongoing conversion.

This function stops the currently ongoing conversion and returns the driver in the DAC_READY state. If there was no conversion being processed then the function does nothing.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 225 of file hal_dac.c.

References _dac_reset_s, DAC_ACTIVE, dac_lld_stop_conversion(), DAC_READY, DACDriver::grpp, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and DACDriver::state.

Here is the call graph for this function:

void dacStopConversionI ( DACDriver * dacp )

Stops an ongoing conversion.

This function stops the currently ongoing conversion and returns the driver in the DAC_READY state. If there was no conversion being processed then the function does nothing.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 255 of file hal_dac.c.

References _dac_reset_i, DAC_ACTIVE, DAC_COMPLETE, dac_lld_stop_conversion(), DAC_READY, DACDriver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, and DACDriver::state.

Here is the call graph for this function:

msg_t dacConvert	(	DACDriver *	dacp,
		const DACConversionGroup *	grpp,
		dacsample_t *	samples,
		size_t	depth
	)

Performs a DAC conversion.

Performs a synchronous conversion operation.

Note: The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	grpp	pointer to a `DACConversionGroup` object
[out]	samples	pointer to the samples buffer
[in]	depth	buffer depth (matrix rows number). The buffer depth must be one or an even number.

Returns: The operation result.

Return values

MSG_OK	Conversion finished.
MSG_RESET	The conversion has been stopped using `acdStopConversion()` or `acdStopConversionI()`, the result buffer may contain incorrect data.
MSG_TIMEOUT	The conversion has been stopped because an hardware error.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 296 of file hal_dac.c.

References dacStartConversionI(), osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), and DACDriver::thread.

Here is the call graph for this function:

void dacAcquireBus ( DACDriver * dacp )

Gains exclusive access to the DAC bus.

This function tries to gain ownership to the DAC bus, if the bus is already being used then the invoking thread is queued.

Precondition: In order to use this function the option DAC_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 324 of file hal_dac.c.

References DACDriver::mutex, osalDbgCheck, and osalMutexLock().

Here is the call graph for this function:

void dacReleaseBus ( DACDriver * dacp )

Releases exclusive access to the DAC bus.

Precondition: In order to use this function the option DAC_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 340 of file hal_dac.c.

References DACDriver::mutex, osalDbgCheck, and osalMutexUnlock().

Here is the call graph for this function:

void dac_lld_init ( void )

Low level DAC driver initialization.

Function Class:Not an API, this function is for internal use only.

Definition at line 63 of file hal_dac_lld.c.

References dacObjectInit().

Referenced by dacInit().

Here is the call graph for this function:

void dac_lld_start ( DACDriver * dacp )

Configures and activates the DAC peripheral.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 77 of file hal_dac_lld.c.

References DAC_STOP, and DACDriver::state.

Referenced by dacStart().

void dac_lld_stop ( DACDriver * dacp )

Deactivates the DAC peripheral.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 98 of file hal_dac_lld.c.

References DAC_READY, and DACDriver::state.

Referenced by dacStop().

void dac_lld_put_channel	(	DACDriver *	dacp,
		dacchannel_t	channel,
		dacsample_t	sample
	)

Outputs a value directly on a DAC channel.

Parameters

[in]	dacp	pointer to the `DACDriver` object
[in]	channel	DAC channel number
[in]	sample	value to be output

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 120 of file hal_dac_lld.c.

Referenced by dacPutChannelX().

void dac_lld_start_conversion ( DACDriver * dacp )

Starts a DAC conversion.

Starts an asynchronous conversion operation.

Note: In DAC_DHRM_8BIT_RIGHT mode the parameters passed to the callback are wrong because two samples are packed in a single dacsample_t element. This will not be corrected, do not rely on those parameters.; In DAC_DHRM_8BIT_RIGHT_DUAL mode two samples are treated as a single 16 bits sample and packed into a single dacsample_t element. The num_channels must be set to one in the group conversion configuration structure.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:Not an API, this function is for internal use only.

Definition at line 145 of file hal_dac_lld.c.

Referenced by dacStartConversionI().

void dac_lld_stop_conversion ( DACDriver * dacp )

Stops an ongoing conversion.

This function stops the currently ongoing conversion and returns the driver in the DAC_READY state. If there was no conversion being processed then the function does nothing.

Parameters

[in] dacp pointer to the DACDriver object

Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 160 of file hal_dac_lld.c.

Referenced by dacStopConversion(), and dacStopConversionI().

Variable Documentation

DACDriver DACD1

DAC1 driver identifier.

Definition at line 39 of file hal_dac_lld.c.

Detailed Description

Macros

DAC configuration options

Low level driver helper macros

Configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation