AM263Px MCU+ SDK: Building an Application

| AM263Px MCU+ SDK 26.00.00 |

Building an Application

Building an example is converting the source files of the application into a machine readable file.

- It involves two primary steps:
  - Compilation
  - Linking
- A compiler converts the human readable source code to assembly language, producing assembly files.
- The assembler converts assembly files into machine code, creating object files (.o/.obj)
- These files are not yet linked into an executable.
- A linker.cmd file specifies memory layout and sections placement information. The linker then combines the multiple object files into a single executable.

# Tools

Tool | Reference | Description
--- | --- | ---
Compiler | TI CLANG Compiler Toolchain | Converts .c source code to machine readable code.
Sysconfig | SysConfig | A GUI tool used for configuring pins, peripherals, software stacks, RTOS, clock tree, linker (see row below) and other components.
Creating linker.cmd file | Memory Configurator | A GUI method of creating a linker file using Sysconfig tool. It generates a linker.cmd file along with other component files.
.out to .mcelf | MCELF Image Gen | Takes individual core .out files as input and combines them to create a single .mcelf ELF file which can be booted by the SBL.
Signing tools | Signing Scripts | Collection of scripts needed to sign SBL and application images.
Clocktree | Clocktree | Configure the Clock settings for all peripherals from the Clocktree view.

# Creation of application binary

Note
  To see the exact sequence of steps in which applications and secondary bootloader (SBL) are converted from compiler generated .out files to boot images, see the makefile `makefile_ccs_bootimage_gen` that is included in every example and secondary bootloader (SBL) CCS project.
  If you are using makefile based build, then see the file named `makefile` in the example folder.

Shown below are the different steps that are done to convert the compiler+linker generated application `.out` into a format suitable for flashing and booting.

## Generating .out binary

- For each CPU, the compiler + linker toolchain is used to create a .out file.
- The compiler convertes the .c files into .asm files, the assembler converts .asm files to object files - .obj files.
- The linker then combines the multiple object files into a single .out file for each CPU.

Generating .out file

- This .out file can be loaded and run via CCS. Refer Load and run example binaries in CCS

## Generating .mcelf binary

- Refer Understanding Multicore ELF image format for information on MCELF
- The mcelf image generator script `genimage.py` takes each individual core's .out file as input and combines them to form a .mcelf file.
- This .mcelf file contains metadata and segments along with information like segment type, load address, size, alignment.
- The `.mcelf` file is then flashed to the board.

Post build steps MCELF

## Generating HEX binary

- TI does not provide a proprietary tool for hex conversion of binaries. Instead use available tools like SRecord that is compatible with both Windows and Linux platforms. It supports conversion of binaries to Intel hex, Motorola S-record and other commonly used formats.

### Installing SRecord on Windows

- Start on this page SRecord 1.65. Click on Download.
- On the next page, click on SourceForge.net download mirrors under the "Pre-compiled Windows Executable" heading.
- On the page that comes up, click on the green box that contains the text Download Latest Version.
- The file downloaded is named srecord-1.65.0-win64.exe. Run it to install the software.

### Installing SRecord on Linux

- Start on this page SRecord 1.65. Click on Download.
- On the next page click on 1.65 release folder under SourceForge Downloads —> Unix and Linux downloads.
- Click on the green box that contains the text Download Latest Version.
- The file downloaded is named srecord-1.65.0-Linux.tar.gz. Extract the package.

### Converting .mcelf to Intel hex:

- Order of invocation:
  {Path to srecord folder}\bin\srec_cat {Path to input binary} -{Type of input file} -offset {application offset from flash} -o {Path to output binary} -{Type of hex file}
- Example to generate hex file for hello world:
  {Path to srecord folder}\bin\srec_cat {SDK_PATH}\examples\hello_world\<soc>-<board>\r5fss0-0_nortos\ti-arm-clang\hello_world.release.mcelf -Binary -offset 0x81000 -o hello_world.release.hex -Intel
- This generated file can be flashed using your custom flashwriter (not Uniflash).

Note
  This process treats the .mcelf file as a raw binary and converts it as it is to hex. The contents after writing to flash will still be of mcelf format so that TI Bootloader can parse, load and boot the application. TI Bootloader cannot understand HEX format in flash.

## Signing the binary

Image | HSFS | HSSE
--- | --- | ---
SBL is signed | Yes | Yes
Application is signed | No | Yes

### SBL Signing

- After building, the SBL application `.out` file is first converted to a binary format `.bin` using the TI ARM CLANG `objcopy` tool.
- This `.bin` file is then signed using the Signing Scripts to create the final `.tiimage` bootable image.
  - The `.tiimage` file extension is kept to separate the SBL boot image from a normal application image
  - The rom_degenerateKey.pem is used for this.
  - This is a ROM bootloader requirement and is needed even on a non-secure device.
  - The signing tools take the `.bin` file
- The SBL communicates with ROM to get the HSMRt (TIFS-MCU) loaded on the HSM. This firmware provides various foundational security services. For HS-FS ,this can be found at source/drivers/hsmclient/soc/am263px/hsmRtImg.h. For HS-SE devices, more information can be found at MySecureSW. For integrating HSM RunTime with SBL, the following should be taken care of:
  - HSMClient should be initialized and registered.
  - HSMRT (TIFS-MCU) image signed appropriately should be available. For HS-FS, this is already part of the SDK, for HS-SE, this can be compiled with TIFS-MCU package (available on MySecureSW)
- Depending on the device type for which we build the SBL, there will be certain prefixes to the `.tiimage` extension like so:
  - HS-FS device:
    - `sbl_xxx.release.tiimage` [No prefix before `.tiimage`, plain image]
  - HS-SE device:
    - `sbl_xxx.release.hs.tiimage` [`hs` prefix before `.tiimage`]
- Note that if we just mentioned `hs` it is meant for HS-SE device.
- The `.tiimage` file can then be flashed or copied to a boot image using the Flashing Tools

TIIMAGE

- For detailed information refer SBL Image Generation

### Application signing

- Application image is signed only for HSSE secure boot.
- Refer Secure application image Generation for detailed information.

# Building a Hello world example

Steps to build the hello world example from SDK is mentioned here Build a Hello World example

# Next step - Loading the application

Go to Loading an Application