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 to support armcl particularities and added
 148         template rules for assembler files, which are included by the
 149         rpp_lib_support.m function to provide support for the OS and RPP
 150         library.
 151
 152         Reference:
 153             <repo>/refs/rtw_ug.pdf p. 1130 and _1183_
 154
 155
 156     -> rpp_download.m
 157
 158         Code download utility for Simulink RPP Target.
 159
 160         This function is optionally executed at the end of the build process
 161         if it is successful and the user selected "Download compiled binary to
 162         RPP" option on the build configuration panel. This function calls
 163         loadti.sh script with the generated binary and using configuration for
 164         the XDS100v2 JTAG Emulators. The board should be powered and correctly
 165         wired. See "Wiring the RPP board for programming" on the main
 166         documentation files.
 167
 168         Reference:
 169             Readme file in <css>/ccs_base/scripting/examples/loadti/readme.txt
 170             loadti utility wiki at http://processors.wiki.ti.com/index.php/Loadti
 171
 172
 173     -> rpp_file_process.tlc
 174
 175         Code generation custom file processing template.
 176
 177         This file should decide which "main" to generate according to
 178         configuration, in particular which mode, Single Tasking or Multitasking,
 179         is chosen. The RPP Target ignores this settings because it uses a
 180         tasking system based on tasking features provided by FreeRTOS. In
 181         consequence is only a wrapper to the "Single Tasking" main, which
 182         clearly is not for single tasking.
 183
 184         Reference:
 185             <repo>/refs/ecoder_ug.pdf p. 556
 186             <repo>/refs/ecoder_ref.pdf p. 1347
 187
 188
 189     -> rpp_lib_support.m
 190
 191         Simulink support for RPP library and operating system setup.
 192
 193         This file adds the source code from the RPP library and operating
 194         to the build.
 195
 196         Reference:
 197             <repo>/refs/rtw_ug.pdf p. 1058
 198             <repo>/refs/rtw_ref.pdf p. 56
 199             Readme file in <repo>/rpp/lib/rpp/doc/os.txt
 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