Linking Matlab/Simulink ERT with the Concerto C28x core

Dear all,

here they follow some instruction on how to run the new Concerto architecture from Matlab/Simulink environment.

 Concerto architecture has not yet been supported by matlab,  and probably they will delay this support a bit more. There  are several reasons for this delay:
 
    * Concerto is new: it takes time to implement all changes;
    * it is dual, different types, core architecture: so matlab needs to implement support also for the m3 core which is not  currently in the target processor support;
    * the control of most features happens in the M3 core which is now the master processor.

Matworks is a high professional company. I guess a decent support to the M3/DSP solution will take a while and maybe it will not appear in the next 2/3 releases of their software.

When I have seen the concerto architecture, I thought it was perfect for teaching in a class, cause it separates among communication and control issues. However, soon I realized that compiling a control scheme for Concerto was not as easy as it was for F28xxx, and I dedicated some time to check the best we can do for implementing such support.

In order to understand how I realized the attached makefile, I have to premise some information:

1. TI devices and compatibility: SPRU566 application note, is fundamental to understand the  compatibility map between the models in the family C28x. Each DSP implements a different generation of interface  (called types) according to the model number. Using this documentation,  you     can understand which interface would be compatible with Concerto.
    for example the ADC Type 3 found in the concerto manual says that concerto ADC is the same of 2803X one.
    
    Similarly, you may realize that some devices are common among several TI models. Hence, it does not matter which one you use within Matlab. For example GPIO is the same between all C28x models, but F28335 has a number of pins much similar to the one of F28M35 while F28035 looses pins.

    SPRU566, together with the concerto datasheet (SPRU566 is not yet updated to include concerto) help you to select the correct device.
    For each device you will find in the documentation which type is it , and from the SPRU566 find a proper match to other processors types who have matlab blocks.
    
    Once you select the appropriate matlab block, the compatibility is almost complete. This is mostly because TI uses a CStyle (structure based) interface to access and control the devices. If the type is the same, also the names of the structure fields is ensured. RTW  uses these structures to implement code generation.
    
    The only difference is for features that have changed and are now managed from the master core (pullup, pll, memory, number of  ADCs,...).
    
    Matlab files needs therefore some editing to remove undesired lines that should appear in the M3 part. As we will see, our approach manages this process automatically.
    
2. Dual core startup
    The C28x on the concerto will not start if not launched by a proper program on the M3Master that configures some environment settings before booting the control processor.
    So far, for starting, we can use the excellent demo (setupM3) you will find in the controlSuite documentation. This demo, can be later substituted  with your own, more complex programs. However, for debug and startup  activities the demo is already there, and will help you to minimize the  time required for setting up an initial configuration.
    
3. Matlab xmakefiles setup
    The full integration of the new processor will not have been possible without the XML compilation process implemented by ERT.
    Matlab explains how to modify xmakefilesetup, to link with the CCSv4. With few changes, you can use it to load programs in the
    target (using DSS server and the loadti.bat demo script of CCSV).  We use it to completely change the building process. In particular
    we insert, before building, a series of activities that alter the generated  code. The trick is simple and does not require to modify matlab in any way.

4. Integration process
    using control suite, the concerto new hardware structure is available in the device_support. Within that folder tree you will    find folders
    that can be bound to matlab code to emulate the support for the concerto integration.  There you will also find loading commands (.cmd) that maps memory structure and peripherals. For simplicity, we use them as-is. However, I strongly suggest to personalize the cmd files for what is appropriate for your code. Editing those files (with a bit of practice) is even more simple than the matlab provided target configuration setting (which is not anymore valid and which we ignore in our buikding process). The implementation concerto core differs from previous C28x models. The WaitState efficiency is higher hence you can consider to use flash running programs and leave more space  for the M3 processor (whose communication activities required more memory).
    
    The example cmd files completely skip the pre-configuration  prepared by matlab in the target preference section. You have to manually control any change to program mapping to memory and flash.

5. Missing features
    Concerto has twice the ADCs of the C2803x, more IPC features, and other devices not present in previous C28. So some devices are not yet in current matlab implementation. However, most devices are already there and you can insert them in your schematics to use concerto features (ePWM, GPIO, eQEP, 1ADC...).
    
    If you need more, a full port will require you to copy/modify or create some TLC files and block masks in matlab

6. Makefile
    I made some efforts to implement all the above work in just one  Makefile. The makefile can be placed anywhere in your file system  and attached to the code generation process as described in step seven.
    
    The operation performed by the makefile, make use of the gmake program and the perl program who come within any regular matlab installation.
    
    
    the makefile works as follows:
    
    First it locates relevant files and directories
    (You should edit this section)

    Second it determines the files to compile
    All library files + Matlab generated files
    We used here the old Makefile name (C2000TGT)
    to determine the details on files
    
    Third we determine the compile option
        - one half of the option are bound to the controlSUITE libraries and the new processor option
    
        - The second half is extracted from the matlab Makefile through the use of PERL


    Fourth perl is used to inspect and correct headers and code files.
    Using a set of mangling rules we change all references to 28035   with equivalent refs to F28M35 architecture.
    
    More sophisticated pattern matching rules remove unsupported features such as non existing registers/ports.
    

    Fifth we implemented the following rules
    
    build:
        Used also by the embedded RTW this rule compiles  the complete model
        
    Info:
        echoes several information on the building process to facilitate debug on errors
        
    convert:
        uses perl to convert all existing codes and headers to the new core architecture.
        
    execute:
        uses loadti.bat to load the program.out in the C28 core.
        This command requires the user to have defined a target LOADFILE.ccxml that only programs the C28x (skips m3) as
        documented by Texas for multicore debug.
        
    defaultM3:
        Still not yet completed I wish to have it to reload the M3 part of the core.


7. Installation procedure:

a. Download and install constrolSUITE and ccsv5
b. have a regular recent Matlab installation and configure it to use CCSV (information is in the Matlab documentation)
c. save the attached makefile in <YOUR PATH>
d. edit the first lines of the makefile to match your system configuration.
d. edit xmakefilestup introducing the following changes:
    * in the make TAB replace command arguments from:
    -f [|||MW_XMK_GENERATED_FILE_NAME[R]|||] [|||MW_XMK_ACTIVE_BUILD_ACTION_REF|||]
    to:
    -f <YOUR PATH>:\F28H52.mk  C2000TGT="[|||MW_XMK_GENERATED_FILE_NAME[R]|||]" [|||MW_XMK_ACTIVE_BUILD_ACTION_REF|||]
    * as for the F28335, you may also use the execute tax of the XMAKEFILESETUP to load and run the C28x core with the compiled application

       
8. Test and Conclusions
    Actually I can upload code on the Control subsystem just by hitting CTRL+b  on some hybrid schematics containing the following blocks:

        * Target preferences for C2803x
        * ADC for C2803x
        * ePWM for C2803x
        * GPIO for C28335
        * eQEP for C28345

    I only have tested GPIO so far. The code also perform PWM and ADC  conversion but I have not done any test to check result.

    Test was performed on Windows 7, CCSv5, Matlab R2010b
    
    Port to new computer is easy, just copy makefile and set xmakefilesetup as appropriate (if you have TI SW already installed). I tested 4 different
    PC so far with XP, Vista and Windows7.
    
    Makefile will generate debug-ready code (option -g). To debug programs import the ".out" file generated in the "_ticcs" directory, connect to
    target C28x and flash it with C28x only target ccxml. If everything goes well you will may debug all source code and TI assembly directly on the
    place.

    SIDE Effects:
    Timer clock on C28x    runs at 75MHz (not 150 as SYSCLKOUT programmed). The clock structure of F28M35 is different and probably the timer clock runs at lower frequency than the core clock (I had not the time to check details). However, this frequency should be copied in the target preference to have a proper code scheduling from matlab.
    
    I found the use of FLASHE (default CMD command) more effective for storing programs than FLASHA (the default one). FLASHE is 32KB wide,
    while FLASHA has less than 8KB available for the code program. Consider to edit it if you wish debug large matlab code (otherwise you may receive
    loading errors).

    
Regards
C.Alberto

PS. My thanks to TI Europe University Program which donated me the boards to performing these tests and to be used in students training programs.

cut Here and save the following as :  <YOUR PATH>:\F28H52.mk

# Copyright March 2012 Carlo Alberto Avizzano
# This Makefile is to integrate and automate building of F28M52 based cores in Matlab
# The makefiles assumes that a Model has been generated for Delfino F28335
# It replaces relevant headers and provide proper inclusion rules

#Targets
#.DEFAULT_GOAL := info
.PHONY : all execute build check clean Diag convert

#####################################################
######        INSTALLATION RELATED SETUP      #######
#####################################################
matlabroot := C:\\Program Files (x86)\\MATLAB\\R2010b\\
C2000      := $(subst \,/,C:\TI\ccsv5\tools\compiler\c2000)
CCS        := $(subst \,/,C:\TI\ccsv5)
CSUITE     := c:/TI/controlSUITE
LOADFILE   := /C/Users/CarloAlberto/user/CCSTargetConfigurations/F288335Concerto.ccxml
LOADM3FILE := /C/Users/CarloAlberto/user/CCSTargetConfigurations/M3Concerto.ccxml
VERSION    := v110
#M3Setup    := $(CSUITE)/


#####################################################
######        MODEL   FILES   SETUP           #######
#####################################################
MODEL_NAME := $(basename $(C2000TGT))
OPT_Head   := $(shell ls DSP28xx*.h)

# Matlab generates a set of files in the working directory
# that need to be compiled together with distribution sources
# Some examples are:
#             rtwtypes.h rtGetNaN.h rtGetInf.h rt_nonfinite.h
#             rt_i32zcfcn.h DSP28xx_SciUtil.h
#            DSP28xx_SciUtil.c MW_c28xx_adc.c MW_c28xx_cap.c MW_c28xx_pwm.c MW_c28xx_qep.c
#             MW_c28xx_board.c MW_c28xx_csl.c rt_i32zcfcn.c rt_nonfinite.c rtGetNaN.c rtGetInf.c
# We got this list automatically from powerful commands of gmake
OPT_SRC    := $(filter-out %.M.c , $(shell ls MW*.c rt*.c))
MODEL_HEAD := $(MODEL_NAME).h $(MODEL_NAME)_types.h $(MODEL_NAME)_private.h  
MODEL_SRC  := $(MODEL_NAME).c $(MODEL_NAME)_data.c $(MODEL_NAME)_main.c


#####################################################
######       FORMATS AND FILE OPTIONS         #######
#####################################################

# Extension to be used in the compilation
# My original intention was to use different extension
# but if you change them then you loose the automatic debug
# capabilities of code composer studio. So that you will not
# anymore able to generate debug projects from matlab generated
# files.

TARGET_EXT := out
OBJ_EXT := obj


#####################################################
######        HOPEFULLY DO NOT TOUCH          #######
#####################################################

MROOTD       := $(matlabroot)
COMPILER     := $(C2000)/bin/cl2000
LINKER       := $(C2000)/bin/cl2000
LOADER       := $(CCS)/ccs_base/scripting/examples/loadti/loadti.bat
RM           := rm -f
CVERSION     := $(CSUITE)/device_support/f28m35x/$(VERSION)
CSUITELIB    := $(CVERSION)/F28M35x_common/source
CINCLUDE     := -I$(CCS)/tools/compiler/C2000/include
CINCLUDE     += -I$(CVERSION)/F28M35x_common/include
CINCLUDE     += -I$(CVERSION)/F28M35x_headers/include
CCFLAGS      ?= -v28 --float_support=FPU32 -qq -g -eo.$(OBJ_EXT) $(CINCLUDE)


# Rules for generating files to compile
LIBCSOURCET     := $(shell ls $(CSUITELIB)/*.c)
LIBCSOURCE      := $(filter-out %/F28M35x_DefaultIsr.c %/F28M35x_PieVect.c,$(LIBCSOURCET))
LIBASMSOURCE    := $(shell ls $(CSUITELIB)/*.asm)
LIBCOBJ_FILES   := $(patsubst %.c, %.$(OBJ_EXT), $(notdir $(LIBCSOURCE)))
LIBASMOBJ_FILES := $(patsubst %.asm, %.$(OBJ_EXT), $(notdir $(LIBASMSOURCE)))
OPT_OBJ         := $(patsubst %.c, %.$(OBJ_EXT), $(notdir $(OPT_SRC)))
MODEL_OBJ       := $(patsubst %.c, %.$(OBJ_EXT), $(notdir $(MODEL_SRC)))

DEVICE_SRC      := $(CVERSION)/F28M35x_headers/source/F28M35x_GlobalVariableDefs.c
DEVICE_OBJ      := $(patsubst %.c, %.$(OBJ_EXT), $(notdir $(DEVICE_SRC)))



#####################################################
######    PERL FILE ALTERING PROCEDURES       #######
#####################################################

# Emulate $ sequence with $($$)
dollar := $$
$(dollar) := $$

# Better if PERL is within your filesystem, but if missing
# matlab provides one within its installation. So we use that one...

PERL       := '$(matlabroot)sys\\perl\\win32\\bin\\perl'
REPLCMD    := $(PERL) -i.bak -pe's/DSP2803x_/F28M35x_/g'

# Why GMAKE requires this conversion is a mistery for me, but it works
PERLMANGLE := $(subst C:,/C, $(subst \\,/, $(PERL)) )

# A bit of Magic to extract compile options from the MAtlab Makefile. This is the template line
# The extraction is a bit fragile and may be unstable if MAthworks changes codegen options
#COMPILER_CODEGEN_ARGS := -I"C:\\Program Files (x86)\\MATLAB\\R2010b\\tool (...) lbox\\rtw\\dspblks\\c" -D"__TICCSC__" -D"RT" -D"USE_RTMODEL" -ml -v28 -D"MODEL=test21" -D"NUMST=2" -D"NCSTATES=0" -D"HAVESTDIO=" -D"ONESTEPFCN=1" -D"TERMFCN=1" -D"MAT_FILE=0" -D"MULTI_INSTANCE_CODE=0" -D"INTEGER_CODE=0" -D"MT=1" -D"TID01EQ=0"
PERLFILT:= 'if (m/COMPILER_CODE.*?(-D(.*))$($$)/g) {print $($$)1}'
MYCFLAGS := $(shell $(PERL)  -ne$(PERLFILT) $(C2000TGT))

#  s/MemCopy/memcpy/g; \

# Multiline define didn't worked with gmake for matlab
# So I had to encode line by line
# Copy of RamfuncsStart can be improved... we keep it as-is so far
MANGLEPROGRAM :=while(<>){ \
  s/DSP2803x_/F28M35x_/g; \
  if ($($$)_ =~ m/(.*)DisableDog(.*)/)  \
   { print "// DisableDog Function not supported $($$)_\n"; \
     printf "memcpy(&RamfuncsRunStart, &RamfuncsLoadStart, (size_t)44);";\
   } \
  elsif ($($$)_ =~ m/SysCtrlRegs\.PCLKCR0\.bit\.ADCENCLK/) \
   { print "// ADCclk already inited by STD sysCtrl.c $($$)_" } \
  elsif ($($$)_ =~ m/Device_cal/) \
   { print "// Device Cal already performed by sysCtrl.c $($$)_" } \
  elsif ($($$)_ =~ m/GP(A|B|C|)PUD/) \
   { print "// Pullup Disable not supported $($$)_" } \
  elsif ($($$)_ =~ m/IntOsc1Sel/) \
   { print "// IntOsc1Sel not required $($$)_" } \
  elsif ($($$)_ =~ m/InitPll/) \
   { print "// InitPll should be done in M3 $($$)_" } \
  elsif ($($$)_ =~ m/GPIO(\d\d)/)  \
   { \
     $($$)v = int($($$)2); \
     if ( (($($$)v>=64)and ($($$)v<=67)) | ($($$)v>=72) ) \
        { print "// GPIO$($$)2 Not Allowed $($$)_" } \
     else \
        { print "$($$)_"; } \
   } \
  else \
   { print "$($$)_"; } \
}


#SOURCE_FILES :=
#$(R2010b\toolbox\idelink\extensions\ticcs\src\DSP2833x_ADC_cal.asm)


MFLAGS := -I"." -I".."
MFLAGS +=-I'$(MROOTD)\\toolbox\\idelink\\extensions\\ticcs\\inc'
MFLAGS +=-I'$(MROOTD)\\extern\\include'
MFLAGS +=-I'$(MROOTD)\\simulink\\include'
MFLAGS +=-I'$(MROOTD)\\rtw\\c\\src'
MFLAGS +=-I'$(MROOTD)\\rtw\\c\\src\\ext_mode\\common'
MFLAGS +=-I'$(MROOTD)\\rtw\\c\\ert'
MFLAGS +=-I'$(MROOTD)\\toolbox\\dspblks\\include'
MFLAGS +=-I'$(MROOTD)\\toolbox\\rtw\\dspblks\\c'
MFLAGS += $(subst ",', $(MYCFLAGS))
#MFLAGS +=-D'__TICCSC__' -D'RT' -D'USE_RTMODEL'
#MFLAGS +=-ml -v28 --float_support=fpu32
#MFLAGS +=-D'MODEL=$(MODEL_NAME)'
#MFLAGS +=-D"NUMST=1"
#MFLAGS +=-D"NCSTATES=0"
#MFLAGS +=-D"HAVESTDIO="
#MFLAGS +=-D"ONESTEPFCN=1"
#MFLAGS +=-D"TERMFCN=1"
#MFLAGS +=-D"MAT_FILE=0"
#MFLAGS +=-D"MULTI_INSTANCE_CODE=0"
#MFLAGS +=-D"INTEGER_CODE=0"
#MFLAGS +=-D"MT=0"
#MFLAGS +=-D"TID01EQ=0"

LDFLAGS := -l$(CCS)/tools/compiler/C2000/lib/rts2800_fpu32.lib
LDFLAGS += -c -x -m"Functions.map"
LDFLAGS += $(CVERSION)/F28M35x_common/cmd/F28M35H52C1_c28.cmd -stack0x200
LDFLAGS += $(CVERSION)/F28M35x_headers/cmd/F28M35x_Headers_nonBIOS.cmd


#####################################################
######        BUILDING     RULES              #######
#####################################################

build: Diag  $(LIBCOBJ_FILES) $(LIBASMOBJ_FILES) $(MODEL_OBJ) $(OPT_OBJ) $(DEVICE_OBJ)
#build: Diag  $(LIBASMOBJ_FILES)
    $(COMPILER) -z -o$(MODEL_NAME).$(TARGET_EXT) $(LDFLAGS) *.$(OBJ_EXT)

Diag: convert Info

Info:
    $(warning 'This is Concerto hook makefile for Matlab - Configuration Follows')
    $(warning MODELNAME: $(MODEL_NAME))
    $(warning CSPATH:    $(CSUITELIB))
    $(warning LIBCFILES: $(LIBCSOURCE))
    $(warning LIBASMFILE:$(LIBASMSOURCE))
    $(warning LIBCOBJ:   $(LIBCOBJ_FILES))
    $(warning LIBASM:    $(LIBASMOBJ_FILES))
    $(warning Compiler:  $(COMPILER))
    $(warning Linker:    $(LINKER))
    $(warning PERLCMD:   $(REPLCMD))
    $(warning Mflags:    $(MFLAGS))
    $(warning PERLFILT:  $(PERLFILT))
    $(warning MYFLAGS:   $(MYFLAGS))
    $(warning 'This is Concerto hook makefile for Matlab')


$(LIBCOBJ_FILES): %.$(OBJ_EXT): $(CSUITELIB)/%.c
    $(info Building File: $@)
    @$(COMPILER) $(CCFLAGS) -c $<
    
$(MODEL_OBJ) $(OPT_OBJ): %.$(OBJ_EXT): %.c
    $(info Building File: $@)
    -$(COMPILER) $(CCFLAGS) $(MFLAGS) -c $<.M.c

$(DEVICE_OBJ) : $(DEVICE_SRC)
    $(info Building File: $@)
    $(COMPILER) $(CCFLAGS) -c $(DEVICE_SRC)


$(LIBASMOBJ_FILES) : %.$(OBJ_EXT): $(CSUITELIB)/%.asm
    $(info Building File: $@ <= $<)
    @$(COMPILER) $(CCFLAGS) -c $<

convert:
    $(shell echo '$(MANGLEPROGRAM)' > mymangle.pl )
    $(foreach file, $(MODEL_SRC), $(shell $(PERLMANGLE) mymangle.pl $(file) >$(file).M.c ))
    $(foreach file, $(MODEL_HEAD), $(shell $(REPLCMD) $(file)))
    $(foreach file, $(OPT_SRC), $(shell $(PERLMANGLE) mymangle.pl $(file) >$(file).M.c ))
    $(foreach file, $(OPT_Head), $(shell $(REPLCMD) $(file)))

execute : Info
    $(info "Loading file on the target")
    $(info using the loadfile: $(LOADFILE))
    cmd /S/C "$(LOADER)" -a -c="$(LOADFILE)" $(MODEL_NAME).$(TARGET_EXT)

defaultM3:
    $(info "Loading file on the M3 Core the default file")
    $(info using the example: $(LOADM3FILE))
    $(info using the example: $(M3Setup))
    cmd /S/C "$(LOADER)" -a -c="$(LOADFILE)" $(MODEL_NAME).$(TARGET_EXT)

clean :
    -$(RM) $(LIBCOBJ_FILES)
    -$(RM) $(LIBASMOBJ_FILES)
    -$(RM) $(TARGET)

#Code Generation Files