4.20. WDG¶
4.20.1. About This Document¶
Document Title |
User Guide of MCAL WDG Driver |
Document Version |
Version 1.0 |
Company |
Texas Instruments |
Document Name |
WDG User Guide |
4.20.2. Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Versiont 1.0 |
13 Oct 2023 |
Initial Release |
Approved |
4.20.3. Table of contents¶
4.20.4. Acronyms and Definitions¶
Acronyms and Definitions Used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
WDG |
Watchdog Timer |
MCU |
Micro Controller Unit |
OS |
Operating System |
4.20.5. Functional Overview¶
4.20.5.1. Brief Overview¶
This document describes the functionality, API and configuration of the AUTOSAR BSW module Wdg.
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile, Post-build |
Vendor ID |
WDG_VENDOR_ID (44) |
Module ID |
WDG_MODULE_ID (102) |
Supported Platform |
AM263px |
The WDG driver depends on some other modules, like DET for error handling, OSEK/AUTOSAR OS for interrupt handling and the Mcu module for system clock settings.
4.20.5.1.1. Wdg Driver Architecture¶
The Wdg driver has architecture as shown in below figure from the AUTOSAR spec
Fig. 4.8 Figure : Wdg in AUTOSAR architecture¶
The WDG driver provides services for handling the watch dog timer on the microcontroller.
The WDG driver performs two main tasks, which are as follows:
Initialization of WDG
Reset WDG expiration time (trigger)
4.20.5.1.2. Initialization¶
The initialization covers the following steps
Set selected watchdog timer expiration time
Set selected trigger timeout
Set selected window size (Digital Windowed Watchdog)
Set selected mode (Fast or slow can be selected but cannot be switched runtime)
4.20.5.1.3. States¶
WDG_IDLE: This is indicating the module is initialized and not busy.
WDG_BUSY: This is indicating the module is busy.
4.20.5.2. Features Supported and Not Supported¶
Features Supported |
Features Not Supported |
|---|---|
Setting default mode and timeout during initialization. |
Off mode not supported |
Setting window size (Digital Windowed Watchdog). |
Due to hardware limitations, Mode and Timeout can’t be modified if watchdog is running. |
Enable watchdog timer |
|
Service watchdog timer. |
4.20.5.3. Assumptions¶
None
4.20.5.4. Limitations¶
None
4.20.5.5. Design overview(Link to the Architecture document and Design Document)¶
Will be updated in future release
4.20.5.6. File Structure¶
Static source C File Structure is defined below in the table.
File Name |
Description |
|---|---|
Wdg.c |
Main part of the module functionality, implements the AUTOSAR APIs for WDG driver |
Wdg_Priv.c and Wdg_Priv.h |
platform specific internal file |
Wdg.h |
WDG module header file. Needs to be included by higher layers |
Wdg_Irq.c and Wdg_Irq.h |
WDG Interrupt service routine |
Plugin structure is defined below in the table.
Plugin Structure |
Descriptions |
|---|---|
Wdg_Cfg.h |
Contains the base addresses, Precompile switches, Macros for channels, counters etc. |
Wdg_PBcfg.c |
Contains all channels Post-Build Configuration parameters |
Wdg_Cfg.c |
Contains all channels Pre-Compile Configuration parameters |
The below diagram shows the files structure for the Wdg driver.
fig4 :WDG header file include structure
4.20.6. Deviations to requirements (Requirement Traceability)¶
4.20.6.1. Module Requirements¶
None
4.20.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.20.7. Integration Details¶
4.20.7.1. Dependency on Other Software Modules¶
4.20.7.1.1. MCU¶
The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL.
4.20.7.1.2. OS¶
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 WDG module may use AUTOSAR OS to suspend and restore global interrupts.
4.20.7.1.3. SchM¶
There are no exclusive areas.
4.20.7.1.4. Critical Sections¶
There are no critical sections.
4.20.7.2. Error Handling module¶
4.20.7.2.1. DET¶
By default, production code related errors are reported to the DET using the service Det_ReportError(). If development error reporting is enabled (i.e. pre-compile parameter WDG_DEV_ERROR_DETECT== STD_ON). The reported service IDs identify the services which are described in 3.4. The following table presents the service IDs and the related services:
The errors reported to DET and DEM are described in the following table
Type of Error |
Relevance |
Related Error Code |
Value |
|---|---|---|---|
API service used in wrong context (e.g. module not initialized). |
Development |
WDG_E_DRIVER_STATE |
0x10 |
API service called with wrong / inconsistent parameter(s) |
Development |
WDG_E_PARAM_MODE |
0x11 |
API service called with wrong / inconsistent parameter(s) |
Development |
WDG_E_PARAM_CONFIG |
0x12 |
The passed timeout value is higher than the max timeout value. |
Development |
WDG_E_PARAM_TIMEOUT |
0x13 |
API is called with wrong pointer value (e.g. NULL pointer) |
Development |
WDG_E_PARAM_POINTER |
0x14 |
4.20.7.2.2. Parameter Checking¶
AUTOSAR requires that API functions check the validity of their parameters. The checks are described in spec and are done as internal parameter checks of the API functions. These checks are for development error reporting and can be en/dis-abled separately. Refer to the configuration chapter where the en/dis-abling of the checks is described. En/dis-abling of single checks is an addition to the AUTOSAR standard which requires to en/dis-able the complete parameter checking via the parameter WDG_DEV_ERROR_DETECT. The following table shows which parameter checks are performed on which services:
Services |
Wdg_Init |
Wdg_SetMode |
Wdg_SetTriggerCondition |
Wdg_GetVersionInfo |
Wdg_Trigger |
|---|---|---|---|---|---|
WDG_E_DRIVER_STATE |
X |
X |
|||
WDG_E_PARAM_MODE |
X |
||||
WDG_E_PARAM_CONFIG |
|||||
WDG_E_PARAM_TIMEOUT |
X |
||||
WDG_E_PARAM_POINTER |
X |
X |
|||
WDG_E_MODE_FAILED |
X |
||||
WDG_E_DISABLE_REJECTED |
X |
4.20.7.2.3. Production Code Error Reporting¶
By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus(). The errors reported to DEM are described in the following table:
ErrorCode |
Description |
|
|---|---|---|
Assigned by DEM |
WDG_E_MODE_FAILED |
This error is raised when setting the watchdog mode fails. |
Assigned by DEM |
WDG_E_DISABLE_REJECTED |
Initialization or watchdog mode switch failed because it would disable the watchdog though this is not allowed in this configuration. |
4.20.7.2.4. Callback Function¶
The WDG driver does not provide any call back functions.
4.20.7.3. Hardware - Software - ISR API name mapping¶
None
4.20.7.4. Scheduling Strategy¶
None
4.20.8. API Description¶
4.20.8.1. Description of the API’s¶
Refer the AUTOSAR SWS for API documentation and Type definition.
4.20.8.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Service ID |
Service |
|---|---|
0x00 |
Wdg_Init |
0x01 |
Wdg_SetMode |
0x03 |
Wdg_SetTriggerCondition |
0x04 |
Wdg_GetVersionInfo |
0x05 |
Wdg_Trigger |
4.20.8.3. Description on Non Standard API’s¶
Wdg_RegisterReadback API–This function is non-autosar based and is used to read the data in the registers of Wdg if we keep Wdg_REGISTER_READBACK_API Macro as ON.
4.20.9. Configuration Description¶
4.20.9.1. Configuration Variants¶
The Wdg is configured through GUI in Post-Build and Pre-Compile Variants.
Variants |
Generated Files |
|---|---|
PostBuild |
Wdg_PBcfg.c , Wdg_Cfg.h |
Pre-Compile |
Wdg_Cfg.c , Wdg_Cfg.h |
4.20.9.2. IP Specific Configuration¶
WDG_INITIAL_TIMEOUT: This is the initial wdg timeout period.
WDG_MAX_TIMEOUT: Maximum timeout for the wdg is 65 * 1000.
WDG_MAX_PRELOAD_VALUE: To define wdg maximum preload value.
WDG_RTI_FREQUENCY: This is defined to get the desired frequency.
WdgDeviceVariant: To Select SOC AM263px variant
4.20.10. Memory mapping¶
Memory Mapping Sections |
WDG_CODE |
WDG_CODE_ISR |
WDG_VAR_NO_INIT |
WDG_VAR_ZERO_INIT |
WDG_PBCFG |
WDG_PBCFG_ROOT |
|---|---|---|---|---|---|---|
WDG_START_SEC_VAR_INIT_UNSPECIFIED(.bss) WDG _STOP_SEC_VAR_INIT_UNSPECIFIED |
x |
|||||
WDG _START_SEC_CODE_APPL(.text) WDG _STOP_SEC_CODE_APPL |
x |
|||||
WDG _START_SEC_VAR_UNSPECIFIED(.data) WDG _STOP_SEC_VAR_UNSPECIFIED |
x |
|||||
WDG _START_SEC_CODE(.text) WDG _STOP_SEC_CODE |
x |
|||||
WDG_START_SEC_PBCFG(.data) WDG_STOP_SEC_PBCFG |
x |
|||||
WDG_START_SEC_PBCFG_ROOT(.const) WDG_STOP_SEC_PBCFG_ROOT |
x |
4.20.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.20.12. Performance¶
None
4.20.13. Example Usage¶
4.20.13.1. Steps to build and run example¶
WDG example application demonstrates the MCAL WDG driver features, which is referred from folder <MCAL_ROOT>/examples/WDG.
This application can be built from the build folder by giving “gmake –s wdg_app PLATFORM=am263px” command in command prompt.
Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.20.13.2. Document external set up Information¶
None
4.20.13.3. Flow of the example application¶
Default Example program is configured in Non-Maskable Interrupt method (WDT will trigger interrupt when counter becomes zero).
WDT window reaction can be changed to “reset” through configuration (EB Tresos).
In example, service interval is 25ms and service count is 100. So, every 25ms core will service the WDT for 100 times (25*100 = 2500 ms).
WDG is integrated with WDG in order to service WDG.
WDG_SetTriggerCondition API is servicing WDG by passing non zero timeout value
Then after it will raise an interrupt and interrupt will run (WDT_Isr() function). In ISR function core reset will occurs and start running program again automatically.
It checks for reset reason, if reset happened due to WDT then “Test Passed”
In Reset window reaction mode, after counter reaches to zero POR(Power ON Reset) happens.
4.20.13.4. Example Logs¶
WDG_APP: Sample Application - STARTS !!!
WDG MCAL Version Info
---------------------
Vendor ID : 44
Module ID : 102
SW Major Version : 9
SW Minor Version : 1
SW Patch Version : 0
----------------------------------------------------------------------------------
Starting WDG test !!!
----------------------------------------------------------------------------------
Service Count 100
Service Interval 25 milliseconds
------------------------------------------
Trigger Value = 2500 milliseconds
------------------------------------------
Maximum Service Interval 74 milliseconds
Initializing channels
Post-Build variant is being used .
Reset Reason 2
Test Passed!!
WDG Stack Usage: 800 bytes
------------------------------------------
4.20.14. FAQ’s¶
Will be updated in future release
4.20.15. Test Report (Link to test report)¶
Will be updated in future release
4.20.16. References¶
4.20.17. 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
