1 \documentclass{scrreprt}
3 \usepackage{graphicx} % images and graphics
4 \usepackage{paralist} % needed for compact lists
5 \usepackage[normalem]{ulem} % needed by strike
6 \usepackage{listings} % required for code blocks
7 \usepackage[urlcolor=blue,colorlinks=true,hyperfootnotes=false]{hyperref} % links
8 \usepackage[utf8]{inputenc} % char encoding
9 \usepackage[bottom]{footmisc} % footnotes
10 \usepackage{todonotes}
11 \usepackage[backend=biber,style=alphabetic,sortcites=true]{biblatex}
15 \addbibresource{rpp_simulink.bib}
18 \usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
19 \usepackage{float} % To fix images position
21 % Prettify code documentation
24 % \usepackage[table]{xcolor}
26 \definecolor{gray97}{gray}{.97}
27 \definecolor{gray75}{gray}{.75}
28 \definecolor{gray45}{gray}{.45}
33 framexbottommargin=3pt,
34 framexleftmargin=0.4cm,
37 backgroundcolor=\color{gray97},
38 rulesepcolor=\color{black},
40 stringstyle=\ttfamily,
41 showstringspaces = false,
42 basicstyle=\small\ttfamily,
43 commentstyle=\color{gray45},
44 keywordstyle=\bfseries,
49 numberfirstline = false,
58 \linespread{1.15} % Lines spacing
59 \setlength{\plitemsep}{0.5\baselineskip} % List items spacing
60 \definecolor{deepblue}{RGB}{0,0,61}
61 \definecolor{deepgreen}{RGB}{0,80,0}
62 \hypersetup{linkcolor=deepblue,citecolor=deepgreen,}
64 % Table of content depth
65 \setcounter{tocdepth}{2}
69 \usepackage{pdflscape}
72 \usepackage{changepage}
76 % \renewcommand{\familydefault}{\sfdefault}
84 \newcommand{\repo}{$\langle$repo$\rangle$}
85 \newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
86 \newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
88 % Supported targets - to be used with \ifx\tgtId\tgtIdXXX
89 \def\tgtIdTMSHDK{tms570\_hdk}
90 \def\tgtIdRMHDK{rm48\_hdk}
91 \def\tgtIdTMSRPP{tms570\_rpp}
92 \def\tgtIdHydCtr{tms570\_hydctr}
94 % Include target specific macros etc.
100 \newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
105 % Upper part of the page
108 \includegraphics[width=0.35\textwidth]{images/cvut.pdf}\\[1cm]
109 \textsc{\LARGE Czech Technical University in Prague}\\[1.5cm]
115 {\huge \bfseries Simulink code generation target for Texas~Instruments
116 \tgname{} platform\par}
118 {\Large Version for \tgtBoardName{} board\par}
125 Carlos \textsc{Jenkins}\\
126 Michal \textsc{Horn}\\
127 Michal \textsc{Sojka}\\[\baselineskip]
140 \section*{Revision history}
143 \noindent\begin{tabularx}{\linewidth}{|l|l|l|X|}
144 \rowcolor[gray]{0.9}\hline
145 Revision & Date & Author(s) & Comments \\ \hline
147 0.1 beta & 2014-12-04 & Sojka, Horn & Initial version \\ \hline
149 0.2 & 2015-02-16 & Sojka, Horn & Improvements, clarifications,
152 0.3 & 2015-03-31 & Sojka, Horn & Added sections
153 \ref{sec-changing-os}, \ref{sec:adding-new-funct} and
154 \ref{sec:mult-single-thre}. Minor
157 0.4 & 2015-04-30 & Sojka, Horn & Added support for TMS570 HDK
158 platform. All RPP software
161 recompilation. \\ \hline
163 0.5 beta & 2015-07-03 & Sojka & Updated section \ref{sec:adding-new-funct}.
164 Added support for Eaton Hydraulics
165 Controller board (TMS570LS1227).
168 0.5.5 & 2015-08-27 & Sojka, Horn & rpp-lib: HAL merged into DRV
169 layer, FreeRTOS upgraded to version 8.2.2.
172 0.6 & 2015-09-03 & Sojka & Multi-rate models can be
173 compiled in multi-tasking mode
175 sec.~\ref{sec-singlet-multit-modes}
176 and \ref{sec:mult-multi-thre}).
177 Added board init block (sec.
178 \ref{sec:block:sfunction_hydctr_init.c}).
179 Documented halcogen directory in
180 sec.~\ref{sec-rpp-lib-subdirectory-content-description}.
183 0.6a & 2015-09-11 & Sojka & Removed reference of
184 Simulink blocks that are not
185 part of Eaton distribution.
188 0.7 & 2015-10-05 & Sojka & Simulink GIO blocks
190 \ref{sec:block:sfunction_gio_in.c},
191 \ref{sec:block:sfunction_gio_out.c})
192 have different parameters and
193 support certain SPI5 pins on the
194 tms570\_hydctr board. Parameters
195 of old GIO blocks are
196 automatically transformed to the
199 Added section \ref{sec:board-init-hydctr}: ``Hydraulics controller
200 initialization demo''.
202 0.8 & 2019-10-18 & NejedlĂ˝, Sojka &
204 Ethernet (\ref{sec-configuration-network-interface}),
205 Simulink external mode (\ref{sec-external-mode}) and
206 description of eth* commands in Section~\ref{sec:commands-description}.
218 \fancypagestyle{plain}{%
219 \fancyhf{} % clear all header and footer fields
220 \renewcommand{\footrulewidth}{0.4pt}
221 \renewcommand{\headrulewidth}{0pt}
222 \fancyfoot[L]{Version \input{version.tex}}
224 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
226 \renewcommand{\headrulewidth}{0.4pt}
227 \renewcommand{\footrulewidth}{0.4pt}
229 \fancyhead[R]{\includegraphics[width=1cm]{images/cvut.pdf}}
231 \fancyhead[L]{\nouppercase \leftmark}
232 \fancyfoot[L]{Version \input{version.tex}}
234 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
237 %\addtolength{\parskip}{\baselineskip} % Paragraph spacing
239 \chapter{Introduction}
240 \label{chap-introduction}
242 This text documents software part of Rapid Prototyping Platform (RPP)
243 project for Texas Instruments \tgname{} safety microcontroller
244 developed by Czech Technical University in Prague (CTU). The software
245 consists of code generation target for Simulink Embedded Coder, a
246 low-level run-time C library and a tool for interactive testing of
247 hardware and software functionality.
249 Originally, the RPP project was created for a custom TMS570-based
250 board. Subsequently, it was ported to other board such as RM48 HDK and
251 TMS570 HDK development kits under a contract from Eaton Corporation.
253 The document contains step-by-step instructions for installation of
254 development tools, information about Simulink Coder configuration,
255 describes how to create new models as well as how to download the
256 resulting firmware to the hardware. It can also be used as a reference
257 for the testing tool, Matlab Simulink blocks and RPP Matlab Simulink
258 Code generator. Additionally, an overall description of the used
259 hardware platform and the architecture of included software is
263 \label{sec-background}
265 In this document, the term \emph{Rapid Prototyping Platform} denotes a
266 hardware board and accompanying software. The hardware board is
267 \tgtBoardName{} based on ARM Cortex R4 safety microcontroller
268 \mcuname{}. This MCU contains several protective mechanisms (two cores
269 in lockstep, error correction mechanisms for SRAM and Flash memory,
270 voltage monitoring, etc.) to fulfill the requirements for safety
271 critical applications. See~\cite{\tgrefman} for details.
273 In order to develop non-trivial applications for the RPP, an operating
274 system is necessary. The RPP is based on FreeRTOS -- a simple
275 opensource real-time operating system kernel. The FreeRTOS provides an
276 API for creating and managing and scheduling multiple tasks, memory
277 manager, semaphores, queues, mutexes, timers and a few of other
278 features which can be used in the applications.
279 See~\cite{usingthefreertos2009} for more details.
281 Even with the operating system it is quite hard and non-intuitive to
282 manipulate the hardware directly. That is the point when abstraction
283 comes into the play. The RPP software is made of several layers
284 implementing, from the bottom to the top, low-level device drivers,
285 hardware abstraction for common functionality on different hardware
286 and an API which is easy to use in applications. The operating system
287 and the basic software layers, can be compiled as a library and easily
288 used in any project. More details about the library can be found in
289 Chapter~\ref{chap-c-support-library} and in~\cite{michalhorn2013}.
291 Because human beings make mistakes and in safety critical applications
292 any mistake can cause damage, loos of money or in the worst case even
293 death of other people, the area for making mistakes has to be as small
294 as possible. An approach called Model-based development
295 \cite{modelbasedwiki2013} has been introduced to reduce the
296 probability of making mistakes. In model-based development, the
297 applications are designed at higher level from models and the
298 functionality of the models can be simulated in a computer before the
299 final application/hardware is finished. This allows to discover
300 potential errors earlier in the development process.
302 One commonly used tool-chain for model-based development is
303 Matlab/Simulink. In Simulink the application is developed as a model
304 made of interconnected blocks. Every block implements some
305 functionality. For example one block reads a value from an
306 analog-to-digital converter and provides the value as an input to
307 another block. This block can implement some clever algorithm and its
308 output is passed to another block, which sends the computed value as a
309 message over CAN bus to some other MCU. Such a model can be simulated
310 and tested even before the real hardware is available by replacing the
311 input and output blocks with simulated ones. Once the hardware is
312 ready, C code is automatically generated from the model by a Simulink
313 Coder. The code is then compiled by the MCU compatible compiler and
314 downloaded to the MCU Flash memory on the device. Because every block
315 and code generated from the block has to pass a series of tests during
316 their development, the area for making mistakes during the application
317 development has been significantly reduced and developers can focus on
318 the application instead of the hardware and control software
319 implementation. More information about code generation can be found in
320 Chapter \ref{chap-simulink-coder-target}. For information about Matlab
321 Simulink, Embedded Coder and Simulink Coder, refer to
322 \cite{embeddedcoderreference2013, ebmeddedcoderusersguide2013,
323 simulinkcoderreference2013, targetlanguagecompiler2013,
324 simulinkcoderusersguide2013, simulinkdevelopingsfunctions2013}.
326 \section{Hardware description}
327 \label{sec-hardware-description}
331 \section{Software architecture}
332 \label{sec-software-architecture}
334 The core of the RPP software is the so called RPP Library. This
335 library is conceptualy structured into 5 layers, depicted in
336 Figure~\ref{fig-layers}. The architecture design was driven by the
337 following guidelines:
340 \item Top-down dependency only. No lower layer depends on anything from
342 % \item 1-1 layer dependency only. The top layer depends
343 % exclusively on the bottom layer, not on any lower level layer (except for a
344 % couple of exceptions).
345 \item Each layer should provide a unified layer interface
346 (\texttt{rpp.h}, \texttt{drv.h}, \texttt{sys.h} and
347 \texttt{os.h}), so that higher layers depend on the lower layer's interface
348 and not on individual elements from that layer.
354 \includegraphics[width=250px]{images/layers.pdf}
355 \caption{The RPP library layers.}
360 As a consequence of this division the source code files and interface files are
361 placed in private directories like \texttt{drv/din.h}. With this organization
362 user applications only needs to include the top layer interface files (for
363 example \texttt{rpp/rpp.h}) to be able to use the selected library API.
365 The rest of the section provides basic description of each layer.
367 \subsection{Operating System layer}
368 \label{sec-operating-system-layer}
369 This is an interchangeable operating system (OS) layer containing the
370 FreeRTOS source files. The system can be easily replaced by another
371 version. For example it is possible to compile the RPP library for
372 Linux (using POSIX version of the FreeRTOS), which can be desirable
373 for some testing. The source files can be found in the
374 \texttt{$\langle$rpp\_lib$\rangle$/os} folder.
376 The following FreeRTOS versions are distributed:
378 \item[6.0.4\_posix] POSIX version, usable for compilation of the
379 library for Linux system.
380 \item[8.2.2] Currently used FreeRTOS version. This is the version
381 downloaded from FreeRTOS.org with changes in directory structure.
382 Namely, include files have added the \emph{os/} prefix and platform
383 dependent code (portable) for \tgname{} is copied to the same
384 directory as platform independent code.
387 \subsection{System Layer}
388 \label{sec-system-layer}
389 This layer contains system files with data types definitions, clock definitions,
390 interrupts mapping, MCU start-up sequence, MCU selftests, and other low level
391 code for controlling some of the MCU peripherals. The source files can be found
392 in \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/sys}, the header files can
393 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/sys}
396 Large part of this layer was generated by the HalCoGen tool (see
397 Section~\ref{sec-halcogen}). Some files were then modified by hand.
399 \subsection{Drivers layer}
400 \label{sec-drivers-layer}
401 The Drivers layer contains code for controlling the RPP peripherals.
402 Typically, it contains code implementing IRQ handling, software
403 queues, management threads, etc. The layer benefits from the lower
404 layer thus it is not too low level, but still there are some
405 peripherals like ADC, which need some special procedure for
406 initialization and running, that would not be very intuitive for the
409 The source files can be found in
410 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
411 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/drv} folder.
413 \subsection{RPP Layer}
414 \label{sec-rpp-layer}
415 The RPP Layer is the highest layer of the library. It provides an easy
416 to use set of functions for every peripheral and requires only basic
417 knowledge about them. For example, to use the ADC, the user can just
418 call \texttt{rpp\_adc\_init()} function and it calls a sequence of
419 Driver layer functions to initialize the hardware and software.
421 The source files can be found in
422 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/rpp} and the header files can
423 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/rpp}.
425 \section{Document structure}
426 \label{sec-document-structure}
427 The structure of this document is as follows:
428 Chapter~\ref{chap-getting-started} gets you started using the RPP
429 software. Chapter~\ref{chap-c-support-library} describes the RPP
430 library. Chapter~\ref{chap-simulink-coder-target} covers the Simulink
431 code generation target and finally
432 Chapter~\ref{chap-rpp-test-software} documents a tool for interactive
433 testing of the RPP functionality.
435 \chapter{Getting started}
436 \label{chap-getting-started}
438 \section{Software requirements}
439 \label{sec-software-requirements}
440 The RPP software stack can be used on Windows and Linux platforms. The
441 following subsections mention the recommended versions of the required
442 software tools/packages.
444 \subsection{Linux environment}
445 \label{sec-linux-environment}
447 \item Debian based 64b Linux distribution (Debian 7.0 or Ubuntu 14.4 for
449 \item Kernel version 3.11.0-12.
450 \item GCC version 4.8.1
451 \item GtkTerm 0.99.7-rc1
452 \item TI Code Composer Studio 5.5.0.00077
453 \item Matlab 2013b 64b with Embedded Coder
454 \item HalCoGen 4.00 (optional)
455 \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
456 \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
457 \item Git 1.7.10.4 (optional)
460 \subsection{Windows environment}
461 \label{sec-windows-environment}
463 \item Windows 7 Enterprise 64b Service Pack 1.
464 \item Microsoft Windows SDK v7.1
465 \item Bray Terminal v1.9b
466 \item TI Code Composer Studio 5.5.0.00077
467 \item Matlab 2013b 64b with Embedded Coder
468 \item HalCoGen 4.00 (optional)
469 \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
470 \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
471 \item Git 1.9.4.msysgit.2 (optional)
474 \section{Software tools}
475 \label{sec-software-and-tools}
477 This section covers tool which are needed or recommended for work with
480 \subsection{TI Code Composer Studio}
482 Code Composer Studio (CCS) is the official Integrated Development Environment
483 (IDE) for developing applications for Texas Instruments embedded processors. CCS
484 is multiplatform software based on
485 Eclipse open source IDE.
487 CCS includes Texas Instruments Code Generation Tools (CGT)
488 \cite{armoptimizingccppcompiler2012, armassemblylanguagetools2012}
489 (compiler, linker, etc). Simulink code generation target requires the
490 CGT to be available in the system, and thus, even if no library
491 development will be done or the IDE is not going to be used CCS is
494 You can find documentation for CGT compiler in \cite{armoptimizingccppcompiler2012} and
495 for CGT archiver in \cite{armassemblylanguagetools2012}.
497 \subsubsection{Installation on Linux}
498 \label{sec-installation-on-linux}
499 Download CCS for Linux from:\\
500 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
502 Once downloaded, add executable permission to the installation file
503 and launch the installation by executing it. Installation must be done
504 by the root user in order to install a driver set.
506 \lstset{language=bash}
508 chmod +x ccs_setup_5.5.0.00077.bin
509 sudo ./ccs_setup_5.5.0.00077.bin
512 After installation the application can be executed with:
514 \lstset{language=bash}
516 cd <ccs>/ccsv5/eclipse/
520 The first launch on 64bits systems might fail. This can happen because CCS5 is
521 a 32 bit application and thus requires 32 bit libraries. They can be
524 \lstset{language=bash}
526 sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
529 If the application crashes with a segmentation fault edit file:
531 \lstset{language=bash}
533 nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
536 And change key \texttt{org.eclipse.ui/showIntro} to \texttt{false}.
538 \subsubsection{Installation on Windows}
539 \label{sec-installation-on-windows}
540 Installation for Windows is more straightforward than the installation
541 procedure for Linux. Download CCS for Windows from:\\
542 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
544 Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.
546 \subsubsection{First launch}
547 \label{sec-first-launch}
548 If no other licence is available, choose ``FREE License -- for use
549 with XDS100 JTAG Emulators'' from the licensing options. Code download
550 for the board uses the XDS100 hardware.
552 \subsection{Matlab/Simulink}
553 \label{sec-matlab-simulink}
554 Matlab Simulink is a set of tools, runtime environment and development
555 environment for Model--Based \cite{modelbasedwiki2013} applications development,
556 simulations and code generation for target platforms. Supported Matlab Simulink
557 version is R2013b for 64 bits Linux and Windows. A licence for an Embedded Coder is
558 necessary to be able to generate code from Simulink models, containing RPP blocks.
560 \subsection{HalCoGen}
562 HalCoGen (HAL Code Generator) is a tool for graphical configuration of peripherals, clocks, interrupts and other MCU parameters. It generates C code which can be imported to the Code Composer Studio.
564 The tool is available for Windows at
566 \url{http://www.ti.com/tool/halcogen}
569 The HalCoGen has been used in early development stage of the RPP
570 project to generate the base code for some of the peripheral. The
571 trend is to not to use the HalCoGen any more, because the generated
572 code is not reliable enough for safety critical applications. Anyway it is
573 sometimes helpful to use it as a reference.
575 The HalCoGen is distributed for Windows only, but can be run on Linux
576 under Wine (tested with Wine version 1.6.2).
578 \subsection{GtkTerm and Bray Terminal}
579 \label{sec-gtkterm-bray-terminal}
580 Most of the interaction with the board is done through a RS-232 serial
581 connection. The terminal software used for communication is called GtkTerm for
582 Linux and Bray terminal for Windows.
584 To install GtkTerm execute:
586 \lstset{language=bash}
588 sudo apt-get install gtkterm
591 The Bray Terminal does not require any installation and the executable file is
593 \url{https://sites.google.com/site/terminalbpp/}
595 \subsection{C Compiler}
596 \label{sec-c-compiler}
597 A C language compiler has to be available on the development system to be able to
598 compile Matlab Simulink blocks S-functions.
600 For Linux a GCC 4.8.1 compiler is recommended and can be installed with a
603 \lstset{language=bash}
605 sudo apt-get install gcc
608 For Windows, the C/C++ compiler is a part of Windows SDK, which is available from\\
609 \url{http://www.microsoft.com/en-us/download/details.aspx?id=8279}
611 \section{Project installation}
612 \label{sec-project-installation}
613 The RPP software is distributed in three packages and a standalone pdf
614 file containing this documentation. Every package is named like
615 \emph{$\langle$package\_name$\rangle$-version.zip}. The three packages
619 \item[rpp-simulink] Contains the source code of Matlab Simulink
620 blocks, demo models and scripts for downloading the generated
621 firmware to the target board from Matlab/Simulink. Details can be
622 found in Chapter \ref{chap-simulink-coder-target}.
624 The package also contains the binary of the RPP Library and all its
625 headers and other files necessary for building and downloading
627 \item[rpp-test-sw] Contains an application for interactive testing and
628 control of the \tgtBoardName{} board over the serial interface. Details can be
629 found in Chapter~\ref{chap-rpp-test-software}.
631 The package also contains the binary of the RPP Library and all
632 headers and other files necessary for building and downloading the
634 \item[rpp-lib] Contains the source code of the RPP library, described
635 in Chapter \ref{chap-c-support-library}. If you want to make any
636 changes in the drivers or the RPP API, this library has to be
637 compiled and linked with applications in the other two packages.
638 Library compilation is described in Section \ref{sec-compilation}.
641 The following sections describe how to start working with individual
644 \ifthenelse{\equal{\tgtId}{\tgtIdTMSHDK} \OR
645 \equal{\tgtId}{\tgtIdTMSRPP}}{
646 \subsection{Getting sources from git repository}
648 To get the source code from Git repository, execute the following command:
650 \texttt{git clone --recursive git@rtime.felk.cvut.cz:jenkicar/rpp-simulink}
652 \noindent If you have got release packages (.zip archives), follow the
653 instructions in the next sections. }
656 \subsection{rpp-simulink}
657 \label{sec-rpp-simulink-installation}
658 This section describes how to install the rpp-simulink project, which
659 is needed to try the demo models or to build your own models that use
663 \item Unzip the \texttt{rpp-simulink-version.zip} file.
664 \item Follow the procedure from Section
665 \ref{sec-configuration-simulink-for-rpp} for configuring Matlab
666 Simulink for the RPP project.
667 \item Follow the procedure from Section \ref{sec-crating-new-model}
668 for instructions about creating your own model which will use the
669 RPP Simulink blocks or follow the instructions in
670 Section~\ref{sec-running-model-on-hw} for downloading the firmware to the RPP hardware.
673 \subsection{rpp-test-sw}
674 \label{sec-test-sw-installation}
675 This section describes how to install and run the application that
676 allows you to interactively control the RPP hardware. This can be
677 useful, for example, to test your modifications of the RPP library.
680 \item Unzip the \texttt{rpp-test-sw-version.zip} file.
681 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
682 \item Import the \texttt{rpp-test-sw} project as described in
683 Section \ref{sec-openning-of-existing-project}.
684 \item Right click on the \texttt{rpp-test-sw} project in the
685 \textsc{Project Explorer} and select \textsc{Build Project}.
686 \item Follow the instructions in
687 Section~\ref{sec-running-software-on-hw} to download, debug and
688 run the software on the target hardware.
692 \label{sec-rpp-lib-installation}
694 This section describes how to open the rpp-lib project in Code
695 Composer Studio and how to use the resulting static library in an
696 application. This is only necessary if you need to modify the library
700 \item Unzip the \texttt{rpp-lib-version.zip} file.
701 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
702 \item Import the rpp-lib project from directory
703 \texttt{rpp-lib-XXX/build/\tgtId} as described in
704 Section~\ref{sec-openning-of-existing-project}.
705 \item Compile the static library by selecting \textsc{Project
706 $\rightarrow$ Build Project} (see Section
707 \ref{sec-compilation} for more information). The compiled
708 library \texttt{rpp-lib.lib} and file
709 \texttt{Makefile.config} will appear in the
710 \texttt{rpp-lib-XXX} directory.
711 \item Either copy the compiled library and the content of the
712 \texttt{rpp/include} directory to the application, where you
713 want to use it or use the library in place, as described in
714 Section~\ref{sec:creating-new-project}.
716 \item In the rpp-simulink application the library is located in
717 the \texttt{rpp/lib} folder.
718 \item In the rpp-test-sw application the library is located in
719 the \texttt{rpp-lib} folder.
723 \section{Code Composer Studio usage}
724 \label{sec-code-composerpstudio-usage}
726 \subsection{Opening an existing project}
727 \label{sec-openning-of-existing-project}
728 The procedure for opening a project is similar to opening a project in
729 the standard Eclipse IDE.
732 \item Launch Code Composer Studio
733 \item Select \textsc{File$\rightarrow$Import}
734 \item In the dialog window select \textsc{Code Composer
735 Studio$\rightarrow$Existing CCS Eclipse project} as an import
736 source (see Figure \ref{fig-import-project}).
737 \item In the next dialog window click on \textsc{Browse} button
738 and find the root directory of the project.
739 \item Select the requested project in the \textsc{Discovered
740 project} section so that the result looks like in Figure
741 \ref{fig-select-project}.
742 \item Click the \textsc{Finish} button.
745 \begin{figure}[H]\begin{center}
746 \includegraphics[width=350px]{images/import_project.png}
747 \caption{Import project dialog}
748 \label{fig-import-project}
749 \end{center}\end{figure}
751 \begin{figure}[H]\begin{center}
752 \includegraphics[width=350px]{images/select_project.png}
753 \caption{Select project dialog}
754 \label{fig-select-project}
755 \end{center}\end{figure}
758 \subsection{Creating new project}
759 \label{sec:creating-new-project}
760 Follow these steps to create an application for \tgname{} MCU compiled with
764 \item Create a new empty CCS project. Select \mcuname{} device, XDS100v2
765 connection and set Linker command file to
766 \texttt{rpp-lib/build/\tgtId/\ldscriptname}.
768 \noindent\includegraphics[scale=0.45]{images/base_1.png}
770 \item In \textsc{Project Explorer}, create normal folders
771 named \texttt{include} and \texttt{src}.
773 \item If you use Git version control system, add \texttt{.gitignore}
774 file with the following content to the root of that project:
783 \item In project \textsc{Properties}, add new variable of type
784 \texttt{Directory} named \texttt{RPP\_LIB\_ROOT} and set it to the
788 \noindent\includegraphics[scale=.45]{images/base_2.png}
790 \item Configure the compiler \#include search path to contain
791 project's \texttt{include} directory, \penalty-100
792 \texttt{\$\{RPP\_LIB\_ROOT\}/os/8.2.2/include} and
793 \texttt{\$\{RPP\_LIB\_ROOT\}/rpp/include}, in that order.
795 \includegraphics[scale=.43]{images/base_5.png}
798 \item Add \texttt{\$\{RPP\_LIB\_ROOT\}/rpp-lib.lib} to the list of
799 linked libraries before the runtime support library
800 (\texttt{\tgtRtlib}).
802 \noindent\includegraphics[scale=.45]{images/base_3.png}
804 \item Configure the compiler to allow GCC extensions.
806 \noindent\includegraphics[scale=.45]{images/base_6.png}
809 \item Create \texttt{main.c} file with the following content:
810 \begin{lstlisting}[language=C]
816 rpp_sci_printf("Hello world\n");
817 vTaskStartScheduler();
818 return 0; /* not reached */
821 void vApplicationMallocFailedHook()
823 void vApplicationStackOverflowHook()
827 \item Compile the application by e.g. \textsc{Project $\rightarrow$
829 \item Select \textsc{Run} $\rightarrow$ \textsc{Debug}. The
830 application will be downloaded to the processor and run. A
831 breakpoint is automatically placed at \texttt{main()} entry. To
832 continue executing the application select \textsc{Run} $\rightarrow$
834 \item If your application fails to run with a \texttt{\_dabort} interrupt, check
835 that the linker script selected in step 1 is not excluded from the build.
836 You can do this by right clicking the \texttt{\ldscriptname} file
837 in the \textsc{Project Explorer} and unchecking the \textsc{Exclude from build}
838 item. The Code Composer Studio sometimes automaticaly excludes this file from
839 the build process when creating a new project.
841 % \item If not already created for another project, create new target
842 % configuration. Select \textsc{Windows $\rightarrow$ Show View
843 % $\rightarrow$ Target Configurations}. In the shown window, click
844 % on \textsc{New Target Configuration} icon and configure XDS100v2
845 % connection and \mcuname{} device as shown below. Click \textsc{Save},
846 % connect your board and click \textsc{Test Connection}.
849 % \includegraphics[width=\linewidth]{images/target_conf.png}
852 \item Optionally, you can change debugger configuration by selecting
853 \textsc{Run $\rightarrow$ Debug Configurations}. In the
854 \textsc{Target} tab, you can configure not to break at \texttt{main}
855 or not to erase the whole flash, but necessary sectors only (see the
858 \includegraphics[width=\linewidth]{images/debug_conf_flash.png}
863 %% Comment this out for Eaton
864 % \subsubsection{Steps to configure new POSIX application:}
865 % Such an application can be used to test certain FreeRTOS features on
866 % Linux and can be compiled with a native GCC compiler.
868 % \begin{compactenum}
869 % \item Create a new managed C project that uses Linux GCC toolchain.
870 % \item Create a source folder \texttt{src}. Link all files from original
871 % CCS application to this folder.
872 % \item Create a normal folder \texttt{include}. Create a folder
873 % \texttt{rpp} inside of it.
874 % \item Add common \texttt{.gitignore} to the root of that project:
881 % \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
882 % repository branch root.\newline{}
883 % \noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
884 % \item Configure compiler to include local includes, CCS application
885 % includes, OS includes for POSIX and RPP includes, in that order.\newline{}
886 % \noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
888 % \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
889 % \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
890 % \noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
893 \subsubsection{Content of the application}
896 \item Include RPP library header file.
897 \lstset{language=c++}
902 If you want to reduce the size of the final application, you can
903 include only the headers of the needed modules. In that case, you
904 need to include two additional headers: \texttt{base.h} and, in case
905 when SCI is used for printing, \texttt{rpp/sci.h}.
907 #include "rpp/hbr.h" /* We want to use H-bridge */
908 #include <base.h> /* This is the necessary base header file of the rpp library. */
909 #include "rpp/sci.h" /* This is needed, because we use rpp_sci_printf in following examples. */
913 \item Create one or as many FreeRTOS task function definitions as
914 required. Those tasks can use functions from the RPP library. Beware
915 that currently not all RPP functions are
916 reentrant\footnote{Determining which functions are not reentrant and
917 marking them as such (or making them reentrant) is planned as
918 future work.}. \lstset{language=c++}
920 void my_task(void* p)
922 static const portTickType freq_ticks = 1000 / portTICK_RATE_MS;
923 portTickType last_wake_time = xTaskGetTickCount();
925 /* Wait until next step */
926 vTaskDelayUntil(&last_wake_time, freq_ticks);
927 rpp_sci_printf((const char*)"Hello RPP.\r\n");
932 \item Create the main function that will:
934 \item Initialize the RPP board. If you have included only selected
935 modules in step 1, initialize only those modules by calling their init
937 example \texttt{rpp\_hbr\_init\(\)}.
938 \item Spawn the tasks the application requires. Refer to FreeRTOS API
940 \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details
942 \item Handle error when the FreeRTOS scheduler cannot be started.
944 \lstset{language=c++}
948 /* In case whole library is included: */
949 /* Initialize RPP board */
951 /* In case only selected modules are included: */
954 /* Initialize sci for printf */
956 /* Enable interrups */
960 if (xTaskCreate(my_task, (const signed char*)"my_task",
961 512, NULL, 0, NULL) != pdPASS) {
963 rpp_sci_printf((const char*)
964 "ERROR: Cannot spawn control task.\r\n"
970 /* Start the FreeRTOS Scheduler */
971 vTaskStartScheduler();
973 /* Catch scheduler start error */
975 rpp_sci_printf((const char*)
976 "ERROR: Problem allocating memory for idle task.\r\n"
984 \item Create hook functions for FreeRTOS:
986 \item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation
988 \item \texttt{vApplicationStackOverflowHook()} allows to catch stack
991 \lstset{language=c++}
993 #if configUSE_MALLOC_FAILED_HOOK == 1
995 * FreeRTOS malloc() failed hook.
997 void vApplicationMallocFailedHook(void) {
999 rpp_sci_printf((const char*)
1000 "ERROR: manual memory allocation failed.\r\n"
1007 #if configCHECK_FOR_STACK_OVERFLOW > 0
1009 * FreeRTOS stack overflow hook.
1011 void vApplicationStackOverflowHook(xTaskHandle xTask,
1012 signed portCHAR *pcTaskName) {
1014 rpp_sci_printf((const char*)
1015 "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName
1027 \subsection{Downloading and running the software}
1028 \label{sec-running-software-on-hw}
1029 \subsubsection{Code Composer Studio Project}
1030 \label{sec-ccs-run-project}
1031 When an application is distributed as a CCS project, you have to open the
1032 project in the CCS as described in the Section
1033 \ref{sec-openning-of-existing-project}. Once the project is opened and built, it
1034 can be easily downloaded to the target hardware with the following procedure:
1037 \ifx\tgtId\tgtIdTMSRPP
1038 \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG port.
1039 \item Connect a USB cable to the XDS100v2 USB emulator and the development computer.
1041 \item Connect the USB cable to the \tgtBoardName{} board.
1043 \item Plug in the power supply.
1044 \item In the Code Composer Studio click on the
1045 \textsc{Run$\rightarrow$Debug}. The project will be optionally built and
1046 the download process will start. The Code Composer Studio will switch into the debug
1047 perspective, when the download is finished.
1048 \item Run the program by clicking on the \textsc{Run} button, with the
1052 \subsubsection{Binary File}
1053 \label{sec-binary-file}
1054 If the application is distributed as a binary file, without source code and CCS
1055 project files, you can download and run just the binary file by creating a new
1056 empty CCS project and configuring the debug session according to the following
1060 \item In Code Composer Studio click on
1061 \textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
1062 \item In the dialog window, type in a project name, for example
1063 myBinaryLoad, Select \textsc{Device
1064 variant} (ARM, Cortex R, \mcuname, Texas Instruments XDS100v2 USB Emulator)
1065 and select project template to \textsc{Empty Project}. The filled dialog should
1066 look like in Figure~\ref{fig-new-empty-project}
1067 \item Click the \textsc{Finish} button and a new empty project will
1069 \item In the \textsc{Project Explorer} right-click on the project and
1070 select \textsc{Debug as$\rightarrow$Debug configurations}.
1071 \item Click \textsc{New launch configuration} button
1072 \item Rename the New\_configuration to, for example, myConfiguration.
1073 \item Select configuration target file by clicking the \textsc{File
1074 System} button, finding and selecting the \texttt{rpp-lib-XXX/build/\tgtId/\tgconfigfilename} file. The result
1075 should look like in Figure~\ref{fig-debug-conf-main-diag}.
1076 \item In the \textsc{program} pane select the binary file you want to
1077 download to the board. Click on the \textsc{File System} button,
1078 find and select the binary file. Try, for example
1079 \texttt{rpp-test-sw.out}. The result should look like in
1080 Figure~\ref{fig-debug-conf-program-diag}.
1081 \item You may also tune the target configuration as described in
1082 Section \ref{sec-target-configuration}.
1083 \item Finish the configuration by clicking the \textsc{Apply} button
1084 and download the code by clicking the \textsc{Debug} button. You can
1085 later invoke the download also from the
1086 \textsc{Run$\rightarrow$Debug} CCS menu. It is not necessary to
1087 create more Debug configurations and CCS empty projects as you can
1088 easily change the binary file in the Debug configuration to load a
1089 different binary file.
1092 \begin{figure}[H]\begin{center}
1093 \includegraphics[scale=.45]{images/new_empty_project.png}
1094 \caption{New empty project dialog}
1095 \label{fig-new-empty-project}
1096 \end{center}\end{figure}
1098 \begin{figure}[H]\begin{center}
1099 \includegraphics[scale=.45]{images/debug_configuration_main.png}
1100 \caption{Debug Configuration Main dialog}
1101 \label{fig-debug-conf-main-diag}
1102 \end{center}\end{figure}
1104 \subsection{Target configuration}
1105 \label{sec-target-configuration}
1106 Default target configuration erases the whole Flash memory, before
1107 downloading the code. This takes long time and in most cases it is
1108 not necessary. You may disable this feature by the following procedure:
1110 \item Right click on the project name in the \textsc{Project Browser}
1111 \item Select \textsc{Debug as$\rightarrow$Debug Configurations}
1112 \item In the dialog window select \textsc{Target} pane.
1113 \item In the \textsc{Flash Settings}, \textsc{Erase Options} select
1114 \textsc{Necessary sectors only}.
1115 \item Save the configuration by clicking the \textsc{Apply} button
1116 and close the dialog.
1119 \begin{figure}[H]\begin{center}
1120 \includegraphics[scale=.45]{images/debug_configuration_program.png}
1121 \caption{Configuration Program dialog}
1122 \label{fig-debug-conf-program-diag}
1123 \end{center}\end{figure}
1125 \section{Matlab Simulink usage}
1126 \label{sec-matlab-simulink-usage}
1127 This section describes the basics of working with the RPP code
1128 generation target for Simulink. For a more detailed description of the
1129 code generation target refer to
1130 Chapter~\ref{chap-simulink-coder-target}.
1132 \subsection{Configuring Simulink for RPP}
1133 \label{sec-configuration-simulink-for-rpp}
1134 Before any work or experiments with the RPP blocks and models, the RPP
1135 target has to be configured to be able to find the ARM cross-compiler,
1136 native C compiler and some other necessary files. Also the S-Functions
1137 of the blocks have to be compiled by the mex tool.
1139 \item Download and install Code Composer Studio CCS (see
1140 Section~\ref{sec-ti-ccs}).
1141 \item Install a C compiler. On Windows follow Section~\ref{sec-c-compiler}.
1142 \item On Windows you have to tell the \texttt{mex} which C compiler to
1143 use. In the Matlab command window run the \texttt{mex -setup}
1144 command and select the native C compiler.
1146 \begin{lstlisting}[basicstyle=\texttt\footnotesize]
1149 Welcome to mex -setup. This utility will help you set up
1150 a default compiler. For a list of supported compilers, see
1151 http://www.mathworks.com/support/compilers/R2013b/win64.html
1153 Please choose your compiler for building MEX-files:
1155 Would you like mex to locate installed compilers [y]/n? y
1158 [1] Microsoft Software Development Kit (SDK) 7.1 in c:\Program Files (x86)\Microsoft Visual Studio 10.0
1164 Please verify your choices:
1166 Compiler: Microsoft Software Development Kit (SDK) 7.1
1167 Location: c:\Program Files (x86)\Microsoft Visual Studio 10.0
1169 Are these correct [y]/n? y
1171 ***************************************************************************
1172 Warning: MEX-files generated using Microsoft Windows Software Development
1173 Kit (SDK) require that Microsoft Visual Studio 2010 run-time
1174 libraries be available on the computer they are run on.
1175 If you plan to redistribute your MEX-files to other MATLAB
1176 users, be sure that they have the run-time libraries.
1177 ***************************************************************************
1180 Trying to update options file: C:\Users\Michal\AppData\Roaming\MathWorks\MATLAB\R2013b\mexopts.bat
1181 From template: C:\PROGRA~1\MATLAB\R2013b\bin\win64\mexopts\mssdk71opts.bat
1185 **************************************************************************
1186 Warning: The MATLAB C and Fortran API has changed to support MATLAB
1187 variables with more than 2^32-1 elements. In the near future
1188 you will be required to update your code to utilize the new
1189 API. You can find more information about this at:
1190 http://www.mathworks.com/help/matlab/matlab_external/upgrading-mex-files-to-use-64-bit-api.html
1191 Building with the -largeArrayDims option enables the new API.
1192 **************************************************************************
1195 \item Configure the RPP code generation target:
1197 Open Matlab and in the command window run:
1199 \lstset{language=Matlab}
1201 cd <rpp-simulink>/rpp/rpp/
1205 This will launch the RPP setup script. This script will ask the user to provide
1206 the path to the CCS compiler root directory (the directory where \texttt{armcl}
1207 binary is located), normally:
1210 <ccs>/tools/compiler/arm_5.X.X/
1213 Then Matlab path will be updated and block S-Functions will be built.
1215 \item Create new model or load a demo:
1217 Demos are located in \texttt{\repo/rpp/demos}. Creation of new
1218 models is described in Section~\ref{sec-crating-new-model} below.
1222 \subsection{Working with demo models}
1223 \label{sec-openning-demo-models}
1224 The demo models are available from the directory
1225 \texttt{\repo/rpp/demos}. To access the demo models for reference or
1226 for downloading to the RPP board open them in Matlab. Use either the
1227 GUI or the following commands:
1229 \begin{lstlisting}[language=Matlab]
1230 cd <rpp-simulink>/rpp/demos
1231 open cantransmit.slx
1234 The same procedure can be used to open any other models. To build the
1235 demo select \textsc{Code$\rightarrow$C/C++ Code $\rightarrow$Build
1236 Model}. This will generate the C code and build the binary firmware
1237 for the RPP board. To run the model on the target hardware see
1238 Section~\ref{sec-running-model-on-hw}.
1240 \subsection{Creating new model}
1241 \label{sec-crating-new-model}
1243 \item Create a model by clicking \textsc{New$\rightarrow$Simulink Model}.
1244 \item Open the configuration dialog by clicking \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
1245 \item The new Simulink model needs to be configured in the following way:
1247 \item Solver (Figure \ref{fig-solver}):
1249 \item Solver type: \emph{Fixed-step}
1250 \item Solver: \emph{discrete}
1251 \item Fixed-step size: \emph{Sampling period in seconds. Minimum
1253 \item Tasking mode -- choose between the following:
1255 \item \textit{Auto} selects SingleTasking modes for
1256 single-rate model or MultiTasking mode for multi-rate
1257 models. See Section \ref{sec-singlet-multit-modes}
1258 \item \textit{SingleTasking} selects SingleTasking mode. See
1259 Section \ref{sec-singlet-mode} for details.
1260 \item \textit{MultiTasking} select MultiTasking mode. In
1261 this mode \textit{Higher priority value indicates higher
1262 task priority} should be checked. See Section
1263 \ref{sec-multit-mode} for details.
1268 \includegraphics[scale=.45]{images/simulink_solver.png}
1269 \caption{Solver settings}
1273 % \item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
1274 % \begin{compactitem}
1275 % \item Disable warning ``Source block specifies -1 sampling
1276 % time''. It's ok for the source blocks to run once per tick.
1279 % \includegraphics[scale=.45]{images/simulink_diagnostics.png}
1280 % \caption{Sample Time settings}
1281 % \label{fig-sample-time-settings}
1284 \item Code generation (Figure~\ref{fig-code-gen-settings}):
1286 \item Set ``System target file'' to \texttt{rpp.tlc}.
1289 \includegraphics[scale=.45]{images/simulink_code.png}
1290 \caption{Code Generation settings}
1291 \label{fig-code-gen-settings}
1295 \item Once the model is configured, you can open the Library Browser
1296 (\textsc{View $\rightarrow$ Library Browser}) and add the necessary
1297 blocks to create the model. The RPP-specific blocks are located in
1298 the RPP Block Library.
1299 \item From Matlab command window change the current directory to where
1300 you want your generated code to appear, e.g.:
1301 \begin{lstlisting}[language=Matlab]
1304 The code will be generated in a subdirectory named
1305 \texttt{<model>\_rpp}, where \texttt{model} is the name of the
1307 \item Generate the code by choosing \textsc{Code $\rightarrow$ C/C++
1308 Code $\rightarrow$ Build Model}.
1311 To run the model on the \tgtBoardName{} board continue with Section
1312 \ref{sec-running-model-on-hw}.
1314 \subsection{Running models on the RPP board}
1315 \label{sec-running-model-on-hw}
1316 To run the model on the \tgtBoardName{} hardware you have to enable the download
1317 feature and build the model by following this procedure:
1319 \item Open the model you want to run (see
1320 Section~\ref{sec-openning-demo-models} for example with demo
1322 \item Click on \textsc{Simulation$\rightarrow$Model Configuration
1324 \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
1325 check the \textsc{Download compiled binary to RPP} checkbox. Click
1326 the \textsc{OK} button
1327 \item Connect the target hardware to the computer (see Section
1328 \ref{sec-ccs-run-project}) and build the model by \textsc{Code
1329 $\rightarrow$ C/C++ Code $\rightarrow$ Build Model}. If the build
1330 succeeds, the download process will start automatically and once
1331 the downloading is finished, the application will run immediately.
1334 %%\subsubsection{Using OpenOCD for downloading}
1335 %%\label{sec:using-open-downl}
1337 %%On Linux systems, it is possible to use an alternative download
1338 %%mechanism based on the OpenOCD tool. This results in much shorter
1339 %%download times. Using OpenOCD is enabled by checking ``Use OpenOCD to
1340 %%download the compiled binary'' checkbox. For more information about
1341 %%the OpenOCD configuration refer to our
1342 %%wiki\footnote{\url{http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137\#OpenOCD_setup_and_Flashing}}.
1344 %%Note: You should close any ongoing Code Composer Studio debug sessions
1345 %%before downloading the generated code to the RPP board. Otherwise the
1348 \section{Configuring serial interface}
1349 \label{sec-configuration-serial-interface}
1350 The main mean for communication with the RPP board is the serial line.
1351 Each application may define its own serial line settings, but the
1352 following settings are the default:
1355 \item Baudrate: 115200
1359 \item Flow control: none
1362 Use GtkTerm on Linux or Bray Terminal on Windows for accessing the
1363 serial interface. On \tgtBoardName{} board, the serial line is tunneled over
1365 % TODO: Conditional compilation
1366 % See Section \ref{sec-hardware-description} for reference about
1367 % the position of the serial interface connector on the RPP board.
1369 \section{Bug reporting}
1370 \label{sec-bug-reporting}
1372 Please report any problems to CTU's bug tracking system at
1373 \url{https://redmine.felk.cvut.cz/projects/eaton-rm48}. New users have
1374 to register in the system and notify Michal Sojka about their
1375 registration via $\langle{}sojkam1@fel.cvut.cz\rangle{}$ email
1378 \chapter{C Support Library}
1379 \label{chap-c-support-library}
1381 This chapter describes the implementation of the C support library
1382 (RPP Library), which is used both for Simulink code generation target
1383 and command line testing tool.
1385 \section{Introduction}
1386 \label{sec-description}
1387 The RPP C Support Library (also called RPP library) defines the API for
1388 working with the board. It includes drivers and the operating system.
1390 designed from the board user perspective and exposes a simplified high-level API
1391 to handle the board's peripheral modules in a safe manner. The library is
1392 compiled as static library named \texttt{rpp-lib.lib} and can be found in
1393 \texttt{\repo/rpp/lib}.
1395 The RPP library can be used in any project, where the RPP hardware
1396 support is required and it is also used in two applications --
1397 Simulink Coder Target, described in Chapter
1398 \ref{chap-simulink-coder-target}, and the command line testing tool,
1399 described in Chapter \ref{chap-rpp-test-software}.
1401 For details about the library architecture, refer to Section~\ref{sec-software-architecture}.
1403 \section{API development guidelines}
1404 \label{sec-api-development-guidlines}
1406 The following are the development guidelines used for developing the RPP API:
1409 \item User documentation should be placed in header files, not in source
1410 code, and should be Doxygen formatted using autobrief. Documentation for each
1411 function present is mandatory and must mention whether the function is
1413 \item Function declarations in the headers files is for public functions
1414 only. Do not declare local/static/private functions in the header.
1415 \item Documentation in source code files should be non-doxygen formatted
1416 and intended for developers, not users. Documentation here is optional and at
1417 the discretion of the developer.
1418 \item Always use standard data types for IO when possible. Use custom
1419 structs as very last resort. \item Use prefix based functions names to avoid
1420 clash. The prefix is of the form \texttt{$\langle$layer$\rangle$\_$\langle$module$\rangle$\_}, for example
1421 \texttt{rpp\_din\_update()} for the update function of the DIN module in the RPP
1423 \item Be very careful about symbol export. Because it is used as a
1424 static library the modules should not export any symbol that is not intended to
1425 be used (function) or \texttt{extern}'ed (variable) from application. As a rule
1426 of thumb declare all global variables as static.
1427 \item Only the RPP Layer symbols are available to user applications. All
1428 information related to lower layers is hidden for the application. This is
1429 accomplished by the inclusion of the rpp.h or rpp\_\{mnemonic\}.h file on the
1430 implementations files only and never on the interface files. Never expose any
1431 other layer to the application or to the whole system below the RPP layer. In
1432 other words, never \texttt{\#include "foo/bar.h"} in any RPP Layer header
1436 \section{Coding style}
1437 \label{sec-coding-style}
1438 In order to keep the code as clean as possible, unified coding style
1439 should be followed by any contributor to the code. The used coding
1440 style is based on the default configuration of Code Composer Studio
1441 editor. Most notable rule is that the Tab character is 4 spaces.
1443 The RPP library project is prepared for use of a tool named
1444 Uncrustify. The Uncrustify tool checks the code and fixes those lines
1445 that do not match the coding style. However, keep in mind that the
1446 program is not perfect and sometimes it can modify code where the
1447 suggested coding style has been followed. This does not causes
1448 problems as long as the contributor follows the committing procedure
1449 described in next paragraph.
1451 When contributing to the code, the contributor should learn the
1452 current coding style from existing code. When a new feature is
1453 implemented and committed to the local repository, the following
1454 commands should be called in Linux terminal:
1456 \begin{lstlisting}[language=bash]
1460 The first line command corrects many found coding style violations and
1461 the second command displays them. If the user agree with the
1462 modification, he/she should amend the last commit, for example by:
1463 \begin{lstlisting}[language=bash]
1468 \section{Subdirectory content description}
1469 \label{sec-rpp-lib-subdirectory-content-description}
1471 The following files and directories are present in the library source
1475 \item[rpp-lib.lib] Compiled RPP library.
1477 The library is needed for Simulink models and other ARM/\tgname{}
1478 applications. It is placed here by the Makefile, when the library is
1481 \item[apps/] Various applications related to the RPP library.
1483 This include the CCS studio project for generating of the static
1484 library and a test suite. The test suit in this directory has
1485 nothing common with the test suite described later in
1486 Chapter~\ref{chap-rpp-test-software} and those two suits are going
1487 to be merged in the future. Also other Hello World applications are
1488 included as a reference about how to create an \tgname{}
1490 \item[build] The library can be compiled for multiple targets. Each
1491 supported target has a subdirectory here, which stores configuration
1492 of how to compile the library and applications for different target.
1493 Each subdirectory contains a CCS project and Makefiles to build the
1494 library for the particular target.
1495 \item[build/$\langle$target$\rangle$/Makefile.config] Configuration
1496 for the particular target. This includes compiler and linker
1498 \item[build/$\langle$target$\rangle$/*.cmd]
1499 CGT Linker command file.
1501 This file is used by all applications that need to tun on the RPP
1502 board, including the Simulink models and test suite. It includes
1503 instructions for the CGT Linker about target memory layout and where
1504 to place various code sections.
1506 \item[halcogen/] HalCoGen project files for the supported boards and
1507 scripts for automated conversion of HalCoGen-generated files for use
1510 Note: This is work in progress. Currently only ``pinmux'' files for
1511 tms570\_hydctr board were produced by the scripts here.
1513 \item[os/] OS layers directory. See
1514 Section~\ref{sec-operating-system-layer} for more information about
1515 currently available operating system versions and
1516 Section~\ref{sec-changing-os} for information how to replace the
1518 \item[rpp/] Main directory for the RPP library.
1519 \item[rpp/doc/] RPP Library API
1521 \item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
1522 implementations files for given \texttt{\{layer\}}. See
1523 Section~\ref{sec-software-architecture} for details on the RPP
1525 \item[rpp/include/rpp/rpp.h] Main library header file.
1527 To use this library with all its modules, just include this file
1528 only. Also, before using any library function call the
1529 \texttt{rpp\_init()} function for hardware initialization.
1530 \item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for
1531 \texttt{\{mnemonic\}} module.
1533 These files includes function definitions, pin definitions, etc,
1534 specific to \{mnemonic\} module. See also
1535 Section~\ref{sec-api-development-guidlines}.
1537 If you want to use only a subset of library functions and make the
1538 resulting binary smaller, you may include only selected
1539 \texttt{rpp\_\{mnemonic\}.h} header files and call the specific
1540 \texttt{rpp\_\{mnemonic\}\_init} functions, instead of the
1541 \texttt{rpp.h} and \texttt{rpp\_init} function.
1542 \item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation.
1544 Implementation of \texttt{rpp\_\{mnemonic\}.h}'s functions on
1545 top of the DRV library.
1546 \item[rpp/src/rpp/rpp.c] Implementation of library-wide functions.
1549 \section{Compilation}
1550 \label{sec-compilation}
1552 To compile the library open the Code Composer studio project
1553 \texttt{rpp-lib} from appropriate \texttt{build/<target>} directory
1554 (see Section~\ref{sec-openning-of-existing-project}) and build the
1555 project (\textsc{Project $\rightarrow$ Build Project}). If the build
1556 process is successful, the \texttt{rpp-lib.lib} and
1557 \texttt{Makefile.config} files will appear in the library root
1560 It is also possible to compile the library using the included
1561 \texttt{Makefile}. From the Linux command line run:
1562 \begin{lstlisting}[language=bash]
1563 cd <library-root>/build/<target>/Debug #or Release
1566 Note that this only works if Code Composer Studio is installed in
1567 \texttt{/opt/ti} directory. Otherwise, you have to set
1568 \texttt{CCS\_UTILS\_DIR} variable.
1570 On Windows command line run:
1571 \begin{lstlisting}[language=bash]
1572 cd <library-root>\build\<target>\Debug
1573 set CCS_UTILS_DIR=C:\ti\ccsv5\utils
1574 C:\ti\ccsv5\utils\bin\gmake.exe lib
1577 You have to use \texttt{gmake.exe} instead of \texttt{make} and it is
1578 necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You can
1579 also edit \texttt{\repo/build/Makefile.rules.arm} and set the variable
1582 Note that the Makefile still requires the Code Composer Studio (ARM
1583 compiler) to be installed because of the CGT.
1585 \section{Compiling applications using the RPP library}
1586 \label{sec:comp-appl-using}
1588 The relevant aspects for compiling and linking an application using
1589 the RPP library are summarized below.
1591 % \subsection{ARM target (RPP board)}
1592 % \label{sec:arm-target-rpp}
1594 The detailed instructions are presented in
1595 Section~\ref{sec:creating-new-project}. Here we briefly repeat the
1599 \item Configure include search path to contain the directory of
1600 used FreeRTOS version, e.g.
1601 \texttt{\repo/os/8.2.2/include}. See Section
1602 \ref{sec-software-architecture}.
1603 \item Include \texttt{rpp/rpp.h} header file or just the needed
1604 peripheral specific header files such as \texttt{rpp/can.h}.
1605 \item Add library \texttt{rpp-lib.lib} to the linker libraries.
1606 The RPP library must be placed before Texas Instruments
1607 support library \tgtRtlib.
1608 \item Use the provided linker command file
1609 \texttt{\ldscriptname}.
1612 % \subsection{POSIX target}
1613 % \label{sec:posix-target}
1615 % \begin{compactitem}
1616 % \item Include headers files of the OS for Simulation. At the time
1617 % of this writing the OS is POSIX FreeRTOS 6.0.4.
1618 % \item Include header files for the RPP library or for modules you
1619 % want to use (rpp\_can.h for CAN module for example).
1620 % \item Add library \texttt{librpp.a} to the linker libraries.
1621 % \item Add \texttt{pthread} to the linker libraries.
1624 \section{Compiling API documentation}
1625 \label{sec-compiling-api-documentation}
1626 The documentation of the RPP layer is formatted using Doxygen
1627 documentation generator. This allows to generate a high quality API
1628 reference. To generate the API reference run in a Linux terminal:
1630 \lstset{language=bash}
1632 cd <repo>/rpp/doc/api
1634 xdg-open html/index.html
1637 The files under \texttt{\repo/rpp/doc/api/content} are used for the API
1638 reference generation are their name is self-explanatory:
1648 \section{Changing operating system}
1649 \label{sec-changing-os}
1650 The C Support Library contains by default the FreeRTOS operating
1651 system in version 8.2.2. This section describes what is necessary to
1652 change in the library and other packages in order to replace the
1655 \subsection{Operating system code and API}
1657 The source and header files of the current operating system (OS) are
1658 stored in directory \texttt{\repo/rpp/lib/os}. The files of the new
1659 operating system should also be placed in this directory.
1661 To make the methods and resources of the new OS available to the C Support
1662 Library, modify the \texttt{\repo/rpp/lib/rpp/include/base.h} file to include
1663 the operating system header files.
1665 Current implementation for FreeRTOS includes a header file
1666 \texttt{\repo/rpp/lib/os/\-8.2.2\-include/os.h}, which
1667 contains all necessary declarations and definitions for the FreeRTOS.
1668 We suggest to provide a similar header file for your operating system as
1671 In order to compile another operating system into the library, it is
1672 necessary to modify \texttt{\repo/rpp/lib/Makefile.var} file, which
1673 contains a list of files that are compiled into the library. All lines
1674 starting with \texttt{os/} should be updated.
1676 \subsection{Device drivers}
1677 Drivers for SCI and ADC depend on the FreeRTOS features. These
1678 features need to be replaced by equivalent features of the new
1679 operating system. Those files should be modified:
1681 \item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data
1682 structure, referring to FreeRTOS queue and semaphore.
1683 \item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Uses FreeRTOS queues
1685 \item[\repo/rpp/lib/rpp/include/drv/sci.h] Declaration of
1686 \texttt{drv\_sci\_receive()} contains \texttt{portTick\-Type}. We
1687 suggest replacing this with OS independent type, e.g. number of
1688 milliseconds to wait, with $-1$ meaning infinite waiting time.
1689 \item[\repo/rpp/lib/rpp/src/drv/sci.c] Uses the following FreeRTOS
1690 specific features: semaphores, queues, data types
1691 (\texttt{portBASE\_TYPE}) and
1692 critical sections (\texttt{taskENTER\_CRITICAL} and
1693 \texttt{task\-EXIT\_CRITICAL}). Inside FreeRTOS critical sections,
1694 task preemption is disabled. The same should be ensured by the other
1695 operating system or the driver should be rewritten to use other
1696 synchronization primitives.
1697 \item[\repo/rpp/lib/rpp/src/drv/adc.c] Uses FreeRTOS semaphores.
1700 \subsection{System start}
1701 The initialization of the MCU and the system is in the
1702 \texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} file. If the new
1703 operating system needs to handle interrupts generated by the Real-Time
1704 Interrupt module, the pointer to the Interrupt Service Routine (ISR)
1705 \texttt{vPreemptiveTick} has to be replaced.
1707 \subsection{Simulink template for main function}
1709 When the operating system in the library is replaced, the users of the
1710 library must be changed as well. In case of Simulink code generation
1711 target, described in Chapter~\ref{chap-simulink-coder-target}, the
1712 template for generation of the \texttt{ert\_main.c} file, containing
1713 the main function, has to be modified to use proper functions for task
1714 creation, task timing and semaphores. The template is stored in
1715 \texttt{\repo/rpp/rpp/rpp\_mrmain.tlc} file.
1717 \section{Networking support and configuration}
1718 \label{sec-configuration-network-interface}
1720 The RPP C support library includes lwIP networking
1721 stack\footnote{\url{https://savannah.nongnu.org/projects/lwip/}} to
1722 implement TCP/IP networking. The lwIP stack is integrated with the
1723 Ethernet driver and the rest of the RPP library.
1725 To use TCP/IP networking (either in developed C applications or for Simulink external mode -- see Section~\ref{sec-external-mode}), it is currently necessary to set a few parameters (MAC and IP addresses) in the \texttt{eth.h} file. The current implementation does not support automatic IP address configuration through the DHCP server.
1727 The MAC address of the Ethernet interface is not fixed in hardware, it must be set by software. The settings shown below works fine, unless multiple target boards are connected to the same network. In that case, the MAC address has to be changed so that each board has a distinct MAC address.
1729 To configure TCP/IP networking, the following parameters has to be set: board's IP address and network mask, and the default gateway. Their values must correspond to the network to which the board is connected.
1731 The parameters and their default values (as stored in \texttt{rpp/lib/rpp/include/rpp/eth.h}) are shown below:
1733 \begin{lstlisting}[language=c]
1734 #define RPP_MAC_ADDR { 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC }
1735 #define RPP_IP_ADDR 0x0A235F19 // 10.35.95.25
1736 #define RPP_NETMASK 0xFFFFFF00 // 255.255.255.0
1737 #define RPP_GW 0x0A235F01 // 10.35.95.1
1742 \chapter{Simulink Coder Target}
1743 \label{chap-simulink-coder-target}
1745 The Simulink Coder Target allows to convert Simulink models to C code,
1746 compile it and download to the board.
1748 \section{Introduction}
1749 \label{sec-introduction}
1751 The Simulink RPP Target provides support for C source code generation from Simulink models and
1752 compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
1753 uses Texas Instruments ARM compiler (\texttt{armcl}) included in the Code Generation Tools distributed with
1754 Code Composer Studio, and thus it depends on it for proper functioning.
1756 This target also provides support for automatic download of the compiled binary to the RPP
1759 \begin{figure}\begin{center}
1761 \includegraphics[scale=.45]{images/tlc_process.png}
1762 \caption{TLC code generation process. \cite[p. 1-6]{targetlanguagecompiler2013}}
1763 \end{center}\end{figure}
1765 \section{Features and limitations}
1766 \label{sec-features}
1769 \item Sampling frequencies up to 1\,kHz.
1770 \item Multi-rate models can be executed in a single or multiple OS
1771 tasks. Multi-tasking mode allows high-rate tasks to preempt low-rate
1772 tasks. See Section \ref{sec-singlet-multit-modes} for more details.
1773 \item Support of external mode over TCP/IP with some limitations. See Section~\ref{sec-external-mode} for more details.
1774 \item Custom compiler options, available via OPTS variable in
1775 \emph{Make command} at \emph{Code Generation} tab (see Figure
1776 \ref{fig-code-gen-settings}). For example \texttt{make\_rtw
1780 \section{RPP Options pane}
1781 \label{sec-rpp-target-options}
1783 The RPP Target includes the following configuration options, all of them
1784 configurable per model under \textsc{Code Generation} \noindent$\rightarrow$
1785 \textsc{RPP Options}:
1788 \item \textbf{C system stack size}: this parameter is passed directly
1789 to the linker for the allocation of the stack. Note that this stack
1790 is used only for initializing the application and FreeRTOS. Once
1791 everything is initialized, another stack is used by the generated
1792 code. See below. Default value is 4096.
1794 \item \textbf{C system heap size}:
1795 \label{sec-rpp-target-options-heap-size} this parameter is passed
1796 directly to the linker for the allocation of the heap. Currently,
1797 the heap is not used, but will be used by the external mode in the future.
1798 Note that FreeRTOS uses its own heap whose size is independent of this
1800 \item \textbf{Model step task stack size}: this parameter will be
1801 passed to the \texttt{xTaskCreate()} that
1802 creates the task for the model to run. In a Simulink model there are always two tasks:
1804 \item The worker task. This task is the one that executes the model
1805 step. This task requires enough stack memory to execute the step.
1806 If your model does not run, it might be caused by too small stack.
1807 The memory needed for the stack depends on the size and structure
1809 \item The control task. This task controls when the worker task should execute and controls overruns.
1812 \item \textbf{Download compiled binary to RPP}: if set, this option will download the generated binary to
1813 the board after the model is successfully built. Note that this option is unaware of the option
1814 \textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to download even if
1815 only source code has been generated, failing graciously or uploading an old binary laying around
1816 in the build directory. This option calls the \texttt{rpp\_download.m} script, which is in turn a
1817 wrapper on the \texttt{loadti.sh}, \texttt{loadti.bat} and \texttt{loadopenocd.sh} script. More information on the \texttt{loadti.sh}
1818 script can be found in:
1820 <ccs>/ccs_base/scripting/examples/loadti/readme.txt
1821 http://processors.wiki.ti.com/index.php/Loadti
1824 The \texttt{loadti.sh} and \texttt{loadti.bat} script will close after the
1825 download of the generated program, leaving the loaded program running.
1827 The \texttt{loadopenocd.sh} script will close after the download of the
1828 generated program as well, but the program will be stopped. In order to run
1829 the loaded program a manual reset of the board is required.
1831 \item \textbf{Download compiled binary to SDRAM}: This feature is not yet
1832 implemented for the simulink target.
1834 \item \textbf{Use OpenOCD to download the compiled binary}: This feature is not yet
1835 implemented for the \mcuname{} simulink target.
1836 % TODO Not true - use conditional compilation here.
1838 \item \textbf{Print model metadata to SCI at start}: if set this option will
1839 print a message to the Serial Communication Interface when the model start
1840 execution on the board. This is very helpful to identify the model running on
1841 the board. The message is in the form:
1844 `model_name' - generated_date (TLC tlc_version)
1849 `hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
1853 \section{Subdirectory content description}
1854 \label{sec-simulink-subdirectory-content-description}
1855 This section describes the directories of the Simulink Coder. If you are
1856 interested in particular file, refer the description at the beginning of the
1860 \item[doc/] Contains the sources of the documentation, you are now
1862 \item[refs/] Contains third party references, which license allows the
1864 \item[rpp/blocks] Contains the Simulink blocks specific to the
1865 \tgtBoardName{} board and their sources (.c and .tlc files). When an
1866 user calls \texttt{rpp\_setup.m}, these files are processed and
1867 Simulink block library \texttt{rpp\_lib.slx} is created.
1868 \item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the
1869 Matlab Simulink model.
1870 \item[rpp/demos] Contains demo models, which purpose is to serve as a
1871 reference for the usage and for testing.
1872 \item[rpp/lib] Contains the C Support Library. See Chapter
1873 \ref{chap-c-support-library}. \item[rpp/loadopenocd] Contains download scripts
1874 for Linux support of the OpenOCD, for code downloading to the target.
1875 \item[rpp/loadti] Contains download scripts for Linux and Windows
1876 support for code downloading to the target, using Texas Instruments CCS code
1878 \item[rpp/rpp] Contains set of support script for the Code Generator.
1881 \section{Tasking modes}
1882 \label{sec-singlet-multit-modes}
1884 This section describes two different modes (single- and multi-tasking)
1885 of how generated code of multi-rate models can be executed. Tasking
1886 mode can be selected for every model in the configuration dialog as
1887 described in Section \ref{sec-crating-new-model}.
1889 For single-rate models, the mode selection does not matter. For
1890 multi-rate models, the mode selection becomes important as it may
1891 influence certain system properties such as safety or performance.
1893 \subsection{SingleTasking mode}
1894 \label{sec-singlet-mode}
1895 In this mode all Simulink tasks, defined by their sampling rate, run
1896 in a single operating system task (thread). This means that the period
1897 of the highest rate Simulink task cannot be greater than the
1898 worst-case execution time of all Simulink tasks together. On the other
1899 hand, using this mode reduces the risk of failures caused by task
1900 synchronization errors, e.g. race conditions, deadlocks.
1902 \subsection{MultiTasking mode}
1903 \label{sec-multit-mode}
1905 In this mode every Simulink task, defined by its sampling rate, runs
1906 in its own operating system task (thread). Thread priorities are
1907 assigned based on task rates in such a way that tasks with higher
1908 rates can preempt tasks with lower rates. This means that the period
1909 of the fastest sampling rate is limited only by the execution time of
1910 this task and not of all the tasks in the system.
1912 This mode offers more efficient use of system resources (CPU) but
1913 there is a possibility of failures caused by task synchronization
1916 \section{Block Library Overview}
1917 \label{sec-block-library-overview}
1918 The Simulink Block Library is a set of blocks that allows Simulink models to use
1919 board IO and communication peripherals. The available blocks are summarized in
1920 Table~\ref{tab:block-lib-status} and more detailed description is
1921 given in Section~\ref{sec-blocks-description}.
1924 \begin{center}\begin{tabular}{|lp{5cm}lll|}
1926 \textbf{Category} & \textbf{Name} & \textbf{Status} & \textbf{Mnemonic} & \textbf{Header} \\
1928 \input{block_table.tex}
1930 \end{tabular}\end{center}
1932 \caption{Block library overview}
1933 \label{tab:block-lib-status}
1936 \label{sec-blocks-implementation}
1937 All of the blocks are implemented as manually created C Mex S-Function . In this section the
1938 approach taken is briefly explained.
1940 \subsection{C MEX S-Functions}
1941 \label{sec-c-mex-functions}
1943 \item C : Implemented in C language. Other options are Fortran and Matlab language itself.
1944 \item MEX: Matlab Executable. They are compiled by Matlab - C compiler wrapper called MEX.
1945 \item S-Function: System Function, as opposed to standard functions, or user functions.
1948 A C MEX S-Function is a structured C file that implements some mandatory and
1949 optional callbacks for a specification of a number of inputs, outputs, data
1950 types, parameters, rate, validity checking, etc. A complete list of callbacks
1953 \htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
1956 The way a C MEX S-Function participates in a Simulink simulation is shown on the
1957 diagram \ref{fig-sfunctions-process}:
1959 \begin{figure}[H]\begin{center}
1961 \includegraphics[scale=.45]{images/sfunctions_process.png}
1962 \caption{Simulation cycle of a S-Function. \cite[p. 57]{simulinkdevelopingsfunctions2013}}
1963 \label{fig-sfunctions-process}
1964 \end{center}\end{figure}
1966 In general, the S-Function can perform calculations, inputs and outputs for simulation. Because
1967 the RPP blocks are for hardware peripherals control and IO the blocks are
1968 implemented as pure sink or pure source, the S-Function is just a descriptor of
1969 the block and does not perform any calculation and does not provide any input or
1970 output for simulations.
1972 The implementation of the S-Functions in the RPP project has following layout:
1975 \item Define S-Function name \texttt{S\_FUNCTION\_NAME}.
1976 \item Include header file \texttt{header.c}, which in connection with
1977 \texttt{trailer.c} creates a miniframework for writing S-Functions.
1978 \item In \texttt{mdlInitializeSizes} define:
1980 \item Number of \textit{dialog} parameter.
1981 \item Number of input ports.
1983 \item Data type of each input port.
1985 \item Number of output ports.
1987 \item Data type of each output port.
1989 \item Standard options for driver blocks.
1991 \item In \texttt{mdlCheckParameters}:
1993 \item Check data type of each parameter.
1994 \item Check range, if applicable, of each parameter.
1996 \item In \texttt{mdlSetWorkWidths}:
1998 \item Map \textit{dialog} parameter to \textit{runtime} parameters.
2000 \item Data type of each \textit{runtime} parameter.
2003 \item Define symbols for unused functions.
2004 \item Include trailer file \texttt{trailer.c}.
2007 The C MEX S-Function implemented can be compiled with the following command:
2009 \lstset{language=bash}
2011 <matlabroot>/bin/mex sfunction_{mnemonic}.c
2014 As noted the standard is to always prefix S-Function with \texttt{sfunction\_}
2015 and use lower case mnemonic of the block.
2017 Also a script called \texttt{compile\_blocks.m} is included. The script that
2018 allows all \texttt{sfunctions\_*.c} to be fed to the \texttt{mex} compiler so
2019 all S-Functions are compiled at once. To use this script, in Matlab do:
2021 \lstset{language=Matlab}
2023 cd <repo>/rpp/blocks/
2027 \subsection{Target Language Compiler files}
2028 \label{sec-target-language-compiler-files}
2030 In order to generate code for each one of the S-Functions, every S-Function implements a TLC file
2031 for \textit{inlining} the S-Function on the generated code. The TLC files describe how to
2032 generate code for a specific C MEX S-Function block. They are programmed using TLC own language and
2033 include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX
2036 The standard for a TLC file is to be located under the \texttt{tlc\_c} subfolder from where the
2037 S-Function is located and to use the very exact file name as the S-Function but with the \texttt{.tlc}
2038 extension: \texttt{sfunction\_foo.c} \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_foo.tlc}
2040 The TLC files implemented for this project use 3 hook functions in particular (other are available,
2041 see TLC reference documentation):
2043 \item \texttt{BlockTypeSetup}: \newline{}
2044 BlockTypeSetup executes once per block type before code generation begins.
2045 This function can be used to include elements required by this block type, like includes or
2047 \item \texttt{Start}: \newline{}
2048 Code here will be placed in the \texttt{void
2049 $\langle$modelname$\rangle$\_initialize(void)}. Code placed here will execute
2051 \item \texttt{Outputs}: \newline{}
2052 Code here will be placed in the \texttt{void
2053 $\langle$modelname$\rangle$\_step(void)} function. Should be used to get the
2054 inputs of a block and/or to set the outputs of that block.
2057 The general layout of the TLC files implemented for this project is:
2059 \item In \texttt{BlockTypeSetup}: \newline{}
2060 Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
2061 \texttt{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
2062 \item \texttt{Start}: \newline{}
2063 Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup,
2064 DAC value initialization, SCI baud rate setup, among others.
2065 \item \texttt{Outputs}: \newline{}
2066 Call common IO routines from RPP Layer, like DIN read, DAC set, etc. Success of this functions
2067 is checked and in case of failure error is reported to the block using ErrFlag.
2070 C code generated from a Simulink model is placed on a file called
2071 \texttt{$\langle$modelname$\rangle$.c} along with other support files in a
2072 folder called \texttt{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}.
2073 For example, the source code generated for model \texttt{foobar} will be placed
2074 in current Matlab directory \texttt{foobar\_rpp/foobar.c}.
2076 The file \texttt{$\langle$modelname$\rangle$.c} has 3 main functions:
2078 \item \texttt{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
2079 This function recalculates all the outputs of the blocks and should be called once per step. This
2080 is the main working function.
2081 \item \texttt{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
2082 This function is called only once before the first step is issued. Default values for blocks IOs
2083 should be placed here.
2084 \item \texttt{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
2085 This function is called when terminating the model. This should be used to free memory or revert
2086 other operations made in the initialization function. With current implementation this function
2087 should never be called unless an error is detected and in most models it is empty.
2090 \section{Block reference}
2091 \label{sec-blocks-description}
2093 This section describes each one of the Simulink blocks present in the Simulink
2094 RPP block library, shown in Figure \ref{fig-block-library}.
2098 \includegraphics[width=\textwidth]{images/block_library.png}
2100 \caption{Simulink RPP Block Library.}
2101 \label{fig-block-library}
2104 \input{block_desc.tex}
2107 \section{Compilation}
2108 \label{sec-simulink-compilation}
2109 The first step, before any attempt to compile demo or other models, is to compile the S-Functions of the RPP blocks. The S-Functions are compiled during the Configuring Simulink for RPP, described in Section \ref{sec-configuration-simulink-for-rpp}. If you want to recompile the S-Functions without reconfiguring the Simulink, open the Matlab and run those commands in the Matlab commad line:
2110 \lstset{language=Matlab}
2112 cd <rpp-simulink>/rpp/blocks
2116 Once the S-Functions are compiled, the C code can be generated from the models. Demos can be compiled one by one with a procedure described in Section \ref{sec-openning-demo-models} or all at once with one of those procedures:
2119 \item Open Matlab and run those commands in the Matlab command line:
2120 \lstset{language=Matlab}
2122 cd <rpp-simulink>/rpp/demos
2125 \item Run those commands in a Linux terminal:
2126 \begin{lstlisting}[language=bash]
2127 cd <rpp-simulink>/rpp/demos
2131 or Windows command line:
2133 \begin{lstlisting}[language=bash]
2134 cd <rpp-simulink>\rpp\demos
2135 "C:\ti\ccsv5\utils\bin\"gmake.exe lib
2138 Both commands will create a directory for each compiled demo, which will contain the generated C code and binary file with the firmware. To download the firmware to the board and run it, see Section \ref{sec-running-software-on-hw}.
2141 \section{External mode}
2142 \label{sec-external-mode}
2143 Simulink external mode allows real-time communication between Simulink and the generated code running on the target device. With it, one can monitor the values of Simulink signals and change values of some Simulink block parameters, e.g., gains. Simulink communicates with the device via a TCP connection. For correct operation of the external mode, it is necessary to configure the static IP address, mask, and default gateway, as described in Section~\ref{sec-configuration-network-interface}.
2145 Using the external mode involves the following activities:
2147 \item Setting up the model,
2148 \item building the target executable,
2149 \item running the external mode target program, and finally
2150 \item tuning parameters and watching signals in real-time.
2152 These activities are described in greater detail in the following sections.
2154 \subsection{Setting up the model}
2156 If one wants to watch signals in the model, when it is running on the target board, scope blocks should be added to the model. An example of an external mode model with scope blocks is shown in Fig.~\ref{fig:extmode-model}.
2158 \begin{figure}\begin{center}
2160 \includegraphics[scale=.45]{images/extmod_scheme.png}
2161 \caption{Example model for external mode}
2162 \label{fig:extmode-model}
2163 \end{center}\end{figure}
2165 The model has to be configured in a specific way for the external model to work. All the necessary configuration is described below. The description and the path to the individual parameters is based on Simulink version 2018a.
2168 \item Open the Configuration Parameters dialog box by selecting \textsc{Simulation → Model Configuration Parameters}.
2169 \item Select the \textsc{Solver} pane.
2170 \item In the \textsc{Solver options} subpane:
2172 \item In the \textsc{Type} field, select \emph{Fixed-step}.
2173 \item In the \textsc{Solver} field, select \emph{discrete (no continuous states)}.
2174 \item In the \textsc{Fixed-step size} field, specify the sampling period of your model. External mode communication was tested with the value of \emph{0.1}.
2177 \begin{figure}[!h]\begin{center}
2179 \includegraphics[scale=.45]{images/extmod_solver.png}
2180 \caption{Solver setup}
2181 \end{center}\end{figure}
2183 \item Select the \textsc{Hardware Implementation} pane.
2185 \item In the Device vendor field, select proper vendor (example Texas Instruments)
2186 \item In the Device type field, select proper target (example TSM570).
2188 \item Select the \textsc{Code Generation} pane and check that \emph{rpp.tlc} is selected as target.
2189 \item Select the \textsc{Code Generation → Optimization}. Set field \textsc{Default parameter behavior} to \emph{Tunable}.
2190 \begin{figure}[!h]\begin{center}
2192 \includegraphics[scale=.45]{images/exmod_parameters.png}
2193 \caption{Set parameters tuneble for external mode}
2194 \end{center}\end{figure}
2196 \item Select the \textsc{Code Generation → Interface} pane.
2198 \item In section \textsc{Software environment → Software environment
2199 → Support}. Enable \emph{floating-point numbers}, \emph{absolute
2200 time} and \emph{continuous time}.
2201 \item In section \textsc{Data exchange interface → Generate C API for}
2202 check \emph{parameters} and \emph{signals}.
2203 \item Enable \textsc{Data exchange interface → External mode} and configure subsection \emph{External mode configuration}: select transport layer to \emph{tcpip} and \textsc{MEX-file arguments} to \emph{$\langle$IP address$\rangle$ 1 $\langle$port$\rangle$}. \emph{IP address} is the IP address of the board, e.g., the one set in \texttt{eth.h}. \emph{Port} is the port where the board listens for Simulink connection. Its value should be 17725, which is also the default so the number can be omitted here.
2205 Example value of \textsc{MEX-file arguments} is: \texttt{"10.35.95.25" 1 17725}
2208 \begin{figure}[!h]\begin{center}
2210 \includegraphics[scale=.45]{images/extmod_interface.png}
2211 \caption{External mode interface setup}
2212 \end{center}\end{figure}
2214 \item In the \textsc{RPP Options} pane, increase \textsc{C system heap size} to \emph{65536}. External mode uses this heap to allocate networking buffers. Check that \emph{Download compiled binary to RPP} is enabled.
2215 \item Close \textsc{Configuration Parameters} dialog box by pressing \textsc{Ok}.
2216 \item Open \textsc{Code → External Mode Control Panel} menu and press \textsc{Signals \& Triggering…} button.
2218 \item In \textsc{Signal section} part of opened dialog box select all scopes.
2219 \item In the \textsc{Trigger options} part set the \textsc{Duration} to \emph{500}.
2221 This value configures the length of the outgoing buffer on the target board. As the frequency of the model increases, the buffer may become full before the data is sent to Simulink, which leads to periodic data outages. These outages can be partially reduced by increasing the \textsc{Duration} value to a sufficiently high value. Due to limited memory, it may be necessary to increase the \textsc{C system heap size} on the \textsc{RPP Options} pane to increase the \textsc{Duration} value further. This value must not be greater than the remaining free heap memory on the target.
2225 \subsection{Build the target executable}
2226 For correct model compilation, it is necessary to switch the simulation mode from \emph{normal} to \emph{external} via \textsc{Simulation → Mode} menu. It is also advisable to select the \emph{Simulation stop time}, to value \emph{inf}.
2227 Then, the model can be compiled and downloaded to the device using the \textsc{Build Model} button in the Simulink model window toolbar.
2229 \subsection{Run the External mode target program}
2230 Once the model has been successfully uploaded to the target, communication must be initiated. This is possible by using the \textsc{Simulation → Connect To Target} menu or the \textsc{Connect} button in the \textsc{External Mode Control Panel}. The program on the target device starts running as soon as the binary file is uploaded, waiting for connection from the Simulink before starting the program is currently not implemented.
2232 \subsection{Tune parameters and watch signals}
2233 After a successful connection to the device, it is possible to configure the gain parameters and view the signal values in scopes blocks in the standard way as during normal Simulink simulation.
2235 \section{Adding new functionality}
2236 \label{sec:adding-new-funct}
2237 This section describes how to create new Simulink blocks and how to add them to the RPP
2238 blocks library. The new block creation process consists of several steps:
2240 \item Addition of the new functionality to the RPP C support library.
2241 \item Definition of the block interface as a C MEX S-Function
2242 (Section~\ref{sec:block-definition-c})
2243 \item Compilation of the block definition to MEX file
2244 (Section~\ref{sec:c-mex-file})
2245 \item Creation of the code generator template (TLC) file
2246 (Section~\ref{sec:tlc-file-creation}).
2247 \item Creation of an S-Function block in the RPP block library
2248 and ``connecting'' this block with the C MEX and TLC files
2249 (Section~\ref{sec:creation-an-s})
2250 \item Optional: Creation of the mask for the new block. The mask
2251 specifies graphical representation of the block as well as
2252 the content of the block parameters dialog box.
2254 The following subsections demonstrate the procedure on an example of a simple user defined block.
2256 \subsection{Block interface definition in a C MEX S-function}
2257 \label{sec:block-definition-c}
2258 In order to use a custom block in the Simulink model, Simulink must know
2259 a certain number of block attributes, such as the number and type of
2260 block inputs, outputs and parameters. These attributes are specified
2261 by a set of functions in a C file. This C file gets compiled by the MEX
2262 compiler into a MEX file and is then used in an S-Function block.
2263 Simulink calls the functions in the C MEX file to obtain the above
2264 mentioned block attributes. In case of RPP blocks, no other
2265 functionality is present in the C MEX file.
2267 The C files are stored in \texttt{\repo/rpp/blocks} directory and are named as
2268 \texttt{sfunction\_$\langle$name$\rangle$.c}. Feel free to open any of
2269 the C files as a reference.
2271 Every C file that will be used with the RPP library should begin with
2272 a comment in YAML\footnote{\url{http://yaml.org/},
2273 \url{https://en.wikipedia.org/wiki/YAML}} format. The information in
2274 this block is used to automatically generate both printed and on-line
2275 documentation. Although this block is not mandatory, it is highly
2276 recommended, as it helps keeping the documentation consistent and
2279 The YAML documentation block may look like this:
2280 \begin{lstlisting}[language=c,basicstyle=\texttt\footnotesize]
2284 Name: Name Of The Block
2290 - { name: "Some Input Signal", type: "bool" }
2293 - { name: "Some Output Signal", type: "bool" }
2297 # Description and Help is in Markdown mark-up
2300 This is a stub of an example block.
2304 This block is a part of an example about how to create
2305 new Matlab Simulink blocks for RPP board.
2309 RPP API functions used:
2317 Following parts are obligatory and the block will not work without them. It starts with a
2318 definition of the block name and inclusion of a common source file:
2320 \begin{lstlisting}[language=c]
2321 #define S_FUNCTION_NAME sfunction_myblock
2325 To let Simulink know the type of the inputs, outputs and how many parameters
2326 will the block have, the \texttt{mdlInitializeSizes()} function has to be defined like this:
2328 \begin{lstlisting}[language=c]
2329 static void mdlInitializeSizes(SimStruct *S)
2331 /* The block will have no parameters. */
2332 if (!rppSetNumParams(S, 0)) {
2335 /* The block will have one input signal. */
2336 if (!ssSetNumInputPorts(S, 1)) {
2339 /* The input signal will be of type boolean */
2340 rppAddInputPort(S, 0, SS_BOOLEAN);
2341 /* The block will have one output signal */
2342 if (!ssSetNumOutputPorts(S, 1)) {
2345 /* The output signal will be of type boolean */
2346 rppAddOutputPort(S, 0, SS_BOOLEAN);
2348 rppSetStandardOptions(S);
2352 The C file may contain several other optional functions definitions for parameters check,
2353 run-time parameters definition and so on. For information about those functions refer the comments
2354 in the header.c file, trailer.c file and documentation of Simulink S-Functions.
2356 The minimal C file compilable into C MEX has to contain following
2357 macros to avoid linker error messages about some of the optional
2358 functions not being defined:
2359 \begin{lstlisting}[language=c]
2360 #define COMMON_MDLINITIALIZESAMPLETIMES_INHERIT
2361 #define UNUSED_MDLCHECKPARAMETERS
2362 #define UNUSED_MDLOUTPUTS
2363 #define UNUSED_MDLTERMINATE
2366 Every C file should end by inclusion of a common trailer source file:
2368 \begin{lstlisting}[language=c]
2369 #include "trailer.c"
2372 \subsection{C MEX file compilation}
2373 \label{sec:c-mex-file}
2374 In order to compile the created C file, the development environment
2375 has to be configured first as described in
2376 Section~\ref{sec-matlab-simulink-usage}.
2378 All C files in the directory \texttt{\repo/rpp/blocks} can be compiled
2379 into C MEX by running script
2380 \texttt{\repo/rpp/blocks/compile\_blocks.m} from Matlab command
2381 prompt. If your block requires some special compiler options, edit the
2382 script and add a branch for your block.
2384 To compile only one block run the \texttt{mex sfunction\_myblock.c}
2385 from Matlab command prompt.
2387 \subsection{TLC file creation}
2388 \label{sec:tlc-file-creation}
2389 The TLC file is a template used by the code generator to generate the
2390 C code for the RPP board. The TLC files are stored in
2391 \texttt{\repo/rpp/blocks/tlc\_c} folder and their names must be the
2392 same (except for the extension) as the names of the corresponding
2393 S-Functions, i.e. \texttt{sfunction\_$\langle$name$\rangle$.tlc}. Feel
2394 free to open any of the TLC files as a reference.
2396 TLC files for RPP blocks should contain a header:
2397 \begin{lstlisting}[language=c]
2398 %implements sfunction_myblock "C"
2399 %include "common.tlc"
2402 Code Generator expects several functions to be implemented in the TLC file. The functions are not obligatory, but most of the blocks will probably need them:
2404 \item BlockTypeSetup
2405 \item BlockInstanceSetup
2410 For detailed description about each one of those functions, refer to
2411 \cite{targetlanguagecompiler2013}. A simple TLC file, which generates
2412 some code may look like this:
2413 \begin{lstlisting}[language=c]
2414 %implements sfunction_myblock "C"
2415 %include "common.tlc"
2417 %function BlockTypeSetup(block, system) void
2418 %% Ensure required header files are included
2419 %<RppCommonBlockTypeSetup(block, system)>
2420 %<LibAddToCommonIncludes("rpp/sci.h")>
2423 %function Outputs(block, system) Output
2424 %if !SLibCodeGenForSim()
2425 %assign in_signal = LibBlockInputSignal(0, "", "", 0)
2426 %assign out_signal = LibBlockOutputSignal(0, "", "", 0)
2428 %<out_signal> = !%<in_signal>;
2429 rpp_sci_printf("Value: %d\r\n", %<in_signal>);
2435 The above template causes the generated code to contain
2436 \texttt{\#include "rpp/sci.h"} line and whenever the block is
2437 executed, its output will be the negation of its input and the value
2438 of the input signal will be printed to the serial line.
2440 \subsection{Creation of an S-Function block in the RPP block library}
2441 \label{sec:creation-an-s}
2442 User defined Simulink blocks can be included in the model as
2443 S-Function blocks. Follow this procedure to create a new block in the
2446 \item Create a new Simulink library by selecting
2447 \textsc{File$\rightarrow$New$\rightarrow$Library} and save it as
2448 \texttt{\repo\-/rpp/blocks/rpp\_$\langle$name$\rangle$.slx}.
2449 Alternatively, open an existing library.
2450 \item In case of opening an existing library, unlock it for editing by
2451 choosing \textsc{Diagram$\rightarrow$Unlock Library}.
2452 \item Open a Simulink Library Browser
2453 (\textsc{View$\rightarrow$Library Browser}) open
2454 \textsc{Simulink$\rightarrow$User-Defined Functions} and drag the
2455 \textsc{S-Function} block into the newly created library.
2456 \item Double click on the just created \textsc{S-Function} block and
2457 fill in the \textsc{S-function name} field. Put there the name
2458 (without the extension) of the created C MEX S-Function, e.g.
2459 sfunction\_myblock. The result should like like in
2460 Figure~\ref{fig-simulink_s_fun_cfg}.
2461 \begin{figure}[h]\begin{center}
2463 \includegraphics[scale=.45]{images/simulink_s_fun_config.png}
2464 \caption{Configuration dialog for user defined S-function.}
2465 \label{fig-simulink_s_fun_cfg}
2466 \end{center}\end{figure}
2467 \item If your block has some parameters, write their names (you can
2468 choose them arbitrarily) in the \textsc{S-function parameters}
2469 field, separated by commas. \label{item:1}
2470 \item Now you should see the new Simulink block with the right number
2471 of inputs and outputs.
2472 \item Optional: Every user-defined block can have a \emph{mask}, which
2473 provides some useful information about the name of the block,
2474 configuration dialog for parameters and names of the IO signals. The
2475 block can be used even without the mask, but it is not as user
2476 friendly as with proper mask. Right-click the block and select
2477 \textsc{Mask$\rightarrow$Create Mask...}. In the definition of
2478 parameters, use the same names as in step~\ref{item:1}. See
2479 \cite[Section ``Block Masks'']{mathworks13:simul_2013b} for more
2481 \item Save the library and run \texttt{rpp\_setup} (or just
2482 \texttt{rpp\_generate\_lib}) from Matlab command line to add the newly
2483 created block to RPP block library (\texttt{rpp\_lib.slx}).
2486 Now, you can start using the new block in Simulink models as described
2487 in Section~\ref{sec-crating-new-model}.
2490 \section{Demos reference}
2491 The Simulink RPP Demo Library is a set of Simulink models that use blocks from
2492 the Simulink RPP Block Library and generates code using the Simulink RPP Target.
2494 This demos library is used as a test suite for the Simulink RPP Block Library
2495 but they are also intended to show basic programs built using it. Because of
2496 this, the demos try to use more than one
2497 type of block and more than one block per block type.
2499 In the reference below you can find a complete description for each of the demos.
2501 \subsection{ADC demo}
2502 \begin{figure}[H]\begin{center}
2504 \includegraphics[scale=.45]{images/demo_adc.png}
2505 \caption{Example of the usage of the Analog Input blocks for RPP.}
2506 \end{center}\end{figure}
2508 \textbf{Description:}
2510 Demostrates how to use Analog Input blocks in order to measure voltage. This demo
2511 measures voltage on every available Analog Input and prints the values on the
2514 \subsection{Simple CAN demo}
2515 \begin{figure}[H]\begin{center}
2517 \includegraphics[scale=.45]{images/demo_simple_can.png}
2518 \caption{The simplest CAN demonstration.}
2519 \end{center}\end{figure}
2521 \textbf{Description:}
2523 The simplest possible usage of the CAN bus. This demo is above all designed for
2524 testing the CAN configuration and transmission.
2526 \subsection{CAN transmit}
2527 \begin{figure}[H]\begin{center}
2529 \includegraphics[scale=.45]{images/demo_cantransmit.png}
2530 \caption{Example of the usage of the CAN blocks for RPP.}
2531 \end{center}\end{figure}
2533 \textbf{Description:}
2535 Demostrates how to use CAN Transmit blocks in order to:
2538 \item Send unpacked data with data type uint8, uint16 and uint32.
2539 \item Send single and multiple signals packed into CAN\_MESSAGE by CAN Pack block.
2540 \item Send a message as extended frame type to be received by CAN Receive
2541 configured to receive both, standard and extended frame types.
2544 Demostrates how to use CAN Receive blocks in order to:
2547 \item Receive unpacked data of data types uint8, uint16 and uint32.
2548 \item Receive and unpack received CAN\_MESSAGE by CAN Unpack block.
2549 \item Configure CAN Receive block to receive Standard, Extended and both frame types.
2550 \item Use function-call mechanism to process received messages
2553 \subsection{Continuous time demo}
2554 \begin{figure}[H]\begin{center}
2556 \includegraphics[scale=.45]{images/demo_continuous.png}
2557 \caption{The demonstration of contiuous time.}
2558 \end{center}\end{figure}
2560 \textbf{Description:}
2562 This demo contains two integrators, which are running at continuous time. The main goal
2563 of this demo is to verify that the generated code is compilable and is working even when
2564 discrete and continuous time blocks are combined together.
2566 \subsection{Simulink Demo model}
2567 \begin{figure}[H]\begin{center}
2569 \includegraphics[scale=.45]{images/demo_board.png}
2570 \caption{Model of the complex demonstration of the boards peripherals.}
2571 \end{center}\end{figure}
2573 \textbf{Description:}
2575 This model demonstrates the usage of RPP Simulink blocks in a complex and interactive
2576 application. The TI HDK kit has eight LEDs placed around the MCU. The application
2577 rotates the light around the MCU in one direction. Every time the user presses the button
2578 on the HDK, the direction is switched.
2580 The state of the LEDs is sent on the CAN bus as a message with ID 0x1. The button can
2581 be emulated by CAN messages with ID 0x0. The message 0x00000000 simulates button release
2582 and the message 0xFFFFFFFF simulates the button press.
2584 Information about the state of the application are printed on the Serial Interface.
2586 \subsection{Echo char}
2587 \begin{figure}[H]\begin{center}
2589 \includegraphics[scale=.45]{images/demo_echo_char.png}
2590 \caption{Echo Character Simulink demo for RPP.}
2591 \end{center}\end{figure}
2593 \textbf{Description:}
2595 This demo will echo (print back) any character received through the Serial Communication
2596 Interface (115200-8-N-1).
2598 Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
2599 if data is received, that is, Serial Receive output is non-negative. Negative values are errors.
2601 \subsection{GIO demo}
2602 \begin{figure}[H]\begin{center}
2604 \includegraphics[scale=.45]{images/demo_gio.png}
2605 \caption{Demonstration of DIN and DOUT blocks}
2606 \end{center}\end{figure}
2608 \textbf{Description:}
2610 The model demonstrates how to use the DIN blocks and DOUT blocks, configured in every mode. The DOUTs
2611 are pushed high and low with period 1 second. The DINs are reading inputs and printing the values
2612 on the Serial Interface with the same period.
2614 \subsection{Hello world}
2615 \begin{figure}[H]\begin{center}
2617 \includegraphics[scale=.45]{images/demo_hello_world.png}
2618 \caption{Hello World Simulink demo for RPP.}
2619 \end{center}\end{figure}
2621 \textbf{Description:}
2623 This demo will print \texttt{Hello Simulink} to the Serial Communication Interface (115200-8-N-1) one
2624 character per second. The output speed is driven by the Simulink model step which is set to one
2627 \subsection{Multi-rate SingleTasking demo}
2628 \label{sec:mult-single-thre}
2630 \begin{figure}[H]\begin{center}
2632 \includegraphics[scale=.45]{images/demo_multirate_st.png}
2633 \caption{Multi-rate SingleTasking Simulink demo for RPP.}
2634 \end{center}\end{figure}
2636 \textbf{Description:}
2638 This demo will toggle LEDs on the Hercules Development Kit with
2639 different rate. This is implemented with multiple Simulink tasks, each
2640 running at different rate. In the generated code, these tasks are
2641 called from a singe thread and therefore no task can preempt another
2642 one. See Section \ref{sec-singlet-mode} for more details.
2644 The state of each LED is printed to the Serial Communication Interface
2645 (115200-8-N-1) when toggled.
2648 \begin{tabular}{lll}
2649 \rowcolor[gray]{0.9}
2650 LED & pin & rate [s] \\
2651 1 & NHET1\_25 & 0.3 \\
2652 2 & NHET1\_05 & 0.5 \\
2653 3 & NHET1\_00 & 1.0 \\
2655 \captionof{table}{LEDs connection and rate}
2656 \label{tab:multirate_st_led_desc}
2659 \subsection{Multi-rate MultiTasking demo}
2660 \label{sec:mult-multi-thre}
2662 \begin{figure}[H]\begin{center}
2664 \includegraphics[scale=.45]{images/demo_multirate_mt.png}
2665 \caption{Multi-rate MultiTasking Simulink demo for RPP.}
2666 \label{fig:multitasking-demo}
2667 \end{center}\end{figure}
2669 \textbf{Description:}
2671 This demo toggles LEDs on the Hercules Development Kit with different
2672 rate (different colors in Figure~\ref{fig:multitasking-demo}). This is
2673 implemented with multiple Simulink tasks, each running at different
2674 rate. In the generated code, every subrate task runs in its own
2675 operating system thread. See Section \ref{sec-multit-mode} for more
2678 The state of each LED is also printed to the Serial Communication
2679 Interface (115200-8-N-1) when toggled.
2682 \begin{tabular}{lll}
2683 \rowcolor[gray]{0.9}
2684 LED & pin & rate [s] \\
2685 1 & NHET1\_25 & 0.3 \\
2686 2 & NHET1\_05 & 0.5 \\
2687 3 & NHET1\_00 & 1.0 \\
2689 \captionof{table}{LEDs connection and rate}
2690 \label{tab:multirate_mt_led_desc}
2693 \subsection{Hydraulics controller initialization demo}
2694 \label{sec:board-init-hydctr}
2697 \includegraphics[scale=0.45]{images/demo_board_init_hydctr.png}
2698 \caption{board\_init\_hydctr demo}
2699 \label{fig:board_init_hydctr}
2702 \paragraph{Description}
2704 This demo shows how to use the \emph{Board Init} block to initialize
2705 SPI devices on the Hydraulics Controller board. Additionally, it shows
2706 how to use unused SPI pins on the MCU as general-purpose IOs. If both
2707 Board Init and GIO SPI blocks are used together, care must be taken
2708 about the order in which the blocks are initialized. GIO blocks that
2709 represent SPI pins must be initialized \emph{after} the Board Init
2710 block. This can be ensured by giving the GIO blocks higher priority
2711 than the Board Init block.
2713 \chapter{Command line testing tool}
2714 \label{chap-rpp-test-software}
2715 \section{Introduction}
2716 \label{sec-rpp-test-sw-intro}
2717 The \texttt{rpp-test-suite} is a RPP application developed testing and direct
2718 control of the RPP hardware. The test suite implements a command processor,
2719 which is listening for commands and prints some output related to the commands
2720 on the serial interface. The command processor is modular and each peripheral
2721 has its commands in a separate module.
2723 The command processor is implemented in \texttt{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
2724 modules are implemented in \texttt{$\langle$rpp-test-sw$\rangle$/commands} directory.
2726 The application enables a command processor using the SCI at
2727 \textbf{115200-8-N-1}. When the software starts, the received welcome message
2728 and prompt should look like:
2731 \ifx\tgtId\tgtIdTMSRPP
2732 \noindent\texttt{Rapid Prototyping Platform v00.01-001\\
2733 Test Software version \input{version.tex}\\
2734 CTU in Prague 2014\\
2738 \noindent\texttt{Ti HDK \mcuname, FreeRTOS 7.0.2\\
2739 Test Software version \input{version.tex}\\
2740 CTU in Prague 10/2014\\
2747 Type in command help for a complete list of available command, or help command
2748 for a description of concrete command.
2750 \section{Compilation}
2751 \label{sec-rpp-test-sw-compilation}
2752 Before the Testing tool can be compiled, the RPP Library has to be built and the binary file \texttt{rpp-lib.lib} has to be present in the \texttt{\repo/rpp-lib/} directory. Once this requirement is fulfilled, there are two ways how to compile the Testing tool.
2754 \item Using a Code Composer Studio, which is described in Section \ref{sec-project-installation}. The procedure of downloading the firmware right from the CCS and running it on the hardware is described in Section \ref{sec-running-software-on-hw}.
2755 \item Using a make from a Linux terminal or gmake from a Windows command line. The procedure of how to download and run the binary on the hardware is described in Section \ref{sec-binary-file}.
2757 To build the Testing tool from Linux terminal run:
2758 \begin{lstlisting}[language=bash]
2763 or from Windows command line:
2765 \begin{lstlisting}[language=bash]
2767 "C:\ti\ccsv5\utils\bin\"gmake.exe
2770 On Windows \texttt{gmake.exe} supplied with CCS is used instead of
2774 \section{Commands description}
2775 \label{sec:commands-description}
2777 This section contains the description of the available commands. The
2778 same description is also available in the program itself via the
2779 \texttt{help} command.
2781 % Pandoc generates \tightlist in its output. Since we don't use pandoc
2782 % template, we have put its definition here.
2783 \providecommand{\tightlist}{%
2784 \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
2786 \input{rpp-test-sw-cmds.tex}
2792 \textit{Analog to Digital Converter.} \newline{}
2793 Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
2794 digital number that represents the quantity's amplitude.
2797 \textit{Analog Input.} \newline{}
2798 Mnemonic to refer to or something related to the analog input (ADC) hardware module.
2801 \textit{Analog Output.} \newline{}
2802 Mnemonic to refer to or something related to the analog output (DAC) hardware module.
2804 \item[API] \textit{Application Programming Interface}
2807 \textit{Controller Area Network.} \newline{}
2808 The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
2809 communicate with each other within a vehicle without a host computer.
2810 In this project it is also used as mnemonic to refer to or something related to the CAN
2813 \item[CCS] \textit{Code Composer Studio} \\
2814 Eclipse-based IDE provided by Texas Instruments.
2817 \textit{Code Generation Tools.} \newline{}
2818 Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
2819 assemble, archive, among others. In this project is normally used as synonym for
2820 ``Texas Instruments ARM compiler and linker."
2823 \textit{Digital to Analog Converter.} \newline{}
2824 Hardware circuitry that converts a digital (usually binary) code to an analog signal
2825 (current, voltage, or electric charge).
2828 \textit{Digital Input.} \newline{}
2829 Mnemonic to refer to or something related to the digital input hardware module.
2832 \textit{Engine Control Unit.} \newline{}
2833 A type of electronic control unit that controls a series of actuators on an internal combustion
2834 engine to ensure the optimum running.
2837 \textit{Ethernet.} \newline{}
2838 Mnemonic to refer to or something related to the Ethernet hardware module.
2841 \textit{FlexRay.} \newline{}
2842 FlexRay is an automotive network communications protocol developed to govern on-board automotive
2844 In this project it is also used as mnemonic to refer to or something related to the FlexRay
2848 \textit{General Purpose Input/Output.} \newline{}
2849 Generic pin on a chip whose behavior (including whether it is an input or output pin) can be
2850 controlled (programmed) by the user at run time.
2853 \textit{H-Bridge.} \newline{}
2854 Mnemonic to refer to or something related to the H-Bridge hardware module. A H-Bridge is
2855 an electronic circuit that enables a voltage to be applied across a load in either direction.
2858 \textit{High-Power Output.} \newline{}
2859 Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
2860 output hardware module.
2863 \textit{Integrated Development Environment.} \newline{}
2864 An IDE is a Software application that provides comprehensive facilities to computer programmers
2865 for software development.
2868 \textit{Legacy Code Tool.} \newline{}
2869 Matlab tool that allows to generate source code for S-Functions given the descriptor of a C
2873 \textit{Model-Based Design.} \newline{}
2874 Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
2875 with designing complex control, signal processing and communication systems. \cite{modelbasedwiki2013}
2878 \textit{Matlab Executable.} \newline{}
2879 Type of binary executable that can be called within Matlab. In this document the common term
2880 used is `C MEX S-Function", which means Matlab executable written in C that implements a system
2884 \textit{Pulse-width modulation.} \newline{}
2885 Technique for getting analog results with digital means. Digital control is used to create a
2886 square wave, a signal switched between on and off. This on-off pattern can simulate voltages
2887 in between full on and off by changing the portion of the time the signal spends on versus
2888 the time that the signal spends off. The duration of ``on time" is called the pulse width or
2889 \textit{duty cycle}.
2891 \item[RPP] \textit{Rapid Prototyping Platform.} \newline{} Name of the
2892 developed platform, that includes both hardware and software.
2895 \textit{Serial Communication Interface.} \newline{}
2896 Serial Interface for communication through hardware's UART using communication standard RS-232.
2897 In this project it is also used as mnemonic to refer to or something related to the Serial
2898 Communication Interface hardware module.
2901 \textit{SD-Card.} \newline{}
2902 Mnemonic to refer to or something related to the SD-Card hardware module.
2905 \textit{SD-RAM.} \newline{}
2906 Mnemonic to refer to or something related to the SD-RAM hardware module for logging.
2909 \textit{Target Language Compiler.} \newline{}
2910 Technology and language used to generate code in Matlab/Simulink.
2913 \textit{Universal Asynchronous Receiver/Transmitter.} \newline{}
2914 Hardware circuitry that translates data between parallel and serial forms.
2921 % LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests
2922 % LocalWords: MCU UART microcontrollers DAC CCS simulink SPI GPIO
2923 % LocalWords: IOs HDK TMDSRM