caffeine-hal 0.6.6
A Header-Defined Interface c library, it provides the hal layer for the Caffeine framework
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
cfn_hal_pwm.h File Reference

Pulse Width Modulation (PWM) HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_gpio.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures

struct  cfn_hal_pwm_phy_t
 PWM hardware physical mapping. More...
 
struct  cfn_hal_pwm_config_t
 PWM configuration structure. More...
 
struct  cfn_hal_pwm_api_s
 PWM Virtual Method Table (VMT). More...
 

Typedefs

typedef struct cfn_hal_pwm_s cfn_hal_pwm_t
 
typedef struct cfn_hal_pwm_api_s cfn_hal_pwm_api_t
 
typedef void(* cfn_hal_pwm_callback_t) (cfn_hal_pwm_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
 PWM callback signature.
 

Enumerations

enum  cfn_hal_pwm_event_t { CFN_HAL_PWM_EVENT_NONE = 0 , CFN_HAL_PWM_EVENT_PERIOD_MATCH = CFN_HAL_BIT(0) , CFN_HAL_PWM_EVENT_PULSE_MATCH = CFN_HAL_BIT(1) }
 PWM nominal event flags. More...
 
enum  cfn_hal_pwm_error_t { CFN_HAL_PWM_ERROR_NONE = 0 , CFN_HAL_PWM_ERROR_FAULT = CFN_HAL_BIT(0) , CFN_HAL_PWM_ERROR_GENERAL = CFN_HAL_BIT(1) }
 PWM exception error flags. More...
 
enum  cfn_hal_pwm_config_polarity_t { CFN_HAL_PWM_CONFIG_POLARITY_NORMAL , CFN_HAL_PWM_CONFIG_POLARITY_INVERTED }
 PWM output polarity. More...
 

Functions

 CFN_HAL_VMT_CHECK (struct cfn_hal_pwm_api_s)
 
 CFN_HAL_CREATE_DRIVER_TYPE (pwm, cfn_hal_pwm_config_t, cfn_hal_pwm_api_t, cfn_hal_pwm_phy_t, cfn_hal_pwm_callback_t)
 
CFN_HAL_INLINE void cfn_hal_pwm_populate (cfn_hal_pwm_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_pwm_api_t *api, const cfn_hal_pwm_phy_t *phy, const cfn_hal_pwm_config_t *config, cfn_hal_pwm_callback_t callback, void *user_arg)
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_validate (const cfn_hal_pwm_t *driver, const cfn_hal_pwm_config_t *config)
 Validates the PWM configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_init (cfn_hal_pwm_t *driver)
 Initializes the PWM driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_deinit (cfn_hal_pwm_t *driver)
 Deinitializes the PWM driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_set (cfn_hal_pwm_t *driver, const cfn_hal_pwm_config_t *config)
 Sets the PWM configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_get (cfn_hal_pwm_t *driver, cfn_hal_pwm_config_t *config)
 Gets the current PWM configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_callback_register (cfn_hal_pwm_t *driver, const cfn_hal_pwm_callback_t callback, void *user_arg)
 Registers a callback for PWM events and errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_power_state_set (cfn_hal_pwm_t *driver, cfn_hal_power_state_t state)
 Sets the PWM power state.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_enable (cfn_hal_pwm_t *driver, uint32_t event_mask)
 Enables one or more PWM nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_disable (cfn_hal_pwm_t *driver, uint32_t event_mask)
 Disables one or more PWM nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_get (cfn_hal_pwm_t *driver, uint32_t *event_mask)
 Retrieves the current PWM nominal event status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_enable (cfn_hal_pwm_t *driver, uint32_t error_mask)
 Enables one or more PWM exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_disable (cfn_hal_pwm_t *driver, uint32_t error_mask)
 Disables one or more PWM exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_get (cfn_hal_pwm_t *driver, uint32_t *error_mask)
 Retrieves the current PWM exception error status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_start (cfn_hal_pwm_t *driver)
 Starts PWM signal generation.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_stop (cfn_hal_pwm_t *driver)
 Stops PWM signal generation.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_set_frequency (cfn_hal_pwm_t *driver, uint32_t frequency_hz)
 Updates the PWM output frequency.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_set_duty_cycle (cfn_hal_pwm_t *driver, uint32_t duty_percent)
 Updates the PWM duty cycle.
 
cfn_hal_error_code_t cfn_hal_pwm_construct (cfn_hal_pwm_t *driver, const cfn_hal_pwm_config_t *config, const cfn_hal_pwm_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_pwm_callback_t callback, void *user_arg)
 
cfn_hal_error_code_t cfn_hal_pwm_destruct (cfn_hal_pwm_t *driver)
 

Detailed Description

Pulse Width Modulation (PWM) HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

◆ cfn_hal_pwm_api_t

◆ cfn_hal_pwm_callback_t

typedef void(* cfn_hal_pwm_callback_t) (cfn_hal_pwm_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

PWM callback signature.

Parameters
driverPointer to the PWM driver instance.
event_maskMask of triggered nominal events.
error_maskMask of triggered exception errors.
user_argUser-defined argument passed during registration.

◆ cfn_hal_pwm_t

typedef struct cfn_hal_pwm_s cfn_hal_pwm_t

Enumeration Type Documentation

◆ cfn_hal_pwm_config_polarity_t

PWM output polarity.

Enumerator
CFN_HAL_PWM_CONFIG_POLARITY_NORMAL 

High during pulse, Low during remainder

CFN_HAL_PWM_CONFIG_POLARITY_INVERTED 

Low during pulse, High during remainder

◆ cfn_hal_pwm_error_t

PWM exception error flags.

Enumerator
CFN_HAL_PWM_ERROR_NONE 
CFN_HAL_PWM_ERROR_FAULT 

External break or safety fault

CFN_HAL_PWM_ERROR_GENERAL 

General hardware error

◆ cfn_hal_pwm_event_t

PWM nominal event flags.

Enumerator
CFN_HAL_PWM_EVENT_NONE 
CFN_HAL_PWM_EVENT_PERIOD_MATCH 

Timer period reached (cycle end)

CFN_HAL_PWM_EVENT_PULSE_MATCH 

Compare match reached (duty transition)

Function Documentation

◆ CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE ( pwm  ,
cfn_hal_pwm_config_t  ,
cfn_hal_pwm_api_t  ,
cfn_hal_pwm_phy_t  ,
cfn_hal_pwm_callback_t   
)

◆ cfn_hal_pwm_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_callback_register ( cfn_hal_pwm_t driver,
const cfn_hal_pwm_callback_t  callback,
void *  user_arg 
)

Registers a callback for PWM events and errors.

Parameters
driverPointer to the PWM driver instance.
callbackThe callback function to register.
user_argUser-defined argument passed to the callback.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_get ( cfn_hal_pwm_t driver,
cfn_hal_pwm_config_t config 
)

Gets the current PWM configuration.

Parameters
driverPointer to the PWM driver instance.
config[out] Pointer to store the configuration.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_set ( cfn_hal_pwm_t driver,
const cfn_hal_pwm_config_t config 
)

Sets the PWM configuration.

Parameters
driverPointer to the PWM driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_config_validate ( const cfn_hal_pwm_t driver,
const cfn_hal_pwm_config_t config 
)

Validates the PWM configuration.

Parameters
driverPointer to the PWM driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_construct()

cfn_hal_error_code_t cfn_hal_pwm_construct ( cfn_hal_pwm_t driver,
const cfn_hal_pwm_config_t config,
const cfn_hal_pwm_phy_t phy,
struct cfn_hal_clock_s *  clock,
void *  dependency,
cfn_hal_pwm_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_pwm_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_deinit ( cfn_hal_pwm_t driver)

Deinitializes the PWM driver.

Parameters
driverPointer to the PWM driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_destruct()

cfn_hal_error_code_t cfn_hal_pwm_destruct ( cfn_hal_pwm_t driver)

◆ cfn_hal_pwm_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_disable ( cfn_hal_pwm_t driver,
uint32_t  error_mask 
)

Disables one or more PWM exception errors.

Parameters
driverPointer to the PWM driver instance.
error_maskMask of errors to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_enable ( cfn_hal_pwm_t driver,
uint32_t  error_mask 
)

Enables one or more PWM exception errors.

Parameters
driverPointer to the PWM driver instance.
error_maskMask of errors to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_error_get ( cfn_hal_pwm_t driver,
uint32_t *  error_mask 
)

Retrieves the current PWM exception error status.

Parameters
driverPointer to the PWM driver instance.
error_mask[out] Pointer to store the error mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_disable ( cfn_hal_pwm_t driver,
uint32_t  event_mask 
)

Disables one or more PWM nominal events.

Parameters
driverPointer to the PWM driver instance.
event_maskMask of events to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_enable ( cfn_hal_pwm_t driver,
uint32_t  event_mask 
)

Enables one or more PWM nominal events.

Parameters
driverPointer to the PWM driver instance.
event_maskMask of events to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_event_get ( cfn_hal_pwm_t driver,
uint32_t *  event_mask 
)

Retrieves the current PWM nominal event status.

Parameters
driverPointer to the PWM driver instance.
event_mask[out] Pointer to store the event mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_init ( cfn_hal_pwm_t driver)

Initializes the PWM driver.

Parameters
driverPointer to the PWM driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_populate()

CFN_HAL_INLINE void cfn_hal_pwm_populate ( cfn_hal_pwm_t driver,
uint32_t  peripheral_id,
struct cfn_hal_clock_s *  clock,
void *  dependency,
const cfn_hal_pwm_api_t api,
const cfn_hal_pwm_phy_t phy,
const cfn_hal_pwm_config_t config,
cfn_hal_pwm_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_pwm_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_power_state_set ( cfn_hal_pwm_t driver,
cfn_hal_power_state_t  state 
)

Sets the PWM power state.

Parameters
driverPointer to the PWM driver instance.
stateTarget power state.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_set_duty_cycle()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_set_duty_cycle ( cfn_hal_pwm_t driver,
uint32_t  duty_percent 
)

Updates the PWM duty cycle.

Parameters
driverPointer to the PWM driver instance.
duty_percentThe new target duty cycle (0 to 100).
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_set_frequency()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_set_frequency ( cfn_hal_pwm_t driver,
uint32_t  frequency_hz 
)

Updates the PWM output frequency.

Parameters
driverPointer to the PWM driver instance.
frequency_hzThe new target frequency in Hertz.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_start()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_start ( cfn_hal_pwm_t driver)

Starts PWM signal generation.

Parameters
driverPointer to the PWM driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_pwm_stop()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_pwm_stop ( cfn_hal_pwm_t driver)

Stops PWM signal generation.

Parameters
driverPointer to the PWM driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK ( struct cfn_hal_pwm_api_s  )