4.13. MCU¶
4.13.1. About This Document¶
Document Title |
Userguide of MCAL MCU Driver |
Document Version |
Version 1.3 |
Company |
Texas Instruments |
Document Name |
MCU UserGuide |
4.13.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
04 Nov 2020 |
Initial Version. |
Approved |
Version 1.1 |
30 Sep 2022 |
MCAL 2.x specific changes. |
Approved |
Version 1.2 |
08 Aug 2023 |
Updated as per HTML format.. |
Approved |
Version 1.3 |
13 Sep 2023 |
Updated PLL configuration and frequency info, Parameter Description added. |
Approved |
4.13.3. Table of contents¶
4.13.4. Acronyms and Definitions¶
Acronyms and Definitions used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
MCU |
Micro Controller Unit |
OS |
Operating System |
API |
Application Programming Interface |
HW |
Hardware |
SW |
Software |
PLL |
Phase Locked Loop |
4.13.5. Functional Overview¶
4.13.5.1. Brief Overview¶
This document describes MCAL MCU Driver functionality, its application interfaces and configuration details as per AUTOSAR version 4.3.1 .
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile, Post-build |
Vendor ID |
MCU_VENDOR_ID (44) |
Module ID |
MCU_MODULE_ID (101) |
Supported Platform |
AM273x |
The MCU driver provides services for basic microcontroller initialization, reset and microcontroller specific functions required by other MCAL software modules.
The MCU driver provides MCU services for Clock and RAM initialization. In the MCU configuration set, the MCU specific settings for the Clock (i.e. PLL setting) and RAM (i.e. section base address and size) shall be configured.
4.13.5.1.1. MCU Driver Architecture¶
The MCU driver has architecture as shown in below figure from the AUTOSAR spec.
Figure 1: MCU in AUTOSAR architecture
Figure 2: Interface of MCU
4.13.5.1.2. Initialization¶
Mcu_Init() initializes the MCU driver and does module enable for the configured module ids.
To enable PLL, MCU_NO_PLL should be kept STD_OFF and generate,so that it will generate PLL configuration required in Mcu_Cfg.h and Mcu_PBcfg.c/Mcu_Cfg.c. Refer to figure below :
For AM273x, configuration settings are as shown below:
Core_Pll shall be set for 800MHz and is divided into two HSDIV_CLKOUT values as mentioned below:
200 MHz.
400 MHz.
Note
By default R5F Core frequency HSDIV_CLKOUT is set to 400MHz to achieve 400MHz and in case of 200MHz it is set to 200MHz.
Dsp_Pll shall be set to 900MHz or 1650MHz. Based on DSP Core Frequency required, user can configure HSDIV_CLKOUT values using the parameter McuDSPC66xFrequencySelect to one of the below frequency provided corresponding part supports that frequency. Please refer variants datasheet for the supported frequency details.
300MHz.
450MHz.
550MHz.
Refer to figure below :
Note
By default DSP Core frequency HSDIV_CLKOUT is set to achieve 450MHz.
Please note few part supports max upto 300MHz and if user configures McuDSPC66xFrequencySelect to 450MHz or 550MHz then DET error will be reported.
Similarly few part supports max upto 450MHz and if user configures McuDSPC66xFrequencySelect to 550MHz then DET error will be reported.
Per_Pll shall be set for 1728MHz and is divided into three HSDIV_CLKOUT values such as:
1920MHz.
960 MHz.
1728MHz.
Refer to figure below :
4.13.6. States¶
No state is maintained in the MCU driver
4.13.6.1. Features Supported and Not Supported¶
AUTOSAR features:
IP Supported Features |
AUTOSAR Supported Features |
Not Supported |
|---|---|---|
Initialization of Core clock, PLL Clock and peripheral clocks. |
Initialization of MCU clock, PLL, clock prescalers and MCU clock distribution. |
Support to activate the MCU power modes |
Initialization of RAM sections. |
MCU Reset/Read Reset Reason. |
|
Activation of a µC reset. |
DSP PLL and Peripheral PLL Supported. |
|
Provides a service to get the reset reason from hardware. |
Support to get the lock status of the PLL. |
4.13.6.2. Assumptions¶
None
4.13.6.3. Limitations¶
None
4.13.6.4. Recommended Configuration for R5F Clock Source¶
It is recommended to set clock source(MCU_CLKSRC_MODULE_ID_CR5) for R5F to MCU_CLKSRC_2.
4.13.6.5. Design overview(Link to the Architecture document and Design Document)¶
Will be avialable in future release.
4.13.6.6. File Structure¶
Description of static files is provided below:
Static source and header files |
Description |
|---|---|
Mcu.h |
Contains the API’s of the MCU driver to be used by upper layers. |
Mcu.c |
Implementation of the API’s for MCU driver. |
Mcu_Priv.h |
Internal function declarations. |
Mcu_Priv.c |
Contains Internal Functions Definitions. |
Description of generated files is provided below:
Plugin Files |
Descriptions |
|---|---|
Mcu_Cfg.h |
Contains the Precompile switches, Symbloic names of McuClockSettingConfig |
Mcu_PBcfg.c |
Contains all Post-Build Configured parameters |
Mcu_Cfg.c |
Contains all Pre-Compile Configured parameters |
Figure 4: MCU header file include structure
4.13.7. Deviations to requirements(Requirement Traceability)¶
4.13.7.1. Module Requirements¶
Will be updated in future release
4.13.7.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.13.8. Integration Details¶
4.13.8.1. Dependency on Other Software Modules¶
4.13.8.1.1. The MCU Driver dependent modules¶
4.13.8.1.2. Error Handling module¶
4.13.8.1.2.1. DET¶
The module MCU 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 MCU_DEV_ERROR_DETECT = STD_ON in the Mcu_Cfg.h
AUTOSAR requires that API functions shall check the validity of their respective parameters. These checks are for development error reporting and can be enabled or disabled.
The errors reported to DET module are described in the following table:
Error Code |
Error Macro |
Description |
|---|---|---|
[0x0A] |
MCU_E_PARAM_CONFIG |
API service called with incorrect configuration parameter. |
[0x0B] |
MCU_E_PARAM_CLOCK |
API service called with invalid clock id. |
[0x0C] |
MCU_E_PARAM_MODE |
API service called with invalid mode id. |
[0x0D] |
MCU_E_PARAM_RAMSECTION |
API service called with invalid ramsection parameter. |
[0x0E] |
MCU_E_PLL_NOT_LOCKED |
DET error reported when PLL is not locked. |
[0x0F] |
MCU_E_UNINIT |
API service used without module initialization. |
[0x10] |
MCU_E_PARAM_POINTER |
API service called with NULL_PTR passed to MCU driver APIs. |
4.13.8.1.2.2. DEM¶
The extended production errors reported to DEM module are described in the following table:
Error Code |
Error Macro |
Description |
|---|---|---|
Assigned by DEM |
MCU_E_CLOCK_FAILURE |
This error is raised when there is an MCU Clock Source Failure |
4.13.8.1.2.3. Callback Notification¶
There are no Callback Notifications.
4.13.8.2. Hardware - Software - ISR API name mapping¶
The MCU module doesn’t implement any Interrupt Service Routines.
4.13.8.3. Scheduling Strategy¶
4.13.8.3.1. SchM (Optional)¶
Beside the OS the BSW Scheduler provides functions that module MCU calls at begin and end of critical sections.
4.13.8.3.2. Critical Sections¶
There is only one kind of critical sections in MCU driver. Within these sections all read /modify / write accesses to internal MCU status variables must be protected. This is handled internally in the MCU driver by invoking SchM_Enter_Mcu_MCU_EXCLUSIVE_AREA_0()/SchM_Exit_Mcu_MCU_EXCLUSIVE_AREA_0().
4.13.9. API Description¶
4.13.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.13.9.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Autosar API’s Supported:
Service ID |
Autosar API’s Supported Service |
Autosar API’s not Supported Service |
|---|---|---|
0x00 |
Mcu_Init |
|
0x01 |
Mcu_InitRamSection |
|
0x02 |
Mcu_InitClock |
|
0x03 |
Mcu_DistributePllClock |
|
0x04 |
Mcu_GetPllStatus |
|
0x05 |
Mcu_GetResetReason |
|
0x06 |
Mcu_GetResetRawValue |
|
0x07 |
Mcu_PerformReset |
|
0x09 |
Mcu_GetVersionInfo |
|
0x0A |
Mcu_GetRamState |
|
0x08 |
Mcu_SetMode |
Refer Autosar SWS for API description mentioned in above table.
4.13.9.3. Description on Non Standard API’s¶
Mcu_DeInit API
This function is Non- Autosar based and is used to de-initialize MCU module.
Mcu_RegisterReadback API
This function is non-autosar based and is used to read the data in the registers of MCU.
This functionality is enabled, if parameter McuEnableRegisterReadbackApi is TRUE (The Parameter sets MCU_REGISTER_READBACK_API Macro as STD_ON ).
4.13.10. Configuration Description¶
4.13.10.1. Configuration Variants¶
The MCU can be configured as Post-Build or Pre-Compile variant, using EB tresos tool.
Variants |
Generated Files |
|---|---|
PostBuild |
Mcu_PBcfg.c , Mcu_Cfg.h |
Pre-Compile |
Mcu_Cfg.c , Mcu_Cfg.h |
4.13.10.2. Parameter Description¶
4.13.10.2.1. Standard Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit/Datatype |
|---|---|---|---|---|
McuDevErrorDetect |
Pre-processor switch for enabling the development error detection and reporting. |
TRUE |
TRUE/ FALSE |
Boolean |
McuGetRamStateApi |
Pre-processor switch to enable/disable the API Mcu_GetRamState |
TRUE |
TRUE/ FALSE |
Boolean |
McuInitClock |
If this parameter is set to FALSE, the clock initialization has to be disabled from the MCU driver. This concept applies when there are some write once clock registers and a bootloader is present. If this parameter is set to TRUE, the MCU driver is responsible of the clock initialization. |
TRUE |
TRUE/ FALSE |
Boolean |
McuNoPll |
This parameter shall be set True, if the H/W does not have a PLL or the PLL circuitry is enabled after the power on without S/W intervention. In this case MCU_DistributePllClock has to be disabled and MCU_GetPllStatus has to return MCU_PLL_STATUS_UNDEFINED. Otherwise this parameters has to be set False |
TRUE |
TRUE/ FALSE |
Boolean |
McuPerformResetApi |
Pre-processor switch to enable / disable the use of the function Mcu_PerformReset() |
FALSE |
TRUE/ FALSE |
Boolean |
McuVersionInfoApi |
Pre-processor switch to enable / disable the API to read out the modules version information |
TRUE |
TRUE/ FALSE |
Boolean |
McuClockSrcFailureNotification |
Enables/Disables clock failure notification. In case this feature is not supported by HW the setting should be disabled. |
DISABLED |
DISABLED/ ENABLED |
Enumeration |
McuNumberOfMcuModes |
This parameter shall represent the number of Modes available for the MCU |
Will be calculated |
1..255 |
Integer |
McuRamSectors |
Maximum value in ticks, the timer channel is able to count. With the next tick, the timer rolls over to zero |
Will be calculated |
1..4294967295 |
Integer |
McuResetSetting |
This parameter relates to the MCU specific reset configuration. This applies to the function Mcu_PerformReset, which performs a microcontroller reset using the hardware feature of the microcontroller. |
5 |
1..255 |
Integer |
McuClockSettingId |
The Id of this McuClockSettingConfig to be used as argument for the API call Mcu_InitClock. |
Value will be changed w.r.t modules |
0..255 |
Integer |
McuClockReferencePointFrequency |
This is the frequency for the specific instance of the McuClockReferencePoint container. It shall be given in Hz. |
1 |
0..Inifinity |
Float |
McuMode |
The parameter represents the MCU Mode settings. |
0 |
0..255 |
Integer |
McuRamDefaultValue |
This parameter shall represent the Data pre-setting to be initialized |
0 |
0..255 |
Integer |
McuRamSectionBaseAddress |
This parameter shall represent the MCU RAM section base address |
2281701376 |
0..4294967295 |
Integer |
McuRamSectionSize |
This parameter represents the MCU RAM Section size in bytes |
256 |
0..4294967295 |
Integer |
McuRamSectionWriteSize |
This parameter shall define the size in bytes of data which can be written into RAM at once |
8 |
0..4294967295 |
Integer |
McuResetReason |
The parameter represents the different type of reset that a Micro supports. This parameter is referenced by the parameter EcuMResetReason in the ECU State manager module. |
Will be calculated |
0..6 |
Boolean |
4.13.10.2.2. IP Specific Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit/Datatype |
|---|---|---|---|---|
McuInitRamApi |
Pre-processor switch to enable / disable the API to initialize RAM section. |
TRUE |
TRUE/ FALSE |
Boolean |
McuRegisterReadbackApi |
Pre-processor switch to enable / disable the API to read MCU registers. |
TRUE |
TRUE/ FALSE |
Boolean |
McuPBISTTestEnable |
Non used/implemented parameter.Pre-processor switch to enable / disable the PBIST test |
FALSE |
TRUE/ FALSE |
Boolean |
McuDefaultOSCounterId |
Default Os Counter Id if node reference to OsCounter ref McuOsCounterRef is not set |
0 |
0..16 |
Integer |
McuTimeoutDuration |
MCU timeout |
32000 |
0..4294967295 |
Integer |
McuPMICFreqAccuModeSel |
Non used/implemented parameter.PMIC_CLKOUT Frequency accumulation Mode selection, 0: Continuous mode, 1: Staircase mode . Bit 8 of DCDCCTL1. |
0 |
0-1 |
Integer |
McuPMICFreqSlopeVal |
Non used/implemented parameter.26 bit PMIC_CLKOUT Frequency slope value. BIT [26:0] of DCDCCTL0 |
0 |
0..0x7FFFFFF |
Integer |
McuPMICFreqThresMin |
Non used/implemented parameter.MIC_CLKOUT Minimum frequency threshold value. Bit [23:16] of DCDCCTL1 |
0 |
0..0xFF |
Integer |
McuPMICFreqThresMax |
Non used/implemented parameter.PMIC_CLKOUT Maximum frequency threshold value. Bit [31:24] of DCDCCTL1 |
0 |
0..0xFF |
Integer |
McuPMICClkEn |
Non used/implemented parameter.PMIC_CLKOUT Enable Multi-bit. BIT 1 of DCDCCTL1 |
0 |
0-1 |
Integer |
McuPMICDiterCtrl |
Non used/implemented parameter.PMIC_CLKOUT dithering control block reset . BIT 0 of DCDCCTL1 |
0 |
0-1 |
Integer |
McuResetMode |
Reset mode enum which can be used in Mcu_PerformReset |
MCU_PERFORM_RESET_MODE_WARM |
MCU_PERFORM_RESET_MODE_COLD MCU_PERFORM_RESET_MODE_WARM |
Enumeration |
McuDSPC66xFrequencySelect |
Select one frequency value to be programmed for DSP C66x core from 300MHz or 450MHz or 550MHz(Only supported in NZN package). |
MCU_DSP_C66x_FREQ_450MHz |
MCU_DSP_C66x_FREQ_300MHz MCU_DSP_C66x_FREQ_450MHz MCU_DSP_C66x_FREQ_550MHz |
Enumeration |
McuClockModuleId |
ModuleId for which clock setting to be applied |
MCU_CLKSRC_MODULE_ID_QSPI |
MCU_CLKSRC_MODULE_ID_MCANA MCU_CLKSRC_MODULE_ID_MCANB MCU_CLKSRC_MODULE_ID_RTIA MCU_CLKSRC_MODULE_ID_RTIB MCU_CLKSRC_MODULE_ID_RTIC MCU_CLKSRC_MODULE_ID_WDT MCU_CLKSRC_MODULE_ID_QSPI MCU_CLKSRC_MODULE_ID_SPIA MCU_CLKSRC_MODULE_ID_SPIB MCU_CLKSRC_MODULE_ID_I2C MCU_CLKSRC_MODULE_ID_SCIA MCU_CLKSRC_MODULE_ID_SCIB MCU_CLKSRC_MODULE_ID_CPSW MCU_CLKSRC_MODULE_ID_CPTS MCU_CLKSRC_MODULE_ID_HSI_CLK MCU_CLKSRC_MODULE_ID_CSIRX MCU_CLKSRC_MODULE_ID_MCU_CLKOUT MCU_CLKSRC_MODULE_ID_PMIC_CLKOUT MCU_CLKSRC_MODULE_ID_OBS_CLKOUT MCU_CLKSRC_MODULE_ID_TRC_CLKOUT MCU_CLKSRC_MODULE_ID_MII100_CLK MCU_CLKSRC_MODULE_ID_MII10_CLK MCU_CLKSRC_MODULE_ID_RGMI_CLK MCU_CLKSRC_MODULE_ID_GPADC_CLK MCU_CLKSRC_MODULE_ID_RCSSSPIA_CLK MCU_CLKSRC_MODULE_ID_RCSSSPIB_CLK |
Enumeration |
McuClockSourceId |
Clock source Id for selected module |
Will be calculated.Vary for modules |
MCU_CLKSRC_0 MCU_CLKSRC_1 MCU_CLKSRC_2 MCU_CLKSRC_3 MCU_CLKSRC_4 MCU_CLKSRC_5 MCU_CLKSRC_6 MCU_CLKSRC_7 |
Enumeration |
McuClockDivId |
Clock divider id for the module |
0 |
0..255 |
Integer |
McuClockInitializationConfigFlag |
Enable CPTS events |
TRUE |
TRUE/ FALSE |
Boolean |
McuDeviceVariant |
Select SOC variant. This parameter shall be used by driver to impose device specific constraints. |
AM273x |
AM273x |
Enumeration |
4.13.10.3. Symbolic Names deviations¶
None
4.13.10.4. Configuration rules and constraints to enable plausibility checks¶
Will be updated in future release
4.13.11. Memory Mapping¶
Memory Mapping Sections |
MCU_CODE |
MCU_DATA |
MCU_PBCFG |
|---|---|---|---|
MCU_START_SEC_VAR_INIT_UNSPECIFIED(.bss) |
x |
||
MCU_STOP_SEC_VAR_INIT_UNSPECIFIED |
x |
||
MCU_START_SEC_CODE(.text) |
x |
||
MCU_STOP_SEC_CODE |
x |
||
MCU_START_SEC_CONFIG_DATA(.data) |
x |
||
MCU_STOP_SEC_CONFIG_DATA |
x |
4.13.12. Memory footprint¶
Please refer Memory Footprint for more details.
4.13.13. Performance¶
Not Applicable
4.13.14. Example Usage¶
4.13.14.1. Steps to build and run example¶
MCU example application demonstrating the MCAL MCU driver features is in folder <MCAL_ROOT>/examples/Mcu.
This application can be built from the root folder by giving gmake –s mcu_app PLATFORM=am273 or gmake –s mcu_app PLATFORM=am2732s.
Once the build is completed we get a binary file,which is loaded in our controller and executed.
4.13.14.2. External set up Information¶
None
4.13.14.3. Configuration used to test this example¶
MCU module will initialize the clock for configured modules.
McuRamSectionBaseAddress is configured with ‘zero’ and reference array is also configured with default value of RAM section.
After configuration, Mcu_InitRamSection API is invoked inorder to set ‘McuRamSectionBaseAddress’ with default value.
Reference array and McuRamSectionBaseAddress is compared with each other to check whether RAM section is initialized properly or not.
It will also check for reset reason.
Mcu_GetResetReason API’s return value is compared with MCU_POWER_ON_RESET to check the wakeup cause.
4.13.14.4. Example Logs¶
Mcu_App: Variant - Post Build being used !!!
McuApp: Sample Application - STARTS !!!
Mcu Driver version info:9.0.1
Mcu Driver Module/Driver:101.44
RAM section is initialized properly
Wake up from Power ON
MCU Test Passed!!!
MCU Stack Usage: 808 bytes
4.13.15. FAQ’s¶
None
4.13.16. Test Report(Link to test report)¶
Will be updated in future release
4.13.17. References¶
AUTOSAR_SWS_MCUDriver.pdf
4.13.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
