=== Code generation process ===[code_generation_process]
-
+%tex% ''' \begin{figure}[H]\advance\leftskip-1cm
+[530-tlc_process.png]
+%tex% ''' \caption{TLC code generation process.}\end{figure}
== Repository branch description ==[repository_branch_description]
+-> ``rpp_setup.m``
+
+RPP Target install script.
+
+This script will, among other things, ask the user to provide the location of the armcl parent directory,
+infer and save some relevant CCS paths, add paths to Matlab path and build S-Function blocks for
+user's architecture (using Matlab's mex command line tool).
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1137.
+
+
+-> ``rpp.tlc``
+
+Embedded real-time system target file for RPP.
+
+This file is the system target file (STF), or target manifest file. Functions of the STF include:
+
+- Making the target visible in the System Target File Browser.
+- Definition of code generation options for the target (inherited and target-specific).
+- Providing an entry point for the top-level control of the TLC code generation process.
+
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1129 and __1144__.
+
+
+-> ``rpp.tmf``
+
+Embedded Coder Template Makefile.
+
+This is just standard Embedded Coder Template Makefile, provided by Matlab. It was slightly modified to
+support ``armcl`` particularities and added template rules for assembler files (which were included by the
+``rpp_lib_support.m`` script, but is no longer the case).
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1130 and __1183__.
+
+
+-> ``rpp_download.m``
+
+Code download utility for Simulink RPP Target.
+
+This function is optionally executed at the end of the build process if it is successful and the user selected
+//Download compiled binary to RPP// option on the build configuration panel. This function calls ``loadti.sh``
+script with the generated binary and using configuration for the XDS100v2 JTAG Emulators. The board should be
+powered and correctly wired. See [Development wiring #development_wiring].
+
+
+NEWPAGE
+-> ``rpp_file_process.tlc``
+
+Code generation custom file processing template.
+
+This file should decide which //main// to generate according to configuration, in particular which mode, Single
+Tasking or Multitasking, is chosen. The RPP Target ignores this settings because it uses a tasking system based
+on tasking features provided by FreeRTOS. In consequence is only a wrapper to the //Single Tasking// main, which
+clearly is not for single tasking.
+
+- __Reference:__
+ - ``<repo>/refs/ecoder_ug.pdf`` p. 556.
+ - ``<repo>/refs/ecoder_ref.pdf`` p. 1347.
+
+
+-> ``rpp_lib_support.m``
+
+**DEPRECATED**. Simulink support for RPP library and operating system setup.
+
+This files used to add the source code from the RPP library and operating to the build. This is no longer required
+when using the static library. This is left for future reference in case new source code needs to be included to
+the build.
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1058.
+ - ``<repo>/refs/rtw_ref.pdf`` p. 56.
+-> ``rpp_make_rtw_hook.m``
+
+Build process hooks file.
+
+This file is hook file that invoke target-specific functions or executables at specified points in the build process.
+In particular, this file handle the copying of required files before the compilation stage.
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1066-1072 and 1131.
+
+
+-> ``rpp_select_callback_handler.m``
+
+RPP Target select callback handler.
+
+This callback function is triggered whenever the user selects the target in the System Target File Browser. Default
+values for Simulation and configurations parameters are set. Some options are disabled if it is not allowed to be
+changed by user.
+
+- __Reference:__
+ - ``<repo>/refs/rtw_ug.pdf`` p. 1211.
+
+
+NEWPAGE
+-> ``rpp_srmain.tlc``
+
+Custom file processing to generate a //main// file.
+
+This file generated the //main// file for the RPP target on top of the RPP library and the FreeRTOS operating system.
+The ``sr`` prefix is standard to mark Single Tasking main, which is not the case. See ``rpp_file_process.m`` description
+above for more information about this.
+
+- __Reference:__
+ - Example in ``<matlab>/rtw/c/tlc/mw/bareboard_srmain.tlc``.
+
+
+-> ``target_tools.mk``
+
+Makefile for CCS (``armcl``) toolchain support.
+
+This file set variables to CCS tools to support build for this toolchain. This file is included by ``rpp.tmf`` before
+declaring the rules for source code.
+
+- __Reference:__
+ - "Include a tool specification settings" comment block in ``rpp.tmf``.
+ - Compiler options documentation available in ``armcl.pdf``.
+
+
+NEWPAGE
+
== Installation procedure ==[installation_procedure]
**1) Download and install CCS for Linux:**
[400-simulink_solver.png]
NEWPAGE
- Diagnostics - Sample Time:
- - Disable warning source block specifies -1 sampling time. It's for the source blocks to run once per tick. @@
+ - Disable warning source block specifies -1 sampling time. It's ok for the source blocks to run once per tick. @@
[400-simulink_diagnostics.png]
- Code generation:
- Set to ``rpp.tlc``. @@
[400-simulink_code.png]
+Note: Single Tasking is the only currently supported mode. If multitasking is required to be implemented in the
+ future create a new file ``rpp_mrmain.tlc`` in ``<repo>/rpp/rpp/`` and edit ``rpp_file_process.tlc`` to use
+ that file instead when multitasking is selected.
+
+
=== RPP Target options ===[rpp_target_options]
+The RPP Target include the following configuration options, all of them configurable per model under
+``Code Generation`` -> ``RPP Options``:
+
+- **C system stack size**: this parameter is passed directly to the linker for the allocation of the stack.
+ Note that this is the stack for the application when running outside a FreeRTOS task, normally before
+ the scheduler has started and for system routines. Default value is 4096.
+- **C system heap size**: this parameter is passed directly to the linker for the allocation of the heap.
+ See [Appendix A: Notes on FreeRTOS memory management #appendix_a_notes_on_freertos_memory_management]
+ for an important overview of memory management and why this parameter is one of the most important in
+ memory management.
+- **Model step task stack size**: this parameter will be passed to the ``xTaskCreate()`` that creates the
+ task for the model to run. In a Simulink model there is always two tasks:
+ - The worker task. This task is the one that executes the model step. This task requires enough stack
+ memory to execute the step. Take into account for example than only a single call to
+ ``rpp_sci_printf()`` requires, with current configuration, 128 bytes from the stack. This value should
+ be minor than the C system heap and leaving enough heap for the system tasks.
+ See [Appendix A: Notes on FreeRTOS memory management #appendix_a_notes_on_freertos_memory_management]
+ for more information.
+ - The control task. This task controls when the worker task should execute and controls overruns.
+- **Download compiled binary to RPP**: if set, this option will download the generated binary to the board after
+ the model is successfully built. Note that this option is unaware of the option //Generate code only// in
+ the //Code Generation// options panel, so it will try to upload even if only source code has being generated,
+ failing graciously or uploading an old binary laying around in the build directory. This option calls the
+ ``rpp_download.m`` script, which is in turn a wrapper on the ``loadti.sh`` script. More information on the
+ ``loadti.sh`` script can be found in:
+```
+<css>/ccs_base/scripting/examples/loadti/readme.txt
+http://processors.wiki.ti.com/index.php/Loadti
+```
+ The ``loadti.sh`` script will close after the download of the generated program and in consequence the execution
+ of the loaded program will stop (because it work as the CCS debug server). In order to test the loaded model a
+ manual reset of the board is always required after a successful download.
+- **Print model metadata to SCI at start**: if set this option will print a message to the Serial Communication
+ Interface when the model start execution on the board. This is very helpful to identify the model running on the
+ board. The message is in the form:
+```
+`model_name' - generated_date (TLC tlc_version)
+```
+ For example:
+```
+`hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
+```
+NEWPAGE
= RPP Library and API =[rpp_library_and_api]
repetitive. Move it the header files.
- The HAL layer currently two elements:
- CPU and chips abstractions. This should stay.
- - Command descriptor. This is remaining elements from the testing applications and should be moved to
+ - Command descriptors. This is remaining elements from the testing applications and should be moved to
application layer.
0 0 0 0 0 0 0 0 0 0 0 0
```
-Status: **PASSED**.
+Status: **PASSED** for channels 1-5. 6-12 remain untested but they //should// work.
=== AOUT test description ===[aout_test_description]
NEWPAGE
-= Appendix A: Notes on FreeRTOS memory managment =[appendix_a_notes_on_freertos_memory_managment]
+= Appendix A: Notes on FreeRTOS memory management =[appendix_a_notes_on_freertos_memory_management]
Write about heap implementation, FreeRTOSConfig.h heap size, C heap size, C stack size, Simulink memory, among others.
projects / jenkicar / rpp-simulink.git / commitdiff
