rpp/rpp/README.txt

   1 #####################################
   2 # Simulink Target for RPP           #
   3 #####################################
   4
   5
   6 This library provides support for C source code generation from Simulink models
   7 and compilation of that code on top of the RPP library and the FreeRTOS
   8 operating system. This library uses Texas Instrument ARM compiler (armcl)
   9 included in the Code Generation Tools available with Code Composer Studio, and
  10 thus it depends on it for proper functioning.
  11 This library also provides support for automatically download the compiled
  12 machine code to the RPP board.
  13
  14 How to install RPP Target support:
  15
  16 1) Get the repository (omit this if you're reading this from the README.txt file
  17    in the repository). From a shell:
  18
  19     git clone ssh://git@rtime.felk.cvut.cz/jenkicar/rpp-simulink.git
  20
  21 This is a private server, you require your SSH private key to be authorized.
  22 For access please consult the Real-Time Systems Group, Department of Control
  23 Engineering, Faculty of Electrical Engineering, Czech Technical University in
  24 Prague. For details about this git server consult:
  25
  26     http://rtime.felk.cvut.cz/hw/index.php/Git_repository_on_this_server
  27
  28
  29 2) Install Code Composer Studio.
  30
  31 Install Code Composer Studio (CCS) from the following URL:
  32
  33     http://processors.wiki.ti.com/index.php/Category:Code_Composer_Studio_v5
  34
  35 CCS GUI is not used, this target relies on the ARM Compiler and Linker
  36 (<ccs>/tools/compiler/arm_5.X.X/bin/armcl) and the Debug Server Scripting (DSS)
  37 Generic Loader (<ccs>/ccs_base/scripting/examples/loadti/loadti.sh) command line
  38 tools.
  39 Please note that all the development was done in a Ubuntu 12.04 LTS GNU/Linux
  40 machine using the CCS Linux version.
  41
  42     armcl reference documentation:
  43         <repo>/refs/armcl.pdf, also available on
  44         http://processors.wiki.ti.com/index.php/TI_Compiler_Information#Compiler_Manuals
  45
  46     loadti.sh reference documentation:
  47         <css>/ccs_base/scripting/examples/loadti/readme.txt
  48         http://processors.wiki.ti.com/index.php/Loadti
  49
  50 Notes on installing Code Composer Studio on Ubuntu 64bits:
  51
  52     After installation the application can be run with:
  53
  54         cd <ccs>/ccsv5/eclipse/
  55         ./ccstudio
  56
  57     If the application fails to start is because CCS5 is a 32bits application a
  58     thus requires 32bits libraries:
  59
  60         sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
  61
  62     If the application crashes with a segmentation fault do:
  63
  64         Edit <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<your version number>/plugin_customization.ini
  65         And change key org.eclipse.ui/showIntro to false.
  66
  67     Choose "FREE License - for use with XDS100 JTAG Emulators" on the licensing
  68     options. This target is configured to download to the board using this
  69     particular hardware.
  70
  71     You may create a symbolic link and a desktop entry:
  72
  73         sudo ln -s <ccs>/ccsv5/eclipse/ccstudio /usr/local/bin/ccstudio
  74
  75     And put in ~/.local/share/applications/ccs5.desktop
  76
  77         [Desktop Entry]
  78         Version=1.0
  79         Type=Application
  80         Terminal=false
  81         Exec=ccstudio
  82         Name=Code Composer Studio
  83         Icon=/usr/local/ti/ccsv5/eclipse/icon.xpm
  84
  85
  86 3) Install RPP Target:
  87
  88     Open Matlab and type on command window:
  89
  90         cd <repo>/rpp/rpp/
  91         rpp_setup()
  92
  93     This will launch the RPP setup script. This script will ask the user to
  94     provide the path to the CCS compiler root directory (the directory where
  95     armcl is located), normally:
  96
  97         <ccs>/tools/compiler/arm_5.X.X/
  98
  99     Find a more detailed description of what this script does in the section
 100     below.
 101
 102
 103 4) Create a new model or load a demo.
 104
 105     Demos are located on <repo>/rpp/demo or you can start a new model and
 106     configure target to RPP.
 107
 108
 109
 110 Library file layout:
 111
 112     -> rpp_setup.m
 113
 114         RPP Target install script.
 115
 116         This script will, among other things, ask the user to provide the
 117         location of the armcl parent directory, infer and save some relevant
 118         CCS paths, add paths to Matlab path and build S-Function blocks for
 119         user's architecture (using Matlab's mex command line tool).
 120
 121         Reference:
 122             <repo>/refs/rtw_ug.pdf p. 1137
 123
 124
 125     -> rpp.tlc
 126
 127         Embedded real-time system target file for RPP.
 128
 129         This file is the system target file (STF), or target manifest file.
 130         Functions of the STF include:
 131
 132             - Making the target visible in the System Target File Browser.
 133             - Definition of code generation options for the target (inherited
 134               and target-specific).
 135             - Providing an entry point for the top-level control of the TLC code
 136               generation process.
 137
 138         Reference:
 139             <repo>/refs/rtw_ug.pdf p. 1129 and _1144_
 140
 141
 142     -> rpp.tmf
 143
 144         Embedded Coder Template Makefile.
 145
 146         This is just standard Embedded Coder Template Makefile, provided by
 147         Matlab. It was slightly modified  to support armcl particularities and
 148         added template rules for assembler files (which were included by the
 149         rpp_lib_support.m, but is no longer the case).
 150
 151         Reference:
 152             <repo>/refs/rtw_ug.pdf p. 1130 and _1183_
 153
 154
 155     -> rpp_download.m
 156
 157         Code download utility for Simulink RPP Target.
 158
 159         This function is optionally executed at the end of the build process
 160         if it is successful and the user selected "Download compiled binary to
 161         RPP" option on the build configuration panel. This function calls
 162         loadti.sh script with the generated binary and using configuration for
 163         the XDS100v2 JTAG Emulators. The board should be powered and correctly
 164         wired. See "Wiring the RPP board for programming" on the main
 165         documentation files.
 166
 167         Reference:
 168             Readme file in <css>/ccs_base/scripting/examples/loadti/readme.txt
 169             loadti utility wiki at http://processors.wiki.ti.com/index.php/Loadti
 170
 171
 172     -> rpp_file_process.tlc
 173
 174         Code generation custom file processing template.
 175
 176         This file should decide which "main" to generate according to
 177         configuration, in particular which mode, Single Tasking or Multitasking,
 178         is chosen. The RPP Target ignores this settings because it uses a
 179         tasking system based on tasking features provided by FreeRTOS. In
 180         consequence is only a wrapper to the "Single Tasking" main, which
 181         clearly is not for single tasking.
 182
 183         Reference:
 184             <repo>/refs/ecoder_ug.pdf p. 556
 185             <repo>/refs/ecoder_ref.pdf p. 1347
 186
 187
 188     -> rpp_lib_support.m
 189
 190         DEPRECATED. Simulink support for RPP library and operating system setup.
 191
 192         This files used to add the source code from the RPP library and
 193         operating to the build. This is no longer required when using the static
 194         library. This is left for future reference in case new source code needs
 195         to be included to the build.
 196
 197         Reference:
 198             <repo>/refs/rtw_ug.pdf p. 1058
 199             <repo>/refs/rtw_ref.pdf p. 56
 200
 201
 202     -> rpp_make_rtw_hook.m
 203
 204         Build process hooks file.
 205
 206         This file is hook file that invoke target-specific functions or
 207         executables at specified points in the build process. In particular,
 208         this file handle the copying of required files before the compilation
 209         stage.
 210
 211         Reference:
 212             <repo>/refs/rtw_ug.pdf p. 1066-1072 and 1131
 213
 214
 215     -> rpp_select_callback_handler.m
 216
 217         RPP Target select callback handler.
 218
 219         This callback function is triggered whenever the user selects the target
 220         in the System Target File Browser. Default values for Simulation and
 221         configurations parameters are set. Some options are disabled if it is
 222         not allowed to be changed by user.
 223
 224         Reference:
 225             <repo>/refs/rtw_ug.pdf p. 1211
 226
 227
 228     -> rpp_srmain.tlc
 229
 230         Custom file processing to generate a "main" file.
 231
 232         This file generated the "main" file for the RPP target on top of the RPP
 233         library and the FreeRTOS operating system. The "sr" is standard to mark
 234         Single Tasking main, which is not the case. See rpp_file_process.m
 235         description above for more information about this.
 236
 237         Reference:
 238             Example in <matlab>/rtw/c/tlc/mw/bareboard_srmain.tlc
 239
 240
 241     -> target_tools.mk
 242
 243         Makefile for CCS (armcl) toolchain support.
 244
 245         This file set variables to CCS tools to support build for this toolchain.
 246         This file is included by rpp.tmf before declaring the rules for source
 247         code.
 248
 249         Reference:
 250             "Include a tool specification settings" comment block in rpp.tmf
 251             Compiler options documentation available in armcl.pdf
 252