3. MCAL Configurator User Guide

3.1. About This Document

Document Title

Configurator Guide of MCAL Driver

Document Version

Version 1.0

Company

Texas Instruments

Document Name

MCAL Configurator User Guide

3.2. Document Revision History

Version

Date

Revision History

Status

1.0

05 Aug 2023

Initial draft

Approved

3.3. Table of contents

  1. Acronyms and Definitions

  2. Introduction

  3. MCAL Overview

  4. Installation

  5. Working with Command Line

  6. Tool versions

  7. Hardware Setup

  8. Un-installing

  9. References

3.4. Acronyms and Definitions

Acronyms and Definitions used are presented in below table.

Acronym
Meaning

AUTOSAR

Automotive Open Standards Architecture

CCS

Texas Instruments Code Composer Studio

BSW

Basic Software in AUTOSAR stack

EB

Elektrobit

ECU

Electronic Control Unit

ECU PD

ECU Parameter Definition

ECU CD

ECU Configuration Description

EVM

Evaluation Module, hardware platform containing the Texas Instruments M4

TI

Texas Instruments

MCAL

Microcontroller Abstraction Layer

BSW

Basic Software

DET

Default Error Tracer

DEM

Diagnostic Event Manager

MCU

Micro Controller Unit

OS

Operating System

API

Application Programming Interface

HW

Hardware

SW

Software

ISR

Interrupt Service Routine

INT

Interrupt

CDD

Complex Device Driver

ADC

Analogue Digital Converter

CAN

Control Area Network

DIO

Digital Input Output

DMA

Direct Memory Access

ETH

Ethernet

ETHTRCV

Ethernet Transceiver

FLS

Flash

GPT

General Purpose Timer

ICU

Input Capture Unit

PWM

Pulse Width Modulation

IPC

Inter Process Communication

I2C

Inter Integrated Circuit

UART

Universal Asynchronous Reciever Transmitter

SPI

Serial Pheripheral Interface

FSI

Fast Serail Interface

Tx

Transmitter

Rx

Reciever

3.5. Introduction

The purpose of this User Guide is to provide detailed information regarding the usage of TI Sitara MCU MCAL configurator/generator package. The Microcontroller abstraction layer (MCAL) is the lowest layer of the AUTOSAR Basic Software architecture. The figure below shows MCAL layer in the AUTOSAR BSW software stack.

_images/Block_Autosar.png

Figure 1: AUTOSAR architecture.

Each MCAL driver has a driver implementation portion and a configurator/generator portion. The configurator/generator portion is described in this user guide.

MCAL generator/configurator steps in the standard AUTOSAR ECU configuration flow is circled below.

_images/Ecu_configurator.png

Figure 2: Ecu_configurator.

The TI MCAL configurator/generator package uses Elektrobit Tresos for the MCAL configuration and code generation.

This TI MCAL module’s ECU parameter definition is captured in Elektrobit xdm format.

This TI MCAL modules are delivered in the form of EB tresos plugins.

This configuration of the MCAL modules can be done using the Elektrobit Tresos Configuration Editor.

Once the configuration is complete, code generation for precompile, link time config and postbuild configuration is done using the EB tresos code generation feature.

This TI MCAL delivery is on AM263 platform.

3.5.1. Supported Devices/Platforms

This release supports AM263 series of SoC.

3.5.2. Other Documentation

Document
Description
2.1_Studio_documentation_users_guide.pdf

EB tresos user guide. This document should be used to understand how to use EB tresos for configuration and code generation.
EB_tresos_installation_guide.pdf

Installation Guide for EB tresos.
LicensingUsersGuide.pdf

Guide related to activating EB license and use of EB Client License Administrator tool.
fnp_LicAdmin.pdf

Document from Flexnet explaining usage of Flexnet licensing tools

3.6. MCAL Overview

A set of MCAL are included in the package each controlling a specific peripheral. MCAL drivers included are

ADC

Driver for ADC peripheral.

DMA

Driver to transfer data between memory and device.

MCU

Driver to control enabling of modules, PLL setting and basic microcontroller initialization.

PORT

Driver for control of pinmux.

SPI

Spi handler and driver for Serial Peripheral Interfaces: McSPI.

CAN

Driver for the on-chip MCAN controller peripheral.

GPT

Driver that controls the internal timer of the controller.

WDG

Driver for controlling the watchdog when controller goes into continuous loop.

DIO

Driver to read and write the data from the Channels / Port.

FLS

Driver provides services for reading, writing, erasing flash memory for external flash device.

CDD I2C

Driver provides services to transmit and Receive data with the external devices.

ETH

Driver provides services to transmit and Receive data with the external devices.

ETHTRCV

Driver for Physical Layer Transceiver.

WDG

Driver for control of Watchdog Timer.

CDD IPC

Driver for the inter process communication between the cores.

PWM

PWM driver for generating the waveforms with required duty cycle and period.

ICU

Driver for input capture unit.

UART

Driver Provides services for reading and writing to/from UART channels and Port/Serial device.

The MCAL drivers implement the Software specification mentioned in AUTOSAR 4.3.1 release. Each module is an EB tresos plug-in and uses EB tresos for configuration and code generation.

3.6.1. Directory Structure

_images/Directory_structure_am273.png

Figure 3: Directory_structure.

Adc_TI_MCAL2x

This directory contains the configurator/generator plugin for ADC MCAL.

Can_TI_MCAL2x

This directory contains the configurator/generator plugin for the CAN MCAL.

Cdd_Dma_TI_MCAL2x

This directory contains the configurator/generator plugin for the DMA MCAL.

Cdd_I2c_TI_MCAL2x

This directory contains the configurator/generator plugin for the I2C MCAL.

Cdd_Ipc_TI_MCAL2x

This directory contains the configurator/generator plugin for the IPC MCAL.

Cdd_Uart_TI_MCAL2x

This directory contains the configurator/generator plugin for the UART MCAL.

Dem_TI_MCAL2x

This directory contains the Dem stub for DEM module.

Dio_TI_MCAL2x

This directory contains the configurator/generator plugin for DIO MCAL.

EcuM_TI_MCAL2x

This directory contains the EcuM stub for Ecu Manager module.

Eth_TI_MCAL2x

This directory contains the configurator/generator plugin for ETH MCAL.

Ethtrcv_TI_MCAL2X

This directory contains the configurator/generator plugin for Ethtrcv MCAL.

FLS_TI_MCAL2x

This directory contains the configurator/generator plugin for FLS MCAL.

Gpt_TI_MCAL2x

This directory contains the configurator/generator plugin for GPT MCAL.

Icu_TI_MCAL2x

This directory contains the configurator/generator plugin for ICU MCAL.

Mcu_TI_MCAL2x

This directory contains the configurator/generator plugin for MCU MCAL.

Os_TI_MCAL2x

This directory contains the Os stub for Os services module.

Port_TI_MCAL2X_AM273X

This directory contains the configurator/generator plugin for PORT MCAL.

Port_TI_MCAL2X_AM2732S

This directory contains the configurator/generator plugin for PORT MCAL.

Pwm_TI_MCAL2x

This directory contains the configurator/generator plugin for the Pwm MCAL.

Spi_TI_MCAL2x

This directory contains the configurator/generator plugin for Spi Handler Driver.

Wdg_TI_MCAL2x

This directory contains the configurator/generator plugin for Wdg module.

In each folder the contents are described below:

  1. <Module>/config/<Mod >.xdm – ECU Parameter definition for the MCAL module.

  2. <Module>/config_ext/<Mod>_Rec.xdm – Recommended values of ECU Configuration Description for the MCAL module.

  3. <Module>/generate/include/<Mod>_Cfg.h – EB tresos template file for precompile config header file generation.

  4. <Module>/generate/src/<Mod>_Lcfg.c or <Module>/generate/src/<Mod>_PBcfg.c or <Module>/generate/src/<Mod>_PBcfg.c– EB tresos template file for link/postbuild/precompile config C file generation.

Note

Please refer Directory Structure, where the generated files are placed in examples_config folder.

3.7. Installation

To install MCAL Configurator package on your PC, install ‘mcal_config_setupwin32_xx_xx_xx_xx.exe’ as admin by Right clicking on that installer and selecting ‘Run as administrator’. The installer allows you to choose the installation directory. The MCAL includes several sub-components, and all the components will be installed in the same location (e.g., “ C:/ti/ mcal_config_xx_xx_xx_xx”).

After installation you should see the following directory structure:

_images/Eb_Directory.png

Figure 4: EbTresos Directory.

3.7.1. Elektrobit Tresos Installation

The following steps need to be followed to install EB Tresos:

  1. Acquire a node-locked single user/eval license on machine where you are going to use EB tresos.

    1. Install EB Client License Administrator 1.2.4:

      • Unzip archive Elektrobit/installer/EB_24_ClientLicenseAdmin_CommandDownload2018-05-30.7z

      • From the extracted folder launch EB_Client_License_Administrator_1_2_4_Setup.exe as administrator.

      • On successful installation you should see icon “EB Client License Administrator 1.2.4” on your desktop.

    2. Launch EB Client License Administrator 1.2.4.

    3. Enter the activation key provided to you by TI FAE. If you have not got the activation key please contact your TI FAE.

    4. Click on “Activate” button.

    5. Check the status of the license activation sequence. If successful your license is ready to use.

    6. For details refer Elektrobit/docs/LicensingUsersGuide.pdf Chapter 5.

_images/License_Administrator.png

Figure 5: License Administrator.

  1. Unzip archive Elektrobit/installer/EB_24_Installer_CommandDownload2018-03-27.7z

  2. From the extracted folder launch EB setup by selecting setup.exe as administrator. Refer Chapter 1 (Installing EB tresos studio) of EB_tresos_Installation_guide for details.

  3. Click Install on below window.

_images/Eb_Installer.png

Figure 6: EbTresos Installer.

  1. After installation, launch “tresos Studio 24.0” and confirm you are able to open EB tresos without any license failure errors.

3.7.2. Elektrobit Tresos License Troubleshooting

If after successful license activation using “EB Client License Administrator” you still face issue with license, please check the following:

  1. Check if “FlexNet Licensing Service” service is started in your Windows Service Manager Panel (Control Panel -> Administrative Tools -> Services). If it is not starter manually start it.

  2. Disable any Anti-Virus software on your machine.

  3. If not possible to disable Anti- Virus, add user defined exceptions in Anti- Virus software to the following folders:

    • C:/ProgramData/Flexnet/*

    • C:/EB/*

  4. If you continue to face license error issues, contact EB support via Help->EB tresos support in EB tresos.

3.7.3. TI MCAL configurator plug-in installation

  1. Close any open Ebtresos instances.

  2. Copy the contents of mcal_config_xx_xx_xx_xx/plugins folder to <EB_Tresos_Installation_Base>/plugins

3.7.4. TI MCAL generator verification

  1. Launch EB tresos studio 24.0. Click on Start icon.

_images/EB_Welcome.png

Figure 7: EBTresos Welcome Page.

  1. Click File->New ->Configuration Project

_images/Configuration.png

Figure 8: Configuration Page.

  1. Enter the following:

    • Project Name: TI Mcal Config (Click Next)

    _images/Project_creation.png

    Figure 10: Project creation.

    • ECU ID: AM273_MCAL

    • Target: ARM/MCAL2X from dropdown menu (Click Next)

    _images/Target_selection_am273.png

    Figure 10: Target selection.

    • Select all plugins listed. You should see all MCAL modules listed.

    • Confirm “Default Recommended Configuration” is selected in Recommended Configuration.

    • Click Finish.

    _images/Module_Configuration_am273.png

    Figure 11: Module Configuration.

  2. Project should be created with all the TI MCAL modules listed as individual packages.

_images/Project_Explorer_am273.png

Figure 12: Project Explorer.

  1. Right Click on project and choose “Verify Project”. You should see 0 errors.

  2. Right Click on project and choose “Generate Project”. You should see 0 errors. You should see the generated precompile, post build files under output/ folder in the project.

_images/Code_generator.png

Figure 12: Code generator.

  1. Ignore any warnings related to PARALLEL GENERATOR license.

  2. If you are successfully able to generate the files, your setup is ready for use. Refer 2.1_Studio_documentation_users_guide for details on how to configure AUTOSAR modules using EB tresos studio.

3.8. Working with Command Line

  1. To start the command line

    • Open the Windows command prompt.

    • Change into the directory, into which you have installed EB tresos Studio; e.g. C:/EB/tresos.

    • Change into the bin subdirectory.

    • You can execute a command by using tresos_cmd.bat; e.g., type tresos_cmd.bat –help to see a short help for the command line options.

Commands for legacy code generation

EB tresos Studio supports legacy mode. This mode works independently from projects. Use Recommended setting xdm files as input present in config_input/<Module>_TI_MCAL2x/config_ext/.

Command to generate code is as follows:

“C:/EB/tresos/bin/tresos_cmd.bat” -Decuid=MCAL2x -Dtarget=ARM -Dderivate=MCAL2x legacy generate -n Mcu -g Mcu_TI_MCAL2X -o “output directory to store output” config_input/Mcu_TI_MCAL2X/config_ext/Mcu_Rec.xdm

Options description:

-Decuid - This option specifiesthe Idof the imported ECU.

-Dtarget - Defines the target architecture

-Dderivate - Defines the target’s derivate

-n - Specifies the name of the module configurations of the configuration files to load

-g – Module Id -o - Sets the directory to which the generated files are written.

3.9. Tool versions

The EB tresos version shipped as part of TI MCAL package is v24.0

3.10. Hardware Setup

List of hardware required.

  • AM273EVM

3.11. Un-installing

Refer EB tresos documentation for details on how to uninstall EB tresos. The MCAL installer installs the un- installer in <install path> directory. The name of the un-installer is uninstall.exe. To uninstall these packages, please run the uninstaller.

3.12. References

  • AUTOSAR Specification 4.3.1

  • AM273EVM

  • EB tresos License user guide

  • EB tresos studio user guide