(8a1a5fe)

PWM Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/dif/autogen/dif_pwm_autogen.h"

Data Structures
struct	dif_pwm_config
	Runtime configuration for PWM. More...

struct	dif_pwm_channel_config
	Runtime configuration for a specific PWM channel. More...

Macros
#define	DIF_PWM_CHANNEL_LIST(X)
	Helper X macro for defining enums and case statements related to PWM channels. More...

#define	PWM_CHANNEL_ENUM_INIT_(channel_) kDifPwmChannel##channel_ = 1U << channel_,
	Helper macro for defining a `dif_pwm_channel_t` enumeration constant. More...

Typedefs
typedef enum dif_pwm_channel	dif_pwm_channel_t
	A PWM channel.

typedef struct dif_pwm_config	dif_pwm_config_t
	Runtime configuration for PWM. More...

typedef enum dif_pwm_mode	dif_pwm_mode_t
	A PWM channel mode.

typedef enum dif_pwm_polarity	dif_pwm_polarity_t
	A PWM channel polarity.

typedef struct dif_pwm_channel_config	dif_pwm_channel_config_t
	Runtime configuration for a specific PWM channel. More...

Enumerations
enum	dif_pwm_channel
	A PWM channel.

enum	dif_pwm_mode { kDifPwmModeFirmware = 0, kDifPwmModeHeartbeat = 1, kDifPwmModeBlink = 2 }
	A PWM channel mode. More...

enum	dif_pwm_polarity { kDifPwmPolarityActiveHigh = 0, kDifPwmPolarityActiveLow = 1 }
	A PWM channel polarity. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_configure (const dif_pwm_t *pwm, dif_pwm_config_t config)
	Configures "phase cycle" and "beat" durations of all PWM channels. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_configure_channel (const dif_pwm_t *pwm, dif_pwm_channel_t channel, dif_pwm_channel_config_t config)
	Configures a single PWM channel. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_phase_cntr_set_enabled (const dif_pwm_t *pwm, dif_toggle_t enabled)
	Sets the enablement state of the PWM phase counter, which controls the enablement of all PWM channels. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_phase_cntr_get_enabled (const dif_pwm_t pwm, dif_toggle_t is_enabled)
	Gets the enablement state of the PWM phase counter, which controls the enablement of all PWM channels. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_channel_set_enabled (const dif_pwm_t *pwm, uint32_t channels, dif_toggle_t enabled)
	Sets the enablement states of one or more PWM channels. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_channel_get_enabled (const dif_pwm_t pwm, dif_pwm_channel_t channel, dif_toggle_t is_enabled)
	Gets the enablement state of one PWM channel. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_lock (const dif_pwm_t *pwm)
	Locks PWM configurations. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_pwm_is_locked (const dif_pwm_t pwm, bool is_locked)
	Checks whether PWM configurations are locked. More...

Detailed Description

PWM Device Interface Functions

The PWM block contains a 16-bit "phase counter" that controls each channel's output signal. The "phase counter" acts as a point of reference for a single PWM "pulse cycle", that is further broken into "beats", depending on the beats_per_cycle parameter. Specifically, a "pulse cycle" may contain [2, 2^16] "beats". Within a "pulse cycle", users can configure the duty cycle in number of "beats". Additionally, the duration of a single "beat", is computed by dividing the core clock frequency by clock_divisor + 1.

  PWM "pulse cycle" defined by 16-bit phase counter

| | v v |-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-| ... |-|-|-|-|

|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-| ... |-|-|-|-| min beat size = 1 phase counter tick --> 2^16 "beats" / "pulse cycle"

|-------------------------------------------— ... | ... –| max beat size = 2^15 phase counter ticks --> 2 "beats" / "pulse cycle"

Definition in file dif_pwm.h.

Data Structure Documentation

◆ dif_pwm_config

struct dif_pwm_config

Runtime configuration for PWM.

This struct describes runtime configuration for one-time configuration of the PWM "pulse cycle" and "beat" durations that impact all PWM channels.

Definition at line 76 of file dif_pwm.h.

Data Fields

uint32_t

beats_per_pulse_cycle

The total number of "beats" in a "pulse cycle", including both "on" and "off" beats in a "pulse cycle".

Valid range: [2, 2^16]

Note: while any value in the range is acceptable, values will be rounded down to closest power-of-two.

A "beat" represents a unit of time of the PWM output signal. Higher values provide higher duty cycle resolutions, at the expense of longer "pulse cycles", while lower values provide shorter "pulse cycles", at the expense of lower duty cycle resolutions (since duty cycles are configured in "beats" / "pulse cycle").

uint32_t

clock_divisor

The core clock frequency divisor that determines the period of a single "beat" within a PWM "pulse cycle".

Valid range: [0, 2^26)

A value of zero, configures the "beat" period to the core clock period.

◆ dif_pwm_channel_config

struct dif_pwm_channel_config

Runtime configuration for a specific PWM channel.

This struct describes runtime configuration for one-time configuration of a specific PWM channel.

Definition at line 144 of file dif_pwm.h.

Data Fields
uint16_t	blink_parameter_x	One of two blink parameters that only impact the "Heartbeat" and "Blink" operation modes. The meaning of this parameter is different based on the operation mode: Heartbeat mode: determines the number of "pulse cycles" between increments/decrements to the duty cycle. Blink mode: determines the number of "pulse cycles" to pulse at duty cycle A, before switching to duty cycle B.
uint16_t	blink_parameter_y	One of two blink parameters that only impact the "Heartbeat" and "Blink" operation modes. The meaning of this parameter is different based on the operation mode: Heartbeat mode: determines the increment/decrement amount in number of duty cycle "beats". Blink mode: determines the number of "pulse cycles" to pulse at duty cycle B, before switching to duty cycle A. Note: the raw value written to the `blink_parameter_x` bitfield in each PWM channel's `BLINK_PARAM_*` CSR is in units of "phase counter ticks", not "beats". However, for ease of configuration, the software manages this conversion under the hood.
uint16_t	duty_cycle_a	Primary duty cycle, in number of "beats" / "pulse cycle". Valid range: [0, beats_per_pulse_cycle) Note: the raw value written to the `A_` bitfield in each PWM channel's `DUTY_CYCLE_` CSR is in units of "phase counter ticks", not "beats". However, the hardware only takes into account the first `DC_RESN` + 1 MSBs of the raw duty cycle value to determine the number of "beats" for a given duty cycle. To make this configuration easier, the software manages the conversion from "beats_per_cycle" to "phase_counter_ticks" under the hood.
uint16_t	duty_cycle_b	Secondary duty cycle, in number of "beats" / "pulse cycle", that is only relevant in heartbeat and blink modes. Valid range: [0, beats_per_pulse_cycle) Note: above notes for `duty_cycle_a` apply here too.
dif_pwm_mode_t	mode	The operation mode to configure the channel in, see `dif_pwm_mode_t`.
uint16_t	phase_delay	Phase delay at the beginning of a "pulse cycle" to delay the active duty cycle "beats" for, in number of "beats". Valid range: [0, beats_per_pulse_cycle)
dif_pwm_polarity_t	polarity	The polarity to configure the channel in, see `dif_pwm_polarity_t`.

Macro Definition Documentation

◆ DIF_PWM_CHANNEL_LIST

#define DIF_PWM_CHANNEL_LIST ( X )

Value:

  X(0)                          \
  X(1)                          \
  X(2)                          \
  X(3)                          \
  X(4)                          \
  X(5)

Helper X macro for defining enums and case statements related to PWM channels.

If an additional channel is ever added to the hardware, this list can be updated.

Definition at line 46 of file dif_pwm.h.

◆ PWM_CHANNEL_ENUM_INIT_

#define PWM_CHANNEL_ENUM_INIT_ ( channel_ ) kDifPwmChannel##channel_ = 1U << channel_,

Helper macro for defining a dif_pwm_channel_t enumeration constant.

@channel_ PWM channel of the enumeration constant.

Definition at line 58 of file dif_pwm.h.

Typedef Documentation

◆ dif_pwm_channel_config_t

typedef struct dif_pwm_channel_config dif_pwm_channel_config_t

Runtime configuration for a specific PWM channel.

This struct describes runtime configuration for one-time configuration of a specific PWM channel.

◆ dif_pwm_config_t

typedef struct dif_pwm_config dif_pwm_config_t

Runtime configuration for PWM.

This struct describes runtime configuration for one-time configuration of the PWM "pulse cycle" and "beat" durations that impact all PWM channels.

Enumeration Type Documentation

◆ dif_pwm_mode

enum dif_pwm_mode

A PWM channel mode.

Enumerator
kDifPwmModeFirmware	The PWM duty cycle is set by the firmware and remains constant.
kDifPwmModeHeartbeat	The PWM duty cycle linearly sweeps between both primary and secondary firmware-configured values, based on a firmware-configured step size.
kDifPwmModeBlink	The PWM duty cycle alternates between both primary and secondary firmware-configured values, based on two firmware-configured durations.

Definition at line 107 of file dif_pwm.h.

◆ dif_pwm_polarity

enum dif_pwm_polarity

A PWM channel polarity.

Enumerator
kDifPwmPolarityActiveHigh	A PWM signal is active-high.
kDifPwmPolarityActiveLow	A PWM signal is active-low.

Definition at line 127 of file dif_pwm.h.

Function Documentation

◆ dif_pwm_channel_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_channel_get_enabled	(	const dif_pwm_t *	pwm,
		dif_pwm_channel_t	channel,
		dif_toggle_t *	is_enabled
	)

Gets the enablement state of one PWM channel.

Parameters

	pwm	A PWM handle.
	channel	The PWM channel to get the enablement state of.
[out]	is_enabled	The enablement state of the PWM channel.

Returns: The result of the operation.

Definition at line 220 of file dif_pwm.c.

◆ dif_pwm_channel_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_channel_set_enabled	(	const dif_pwm_t *	pwm,
		uint32_t	channels,
		dif_toggle_t	enabled
	)

Sets the enablement states of one or more PWM channels.

Parameters

pwm	A PWM handle.
channels	The channels to enable (one or more `dif_pmw_channel_t`s ORed together.)
enabled	The enablement state to set.

Returns: The result of the operation.

Definition at line 194 of file dif_pwm.c.

◆ dif_pwm_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_configure	(	const dif_pwm_t *	pwm,
		dif_pwm_config_t	config
	)

Configures "phase cycle" and "beat" durations of all PWM channels.

Since changes to CLK_DIV and DC_RESN are only allowed when the PWM is disabled, this function has the side effect of temporarily disabling all PWM channels while configurations are updated, before restoring the original enablement state.

This function should only need to be called once for the lifetime of handle.

Parameters

pwm	A PWM handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 19 of file dif_pwm.c.

◆ dif_pwm_configure_channel()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_configure_channel	(	const dif_pwm_t *	pwm,
		dif_pwm_channel_t	channel,
		dif_pwm_channel_config_t	config
	)

Configures a single PWM channel.

Since changes to CLK_DIV and DC_RESN are only allowed when the PWM is disabled, this function has the side effect of temporarily disabling the PWM while configurations are updated, before returning the block to its original enablement state.

This function should only need to be called once for each PWM channel that will be used.

Parameters

pwm	A PWM handle.
channel	A PWM channel to configure.
config	Runtime configuration parameters for the channel.

Returns: The result of the operation.

Definition at line 56 of file dif_pwm.c.

◆ dif_pwm_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_is_locked	(	const dif_pwm_t *	pwm,
		bool *	is_locked
	)

Checks whether PWM configurations are locked.

Parameters

	pwm	A PWM handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 251 of file dif_pwm.c.

◆ dif_pwm_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_lock ( const dif_pwm_t * pwm )

Locks PWM configurations.

This function is reentrant: calling it while locked will have no effect and return kDifOk.

Parameters

pwm	A PWM handle.

Returns: The result of the operation.

Definition at line 241 of file dif_pwm.c.

◆ dif_pwm_phase_cntr_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_phase_cntr_get_enabled	(	const dif_pwm_t *	pwm,
		dif_toggle_t *	is_enabled
	)

Gets the enablement state of the PWM phase counter, which controls the enablement of all PWM channels.

Parameters

	pwm	A PWM handle.
[out]	is_enabled	The enablement state of the PWM phase counter.

Returns: The result of the operation.

Definition at line 181 of file dif_pwm.c.

◆ dif_pwm_phase_cntr_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_pwm_phase_cntr_set_enabled	(	const dif_pwm_t *	pwm,
		dif_toggle_t	enabled
	)

Sets the enablement state of the PWM phase counter, which controls the enablement of all PWM channels.

Parameters

pwm	A PWM handle.
enabled	The enablement state to configure the PWM phase counter in.

Returns: The result of the operation.

Definition at line 163 of file dif_pwm.c.

(8a1a5fe)

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_pwm_config

◆ dif_pwm_channel_config

Macro Definition Documentation

◆ DIF_PWM_CHANNEL_LIST

◆ PWM_CHANNEL_ENUM_INIT_

Typedef Documentation

◆ dif_pwm_channel_config_t

◆ dif_pwm_config_t

Enumeration Type Documentation

◆ dif_pwm_mode

◆ dif_pwm_polarity

Function Documentation

◆ dif_pwm_channel_get_enabled()

◆ dif_pwm_channel_set_enabled()

◆ dif_pwm_configure()

◆ dif_pwm_configure_channel()

◆ dif_pwm_is_locked()

◆ dif_pwm_lock()

◆ dif_pwm_phase_cntr_get_enabled()

◆ dif_pwm_phase_cntr_set_enabled()