MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
TPM: Timer PWM Module

Overview

The MCUXpresso SDK provides a driver for the Timer PWM Module (TPM) of MCUXpresso SDK devices.

The TPM driver supports the generation of PWM signals, input capture, and output compare modes. On some SoCs, the driver supports the generation of combined PWM signals, dual-edge capture, and quadrature decoder modes. The driver also supports configuring each of the TPM fault inputs. The fault input is available only on some SoCs.

The function TPM_Init() initializes the TPM with a specified configurations. The function TPM_GetDefaultConfig() gets the default configurations. On some SoCs, the initialization function issues a software reset to reset the TPM internal logic. The initialization function configures the TPM's behavior when it receives a trigger input and its operation in doze and debug modes.

The function TPM_Deinit() disables the TPM counter and turns off the module clock.

The function TPM_SetupPwm() sets up TPM channels for the PWM output. The function can set up the PWM signal properties for multiple channels. Each channel has its own tpm_chnl_pwm_signal_param_t structure that is used to specify the output signals duty cycle and level-mode. However, the same PWM period and PWM mode is applied to all channels requesting a PWM output. The signal duty cycle is provided as a percentage of the PWM period. Its value should be between 0 and 100 where 0=inactive signal (0% duty cycle) and 100=always active signal (100% duty cycle). When generating a combined PWM signal, the channel number passed refers to a channel pair number, for example 0 refers to channel 0 and 1, 1 refers to channels 2 and 3.

The function TPM_UpdatePwmDutycycle() updates the PWM signal duty cycle of a particular TPM channel.

The function TPM_UpdateChnlEdgeLevelSelect() updates the level select bits of a particular TPM channel. This can be used to disable the PWM output when making changes to the PWM signal.

The function TPM_SetupInputCapture() sets up a TPM channel for input capture. The user can specify the capture edge.

The function TPM_SetupDualEdgeCapture() can be used to measure the pulse width of a signal. This is available only for certain SoCs. A channel pair is used during the capture with the input signal coming through a channel that can be configured. The user can specify the capture edge for each channel and any filter value to be used when processing the input signal.

The function TPM_SetupOutputCompare() sets up a TPM channel for output comparison. The user can specify the channel output on a successful comparison and a comparison value.

The function TPM_SetupQuadDecode() sets up TPM channels 0 and 1 for quad decode, which is available only for certain SoCs. The user can specify the quad decode mode, polarity, and filter properties for each input signal.

The function TPM_SetupFault() sets up the properties for each fault, which is available only for certain SoCs. The user can specify the fault polarity and whether to use a filter on a fault input. The overall fault filter value and fault control mode are set up during initialization.

Provides functions to get and clear the TPM status.

Provides functions to enable/disable TPM interrupts and get current enabled interrupts.

Typical use case

PWM output

Output the PWM signal on 2 TPM channels with different duty cycles. Periodically update the PWM signal duty cycle.

int main(void)
{
bool brightnessUp = true; /* Indicates whether the LED is brighter or dimmer. */
tpm_config_t tpmInfo;
uint8_t updatedDutycycle = 0U;
/* Configures the TPM parameters with frequency 24 kHZ. */
tpmParam[0].chnlNumber = (tpm_chnl_t)BOARD_FIRST_TPM_CHANNEL;
tpmParam[0].level = kTPM_LowTrue;
tpmParam[0].dutyCyclePercent = 0U;
tpmParam[1].chnlNumber = (tpm_chnl_t)BOARD_SECOND_TPM_CHANNEL;
tpmParam[1].level = kTPM_LowTrue;
tpmParam[1].dutyCyclePercent = 0U;
/* Board pin, clock, and debug console initialization. */
BOARD_InitHardware();
/* Initializes the TPM module. */
TPM_Init(BOARD_TPM_BASEADDR, &tpmInfo);
TPM_SetupPwm(BOARD_TPM_BASEADDR, tpmParam, 2U, kTPM_EdgeAlignedPwm, 24000U, TPM_SOURCE_CLOCK);
TPM_StartTimer(BOARD_TPM_BASEADDR, kTPM_SystemClock);
while (1)
{
/* Delays to see the change of LED brightness. */
delay();
if (brightnessUp)
{
/* Increases a duty cycle until it reaches a limited value. */
if (++updatedDutycycle == 100U)
{
brightnessUp = false;
}
}
else
{
/* Decreases a duty cycle until it reaches a limited value. */
if (--updatedDutycycle == 0U)
{
brightnessUp = true;
}
}
/* Starts PWM mode with an updated duty cycle. */
TPM_UpdatePwmDutycycle(BOARD_TPM_BASEADDR, (tpm_chnl_t)BOARD_FIRST_TPM_CHANNEL, kTPM_EdgeAlignedPwm,
updatedDutycycle);
TPM_UpdatePwmDutycycle(BOARD_TPM_BASEADDR, (tpm_chnl_t)BOARD_SECOND_TPM_CHANNEL, kTPM_EdgeAlignedPwm,
updatedDutycycle);
}
}

Data Structures

struct  tpm_chnl_pwm_signal_param_t
 Options to configure a TPM channel's PWM signal. More...
 
struct  tpm_config_t
 TPM config structure. More...
 

Enumerations

enum  tpm_chnl_t {
  kTPM_Chnl_0 = 0U,
  kTPM_Chnl_1,
  kTPM_Chnl_2,
  kTPM_Chnl_3,
  kTPM_Chnl_4,
  kTPM_Chnl_5,
  kTPM_Chnl_6,
  kTPM_Chnl_7
}
 List of TPM channels. More...
 
enum  tpm_pwm_mode_t {
  kTPM_EdgeAlignedPwm = 0U,
  kTPM_CenterAlignedPwm
}
 TPM PWM operation modes. More...
 
enum  tpm_pwm_level_select_t {
  kTPM_NoPwmSignal = 0U,
  kTPM_LowTrue,
  kTPM_HighTrue
}
 TPM PWM output pulse mode: high-true, low-true or no output. More...
 
enum  tpm_trigger_select_t
 Trigger options available. More...
 
enum  tpm_output_compare_mode_t {
  kTPM_NoOutputSignal = (1U << TPM_CnSC_MSA_SHIFT),
  kTPM_ToggleOnMatch = ((1U << TPM_CnSC_MSA_SHIFT) | (1U << TPM_CnSC_ELSA_SHIFT)),
  kTPM_ClearOnMatch = ((1U << TPM_CnSC_MSA_SHIFT) | (2U << TPM_CnSC_ELSA_SHIFT)),
  kTPM_SetOnMatch = ((1U << TPM_CnSC_MSA_SHIFT) | (3U << TPM_CnSC_ELSA_SHIFT)),
  kTPM_HighPulseOutput = ((3U << TPM_CnSC_MSA_SHIFT) | (1U << TPM_CnSC_ELSA_SHIFT)),
  kTPM_LowPulseOutput = ((3U << TPM_CnSC_MSA_SHIFT) | (2U << TPM_CnSC_ELSA_SHIFT))
}
 TPM output compare modes. More...
 
enum  tpm_input_capture_edge_t {
  kTPM_RisingEdge = (1U << TPM_CnSC_ELSA_SHIFT),
  kTPM_FallingEdge = (2U << TPM_CnSC_ELSA_SHIFT),
  kTPM_RiseAndFallEdge = (3U << TPM_CnSC_ELSA_SHIFT)
}
 TPM input capture edge. More...
 
enum  tpm_clock_source_t {
  kTPM_SystemClock = 1U,
  kTPM_ExternalClock
}
 TPM clock source selection. More...
 
enum  tpm_clock_prescale_t {
  kTPM_Prescale_Divide_1 = 0U,
  kTPM_Prescale_Divide_2,
  kTPM_Prescale_Divide_4,
  kTPM_Prescale_Divide_8,
  kTPM_Prescale_Divide_16,
  kTPM_Prescale_Divide_32,
  kTPM_Prescale_Divide_64,
  kTPM_Prescale_Divide_128
}
 TPM prescale value selection for the clock source. More...
 
enum  tpm_interrupt_enable_t {
  kTPM_Chnl0InterruptEnable = (1U << 0),
  kTPM_Chnl1InterruptEnable = (1U << 1),
  kTPM_Chnl2InterruptEnable = (1U << 2),
  kTPM_Chnl3InterruptEnable = (1U << 3),
  kTPM_Chnl4InterruptEnable = (1U << 4),
  kTPM_Chnl5InterruptEnable = (1U << 5),
  kTPM_Chnl6InterruptEnable = (1U << 6),
  kTPM_Chnl7InterruptEnable = (1U << 7),
  kTPM_TimeOverflowInterruptEnable = (1U << 8)
}
 List of TPM interrupts. More...
 
enum  tpm_status_flags_t {
  kTPM_Chnl0Flag = (1U << 0),
  kTPM_Chnl1Flag = (1U << 1),
  kTPM_Chnl2Flag = (1U << 2),
  kTPM_Chnl3Flag = (1U << 3),
  kTPM_Chnl4Flag = (1U << 4),
  kTPM_Chnl5Flag = (1U << 5),
  kTPM_Chnl6Flag = (1U << 6),
  kTPM_Chnl7Flag = (1U << 7),
  kTPM_TimeOverflowFlag = (1U << 8)
}
 List of TPM flags. More...
 

Driver version

#define FSL_TPM_DRIVER_VERSION   (MAKE_VERSION(2, 0, 2))
 Version 2.0.2.
 

Initialization and deinitialization

void TPM_Init (TPM_Type *base, const tpm_config_t *config)
 Ungates the TPM clock and configures the peripheral for basic operation. More...
 
void TPM_Deinit (TPM_Type *base)
 Stops the counter and gates the TPM clock. More...
 
void TPM_GetDefaultConfig (tpm_config_t *config)
 Fill in the TPM config struct with the default settings. More...
 

Channel mode operations

status_t TPM_SetupPwm (TPM_Type *base, const tpm_chnl_pwm_signal_param_t *chnlParams, uint8_t numOfChnls, tpm_pwm_mode_t mode, uint32_t pwmFreq_Hz, uint32_t srcClock_Hz)
 Configures the PWM signal parameters. More...
 
void TPM_UpdatePwmDutycycle (TPM_Type *base, tpm_chnl_t chnlNumber, tpm_pwm_mode_t currentPwmMode, uint8_t dutyCyclePercent)
 Update the duty cycle of an active PWM signal. More...
 
void TPM_UpdateChnlEdgeLevelSelect (TPM_Type *base, tpm_chnl_t chnlNumber, uint8_t level)
 Update the edge level selection for a channel. More...
 
void TPM_SetupInputCapture (TPM_Type *base, tpm_chnl_t chnlNumber, tpm_input_capture_edge_t captureMode)
 Enables capturing an input signal on the channel using the function parameters. More...
 
void TPM_SetupOutputCompare (TPM_Type *base, tpm_chnl_t chnlNumber, tpm_output_compare_mode_t compareMode, uint32_t compareValue)
 Configures the TPM to generate timed pulses. More...
 

Interrupt Interface

void TPM_EnableInterrupts (TPM_Type *base, uint32_t mask)
 Enables the selected TPM interrupts. More...
 
void TPM_DisableInterrupts (TPM_Type *base, uint32_t mask)
 Disables the selected TPM interrupts. More...
 
uint32_t TPM_GetEnabledInterrupts (TPM_Type *base)
 Gets the enabled TPM interrupts. More...
 

Status Interface

static uint32_t TPM_GetStatusFlags (TPM_Type *base)
 Gets the TPM status flags. More...
 
static void TPM_ClearStatusFlags (TPM_Type *base, uint32_t mask)
 Clears the TPM status flags. More...
 

Read and write the timer period

static void TPM_SetTimerPeriod (TPM_Type *base, uint32_t ticks)
 Sets the timer period in units of ticks. More...
 
static uint32_t TPM_GetCurrentTimerCount (TPM_Type *base)
 Reads the current timer counting value. More...
 

Timer Start and Stop

static void TPM_StartTimer (TPM_Type *base, tpm_clock_source_t clockSource)
 Starts the TPM counter. More...
 
static void TPM_StopTimer (TPM_Type *base)
 Stops the TPM counter. More...
 

Data Structure Documentation

struct tpm_chnl_pwm_signal_param_t

Data Fields

tpm_chnl_t chnlNumber
 TPM channel to configure. More...
 
tpm_pwm_level_select_t level
 PWM output active level select.
 
uint8_t dutyCyclePercent
 PWM pulse width, value should be between 0 to 100 0=inactive signal(0% duty cycle)... More...
 

Field Documentation

tpm_chnl_t tpm_chnl_pwm_signal_param_t::chnlNumber

In combined mode (available in some SoC's, this represents the channel pair number

uint8_t tpm_chnl_pwm_signal_param_t::dutyCyclePercent

100=always active signal (100% duty cycle)

struct tpm_config_t

This structure holds the configuration settings for the TPM peripheral. To initialize this structure to reasonable defaults, call the TPM_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

Data Fields

tpm_clock_prescale_t prescale
 Select TPM clock prescale value.
 
bool useGlobalTimeBase
 true: Use of an external global time base is enabled; false: disabled
 
tpm_trigger_select_t triggerSelect
 Input trigger to use for controlling the counter operation.
 
bool enableDoze
 true: TPM counter is paused in doze mode; false: TPM counter continues in doze mode
 
bool enableDebugMode
 true: TPM counter continues in debug mode; false: TPM counter is paused in debug mode
 
bool enableReloadOnTrigger
 true: TPM counter is reloaded on trigger; false: TPM counter not reloaded
 
bool enableStopOnOverflow
 true: TPM counter stops after overflow; false: TPM counter continues running after overflow
 
bool enableStartOnTrigger
 true: TPM counter only starts when a trigger is detected; false: TPM counter starts immediately
 

Enumeration Type Documentation

enum tpm_chnl_t
Note
Actual number of available channels is SoC dependent
Enumerator
kTPM_Chnl_0 

TPM channel number 0.

kTPM_Chnl_1 

TPM channel number 1.

kTPM_Chnl_2 

TPM channel number 2.

kTPM_Chnl_3 

TPM channel number 3.

kTPM_Chnl_4 

TPM channel number 4.

kTPM_Chnl_5 

TPM channel number 5.

kTPM_Chnl_6 

TPM channel number 6.

kTPM_Chnl_7 

TPM channel number 7.

Enumerator
kTPM_EdgeAlignedPwm 

Edge aligned PWM.

kTPM_CenterAlignedPwm 

Center aligned PWM.

Enumerator
kTPM_NoPwmSignal 

No PWM output on pin.

kTPM_LowTrue 

Low true pulses.

kTPM_HighTrue 

High true pulses.

This is used for both internal & external trigger sources (external option available in certain SoC's)

Note
The actual trigger options available is SoC-specific.
Enumerator
kTPM_NoOutputSignal 

No channel output when counter reaches CnV.

kTPM_ToggleOnMatch 

Toggle output.

kTPM_ClearOnMatch 

Clear output.

kTPM_SetOnMatch 

Set output.

kTPM_HighPulseOutput 

Pulse output high.

kTPM_LowPulseOutput 

Pulse output low.

Enumerator
kTPM_RisingEdge 

Capture on rising edge only.

kTPM_FallingEdge 

Capture on falling edge only.

kTPM_RiseAndFallEdge 

Capture on rising or falling edge.

Enumerator
kTPM_SystemClock 

System clock.

kTPM_ExternalClock 

External clock.

Enumerator
kTPM_Prescale_Divide_1 

Divide by 1.

kTPM_Prescale_Divide_2 

Divide by 2.

kTPM_Prescale_Divide_4 

Divide by 4.

kTPM_Prescale_Divide_8 

Divide by 8.

kTPM_Prescale_Divide_16 

Divide by 16.

kTPM_Prescale_Divide_32 

Divide by 32.

kTPM_Prescale_Divide_64 

Divide by 64.

kTPM_Prescale_Divide_128 

Divide by 128.

Enumerator
kTPM_Chnl0InterruptEnable 

Channel 0 interrupt.

kTPM_Chnl1InterruptEnable 

Channel 1 interrupt.

kTPM_Chnl2InterruptEnable 

Channel 2 interrupt.

kTPM_Chnl3InterruptEnable 

Channel 3 interrupt.

kTPM_Chnl4InterruptEnable 

Channel 4 interrupt.

kTPM_Chnl5InterruptEnable 

Channel 5 interrupt.

kTPM_Chnl6InterruptEnable 

Channel 6 interrupt.

kTPM_Chnl7InterruptEnable 

Channel 7 interrupt.

kTPM_TimeOverflowInterruptEnable 

Time overflow interrupt.

Enumerator
kTPM_Chnl0Flag 

Channel 0 flag.

kTPM_Chnl1Flag 

Channel 1 flag.

kTPM_Chnl2Flag 

Channel 2 flag.

kTPM_Chnl3Flag 

Channel 3 flag.

kTPM_Chnl4Flag 

Channel 4 flag.

kTPM_Chnl5Flag 

Channel 5 flag.

kTPM_Chnl6Flag 

Channel 6 flag.

kTPM_Chnl7Flag 

Channel 7 flag.

kTPM_TimeOverflowFlag 

Time overflow flag.

Function Documentation

void TPM_Init ( TPM_Type *  base,
const tpm_config_t config 
)
Note
This API should be called at the beginning of the application using the TPM driver.
Parameters
baseTPM peripheral base address
configPointer to user's TPM config structure.
void TPM_Deinit ( TPM_Type *  base)
Parameters
baseTPM peripheral base address
void TPM_GetDefaultConfig ( tpm_config_t config)

The default values are:

* config->prescale = kTPM_Prescale_Divide_1;
* config->useGlobalTimeBase = false;
* config->dozeEnable = false;
* config->dbgMode = false;
* config->enableReloadOnTrigger = false;
* config->enableStopOnOverflow = false;
* config->enableStartOnTrigger = false;
*#if FSL_FEATURE_TPM_HAS_PAUSE_COUNTER_ON_TRIGGER
* config->enablePauseOnTrigger = false;
*#endif
* config->triggerSelect = kTPM_Trigger_Select_0;
*#if FSL_FEATURE_TPM_HAS_EXTERNAL_TRIGGER_SELECTION
* config->triggerSource = kTPM_TriggerSource_External;
*#endif
*
Parameters
configPointer to user's TPM config structure.
status_t TPM_SetupPwm ( TPM_Type *  base,
const tpm_chnl_pwm_signal_param_t chnlParams,
uint8_t  numOfChnls,
tpm_pwm_mode_t  mode,
uint32_t  pwmFreq_Hz,
uint32_t  srcClock_Hz 
)

User calls this function to configure the PWM signals period, mode, dutycycle and edge. Use this function to configure all the TPM channels that will be used to output a PWM signal

Parameters
baseTPM peripheral base address
chnlParamsArray of PWM channel parameters to configure the channel(s)
numOfChnlsNumber of channels to configure, this should be the size of the array passed in
modePWM operation mode, options available in enumeration tpm_pwm_mode_t
pwmFreq_HzPWM signal frequency in Hz
srcClock_HzTPM counter clock in Hz
Returns
kStatus_Success if the PWM setup was successful, kStatus_Error on failure
void TPM_UpdatePwmDutycycle ( TPM_Type *  base,
tpm_chnl_t  chnlNumber,
tpm_pwm_mode_t  currentPwmMode,
uint8_t  dutyCyclePercent 
)
Parameters
baseTPM peripheral base address
chnlNumberThe channel number. In combined mode, this represents the channel pair number
currentPwmModeThe current PWM mode set during PWM setup
dutyCyclePercentNew PWM pulse width, value should be between 0 to 100 0=inactive signal(0% duty cycle)... 100=active signal (100% duty cycle)
void TPM_UpdateChnlEdgeLevelSelect ( TPM_Type *  base,
tpm_chnl_t  chnlNumber,
uint8_t  level 
)
Parameters
baseTPM peripheral base address
chnlNumberThe channel number
levelThe level to be set to the ELSnB:ELSnA field; valid values are 00, 01, 10, 11. See the appropriate SoC reference manual for details about this field.
void TPM_SetupInputCapture ( TPM_Type *  base,
tpm_chnl_t  chnlNumber,
tpm_input_capture_edge_t  captureMode 
)

When the edge specified in the captureMode argument occurs on the channel, the TPM counter is captured into the CnV register. The user has to read the CnV register separately to get this value.

Parameters
baseTPM peripheral base address
chnlNumberThe channel number
captureModeSpecifies which edge to capture
void TPM_SetupOutputCompare ( TPM_Type *  base,
tpm_chnl_t  chnlNumber,
tpm_output_compare_mode_t  compareMode,
uint32_t  compareValue 
)

When the TPM counter matches the value of compareVal argument (this is written into CnV reg), the channel output is changed based on what is specified in the compareMode argument.

Parameters
baseTPM peripheral base address
chnlNumberThe channel number
compareModeAction to take on the channel output when the compare condition is met
compareValueValue to be programmed in the CnV register.
void TPM_EnableInterrupts ( TPM_Type *  base,
uint32_t  mask 
)
Parameters
baseTPM peripheral base address
maskThe interrupts to enable. This is a logical OR of members of the enumeration tpm_interrupt_enable_t
void TPM_DisableInterrupts ( TPM_Type *  base,
uint32_t  mask 
)
Parameters
baseTPM peripheral base address
maskThe interrupts to disable. This is a logical OR of members of the enumeration tpm_interrupt_enable_t
uint32_t TPM_GetEnabledInterrupts ( TPM_Type *  base)
Parameters
baseTPM peripheral base address
Returns
The enabled interrupts. This is the logical OR of members of the enumeration tpm_interrupt_enable_t
static uint32_t TPM_GetStatusFlags ( TPM_Type *  base)
inlinestatic
Parameters
baseTPM peripheral base address
Returns
The status flags. This is the logical OR of members of the enumeration tpm_status_flags_t
static void TPM_ClearStatusFlags ( TPM_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseTPM peripheral base address
maskThe status flags to clear. This is a logical OR of members of the enumeration tpm_status_flags_t
static void TPM_SetTimerPeriod ( TPM_Type *  base,
uint32_t  ticks 
)
inlinestatic

Timers counts from 0 until it equals the count value set here. The count value is written to the MOD register.

Note
  1. This API allows the user to use the TPM module as a timer. Do not mix usage of this API with TPM's PWM setup API's.
  2. Call the utility macros provided in the fsl_common.h to convert usec or msec to ticks.
Parameters
baseTPM peripheral base address
ticksA timer period in units of ticks, which should be equal or greater than 1.
static uint32_t TPM_GetCurrentTimerCount ( TPM_Type *  base)
inlinestatic

This function returns the real-time timer counting value in a range from 0 to a timer period.

Note
Call the utility macros provided in the fsl_common.h to convert ticks to usec or msec.
Parameters
baseTPM peripheral base address
Returns
The current counter value in ticks
static void TPM_StartTimer ( TPM_Type *  base,
tpm_clock_source_t  clockSource 
)
inlinestatic
Parameters
baseTPM peripheral base address
clockSourceTPM clock source; once clock source is set the counter will start running
static void TPM_StopTimer ( TPM_Type *  base)
inlinestatic
Parameters
baseTPM peripheral base address