4.19. PWM Module

4.19.1. Acronyms and Definitions

Abbreviation/Term

Explanation

AUTOSAR

Automotive Open System Architecture

BSW

Basic Software

DET

Default Error Tracer

HW

Hardware

SW

Software

PWM

Pulse Width Modulation

MCU

Micro Controller Unit

OS

Operating System

PLL

Phase Locked loop

Definitions

Descriptions

PWM Channel

Numeric identifier linked to a hardware PWM.

PWM period

Defines the period of the PWM signal.

PWM Duty cycle

Defines a percentage of the starting level (could be high or low) related to the period.

PWM Idle State

The idle state represents the output state of the PWM channel after the call of Pwm_SetOutputToIdle or Pwm_DeInit.

PWM Output State

Defines the output state for a PWM signal. It could be High or Low.

4.19.2. Introduction

This document describes the functionality and configuration of the AUTOSAR BSW module PWM.

Supported AUTOSAR Release

4.3.1

Supported Configuration Variants

Pre-Compile, Post-build

Vendor ID

PWM_VENDOR_ID (44)

Module ID

PWM_MODULE_ID (121)

Supported Platform

AM263Px

The PWM driver provides functions for initialization and control of the microcontroller internal PWM stage (pulse width modulation).

4.19.3. Functional Overview

The PWM driver depends on other modules like DET for error handling, OSEK/AUTOSAR OS for interrupt handling, MCU module for system clock settings and SchM module which is BSW Scheduler provides functions that module PWM calls at begin and end of critical sections. Each PWM channel is linked to a hardware PWM which belongs to the microcontroller.

The PWM module generates pulses with variable pulse width and offers services to,

  1. Start output of a PWM signal.

  2. Stop output of a PWM signal.

  3. Set parameters of a PWM channel’s waveform.

  4. Set compare value for Events.

  5. Enable/disable notifications.

  6. Allows the selection of duty cycle and signal period time.

4.19.3.1. Initialization

The driver PWM is initialized by calling Pwm_Init() with a pointer to a configuration as parameter. To re-initialize call Pwm_DeInit() first and then Pwm_Init() with a different configuration.

The below table represents the PWM Channel state during the driver initialization

Point in time

Module state

Before Pwm_Init()

PWM_STATUS_UNINIT

After Pwm_Init()

PWM_STATUS_INIT

After Pwm_DeInit()

PWM_STATUS_UNINIT

4.19.3.2. Driver Architecture

The following figure shows where the PWM is located in the AUTOSAR architecture.

PWM in AUTOSAR architecture

Fig. 4.86 PWM in AUTOSAR architecture

The AUTOSAR Architecture distinguishes on the highest abstraction level between three software layers Application, Runtime Environment and Basic Software which run on a Microcontroller.

PWM Driver: The Pwm driver is part of the microcontroller abstraction layer (MCAL). The driver provides functions for initialization and control of the microcontroller internal PWM stage (pulse width modulation).

Interfaces to adjacent modules of the PWM

Fig. 4.87 Interfaces to adjacent modules of the PWM

Refer Integration Details section for detail explanation on adjacent modules of the PWM.

Standard alignment left and right, expressed by high and low

Fig. 4.88 priority level :align: center Standard alignment left and right, expressed by high and low priority level

4.19.3.3. Assumptions

None

4.19.3.4. Limitations

  1. Depending on specific use case, either the CDD PWM or MCAL PWM module should be selected. Both should not be used together.

  2. Same duty cycle will generate for both the channels EPWMxA and EPWMxB due to design constraint.

4.19.3.5. Design overview

Will be updated in future release

4.19.4. Hardware Features

4.19.4.1. IP Supported Features

  • Dedicated 16-bit time-base counter with period and frequency control.

  • Up Down count mode.

  • The HRPWM works together with the ePWM registers to extend resolution.

  • Two PWM outputs (EPWMxA and EPWMxB) that can be used. The DutyCycle and Period generated shall be same for both output, which is controlled by single PWM Channel.

  • The HRPWM is based on micro edge positioner(MEP) technology.

  • HRPWM feature should use the TI-supplied MEP scale factor optimizer (SFO) software function.The SFO function helps to dynamically determine the number of MEP steps per SYSCLKOUT period.

  • Same duty cycle will generate for both the channels EPWMxA and EPWMxB due to design constraint.

4.19.4.2. AUTOSAR Supported Features

  • Provide services to start and stop the output of pulse-width-modulated wave forms/signal.

  • Changing of frequency and duty cycle for a PWM channel at runtime besides the default configuration.

  • Enable/disable notifications. Allows the selection of duty cycle and signal period time.

  • There are a number of waveforms, which are supported by the PWM driver. The most widely used is standard PWM. Each period begins with an active state and changes to idle after the duty cycle has ended (see Figure 3). Idle output is configurable allowing high or low for idle state according to requirement.

4.19.4.3. Not supported Features

  • APIs related to the power state. PwmgetOutputState API is not supported and it always returns LOW

  • Asynchronous override control of PWM signals through software.

  • Programmable phase-control support for lag or lead operation relative to other ePWM modules

  • Hardware-locked (synchronized) phase relationship on a cycle-by-cycle basis

  • Dead-band generation with independent rising and falling edge delay control.

  • Programmable trip zone allocation of both cycle-by-cycle trip and one-shot trip on fault conditions.

  • A trip condition can force either high,low,or high-impedance state logic levels at PWM outputs.

  • All events can trigger both CPU interrupts and ADC start of conversion (SOC).

  • Programmable event prescaling minimizes CPU overhead on interrupts.

  • PWM chopping by high-frequency carrier signal, useful for pulse transformer gate drives.

4.19.4.4. Non compliance

4.19.4.4.1. Deviations to requirements (Requirement Traceability)

4.19.4.4.1.1. Deviation of requirements against AUTOSAR specification requirements

Will be updated in next release

4.19.5. Source files

Static source C Files are defined below

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Pwm
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┣ 📜Pwm.h : Contains the API’s of the PWM driver to be used by upper layers.
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📜Pwm.c : Implementation of the API’s for PWM driver.
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┗ 📜Pwm_Irq.c : Contains ISR function definitions.
┃ ┃ ┃ ┣ 📜Pwm_Irq.h : Contains ISR function declaration.
┃ ┃ ┃ ┗ 📜Pwm_Priv.c : Contains Internal Functions Definitions.
┃ ┃ ┃ ┣ 📜Pwm_Priv.h : Contains data structures and Internal function declarations.
┃ ┃ ┃ ┗ 📜Pwm_Sfo.c : Contains the Macros and function definitions relate Scale factor optimizer for HRPWM.
┃ ┃ ┃ ┣ 📜Pwm_Sfo.h : Contains the Macros and function declaration.
┃ ┃ ┗ 📜Makefile
┃ 📂mcal_config
┃ 📂mcal_docs
┃ 📜README.txt

Plugin files are defined below in the table.

Plugin Files

Description

Pwm_Cfg.h

Contains the base addresses, Precompile switches, Macros for channels, counters etc

Pwm_PBcfg.c

Contains all channels Post-Build Configuration parameters

Pwm_Cfg.c

Contains all channels Pre-Compile Configuration parameters

The below diagram shows the files structure for the PWM driver.

Header file structure of the PWM driver

Fig. 4.89 Header file structure of the PWM driver

4.19.6. Module requirements

Please refer Software Product Specification document provided as part of CSP.

4.19.6.1. Memory Mapping

The objects (e.g. variables, functions, constants) are declared by compiler independent definitions – the compiler abstraction definitions. Each compiler abstraction definition is assigned to a memory section. The following table contains the memory section names and the compiler abstraction definitions defined for the PWM and illustrate their assignment among each other.

Memory Mapping Sections

PWM_CODE

PWM_VAR_INIT

PWM_VAR_NOINIT

PWM_CONST

PWM_CONFIG_DATA

PWM_APPL_CODE

PWM_START_SEC_VAR_INIT_UNSPECIFIED (.data)

x

PWM_STOP_SEC_VAR_INIT_UNSPECIFIED

x

PWM_START_SEC_CODE (.text)

x

PWM_STOP_SEC_CODE

x

PWM_START_SEC_VAR_NO_INIT_UNSPECIFIED (.bss)

x

PWM_STOP_SEC_VAR_NO_INIT_UNSPECIFIED

x

PWM_START_SEC_CONST_UNSPECIFIED (.rodata)

x

PWM_STOP_SEC_CONST_UNSPECIFIED

x

PWM_START_SEC_ISR_CODE (.text)

x

PWM_STOP_SEC_ISR_CODE

x

PWM_START_SEC_CONST_PTR (.rodata)

x

PWM_STOP_SEC_CONST_PTR

x

PWM_START_SEC_CONFIG_DATA (.data)

x

PWM_STOP_SEC_CONFIG_DATA

x

4.19.6.2. Scheduling

4.19.6.2.1. SchM (Optional)

Beside the OSEK / AUTOSAR OS the BSW Scheduler provides functions that module PWM calls at begin and end of critical sections. There is only one kind of critical sections in this driver. Within these sections all read /modify / write accesses to internal PWM status variables must be protected. This is handled internally in the PWM driver by invoking SchM_Enter_Pwm_PWM_EXCLUSIVE_AREA_0()/ SchM_Exit_Pwm_PWM_EXCLUSIVE_AREA_0()

4.19.6.3. Error handling

4.19.6.3.1. Development Error Reporting (DET)

By default, development errors are reported to the Development Error Tracer (DET) using the service Det_ReportError() if detection and reporting of development errors is enabled in the configuration tool. If another module is used for development error reporting, the function name for reporting the error can be configured by the integrator, but must have the same signature as the service Det_ReportError().

AUTOSAR requires that API functions shall check the validity of their respective parameters. The errors reported to DET are described in the following table

Type of Error

Related Error code

Value (Hex)

Parameter ConfigPtr references NULL.

PWM_E_PARAM_CONFIG

0x10

API service used without module initialization of driver.

PWM_E_UNINIT

0x11

API parameter has invalid channel.

PWM_E_PARAM_CHANNEL

0x12

Usage of unauthorized PWM service on PWM channel configured a fixed period.

PWM_E_PERIOD_UNCHANGEABLE

0x13

API Pwm_Init service called while the module already initialized

PWM_E_ALREADY_INITIALIZED

0x14

API parameter passed with invalid pointer(NULL)

PWM_E_PARAM_POINTER

0x15

4.19.6.3.2. Runtime Errors

Type of Error

Related Error code

Value (Hex)

API Pwm_SetPowerState is called while the PWM module is still in use(running).

PWM_E_NOT_DISENGAGED

0x16

4.19.7. Used resources

4.19.7.1. Interrupt Handling

For each of the configured hardware units, one interrupt service routine has to be mapped. The Integrator has to map the interrupt service routines to the interrupt sources of the respective PWM unit interrupt. The supported ISR’s are part of the Pwm_Irq.h file.

For interrupt notification, ISR’s are provided in PWM driver. There is one ISR for each PWM hardware unit. Depending on hardware unit configured, it will call group notify function. The interrupt service routines shall be mapped to the interrupt sources of the respective cross bar interrupt.

Hardware units

ISR API Mapped

0

Pwm_Ch0Isr( void )

1

Pwm_Ch1Isr( void )

2

Pwm_Ch2Isr( void )

3

Pwm_Ch3Isr( void )

4

Pwm_Ch4Isr( void )

5

Pwm_Ch5Isr( void )

6

Pwm_Ch6Isr( void )

7

Pwm_Ch7Isr( void )

8

Pwm_Ch8Isr( void )

9

Pwm_Ch9Isr( void )

10

Pwm_Ch10Isr( void )

126

Pwm_Ch126Isr( void )

127

Pwm_Ch127Isr( void )

4.19.8. Integration description

4.19.8.1. Dependent modules

4.19.8.1.1. OSEK / AUTOSAR OS (Optional)

An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table. The PWM module may use OSEK/AUTOSAR OS to suspend and restore global interrupts.

4.19.8.1.2. MCU

The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL(not directly) and the internal clock domains.

The PWM module depends on MCU module for enabling PWM clock for channel and crossbar interrupt mapping of PWM interrupts depending on the PWM channel configured.

Suppose the PWM channel 0 are configured for PWM module as shown in below figure:

../_images/pwm_image5.JPG

Then, the MCU module container “McuPwmConfiguration” should be configured as shown in below figure:

../_images/pwm_image6.JPG

Similarly, the crossbar interrupts also need to be mapped in MCU module according to PWM channel configured. The PWM interrupts needs to be mapped to the corresponding cross bar interrupt.

../_images/pwm_image7.JPG

NOTE : McuPwmConfiguration and McuCddPwmConfiguration cannot be used together.

4.19.8.1.3. PORT

Module PORT configures the port pins that are used for output of PWM signal. For details see Technical Reference of Port.

4.19.8.1.4. DET

The module PWM depends on the DET (by default) in order to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch.

“Enable Development Error Detection”.

The DET can be replaced optionally by an equivalent component which is responsible to recognize development errors, if no DET component is available.

4.19.8.1.5. Callback Notification

The Pwm driver provide configured notification call back for each interrupt occurred.

4.19.8.2. Multi-core and Resource allocator

Will be updated in the next release

4.19.9. Configuration

The Wdg is configured through GUI in Post-Build, Pre-Compile Variants and Link Time Variants.

Variants

Configured Files

PostBuild

Pwm_PBcfg.c, Pwm_Cfg.c, Pwm_Cfg.h

Pre-Compile

Pwm_Cfg.c, Pwm_Cfg.h

4.19.9.1. Parameter Description

4.19.9.1.1. Standard Configuration

Standard Parameters

Description

Default Value

Range

Unit/DataType

PwmChannelClass

Class of PWM Channel.

PWM_FIXED_PERIOD

PWM_FIXED_PERIOD

PWM_FIXED_PERIOD_SHIFTED

PWM_VARIABLE_PERIOD

Enumeration

PwmChannelId

Channel Id of the PWM channel. This value will be assigned to the symbolic name derived of the PwmChannel container short name.

0

0..255

Integer

PwmDutycycleDefault

Value of duty cycle used for Initialization

16384

0..32768

Integer

PwmIdleState

The parameter PWM_IDLE_STATE represents the output state of the PWM after the signal is stopped

PWM_HIGH

PWM_HIGH

PWM_LOW

Enumeration

PwmNotification

Definition of the Callback function.

NULL_PTR

String

PwmPeriodDefault

Value of period used for Initialization.(in seconds).

1

0..Infinity

Float

PwmPolarity

Defines the starting polarity of each PWM channel.

PWM_HIGH

PWM_HIGH

PWM_LOW

Enumeration

PwmMcuClockReferencePoint

This parameter contains reference to the McuClockReferencePoint

REFERENCE

PwmDeInitApi

Adds / removes the service Pwm_DeInit() from the code.

TRUE

TRUE

FALSE

Boolean

PwmGetOutputState

Get Output state

FALSE

TRUE

FALSE

Boolean

PwmSetDutyCycle

Set Duty cycle

TRUE

TRUE

FALSE

Boolean

PwmSetOutputToIdle

Set output to idle

TRUE

TRUE

FALSE

Boolean

PwmSetPeriodAndDuty

Set Period and duty

TRUE

TRUE

FALSE

Boolean

PwmVersionInfoApi

Switch to indicate that the Pwm_ GetVersionInfo is supported

FALSE

TRUE

FALSE

Boolean

PwmDevErrorDetect

Switch for enabling the development error detection.

TRUE

TRUE

FALSE

Boolean

PwmDutycycleUpdatedEndperiod

Switch for enabling the update of the duty cycle parameter at the end of the current period.

TRUE

TRUE

FALSE

Boolean

PwmIndex

Specifies the InstanceId of this module instance. If only one instance is present it shall have the Id 0.

1

0..1

Integer

PwmNotificationSupported

Switch to indicate that the notifications are supported

TRUE

TRUE

FALSE

Boolean

PwmPeriodUpdatedEndperiod

Switch for enabling the update of the period parameter at the end of the current period.

TRUE

TRUE

FALSE

Boolean

PwmPowerStateAsynchTransitionMode

Enables / disables support of the PWM Driver to the asynchronous power state transition.

FALSE

TRUE

FALSE

Boolean

PwmPowerState

Each instance of this parameter describes a different power state supported by the PWM HW. It should be defined by the HW supplier and used by the PWMDriver to reference specific HW configurations which set the PWM HW module in the referenced power state.

0

0..9223372036854775807

Integer

PwmPowerStateReadyCbkRef

Each instance of this parameter contains a reference to a power mode callback defined in a CDD or IoHwAbs component.

FUNCTION

4.19.9.1.2. IP Specific Configuration

IP Specific Parameters

Description

Default Value

Range

Unit/DataType

PwmSysClockFrequency

Value of the System clock frequency in Hz Default frequency is 200MHz

1

1..200000000

INTEGER

PwmErrorHook

Used to report development errors.

Det_ReportError

NA

STRING

PwmDetIncludeFile

Includes the header file where the Error hook function is defined.

Det.h

NA

STRING

PwmNotificationsIncludeFile

Includes the header file where the notification functions are defined.

STRING

PwmCfgDebugReporting

Switch to Enable/disable debug support.

TRUE

TRUE

FALSE

BOOLEAN

PwmTypeofInterruptFunction

Type of ISR function

PWM_ISR_CAT1

PWM_ISR_VOID

PWM_ISR_CAT1

PWM_ISR_CAT2

ENUMERATION

PwmDeviceVariant

Device variant

AM263Px

AM263Px

STRING

PwmHWChannelId

Channel Id of the PWM channel

0

0..31

INTEGER

PwmOutputChSelect

PWM Output Channel select EPWMxA or EPWMxB or Both. Both Outputs available with same duty cycle, period and polarity

PWM_OUTPUT_CH_A

PWM_OUTPUT_CH_A

PWM_OUTPUT_CH_B

PWM_OUTPUT_CH_BOTH_A_AND_B

ENUMERATION

PwmFunctionalClock

Value of the System clock frequency in Hz Default frequency is 125MHz for EPWM

19200000

INTEGER

PwmClkPrescaler

The clock to Timer module is divided by the value specified

0

0..7

INTEGER

PwmHSClkPrescaler

High-Speed Time-base Clock Prescale Bits

0

0..7

INTEGER

PwmEnableHighRes

This parameter will be a switch to enable or disable high resolution (HRPWM) capability of EPWM module

FALSE

TRUE

FALSE

BOOLEAN

PwmEnableRegisterReadbackApi

Switch to indicate that the Pwm_RegisterReadBack is supported

TRUE

TRUE

FALSE

BOOLEAN

PwmDefaultOSCounterId

Default Os Counter Id if node reference to OsCounter ref PwmOsCounterRef is not set

0

0..16

INTEGER

PwmOsCounterRef

This parameter contains a reference to the OsCounter which is used by the PWM driver

REFERENCE

PwmHwUnit

PWM Hardware Unit

PWM_CONTROLSS_G0

PWM_CONTROLSS_G0

PWM_CONTROLSS_G1

PWM_CONTROLSS_G2

PWM_CONTROLSS_G3

ENUMERATION

PwmSfoSupportEnable

Switch for enabling the SFO Inclusion for HRPWM ,If HRPWM is enabled

FALSE

TRUE

FALSE

BOOLEAN

PwmMaxTimeoutDuration

Maximum time duration for PWM SFO status. Unit is in clock ticks. Configure the timeout according to r5f clock frequency(400MHz/200MHz)

10000

1..4294967295

INTEGER

Note: PwmMaxTimeoutDuration parameter Value should be passed as number of ticks according to clock frequency. The clock source have changed from RTI timers which used 200MHz clock frequency to R5f timers which uses 400MHz clock frequency, so the timeout values need to be configured accordingly.

4.19.9.2. Symbolic Names deviations

None

4.19.9.3. Configuration rules and constraints to enable plausibility checks

Will be updated in future release

4.19.10. Examples

4.19.10.1. Overview

Will be updated in the next release

4.19.10.2. Hardware Software Setup and Tools

None

4.19.10.3. Steps to build and run example

Pwm example application demonstrating the MCAL PWM driver features is in folder <MCAL_ROOT>/examples/Pwm.

This application can be built from the build folder by giving “gmake -s pwm_app PLATFORM= am263px”.

  1. Module is tested in AM263Px-CC board.

  2. Oscilloscope is used to monitor PWM dutycycle and frequency Variation

  3. The PWM module example is configured with channel id PWM_CHANNEL_PWM_CONTROLSS_G0_PWMCHANNEL9 , which is mapped to physical channel EPWM9

  4. Connect EPWM output pin of 9th channel to Oscilloscope and check the output in CRO

  5. Example code is tested for variation of Frequency and Duty cycle

The PWM module testing procedure as follows:

  1. The PWM module is initialized with configured values : Dutycycle as 50% and Frequency as 1KHz

  2. The PWM signal is changed to Dutycycle of 80 percent with Pwm_SetDutyCycle API

  3. The PWM signal is changed to Dutycycle of 100 percent with Pwm_SetDutyCycle API

  4. The PWM signal is output to Idle state with Pwm_SetOutputToIdle API

  5. The PWM Frequency is changed to 10KHz and Dutycycle of 50 percent with Pwm_SetPeriodAndDuty API.

4.19.10.4. Example Logs


   PWM_APP: Sample Application - STARTS !!!

   PWM_APP: PWM MCAL Version Info
   ---------------------
   PWM_APP: Vendor ID           : 44
   PWM_APP: Module ID           : 121
   PWM_APP: SW Major Version    : 9
   PWM_APP: SW Minor Version    : 1
   PWM_APP: SW Patch Version    : 0

   PWM_APP: EPWM being used with Channel 0 !!! 
   PWM_APP: Variant - Post Build being used !!!

   PWM_APP: Changing the Duty cycle from to 50 to 80 percent 
   PWM_APP: This example waits for 30 seconds Please probe

   PWM_APP: Changing the Duty cycle to 100 Percent 
   PWM_APP: This example waits for 10 seconds Please probe

   PWM_APP: Setting Output to Idle state 
   PWM_APP: This example waits for 10 seconds Please probe

   PWM_APP: Changing Frequency from 1kHz to 10KHz and Duty Cycle to 50%
   PWM_APP: period is set to 20000
   PWM_APP: This app again waits for 30 seconds please probe
   PWM_APP: Pwm Isr Count: 300000 

   PWM_APP: Disabling Notifications for PWM channel
   PWM Test Completed !!!
   PWM Stack Usage: 792 bytes
   All tests have Passed !!!
   PWM_APP: Sample Application - DONE !!!
   

4.19.10.5. File Structure

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Pwm
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┣ 📜Makefile
┃ ┃ ┃ ┣ 📜PwmApp.c : Contains PWM test example.
┃ ┃ ┃ ┣ 📜PwmApp.h : Contains PWM test example header.
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Pwm_Demo_Cfg
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┣ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Pwm_Cfg.h : Contains the Precompile switches and macros.
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Pwm_Cfg.c : Contains all Pre-Compile Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Pwm_PBcfg.c : Contains all Post-Build Configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┣ 📜README.txt

4.19.11. FAQ’s

Will be updated in next release

4.19.12. Test Report

Please refer AM26x PWM Driver Test Case Report as part of CSP provided in the release package.

4.19.13. References

AUTOSAR_SWS_PWMDriver
Technical Reference Manual