MCUSW
|
The figure below depicts the AUTOSAR layered architecture as 3 distinct layers, Application, Runtime Environment (RTE) and Basic Software (BSW). The BSW is further divided into 4 layers, Services, Electronic Control Unit Abstraction, MicroController Abstraction (MCAL) and Complex Drivers.
MCAL is the lowest abstraction layer of the Basic Software. It contains software modules that interact with the Microcontroller and its internal peripherals directly. Gpt driver is part of the Microcontroller Drivers (block, show above). Below shows the position of the Gpt driver in the AUTOSAR Architecture.
Gpt primarily used to generate different time bases that other modules of AUTOSAR could depend on. TDA4x class of devices includes multiple timers, below listed are some of the key features provided.
Supports 3 basic functional modes Timer mode, Capture mode & Compare mode. Refer section (References) for more details on timer operation.
Sl No | Specification | Comment / Link |
---|---|---|
1 | AUTOSAR 4.3.1 | AUTOSAR Specification for GPT Driver Intranet Link |
2 | TDA4x TRM | Technical Reference Manual, TDA4X Timer module is detailed |
3 | BSW General Requirements / Coding guidelines | Intranet Link |
4 | Software Product Specification (SPS) | Intranet Link Requirements are derived from 1 |
The Gpt driver shall implement as per requirements detailed in 4, 1 and 3. It’s recommended to refer 1 for clarification.
Below listed are some of the key features that are expected to be supported
Design ID | DES_GPT_001 |
Requirements Covered | MCAL-2123, MCAL-955, MCAL-920, MCAL-921, MCAL-922, MCAL-923, MCAL-925, MCAL-929, MCAL-930, MCAL-932, MCAL-933, MCAL-937, MCAL-938, MCAL-939, MCAL-942, MCAL-947, MCAL-980, MCAL-945, MCAL-1056 |
Design ID | DES_GPT_002 |
Non Requirements | MCAL-2124, MCAL-2080, MCAL-2079, MCAL-2110, MCAL-2109, MCAL-2108, MCAL-2107, MCAL-2106, MCAL-2105, MCAL-2104, MCAL-2103, MCAL-2102, MCAL-2101, MCAL-2007, MCAL-2001, MCAL-2001, MCAL-1991, MCAL-1983, MCAL-1982, MCAL-1981, MCAL-1980, MCAL-1979, MCAL-1948, MCAL-1947 |
Below listed are assumed to valid for this design/implementation, exceptions and other deviations are listed for each explicitly. Care should be taken to ensure these assumptions are addressed.
Note that assumption 1 & 2 are specified by AUTOSAR GPT specification and 3 & 4 are device specific assumption.
Some of the critical constraints of this design are listed below
Design ID | DES_GPT_003 |
Requirements Covered | MCAL-1951, MCAL-1960, MCAL-1950 |
As detailed in the TRM, the timer module generates an interrupt when the counter reaches its maximum value (i.e. 0xFFFFFFFF, for a 32 bit counter). The basic idea is use “Auto Reload” mode of the timer and initial count that could be set (TCRR register). Consider an example where timer is configured to expire after reaching a count of 0x0E000000
Following sequence of steps shall be performed, before the timer could be started
As detailed in section 7.1 of 1, a timer would be in one of the following states. Initialized, running, stopped, expired. A variable shall be maintained on per channel basis to track and maintain the state. The diagram below shows transitions of states and it’s associated service API’s.
Refer 1 specifically section 7.1 of the specification for more details
Design ID | DES_GPT_006 |
Requirements Covered | MCAL-1976, MCAL-1975, MCAL-1973 |
Design ID | DES_GPT_007 |
Requirements Covered | MCAL-2018, MCAL-2028 |
Design ID | DES_GPT_008 |
Requirements Covered | MCAL-1974, MCAL-1973 |
The elapsed time could be computed under following conditions, also Refer 1 specifically “Table 5: Summary: Return values and DET errors of Gpt_GetTimeElapsed”
Design ID | DES_GPT_009 |
Requirements Covered | MCAL-2018 |
The elapsed time could be computed under following conditions, also Refer 1 section 1.5 specifically “Table 6: Summary: Return values and DET errors of Gpt_GetTimeRemaining”
Design ID | DES_GPT_010 |
Requirements Covered | MCAL-2028 |
The directory structure is as depicted in figures below, the source files can be categorized under “Driver Implementation” and “Example Application”
Driver Implemented by
Example Application
Design ID | DES_GPT_011 |
Requirements Covered | MCAL-1972, MCAL-1971, MCAL-1970 |
The AUTOSAR GPT Driver Specification details mandatory parameters that shall be configurable via the configurator. Please refer section 10 of 1
Design ID | DES_GPT_012 |
Requirements Covered | MCAL-1945, MCAL-1969, MCAL-1968, MCAL-1967, MCAL-1966, MCAL-1965, MCAL-1964, MCAL-1963, MCAL-1962, MCAL-1961, MCAL-1960, MCAL-1959, MCAL-1958, MCAL-1957, MCAL-1956, MCAL-1955, MCAL-1954, MCAL-1953, MCAL-1952, MCAL-1951, MCAL-1950, MCAL-1949, MCAL-1946, MCAL-1945, MCAL-4175 |
Following lists this design’s specific configurable parameters
Parameter | Usage comment |
---|---|
GptDefaultOSCounterId | This shall allow integrators to specify the OS counter instance to be used in OS API GetCounterValue () The driver shall implement timed-wait for all waits (e.g. waiting for reset to complete). This timed wait shall use OS API GetCounterValue () |
GptDeviceVariant | This shall allow integrators to select the device variant for which integration is being performed. This parameter shall be used by driver to impose device specific constraints. The user guide shall detail the device specific constraints |
GptChannelPrescale | This parameter per channel and as part of container “GptChannelConfigSet” will allow user to scale the FCLK |
The configurator shall determine the maximum number of channels that are configured and generate a macro to define the same. This shall be used to perform range checks on channel configurations and channel ID provided at driver initialization time. Refer section (MACROS, Data Types & Structures)
The driver shall support both VARIANT-POST-BUILD & VARIANT-PRE-COMPILE
Design ID | DES_GPT_014 |
Requirements Covered | MCAL-1945 |
In addition to dependencies listed in section 5 of 1, GPT driver shall depend on these modules to realize the required functionality. GPT uses Timer hardware present in the device to realize the functionality, this peripheral requires 2 different clock to be operational, namely ICLK and FCLK.
Design ID | DES_GPT_015 |
Requirements Covered | MCAL-1950 |
Errors are classified in two categories, development error and runtime / production error.
Type of Error | Related Error code | Value (Hex) | Refer Req |
API service called without module initialization | GPT_E_UINIT | 0x0A | MCAL-2512 |
API service for initialization is called when already initialized | GPT_E_ALREADY_INITIALIZED | 0x0D | MCAL-2515 |
API error return code: Init function failed | GPT_E_INIT_FAILED | 0x0E | MCAL-2516 |
API parameter checking: invalid channel | GPT_E_PARAM_CHANNEL | 0x14 | MCAL-2517 |
API parameter checking: invalid value | GPT_E_PARAM_VALUE | 0x15 | MCAL-2518 |
API parameter checking: invalid pointer | GPT_E_PARAM_POINTER | 0x16 | MCAL-2519 |
API parameter checking: invalid mode | GPT_E_PARAM_MODE | 0x1F | MCAL-2520 |
Design ID | DES_GPT_037 |
Requirements Covered | MCAL-2512, MCAL-2515, MCAL-2516, MCAL-2517, MCAL-2518, MCAL-2519, MCAL-2520 |
The detection of development errors is configurable (ON / OFF) at pre-compile time. The switch GptDevErrorDetect will activate or deactivate the detection of all development errors.
All detected development errors are reported to Det_ReportError service of the Development Error Tracer (DET).
The following runtime/production errors shall be detectable by Gpt driver.
Type of Error | Related Error code | Value (Hex) |
API service is called when timer channel is still busy | GPT_E_BUSY | 0x0B |
All detected run time errors shall be reported to Det_ReportRuntimeError () service.
Design ID | DES_GPT_017 |
Requirements Covered | MCAL-2100, MCAL-2094, MCAL-2093, MCAL-2087, MCAL-2086, MCAL-2077, MCAL-2076, MCAL-2067, MCAL-2066, MCAL-2065, MCAL-2060, MCAL-2059, MCAL-2058, MCAL-2053, MCAL-2052, MCAL-2049, MCAL-2045, MCAL-2044, MCAL-2043, MCAL-2042, MCAL-2036, MCAL-2035, MCAL-2027, MCAL-2026, MCAL-2016, MCAL-2015, MCAL-2003, MCAL-1993, MCAL-1984, MCAL-2513 MCAL-4177, MCAL-4176 |
Design ID | DES_GPT_004 |
Requirements Covered | MCAL-2126 |
Design ID | DES_GPT_005 |
Requirements Covered | MCAL-2125 |
The detailed API and interface description is available as part of 1 & 4. This section describes the API supported by the MCAL driver and the requirements covered by each of the API.
The sections below lists some of key data structures that shall be implemented and used in driver implementation
Type | Identifier | Comments |
---|---|---|
uint32 | GPT_MAX_CHANNELS | Defines the maximum number of channels that are configured. Its required that configurations for all channel specified is valid. |
Used to specify the timer ticks, please refer section 8.3.2 of 1
Enumeration, refer section 8.3.4 of 1
Enumeration, refer section 8.3.5 of 1
Is a function pointer with prototype as void Gpt_Notification_<channel> ( void )” . The “_channel” postfix is provided by integrators via the configurator. “_channel” is used by applications to uniquely identify the GPT channel. Refer section 8.7.3.1 of 1
Refer section 10.6.2 of 1
Name | Type | Range | Comments |
---|---|---|---|
gptRev | uint32 | 0 to 0xFFFFFFFF | H/W version identifier, will not change for a given SoC |
gptTtgr | uint32 | 0 to 0xFFFFFFFF | Shall always read 0xFFFFFFFF |
gptTimerSynCtrl | uint32 | 0 to 0xFFFFFFFF | Interface control register, will read 0x00000000 |
Used to define channel specific parameters for, one channel and the values of these are expected to be populated by configurator.
Type | Variable Name | Comments |
---|---|---|
uint32 | channelId | Used to identify the channel (instance of timer (h/w) in implementation |
Gpt_ChannelMode | channelMode | Used to specify the mode of channel |
uint32 | tickValueMax | Maximum value in ticks, the timer channel is able to count. With the next tick, the timer rolls over to zero |
uint8 | enableWakeupFlag | Flag indicating, if wakeup functionality is to be supported on this channel |
Gpt_NotifyType | fnPtrNotifyFunction | Pointer to function, which shall be called to notify. Expected to be populated by the configurator |
uint8 | wakeupSourceRef | Value that shall be passed as function argument, when wakeup event occurs |
uint32 | prescale | The peripheral provide ability to scale function clock (FCLK), this parameter shall define scaling factor for this clock. The value/range would be device specific, check with device TRM for details. |
Design ID | DES_GPT_018 |
Requirements Covered | MCAL-2119, MCAL-2114, MCAL-1990, MCAL-1989, MCAL-1988, MCAL-1961, MCAL-1959, MCAL-1958, MCAL-1955, MCAL-1953, MCAL-1952 |
Used to define all channels specific parameters, shall be supplied to Gpt_Init () function. Values of these are expected to be populated by configurator.
Type | Variable Name | Comments |
---|---|---|
Gpt_ChannelConfigType * | channelCfgPtr | Is a constant pointer, pointing to all channel specific parameters. For “VARIANT-PRE-COMPILE” an instance of this structure shall instantiated in Gpt_Cfg.c by the configurator and driver implementation shall refer directly. Consider naming this variable as GptChannelConfigSet_PC For “VARIANT-POST-BUILD” an pointer of this type shall be provided to Gpt_Init () function. |
Design ID | DES_GPT_019 |
Requirements Covered | MCAL-1987 |
Used to define all channels identifiers, values of these are expected to be populated by configurator.
Type | Variable Name | Comments |
---|---|---|
Gpt_ChannelType | channelId[GPT_MAX_CHANNELS] | Shall contain channel identifiers for all channels. For “VARIANT-PRE-COMPILE” an instance of this structure shall instantiated in Gpt_Cfg.c by the configurator and driver implementation shall refer directly. Consider naming this variable as GptChannelIdConfig_PC. For “VARIANT-POST-BUILD”, this shall not be used, i.e. Gpt_Init (NULL_PTR) |
Design ID | DES_GPT_020 |
Requirements Covered | MCAL-1987, MCAL-1954 |
For the standard API's please refer 8.3 of 1. Sections below highlight other design considerations for the implementation.
Refer section 8.3.2 of 1
Design ID | DES_GPT_021 |
Requirements Covered | MCAL-2006, MCAL-2005, MCAL-2004, MCAL-2003, MCAL-2002, MCAL-2000, MCAL-1999, MCAL-1998, MCAL-1997, MCAL-1996, MCAL-1995, MCAL-1994 |
Refer section 8.3.3 of 1
Design ID | DES_GPT_022 |
Requirements Covered | MCAL-2017, MCAL-2016, MCAL-2015, MCAL-2014, MCAL-2013, MCAL-2012, MCAL-2011, MCAL-2010, MCAL-2009, MCAL-2008, MCAL-1964 |
Refer section 8.3.4 of 1
Design ID | DES_GPT_023 |
Requirements Covered | MCAL-2027, MCAL-2026, MCAL-2025, MCAL-2024, MCAL-2023, MCAL-2022, MCAL-2021, MCAL-2020, MCAL-2019, MCAL-2018, MCAL-1966 |
Refer section 8.3.5 of 1
Design ID | DES_GPT_024 |
Requirements Covered | MCAL-2028, MCAL-2029, MCAL-2030, MCAL-2031, MCAL-2032, MCAL-2033, MCAL-2034, MCAL-2035, MCAL-2036, MCAL-1967 |
Refer section In addition to details provided in 8.3.6 of 1 following design shall be implemented.
Design ID | DES_GPT_025 |
Requirements Covered | MCAL-2045, MCAL-2044, MCAL-2043, MCAL-2042, MCAL-2041, MCAL-2040, MCAL-2039, MCAL-2038, MCAL-2037 |
Refer section 8.3.7 of 1
Design ID | DES_GPT_026 |
Requirements Covered | MCAL-2053, MCAL-2052, MCAL-2051, MCAL-2050, MCAL-2049, MCAL-2048, MCAL-2047, MCAL-2046 |
Refer section 8.3.8 of 1
Design ID | DES_GPT_027 |
Requirements Covered | MCAL-2060, MCAL-2059, MCAL-2058, MCAL-2057, MCAL-2056, MCAL-2055, MCAL-2054, MCAL-1977 |
In addition to details provided in 8.3.9 of 1 following design shall be implemented.
Design ID | DES_GPT_028 |
Requirements Covered | MCAL-2067, MCAL-2066, MCAL-2065, MCAL-2064, MCAL-2063, MCAL-2062, MCAL-2061, MCAL-1965 |
Refer section 8.3.10 of 1
Design ID | DES_GPT_029 |
Requirements Covered | MCAL-2078, MCAL-2077, MCAL-2076, MCAL-2075, MCAL-2074, MCAL-2073, MCAL-2072, MCAL-2071, MCAL-2070, MCAL-2069, MCAL-2068 |
Refer section 8.3.11 of 1
Design ID | DES_GPT_030 |
Requirements Covered | MCAL-2087, MCAL-2086, MCAL-2085, MCAL-2084, MCAL-2083, MCAL-2082, MCAL-2081, MCAL-1969 |
Refer section 8.3.12 of 1
Design ID | DES_GPT_031 |
Requirements Covered | MCAL-2094, MCAL-2093, MCAL-2092, MCAL-2091, MCAL-2090, MCAL-2089, MCAL-2088, MCAL-1978, MCAL-1969 |
Refer section 8.3.13 of 1
Design ID | DES_GPT_032 |
Requirements Covered | MCAL-2100, MCAL-2099, MCAL-2098, MCAL-2097, MCAL-2096, MCAL-2095, MCAL-1969 |
Refer section 8.3.1 of 1
Design ID | DES_GPT_033 |
Requirements Covered | MCAL-1992, MCAL-1993, MCAL-1968 |
As noted from previous implementation, the timer configuration registers could potentially be corrupted by other entities (s/w or h/w). One of the recommended detection methods would be to periodically read-back the configuration and confirm configuration is consistent. The service API defined below shall be implemented to enable this detection.
Description | Comments | |
Service Name | Gpt_RegisterReadback | Can potentially be turned OFF |
Syntax | Std_ReturnType Gpt_RegisterReadback(Gpt_ChannelType GptChannel, Gpt_RegisterReadbackType *RegRbPtr) | Gpt_RegisterReadbackType defines the type, that holds critical values, refer below |
Service ID | 0x0F | |
Sync / Async | Sync | |
Reentrancy | Non Reentrant | |
Parameter in | GptChannel | Identifies a unique valid channel |
Parameters out | RegRbPtr | A pointer of type Gpt_RegisterReadbackType, which holds the read back values |
Return Value | Standard return type | E_OK or E_NOT_OK in case of invalid channel id |
The critical register listed is a recommendation and implementation shall determine appropriate registers.
This service could potentially be turned OFF in the configurator.
On elapse of configured count, the timer peripheral generates an interrupt. The implementation shall provide an ISR with prototype as “void Gpt_<ChannelNum>Isr (void)” The control flow shall be as depicted in flow chart figure below. Since, the function prototype dosen’t take any arguments to uniquely identify the timer channel that caused this interrupt, a separate ISR shall be implemented for each configured / enabled channel.
Design ID | DES_GPT_034 |
Requirements Covered | MCAL-2118, MCAL-2117, MCAL-2116, MCAL-2115, MCAL-2113, MCAL-2112 |
On elapse of configured count the timer peripheral generates an interrupt. The implementation shall provide an ISR with prototype as “void Gpt_<ChannelNum>Isr (void)” The control flow shall be as depicted in flow chart above, with following exceptions
Design ID | DES_GPT_035 |
Requirements Covered | MCAL-2111, MCAL-2122, MCAL-1986 |
This design expects that implementation will require to use following global variables.
Variable | Type | Description | Default Value |
---|---|---|---|
Gpt_DrvStatus | uint32 | Initialization status of the driver is maintained | FALSE |
Gpt_DrvObj | Gpt_DriverObjType | GPT driver object, local to the implementation and scope shall NOT be limited to Gpt.c | Un defined |
Gpt_WakeupSourceType | EcuM_WakeupSourceType | Used to store the WakeupSource Ref value for all configured channels. Local to the driver implementation and scope shall be limited to Gpt.c | Un defined |
Gpt_IsrFxn | Gpt_IsrRefType | Array of pointers to the call notification and wakeup Functions | Un defined |
Design ID | DES_GPT_036 |
Requirements Covered | SWS_BSW_00130 |
Sections below list some of the important design decisions and rational behind those decision.
The timer hardware doesn’t support continuous mode if configured timer count is less than max count of timer (0xFFFFFFFF in 32 bit timer). To implement GPT continuous mode we have to use timer interrupt to trigger timer start or tweak timer configuration during timer start to work in Continuous mode.
Implementation of GPT ‘Continuous’ mode, without timing constraints (or programming registers in ISR)
To avoid dependency on processor and interrupt service routine, recommended to use timer hardware auto-reload feature. Software will make sure to return correct values for time elapsed and time remaining functions.
Design ID | DES_GPT_037 |
Requirements Covered | MCAL-1976, MCAL-1975, MCAL-1973 |
The sections below identify some of the aspects of design that would require emphasis during testing of this design implementation
Revision | Date | Author | Description | Status |
---|---|---|---|---|
0.1 | 25 July 2018 | Sujith S | First version | Pending Review |
0.2 | 01 Oct 2018 | Sujith S | Format conversion and review completed | Approved |
0.3 | 28 Dec 2018 | Sujith S | Updated section "Development Errors" to include requirement mapping | Approved |
0.4 | 19 Jan 2020 | Sunil M S | Updates w.r.o porting AUTOSAR 4.3.1 Version | Approved |