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''.
212 \fancypagestyle{plain}{%
213 \fancyhf{} % clear all header and footer fields
214 \renewcommand{\footrulewidth}{0.4pt}
215 \renewcommand{\headrulewidth}{0pt}
216 \fancyfoot[L]{Version \input{version.tex}}
218 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
220 \renewcommand{\headrulewidth}{0.4pt}
221 \renewcommand{\footrulewidth}{0.4pt}
223 \fancyhead[R]{\includegraphics[width=1cm]{images/cvut.pdf}}
225 \fancyhead[L]{\nouppercase \leftmark}
226 \fancyfoot[L]{Version \input{version.tex}}
228 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
231 %\addtolength{\parskip}{\baselineskip} % Paragraph spacing
233 \chapter{Introduction}
234 \label{chap-introduction}
236 This text documents software part of Rapid Prototyping Platform (RPP)
237 project for Texas Instruments \tgname{} safety microcontroller
238 developed by Czech Technical University in Prague (CTU). The software
239 consists of code generation target for Simulink Embedded Coder, a
240 low-level run-time C library and a tool for interactive testing of
241 hardware and software functionality.
243 Originally, the RPP project was created for a custom TMS570-based
244 board. Subsequently, it was ported to other board such as RM48 HDK and
245 TMS570 HDK development kits under a contract from Eaton Corporation.
247 The document contains step-by-step instructions for installation of
248 development tools, information about Simulink Coder configuration,
249 describes how to create new models as well as how to download the
250 resulting firmware to the hardware. It can also be used as a reference
251 for the testing tool, Matlab Simulink blocks and RPP Matlab Simulink
252 Code generator. Additionally, an overall description of the used
253 hardware platform and the architecture of included software is
257 \label{sec-background}
259 In this document, the term \emph{Rapid Prototyping Platform} denotes a
260 hardware board and accompanying software. The hardware board is
261 \tgtBoardName{} based on ARM Cortex R4 safety microcontroller
262 \mcuname{}. This MCU contains several protective mechanisms (two cores
263 in lockstep, error correction mechanisms for SRAM and Flash memory,
264 voltage monitoring, etc.) to fulfill the requirements for safety
265 critical applications. See~\cite{\tgrefman} for details.
267 In order to develop non-trivial applications for the RPP, an operating
268 system is necessary. The RPP is based on FreeRTOS -- a simple
269 opensource real-time operating system kernel. The FreeRTOS provides an
270 API for creating and managing and scheduling multiple tasks, memory
271 manager, semaphores, queues, mutexes, timers and a few of other
272 features which can be used in the applications.
273 See~\cite{usingthefreertos2009} for more details.
275 Even with the operating system it is quite hard and non-intuitive to
276 manipulate the hardware directly. That is the point when abstraction
277 comes into the play. The RPP software is made of several layers
278 implementing, from the bottom to the top, low-level device drivers,
279 hardware abstraction for common functionality on different hardware
280 and an API which is easy to use in applications. The operating system
281 and the basic software layers, can be compiled as a library and easily
282 used in any project. More details about the library can be found in
283 Chapter~\ref{chap-c-support-library} and in~\cite{michalhorn2013}.
285 Because human beings make mistakes and in safety critical applications
286 any mistake can cause damage, loos of money or in the worst case even
287 death of other people, the area for making mistakes has to be as small
288 as possible. An approach called Model-based development
289 \cite{modelbasedwiki2013} has been introduced to reduce the
290 probability of making mistakes. In model-based development, the
291 applications are designed at higher level from models and the
292 functionality of the models can be simulated in a computer before the
293 final application/hardware is finished. This allows to discover
294 potential errors earlier in the development process.
296 One commonly used tool-chain for model-based development is
297 Matlab/Simulink. In Simulink the application is developed as a model
298 made of interconnected blocks. Every block implements some
299 functionality. For example one block reads a value from an
300 analog-to-digital converter and provides the value as an input to
301 another block. This block can implement some clever algorithm and its
302 output is passed to another block, which sends the computed value as a
303 message over CAN bus to some other MCU. Such a model can be simulated
304 and tested even before the real hardware is available by replacing the
305 input and output blocks with simulated ones. Once the hardware is
306 ready, C code is automatically generated from the model by a Simulink
307 Coder. The code is then compiled by the MCU compatible compiler and
308 downloaded to the MCU Flash memory on the device. Because every block
309 and code generated from the block has to pass a series of tests during
310 their development, the area for making mistakes during the application
311 development has been significantly reduced and developers can focus on
312 the application instead of the hardware and control software
313 implementation. More information about code generation can be found in
314 Chapter \ref{chap-simulink-coder-target}. For information about Matlab
315 Simulink, Embedded Coder and Simulink Coder, refer to
316 \cite{embeddedcoderreference2013, ebmeddedcoderusersguide2013,
317 simulinkcoderreference2013, targetlanguagecompiler2013,
318 simulinkcoderusersguide2013, simulinkdevelopingsfunctions2013}.
320 \section{Hardware description}
321 \label{sec-hardware-description}
325 \section{Software architecture}
326 \label{sec-software-architecture}
328 The core of the RPP software is the so called RPP Library. This
329 library is conceptualy structured into 5 layers, depicted in
330 Figure~\ref{fig-layers}. The architecture design was driven by the
331 following guidelines:
334 \item Top-down dependency only. No lower layer depends on anything from
336 % \item 1-1 layer dependency only. The top layer depends
337 % exclusively on the bottom layer, not on any lower level layer (except for a
338 % couple of exceptions).
339 \item Each layer should provide a unified layer interface
340 (\texttt{rpp.h}, \texttt{drv.h}, \texttt{sys.h} and
341 \texttt{os.h}), so that higher layers depend on the lower layer's interface
342 and not on individual elements from that layer.
348 \includegraphics[width=250px]{images/layers.pdf}
349 \caption{The RPP library layers.}
354 As a consequence of this division the source code files and interface files are
355 placed in private directories like \texttt{drv/din.h}. With this organization
356 user applications only needs to include the top layer interface files (for
357 example \texttt{rpp/rpp.h}) to be able to use the selected library API.
359 The rest of the section provides basic description of each layer.
361 \subsection{Operating System layer}
362 \label{sec-operating-system-layer}
363 This is an interchangeable operating system (OS) layer containing the
364 FreeRTOS source files. The system can be easily replaced by another
365 version. For example it is possible to compile the RPP library for
366 Linux (using POSIX version of the FreeRTOS), which can be desirable
367 for some testing. The source files can be found in the
368 \texttt{$\langle$rpp\_lib$\rangle$/os} folder.
370 The following FreeRTOS versions are distributed:
372 \item[6.0.4\_posix] POSIX version, usable for compilation of the
373 library for Linux system.
374 \item[8.2.2] Currently used FreeRTOS version. This is the version
375 downloaded from FreeRTOS.org with changes in directory structure.
376 Namely, include files have added the \emph{os/} prefix and platform
377 dependent code (portable) for \tgname{} is copied to the same
378 directory as platform independent code.
381 \subsection{System Layer}
382 \label{sec-system-layer}
383 This layer contains system files with data types definitions, clock definitions,
384 interrupts mapping, MCU start-up sequence, MCU selftests, and other low level
385 code for controlling some of the MCU peripherals. The source files can be found
386 in \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/sys}, the header files can
387 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/sys}
390 Large part of this layer was generated by the HalCoGen tool (see
391 Section~\ref{sec-halcogen}). Some files were then modified by hand.
393 \subsection{Drivers layer}
394 \label{sec-drivers-layer}
395 The Drivers layer contains code for controlling the RPP peripherals.
396 Typically, it contains code implementing IRQ handling, software
397 queues, management threads, etc. The layer benefits from the lower
398 layer thus it is not too low level, but still there are some
399 peripherals like ADC, which need some special procedure for
400 initialization and running, that would not be very intuitive for the
403 The source files can be found in
404 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
405 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/drv} folder.
407 \subsection{RPP Layer}
408 \label{sec-rpp-layer}
409 The RPP Layer is the highest layer of the library. It provides an easy
410 to use set of functions for every peripheral and requires only basic
411 knowledge about them. For example, to use the ADC, the user can just
412 call \texttt{rpp\_adc\_init()} function and it calls a sequence of
413 Driver layer functions to initialize the hardware and software.
415 The source files can be found in
416 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/rpp} and the header files can
417 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/rpp}.
419 \section{Document structure}
420 \label{sec-document-structure}
421 The structure of this document is as follows:
422 Chapter~\ref{chap-getting-started} gets you started using the RPP
423 software. Chapter~\ref{chap-c-support-library} describes the RPP
424 library. Chapter~\ref{chap-simulink-coder-target} covers the Simulink
425 code generation target and finally
426 Chapter~\ref{chap-rpp-test-software} documents a tool for interactive
427 testing of the RPP functionality.
429 \chapter{Getting started}
430 \label{chap-getting-started}
432 \section{Software requirements}
433 \label{sec-software-requirements}
434 The RPP software stack can be used on Windows and Linux platforms. The
435 following subsections mention the recommended versions of the required
436 software tools/packages.
438 \subsection{Linux environment}
439 \label{sec-linux-environment}
441 \item Debian based 64b Linux distribution (Debian 7.0 or Ubuntu 14.4 for
443 \item Kernel version 3.11.0-12.
444 \item GCC version 4.8.1
445 \item GtkTerm 0.99.7-rc1
446 \item TI Code Composer Studio 5.5.0.00077
447 \item Matlab 2013b 64b with Embedded Coder
448 \item HalCoGen 4.00 (optional)
449 \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
450 \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
451 \item Git 1.7.10.4 (optional)
454 \subsection{Windows environment}
455 \label{sec-windows-environment}
457 \item Windows 7 Enterprise 64b Service Pack 1.
458 \item Microsoft Windows SDK v7.1
459 \item Bray Terminal v1.9b
460 \item TI Code Composer Studio 5.5.0.00077
461 \item Matlab 2013b 64b with Embedded Coder
462 \item HalCoGen 4.00 (optional)
463 \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
464 \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
465 \item Git 1.9.4.msysgit.2 (optional)
468 \section{Software tools}
469 \label{sec-software-and-tools}
471 This section covers tool which are needed or recommended for work with
474 \subsection{TI Code Composer Studio}
476 Code Composer Studio (CCS) is the official Integrated Development Environment
477 (IDE) for developing applications for Texas Instruments embedded processors. CCS
478 is multiplatform software based on
479 Eclipse open source IDE.
481 CCS includes Texas Instruments Code Generation Tools (CGT)
482 \cite{armoptimizingccppcompiler2012, armassemblylanguagetools2012}
483 (compiler, linker, etc). Simulink code generation target requires the
484 CGT to be available in the system, and thus, even if no library
485 development will be done or the IDE is not going to be used CCS is
488 You can find documentation for CGT compiler in \cite{armoptimizingccppcompiler2012} and
489 for CGT archiver in \cite{armassemblylanguagetools2012}.
491 \subsubsection{Installation on Linux}
492 \label{sec-installation-on-linux}
493 Download CCS for Linux from:\\
494 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
496 Once downloaded, add executable permission to the installation file
497 and launch the installation by executing it. Installation must be done
498 by the root user in order to install a driver set.
500 \lstset{language=bash}
502 chmod +x ccs_setup_5.5.0.00077.bin
503 sudo ./ccs_setup_5.5.0.00077.bin
506 After installation the application can be executed with:
508 \lstset{language=bash}
510 cd <ccs>/ccsv5/eclipse/
514 The first launch on 64bits systems might fail. This can happen because CCS5 is
515 a 32 bit application and thus requires 32 bit libraries. They can be
518 \lstset{language=bash}
520 sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
523 If the application crashes with a segmentation fault edit file:
525 \lstset{language=bash}
527 nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
530 And change key \texttt{org.eclipse.ui/showIntro} to \texttt{false}.
532 \subsubsection{Installation on Windows}
533 \label{sec-installation-on-windows}
534 Installation for Windows is more straightforward than the installation
535 procedure for Linux. Download CCS for Windows from:\\
536 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
538 Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.
540 \subsubsection{First launch}
541 \label{sec-first-launch}
542 If no other licence is available, choose ``FREE License -- for use
543 with XDS100 JTAG Emulators'' from the licensing options. Code download
544 for the board uses the XDS100 hardware.
546 \subsection{Matlab/Simulink}
547 \label{sec-matlab-simulink}
548 Matlab Simulink is a set of tools, runtime environment and development
549 environment for Model--Based \cite{modelbasedwiki2013} applications development,
550 simulations and code generation for target platforms. Supported Matlab Simulink
551 version is R2013b for 64 bits Linux and Windows. A licence for an Embedded Coder is
552 necessary to be able to generate code from Simulink models, containing RPP blocks.
554 \subsection{HalCoGen}
556 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.
558 The tool is available for Windows at
560 \url{http://www.ti.com/tool/halcogen}
563 The HalCoGen has been used in early development stage of the RPP
564 project to generate the base code for some of the peripheral. The
565 trend is to not to use the HalCoGen any more, because the generated
566 code is not reliable enough for safety critical applications. Anyway it is
567 sometimes helpful to use it as a reference.
569 The HalCoGen is distributed for Windows only, but can be run on Linux
570 under Wine (tested with Wine version 1.6.2).
572 \subsection{GtkTerm and Bray Terminal}
573 \label{sec-gtkterm-bray-terminal}
574 Most of the interaction with the board is done through a RS-232 serial
575 connection. The terminal software used for communication is called GtkTerm for
576 Linux and Bray terminal for Windows.
578 To install GtkTerm execute:
580 \lstset{language=bash}
582 sudo apt-get install gtkterm
585 The Bray Terminal does not require any installation and the executable file is
587 \url{https://sites.google.com/site/terminalbpp/}
589 \subsection{C Compiler}
590 \label{sec-c-compiler}
591 A C language compiler has to be available on the development system to be able to
592 compile Matlab Simulink blocks S-functions.
594 For Linux a GCC 4.8.1 compiler is recommended and can be installed with a
597 \lstset{language=bash}
599 sudo apt-get install gcc
602 For Windows, the C/C++ compiler is a part of Windows SDK, which is available from\\
603 \url{http://www.microsoft.com/en-us/download/details.aspx?id=8279}
605 \section{Project installation}
606 \label{sec-project-installation}
607 The RPP software is distributed in three packages and a standalone pdf
608 file containing this documentation. Every package is named like
609 \emph{$\langle$package\_name$\rangle$-version.zip}. The three packages
613 \item[rpp-simulink] Contains the source code of Matlab Simulink
614 blocks, demo models and scripts for downloading the generated
615 firmware to the target board from Matlab/Simulink. Details can be
616 found in Chapter \ref{chap-simulink-coder-target}.
618 The package also contains the binary of the RPP Library and all its
619 headers and other files necessary for building and downloading
621 \item[rpp-test-sw] Contains an application for interactive testing and
622 control of the \tgtBoardName{} board over the serial interface. Details can be
623 found in Chapter~\ref{chap-rpp-test-software}.
625 The package also contains the binary of the RPP Library and all
626 headers and other files necessary for building and downloading the
628 \item[rpp-lib] Contains the source code of the RPP library, described
629 in Chapter \ref{chap-c-support-library}. If you want to make any
630 changes in the drivers or the RPP API, this library has to be
631 compiled and linked with applications in the other two packages.
632 Library compilation is described in Section \ref{sec-compilation}.
635 The following sections describe how to start working with individual
638 \ifthenelse{\equal{\tgtId}{\tgtIdTMSHDK} \OR
639 \equal{\tgtId}{\tgtIdTMSRPP}}{
640 \subsection{Getting sources from git repository}
642 To get the source code from Git repository, execute the following command:
644 \texttt{git clone --recursive git@rtime.felk.cvut.cz:jenkicar/rpp-simulink}
646 \noindent If you have got release packages (.zip archives), follow the
647 instructions in the next sections. }
650 \subsection{rpp-simulink}
651 \label{sec-rpp-simulink-installation}
652 This section describes how to install the rpp-simulink project, which
653 is needed to try the demo models or to build your own models that use
657 \item Unzip the \texttt{rpp-simulink-version.zip} file.
658 \item Follow the procedure from Section
659 \ref{sec-configuration-simulink-for-rpp} for configuring Matlab
660 Simulink for the RPP project.
661 \item Follow the procedure from Section \ref{sec-crating-new-model}
662 for instructions about creating your own model which will use the
663 RPP Simulink blocks or follow the instructions in
664 Section~\ref{sec-running-model-on-hw} for downloading the firmware to the RPP hardware.
667 \subsection{rpp-test-sw}
668 \label{sec-test-sw-installation}
669 This section describes how to install and run the application that
670 allows you to interactively control the RPP hardware. This can be
671 useful, for example, to test your modifications of the RPP library.
674 \item Unzip the \texttt{rpp-test-sw-version.zip} file.
675 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
676 \item Import the \texttt{rpp-test-sw} project as described in
677 Section \ref{sec-openning-of-existing-project}.
678 \item Right click on the \texttt{rpp-test-sw} project in the
679 \textsc{Project Explorer} and select \textsc{Build Project}.
680 \item Follow the instructions in
681 Section~\ref{sec-running-software-on-hw} to download, debug and
682 run the software on the target hardware.
686 \label{sec-rpp-lib-installation}
688 This section describes how to open the rpp-lib project in Code
689 Composer Studio and how to use the resulting static library in an
690 application. This is only necessary if you need to modify the library
694 \item Unzip the \texttt{rpp-lib-version.zip} file.
695 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
696 \item Import the rpp-lib project from directory
697 \texttt{rpp-lib-XXX/build/\tgtId} as described in
698 Section~\ref{sec-openning-of-existing-project}.
699 \item Compile the static library by selecting \textsc{Project
700 $\rightarrow$ Build Project} (see Section
701 \ref{sec-compilation} for more information). The compiled
702 library \texttt{rpp-lib.lib} and file
703 \texttt{Makefile.config} will appear in the
704 \texttt{rpp-lib-XXX} directory.
705 \item Either copy the compiled library and the content of the
706 \texttt{rpp/include} directory to the application, where you
707 want to use it or use the library in place, as described in
708 Section~\ref{sec:creating-new-project}.
710 \item In the rpp-simulink application the library is located in
711 the \texttt{rpp/lib} folder.
712 \item In the rpp-test-sw application the library is located in
713 the \texttt{rpp-lib} folder.
717 \section{Code Composer Studio usage}
718 \label{sec-code-composerpstudio-usage}
720 \subsection{Opening an existing project}
721 \label{sec-openning-of-existing-project}
722 The procedure for opening a project is similar to opening a project in
723 the standard Eclipse IDE.
726 \item Launch Code Composer Studio
727 \item Select \textsc{File$\rightarrow$Import}
728 \item In the dialog window select \textsc{Code Composer
729 Studio$\rightarrow$Existing CCS Eclipse project} as an import
730 source (see Figure \ref{fig-import-project}).
731 \item In the next dialog window click on \textsc{Browse} button
732 and find the root directory of the project.
733 \item Select the requested project in the \textsc{Discovered
734 project} section so that the result looks like in Figure
735 \ref{fig-select-project}.
736 \item Click the \textsc{Finish} button.
739 \begin{figure}[H]\begin{center}
740 \includegraphics[width=350px]{images/import_project.png}
741 \caption{Import project dialog}
742 \label{fig-import-project}
743 \end{center}\end{figure}
745 \begin{figure}[H]\begin{center}
746 \includegraphics[width=350px]{images/select_project.png}
747 \caption{Select project dialog}
748 \label{fig-select-project}
749 \end{center}\end{figure}
752 \subsection{Creating new project}
753 \label{sec:creating-new-project}
754 Follow these steps to create an application for \tgname{} MCU compiled with
758 \item Create a new empty CCS project. Select \mcuname{} device, XDS100v2
759 connection and set Linker command file to
760 \texttt{rpp-lib/build/\tgtId/\ldscriptname}.
762 \noindent\includegraphics[scale=0.45]{images/base_1.png}
764 \item In \textsc{Project Explorer}, create normal folders
765 named \texttt{include} and \texttt{src}.
767 \item If you use Git version control system, add \texttt{.gitignore}
768 file with the following content to the root of that project:
777 \item In project \textsc{Properties}, add new variable of type
778 \texttt{Directory} named \texttt{RPP\_LIB\_ROOT} and set it to the
782 \noindent\includegraphics[scale=.45]{images/base_2.png}
784 \item Configure the compiler \#include search path to contain
785 project's \texttt{include} directory, \penalty-100
786 \texttt{\$\{RPP\_LIB\_ROOT\}/os/8.2.2/include} and
787 \texttt{\$\{RPP\_LIB\_ROOT\}/rpp/include}, in that order.
789 \includegraphics[scale=.43]{images/base_5.png}
792 \item Add \texttt{\$\{RPP\_LIB\_ROOT\}/rpp-lib.lib} to the list of
793 linked libraries before the runtime support library
794 (\texttt{\tgtRtlib}).
796 \noindent\includegraphics[scale=.45]{images/base_3.png}
798 \item Configure the compiler to allow GCC extensions.
800 \noindent\includegraphics[scale=.45]{images/base_6.png}
803 \item Create \texttt{main.c} file with the following content:
804 \begin{lstlisting}[language=C]
810 rpp_sci_printf("Hello world\n");
811 vTaskStartScheduler();
812 return 0; /* not reached */
815 void vApplicationMallocFailedHook()
817 void vApplicationStackOverflowHook()
821 \item Compile the application by e.g. \textsc{Project $\rightarrow$
823 \item Select \textsc{Run} $\rightarrow$ \textsc{Debug}. The
824 application will be downloaded to the processor and run. A
825 breakpoint is automatically placed at \texttt{main()} entry. To
826 continue executing the application select \textsc{Run} $\rightarrow$
828 \item If your application fails to run with a \texttt{\_dabort} interrupt, check
829 that the linker script selected in step 1 is not excluded from the build.
830 You can do this by right clicking the \texttt{\ldscriptname} file
831 in the \textsc{Project Explorer} and unchecking the \textsc{Exclude from build}
832 item. The Code Composer Studio sometimes automaticaly excludes this file from
833 the build process when creating a new project.
835 % \item If not already created for another project, create new target
836 % configuration. Select \textsc{Windows $\rightarrow$ Show View
837 % $\rightarrow$ Target Configurations}. In the shown window, click
838 % on \textsc{New Target Configuration} icon and configure XDS100v2
839 % connection and \mcuname{} device as shown below. Click \textsc{Save},
840 % connect your board and click \textsc{Test Connection}.
843 % \includegraphics[width=\linewidth]{images/target_conf.png}
846 \item Optionally, you can change debugger configuration by selecting
847 \textsc{Run $\rightarrow$ Debug Configurations}. In the
848 \textsc{Target} tab, you can configure not to break at \texttt{main}
849 or not to erase the whole flash, but necessary sectors only (see the
852 \includegraphics[width=\linewidth]{images/debug_conf_flash.png}
857 %% Comment this out for Eaton
858 % \subsubsection{Steps to configure new POSIX application:}
859 % Such an application can be used to test certain FreeRTOS features on
860 % Linux and can be compiled with a native GCC compiler.
862 % \begin{compactenum}
863 % \item Create a new managed C project that uses Linux GCC toolchain.
864 % \item Create a source folder \texttt{src}. Link all files from original
865 % CCS application to this folder.
866 % \item Create a normal folder \texttt{include}. Create a folder
867 % \texttt{rpp} inside of it.
868 % \item Add common \texttt{.gitignore} to the root of that project:
875 % \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
876 % repository branch root.\newline{}
877 % \noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
878 % \item Configure compiler to include local includes, CCS application
879 % includes, OS includes for POSIX and RPP includes, in that order.\newline{}
880 % \noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
882 % \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
883 % \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
884 % \noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
887 \subsubsection{Content of the application}
890 \item Include RPP library header file.
891 \lstset{language=c++}
896 If you want to reduce the size of the final application, you can
897 include only the headers of the needed modules. In that case, you
898 need to include two additional headers: \texttt{base.h} and, in case
899 when SCI is used for printing, \texttt{rpp/sci.h}.
901 #include "rpp/hbr.h" /* We want to use H-bridge */
902 #include <base.h> /* This is the necessary base header file of the rpp library. */
903 #include "rpp/sci.h" /* This is needed, because we use rpp_sci_printf in following examples. */
907 \item Create one or as many FreeRTOS task function definitions as
908 required. Those tasks can use functions from the RPP library. Beware
909 that currently not all RPP functions are
910 reentrant\footnote{Determining which functions are not reentrant and
911 marking them as such (or making them reentrant) is planned as
912 future work.}. \lstset{language=c++}
914 void my_task(void* p)
916 static const portTickType freq_ticks = 1000 / portTICK_RATE_MS;
917 portTickType last_wake_time = xTaskGetTickCount();
919 /* Wait until next step */
920 vTaskDelayUntil(&last_wake_time, freq_ticks);
921 rpp_sci_printf((const char*)"Hello RPP.\r\n");
926 \item Create the main function that will:
928 \item Initialize the RPP board. If you have included only selected
929 modules in step 1, initialize only those modules by calling their init
931 example \texttt{rpp\_hbr\_init\(\)}.
932 \item Spawn the tasks the application requires. Refer to FreeRTOS API
934 \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details
936 \item Handle error when the FreeRTOS scheduler cannot be started.
938 \lstset{language=c++}
942 /* In case whole library is included: */
943 /* Initialize RPP board */
945 /* In case only selected modules are included: */
948 /* Initialize sci for printf */
950 /* Enable interrups */
954 if (xTaskCreate(my_task, (const signed char*)"my_task",
955 512, NULL, 0, NULL) != pdPASS) {
957 rpp_sci_printf((const char*)
958 "ERROR: Cannot spawn control task.\r\n"
964 /* Start the FreeRTOS Scheduler */
965 vTaskStartScheduler();
967 /* Catch scheduler start error */
969 rpp_sci_printf((const char*)
970 "ERROR: Problem allocating memory for idle task.\r\n"
978 \item Create hook functions for FreeRTOS:
980 \item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation
982 \item \texttt{vApplicationStackOverflowHook()} allows to catch stack
985 \lstset{language=c++}
987 #if configUSE_MALLOC_FAILED_HOOK == 1
989 * FreeRTOS malloc() failed hook.
991 void vApplicationMallocFailedHook(void) {
993 rpp_sci_printf((const char*)
994 "ERROR: manual memory allocation failed.\r\n"
1001 #if configCHECK_FOR_STACK_OVERFLOW > 0
1003 * FreeRTOS stack overflow hook.
1005 void vApplicationStackOverflowHook(xTaskHandle xTask,
1006 signed portCHAR *pcTaskName) {
1008 rpp_sci_printf((const char*)
1009 "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName
1021 \subsection{Downloading and running the software}
1022 \label{sec-running-software-on-hw}
1023 \subsubsection{Code Composer Studio Project}
1024 \label{sec-ccs-run-project}
1025 When an application is distributed as a CCS project, you have to open the
1026 project in the CCS as described in the Section
1027 \ref{sec-openning-of-existing-project}. Once the project is opened and built, it
1028 can be easily downloaded to the target hardware with the following procedure:
1031 \ifx\tgtId\tgtIdTMSRPP
1032 \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG port.
1033 \item Connect a USB cable to the XDS100v2 USB emulator and the development computer.
1035 \item Connect the USB cable to the \tgtBoardName{} board.
1037 \item Plug in the power supply.
1038 \item In the Code Composer Studio click on the
1039 \textsc{Run$\rightarrow$Debug}. The project will be optionally built and
1040 the download process will start. The Code Composer Studio will switch into the debug
1041 perspective, when the download is finished.
1042 \item Run the program by clicking on the \textsc{Run} button, with the
1046 \subsubsection{Binary File}
1047 \label{sec-binary-file}
1048 If the application is distributed as a binary file, without source code and CCS
1049 project files, you can download and run just the binary file by creating a new
1050 empty CCS project and configuring the debug session according to the following
1054 \item In Code Composer Studio click on
1055 \textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
1056 \item In the dialog window, type in a project name, for example
1057 myBinaryLoad, Select \textsc{Device
1058 variant} (ARM, Cortex R, \mcuname, Texas Instruments XDS100v2 USB Emulator)
1059 and select project template to \textsc{Empty Project}. The filled dialog should
1060 look like in Figure~\ref{fig-new-empty-project}
1061 \item Click the \textsc{Finish} button and a new empty project will
1063 \item In the \textsc{Project Explorer} right-click on the project and
1064 select \textsc{Debug as$\rightarrow$Debug configurations}.
1065 \item Click \textsc{New launch configuration} button
1066 \item Rename the New\_configuration to, for example, myConfiguration.
1067 \item Select configuration target file by clicking the \textsc{File
1068 System} button, finding and selecting the \texttt{rpp-lib-XXX/build/\tgtId/\tgconfigfilename} file. The result
1069 should look like in Figure~\ref{fig-debug-conf-main-diag}.
1070 \item In the \textsc{program} pane select the binary file you want to
1071 download to the board. Click on the \textsc{File System} button,
1072 find and select the binary file. Try, for example
1073 \texttt{rpp-test-sw.out}. The result should look like in
1074 Figure~\ref{fig-debug-conf-program-diag}.
1075 \item You may also tune the target configuration as described in
1076 Section \ref{sec-target-configuration}.
1077 \item Finish the configuration by clicking the \textsc{Apply} button
1078 and download the code by clicking the \textsc{Debug} button. You can
1079 later invoke the download also from the
1080 \textsc{Run$\rightarrow$Debug} CCS menu. It is not necessary to
1081 create more Debug configurations and CCS empty projects as you can
1082 easily change the binary file in the Debug configuration to load a
1083 different binary file.
1086 \begin{figure}[H]\begin{center}
1087 \includegraphics[scale=.45]{images/new_empty_project.png}
1088 \caption{New empty project dialog}
1089 \label{fig-new-empty-project}
1090 \end{center}\end{figure}
1092 \begin{figure}[H]\begin{center}
1093 \includegraphics[scale=.45]{images/debug_configuration_main.png}
1094 \caption{Debug Configuration Main dialog}
1095 \label{fig-debug-conf-main-diag}
1096 \end{center}\end{figure}
1098 \subsection{Target configuration}
1099 \label{sec-target-configuration}
1100 Default target configuration erases the whole Flash memory, before
1101 downloading the code. This takes long time and in most cases it is
1102 not necessary. You may disable this feature by the following procedure:
1104 \item Right click on the project name in the \textsc{Project Browser}
1105 \item Select \textsc{Debug as$\rightarrow$Debug Configurations}
1106 \item In the dialog window select \textsc{Target} pane.
1107 \item In the \textsc{Flash Settings}, \textsc{Erase Options} select
1108 \textsc{Necessary sectors only}.
1109 \item Save the configuration by clicking the \textsc{Apply} button
1110 and close the dialog.
1113 \begin{figure}[H]\begin{center}
1114 \includegraphics[scale=.45]{images/debug_configuration_program.png}
1115 \caption{Configuration Program dialog}
1116 \label{fig-debug-conf-program-diag}
1117 \end{center}\end{figure}
1119 \section{Matlab Simulink usage}
1120 \label{sec-matlab-simulink-usage}
1121 This section describes the basics of working with the RPP code
1122 generation target for Simulink. For a more detailed description of the
1123 code generation target refer to
1124 Chapter~\ref{chap-simulink-coder-target}.
1126 \subsection{Configuring Simulink for RPP}
1127 \label{sec-configuration-simulink-for-rpp}
1128 Before any work or experiments with the RPP blocks and models, the RPP
1129 target has to be configured to be able to find the ARM cross-compiler,
1130 native C compiler and some other necessary files. Also the S-Functions
1131 of the blocks have to be compiled by the mex tool.
1133 \item Download and install Code Composer Studio CCS (see
1134 Section~\ref{sec-ti-ccs}).
1135 \item Install a C compiler. On Windows follow Section~\ref{sec-c-compiler}.
1136 \item On Windows you have to tell the \texttt{mex} which C compiler to
1137 use. In the Matlab command window run the \texttt{mex -setup}
1138 command and select the native C compiler.
1140 \begin{lstlisting}[basicstyle=\texttt\footnotesize]
1143 Welcome to mex -setup. This utility will help you set up
1144 a default compiler. For a list of supported compilers, see
1145 http://www.mathworks.com/support/compilers/R2013b/win64.html
1147 Please choose your compiler for building MEX-files:
1149 Would you like mex to locate installed compilers [y]/n? y
1152 [1] Microsoft Software Development Kit (SDK) 7.1 in c:\Program Files (x86)\Microsoft Visual Studio 10.0
1158 Please verify your choices:
1160 Compiler: Microsoft Software Development Kit (SDK) 7.1
1161 Location: c:\Program Files (x86)\Microsoft Visual Studio 10.0
1163 Are these correct [y]/n? y
1165 ***************************************************************************
1166 Warning: MEX-files generated using Microsoft Windows Software Development
1167 Kit (SDK) require that Microsoft Visual Studio 2010 run-time
1168 libraries be available on the computer they are run on.
1169 If you plan to redistribute your MEX-files to other MATLAB
1170 users, be sure that they have the run-time libraries.
1171 ***************************************************************************
1174 Trying to update options file: C:\Users\Michal\AppData\Roaming\MathWorks\MATLAB\R2013b\mexopts.bat
1175 From template: C:\PROGRA~1\MATLAB\R2013b\bin\win64\mexopts\mssdk71opts.bat
1179 **************************************************************************
1180 Warning: The MATLAB C and Fortran API has changed to support MATLAB
1181 variables with more than 2^32-1 elements. In the near future
1182 you will be required to update your code to utilize the new
1183 API. You can find more information about this at:
1184 http://www.mathworks.com/help/matlab/matlab_external/upgrading-mex-files-to-use-64-bit-api.html
1185 Building with the -largeArrayDims option enables the new API.
1186 **************************************************************************
1189 \item Configure the RPP code generation target:
1191 Open Matlab and in the command window run:
1193 \lstset{language=Matlab}
1195 cd <rpp-simulink>/rpp/rpp/
1199 This will launch the RPP setup script. This script will ask the user to provide
1200 the path to the CCS compiler root directory (the directory where \texttt{armcl}
1201 binary is located), normally:
1204 <ccs>/tools/compiler/arm_5.X.X/
1207 Then Matlab path will be updated and block S-Functions will be built.
1209 \item Create new model or load a demo:
1211 Demos are located in \texttt{\repo/rpp/demos}. Creation of new
1212 models is described in Section~\ref{sec-crating-new-model} below.
1216 \subsection{Working with demo models}
1217 \label{sec-openning-demo-models}
1218 The demo models are available from the directory
1219 \texttt{\repo/rpp/demos}. To access the demo models for reference or
1220 for downloading to the RPP board open them in Matlab. Use either the
1221 GUI or the following commands:
1223 \begin{lstlisting}[language=Matlab]
1224 cd <rpp-simulink>/rpp/demos
1225 open cantransmit.slx
1228 The same procedure can be used to open any other models. To build the
1229 demo select \textsc{Code$\rightarrow$C/C++ Code $\rightarrow$Build
1230 Model}. This will generate the C code and build the binary firmware
1231 for the RPP board. To run the model on the target hardware see
1232 Section~\ref{sec-running-model-on-hw}.
1234 \subsection{Creating new model}
1235 \label{sec-crating-new-model}
1237 \item Create a model by clicking \textsc{New$\rightarrow$Simulink Model}.
1238 \item Open the configuration dialog by clicking \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
1239 \item The new Simulink model needs to be configured in the following way:
1241 \item Solver (Figure \ref{fig-solver}):
1243 \item Solver type: \emph{Fixed-step}
1244 \item Solver: \emph{discrete}
1245 \item Fixed-step size: \emph{Sampling period in seconds. Minimum
1247 \item Tasking mode -- choose between the following:
1249 \item \textit{Auto} selects SingleTasking modes for
1250 single-rate model or MultiTasking mode for multi-rate
1251 models. See Section \ref{sec-singlet-multit-modes}
1252 \item \textit{SingleTasking} selects SingleTasking mode. See
1253 Section \ref{sec-singlet-mode} for details.
1254 \item \textit{MultiTasking} select MultiTasking mode. In
1255 this mode \textit{Higher priority value indicates higher
1256 task priority} should be checked. See Section
1257 \ref{sec-multit-mode} for details.
1262 \includegraphics[scale=.45]{images/simulink_solver.png}
1263 \caption{Solver settings}
1267 % \item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
1268 % \begin{compactitem}
1269 % \item Disable warning ``Source block specifies -1 sampling
1270 % time''. It's ok for the source blocks to run once per tick.
1273 % \includegraphics[scale=.45]{images/simulink_diagnostics.png}
1274 % \caption{Sample Time settings}
1275 % \label{fig-sample-time-settings}
1278 \item Code generation (Figure~\ref{fig-code-gen-settings}):
1280 \item Set ``System target file'' to \texttt{rpp.tlc}.
1283 \includegraphics[scale=.45]{images/simulink_code.png}
1284 \caption{Code Generation settings}
1285 \label{fig-code-gen-settings}
1289 \item Once the model is configured, you can open the Library Browser
1290 (\textsc{View $\rightarrow$ Library Browser}) and add the necessary
1291 blocks to create the model. The RPP-specific blocks are located in
1292 the RPP Block Library.
1293 \item From Matlab command window change the current directory to where
1294 you want your generated code to appear, e.g.:
1295 \begin{lstlisting}[language=Matlab]
1298 The code will be generated in a subdirectory named
1299 \texttt{<model>\_rpp}, where \texttt{model} is the name of the
1301 \item Generate the code by choosing \textsc{Code $\rightarrow$ C/C++
1302 Code $\rightarrow$ Build Model}.
1305 To run the model on the \tgtBoardName{} board continue with Section
1306 \ref{sec-running-model-on-hw}.
1308 \subsection{Running models on the RPP board}
1309 \label{sec-running-model-on-hw}
1310 To run the model on the \tgtBoardName{} hardware you have to enable the download
1311 feature and build the model by following this procedure:
1313 \item Open the model you want to run (see
1314 Section~\ref{sec-openning-demo-models} for example with demo
1316 \item Click on \textsc{Simulation$\rightarrow$Model Configuration
1318 \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
1319 check the \textsc{Download compiled binary to RPP} checkbox. Click
1320 the \textsc{OK} button
1321 \item Connect the target hardware to the computer (see Section
1322 \ref{sec-ccs-run-project}) and build the model by \textsc{Code
1323 $\rightarrow$ C/C++ Code $\rightarrow$ Build Model}. If the build
1324 succeeds, the download process will start automatically and once
1325 the downloading is finished, the application will run immediately.
1328 %%\subsubsection{Using OpenOCD for downloading}
1329 %%\label{sec:using-open-downl}
1331 %%On Linux systems, it is possible to use an alternative download
1332 %%mechanism based on the OpenOCD tool. This results in much shorter
1333 %%download times. Using OpenOCD is enabled by checking ``Use OpenOCD to
1334 %%download the compiled binary'' checkbox. For more information about
1335 %%the OpenOCD configuration refer to our
1336 %%wiki\footnote{\url{http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137\#OpenOCD_setup_and_Flashing}}.
1338 %%Note: You should close any ongoing Code Composer Studio debug sessions
1339 %%before downloading the generated code to the RPP board. Otherwise the
1342 \section{Configuring serial interface}
1343 \label{sec-configuration-serial-interface}
1344 The main mean for communication with the RPP board is the serial line.
1345 Each application may define its own serial line settings, but the
1346 following settings are the default:
1349 \item Baudrate: 115200
1353 \item Flow control: none
1356 Use GtkTerm on Linux or Bray Terminal on Windows for accessing the
1357 serial interface. On \tgtBoardName{} board, the serial line is tunneled over
1359 % TODO: Conditional compilation
1360 % See Section \ref{sec-hardware-description} for reference about
1361 % the position of the serial interface connector on the RPP board.
1363 \section{Configuring network interface}
1364 \label{sec-configuration-network-interface}
1365 To configure the network, it is currently necessary to set the parameters in the eth.h file. The current implementation does not allow automatic IP address retrieval through the DHCP server. The target has a configurable MAC address. It is not usually necessary to change the settings for a network connection. Only if the address could collide with other devices on the network. To configure the third-layer parameters, it is necessary to set a static IP address, network mask, and default gateway. The parameters must correspond to the network to which the device is connected.
1366 \begin{lstlisting}[language=c]
1367 #define RPP_MAC_ADDR { 0x12 /* Unicast, Locally administered */, 0x34, 0x56, 0x78, 0x9A, 0xBC }
1368 #define RPP_IP_ADDR 0x0A235F19
1369 #define RPP_NETMASK 0xFFFFFF00
1370 #define RPP_GW 0x0A235F01
1373 \section{External mode}
1374 \label{sec-external-mode}
1375 The external mode allows communication with the simulation running on the target device. It is possible to monitor the internal signals of the simulation and change the parameters of the amplifiers in the wiring. Communication is performed using the network connection of the target device. For correct operation of the external mode, it is necessary to configure the static IP address, mask, and basic gateway correctly.\\
1377 \textbf{External Mode Communication Channel Setup.} External mode is a very
1378 useful environment for rapid prototyping. Procedure to set external mode up is consisting of four parts,
1379 each of which depends on completion of the preceding ones, in order. The four
1380 parts correspond to the steps that you follow in simulating, building, running,
1381 and tuning an actual real-time application.
1383 \item Set up the model.
1384 \item Build the target executable.
1385 \item Run the External mode target program.
1386 \item Tune parameters and watch signals.
1389 \subsection{Set up the model}
1390 When creating a model, before compiling it is necessary to add scope elements to the signals, that the user will need to follow while debugging the simulation.
1391 An example of an external mode simulation is shown below.
1393 \begin{figure}[!h]\begin{center}
1395 \includegraphics[scale=.45]{images/extmod_scheme.png}
1396 \caption{The example scheme for external mode}
1397 \end{center}\end{figure}
1400 It is necessary to set the following parameters for the simulation. The description of the path to the individual parameters is based on their position in version 2018a.
1403 \item Open the Configuration Parameters dialog box by selecting Simulation -$>$ Model Configuration Parameters.
1404 \item Select the Solver pane.
1405 \item In the Solver options subpane:
1407 \item In the Type field, select Fixed-step .
1408 \item In the Solver field, select discrete (no continuous states) .
1409 \item In the Fixed-step size field, specify 0.1 . (Otherwise, when you generate
1410 code, the Simulink Coder build process posts a warning and supplies a
1414 \begin{figure}[!h]\begin{center}
1416 \includegraphics[scale=.45]{images/extmod_solver.png}
1417 \caption{Solver setup}
1418 \end{center}\end{figure}
1420 \item Select the Hardware Implementation
1422 \item In the Device vendor field, select proper vendor (example Texas Instruments)
1423 \item In the Device type field, select proper target (example TSM570).
1425 \item Select the Code Generation pane. And control that rpp target is selected.
1426 \item Select the Code Generation -$>$ Optimalization. Set field Default parameter behavior to Tunable.
1427 \begin{figure}[!h]\begin{center}
1429 \includegraphics[scale=.45]{images/exmod_parameters.png}
1430 \caption{Set parameters tuneble for external mode}
1431 \end{center}\end{figure}
1433 \item Select the Code Generation -$>$ Interface pane.
1435 \item In section Software environment, subsection Support. Set positive floating-point numbers, absolute and continuous time.
1436 \item In section Data exchange interface, set C api generation for parameters and signals. Also set External mode on and configure subsection External mode configuration. There select transport layer to tcpip and MEX-file argument to this format. The Ip address is static IP of target. This address is set in file eth.h. Default value of port si 17725. To change port number is nessesary tu redefine parameter in tcpip interface.
1437 \begin{lstlisting}[language=Matlab]
1441 \begin{lstlisting}[language=Matlab]
1442 "10.35.95.25" 1 17725
1446 \begin{figure}[!h]\begin{center}
1448 \includegraphics[scale=.45]{images/extmod_interface.png}
1449 \caption{External mode interface setup}
1450 \end{center}\end{figure}
1452 \item In the RPP, increase C system heap size to 65536. External mode uses this heap to allocate outgoing buffer. And control if is set Download compiled binary to RPP to positive.
1453 \item Open Code -$>$ External mode control panel. And click on Signals \& trigging.
1455 \item In main part of panel select scopes using external modes.
1456 \item In subsection, Trigger options set the Duration to 500. This option describes the length of the outgoing buffer on the target platform. As the frequency of the model increases, the buffer becomes full between data sending to the external modem. This leads to periodic data outages. These failures can be partially reduced by increasing the Duration value to a sufficiently high value. Due to limited memory, it may be necessary to increase the C system heap size on the RPP panel to increase the Duration value further. This value must not be greater than the remaining free space on the target.
1460 \subsection{Build the target executable}
1461 For correct model compilation, it is necessary to switch the running mode from normal to external. It is also advisable to select the simulation time, for example, to value inf.
1462 After making the previous settings, the model can be compiled and uploaded to the device using the Build model button in the Simulink header.
1464 \subsection{Run the External mode target program}
1465 Once the model has been successfully uploaded to the target, communication must be initiated.\\
1466 This is possible using the Connect to target button or the Connect button in the External mode control panel.
1467 The simulation program on the target device starts the calculation as soon as the binary file is uploaded. \\
1468 Waiting simulation on user connection is not currently implemented.
1470 \subsection{Tune parameters and watch signals}
1471 After a successful connection to the device, it is possible to configure the amplifier parameters and view the scopes in the standard way as during local machine simulation.
1473 \section{Bug reporting}
1474 \label{sec-bug-reporting}
1476 Please report any problems to CTU's bug tracking system at
1477 \url{https://redmine.felk.cvut.cz/projects/eaton-rm48}. New users have
1478 to register in the system and notify Michal Sojka about their
1479 registration via $\langle{}sojkam1@fel.cvut.cz\rangle{}$ email
1482 \chapter{C Support Library}
1483 \label{chap-c-support-library}
1485 This chapter describes the implementation of the C support library
1486 (RPP Library), which is used both for Simulink code generation target
1487 and command line testing tool.
1489 \section{Introduction}
1490 \label{sec-description}
1491 The RPP C Support Library (also called RPP library) defines the API for
1492 working with the board. It includes drivers and the operating system.
1494 designed from the board user perspective and exposes a simplified high-level API
1495 to handle the board's peripheral modules in a safe manner. The library is
1496 compiled as static library named \texttt{rpp-lib.lib} and can be found in
1497 \texttt{\repo/rpp/lib}.
1499 The RPP library can be used in any project, where the RPP hardware
1500 support is required and it is also used in two applications --
1501 Simulink Coder Target, described in Chapter
1502 \ref{chap-simulink-coder-target}, and the command line testing tool,
1503 described in Chapter \ref{chap-rpp-test-software}.
1505 For details about the library architecture, refer to Section~\ref{sec-software-architecture}.
1507 \section{API development guidelines}
1508 \label{sec-api-development-guidlines}
1510 The following are the development guidelines used for developing the RPP API:
1513 \item User documentation should be placed in header files, not in source
1514 code, and should be Doxygen formatted using autobrief. Documentation for each
1515 function present is mandatory and must mention whether the function is
1517 \item Function declarations in the headers files is for public functions
1518 only. Do not declare local/static/private functions in the header.
1519 \item Documentation in source code files should be non-doxygen formatted
1520 and intended for developers, not users. Documentation here is optional and at
1521 the discretion of the developer.
1522 \item Always use standard data types for IO when possible. Use custom
1523 structs as very last resort. \item Use prefix based functions names to avoid
1524 clash. The prefix is of the form \texttt{$\langle$layer$\rangle$\_$\langle$module$\rangle$\_}, for example
1525 \texttt{rpp\_din\_update()} for the update function of the DIN module in the RPP
1527 \item Be very careful about symbol export. Because it is used as a
1528 static library the modules should not export any symbol that is not intended to
1529 be used (function) or \texttt{extern}'ed (variable) from application. As a rule
1530 of thumb declare all global variables as static.
1531 \item Only the RPP Layer symbols are available to user applications. All
1532 information related to lower layers is hidden for the application. This is
1533 accomplished by the inclusion of the rpp.h or rpp\_\{mnemonic\}.h file on the
1534 implementations files only and never on the interface files. Never expose any
1535 other layer to the application or to the whole system below the RPP layer. In
1536 other words, never \texttt{\#include "foo/bar.h"} in any RPP Layer header
1540 \section{Coding style}
1541 \label{sec-coding-style}
1542 In order to keep the code as clean as possible, unified coding style
1543 should be followed by any contributor to the code. The used coding
1544 style is based on the default configuration of Code Composer Studio
1545 editor. Most notable rule is that the Tab character is 4 spaces.
1547 The RPP library project is prepared for use of a tool named
1548 Uncrustify. The Uncrustify tool checks the code and fixes those lines
1549 that do not match the coding style. However, keep in mind that the
1550 program is not perfect and sometimes it can modify code where the
1551 suggested coding style has been followed. This does not causes
1552 problems as long as the contributor follows the committing procedure
1553 described in next paragraph.
1555 When contributing to the code, the contributor should learn the
1556 current coding style from existing code. When a new feature is
1557 implemented and committed to the local repository, the following
1558 commands should be called in Linux terminal:
1560 \begin{lstlisting}[language=bash]
1564 The first line command corrects many found coding style violations and
1565 the second command displays them. If the user agree with the
1566 modification, he/she should amend the last commit, for example by:
1567 \begin{lstlisting}[language=bash]
1572 \section{Subdirectory content description}
1573 \label{sec-rpp-lib-subdirectory-content-description}
1575 The following files and directories are present in the library source
1579 \item[rpp-lib.lib] Compiled RPP library.
1581 The library is needed for Simulink models and other ARM/\tgname{}
1582 applications. It is placed here by the Makefile, when the library is
1585 \item[apps/] Various applications related to the RPP library.
1587 This include the CCS studio project for generating of the static
1588 library and a test suite. The test suit in this directory has
1589 nothing common with the test suite described later in
1590 Chapter~\ref{chap-rpp-test-software} and those two suits are going
1591 to be merged in the future. Also other Hello World applications are
1592 included as a reference about how to create an \tgname{}
1594 \item[build] The library can be compiled for multiple targets. Each
1595 supported target has a subdirectory here, which stores configuration
1596 of how to compile the library and applications for different target.
1597 Each subdirectory contains a CCS project and Makefiles to build the
1598 library for the particular target.
1599 \item[build/$\langle$target$\rangle$/Makefile.config] Configuration
1600 for the particular target. This includes compiler and linker
1602 \item[build/$\langle$target$\rangle$/*.cmd]
1603 CGT Linker command file.
1605 This file is used by all applications that need to tun on the RPP
1606 board, including the Simulink models and test suite. It includes
1607 instructions for the CGT Linker about target memory layout and where
1608 to place various code sections.
1610 \item[halcogen/] HalCoGen project files for the supported boards and
1611 scripts for automated conversion of HalCoGen-generated files for use
1614 Note: This is work in progress. Currently only ``pinmux'' files for
1615 tms570\_hydctr board were produced by the scripts here.
1617 \item[os/] OS layers directory. See
1618 Section~\ref{sec-operating-system-layer} for more information about
1619 currently available operating system versions and
1620 Section~\ref{sec-changing-os} for information how to replace the
1622 \item[rpp/] Main directory for the RPP library.
1623 \item[rpp/doc/] RPP Library API
1625 \item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
1626 implementations files for given \texttt{\{layer\}}. See
1627 Section~\ref{sec-software-architecture} for details on the RPP
1629 \item[rpp/include/rpp/rpp.h] Main library header file.
1631 To use this library with all its modules, just include this file
1632 only. Also, before using any library function call the
1633 \texttt{rpp\_init()} function for hardware initialization.
1634 \item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for
1635 \texttt{\{mnemonic\}} module.
1637 These files includes function definitions, pin definitions, etc,
1638 specific to \{mnemonic\} module. See also
1639 Section~\ref{sec-api-development-guidlines}.
1641 If you want to use only a subset of library functions and make the
1642 resulting binary smaller, you may include only selected
1643 \texttt{rpp\_\{mnemonic\}.h} header files and call the specific
1644 \texttt{rpp\_\{mnemonic\}\_init} functions, instead of the
1645 \texttt{rpp.h} and \texttt{rpp\_init} function.
1646 \item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation.
1648 Implementation of \texttt{rpp\_\{mnemonic\}.h}'s functions on
1649 top of the DRV library.
1650 \item[rpp/src/rpp/rpp.c] Implementation of library-wide functions.
1653 \section{Compilation}
1654 \label{sec-compilation}
1656 To compile the library open the Code Composer studio project
1657 \texttt{rpp-lib} from appropriate \texttt{build/<target>} directory
1658 (see Section~\ref{sec-openning-of-existing-project}) and build the
1659 project (\textsc{Project $\rightarrow$ Build Project}). If the build
1660 process is successful, the \texttt{rpp-lib.lib} and
1661 \texttt{Makefile.config} files will appear in the library root
1664 It is also possible to compile the library using the included
1665 \texttt{Makefile}. From the Linux command line run:
1666 \begin{lstlisting}[language=bash]
1667 cd <library-root>/build/<target>/Debug #or Release
1670 Note that this only works if Code Composer Studio is installed in
1671 \texttt{/opt/ti} directory. Otherwise, you have to set
1672 \texttt{CCS\_UTILS\_DIR} variable.
1674 On Windows command line run:
1675 \begin{lstlisting}[language=bash]
1676 cd <library-root>\build\<target>\Debug
1677 set CCS_UTILS_DIR=C:\ti\ccsv5\utils
1678 C:\ti\ccsv5\utils\bin\gmake.exe lib
1681 You have to use \texttt{gmake.exe} instead of \texttt{make} and it is
1682 necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You can
1683 also edit \texttt{\repo/build/Makefile.rules.arm} and set the variable
1686 Note that the Makefile still requires the Code Composer Studio (ARM
1687 compiler) to be installed because of the CGT.
1689 \section{Compiling applications using the RPP library}
1690 \label{sec:comp-appl-using}
1692 The relevant aspects for compiling and linking an application using
1693 the RPP library are summarized below.
1695 % \subsection{ARM target (RPP board)}
1696 % \label{sec:arm-target-rpp}
1698 The detailed instructions are presented in
1699 Section~\ref{sec:creating-new-project}. Here we briefly repeat the
1703 \item Configure include search path to contain the directory of
1704 used FreeRTOS version, e.g.
1705 \texttt{\repo/os/8.2.2/include}. See Section
1706 \ref{sec-software-architecture}.
1707 \item Include \texttt{rpp/rpp.h} header file or just the needed
1708 peripheral specific header files such as \texttt{rpp/can.h}.
1709 \item Add library \texttt{rpp-lib.lib} to the linker libraries.
1710 The RPP library must be placed before Texas Instruments
1711 support library \tgtRtlib.
1712 \item Use the provided linker command file
1713 \texttt{\ldscriptname}.
1716 % \subsection{POSIX target}
1717 % \label{sec:posix-target}
1719 % \begin{compactitem}
1720 % \item Include headers files of the OS for Simulation. At the time
1721 % of this writing the OS is POSIX FreeRTOS 6.0.4.
1722 % \item Include header files for the RPP library or for modules you
1723 % want to use (rpp\_can.h for CAN module for example).
1724 % \item Add library \texttt{librpp.a} to the linker libraries.
1725 % \item Add \texttt{pthread} to the linker libraries.
1728 \section{Compiling API documentation}
1729 \label{sec-compiling-api-documentation}
1730 The documentation of the RPP layer is formatted using Doxygen
1731 documentation generator. This allows to generate a high quality API
1732 reference. To generate the API reference run in a Linux terminal:
1734 \lstset{language=bash}
1736 cd <repo>/rpp/doc/api
1738 xdg-open html/index.html
1741 The files under \texttt{\repo/rpp/doc/api/content} are used for the API
1742 reference generation are their name is self-explanatory:
1752 \section{Changing operating system}
1753 \label{sec-changing-os}
1754 The C Support Library contains by default the FreeRTOS operating
1755 system in version 8.2.2. This section describes what is necessary to
1756 change in the library and other packages in order to replace the
1759 \subsection{Operating system code and API}
1761 The source and header files of the current operating system (OS) are
1762 stored in directory \texttt{\repo/rpp/lib/os}. The files of the new
1763 operating system should also be placed in this directory.
1765 To make the methods and resources of the new OS available to the C Support
1766 Library, modify the \texttt{\repo/rpp/lib/rpp/include/base.h} file to include
1767 the operating system header files.
1769 Current implementation for FreeRTOS includes a header file
1770 \texttt{\repo/rpp/lib/os/\-8.2.2\-include/os.h}, which
1771 contains all necessary declarations and definitions for the FreeRTOS.
1772 We suggest to provide a similar header file for your operating system as
1775 In order to compile another operating system into the library, it is
1776 necessary to modify \texttt{\repo/rpp/lib/Makefile.var} file, which
1777 contains a list of files that are compiled into the library. All lines
1778 starting with \texttt{os/} should be updated.
1780 \subsection{Device drivers}
1781 Drivers for SCI and ADC depend on the FreeRTOS features. These
1782 features need to be replaced by equivalent features of the new
1783 operating system. Those files should be modified:
1785 \item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data
1786 structure, referring to FreeRTOS queue and semaphore.
1787 \item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Uses FreeRTOS queues
1789 \item[\repo/rpp/lib/rpp/include/drv/sci.h] Declaration of
1790 \texttt{drv\_sci\_receive()} contains \texttt{portTick\-Type}. We
1791 suggest replacing this with OS independent type, e.g. number of
1792 milliseconds to wait, with $-1$ meaning infinite waiting time.
1793 \item[\repo/rpp/lib/rpp/src/drv/sci.c] Uses the following FreeRTOS
1794 specific features: semaphores, queues, data types
1795 (\texttt{portBASE\_TYPE}) and
1796 critical sections (\texttt{taskENTER\_CRITICAL} and
1797 \texttt{task\-EXIT\_CRITICAL}). Inside FreeRTOS critical sections,
1798 task preemption is disabled. The same should be ensured by the other
1799 operating system or the driver should be rewritten to use other
1800 synchronization primitives.
1801 \item[\repo/rpp/lib/rpp/src/drv/adc.c] Uses FreeRTOS semaphores.
1804 \subsection{System start}
1805 The initialization of the MCU and the system is in the
1806 \texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} file. If the new
1807 operating system needs to handle interrupts generated by the Real-Time
1808 Interrupt module, the pointer to the Interrupt Service Routine (ISR)
1809 \texttt{vPreemptiveTick} has to be replaced.
1811 \subsection{Simulink template for main function}
1813 When the operating system in the library is replaced, the users of the
1814 library must be changed as well. In case of Simulink code generation
1815 target, described in Chapter~\ref{chap-simulink-coder-target}, the
1816 template for generation of the \texttt{ert\_main.c} file, containing
1817 the main function, has to be modified to use proper functions for task
1818 creation, task timing and semaphores. The template is stored in
1819 \texttt{\repo/rpp/rpp/rpp\_mrmain.tlc} file.
1821 \chapter{Simulink Coder Target}
1822 \label{chap-simulink-coder-target}
1824 The Simulink Coder Target allows to convert Simulink models to C code,
1825 compile it and download to the board.
1827 \section{Introduction}
1828 \label{sec-introduction}
1830 The Simulink RPP Target provides support for C source code generation from Simulink models and
1831 compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
1832 uses Texas Instruments ARM compiler (\texttt{armcl}) included in the Code Generation Tools distributed with
1833 Code Composer Studio, and thus it depends on it for proper functioning.
1835 This target also provides support for automatic download of the compiled binary to the RPP
1838 \begin{figure}\begin{center}
1840 \includegraphics[scale=.45]{images/tlc_process.png}
1841 \caption{TLC code generation process. \cite[p. 1-6]{targetlanguagecompiler2013}}
1842 \end{center}\end{figure}
1844 \section{Features and limitations}
1845 \label{sec-features}
1848 \item Sampling frequencies up to 1\,kHz.
1849 \item Multi-rate models can be executed in a single or multiple OS
1850 tasks. Multi-tasking mode allows high-rate tasks to preempt low-rate
1851 tasks. See Section \ref{sec-singlet-multit-modes} for more details.
1852 \item Support of external mode included over TCPIP with some limitations. See Section \ref{sec-external-mode} for more details.
1853 \item Custom compiler options, available via OPTS variable in
1854 \emph{Make command} at \emph{Code Generation} tab (see Figure
1855 \ref{fig-code-gen-settings}). For example \texttt{make\_rtw
1859 \section{RPP Options pane}
1860 \label{sec-rpp-target-options}
1862 The RPP Target includes the following configuration options, all of them
1863 configurable per model under \textsc{Code Generation} \noindent$\rightarrow$
1864 \textsc{RPP Options}:
1867 \item \textbf{C system stack size}: this parameter is passed directly
1868 to the linker for the allocation of the stack. Note that this stack
1869 is used only for initializing the application and FreeRTOS. Once
1870 everything is initialized, another stack is used by the generated
1871 code. See below. Default value is 4096.
1873 \item \textbf{C system heap size}:
1874 \label{sec-rpp-target-options-heap-size} this parameter is passed
1875 directly to the linker for the allocation of the heap. Currently,
1876 the heap is not used, but will be used by the external mode in the future.
1877 Note that FreeRTOS uses its own heap whose size is independent of this
1879 \item \textbf{Model step task stack size}: this parameter will be
1880 passed to the \texttt{xTaskCreate()} that
1881 creates the task for the model to run. In a Simulink model there are always two tasks:
1883 \item The worker task. This task is the one that executes the model
1884 step. This task requires enough stack memory to execute the step.
1885 If your model does not run, it might be caused by too small stack.
1886 The memory needed for the stack depends on the size and structure
1888 \item The control task. This task controls when the worker task should execute and controls overruns.
1891 \item \textbf{Download compiled binary to RPP}: if set, this option will download the generated binary to
1892 the board after the model is successfully built. Note that this option is unaware of the option
1893 \textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to download even if
1894 only source code has been generated, failing graciously or uploading an old binary laying around
1895 in the build directory. This option calls the \texttt{rpp\_download.m} script, which is in turn a
1896 wrapper on the \texttt{loadti.sh}, \texttt{loadti.bat} and \texttt{loadopenocd.sh} script. More information on the \texttt{loadti.sh}
1897 script can be found in:
1899 <ccs>/ccs_base/scripting/examples/loadti/readme.txt
1900 http://processors.wiki.ti.com/index.php/Loadti
1903 The \texttt{loadti.sh} and \texttt{loadti.bat} script will close after the
1904 download of the generated program, leaving the loaded program running.
1906 The \texttt{loadopenocd.sh} script will close after the download of the
1907 generated program as well, but the program will be stopped. In order to run
1908 the loaded program a manual reset of the board is required.
1910 \item \textbf{Download compiled binary to SDRAM}: This feature is not yet
1911 implemented for the simulink target.
1913 \item \textbf{Use OpenOCD to download the compiled binary}: This feature is not yet
1914 implemented for the \mcuname{} simulink target.
1915 % TODO Not true - use conditional compilation here.
1917 \item \textbf{Print model metadata to SCI at start}: if set this option will
1918 print a message to the Serial Communication Interface when the model start
1919 execution on the board. This is very helpful to identify the model running on
1920 the board. The message is in the form:
1923 `model_name' - generated_date (TLC tlc_version)
1928 `hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
1932 \section{Subdirectory content description}
1933 \label{sec-simulink-subdirectory-content-description}
1934 This section describes the directories of the Simulink Coder. If you are
1935 interested in particular file, refer the description at the beginning of the
1939 \item[doc/] Contains the sources of the documentation, you are now
1941 \item[refs/] Contains third party references, which license allows the
1943 \item[rpp/blocks] Contains the Simulink blocks specific to the
1944 \tgtBoardName{} board and their sources (.c and .tlc files). When an
1945 user calls \texttt{rpp\_setup.m}, these files are processed and
1946 Simulink block library \texttt{rpp\_lib.slx} is created.
1947 \item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the
1948 Matlab Simulink model.
1949 \item[rpp/demos] Contains demo models, which purpose is to serve as a
1950 reference for the usage and for testing.
1951 \item[rpp/lib] Contains the C Support Library. See Chapter
1952 \ref{chap-c-support-library}. \item[rpp/loadopenocd] Contains download scripts
1953 for Linux support of the OpenOCD, for code downloading to the target.
1954 \item[rpp/loadti] Contains download scripts for Linux and Windows
1955 support for code downloading to the target, using Texas Instruments CCS code
1957 \item[rpp/rpp] Contains set of support script for the Code Generator.
1960 \section{Tasking modes}
1961 \label{sec-singlet-multit-modes}
1963 This section describes two different modes (single- and multi-tasking)
1964 of how generated code of multi-rate models can be executed. Tasking
1965 mode can be selected for every model in the configuration dialog as
1966 described in Section \ref{sec-crating-new-model}.
1968 For single-rate models, the mode selection does not matter. For
1969 multi-rate models, the mode selection becomes important as it may
1970 influence certain system properties such as safety or performance.
1972 \subsection{SingleTasking mode}
1973 \label{sec-singlet-mode}
1974 In this mode all Simulink tasks, defined by their sampling rate, run
1975 in a single operating system task (thread). This means that the period
1976 of the highest rate Simulink task cannot be greater than the
1977 worst-case execution time of all Simulink tasks together. On the other
1978 hand, using this mode reduces the risk of failures caused by task
1979 synchronization errors, e.g. race conditions, deadlocks.
1981 \subsection{MultiTasking mode}
1982 \label{sec-multit-mode}
1984 In this mode every Simulink task, defined by its sampling rate, runs
1985 in its own operating system task (thread). Thread priorities are
1986 assigned based on task rates in such a way that tasks with higher
1987 rates can preempt tasks with lower rates. This means that the period
1988 of the fastest sampling rate is limited only by the execution time of
1989 this task and not of all the tasks in the system.
1991 This mode offers more efficient use of system resources (CPU) but
1992 there is a possibility of failures caused by task synchronization
1995 \section{Block Library Overview}
1996 \label{sec-block-library-overview}
1997 The Simulink Block Library is a set of blocks that allows Simulink models to use
1998 board IO and communication peripherals. The available blocks are summarized in
1999 Table~\ref{tab:block-lib-status} and more detailed description is
2000 given in Section~\ref{sec-blocks-description}.
2003 \begin{center}\begin{tabular}{|lp{5cm}lll|}
2005 \textbf{Category} & \textbf{Name} & \textbf{Status} & \textbf{Mnemonic} & \textbf{Header} \\
2007 \input{block_table.tex}
2009 \end{tabular}\end{center}
2011 \caption{Block library overview}
2012 \label{tab:block-lib-status}
2015 \label{sec-blocks-implementation}
2016 All of the blocks are implemented as manually created C Mex S-Function . In this section the
2017 approach taken is briefly explained.
2019 \subsection{C MEX S-Functions}
2020 \label{sec-c-mex-functions}
2022 \item C : Implemented in C language. Other options are Fortran and Matlab language itself.
2023 \item MEX: Matlab Executable. They are compiled by Matlab - C compiler wrapper called MEX.
2024 \item S-Function: System Function, as opposed to standard functions, or user functions.
2027 A C MEX S-Function is a structured C file that implements some mandatory and
2028 optional callbacks for a specification of a number of inputs, outputs, data
2029 types, parameters, rate, validity checking, etc. A complete list of callbacks
2032 \htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
2035 The way a C MEX S-Function participates in a Simulink simulation is shown on the
2036 diagram \ref{fig-sfunctions-process}:
2038 \begin{figure}[H]\begin{center}
2040 \includegraphics[scale=.45]{images/sfunctions_process.png}
2041 \caption{Simulation cycle of a S-Function. \cite[p. 57]{simulinkdevelopingsfunctions2013}}
2042 \label{fig-sfunctions-process}
2043 \end{center}\end{figure}
2045 In general, the S-Function can perform calculations, inputs and outputs for simulation. Because
2046 the RPP blocks are for hardware peripherals control and IO the blocks are
2047 implemented as pure sink or pure source, the S-Function is just a descriptor of
2048 the block and does not perform any calculation and does not provide any input or
2049 output for simulations.
2051 The implementation of the S-Functions in the RPP project has following layout:
2054 \item Define S-Function name \texttt{S\_FUNCTION\_NAME}.
2055 \item Include header file \texttt{header.c}, which in connection with
2056 \texttt{trailer.c} creates a miniframework for writing S-Functions.
2057 \item In \texttt{mdlInitializeSizes} define:
2059 \item Number of \textit{dialog} parameter.
2060 \item Number of input ports.
2062 \item Data type of each input port.
2064 \item Number of output ports.
2066 \item Data type of each output port.
2068 \item Standard options for driver blocks.
2070 \item In \texttt{mdlCheckParameters}:
2072 \item Check data type of each parameter.
2073 \item Check range, if applicable, of each parameter.
2075 \item In \texttt{mdlSetWorkWidths}:
2077 \item Map \textit{dialog} parameter to \textit{runtime} parameters.
2079 \item Data type of each \textit{runtime} parameter.
2082 \item Define symbols for unused functions.
2083 \item Include trailer file \texttt{trailer.c}.
2086 The C MEX S-Function implemented can be compiled with the following command:
2088 \lstset{language=bash}
2090 <matlabroot>/bin/mex sfunction_{mnemonic}.c
2093 As noted the standard is to always prefix S-Function with \texttt{sfunction\_}
2094 and use lower case mnemonic of the block.
2096 Also a script called \texttt{compile\_blocks.m} is included. The script that
2097 allows all \texttt{sfunctions\_*.c} to be fed to the \texttt{mex} compiler so
2098 all S-Functions are compiled at once. To use this script, in Matlab do:
2100 \lstset{language=Matlab}
2102 cd <repo>/rpp/blocks/
2106 \subsection{Target Language Compiler files}
2107 \label{sec-target-language-compiler-files}
2109 In order to generate code for each one of the S-Functions, every S-Function implements a TLC file
2110 for \textit{inlining} the S-Function on the generated code. The TLC files describe how to
2111 generate code for a specific C MEX S-Function block. They are programmed using TLC own language and
2112 include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX
2115 The standard for a TLC file is to be located under the \texttt{tlc\_c} subfolder from where the
2116 S-Function is located and to use the very exact file name as the S-Function but with the \texttt{.tlc}
2117 extension: \texttt{sfunction\_foo.c} \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_foo.tlc}
2119 The TLC files implemented for this project use 3 hook functions in particular (other are available,
2120 see TLC reference documentation):
2122 \item \texttt{BlockTypeSetup}: \newline{}
2123 BlockTypeSetup executes once per block type before code generation begins.
2124 This function can be used to include elements required by this block type, like includes or
2126 \item \texttt{Start}: \newline{}
2127 Code here will be placed in the \texttt{void
2128 $\langle$modelname$\rangle$\_initialize(void)}. Code placed here will execute
2130 \item \texttt{Outputs}: \newline{}
2131 Code here will be placed in the \texttt{void
2132 $\langle$modelname$\rangle$\_step(void)} function. Should be used to get the
2133 inputs of a block and/or to set the outputs of that block.
2136 The general layout of the TLC files implemented for this project is:
2138 \item In \texttt{BlockTypeSetup}: \newline{}
2139 Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
2140 \texttt{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
2141 \item \texttt{Start}: \newline{}
2142 Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup,
2143 DAC value initialization, SCI baud rate setup, among others.
2144 \item \texttt{Outputs}: \newline{}
2145 Call common IO routines from RPP Layer, like DIN read, DAC set, etc. Success of this functions
2146 is checked and in case of failure error is reported to the block using ErrFlag.
2149 C code generated from a Simulink model is placed on a file called
2150 \texttt{$\langle$modelname$\rangle$.c} along with other support files in a
2151 folder called \texttt{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}.
2152 For example, the source code generated for model \texttt{foobar} will be placed
2153 in current Matlab directory \texttt{foobar\_rpp/foobar.c}.
2155 The file \texttt{$\langle$modelname$\rangle$.c} has 3 main functions:
2157 \item \texttt{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
2158 This function recalculates all the outputs of the blocks and should be called once per step. This
2159 is the main working function.
2160 \item \texttt{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
2161 This function is called only once before the first step is issued. Default values for blocks IOs
2162 should be placed here.
2163 \item \texttt{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
2164 This function is called when terminating the model. This should be used to free memory or revert
2165 other operations made in the initialization function. With current implementation this function
2166 should never be called unless an error is detected and in most models it is empty.
2169 \section{Block reference}
2170 \label{sec-blocks-description}
2172 This section describes each one of the Simulink blocks present in the Simulink
2173 RPP block library, shown in Figure \ref{fig-block-library}.
2177 \includegraphics[width=\textwidth]{images/block_library.png}
2179 \caption{Simulink RPP Block Library.}
2180 \label{fig-block-library}
2183 \input{block_desc.tex}
2186 \section{Compilation}
2187 \label{sec-simulink-compilation}
2188 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:
2189 \lstset{language=Matlab}
2191 cd <rpp-simulink>/rpp/blocks
2195 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:
2198 \item Open Matlab and run those commands in the Matlab command line:
2199 \lstset{language=Matlab}
2201 cd <rpp-simulink>/rpp/demos
2204 \item Run those commands in a Linux terminal:
2205 \begin{lstlisting}[language=bash]
2206 cd <rpp-simulink>/rpp/demos
2210 or Windows command line:
2212 \begin{lstlisting}[language=bash]
2213 cd <rpp-simulink>\rpp\demos
2214 "C:\ti\ccsv5\utils\bin\"gmake.exe lib
2217 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}.
2220 \section{Adding new functionality}
2221 \label{sec:adding-new-funct}
2222 This section describes how to create new Simulink blocks and how to add them to the RPP
2223 blocks library. The new block creation process consists of several steps:
2225 \item Addition of the new functionality to the RPP C support library.
2226 \item Definition of the block interface as a C MEX S-Function
2227 (Section~\ref{sec:block-definition-c})
2228 \item Compilation of the block definition to MEX file
2229 (Section~\ref{sec:c-mex-file})
2230 \item Creation of the code generator template (TLC) file
2231 (Section~\ref{sec:tlc-file-creation}).
2232 \item Creation of an S-Function block in the RPP block library
2233 and ``connecting'' this block with the C MEX and TLC files
2234 (Section~\ref{sec:creation-an-s})
2235 \item Optional: Creation of the mask for the new block. The mask
2236 specifies graphical representation of the block as well as
2237 the content of the block parameters dialog box.
2239 The following subsections demonstrate the procedure on an example of a simple user defined block.
2241 \subsection{Block interface definition in a C MEX S-function}
2242 \label{sec:block-definition-c}
2243 In order to use a custom block in the Simulink model, Simulink must know
2244 a certain number of block attributes, such as the number and type of
2245 block inputs, outputs and parameters. These attributes are specified
2246 by a set of functions in a C file. This C file gets compiled by the MEX
2247 compiler into a MEX file and is then used in an S-Function block.
2248 Simulink calls the functions in the C MEX file to obtain the above
2249 mentioned block attributes. In case of RPP blocks, no other
2250 functionality is present in the C MEX file.
2252 The C files are stored in \texttt{\repo/rpp/blocks} directory and are named as
2253 \texttt{sfunction\_$\langle$name$\rangle$.c}. Feel free to open any of
2254 the C files as a reference.
2256 Every C file that will be used with the RPP library should begin with
2257 a comment in YAML\footnote{\url{http://yaml.org/},
2258 \url{https://en.wikipedia.org/wiki/YAML}} format. The information in
2259 this block is used to automatically generate both printed and on-line
2260 documentation. Although this block is not mandatory, it is highly
2261 recommended, as it helps keeping the documentation consistent and
2264 The YAML documentation block may look like this:
2265 \begin{lstlisting}[language=c,basicstyle=\texttt\footnotesize]
2269 Name: Name Of The Block
2275 - { name: "Some Input Signal", type: "bool" }
2278 - { name: "Some Output Signal", type: "bool" }
2282 # Description and Help is in Markdown mark-up
2285 This is a stub of an example block.
2289 This block is a part of an example about how to create
2290 new Matlab Simulink blocks for RPP board.
2294 RPP API functions used:
2302 Following parts are obligatory and the block will not work without them. It starts with a
2303 definition of the block name and inclusion of a common source file:
2305 \begin{lstlisting}[language=c]
2306 #define S_FUNCTION_NAME sfunction_myblock
2310 To let Simulink know the type of the inputs, outputs and how many parameters
2311 will the block have, the \texttt{mdlInitializeSizes()} function has to be defined like this:
2313 \begin{lstlisting}[language=c]
2314 static void mdlInitializeSizes(SimStruct *S)
2316 /* The block will have no parameters. */
2317 if (!rppSetNumParams(S, 0)) {
2320 /* The block will have one input signal. */
2321 if (!ssSetNumInputPorts(S, 1)) {
2324 /* The input signal will be of type boolean */
2325 rppAddInputPort(S, 0, SS_BOOLEAN);
2326 /* The block will have one output signal */
2327 if (!ssSetNumOutputPorts(S, 1)) {
2330 /* The output signal will be of type boolean */
2331 rppAddOutputPort(S, 0, SS_BOOLEAN);
2333 rppSetStandardOptions(S);
2337 The C file may contain several other optional functions definitions for parameters check,
2338 run-time parameters definition and so on. For information about those functions refer the comments
2339 in the header.c file, trailer.c file and documentation of Simulink S-Functions.
2341 The minimal C file compilable into C MEX has to contain following
2342 macros to avoid linker error messages about some of the optional
2343 functions not being defined:
2344 \begin{lstlisting}[language=c]
2345 #define COMMON_MDLINITIALIZESAMPLETIMES_INHERIT
2346 #define UNUSED_MDLCHECKPARAMETERS
2347 #define UNUSED_MDLOUTPUTS
2348 #define UNUSED_MDLTERMINATE
2351 Every C file should end by inclusion of a common trailer source file:
2353 \begin{lstlisting}[language=c]
2354 #include "trailer.c"
2357 \subsection{C MEX file compilation}
2358 \label{sec:c-mex-file}
2359 In order to compile the created C file, the development environment
2360 has to be configured first as described in
2361 Section~\ref{sec-matlab-simulink-usage}.
2363 All C files in the directory \texttt{\repo/rpp/blocks} can be compiled
2364 into C MEX by running script
2365 \texttt{\repo/rpp/blocks/compile\_blocks.m} from Matlab command
2366 prompt. If your block requires some special compiler options, edit the
2367 script and add a branch for your block.
2369 To compile only one block run the \texttt{mex sfunction\_myblock.c}
2370 from Matlab command prompt.
2372 \subsection{TLC file creation}
2373 \label{sec:tlc-file-creation}
2374 The TLC file is a template used by the code generator to generate the
2375 C code for the RPP board. The TLC files are stored in
2376 \texttt{\repo/rpp/blocks/tlc\_c} folder and their names must be the
2377 same (except for the extension) as the names of the corresponding
2378 S-Functions, i.e. \texttt{sfunction\_$\langle$name$\rangle$.tlc}. Feel
2379 free to open any of the TLC files as a reference.
2381 TLC files for RPP blocks should contain a header:
2382 \begin{lstlisting}[language=c]
2383 %implements sfunction_myblock "C"
2384 %include "common.tlc"
2387 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:
2389 \item BlockTypeSetup
2390 \item BlockInstanceSetup
2395 For detailed description about each one of those functions, refer to
2396 \cite{targetlanguagecompiler2013}. A simple TLC file, which generates
2397 some code may look like this:
2398 \begin{lstlisting}[language=c]
2399 %implements sfunction_myblock "C"
2400 %include "common.tlc"
2402 %function BlockTypeSetup(block, system) void
2403 %% Ensure required header files are included
2404 %<RppCommonBlockTypeSetup(block, system)>
2405 %<LibAddToCommonIncludes("rpp/sci.h")>
2408 %function Outputs(block, system) Output
2409 %if !SLibCodeGenForSim()
2410 %assign in_signal = LibBlockInputSignal(0, "", "", 0)
2411 %assign out_signal = LibBlockOutputSignal(0, "", "", 0)
2413 %<out_signal> = !%<in_signal>;
2414 rpp_sci_printf("Value: %d\r\n", %<in_signal>);
2420 The above template causes the generated code to contain
2421 \texttt{\#include "rpp/sci.h"} line and whenever the block is
2422 executed, its output will be the negation of its input and the value
2423 of the input signal will be printed to the serial line.
2425 \subsection{Creation of an S-Function block in the RPP block library}
2426 \label{sec:creation-an-s}
2427 User defined Simulink blocks can be included in the model as
2428 S-Function blocks. Follow this procedure to create a new block in the
2431 \item Create a new Simulink library by selecting
2432 \textsc{File$\rightarrow$New$\rightarrow$Library} and save it as
2433 \texttt{\repo\-/rpp/blocks/rpp\_$\langle$name$\rangle$.slx}.
2434 Alternatively, open an existing library.
2435 \item In case of opening an existing library, unlock it for editing by
2436 choosing \textsc{Diagram$\rightarrow$Unlock Library}.
2437 \item Open a Simulink Library Browser
2438 (\textsc{View$\rightarrow$Library Browser}) open
2439 \textsc{Simulink$\rightarrow$User-Defined Functions} and drag the
2440 \textsc{S-Function} block into the newly created library.
2441 \item Double click on the just created \textsc{S-Function} block and
2442 fill in the \textsc{S-function name} field. Put there the name
2443 (without the extension) of the created C MEX S-Function, e.g.
2444 sfunction\_myblock. The result should like like in
2445 Figure~\ref{fig-simulink_s_fun_cfg}.
2446 \begin{figure}[h]\begin{center}
2448 \includegraphics[scale=.45]{images/simulink_s_fun_config.png}
2449 \caption{Configuration dialog for user defined S-function.}
2450 \label{fig-simulink_s_fun_cfg}
2451 \end{center}\end{figure}
2452 \item If your block has some parameters, write their names (you can
2453 choose them arbitrarily) in the \textsc{S-function parameters}
2454 field, separated by commas. \label{item:1}
2455 \item Now you should see the new Simulink block with the right number
2456 of inputs and outputs.
2457 \item Optional: Every user-defined block can have a \emph{mask}, which
2458 provides some useful information about the name of the block,
2459 configuration dialog for parameters and names of the IO signals. The
2460 block can be used even without the mask, but it is not as user
2461 friendly as with proper mask. Right-click the block and select
2462 \textsc{Mask$\rightarrow$Create Mask...}. In the definition of
2463 parameters, use the same names as in step~\ref{item:1}. See
2464 \cite[Section ``Block Masks'']{mathworks13:simul_2013b} for more
2466 \item Save the library and run \texttt{rpp\_setup} (or just
2467 \texttt{rpp\_generate\_lib}) from Matlab command line to add the newly
2468 created block to RPP block library (\texttt{rpp\_lib.slx}).
2471 Now, you can start using the new block in Simulink models as described
2472 in Section~\ref{sec-crating-new-model}.
2475 \section{Demos reference}
2476 The Simulink RPP Demo Library is a set of Simulink models that use blocks from
2477 the Simulink RPP Block Library and generates code using the Simulink RPP Target.
2479 This demos library is used as a test suite for the Simulink RPP Block Library
2480 but they are also intended to show basic programs built using it. Because of
2481 this, the demos try to use more than one
2482 type of block and more than one block per block type.
2484 In the reference below you can find a complete description for each of the demos.
2486 \subsection{ADC demo}
2487 \begin{figure}[H]\begin{center}
2489 \includegraphics[scale=.45]{images/demo_adc.png}
2490 \caption{Example of the usage of the Analog Input blocks for RPP.}
2491 \end{center}\end{figure}
2493 \textbf{Description:}
2495 Demostrates how to use Analog Input blocks in order to measure voltage. This demo
2496 measures voltage on every available Analog Input and prints the values on the
2499 \subsection{Simple CAN demo}
2500 \begin{figure}[H]\begin{center}
2502 \includegraphics[scale=.45]{images/demo_simple_can.png}
2503 \caption{The simplest CAN demonstration.}
2504 \end{center}\end{figure}
2506 \textbf{Description:}
2508 The simplest possible usage of the CAN bus. This demo is above all designed for
2509 testing the CAN configuration and transmission.
2511 \subsection{CAN transmit}
2512 \begin{figure}[H]\begin{center}
2514 \includegraphics[scale=.45]{images/demo_cantransmit.png}
2515 \caption{Example of the usage of the CAN blocks for RPP.}
2516 \end{center}\end{figure}
2518 \textbf{Description:}
2520 Demostrates how to use CAN Transmit blocks in order to:
2523 \item Send unpacked data with data type uint8, uint16 and uint32.
2524 \item Send single and multiple signals packed into CAN\_MESSAGE by CAN Pack block.
2525 \item Send a message as extended frame type to be received by CAN Receive
2526 configured to receive both, standard and extended frame types.
2529 Demostrates how to use CAN Receive blocks in order to:
2532 \item Receive unpacked data of data types uint8, uint16 and uint32.
2533 \item Receive and unpack received CAN\_MESSAGE by CAN Unpack block.
2534 \item Configure CAN Receive block to receive Standard, Extended and both frame types.
2535 \item Use function-call mechanism to process received messages
2538 \subsection{Continuous time demo}
2539 \begin{figure}[H]\begin{center}
2541 \includegraphics[scale=.45]{images/demo_continuous.png}
2542 \caption{The demonstration of contiuous time.}
2543 \end{center}\end{figure}
2545 \textbf{Description:}
2547 This demo contains two integrators, which are running at continuous time. The main goal
2548 of this demo is to verify that the generated code is compilable and is working even when
2549 discrete and continuous time blocks are combined together.
2551 \subsection{Simulink Demo model}
2552 \begin{figure}[H]\begin{center}
2554 \includegraphics[scale=.45]{images/demo_board.png}
2555 \caption{Model of the complex demonstration of the boards peripherals.}
2556 \end{center}\end{figure}
2558 \textbf{Description:}
2560 This model demonstrates the usage of RPP Simulink blocks in a complex and interactive
2561 application. The TI HDK kit has eight LEDs placed around the MCU. The application
2562 rotates the light around the MCU in one direction. Every time the user presses the button
2563 on the HDK, the direction is switched.
2565 The state of the LEDs is sent on the CAN bus as a message with ID 0x1. The button can
2566 be emulated by CAN messages with ID 0x0. The message 0x00000000 simulates button release
2567 and the message 0xFFFFFFFF simulates the button press.
2569 Information about the state of the application are printed on the Serial Interface.
2571 \subsection{Echo char}
2572 \begin{figure}[H]\begin{center}
2574 \includegraphics[scale=.45]{images/demo_echo_char.png}
2575 \caption{Echo Character Simulink demo for RPP.}
2576 \end{center}\end{figure}
2578 \textbf{Description:}
2580 This demo will echo (print back) any character received through the Serial Communication
2581 Interface (115200-8-N-1).
2583 Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
2584 if data is received, that is, Serial Receive output is non-negative. Negative values are errors.
2586 \subsection{GIO demo}
2587 \begin{figure}[H]\begin{center}
2589 \includegraphics[scale=.45]{images/demo_gio.png}
2590 \caption{Demonstration of DIN and DOUT blocks}
2591 \end{center}\end{figure}
2593 \textbf{Description:}
2595 The model demonstrates how to use the DIN blocks and DOUT blocks, configured in every mode. The DOUTs
2596 are pushed high and low with period 1 second. The DINs are reading inputs and printing the values
2597 on the Serial Interface with the same period.
2599 \subsection{Hello world}
2600 \begin{figure}[H]\begin{center}
2602 \includegraphics[scale=.45]{images/demo_hello_world.png}
2603 \caption{Hello World Simulink demo for RPP.}
2604 \end{center}\end{figure}
2606 \textbf{Description:}
2608 This demo will print \texttt{Hello Simulink} to the Serial Communication Interface (115200-8-N-1) one
2609 character per second. The output speed is driven by the Simulink model step which is set to one
2612 \subsection{Multi-rate SingleTasking demo}
2613 \label{sec:mult-single-thre}
2615 \begin{figure}[H]\begin{center}
2617 \includegraphics[scale=.45]{images/demo_multirate_st.png}
2618 \caption{Multi-rate SingleTasking Simulink demo for RPP.}
2619 \end{center}\end{figure}
2621 \textbf{Description:}
2623 This demo will toggle LEDs on the Hercules Development Kit with
2624 different rate. This is implemented with multiple Simulink tasks, each
2625 running at different rate. In the generated code, these tasks are
2626 called from a singe thread and therefore no task can preempt another
2627 one. See Section \ref{sec-singlet-mode} for more details.
2629 The state of each LED is printed to the Serial Communication Interface
2630 (115200-8-N-1) when toggled.
2633 \begin{tabular}{lll}
2634 \rowcolor[gray]{0.9}
2635 LED & pin & rate [s] \\
2636 1 & NHET1\_25 & 0.3 \\
2637 2 & NHET1\_05 & 0.5 \\
2638 3 & NHET1\_00 & 1.0 \\
2640 \captionof{table}{LEDs connection and rate}
2641 \label{tab:multirate_st_led_desc}
2644 \subsection{Multi-rate MultiTasking demo}
2645 \label{sec:mult-multi-thre}
2647 \begin{figure}[H]\begin{center}
2649 \includegraphics[scale=.45]{images/demo_multirate_mt.png}
2650 \caption{Multi-rate MultiTasking Simulink demo for RPP.}
2651 \label{fig:multitasking-demo}
2652 \end{center}\end{figure}
2654 \textbf{Description:}
2656 This demo toggles LEDs on the Hercules Development Kit with different
2657 rate (different colors in Figure~\ref{fig:multitasking-demo}). This is
2658 implemented with multiple Simulink tasks, each running at different
2659 rate. In the generated code, every subrate task runs in its own
2660 operating system thread. See Section \ref{sec-multit-mode} for more
2663 The state of each LED is also printed to the Serial Communication
2664 Interface (115200-8-N-1) when toggled.
2667 \begin{tabular}{lll}
2668 \rowcolor[gray]{0.9}
2669 LED & pin & rate [s] \\
2670 1 & NHET1\_25 & 0.3 \\
2671 2 & NHET1\_05 & 0.5 \\
2672 3 & NHET1\_00 & 1.0 \\
2674 \captionof{table}{LEDs connection and rate}
2675 \label{tab:multirate_mt_led_desc}
2678 \subsection{Hydraulics controller initialization demo}
2679 \label{sec:board-init-hydctr}
2682 \includegraphics[scale=0.45]{images/demo_board_init_hydctr.png}
2683 \caption{board\_init\_hydctr demo}
2684 \label{fig:board_init_hydctr}
2687 \paragraph{Description}
2689 This demo shows how to use the \emph{Board Init} block to initialize
2690 SPI devices on the Hydraulics Controller board. Additionally, it shows
2691 how to use unused SPI pins on the MCU as general-purpose IOs. If both
2692 Board Init and GIO SPI blocks are used together, care must be taken
2693 about the order in which the blocks are initialized. GIO blocks that
2694 represent SPI pins must be initialized \emph{after} the Board Init
2695 block. This can be ensured by giving the GIO blocks higher priority
2696 than the Board Init block.
2698 \chapter{Command line testing tool}
2699 \label{chap-rpp-test-software}
2700 \section{Introduction}
2701 \label{sec-rpp-test-sw-intro}
2702 The \texttt{rpp-test-suite} is a RPP application developed testing and direct
2703 control of the RPP hardware. The test suite implements a command processor,
2704 which is listening for commands and prints some output related to the commands
2705 on the serial interface. The command processor is modular and each peripheral
2706 has its commands in a separate module.
2708 The command processor is implemented in \texttt{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
2709 modules are implemented in \texttt{$\langle$rpp-test-sw$\rangle$/commands} directory.
2711 The application enables a command processor using the SCI at
2712 \textbf{115200-8-N-1}. When the software starts, the received welcome message
2713 and prompt should look like:
2716 \ifx\tgtId\tgtIdTMSRPP
2717 \noindent\texttt{Rapid Prototyping Platform v00.01-001\\
2718 Test Software version \input{version.tex}\\
2719 CTU in Prague 2014\\
2723 \noindent\texttt{Ti HDK \mcuname, FreeRTOS 7.0.2\\
2724 Test Software version \input{version.tex}\\
2725 CTU in Prague 10/2014\\
2732 Type in command help for a complete list of available command, or help command
2733 for a description of concrete command.
2735 \section{Compilation}
2736 \label{sec-rpp-test-sw-compilation}
2737 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.
2739 \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}.
2740 \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}.
2742 To build the Testing tool from Linux terminal run:
2743 \begin{lstlisting}[language=bash]
2748 or from Windows command line:
2750 \begin{lstlisting}[language=bash]
2752 "C:\ti\ccsv5\utils\bin\"gmake.exe
2755 On Windows \texttt{gmake.exe} supplied with CCS is used instead of
2759 \section{Commands description}
2761 This section contains the description of the available commands. The
2762 same description is also available in the program itself via the
2763 \texttt{help} command.
2765 % Pandoc generates \tightlist in its output. Since we don't use pandoc
2766 % template, we have put its definition here.
2767 \providecommand{\tightlist}{%
2768 \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
2770 \input{rpp-test-sw-cmds.tex}
2776 \textit{Analog to Digital Converter.} \newline{}
2777 Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
2778 digital number that represents the quantity's amplitude.
2781 \textit{Analog Input.} \newline{}
2782 Mnemonic to refer to or something related to the analog input (ADC) hardware module.
2785 \textit{Analog Output.} \newline{}
2786 Mnemonic to refer to or something related to the analog output (DAC) hardware module.
2788 \item[API] \textit{Application Programming Interface}
2791 \textit{Controller Area Network.} \newline{}
2792 The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
2793 communicate with each other within a vehicle without a host computer.
2794 In this project it is also used as mnemonic to refer to or something related to the CAN
2797 \item[CCS] \textit{Code Composer Studio} \\
2798 Eclipse-based IDE provided by Texas Instruments.
2801 \textit{Code Generation Tools.} \newline{}
2802 Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
2803 assemble, archive, among others. In this project is normally used as synonym for
2804 ``Texas Instruments ARM compiler and linker."
2807 \textit{Digital to Analog Converter.} \newline{}
2808 Hardware circuitry that converts a digital (usually binary) code to an analog signal
2809 (current, voltage, or electric charge).
2812 \textit{Digital Input.} \newline{}
2813 Mnemonic to refer to or something related to the digital input hardware module.
2816 \textit{Engine Control Unit.} \newline{}
2817 A type of electronic control unit that controls a series of actuators on an internal combustion
2818 engine to ensure the optimum running.
2821 \textit{Ethernet.} \newline{}
2822 Mnemonic to refer to or something related to the Ethernet hardware module.
2825 \textit{FlexRay.} \newline{}
2826 FlexRay is an automotive network communications protocol developed to govern on-board automotive
2828 In this project it is also used as mnemonic to refer to or something related to the FlexRay
2832 \textit{General Purpose Input/Output.} \newline{}
2833 Generic pin on a chip whose behavior (including whether it is an input or output pin) can be
2834 controlled (programmed) by the user at run time.
2837 \textit{H-Bridge.} \newline{}
2838 Mnemonic to refer to or something related to the H-Bridge hardware module. A H-Bridge is
2839 an electronic circuit that enables a voltage to be applied across a load in either direction.
2842 \textit{High-Power Output.} \newline{}
2843 Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
2844 output hardware module.
2847 \textit{Integrated Development Environment.} \newline{}
2848 An IDE is a Software application that provides comprehensive facilities to computer programmers
2849 for software development.
2852 \textit{Legacy Code Tool.} \newline{}
2853 Matlab tool that allows to generate source code for S-Functions given the descriptor of a C
2857 \textit{Model-Based Design.} \newline{}
2858 Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
2859 with designing complex control, signal processing and communication systems. \cite{modelbasedwiki2013}
2862 \textit{Matlab Executable.} \newline{}
2863 Type of binary executable that can be called within Matlab. In this document the common term
2864 used is `C MEX S-Function", which means Matlab executable written in C that implements a system
2868 \textit{Pulse-width modulation.} \newline{}
2869 Technique for getting analog results with digital means. Digital control is used to create a
2870 square wave, a signal switched between on and off. This on-off pattern can simulate voltages
2871 in between full on and off by changing the portion of the time the signal spends on versus
2872 the time that the signal spends off. The duration of ``on time" is called the pulse width or
2873 \textit{duty cycle}.
2875 \item[RPP] \textit{Rapid Prototyping Platform.} \newline{} Name of the
2876 developed platform, that includes both hardware and software.
2879 \textit{Serial Communication Interface.} \newline{}
2880 Serial Interface for communication through hardware's UART using communication standard RS-232.
2881 In this project it is also used as mnemonic to refer to or something related to the Serial
2882 Communication Interface hardware module.
2885 \textit{SD-Card.} \newline{}
2886 Mnemonic to refer to or something related to the SD-Card hardware module.
2889 \textit{SD-RAM.} \newline{}
2890 Mnemonic to refer to or something related to the SD-RAM hardware module for logging.
2893 \textit{Target Language Compiler.} \newline{}
2894 Technology and language used to generate code in Matlab/Simulink.
2897 \textit{Universal Asynchronous Receiver/Transmitter.} \newline{}
2898 Hardware circuitry that translates data between parallel and serial forms.
2905 % LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests
2906 % LocalWords: MCU UART microcontrollers DAC CCS simulink SPI GPIO
2907 % LocalWords: IOs HDK TMDSRM