Software APIs
Data Structures | Macros | Typedefs | Enumerations | Functions
dif_pwm.h File Reference

(d77a3a3)

PWM Device Interface Functions More...

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

Go to the source code of this file.

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

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

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

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

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
pwmA PWM handle.
channelThe PWM channel to get the enablement state of.
[out]is_enabledThe 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
pwmA PWM handle.
channelsThe channels to enable (one or more dif_pmw_channel_ts ORed together.)
enabledThe 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
pwmA PWM handle.
configRuntime 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
pwmA PWM handle.
channelA PWM channel to configure.
configRuntime 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
pwmA PWM handle.
[out]is_lockedOut-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
pwmA 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
pwmA PWM handle.
[out]is_enabledThe 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
pwmA PWM handle.
enabledThe enablement state to configure the PWM phase counter in.
Returns
The result of the operation.

Definition at line 163 of file dif_pwm.c.