4.18. PWM¶
4.18.1. About This Document¶
Document Title |
User Guide of MCAL PWM Driver |
Document Version |
Version 1.0 |
Company |
Texas Instruments |
Document Name |
PWM User Guide |
4.18.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
13 Oct 2023 |
Initial Release. |
Approved |
4.18.3. Table of contents¶
4.18.4. Acronyms and Definitions¶
Acronyms and Definitions Used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
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. Low. |
4.18.5. Functional Overview¶
4.18.5.1. Brief Overview¶
This document describes the functionality, API 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 |
This document describes the functionality and the API of the PWM (Pulse Width Modulation) driver for the AM263px.
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 driver provides functions for initialization and control of the microcontroller internal PWM stage (pulse width modulation). The PWM module generates pulses with variable pulse width and offers services to,
Start output of a PWM signal.
Stop output of a PWM signal.
Set parameters of a PWM channel’s waveform.
Set compare value for Events.
Enable/disable notifications.
Allows the selection of duty cycle and signal period time.
4.18.5.1.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.18.6. Driver Architecture¶
The following figure shows where the PWM is located in the AUTOSAR architecture.
Figure 1: 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).
Figure 2: Interfaces to adjacent modules of the PWM
Refer Integration Details section for detail explanation on adjacent modules of the PWM
4.18.6.1. Supported and Not Supported Features¶
The features listed in this chapter cover the complete functionality specified
IP Supported Features |
AUTOSAR Supported Features |
Not Supported |
|---|---|---|
Dedicated 16-bit time-base counter with period and frequency control |
Provide services to start and stop the output of pulse-width- modulated wave forms/signal. |
APIs related to the power state. PwmgetOutputState API is not supported and it always returns LOW |
Up Down count mode. |
Changing of frequency and duty cycle for a PWM channel at runtime besides the default configuration. |
Asynchronous override control of PWM signals through software. |
The HRPWM works together with the ePWM registers to extend resolution. |
Enable/disable notifications. Allows the selection of duty cycle and signal period time. |
Programmable phase-control support for lag or lead operation relative to other ePWM modules |
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. |
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. |
Hardware-locked (synchronized) phase relationship on a cycle-by-cycle basis |
The HRPWM is based on micro edge positioner(MEP) technology. |
Dead-band generation with independent rising and falling edge delay control. |
|
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. |
Programmable trip zone allocation of both cycle-by-cycle trip and one-shot trip on fault conditions. |
|
Same duty cycle will generate for both the channels EPWMxA and EPWMxB due to design constraint. |
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. |
Figure 3: Standard alignment left and right, expressed by high and low priority level
4.18.6.2. Assumptions¶
None
4.18.6.3. Limitations¶
Note
CDD PWM module and MCAL PWM module shall not use same EPWM channel.
Same duty cycle will generate for both the channels EPWMxA and EPWMxB due to design constraint.
4.18.6.4. Design overview(Link to the Architecture document and Design Document)¶
Will be updated in future release
4.18.6.5. File Structure¶
Static source C File Structure is defined below in the table.
Static source C File Structure |
Description |
|---|---|
Pwm.h |
Contains the API’s of the PWM driver to be used by upper layers |
Pwm_Priv.h |
Contains data structures and Internal function declarations |
Pwm_Irq.h |
Contains ISR function declaration |
Pwm.c |
Implementation of the API’s for PWM driver. |
Pwm_Priv.c |
Contains Internal Functions Definitions. |
Pwm_Irq.c |
Contains ISR function definitions. |
Pwm_Reg.h |
Declaration of Register and its base address. |
Pwm_Platform.h |
Contains the platform dependent Macros and structure declaration. |
Pwm_Sfo.h |
Contains the Macros and function declaration. |
Pwm_Sfo.c |
Contains the Macros and function definitions relate Scale factor optimizer for HRPWM |
Plugin file structure is defined below in the table.
Plugin Structure |
Descriptions |
|---|---|
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.
Figure 4: Header file structure of the PWM driver
4.18.7. Deviations to requirements(Requirement Traceability)¶
4.18.7.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.18.7.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.18.8. Integration Details¶
4.18.8.1. Dependency on Other Software Modules¶
4.18.8.1.1. OSEK / AUTOSAR OS (Optional)¶
An operating system can be used fortask 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.18.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:
Then, the MCU module container “McuPwmConfiguration” should be configured as shown in below figure:
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.
NOTE : McuPwmConfiguration and McuCddPwmConfiguration cannot be used together.
4.18.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.18.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.18.8.1.5. Error Handling¶
Development Error Reporting
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.
Type of Error |
Relevance |
Related Error Code |
Value |
|---|---|---|---|
Parameter ConfigPtr references NULL. |
Development |
PWM_E_PARAM_CONFIG |
0x10 |
API service used without module initialization of driver. |
Development |
PWM_E_UNINIT |
0x11 |
API parameter has invalid channel. |
Development |
PWM_E_PARAM_CHANNEL |
0x12 |
Usage of unauthorized PWM service on PWM channel configured a fixed period. |
Development |
PWM_E_PERIOD_UNCHANGEABLE |
0x13 |
API Pwm_Init service called while the module already initialized |
Development |
PWM_E_ALREADY_INITIALIZED |
0x14 |
API parameter passed with invalid pointer(NULL) |
Development |
PWM_E_PARAM_POINTER |
0x15 |
4.18.8.1.6. Error Handling: Runtime Errors¶
Type of Error |
Relevance |
Related Error Code |
Value |
|---|---|---|---|
API Pwm_SetPowerState is called while the PWM module is still in use(running). |
Development |
PWM_E_NOT_DISENGAGED |
0x16 |
4.18.8.1.7. Callback Notification¶
The Pwm driver provide configured notification call back for each interrupt occurred.
4.18.8.2. Hardware - Software - ISR API name mapping¶
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 ) |
To |
|
126 |
Pwm_Ch126Isr( void ) |
127 |
Pwm_Ch127Isr( void ) |
4.18.8.3. Scheduling Strategy¶
4.18.8.3.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.18.9. API Description¶
4.18.9.1. Description of the API’s(Can be referred to Api Guide spec)¶
Refer the AUTOSAR SWS for API documentation and Type definition.
4.18.9.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Service ID |
Service |
|---|---|
0x00 |
Pwm_Init |
0x01 |
Pwm_DeInit |
0x02 |
Pwm_SetDutyCycle |
0x03 |
Pwm_SetPeriodAndDuty |
0x04 |
Pwm_SetOutputToIdle |
0x06 |
Pwm_DisableNotification |
0x07 |
Pwm_EnableNotification |
0x08 |
Pwm_GetVersionInfo |
Autosar API’s not Supported:
Service ID |
Service |
|---|---|
0x09 |
Pwm_SetPowerState |
0x0a |
Pwm_GetCurrentPowerState |
0x0b |
Pwm_GetTargetPowerState |
0x0c |
Pwm_PreparePowerState |
0x05 |
Pwm_GetOuputState |
Refer Autosar SWS for API description mentioned in above table.
4.18.9.3. Description on Non Standard API’s¶
Pwm_RegisterReadback API–This function is non-autosar based and is used to read the data in the registers of Pwm if we keep PWM_REGISTER_READBACK_API Macro as ON. and Service Id is 0xD0.
4.18.10. Configuration Description¶
4.18.10.1. Configuration Variants¶
The PWM is configured through GUI in Post-Build and Pre-Compile Variants.
Variants |
Configured Files |
|---|---|
PostBuild |
Pwm_PBcfg.c, Pwm_Cfg.c, Pwm_Cfg.h |
Pre-Compile |
Pwm_Cfg.c, Pwm_Cfg.h |
4.18.10.2. Parameter Description¶
4.18.10.2.1. Standard Configuration¶
Will be updated in future release
4.18.10.2.2. IP Specific Configuration¶
Will be updated in future release
4.18.10.3. Symbolic Names deviations¶
None
4.18.10.4. Configuration rules and constraints to enable plausibility checks¶
Will be updated in future release
4.18.11. 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_START_SEC_CONFIG_DATA |
x |
|||||
4.18.12. Memory footprint¶
Please refer Memory Footprint for more details.
4.18.13. Performance¶
Will be updated in future release
4.18.14. Example Usage¶
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”.
Module is tested in AM263p-CC board.
Oscilloscope is used to monitor PWM dutycycle and frequency Variation
The PWM module example is configured with channel id PWM_CHANNEL_PWM_CONTROLSS_G0_PWMCHANNEL9 , which is mapped to physical channel EPWM9
Connect EPWM output pin of 9th channel to Oscilloscope and check the output in CRO
Example code is tested for variation of Frequency and Duty cycle
The PWM module testing procedure as follows:
The PWM module is initialized with configured values : Dutycycle as 50% and Frequency as 1KHz
The PWM signal is changed to Dutycycle of 80 percent with Pwm_SetDutyCycle API
The PWM signal is changed to Dutycycle of 100 percent with Pwm_SetDutyCycle API
The PWM signal is output to Idle state with Pwm_SetOutputToIdle API
The PWM Frequency is changed to 10KHz and Dutycycle of 50 percent with Pwm_SetPeriodAndDuty API.
4.18.14.1. 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.18.15. FAQ’s¶
Will be updated in future release
4.18.16. Test Report(Link to test report)¶
Will be updated in future release
4.18.17. References¶
4.18.18. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments Post Office Box 655303 Dallas, Texas 75265
