Pulse Width Modulation (PWM) interface for hardware platforms. More...

Collaboration diagram for PWM:

Data Structures
struct	hw_pwm_config_t
	PWM configuration structure for setup parameters. More...

struct	hw_pwm_t
	PWM structure representing a PWM instance. More...

Typedefs
typedef struct hw_pwm_t	hw_pwm_t
	PWM structure representing a PWM instance.

typedef void(*	hw_pwm_callback_t) (uint8_t unit, void *userdata)
	PWM interrupt callback function pointer. More...

Functions
hw_pwm_t	hw_pwm_init (uint8_t unit, hw_pwm_config_t *config)
	Initialize a PWM unit. More...

uint8_t	hw_pwm_count ()
	Get the number of PWM units. More...

static bool	hw_pwm_valid (hw_pwm_t *pwm)
	Validate the PWM unit. More...

void	hw_pwm_finalize (hw_pwm_t *pwm)
	Finalize and release a PWM unit. More...

uint8_t	hw_pwm_gpio_unit (uint8_t gpio)
	Get the PWM unit for a GPIO pin. More...

hw_pwm_config_t	hw_pwm_get_config (float freq)
	Get PWM configuration. More...

float	hw_pwm_get_freq (hw_pwm_config_t *config)
	Returns the frequency for a configuration. More...

void	hw_pwm_set_config (hw_pwm_t pwm, const hw_pwm_config_t config)
	Apply configuration to a PWM unit. More...

bool	hw_pwm_start (hw_pwm_t *pwm, uint8_t gpio, float duty_percent)
	Start PWM output on a specific GPIO pin. More...

void	hw_pwm_stop (hw_pwm_t *pwm)
	Stop PWM output. More...

void	hw_pwm_set_callback (hw_pwm_callback_t callback, void *userdata)
	Set the PWM interrupt callback handler. More...

void	hw_pwm_set_irq_enabled (hw_pwm_t *pwm, bool enabled)
	Enable or disable PWM wrap interrupt for a slice. More...

Detailed Description

Pulse Width Modulation (PWM) interface for hardware platforms.

This module provides functions to initialize PWM units, configure frequency and duty cycle, and control PWM output.

The PWM implementation supports multiple units (slices), each with one or more GPIO outputs. On the Raspberry Pi Pico, there are 8 PWM units on the RP2040 and 12 PWM units on the RP2350.

Interrupts can be configured to trigger on PWM wrap events, allowing for precise timing and control in applications such as motor control, LED dimming, and audio generation.

There is one global PWM callback, which is called when a PWM wrap interrupt occurs on any unit. The callback is executed in interrupt context, so it should be kept short and avoid blocking operations.

The frequency of the PWM output is platform-dependent, but on the Pico this can range from approximately 8 Hz to 60 MHz. The value that is set in the PWM configuration is not necessarily the exact frequency, but rather the closest achievable frequency based on the hardware capabilities.

Similarly the duty cycle (the ratio of HIGH vs LOW for each PWM period) is set as a percentage (0-100) of the PWM period. The actual duty cycle may not be exact due to hardware limitations, but it will be as close as possible to the requested value.

Typedef Documentation

◆ hw_pwm_callback_t

typedef void(* hw_pwm_callback_t) (uint8_t unit, void *userdata)

PWM interrupt callback function pointer.

Parameters

unit	The PWM unit that triggered the interrupt.
userdata	User-defined data pointer passed when setting the callback.

This callback function is called when a PWM wrap interrupt occurs on a unit that has been configured for interrupt detection. The callback is executed in interrupt context, so it should be kept short and avoid blocking operations.

See also: hw_pwm_set_callback() for setting up the callback handler.

Definition at line 75 of file pwm.h.

Function Documentation

◆ hw_pwm_count()

uint8_t hw_pwm_count ( )

Get the number of PWM units.

Returns: Number of PWM units available.

This function returns the total number of PWM units that can be used. It will return zero if PWM is not supported on the platform.

◆ hw_pwm_finalize()

void hw_pwm_finalize ( hw_pwm_t * pwm )

Finalize and release a PWM unit.

Parameters

pwm	Pointer to the PWM structure to finalize.

This function disables the PWM unit, resets its configuration, and releases any associated GPIO pins. After calling this function, the PWM unit should not be used until re-initialized.

◆ hw_pwm_get_config()

hw_pwm_config_t hw_pwm_get_config ( float freq )

Get PWM configuration.

Parameters

freq	Desired frequency in Hz.

Returns: Default PWM configuration structure, with the frequency set to the specified value. If frequency is zero, the maximum frequency supported by the platform will be used.

◆ hw_pwm_get_freq()

float hw_pwm_get_freq ( hw_pwm_config_t * config )

Returns the frequency for a configuration.

Parameters

config Pointer to the PWM configuration structure.

Returns: The frequency for the configuration.

This function retrieves the actual frequency value from the PWM configuration, which is calculated based on the wrap value and divider.

◆ hw_pwm_gpio_unit()

uint8_t hw_pwm_gpio_unit ( uint8_t gpio )

Get the PWM unit for a GPIO pin.

Parameters

gpio	The GPIO pin number.

Returns: The PWM unit number associated with the GPIO pin

This function retrieves the PWM unit number associated with a GPIO pin. The GPIO pin must be less than the total number of GPIO pins available.

Examples:: examples/runtime/led/main.c.

◆ hw_pwm_init()

hw_pwm_t hw_pwm_init	(	uint8_t	unit,
		hw_pwm_config_t *	config
	)

Initialize a PWM unit.

Parameters

unit	The PWM unit number to initialize.
config	Optional pointer to a configuration structure. If NULL, default configuration will be used.

Returns: A PWM structure representing the initialized unit.

This function initializes the PWM unit and channel(s) the GPIO pin belongs to and initializes the unit with default settings. The PWM unit is not started and is set to the disabled state.

Examples:: examples/runtime/led/main.c.

◆ hw_pwm_set_callback()

void hw_pwm_set_callback	(	hw_pwm_callback_t	callback,
		void *	userdata
	)

Set the PWM interrupt callback handler.

Parameters

callback	Pointer to the callback function to handle PWM interrupts, or NULL to disable interrupt handling.
userdata	User-defined data pointer to pass to the callback.

This function registers a global callback handler that will be invoked whenever a PWM wrap interrupt occurs on any slice that has been configured for interrupt detection. Only one callback can be active at a time.

See also: hw_pwm_callback_t for callback function signature requirements.

◆ hw_pwm_set_config()

void hw_pwm_set_config	(	hw_pwm_t *	pwm,
		const hw_pwm_config_t *	config
	)

Apply configuration to a PWM unit.

Parameters

pwm	Pointer to the PWM structure.
config	Pointer to the configuration to apply.

This function applies the specified configuration to the PWM unit. If the PWM unit is currently enabled, it will be stopped before applying the new configuration, and then restarted.

◆ hw_pwm_set_irq_enabled()

void hw_pwm_set_irq_enabled	(	hw_pwm_t *	pwm,
		bool	enabled
	)

Enable or disable PWM wrap interrupt for a slice.

Parameters

pwm	Pointer to the PWM structure.
enabled	True to enable interrupt, false to disable.

This function enables or disables the wrap interrupt for the specified PWM slice. The interrupt fires when the counter reaches the wrap value. A callback must be set using hw_pwm_set_callback() to handle interrupts.

◆ hw_pwm_start()

bool hw_pwm_start	(	hw_pwm_t *	pwm,
		uint8_t	gpio,
		float	duty_percent
	)

Start PWM output on a specific GPIO pin.

Parameters

pwm	Pointer to the PWM structure.
gpio	GPIO pin number to attach.
duty_percent	Duty cycle as a percentage, between 0 and 100.

Returns: True if the PWM was started successfully, false if the GPIO pin is invalid.

This function attaches the specified GPIO pin to the PWM channel, starts the PWM output, sets the duty cycle for the specified PWM channel.

If the duty_percent is less than or equal to 0, the PWM output will always be low. If the duty_percent is 100 or greater, the PWM output will always be high. If the duty_percent is between 0 and 100, the PWM output will toggle between high and low at the specified frequency, with the duty cycle determining the proportion of time the output is high.

◆ hw_pwm_stop()

void hw_pwm_stop ( hw_pwm_t * pwm )

Stop PWM output.

Parameters

pwm	Pointer to the PWM structure.

This function disables the PWM unit, stopping output generation. The counter value is preserved and will resume from this point when the PWM is restarted.

The IRQ state is not affected by this function, so if the PWM was configured to generate interrupts, the interrupt handler will still be called when the PWM is restarted.

◆ hw_pwm_valid()

static bool hw_pwm_valid ( hw_pwm_t * pwm )

inlinestatic

Validate the PWM unit.

Parameters

pwm	Pointer to the PWM structure.

Returns: True if the PWM unit is valid, false otherwise.

The result of hw_pwm_init can return an empty PWM structure if the initialization fails. This function checks if the PWM unit is valid.

Definition at line 113 of file pwm.h.

                                                {
   if (pwm == NULL) {
     return false;
   }
   if (pwm->unit == 0xFF) {
     return false;
   }
   if (pwm->unit >= hw_pwm_count()) {
     return false;
   }
   return true;
 }

objc

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ hw_pwm_callback_t

Function Documentation

◆ hw_pwm_count()

◆ hw_pwm_finalize()

◆ hw_pwm_get_config()

◆ hw_pwm_get_freq()

◆ hw_pwm_gpio_unit()

◆ hw_pwm_init()

◆ hw_pwm_set_callback()

◆ hw_pwm_set_config()

◆ hw_pwm_set_irq_enabled()

◆ hw_pwm_start()

◆ hw_pwm_stop()

◆ hw_pwm_valid()