1 \newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
2 \newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
4 \documentclass{article}
6 \usepackage{graphicx} % images and graphics
7 \usepackage{paralist} % needed for compact lists
8 \usepackage[normalem]{ulem} % needed by strike
9 \usepackage{listings} % required for code blocks
10 \usepackage[urlcolor=blue,colorlinks=true,hyperfootnotes=false]{hyperref} % links
11 \usepackage[utf8]{inputenc} % char encoding
12 \usepackage[bottom]{footmisc} % footnotes
15 \usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
16 \usepackage{float} % To fix images position
18 % Prettify code documentation
20 \definecolor{gray97}{gray}{.97}
21 \definecolor{gray75}{gray}{.75}
22 \definecolor{gray45}{gray}{.45}
27 framexbottommargin=3pt,
28 framexleftmargin=0.4cm,
31 backgroundcolor=\color{gray97},
32 rulesepcolor=\color{black},
34 stringstyle=\ttfamily,
35 showstringspaces = false,
36 basicstyle=\small\ttfamily,
37 commentstyle=\color{gray45},
38 keywordstyle=\bfseries,
43 numberfirstline = false,
49 \addtolength{\parskip}{\baselineskip} % Paragraph spacing
50 \linespread{1.15} % Lines spacing
51 \setlength{\plitemsep}{0.5\baselineskip} % List items spacing
52 \definecolor{deepblue}{RGB}{0,0,61}
53 \hypersetup{linkcolor=deepblue,}
55 % Table of content depth
56 \setcounter{tocdepth}{4}
60 \usepackage{pdflscape}
63 \usepackage{changepage}
67 % \renewcommand{\familydefault}{\sfdefault}
77 \newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
82 % Upper part of the page
83 \includegraphics[width=0.70\textwidth]{media/images/logos.png}\\[1cm]
84 \textsc{\LARGE Costa Rica Institute of Technology}\\[0.5cm]
85 \textsc{\LARGE Czech Technical University in Prague}\\[1.5cm]
86 \textsc{\Large Undergraduate project}\\[0.5cm]
91 { \huge \bfseries Code generation for automotive rapid prototyping platform using Matlab/Simulink}\\[0.4cm]
97 Carlos \textsc{Jenkins}\\
116 \hypertarget{introduction}{}
117 \section{Introduction}
119 This document describes the final results of the project ``Code generation for automotive rapid
120 prototyping platform using Matlab/Simulink".
122 \hypertarget{background}{}
123 \subsection{Background}
125 Back in the beginning of 2012 a leading automotive company requested the Czech Technical University
126 to develop a Engine Control Unit (ECU) for automotive applications. Real-Time Systems group at the
127 Department of Control Engineering from the Faculty of Electrical Engineering developed a hardware
128 and Software platform to the needs of this industry. The hardware uses Texas Instruments
129 TMS570LS3137 CPU and is built with automotive standards and interfaces in mind. It uses a real-time
130 operating system and was directly programmed in C.
132 Nevertheless, in accordance to company policies the Software developed for the engine control unit
133 must be designed in a safe and auditable way. The company has the policy to implement the Software
134 for their system using Model-Based Design:
137 Model-Based Design (MBD) is a mathematical and visual method of addressing
138 problems associated with designing complex control, signal processing and
139 communication systems. It is used in many motion control, industrial equipment,
140 aerospace, and automotive applications. Model-based design is a methodology
141 applied in designing embedded software.
144 In order to meet this requirement an interaction layer between the platform and the Software the
145 company uses, Matlab/Simulink, must be implemented. This document describes the implementation of
146 this interaction system.
148 \hypertarget{technologies_involved}{}
149 \subsection{Technologies involved}
152 \item Matlab/Simulink data flow graphical programming language tool for modeling, simulating and
153 analyzing multidomain dynamic systems.
154 \item Standard ANSI C programming.
155 \item FreeRTOS real-time operating system.
156 \item Texas Instruments TI Code Generation Tools (CGT).
157 \item RPP in-house automotive hardware board using Texas Instruments TMS570LS3137 CPU.
162 \hypertarget{objectives}{}
163 \subsection{Objectives}
165 Main objectives of this project are:
168 \item Allow C code generation from Matlab/Simulink models for custom made hardware platform.
169 \item Implement model blocks for some of the peripheral units of the board for use in Simulink
173 At the time of this writing the objectives of this project are considered successfully achieved.
175 \hypertarget{benefits}{}
176 \subsection{Benefits}
178 Expected benefits of this project are:
181 \item Enabling faster implementation and rapid-prototyping of Software components through the use of
182 model-based programming.
183 \item Enabling better and clearer visualization of Software implementations for the hardware board
185 \item Improve auditability of Software system for automotive applications.
188 At the time of this writing the benefits of this project are considered enabled.
190 \hypertarget{final_outcome}{}
191 \subsection{Final outcome}
193 The main products generated for this project are:
196 \item \textbf{C Support Library}: \newline{}
197 Define the API to communicate with the board. Include drivers and operating system.
199 \item \textbf{Simulink Coder Target}: \newline{}
200 Allows Simulink model's code generation, compilation and download for the board.
202 \item \textbf{Simulink Block Library}: \newline{}
203 Set of blocks that allows Simulink models to use board IO and communication peripherals.
205 \item \textbf{Simulink Demos Library}: \newline{}
206 Collection of examples of control applications in form of Simulink models.
209 Each of this product is described deeply in the following sections.
213 \hypertarget{document_layout}{}
214 \subsection{Document layout}
216 The general layout of this document is as follows:
219 \item Project description, objectives and outcome. This section.
220 \item Software and Hardware setup for development, repository layout and programming standards.
221 \item A section for each of the four products delivered, with:
223 \item Implementation fundamentals.
224 \item Repository branch description.
225 \item Product specific aspects.
226 \item Reference documentation.
235 \hypertarget{project_setup}{}
236 \section{Project setup}
238 This sections describes the Software and Hardware aspects required to undertake development for
239 this project. It considers:
242 \item Software development environment.
243 \item Hardware reference documentation and wiring for development.
244 \item Repository's general layout.
247 \hypertarget{development_environment}{}
248 \subsection{Development environment}
250 This section describes the Software environment setup for development.
252 \hypertarget{operating_system}{}
253 \subsubsection{Operating system}
255 This project was developed on a GNU/Linux operating system. For development it is recommended to
256 use a Debian based operating system for development as most of the tools are easily available from
259 Relevant OS information on which this project was developed:
262 \item Ubuntu 12.04.2 LTS AMD64.
263 \item Kernel 3.2.0-48-generic.
264 \item GCC version 4.6.3.
267 No test for cross-platform interoperability was performed on the code developed. Although care was
268 taken to try to provide platform independent code and tools there is elements known to be Linux
269 dependent. For a list of this elements refer to
270 \htmladdnormallink{Appendix B: Known operating-system dependent files}{\#appendix\_b\_known\_operating\_system\_dependent\_files}.
272 \hypertarget{version_control_system}{}
273 \subsubsection{Version Control System}
275 The version control system used for this project is \textbf{git}. The repository of this project
276 contains all the files produced during development, including documentation, references, code and
277 graphics. Also, the GUI application \textbf{giggle} was used to easily review changes. To install both
278 execute on a terminal:
280 \lstset{language=bash}
282 sudo apt-get install git giggle
287 \hypertarget{ti_code_composer_studio}{}
288 \subsubsection{TI Code Composer Studio}
290 Code Composer Studio (CCS) is the official Integrated Development Environment (IDE) for developing
291 applications for Texas Instruments embedded processors. CCS is multiplatform Software based on
292 Eclipse Open Source IDE.
294 The version used in this project is the 5.3.0. Download and install CCS for Linux from:
297 \htmladdnormallink{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
300 CCS download requires a valid MyTI account. Tedious. CCS download is about 1.5GB. Once downloaded
301 extract the content of the \texttt{tar.gz} archiver and run \texttt{css\_setup\_$<$version$>$.bin} script as
302 \underline{root}. Installation must done as root in order to install driver set.
304 After installation the application can be executed with:
306 \lstset{language=bash}
308 cd <ccs>/ccsv5/eclipse/
312 If the application fails to start on 64bits systems is because CCS5 is a 32bits application a thus
313 requires 32bits libraries:
315 \lstset{language=bash}
317 sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
320 If the application crashes with a segmentation fault edit file:
322 \lstset{language=bash}
324 nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
327 And change key \texttt{org.eclipse.ui/showIntro} to false.
329 Choose ``FREE License - for use with XDS100 JTAG Emulators" on the licensing options. Code download
330 for the board is uses that particular hardware. See \htmladdnormallink{Development wiring}{\#development\_wiring} for
331 more details on this hardware.
333 CCS include Texas Instruments Code Generation Tools (CGT) (compiler, linker, etc). Simulink code
334 generation requires the CGT to be available in the system, and thus, even if no library development
335 will be done or the IDE is not going to be used CCS is still required. \newline{}
336 See \texttt{$<$repo$>$/rpp/rpp/README.txt} file for more information.
338 You can find documentation for CGT compiler in \texttt{$<$repo$>$/ref/armcl.pdf} and for CGT archiver in
339 \texttt{$<$repo$>$/ref/armar.pdf}.
341 \hypertarget{matlabsimulink}{}
342 \subsubsection{Matlab/Simulink}
344 Matlab/Simulink version used is R2012b for Linux 64 bits. For in-house development the CVUT should
345 provide a network licensing server descriptor file.
347 \hypertarget{gtkterm}{}
348 \subsubsection{GtkTerm}
350 Most of the interaction with the board for development is done through a RS-232 serial connection.
351 The terminal Software used for communication is called GtkTerm.
353 The default configuration for the board serial communication module is 9600-8-N-1. Note that the
354 RPP Library test suite is setup to 115200-8-N-1.
356 To install GtkTerm execute:
358 \lstset{language=bash}
360 sudo apt-get install gtkterm
363 \hypertarget{doxygen}{}
364 \subsubsection{Doxygen}
366 Doxygen is the name of the documentation generator used to generate the RPP API documentation based
367 on the source code files. The generated API include dependency graphs and thus it also requires
368 Graphviz, a graph drawing tool. To install both execute:
370 \lstset{language=bash}
372 sudo apt-get install doxygen graphviz
375 See \htmladdnormallink{API generation}{\#api\_generation} on how to use Doxygen to generate the API Reference
380 \hypertarget{nested}{}
381 \subsubsection{Nested}
383 Nested is the documentation editor used to create the document you're reading. It features a plain
384 text version control friendly simple to read non-cluttered format, WYSIWYM paradigm, divide and
385 conquer document creation approach, a nested (non-linear) document tree and content/presentation
386 separation scheme and thus documents can be published to LaTeX, PDF or HTML. Nested is a tool
387 created by the author of this report.
389 To install Nested first install dependencies:
391 \lstset{language=bash}
393 sudo apt-get install python2.7 python-gtk2 python-webkit python-gtkspellcheck texlive-publishers texlive texlive-latex-extra rubber iso-codes subversion
396 Then get the latest revision from the stable repository:
398 \lstset{language=bash}
400 svn checkout svn://svn.code.sf.net/p/nestededitor/code/trunk nested
405 \lstset{language=bash}
411 Nested sources for this document can be found on the repository under
412 \texttt{$<$repo$>$/doc/reports/report/}.
417 The LMC1 is a simple script developed for this project written in Python 3 using Gtk+ 3.0 Python
418 dynamic bindings PyGObject. This script, based on Michal Horn's command line script, allows to set
419 or clear the outputs of the test board.
421 This script includes both a GUI and command line tool. If no parameters are given to the script the
422 GUI version is launched:
424 \begin{figure}[H]\begin{center}
426 \noindent\includegraphics[width=350px]{media/images/lmc1.png}
427 \caption{LMC1 GUI application.}\end{center}\end{figure}
429 To run the LMC1 application first install dependencies:
431 \lstset{language=bash}
433 apt-get install python3 python3-gi python3-serial
436 To launch LMC1 GUI version double click file:
438 \texttt{$<$repo$>$/rpp/lib/apps/lmc1/lmc1.py}
440 To launch LMC1 command line version type:
442 \texttt{$<$repo$>$/rpp/lib/apps/lmc1/lmc1.py --help}
446 \hypertarget{hardware_reference}{}
447 \subsection{Hardware reference}
449 This section provides reference documentation for the RPP board:
452 \item Connectors pinout.
453 \item Modules capabilities and features.
454 \item Wiring configuration for development and testing.
457 Please note that although this is a hardware reference documentation this is from a Software
458 development perspective and \underline{\textbf{NOT}} Hardware development perspective. For full hardware details
459 please refer to schematics and related documentation.
461 \begin{figure}[H]\begin{center}
463 \noindent\includegraphics[width=300px]{media/images/board.png}
464 \caption{The RPP board (signal connector missing).}\end{center}\end{figure}
466 \hypertarget{connectors_pinout}{}
467 \subsubsection{Connectors pinout}
469 \begin{figure}[H]\advance\leftskip-1cm
471 \noindent\includegraphics[width=530px]{media/images/pinout.pdf}
472 \caption{The RPP connectors pinout.}\end{figure}
474 \hypertarget{modules_description}{}
475 \subsubsection{Modules description}
477 This section enumerates the capabilities of the hardware modules from Software perspective.
479 \hypertarget{logic_io}{}
480 \paragraph{Logic IO}\textnormal{\\}
482 \hypertarget{digital_inputs_din}{}
483 \subparagraph{Digital Inputs (DIN)}\textnormal{\\}
486 \item 16 pins available on Signal Connector.
487 \item Pins 9-16 status can be read via GPIO using configurable threshold. \newline{}
488 Pins 9-12 use variable threshold B and pins 13-16 use variable threshold A.
489 \item Variable threshold is a DAC chip MCP4922.
490 \item All pins are read at once via SPI (fixed threshold) using chip MC33972.
491 \item 1-8 are programmable pins and ca be set to pull-up or pull-down. 9-16 are pull-down only.
492 \item All pins can be set to be active or tri-stated.
493 \item All pins can be set to trigger interrupt.
494 \item On-line diagnostic of broken wire.
497 \hypertarget{digital_outputs_lout}{}
498 \subparagraph{Digital Outputs (LOUT)}\textnormal{\\}
501 \item 8 pins available on Signal Connector.
502 \item Pins for logic output only, up to 100mA.
503 \item All pins are set at once using a chip through SPI.
506 \hypertarget{analog_input_ain}{}
507 \subparagraph{Analog Input (AIN)}\textnormal{\\}
510 \item 12 channels available.
511 \item Differential inputs, thus 24 pins available on Signal Connector.
512 \item Range for 0-20 volts.
513 \item 12 bits resolution.
517 \hypertarget{analog_output_aout}{}
518 \subparagraph{Analog Output (AOUT)}\textnormal{\\}
521 \item 4 pins available on Signal Connector.
522 \item Output range is 0-12 volts.
523 \item Using 2 x MCP4922 DACs controlled using SPI.
524 \item Resolution is 12 bits. But because of amplification and voltage reference not all range is used.
527 \hypertarget{power_output}{}
528 \paragraph{Power Output}\textnormal{\\}
530 \hypertarget{h_bridge_hbr}{}
531 \subparagraph{H-Bridge (HBR)}\textnormal{\\}
534 \item 1 port (2 pins) available on Power Connector.
535 \item Communication is done through SPI.
536 \item H-Bridge can be enabled or disabled.
537 \item Current direction can be set.
538 \item PWM control with 1\% resolution change of the duty cycle.
539 \item Port can drive load up to 10A.
542 \hypertarget{power_output_mout}{}
543 \subparagraph{Power Output (MOUT)}\textnormal{\\}
546 \item 6 pins available on Power Connector.
547 \item Pins can drive a load up to 2A. Push/Pull.
548 \item Pins are set using 6 CPU output GPIOs. Diagnostic are read using 6 externally pulled-up
549 open-drain input GPIOs.
550 \item On-line diagnostics. Driver chip will pull-down the corresponding diagnostic pin on the CPU.
553 \hypertarget{high_power_output_hout}{}
554 \subparagraph{High-Power Output (HOUT)}\textnormal{\\}
557 \item 6 pins available on Power Connector.
558 \item Pins can be set ON/OFF.
559 \item Pins can drive a load up to 10A with PWM.
560 \item System can read analog values of current flowing (IFBK).
561 \item System can read diagnostics values (DIAG). Detection of a fault condition.
564 \hypertarget{communication}{}
565 \paragraph{Communication}\textnormal{\\}
567 \hypertarget{can_bus_can}{}
568 \subparagraph{CAN bus (CAN)}\textnormal{\\}
571 \item 3 ports available (CAN uses differential signaling) thus 6 pins are available on Communication
574 \item Recover from error.
575 \item Detection of network errors.
578 \hypertarget{local_interconnect_network_lin}{}
579 \subparagraph{Local Interconnect Network (LIN)}\textnormal{\\}
582 \item 2 ports/pins available on Communication Connector.
583 \item Only first port can be used when using the SCI. Second port us shared with SCI.
586 \hypertarget{flexray_fr}{}
587 \subparagraph{FlexRay (FR)}\textnormal{\\}
590 \item 2 ports available. FlexRay uses differential signaling thus 4 pins are available on
591 Communication Connector.
594 \hypertarget{serial_comm_interface_sci}{}
595 \subparagraph{Serial Comm. Interface (SCI)}\textnormal{\\}
598 \item 1 port available inside the box on SCI connector (4 pins).
599 \item Variable baud rate. Tested on 9600 and 115200.
600 \item RS232 standard compatible.
603 \hypertarget{ethernet_eth}{}
604 \subparagraph{Ethernet (ETH)}\textnormal{\\}
607 \item 1 port available. Standard Ethernet connector available inside box.
612 \hypertarget{data_storagelogging}{}
613 \paragraph{Data storage/logging}\textnormal{\\}
615 \hypertarget{external_memory_sd_ram_sdr}{}
616 \subparagraph{External Memory SD-RAM (SDR)}\textnormal{\\}
619 \item 64MB (currently installed) external RAM used for logging. Maximal supported capacity is 256MB.
620 \item Memory test routine available with test Software.
623 \hypertarget{sd_card_sdc}{}
624 \subparagraph{SD Card (SDC)}\textnormal{\\}
627 \item Standard SD-Card connector or microSD connector available inside box.
628 \item Communication done using SPI.
633 \hypertarget{development_wiring}{}
634 \subsubsection{Development wiring}
636 For development, the RPP board needs to be wired as follow:
639 \item \textbf{Power input}: supply around 13 volts on any PWR pin (Power and Communication connectors) and
640 connect GND to power supply's GND. See \htmladdnormallink{Connectors pinout}{\#connectors\_pinout}.
641 \item \textbf{Serial communication}: board serial interface connected to a RS-232 port on the host computer
642 (\texttt{/dev/ttySX}) or to a USB converter (\texttt{/dev/ttyUSBX}).
643 \item \textbf{Debug and code download}: XDS100v2 JTAG Emulator connected to RPP board JTAG connector,
644 which in turn is connected through USB to the host computer (\texttt{/dev/ttyUSBX}).
645 See below on details for configuring the XDS100v2 on Linux.
650 \begin{figure}[H]\begin{center}
652 \noindent\includegraphics[width=300px]{media/images/dev_wiring.png}
653 \caption{RPP Wiring for Development.}\end{center}\end{figure}
655 Setup XDS100v2 on Linux:
657 By default the device (if nothing more connected then \texttt{/dev/ttyUSB0}) is added with permissions
658 \texttt{664} and \texttt{root} as user and group. To access the device write access for current user is
659 required. To do so create a new udev rule file:
661 \lstset{language=bash}
663 sudo nano /etc/udev/rules.d/45-pes-rpp.rules
671 SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="a6d0", MODE="0660", GROUP="plugdev"
674 Then reload udev rules with:
676 \lstset{language=bash}
678 sudo udevadm control --reload-rules
681 To check device properties like \texttt{idVendor} or \texttt{idProduct} issue the following command:
683 \lstset{language=bash}
685 udevadm info -a -p $(udevadm info -q path -n /dev/ttyUSB0)
688 \hypertarget{test_wiring}{}
689 \subsubsection{Test wiring}
691 Wiring for test differ from testing objectives. It test performed for this project no communication
692 test, besides SCI, was performed. The following describes how to wire each of the modules tested:
695 \item \textbf{DIN}: \newline{}
696 Connect all DIN pins to one LMC1 board outputs.
697 \item \textbf{LOUT}: \newline{}
698 Connect all LOUT pins to one LMC1 board inputs.
699 \item \textbf{AIN}: \newline{}
700 Connect all low pins to GND and leave all high pins floating. Allow to hook a potentiometer
702 \item \textbf{AOUT}: \newline{}
703 Connect all 4 pins to different channels on a oscilloscope.
704 \item \textbf{HBR}: \newline{}
705 Connect a motor to the H-bridge pins.
706 \item \textbf{MOUT}: \newline{}
707 Connect all 6 pins to a LMC1 board inputs. Another option is to connect a motor to one of the
709 \item \textbf{SCI}: \newline{}
710 Connect the SCI to a host computer. See \htmladdnormallink{Development wiring}{\#development\_wiring}.
711 \item \textbf{SDR}: \newline{}
712 No particular wiring is required for testing the SD-RAM.
715 It is recommended to setup a power bus using regulated 12volts from Signal Connector. Power the
716 LMC1 boards and the potentiometer with this bus. The LCM1 controller board should be connected
717 to the host computer through a RS-232 port or a USB converter.
721 \begin{figure}[H]\advance\leftskip-1cm
723 \noindent\includegraphics[width=530px]{media/images/test_wiring.png}
724 \caption{RPP Wiring for Testing.}\end{figure}
728 \hypertarget{project_repository}{}
729 \subsection{Project repository}
731 This git repository holds all the work done on this project.
733 To get the repository:
736 \texttt{git clone ssh://git@rtime.felk.cvut.cz/jenkicar/rpp-simulink.git}
739 This is a private repository, you require your SSH private key to be authorized. For access please
740 consult the Real-Time Systems Group, Department of Control Engineering, Faculty of Electrical
741 Engineering, Czech Technical University in Prague. For details about this git server refer to:
744 \htmladdnormallink{http://rtime.felk.cvut.cz/hw/index.php/Git\_repository\_on\_this\_server}{http://rtime.felk.cvut.cz/hw/index.php/Git\_repository\_on\_this\_server}
747 The general layout of the repository is:
751 |__ doc - Documentation created for this project.
752 |__ refs - Official reference documentation.
754 |__ blocks - Simulink Block Set.
755 |__ demos - Simulink Demos Library.
756 |__ lib - C support Library and API.
757 \__ rpp - Simulink Coder Target.
760 A detailed description of the content of each subfolder under \texttt{rpp/} can be found in the section
761 \textit{Subdirectory content description} on each dedicated section for the products developed.
763 In this document, the root folder on this repository is used as reference for file location and is
764 referred with the token \texttt{$<$repo$>$}.
768 \hypertarget{c_support_library}{}
769 \section{C Support Library}
771 The RPP C Support Library define the API to communicate with the board. It include drivers and
772 operating system. This section documents the implementation of this library.
774 \hypertarget{description}{}
775 \subsection{Description}
777 The RPP Library is the support library used by Simulink models. It is designed from the board user
778 perspective and exposes a simplified high-level API to handle the board's peripheral modules in a
781 The library as a concept and as a functional unit was introduced by this project. At the beginning
782 of this project the RPP board had just one application developed for. This application intended for
783 board testing allows the user to issue low-level commands to control and test the peripherals of
784 the board. This application was created using a combination of custom code, contributed drivers and
785 generated code from TI tool HalCoGen. Library functionality, like drivers and hardware access, and
786 application logic, like command processor and test routines, was largely merged in a single layer,
787 166 source code files long highly coupled application. In order to develop independent applications
788 for the RPP board, as it was expected to be each Simulink model, the library logic needed to be
789 separated from the application logic. This work implied a heavy refactoring on the testing
790 application in order extract from it the library functionality. Because the application files were
791 highly coupled in a single layer the refactoring and testing of the library implied roughly 70\% of
792 the work done on this project.
794 \begin{figure}[H]\advance\leftskip-1cm
796 \noindent\includegraphics[width=500px]{media/images/adc_dep_before.png}
797 \caption{Dependency graph of the ADC driver before refactoring.}\end{figure}
799 The above graph shows the dependencies of the ADC driver before the refactoring. Please note the
800 dependency on \texttt{cmdproc\_io\_tisci.h} and \texttt{cmdproc.h}, both application level modules. Also, note
801 the indirect dependency on the Operating System is being resolved through the application modules.
803 \begin{figure}[H]\begin{center}
805 \noindent\includegraphics[width=150px]{media/images/adc_dep_after.png}
806 \caption{Dependency graph of the ADC driver after refactoring.}\end{center}\end{figure}
808 The above graph shows the current dependencies for the ADC driver in the RPP Library. Please note
809 that it dependents only on the system layer low-level driver and that the Operating System indirect
810 dependency is resolved through the library foundations \texttt{base.h}.
812 Some other relevant changes introduced with the refactoring are:
815 \item ADC driver was completely rewritten.
816 \item MOUT driver was implemented.
817 \item DIN driver was slightly modified and extended.
818 \item DAC driver was slightly modified.
819 \item HBR driver was largely modified (in particular watchdog functionality).
820 \item SCI driver was refactored and extended.
821 \item SDR driver was implemented.
824 Also, once the library functionality could be isolated, the resulting API was too low-level to be
825 used by applications, in consequence one of the contributions of this projects was the
826 implementation of a high-level API on top of this low level API: the RPP Layer.
830 \hypertarget{architecture}{}
831 \subsubsection{Architecture}
833 The RPP library was structured into 5 layers with the following guidelines:
836 \item Top-down dependency only. No lower layer depends on anything from upper layers.
837 \item 1-1 layer dependency only. The top layer depends exclusively on the bottom layer, not on any
838 lower level layer (except for a couple of exceptions).
839 \item Each layer should provide a unified layer interface (\texttt{rpp.h}, \texttt{drv.h}, \texttt{hal.h}, \texttt{sys.h}
840 and \texttt{os.h}), so top layers depends on that layer interface and not on individual elements from
844 \begin{figure}[H]\begin{center}
846 \noindent\includegraphics[width=250px]{media/images/layers.pdf}
847 \caption{The RPP library layers.}\end{center}\end{figure}
849 As a consequence of this division the source code files and interface files are now placed on
850 private directories so the previous prefix based inclusion \texttt{drv\_din.h} is replaced by
851 \texttt{drv/din.h}. With this organization user applications only needs to include the top layer
852 interface file (\texttt{rpp/rpp.h}) to be able to use the library API.
854 Please note the sublayer uLut, which is used only by the SPI driver in order to use thread safe
855 queue mechanisms. Because the FreeRTOS already provides thread safe queues and in order to match
856 the order parts of the system it would be advisable to drop this dependency in the future.
860 \hypertarget{rpp_layer_modules}{}
861 \subsubsection{RPP Layer Modules}
863 The RPP Layer was structured into 14 different modules from 4 different categories that match the
864 hardware modules on the board:
866 \begin{center}\begin{tabular}{lll}
867 \textbf{Category} & \textbf{Description} & \textbf{MNEMONIC} \\
868 Logic IO & Digital Input & \texttt{[DIN ]} \\
869 & Digital (Logic) Output & \texttt{[LOUT]} \\
870 & Analog Input & \texttt{[AIN ]} \\
871 & Analog Output & \texttt{[AOUT]} \\
872 Power output & H-Bridge output & \texttt{[HBR ]} \\
873 & Power output (12V, 2A) & \texttt{[MOUT]} \\
874 & High-Power output (12V, 10A) & \texttt{[HOUT]} \\
875 Communication & CAN Bus & \texttt{[CAN ]} \\
876 & LIN (Local Interconnect Network) & \texttt{[LIN ]} \\
877 & FlexRay & \texttt{[FR ]} \\
878 & Serial Communication Interface & \texttt{[SCI ]} \\
879 & Ethernet & \texttt{[ETH ]} \\
880 Logging & SD Card & \texttt{[SDC ]} \\
881 & SD-RAM & \texttt{[SDR ]} \\
882 \end{tabular}\end{center}
884 Please note the mnemonic of each module, as they are constantly used on the Software and
885 documentation. Also note that only the following modules were implemented as part of this project:
902 Modules for which there is a low-level API available on the library but no high-level module was
915 Modules that are not yet available on the library at all:
920 \item ETH (in the works).
922 \item HOUT (partial).
927 The following graphic shows the library modules and the connectors on the hardware they map to.
929 \begin{figure}[H]\advance\leftskip-1cm
931 \noindent\includegraphics[width=500px]{media/images/blocks.pdf}
932 \caption{The RPP layer modules.}\end{figure}
936 \hypertarget{os_interchangeable_layer}{}
937 \subsubsection{OS interchangeable layer}
939 The OS Layer is composed by the FreeRTOS source code files. Because the FreeRTOS exposes an stable
940 API the OS layer can be changed in order to upgrade the Operating System or use a different port of
941 the OS, without changing the upper layers source code. The OS Layers currently available for the
942 RPP Library at \texttt{$<$repo$>$/rpp/lib/os/} at the time of this writing are:
945 \item Version 6.0.4 using POSIX port. This layer is the one that should be used when compiling a
946 program for x86(\_64) simulation. The port uses the \texttt{pthread} library and because of this the
947 port is not true real time and this is considered a simulator.
948 \item Version 7.0.2 using HalCoGen port for TMS570. This layer is the one currently supported and
949 tested. It was originally included in the testing application and was generated by an older
950 version of TI code generation tool HalCoGen.
951 \item Version 7.4.0 using HalCoGen port for TMS570. This layer was extracted from a newly generated
952 project using a newer version of HalCoGen. This layer is untested but \textit{should} work out of the
954 \item Version 7.4.2 using ARM Cortex R4 official port for CCS. This layer was created from vanilla
955 FreeRTOS 7.4.2 release. It is tested but non-working. Ticks are proved to be executed in time but
956 applications using this kernel runs at full-speed. The reason if this is currently unknown.
959 The general layout of all the layers are as following:
962 \item Common source code (kernel):
965 src/os/croutine.c (Optional)
969 src/os/timers.c (Optional)
973 Originally found in vanilla distribution in: \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Source}
975 \item Common interface files:
978 include/os/croutine.h
979 include/os/FreeRTOS.h
981 include/os/mpu_wrappers.h
982 include/os/portable.h (with minor editions)
983 include/os/projdefs.h
986 include/os/StackMacros.h
992 Originally found in vanilla distribution in: \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Source/include}
994 \item Memory management file:
997 src/os/heap.c (One of 4 version available, see Appendix A).
1001 Originally found in vanilla distribution in: \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Source/portable/MemMang}
1003 \item Port specific files:
1008 include/os/portmacro.h
1009 include/os/FreeRTOSConfig.h
1013 This depend of the port. In the case of the 7.4.2 TMS570 / ARM Cortex R4 for CCS port:
1016 \item First three files can be found in vanilla distribution in \newline{}
1017 \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Source/portable/CCS/ARM\_Cortex-R4}.
1018 \item Last file in \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Demo/CORTEX\_R4\_RM48\_TMS570\_CCS5}.
1022 In general, the following changes were applied to the source code base of all kernels:
1025 \item Replaced include directives to adapt to RPP library standard:
1027 \texttt{\#include "} with \texttt{\#include "os/}
1029 \item Line ending character set to UNIX '$\backslash$n' and tabs replaced by 4 spaces.
1034 \hypertarget{api_development_guidelines}{}
1035 \subsubsection{API development guidelines}
1039 The following are the development guidelines use for developing the RPP API:
1042 \item User documentation should be placed in header files, not in source code, and should be Doxygen
1043 formatted using autobrief. Documentation for each function present is mandatory.
1044 \item Function declarations on the headers files is for public functions only. Do not declare
1045 local/static/private functions on the header.
1046 \item Documentation on source code files should be non-doxygen formatted and intended for developers,
1047 not users. Documentation here is optional and at the discretion of the developer.
1048 \item Always use standard data types for IO when possible. Use custom structs as very last resort.
1049 \item Use prefix based functions names to avoid clash. The prefix is of the form \texttt{[layer]\_[module]\_},
1050 for example \texttt{rpp\_din\_update()} for the update function of the DIN module in the RPP Layer.
1051 \item To be very careful about symbol export. Because it is used as a static library the modules should
1052 not export any symbol that is not intended to be used (function) or \texttt{extern}'ed (variable) from
1053 application. As a rule of thumb declare all global variables as static.
1054 \item Only the RPP Layer symbols are available to user applications. All information related to lower
1055 layers is hidden for the application. This is accomplished by conditionally including the layers
1056 elements on the implementations files only and never on the interface files. Never expose any
1057 other layer to the application or the the whole system below that layer will be exposed. In other
1058 words, never \texttt{\#include "foo/foo.h"} in any RPP Layer interface file.
1059 \item Any module is conditionally included by using \texttt{rppCONFIG\_INCLUDE\_\{MNEMONIC\}} directive on the
1060 \texttt{RppConfig.h} configuration file.
1065 \hypertarget{further_improvements}{}
1066 \subsubsection{Further improvements}
1070 The following are recommendations for future improvements of the library:
1073 \item General code revision to remove local-only methods and variables from being exported.
1074 \item General code revision and refactoring to normalize the functions naming scheme. Normalize DRV and
1075 HAL to use prefix based scheme, not all the functions and exported variables do. Refactor the SYS
1076 layer, most of it generated by HalCoGen and that uses \texttt{thisNamingScheme} to use library
1077 standards (see \htmladdnormallink{RPP API}{\#rpp\_api} programming standards).
1078 \item Simplify doxygen documentation on the SYS layer, because is clunky, doesn't add any value and is
1079 repetitive. Move it to the header files.
1080 \item Remove error throwing from wrong parameter input in the DRV layer and assume a
1081 \textit{correct parameter and continue} safe approach. Move all error throwing and validation to the
1082 RPP layer (already implemented).
1087 Recommendations for changes on the electrical diagrams:
1090 \item Change name of GPIO MOUT1\_EN to MOUT1\_DIAG.
1091 \item Change name of GPIO MOUT1\_IN to MOUT1\_EN.
1094 The current names are misleading.
1096 \hypertarget{subdirectory__content_description}{}
1097 \subsection{Subdirectory content description}
1099 \noindent$\rightarrow$ \texttt{librpp.a} and \texttt{rpp-lib.lib}
1101 Version controlled RPP static libraries.
1103 The first one is for POSIX simulation, the second one for Simulink models and other ARM/TMS570
1104 applications. This files are placed here by the projects \texttt{apps/rpp-lib\_posix} and
1105 \texttt{apps/rpp-lib} when built.
1107 \noindent$\rightarrow$ \texttt{apps/}
1109 Applications related to the RPP library.
1111 This include the CCS studio project for generation of the static library and the test suite. See
1112 \htmladdnormallink{Static libraries}{\#static\_libraries}, \htmladdnormallink{Test Suite}{\#test\_suite} and
1113 \htmladdnormallink{Base application}{\#base\_application} for more information.
1115 \noindent$\rightarrow$ \texttt{os/}
1117 OS layers directory.
1119 See \htmladdnormallink{OS interchangeable layer}{\#os\_interchangeable\_layer} for more information.
1121 \noindent$\rightarrow$ \texttt{rpp/}
1123 Main directory for the RPP Library.
1125 \noindent$\rightarrow$ \texttt{rpp/doc/}
1127 Documentation directory for the RPP Library. See \htmladdnormallink{API generation}{\#api\_generation} for more
1130 \noindent$\rightarrow$ \texttt{rpp/TMS570LS3137.ccxml}
1132 Descriptor for code download.
1134 This file is used by all the projects including the Simulink RPP Target for code download. It is
1135 configured to use the Texas Instruments XDS100v2 USB Emulator. See
1136 \htmladdnormallink{Development wiring}{\#development\_wiring} for information about this hardware.
1138 \noindent$\rightarrow$ \texttt{rpp/TMS570LS313xFlashLnk.cmd}
1140 CGT Linker command file.
1142 This file is used by all applications linking for the board, including the Simulink models, static
1143 library and test suite. It includes instructions for the CGT Linker on where to place sections
1144 and size of some sections.
1146 \noindent$\rightarrow$ \texttt{rpp/include/\{layer\}} and \texttt{rpp/src/\{layer\}}
1148 Interface files and implementations files for given \texttt{\{layer\}}. See below for details on the RPP
1151 \noindent$\rightarrow$ \texttt{rpp/include/rpp/rpp.h}
1153 Main library header file.
1155 To use this library just include this file and this file only. Also, before using any library
1156 function please call \texttt{rpp\_init()} function for hardware initialization.
1158 \noindent$\rightarrow$ \texttt{rpp/include/rpp/RppConfig.h}
1160 Library configuration file.
1162 Please refer to the API documentation and header file comments for specific documentation for each
1163 configuration parameter.
1165 \noindent$\rightarrow$ \texttt{rpp/include/rpp/rpp\_\{mnemonic\}.h}
1167 Header file for \texttt{\{mnemonic\}} module.
1169 This files includes function definitions, pin definitions, etc, specific to \{mnemonic\} module. The
1170 inclusion of this header can be configured in \texttt{RppConfig.h} using
1171 \texttt{rppCONFIG\_INCLUDE\_\{MNEMONIC\}} directive. See
1172 \htmladdnormallink{API development guidelines}{\#api\_development\_guidelines}.
1174 \noindent$\rightarrow$ \texttt{rpp/src/rpp/rpp\_\{mnemonic\}.c}
1176 Module implementation.
1178 Implementation of \texttt{rpp\_\{mnemonic\}.h}'s functions on top of the DRV library. See
1179 \htmladdnormallink{API development guidelines}{\#api\_development\_guidelines}.
1181 \noindent$\rightarrow$ \texttt{rpp/src/rpp/rpp.c}
1183 Implementation of library-wide functions.
1187 \hypertarget{test_suite}{}
1188 \subsection{Test Suite}
1190 The \texttt{rpp-test-suite} is a RPP application developed as part of this project that includes a
1191 series of test tasks or test commands to verify the correct behavior and functionality of the RPP
1192 layer modules. There is one command per module, and the command use the same mnemonic that the
1195 This test suite can be found in \texttt{$<$repo$>$/rpp/lib/apps/rpp-test-suite} for the ARM version and in
1196 \texttt{$<$repo$>$/rpp/lib/apps/rpp-test-suite\_posix} for the simulated version.
1198 The application enables a command processor using the SCI at \textbf{115200-8-N-1}:
1201 RPP Library Test Suite.
1202 ===========================================================
1203 [Type a module to test or 'help']
1206 help - Display this help.
1207 ain - Test Analog Input.
1208 aout - Test Analog Output.
1209 can - Test CAN communication.
1210 din - Test Digital Inputs.
1211 eth - Test Ethernet communication.
1212 fr - Test FlexRay communication.
1213 hbr - Test H-Bridge.
1214 hout - Test High Power Output.
1215 lin - Test LIN communication.
1216 lout - Test Digital Outputs.
1217 mout - Test Power Outputs.
1218 sci - Test Serial Communication Interface.
1223 Current modules with tests implemented are:
1225 \begin{multicols}{2}
1234 \item SCI. (the test-suite itself)
1240 A note of warning: tests spawn OS tasks at the beginning of the test and deletes them at the end.
1241 Because current memory memory management implementation cannot free memory the test suite will
1242 fill all the memory and tests will be unable to start. In this case just reset the board. See
1243 \htmladdnormallink{Appendix A: Notes on FreeRTOS memory management}{\#appendix\_a\_notes\_on\_freertos\_memory\_management}
1244 for more information.
1248 \hypertarget{ain_test_description}{}
1249 \subsubsection{AIN test description}
1251 This test will read all the analog inputs at a rate of 100 times per second and print the result.
1255 Analog Inputs Test [1-12]:
1256 ===========================================================
1257 1 2 3 4 5 6 7 8 9 10 11 12
1258 0 0 0 0 0 0 0 0 0 0 0 0
1261 Status: \textbf{PASSED} for channels 1-5. 6-12 remain untested but they \textit{should} work.
1263 \hypertarget{aout_test_description}{}
1264 \subsubsection{AOUT test description}
1266 This test will generate a 10Hz sinus wave on all the analog outputs with a sampling rate of 1kHz.
1267 The sinus wave of each analog output channel is sifted by (1/4)pi.
1271 Analog Output Test at 10 Hz:
1272 ===========================================================
1276 Status: \textbf{PASSED}.
1278 \hypertarget{din_test_description}{}
1279 \subsubsection{DIN test description}
1281 This test will read all 16 + 8 digital inputs at a rate of 100 times per second, using both low
1282 speed SPI chip and variable threshold high-speed inputs.
1286 Digital Inputs Test [1-16]:
1287 ===========================================================
1288 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 A B C D E F G H
1289 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
1295 \item Low speed fixed threshold [1-16]: \textbf{PASSED}.
1296 \item High speed variable threshold [A-H]: \textbf{PASSED}.
1299 \hypertarget{hbr_test_description}{}
1300 \subsubsection{HBR test description}
1302 This test will generate a sinus wave to control the H-Bridge of one period per 20 seconds (0.05Hz)
1303 at a sampling rate of 20Hz.
1307 H-Bridge Test at 0.05 Hz:
1308 ===========================================================
1312 Status: \textbf{PASSED}.
1314 \hypertarget{lout_test_description}{}
1315 \subsubsection{LOUT test description}
1317 This test will show in the digital outputs the value in binary of a counter, incrementing the
1318 counter once per second. The counter is 8 bits, the same as the outputs, so 255 seconds are
1319 required for an overflow/restart of the counting.
1323 Digital Output Test:
1324 ===========================================================
1328 Status: \textbf{PASSED}.
1330 \hypertarget{mout_test_description}{}
1331 \subsubsection{MOUT test description}
1333 This test will toggle the power outputs one by one per second, then wait 10 seconds in that state
1334 while constantly verifying the diagnostics.
1339 ===========================================================
1341 1: OK 1: OK 1: OK 1: OK 1: OK 1: OK
1344 Status: \textbf{PASSED}.
1346 \hypertarget{sci_test_description}{}
1347 \subsubsection{SCI test description}
1349 A more comprehensive test is not implemented. The very use of this test-suite implies the correct
1350 function of the SCI module. Nevertheless, as a future improvement, a test that will verify run-time
1351 baud rate changes and test some other RPP SCI functions is desirable.
1355 You're using the SCI, reading this and typing this command.
1356 Press any key to continue...
1359 Status: \textbf{PASSED}.
1361 \hypertarget{sdr_test_description}{}
1362 \subsubsection{SDR test description}
1364 This test will launch a noise generator task that will log noise and then start the library
1365 included SD-RAM logging command processor, allowing the user to see and handle the log on the
1370 Log control: 1024kB available.
1371 ===========================================================
1373 [ 1239864] This is the noise generator at iteration 1 putting some noise value 279735017.
1374 [ 1240779] This is the noise generator at iteration 2 putting some noise value 1943579783.
1377 1023 kB of 1024 kB available.
1385 Status: \textbf{PASSED}.
1389 \hypertarget{static_libraries}{}
1390 \subsection{Static libraries}
1392 The RPP Library can be compiled as a static library for ARM using TI CGT and for x86(\_64) using
1393 GCC. CCS projects \texttt{rpp-lib} and \texttt{rpp-lib\_posix} in \texttt{$<$repo$>$/rpp/lib/apps/} allows to generate
1394 the static libraries. After compilation, as part of the build process, both projects will
1395 automatically update the version-controlled static libraries in \texttt{$<$repo$>$/rpp/lib/}:
1398 \item \texttt{rpp-lib.lib}, static library for ARM using TI naming scheme.
1399 \item \texttt{librpp.a}, static library for x86(\_64) using standard Linux naming scheme.
1402 One future improvement would be the creation of a Makefile for each compilation scheme in order to
1403 not depend on CCS managed build system. For ARM manual compilation or makefile creation using Texas
1404 CGT see the \texttt{target\_tools.mk} file under the Simulink RPP Target folder. The relevant aspects for
1405 compiling and linking an application using the static libraries are:
1407 \textbf{ARM compilation using CCS for the RPP board:}
1410 \item Include headers files of the OS for which the library was compiled against. At the time of this
1411 writing the OS is FreeRTOS 7.0.2. See \htmladdnormallink{OS interchangeable layer}{\#os\_interchangeable\_layer}
1413 \item Include header files for the RPP library.
1414 \item Add library \texttt{rpp-lib.lib} to the linker libraries. The RPP library \textbf{MUST} be looked for
1415 before Texas Instruments support library \texttt{rtsv7R4\_T\_be\_v3D16\_eabi.lib}.
1416 \item Configure linker to retain \texttt{.intvecs} section from RPP Library:\newline{}
1417 \texttt{--retain="rpp-lib.lib$<$sys\_intvecs.obj$>$(.intvecs)"}
1418 \item Use the provided linker command file \texttt{TMS570LS313xFlashLnk.cmd}.
1421 \textbf{x86(\_64) compilation using GCC for Simulation:}
1424 \item Include headers files of the OS for Simulation. At the time of this writing the OS is POSIX
1426 \item Include header files for the RPP library.
1427 \item Create a \texttt{RppConfig.h} override file and drop DRV layer dependency: \texttt{rppCONFIG\_DRV 0}.
1428 \item Includes must be configured in a way that the \texttt{RppConfig.h} taken under consideration is the
1429 override and not the library one.
1430 \item Add library \texttt{librpp.a} to the linker libraries.
1431 \item Add \texttt{pthread} to the linker libraries.
1434 As an important note, all the models compiled using Simulink will link against \texttt{rpp-lib.lib}.
1435 When compiling a Simulink model, Simulink, and then \texttt{make}, will not update the generated binary
1436 if the model hasn't changed, and then if the source code hasn't changed. Static libraries changes
1437 are not considered for re-compilation and re-linking. If library development is being done and
1438 static library is updated, in order for the Simulink model to generate a newly linked version of
1439 the binary the whole code generation folder needs to be deleted in order to force code generation,
1440 compilation and linking with the new static library.
1444 \hypertarget{base_application}{}
1445 \subsection{Base application}
1447 In \texttt{$<$repo$>$/rpp/lib/apps/} there is two RPP base applications, \texttt{base} and \texttt{base\_posix}, that
1448 already configured for the RPP Library. It is advised that new applications uses this projects a
1451 To create a new application copy this directory and rename it. Now open files \texttt{.project},
1452 \texttt{.cproject} and \texttt{.ccsproject} (if available) and change any occurrence of the work \texttt{base}
1453 with the name of your project. Use lower case ASCII letters and underscores only.
1455 \textbf{Steps to configure a new CCS (ARM, using CGT) RPP application:}
1458 \item Create a new CCS project. \newline{}
1459 \noindent\includegraphics[width=400px]{media/images/base_1.png}
1460 \item Create a normal folder \texttt{include}.
1461 \item Create a source folder \texttt{src}.
1462 \item Add common \texttt{.gitignore} to the root of that project:
1470 \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this repository branch root.\newline{}
1471 \noindent\includegraphics[width=400px]{media/images/base_2.png}
1472 \item Add \texttt{rpp-lib.lib} static library to linker libraries and add \texttt{RPP\_LIB\_ROOT} to the library
1473 search path.\newline{}
1474 \noindent\includegraphics[width=400px]{media/images/base_3.png}
1476 \item Configure linker to retain \texttt{.intvecs} from RPP static library.\newline{}
1477 \noindent\includegraphics[width=350px]{media/images/base_4.png}
1478 \item Configure compiler to include local includes, OS includes for TMS570 and RPP includes, in that
1480 \noindent\includegraphics[width=350px]{media/images/base_5.png}
1482 \item Configure compiler to allow GCC extensions.\newline{}
1483 \noindent\includegraphics[width=400px]{media/images/base_6.png}
1484 \item Import and link (\underline{do not copy!}) linker file and board upload descriptor.\newline{}
1485 \noindent\includegraphics[width=200px]{media/images/base_7.png}
1488 \textbf{Steps to configure a new GCC (x86(\_64)) RPP simulated application:}
1491 \item Create a new managed C project that uses Linux GCC toolchain.
1492 \item Create a source folder \texttt{src}. Link all files from original CCS application to this folder.
1493 \item Create a normal folder \texttt{include}. Create a folder \texttt{rpp} inside of it.
1494 \item Add common \texttt{.gitignore} to the root of that project:
1502 \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this repository branch root.\newline{}
1503 \noindent\includegraphics[width=400px]{media/images/base_posix_1.png}
1504 \item Configure compiler to include local includes, CCS application includes, OS includes for POSIX and
1505 RPP includes, in that order.\newline{}
1506 \noindent\includegraphics[width=400px]{media/images/base_posix_2.png}
1508 \item Add \texttt{rpp} and \texttt{pthread}to linker libraries and add \texttt{RPP\_LIB\_ROOT} to the library search
1510 \noindent\includegraphics[width=400px]{media/images/base_posix_3.png}
1511 \item Copy \texttt{RppConfig.h} from RPP Library to a new folder \texttt{include/rpp} and configure it drop DRV
1512 layer dependency: \texttt{rppCONFIG\_DRV 0}.\newline{}
1513 \noindent\includegraphics[width=200px]{media/images/base_posix_4.png}
1516 \textbf{In general any RPP application uses the layout/template:}
1519 \item Include RPP library header file.
1520 \lstset{language=c++}
1522 #include "rpp/rpp.h"
1526 \item Create one or as many FreeRTOS task function definitions as required. Those tasks should use
1527 functions from this library.
1528 \lstset{language=c++}
1530 void my_task(void* p)
1532 static const portTickType freq_ticks = 1000 / portTICK_RATE_MS;
1533 portTickType last_wake_time = xTaskGetTickCount();
1535 /* Wait until next step */
1536 vTaskDelayUntil(&last_wake_time, freq_ticks);
1537 rpp_sci_printf((const char*)"Hello RPP.\r\n");
1542 \item Create the main function that will:
1544 \item Initialize the RPP board.
1545 \item Spawn the tasks the application requires. Refer to FreeRTOS API for
1547 \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details.
1548 \item Catch if idle task could not be created.
1550 \lstset{language=c++}
1554 /* Initialize RPP board */
1558 if(xTaskCreate(my_task, (const signed char*)"my_task",
1559 512, NULL, 0, NULL) != pdPASS) {
1561 rpp_sci_printf((const char*)
1562 "ERROR: Cannot spawn control task.\r\n"
1565 while(TRUE) { asm(" nop"); }
1568 /* Start the FreeRTOS Scheduler */
1569 vTaskStartScheduler();
1571 /* Catch scheduler start error */
1573 rpp_sci_printf((const char*)
1574 "ERROR: Problem allocating memory for idle task.\r\n"
1577 while(TRUE) { asm(" nop"); }
1582 \item Create hook functions for FreeRTOS:
1584 \item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation errors.
1585 \item \texttt{vApplicationStackOverflowHook()} allows to catch if a task overflows it's
1588 \lstset{language=c++}
1590 #if configUSE_MALLOC_FAILED_HOOK == 1
1592 * FreeRTOS malloc() failed hook.
1594 void vApplicationMallocFailedHook(void) {
1596 rpp_sci_printf((const char*)
1597 "ERROR: manual memory allocation failed.\r\n"
1604 #if configCHECK_FOR_STACK_OVERFLOW > 0
1606 * FreeRTOS stack overflow hook.
1608 void vApplicationStackOverflowHook(xTaskHandle xTask,
1609 signed portCHAR *pcTaskName) {
1611 rpp_sci_printf((const char*)
1612 "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName
1623 \hypertarget{api_generation}{}
1624 \subsection{API generation}
1626 The RPP Layer is formatted using Doxygen documentation generator. This allows to generate a high
1627 quality API reference. To generate the API reference do in a terminal:
1629 \lstset{language=bash}
1631 cd <repo>/rpp/lib/rpp/doc/api
1632 doxygen doxygen.conf
1633 xdg-open html/index.html
1636 The files under \texttt{$<$repo$>$/rpp/lib/rpp/doc/api/content} are used for the API reference generation
1637 are their name is self-explanatory:
1647 To install Doxygen see \htmladdnormallink{Development environment}{\#development\_environment} section.
1649 \hypertarget{api_reference}{}
1650 \subsection{API Reference}
1652 For the complete API reference please generate the HTML version using the above section
1653 instructions. Here is listed the index of functions of each module and their brief.
1655 Please note that not all modules were implemented as part of this project. See
1656 \htmladdnormallink{RPP Layer Modules}{\#rpp\_layer\_modules} for a list of the modules implemented.
1660 \hypertarget{din_api_reference}{}
1661 \subsubsection{DIN API Reference}
1663 \texttt{int8\_t rpp\_din\_init();} \newline{} \noindent$\rightarrow$ DIN module initialization. \newline{} \newline{}
1664 \texttt{int8\_t rpp\_din\_ref(uint16\_t refA, uint16\_t refB);} \newline{} \noindent$\rightarrow$ Configure voltage reference levels for digital inputs using variable reference threshold. \newline{} \newline{}
1665 \texttt{int8\_t rpp\_din\_setup(uint8\_t pin, boolean\_t pull\_type, boolean\_t active, boolean\_t can\_wake);} \newline{} \noindent$\rightarrow$ Configure given pin. \newline{} \newline{}
1666 \texttt{int8\_t rpp\_din\_get(uint8\_t pin, boolean\_t var\_thr);} \newline{} \noindent$\rightarrow$ Get the current cached value of the given pin. \newline{} \newline{}
1667 \texttt{int8\_t rpp\_din\_diag(uint8\_t pin);} \newline{} \noindent$\rightarrow$ Get the diagnostic cached value for given pin. \newline{} \newline{}
1668 \texttt{int8\_t rpp\_din\_update();} \newline{} \noindent$\rightarrow$ Read and update cached values and diagnostic values of all pins. Also commit configuration changes.
1670 \hypertarget{lout_api_reference}{}
1671 \subsubsection{LOUT API Reference}
1673 \texttt{int8\_t rpp\_lout\_init();} \newline{} \noindent$\rightarrow$ LOUT module initialization. \newline{} \newline{}
1674 \texttt{int8\_t rpp\_lout\_set(uint8\_t pin, uint8\_t val);} \newline{} \noindent$\rightarrow$ Set the output cache of given pin to given value. \newline{} \newline{}
1675 \texttt{int8\_t rpp\_lout\_diag(uint8\_t pin);} \newline{} \noindent$\rightarrow$ Get the diagnostic cached value for given pin. \newline{} \newline{}
1676 \texttt{int8\_t rpp\_lout\_update();} \newline{} \noindent$\rightarrow$ Flush cached output values and read back diagnostic values of all pins.
1678 \hypertarget{ain_api_reference}{}
1679 \subsubsection{AIN API Reference}
1681 \texttt{int8\_t rpp\_ain\_init();} \newline{} \noindent$\rightarrow$ AIN module initialization. \newline{} \newline{}
1682 \texttt{int16\_t rpp\_ain\_get(uint8\_t pin);} \newline{} \noindent$\rightarrow$ Get the current analog value on the given pin. \newline{} \newline{}
1683 \texttt{int8\_t rpp\_ain\_update();} \newline{} \noindent$\rightarrow$ Read and update analog cached values.
1685 \hypertarget{aout_api_reference}{}
1686 \subsubsection{AOUT API Reference}
1688 \texttt{\#define RPP\_DAC\_OA 5.6} \newline{} \noindent$\rightarrow$ DAC output operational amplifier multiplication constant. \newline{} \newline{}
1689 \texttt{\#define RPP\_DAC\_VREF 2.5} \newline{} \noindent$\rightarrow$ DAC hardware reference voltage. \newline{} \newline{}
1690 \texttt{int8\_t rpp\_aout\_init();} \newline{} \noindent$\rightarrow$ AOUT module initialization. \newline{} \newline{}
1691 \texttt{int8\_t rpp\_aout\_setup(uint8\_t pin, boolean\_t enabled);} \newline{} \noindent$\rightarrow$ Configure enabled/disabled state for given pin. \newline{} \newline{}
1692 \texttt{int8\_t rpp\_aout\_set(uint8\_t pin, uint16\_t val);} \newline{} \noindent$\rightarrow$ Set the output cache of given pin to given value. \newline{} \newline{}
1693 \texttt{int8\_t rpp\_aout\_set\_voltage(uint8\_t pin, uint16\_t mv);} \newline{} \noindent$\rightarrow$ Set output to given voltage. \newline{} \newline{}
1694 \texttt{int8\_t rpp\_aout\_update();} \newline{} \noindent$\rightarrow$ Flush cached output values and configuration changes.
1696 \hypertarget{hbr_api_reference}{}
1697 \subsubsection{HBR API Reference}
1699 \texttt{int8\_t rpp\_hbr\_init();} \newline{} \noindent$\rightarrow$ HBR module initialization. \newline{} \newline{}
1700 \texttt{int8\_t rpp\_hbr\_enable(int32\_t period);} \newline{} \noindent$\rightarrow$ Enable the H-Bridge for control. \newline{} \newline{}
1701 \texttt{int8\_t rpp\_hbr\_control(double cmd);} \newline{} \noindent$\rightarrow$ Control the H-Bridge direction, enabled/disabled and PWM. \newline{} \newline{}
1702 \texttt{int8\_t rpp\_hbr\_disable();} \newline{} \noindent$\rightarrow$ Disable the H-Bridge.
1706 \hypertarget{mout_api_reference}{}
1707 \subsubsection{MOUT API Reference}
1709 \texttt{int8\_t rpp\_hbr\_init();} \newline{} \noindent$\rightarrow$ HBR module initialization. \newline{} \newline{}
1710 \texttt{int8\_t rpp\_mout\_init();} \newline{} \noindent$\rightarrow$ MOUT module initialization. \newline{} \newline{}
1711 \texttt{int8\_t rpp\_mout\_set(uint8\_t pin, uint8\_t val);} \newline{} \noindent$\rightarrow$ Set the output of given pin to given value. \newline{} \newline{}
1712 \texttt{int8\_t rpp\_mout\_get(uint8\_t pin);} \newline{} \noindent$\rightarrow$ Get the cached value of the given pin set by rpp\_mout\_set(). \newline{} \newline{}
1713 \texttt{int8\_t rpp\_mout\_diag(uint8\_t pin);} \newline{} \noindent$\rightarrow$ Reads the value on the given diagnostic pin.
1715 \hypertarget{hout_api_reference}{}
1716 \subsubsection{HOUT API Reference}
1718 \texttt{int8\_t rpp\_hout\_init();} \newline{} \noindent$\rightarrow$ HOUT module initialization.
1720 \hypertarget{can_api_reference}{}
1721 \subsubsection{CAN API Reference}
1723 \texttt{int8\_t rpp\_can\_init();} \newline{} \noindent$\rightarrow$ CAN module initialization.
1725 \hypertarget{lin_api_reference}{}
1726 \subsubsection{LIN API Reference}
1728 \texttt{int8\_t rpp\_lin\_init();} \newline{} \noindent$\rightarrow$ LIN module initialization.
1730 \hypertarget{fr_api_reference}{}
1731 \subsubsection{FR API Reference}
1733 \texttt{int8\_t rpp\_fr\_init();} \newline{} \noindent$\rightarrow$ FR module initialization.
1737 \hypertarget{sci_api_reference}{}
1738 \subsubsection{SCI API Reference}
1740 \texttt{int8\_t rpp\_sci\_init();} \newline{} \noindent$\rightarrow$ SCI module initialization. \newline{} \newline{}
1741 \texttt{boolean\_t rpp\_sci\_setup(uint32\_t baud);} \newline{} \noindent$\rightarrow$ SCI module setup. \newline{} \newline{}
1742 \texttt{uint16\_t rpp\_sci\_available();} \newline{} \noindent$\rightarrow$ Number of bytes available on input buffer. \newline{} \newline{}
1743 \texttt{int8\_t rpp\_sci\_read(uint32\_t amount, uint8\_t* buffer);} \newline{} \noindent$\rightarrow$ Read n number of bytes from input buffer. \newline{} \newline{}
1744 \texttt{int8\_t rpp\_sci\_read\_nb(uint32\_t amount, uint8\_t* buffer);} \newline{} \noindent$\rightarrow$ Read n number of bytes from input buffer if possible. \newline{} \newline{}
1745 \texttt{int8\_t rpp\_sci\_write(uint32\_t amount, uint8\_t* data);} \newline{} \noindent$\rightarrow$ Write n number of bytes to the output buffer. \newline{} \newline{}
1746 \texttt{int8\_t rpp\_sci\_write\_nb(uint32\_t amount, uint8\_t* data);} \newline{} \noindent$\rightarrow$ Write n number of bytes to the output buffer if possible. \newline{} \newline{}
1747 \texttt{int8\_t rpp\_sci\_flush(boolean\_t buff);} \newline{} \noindent$\rightarrow$ Flush incomming or outgoing buffers. \newline{} \newline{}
1748 \texttt{int32\_t rpp\_sci\_printf(const char* format, ...);} \newline{} \noindent$\rightarrow$ C style printf using RPP SCI module. \newline{} \newline{}
1749 \texttt{int8\_t rpp\_sci\_putc(uint8\_t byte);} \newline{} \noindent$\rightarrow$ C style putc (put character) using RPP SCI module. \newline{} \newline{}
1750 \texttt{int16\_t rpp\_sci\_getc();} \newline{} \noindent$\rightarrow$ C style getc (get character) using RPP SCI module.
1752 \hypertarget{eth_api_reference}{}
1753 \subsubsection{ETH API Reference}
1755 \texttt{int8\_t rpp\_eth\_init();} \newline{} \noindent$\rightarrow$ ETH module initialization.
1757 \hypertarget{sdc_api_reference}{}
1758 \subsubsection{SDC API Reference}
1760 \texttt{int8\_t rpp\_sdc\_init();} \newline{} \noindent$\rightarrow$ SDC module initialization.
1762 \hypertarget{sdr_api_reference}{}
1763 \subsubsection{SDR API Reference}
1765 \texttt{\#define RPP\_SDR\_ADDR\_START 0x80000000U} \newline{} \noindent$\rightarrow$ SDRAM start address on RPP board. \newline{} \newline{}
1766 \texttt{\#define RPP\_SDR\_ADDR\_END 0x83FFFFFFU} \newline{} \noindent$\rightarrow$ SDRAM end address on RPP board. \newline{} \newline{}
1767 \texttt{int8\_t rpp\_sdr\_init();} \newline{} \noindent$\rightarrow$ SDR module initialization. \newline{} \newline{}
1768 \texttt{int8\_t rpp\_sdr\_setup(boolean\_t enable);} \newline{} \noindent$\rightarrow$ Configure SD-RAM logging. \newline{} \newline{}
1769 \texttt{uint32\_t rpp\_sdr\_available();} \newline{} \noindent$\rightarrow$ Query for the amount of space free on the SD-RAM. \newline{} \newline{}
1770 \texttt{int32\_t rpp\_sdr\_printf(const char* format, ...);} \newline{} \noindent$\rightarrow$ Store a formatted user string on the log, if logging is enabled. \newline{} \newline{}
1771 \texttt{int8\_t rpp\_sdr\_clear();} \newline{} \noindent$\rightarrow$ Clear log. \newline{} \newline{}
1772 \texttt{int8\_t rpp\_sdr\_show(boolean\_t start);} \newline{} \noindent$\rightarrow$ Start/Stop the task that sends the log to the SCI.
1776 \hypertarget{simulink_coder_target}{}
1777 \section{Simulink Coder Target}
1779 The Simulink Coder Target allows Simulink model's code generation, compilation and download for the
1782 \hypertarget{description}{}
1783 \subsection{Description}
1785 The Simulink RPP Target provides support for C source code generation from Simulink models and
1786 compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
1787 uses Texas Instruments ARM compiler (armcl) included in the Code Generation Tools available with
1788 Code Composer Studio, and thus it depends on it for proper functioning.
1790 This library also provides support for automatic download of the compiled binary to the RPP
1793 \hypertarget{code_generation_process}{}
1794 \subsubsection{Code generation process}
1796 \begin{figure}[H]\begin{center}
1798 \noindent\includegraphics[width=400px]{media/images/tlc_process.png}
1799 \caption{TLC code generation process.}\end{center}\end{figure}
1803 \hypertarget{subdirectory__content_description}{}
1804 \subsection{Subdirectory content description}
1806 \noindent$\rightarrow$ \texttt{rpp\_setup.m}
1808 RPP Target install script.
1810 This script will, among other things, ask the user to provide the location of the armcl parent
1811 directory, infer and save some relevant CCS paths, add paths to Matlab path and build S-Function
1812 blocks for user's architecture (using Matlab's mex command line tool).
1815 \item \underline{Reference:}
1817 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1137.
1821 \noindent$\rightarrow$ \texttt{rpp.tlc}
1823 Embedded real-time system target file for RPP.
1825 This file is the system target file (STF), or target manifest file. Functions of the STF include:
1828 \item Making the target visible in the System Target File Browser.
1829 \item Definition of code generation options for the target (inherited and target-specific).
1830 \item Providing an entry point for the top-level control of the TLC code generation process.
1834 \item \underline{Reference:}
1836 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1129 and \underline{1144}.
1840 \noindent$\rightarrow$ \texttt{rpp.tmf}
1842 Embedded Coder Template Makefile.
1844 This is just standard Embedded Coder Template Makefile, provided by Matlab. It was slightly
1845 modified to support \texttt{armcl} particularities and added template rules for assembler files (which
1846 were included by the \texttt{rpp\_lib\_support.m} script, but is no longer the case).
1849 \item \underline{Reference:}
1851 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1130 and \underline{1183}.
1855 \noindent$\rightarrow$ \texttt{rpp\_download.m}
1857 Code download utility for Simulink RPP Target.
1859 This function is optionally executed at the end of the build process if it is successful and the
1860 user selected \textit{Download compiled binary to RPP} option on the build configuration panel. This
1861 function calls \texttt{loadti.sh} script with the generated binary and using configuration for the
1862 XDS100v2 JTAG Emulators. The board should be powered and correctly wired. \newline{}
1863 See \htmladdnormallink{Development wiring}{\#development\_wiring}.
1866 \noindent$\rightarrow$ \texttt{rpp\_file\_process.tlc}
1868 Code generation custom file processing template.
1870 This file should decide which \textit{main} to generate according to configuration, in particular which
1871 mode, Single Tasking or Multitasking, is chosen. The RPP Target ignores this settings because it
1872 uses a tasking system based on tasking features provided by FreeRTOS. In consequence is only a
1873 wrapper to the \textit{Single Tasking} main, which clearly is not for single tasking.
1876 \item \underline{Reference:}
1878 \item \texttt{$<$repo$>$/refs/ecoder\_ug.pdf} p. 556.
1879 \item \texttt{$<$repo$>$/refs/ecoder\_ref.pdf} p. 1347.
1883 \noindent$\rightarrow$ \texttt{rpp\_lib\_support.m}
1885 \textbf{DEPRECATED}. Simulink support for RPP library and operating system setup.
1887 This files used to add the source code from the RPP library and operating to the build. This is no
1888 longer required when using the static library. This is left for future reference in case new source
1889 code needs to be included to the build.
1892 \item \underline{Reference:}
1894 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1058.
1895 \item \texttt{$<$repo$>$/refs/rtw\_ref.pdf} p. 56.
1899 \noindent$\rightarrow$ \texttt{rpp\_make\_rtw\_hook.m}
1901 Build process hooks file.
1903 This file is hook file that invoke target-specific functions or executables at specified points in
1904 the build process. In particular, this file handle the copying of required files before the
1908 \item \underline{Reference:}
1910 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1066-1072 and 1131.
1914 \noindent$\rightarrow$ \texttt{rpp\_select\_callback\_handler.m}
1916 RPP Target select callback handler.
1918 This callback function is triggered whenever the user selects the target in the System Target File
1919 Browser. Default values for Simulation and configurations parameters are set. Some options are
1920 disabled if it is not allowed to be changed by user.
1923 \item \underline{Reference:}
1925 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1211.
1930 \noindent$\rightarrow$ \texttt{rpp\_srmain.tlc}
1932 Custom file processing to generate a \textit{main} file.
1934 This file generated the \textit{main} file for the RPP target on top of the RPP library and the FreeRTOS
1935 operating system. The \texttt{sr} prefix is standard to mark Single Tasking main, which is the case.
1936 See \texttt{rpp\_file\_process.m} description above for more information about this.
1939 \item \underline{Reference:}
1941 \item Example in \texttt{$<$matlab$>$/rtw/c/tlc/mw/bareboard\_srmain.tlc}.
1945 \noindent$\rightarrow$ \texttt{target\_tools.mk}
1947 Makefile for CCS (\texttt{armcl}) toolchain support.
1949 This file set variables to CCS tools to support build for this toolchain. This file is included by
1950 \texttt{rpp.tmf} before declaring the rules for source code.
1953 \item \underline{Reference:}
1955 \item \textit{Include a tool specification settings} comment block in \texttt{rpp.tmf}.
1956 \item Compiler options documentation available in \texttt{armcl.pdf}.
1962 \hypertarget{installation_procedure}{}
1963 \subsection{Installation procedure}
1966 \item Download and install CCS for Linux:
1968 Details on how to setup CCS are available in section
1969 \htmladdnormallink{TI Code Composer Studio}{\#ti\_code\_composer\_studio}.
1971 \item Install RPP Target:
1973 Open Matlab and type on command window:
1975 \lstset{language=Matlab}
1981 This will launch the RPP setup script. This script will ask the user to provide the path to the CCS
1982 compiler root directory (the directory where \texttt{armcl} binary is located), normally:
1985 <ccs>/tools/compiler/arm_5.X.X/
1988 This script will, among other things, ask the user to provide the location of the armcl parent
1989 directory, infer and save some relevant CCS paths, add paths to Matlab path and build S-Function
1990 blocks for user's architecture (using Matlab's mex command line tool).
1992 \item Create a new model or load a demo:
1994 Demos are located on \texttt{$<$repo$>$/rpp/demo} or you can start a new model and configure target to RPP.
1995 For new models see \htmladdnormallink{Target Reference}{\#target\_reference} section below.
2003 \item Open or create a model you want to generate code from.
2004 \item Make sure that the model is configured (Simulation $\rightarrow$
2005 Model Configuration Parameters) as described in Section \ref{sec:target-reference}.
2006 \item From Matlab command window change the current directory to where
2007 you want your generated code to appear, e.g.:
2008 \begin{lstlisting}[language=Matlab]
2011 The code will be generated in a subdirectory of that directory. The
2012 name of the subdirectory will be \texttt{<model>\_rpp}, where
2013 \texttt{model} is the name of the Simulink model.
2014 \item Generate the code by choosing ``Code $\rightarrow$ C/C++ Code
2015 $\rightarrow$ Build Model''.
2016 \item If \emph{Download compiled binary to RPP} was selected in
2017 \emph{RPP Options} pane (see Section \ref{sec:rpp-target-options}),
2018 the compiled binary will be downloaded to the to the board. After
2019 the download is finished you should reset the board to run the
2022 Note: You should quit the Code Composer Studio before downloading the
2023 generated code to the RPP board. Otherwise the download fails.
2028 \hypertarget{target_reference}{}
2029 \subsection{Target Reference}
2030 \label{sec:target-reference}
2032 This section describes the options required or available for running a Simulink model with the RPP
2035 \hypertarget{simulink_model_options}{}
2036 \subsubsection{Simulink model options}
2038 The Simulink model needs to be configured in the following way:
2043 \item \textit{fixed-step discrete}.
2044 \item Tasking mode set to \textit{SingleTasking}. \newline{}
2045 \noindent\includegraphics[width=400px]{media/images/simulink_solver.png}
2048 \item Diagnostics -- Sample Time:
2050 \item Disable warning source block specifies -1 sampling time. It's ok for the source blocks to run
2051 once per tick. \newline{}
2052 \noindent\includegraphics[width=400px]{media/images/simulink_diagnostics.png}
2054 \item Code generation:
2056 \item Set to \texttt{rpp.tlc}. \newline{}
2057 \noindent\includegraphics[width=400px]{media/images/simulink_code.png}
2061 Note: Single Tasking is the only currently supported mode. If multitasking is required to be
2062 implemented in the future create a new file \texttt{rpp\_mrmain.tlc} in \texttt{$<$repo$>$/rpp/rpp/} and
2063 edit \texttt{rpp\_file\_process.tlc} to use that file instead when multitasking is selected.
2065 \hypertarget{rpp_target_options}{}
2066 \subsubsection{RPP Target options}
2067 \label{sec:rpp-target-options}
2069 The RPP Target include the following configuration options, all of them configurable per model
2070 under \texttt{Code Generation} \noindent$\rightarrow$ \texttt{RPP Options}:
2073 \item \textbf{C system stack size}: this parameter is passed directly to the linker for the allocation of
2074 the stack. Note that this is the stack for the application when running outside a FreeRTOS task,
2075 normally before the scheduler has started and for system routines. Default value is 4096.
2077 \item \textbf{C system heap size}: this parameter is passed directly to the linker for the allocation of the
2079 \htmladdnormallink{Appendix A: Notes on FreeRTOS memory management}{\#appendix\_a\_notes\_on\_freertos\_memory\_management}
2080 for an important information about this parameter.
2082 \item \textbf{Model step task stack size}: this parameter will be passed to the \texttt{xTaskCreate()} that
2083 creates the task for the model to run. In a Simulink model there is always two tasks:
2085 \item The worker task. This task is the one that executes the model step. This task requires enough
2086 stack memory to execute the step. Take into account for example than only a single call to
2087 \texttt{rpp\_sci\_printf()} requires, with current configuration, 128 bytes from the stack. This value
2088 should be minor than the C system heap and leaving enough heap for the system tasks. See
2089 \htmladdnormallink{Appendix A: Notes on FreeRTOS memory management}{\#appendix\_a\_notes\_on\_freertos\_memory\_management}
2090 for more information.
2091 \item The control task. This task controls when the worker task should execute and controls overruns.
2094 \item \textbf{Download compiled binary to RPP}: if set, this option will download the generated binary to
2095 the board after the model is successfully built. Note that this option is unaware of the option
2096 \textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to upload even if
2097 only source code has been generated, failing graciously or uploading an old binary laying around
2098 in the build directory. This option calls the \texttt{rpp\_download.m} script, which is in turn a
2099 wrapper on the \texttt{loadti.sh} script. More information on the \texttt{loadti.sh} script can be found
2102 <css>/ccs_base/scripting/examples/loadti/readme.txt
2103 http://processors.wiki.ti.com/index.php/Loadti
2106 The \texttt{loadti.sh} script will close after the download of the generated program and in
2107 consequence the execution of the loaded program will stop (because it works as the CCS debug
2108 server). In order to test the loaded model a manual reset of the board is always required after a
2109 successful download.
2111 \item \textbf{Print model metadata to SCI at start}: if set this option will print a message to the Serial
2112 Communication Interface when the model start execution on the board. This is very helpful to
2113 identify the model running on the board. The message is in the form:
2115 `model_name' - generated_date (TLC tlc_version)
2120 `hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
2127 \hypertarget{simulink_block_library}{}
2128 \section{Simulink Block Library}
2132 The Simulink Block Library is a set of blocks that allows Simulink models to use board IO and
2133 communication peripherals.
2137 \hypertarget{description}{}
2138 \subsection{Description}
2142 As part of this project the ideal set was defined, but not all blocks were implemented. The
2143 following table shows the current status of the block library.
2147 \begin{center}\begin{tabular}{lllll}
2148 \textbf{CATEGORY} & \textbf{NAME} & \textbf{STATUS*} & \textbf{MNEMONIC} & \textbf{LRH*} \\
2149 System blocks & Configuration block & \texttt{X} & \texttt{[CONF]} & \texttt{RppConfig.h} \\
2150 Logic IO blocks & Digital Input block & \texttt{T} & \texttt{[DIN ]} & \texttt{rpp\_din.h} \\
2151 & Digital Output block & \texttt{T} & \texttt{[LOUT]} & \texttt{rpp\_lout.h} \\
2152 & Analog Input block & \texttt{T} & \texttt{[AIN ]} & \texttt{rpp\_ain.h} \\
2153 & Analog Output block & \texttt{T} & \texttt{[AOUT]} & \texttt{rpp\_aout.h} \\
2154 Power output blocks & H-Bridge Control block & \texttt{T} & \texttt{[HBR ]} & \texttt{rpp\_hbr.h} \\
2155 & Power output block & \texttt{T} & \texttt{[MOUT]} & \texttt{rpp\_mout.h} \\
2156 & High-Power output block & \texttt{X} & \texttt{[HOUT]} & \texttt{rpp\_hout.h} \\
2157 Communication blocks & CAN Bus receive block & \texttt{X} & \texttt{[CANR]} & \texttt{rpp\_can.h} \\
2158 & CAN Bus send msg block & \texttt{X} & \texttt{[CANS]} & - Idem - \\
2159 & LIN receive block & \texttt{X} & \texttt{[LINR]} & \texttt{rpp\_lin.h} \\
2160 & LIN send msg block & \texttt{X} & \texttt{[LINS]} & - Idem - \\
2161 & FlexRay receive block & \texttt{X} & \texttt{[FRR ]} & \texttt{rpp\_fr.h} \\
2162 & FlexRay send msg block & \texttt{X} & \texttt{[FRS ]} & - Idem - \\
2163 & SCI receive block & \texttt{T} & \texttt{[SCIR]} & \texttt{rpp\_sci.h} \\
2164 & SCI send msg block & \texttt{T} & \texttt{[SCIS]} & - Idem - \\
2165 & SCI configure block & \texttt{T} & \texttt{[SCIC]} & - Idem - \\
2166 & Ethernet receive block & \texttt{X} & \texttt{[ETHR]} & \texttt{rpp\_eth.h} \\
2167 & Ethernet send msg block & \texttt{X} & \texttt{[ETHS]} & - Idem - \\
2168 Logging/Storage blocks & SD Card write block & \texttt{T} & \texttt{[SDCW]} & \texttt{rpp\_sdc.h} \\
2169 & SDRAM write block & \texttt{X} & \texttt{[SDRW]} & \texttt{rpp\_sdr.h} \\
2170 Trigger blocks & Overrun detected block & \texttt{X} & \texttt{[TROR]} & - None - \\
2171 & Stack overflow detected block & \texttt{X} & \texttt{[TRSO]} & - None - \\
2172 & Malloc Failed detected block & \texttt{X} & \texttt{[TRMF]} & - None - \\
2173 \end{tabular}\end{center}
2176 \begin{multicols}{2}
2181 \item *LRH : Library Reference Header.
2184 \item \texttt{X} - Unimplemented. Files non present.
2185 \item \texttt{P} - Unimplemented. Files present.
2186 \item \texttt{W} - Work in progress.
2187 \item \texttt{I} - Implemented.
2188 \item \texttt{T} - Implemented and tested.
2194 \textbf{Notes:} \newline{}
2195 Each block that can detect fault condition should have a trigger output. \newline{}
2196 High-power output provides current flow as an input to the model.
2200 \hypertarget{c_mex_s_functions}{}
2201 \subsubsection{C MEX S-Functions}
2203 All of the blocks are implemented as a C Mex S-Function coded by hand. In the this section the
2204 approach taken is explained.
2209 \item C : Implemented in C language. Other options are Fortran and Matlab language itself.
2210 \item MEX: Matlab Executable. They are compiled by Matlab GCC wrapper called MEX.
2211 \item S-Function: System Function, as opposed to standard functions, or user functions.
2214 A C-MEX S-Function is a structured C file that includes the following mandatory callbacks:
2217 \item \texttt{mdlInitializeSizes}: \newline{}
2218 Specify the number of inputs, outputs, states, parameters, and other characteristics of the C
2220 \item \texttt{mdlInitializeSampleTimes}: \newline{}
2221 Specify the sample rates at which this C MEX S-function operates.
2222 \item \texttt{mdlOutputs}: \newline{}
2223 Compute the signals that this block emits.
2224 \item \texttt{mdlTerminate}: \newline{}
2225 Perform any actions required at termination of the simulation.
2228 Plus many more optional callbacks. Relevant optional callbacks are:
2231 \item \texttt{mdlCheckParameters}: \newline{}
2232 Check the validity of a C MEX S-function's parameters.
2233 \item \texttt{mdlRTW}: \newline{}
2234 Generate code generation data for a C MEX S-function.
2235 \item \texttt{mdlSetWorkWidths}: \newline{}
2236 Specify the sizes of the work vectors and create the run-time parameters required by the C MEX
2238 \item \texttt{mdlStart}: \newline{}
2239 Initialize the state vectors of the C MEX S-function.
2242 A complete list of callbacks can be found in:
2245 \htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
2249 The way a C-MEX S-Function participates in a Simulink simulation is shown by the following diagram:
2251 \begin{figure}[H]\begin{center}
2253 \noindent\includegraphics[width=250px]{media/images/sfunctions_process.png}
2254 \caption{Simulation cycle of a S-Function.}\end{center}\end{figure}
2256 In general, a S-Function can perform calculations and inputs and outputs for simulation. Because
2257 the blocks implemented for this project are for hardware peripherals control and IO the blocks are
2258 implemented as pure sink or pure source. That is, the S-Function is a descriptor of the block but
2259 does not any calculation, input or output for simulation.
2261 The S-Functions required could be implemented in several ways:
2264 \item Writing the S-Function. \newline{}
2265 Using this method, the user hand write a new C S-Function and associated TLC file. This method
2266 requires the most knowledge about the structure of a C S-Function.
2267 \item Using an S-Function Builder block. \newline{}
2268 Using this method, the user enter the characteristics of the S-function into a block dialog. This
2269 method does not require any knowledge about writing S-Functions. However, a basic understanding
2270 of the structure of an S-Function can make the S-Function Builder dialog box easier to use.
2271 \item Using the Legacy Code Tool (LCT). \newline{}
2272 Using this command line method, the user define the characteristics of your S-function in a data
2273 structure in the MATLAB workspace. This method requires the least amount of knowledge about
2277 From the above, the LCT is a tool that can be called within Matlab workshop that allows to generate
2278 source code for S-Functions given the descriptor of a C function call. This approach is used by
2279 most of the other targets reviewed for this project. The descriptor is a Matlab file with
2280 definitions like the following:
2283 \begin{lstlisting}[language=Matlab]
2285 % Populate legacy_code structure with information
2286 GPIOWrite = legacy_code('initialize');
2287 GPIOWrite.SFunctionName = 'sfun_GPIOWrite';
2288 GPIOWrite.HeaderFiles = {'gpiolct.h'};
2289 GPIOWrite.SourceFiles = {'gpiolct.c'};
2290 GPIOWrite.OutputFcnSpec = 'GPIOWrite(uint32 p1, uint8 u1, uint8 u2)';
2291 % Support calling from within For-Each subsystem
2292 GPIOWrite.Options.supportsMultipleExecInstances = true;
2295 The interface and implementation files specified should hold the declaration and implementation of
2296 the \texttt{OutputFcnSpec} function. This tool will generate a simple S-Function that will input and
2297 output the values required by that function. This approach was \textbf{not} for this project, mainly
2301 \item The RPP Library requires that after some actions (like setting one LOUT output) the changes are
2302 committed to the hardware, or before some other actions (like getting the value from DIN using
2303 the fixed threshold) the values cached are updated. And the implementation of a wrapper function
2304 that would update or commit the changes wasn't considered because of the efficiency impact it
2307 \item Furthermore, the error handling of the function call is not considered, and for some blocks
2308 (like MOUT and HOUT) the diagnostic handling is mandatory.
2310 \item Also, the dialog parameters of the S-Function cannot be validated otherwise than data type
2311 (cannot validate range, for example).
2313 \item For future improvements the LCT cannot generate code for simulation, and a lot of S-Function
2314 options cannot not be fine tuned.
2316 \item Finally, the generated code is very obscure, hard to read and to maintain in case the above
2317 functionality had to be implemented on top of the generated code.
2320 Similarly the hand written S-Functions shares a large amount of code like parameters scalar, data
2321 type and range validation, standard options for this kind of blocks, unused functions, among other.
2322 Because of this a mini framework for writing S-Functions for RPP was implemented in the form of two
2323 files that are directly included at the beginning and end of the S-Function implementation:
2324 \texttt{header.c} and \texttt{trailer.c}.
2326 This mini-framework reduces the amount of required code for each S-Function considerably, making
2327 easier to maintain and adapt. Because each S-Function is a program by itself there is no need to
2328 use interface files and the files are directly included.
2331 The final form of the S-Function is a C file of around 100 lines of code with the following layout:
2334 \item Define S-Function name \texttt{S\_FUNCTION\_NAME}.
2336 \item Include header file \texttt{header.c}.
2338 \item In \texttt{mdlInitializeSizes} define:
2340 \item Number of \textit{dialog} parameter.
2341 \item Number of input ports.
2343 \item Data type of each input port.
2345 \item Number of output ports.
2347 \item Data type of each output port.
2349 \item Standard options for driver blocks.
2352 \item In \texttt{mdlCheckParameters}:
2354 \item Check data type of each parameter.
2355 \item Check range, if applicable, of each parameter.
2358 \item In \texttt{mdlSetWorkWidths}:
2360 \item Map \textit{dialog} parameter to \textit{runtime} parameters.
2362 \item Data type of each \textit{runtime} parameter.
2366 \item Define symbols for unused functions.
2368 \item Include trailer file \texttt{trailer.c}.
2371 The C-MEX S-Function implemented can be compile with the following command:
2373 \lstset{language=bash}
2375 <matlabroot>/bin/mex sfunction_{mnemonic}.c
2378 As noted the standard is to always prefix S-Function with \texttt{sfunction\_} and use lower case
2379 mnemonic of the block.
2381 Also a script called \texttt{compile\_blocks.m} is included that allows all \texttt{sfunctions\_*.c} to be fed
2382 to the \texttt{mex} compiler so all S-Functions are compiled at once. To use this script, in Matlab do:
2384 \lstset{language=Matlab}
2386 cd <repo>/rpp/blocks/
2392 \hypertarget{target_language_compiler_files}{}
2393 \subsubsection{Target Language Compiler files}
2395 C code generated from a Simulink model is placed on a file called \texttt{$<$modelname$>$.c} along with
2396 other support files in a folder called \texttt{$<$modelname$>$\_$<$target$>$/}. For example, the source code
2397 generated for model \texttt{foobar} will be placed in current Matlab directory \texttt{foobar\_rpp/foobar.c}.
2399 The file \texttt{$<$modelname$>$.c} has 3 main functions:
2402 \item \texttt{void $<$modelname$>$\_step(void)}: \newline{}
2403 This function recalculates all the outputs of the blocks and should be called once per step. This
2404 is the main working function.
2405 \item \texttt{void $<$modelname$>$\_initialize(void)}: \newline{}
2406 This function is called only once before the first step is issued. Default values for blocks IOs
2407 should be placed here.
2408 \item \texttt{void $<$modelname$>$\_terminate(void)}: \newline{}
2409 This function is called when terminating the model. This should be used to free memory of revert
2410 other operations made on the initialization function. With current implementation this function
2411 should never be called unless an errors is detected and in most models it is empty.
2414 In order to generate code for each one of those functions each S-Function implement a TLC file
2415 for \textit{inlining} the S-Function on the generated code. The TLC files are files that describe how to
2416 generate code for a specific C-MEX S-Function block. They are programmed using TLC own language and
2417 include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX
2420 TLC files are located under \texttt{$<$repo$>$/rpp/blocks/tlc\_c/} directory. For a diagram on how TLC files
2421 work see \htmladdnormallink{Code generation process}{\#code\_generation\_process} section.
2423 The standard for a TLC file is to be located under the \texttt{tlc\_c} subfolder from where the
2424 S-Function is located and to use the very exact file name as the S-Function but with the \texttt{.tlc}
2427 \texttt{sfunction\_foo.c} \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_foo.tlc}
2429 The TLC files implemented for this project use 3 hook functions in particular (other are available,
2430 see TLC reference documentation):
2433 \item \texttt{BlockTypeSetup}: \newline{}
2434 BlockTypeSetup executes once per block type before code generation begins.
2435 This function can be used to include elements required by this block type, like includes or
2438 \item \texttt{Start}: \newline{}
2439 Code here will be placed in the \texttt{void $<$modelname$>$\_initialize(void)}. Code placed here will
2442 \item \texttt{Outputs}: \newline{}
2443 Code here will be placed in the \texttt{void $<$modelname$>$\_step(void)} function. Should be used to
2444 get the inputs o a block and/or to set the outputs of that block.
2447 The general layout of the TLC files implemented for this project are:
2450 \item In \texttt{BlockTypeSetup}: \newline{}
2451 Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
2452 \texttt{rpp/rpp.h} header file (can be called multiple times but header is included only once).
2454 \item \texttt{Start}: \newline{}
2455 Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup,
2456 AOUT value initialization, SCI baud rate setup, among others.
2458 \item \texttt{Outputs}: \newline{}
2459 Call common IO routines from RPP Layer, like DIN read, AOUT set, etc. Success of this functions
2460 is checked and in case of failure error is reported to the block using ErrFlag.
2465 \hypertarget{subdirectory__content_description}{}
2466 \subsection{Subdirectory content description}
2468 \noindent$\rightarrow$ \texttt{header.c} and \texttt{trailer.c}
2470 RPP framework for simple S-Functions.
2472 This files are included at the head and tail of each S-Function file. They include refactored and
2473 commonly repeated structures that pollute S-Functions implementations. They include basic includes,
2474 required definitions, macro definitions, common functions implementations and documentation on
2475 optional functions and commented prototypes for optional model calls/hooks.
2478 \item \underline{Reference:}
2480 \item See header of those files.
2484 \noindent$\rightarrow$ \texttt{sfunction\_\{mnemonic\}.c}
2486 C-MEX S-Function implementation for \{mnemonic\} block.
2488 This file implements the \{mnemonic\} block using C-MEX S-Function API. See the reference for
2489 information about the S-Function API.
2492 \item \underline{Reference:}
2494 \item \texttt{$<$repo$>$/refs/sfunctions.pdf}
2498 \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_\{mnemonic\}.tlc}
2500 Target Language Compiler (TLC) file for \{mnemonic\} block.
2502 This file implements the C code inlining for \{mnemonic\} block. See the reference for information
2506 \item \underline{Reference:}
2508 \item \texttt{$<$repo$>$/refs/rtw\_tlc.pdf}
2512 \noindent$\rightarrow$ \texttt{tlc\_c/common.tlc}
2514 Common TLC functions.
2516 This file implements common TLC functions used by all the blocks.
2519 \item \underline{Reference:}
2526 \noindent$\rightarrow$ \texttt{slblocks.m}
2528 Simulink library control file.
2530 This file allows a group of blocks to be integrated into the Simulink Library and Simulink Library
2531 Browser. This file is required by Simulink in order to interpret this folder as a block library.
2532 For information about this file see the references.
2535 \item \underline{Reference:}
2537 \item \texttt{$<$repo$>$/refs/rtw\_ug.pdf} p. 1127
2541 \noindent$\rightarrow$ \texttt{rpp\_lib.slx}
2543 RPP Simulink block library.
2545 Simulink block library that includes all the blocks. This file is referenced by \texttt{slblocks.m}
2548 \item \underline{Reference:}
2554 \noindent$\rightarrow$ compile\_blocks.m
2556 Blocks compilation script.
2558 This script compiles all the sfunction blocks to MEX executables. This script is called by the
2559 \texttt{rpp\_setup()} function in order make all the blocks available to the Simulink environment or it
2560 can be called independently when developing S-Functions.
2563 \item \underline{Reference:}
2571 \hypertarget{block_library_reference}{}
2572 \subsection{Block Library Reference}
2574 This section describes each one of the Simulink blocks implements as part of this project:
2576 \begin{figure}[H]\advance\leftskip-1cm
2578 \noindent\includegraphics[width=530px]{media/images/block_library.png}
2579 \caption{Simulink RPP Block Library.}\end{figure}
2583 \hypertarget{din_digital_input_block}{}
2584 \subsubsection{DIN Digital Input block}
2595 uint8 Pin number [1-16]
2596 bool Use variable threshold
2599 This block allows to read the digital inputs on the RPP board. The variable threshold check change
2600 the read mode of the pin. The ErrFlag should raise if \texttt{rpp\_din\_update()} or \texttt{rpp\_din\_get()}
2601 returns error. \texttt{rpp\_din\_update()} is called just by the first DIN block in the model and thus
2602 only the first block could raise the flag because of this. In case an errors occurs the return
2603 value will always be LOW (0). Because the ErrFlag should never set, once set the following steps
2604 will never clear it back.
2606 \begin{multicols}{3}
2609 \item \textbf{Tested}:
2611 \item Changing the pin.
2612 \item Compilation and general use.
2613 \item Using variable threshold.
2620 \item \textbf{Untested}:
2622 \item Faulty situation for the ErrFlag to set.
2629 \item \textbf{Not working}:
2634 \textbf{RPP API functions used:}
2637 \item \texttt{rpp\_din\_setup()}.
2638 \item \texttt{rpp\_din\_update()}.
2639 \item \texttt{rpp\_din\_get()}.
2642 \textbf{Relevant demos:}
2645 \item \texttt{digital\_passthrough}.
2646 \item \texttt{hbridge\_digital\_control}.
2651 \hypertarget{lout_digital_output_block}{}
2652 \subsubsection{LOUT Digital Output block}
2662 uint8 Pin number [1-8]
2665 This block allows to write to the digital outputs on the RPP board. The ErrFlag should raise if
2666 \texttt{rpp\_lout\_set()} or \texttt{rpp\_lout\_update()} returns error. Because the ErrFlag should never set,
2667 once set the following steps will never clear it back. \texttt{rpp\_lout\_update()} is called on each
2668 block, which is not the most efficient but guaranties consistent behavior.
2671 \begin{multicols}{3}
2674 \item \textbf{Tested}:
2676 \item Changing the pin.
2677 \item Compilation and general use.
2684 \item \textbf{Untested}:
2686 \item Faulty situation for the ErrFlag to set.
2693 \item \textbf{Not working}:
2698 \textbf{RPP API functions used:}
2701 \item \texttt{rpp\_lout\_set()}.
2702 \item \texttt{rpp\_lout\_update()}.
2705 \textbf{Relevant demos:}
2708 \item \texttt{digital\_passthrough}.
2709 \item \texttt{led\_blink\_all}.
2710 \item \texttt{led\_blink}.
2715 \hypertarget{ain_analog_input_block}{}
2716 \subsubsection{AIN Analog Input block}
2727 uint8 Pin number [1-12]
2730 This block allows to read the analog inputs on the RPP board. The ErrFlag should if raise
2731 \texttt{rpp\_ain\_update()} or \texttt{rpp\_ain\_get()} returns error. \texttt{rpp\_ain\_update()} is called just by the
2732 first DIN block in the model and thus only the first block could raise the flag because of this.
2733 In case an errors occurs the return value will always be 0. Because the ErrFlag should never set,
2734 once set the following steps will never clear it back.
2737 \begin{multicols}{3}
2740 \item \textbf{Tested}:
2742 \item Changing the pin.
2743 \item Compilation and general use.
2750 \item \textbf{Untested}:
2752 \item Faulty situation for the ErrFlag to set.
2759 \item \textbf{Not working}:
2764 \textbf{RPP API functions used:}
2767 \item \texttt{rpp\_ain\_update()}.
2768 \item \texttt{rpp\_ain\_get()}.
2771 \textbf{Relevant demos:}
2774 \item \texttt{analog\_passthrough}.
2775 \item \texttt{hbridge\_analog\_control}.
2776 \item \texttt{log\_analog\_input}.
2781 \hypertarget{aout_analog_output_block}{}
2782 \subsubsection{AOUT Analog Output block}
2786 uint16 Analog Output
2792 uint8 Pin number [1-4]
2796 This block allows to write to the analog outputs on the RPP board. The UseVoltage flag allows the
2797 user to configure if block inputs should be interpreted as raw DAC value or millivolts. The ErrFlag
2798 should raise if \texttt{rpp\_aout\_update()} or \texttt{rpp\_aout\_set()} (or \texttt{rpp\_aout\_set\_voltage()}
2799 depending on block configuration) returns error. Because the ErrFlag should never set, once set the
2800 following steps will never clear it back.
2802 \texttt{rpp\_aout\_update()} is called on each block but the implementation provides this to be efficient.
2804 There is a know bug on the RPP Library, check \texttt{rpp\_aout\_update()} on the RPP API for details.
2805 Because of this, the outputs of the DACs are initialized on the first step of the model and not on
2806 the model initialization.
2809 \begin{multicols}{3}
2812 \item \textbf{Tested}:
2814 \item Changing the pin.
2815 \item Changing voltage/value flag.
2816 \item Compilation and general use.
2823 \item \textbf{Untested}:
2825 \item Faulty situation for the ErrFlag to set.
2832 \item \textbf{Not working}:
2834 \item Initializing DACs on model's initialization.
2840 \textbf{RPP API functions used:}
2843 \item \texttt{rpp\_aout\_setup()}.
2844 \item \texttt{rpp\_aout\_set()}, or
2845 \item \texttt{rpp\_aout\_set\_voltage()}.
2846 \item \texttt{rpp\_aout\_update()}.
2849 \textbf{Relevant demos:}
2852 \item \texttt{analog\_passthrough}.
2853 \item \texttt{analog\_sinewave}.
2858 \hypertarget{hbr_h_bridge_control_block}{}
2859 \subsubsection{HBR H-Bridge Control block}
2872 This block allows to control the H-Bridge on the RPP board. The ErrFlag should raise only if
2873 \texttt{rpp\_hbr\_control()} returns error. The H-Bridge is initialized with the default frequency
2874 (\~{}18kHz). A future improvement could include a parameter to set the frequency. Because the ErrFlag
2875 should never set, once set the following steps will never clear it back.
2878 \begin{multicols}{3}
2881 \item \textbf{Tested}:
2883 \item Compilation and general use.
2890 \item \textbf{Untested}:
2892 \item Faulty situation for the ErrFlag to set.
2899 \item \textbf{Not working}:
2904 \textbf{RPP API functions used:}
2907 \item \texttt{rpp\_hbr\_enable()}.
2908 \item \texttt{rpp\_hbr\_control()}.
2911 \textbf{Relevant demos:}
2914 \item \texttt{hbridge\_analog\_control}.
2915 \item \texttt{hbridge\_digital\_control}.
2916 \item \texttt{hbridge\_sinewave\_control}.
2921 \hypertarget{mout_power_output_block}{}
2922 \subsubsection{MOUT Power Output block}
2932 uint8 Pin number [1-6]
2935 This block allows to write the power outputs (2A) on the RPP board. The ErrFlag should raise only
2936 if \texttt{rpp\_mout\_set()}returns error. Note that \texttt{rpp\_mout\_set()} returns error only if some bad
2937 parameter or in case it could detect a faulty condition on the pin in a very very short period of
2938 time after setting the value, see the function API for details. If the faulty condition persist on
2939 the next step the call will successfully detect the faulty condition and ErrFlag should set.
2940 Because the ErrFlag should never set, once set the following steps will never clear it back.
2943 \begin{multicols}{3}
2946 \item \textbf{Tested}:
2948 \item Changing the pin.
2949 \item Compilation and general use.
2956 \item \textbf{Untested}:
2958 \item Faulty situation for the ErrFlag to set.
2965 \item \textbf{Not working}:
2970 \textbf{RPP API functions used:}
2973 \item \texttt{rpp\_mout\_set()}.
2976 \textbf{Relevant demos:}
2979 \item \texttt{power\_toggle}.
2984 \hypertarget{scir_serial_comm_interface_receive}{}
2985 \subsubsection{SCIR Serial Comm. Interface Receive}
2999 This block allows to receive a byte from the SCI. The ErrFlag should raise if \texttt{rpp\_sci\_read\_nb()}
3000 doesn't succeed. The behavior of the ErrFlag is different from others blocks in that this block
3001 will set or clear the flag if the call fails of success at each step. Note that this block uses the
3002 non-blocking call to read the SCI and thus will never cause an overrun.
3005 \begin{multicols}{3}
3008 \item \textbf{Tested}:
3010 \item Receiving data.
3011 \item Compilation and general use.
3012 \item Faulty situation for the ErrFlag to set.
3019 \item \textbf{Untested}:
3025 \item \textbf{Not working}:
3030 \textbf{RPP API functions used:}
3033 \item \texttt{rpp\_sci\_read\_nb()}.
3036 \textbf{Relevant demos:}
3039 \item \texttt{echo\_char}.
3044 \hypertarget{scis_serial_comm_interface_send}{}
3045 \subsubsection{SCIS Serial Comm. Interface Send}
3056 string PrintFormat [SETTING]
3059 This block allows to send a byte to the SCI or to print a formatted string that uses that byte. The
3060 UsePrintf flag allows to user to select \texttt{rpp\_sci\_write\_nb()} (raw send) or \texttt{rpp\_sci\_printf()}
3061 (formatted print) as the function the block should use on code generation. If UsePrintf is set the
3062 PrintFormat string parameters SETTING is used as the format specifier. Note that this value is
3063 inserted raw between quotes on code generation and thus there is no validation on it. User should
3064 always put any valid integer specifier for the value on the input of the block.
3066 The behavior of this block depends if UsePrintf is set or not. If set, the call \texttt{rpp\_sci\_printf()}
3067 (a blocking call) could potentially overrun the step. Also, the ErrFlag will set only if
3068 \texttt{rpp\_sci\_printf()} returns an error, and because it should never set, once set it will never
3069 clear back. On the contrary, if UsePrintf is clear, the call \texttt{rpp\_sci\_write\_nb()} (non-blocking)
3070 is used and thus the step cannot be overrun, but because is a best-effort call it cannot guarantee
3071 that all the data will be sent. In the case that not all data could be sent, the ErrFlag will set,
3072 but it will clear back if the next step is able to send all it's data (which with the current
3073 implementation is just one byte).
3075 A possible future improvement for this block is to allow input to be non-scalar so user can print a
3076 whole string in one step using raw non-blocking write. This is currently possible if input
3077 configuration is adapted in S-Function and TLC. The problem this could pose is is that for printf
3078 user should include specifiers for all the cells in the non-scalar input, and if unknown, then
3079 printf cannot be used.
3082 \begin{multicols}{3}
3085 \item \textbf{Tested}:
3088 \item Compilation and general use.
3095 \item \textbf{Untested}:
3097 \item Faulty situation for the ErrFlag to set.
3104 \item \textbf{Not working}:
3109 \textbf{RPP API functions used:}
3112 \item \texttt{rpp\_sci\_write\_nb()}, or \texttt{rpp\_sci\_printf()}.
3115 \textbf{Relevant demos:}
3118 \item \texttt{echo\_char} and \texttt{hello\_world}.
3123 \hypertarget{scic_serial_comm_interface_configure}{}
3124 \subsubsection{SCIC Serial Comm. Interface Configure}
3137 This block allows to configure the baud rate of the SCI. There should only one block of this type
3138 per model, and this requirement is not validated, but the inclusion of several blocks is harmless
3139 and will just produce the baud rate to be changed several times, being the final baud rate to be
3140 the one of the last executed block. This block just executes on model initialization and not on
3144 \begin{multicols}{3}
3147 \item \textbf{Tested}:
3149 \item Changing baud rate.
3150 \item Compilation and general use.
3157 \item \textbf{Untested}:
3159 \item Using more than one block in a model.
3166 \item \textbf{Not working}:
3171 \textbf{RPP API functions used:}
3174 \item \texttt{rpp\_sci\_setup()}.
3177 \textbf{Relevant demos:}
3180 \item \texttt{echo\_char}.
3181 \item \texttt{hello\_world}.
3186 \hypertarget{sdrw_sd_ram_write}{}
3187 \subsubsection{SDRW SD-RAM Write}
3198 string PrintFormat [SETTING]
3201 This block allows to log a double value to the SD-RAM. User needs to provide a valid PrintFormat
3202 string to format and register the double value on the log. The PrintFormat string should include
3206 \item For the block ID. Any valid integer specifier.
3207 \item For the value to log. Any valid double specifier.
3210 Note that the value of PrintFormat is inserted raw between quotes on code generation and thus there
3211 is no validation on it. Error to provide a valid PrintFormat could generate compilation errors on
3212 even run-time errors (normally this generates a warning on compile time). Note that the function
3213 for logging used is \texttt{rpp\_sdr\_printf()}, which is a blocking call, and can potentially overrun the
3214 step. The ErrFlag will set if \texttt{rpp\_sdr\_printf()} returns an error (for example out of memory),
3215 but will clear back if the next step the call to this function is successful.
3218 \begin{multicols}{3}
3221 \item \textbf{Tested}:
3224 \item Compilation and general use.
3231 \item \textbf{Untested}:
3233 \item Faulty situation for the ErrFlag to set.
3240 \item \textbf{Not working}:
3245 \textbf{RPP API functions used:}
3248 \item \texttt{rpp\_sdr\_printf()}.
3251 \textbf{Relevant demos:}
3254 \item \texttt{log\_analog\_input}.
3259 \hypertarget{simulink_demos_library}{}
3260 \section{Simulink Demos Library}
3262 The Simulink RPP Demo Library is a set of Simulink models that use blocks from the Simulink RPP
3263 Block Library and generates code using the Simulink RPP Target.
3265 \hypertarget{description}{}
3266 \subsection{Description}
3268 This demos library is used as a test suite for the Simulink RPP Block Library but they are also
3269 intended to show basic programs built using it. Because of this, the demos try to use more than one
3270 type of block and more than one block per block type.
3272 The following table shows the current status of the demos:
3274 \begin{center}\begin{tabular}{|l|l|l|}
3275 \hline \textbf{Name} & \textbf{Implemented} & \textbf{Tested} \\
3276 \hline analog\_passthrough & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3277 \hline analog\_sinewave & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3278 \hline digital\_passthrough & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3279 \hline echo\_char & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3280 \hline hbridge\_analog\_control & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3281 \hline hbridge\_digital\_control & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3282 \hline hbridge\_sinewave\_control & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3283 \hline hello\_world & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3284 \hline led\_blink\_all & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3285 \hline led\_blink & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3286 \hline log\_analog\_input & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3287 \hline power\_toggle & \multicolumn{1}{|c|}{YES} & \multicolumn{1}{|r|}{SUCCESS} \\
3288 \hline \end{tabular}\end{center}
3290 In the reference below you can find a complete description for each of the demos.
3292 \hypertarget{subdirectory__content_description}{}
3293 \subsection{Subdirectory content description}
3295 \noindent$\rightarrow$ \texttt{\{demo\}.slx}
3299 This subdirectory just includes all the Simulink demos described in the following section.
3303 \hypertarget{demos_reference}{}
3304 \subsection{Demos Reference}
3306 This section describes the demos implemented as part of this project that uses the Simulink RRP
3307 Block Library and generates code using the RPP Simulink Target.
3309 \hypertarget{analog_pass_through}{}
3310 \subsubsection{Analog pass-through}
3312 \begin{figure}[H]\begin{center}
3314 \noindent\includegraphics[width=450px]{media/images/demo_analog_passthrough.png}
3315 \caption{Analog Passthrough Simulink demo for RPP.}\end{center}\end{figure}
3317 \textbf{Description:}
3319 This demo will read analog input 1 and write it to analog output 1.
3321 In laboratory the minimum read value for analog input a 0 volts is 107. The maximum read at 12
3322 volts is 2478. The map subsystem will map the input domain (AIN)\texttt{[110, 2400]} to the output domain
3323 (AOUT)\texttt{[0, 4095]}.
3327 \hypertarget{analog_sinewave}{}
3328 \subsubsection{Analog sinewave}
3330 \begin{figure}[H]\begin{center}
3332 \noindent\includegraphics[width=450px]{media/images/demo_analog_sinewave.png}
3333 \caption{Analog Sinewave Simulink demo for RPP.}\end{center}\end{figure}
3335 \textbf{Description:}
3337 This demo will generate a sinewave on analog output 1. Siwave is 10Hz and sampling rate is set to
3338 1000Hz (driven from Simulink step of 1ms, same as operating system). Amplitude is set to use AOUT
3339 full range [0-4095] which means output amplitude will be [0-12] volts.
3341 The Software oscilloscope shown should match an external one connected to AOUT 1.
3343 Note that the driver configuration of the MCP4922 is set to unbuffered (which should eventually
3344 be changed to buffered) and thus the last resolution millivolts are lost.
3348 \hypertarget{digital_pass_through}{}
3349 \subsubsection{Digital pass-through}
3351 \begin{figure}[H]\begin{center}
3353 \noindent\includegraphics[width=400px]{media/images/demo_digital_passthrough.png}
3354 \caption{Digital Pass-through Simulink demo for RPP.}\end{center}\end{figure}
3356 \textbf{Description:}
3358 This demo will directly pass the digital values read on DIN [1-8] to LOUT [1-8], and thus acting
3359 as a digital pass-through or gateway.
3361 Also note that all the ErrFlag are aggregated on a global ErrFlag.
3365 \hypertarget{echo_char}{}
3366 \subsubsection{Echo char}
3368 \begin{figure}[H]\begin{center}
3370 \noindent\includegraphics[width=450px]{media/images/demo_echo_char.png}
3371 \caption{Echo Character Simulink demo for RPP.}\end{center}\end{figure}
3373 \textbf{Description:}
3375 This demo will echo twice (print back) any character received through the Serial Communication
3376 Interface (9600-8-N-1).
3378 Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
3379 if data is received, that is, Serial Receive output is non-negative. Negative values are errors.
3383 \hypertarget{h_bridge_analog_control}{}
3384 \subsubsection{H-bridge analog control}
3386 \begin{figure}[H]\begin{center}
3388 \noindent\includegraphics[width=450px]{media/images/demo_hbridge_analog_control.png}
3389 \caption{H-Bridge Analog Control Simulink demo for RPP.}\end{center}\end{figure}
3391 \textbf{Description:}
3393 This demo will read values from the analog input, map them, and control the H-Bridge. This allows
3394 a motor connected to the H-Bridge to be controlled with a potentiometer connected to Analog Input 1.
3396 Setting the potentiometer to output around 6 volts will stop the motor. Less (or greater) than 6
3397 volts will trigger the motor in one sense (or in the other sense) and speed proportional with 1\%
3400 In laboratory the minimum read value for analog input is 107 at 0 volts. The maximum read at 12 volts
3401 is 2478. The map subsystem will map the input domain (AIN)\texttt{[110, 2400]} to the output domain
3402 (HBR)\texttt{[-1.0, 1.0]}.
3406 \hypertarget{h_bridge_digital_control}{}
3407 \subsubsection{H-bridge digital control}
3409 \begin{figure}[H]\begin{center}
3411 \noindent\includegraphics[width=450px]{media/images/demo_hbridge_digital_control.png}
3412 \caption{H-Bridge Digital Control Simulink demo for RPP.}\end{center}\end{figure}
3414 \textbf{Description:}
3416 This demo toggle the H-Bridge from stop to full speed in one direction using digital input 1.
3417 So basically is a ON/OFF switch on DIN 1 for a motor connected on the HBR. Note the data type
3418 conversion because the output of the DIN is a boolean and the input to the HBR is a double.
3422 \hypertarget{h_bridge_sine_wave_control}{}
3423 \subsubsection{H-bridge sine wave control}
3425 \begin{figure}[H]\begin{center}
3427 \noindent\includegraphics[width=300px]{media/images/demo_hbridge_sinewave_control.png}
3428 \caption{H-Bridge Sinewave Control Simulink demo for RPP.}\end{center}\end{figure}
3430 \textbf{Description:}
3432 This demo will generate a sine wave to control the H-Bridge. Sine wave is one period per 20
3433 seconds or 0.05Hz. Sampling rate is 20Hz or 100 samples per 1/4 of period (for 1\% speed
3436 Note that the Software oscilloscope should is not the output of the H-Bridge, the H-Bridge will
3437 change current sense and the duty cycle of the pulse that drive it (PWM), it does not output
3438 analog values. The Software oscilloscope just shows what the input to the HBR block is.
3442 \hypertarget{hello_world}{}
3443 \subsubsection{Hello world}
3445 \begin{figure}[H]\begin{center}
3447 \noindent\includegraphics[width=450px]{media/images/demo_hello_world.png}
3448 \caption{Hello World Simulink demo for RPP.}\end{center}\end{figure}
3450 \textbf{Description:}
3452 This demo will print \texttt{"Hello Simulink"} to the Serial Communication Interface (9600-8-N-1) one
3453 character per second. The output speed is driven by the Simulink model step which is set to one
3458 \hypertarget{led_blink}{}
3459 \subsubsection{LED blink}
3461 \begin{figure}[H]\begin{center}
3463 \noindent\includegraphics[width=450px]{media/images/demo_led_blink.png}
3464 \caption{LED Blink Simulink demo for RPP.}\end{center}\end{figure}
3466 \textbf{Description:}
3468 This the simplest demo of all that shows the basics of using the RPP target and blocks. The
3469 goal of this demo is to show the configuration of the model (not shown on the picture above),
3470 that is, how the RPP Simulink Coder Target is setup, general model setup and step setup.
3472 This demo will toggle each second a LED connected on LOUT 1. The timing is set by the Simulink
3473 model step which is set to 1 second.
3477 \hypertarget{led_blink_all}{}
3478 \subsubsection{LED blink all}
3480 \begin{figure}[H]\begin{center}
3482 \noindent\includegraphics[width=350px]{media/images/demo_led_blink_all.png}
3483 \caption{LED Blink All Simulink demo for RPP.}\end{center}\end{figure}
3485 \textbf{Description:}
3487 This demo will toggle all LEDs connected to the LOUT port. Even outputs pins will be negated.
3488 Toggle will happen each second. The timing is driven by Simulink model step configuration that
3489 is set to 1 second. All blocks ErrFlags are aggregated into one global ErrFlag.
3493 \hypertarget{log_analog_input}{}
3494 \subsubsection{Log analog input}
3496 \begin{figure}[H]\begin{center}
3498 \noindent\includegraphics[width=450px]{media/images/demo_log_analog_input.png}
3499 \caption{Log Analog Input Simulink demo for RPP.}\end{center}\end{figure}
3501 \textbf{Description:}
3503 This demo will log once per second the value read on the analog input 1. User can read the log
3504 using the SCI logging integrated command processor (9600-8-N-1). Logging block ID set to 1. The
3505 timing is driven by Simulink model step configuration that is set to 1 second.
3509 \hypertarget{power_toggle}{}
3510 \subsubsection{Power toggle}
3512 \begin{figure}[H]\begin{center}
3514 \noindent\includegraphics[width=300px]{media/images/demo_power_toggle.png}
3515 \caption{Power Toggle Simulink demo for RPP.}\end{center}\end{figure}
3517 \textbf{Description:}
3519 This demo will toggle the power output once per second. If an error is detected on at least one of
3520 the outputs a generic error message is printed to the serial line. The timing is driven by Simulink
3521 model step configuration that is set to 1 second. Power outputs can drive a load up to 2A, so please
3522 take into account required safety considerations.
3526 \hypertarget{glossary}{}
3531 \textit{Analog to Digital Converter.} \newline{}
3532 Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
3533 digital number that represents the quantity's amplitude.
3536 \textit{Analog Input.} \newline{}
3537 Mnemonic to refer to or something related to the analog input (ADC) hardware module.
3540 \textit{Analog Output.} \newline{}
3541 Mnemonic to refer to or something related to the analog output (DAC) hardware module.
3544 \textit{Controller Area Network.} \newline{}
3545 The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
3546 communicate with each other within a vehicle without a host computer.
3547 In this project it is also used as mnemonic to refer to or something related to the CAN
3551 \textit{Code Generation Tools.} \newline{}
3552 Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
3553 assemble, archive, among others. In this project is normally used as synonym for
3554 ``Texas Instruments ARM compiler and linker."
3557 \textit{Digital to Analog Converter.} \newline{}
3558 Hardware circuitry that converts a digital (usually binary) code to an analog signal
3559 (current, voltage, or electric charge).
3562 \textit{Digital Input.} \newline{}
3563 Mnemonic to refer to or something related to the digital input hardware module.
3566 \textit{Engine Control Unit.} \newline{}
3567 A type of electronic control unit that controls a series of actuators on an internal combustion
3568 engine to ensure the optimum running.
3571 \textit{Ethernet.} \newline{}
3572 Mnemonic to refer to or something related to the Ethernet hardware module.
3575 \textit{FlexRay.} \newline{}
3576 FlexRay is an automotive network communications protocol developed to govern on-board automotive
3578 In this project it is also used as mnemonic to refer to or something related to the FlexRay
3582 \textit{General Purpose Input/Output.} \newline{}
3583 Generic pin on a chip whose behavior (including whether it is an input or output pin) can be
3584 controlled (programmed) by the user at run time.
3587 \textit{H-Bridge.} \newline{}
3588 Mnemonic to refer to or something related to the H-Bridge hardware module. A H-Bridge is
3589 an electronic circuit that enables a voltage to be applied across a load in either direction.
3592 \textit{High-Power Output.} \newline{}
3593 Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
3594 output hardware module.
3597 \textit{Integrated Development Environment.} \newline{}
3598 An IDE is a Software application that provides comprehensive facilities to computer programmers
3599 for software development.
3602 \textit{Legacy Code Tool.} \newline{}
3603 Matlab tool that allows to generate source code for S-Functions given the descriptor of a C
3607 \textit{Local Interconnect Network.} \newline{}
3608 The LIN is a serial network protocol used for communication between components in vehicles.
3609 In this project it is also used as mnemonic to refer to or something related to the LIN
3613 \textit{Logic Output.} \newline{}
3614 Mnemonic to refer to or something related to the digital output hardware module.
3615 It is logic output (100mA), as opposed to power outputs (2A, 10A).
3618 \textit{Model-Based Design.} \newline{}
3619 Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
3620 with designing complex control, signal processing and communication systems.
3623 \textit{Matlab Executable.} \newline{}
3624 Type of binary executable that can be called within Matlab. In this document the common term
3625 used is `C MEX S-Function", which means Matlab executable written in C that implements a system
3629 \textit{(Motor) Power Output.} \newline{}
3630 Mnemonic to refer to or something related to the 2A push/pull power output hardware module.
3633 \textit{Pulse-width modulation.} \newline{}
3634 Technique for getting analog results with digital means. Digital control is used to create a
3635 square wave, a signal switched between on and off. This on-off pattern can simulate voltages
3636 in between full on and off by changing the portion of the time the signal spends on versus
3637 the time that the signal spends off. The duration of ``on time" is called the pulse width or
3638 \textit{duty cycle}.
3641 \textit{Rapid Prototyping Platform.} \newline{}
3642 Name of the automotive hardware board. Also generic term to define something related
3643 to the board, like the RPP Library, RPP Layer, RPP API, etc.
3646 \textit{Serial Communication Interface.} \newline{}
3647 Serial Interface for communication through hardware's UART using communication standard RS-232.
3648 In this project it is also used as mnemonic to refer to or something related to the Serial
3649 Communication Interface hardware module.
3652 \textit{SD-Card.} \newline{}
3653 Mnemonic to refer to or something related to the SD-Card hardware module.
3656 \textit{SD-RAM.} \newline{}
3657 Mnemonic to refer to or something related to the SD-RAM hardware module for logging.
3660 \textit{Target Language Compiler.} \newline{}
3661 Technology and language used to generate code in Matlab/Simulink.
3664 \textit{Universal Asynchronous Receiver/Transmitter.} \newline{}
3665 Hardware circuitry that translates data between parallel and serial forms.
3670 \hypertarget{references}{}
3671 \section{References}
3674 \item Horn, M. (2013). \textit{Software obsluhující periferie a flexray na automobilové rídicí jednotce}.
3675 (Unpublished master's thesis, Czech Technical University in Prague, Prague, Czech Republic).
3677 \item \textit{Model-based design}. (n.d.). In Wikipedia. Retrieved March 10, 2013, from \newline{}
3678 \htmladdnormallink{http://en.wikipedia.org/wiki/Model-based\_design}{http://en.wikipedia.org/wiki/Model-based\_design}
3680 \item (2012). \textit{ARM Assembly Language Tools}. Texas Instruments.
3682 \item (2012). \textit{ARM Optimizing C/C++ Compiler}. Texas Instruments.
3684 \item (2013). \textit{Embedded Coder - Reference}. MathWorks.
3686 \item (2013). \textit{Embedded Coder - User's Guide}. MathWorks.
3688 \item Barry, R. (2009). \textit{Using the FreeRTOS real time kernel - A practical guide}.
3690 \item (2013). \textit{Simulink Coder - Reference}. MathWorks.
3692 \item (2013). \textit{Simulink - Target Language Compiler}. MathWorks.
3694 \item (2013). \textit{Simulink Coder - User's Guide}. MathWorks.
3696 \item (2013). \textit{Simulink - Developing S-Functions}. MathWorks.
3698 \item (2012). \textit{TMS570LS31x/21x 16/32-Bit RISC Flash Microcontroller - Technical Reference Manual}.
3704 \hypertarget{appendix_a_notes_on_freertos_memory_management}{}
3705 \section{Appendix A: Notes on FreeRTOS memory management}
3707 FreeRTOS provides 4 different (at the time of this writing) memory management implementations.
3708 On vanilla distribution of FreeRTOS these can be found in
3709 \texttt{$<$FreeRTOSRoot$>$/FreeRTOS/Source/portable/MemMang} with the names \texttt{heap\_1.c}, \texttt{heap\_2.c},
3710 \texttt{heap\_3.c} and \texttt{heap\_4.c}. The user is supposed to choose one and rename it to \texttt{heap.c}
3711 and include it in the port for the target processor. Memory management implementation of each file
3712 is explained in depth in:
3715 \htmladdnormallink{Memory Management}{http://www.freertos.org/a00111.html}
3718 The above is a must read documentation. In summary:
3720 \noindent$\rightarrow$ \texttt{heap\_1.c}
3723 \item Use a static allocated array for memory and thus will be placed on the \texttt{.bss} section.
3724 \item Subdivides the array into smaller blocks as RAM is requested.
3725 \item Memory cannot be freed.
3726 \item Array is as large as \texttt{configTOTAL\_HEAP\_SIZE} option in \texttt{FreeRTOSConfig.h}.
3729 \noindent$\rightarrow$ \texttt{heap\_2.c}
3732 \item Use a static allocated array for memory and thus will be placed on the \texttt{.bss} section.
3733 \item Uses a best fit algorithm and allows previously allocated blocks to be freed.
3734 \item It does \textbf{not} however combine adjacent free blocks into a single large block.
3735 \item Array is as large as \texttt{configTOTAL\_HEAP\_SIZE} option in \texttt{FreeRTOSConfig.h}.
3738 \noindent$\rightarrow$ \texttt{heap\_3.c}
3741 \item Wrapper around standard C library \texttt{malloc()} and \texttt{free()}.
3742 \item Wrapper makes \texttt{malloc()} and \texttt{free()} functions thread safe.
3743 \item Memory is as large as defined in linker for C system heap.
3744 \item \texttt{configTOTAL\_HEAP\_SIZE} option in \texttt{FreeRTOSConfig.h} is ignored.
3747 \noindent$\rightarrow$ \texttt{heap\_4.c}
3750 \item Use a static allocated array for memory and thus will be placed on the \texttt{.bss} section.
3751 \item Uses a first fit algorithm.
3752 \item It \textbf{does} combine adjacent free memory blocks into a single large block (it does include a
3753 coalescence algorithm).
3754 \item Array is as large as \texttt{configTOTAL\_HEAP\_SIZE} option in \texttt{FreeRTOSConfig.h}.
3757 Not all kernels available for the RPP C Library use the same implementation. This is what each
3758 kernel is currently configured to use:
3760 \begin{center}\begin{tabular}{|r|c|c|}
3761 \hline \textbf{Kernel} & \textbf{Origin} & \textbf{Implementation} \\
3762 \hline 6.0.4 Posix & Simulator from OpenPilot.org & \texttt{heap\_3.c} \\
3763 \hline 7.0.2 TMS570 & HalCoGen & \texttt{heap\_1.c} \\
3764 \hline 7.4.0 TMS570 & HalCoGen & \texttt{heap\_4.c} \\
3765 \hline 7.4.2 TMS570 & Adapted from vanilla distribution & \texttt{heap\_4.c} \\
3766 \hline \end{tabular}\end{center}
3768 The relevant implications of this are:
3771 \item If a kernel with \texttt{heap\_3.c} is used the Simulink model \textit{C system heap size} and
3772 \textit{Model step task stack size} should be tightly related and the first should be large enough to
3773 allocate system tasks and the stack for the stepping task.
3775 \item If a kernel with \texttt{heap\_1.c} is used the programs should not delete tasks, queues or semaphores.
3776 If the application spawn and deletes tasks it will eventually deplete the memory available. This
3777 is the case with the \textit{rpp-test-suite}. Note that failure to allocated memory from the array
3778 will trigger the \textit{Malloc Failed Hook Function} \texttt{vApplicationMallocFailedHook()}, even if the
3779 implementation doesn't use the C system \texttt{malloc()} function. \newline{}
3780 Also, \textit{Model step task stack size} should never be set larger than \texttt{configTOTAL\_HEAP\_SIZE}
3781 option in \texttt{FreeRTOSConfig.h}. Currently the RPP Target doesn't include a GUI option for setting
3782 \texttt{configTOTAL\_HEAP\_SIZE} because the library is statically linked and thus memory will be of the
3783 size specified when built. The RPP Target \textbf{doesn't} check that the requested memory for the
3784 step task is less than the \texttt{configTOTAL\_HEAP\_SIZE}, and if greater then the application will
3785 fail at runtime and trigger the \textit{Malloc Failed Hook Function}.
3790 \hypertarget{appendix_b_known_operating_system_dependent_files}{}
3791 \section{Appendix B: Known operating-system dependent files}
3793 This project was developed on a GNU/Linux operating system. No test for cross-platform
3794 interoperability was performed on the code developed. Although care was taken to try to provide
3795 platform independent code and tools this are the elements that are know to be Linux dependent:
3798 \item LCM1 hardware control tool \texttt{lmc1.py}. \newline{}
3799 This tool is both GUI and command line capable, the following just affects the GUI part. \newline{}
3800 Command line should be usable under Windows systems.
3802 \underline{Cause}: Serial port search algorithm is Linux dependent and Gtk 3.0 dynamic Python bindings
3803 are not yet available on other operating systems.
3805 \item TI CGT support file for RPP Simulink Target \texttt{target\_tools.mk}.
3807 \underline{Cause}: Use UNIX path separator \texttt{/}.
3809 \item Simulink RPP Target download script \texttt{rpp\_download.m}.
3811 \underline{Cause}: Use UNIX path separator \texttt{/}.
3813 \item Simulink RPP Target install script \texttt{rpp\_setup.m}.
3815 \underline{Cause}: Use UNIX path separator \texttt{/}.
3817 \item Simulink RPP Block Library block compilation script \texttt{compile\_blocks.m}.
3819 \underline{Cause}: Call Matlab MEX executable with Unix name.
3821 \item All CCS projects under \texttt{$<$repo$>$/rpp/lib/apps/}.
3822 \underline{Cause}: Paths are configure using UNIX path separator \texttt{/}.