4.17. WDG¶

4.17.1. About This Document¶


Document Title	Userguide of MCAL WDG Driver
Document Version	Version 1.5
Company	Texas Instruments
Document Name	WDG User Guide

4.17.2. Revision History¶

Version	Date	Revision History	Status
Versiont 1.0	26 April 2022	Initial Release	Approved
Versiont 1.1	05 Aug 2022	Updated AM263 to AM273x	Approved
Versiont 1.2	23 Dec 2022	WDG Example application testing procedure is added	Approved
Versiont 1.3	8 May 2023	WDG Example application testing procedure updated	Approved
Versiont 1.4	04 Aug 2023	Updated as per HTML format.	Approved
Versiont 1.5	30 Aug 2023	Document release version column removed	Approved

4.17.3. Table of contents¶

Acronyms and Definitions
Functional Overview
Deviations to requirements (Requirement Traceability)
Integration Details
API Description
Configuration Description
Memory mapping
Memory footprint
Performance
Example Usage
FAQ’s
Test Report (Link to test report)
References
TI Disclaimer

4.17.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.17.5. Functional Overview¶

4.17.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	Am273x

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.17.5.1.1. Wdg Driver Architecture¶

The Wdg driver has architecture as shown in below figure from the AUTOSAR spec

../_images/Wdg_image1.png — Fig. 4.6 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.17.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.17.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.17.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.17.5.3. Assumptions¶

None

4.17.5.4. Limitations¶

None

4.17.5.5. Design overview(Link to the Architecture document and Design Document)¶

Will be updated in future release

4.17.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
Wdg_Lcfg.c	Contains all channels Link-Time Configuration parameters

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

fig4 :WDG header file include structure

4.17.6. Deviations to requirements (Requirement Traceability)¶

4.17.6.1. Module Requirements¶

None

4.17.6.2. Deviation of requirements against AUTOSAR specification requirements¶

Will be updated in future release

4.17.7. Integration Details¶

4.17.7.1. Dependency on Other Software Modules¶

4.17.7.1.1. MCU¶

The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL.

4.17.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.17.7.1.3. SchM¶

There are no exclusive areas.

4.17.7.1.4. Critical Sections¶

There are no critical sections.

4.17.7.2. Error Handling module¶

4.17.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.17.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.17.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.17.7.2.4. Callback Function¶

The WDG driver does not provide any call back functions.

4.17.7.3. Hardware - Software - ISR API name mapping¶

None

4.17.7.4. Scheduling Strategy¶

None

4.17.8. API Description¶

4.17.8.1. Description of the API’s¶

Refer the AUTOSAR SWS for API documentation and Type definition.

4.17.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.17.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.17.9. Configuration Description¶

4.17.9.1. Configuration Variants¶

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

Variants	Generated Files
PostBuild	Wdg_PBcfg.c , Wdg_Cfg.h
Pre-Compile	Wdg_Cfg.c , Wdg_Cfg.h
Link-Time	Wdg_Lcfg.c , Wdg_Cfg.h

4.17.9.2. Parameter Description¶

4.17.9.2.1. Standard Configuration¶

Standard Parameters	Description	Default Value	Range	Unit

WDG_E_DISABLE_REJECTED	Reference to the DemEventParameter which shall be issued when the error “Initialization or mode switch failed because it would disable the watchdog” has occurred.	FALSE	0..1	Boolean
WDG_E_MODE_FAILED	Setting a watchdog mode failed (during initialization or mode switch)	FALSE	0..1	Boolean
WdgDevErrorDetect	Switches the development error detection and notification on or off.	FALSE	0..1	Boolean
WdgDisableAllowed	Compile switch to allow / forbid disabling the watchdog driver during runtime.	FALSE	0..1	Boolean
WdgIndex	Specifies the InstanceId of this module instance. If only one instance is present it shall have the Id 0.	0	0 .. 255	Integer
WdgInitialTimeout	The initial timeout (sec) for the trigger condition to be initialized during Init function.	0	0 .. 65.535]	Integer
WdgMaxTimeout	The maximum timeout (sec) to which the watchdog trigger condition can be initialized.	0	0 .. 65.535]	Integer
WdgVersionInfoApi	Compile switch to enable / disable the version information API	TRUE	0..1	Boolean
WdgDefaultMode	Default mode for watchdog driver initialization.	WDGIF_FAST_MODE	Wdg_ModeInfoType	Enumeration
WdgInstanceId	Watchdog HW instance id	0	0..3	Integer
WdgTriggerMode	Watchdog trigger mode (toggle/window/both)	WDG_WINDOW	WdgTriggerMode	Enumeration

4.17.9.2.2. IP Specific Configuration¶

Standard Parameters	Description	Default Value	Range	Unit/Datatype

WdgWindowSize	The Digital Windowed Watchdog window size. Selecting 100% enables standard watchdod	WINDOW_SIZE_100_PERCENT	Wdg_WindowSize	Enumeration
WdgRegisterReadbackApi	Compile switch to enable / disable the Register Readback API	FALSE	0..1	Boolean
WdgRtiFrequency	RTI Clock Frequency (MHz)	200	0..200	MHz
WdgPreloadValue	Watchdog preload value to be set in RTIDWDPRLD register. Expiration time is calculated using this function: texp = (WdgPreloadValue + 1) x 2^13 / RTICLK1	4095	0..4095	ms
WdgDeviceVariant	Select SOC AM273x variant	AM273x	AM273x
WdgReaction	Watchdog reaction for timer expiration or incorrect service.	WDG_GENERATE_RESET	Wdg_Reaction	Enumeration

4.17.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.17.11. Memory footprint¶

Please refer Memory Footprint for more details.

4.17.12. Performance¶

None

4.17.13. Example Usage¶

4.17.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=am273” command in command prompt.
Once the build is completed we get a binary file, which is loaded in our controller and executed.

4.17.13.2. Document external set up Information¶

None

4.17.13.3. Flow of the example application¶

WDG example application demonstrating the MCAL WDG driver features is in folder<MCAL_ROOT>/examples /Wdg.
This application can be built from the build folder by giving “gmake –s wdg_app”.
Default Example program is configured in reset mode.
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.
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.17.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    : 0
    SW Patch Version    : 1

    ----------------------------------------------------------------------------------
    Starting WDG test  !!!
    ----------------------------------------------------------------------------------
    Service Count 100
    Service Interval 25 milliseconds
    ------------------------------------------
    Trigger Value = 2500 milliseconds
    ------------------------------------------
    Maximum Service Interval 167 milliseconds
    Initializing channels
Post-Build variant is being used ..
Reset Reason 2
Test Passed!!
WDG Test Completed !!!
    WDG Stack Usage: 800 bytes
    ------------------------------------------

4.17.14. FAQ’s¶

Will be updated in future release

4.17.15. Test Report (Link to test report)¶

Will be updated in future release

4.17.16. References¶

Autosar SWS 4.3.1 will be updated in future release.

Technical Reference Manual

4.17.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