PWM (Pulse Width Modulator)

General Description

High level interface for interacting with the pulse width modulator (PWM) hardware resource.

The PWM driver can be used to generate periodic digital waveforms with configurable frequency and duty cycle. The driver allows assigning the PWM output and an optional inverted output to supplied pins. The driver supports interrupt generation on PWM terminal count and compare events.

Features

• Configurable pin assignment for the PWM output
• Optional complementary (inverted) PWM output to a second pin
• Configurable dead time between normal and inverted PWM outputs
• Configurable alignment: left, right or center
• Continuous or One-shot operation
• Option to instantiate and use a new clock or use pre-allocated clock for clock input
• Configurable interrupt and callback assignment on PWM events: terminal count, compare match or combination of both

Quick Start

See Snippet 1: Simple PWM initialization and output to pin for a code snippet that generates a signal with the specified frequency and duty cycle on the specified pin.

Code snippets

Snippet 1: Simple PWM initialization and output to pin

The clock parameter clk is optional and need not be provided (NULL), to generate and use an available clock resource with a default frequency.
The clock frequency and the duty cycle is set using mtb_hal_pwm_set_period.
mtb_hal_pwm_start starts the PWM output on the pin.

    cy_rslt_t        rslt;
    mtb_hal_pwm_t    pwm_obj;
    // Specify the clock source
    mtb_hal_clock_t pwm_clock;
 
    // Initialize the PWM configuration structure
    const cy_stc_tcpwm_pwm_config_t pwm_config = { 0 };
 
    // Initialize PWM
    rslt = (cy_rslt_t)Cy_TCPWM_PWM_Init(PWM_HW, PWM_CNTNUM, &pwm_config);
    rslt = mtb_hal_pwm_setup(&pwm_obj, &PWM_hal_cfg, &pwm_clock);
    rslt = mtb_hal_pwm_enable(&pwm_obj, true);
 
    // Set a 10us pulse with 100us period
    rslt = mtb_hal_pwm_set_period(&pwm_obj, 100, 10);
 
    // Start the PWM output
    rslt = mtb_hal_pwm_start(&pwm_obj);

Snippet 2: Starting and stopping the PWM output

mtb_hal_pwm_start and mtb_hal_pwm_stop functions can be used after PWM initialization to start and stop the PWM output.

    mtb_hal_pwm_t pwm_obj;
    // Specify the clock source
    mtb_hal_clock_t pwm_clock;
    const cy_stc_tcpwm_pwm_config_t pwm_config = { 0 };
 
    // Initialize PWM
    rslt = (cy_rslt_t)Cy_TCPWM_PWM_Init(PWM_HW, PWM_CNTNUM, &pwm_config);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);
    rslt = mtb_hal_pwm_setup(&pwm_obj, &PWM_hal_cfg, &pwm_clock);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);
    rslt = mtb_hal_pwm_enable(&pwm_obj, true);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);
 
    // Set a 10us pulse with 100us period
    rslt = mtb_hal_pwm_set_period(&pwm_obj, 100, 10);
 
    while (loop)
    {
        // Stop the PWM output
        rslt = mtb_hal_pwm_stop(&pwm_obj);
 
        // Delay for observing the output
        mtb_hal_system_delay_ms(5000);
 
        // (Re-)start the PWM output
        rslt = mtb_hal_pwm_start(&pwm_obj);
 
        // Delay for observing the output
        mtb_hal_system_delay_ms(5000);
    }

API Reference
	PWM HAL Results
	PWM specific return codes.

Typedefs
typedef void(*	mtb_hal_pwm_event_callback_t) (void *callback_arg, mtb_hal_pwm_event_t event)
	Handler for PWM events.

Enumerations
enum	mtb_hal_pwm_event_t {   MTB_HAL_PWM_EVENT_NONE = 0 ,   MTB_HAL_PWM_EVENT_TERMINAL_COUNT = 1 << 0 ,   MTB_HAL_PWM_EVENT_COMPARE = 1 << 1 ,   MTB_HAL_PWM_EVENT_ALL = (1 << 2) - 1 }
	PWM event types. More...
enum	mtb_hal_pwm_output_t {   MTB_HAL_PWM_OUTPUT_CONSTANT_0 = 0 ,   MTB_HAL_PWM_OUTPUT_CONSTANT_1 = 1 ,   MTB_HAL_PWM_OUTPUT_PWM_SIGNAL = 2 ,   MTB_HAL_PWM_OUTPUT_INVERTED_PWM_SIGNAL = 3 ,   MTB_HAL_PWM_OUTPUT_PORT_DEFAULT = 4 ,   MTB_HAL_PWM_OUTPUT_SOURCE_MOTIF = 5 }
	PWM output source. More...

Functions
cy_rslt_t	mtb_hal_pwm_setup (mtb_hal_pwm_t *obj, const mtb_hal_pwm_configurator_t *config, const mtb_hal_clock_t *clock)
	Sets up a HAL instance to use the specified hardware resource. More...
cy_rslt_t	mtb_hal_pwm_set_period (mtb_hal_pwm_t *obj, uint32_t period_us, uint32_t pulse_width_us)
	Set the number of microseconds for the PWM period & pulse width. More...
cy_rslt_t	mtb_hal_pwm_enable (mtb_hal_pwm_t *obj, bool enable)
	Enable/disable the PWM. More...
cy_rslt_t	mtb_hal_pwm_start (mtb_hal_pwm_t *obj)
	Starts the PWM generation and outputs on pin and compl_pin. More...
cy_rslt_t	mtb_hal_pwm_stop (mtb_hal_pwm_t *obj)
	Stops the PWM generation and outputs on pin and compl_pin. More...
cy_rslt_t	mtb_hal_pwm_set_period_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the period count value. More...
cy_rslt_t	mtb_hal_pwm_set_period_alt_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the alternative period count value. More...
cy_rslt_t	mtb_hal_pwm_set_compare_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the compare count value. More...
cy_rslt_t	mtb_hal_pwm_set_compare_shadow_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the shadow compare count value. More...
cy_rslt_t	mtb_hal_pwm_set_compare_alt_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the alternative compare count value. More...
cy_rslt_t	mtb_hal_pwm_set_compare_alt_shadow_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the alternative shadow compare count value. More...
cy_rslt_t	mtb_hal_pwm_set_deadtime_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the deadtime count value. More...
cy_rslt_t	mtb_hal_pwm_set_deadtime_shadow_count (mtb_hal_pwm_t *obj, uint32_t count)
	Sets the shadow deadtime count value. More...
cy_rslt_t	mtb_hal_pwm_configure_output (mtb_hal_pwm_t *obj, mtb_hal_pwm_output_t out, mtb_hal_pwm_output_t out_compl)
	Configures the source of the output pins. More...
void	mtb_hal_pwm_resume (mtb_hal_pwm_t *obj)
	Resume the PWM counter. More...
void	mtb_hal_pwm_pause (mtb_hal_pwm_t *obj)
	Pause the PWM counter. More...
void	mtb_hal_pwm_reload (mtb_hal_pwm_t *obj)
	Reload the PWM counter. More...
void	mtb_hal_pwm_register_callback (mtb_hal_pwm_t *obj, mtb_hal_pwm_event_callback_t callback, void *callback_arg)
	Register/clear a callback handler for PWM events. More...
void	mtb_hal_pwm_enable_event (mtb_hal_pwm_t *obj, mtb_hal_pwm_event_t event, bool enable)
	Enable or Disable the specified PWM event. More...
cy_rslt_t	mtb_hal_pwm_process_interrupt (mtb_hal_pwm_t *obj)
	Process interrupts related related to a PWM instance. More...

Enumeration Type Documentation

mtb_hal_pwm_event_t

enum mtb_hal_pwm_event_t

PWM event types.

Enumerator
MTB_HAL_PWM_EVENT_NONE	No event.
MTB_HAL_PWM_EVENT_TERMINAL_COUNT	Event on terminal count match event.
MTB_HAL_PWM_EVENT_COMPARE	Event on compare match event.
MTB_HAL_PWM_EVENT_ALL	Event on any events.

mtb_hal_pwm_output_t

enum mtb_hal_pwm_output_t

PWM output source.

Enumerator
MTB_HAL_PWM_OUTPUT_CONSTANT_0	Output signal is 0.
MTB_HAL_PWM_OUTPUT_CONSTANT_1	Output signal is 1.
MTB_HAL_PWM_OUTPUT_PWM_SIGNAL	Output signal is PWM Signal.
MTB_HAL_PWM_OUTPUT_INVERTED_PWM_SIGNAL	Output signal is inverted PWM Signal.
MTB_HAL_PWM_OUTPUT_PORT_DEFAULT	Output is not driven by the TCPWM. Instead the port default level configuration applies, e.g. "Z" (high impedance).
MTB_HAL_PWM_OUTPUT_SOURCE_MOTIF	Source for PWM signal conditioning comes from MOTIF modulation output control signals. It can be set to '0' , '1' or PWM.

Function Documentation

mtb_hal_pwm_setup()

cy_rslt_t mtb_hal_pwm_setup	(	mtb_hal_pwm_t *	obj,
		const mtb_hal_pwm_configurator_t *	config,
		const mtb_hal_clock_t *	clock
	)

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

[out]	obj	The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
[in]	config	The configurator-generated HAL config structure for this peripheral instance
[in]	clock	The HAL clock object that is connected to this peripheral instance

Returns

the status of the HAL setup

mtb_hal_pwm_set_period()

cy_rslt_t mtb_hal_pwm_set_period	(	mtb_hal_pwm_t *	obj,
		uint32_t	period_us,
		uint32_t	pulse_width_us
	)

Set the number of microseconds for the PWM period & pulse width.

Parameters

[in]	obj	The PWM object
[in]	period_us	The period in microseconds
[in]	pulse_width_us	The pulse width in microseconds

Returns

The status of the period request

mtb_hal_pwm_enable()

cy_rslt_t mtb_hal_pwm_enable	(	mtb_hal_pwm_t *	obj,
		bool	enable
	)

Enable/disable the PWM.

The function returns without waiting for the enable to complete.

Parameters

[in]	obj	The PWM object
[in]	enable	Enable/disable

Returns

The status of the enable request

mtb_hal_pwm_start()

cy_rslt_t mtb_hal_pwm_start

(

mtb_hal_pwm_t *

obj

)

Starts the PWM generation and outputs on pin and compl_pin.

Parameters

[in]

obj

The PWM object

Returns

The status of the start request

mtb_hal_pwm_stop()

cy_rslt_t mtb_hal_pwm_stop

(

mtb_hal_pwm_t *

obj

)

Stops the PWM generation and outputs on pin and compl_pin.

Parameters

[in]

obj

The PWM object

Returns

The status of the stop request

mtb_hal_pwm_set_period_count()

cy_rslt_t mtb_hal_pwm_set_period_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the period count value.

Parameters

[in]	obj	The PWM object
[in]	count	The period value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_period_alt_count()

cy_rslt_t mtb_hal_pwm_set_period_alt_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the alternative period count value.

Parameters

[in]	obj	The PWM object
[in]	count	The period value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_compare_count()

cy_rslt_t mtb_hal_pwm_set_compare_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the compare count value.

Parameters

[in]	obj	The PWM object
[in]	count	The compare value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_compare_shadow_count()

cy_rslt_t mtb_hal_pwm_set_compare_shadow_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the shadow compare count value.

Parameters

[in]	obj	The PWM object
[in]	count	The compare value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_compare_alt_count()

cy_rslt_t mtb_hal_pwm_set_compare_alt_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the alternative compare count value.

Parameters

[in]	obj	The PWM object
[in]	count	The compare value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_compare_alt_shadow_count()

cy_rslt_t mtb_hal_pwm_set_compare_alt_shadow_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the alternative shadow compare count value.

Parameters

[in]	obj	The PWM object
[in]	count	The compare value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_deadtime_count()

cy_rslt_t mtb_hal_pwm_set_deadtime_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the deadtime count value.

Parameters

[in]	obj	The PWM object
[in]	count	The deadtime value in counts

Returns

The status of the count set request

mtb_hal_pwm_set_deadtime_shadow_count()

cy_rslt_t mtb_hal_pwm_set_deadtime_shadow_count	(	mtb_hal_pwm_t *	obj,
		uint32_t	count
	)

Sets the shadow deadtime count value.

Parameters

[in]	obj	The PWM object
[in]	count	The deadtime value in counts

Returns

The status of the count set request

mtb_hal_pwm_configure_output()

cy_rslt_t mtb_hal_pwm_configure_output	(	mtb_hal_pwm_t *	obj,
		mtb_hal_pwm_output_t	out,
		mtb_hal_pwm_output_t	out_compl
	)

Configures the source of the output pins.

Parameters

[in]	obj	The PWM object
[in]	out	Output source for pwm pin
[in]	out_compl	Output source for the complementary pwm pin

Returns

The status of the output source configuration request

mtb_hal_pwm_resume()

void mtb_hal_pwm_resume

(

mtb_hal_pwm_t *

obj

)

Resume the PWM counter.

This function is intented for starting an already enabled PWM. For enabling the PWM, use mtb_hal_pwm_start

Parameters

[in]

obj

The PWM object

mtb_hal_pwm_pause()

void mtb_hal_pwm_pause

(

mtb_hal_pwm_t *

obj

)

Pause the PWM counter.

This function is intented for temporarily stopping the PWM. For disabling the PWM, use mtb_hal_pwm_stop

Parameters

[in]

obj

The PWM object

mtb_hal_pwm_reload()

void mtb_hal_pwm_reload

(

mtb_hal_pwm_t *

obj

)

Reload the PWM counter.

This function resets the counter to its initial value at configuration.

Parameters

[in]

obj

The PWM object

mtb_hal_pwm_register_callback()

void mtb_hal_pwm_register_callback	(	mtb_hal_pwm_t *	obj,
		mtb_hal_pwm_event_callback_t	callback,
		void *	callback_arg
	)

Register/clear a callback handler for PWM events.

The referenced function will be called when one of the events enabled by mtb_hal_pwm_enable_event occurs.

Parameters

[in]	obj	The PWM object
[in]	callback	The callback handler which will be invoked when the event occurs
[in]	callback_arg	Generic argument that will be provided to the callback when called

mtb_hal_pwm_enable_event()

void mtb_hal_pwm_enable_event	(	mtb_hal_pwm_t *	obj,
		mtb_hal_pwm_event_t	event,
		bool	enable
	)

Enable or Disable the specified PWM event.

When an enabled event occurs, the function specified by mtb_hal_pwm_register_callback will be called.

Parameters

[in]	obj	The PWM object
[in]	event	The PWM event
[in]	enable	True to turn on interrupts, False to turn off

mtb_hal_pwm_process_interrupt()

cy_rslt_t mtb_hal_pwm_process_interrupt

(

mtb_hal_pwm_t *

obj

)

Process interrupts related related to a PWM instance.

Parameters

obj	HAL object for which the interrupt should be processed

Returns

CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error