PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Typedefs | Enumerations | Functions
PWM (Pulse Width Modulator)
HAL API Reference » HAL Drivers

## 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);
mtb_hal_pwm_t
PWM object.
Definition: mtb_hal_hw_types_pwm_tcpwm.h:52
mtb_hal_pwm_enable
cy_rslt_t mtb_hal_pwm_enable(mtb_hal_pwm_t *obj, bool enable)
Enable/disable the PWM.
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.
Definition: mtb_hal_pwm.c:129
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.
Definition: mtb_hal_pwm.c:152
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.
Definition: mtb_hal_pwm.c:108
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
cy_stc_tcpwm_pwm_config_t
PWM configuration structure.
Definition: cy_tcpwm_pwm.h:183
Cy_TCPWM_PWM_Init
cy_en_tcpwm_status_t Cy_TCPWM_PWM_Init(TCPWM_Type *base, uint32_t cntNum, cy_stc_tcpwm_pwm_config_t const *config)
Initializes the counter in the TCPWM block for the PWM operation.
Definition: cy_tcpwm_pwm.c:76
mtb_hal_clock_t
Clock object Application shall provide implementations for the functions needed by the clock object.
Definition: mtb_hal_hw_types_clock_srss.h:80

## 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);
}
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.
Definition: mtb_hal_pwm.c:141
mtb_hal_system_delay_ms
cy_rslt_t mtb_hal_system_delay_ms(uint32_t milliseconds)
Requests that the current operation delays for at least the specified length of time.
Definition: mtb_hal_system.c:63
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486

## 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