Making Customizations

You may wish to make customizations the way that this package is configured. For example, you may wish to change the RM48 family part number to the part that you plan to target; or change to a TMS570 series part. Or, you may wish to change the core's clock rate, communication baud rate or some other device setting that affects performance. We will provide guidance in this section to help make this package better suite your needs.


Key files and their Roles within this Package

We will start with a description of key files in this package and what their roles are in the build, download, and simulation phases are. All filenames are relative to the target pacakges root installation directory.

Assuming that you have already gone through the setup steps, the target root directory can be found by the command:


File / Path Description
Files Controlling the Build Process
Determines the Compiler, Assembler, Linker options that are used when embedded coder generates a makefile to build the PIL target.

This file creates instances for each host OS platform of an coder.make.Toolchaininfo object for the RM48xx target and Code Composer Studio Toolchain.

This file primarily configures the Compiler, Assembler, and Linker options for three build profiles:

  • Faster Builds - Optimization Level 0
  • Faster Runs< - Optimization Level 2
  • Debug - Optimization Level 0 and Debug Symbols
For each of these build profiles, the basic compiler options needed to target an RM48xx device are also defined in this file.

For example compiler options such as -mv7R4, --float_support=VFPv3D16, and --little_endian (among others) are set in this file.

You must run RefreshToolchainMATFiles.m any time you change this file.
You must run this script after making changes to TI_HERCULES_RM48_toolchain.m.

This script saves the coder.make.Toolchaininfo objects created by the TI_HERCULES_RM48_toolchain.m script as individual .MAT files, with one .MAT file for each host OS platform.

The toolchain registration methods that make the RM48 appear in the simulink model configuration dialog read these .MAT files. Therefore, this script must be run each time changes are made to the toolchain script or else the changes will not be reflected in the makefiles that are generated during the build process.
This file contains a code replacement table 'cr4pmu_crl' and an entry specifying the HalCoGen function _pmuGetCycleCount_() as a replacement for the embedded coder function code_profile_read_timer.

This replacement enables the code execution profiling capabilities available during a PIL simulation.
This file defines a subclass of the class rtw.pil.RtIOStreamApplicationFramework and defines an RM48 specific constructor method.

The constructor method gets a handle to the object's RTW.BuildInfo object using the getBuildInfo method. It then uses the Simulink Coder functions addIncludePaths, addSourcePaths, and addSourceFiles to add all of the RM48 specific framework source files to the build.

So, for example, all of the HalCoGen sources and includes are added in this constructor.   If you decide to target a differnet device, you may wish to generate a set of HalCoGen sources in a separate folder.   Then you would change the path to the HalCoGen sources and includes inside this file to point to your new source folder.

Other sources that are added to the build in this file are the rtIOstream implementation sources, and the standard PIL main sources from the Mathworks Embedded Coder toolbox.

Note that the Mathworks PIL main sources define the main() function for the PIL applicaiton, so the HalCoGen main() function in file sys_main.c is specifically excluded from the list of files that are added to the build.
Framework Source Files (Device Setup, Serial Communication)
This file may be opened in HalCoGen to reconfigure and then generate device initializaiton code with different settings (or for a different device).
*.c, *.cpp, *.asm
Generated Source Files that make up device initialization code.  Do not Edit Manually, instead use HalCoGen to make configuration changes and generate again.
Generated Header Files for device initialization code.
Generated file that contains main().  This file is excluded from the build procedure because EmbeddedCoder adds it's own main() to the build that implements the XIL protocol engine and calls rtIOStream functions.
HERCULES_RM48 Specific RTIOStream functions, rtIOStreamOpen, rtIOStreamClose, rtIOStreamSend, and rtIOStreamRecv
Header file for RM48 Specific rtIOStream implementation.
Excluded from PIL build, but useful if you are customizing the rtIOStream functions for a differnent serial port or changing port settings. Creates a loopback function between rtIOStreamSend and rtIOStreamRecv so that you can test the low level functions independently.   See rtiostream_wrapper 
Files Involved in Launching (Download the PIL application to Target Board and Run)
This file defines a subclass of the class rtw.connectivity.Config.
This class ties the correct builder, launcher and communicator subclasses together to create a ConnectivityConfig object that is used to communicate with the target during a PIL simulation.
Note that the application framework is included through the builder.

In this file, we have defined the communicator to use the DLL libmwrtiostreamserial.dll on the Host, and to use the COMPORT and COMBAUD preferences set in the Matlab environment by the TI_HERCULES_RM48_setup function. To use a different communication link to the target, you would need to modify the comminicator definition in this file.
This file defines a subclass of the class rtw.connectivity.Launcher that is specific to the TI Hercules RM48 HDK.

The custom startApplication method in this file is responsible for invoking the loadti
utility to download and execute the PIL application on the target.  

If you wish to change the launcher to use a different method instead of the loadti utility that works through debug server scripting, then this would be the file to modify.  For example, you may wish to flash a bootloader onto your target board and then implement a custom function that is called by this file to communicate with the bootloader to download and execute the PIL executable.
This folder contains a customized version of the 'loadti' example utility that is included with the Code Composer Studio installation.   (Normally in the ccs_base\scripting\examples\loadti subdirectory of the Code Composer Studio installation).

'loadti' is a versatile utiltiy that can among other things download and execute a .out file on any TI target supported by Code Composer Studio.   For the RM48, the download step includes programming the .out file into the on-chip flash.

We have made a few modifications to the standard loadti.bat file that is included with Code Composer Studio.   First,  we have added command line parameters to accept the path to the debug server executable so that loadti can work outside of the Code Composer Studio installation tree.   Second, we had to change a debug session option AddCEXITbreakpointAfterLoad to 'false' or the RM48 would not continue to execute after the loadti script terminate.  (if the RM48 is halted as loadti terminates, then the simulaton will time-out trying to establish an rtIOstream connection to the halted device).

If you want to learn more about loadti or debug server scripting please refer to:
The loadti utility requires a Code Composer Studio target configuration file (.ccxml) to establish a JTAG connection with the target device through Debug Server Scripting.   We have included this file as an example that is suitable for use with the XDS100v2 emulator built into the RM48 HDK board. By default the TCONF preference in the 'TI_HERCULES_RM48' preference group is set to point to this file.

If you are using a different emulator, or a different target device, then: you need to use a .ccxml file that works for your emulator / target device combination.   You should also change the TCONF preference to point to your own .ccxml file instead of this file.

For help creating target configuration files, see Common_target_configurations_v5

Customizing the Device Initialization Code

If you wish to make changes to the device initialization code, (e.x. flash wait states, CPU clock frequency) then you might do the following:

Customizing Compiler Options (Same Target Device)

You may also want to customize the compiler options that are used during the PIL build process. These settings are controlled by the TARGETDIR\utils\TI_HERCULES_RM48_toolchain.m file.

Simply changing the compiler optimization level may not require edits to this file, because this file already has defined build profiles for Faster Builds (-O0) and Faster Runs (-O2). You can switch between these profiles by changing the build configurations parameter:
ex. set_param('ex1_fir_mdl_tb','BuildConfiguration','Faster Runs')

On the other hand, changing a compiler option like '--little-endian' will require edits to this file. This file is not a makefile itself, but sets varialbles that are used in the generated makefile. Therefore, you should be familiar with makefiles before attempting to edit this file.

Finally, always make sure to run the script TARGETDIR\utils\RefreshToolchainMATFiles.m after making changes to TI_HERCULES_RM48_toolchain.m.

Targetting a TMS570 Series Hercules Device

In case you wish to target a TMS570 series hercules device, you will need to make additional changes.

For help creating target configuration files, see Common_target_configurations_v5

Changing the Serial Port Baud Rate

If changing the serial port Baud rate, you need to make sure to change both the target's SCI baud rate and the Host's COM port baud rate. To change the Target's SCI baud rate, modify the baud setting in HalCoGen and re-generate the driver files. See Customizing the Device Initialization Code for more detials on how to do this.

To change the host side COM port baud rate, you simply change the preference 'TI_HERCULES_RM48','COMBAUD' to match the baud rate that you configured through HalCoGen.

Note: The target baud rate setting also is dependent on having the correct PLL clock frequency. If you are using your own board, make sure that you have configured the Crystal input frequency in HalCoGen to match the crystal frequency on your board. If they don't match, then the SCI baud settings will also be wrong.

Copyright (C) 2012-2014 Texas Instruments Incorporated. Licensed as Creative Commons 3.0 Share Alike