Generic ICU Driver. More...

Collaboration diagram for ICU Driver:

Detailed Description

Generic ICU Driver.

This module implements a generic ICU (Input Capture Unit) driver. The purpose of the driver is to measure period and duty cycle of an input digital signal (PWM input).

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

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

ICU Operations.

This driver abstracts a generic Input Capture Unit composed of:

A clock prescaler.
A main up counter.
Two capture registers triggered by the rising and falling edges on the sampled input.

The ICU unit can be programmed to synchronize on the rising or falling edge of the sample input:

ICU_INPUT_ACTIVE_HIGH, a rising edge is the start signal.
ICU_INPUT_ACTIVE_LOW, a falling edge is the start signal.

Callbacks are optionally invoked when:

On the PWM de-activation edge.
On the PWM activation edge, measurements for the previous cycle are available from this callback and can be retrieved using icuGetPeriodX() and icuGetWidthX().

Macros
#define	icu_lld_get_width(icup) 0
	Returns the width of the latest pulse. More...

#define	icu_lld_get_period(icup) 0
	Returns the width of the latest cycle. More...

#define	icu_lld_are_notifications_enabled(icup) false
	Check on notifications status. More...

Macro Functions
#define	icuStartCaptureI(icup)
	Starts the input capture. More...

#define	icuStopCaptureI(icup)
	Stops the input capture. More...

#define	icuEnableNotificationsI(icup) icu_lld_enable_notifications(icup)
	Enables notifications. More...

#define	icuDisableNotificationsI(icup) icu_lld_disable_notifications(icup)
	Disables notifications. More...

#define	icuAreNotificationsEnabledX(icup) icu_lld_are_notifications_enabled(icup)
	Check on notifications status. More...

#define	icuGetWidthX(icup) icu_lld_get_width(icup)
	Returns the width of the latest pulse. More...

#define	icuGetPeriodX(icup) icu_lld_get_period(icup)
	Returns the width of the latest cycle. More...

Low level driver helper macros
#define	_icu_isr_invoke_width_cb(icup)
	Common ISR code, ICU width event. More...

#define	_icu_isr_invoke_period_cb(icup)
	Common ISR code, ICU period event. More...

#define	_icu_isr_invoke_overflow_cb(icup)
	Common ISR code, ICU timer overflow event. More...

PLATFORM configuration options
#define	PLATFORM_ICU_USE_ICU1 FALSE
	ICUD1 driver enable switch. More...

Typedefs
typedef struct ICUDriver	ICUDriver
	Type of a structure representing an ICU driver. More...

typedef void(*	icucallback_t) (ICUDriver *icup)
	ICU notification callback type. More...

typedef uint32_t	icufreq_t
	ICU frequency type. More...

typedef uint32_t	icucnt_t
	ICU counter type. More...

Data Structures
struct	ICUConfig
	Driver configuration structure. More...

struct	ICUDriver
	Structure representing an ICU driver. More...

Functions
void	icuInit (void)
	ICU Driver initialization. More...

void	icuObjectInit (ICUDriver *icup)
	Initializes the standard part of a `ICUDriver` structure. More...

void	icuStart (ICUDriver icup, const ICUConfig config)
	Configures and activates the ICU peripheral. More...

void	icuStop (ICUDriver *icup)
	Deactivates the ICU peripheral. More...

void	icuStartCapture (ICUDriver *icup)
	Starts the input capture. More...

bool	icuWaitCapture (ICUDriver *icup)
	Waits for a completed capture. More...

void	icuStopCapture (ICUDriver *icup)
	Stops the input capture. More...

void	icuEnableNotifications (ICUDriver *icup)
	Enables notifications. More...

void	icuDisableNotifications (ICUDriver *icup)
	Disables notifications. More...

void	icu_lld_init (void)
	Low level ICU driver initialization. More...

void	icu_lld_start (ICUDriver *icup)
	Configures and activates the ICU peripheral. More...

void	icu_lld_stop (ICUDriver *icup)
	Deactivates the ICU peripheral. More...

void	icu_lld_start_capture (ICUDriver *icup)
	Starts the input capture. More...

bool	icu_lld_wait_capture (ICUDriver *icup)
	Waits for a completed capture. More...

void	icu_lld_stop_capture (ICUDriver *icup)
	Stops the input capture. More...

void	icu_lld_enable_notifications (ICUDriver *icup)
	Enables notifications. More...

void	icu_lld_disable_notifications (ICUDriver *icup)
	Disables notifications. More...

Enumerations

Variables
ICUDriver	ICUD1
	ICUD1 driver identifier. More...

Macro Definition Documentation

#define icuStartCaptureI ( icup )

Value:

do {                                         \
  icu_lld_start_capture(icup);                                              \
  (icup)->state = ICU_WAITING;                                              \
} while (false)

Starts the input capture.

Parameters

[in] icup pointer to the ICUDriver 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 86 of file hal_icu.h.

Referenced by icuStartCapture().

#define icuStopCaptureI ( icup )

Value:

do {                                          \
  icu_lld_stop_capture(icup);                                               \
  (icup)->state = ICU_READY;                                                \
} while (false)

Stops the input capture.

Parameters

[in] icup pointer to the ICUDriver 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 98 of file hal_icu.h.

Referenced by icuStopCapture().

#define icuEnableNotificationsI ( icup ) icu_lld_enable_notifications(icup)

Enables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already enabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver 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 113 of file hal_icu.h.

Referenced by icuEnableNotifications().

#define icuDisableNotificationsI ( icup ) icu_lld_disable_notifications(icup)

Disables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already disabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver 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 125 of file hal_icu.h.

Referenced by icuDisableNotifications().

#define icuAreNotificationsEnabledX ( icup ) icu_lld_are_notifications_enabled(icup)

Check on notifications status.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The notifications status.

Return values

false	if notifications are not enabled.
true	if notifications are enabled.

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

Definition at line 137 of file hal_icu.h.

Referenced by icuWaitCapture().

#define icuGetWidthX ( icup ) icu_lld_get_width(icup)

Returns the width of the latest pulse.

The pulse width is defined as number of ticks between the start edge and the stop edge.

Note: This function is meant to be invoked from the width capture callback.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The number of ticks.

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

Definition at line 152 of file hal_icu.h.

#define icuGetPeriodX ( icup ) icu_lld_get_period(icup)

Returns the width of the latest cycle.

The cycle width is defined as number of ticks between a start edge and the next start edge.

Note: This function is meant to be invoked from the width capture callback.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The number of ticks.

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

Definition at line 166 of file hal_icu.h.

#define _icu_isr_invoke_width_cb ( icup )

Value:

do {                                 \
  if (((icup)->state == ICU_ACTIVE) &&                                      \
      ((icup)->config->width_cb != NULL))                                   \
    (icup)->config->width_cb(icup);                                         \
} while (0)

Common ISR code, ICU width event.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 180 of file hal_icu.h.

#define _icu_isr_invoke_period_cb ( icup )

Value:

do {                                \
  if (((icup)->state == ICU_ACTIVE) &&                                      \
      ((icup)->config->period_cb != NULL))                                  \
    (icup)->config->period_cb(icup);                                        \
  (icup)->state = ICU_ACTIVE;                                               \
} while (0)

Common ISR code, ICU period event.

Note: A period event brings the driver into the ICU_ACTIVE state.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 194 of file hal_icu.h.

#define _icu_isr_invoke_overflow_cb ( icup )

Value:

do {                              \
  (icup)->config->overflow_cb(icup);                                        \
  (icup)->state = ICU_WAITING;                                              \
} while (0)

Common ISR code, ICU timer overflow event.

Note: An overflow always brings the driver back to the ICU_WAITING state.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 210 of file hal_icu.h.

#define PLATFORM_ICU_USE_ICU1 FALSE

ICUD1 driver enable switch.

If set to TRUE the support for ICUD1 is included.

Note: The default is FALSE.

Definition at line 48 of file hal_icu_lld.h.

#define icu_lld_get_width ( icup ) 0

Returns the width of the latest pulse.

The pulse width is defined as number of ticks between the start edge and the stop edge.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The number of ticks.

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

Definition at line 140 of file hal_icu_lld.h.

#define icu_lld_get_period ( icup ) 0

Returns the width of the latest cycle.

The cycle width is defined as number of ticks between a start edge and the next start edge.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The number of ticks.

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

Definition at line 152 of file hal_icu_lld.h.

#define icu_lld_are_notifications_enabled ( icup ) false

Check on notifications status.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The notifications status.

Return values

false	if notifications are not enabled.
true	if notifications are enabled.

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

Definition at line 164 of file hal_icu_lld.h.

Typedef Documentation

typedef struct ICUDriver ICUDriver

Type of a structure representing an ICU driver.

Definition at line 60 of file hal_icu.h.

typedef void(* icucallback_t) (ICUDriver *icup)

ICU notification callback type.

Parameters

[in] icup pointer to a ICUDriver object

Definition at line 67 of file hal_icu.h.

typedef uint32_t icufreq_t

ICU frequency type.

Definition at line 71 of file hal_icu_lld.h.

typedef uint32_t icucnt_t

ICU counter type.

Definition at line 76 of file hal_icu_lld.h.

Enumeration Type Documentation

enum icustate_t

Driver state machine possible states.

Enumerator
ICU_UNINIT	Not initialized.
ICU_STOP	Stopped.
ICU_READY	Ready.
ICU_WAITING	Waiting for first front.
ICU_ACTIVE	First front detected.

Definition at line 49 of file hal_icu.h.

enum icumode_t

ICU driver mode.

Enumerator
ICU_INPUT_ACTIVE_HIGH	Trigger on rising edge.
ICU_INPUT_ACTIVE_LOW	Trigger on falling edge.

Definition at line 63 of file hal_icu_lld.h.

Function Documentation

void icuInit ( void )

ICU 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_icu.c.

References icu_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void icuObjectInit ( ICUDriver * icup )

Initializes the standard part of a ICUDriver structure.

Parameters

[out] icup pointer to the ICUDriver 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_icu.c.

References ICUDriver::config, ICU_STOP, and ICUDriver::state.

Referenced by icu_lld_init().

void icuStart	(	ICUDriver *	icup,
		const ICUConfig *	config
	)

Configures and activates the ICU peripheral.

Parameters

[in]	icup	pointer to the `ICUDriver` object
[in]	config	pointer to the `ICUConfig` object

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

Definition at line 82 of file hal_icu.c.

References ICUDriver::config, icu_lld_start(), ICU_READY, ICU_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icuStop ( ICUDriver * icup )

Deactivates the ICU peripheral.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 102 of file hal_icu.c.

References ICUDriver::config, icu_lld_stop(), ICU_READY, ICU_STOP, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icuStartCapture ( ICUDriver * icup )

Starts the input capture.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 125 of file hal_icu.c.

References ICU_READY, icuStartCaptureI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

bool icuWaitCapture ( ICUDriver * icup )

Waits for a completed capture.

Note: The operation could be performed in polled mode depending on.; In order to use this function notifications must be disabled.

Precondition: The driver must be in ICU_WAITING or ICU_ACTIVE states.

Postcondition: After the capture is available the driver is in ICU_ACTIVE state. If a capture fails then the driver is in ICU_WAITING state.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The capture status.

Return values

false	if the capture is successful.
true	if a timer overflow occurred.

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

Definition at line 151 of file hal_icu.c.

References ICU_ACTIVE, icu_lld_wait_capture(), ICU_WAITING, icuAreNotificationsEnabledX, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icuStopCapture ( ICUDriver * icup )

Stops the input capture.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 175 of file hal_icu.c.

References ICU_ACTIVE, ICU_READY, ICU_WAITING, icuStopCaptureI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icuEnableNotifications ( ICUDriver * icup )

Enables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already enabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 197 of file hal_icu.c.

References ICU_ACTIVE, ICU_WAITING, icuEnableNotificationsI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icuDisableNotifications ( ICUDriver * icup )

Disables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already disabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 218 of file hal_icu.c.

References ICU_ACTIVE, ICU_WAITING, icuDisableNotificationsI, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ICUDriver::state.

Here is the call graph for this function:

void icu_lld_init ( void )

Low level ICU driver initialization.

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

Definition at line 66 of file hal_icu_lld.c.

References icuObjectInit().

Referenced by icuInit().

Here is the call graph for this function:

void icu_lld_start ( ICUDriver * icup )

Configures and activates the ICU peripheral.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 81 of file hal_icu_lld.c.

References ICU_STOP, and ICUDriver::state.

Referenced by icuStart().

void icu_lld_stop ( ICUDriver * icup )

Deactivates the ICU peripheral.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 100 of file hal_icu_lld.c.

References ICU_READY, and ICUDriver::state.

Referenced by icuStop().

void icu_lld_start_capture ( ICUDriver * icup )

Starts the input capture.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 119 of file hal_icu_lld.c.

bool icu_lld_wait_capture ( ICUDriver * icup )

Waits for a completed capture.

Note: The operation is performed in polled mode.; In order to use this function notifications must be disabled.

Parameters

[in] icup pointer to the ICUDriver object

Returns: The capture status.

Return values

false	if the capture is successful.
true	if a timer overflow occurred.

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

Definition at line 136 of file hal_icu_lld.c.

Referenced by icuWaitCapture().

void icu_lld_stop_capture ( ICUDriver * icup )

Stops the input capture.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 150 of file hal_icu_lld.c.

void icu_lld_enable_notifications ( ICUDriver * icup )

Enables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already enabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 165 of file hal_icu_lld.c.

void icu_lld_disable_notifications ( ICUDriver * icup )

Disables notifications.

Precondition: The ICU unit must have been activated using icuStart() and the capture started using icuStartCapture().

Note: If the notification is already disabled then the call has no effect.

Parameters

[in] icup pointer to the ICUDriver object

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

Definition at line 180 of file hal_icu_lld.c.

Variable Documentation

ICUDriver ICUD1

ICUD1 driver identifier.

Note: The driver ICUD1 allocates the complex timer TIM1 when enabled.

Definition at line 42 of file hal_icu_lld.c.

Detailed Description

Driver State Machine

ICU Operations.

Macros

Macro Functions

Low level driver helper macros

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation