MCUSW
Gpt User Guide

Introduction

This document details AUTOSAR BSW GPT module implementation

  • Supported AUTOSAR Release : 4.3.1
  • Supported Configuration Variants : Post-build, Pre-Compile
  • Vendor ID : GPT_VENDOR_ID (44)
  • Module ID : GPT_MODULE_ID (100)

The GPT module initializes, configures and controls the internal Timer(s) hardware to realize GPT driver as detailed in AUTOSAR BSW GPT Driver Specification. Following section highlights key aspects of this implementation, which would of interest to an integrator.

Gpt Driver Architecture/Design

Please refer the GPT design, which is included as part of release (Gpt Design Document)

Functional Description

Clock Source to timers

The Timer hardware is down-counter that count from non-zero value to zero. The clock supplied to these timers determines the rate of count-down. For each timer, clock source can be programmable and frequency of the clock varies on the SoC being used.

Programming of clock source for the timer, is beyond the scope of this document. The driver expects user of this module has programmed required clock source. The example application demonstrates configuring clock sources for the timer. Please note that “Gpt_ValueType Value” used in API Gpt_StartTimer () is a function of the clock source to the timer.

Back To Top

Computing the Gpt_ValueType Value for API Gpt_StartTimer ()

Value can be expressed as function of clock provided to timer with following equation. 

Value = <Clock Frequency in MHz> * <Required Time duration in seconds>

e.g.

  • second duration for a 12.5 MHz clock source would be 78643200 = (1024 * 1024 * 12.5) * 6
  • millisecond duration for a 12.5 MHz clock source would be 13107 = (1024 * 1024 * 12.5) * 0.001

Also refer (GptChannelPrescale)

Back To Top

Timer Instance, Gpt Channel ID mapping and ISR mapping

All timer instances are supported by this driver implementation (Timers in Main Domain & MCU Domain). The following table lists the mapping between instance of timer and GptChannelId of the configurator

GptChannelId Timer Instance Associated ISR (if notification is enabled)
0 MCU TIMER 0 Gpt_Ch1Isr
1 MCU TIMER 1 Gpt_Ch2Isr
. . .
. . .
9 MCU TIMER 9 Gpt_Ch10Isr
10 TIMER 0 Gpt_Ch11Isr
11 TIMER 1 Gpt_Ch12Isr
. . .
29 TIMER 29 Gpt_Ch30Isr

Back To Top

Configuration

The Gpt Driver implementation supports multiple configuration variants (refer section Introduction), the driver expects generated Gpt_Cfg.h to be present as (File Structure). Please refer (Build) to specify path to generated configuration. The associated timer configuration generated files Gpt_Cfg.c and Gpt_PBcfg.c to be present as show (File Structure)

NOTE: Always use configurator tool for MCAL configuration generation.

The following section details on the un-supported features and additional features added.

Variance / Deviation from the specification

PreDef Timers

This driver implementation doesn’t implement PreDef Timers. As Gpt would require to access/configure registers which are common (not just the Timer hardware module - clock source)

Back To Top

GptClockReference

To configure the clock source for Gpt (Timer hardware), one would have to access/configure common registers. It’s recommended that clock sources for the Gpt (Timer hardware) are done in SBL / Start up code.

GptChannelTickFrequency

The GptChannelTickFrequency, parameter is not used in this implementation

Implementation Specific Configurations

This driver implementation introduces below listed configurable options

Back To Top

GptDeviceVariant

Name GptDeviceVariant
Description Used to specific family of devices, the variant of the device being used will belong one or more family of devices. Please refer (Supported Device Families) to determine the family of device. Based on the family, the number of instances of Timer module supported could vary.
Container Name GptDriverConfiguration
Type Enumeration
Range TDA4x, etc… (new family of devices could be added in future)
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top

GptCategoryOfIsr

Name GptCategoryOfIsr
Description Specifies category of ISR.
Container Name GptDriverConfiguration
Type Enumeration
Range GPT_ISR_CAT1 & GPT_ISR_CAT2
Value Configuration Class VARIANT-PRE-COMPILE
Note This implementation has been validated with GPT_ISR_CAT1 only

Back To Top

GptDefaultOSCounterId

Name GptDefaultOSCounterId
Description

Specifies the OS counter to be used by the driver. All wait operations (wait for hardware timer module reset to complete) are time bound.

This implementation uses OS calls (GetCounterValue () & GetElapsedValue ()) to get current and elapsed time to establish time bound operation.

In cases where a constant value is returned / OS call is not operational, the time bound operation cannot be realized.

Container Name GptDriverConfiguration
Type Boolean
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top

GptRegisterReadbackApi

Name GptRegisterReadbackApi
Description Adds / Removes service API Gpt_RegisterReadback () 
Safety feature : Some of the critical registers (corruption of which
could potentially break functionality of the Gpt/Timer)

The expected usage: Periodically this service API is invoked and
checked for data-consistency. i.e. the values of members of structure
Gpt_RegisterReadbackType is not expected to change.

Also refer (@ref ug_gpt_functional_i_cfg_s_api_imp)
Container Name GptConfigurationOfOptApiServices
Type Boolean
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top

GptChannelPrescale

Name GptChannelPrescale
Description

Used configure divider for the input clock, as discussed in section (Computing the Gpt_ValueType Value for API Gpt_StartTimer ()) the clock source is used as time base.

This parameter could be used to divide this clock before it’s used to count.

Container Name GptChannelConfigSet
Type Enumeration
Range GPT_PRESCALER_NO_PRESCALE : Divider is disabled GPT_PRESCALER_CLK_DIV_BY_2 : Clock is divided by 2 : GPT_PRESCALER_CLK_DIV_BY_256: Clock is divided by 256
Value Configuration Class VARIANT-PRE-COMPILE & VARIANT-POST-BUILD

Back To Top

Non Standard Service APIs

Gpt_RegisterReadback

To protect HW from un-intended re-configuration (corrupted / fault hardware), some of the critical registers are read periodically and checked. By an entity outside the driver, the values of these registers are not expected to change. This is an optional service API, which can be turned OFF (refer section GptRegisterReadbackApi)

Service Name Gpt_RegisterReadback
Syntax void Gpt_RegisterReadback (Gpt_ChannelType GptChannel, Gpt_RegisterReadbackType * RegRbPtr)
Service ID[hex] 0x0F
Sync/Async Synchronous
Reentrancy Reentrant (but not for the same timer channel)
Parameters (in) GptChannel : Numeric identifier of the GPT channel
Parameters (inout) RegRbPtr : Pointer of type Gpt_RegisterReadbackType
Parameters (out) None
Return Value E_OK: Register read back has been done E_NOT_OK: Register read back failed (if channel is not initialized or RegRbPtr is NULL_PTR
Description Reads the important registers of the hardware unit and returns the value in the structure.

Back To Top

Interrupt Configuration

The Driver doesn’t register any interrupts handler (ISR), it’s expected that consumer of this driver registers the required interrupt handler.

For every Gpt channel with notification enabled, an ISR requires to be registered. The Interrupt number associated with instance of the Timer is detailed in TRM (also, please refer the demo application). Please refer GptApp_InterruptConfig () in Gpt demo application.

Some of the Timer interrupts are not routed/mapped to this core, these interrupts would require additional programming to route these to this core. Please refer GptApp_InterruptConfig () in Gpt demo application.

Refer section (Timer Instance, Gpt Channel ID mapping and ISR mapping), for association between channel ID and ISR

Back To Top

Power-up

The driver doesn't configured the functional clock and power for the timer modules. Its expected that SBL power-up the required modules. Please refer SBL documentation.

Back To Top

Build and Running the Example Application

Please follow steps detailed in section (Build) to build library or example

Back To Top

Example Application

  • Support both Post Build and Pre Compile Configuration Variants
  • For each Configured Timer, with default configuration provided in the release
    • A time duration of ~6 seconds is configured
    • Extracts and prints timer status during this period
    • Demonstrates use of TimeLapsed, TimeRemaining API's
    • Demonstrates Wakeup functionality

Back To Top

Steps to run example application

Please refer (Running Examples)

Back To Top

Memory Mapping

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file at (Examples Linker File (Select memory location to hold example binary)) defines separate section for these objects. When the driver is integrated, its expected that these sections are created and placed in appropriate memory locations. (Locations of these objects depend on the system design and performance needs)

Section GPT_CODE GPT_VAR GPT_VAR_NOINIT GPT_CONST GPT_CONFIG
GPT_START_SEC_VAR_INIT_UNSPECIFIED (.data) USED
GPT_DATA_INIT_32_SECTION USED
GPT_TEXT_SECTION USED
GPT_DATA_NO_INIT_UNSPECIFIED_SECTION USED
GPT_CONST_32_SECTION USED
GPT_ISR_TEXT_SECTION USED
GPT_CONFIG_SECTION USED

Back To Top

Cache

This driver implementation has been validated with cache enabled. For optimal performance it’s recommended to place (Memory Mapping) sections in cache enabled memory area.

Back To Top

Dependencies on SW Modules

DET

This implementation depends on the DET in order to report development errors and can be turned OFF. Refer section (Development Error Reporting) for detailed error codes.

Back To Top

Module EcuM

When wakeup is enabled, this implementation reports the wakeup interrupts to the ECU State Manager for further processing.

Back To Top

SchM

This implementation requires 1 level of exclusive access to guard critical sections. Invokes SchM_Enter_Gpt_GPT_EXCLUSIVE_AREA_0 (), SchM_Exit_Gpt_GPT_EXCLUSIVE_AREA_0 () to enter critical section and exit.

In the example implementation (File Structure SchM_Gpt.c) , all the interrupts on CPU are disabled. However, disabling of the enabled Timer/Gpt interrupt should suffice.

Back To Top

File Structure

gpt_design_timer_dir_detailed.png
Detailed Directory Structure
  1. Driver implemented by : Gpt.h, Gpt_Irq.h, Gpt.c, Gpt_Gptimer.c, Gpt_Irq.c and Gpt_Priv.h
  2. Example Configuration by : Gpt_Cfg.h, Gpt_Cfg.c and Gpt_PBcfg.c
  3. Example Application by : GptApp.c and GptApp.h

Back To Top

Error Handling

Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface (Gpt.h File Structure) lists the SID

Back To Top

Error codes

Type of Error Related Error code Value (Hex)
API service called without module initialization GPT_E_UINIT 0x0A
API service is called when timer channel is still busy GPT_E_BUSY 0x0B
API service for initialization is called when already initialized GPT_E_ALREADY_INITIALIZED 0x0D
API parameter checking: invalid channel GPT_E_PARAM_CHANNEL 0x14
API parameter checking: invalid value GPT_E_PARAM_VALUE 0x15
API parameter checking: invalid pointer GPT_E_PARAM_POINTER 0x16
API parameter checking: invalid mode GPT_E_PARAM_MODE 0x1F

Back To Top

Production Code Error Reporting

Production error are reported to DEM via the service DEM_ReportErrorStatus(). In addition to standard errors, this implementation reports "GPT_E_HARDWARE_ERROR" when GPT Timer register hardware reset fails.

Back To Top

API Description

The AUTOSAR BSW Gpt Driver specification details the API, as listed in section (PreDef Timers), following API’s are not implemented

  • Gpt_GetPredefTimerValue ( )
  • Other service API’s such as Gpt_Init (), Gpt_DeInit (), Gpt_SetMode ()etc… will not perform any actions associated with Pre Def Timer

Refer API Documentation for details

Back To Top

Example Application

The example application demonstrate use of Gpt module, the list below identifies key steps performed the example. The configuration file is present at (File Structure)

  • Initializes “Result Status Flag”
  • GptApp_Startup ()
    • Clear any pre-running timers
    • Builds interrupt list and registers ISR for enabled Gpt channels
    • Sets up clock sources for the timer modules
  • GptApp_mainTest ()
    • For each enabled channel
      • Enables Notification (if notification is enabled)
      • Starts Gpt
      • Prints channel status until notification is received (if notification is enabled)
      • Disable notification (if notification is enabled)
      • Wait for Timer expiry (if not in one shot mode)
      • Stop Gpt
      • Enable Wakeup (if enabled)
      • Re Start Gpt
      • Set Sleep mode
      • Waits for wakeup notification
      • Stops Gpt
  • Checks for error status, stack corruption and prints result

Back To Top

Example Log

        GPT_APP: Building Interrupt List !!!
        GPT_APP: Variant - Post Build being used !!!
        GPT_APP: Interrupt List Completed !!!
        GPT_APP: rmIrqReq = 0
        GPT_APP: rmIrqReq = 0
        GPT_APP: rmIrqReq = 0

        GPT_APP: Sample Application - STARTS !!!
        GPT_APP: Variant - Post Build being used !!!

        GPT_APP GPT MCAL Version Info
        GPT_APP---------------------
        GPT_APP Vendor ID           : 44
        GPT_APP Module ID           : 100
        GPT_APP SW Major Version    : 2
        GPT_APP SW Minor Version    : 0
        GPT_APP SW Patch Version    : 0


        GPT_APP------------------------------------------
        GPT_APP: GPT Channel 11 configuration register values  
        GPT_APP TIMER_TIDR         : 0x50003900
        GPT_APP TIMER_TTGR         : 0xffffffff
        GPT_APP TIMER_TSICR        : 0x0
        GPT_APP TIMER_TIOCP_CFG    : 0xa
        GPT_APP TIMER_TCLR         : 0x0
        ------------------------------------------
        GPT_APP: Running GPT Test for channel 11
        ------------------------------------------
        GPT_APP: Enabled notification for channel [11]
        GPT_APP: Started Timer Channel [11]
        GPT_APP: Elapsed Time Value = adb48
        GPT_APP: Wait for notification(approx. 6 seconds)
        GPT_APP: GPT Notification received for channel 11 !!!

        GPT_APP: Disable channel notification for this channel

        GPT_APP: Stopped for channel 11
        GPT_APP: Enable wakeup for this channel
        GPT_APP: Started timer channel [11]
        GPT_APP: check if this channel is wakeup source for any wakeup event
        EcuM : Wakeup event received for wakeupSource =0 !!!
        GPT_APP: Woken up for channel [11]
        GPT_APP: Stop timer
        GPT_APP: GPT example passed for channel =11 !!!

        GPT_APP------------------------------------------
        GPT_APP: GPT Channel 6 configuration register values  
        GPT_APP TIMER_TIDR         : 0x50003900
        GPT_APP TIMER_TTGR         : 0xffffffff
        GPT_APP TIMER_TSICR        : 0x0
        GPT_APP TIMER_TIOCP_CFG    : 0xa
        GPT_APP TIMER_TCLR         : 0x0
        ------------------------------------------
        GPT_APP: Running GPT Test for channel 6
        ------------------------------------------
        GPT_APP: Enabled notification for channel [6]
        GPT_APP: Started Timer Channel [6]
        GPT_APP: Elapsed Time Value = adaee
        GPT_APP: Wait for notification(approx. 6 seconds)
        GPT_APP: GPT Notification received for channel 6 !!!

        GPT_APP: Disable channel notification for this channel
        GPT_APP: Wait till timer overflows, no notification should be received
        GPT_APP: Time Elapsed Value = 0x36ddc1
        GPT_APP: Time Remaining Value = 0x8adec39
        GPT_APP: Waiting for timer to overflow
        GPT_APP: Overflow happened no notification received

        GPT_APP: Stopped for channel 6
        GPT_APP: Enable wakeup for this channel
        GPT_APP: Started timer channel [6]
        GPT_APP: check if this channel is wakeup source for any wakeup event
        EcuM : Wakeup event received for wakeupSource =0 !!!
        GPT_APP: Woken up for channel [6]
        GPT_APP: Stop timer
        GPT_APP: GPT example passed for channel =6 !!!

        GPT_APP------------------------------------------
        GPT_APP: GPT Channel 9 configuration register values  
        GPT_APP TIMER_TIDR         : 0x50003900
        GPT_APP TIMER_TTGR         : 0xffffffff
        GPT_APP TIMER_TSICR        : 0x0
        GPT_APP TIMER_TIOCP_CFG    : 0xa
        GPT_APP TIMER_TCLR         : 0x0
        ------------------------------------------
        GPT_APP: Running GPT Test for channel 9
        ------------------------------------------
        GPT_APP: Enabled notification for channel [9]
        GPT_APP: Started Timer Channel [9]
        GPT_APP: Elapsed Time Value = adaee
        GPT_APP: Wait for notification(approx. 6 seconds)
        GPT_APP: GPT Notification received for channel 9 !!!

        GPT_APP: Disable channel notification for this channel
        GPT_APP: Wait till timer overflows, no notification should be received
        GPT_APP: Time Elapsed Value = 0x36dda0
        GPT_APP: Time Remaining Value = 0x8adec72
        GPT_APP: Waiting for timer to overflow
        GPT_APP: Overflow happened no notification received

        GPT_APP: Stopped for channel 9
        GPT_APP: Enable wakeup for this channel
        GPT_APP: Started timer channel [9]
        GPT_APP: check if this channel is wakeup source for any wakeup event
        EcuM : Wakeup event received for wakeupSource =0 !!!
        GPT_APP: Woken up for channel [9]
        GPT_APP: Stop timer
        GPT_APP: GPT example passed for channel =9 !!!

        GPT_APP------------------------------------------
        GPT_APP: GPT Channel 15 configuration register values  
        GPT_APP TIMER_TIDR         : 0x50003900
        GPT_APP TIMER_TTGR         : 0xffffffff
        GPT_APP TIMER_TSICR        : 0x0
        GPT_APP TIMER_TIOCP_CFG    : 0xa
        GPT_APP TIMER_TCLR         : 0x0
        ------------------------------------------
        GPT_APP: Running GPT Test for channel 15
        ------------------------------------------
        GPT_APP: Enabled notification for channel [15]
        GPT_APP: Started Timer Channel [15]
        GPT_APP: Elapsed Time Value = b2612
        GPT_APP: Wait for notification(approx. 6 seconds)
        GPT_APP: GPT Notification received for channel 15 !!!

        GPT_APP: Disable channel notification for this channel
        GPT_APP: Wait till timer overflows, no notification should be received
        GPT_APP: Time Elapsed Value = 0x37284c
        GPT_APP: Time Remaining Value = 0x8ada1c9
        GPT_APP: Waiting for timer to overflow
        GPT_APP: Overflow happened no notification received

        GPT_APP: Stopped for channel 15
        GPT_APP: Enable wakeup for this channel
        GPT_APP: Started timer channel [15]
        GPT_APP: check if this channel is wakeup source for any wakeup event
        EcuM : Wakeup event received for wakeupSource =0 !!!
        GPT_APP: Woken up for channel [15]
        GPT_APP: Stop timer
        GPT_APP: GPT example passed for channel =15 !!!

        GPT_APP------------------------------------------
        GPT_APP: GPT Channel 17 configuration register values  
        GPT_APP TIMER_TIDR         : 0x50003900
        GPT_APP TIMER_TTGR         : 0xffffffff
        GPT_APP TIMER_TSICR        : 0x0
        GPT_APP TIMER_TIOCP_CFG    : 0xa
        GPT_APP TIMER_TCLR         : 0x0
        ------------------------------------------
        GPT_APP: Running GPT Test for channel 17
        ------------------------------------------
        GPT_APP: Enabled notification for channel [17]
        GPT_APP: Started Timer Channel [17]
        GPT_APP: Elapsed Time Value = b2612
        GPT_APP: Wait for notification(approx. 6 seconds)
        GPT_APP: GPT Notification received for channel 18 !!!

        GPT_APP: Disable channel notification for this channel
        GPT_APP: Wait till timer overflows, no notification should be received
        GPT_APP: Time Elapsed Value = 0x372831
        GPT_APP: Time Remaining Value = 0x8ada1e4
        GPT_APP: Waiting for timer to overflow
        GPT_APP: Overflow happened no notification received

        GPT_APP: Stopped for channel 17
        GPT_APP: Enable wakeup for this channel
        GPT_APP: Started timer channel [17]
        GPT_APP: check if this channel is wakeup source for any wakeup event
        EcuM : Wakeup event received for wakeupSource =0 !!!
        GPT_APP: Woken up for channel [17]
        GPT_APP: Stop timer
        GPT_APP: GPT example passed for channel =17 !!!
        GPT_APP: GPT example Completed !!!
        GPT_APP: GPT Stack Usage 2924 bytes
        GPT_APP: GPT Test Passed!!!

Back To Top

References

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 26 Sep 2018 Sujith S First version Pending Review
0.2 11 Oct 2018 Sujith S Addressed review comments Approved
0.3 16 Oct 2018 Sujith S Added Logs from J721E testing Approved
0.4 19 Jan 2020 Sunil M S Updates w.r.o porting AUTOSAR 4.3.1 Version Approved
0.5 02 Nov 2020 Nikki S J7200 updated Approved
0.6 17 Mar 2022 Rohit T Removed J721E & J7200 specific contents Approved
0.7 08 Dec 2022 Subham Swain Adding J721s2 specific content Approved
0.8 10 April 2023 Rohit T Fixed doxygen warnings Approved