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}
12 \addbibresource{rpp_simulink.bib}
15 \usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
16 \usepackage{float} % To fix images position
18 % Prettify code documentation
20 \definecolor{gray97}{gray}{.97}
21 \definecolor{gray75}{gray}{.75}
22 \definecolor{gray45}{gray}{.45}
27 framexbottommargin=3pt,
28 framexleftmargin=0.4cm,
31 backgroundcolor=\color{gray97},
32 rulesepcolor=\color{black},
34 stringstyle=\ttfamily,
35 showstringspaces = false,
36 basicstyle=\small\ttfamily,
37 commentstyle=\color{gray45},
38 keywordstyle=\bfseries,
43 numberfirstline = false,
52 \linespread{1.15} % Lines spacing
53 \setlength{\plitemsep}{0.5\baselineskip} % List items spacing
54 \definecolor{deepblue}{RGB}{0,0,61}
55 \definecolor{deepgreen}{RGB}{0,80,0}
56 \hypersetup{linkcolor=deepblue,citecolor=deepgreen,}
58 % Table of content depth
59 \setcounter{tocdepth}{2}
63 \usepackage{pdflscape}
66 \usepackage{changepage}
70 % \renewcommand{\familydefault}{\sfdefault}
78 \newcommand{\repo}{$\langle$repo$\rangle$}
79 \newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
80 \newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
85 \newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
90 % Upper part of the page
93 \includegraphics[width=0.35\textwidth]{images/cvut.pdf}\\[1cm]
94 \textsc{\LARGE Czech Technical University in Prague}\\[1.5cm]
100 {\huge \bfseries Simulink code generation target for Texas~Instruments
108 Carlos \textsc{Jenkins}\\
109 Michal \textsc{Horn}\\
110 Michal \textsc{Sojka}\\[\baselineskip]
131 \fancypagestyle{plain}{%
132 \fancyhf{} % clear all header and footer fields
133 \renewcommand{\footrulewidth}{0.4pt}
134 \renewcommand{\headrulewidth}{0pt}
135 \fancyfoot[L]{Version \input{version.tex}}
137 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
139 \renewcommand{\headrulewidth}{0.4pt}
140 \renewcommand{\footrulewidth}{0.4pt}
142 \fancyhead[R]{\includegraphics[width=1cm]{images/cvut.pdf}}
144 \fancyhead[L]{\nouppercase \leftmark}
145 \fancyfoot[L]{Version \input{version.tex}}
147 \fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
150 %\addtolength{\parskip}{\baselineskip} % Paragraph spacing
152 \chapter{Introduction}
153 \label{chap-introduction}
155 This text documents software part of Rapid Prototyping Platform (RPP)
156 project for Texas Instruments RM48 safety microcontroller. The
157 software consists of code generation target for Simulink Embedded
158 Coder, a low-level run-time C library and a tool for interactive
159 testing of hardware and software functionality.
161 Originally, the RPP project was created for TMS570 microcontroller and
162 the port to RM48 was derived from it under a contract with Eaton
165 The document contains step-by-step instructions for installation of
166 development tools, information about Simulink Coder configuration,
167 describes how to create new models as well as how to download the
168 resulting firmware to the hardware. It can also be used as a reference
169 for the testing tool, Matlab Simulink blocks and RPP Matlab Simulink
170 Code generator. Additionally, an overall description of the used
171 hardware platform and the architecture of included software is
175 \label{sec-background}
177 The Rapid Prototyping Platform is an control unit based on TMDSRM48HDK
178 development kit from Texas Instruments. Cental to the kit is the
179 RM48L952 MCU -- an ARM Cortex R4 based microcontroller developed by
180 Texas Instruments. This MCU contains several protective mechanisms
181 (two cores in lockstep, error correction mechanisms for SRAM and Flash
182 memory, voltage monitoring, etc.) to fulfill the requirements for
183 safety critical applications.
184 See~\cite{rm48xtechnicalreferencemanual2013} for details.
186 In order to develop non-trivial applications for the RPP, an operating
187 system is necessary. The RPP is based on FreeRTOS -- a simple
188 opensource real-time operating system kernel. The FreeRTOS provides an
189 API for creating and managing and scheduling multiple tasks, memory
190 manager, semaphores, queues, mutexes, timers and a few of other
191 features which can be used in the applications.
192 See~\cite{usingthefreertos2009} for more details.
194 Even with the operating system it is quite hard and non-intuitive to
195 manipulate the hardware directly. That is the point when abstraction
196 comes into the play. The RPP software is made of several layers
197 implementing, from the bottom to the top, low-level device drivers,
198 hardware abstraction for common functionality on different hardware
199 and an API which is easy to use in applications. The operating system
200 and the basic software layers, can be compiled as a library and easily
201 used in any project. More details about the library can be found in
202 Chapter~\ref{chap-c-support-library} and in~\cite{michalhorn2013}.
204 Because human beings make mistakes and in safety critical applications
205 any mistake can cause damage, loos of money or in the worst case even
206 death of other people, the area for making mistakes has to be as small
207 as possible. An approach called Model-based development
208 \cite{modelbasedwiki2013} has been introduced to reduce the
209 probability of making mistakes. In model-based development, the
210 applications are designed at higher level from models and the
211 functionality of the models can be simulated in a computer before the
212 final application/hardware is finished. This allows to discover
213 potential errors earlier in the development process.
215 One commonly used tool-chain for model-based development is
216 Matlab/Simulink. In Simulink the application is developed as a model
217 made of interconnected blocks. Every block implements some
218 functionality. For example one block reads a value from an
219 analog-to-digital converter and provides the value as an input to
220 another block. This block can implement some clever algorithm and its
221 output is passed to another block, which sends the computed value as a
222 message over CAN bus to some other MCU. Such a model can be simulated
223 and tested even before the real hardware is available by replacinf the
224 input and output blocks with simulated ones. Once the hardware is
225 ready, C code is automatically generated from the model by a Simulink
226 Coder. The code is then compiled by the MCU compatible compiler and
227 downloaded to the MCU Flash memory on the device. Because every block
228 and code generated from the block has to pass a series of tests during
229 their development, the area for making mistakes during the application
230 development has been significantly reduced and developers can focus on
231 the application instead of the hardware and control software
232 implementation. More information about code generation can be found in
233 Chapter \ref{chap-simulink-coder-target}. For information about Matlab
234 Simulink, Embedded Coder and Simulink Coder, refer to
235 \cite{embeddedcoderreference2013, ebmeddedcoderusersguide2013,
236 simulinkcoderreference2013, targetlanguagecompiler2013,
237 simulinkcoderusersguide2013, simulinkdevelopingsfunctions2013}.
239 \section{Hardware description}
240 \label{sec-hardware-description}
242 This section provides a brief description of the Texas Instrument
243 TMDSRM48HDK development kit. For a more detailed information refer to
244 \cite{rm48hdkusersguide2013}. The kit is depicted in
245 Figure~\ref{fig-board_photo}.
247 \begin{figure}\begin{center}
249 \includegraphics[width=300px]{images/board.png}
250 \caption{The TMDSRM48HDK kit \cite[p. 8]{rm48hdkusersguide2013}}
251 \label{fig-board_photo}
252 \end{center}\end{figure}
254 Only a subset of peripherals available on the kit is currently
255 supported by the RPP software. A block diagram in
256 Figure~\ref{fig-blocks} ilustrates the supported peripherals and their
257 connection to the MCU, expansion connectors and other components on
258 the development kit. For pinout description of the implemented
259 peripherals refer the RM48HDK User's Guide
260 \cite{rm48hdkusersguide2013}. The main features of supported
261 peripherals are provided in the following subsections.
263 \begin{figure}\begin{center}
265 \includegraphics[width=400px]{images/blocks.png}
266 \caption{Block diagram of supported peripherals}
268 \end{center}\end{figure}
270 \subsection{Digital Inputs and Outputs (DIN and DOUT)}
271 \label{par-digital-inputs-outputs}
273 \item 46 pins available on Expansion connector J11.
274 \item 8 pins available on GIOA
275 \item 8 pins available on GIOB
276 \item 30 pins available on NHET1. Pins NHET1 6 and NHET1 13 are disabled.
277 \item All the pins are configurable as inputs and outputs with different modes:
279 \item Push/Pull or Open Drain for Output configuration.
280 \item Pull up, Pull down or tri-stated for Input configuration.
282 \item Some of the pins are connected to LEDs or to a button. See
283 Figure~\ref{fig-blocks} or refer to~\cite{rm48hdkusersguide2013}.
286 \subsection{Analog Input (ADC)}
287 \label{par-analog-input}
288 \vbox{% Keep this on the same page
290 \item 16 channels available on the Expansion connector J9.
291 \item Range for 0 -- 5 Volts.
292 \item 12 bits resolution.
295 \subsection{CAN bus (CAN)}
298 \item Up to three CAN ports
300 \item 2 ports equipped with physical layer CAN transciever
301 connected to J2 and J3 connectors.
302 \item All 3 ports available as link-level interface on the
303 Expansion connector J11.
306 \item Recovery from errors.
307 \item Detection of network errors.
310 \subsection{Serial Communication Interface (SCI)}
313 \item 1 port available on connector J7.
314 \item Configurable baud rate. Tested with 9600 and 115200 bps.
315 \item RS232 compatible.
318 \section{Software architecture}
319 \label{sec-software-architecture}
321 The core of the RPP software is the so called RPP Library. This
322 library is conceptualy structured into 5 layers, depicted in
323 Figure~\ref{fig-layers}. The architecture design was driven by the
324 following guidelines:
327 \item Top-down dependency only. No lower layer depends on anything from
329 % \item 1-1 layer dependency only. The top layer depends
330 % exclusively on the bottom layer, not on any lower level layer (except for a
331 % couple of exceptions).
332 \item Each layer should provide a unified layer interface
333 (\texttt{rpp.h}, \texttt{drv.h}, \texttt {hal.h}, \texttt{sys.h} and
334 \texttt{os.h}), so that top layers depends on the layer interface
335 and not on individual elements from that layer.
341 \includegraphics[width=250px]{images/layers.pdf}
342 \caption{The RPP library layers.}
347 As a consequence of this division the source code files and interface files are
348 placed in private directories like \texttt{drv/din.h}. With this organization
349 user applications only needs to include the top layer interface files (for
350 example \texttt{rpp/rpp\_can.h}) to be able to use the selected library API.
352 The rest of the section provides basic description of each layer.
354 \subsection{Operating System layer}
355 \label{sec-operating-system-layer}
356 This is an interchangeable operating system layer, containing the
357 FreeRTOS source files. The system can be easily replaced by another
358 version. For example it is possible to compile the RPP library for
359 Linux (using POSIX version of the FreeRTOS), which can be desirable
360 for some testing. The source files can be found in the
361 \texttt{$\langle$rpp\_lib$\rangle$/os} folder.
363 The following FreeRTOS versions are distributed:
365 \item[6.0.4\_posix] POSIX version, usable for compilation of the library
367 \item[7.0.2] Preferred version of the FreeRTOS, distributed by
368 Texas Instruments. This version has been tested and is used in the current
369 version of the library.
370 \item[7.4.0] Newest version distributed by the Texas Instruments.
371 \item[7.4.2] Newer version available from FreeRTOS pages. Slightly
372 modified to run on RM48 MCU.
376 Both 7.4.x version were tested and work, but the testing was not so
377 extensive as with the used 7.0.2 version.
379 \subsection{System Layer}
380 \label{sec-system-layer}
381 This layer contains system files with data types definitions, clock definitions,
382 interrupts mapping, MCU start-up sequence, MCU selftests, and other low level
383 code for controlling some of the MCU peripherals. The source files can be found
384 in \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/sys}, the header files can
385 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/sys}
388 Large part of this layer was generated by the HalCoGen tool (see
389 Section~\ref{sec-halcogen}).
391 \subsection{HAL abstraction layer}
392 \label{sec-hal-abstraction-layer}
393 Hardware Abstraction Layer (HAL) provides an abstraction over the real
394 hardware. For example imagine an IO port with 8 pins. First four pins
395 are connected directly to the GPIO pins on the MCU, another four pins
396 are connected to an external integrated circuit, communicating with
397 the MCU via SPI. This layer allows to control the IO pins
398 independently of how that are connected to the MCU, providing a single
401 Note that this functionality is not needed in the current version of
402 for TMDSRM48HDK, because all IOs are controlled directly by GPIO pins.
404 As a result, the higher layers do not have to know anything about the
405 wiring of the peripherals, they can just call read, write or configure
406 function with a pin name as a parameter and the HAL handles all the
409 The source files can be found in
410 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/hal} and the header files can
411 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/hal} folder.
413 \subsection{Drivers layer}
414 \label{sec-drivers-layer}
415 The Drivers layer contains code for controlling the RPP peripherals.
416 Typically, it contains code implementing IRQ handling, software
417 queues, management threads, etc. The layer benefits from the lower
418 layers thus it is not too low level, but still there are some
419 peripherals like ADC, which need some special procedure for
420 initialization and running, that would not be very intuitive for the
423 The source files can be found in
424 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
425 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/drv} folder.
427 \subsection{RPP Layer}
428 \label{sec-rpp-layer}
429 The RPP Layer is the highest layer of the library. It provides an easy
430 to use set of functions for every peripheral and requires only basic
431 knowledge about them. For example, to use the ADC, the user can just
432 call \texttt{rpp\_adc\_init()} function and it calls a sequence of
433 Driver layer functions to initialize the hardware and software.
435 The source files can be found in
436 \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/rpp} and the header files can
437 be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/rpp}.
439 \section{Document structure}
440 \label{sec-document-structure}
441 The structure of this document is as follows:
442 Chapter~\ref{chap-getting-started} gets you started using the RPP
443 software. Chapter~\ref{chap-c-support-library} describes the RPP
444 library. Chapter~\ref{chap-simulink-coder-target} covers the Simulink
445 code generation target and finally
446 Chapter~\ref{chap-rpp-test-software} documents a tool for interactive
447 testing of the RPP functionality.
449 \chapter{Getting started}
450 \label{chap-getting-started}
452 \section{Software requirements}
453 \label{sec-software-requirements}
454 The RPP software stack can be used on Windows and Linux platforms. The
455 following subsections mention the recommended versions of the required
456 software tools/packages.
458 \subsection{Linux environment}
459 \label{sec-linux-environment}
461 \item Debian based 64b Linux distribution (Debian 7.0 or Ubuntu 14.4 for
463 \item Kernel version 3.11.0-12.
464 \item GCC version 4.8.1
465 \item GtkTerm 0.99.7-rc1
466 \item TI Code Composer Studio 5.5.0.00077
467 \item Matlab 2013b 64b with Embedded Coder
468 \item HalCoGen 4.00 (optionally)
469 \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
470 \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
471 \item Git 1.7.10.4 (optionally)
474 \subsection{Windows environment}
475 \label{sec-windows-environment}
477 \item Windows 7 Enterprise 64b Service Pack 1.
478 \item Microsoft Windows SDK v7.1
479 \item Bray Terminal v1.9b
480 \item TI Code Composer Studio 5.5.0.00077
481 \item Matlab 2013b 64b with Embedded Coder
482 \item HalCoGen 4.00 (optionally)
483 \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
484 \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
485 \item Git 1.9.4.msysgit.2 (optionally)
488 \section{Software tools}
489 \label{sec-software-and-tools}
491 This section covers tool which are needed or recommended for work with
494 \subsection{TI Code Composer Studio}
496 Code Composer Studio (CCS) is the official Integrated Development Environment
497 (IDE) for developing applications for Texas Instruments embedded processors. CCS
498 is multiplatform software based on
499 Eclipse open source IDE.
501 CCS includes Texas Instruments Code Generation Tools (CGT)
502 \cite{armoptimizingccppcompiler2012, armassemblylanguagetools2012}
503 (compiler, linker, etc). Simulink code generation target requires the
504 CGT to be available in the system, and thus, even if no library
505 development will be done or the IDE is not going to be used CCS is
508 You can find documentation for CGT compiler in \cite{armoptimizingccppcompiler2012} and
509 for CGT archiver in \cite{armassemblylanguagetools2012}.
511 \subsubsection{Installation on Linux}
512 \label{sec-installation-on-linux}
513 Download CCS for Linux from:\\
514 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
516 Once downloaded, add executable permission to the installation file
517 and launch the installation by executing it. Installation must be done
518 by the root user in order to install a driver set.
520 \lstset{language=bash}
522 chmod +x ccs_setup_5.5.0.00077.bin
523 sudo ./ccs_setup_5.5.0.00077.bin
526 After installation the application can be executed with:
528 \lstset{language=bash}
530 cd <ccs>/ccsv5/eclipse/
534 The first launch on 64bits systems might fail. This can happen because CCS5 is
535 a 32 bit application and thus requires 32 bit libraries. They can be
538 \lstset{language=bash}
540 sudo apt-get install libgtk2.0-0:i386 libxtst6:i386
543 If the application crashes with a segmentation fault edit file:
545 \lstset{language=bash}
547 nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
550 And change key \texttt{org.eclipse.ui/showIntro} to \texttt{false}.
552 \subsubsection{Installation on Windows}
553 \label{sec-installation-on-windows}
554 Installation for Windows is more straightforward than the installation
555 procedure for Linux. Download CCS for Windows from:\\
556 \url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
558 Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.
560 \subsubsection{First launch}
561 \label{sec-first-launch}
562 If no other licence is available, choose ``FREE License -- for use
563 with XDS100 JTAG Emulators'' from the licensing options. Code download
564 for the board uses the XDS100 hardware.
566 \subsection{Matlab/Simulink}
567 \label{sec-matlab-simulink}
568 Matlab Simulink is a set of tools, runtime environment and development
569 environment for Model--Based \cite{modelbasedwiki2013} applications development,
570 simulations and generation code for target platforms. Supported Matlab Simulink
571 version is R2013b for 64 bits Linux and Windows. A licence for an Embedded Coder is
572 necessary to be able to generate code from Simulink models, containing RPP blocks.
574 \subsection{HalCoGen}
576 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.
578 The tool is available for Windows at
580 \url{http://www.ti.com/tool/halcogen?keyMatch=halcogen&tisearch=Search-EN}
583 The HalCoGen has been used in early development stage of the RPP
584 project to generate the base code for some of the peripheral. The
585 trend is to not to use the HalCoGen any more, because the generated
586 code is not reliable enough for safety critical applications. Anyway it is
587 sometimes helpful to use it as a reference.
589 The HalCoGen is distributed for Windows only, but can be run on Linux
590 under Wine (tested with Wine version 1.6.2).
592 \subsection{GtkTerm and Bray Terminal}
593 \label{sec-gtkterm-bray-terminal}
594 Most of the interaction with the board is done through a RS-232 serial
595 connection. The terminal software used for communication is called GtkTerm for
596 Linux and Bray terminal for Windows.
598 To install GtkTerm execute:
600 \lstset{language=bash}
602 sudo apt-get install gtkterm
605 The Bray Terminal does not require any installation and the executable file is
607 \url{https://sites.google.com/site/terminalbpp/}
609 \subsection{C Compiler}
610 \label{sec-c-compiler}
611 A C language compiler has to be available on the development system to be able to
612 compile Matlab Simulink blocks S-functions.
614 For Linux a GCC 4.8.1 compiler is recommended and can be installed with a
617 \lstset{language=bash}
619 sudo apt-get install gcc
622 For Windows, the C/C++ compiler is a part of Windows SDK, which is available from\\
623 \url{http://www.microsoft.com/en-us/download/details.aspx?id=8279}
625 \section{Project installation}
626 \label{sec-project-installation}
627 The RPP software is distributed in three packages and a standalone pdf
628 file containing this documentation. Every package is named like
629 \emph{$\langle$package\_name$\rangle$-version.zip}. The three packages
633 \item[rpp-lib] Contains the source code of the RPP library, described
634 in Chapter \ref{chap-c-support-library}. If you want to make any
635 changes in the drivers or RPP API, this library has to be compiled
636 and linked with applications in the other two packages. The library compile
637 procedure can be found in Section \ref{sec-compilation}.
638 \item[rpp-simulink] Contains the source code of Matlab Simulink
639 blocks, demo models and scripts for downloading the generated
640 firmware to the target from Matlab/Simulink. Details can be
641 found in Chapter \ref{chap-simulink-coder-target}.
643 The package also contains the binary of the RPP Library and all its
644 headers and other files necessary for building and downloading the
646 \item[rpp-test-sw] Contains an application for interactive testing and
647 control of the RPP board over the serial interface. Details can be
648 found in Chapter~\ref{chap-rpp-test-software}.
650 The package also contains the binary of the RPP Library and all
651 headers and other files necessary for building and downloading the
655 The following sections describe how to start working with individual
659 \label{sec-rpp-lib-installation}
661 This section describes how to open the rpp-lib project in Code
662 Composer Studio and how to use the resulting static library in an
663 application. This is only necessary if you need to modify the library
667 \item Unzip the \texttt{rpp-lib-version.zip} file.
668 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
669 \item Import the rpp-lib project as described in
670 Section~\ref{sec-openning-of-existing-project}.
671 \item Compile the static library using the procedure from Section
672 \ref{sec-compilation}. The compiled library \texttt{rpp-lib.lib}
673 will appear in the project root directory.
674 \item Either copy the compiled library and the content of the
675 \texttt{rpp/include} directory to the application, where you
676 want to use it or use the library in place, as described in
677 Section~\ref{sec:creating-new-project}.
679 \item In the rpp-simulink application the library is located in
680 the \texttt{rpp/lib} folder.
681 \item In the rpp-test-sw application the library is located in
682 the \texttt{rpp-lib} folder.
686 \subsection{rpp-simulink}
687 \label{sec-rpp-simulink-installation}
688 This section describes how to install the rpp-simulink project, which
689 is needed to try the demo models or to build your own models that use
693 \item Unzip the \texttt{rpp-simulink-version.zip} file.
694 \item Follow the procedure from Section
695 \ref{sec-configuration-simulink-for-rpp} for configuring Matlab
696 Simulink for the RPP project.
697 \item Follow the procedure from Section \ref{sec-crating-new-model}
698 for instructions about creating your own model which will use the
699 RPP Simulink blocks or follow the instructions in
700 Section~\ref{sec-running-model-on-hw} for downloading the firmware to the RPP hardware.
703 \subsection{rpp-test-sw}
704 \label{sec-test-sw-installation}
705 This section describes how to install and run the application that
706 allows you to interactively control the RPP hardware. This can be
707 useful, for example, to test your modifications of the RPP library.
710 \item Unzip the \texttt{rpp-test-sw-version.zip} file.
711 \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
712 \item Follow the procedure for opening the projects in CCS in
713 Section \ref{sec-openning-of-existing-project} and open both
714 \texttt{rpp-lib} and \texttt{rpp-test-sw} projects.
715 \item Right click on the \texttt{rpp-test-sw} project in the
716 \textsc{Project Explorer} and select \textsc{Build Project}.
717 \item Follow the instructions in
718 Section~\ref{sec-running-software-on-hw} to download, debug and
719 run the software on the target hardware. If CCS asks you whether
720 to proceed with the detected errors in \texttt{rpp-lib} project.
721 Ignore them and click the \textsc{Proceed} button to continue.
724 \section{Code Composer Studio usage}
725 \label{sec-code-composerpstudio-usage}
727 \subsection{Opening of existing project}
728 \label{sec-openning-of-existing-project}
729 The procedure for opening a project is similar to opening a project in
730 the standard Eclipse IDE.
733 \item Launch Code Composer Studio
734 \item Select \textsc{File$\rightarrow$Import}
735 \item In the dialog window select \textsc{Code Composer
736 Studio$\rightarrow$Existing CCS Eclipse project} as an import
737 source (see Figure \ref{fig-import-project}).
738 \item In the next dialog window click on \textsc{Browse} button
739 and find the root directory of the project.
740 \item Select the requested project in the \textsc{Discovered
741 project} section so that the result looks like in Figure
742 \ref{fig-select-project}.
743 \item Click the \textsc{Finish} button.
746 \begin{figure}[H]\begin{center}
747 \includegraphics[width=350px]{images/import_project.png}
748 \caption{Import project dialog}
749 \label{fig-import-project}
750 \end{center}\end{figure}
752 \begin{figure}[H]\begin{center}
753 \includegraphics[width=350px]{images/select_project.png}
754 \caption{Select project dialog}
755 \label{fig-select-project}
756 \end{center}\end{figure}
759 \subsection{Creating new project}
760 \label{sec:creating-new-project}
761 Follow these steps to create an application for RM48 MCU compiled with
765 \item Create a new empty CCS project. Select RM48L952 device, XDS100v2
766 connection and set Linker command file to
767 \texttt{rpp-lib/rpp/RM48L952FlashLnk.cmd}.
769 \noindent\includegraphics[scale=0.45]{images/base_1.png}
771 \item In \textsc{Project Explorer}, create normal folders
772 named \texttt{include} and \texttt{src}.
774 \item If you use Git version control system, add \texttt{.gitignore}
775 file with the following content to the root of that project:
784 \item In project \textsc{Properties}, add new variable of type
785 \texttt{Directory} named \texttt{RPP\_LIB\_ROOT} and set it to the
789 \noindent\includegraphics[scale=.45]{images/base_2.png}
791 \item Configure the compiler \#include search path to contain
792 project's \texttt{include} directory, \penalty-100
793 \texttt{\$\{RPP\_LIB\_ROOT\}/os/7.0.2\_rm48/include} and
794 \texttt{\$\{RPP\_LIB\_ROOT\}/rpp/include}, in that order.
796 \includegraphics[scale=.43]{images/base_5.png}
799 \item Add \texttt{\$\{RPP\_LIB\_ROOT\}/rpp-lib.lib} to the list of
800 linked libraries before the runtime support library
801 (\texttt{rtsv7R4\_T\_le\_v3D16\_eabi.lib}).
803 \noindent\includegraphics[scale=.45]{images/base_3.png}
805 \item Configure the compiler to allow GCC extensions.
807 \noindent\includegraphics[scale=.45]{images/base_6.png}
810 \item Create \texttt{main.c} file with the following content:
811 \begin{lstlisting}[language=C]
817 rpp_sci_printf("Hello world\n");
818 vTaskStartScheduler();
819 return 0; /* not reached */
822 void vApplicationMallocFailedHook()
824 void vApplicationStackOverflowHook()
828 \item Compile the application by e.g. \textsc{Project $\rightarrow$
830 \item Select \textsc{Run} $\rightarrow$ \textsc{Debug}. The
831 application will be downloaded to the processor and run. A
832 breakpoint is automatically placed at \texttt{main()} entry. To
833 continue executing the application select \textsc{Run} $\rightarrow$
835 \item If your application fails to run with a \texttt{\_dabort} interrupt, check
836 that the linker script selected in step 1 is not excluded from the build.
837 You can do this by right clicking on the file \texttt{RM48L952FlashLnk.cmd}
838 in the \textsc{Project Explorer} and unchecking the \textsc{Exclude from build}
839 item. The Code Composer Studio sometimes automaticaly excludes this file from
840 the build process when creating the new project.
842 % \item If not already created for another project, create new target
843 % configuration. Select \textsc{Windows $\rightarrow$ Show View
844 % $\rightarrow$ Target Configurations}. In the shown window, click
845 % on \textsc{New Target Configuration} icon and configure XDS100v2
846 % connection and RM48L952 device as shown below. Click \textsc{Save},
847 % connect your board and click \textsc{Test Connection}.
850 % \includegraphics[width=\linewidth]{images/target_conf.png}
853 \item Optionally, you can change debugger configuration by selecting
854 \textsc{Run $\rightarrow$ Debug Configurations}. In the
855 \textsc{Target} tab, you can configure not to break at \texttt{main}
856 or not to erase the whole flash, but only necessary sectors (see the
859 \includegraphics[width=\linewidth]{images/debug_conf_flash.png}
864 \subsubsection{Steps to configure new POSIX application:}
865 Such an application can be used to test certain FreeRTOS features on
866 Linux and can be compiled with a native GCC compiler.
869 \item Create a new managed C project that uses Linux GCC toolchain.
870 \item Create a source folder \texttt{src}. Link all files from original
871 CCS application to this folder.
872 \item Create a normal folder \texttt{include}. Create a folder
873 \texttt{rpp} inside of it.
874 \item Add common \texttt{.gitignore} to the root of that project:
881 \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
882 repository branch root.\newline{}
883 \noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
884 \item Configure compiler to include local includes, CCS application
885 includes, OS includes for POSIX and RPP includes, in that order.\newline{}
886 \noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
888 \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
889 \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
890 \noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
893 \subsubsection{Content of the application}
896 \item Include RPP library header file.
897 \lstset{language=c++}
902 If you want to reduce the size of the final application, you can
903 include only the headers of the needed modules. In that case, you
904 need to include two additional headers: \texttt{base.h} and, in case
905 when SCI is used for printing, \texttt{rpp/sci.h}.
907 #include "rpp/hbr.h" /* We want to use H-bridge */
908 #include <base.h> /* This is the necessary base header file of the rpp library. */
909 #include "rpp/sci.h" /* This is needed, because we use rpp_sci_printf in following examples. */
913 \item Create one or as many FreeRTOS task function definitions as
914 required. Those tasks can use functions from the RPP library. Beware
915 that currently not all RPP functions are
916 reentrant\footnote{Determining which functions are not reentrant and
917 marking them as such (or making them reentrant) is planned as
918 future work.}. \lstset{language=c++}
920 void my_task(void* p)
922 static const portTickType freq_ticks = 1000 / portTICK_RATE_MS;
923 portTickType last_wake_time = xTaskGetTickCount();
925 /* Wait until next step */
926 vTaskDelayUntil(&last_wake_time, freq_ticks);
927 rpp_sci_printf((const char*)"Hello RPP.\r\n");
932 \item Create the main function that will:
934 \item Initialize the RPP board. If you have included only selected
935 modules in step 1, initialize only those modules by calling their init
937 example \texttt{rpp\_hbr\_init\(\)}.
938 \item Spawn the tasks the application requires. Refer to FreeRTOS API
940 \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details
942 \item Handle error when the FreeRTOS scheduler cannot be started.
944 \lstset{language=c++}
948 /* In case whole library is included: */
949 /* Initialize RPP board */
951 /* In case only selected modules are included: */
954 /* Initialize sci for printf */
956 /* Enable interrups */
960 if (xTaskCreate(my_task, (const signed char*)"my_task",
961 512, NULL, 0, NULL) != pdPASS) {
963 rpp_sci_printf((const char*)
964 "ERROR: Cannot spawn control task.\r\n"
970 /* Start the FreeRTOS Scheduler */
971 vTaskStartScheduler();
973 /* Catch scheduler start error */
975 rpp_sci_printf((const char*)
976 "ERROR: Problem allocating memory for idle task.\r\n"
984 \item Create hook functions for FreeRTOS:
986 \item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation
988 \item \texttt{vApplicationStackOverflowHook()} allows to catch stack
991 \lstset{language=c++}
993 #if configUSE_MALLOC_FAILED_HOOK == 1
995 * FreeRTOS malloc() failed hook.
997 void vApplicationMallocFailedHook(void) {
999 rpp_sci_printf((const char*)
1000 "ERROR: manual memory allocation failed.\r\n"
1007 #if configCHECK_FOR_STACK_OVERFLOW > 0
1009 * FreeRTOS stack overflow hook.
1011 void vApplicationStackOverflowHook(xTaskHandle xTask,
1012 signed portCHAR *pcTaskName) {
1014 rpp_sci_printf((const char*)
1015 "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName
1027 \subsection{Downloading and running the software}
1028 \label{sec-running-software-on-hw}
1029 \subsubsection{Code Composer Studio Project}
1030 \label{sec-ccs-run-project}
1031 When the application is distributed as a CCS project, you have to open the
1032 project in the CCS as described in the Section
1033 \ref{sec-openning-of-existing-project}. Once the project is opened and built, it
1034 can be easily downloaded to the target hardware with the following procedure:
1037 \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG
1039 \item Connect a USB cable to the XDS100v2 USB emulator and the
1040 development computer.
1041 \item Plug in the power supply.
1042 \item In the Code Composer Studio click on the
1043 \textsc{Run$\rightarrow$Debug}. The project will be optionally built and
1044 the download process will start. The Code Composer Studio will switch into the debug
1045 perspective, when the download is finished.
1046 \item Run the program by clicking on the \textsc{Run} button, with the
1050 \subsubsection{Binary File}
1051 \label{sec-binary-file}
1052 If the application is distributed as a binary file, without source code and CCS
1053 project files, you can download and run just the binary file by creating a new
1054 empty CCS project and configuring the debug session according to the following
1058 \item In Code Composer Studio click on
1059 \textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
1060 \item In the dialog window, type in a project name, for example
1061 myBinaryLoad, Select \textsc{Device
1062 variant} (ARM, Cortex R, RM48L952, Texas Instruments XDS100v2 USB Emulator)
1063 and select project template to \textsc{Empty Project}. The filled dialog should
1064 look like in Figure~\ref{fig-new-empty-project}
1065 \item Click on the \textsc{Finish} button and a new empty project will
1067 \item In the \textsc{Project Explorer} right-click on the project and
1068 select \textsc{Debug as$\rightarrow$Debug configurations}.
1069 \item Click \textsc{New launch configuration} button
1070 \item Rename the New\_configuration to, for example, myConfiguration.
1071 \item Select configuration target file by clicking the \textsc{File
1072 System} button, finding and selecting the \texttt{RM48L952.ccxml} file. The result
1073 should look like in Figure~\ref{fig-debug-conf-main-diag}.
1074 \item In the \textsc{program} pane select the binary file you want to
1075 download to the board. Click on the \textsc{File System} button,
1076 find and select the binary file. Try, for example
1077 \texttt{rpp-test-sw.out}. The result should look like in
1078 Figure~\ref{fig-debug-conf-program-diag}.
1079 \item You may also tune the target configuration like in the Section
1080 \ref{sec-target-configuration}.
1081 \item Finish the configuration by clicking on the \textsc{Apply}
1082 button and download the code by clicking on the \textsc{Debug}
1083 button. You can later invoke the download also from the
1084 \textsc{Run$\rightarrow$Debug} CCS menu. It is not necessary to
1085 create more Debug configurations and CCS empty projects as you can
1086 easily change the binary file in the Debug configuration to load a
1087 different binary file.
1090 \begin{figure}[H]\begin{center}
1091 \includegraphics[scale=.45]{images/new_empty_project.png}
1092 \caption{New empty project dialog}
1093 \label{fig-new-empty-project}
1094 \end{center}\end{figure}
1096 \begin{figure}[H]\begin{center}
1097 \includegraphics[scale=.45]{images/debug_configuration_main.png}
1098 \caption{Debug Configuration Main dialog}
1099 \label{fig-debug-conf-main-diag}
1100 \end{center}\end{figure}
1102 \subsection{Target configuration}
1103 \label{sec-target-configuration}
1104 Default target configuration erases the whole Flash memory, before
1105 downloading the code. This takes long time and in most cases it is
1106 not necessary. You may disable this feature by the following procedure:
1108 \item Right click on the project name in the \textsc{Project Browser}
1109 \item Select \textsc{Debug as$\rightarrow$Debug Configurations}
1110 \item In the dialog window select \textsc{Target} pane.
1111 \item In the \textsc{Flash Settings}, \textsc{Erase Options} select
1112 \textsc{Necessary sectors only}.
1113 \item Save the configuration by clicking on the \textsc{Apply} button
1114 and close the dialog.
1117 \begin{figure}[H]\begin{center}
1118 \includegraphics[scale=.45]{images/debug_configuration_program.png}
1119 \caption{Configuration Program dialog}
1120 \label{fig-debug-conf-program-diag}
1121 \end{center}\end{figure}
1123 \section{Matlab Simulink usage}
1124 \label{sec-matlab-simulink-usage}
1125 This section describes the basic tasks for working with the RPP code
1126 generation target for Simulink. For a more detailed description of the
1127 code generation target refer to
1128 Chapter~\ref{chap-simulink-coder-target}.
1130 \subsection{Configuring Simulink for RPP}
1131 \label{sec-configuration-simulink-for-rpp}
1132 Before any work or experiments with the RPP blocks and models, the RPP
1133 target has to be configured to be able to find the ARM cross-compiler,
1134 native C compiler and some other necessary files. Also the S-Functions
1135 of the blocks have to be compiled by the mex tool.
1137 \item Download and install Code Composer Studio CCS (see
1138 Section~\ref{sec-ti-ccs}).
1139 \item Install a C compiler. On Windows follow Section~\ref{sec-c-compiler}.
1140 \item On Windows you have to tell the \texttt{mex} which C compiler to
1141 use. In the Matlab command window run the \texttt{mex -setup}
1142 command and select the native C compiler.
1144 \begin{lstlisting}[basicstyle=\tt\footnotesize]
1147 Welcome to mex -setup. This utility will help you set up
1148 a default compiler. For a list of supported compilers, see
1149 http://www.mathworks.com/support/compilers/R2013b/win64.html
1151 Please choose your compiler for building MEX-files:
1153 Would you like mex to locate installed compilers [y]/n? y
1156 [1] Microsoft Software Development Kit (SDK) 7.1 in c:\Program Files (x86)\Microsoft Visual Studio 10.0
1162 Please verify your choices:
1164 Compiler: Microsoft Software Development Kit (SDK) 7.1
1165 Location: c:\Program Files (x86)\Microsoft Visual Studio 10.0
1167 Are these correct [y]/n? y
1169 ***************************************************************************
1170 Warning: MEX-files generated using Microsoft Windows Software Development
1171 Kit (SDK) require that Microsoft Visual Studio 2010 run-time
1172 libraries be available on the computer they are run on.
1173 If you plan to redistribute your MEX-files to other MATLAB
1174 users, be sure that they have the run-time libraries.
1175 ***************************************************************************
1178 Trying to update options file: C:\Users\Michal\AppData\Roaming\MathWorks\MATLAB\R2013b\mexopts.bat
1179 From template: C:\PROGRA~1\MATLAB\R2013b\bin\win64\mexopts\mssdk71opts.bat
1183 **************************************************************************
1184 Warning: The MATLAB C and Fortran API has changed to support MATLAB
1185 variables with more than 2^32-1 elements. In the near future
1186 you will be required to update your code to utilize the new
1187 API. You can find more information about this at:
1188 http://www.mathworks.com/help/matlab/matlab_external/upgrading-mex-files-to-use-64-bit-api.html
1189 Building with the -largeArrayDims option enables the new API.
1190 **************************************************************************
1193 \item Configure the RPP code generation target:
1195 Open Matlab and in the command window run:
1197 \lstset{language=Matlab}
1199 cd <rpp-simulink>/rpp/rpp/
1203 This will launch the RPP setup script. This script will ask the user to provide
1204 the path to the CCS compiler root directory (the directory where \texttt{armcl}
1205 binary is located), normally:
1208 <ccs>/tools/compiler/arm_5.X.X/
1211 Then Matlab path will be updated and block S-Functions will be built.
1213 \item Create new model or load a demo:
1215 Demos are located in \texttt{\repo/rpp/demos} or you can start a new
1216 model and configure target to RPP. For new models see Section
1217 \ref{sec-crating-new-model} below.
1221 \subsection{Working with demo models}
1222 \label{sec-openning-demo-models}
1223 The demo models are available from the directory
1224 \texttt{\repo/rpp/demos}. To access the demo models for reference or
1225 for downloading to the RPP board open them in Matlab. Use either the
1226 GUI or the following commands:
1228 \begin{lstlisting}[language=Matlab]
1229 cd <rpp-simulink>/rpp/demos
1230 open cantransmit.slx
1233 The same procedure can be used to open any other models. To build the
1234 demo select \textsc{Code$\rightarrow$C/C++ Code $\rightarrow$Build
1235 Model}. This will generate the C code and build the binary firmware
1236 for the RPP board. To run the model on the target hardware see
1237 Section~\ref{sec-running-model-on-hw}.
1239 \subsection{Creating new model}
1240 \label{sec-crating-new-model}
1242 \item Create a model by clicking \textsc{New$\rightarrow$Simulink Model}.
1243 \item Open the configuration dialog by clicking \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
1244 \item The new Simulink model needs to be configured in the following way:
1246 \item Solver (Figure \ref{fig-solver}):
1248 \item Solver type: \emph{Fixed-step}
1249 \item Solver: \emph{discrete}
1250 \item Fixed-step size: \emph{Sampling period in seconds. Minimum
1252 \item Tasking mode: \textit{SingleTasking}.
1255 \includegraphics[scale=.45]{images/simulink_solver.png}
1256 \caption{Solver settings}
1260 % \item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
1261 % \begin{compactitem}
1262 % \item Disable warning ``Source block specifies -1 sampling
1263 % time''. It's ok for the source blocks to run once per tick.
1266 % \includegraphics[scale=.45]{images/simulink_diagnostics.png}
1267 % \caption{Sample Time settings}
1268 % \label{fig-sample-time-settings}
1271 \item Code generation (Figure~\ref{fig-code-gen-settings}):
1273 \item Set ``System target file'' to \texttt{rpp.tlc}.
1276 \includegraphics[scale=.45]{images/simulink_code.png}
1277 \caption{Code Generation settings}
1278 \label{fig-code-gen-settings}
1282 \item Once the model is configured, you can open the Library Browser
1283 (\textsc{View $\rightarrow$ Library Browser}) and add the necessary
1284 blocks to create the model. The RPP-specific blocks are located in
1285 the RPP Block Library.
1286 \item From Matlab command window change the current directory to where
1287 you want your generated code to appear, e.g.:
1288 \begin{lstlisting}[language=Matlab]
1291 The code will be generated in a subdirectory named
1292 \texttt{<model>\_rpp}, where \texttt{model} is the name of the
1294 \item Generate the code by choosing \textsc{Code $\rightarrow$ C/C++
1295 Code $\rightarrow$ Build Model}.
1298 If you want to run the model on the RPP board, see Section
1299 \ref{sec-running-model-on-hw}.
1301 \subsection{Running models on the RPP board}
1302 \label{sec-running-model-on-hw}
1303 To run the model on the target RPP hardware you have to enable the download
1304 feature and build the model by following this procedure:
1306 \item Open the model you want to run (see
1307 Section~\ref{sec-openning-demo-models} for example with demo
1309 \item Click on \textsc{Simulation$\rightarrow$Model Configuration
1311 \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
1312 check the \textsc{Download compiled binary to RPP} checkbox.
1313 \item Click the \textsc{OK} button, connect the target HW to the computer
1314 like in the Section \ref{sec-ccs-run-project} and build the model by \textsc{Code $\rightarrow$ C/C++
1315 Code $\rightarrow$ Build Model}. If the build
1316 ends with a success, the download process will start and once the downloading is
1317 finished, the application will run immediatelly.
1320 %%\subsubsection{Using OpenOCD for downloading}
1321 %%\label{sec:using-open-downl}
1323 %%On Linux systems, it is possible to use an alternative download
1324 %%mechanism based on the OpenOCD tool. This results in much shorter
1325 %%download times. Using OpenOCD is enabled by checking ``Use OpenOCD to
1326 %%download the compiled binary'' checkbox. For more information about
1327 %%the OpenOCD configuration refer to our
1328 %%wiki\footnote{\url{http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137\#OpenOCD_setup_and_Flashing}}.
1330 %%Note: You should close any ongoing Code Composer Studio debug sessions
1331 %%before downloading the generated code to the RPP board. Otherwise the
1334 \section{Configuring serial interface}
1335 \label{sec-configuration-serial-interface}
1336 The main mean for communication with the RPP board is the serial line.
1337 Each application may define its own serial line settings, but the
1338 following settings is the default one:
1341 \item Baudrate: 115200
1345 \item Flow control: none
1348 Use GtkTerm in Linux or Bray Terminal for accessing the serial
1349 interface. On TMDSRM48HDK, the serial line is tunneled over the USB
1350 cable. % See Section \ref{sec-hardware-description} for reference about
1351 % the position of the serial interface connector on the RPP board.
1353 \section{Bug reporting}
1354 \label{sec-bug-reporting}
1356 Please report any problems to CTU's bug tracking system at
1357 \url{https://redmine.felk.cvut.cz/projects/eaton-rm48}. New users have
1358 to register in the system and notify Michal Sojka about their
1359 registration via $\langle{}sojkam1@fel.cvut.cz\rangle{}$ email
1362 \chapter{C Support Library}
1363 \label{chap-c-support-library}
1365 This chapter describes the implementation of the C support library
1366 (RPP Library), which is used both for Simulink code generation target
1367 and command line testing tool.
1369 \section{Introduction}
1370 \label{sec-description}
1371 The RPP C Support Library (also called RPP library) defines the API for
1372 working with the board. It includes drivers and an operating system.
1374 designed from the board user perspective and exposes a simplified high-level API
1375 to handle the board's peripheral modules in a safe manner. The library is
1376 compiled as static library named \texttt{rpp-lib.lib} and can be found in
1377 \texttt{\repo/rpp/lib}.
1379 The RPP library can be used in any project, where the RPP hardware
1380 support is required and it is also used in two applications --
1381 Simulink Coder target, described in Chapter
1382 \ref{chap-simulink-coder-target}, and the command line testing tool,
1383 described in Chapter \ref{chap-rpp-test-software}.
1385 For details about the library architecture, refer to Section~\ref{sec-software-architecture}.
1387 \section{API development guidelines}
1388 \label{sec-api-development-guidlines}
1390 The following are the development guidelines used for developing the RPP API:
1393 \item User documentation should be placed in header files, not in source
1394 code, and should be Doxygen formatted using autobrief. Documentation for each
1395 function present is mandatory.
1396 \item Function declarations in the headers files is for public functions
1397 only. Do not declare local/static/private functions in the header.
1398 \item Documentation in source code files should be non-doxygen formatted
1399 and intended for developers, not users. Documentation here is optional and at
1400 the discretion of the developer.
1401 \item Always use standard data types for IO when possible. Use custom
1402 structs as very last resort. \item Use prefix based functions names to avoid
1403 clash. The prefix is of the form \texttt{$\langle$layer$\rangle$\_$\langle$module$\rangle$\_}, for example
1404 \texttt{rpp\_din\_update()} for the update function of the DIN module in the RPP
1406 \item Be very careful about symbol export. Because it is used as a
1407 static library the modules should not export any symbol that is not intended to
1408 be used (function) or \texttt{extern}'ed (variable) from application. As a rule
1409 of thumb declare all global variables as static.
1410 \item Only the RPP Layer symbols are available to user applications. All
1411 information related to lower layers is hidden for the application. This is
1412 accomplished by the inclusion of the rpp.h or rpp\_\{mnemonic\}.h file on the
1413 implementations files only and never on the interface files. Never expose any
1414 other layer to the application or to the whole system below the RPP layer. In
1415 other words, never \texttt{\#include "foo/bar.h"} in any RPP Layer header
1419 \section{Changing operating system}
1420 \label{sec-changing-os}
1421 The C Support Library contains by default the FreeRTOS operating system in
1422 version 7.0.2. However newer versions up to 8.1.2 are supported and should
1423 be working, no functional tests have been done for them. This section
1424 describes all changes necessary for replacing the operating system.
1427 The source and header files of the current operating system (OS) are
1428 stored in directory \texttt{\repo/rpp/lib/os}. The files of the new
1429 operating system should also be placed in this directory.
1431 To make the methods and resources of the new OS available to the C Support
1432 Library, modify the \texttt{\repo/rpp/lib/rpp/include/base.h} file to include
1433 the operating system header files.
1435 Our implementation for FreeRTOS includes one header file
1436 \texttt{\repo/rpp/lib/os/i/7.0.2\_rm48/include/os.h}, which contains all
1437 necessary inclusions and macro definitions for the FreeRTOS. We suggest to
1438 define similar header file for your operating system as well.
1440 The API for SCI in file \texttt{\repo/rpp/lib/rpp/src/sci.c} contains a
1441 FreeRTOS constant \texttt{portMAX\_DELAY}, defining infinite waiting time
1442 for Queues and Semaphores, that has to be replaced.
1444 \subsection{Drivers}
1445 Drivers for SCI and ADC contain dependencies on the FreeRTOS. Those files should be modified:
1447 \item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data structure,
1448 containing definitions of Queue and Semaphore.
1449 \item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Contains FreeRTOS Queue and
1450 Semaphore data types and functions.
1451 \item[\repo/rpp/lib/rpp/include/drv/sci.h] Contains a \texttt{portTickType}, defining
1452 a data type for timing in miliseconds
1453 \item[\repo/rpp/lib/rpp/src/drv/sci.c] Contains references to Semaphore,
1454 Queue data types and functions, data type for return values
1455 (\texttt{portBASE\_TYPE}) and critical sections, determined by
1456 \texttt{taskENTER\_CRITICAL} and \texttt{taskEXIT\_CRITICAL} macros,
1457 where preemtion is disabled.
1458 \item[\repo/rpp/lib/rpp/src/drv/adc.c] Contains FreeRTOS Semaphore data types,
1459 functions and contains data type for return values (\texttt{portBASE\_TYPE})
1460 and FreeRTOS constant \texttt{portMAX\_DELAY}, defining infinite waiting time.
1463 \subsection{System start}
1464 The initialization of the MCU and the system is in the
1465 \texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} source file. If your
1466 system relies on interrupts generated by Real-Time Interrupt module, the
1467 pointer to the Interrupt Service Routine (ISR) \texttt{vPreemptiveTick}
1470 \subsection{Simulink template for main function}
1471 The template for generation of the \texttt{ert\_main.c} file, containing
1472 the main function, has to be modified to use proper functions for task
1473 creation, task timing and semaphores. The template is defined in
1474 \texttt{\repo/rpp/rpp/rpp\_srmain.tlc} file.
1476 \subsection{Makefile}
1477 To be able to build the C Support Library with the new operating system,
1478 the \texttt{\repo/rpp/lib/Makefile.var} file, containing paths to the
1479 source and header files, has to be modified to contain paths to the files
1482 \section{Coding style}
1483 \label{sec-coding-style}
1484 In order to keep the code as clean as possible, unified coding style
1485 should be followed by any contributor to the code. The used coding
1486 style is based on the default configuration of Code Composer Studio
1487 editor. Most notable rule is that the Tab character is 4 spaces.
1489 The RPP library project is prepared for use of a tool named
1490 Uncrustify. The Uncrustify tool checks the code and fixes those lines
1491 that do not match the coding style. However, keep in mind that the
1492 program is not perfect and sometimes it can modify code where the
1493 suggested coding style has been followed. This does not causes
1494 problems as long as the contributor follows the committing procedure
1495 described in next paragraph.
1497 When contributing to the code, the contributor should learn the
1498 current coding style from existing code. When a new feature is
1499 implemented and committed to the local repository, the following
1500 commands should be called in Linux terminal:
1502 \begin{lstlisting}[language=bash]
1506 The first line command corrects many found coding style violations and
1507 the second command displays them. If the user agree with the
1508 modification, he/she should amend the last commit, for example by:
1509 \begin{lstlisting}[language=bash]
1514 \section{Subdirectory content description}
1515 \label{sec-rpp-lib-subdirectory-content-description}
1517 The following files and directories are present in the library source
1521 \item[rpp-lib.lib and librpp.a] static RPP libraries.
1523 The first one is the library for Simulink models and other ARM/RM48
1524 applications, the other can be used for POSIX simulation. This files
1525 are placed here by the Makefile, when the library is built.
1527 \item[apps/] Demo applications related to the RPP library.
1529 This include the CCS studio project for generating of the static
1530 library and a test suite. The test suit in this directory has
1531 nothing common with the test suite described later in
1532 Chapter~\ref{chap-rpp-test-software} and those two suits are going
1533 to be merged in the future. Also other Hello World applications are
1534 included as a reference about how to create an RM48 application.
1535 \item[os/] OS layers directory. See
1536 Section~\ref{sec-operating-system-layer} for more information about
1537 currently available operating system versions and
1538 Section~\ref{sec-changing-os} for information how to replace the
1540 \item[rpp/] Main directory for the RPP library.
1541 \item[rpp/doc/] RPP Library API
1543 \item[rpp/RM48L952FlashLnk.cmd] CGT Linker command file.
1545 This file is used by all applications linked for the RPP board,
1546 including the Simulink models and test suite. It includes
1547 instructions for the CGT Linker about target memory layout and where
1548 to place various code sections.
1549 \item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
1550 implementations files for given \texttt{\{layer\}}. See
1551 Section~\ref{sec-software-architecture} for details on the RPP
1553 \item[rpp/include/rpp/rpp.h] Main library header file.
1555 To use this library with all its modules, just include this file
1556 only. Also, before using any library function call the
1557 \texttt{rpp\_init()} function for hardware initialization.
1558 \item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for
1559 \texttt{\{mnemonic\}} module.
1561 These files includes function definitions, pin definitions, etc,
1562 specific to \{mnemonic\} module. See also
1563 Section~\ref{sec-api-development-guidlines}.
1565 If you want to use only a subset of library functions and make the
1566 resulting binary smaller, you may include only selected
1567 \texttt{rpp\_\{mnemonic\}.h} header files and call the specific
1568 \texttt{rpp\_\{mnemonic\}\_init} functions, instead of the
1569 \texttt{rpp.h} and \texttt{rpp\_init} function.
1570 \item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation.
1572 Implementation of \texttt{rpp\_\{mnemonic\}.h}'s functions on
1573 top of the DRV library.
1574 \item[rpp/src/rpp/rpp.c] Implementation of library-wide functions.
1577 \section{Compilation}
1578 \label{sec-compilation}
1580 To compile the library open the Code Composer studio project
1581 \texttt{rpp-lib} (see Section~\ref{sec-openning-of-existing-project})
1582 and build the project (\textsc{Project $\rightarrow$ Build Project}).
1583 If the build process is successful, the \texttt{rpp-lib.lib} file will
1584 appear in the library root directory.
1586 It is also possible to compile the library using the included
1587 \texttt{Makefile}. From the Linux command line run:
1588 \begin{lstlisting}[language=bash]
1592 Note that this only works if Code Composer Studio is installed in
1593 \texttt{/opt/ti} directory. Otherwise, you have to set
1594 \texttt{CCS\_UTILS\_DIR} variable.
1596 On Windows command line run:
1597 \begin{lstlisting}[language=bash]
1599 set CCS_UTILS_DIR=C:\ti\ccsv5\utils
1600 C:\ti\ccsv5\utils\bin\gmake.exe lib
1603 You have to use \texttt{gmake.exe} is instead of \texttt{make} and it
1604 is necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You
1605 can also edit \texttt{\repo/Debug/GNUmakefile} and set the variable
1608 Note that the Makefile still requires the Code Composer Studio (ARM
1609 compiler) to be installed because of the CGT.
1611 \section{Compiling applications using the RPP library}
1612 \label{sec:comp-appl-using}
1614 The relevant aspects for compiling and linking an application using
1615 the RPP library are summarized below.
1617 \subsection{ARM target (RPP board)}
1618 \label{sec:arm-target-rpp}
1620 The detailed instructions are presented in
1621 Section~\ref{sec:creating-new-project}. Here we briefly repeat the
1625 \item Configure include search path to contain the directory of
1626 used FreeRTOS version, e.g.
1627 \texttt{\repo/os/7.0.2\_rm48/include}. See Section
1628 \ref{sec-software-architecture}.
1629 \item Include \texttt{rpp/rpp.h} header file or just the needed
1630 peripheral specific header files such as \texttt{rpp/can.h}.
1631 \item Add library \texttt{rpp-lib.lib} to the linker libraries.
1632 The RPP library must be placed before Texas Instruments
1633 support library \texttt{rtsv7R4\_T\_le\_v3D16\_eabi.lib}.
1634 \item Use the provided linker command file
1635 \texttt{RM48L952FlashLnk.cmd}.
1638 \subsection{POSIX target}
1639 \label{sec:posix-target}
1642 \item Include headers files of the OS for Simulation. At the time
1643 of this writing the OS is POSIX FreeRTOS 6.0.4.
1644 \item Include header files for the RPP library or for modules you
1645 want to use (rpp\_can.h for CAN module for example).
1646 \item Add library \texttt{librpp.a} to the linker libraries.
1647 \item Add \texttt{pthread} to the linker libraries.
1650 \section{Compiling API documentation}
1651 \label{sec-compiling-api-documentation}
1652 The documentation of the RPP layer is formatted using Doxygen
1653 documentation generator. This allows to generate a high quality API
1654 reference. To generate the API reference run in a Linux terminal:
1656 \lstset{language=bash}
1658 cd <repo>/rpp/doc/api
1660 xdg-open html/index.html
1663 The files under \texttt{\repo/rpp/doc/api/content} are used for the API
1664 reference generation are their name is self-explanatory:
1674 \chapter{Simulink Coder Target}
1675 \label{chap-simulink-coder-target}
1677 The Simulink Coder Target allows to convert Simulink models to a C code,
1678 compile it and download to the board.
1680 \section{Introduction}
1681 \label{sec-introduction}
1683 The Simulink RPP Target provides support for C source code generation from Simulink models and
1684 compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
1685 uses Texas Instruments ARM compiler (\texttt{armcl}) included in the Code Generation Tools distributed with
1686 Code Composer Studio, and thus it depends on it for proper functioning.
1688 This target also provides support for automatic download of the compiled binary to the RPP
1691 \begin{figure}[H]\begin{center}
1693 \includegraphics[scale=.45]{images/tlc_process.png}
1694 \caption{TLC code generation process. \cite[p. 1-6]{targetlanguagecompiler2013}}
1695 \end{center}\end{figure}
1697 \section{Features and limitations}
1698 \label{sec-features}
1701 \item Sampling frequencies up to 1\,kHz.
1702 \item Supports only single-tasking and single-rate systems. Support
1703 for single-rate systems will be available in the final version.
1704 Support for multitasking system will require careful audit of the
1705 RPP library with respect to thread-safe code.
1706 \item No External mode support yet. We work on it.
1707 \item Custom compiler options, available via OPTS variable in
1708 \emph{Make command} at \emph{Code Generation} tab (see Figure
1709 \ref{fig-code-gen-settings}). For example \texttt{make\_rtw
1713 \section{RPP Options pane}
1714 \label{sec-rpp-target-options}
1716 The RPP Target includes the following configuration options, all of them
1717 configurable per model under \textsc{Code Generation} \noindent$\rightarrow$
1718 \textsc{RPP Options}:
1721 \item \textbf{C system stack size}: this parameter is passed directly
1722 to the linker for the allocation of the stack. Note that this stack
1723 is used only for initializing the application and FreeRTOS. Once
1724 everything is initialized, another stack is used by the generated
1725 code. See below. Default value is 4096.
1727 \item \textbf{C system heap size}:
1728 \label{sec-rpp-target-options-heap-size} this parameter is passed
1729 directly to the linker for the allocation of the heap. Currently,
1730 the heap is not used, but will be used by the external mode in the future.
1731 Note that FreeRTOS uses its own heap whose size is independent of this
1733 \item \textbf{Model step task stack size}: this parameter will be
1734 passed to the \texttt{xTaskCreate()} that
1735 creates the task for the model to run. In a Simulink model there are always two tasks:
1737 \item The worker task. This task is the one that executes the model
1738 step. This task requires enough stack memory to execute the step.
1739 If your model does not run, it might be caused by too small stack.
1740 The memory needed for the stack depends on the size and structure
1742 \item The control task. This task controls when the worker task should execute and controls overruns.
1745 \item \textbf{Download compiled binary to RPP}: if set, this option will download the generated binary to
1746 the board after the model is successfully built. Note that this option is unaware of the option
1747 \textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to download even if
1748 only source code has been generated, failing graciously or uploading an old binary laying around
1749 in the build directory. This option calls the \texttt{rpp\_download.m} script, which is in turn a
1750 wrapper on the \texttt{loadti.sh}, \texttt{loadti.bat} and \texttt{loadopenocd.sh} script. More information on the \texttt{loadti.sh}
1751 script can be found in:
1753 <css>/ccs_base/scripting/examples/loadti/readme.txt
1754 http://processors.wiki.ti.com/index.php/Loadti
1757 The \texttt{loadti.sh} and \texttt{loadti.bat} script will close after the
1758 download of the generated program, leaving the loaded program running.
1760 The \texttt{loadopenocd.sh} script will close after the download of the
1761 generated program as well, but the program will be stopped. In order to run
1762 the loaded program a manual reset of the board is required.
1764 \item \textbf{Download compiled binary to SDRAM}: This feature is not yet
1765 implemented for the simulink target.
1767 \item \textbf{Use OpenOCD to download the compiled binary}: This feature is not yet
1768 implemented for the RM48L952 simulink target.
1770 \item \textbf{Print model metadata to SCI at start}: if set this option will
1771 print a message to the Serial Communication Interface when the model start
1772 execution on the board. This is very helpful to identify the model running on
1773 the board. The message is in the form:
1776 `model_name' - generated_date (TLC tlc_version)
1781 `hbridge_analog_control' - Wed Jun 19 14:10:44 2013 (TLC 8.3 (Jul 20 2012))
1785 \section{Subdirectory content description}
1786 \label{sec-simulink-subdirectory-content-description}
1787 This section describes the directories of the Simulink Coder. If you are
1788 interested in particular file, refer the description at the beginning of the
1792 \item[doc/] Contains the sources of the documentation, you are now
1794 \item[refs/] Contains third party references, which license allows the
1796 \item[rpp/blocks] Contains the TLC files, which defines the blocks for
1797 the Matlab Simulink and \texttt{rpp\_lib.slx}, which is the Simulink RPP
1798 Library, containing all the Simulink blocks for RPP.
1799 \item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the
1800 Matlab Simulink model.
1801 \item[rpp/demos] Contains demo models, which purpose is to serve as a
1802 reference for the usage and for testing.
1803 \item[rpp/lib] Contains the C Support Library. See Chapter
1804 \ref{chap-c-support-library}. \item[rpp/loadopenocd] Contains download scripts
1805 for Linux support of the OpenOCD, for code downloading to the target.
1806 \item[rpp/loadti] Contains download scripts for Linux and Windows
1807 support for code downloading to the target, using Texas Instruments CCS code
1809 \item[rpp/rpp] Contains set of support script for the Code Generator.
1812 \section{Block Library Overview}
1813 \label{sec-block-library-overview}
1814 The Simulink Block Library is a set of blocks that allows Simulink models to use
1815 board IO and communication peripherals. The available blocks are summarized in
1816 Table~\ref{tab:block-lib-status} and more detailed description is
1817 given in Section~\ref{sec-blocks-description}.
1820 \begin{center}\begin{tabular}{|lp{5cm}lll|}
1822 \textbf{Category} & \textbf{Name} & \textbf{Status} & \textbf{Mnemonic} & \textbf{Header} \\
1824 \input{block_table.tex}
1826 \end{tabular}\end{center}
1828 \caption{Block library overview}
1829 \label{tab:block-lib-status}
1832 \label{sec-blocks-implementation}
1833 All of the blocks are implemented as manually created C Mex S-Function . In this section the
1834 approach taken is briefly explained.
1836 \subsection{C MEX S-Functions}
1837 \label{sec-c-mex-functions}
1839 \item C : Implemented in C language. Other options are Fortran and Matlab language itself.
1840 \item MEX: Matlab Executable. They are compiled by Matlab - C compiler wrapper called MEX.
1841 \item S-Function: System Function, as opposed to standard functions, or user functions.
1844 A C-MEX S-Function is a structured C file that implements some mandatory and
1845 optional callbacks for a specification of a number of inputs, outputs, data
1846 types, parameters, rate, validity checking, etc. A complete list of callbacks
1849 \htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
1852 The way a C-MEX S-Function participates in a Simulink simulation is shown on the
1853 diagram \ref{fig-sfunctions-process}:
1855 \begin{figure}[H]\begin{center}
1857 \includegraphics[scale=.45]{images/sfunctions_process.png}
1858 \caption{Simulation cycle of a S-Function. \cite[p. 57]{simulinkdevelopingsfunctions2013}}
1859 \label{fig-sfunctions-process}
1860 \end{center}\end{figure}
1862 In general, the S-Function can perform calculations, inputs and outputs for simulation. Because
1863 the RPP blocks are for hardware peripherals control and IO the blocks are
1864 implemented as pure sink or pure source, the S-Function is just a descriptor of
1865 the block and does not perform any calculation and does not provide any input or
1866 output for simulations.
1868 The implementation of the S-Functions in the RPP project has following layout:
1871 \item Define S-Function name \texttt{S\_FUNCTION\_NAME}.
1872 \item Include header file \texttt{header.c}, which in connection with
1873 \texttt{trailer.c} creates a miniframework for writing S-Functions.
1874 \item In \texttt{mdlInitializeSizes} define:
1876 \item Number of \textit{dialog} parameter.
1877 \item Number of input ports.
1879 \item Data type of each input port.
1881 \item Number of output ports.
1883 \item Data type of each output port.
1885 \item Standard options for driver blocks.
1887 \item In \texttt{mdlCheckParameters}:
1889 \item Check data type of each parameter.
1890 \item Check range, if applicable, of each parameter.
1892 \item In \texttt{mdlSetWorkWidths}:
1894 \item Map \textit{dialog} parameter to \textit{runtime} parameters.
1896 \item Data type of each \textit{runtime} parameter.
1899 \item Define symbols for unused functions.
1900 \item Include trailer file \texttt{trailer.c}.
1903 The C-MEX S-Function implemented can be compiled with the following command:
1905 \lstset{language=bash}
1907 <matlabroot>/bin/mex sfunction_{mnemonic}.c
1910 As noted the standard is to always prefix S-Function with \texttt{sfunction\_}
1911 and use lower case mnemonic of the block.
1913 Also a script called \texttt{compile\_blocks.m} is included. The script that
1914 allows all \texttt{sfunctions\_*.c} to be fed to the \texttt{mex} compiler so
1915 all S-Functions are compiled at once. To use this script, in Matlab do:
1917 \lstset{language=Matlab}
1919 cd <repo>/rpp/blocks/
1923 \subsection{Target Language Compiler files}
1924 \label{sec-target-language-compiler-files}
1926 In order to generate code for each one of the S-Functions, every S-Function implements a TLC file
1927 for \textit{inlining} the S-Function on the generated code. The TLC files describe how to
1928 generate code for a specific C-MEX S-Function block. They are programmed using TLC own language and
1929 include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX
1932 The standard for a TLC file is to be located under the \texttt{tlc\_c} subfolder from where the
1933 S-Function is located and to use the very exact file name as the S-Function but with the \texttt{.tlc}
1934 extension: \texttt{sfunction\_foo.c} \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_foo.tlc}
1936 The TLC files implemented for this project use 3 hook functions in particular (other are available,
1937 see TLC reference documentation):
1939 \item \texttt{BlockTypeSetup}: \newline{}
1940 BlockTypeSetup executes once per block type before code generation begins.
1941 This function can be used to include elements required by this block type, like includes or
1943 \item \texttt{Start}: \newline{}
1944 Code here will be placed in the \texttt{void
1945 $\langle$modelname$\rangle$\_initialize(void)}. Code placed here will execute
1947 \item \texttt{Outputs}: \newline{}
1948 Code here will be placed in the \texttt{void
1949 $\langle$modelname$\rangle$\_step(void)} function. Should be used to get the
1950 inputs o a block and/or to set the outputs of that block.
1953 The general layout of the TLC files implemented for this project are:
1955 \item In \texttt{BlockTypeSetup}: \newline{}
1956 Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
1957 \texttt{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
1958 \item \texttt{Start}: \newline{}
1959 Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup,
1960 DAC value initialization, SCI baud rate setup, among others.
1961 \item \texttt{Outputs}: \newline{}
1962 Call common IO routines from RPP Layer, like DIN read, DAC set, etc. Success of this functions
1963 is checked and in case of failure error is reported to the block using ErrFlag.
1966 C code generated from a Simulink model is placed on a file called
1967 \texttt{$\langle$modelname$\rangle$.c} along with other support files in a
1968 folder called \texttt{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}.
1969 For example, the source code generated for model \texttt{foobar} will be placed
1970 in current Matlab directory \texttt{foobar\_rpp/foobar.c}.
1972 The file \texttt{$\langle$modelname$\rangle$.c} has 3 main functions:
1974 \item \texttt{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
1975 This function recalculates all the outputs of the blocks and should be called once per step. This
1976 is the main working function.
1977 \item \texttt{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
1978 This function is called only once before the first step is issued. Default values for blocks IOs
1979 should be placed here.
1980 \item \texttt{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
1981 This function is called when terminating the model. This should be used to free memory of revert
1982 other operations made on the initialization function. With current implementation this function
1983 should never be called unless an error is detected and in most models it is empty.
1986 \section{Block reference}
1987 \label{sec-blocks-description}
1989 This section describes each one of the Simulink blocks present in the Simulink
1990 RPP block library, shown in Figure \ref{fig-block-library}.
1994 \includegraphics[width=\textwidth]{images/block_library.png}
1996 \caption{Simulink RPP Block Library.}
1997 \label{fig-block-library}
2000 \input{block_desc.tex}
2002 \section{Compilation}
2003 \label{sec-simulink-compilation}
2004 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:
2005 \lstset{language=Matlab}
2007 cd <rpp-simulink>/rpp/blocks
2011 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:
2014 \item Open Matlab and run those commands in the Matlab command line:
2015 \lstset{language=Matlab}
2017 cd <rpp-simulink>/rpp/demos
2020 \item Run those commands in a Linux terminal:
2021 \begin{lstlisting}[language=bash]
2022 cd <rpp-simulink>/rpp/demos
2026 or Windows command line:
2028 \begin{lstlisting}[language=bash]
2029 cd <rpp-simulink>\rpp\demos
2030 "C:\ti\ccsv5\utils\bin\"gmake.exe lib
2033 Both commands will create a directory for each compiled demo, which will contai 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}.
2036 \section{Adding new functionality}
2037 This section describes how to create new Matlab Simulink blocks and how to add them to the RPP
2039 The new block creation process consists of several steps:
2041 \item Definition of block by a C-MEX file for Matlab Simulink.
2042 \item Definition of TLC file of the block for Code Generator.
2043 \item Creation of an S-Function object in the RPP library and linking this object with the
2044 C-MEX and TLC files.
2045 \item Optionally modification of texttt{compile\_blocks.m} script, if the block requires special
2046 paths to libraries or other options for C-MEX source file compilation.
2048 The following subsections demonstrates the procedure on an example of a simple user defined block.
2050 \subsection{Block definition in C-MEX file}
2051 The block attributes and behavioral is specified by a set of functions in a C file, which is
2052 compiled by a MEX compiler into C-MEX files, which are finally linked with an S-function objects
2053 in the Matlab Simlulink. The Matlab calls those C-MEX functions to obtain the number and types of
2054 inputs, outputs and block parameters.
2056 The C files are stored in \texttt{\repo/rpp/blocks} and are named following \texttt{sfunction\_name.c}
2057 pattern. Feel free to open any of the C files as a reference.
2059 Every C file that will be used with the RPP library should begin with a block of text, structured in
2060 YAML format. This block is parsed by a makefile which is generating this documentation. Althought
2061 this block is not mandatory, it is highly sugested, as it helps keeping the documentation actual.
2063 The YAML documentation block may look like this:
2064 \begin{lstlisting}[language=c]
2068 Name: Name Of The Block
2074 - { name: "Some Input Signal", type: "bool" }
2077 - { name: "Some Output Signal", type: "bool" }
2081 # Description and Help is in Markdown mark-up
2084 This is a stub of an example block.
2088 This block show is a part of an example about how to create
2089 new Matlab Simulink blocks for RPP board.
2093 RPP API functions used:
2101 Following parts are obligatory and the block will not work without them. It starts with a
2102 definition of the block name and an inclusion of a common source file:
2104 \begin{lstlisting}[language=c]
2105 #define S_FUNCTION_NAME sfunction_myblock
2109 To let the Matlab Simulink know the type of the inputs, outputs and how many parameters
2110 will the block have, a mdlInitializeSizes() function has to be defined like this:
2112 \begin{lstlisting}[language=c]
2113 static void mdlInitializeSizes(SimStruct *S)
2115 /* The block will have no parameters. */
2116 if (!rppSetNumParams(S, 0)) {
2119 /* The block will have one input signal. */
2120 if (!ssSetNumInputPorts(S, 1)) {
2123 /* The input signal will be of type boolean */
2124 rppAddInputPort(S, 0, SS_BOOLEAN);
2125 /* The block will have one output signal */
2126 if (!ssSetNumOutputPorts(S, 1)) {
2129 /* The output signal will be of type boolean */
2130 rppAddOutputPort(S, 0, SS_BOOLEAN);
2132 rppSetStandardOptions(S);
2136 The C file may contain several other optional functions definitions for parameters checking,
2137 run-time parameters definition and so on. For information about those functions refer the comments
2138 in the header.c file, trailer.c file and Matlab Simulink Help.
2140 The minimal C file compilable into C-MEX has to contain following macros to avoid linker error
2141 messages, complaining about some of the optional functions not being defined:
2142 \begin{lstlisting}[language=c]
2143 #define COMMON_MDLINITIALIZESAMPLETIMES_INHERIT
2144 #define UNUSED_MDLCHECKPARAMETERS
2145 #define UNUSED_MDLOUTPUTS
2146 #define UNUSED_MDLTERMINATE
2149 Every C file has to be closed by an inclusion of a common trailer source file:
2151 \begin{lstlisting}[language=c]
2152 #include "trailer.c"
2155 \subsection{C-MEX file compilation}
2156 The development environment has to be configured first as described in section \ref{sec-matlab-simulink-usage}
2158 All C files in the directory \texttt{\repo/rpp/blocks} can be compiled into C-MEX by running script
2159 \texttt{\repo/rpp/blocks/compile\_blocks.m} from Matlab. If your block requires some special
2160 compiler options, edit the script and add a branch for your block.
2162 To compile only one block run the \texttt{mex sfunction\_myblock.c} from the Matlab.
2164 \subsection{TLC file definition}
2165 The TLC file is a template used by the Code Generator to generate the C code for the RPP board. The
2166 TLC files are stored in \texttt{\repo/rpp/blocks/tlc\_c} folder and are named following the
2167 \texttt{sfunction\_name.tlc} pattern. Feel free to open any of the TLC files as a reference.
2169 Every TLC file has to contain a header:
2170 \begin{lstlisting}[language=c]
2171 %implements sfunction_myblock "C"
2172 %include "common.tlc"
2175 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:
2177 \item BlockTypeSetup
2178 \item BlockInstanceSetup
2183 For detail description about each one of those functions refer to the
2184 \cite{targetlanguagecompiler2013}
2186 The minimal TLC file which actually doeas something may look like this:
2187 \begin{lstlisting}[language=c]
2188 %implements sfunction_myblock "C"
2189 %include "common.tlc"
2191 %function BlockTypeSetup(block, system) void
2192 %% Ensure required header files are included
2193 %<RppCommonBlockTypeSetup(block, system)>
2194 %<LibAddToCommonIncludes("rpp/sci.h")>
2197 %function Outputs(block, system) Output
2198 %if !SLibCodeGenForSim()
2199 %assign in_signal = LibBlockInputSignal(0, "", "", 0)
2200 %assign out_signal = LibBlockOutputSignal(0, "", "", 0)
2202 %<out_signal> = !%<in_signal>;
2203 rpp_sci_printf("Value: %d\r\n", %<in_signal>);
2209 \subsection{S-Function creation in RPP library}
2210 User defined blocks in Matlab can be represented by an object named S-function. Follow this
2211 procedure to create new block in the RPP library:
2213 \item Open the \texttt{\repo/rpp/blocks/rpp\_lib.slx} file in Matlab.
2214 \item Unlock it for editing by clicking on \textsc{Diagram$\rightarrow$Unlock Library}.
2215 \item Open a Simulink Library Browser (\textsc{View$\rightarrow$Library Browser}) and from
2216 \textsc{Simulink$\rightarrow$User-Defined Functions} drag the S-Function block and drop it in the
2218 \item Double click on the recently created object and in the dialog window write the name of the
2219 S-functions C-MEX file without the suffix (sfunction\_myblock for example) in the field
2220 \textsc{S-function name}.
2221 \item If your block has some parameters, write their names in the \textsc{S-function parameters}
2222 field, separated by commas. The result should like like in the figure \ref{fig-simulink_s_fun_cfg}.
2223 \item Now you should see new Simulink block with the right number of inputs and outputs. For
2224 every user-defined block a mask should be defined to provide some useful information about the name
2225 of the block, configuration dialog for parameters and names of the IO signals. But the block is
2226 ready to be used in the models whether it has a mask or not.
2227 \item Follow the procedur in Section \ref{sec-crating-new-model} to use the new block in model.
2229 \begin{figure}[H]\begin{center}
2231 \includegraphics[scale=.45]{images/simulink_s_fun_config.png}
2232 \caption{Configuration dialog for user defined S-function.}
2233 \label{fig-simulink_s_fun_cfg}
2234 \end{center}\end{figure}
2238 \section{Demos reference}
2239 The Simulink RPP Demo Library is a set of Simulink models that use blocks from
2240 the Simulink RPP Block Library and generates code using the Simulink RPP Target.
2242 This demos library is used as a test suite for the Simulink RPP Block Library
2243 but they are also intended to show basic programs built using it. Because of
2244 this, the demos try to use more than one
2245 type of block and more than one block per block type.
2247 In the reference below you can find a complete description for each of the demos.
2249 \subsection{ADC demo}
2250 \begin{figure}[H]\begin{center}
2252 \includegraphics[scale=.45]{images/demo_adc.png}
2253 \caption{Example of the usage of the Analog Input blocks for RPP.}
2254 \end{center}\end{figure}
2256 \textbf{Description:}
2258 Demostrates how to use Analog Input blocks in order to measure voltage. This demo
2259 measures voltage on every available Analog Input and prints the values on the
2262 \subsection{Simple CAN demo}
2263 \begin{figure}[H]\begin{center}
2265 \includegraphics[scale=.45]{images/demo_simple_can.png}
2266 \caption{The simplest CAN demonstration.}
2267 \end{center}\end{figure}
2269 \textbf{Description:}
2271 The simplest possible usage of the CAN bus. This demo is above all designed for
2272 testing the CAN configuration and transmission.
2274 \subsection{CAN transmit}
2275 \begin{figure}[H]\begin{center}
2277 \includegraphics[scale=.45]{images/demo_cantransmit.png}
2278 \caption{Example of the usage of the CAN blocks for RPP.}
2279 \end{center}\end{figure}
2281 \textbf{Description:}
2283 Demostrates how to use CAN Transmit blocks in order to:
2286 \item Send unpacked data with data type uint8, uint16 and uint32.
2287 \item Send single and multiple signals packed into CAN\_MESSAGE by CAN Pack block.
2288 \item Send a message as extended frame type to be received by CAN Receive
2289 configured to receive both, standard and extended frame types.
2292 Demostrates how to use CAN Receive blocks in order to:
2295 \item Receive unpacked data of data types uint8, uint16 and uint32.
2296 \item Receive and unpack received CAN\_MESSAGE by CAN Unpack block.
2297 \item Configure CAN Receive block to receive Standard, Extended and both frame types.
2298 \item Use function-call mechanism to process received messages
2301 \subsection{Simulink Demo model}
2302 \begin{figure}[H]\begin{center}
2304 \includegraphics[scale=.45]{images/demo_board.png}
2305 \caption{Model of the complex demonstration of the boards peripherals.}
2306 \end{center}\end{figure}
2308 \textbf{Description:}
2310 This model demonstrates the usage of RPP Simulink blocks in a complex and interactive
2311 application. The TI HDK kit has eight LEDs placed around the MCU. The application
2312 rotates the light around the MCU in one direction. Every time the user presses the button
2313 on the HDK, the direction is switched.
2315 The state of the LEDs is sent on the CAN bus as a message with ID 0x1. The button can
2316 be emulated by CAN messages with ID 0x0. The message 0x00000000 simulates button release
2317 and the message 0xFFFFFFFF simulates the button press.
2319 Information about the state of the application are printed on the Serial Interface.
2321 \subsection{Echo char}
2322 \begin{figure}[H]\begin{center}
2324 \includegraphics[scale=.45]{images/demo_echo_char.png}
2325 \caption{Echo Character Simulink demo for RPP.}
2326 \end{center}\end{figure}
2328 \textbf{Description:}
2330 This demo will echo (print back) any character received through the Serial Communication
2331 Interface (115200-8-N-1).
2333 Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
2334 if data is received, that is, Serial Receive output is non-negative. Negative values are errors.
2336 \subsection{GIO demo}
2337 \begin{figure}[H]\begin{center}
2339 \includegraphics[scale=.45]{images/demo_gio.png}
2340 \caption{Demonstration of DIN and DOUT blocks}
2341 \end{center}\end{figure}
2343 \textbf{Description:}
2345 The model demonstrates how to use the DIN blocks and DOUT blocks, configured in every mode. The DOUTs
2346 are pushed high and low with period 1 second. The DINs are reading inputs and printing the values
2347 on the Serial Interface with the same period.
2349 \subsection{Hello world}
2350 \begin{figure}[H]\begin{center}
2352 \includegraphics[scale=.45]{images/demo_hello_world.png}
2353 \caption{Hello World Simulink demo for RPP.}
2354 \end{center}\end{figure}
2356 \textbf{Description:}
2358 This demo will print \texttt{Hello Simulink} to the Serial Communication Interface (115200-8-N-1) one
2359 character per second. The output speed is driven by the Simulink model step which is set to one
2362 \chapter{Command line testing tool}
2363 \label{chap-rpp-test-software}
2364 \section{Introduction}
2365 \label{sec-rpp-test-sw-intro}
2366 The \texttt{rpp-test-suite} is a RPP application developed testing and direct
2367 control of the RPP hardware. The test suite implements a command processor,
2368 which is listening for a commands and prints some output related to the commands
2369 on the serial interface. The command processor is modular and each peripheral
2370 has its commands in a separated module.
2372 The command processor is implemented in \texttt{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
2373 modules are implemented in \texttt{$\langle$rpp-test-sw$\rangle$/commands} directory.
2375 The application enables a command processor using the SCI at
2376 \textbf{115200-8-N-1}. When the software starts, the received welcome message
2377 and prompt should look like:
2380 Ti HDK RM48L952, FreeRTOS 7.0.2
2381 Test Software version eaton-0.1-beta-8-g91419f5
2382 CTU in Prague 10/2014
2386 Type in command help for a complete list of available command, or help command
2387 for a description of concrete command.
2389 \section{Compilation}
2390 \label{sec-rpp-test-sw-compilation}
2391 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.
2393 \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}.
2394 \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}.
2396 To build the Testing tool from Linux terminal run:
2397 \begin{lstlisting}[language=bash]
2402 or from Windows command line:
2404 \begin{lstlisting}[language=bash]
2406 "C:\ti\ccsv5\utils\bin\"gmake.exe
2409 On Windows \texttt{gmake.exe} supplied with CCS is used instead of
2413 \section{Commands description}
2415 This section contains the description of the available commands. The
2416 same description is also available in the program itself via the
2417 \texttt{help} command.
2419 \input{rpp-test-sw-cmds.tex}
2425 \textit{Analog to Digital Converter.} \newline{}
2426 Hardware circuitry that converts a continuous physical quantity (usually voltage) to a
2427 digital number that represents the quantity's amplitude.
2430 \textit{Analog Input.} \newline{}
2431 Mnemonic to refer to or something related to the analog input (ADC) hardware module.
2434 \textit{Analog Output.} \newline{}
2435 Mnemonic to refer to or something related to the analog output (DAC) hardware module.
2438 \textit{Controller Area Network.} \newline{}
2439 The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
2440 communicate with each other within a vehicle without a host computer.
2441 In this project it is also used as mnemonic to refer to or something related to the CAN
2445 \textit{Code Generation Tools.} \newline{}
2446 Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
2447 assemble, archive, among others. In this project is normally used as synonym for
2448 ``Texas Instruments ARM compiler and linker."
2451 \textit{Digital to Analog Converter.} \newline{}
2452 Hardware circuitry that converts a digital (usually binary) code to an analog signal
2453 (current, voltage, or electric charge).
2456 \textit{Digital Input.} \newline{}
2457 Mnemonic to refer to or something related to the digital input hardware module.
2460 \textit{Engine Control Unit.} \newline{}
2461 A type of electronic control unit that controls a series of actuators on an internal combustion
2462 engine to ensure the optimum running.
2465 \textit{Ethernet.} \newline{}
2466 Mnemonic to refer to or something related to the Ethernet hardware module.
2469 \textit{FlexRay.} \newline{}
2470 FlexRay is an automotive network communications protocol developed to govern on-board automotive
2472 In this project it is also used as mnemonic to refer to or something related to the FlexRay
2476 \textit{General Purpose Input/Output.} \newline{}
2477 Generic pin on a chip whose behavior (including whether it is an input or output pin) can be
2478 controlled (programmed) by the user at run time.
2481 \textit{H-Bridge.} \newline{}
2482 Mnemonic to refer to or something related to the H-Bridge hardware module. A H-Bridge is
2483 an electronic circuit that enables a voltage to be applied across a load in either direction.
2486 \textit{High-Power Output.} \newline{}
2487 Mnemonic to refer to or something related to the 10A, PWM, with current sensing, high-power
2488 output hardware module.
2491 \textit{Integrated Development Environment.} \newline{}
2492 An IDE is a Software application that provides comprehensive facilities to computer programmers
2493 for software development.
2496 \textit{Legacy Code Tool.} \newline{}
2497 Matlab tool that allows to generate source code for S-Functions given the descriptor of a C
2501 \textit{Model-Based Design.} \newline{}
2502 Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
2503 with designing complex control, signal processing and communication systems. \cite{modelbasedwiki2013}
2506 \textit{Matlab Executable.} \newline{}
2507 Type of binary executable that can be called within Matlab. In this document the common term
2508 used is `C MEX S-Function", which means Matlab executable written in C that implements a system
2512 \textit{Pulse-width modulation.} \newline{}
2513 Technique for getting analog results with digital means. Digital control is used to create a
2514 square wave, a signal switched between on and off. This on-off pattern can simulate voltages
2515 in between full on and off by changing the portion of the time the signal spends on versus
2516 the time that the signal spends off. The duration of ``on time" is called the pulse width or
2517 \textit{duty cycle}.
2519 \item[RPP] \textit{Rapid Prototyping Platform.} \newline{} Name of the
2520 developed platform, that includes both hardware and software.
2523 \textit{Serial Communication Interface.} \newline{}
2524 Serial Interface for communication through hardware's UART using communication standard RS-232.
2525 In this project it is also used as mnemonic to refer to or something related to the Serial
2526 Communication Interface hardware module.
2529 \textit{SD-Card.} \newline{}
2530 Mnemonic to refer to or something related to the SD-Card hardware module.
2533 \textit{SD-RAM.} \newline{}
2534 Mnemonic to refer to or something related to the SD-RAM hardware module for logging.
2537 \textit{Target Language Compiler.} \newline{}
2538 Technology and language used to generate code in Matlab/Simulink.
2541 \textit{Universal Asynchronous Receiver/Transmitter.} \newline{}
2542 Hardware circuitry that translates data between parallel and serial forms.
2549 % LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests
2550 % LocalWords: MCU UART microcontrollers DAC CCS simulink SPI GPIO
2551 % LocalWords: IOs HDK TMDSRM