TI Tiva TM4C12x

Porting Paulus on TI Tiva TM4C12x

File structure

After installation of Paulus the source code is stored in the file structure shown in Table 1 describes the contents.

directory

description

/paulus_tm4c129x

project folder with all necessary code composer project files for the Tiva cpu type tm4c129x

/paulus_tm4c129x_Keil

project folder with all necessary Keil µVision project files for the Tiva cpu type tm4c129x

/bootloader

target independent CANopen sources for Paulus

/eds

Design Tool project of Paulus with all generated files, e.g. the EDS file and documentation files

/tiva_tm4c/

target-specific sources of Paulus, e.g. CAN-driver and Flash services

/tiva_tm4c/tm4c_flash.[ch]

target-specific flash routines (used flash TivaWare driver)

/tiva_tm4c/tm4c_can.[ch]

CAN routines

/tiva_tm4c/tm4c_init.c

CPU initialization

/tiva_tm4c/environ.h

header file for the environment includes

/tiva_tm4c/bl_config.h

Paulus configuration file

/tiva_tm4c/startup_ccs/…

Startup and linker file from TI CCS adapted by port

/examples

example applications for a CANopen slave and simple “hello World” example with necessary project files

/tools

checksum generator tool for Paulus

main.c

main loop of Paulus

Table 1: File structure

Paulus is implementet und tested on the Board “DK-TM4C129X development kit” from TI with TM4C129X.

The initialization of the CAN controller is done in module /tiva_tm4c/tm4c _can.c.

In module tm4c _init.c the I/O pins for the CAN interface have to be initialized.

In module tm4c_init.c there must be the functions getBitRate() and getNodeId() available. Usually the CANopen network parameters are provided by reading jumpers or by loading from flash memory.

Development environment

Paulus on the platform of TM4C129X was developed with the workbench TI CodeComposer v6.1.2. The TI firmware TivaWare (version 2.1.3.156) is used. Please install first this SW-framework before you can build and run the Paulus software. You can download this from TI: http://www.ti.com/tool/sw-tm4c. Additional a porting with Keil µVision v5.26 is included. This porting used the same TivaWare package.

Paulus configuration

In general the initialization function initializes only the absolutely necessary peripherals like clock system, CAN controller, memory management as needed by Paulus and a timer for Heartbeat or LSS. Nevertheless, there might be situations where it makes sense that Paulus initializes other functionalities which are later used by the application as well. As an example consider the serial interface for debug messages.

CAN bit rate

The CAN bit rate is coded by the index of the CAN bit timing table according to /CiA-305/. The index of the default CAN bit rate is specified about the compiler-define BITRATE_INDEX_<bit_rate> in / tiva_tm4c /bl_config.h:

#define BL_USED_BITRATE_INDEX   BITRATE_INDEX_125K

The default CAN bit rate is 125 kbit/s and can be changed by LSS services. The LSS services are described in /Paulus_man/ and base on /CiA-305/. The supported CAN bit rates are depending on the clock of the CAN controller and are listed in /tiva_tm4c/tm4c_can.c. The value FFh for segment2 marks unsupported CAN bit rates. The clock for the activation of the CAN bit rate is generated by hardware Timer0 with a period of 1 ms.

Heartbeat producer

Timer0 is also used for the generation of Heartbeat producer messages.

Debug output

By the compiler-define DEBUG a debug output can be activated about the serial interface usart. The compiler-define is set in file / tiva_tm4c / bl_config.h:

#define DEBUG 1

In general the initialization function will initialize only the absolutely necessary peripherals like clock system, CAN controller, memory management as needed by Paulus. Nevertheless, there might be situations where it makes sense that Paulus initializes other functionalities which are later used by the application as well. As an example consider the serial interface for debug messages.

Generating application software

The application software consists of an application header and an application program.

The application program has to be prepared for download by the following steps:

  •     build the application program in binary format

  •     calculate the CRC of the application program, build the application header and generate the application software to download

  •     configure the start address of the application software in Paulus

Paulus checksum

The program paulus_cksum calculates the CRC checksum of the binary application program generates the application header and stores the application header and the application program in a new file. This file can be loaded in the device by Paulus. The application for download must be a binary file.

Use of TI Code Composer Studio

They could e.g. use the CCS Post build step to convert a created output file from CCS to binary file as an intermediate step. We used following Postbuild script like TI example (placed in CCS menu -> /build/Steps/Post-build steps):

1 2 3 4 "${CCE_INSTALL_ROOT}/utils/tiobj2bin/tiobj2bin" "${BuildArtifactFileName}" "${BuildArtifactFileBaseName}.bin" "${CG_TOOL_ROOT}/bin/armofd" "${CG_TOOL_ROOT}/bin/armhex" "${CCE_INSTALL_ROOT}/utils/tiobj2bin/mkhex4bin"

“HelloWorld”-Example: show the execution from the prepared post build command in the CCS console:

1 2 3 4 "C:/ti/ccsv6/utils/tiobj2bin/tiobj2bin" "hello_tm4c.out" "hello_tm4c.bin" "C:/ti/ccsv6/tools/compiler/ti-cgt-arm_5.2.5/bin/armofd" "C:/ti/ccsv6/tools/compiler/ti-cgt-arm_5.2.5/bin/armhex" "C:/ti/ccsv6/utils/tiobj2bin/mkhex4bin"

Unused bytes in the application header are set to 0x00 with the Tiva TM4C. The length of the application header is 1024 bytes.

Example: The download file for the application program hello_tm4c_download.bin is generated about Windows console with the prepared script “create_image.bat”:

1 2 3 4 5 6 7 8 9 10 11 C:\jsc\Paulus_TivaTM4C\software\examples\hello_TivaTM4C>..\..\tools\paulus_cksum -v -C -l 1024 -x 0x8400 hello_tm4c\Debug\hello_tm4c.bin -O hello_tm4c_download.bin reduce Flash end to file end: 0x00002f40 reduce EndAddr to the Flash end 0x00002f3f address - crc: 0x00000000, start: 0x00000000, end: 0x00002f3f, exec 0x00008400 Flash end: 0x00002f40 out: >hello_tm4c_download.bin< input: >hello_tm4c\Debug\hello_tm4c.bin< calc CRC from 0x00000000 to 0x00002f3f size: 0x00002f40, crc: 0x02c7 Writing Appl. to >hello_tm4c_download.bin<: length: 12096/0x2f40, crc: 0x02c7, execadr: 0x00008400

Use of Keil µVision

Unused bytes in the application header are set to 0x00 with the Tiva TM4C. The length of the application header is 1024 bytes. The application must be a binary file. They could e.g. use the tool

hex2bin to convert a created hex file to binary. (Download ->https://sourceforge.net/projects/hex2bin/)

Example à The download file for the application program s1_tivatm4c_keil_download.bin is generated about Windows console with the prepared script “create_image.bat”:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 C:\Paulus_TivaTM4C_Keil\software\examples\CANopenSlave1_TivaTM4C\examples\ s1_TivaTM4C_FreeRTOS_withHeap>..\..\..\..\tools\hex2bin.exe s1_tivatm4c_Keil\Objects\s1_tivatm4c.hex hex2bin v1.0.1, Copyright (C) 1999 Jacques Pelletier Lowest address = 00008400 Highest address = 0000F0A7 - create example application download binary – C:\Paulus_TivaTM4C_Keil\software\examples\CANopenSlave1_TivaTM4C\examples\s1_TivaTM4C_FreeRTOS_withHeap>..\..\..\..\tools\paulus_cksum -v –C -l 1024 -x 0x8400 s1_tivatm4c_Keil\Objects\s1_tivatm4c.bin -O s1_tivatm4c_keil_download.bin reduce Flash end to file end: 0x00006ca8 reduce EndAddr to the Flash end 0x00006ca7 address - crc: 0x00000000, start: 0x00000000, end: 0x00006ca7, exec 0x00008400 Flash end: 0x00006ca8 out: >s1_tivatm4c_keil_download.bin< input: >s1_tivatm4c_Keil\Objects\s1_tivatm4c.bin< calc CRC from 0x00000000 to 0x00006ca7 size: 0x00006ca8, crc: 0x0941 Writing Appl. to >s1_tivatm4c_keil_download.bin<: length: 27816/0x6ca8, crc: 0x0941, execadr: 0x00008400

For both variants valid

Besides checking the CRC Paulus checks also the size of the application header. A size of 0 is invalid. An application may destroy the ’valid’ information by overwriting the size with 0xFF. That is always possible on the Tiva TM4C FLASH, because the byte content is 0xFF after erasing.

More detailed information from this tool can find in /Paulus_CRC/.

Start address

It is important that the start address of the application software in the flash memory and the information in the Paulus configuration in /tiva_tm4c/bl_config.h are identical. The application software is stored as a separate program in the flash memory additionally to the bootloader program. Therefore the application software is flashed to:

#define FLASH_PROGRAM_START_ADR   0x00008000

The length of the application header is 1024 byte. The program start of the application is at address (FLASH_PROGRAM_START_ADR + 1024 bytes).

Explanation: When configuring the OFFSET field for interrupt Vector Table Offset from application, the offset must be aligned to the number of exception entries in the vector table. Because there are 112 interrupts, the offset must be aligned on a 1024-byte boundary.

Memory

Shared RAM

The shared RAM for data exchange between bootloader and application starts at address 0x2003FF00 in the NOINIT section from SRAM block. This address and the size is a default and may be customizable to other user requirements. The size of the current used shared RAM is specified in /tiva_tm4c/bl_interface.h by the compiler-define BL_JUMPCODE_SIZE.

The shared memory is installed in /tiva_tm4c/bl_interface.c as follow (either Keil or CCS version):

1 2 3 4 5 6 7 8 #if defined(__CC_ARM) /* using Keil ARMCC compiler */ /* jumpcode placed on ram adress 0x2003FF00 */ UNSIGNED8 jumpcode[BL_JUMPCODE_SIZE] __attribute__((at(0x2003FF00))); #else // Code Composer studio #pragma DATA_SECTION(jumpcode , ".noinit") UNSIGNED8 jumpcode[BL_JUMPCODE_SIZE]; #endif

The keyword for the re-start of the application program is set in byte 0-3 of jumpcode. Paulus uses the keyword “APPL” or “BOOT”  to start the application program, see /Paulus_man/.

Flash

The size of the respective flash is dependent on the CPU type. The total size of the TM4C129XNCZAD flash is 1024Kb. The current implementation of Paulus occupies a memory area of 32Kb from this. Therefore 992Kb (less 1024 byte crc header) flash memory area available for the application software.

Flash memory TM4C129XNCZAD device type:

 

The flash area for configuration data of Paulus is located at address 0x7F00. On this address and the following Paulus stores the node-ID and the CAN bit rate index during the execution of the optionally  LSS service “LSS store configuration“. The addresses are configurable in /tiva_tm4c/bl_interface.h:

1 2 #define FLASH_ADDRESS_NODEID 0x7F00 #define FLASH_ADDRESS_BITRATE_INDEX 0x7F01

After the next re-start Paulus uses this node-ID and this CAN bit rate index for communication. The new CAN bit rate cannot be activated by NMT-Command Reset Application. If the LSS services are not used, Paulus uses the node-ID and CAN bit rate index configured in /tiva_tm4c/bl_config.h.

Example application

Use of TI Code Composer Studio

CANopen Slave1 is an example for an application program. The directory examples/ CANopenSlave1_TivaTM4C/ contain the compiler project and the application-specific functions. For compilation the CANopen Library and the suitable driver package is necessary. The CANopen Library and the driver package belong not to the delivery scope of Paulus. The binary application software in example/ CANopenSlave1_TivaTM4C/bin/s1_tivatm4c_download.bin can be used for a quick start.

Additional a simple “hello World” example is available for some targets (/examples/ hello_TivaTM4C/). This example sends usart printf output after jumping into this. After some time, the jump back into the boot loader. The linker file of this example project is adapted on these Paulus memory requirements. See flash address settings in the examples linker-file (tm4c129xnczad.cmd):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 /* The starting address of the application. Normally the interrupt vectors */ /* must be located at the beginning of the application. */ #define APP_BASE 0x00008400 #define RAM_BASE 0x20000000 MEMORY { FLASH (RX) : origin = APP_BASE, length = 0x000F7C00 SRAM (RWX) : origin = RAM_BASE, length = 0x0003FF00 NOINIT : origin = 0x2003FF00, length = 0x00000100 } /* Section allocation in memory */ /* Section .noinit is placed for hold the Paulus jumpcode variable */ SECTIONS { .intvecs: > APP_BASE . . .

Use of Keil µVision

CANopen Slave1 is an example for an application program. The directory example/ CANopenSlave1_TivaTM4C/examples/s1_TivaTM4C_FreeRTOS_withHeap/ contain the compiler project and the application-specific functions. For a new compilation the CANopen Library, FreeRTOS sources and the suitable driver package is necessary. The CANopen Library and the driver package belong not to the delivery scope of Paulus. The binary application software in example/ CANopenSlave1_TivaTM4C/bin/ s1_tivatm4c_keil_download.bin can be used for a quick start.

The linker file of this example project is adapted on these memory requirements with the Target dialog from the Keil μVision-IDE:

Additional see the settings in scatter-file (s1_tivatm4c.sct) as output from linker:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ; ************************************************************* ; *** Scatter-Loading Description File generated by uVision *** ; ************************************************************* LR_IROM1 0x00008400 0x000F7C00 { ; load region size_region ER_IROM1 0x00008400 0x000F7C00 { ; load address = execution address *.o (RESET, +First) *(InRoot$$Sections) .ANY (+RO) .ANY (+XO) } RW_IRAM1 0x20000000 0x0003FF00 { ; RW data .ANY (+RW +ZI) } RW_IRAM2 0x2003FF00 UNINIT 0x00000100 { .ANY (+RW +ZI) } }

For both variants valid

This examples has included source files bl_interface.c, bl_interface.h from bootloader. The application program can request an update by jumping back into Paulus by writing of the program control command start application program (value 1) on object 1F51h/1. The application program calls the macro BOOTLOADER_JUMP(APPL). This call is implemented in usr_301.c /sdoWrInd(). The application program stores the keyword “APPL” in the shared RAM and jumps into Paulus. Paulus is re-started and stays running until the application program is started by command.

References

/CiA-305/

CANopen Layer Setting Services and Protocols, CiA

/Paulus_CRC/

manual “Paulus Checksum Tool”, see file  tools/manual_cksum.pdf

/Paulus_man/

manual “Paulus User Manual”, see file  UserMan_Paulus_Bootloader_e.pdf

Table 2: References