3. Getting Started With AM263Px MCAL

3.1. Package installer

3.1.1. CCS Setup

If user does not have a functional setup using CCS, then the instructions in this section are relevant.

3.1.1.1. Installation Steps

1.Use TI CCS v12.5.0 or later

2.After the package is downloaded, you will be prompted to restart CCS to complete the installation.

3.The installer will install the Emulation package and complete installation.

3.1.2. Hardware Setup

List of hardware required for AM263Px EVM:

1.AM263Px CC / EVM

2.5V 3Amp USB Type-C Power Adaptor.

3.Micro USB Cable.

3.2. AM263Px MCAL Overview

AM263Px is an SOC from TI targeted to address various AUTOMOTIVE markets. AUTOSAR is a key software which needs to run on ARM Cortex-R5 so that it can enable communication with other ECUs in the system. TI needs to provide the MCAL drivers for the AUTOSAR to run on the SOCs. Customers will need to procure the other AUTOSAR SW stack either internally or from third parties.

3.3. Folder structure

Mcu - This directory contains the source files for the MCU driver.
Port - This directory contains the source files for the PORT driver.
Spi - This directory contains the source files for the SPI Driver handler.
Can - This directory contains the source files for the Can driver.
Gpt - This directory contains the source files for the GPT driver.
Wdg - This directory contains the source files for the WDG driver.
Dio - This directory contains the source files for the DIO Driver.
Fls - This directory contains the source files for the FLS driver.
Eth - This directory contains the source files for the Eth driver.
EthTrcv - This directory contains the source files for the EthTrcv driver.
Adc - This directory contains the source files for the ADC driver.
Pwm - This directory contains the source files for the PWM driver.
Icu - This directory contains the source files for the ICU driver.
Ipc - This directory contains the source files for the IPC driver.
Uart - This directory contains the source files for the UART Driver.
I2c - This directory contains the source files for the I2C driver.
Dma - This directory contains the source files for the DMA driver.
FsiRx - This directory contains the source files for the FsiRx driver.
FsiTx - This directory contains the source files for the FsiTx Driver.
Lin - This directory contains the source files for the LIN driver.
Epwm - This directory contains the source files for the EPWM driver.
examples - Examples provided as part of the package to show MCAL driver usage.
examples_config - This directory contains configuration details(<Module>_Cfg.h / <Module>_Cfg.c) which are generated using EB Tresos tool for all drivers as per example use case. Refer - configurator_userguide for more details.
include - Contains include files referred by MCAL drivers.
autosar_include - These included files part of the AUTOSAR BSW core. There include files should replace with the header files part of the AUTOSAR stack into which the MCAL integrated.
build - Make files for building the MCAL library. MCAL supports make based build.
binary - The entire executables get placed in this directory. The generated library or executable/binary are placed in an appropriate path under target-specific directory.
examples/Utils - The contents of this directory SHOULD NOT be used in an AUTOSAR stack integration. It contains the utility API’s for ISR’s and enabling/disabling interrupts used, commonly across the examples when used in a non-AUTOSAR context.

3.4. Getting access to CSP

Will be added in later release.

3.5. Compiler Settings

3.5.1. Compiler Variants

MCAL package can be built with the following compiler variant: TI ARM CLANG 4.0.0.LTS.

Users can build with either compiler variants.

gmake all PLATFORM=am263px PROFILE=<release/debug> COMPILER_VARIANT=<CLANG>

COMPILER_VARIANT can take the following value(s): CLANG

If COMPILER_VARIANT is not specified during the build, MCAL will be built for CLANG by default.

3.5.2. Compiler Options

Below are the compiler flags used:

Compiler Option	Description
-c	Stop compilation after emitting compilergenerated object files; do not call linker.
-mlittle-endian	Select little-endian; default
-mcpu=cortex-r5	ARM R5 architecture
-mfpu=vfpv3-d16	Select appropriate floating-point hardware
-mfloat-abi=hard	Floating-point hardware is available; select appropriate hardware with -mfpu option
-ffunction-sections	Instructs the tiarmclang compiler to generate code for a function definition into its own section
-gdwarf-3	Emit DWARF version 3 debug information
-Werror	Treat detected warnings in the specified category as errors
-Os	Most optimizations enabled, especially optimizations that are designed to reduce code size while mitigating negative impacts on performance
-x	Decides the compile mode (c / c++ / ti-asm …)
-save-temps	Keeps all temporary files generated during compilation and linking without halting either the compiler or the linker
-mthumb	Recognized when using armclang as a compiler,but not when using it as a assembler

3.6. Modules Supported

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

Driver	Comments
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
ETH	Driver provides services to transmit and receive data with the external devices
ETHTRCV	Driver for Physical Layer Transceiver
ADC	Driver converts the analog value applied to ADC pin to its equivalent digital value
PWM	Driver provides the pulse width modulated signal
EPWM	Driver provides the enhanced pulse width modulated signal
ICU	The ICU driver is a module using the input capture unit (ICU) counting pulses, measuring of frequency and duty cycle
IPC	Make the initialization of mailbox driver and provides read and write APIs to perform inter processor communication
UART	Driver provides serial communication using UART
I2C	Driver provides support for transferring data between an external I2C device and the chip running this driver
DMA	Provides direct memory access
FsiRx	Provides fast serial data reception service with the external devices
FsiTx	Provides fast serial data transmission service with the external devices
LIN	Driver for the on-chip Lin controller peripheral

The MCAL drivers implement the Software specification as mentioned in the AUTOSAR 4.3.1 release. Additionally, examples to demonstrate MCAL driver usages have also been included.

3.7. Getting access to MCAL

Will be added later

3.8. Multi-core support & resource allocator

3.8.1. Supported Devices/Platforms

AM263Px: This release supports AM263Px SoC

3.9. Dependencies

Will be added later

3.10. Start-up & AppUtils

Will be added in later release

3.11. Build system

3.11.1. Build Steps

This section describes how to build the MCAL package. The package is built using “gmake” from Cygwin. Make sure that the Cygwin tools location is added to the PATH variable. Also, make file internally uses some binaries like rm, mkdir, echo etc. from Cygwin. Standard CCS installation comes with Cygwin, gmake and other utils as required to build MCAL modules.

Edit the Rules. Make file present in <MCAL_INSTALL_PATH>/build/Rules.make to give the appropriate paths for the tool chains and the current working directory. Make sure that CCS_PATH, and the TOOLCHAIN_PATH_R5 are updated with the proper path.

Edit paths for the below variables according to your system environment

1.In case of windows machine edit CCS path according to CCS version,

CCS_PATH := C:/ti/ccs1250/ccs
TOOLCHAIN_PATH_R5 := $(CCS_PATH)/Compilers/ti-cgt-armllvm_4.0.0.LTS

2.In case of Linux machine edit CCS path according to CCS version,

CCS_PATH := /opt/ti/ccs1250/ccs
TOOLCHAIN_PATH_R5 := $(CCS_PATH)/Compilers/ti-cgt-armllvm_4.0.0.LTS

3.By default the above are for CLANG compiler, modify respective paths accordingly for using other compilers.

4.Install dependencies required for MCELF image format
Install Python3
Install Pip
Make sure pyelftools and construct is installed from pip. This package is required for encrypting MCELF application images.
pip install pyelftools construct
Install openssl v3 from here https://slproweb.com/products/Win32OpenSSL.html

Also, the path to generated pre-compile headers for the MCAL modules and generated <Module>_Memmap.h needs to be set by modifying macro autosarConfig_PATH. The value can be list of directories separated by space.

By default, MCAL package provides pre-generated pre-compile config headers under <MCAL_INSTALL_PATH>/examples_config/<Module>_Demo_Cfg/soc/<SOC>/<Core>/include.

<SOC> should be with the following value(s): am263px in folder structure.

Sample <Module>_Memmap.h can be found under <MCAL_INSTALL_PATH>/include/memmap

Go to <MCAL_INSTALL_PATH>/build directory and type below commands:

Description	Commands
Command to build all the libraries	gmake -s all PLATFORM=am263px
Command to build an application given in examples folder	gmake -s <app_name> PLATFORM=am263px app_name can be found in the make file of the respective examples folder.
Command to clean all targets	gmake -s clean PLATFORM=am263px
Command to clean individual targets	gmake -s $(target)_clean PLATFORM=am263px
Command to build an application for Resolver Package	gmake -s <app_name> PLATFORM=am263px PACKAGE=L
Command to build an application for Compatible Package	gmake -s <app_name> PLATFORM=am263px PACKAGE=C
Command to build an application for SIP Package	gmake -s <app_name> PLATFORM=am263px PACKAGE=SIP

3.11.2. Build Profiles

MCAL package can be built in two profiles:

Release Profile
Debug Profile

Users can build in mode by setting parameter PROFILE while building.

gmake all PLATFORM=am263px PROFILE=<release/debug>

PROFILE makefile macro can take either of the following values:

release for Release Profile
debug for Debug Profile

If PROFILE is not set during build, MCAL will be built for release profile by default.

To build all the examples and libraries in debug mode, you can give the following command.

gmake -s all PLATFORM=am263px PROFILE=debug

Similarly, PROFILE can be set in all the above build commands.

3.11.3. Cable Connections

Important cable connections, ports and switches.

3.11.3.1. AM263PX-CC

1.System Power On/Off

5V power through Type-C 5V/3A
HSEC 5V power is available only if Type-C is unavailable
No mechanical on/off switch on this EVM

3.11.3.2. AM263PX-LP

3.11.4. Setup UART Terminal

3.11.4.1. AM263PX-CC

1.Many examples use a standard UART terminal to log the output from the examples. You can use any UART terminal program for the same. Below steps show how to setup the UART terminal from CCS.

2.First identify the UART port as enumerated on the host machine.

Make sure that the EVM and UART cable connected as shown in Cable Connections
In windows, you can use the “Device Manager” to see the detected UART ports
Search “Device Manager” in Windows Search Box in the Windows taskbar.
If you don’t see any USB serial ports listed in “Device Manager” under “Ports (COM & LPT)”, then make sure you have installed the UART to USB driver from FTDI, https://www.ftdichip.com/FTDrivers.htm.

Fig. 3.4 Identify UART Port in Windows Device Manager

3.In CCS, goto “View > Terminal”

4.Open a new UART terminal

5.Select the UART port, keep other options to default, i.e 115200 baud rate - 8 data bits - No parity - 1 stop bit,

We use this serial port, as seen in the device manager, for below in the SDK
- Flashing application via UART
- Booting application via UART
- Console output for examples

6.In this screenshot this happens to be COM5/COM11 however on your machine this could be different. One tip to make sure there is no mistake in identifying the UART port is to disconnect all other UART to USB devices other than this EVM before checking in device manager.

3.11.4.2. AM263PX-LP

1.Many examples use a standard UART terminal to log the output from the examples. You can use any UART terminal program for the same. Below steps show how to setup the UART terminal from CCS. 2.First identify the UART port as enumerated on the host machine.

Make sure that the EVM and UART cable connected as shown in :ref:Cable Connections_p.
In windows, you can use the “Device Manager” to see the detected UART ports.
Search “Device Manager” in Windows Search Box in the Windows taskbar.
If dont see any USB serial ports listed in “Device Manager” under “Ports (COM & LPT)”, then make sure you have installed the UART to USB driver from FTDI, https://www.ftdichip.com/FTDrivers.htm.

3.In CCS, goto “View > Terminal”

4.Open a new UART terminal

5.Select the UART port, keep other options to default, i.e 115200 baud rate - 8 data bits - No parity - 1 stop bit,

We use this serial port, as seen in the device manager, for below in the SDK
- Flashing application via UART
- Booting application via UART
- Console output for examples

6.In this screenshot this happens to be COM5/COM11 however on your machine this could be different. One tip to make sure there is no mistake in identifying the UART port is to disconnect all other UART to USB devices other than this EVM before checking in device manager.

3.12. Information on the AM263Px device family

Will be added in later release

3.13. Boot Modes

Note

–This section has more details on AM263PX-CC. This is mainly for reference. Make sure boot mode switch is setup to NOBOOT mode to use with CCS.

3.13.1. OSPI BOOT MODE

3.13.1.1. AM263PX-CC

This mode is used to boot flashed applications via EVM flash like OSPI flash.

BOOTMODE [ 1 : 4 ] (SW3) = 1100

3.13.1.2. AM263PX-LP

This mode is used to boot flashed applications via EVM flash like OSPI flash.

3.13.2. UARTBOOT MODE

3.13.2.1. AM263PX-CC

This mode is used to flash files to the EVM flash via UART. It can also be used to boot applications via UART.

BOOTMODE [ 1 : 4 ] (SW3) = 1000

3.13.2.2. AM263PX-LP

This mode is used to flash files to the EVM flash via UART. It can also be used to boot applications via UART.

3.13.3. NOBOOT MODE

3.13.3.1. AM263PX-CC

This mode is used in CCS.

BOOTMODE [ 1 : 4 ] (SW3) = 1101

3.13.3.2. AM263PX-LP

This mode is used in CCS.

3.14. Memory Usage

Please refer Memory Footprint for more details.

3.15. Multicore ELF Image Format

Multicore ELF, or MCELF is a new application image format different from the existing RPRC format. Unlike a proprietary format like RPRC, multicore elf is based on the widely recognized ELF (Executable and Linkable format) standard. This ensures seamless compatibility with industry-standard tools and platforms.
For more information on ELF format please refer: https://man7.org/linux/man-pages/man5/elf.5.html
For more information on MCELF image format please refer: AM263Px MCU SDK: Understanding Multicore ELF image format

3.16. Running the examples

Connect the CC or EVM board to your computer through JTag (USB Port)

Before running the binary file on target H/W follow the steps mentioned below:
Launch CCS, Go to View > Target Configuration
Create a new target configuration
Give a nice name to the new target configuration, typically {SOC name} _ {JTAG type}
Select connection as XDS110 USB Debug Probe
In “Board or Device” type “@VAR_SOC_NAME” and select “AM263Px”
Click “Save” to save the newly created target configuration.
Under Advanced tab – Select Cortex_R5_0
Make sure the device gel file path is in the Initialization script field (C:/ti/ccs1250/ccs/ccs_base/emulation/gel/AM263Px/AM263Px.gel)
Click “Save” to save the newly created target configuration
Launch the target configuration for AM263Px
Connect to Cortex_R5_0 core
Connect UART USB cable to the serial UART terminal (with appropriate port) and select UART1 serial port for viewing the UART logs and providing user input. By default, configuration may be matched by selecting baud rate as 115200, 8-bit Data Size, Parity None and 1 Stop Bit as the serial port settings.
Load binary files using Load Program option
Run the application and follow the prompts and output on CCS console/UART serial console.