-\newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
-\newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
-
\documentclass{scrreprt}
\usepackage{graphicx} % images and graphics
\usepackage[normalem]{ulem} % needed by strike
\usepackage{listings} % required for code blocks
\usepackage[urlcolor=blue,colorlinks=true,hyperfootnotes=false]{hyperref} % links
-\usepackage[utf8x]{inputenc} % char encoding
+\usepackage[utf8]{inputenc} % char encoding
\usepackage[bottom]{footmisc} % footnotes
\usepackage{todonotes}
+\usepackage[backend=biber,style=alphabetic,sortcites=true]{biblatex}
+\usepackage{tabularx}
+\addbibresource{rpp_simulink.bib}
% header
\usepackage[top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
% Prettify code documentation
\usepackage{color}
+\usepackage{colortbl}
+% \usepackage[table]{xcolor}
+
\definecolor{gray97}{gray}{.97}
\definecolor{gray75}{gray}{.75}
\definecolor{gray45}{gray}{.45}
\usepackage{caption}
\newcommand{\repo}{$\langle$repo$\rangle$}
+\newcommand{\superscript}[1]{\ensuremath{^{\textrm{\small#1}}}}
+\newcommand{\subscript}[1]{\ensuremath{_{\textrm{\small#1}}}}
+
+% Supported targets - to be used with \ifx\tgtId\tgtIdXXX
+\def\tgtIdTMSHDK{tms570\_hdk}
+\def\tgtIdRMHDK{rm48\_hdk}
+\def\tgtIdTMSRPP{tms570\_rpp}
+\def\tgtIdHydCtr{tms570\_hydctr}
+
+% Include target specific macros etc.
+\input{target_def}
\begin{document}
\begin{center}
% Upper part of the page
-\includegraphics[width=0.70\textwidth]{images/logos.png}\\[1cm]
-\textsc{\LARGE Costa Rica Institute of Technology}\\[0.5cm]
+\vspace{3cm}
+
+\includegraphics[width=0.35\textwidth]{images/cvut.pdf}\\[1cm]
\textsc{\LARGE Czech Technical University in Prague}\\[1.5cm]
% Document title
-\HRule \\[0.4cm]
-{ \huge \bfseries Code generation for automotive rapid prototyping platform using Matlab/Simulink}\\[0.4cm]
+\HRule
+\vspace{0.4cm}
+{\huge \bfseries Simulink code generation target for Texas~Instruments
+ \tgname{} platform\par}
+\vspace{0.8cm}
+{\Large Version for \tgtBoardName{} board\par}
+\vspace{0.4cm}
\HRule \\[1.5cm]
\end{titlepage}
% Title end
+\section*{Revision history}
+
+\noindent\begin{tabularx}{\linewidth}{|l|l|l|X|}
+ \rowcolor[gray]{0.9}\hline
+ Revision & Date & Author(s) & Comments \\ \hline
+
+ 0.1 beta & 2014-12-04 & Sojka, Horn & Initial version \\ \hline
+
+ 0.2 & 2015-02-16 & Sojka, Horn & Improvements, clarifications,
+ cleanup \\ \hline
+
+ 0.3 & 2015-03-31 & Sojka, Horn & Added sections
+ \ref{sec-changing-os}, \ref{sec:adding-new-funct} and
+ \ref{sec:mult-single-thre}. Minor
+ updates. \\ \hline
+
+ 0.4 & 2015-04-30 & Sojka, Horn & Added support for TMS570 HDK
+ platform. All RPP software
+ supports multiple
+ platforms by
+ recompilation. \\ \hline
+
+ 0.5 beta & 2015-07-03 & Sojka & Updated section \ref{sec:adding-new-funct}.
+ Added support for Eaton Hydraulics
+ Controller board (TMS570LS1227).
+ \\\hline
+
+ 0.5.5 & 2015-08-27 & Sojka, Horn & rpp-lib: HAL merged into DRV
+ layer, FreeRTOS upgraded to version 8.2.2.
+ \\\hline
+\end{tabularx}
+
\tableofcontents
\newpage
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
\pagestyle{fancy} {
- \fancyhead[R]{\includegraphics[width=30px]{images/cvut.png}}
+ \fancyhead[R]{\includegraphics[width=1cm]{images/cvut.pdf}}
\fancyhead[C]{}
\fancyhead[L]{\nouppercase \leftmark}
\fancyfoot[L]{Version \input{version.tex}}
\fancyfoot[C]{}
\fancyfoot[R]{Page {\thepage} of \pageref{LastPage}}
}
+\headheight=26pt
%\addtolength{\parskip}{\baselineskip} % Paragraph spacing
\chapter{Introduction}
\label{chap-introduction}
-This text is a documentation for a Rapid Prototyping Platform (RPP) project. It
-may serve as a guideline for development tools installation, Simulink Coder
-configuration, creation of new models as well as downloading the resulting
-firmware to the hardware. It can also be used as a reference for a testing tool,
-Matlab Simulink blocks and RPP Matlab Simulink Code generator. The document also
-provides an overall description of the hardware design and architecture of its
-control software.
+This text documents software part of Rapid Prototyping Platform (RPP)
+project for Texas Instruments \tgname{} safety microcontroller
+developed by Czech Technical University in Prague (CTU). The software
+consists of code generation target for Simulink Embedded Coder, a
+low-level run-time C library and a tool for interactive testing of
+hardware and software functionality.
+
+Originally, the RPP project was created for a custom TMS570-based board
+and the port to other platforms such as RM48 HDK and TMS570 HDK
+development kits. Porting to other platforms was done under a contract
+from Eaton Corporation.
+
+The document contains step-by-step instructions for installation of
+development tools, information about Simulink Coder configuration,
+describes how to create new models as well as how to download the
+resulting firmware to the hardware. It can also be used as a reference
+for the testing tool, Matlab Simulink blocks and RPP Matlab Simulink
+Code generator. Additionally, an overall description of the used
+hardware platform and the architecture of included software is
+provided.
\section{Background}
\label{sec-background}
-The Rapid Prototyping Platform is an ECU (Electronic Control Unit) designed for
-use in Automotive, thus requirements for Automotive communication interfaces,
-durable IO ports and analog-digital converters were applied.
-
-The ECU is controlled by TMS570LS5137ZWT MCU, which is an ARM Cortex R4 based
-microcontroller developed by Texas Instruments. This MCU contains several
-protective mechanisms (two cores in lockstep, error correction mechanisms for
-SRAM and Flash memory, voltage monitoring, etc.) to fulfill the requirements for
-safety critical applications. See~\cite{tms570ls31xtechnicalreferencemanual2012}
-for details.
+In this document, the term \emph{Rapid Prototyping Platform} denotes a
+hardware board and accompanying software. The hardware board is
+\tgtBoardName{} based on ARM Cortex R4 safety microcontroller
+\mcuname{}. This MCU contains several protective mechanisms (two cores
+in lockstep, error correction mechanisms for SRAM and Flash memory,
+voltage monitoring, etc.) to fulfill the requirements for safety
+critical applications. See~\cite{\tgrefman} for details.
In order to develop non-trivial applications for the RPP, an operating
-system is necessary. The RPP is based on FreeRTOS -- an opensource operating
-system real-time kernel, aimed not only at embedded systems. The FreeRTOS
-provides an API for creating and managing multiple tasks, scheduler, memory
-manager, semaphores, queues, mutexes, timers and lots of other features which can
-be used in the applications. See~\cite{usingthefreertos2009} for more details.
+system is necessary. The RPP is based on FreeRTOS -- a simple
+opensource real-time operating system kernel. The FreeRTOS provides an
+API for creating and managing and scheduling multiple tasks, memory
+manager, semaphores, queues, mutexes, timers and a few of other
+features which can be used in the applications.
+See~\cite{usingthefreertos2009} for more details.
Even with the operating system it is quite hard and non-intuitive to
-control the hardware directly. That is the point when abstraction
+manipulate the hardware directly. That is the point when abstraction
comes into the play. The RPP software is made of several layers
implementing, from the bottom to the top, low-level device drivers,
hardware abstraction for common functionality on different hardware
-and an API which is easy to use in applications. The operating
-system and the control software, can be compiled as a library and
-easily used in any project. More details about the library can be
-found in Chapter~\ref{chap-c-support-library} and in~\cite{michalhorn2013}.
-
-Because humans make mistakes and in safety critical applications any mistake can
-cause damage, looses of money or in the worst case even death of other people,
-the area for making mistakes has to be as small as possible. An approach called
-Model--based \cite{modelbasedwiki2013} development has been introduced. In
-Simulink the application is developed as a model made of interconnected blocks.
-Every block implements some functionality. For example one block
-receives a voltage from an analog--digital converter, provides the value as an
-input to another block which implements some clever algorithm and the product is
-passed as an input to another block, which sends the value as a CAN message to
-some other MCU. The final model can be simulated and tested even before the real
-hardware exists. Finally a C code is generated from the model by a Simulink Code
-Generator. The code can be compiled by the MCU compatible compiler and
-downloaded to the MCU Flash memory on the device. Because every block and code
-generated from the block has to pass a series of tests during their development,
-the area for making mistakes during the application development has
-been significantly reduced and developers can focus on the application instead of
-the hardware and control software implementation. More information about Code
-generation can be found in Chapter \ref{chap-simulink-coder-target}. For a
-reference about Matlab Simulink, Embedded Coder and Simulink Coder,
-refer to
+and an API which is easy to use in applications. The operating system
+and the basic software layers, can be compiled as a library and easily
+used in any project. More details about the library can be found in
+Chapter~\ref{chap-c-support-library} and in~\cite{michalhorn2013}.
+
+Because human beings make mistakes and in safety critical applications
+any mistake can cause damage, loos of money or in the worst case even
+death of other people, the area for making mistakes has to be as small
+as possible. An approach called Model-based development
+\cite{modelbasedwiki2013} has been introduced to reduce the
+probability of making mistakes. In model-based development, the
+applications are designed at higher level from models and the
+functionality of the models can be simulated in a computer before the
+final application/hardware is finished. This allows to discover
+potential errors earlier in the development process.
+
+One commonly used tool-chain for model-based development is
+Matlab/Simulink. In Simulink the application is developed as a model
+made of interconnected blocks. Every block implements some
+functionality. For example one block reads a value from an
+analog-to-digital converter and provides the value as an input to
+another block. This block can implement some clever algorithm and its
+output is passed to another block, which sends the computed value as a
+message over CAN bus to some other MCU. Such a model can be simulated
+and tested even before the real hardware is available by replacing the
+input and output blocks with simulated ones. Once the hardware is
+ready, C code is automatically generated from the model by a Simulink
+Coder. The code is then compiled by the MCU compatible compiler and
+downloaded to the MCU Flash memory on the device. Because every block
+and code generated from the block has to pass a series of tests during
+their development, the area for making mistakes during the application
+development has been significantly reduced and developers can focus on
+the application instead of the hardware and control software
+implementation. More information about code generation can be found in
+Chapter \ref{chap-simulink-coder-target}. For information about Matlab
+Simulink, Embedded Coder and Simulink Coder, refer to
\cite{embeddedcoderreference2013, ebmeddedcoderusersguide2013,
simulinkcoderreference2013, targetlanguagecompiler2013,
simulinkcoderusersguide2013, simulinkdevelopingsfunctions2013}.
+\section{Hardware description}
+\label{sec-hardware-description}
+
+\input{hwdesc}
+
\section{Software architecture}
\label{sec-software-architecture}
-The basic RPP software, also called the RPP Library, is structured
-into 5 layers, depicted in Figure~\ref{fig-layers}. The architecture
-design was driven by the following guidelines:
+
+The core of the RPP software is the so called RPP Library. This
+library is conceptualy structured into 5 layers, depicted in
+Figure~\ref{fig-layers}. The architecture design was driven by the
+following guidelines:
\begin{compactitem}
\item Top-down dependency only. No lower layer depends on anything from
upper layers.
- \item 1-1 layer dependency only. The top layer depends
-exclusively on the bottom layer, not on any lower level layer (except for a
-couple of exceptions).
- \item Each layer should provide a unified layer interface
-(\textsc{rpp.h}, \textsc{drv.h}, \textsc {hal.h}, \textsc{sys.h} and
-\textsc{os.h}), so top layers depends on that layer interface and not on
-individual elements from that layer. \end{compactitem}
-
-\begin{figure}[H]
+% \item 1-1 layer dependency only. The top layer depends
+% exclusively on the bottom layer, not on any lower level layer (except for a
+% couple of exceptions).
+\item Each layer should provide a unified layer interface
+ (\texttt{rpp.h}, \texttt{drv.h}, \texttt {hal.h}, \texttt{sys.h} and
+ \texttt{os.h}), so that higher layers depend on the lower layer's interface
+ and not on individual elements from that layer.
+\end{compactitem}
+
+\begin{figure}
\begin{center}
\noindent
\includegraphics[width=250px]{images/layers.pdf}
\end{figure}
As a consequence of this division the source code files and interface files are
-placed in private directories like \textsc{drv/din.h}. With this organization
+placed in private directories like \texttt{drv/din.h}. With this organization
user applications only needs to include the top layer interface files (for
-example \textsc{rpp/rpp\_can.h}) to be able to use the selected library API.
+example \texttt{rpp/rpp\_can.h}) to be able to use the selected library API.
The rest of the section provides basic description of each layer.
\subsection{Operating System layer}
\label{sec-operating-system-layer}
-This is an operating system interchangeable layer, containing the FreeRTOS
-source files. The system can be easily replaced by another version thanks to
-this layer. For example it is possible to compile the library for Linux (using
-POSIX version of the FreeRTOS), which can be desirable for some testing. The
-source files can be found in the \textsc{$\langle$rpp\_lib$\rangle$/os}
-folder.
+This is an interchangeable operating system (OS) layer containing the
+FreeRTOS source files. The system can be easily replaced by another
+version. For example it is possible to compile the RPP library for
+Linux (using POSIX version of the FreeRTOS), which can be desirable
+for some testing. The source files can be found in the
+\texttt{$\langle$rpp\_lib$\rangle$/os} folder.
The following FreeRTOS versions are distributed:
\begin{description}
- \item[6.0.4\_posix] POSIX version, usable for compilation of the library
-for Linux system.
- \item[7.0.2] Prefered version of the FreeRTOS, distributed by
-Texas Instruments. This version has been tested and is used in the current
-version of the library.
- \item[7.4.0] Newest version distributed by the Texas Instruments.
- \item[7.4.2] Newer version available from FreeRTOS pages. Slightly
-modified to run on TMS570 MCU.
+\item[6.0.4\_posix] POSIX version, usable for compilation of the
+ library for Linux system.
+\item[8.2.2] Currently used FreeRTOS version. This is the version
+ downloaded from FreeRTOS.org with changes in directory structure.
+ Namely, include files have added the \emph{os/} prefix and platform
+ dependent code (portable) for \tgname{} is copied to the same
+ directory as platform independent code.
\end{description}
\subsection{System Layer}
\label{sec-system-layer}
This layer contains system files with data types definitions, clock definitions,
-interrupts mapping, MCU startup sequence, MCU selftests, and other low level
+interrupts mapping, MCU start-up sequence, MCU selftests, and other low level
code for controlling some of the MCU peripherals. The source files can be found
-in \textsc{$\langle$rpp\_lib$\rangle$/rpp/src/sys}, the header files can
-be found in \textsc{$\langle$rpp\_lib$\rangle$/rpp/include/sys}
+in \texttt{$\langle$rpp\_lib$\rangle$/rpp/src/sys}, the header files can
+be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/sys}
folder.
-Large part of this layer was generated by the HalCoGen tool \ref{sec-halcogen}.
-
-\subsection{HAL abstraction layer}
-\label{sec-hal-abstraction-layer}
-Hardware Abstraction Layer (HAL) creates an abstraction over the real hardware.
-For example imagine an IO port with 8 pins. First four pins are connected to the
-MCU directly to GPIO pins, another four pins are connected to an external
-integrated circuit, communicating with the MCU via SPI. It would be annoying to
-have to remember which group is which and to have two sets of control functions
-for one peripheral. This layer maps every pin of the port to a control function
-from the System Layer, groups the pins together, names them in a unified style
-and provides common read, write and configure functions.
-
-As a result, the higher layers do not have to know anything about the wiring of
-the peripherals, they can just call read, write or configure function with a pin
-name as a parameter and the HAL handles all the details.
-
-The source files can be found in
-\textsc{$\langle$rpp\_lib$\rangle$/rpp/src/hal} and the header files can
-be found in \textsc{$\langle$rpp\_lib$\rangle$/rpp/include/hal} folder.
+Large part of this layer was generated by the HalCoGen tool (see
+Section~\ref{sec-halcogen}). Some files were then modified by hand.
\subsection{Drivers layer}
\label{sec-drivers-layer}
-The Drivers layer contains code for controlling the RPP peripherals. The layer
-benefits from the lower layers thus it is not too low level, but still there are
-some peripherals like ADC or H-bridge, which needs some special procedure for
-initialization and running, that would not be very intuitive for the user. For
-example the H-bridge needs a watchdog reset task to be started before the bridge
-is enabled.
+The Drivers layer contains code for controlling the RPP peripherals.
+Typically, it contains code implementing IRQ handling, software
+queues, management threads, etc. The layer benefits from the lower
+layer thus it is not too low level, but still there are some
+peripherals like ADC, which need some special procedure for
+initialization and running, that would not be very intuitive for the
+typical end user.
The source files can be found in
-\textsc{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
-be found in \textsc{$\langle$rpp\_lib$\rangle$/rpp/include/drv} folder.
+\texttt{$\langle$rpp\_lib$\rangle$/rpp/src/drv} and the header files can
+be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/drv} folder.
\subsection{RPP Layer}
\label{sec-rpp-layer}
-The RPP Layer is the highest layer of the control software. This layer provides
-an easy to use set of functions for every peripheral and requires only basic
-knowledge about them. For example, to control the H-bridge,
-the user can just call \textsc{rpp\_hbr\_init()} function to enable the H-bridge
-and the function calls a sequence of Drivers layer functions to start the
-Watchdog and configure the peripheral.
+The RPP Layer is the highest layer of the library. It provides an easy
+to use set of functions for every peripheral and requires only basic
+knowledge about them. For example, to use the ADC, the user can just
+call \texttt{rpp\_adc\_init()} function and it calls a sequence of
+Driver layer functions to initialize the hardware and software.
The source files can be found in
-\textsc{$\langle$rpp\_lib$\rangle$/rpp/src/rpp} and the header files can
-be found in \textsc{$\langle$rpp\_lib$\rangle$/rpp/include/rpp}.
-
-\section{Hardware description}
-\label{sec-hardware-description}
-
-This section provides reference documentation for the RPP board:
-
-%%TODO: operating conditions as a reference to the Ti documentation
-
-\begin{compactitem}
- \item Layout description.
- \item Connectors pinout.
- \item Modules capabilities and features.
-\end{compactitem}
-
-\subsection{Layout description}
-\label{sec-layout-description}
-The RPP board has been designed with strict Automotive standards and safety in
-mind. The components and pins are placed in sections and wires are routed in a
-way to avoid any significant electromagnetic interference.
-
-As can be seen on Figure \ref{board_photo}, the high power output logic is
-placed in the top left corner, the low power output logic is placed on the
-bottom left corner, while the communication logic is placed on the top right
-corner. In the middle there is the only one button available, the reset button
-and below it is placed the TMS570 MCU itself. In the bottom right corner there
-are components of analog inputs.
-
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=300px]{images/board-photo.png}
-\caption{The RPP board (signal connector missing).}
-\label{board_photo}
-\end{center}\end{figure}
-
-
-\subsection{Connectors pinout}
-\label{sec-connector-pinout}
-The pinout of the board, described by the Figure \ref{pinout}, follows the
-layout described in the previous section. The side connectors for communication
-(24 pins), signals (56 pins) and power (24 pins) are automotive approved
-humidity resistant connectors.
-
-\begin{figure}[H]
-\advance\leftskip-1cm
-\noindent
-\includegraphics[width=530px]{images/pinout.pdf}
-\caption{The RPP connectors pinout.}
-\label{pinout}
-\end{figure}
-
-\subsection{Modules description}
-\label{sec-modules-description}
-This section enumerates the capabilities of the hardware modules from Software
-perspective. The block diagram of the modules can be seen in Figure
-\ref{blocks}.
-
-\begin{figure}[H]
-\advance
-\leftskip-1cm
-\noindent
-\includegraphics[width=500px]{images/blocks.pdf}
-\caption{The RPP layer modules.}
-\label{blocks}
-\end{figure}
-
-\subsubsection{Logic IO}
-\label{sec-logic-io}
-
-\paragraph{Digital Inputs (DIN)}
-\label{par-digital-inputs}
-\begin{compactitem}
- \item 16 pins available on Signal Connector.
- \item Pins 8-15 status can be read via GPIO using configurable
-threshold. \newline{} Pins 8-11 use variable threshold B and pins 12-15 use
-variable threshold A.
- \item Variable threshold is a DAC chip MCP4922.
- \item All pins are read at once via SPI (fixed threshold) using chip
-MC33972.
- \item 0-7 are programmable pins and can be set to pull-up or
-pull-down. 8-15 are pull-down only.
- \item All pins can be set to be active or tri-stated.
- \item All pins can be set to trigger interrupt.
- \item On-line diagnostic of broken wire.
-\end{compactitem}
-
-\paragraph{Digital Outputs (LOUT)}
-\label{par-digital-outputs}
-\begin{compactitem}
- \item 8 pins available on Signal Connector.
- \item Pins for logic output only, up to 100mA.
- \item All pins are set at once using a chip through SPI.
-\end{compactitem}
-
-\paragraph{Analog Input (ADC)}
-\label{par-analog-input}
-\begin{compactitem}
- \item 12 channels available.
- \item Differential inputs, thus 24 pins available on Signal Connector.
- \item Range for 0-20 volts.
- \item 12 bits resolution.
- \item Using CPU ADC.
-\end{compactitem}
-
-\paragraph{Analog Output (DAC)}
-\label{par-analog-output}
-\begin{compactitem}
- \item 4 pins available on Signal Connector.
- \item Output range is 0-12 volts.
- \item Using 2 x MCP4922 DACs controlled using SPI.
- \item Resolution is 12 bits. But because of amplification and voltage
-reference not all range is used.
-\end{compactitem}
-
-\subsubsection{Power Output}
-\label{sec-power-output}
-\paragraph{H-Bridge (HBR)}
-\label{par-hbr}
-\begin{compactitem}
- \item 1 port (2 pins) available on Power Connector.
- \item Communication is done through SPI.
- \item H-Bridge can be enabled or disabled.
- \item Current direction can be set.
- \item PWM control with 1\% resolution change of the duty cycle.
- \item Port can drive load up to 10A.
-\end{compactitem}
-
-\paragraph{Power Output (MOUT)}
-\label{par-power-output}
-\begin{compactitem}
- \item 6 pins available on Power Connector.
- \item Pins can drive a load up to 2A. Push/Pull.
- \item Pins are set using 6 CPU output GPIOs. Diagnostic are read using 6
-externally pulled-up open-drain input GPIOs.
- \item On-line diagnostics. Driver chip will pull-down the corresponding
-diagnostic pin on the CPU.
-\end{compactitem}
-
-\paragraph{High-Power Output (HOUT)}
-\label{par-high-power-output}
-\begin{compactitem}
- \item 6 pins available on Power Connector.
- \item Pins can be set ON/OFF.
- \item Pins can drive a load up to 10A with PWM.
- \item System can read analog values of current flowing (IFBK).
- \item System can read diagnostics values (DIAG). Detection of a fault
-condition.
-\end{compactitem}
-
-\subsubsection{Communication}
-\label{sec-communication}
-\paragraph{CAN bus (CAN)}
-\label{par-can}
-\begin{compactitem}
- \item 3 ports available (CAN uses differential signaling) thus 6 pins
-are available on Communication connector.
- \item High speed.
- \item Recover from error.
- \item Detection of network errors.
-\end{compactitem}
-
-\paragraph{Local Interconnect Network (LIN)}
-\label{par-lin}
-\begin{compactitem}
- \item 2 ports/pins available on Communication Connector.
- \item Only first port can be used when using the SCI. Second port is
-shared with SCI.
-\end{compactitem}
-
-\paragraph{FlexRay (FR)}
-\label{par-flexray}
-\begin{compactitem}
- \item 2 ports available. FlexRay uses differential signaling thus 4 pins
-are available on Communication Connector.
-\end{compactitem}
-
-\paragraph{Serial Comm. Interface (SCI)}
-\label{par-sci}
-\begin{compactitem}
- \item 1 port available inside the box on SCI connector (4 pins).
- \item Variable baud rate. Tested on 9600 and 115200.
- \item RS232 standard compatible.
-\end{compactitem}
-
-\paragraph{Ethernet (ETH)}
-\label{par-eth}
-\begin{compactitem}
- \item 1 port available. Standard Ethernet connector available inside box.
-\end{compactitem}
-
-\subsubsection{Data storage/logging}
-\label{sec-data-storage}
-\paragraph{External Memory SD-RAM (SDR)}
-\label{par-external-memory}
-\begin{compactitem}
- \item 64MB (currently installed) external RAM used for logging. Maximal
-supported capacity is 256MB.
- \item Memory test routine available with test
-Software.
-\end{compactitem}
-
-\paragraph{SD Card (SDC)}
-\label{par-sd-card}
-\begin{compactitem}
- \item Standard SD-Card connector or microSD connector available inside box.
- \item Communication done using SPI.
-\end{compactitem}
+\texttt{$\langle$rpp\_lib$\rangle$/rpp/src/rpp} and the header files can
+be found in \texttt{$\langle$rpp\_lib$\rangle$/rpp/include/rpp}.
\section{Document structure}
\label{sec-document-structure}
The structure of this document is as follows:
-Chapter~\ref{chap-getting-started} gets you started using the RPP.
-Chapter~\ref{chap-c-support-library} describes the RPP library.
-Chapter~\ref{chap-simulink-coder-target} covers the Simulink code
-generation target and finally Chapter~\ref{chap-rpp-test-software}
-documents a tool for interactive testing of RPP functionality.
+Chapter~\ref{chap-getting-started} gets you started using the RPP
+software. Chapter~\ref{chap-c-support-library} describes the RPP
+library. Chapter~\ref{chap-simulink-coder-target} covers the Simulink
+code generation target and finally
+Chapter~\ref{chap-rpp-test-software} documents a tool for interactive
+testing of the RPP functionality.
\chapter{Getting started}
\label{chap-getting-started}
\section{Software requirements}
\label{sec-software-requirements}
-The RPP software stack has been developed to be functional on Windows and
-Linux platforms. The following subsections mention the recommended
-versions of the required software tools/packages.
+The RPP software stack can be used on Windows and Linux platforms. The
+following subsections mention the recommended versions of the required
+software tools/packages.
\subsection{Linux environment}
\label{sec-linux-environment}
\item GtkTerm 0.99.7-rc1
\item TI Code Composer Studio 5.5.0.00077
\item Matlab 2013b 64b with Embedded Coder
- \item HalCoGen 4.00 (optionally)
- \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
- \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
- \item Git 1.7.10.4 (optionally)
+ \item HalCoGen 4.00 (optional)
+ \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
+ \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
+ \item Git 1.7.10.4 (optional)
\end{itemize}
\subsection{Windows environment}
\item Bray Terminal v1.9b
\item TI Code Composer Studio 5.5.0.00077
\item Matlab 2013b 64b with Embedded Coder
- \item HalCoGen 4.00 (optionally)
- \item Doxygen 1.8.4 (optionally, see Section \ref{sec-compiling-api-documentation})
- \item Uncrustify 0.59 (optionally, see Section \ref{sec-compilation})
- \item Git 1.9.4.msysgit.2 (optionally)
+ \item HalCoGen 4.00 (optional)
+ \item Doxygen 1.8.4 (optional, see Section \ref{sec-compiling-api-documentation})
+ \item Uncrustify 0.59 (optional, see Section \ref{sec-compilation})
+ \item Git 1.9.4.msysgit.2 (optional)
\end{itemize}
-\section{Software and tools}
+\section{Software tools}
\label{sec-software-and-tools}
+This section covers tool which are needed or recommended for work with
+the RPP project.
+
\subsection{TI Code Composer Studio}
\label{sec-ti-ccs}
Code Composer Studio (CCS) is the official Integrated Development Environment
(IDE) for developing applications for Texas Instruments embedded processors. CCS
-is multiplatform Software based on
-Eclipse Open Source IDE.
+is multiplatform software based on
+Eclipse open source IDE.
CCS includes Texas Instruments Code Generation Tools (CGT)
\cite{armoptimizingccppcompiler2012, armassemblylanguagetools2012}
-(compiler, linker, etc). Simulink code generation requires the CGT to be
-available in the system, and thus, even if no library development
-will be done or the IDE is not going to be used CCS is still required.
+(compiler, linker, etc). Simulink code generation target requires the
+CGT to be available in the system, and thus, even if no library
+development will be done or the IDE is not going to be used CCS is
+still required.
You can find documentation for CGT compiler in \cite{armoptimizingccppcompiler2012} and
for CGT archiver in \cite{armassemblylanguagetools2012}.
\subsubsection{Installation on Linux}
\label{sec-installation-on-linux}
-Download CCS for Linux from:
-
- \begin{quotation}
+Download CCS for Linux from:\\
\url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
- \end{quotation}
-Once downloaded, add executable permission to the installation file and launch
-the installation by executing it. Installation must be done as root in order to
-install a driver set.
+Once downloaded, add executable permission to the installation file
+and launch the installation by executing it. Installation must be done
+by the root user in order to install a driver set.
\lstset{language=bash}
\begin{lstlisting}
\end{lstlisting}
The first launch on 64bits systems might fail. This can happen because CCS5 is
-32b application and thus requires 32bits libraries:
+a 32 bit application and thus requires 32 bit libraries. They can be
+installed by:
\lstset{language=bash}
\begin{lstlisting}
\lstset{language=bash}
\begin{lstlisting}
-nano
-<ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
+nano <ccs>/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_<version>/plugin_customization.ini
\end{lstlisting}
-And change key \textsc{org.eclipse.ui/showIntro} to false.
+And change key \texttt{org.eclipse.ui/showIntro} to \texttt{false}.
\subsubsection{Installation on Windows}
\label{sec-installation-on-windows}
-The installation for Windows is more straightforward than the previous procedure
-for Linux.
-
-Download CCS for Windows from:
-
- \begin{quotation}
+Installation for Windows is more straightforward than the installation
+procedure for Linux. Download CCS for Windows from:\\
\url{http://processors.wiki.ti.com/index.php/Category:Code\_Composer\_Studio\_v5}
- \end{quotation}
Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.
\subsubsection{First launch}
\label{sec-first-launch}
-If no other licence is available, choose ``FREE License -- for use with XDS100
-JTAG Emulators'' from the licensing options. Code download for the board is using
-that particular hardware.
+If no other licence is available, choose ``FREE License -- for use
+with XDS100 JTAG Emulators'' from the licensing options. Code download
+for the board uses the XDS100 hardware.
\subsection{Matlab/Simulink}
\label{sec-matlab-simulink}
Matlab Simulink is a set of tools, runtime environment and development
environment for Model--Based \cite{modelbasedwiki2013} applications development,
-simulations and generation code for target platforms. Supported Matlab Simulink
+simulations and code generation for target platforms. Supported Matlab Simulink
version is R2013b for 64 bits Linux and Windows. A licence for an Embedded Coder is
-necessary to be able to generate code from models, containing RPP blocks.
+necessary to be able to generate code from Simulink models, containing RPP blocks.
\subsection{HalCoGen}
\label{sec-halcogen}
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.
The tool is available for Windows at
- \begin{quotation}
-\url{http://www.ti.com/tool/halcogen?keyMatch=halcogen&tisearch=Search-EN}
- \end{quotation}
+\begin{quotation}
+\url{http://www.ti.com/tool/halcogen}
+\end{quotation}
-The HalCoGen has been used in early development stage to generate the base code for some of the peripheral. The trend is to not to use the HalCoGen any more, because the generated code is not reliable enough for safety application. Anyway it is sometimes helpful to use it as a reference.
+The HalCoGen has been used in early development stage of the RPP
+project to generate the base code for some of the peripheral. The
+trend is to not to use the HalCoGen any more, because the generated
+code is not reliable enough for safety critical applications. Anyway it is
+sometimes helpful to use it as a reference.
-The HalCoGen is distributed for Windows only, but can be run on Linux with Wine 1.6.2.
+The HalCoGen is distributed for Windows only, but can be run on Linux
+under Wine (tested with Wine version 1.6.2).
\subsection{GtkTerm and Bray Terminal}
\label{sec-gtkterm-bray-terminal}
Most of the interaction with the board is done through a RS-232 serial
-connection. The terminal Software used for communication is called GtkTerm for
+connection. The terminal software used for communication is called GtkTerm for
Linux and Bray terminal for Windows.
To install GtkTerm execute:
\end{lstlisting}
The Bray Terminal does not require any installation and the executable file is
-available at
-
-\begin{quotation}
+available at\\
\url{https://sites.google.com/site/terminalbpp/}
-\end{quotation}
\subsection{C Compiler}
\label{sec-c-compiler}
sudo apt-get install gcc
\end{lstlisting}
-For Windows, the C/C++ compiler is a part of Windows SDK, which installation
-file is available at
-
-\begin{quotation}
+For Windows, the C/C++ compiler is a part of Windows SDK, which is available from\\
\url{http://www.microsoft.com/en-us/download/details.aspx?id=8279}
-\end{quotation}
-\section{Project Installation}
+\section{Project installation}
\label{sec-project-installation}
-The RPP project is distributed in three packages and a standalone pdf file,
-containing this documentation. Every package is named like
-\textsc{package\_name-version.zip}. The three packages are:
+The RPP software is distributed in three packages and a standalone pdf
+file containing this documentation. Every package is named like
+\emph{$\langle$package\_name$\rangle$-version.zip}. The three packages
+are:
\begin{description}
- \item[rpp-lib] Contains the source codes of the RPP Library,
-described in Chapter \ref{chap-c-support-library}. If you want to make any
-changes in the drivers or RPP API, this library has to be compiled and linked
-with the other two applications in the other two packages. The compile procedure
-can be found in Section \ref{sec-compilation}.
- \item[rpp-simulink] Contains source codes of the Matlab Simulink blocks, demo
-models and scripts for downloading the resulting firmware to the target from the
-Matlab Simulink. Details can be found in Chapter \ref{chap-simulink-coder-target}.
-
-The package also contains the binary file of the RPP Library and all headers and
-other files necessary for building and downloading the models.
- \item[rpp-test-sw] Contains an application for rapid testing and direct
-controlling the RPP board over the Serial Interface.
-
-The package also contains the binary file of the RPP Library and all headers and
-other files necessary for building and downloading the application.
+\item[rpp-simulink] Contains the source code of Matlab Simulink
+ blocks, demo models and scripts for downloading the generated
+ firmware to the target board from Matlab/Simulink. Details can be
+ found in Chapter \ref{chap-simulink-coder-target}.
+
+ The package also contains the binary of the RPP Library and all its
+ headers and other files necessary for building and downloading
+ Simulink models.
+\item[rpp-test-sw] Contains an application for interactive testing and
+ control of the \tgtBoardName{} board over the serial interface. Details can be
+ found in Chapter~\ref{chap-rpp-test-software}.
+
+ The package also contains the binary of the RPP Library and all
+ headers and other files necessary for building and downloading the
+ application.
+\item[rpp-lib] Contains the source code of the RPP library, described
+ in Chapter \ref{chap-c-support-library}. If you want to make any
+ changes in the drivers or the RPP API, this library has to be
+ compiled and linked with applications in the other two packages.
+ Library compilation is described in Section \ref{sec-compilation}.
\end{description}
-\subsection{rpp-lib}
-\label{sec-rpp-lib-installation}
-You may not need to deal with this package at all because the compiled library is
-distributed with the applications. But in case of contributions or further
-development done by your team, this subsection describes how to open the project
-in development environment and how to use the resulting static library in an
-application.
+The following sections describe how to start working with individual
+packages.
-\begin{enumerate}
- \item Unzip the \textsc{rpp-lib-version.zip} file.
- \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
- \item Follow the procedure for openning the projects in CCS in Section
-\ref{sec-openning-of-existing-project} and open the rpp-lib project. \item
-Compile the static library using a procedure in Section \ref{sec-compilation}.
-The binary file will appear in the project root directory.
- \item Copy the binary file to the application, where you want to test
-and use the new library version.
- \begin{itemize}
- \item In the rpp-simulink application the library binary file is
-present in \textsc{rpp/lib} folder.
- \item In the rpp-test-sw application the library binary file is
-present in \textsc{rpp-lib} folder.
- \end{itemize}
-\end{enumerate}
+\ifx\tgtId\tgtIdTMSRPP
+\subsection{Getting sources from git repository}
+\begin{verbatim}
+git clone --recursive git@rtime.felk.cvut.cz:jenkicar/rpp-simulink
+\end{verbatim}
+If you get release packages, follow the instructions in the next sections.
+\fi
\subsection{rpp-simulink}
\label{sec-rpp-simulink-installation}
-If you want to access the demo models or build your own models using the RPP blocks, if
-you want to generate a C code from the models, build it to a binary firmware for the RPP board and download it to the real hardware, follow these steps.
+This section describes how to install the rpp-simulink project, which
+is needed to try the demo models or to build your own models that use
+the RPP blocks.
\begin{enumerate}
- \item Unzip the \textsc{rpp-simulink-version.zip} file.
- \item Follow the procedure in Section
-\ref{sec-configuration-simulink-for-rpp} for configuring the Matlab Simulink for
-the RPP project.
- \item Follow the procedure in Section \ref{sec-crating-new-model} for
-instruction about creating your own model which will be using the RPP Simulink
-blocks or follow the instructions in Section \ref{sec-running-model-on-hw}
-for downloading the firmware to the real RPP hardware.
+\item Unzip the \texttt{rpp-simulink-version.zip} file.
+\item Follow the procedure from Section
+ \ref{sec-configuration-simulink-for-rpp} for configuring Matlab
+ Simulink for the RPP project.
+\item Follow the procedure from Section \ref{sec-crating-new-model}
+ for instructions about creating your own model which will use the
+ RPP Simulink blocks or follow the instructions in
+ Section~\ref{sec-running-model-on-hw} for downloading the firmware to the RPP hardware.
\end{enumerate}
\subsection{rpp-test-sw}
\label{sec-test-sw-installation}
-If you want a direct control over the hardware for example to test your
-modifications in the RPP Library follow this procedure for the rpp-test-sw
-application installation.
+This section describes how to install and run the application that
+allows you to interactively control the RPP hardware. This can be
+useful, for example, to test your modifications of the RPP library.
\begin{enumerate}
- \item Unzip the \textsc{rpp-test-sw-version.zip} file.
+ \item Unzip the \texttt{rpp-test-sw-version.zip} file.
\item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
- \item Follow the procedure for openning the projects in CCS in Section
-\ref{sec-openning-of-existing-project} and open both, the \textsc{rpp-lib} and
-the \textsc{rpp-test-sw} projects.
- \item Right click on the \textsc{rpp-test-sw} project in the
-\textsc{Project Explorer} and select \textsc{Build Project}. Ignore any errors
-in the \textsc{rpp-lib} project.
- \item Follow the instructions in Section
-\ref{sec-running-software-on-hw} to download, debug and run the software on the
-target hardware. CCS will ask you wether to proceed with the detected errors in
-\textsc{rpp-lib} project. Do not mind them and click to the \textsc{Proceed} button
-to continue.
+ \item Import the \texttt{rpp-test-sw} project as described in
+ Section \ref{sec-openning-of-existing-project}.
+ \item Right click on the \texttt{rpp-test-sw} project in the
+ \textsc{Project Explorer} and select \textsc{Build Project}.
+ \item Follow the instructions in
+ Section~\ref{sec-running-software-on-hw} to download, debug and
+ run the software on the target hardware.
+\end{enumerate}
+
+\subsection{rpp-lib}
+\label{sec-rpp-lib-installation}
+
+This section describes how to open the rpp-lib project in Code
+Composer Studio and how to use the resulting static library in an
+application. This is only necessary if you need to modify the library
+for some reason.
+
+\begin{enumerate}
+ \item Unzip the \texttt{rpp-lib-version.zip} file.
+ \item Open the Code Composer Studio (see Section \ref{sec-ti-ccs}).
+ \item Import the rpp-lib project from directory
+ \texttt{rpp-lib-XXX/build/\tgtId} as described in
+ Section~\ref{sec-openning-of-existing-project}.
+ \item Compile the static library by selecting \textsc{Project
+ $\rightarrow$ Build Project} (see Section
+ \ref{sec-compilation} for more information). The compiled
+ library \texttt{rpp-lib.lib} and file
+ \texttt{Makefile.config} will appear in the
+ \texttt{rpp-lib-XXX} directory.
+ \item Either copy the compiled library and the content of the
+ \texttt{rpp/include} directory to the application, where you
+ want to use it or use the library in place, as described in
+ Section~\ref{sec:creating-new-project}.
+ \begin{itemize}
+ \item In the rpp-simulink application the library is located in
+ the \texttt{rpp/lib} folder.
+ \item In the rpp-test-sw application the library is located in
+ the \texttt{rpp-lib} folder.
+ \end{itemize}
\end{enumerate}
\section{Code Composer Studio usage}
\label{sec-code-composerpstudio-usage}
-\subsection{Opening of existing project}
+\subsection{Opening an existing project}
\label{sec-openning-of-existing-project}
-The project opening procedure is similar to standard Eclipse project opening.
+The procedure for opening a project is similar to opening a project in
+the standard Eclipse IDE.
\begin{enumerate}
\item Launch Code Composer Studio
\item Select \textsc{File$\rightarrow$Import}
\item In the dialog window select \textsc{Code Composer
-Studio$\rightarrow$Existing CCS Eclipse project} as an import source as depicted
-in Figure \ref{fig-import-project}.
- \item In the next dialog window click on
-\textsc{Browse} button and find the root directory of the project.
- \item Select the requested project in the \textsc{Discovered project}
-section so that the result looks like in Figure \ref{fig-select-project}.
- \item Click on \textsc{Finish} button.
+ Studio$\rightarrow$Existing CCS Eclipse project} as an import
+ source (see Figure \ref{fig-import-project}).
+ \item In the next dialog window click on \textsc{Browse} button
+ and find the root directory of the project.
+ \item Select the requested project in the \textsc{Discovered
+ project} section so that the result looks like in Figure
+ \ref{fig-select-project}.
+ \item Click the \textsc{Finish} button.
\end{enumerate}
\begin{figure}[H]\begin{center}
\label{fig-select-project}
\end{center}\end{figure}
+\newpage
\subsection{Creating new project}
-\label{sec-creating-new-project}
-In \textsc{\repo/rpp/lib/apps/} there are two RPP based
-applications, \textsc{helloworld} and \textsc{helloworld\_posix}, that are
-already configured for the RPP Library. It is advised that new applications use
-this project as a foundation.
+\label{sec:creating-new-project}
+Follow these steps to create an application for \tgname{} MCU compiled with
+CGT.
-To create a new application copy this directory and rename it. Now open files
-\textsc{.project}, \textsc{.cproject} and \textsc{.ccsproject} (if available)
-and change any occurrence of the work \textsc{helloworld}
-with the name of your project. Use lower case ASCII letters and underscores only.
+\begin{compactenum}
+\item Create a new empty CCS project. Select \mcuname{} device, XDS100v2
+ connection and set Linker command file to
+ \texttt{rpp-lib/build/\tgtId/\ldscriptname}.
-\textbf{Steps to configure a new CCS (ARM, using CGT) RPP application:}
+ \noindent\includegraphics[scale=0.45]{images/base_1.png}
-\begin{compactenum}
- \item Create a new CCS project. \newline{}
-\noindent\includegraphics[width=400px]{images/base_1.png}
- \item Create a normal folder \textsc{include}.
- \item Create a source folder \textsc{src}.
- \item Add common \textsc{.gitignore} to the root of that project:
-\lstset{language=}
+\item In \textsc{Project Explorer}, create normal folders
+ named \texttt{include} and \texttt{src}.
+
+\item If you use Git version control system, add \texttt{.gitignore}
+ file with the following content to the root of that project:
+ \lstset{language=}
\begin{lstlisting}
Debug
Release
.settings/*
\end{lstlisting}
+
+ \newpage
+\item In project \textsc{Properties}, add new variable of type
+ \texttt{Directory} named \texttt{RPP\_LIB\_ROOT} and set it to the
+ rpp-lib directory
+ root.
+
+ \noindent\includegraphics[scale=.45]{images/base_2.png}
+
+\item Configure the compiler \#include search path to contain
+ project's \texttt{include} directory, \penalty-100
+ \texttt{\$\{RPP\_LIB\_ROOT\}/os/8.2.2/include} and
+ \texttt{\$\{RPP\_LIB\_ROOT\}/rpp/include}, in that order.
+
+ \includegraphics[scale=.43]{images/base_5.png}
+
+ \newpage
+\item Add \texttt{\$\{RPP\_LIB\_ROOT\}/rpp-lib.lib} to the list of
+ linked libraries before the runtime support library
+ (\texttt{\tgtRtlib}).
+
+ \noindent\includegraphics[scale=.45]{images/base_3.png}
+
+\item Configure the compiler to allow GCC extensions.
+
+ \noindent\includegraphics[scale=.45]{images/base_6.png}
+
\newpage
- \item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this
-repository branch root.\newline{}
-\noindent\includegraphics[width=400px]{images/base_2.png}
- \item Add \textsc{rpp-lib.lib} static library to linker libraries and
-add \textsc{RPP\_LIB\_ROOT} to the library search path.\newline{}
-\noindent\includegraphics[width=400px]{images/base_3.png}
-\newpage
- \item Configure linker to retain \textsc{.intvecs} from RPP static
-library.\newline{} \noindent\includegraphics[width=350px]{images/base_4.png}
- \item Configure compiler to include local includes, OS includes for
-TMS570 and RPP includes, in that order\todo{Add lwip include paths as
-well}.\newline{}
-\noindent\includegraphics[width=350px]{images/base_5.png}
-\newpage
- \item Configure compiler to allow GCC extensions.\newline{}
-\noindent\includegraphics[width=400px]{images/base_6.png}
- \item Import and link (\underline{do not copy!}) linker file and board
-upload descriptor.\newline{}
-\noindent\includegraphics[width=200px]{images/base_7.png}
-\end{compactenum}
+\item Create \texttt{main.c} file with the following content:
+\begin{lstlisting}[language=C]
+#include <rpp/rpp.h>
-\textbf{Steps to configure a new GCC (x86(\_64)) RPP simulated application:}
+int main(void)
+{
+ rpp_init();
+ rpp_sci_printf("Hello world\n");
+ vTaskStartScheduler();
+ return 0; /* not reached */
+}
-\begin{compactenum}
- \item Create a new managed C project that uses Linux GCC toolchain.
- \item Create a source folder \textsc{src}. Link all files from original
-CCS application to this folder.
- \item Create a normal folder \textsc{include}. Create a folder
-\textsc{rpp} inside of it.
- \item Add common \textsc{.gitignore} to the root of that project:
-\lstset{language=}
-\begin{lstlisting}
-Debug
-Release
-.settings/*
+void vApplicationMallocFailedHook()
+{}
+void vApplicationStackOverflowHook()
+{}
\end{lstlisting}
-\newpage
- \item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this
-repository branch root.\newline{}
-\noindent\includegraphics[width=400px]{images/base_posix_1.png}
- \item Configure compiler to include local includes, CCS application
-includes, OS includes for POSIX and RPP includes, in that order.\newline{}
-\noindent\includegraphics[width=400px]{images/base_posix_2.png}
-\newpage
- \item Add \textsc{rpp} and \textsc{pthread}to linker libraries and add
-\textsc{RPP\_LIB\_ROOT} to the library search path.\newline{}
-\noindent\includegraphics[width=400px]{images/base_posix_3.png}
+
+\item Compile the application by e.g. \textsc{Project $\rightarrow$
+ Build All}.
+\item Select \textsc{Run} $\rightarrow$ \textsc{Debug}. The
+ application will be downloaded to the processor and run. A
+ breakpoint is automatically placed at \texttt{main()} entry. To
+ continue executing the application select \textsc{Run} $\rightarrow$
+ \textsc{Resume}.
+\item If your application fails to run with a \texttt{\_dabort} interrupt, check
+that the linker script selected in step 1 is not excluded from the build.
+You can do this by right clicking the \texttt{\ldscriptname} file
+in the \textsc{Project Explorer} and unchecking the \textsc{Exclude from build}
+item. The Code Composer Studio sometimes automaticaly excludes this file from
+the build process when creating a new project.
+
+% \item If not already created for another project, create new target
+% configuration. Select \textsc{Windows $\rightarrow$ Show View
+% $\rightarrow$ Target Configurations}. In the shown window, click
+% on \textsc{New Target Configuration} icon and configure XDS100v2
+% connection and \mcuname{} device as shown below. Click \textsc{Save},
+% connect your board and click \textsc{Test Connection}.
+
+% \medskip
+% \includegraphics[width=\linewidth]{images/target_conf.png}
+
+% \newpage
+\item Optionally, you can change debugger configuration by selecting
+ \textsc{Run $\rightarrow$ Debug Configurations}. In the
+ \textsc{Target} tab, you can configure not to break at \texttt{main}
+ or not to erase the whole flash, but necessary sectors only (see the
+ figure below).
+
+ \includegraphics[width=\linewidth]{images/debug_conf_flash.png}
+
+
\end{compactenum}
-\textbf{In general any RPP application uses the layout/template:}
+%% Comment this out for Eaton
+% \subsubsection{Steps to configure new POSIX application:}
+% Such an application can be used to test certain FreeRTOS features on
+% Linux and can be compiled with a native GCC compiler.
+
+% \begin{compactenum}
+% \item Create a new managed C project that uses Linux GCC toolchain.
+% \item Create a source folder \texttt{src}. Link all files from original
+% CCS application to this folder.
+% \item Create a normal folder \texttt{include}. Create a folder
+% \texttt{rpp} inside of it.
+% \item Add common \texttt{.gitignore} to the root of that project:
+% \lstset{language=}
+% \begin{lstlisting}
+% Debug
+% Release
+% .settings/*
+% \end{lstlisting}
+% \item Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
+% repository branch root.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_1.png}
+% \item Configure compiler to include local includes, CCS application
+% includes, OS includes for POSIX and RPP includes, in that order.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_2.png}
+% \newpage
+% \item Add \texttt{rpp} and \texttt{pthread} to linker libraries and add
+% \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
+% \noindent\includegraphics[width=\linewidth]{images/base_posix_3.png}
+% \end{compactenum}
+
+\subsubsection{Content of the application}
\begin{enumerate}
- \item Include RPP library header file. You may also include only a
-selected modules to save space. \lstset{language=c++}
+\item Include RPP library header file.
+ \lstset{language=c++}
\begin{lstlisting}
#include "rpp/rpp.h"
\end{lstlisting}
-You may not want to include the whole library to save space and compile time. In
-this case you may include only those modules, that you want to use. Inclusion
-selected modules only requires two more
-header files to be included as well: base.h and, in case sci is used for printing, rpp/sci.h.
+ If you want to reduce the size of the final application, you can
+ include only the headers of the needed modules. In that case, you
+ need to include two additional headers: \texttt{base.h} and, in case
+ when SCI is used for printing, \texttt{rpp/sci.h}.
\begin{lstlisting}
#include "rpp/hbr.h" /* We want to use H-bridge */
-#include <base.h> /* This is a necessary base header file of the rpp library. */
-#include "rpp/sci.h" /* This is needed, because we are using rpp_sci_printf in following examples. */
+#include <base.h> /* This is the necessary base header file of the rpp library. */
+#include "rpp/sci.h" /* This is needed, because we use rpp_sci_printf in following examples. */
\end{lstlisting}
\newpage
-\item Create one or as many FreeRTOS task function definitions as required. Those tasks should use
- functions from this library.
-\lstset{language=c++}
+\item Create one or as many FreeRTOS task function definitions as
+ required. Those tasks can use functions from the RPP library. Beware
+ that currently not all RPP functions are
+ reentrant\footnote{Determining which functions are not reentrant and
+ marking them as such (or making them reentrant) is planned as
+ future work.}. \lstset{language=c++}
\begin{lstlisting}
void my_task(void* p)
{
\item Initialize the RPP board. If you have included only selected
modules in step 1, initialize only those modules by calling their init
functions, for
-example rpp\_hbr\_init\(\).
+example \texttt{rpp\_hbr\_init\(\)}.
\item Spawn the tasks the application requires. Refer to FreeRTOS API
for details.
- \item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details.
- \item Catch if idle task could not be created.
+\item Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details
+ \cite{freertosapi}.
+ \item Handle error when the FreeRTOS scheduler cannot be started.
\lstset{language=c++}
\begin{lstlisting}
rpp_init();
/* In case only selected modules are included: */
/* Initialize HBR */
- rpp_hbr_init();
+ rpp_hbr_init();
/* Initialize sci for printf */
rpp_sci_init();
/* Enable interrups */
"ERROR: Cannot spawn control task.\r\n"
);
#endif
- while (TRUE) { asm(" nop"); }
+ while (TRUE) { ; }
}
/* Start the FreeRTOS Scheduler */
"ERROR: Problem allocating memory for idle task.\r\n"
);
#endif
- while (TRUE) { asm(" nop"); }
+ while (TRUE) { ; }
}
\end{lstlisting}
\end{itemize}
\item Create hook functions for FreeRTOS:
\begin{itemize}
- \item \textsc{vApplicationMallocFailedHook()} allows to catch memory allocation
+ \item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation
errors.
- \item \textsc{vApplicationStackOverflowHook()} allows to catch if a task
-overflows it's stack.
+\item \texttt{vApplicationStackOverflowHook()} allows to catch stack
+ overflow errors.
\lstset{language=c++}
\begin{lstlisting}
\end{enumerate}
-\subsection{Running the software on the HW}
+\subsection{Downloading and running the software}
\label{sec-running-software-on-hw}
\subsubsection{Code Composer Studio Project}
\label{sec-ccs-run-project}
-When the application is distributed as a CCS project, you have to open the
+When an application is distributed as a CCS project, you have to open the
project in the CCS as described in the Section
\ref{sec-openning-of-existing-project}. Once the project is opened and built, it
can be easily downloaded to the target hardware with the following procedure:
\begin{enumerate}
- \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG
-port (see Figure \ref{pinout}, port 1).
- \item Connect a USB cable to the XDS100v2 USB emulator and the
-development computer.
+\ifx\tgtId\tgtIdTMSRPP
+ \item Connect the Texas Instruments XDS100v2 USB emulator to the JTAG port.
+ \item Connect a USB cable to the XDS100v2 USB emulator and the development computer.
+\else
+ \item Connect the USB cable to the \tgtBoardName{} board.
+\fi
\item Plug in the power supply.
\item In the Code Composer Studio click on the
\textsc{Run$\rightarrow$Debug}. The project will be optionally built and
the download process will start. The Code Composer Studio will switch into the debug
-mode, when the download is finished.
+perspective, when the download is finished.
\item Run the program by clicking on the \textsc{Run} button, with the
green arrow.
\end{enumerate}
\subsubsection{Binary File}
\label{sec-binary-file}
-If the application is distributed as a binary file, without source codes and CCS
+If the application is distributed as a binary file, without source code and CCS
project files, you can download and run just the binary file by creating a new
empty CCS project and configuring the debug session according to the following
procedure:
\textsc{File$\rightarrow$New$\rightarrow$CCS Project}.
\item In the dialog window, type in a project name, for example
myBinaryLoad, Select \textsc{Device
-variant} (ARM, Cortex R, TMS570LS3137, Texas Instruments XDS100v2 USB Emulator)
+variant} (ARM, Cortex R, \mcuname, Texas Instruments XDS100v2 USB Emulator)
and select project template to \textsc{Empty Project}. The filled dialog should
-look like on the Figure \ref{fig-new-empty-project}
- \item Click on the \textsc{Finish} button and new empty project will be
-created.
- \item In the \textsc{Project Explorer} click on the project with a right
-mouse button and in the context menu select \textsc{Debug
-as$\rightarrow$Debug configurations}.
- \item Click on a button \textsc{New launch configuration}
- \item Rename the New\_configuration, for example to myConfiguration.
+look like in Figure~\ref{fig-new-empty-project}
+\item Click the \textsc{Finish} button and a new empty project will
+ be created.
+\item In the \textsc{Project Explorer} right-click on the project and
+ select \textsc{Debug as$\rightarrow$Debug configurations}.
+ \item Click \textsc{New launch configuration} button
+ \item Rename the New\_configuration to, for example, myConfiguration.
\item Select configuration target file by clicking the \textsc{File
-System} button, finding and selecting the TMS5703137.ccxml file. The result
-should look like on the Figure \ref{fig-debug-conf-main-diag}.
- \item On the \textsc{program} pane select the binary file you want to
-download to the board.
-Click on the \textsc{File System} button, find and select the binary file.
-Rpp-test-sw.out for example. The result should look like on the Figure
-\ref{fig-debug-conf-program-diag}.
- \item You may also tune the target configuration like in the Section
-\ref{sec-target-configuration}.
- \item Finish the configuration by clicking on the \textsc{Apply} button
-and download the code by clicking on the \textsc{Debug} button. You can later
-invoke the download also from the \textsc{Run$\rightarrow$Debug} CCS menu. You
-may not need to create more Debug configurations and CCS empty projects as you
-can easily change the binary file in the Debug configuration to load different
-binary file.
+System} button, finding and selecting the \texttt{rpp-lib-XXX/build/\tgtId/\tgconfigfilename} file. The result
+should look like in Figure~\ref{fig-debug-conf-main-diag}.
+\item In the \textsc{program} pane select the binary file you want to
+ download to the board. Click on the \textsc{File System} button,
+ find and select the binary file. Try, for example
+ \texttt{rpp-test-sw.out}. The result should look like in
+ Figure~\ref{fig-debug-conf-program-diag}.
+\item You may also tune the target configuration as described in
+ Section \ref{sec-target-configuration}.
+\item Finish the configuration by clicking the \textsc{Apply} button
+ and download the code by clicking the \textsc{Debug} button. You can
+ later invoke the download also from the
+ \textsc{Run$\rightarrow$Debug} CCS menu. It is not necessary to
+ create more Debug configurations and CCS empty projects as you can
+ easily change the binary file in the Debug configuration to load a
+ different binary file.
\end{enumerate}
\begin{figure}[H]\begin{center}
- \includegraphics[width=350px]{images/new_empty_project.png}
+ \includegraphics[scale=.45]{images/new_empty_project.png}
\caption{New empty project dialog}
\label{fig-new-empty-project}
\end{center}\end{figure}
\begin{figure}[H]\begin{center}
- \includegraphics[width=350px]{images/debug_configuration_main.png}
+ \includegraphics[scale=.45]{images/debug_configuration_main.png}
\caption{Debug Configuration Main dialog}
\label{fig-debug-conf-main-diag}
\end{center}\end{figure}
\subsection{Target configuration}
\label{sec-target-configuration}
-Default target configuration erases the whole Flash memory, before downloading
-the code. This is however not needed in most cases. You may disable this feature
-by the following procedure:
+Default target configuration erases the whole Flash memory, before
+downloading the code. This takes long time and in most cases it is
+not necessary. You may disable this feature by the following procedure:
\begin{enumerate}
\item Right click on the project name in the \textsc{Project Browser}
\item Select \textsc{Debug as$\rightarrow$Debug Configurations}
\item In the dialog window select \textsc{Target} pane.
\item In the \textsc{Flash Settings}, \textsc{Erase Options} select
\textsc{Necessary sectors only}.
- \item Save the configuration by clicking on the \textsc{Apply} button
+ \item Save the configuration by clicking the \textsc{Apply} button
and close the dialog.
\end{enumerate}
\begin{figure}[H]\begin{center}
- \includegraphics[width=350px]{images/debug_configuration_program.png}
+ \includegraphics[scale=.45]{images/debug_configuration_program.png}
\caption{Configuration Program dialog}
\label{fig-debug-conf-program-diag}
\end{center}\end{figure}
\section{Matlab Simulink usage}
\label{sec-matlab-simulink-usage}
+This section describes the basics of working with the RPP code
+generation target for Simulink. For a more detailed description of the
+code generation target refer to
+Chapter~\ref{chap-simulink-coder-target}.
\subsection{Configuring Simulink for RPP}
\label{sec-configuration-simulink-for-rpp}
-Before any work or experiments with the RPP blocks and models can be done, the RPP target has to be configured to be able to find the ARM compiler, C compiler and some necessary files. Also the S-Functions of the blocks have to be compiled by the mex tool.
+Before any work or experiments with the RPP blocks and models, the RPP
+target has to be configured to be able to find the ARM cross-compiler,
+native C compiler and some other necessary files. Also the S-Functions
+of the blocks have to be compiled by the mex tool.
\begin{enumerate}
-\item Download and install CCS for Linux:
-
-Details on how to setup CCS are available in Section \ref{sec-ti-ccs}.
-
-\item On Windows you have to tell the \textsc{mex} which C compiler it should be using. Open the command line, run the \textsc{mex} tool from the Matlab installation folder and select the C compiler.
+\item Download and install Code Composer Studio CCS (see
+ Section~\ref{sec-ti-ccs}).
+\item Install a C compiler. On Windows follow Section~\ref{sec-c-compiler}.
+\item On Windows you have to tell the \texttt{mex} which C compiler to
+ use. In the Matlab command window run the \texttt{mex -setup}
+ command and select the native C compiler.
-\begin{lstlisting}[language=bash]
-C:\Program Files\MATLAB\R2013b\bin>mex -setup
+\begin{lstlisting}[basicstyle=\tt\footnotesize]
+>> mex -setup
Welcome to mex -setup. This utility will help you set up
a default compiler. For a list of supported compilers, see
http://www.mathworks.com/help/matlab/matlab_external/upgrading-mex-files-to-use-64-bit-api.html
Building with the -largeArrayDims option enables the new API.
**************************************************************************
-
-C:\Program Files\MATLAB\R2013b\bin>
\end{lstlisting}
-\item Install RPP Target:
+\item Configure the RPP code generation target:
-Open Matlab and type on command window:
+Open Matlab and in the command window run:
\lstset{language=Matlab}
\begin{lstlisting}
\end{lstlisting}
This will launch the RPP setup script. This script will ask the user to provide
-the path to the CCS compiler root directory (the directory where \textsc{armcl}
+the path to the CCS compiler root directory (the directory where \texttt{armcl}
binary is located), normally:
\begin{verbatim}
<ccs>/tools/compiler/arm_5.X.X/
\end{verbatim}
-This script will, among other things, ask the user to provide the location of
-the armcl parent directory, infer and save some relevant CCS paths, add paths to
-Matlab path and build S-Function
-blocks for user's architecture (using Matlab's mex command line tool).
+Then Matlab path will be updated and block S-Functions will be built.
\item Create new model or load a demo:
-Demos are located on \textsc{\repo/rpp/demo} or you can start a new model and
-configure target to RPP. For new models see Section \ref{sec-crating-new-model} below.
+ Demos are located in \texttt{\repo/rpp/demos}. Creation of new
+ models is described in Section~\ref{sec-crating-new-model} below.
\end{enumerate}
\subsection{Working with demo models}
\label{sec-openning-demo-models}
-The demo models are available from the directory \textsc{\repo/rpp/demos}. To
-access the demo models for reference or for downloading to the RPP board you
-have to change the directory to the one, containing the desired demo. For
-example to open the cantransmit demo you have to type these commands into the
-Matlab command line:
+The demo models are available from the directory
+\texttt{\repo/rpp/demos}. To access the demo models for reference or
+for downloading to the RPP board open them in Matlab. Use either the
+GUI or the following commands:
\begin{lstlisting}[language=Matlab]
cd <rpp-simulink>/rpp/demos
open cantransmit.slx
\end{lstlisting}
-The same procedure can be used to open any other models. To build the demo select
-\textsc{Code$\rightarrow$C/C++ Code $\rightarrow$Build Model}. This selection
-will generate the C code and build the binary firmware for the RPP board.
-To run the model on the target hardware see Section \ref{sec-running-model-on-hw}.
+The same procedure can be used to open any other models. To build the
+demo select \textsc{Code$\rightarrow$C/C++ Code $\rightarrow$Build
+ Model}. This will generate the C code and build the binary firmware
+for the RPP board. To run the model on the target hardware see
+Section~\ref{sec-running-model-on-hw}.
-\subsection{Creating a new model}
+\subsection{Creating new model}
\label{sec-crating-new-model}
\begin{enumerate}
\item Create a model by clicking \textsc{New$\rightarrow$Simulink Model}.
- \item Open a configuration dialog by clicking \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
+ \item Open the configuration dialog by clicking \textsc{Simulation$\rightarrow$Model Configuration Parameters}.
\item The new Simulink model needs to be configured in the following way:
\begin{compactitem}
\item Solver (Figure \ref{fig-solver}):
\begin{compactitem}
- \item Options: \emph{Fixed-step, discrete}
- \item Tasking mode set to \textit{SingleTasking}.
+ \item Solver type: \emph{Fixed-step}
+ \item Solver: \emph{discrete}
+ \item Fixed-step size: \emph{Sampling period in seconds. Minimum
+ is 0.001.}
+ \item Tasking mode -- choose between the following:
+ \begin{compactitem}
+ \item \textit{Auto} selects SingleTasking modes for
+ single-rate model or MultiTasking mode for multi-rate
+ models. See Section \ref{sec-singlet-multit-modes}
+ \item \textit{SingleTasking} selects SingleTasking mode. See
+ Section \ref{sec-singlet-mode} for details.
+ \item \textit{MultiTasking} select MultiTasking mode. In
+ this mode \textit{Higher priority value indicates higher
+ task priority} should be checked. See Section
+ \ref{sec-multit-mode} for details.
+ \end{compactitem}
+
\begin{figure}
\centering
- \includegraphics[width=400px]{images/simulink_solver.png}
+ \includegraphics[scale=.45]{images/simulink_solver.png}
\caption{Solver settings}
\label{fig-solver}
\end{figure}
\end{compactitem}
- \item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
- \begin{compactitem}
- \item Disable warning source block specifies -1 sampling time. It's ok for the
-source blocks to run once per tick.
- \begin{figure}
- \centering
- \includegraphics[width=400px]{images/simulink_diagnostics.png}
- \caption{Sample Time settings}
- \label{fig-sample-time-settings}
- \end{figure}
- \end{compactitem}
+% \item Diagnostics $\rightarrow$ Sample Time (Figure~\ref{fig-sample-time-settings}):
+% \begin{compactitem}
+% \item Disable warning ``Source block specifies -1 sampling
+% time''. It's ok for the source blocks to run once per tick.
+% \begin{figure}
+% \centering
+% \includegraphics[scale=.45]{images/simulink_diagnostics.png}
+% \caption{Sample Time settings}
+% \label{fig-sample-time-settings}
+% \end{figure}
+% \end{compactitem}
\item Code generation (Figure~\ref{fig-code-gen-settings}):
\begin{compactitem}
- \item Set to \textsc{rpp.tlc}.
+ \item Set ``System target file'' to \texttt{rpp.tlc}.
\begin{figure}
\centering
- \includegraphics[width=400px]{images/simulink_code.png}
+ \includegraphics[scale=.45]{images/simulink_code.png}
\caption{Code Generation settings}
\label{fig-code-gen-settings}
\end{figure}
\end{compactitem}
\end{compactitem}
+\item Once the model is configured, you can open the Library Browser
+ (\textsc{View $\rightarrow$ Library Browser}) and add the necessary
+ blocks to create the model. The RPP-specific blocks are located in
+ the RPP Block Library.
\item From Matlab command window change the current directory to where
you want your generated code to appear, e.g.:
\begin{lstlisting}[language=Matlab]
cd /tmp/my-code
\end{lstlisting}
- The code will be generated in a subdirectory of that directory. The name of
-the subdirectory will be \textsc{<model>\_rpp}, where \textsc{model} is the name
-of the Simulink model.
+The code will be generated in a subdirectory named
+\texttt{<model>\_rpp}, where \texttt{model} is the name of the
+Simulink model.
\item Generate the code by choosing \textsc{Code $\rightarrow$ C/C++
Code $\rightarrow$ Build Model}.
\end{enumerate}
-If you want to run the model on the RPP board, see Section
+To run the model on the \tgtBoardName{} board continue with Section
\ref{sec-running-model-on-hw}.
-\subsection{Running model on the RPP board}
+\subsection{Running models on the RPP board}
\label{sec-running-model-on-hw}
-To run the model on the target RPP hardware you have to enable the download
-feature and build the model by following this procedure: \begin{enumerate}
- \item Open the model you want to run (See Section
-\ref{sec-openning-demo-models}.)
- \item Click on \textsc{Simulation$\rightarrow$Model Configuration
-Parameters}.
- \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
-check \textsc{Download compiled binary to RPP} checkbox.
- \item Click on \textsc{OK} button, connect the target HW to the computer
-like in the Section \ref{sec-ccs-run-project} and build the model by \textsc{Code $\rightarrow$ C/C++
-Code $\rightarrow$ Build Model}. If the build
-ends with a success, the download process will start and once the downloading is
-finished, the application will run immediatelly.
+To run the model on the \tgtBoardName{} hardware you have to enable the download
+feature and build the model by following this procedure:
+ \begin{enumerate}
+ \item Open the model you want to run (see
+ Section~\ref{sec-openning-demo-models} for example with demo
+ models).
+ \item Click on \textsc{Simulation$\rightarrow$Model Configuration
+ Parameters}.
+ \item In the \textsc{Code Generation$\rightarrow$RPP Options} pane
+ check the \textsc{Download compiled binary to RPP} checkbox. Click
+ the \textsc{OK} button
+ \item Connect the target hardware to the computer (see Section
+ \ref{sec-ccs-run-project}) and build the model by \textsc{Code
+ $\rightarrow$ C/C++ Code $\rightarrow$ Build Model}. If the build
+ succeeds, the download process will start automatically and once
+ the downloading is finished, the application will run immediately.
\end{enumerate}
-The code downloading is supported for Windows and Linux development systems. If
-you are using Linux, you may also try to use the OpenOCD by checking Use OpenOCD
-to download the compiled binary checkbox in addition. For more information about
-the OpenOCD configuration refer
-
-\begin{verbatim}
-http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137#OpenOCD_setup_and_Flashing
-\end{verbatim}
+%%\subsubsection{Using OpenOCD for downloading}
+%%\label{sec:using-open-downl}
+%%
+%%On Linux systems, it is possible to use an alternative download
+%%mechanism based on the OpenOCD tool. This results in much shorter
+%%download times. Using OpenOCD is enabled by checking ``Use OpenOCD to
+%%download the compiled binary'' checkbox. For more information about
+%%the OpenOCD configuration refer to our
+%%wiki\footnote{\url{http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137\#OpenOCD_setup_and_Flashing}}.
+%%
+%%Note: You should close any ongoing Code Composer Studio debug sessions
+%%before downloading the generated code to the RPP board. Otherwise the
+%%download fails.
-Note: You should end the Code Composer Studio debug session before
-downloading the generated code to the RPP board. Otherwise the
-download will fail.
-
\section{Configuring serial interface}
\label{sec-configuration-serial-interface}
-The main interface for communicating with the RPP board is the serial interface.
-The application may define its own interface settings, but the following
-settings is the default one:
+The main mean for communication with the RPP board is the serial line.
+Each application may define its own serial line settings, but the
+following settings are the default:
\begin{itemize}
\item Baudrate: 115200
\item Flow control: none
\end{itemize}
-Use GtkTerm in Linux or Bray Terminal for accessing the serial interface. See
-Section \ref{sec-hardware-description} for reference about the position of the
-serial interface connector on the RPP board.
+Use GtkTerm on Linux or Bray Terminal on Windows for accessing the
+serial interface. On \tgtBoardName{} board, the serial line is tunneled over
+the USB.
+% TODO: Conditional compilation
+ % See Section \ref{sec-hardware-description} for reference about
+% the position of the serial interface connector on the RPP board.
\section{Bug reporting}
\label{sec-bug-reporting}
-% TODO: implement
+Please report any problems to CTU's bug tracking system at
+\url{https://redmine.felk.cvut.cz/projects/eaton-rm48}. New users have
+to register in the system and notify Michal Sojka about their
+registration via $\langle{}sojkam1@fel.cvut.cz\rangle{}$ email
+address.
\chapter{C Support Library}
\label{chap-c-support-library}
(RPP Library), which is used both for Simulink code generation target
and command line testing tool.
-\section{Description}
+\section{Introduction}
\label{sec-description}
The RPP C Support Library (also called RPP library) defines the API for
-working with the board. It includes drivers and an operating system.
+working with the board. It includes drivers and the operating system.
The library is
designed from the board user perspective and exposes a simplified high-level API
to handle the board's peripheral modules in a safe manner. The library is
-compiled as a static library named \texttt{rpp-lib.lib} and can be found in
-\textsc{\repo/rpp/lib}.
+compiled as static library named \texttt{rpp-lib.lib} and can be found in
+\texttt{\repo/rpp/lib}.
-The RPP library can be used in any project, where the RPP hardware support is
-required and it is also used in two applications -- the Command line testing
-tool, described in Chapter \ref{chap-rpp-test-software}, and Simulink Coder
-target, described in Chapter \ref{chap-simulink-coder-target}.
+The RPP library can be used in any project, where the RPP hardware
+support is required and it is also used in two applications --
+Simulink Coder Target, described in Chapter
+\ref{chap-simulink-coder-target}, and the command line testing tool,
+described in Chapter \ref{chap-rpp-test-software}.
-For details about the library architecture, refer Section \ref{sec-software-architecture}.
+For details about the library architecture, refer to Section~\ref{sec-software-architecture}.
\section{API development guidelines}
\label{sec-api-development-guidlines}
the discretion of the developer.
\item Always use standard data types for IO when possible. Use custom
structs as very last resort. \item Use prefix based functions names to avoid
-clash. The prefix is of the form \textsc{$\langle$layer$\rangle$\_$\langle$module$\rangle$\_}, for example
-\textsc{rpp\_din\_update()} for the update function of the DIN module in the RPP
+clash. The prefix is of the form \texttt{$\langle$layer$\rangle$\_$\langle$module$\rangle$\_}, for example
+\texttt{rpp\_din\_update()} for the update function of the DIN module in the RPP
Layer.
\item Be very careful about symbol export. Because it is used as a
static library the modules should not export any symbol that is not intended to
-be used (function) or \textsc{extern}'ed (variable) from application. As a rule
+be used (function) or \texttt{extern}'ed (variable) from application. As a rule
of thumb declare all global variables as static.
\item Only the RPP Layer symbols are available to user applications. All
information related to lower layers is hidden for the application. This is
accomplished by the inclusion of the rpp.h or rpp\_\{mnemonic\}.h file on the
implementations files only and never on the interface files. Never expose any
other layer to the application or to the whole system below the RPP layer. In
-other words, never \textsc{\#include "foo/foo.h"} in any RPP Layer interface
-file.
+other words, never \texttt{\#include "foo/bar.h"} in any RPP Layer header
+file.
\end{compactitem}
\section{Coding style}
\label{sec-coding-style}
-In order to keep the code as clean as possible, a unified coding style
+In order to keep the code as clean as possible, unified coding style
should be followed by any contributor to the code. The used coding
style is based on the default configuration of Code Composer Studio
editor. Most notable rule is that the Tab character is 4 spaces.
-The RPP library project is prepared for a usage of a program named
-Uncrustify. The Uncrustify program checks the code and fixes those
-lines that does not match the coding style. However, keep in mind that
-the program is not perfect and sometimes some lines can be modified
-even when the suggested coding style has been followed. This does not
-causes problems as long as the contributor follows the committing
-procedure described in next paragraph.
+The RPP library project is prepared for use of a tool named
+Uncrustify. The Uncrustify tool checks the code and fixes those lines
+that do not match the coding style. However, keep in mind that the
+program is not perfect and sometimes it can modify code where the
+suggested coding style has been followed. This does not causes
+problems as long as the contributor follows the committing procedure
+described in next paragraph.
-When contributing to the code, the contributor should learn the current coding
-style from the existing code. When a new feature is implemented, before
-committing to the repository, a command:
+When contributing to the code, the contributor should learn the
+current coding style from existing code. When a new feature is
+implemented and committed to the local repository, the following
+commands should be called in Linux terminal:
-\lstset{language=bash}
-\begin{lstlisting}
+\begin{lstlisting}[language=bash]
make uncrustify
+git diff
+\end{lstlisting}
+The first line command corrects many found coding style violations and
+the second command displays them. If the user agree with the
+modification, he/she should amend the last commit, for example by:
+\begin{lstlisting}[language=bash]
+git add --update
+git commit --amend
\end{lstlisting}
-in a Linux terminal should be called. This command fixes any coding style
-errors. After that all changes can be committed.
\section{Subdirectory content description}
\label{sec-rpp-lib-subdirectory-content-description}
+
+The following files and directories are present in the library source
+code package:
+
\begin{description}
-\item[librpp.a and rpp-lib.lib] static RPP libraries.
-
-The first one is for POSIX simulation, the second one for Simulink models and
-other ARM/TMS570 applications. This files are placed here by the Makefile, when
-the library is built.
-
- \item[apps/] Demo applications related to the RPP library.
-
-This include the CCS studio project for generating of the static library and
-a test suite. The test suit in this directory has nothing common with the test suite
-mentioned later in Chapter 5 and those two suits are going to be merged in the
-future. Also other Hello World applications are included as a reference about how
-to create a TMS570 application.
- \item[os/] OS layers directory. See OS interchangeable layer in Section
-\ref{sec-software-architecture} for more information.
- \item[rpp/] Main directory for the RPP Library.
- \item[rpp/doc/] Documentation directory for the RPP Library API documentation.
- \item[rpp/TMS570LS3137.ccxml] Descriptor for code download.
-
-This file is used by all the projects including the Simulink RPP Target for code
-download. It is configured to use the Texas Instruments XDS100v2 USB Emulator.
- \item[rpp/TMS570LS313xFlashLnk.cmd] CGT Linker command file.
-
-This file is used by all applications linked for the RPP board, including the
-Simulink models, static library and test suite. It includes instructions for the
-CGT Linker on where to place sections and sizes of some sections.
- \item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
-implementations files for given \textsc{\{layer\}}. See Section
-\ref{sec-software-architecture} in Chapter \ref{chap-introduction} for details
-on the RPP Layer.
- \item[rpp/include/rpp/rpp.h] Main library header file.
-
-To use this library with all its modules, just include this file and this file
-only. Also, before using any library function call the \textsc{rpp\_init()}
-function for hardware initialization.
- \item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for
-\textsc{\{mnemonic\}} module.
-
-This files includes function definitions, pin definitions, etc, specific to
-\{mnemonic\} module. See Section \ref{sec-api-development-guidlines}.
-
-You may include only selected \textsc{rpp\_\{mnemonic\}.h} header files and call the
-specific \textsc{rpp\_\{mnemonic\}\_init} functions, instead of the \textsc{rpp.h} and
-\textsc{rpp\_init} function, if you want to use only a subset of the library functions.
+\item[rpp-lib.lib] Compiled RPP library.
+
+ The library is needed for Simulink models and other ARM/\tgname{}
+ applications. It is placed here by the Makefile, when the library is
+ compiled.
+
+\item[apps/] Various applications related to the RPP library.
+
+ This include the CCS studio project for generating of the static
+ library and a test suite. The test suit in this directory has
+ nothing common with the test suite described later in
+ Chapter~\ref{chap-rpp-test-software} and those two suits are going
+ to be merged in the future. Also other Hello World applications are
+ included as a reference about how to create an \tgname{}
+ application.
+\item[build] The library can be compiled for multiple targets. Each
+ supported target has a subdirectory here, which stores configuration
+ of how to compile the library and applications for different target.
+ Each subdirectory contains a CCS project and Makefiles to build the
+ library for the particular target.
+\item[build/$\langle$target$\rangle$/Makefile.config] Configuration
+ for the particular target. This includes compiler and linker
+ switches etc.
+\item[build/$\langle$target$\rangle$/*.cmd]
+CGT Linker command file.
+
+This file is used by all applications that need to tun on the RPP
+board, including the Simulink models and test suite. It includes
+instructions for the CGT Linker about target memory layout and where
+to place various code sections.
+\item[os/] OS layers directory. See
+ Section~\ref{sec-operating-system-layer} for more information about
+ currently available operating system versions and
+ Section~\ref{sec-changing-os} for information how to replace the
+ operating system.
+\item[rpp/] Main directory for the RPP library.
+\item[rpp/doc/] RPP Library API
+ documentation.
+\item[rpp/include/\{layer\} and rpp/src/\{layer\}] Interface files and
+ implementations files for given \texttt{\{layer\}}. See
+ Section~\ref{sec-software-architecture} for details on the RPP
+ Layer.
+\item[rpp/include/rpp/rpp.h] Main library header file.
+
+ To use this library with all its modules, just include this file
+ only. Also, before using any library function call the
+ \texttt{rpp\_init()} function for hardware initialization.
+\item[rpp/include/rpp/rpp\_\{mnemonic\}.h] Header file for
+ \texttt{\{mnemonic\}} module.
+
+ These files includes function definitions, pin definitions, etc,
+ specific to \{mnemonic\} module. See also
+ Section~\ref{sec-api-development-guidlines}.
+
+ If you want to use only a subset of library functions and make the
+ resulting binary smaller, you may include only selected
+ \texttt{rpp\_\{mnemonic\}.h} header files and call the specific
+ \texttt{rpp\_\{mnemonic\}\_init} functions, instead of the
+ \texttt{rpp.h} and \texttt{rpp\_init} function.
\item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation.
-Implementation of \textsc{rpp\_\{mnemonic\}.h}'s functions on top of the DRV
-library.
+ Implementation of \texttt{rpp\_\{mnemonic\}.h}'s functions on
+ top of the DRV library.
\item[rpp/src/rpp/rpp.c] Implementation of library-wide functions.
\end{description}
\section{Compilation}
\label{sec-compilation}
-The RPP Library can be compiled as a static library using a Code
-Composer Studio project. The compilation process will automatically
-update the generated binary static library file in the library root
+To compile the library open the Code Composer studio project
+\texttt{rpp-lib} from appropriate \texttt{build/<target>} directory
+(see Section~\ref{sec-openning-of-existing-project}) and build the
+project (\textsc{Project $\rightarrow$ Build Project}). If the build
+process is successful, the \texttt{rpp-lib.lib} and
+\texttt{Makefile.config} files will appear in the library root
directory.
-For the compilation of the library as a static library open the Code
-Composer studio project \textsc{rpp-lib} (see
-Section~\ref{sec-openning-of-existing-project}) and build the project.
-If the build process is successful, the \textsc{rpp-lib.lib} file will
-appear in the library root directory.
-
-Because compilation of the libraries in Eclipse IDE can be error
-prone, there is a \textsc{Makefile} that allows to compile the
-libraries from the Linux terminal:
-
+It is also possible to compile the library using the included
+\texttt{Makefile}. From the Linux command line run:
\begin{lstlisting}[language=bash]
-cd <library-root>
-make lib
+cd <library-root>/build/<target>/Debug #or Release
+make
\end{lstlisting}
+Note that this only works if Code Composer Studio is installed in
+\texttt{/opt/ti} directory. Otherwise, you have to set
+\texttt{CCS\_UTILS\_DIR} variable.
-or Windows command line:
-
+On Windows command line run:
\begin{lstlisting}[language=bash]
-cd <library-root>
+cd <library-root>\build\<target>\Debug
set CCS_UTILS_DIR=C:\ti\ccsv5\utils
-"C:\ti\ccsv5\utils\bin\"gmake.exe lib
+C:\ti\ccsv5\utils\bin\gmake.exe lib
\end{lstlisting}
-On Windows \texttt{gmake.exe} supplied with CCS is used instead of
-\texttt{make}. The \texttt{gmake.exe} uses variable \texttt{CCS\_UTILS\_DIR},
-which has to be set properly, before the build process is invoked. The variable
-can be set manually for one session by the \textsc{set} command like in the
-previous example or permanently in \textsc{\repo/Debug/GNUMakefile}.
+You have to use \texttt{gmake.exe} instead of \texttt{make} and it is
+necessary to set variable \texttt{CCS\_UTILS\_DIR} manually. You can
+also edit \texttt{\repo/build/Makefile.rules.arm} and set the variable
+there.
Note that the Makefile still requires the Code Composer Studio (ARM
compiler) to be installed because of the CGT.
-The relevant aspects for compiling and linking an application using the static
-libraries are:
+\section{Compiling applications using the RPP library}
+\label{sec:comp-appl-using}
+
+The relevant aspects for compiling and linking an application using
+the RPP library are summarized below.
+
+% \subsection{ARM target (RPP board)}
+% \label{sec:arm-target-rpp}
+
+The detailed instructions are presented in
+Section~\ref{sec:creating-new-project}. Here we briefly repeat the
+main steps.
-\begin{itemize}
- \item \textbf{ARM compilation using CCS for the RPP board:}
- \begin{compactitem}
- \item Include headers files of the OS for which the library was
-compiled against. At the time of this writing the OS is FreeRTOS 7.0.2. See
-Section \ref{sec-software-architecture}
- \item Include header files for the RPP library or for modules
-you want to use rpp\_can.h for CAN module for example.
- \item Add library \textsc{rpp-lib.lib} to the linker libraries.
-The RPP library \textbf{MUST} be looked for before Texas Instruments support
-library \textsc{rtsv7R4\_T\_be\_v3D16\_eabi.lib}.
- \item Configure linker to retain \textsc{.intvecs} section from
-RPP Library:\newline{}
-\textsc{--retain="rpp-lib.lib$\langle$sys\_intvecs.obj$\rangle$(.intvecs)"}
- \item Use the provided linker command file
-\textsc{TMS570LS313xFlashLnk.cmd}.
- \end{compactitem}
- \item \textbf{x86(\_64) compilation using GCC for Simulation:}
\begin{compactitem}
- \item Include headers files of the OS for Simulation. At the
-time of this writing the OS is POSIX FreeRTOS 6.0.4.
- \item Include header files for the RPP library or for modules
-you want to use (rpp\_can.h for CAN module for example).
- \item Add library \textsc{librpp.a} to the linker libraries.
- \item Add \textsc{pthread} to the linker libraries.
+ \item Configure include search path to contain the directory of
+ used FreeRTOS version, e.g.
+ \texttt{\repo/os/8.2.2/include}. See Section
+ \ref{sec-software-architecture}.
+ \item Include \texttt{rpp/rpp.h} header file or just the needed
+ peripheral specific header files such as \texttt{rpp/can.h}.
+ \item Add library \texttt{rpp-lib.lib} to the linker libraries.
+ The RPP library must be placed before Texas Instruments
+ support library \tgtRtlib.
+ \item Use the provided linker command file
+ \texttt{\ldscriptname}.
\end{compactitem}
-\end{itemize}
-As an important note, all the models compiled using Simulink will link against
-\textsc{rpp-lib.lib}. When compiling a Simulink model, neither Simulink nor the
-\textsc{make} invoked during the build process, will update the generated binary
-if the model hasn't changed, and then if the source code hasn't changed. Static
-libraries changes are not considered for re-compilation and re-linking. If
-library development is being done and static library is updated, in order for
-the Simulink model to generate a newly linked version of the binary the whole
-code generation folder needs to be deleted in order to force code generation,
-compilation and linking with the new static library.
+% \subsection{POSIX target}
+% \label{sec:posix-target}
+
+% \begin{compactitem}
+% \item Include headers files of the OS for Simulation. At the time
+% of this writing the OS is POSIX FreeRTOS 6.0.4.
+% \item Include header files for the RPP library or for modules you
+% want to use (rpp\_can.h for CAN module for example).
+% \item Add library \texttt{librpp.a} to the linker libraries.
+% \item Add \texttt{pthread} to the linker libraries.
+% \end{compactitem}
\section{Compiling API documentation}
\label{sec-compiling-api-documentation}
-The RPP Layer is formatted using Doxygen documentation generator. This allows to
-generate a high quality API reference. To generate the API reference run in a
-Linux terminal:
+The documentation of the RPP layer is formatted using Doxygen
+documentation generator. This allows to generate a high quality API
+reference. To generate the API reference run in a Linux terminal:
\lstset{language=bash}
\begin{lstlisting}
xdg-open html/index.html
\end{lstlisting}
-The files under \textsc{\repo/rpp/lib/rpp/doc/api/content} are used for the API
+The files under \texttt{\repo/rpp/doc/api/content} are used for the API
reference generation are their name is self-explanatory:
\begin{verbatim}
main_page.dox
\end{verbatim}
+\section{Changing operating system}
+\label{sec-changing-os}
+The C Support Library contains by default the FreeRTOS operating
+system in version 8.2.2. This section describes what is necessary to
+change in the library and other packages in order to replace the
+operating system.
+
+\subsection{Operating system code and API}
+
+The source and header files of the current operating system (OS) are
+stored in directory \texttt{\repo/rpp/lib/os}. The files of the new
+operating system should also be placed in this directory.
+
+To make the methods and resources of the new OS available to the C Support
+Library, modify the \texttt{\repo/rpp/lib/rpp/include/base.h} file to include
+the operating system header files.
+
+Current implementation for FreeRTOS includes a header file
+\texttt{\repo/rpp/lib/os/\-8.2.2\-include/os.h}, which
+contains all necessary declarations and definitions for the FreeRTOS.
+We suggest to provide a similar header file for your operating system as
+well.
+
+In order to compile another operating system into the library, it is
+necessary to modify \texttt{\repo/rpp/lib/Makefile.var} file, which
+contains a list of files that are compiled into the library. All lines
+starting with \texttt{os/} should be updated.
+
+\subsection{Device drivers}
+Drivers for SCI and ADC depend on the FreeRTOS features. These
+features need to be replaced by equivalent features of the new
+operating system. Those files should be modified:
+\begin{description}
+\item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data
+ structure, referring to FreeRTOS queue and semaphore.
+\item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Uses FreeRTOS queues
+ and semaphores.
+\item[\repo/rpp/lib/rpp/include/drv/sci.h] Declaration of
+ \texttt{drv\_sci\_receive()} contains \texttt{portTick\-Type}. We
+ suggest replacing this with OS independent type, e.g. number of
+ milliseconds to wait, with $-1$ meaning infinite waiting time.
+\item[\repo/rpp/lib/rpp/src/drv/sci.c] Uses the following FreeRTOS
+ specific features: semaphores, queues, data types
+ (\texttt{portBASE\_TYPE}) and
+ critical sections (\texttt{taskENTER\_CRITICAL} and
+ \texttt{task\-EXIT\_CRITICAL}). Inside FreeRTOS critical sections,
+ task preemption is disabled. The same should be ensured by the other
+ operating system or the driver should be rewritten to use other
+ synchronization primitives.
+\item[\repo/rpp/lib/rpp/src/drv/adc.c] Uses FreeRTOS semaphores.
+\end{description}
+
+\subsection{System start}
+The initialization of the MCU and the system is in the
+\texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} file. If the new
+operating system needs to handle interrupts generated by the Real-Time
+Interrupt module, the pointer to the Interrupt Service Routine (ISR)
+\texttt{vPreemptiveTick} has to be replaced.
+
+\subsection{Simulink template for main function}
+
+When the operating system in the library is replaced, the users of the
+library must be changed as well. In case of Simulink code generation
+target, described in Chapter~\ref{chap-simulink-coder-target}, the
+template for generation of the \texttt{ert\_main.c} file, containing
+the main function, has to be modified to use proper functions for task
+creation, task timing and semaphores. The template is stored in
+\texttt{\repo/rpp/rpp/rpp\_srmain.tlc} file.
+
\chapter{Simulink Coder Target}
\label{chap-simulink-coder-target}
-The Simulink Coder Target allows to convert Simulink models to a C code,
+The Simulink Coder Target allows to convert Simulink models to C code,
compile it and download to the board.
\section{Introduction}
The Simulink RPP Target provides support for C source code generation from Simulink models and
compilation of that code on top of the RPP library and the FreeRTOS operating system. This target
-uses Texas Instruments ARM compiler (\textsc{armcl}) included in the Code Generation Tools distributed with
+uses Texas Instruments ARM compiler (\texttt{armcl}) included in the Code Generation Tools distributed with
Code Composer Studio, and thus it depends on it for proper functioning.
This target also provides support for automatic download of the compiled binary to the RPP
board.
-\begin{figure}[H]\begin{center}
+\begin{figure}\begin{center}
\noindent
-\includegraphics[width=300px]{images/tlc_process.png}
+\includegraphics[scale=.45]{images/tlc_process.png}
\caption{TLC code generation process. \cite[p. 1-6]{targetlanguagecompiler2013}}
\end{center}\end{figure}
\begin{itemize}
\item Sampling frequencies up to 1\,kHz.
-\item Supports only single-tasking and single-rate systems. Support
- for single-rate systems will be available in the final version.
- Support for multitasking system will require careful audit of the
- RPP library with respect to thread-safe code.
+\item Multi-rate models can be executed in a single or multiple OS
+ tasks. Multi-tasking mode allows high-rate tasks to preempt low-rate
+ tasks. See Section \ref{sec-singlet-multit-modes} for more details.
\item No External mode support yet. We work on it.
\item Custom compiler options, available via OPTS variable in
\emph{Make command} at \emph{Code Generation} tab (see Figure
- \ref{fig-code-gen-settings}). For example \textsc{make\_rtw
+ \ref{fig-code-gen-settings}). For example \texttt{make\_rtw
OPTS="-O0 -g"}.
\end{itemize}
Note that FreeRTOS uses its own heap whose size is independent of this
parameter.
\item \textbf{Model step task stack size}: this parameter will be
-passed to the \textsc{xTaskCreate()} that
+passed to the \texttt{xTaskCreate()} that
creates the task for the model to run. In a Simulink model there are always two tasks:
\begin{itemize}
\item The worker task. This task is the one that executes the model
the board after the model is successfully built. Note that this option is unaware of the option
\textit{Generate code only} in the \textit{Code Generation} options panel, so it will try to download even if
only source code has been generated, failing graciously or uploading an old binary laying around
- in the build directory. This option calls the \textsc{rpp\_download.m} script, which is in turn a
- wrapper on the \textsc{loadti.sh}, \textsc{loadti.bat} and \textsc{loadopenocd.sh} script. More information on the \textsc{loadti.sh}
+ in the build directory. This option calls the \texttt{rpp\_download.m} script, which is in turn a
+ wrapper on the \texttt{loadti.sh}, \texttt{loadti.bat} and \texttt{loadopenocd.sh} script. More information on the \texttt{loadti.sh}
script can be found in:
\begin{verbatim}
-<css>/ccs_base/scripting/examples/loadti/readme.txt
+<ccs>/ccs_base/scripting/examples/loadti/readme.txt
http://processors.wiki.ti.com/index.php/Loadti
\end{verbatim}
- The \textsc{loadti.sh} and \textsc{loadti.bat} script will close after the
+ The \texttt{loadti.sh} and \texttt{loadti.bat} script will close after the
download of the generated program, leaving the loaded program running.
- The \textsc{loadopenocd.sh} script will close after the download of the
+ The \texttt{loadopenocd.sh} script will close after the download of the
generated program as well, but the program will be stopped. In order to run
the loaded program a manual reset of the board is required.
\item \textbf{Download compiled binary to SDRAM}: This feature is not yet
implemented for the simulink target.
-\item \textbf{Use OpenOCD to download the compiled binary}: This option switches
-from Ti loading script \textsc{loadti.sh} to OpenOCD script
-\textsc{loadopenocd.sh}. The benefit of using OpenOCD, besides that it is open
-source
- software, is much shorter loading time. More information about the right
-OpenOCD version and its installation can be found at:
-\begin{verbatim}
-http://rtime.felk.cvut.cz/hw/index.php/TMS570LS3137#OpenOCD_setup_and_Flashing
-\end{verbatim}
-This feature is available for Linux system only.
+\item \textbf{Use OpenOCD to download the compiled binary}: This feature is not yet
+implemented for the \mcuname{} simulink target.
+% TODO Not true - use conditional compilation here.
\item \textbf{Print model metadata to SCI at start}: if set this option will
print a message to the Serial Communication Interface when the model start
reading.
\item[refs/] Contains third party references, which license allows the
distribution.
- \item[rpp/blocks] Contains the TLC files, which defines the blocks for
-the Matlab Simulink and \textsc{rpp\_lib.slx}, which is the Simulink RPP
-Library, containing all the Simulink blocks for RPP.
+\item[rpp/blocks] Contains the Simulink blocks specific to the
+ \tgtBoardName{} board and their sources (.c and .tlc files). When an
+ user calls \texttt{rpp\_setup.m}, these files are processed and
+ Simulink block library \texttt{rpp\_lib.slx} is created.
\item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the
Matlab Simulink model.
\item[rpp/demos] Contains demo models, which purpose is to serve as a
\item[rpp/rpp] Contains set of support script for the Code Generator.
\end{description}
+\section{Tasking modes}
+\label{sec-singlet-multit-modes}
+
+This section describes two different modes (single- and multi-tasking)
+of how generated code of multi-rate models can be executed. Tasking
+mode can be selected for every model in the configuration dialog as
+described in Section \ref{sec-crating-new-model}.
+
+For single-rate models, the mode selection does not matter. For
+multi-rate models, the mode selection becomes important as it may
+influence certain system properties such as safety or performance.
+
+\subsection{SingleTasking mode}
+\label{sec-singlet-mode}
+In this mode all Simulink tasks, defined by their sampling rate, run
+in a single operating system task (thread). This means that the period
+of the highest rate Simulink task cannot be greater than the
+worst-case execution time of all Simulink tasks together. On the other
+hand, using this mode reduces the risk of failures caused by task
+synchronization errors, e.g. race conditions, deadlocks.
+
+\subsection{MultiTasking mode}
+\label{sec-multit-mode}
+
+In this mode every Simulink task, defined by its sampling rate, runs
+in its own operating system task (thread). Thread priorities are
+assigned based on task rates in such a way that tasks with higher
+rates can preempt tasks with lower rates. This means that the period
+of the fastest sampling rate is limited only by the execution time of
+this task and not of all the tasks in the system.
+
+This mode offers more efficient use of system resources (CPU) but
+there is a possibility of failures caused by task synchronization
+errors.
+
\section{Block Library Overview}
\label{sec-block-library-overview}
The Simulink Block Library is a set of blocks that allows Simulink models to use
\item S-Function: System Function, as opposed to standard functions, or user functions.
\end{compactitem}
-A C-MEX S-Function is a structured C file that implements some mandatory and
+A C MEX S-Function is a structured C file that implements some mandatory and
optional callbacks for a specification of a number of inputs, outputs, data
types, parameters, rate, validity checking, etc. A complete list of callbacks
can be found in:
\htmladdnormallink{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}{http://www.mathworks.com/help/simulink/create-cc-s-functions.html}
\end{quotation}
-The way a C-MEX S-Function participates in a Simulink simulation is shown on the
+The way a C MEX S-Function participates in a Simulink simulation is shown on the
diagram \ref{fig-sfunctions-process}:
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=250px]{images/sfunctions_process.png}
+\includegraphics[scale=.45]{images/sfunctions_process.png}
\caption{Simulation cycle of a S-Function. \cite[p. 57]{simulinkdevelopingsfunctions2013}}
\label{fig-sfunctions-process}
\end{center}\end{figure}
The implementation of the S-Functions in the RPP project has following layout:
\begin{itemize}
- \item Define S-Function name \textsc{S\_FUNCTION\_NAME}.
- \item Include header file \textsc{header.c}, which in connection with
-\textsc{trailer.c} creates a miniframework for writing S-Functions.
- \item In \textsc{mdlInitializeSizes} define:
+ \item Define S-Function name \texttt{S\_FUNCTION\_NAME}.
+ \item Include header file \texttt{header.c}, which in connection with
+\texttt{trailer.c} creates a miniframework for writing S-Functions.
+ \item In \texttt{mdlInitializeSizes} define:
\begin{itemize}
\item Number of \textit{dialog} parameter.
\item Number of input ports.
\end{compactitem}
\item Standard options for driver blocks.
\end{itemize}
- \item In \textsc{mdlCheckParameters}:
+ \item In \texttt{mdlCheckParameters}:
\begin{itemize}
\item Check data type of each parameter.
\item Check range, if applicable, of each parameter.
\end{itemize}
- \item In \textsc{mdlSetWorkWidths}:
+ \item In \texttt{mdlSetWorkWidths}:
\begin{compactitem}
\item Map \textit{dialog} parameter to \textit{runtime} parameters.
\begin{itemize}
\end{itemize}
\end{compactitem}
\item Define symbols for unused functions.
- \item Include trailer file \textsc{trailer.c}.
+ \item Include trailer file \texttt{trailer.c}.
\end{itemize}
-The C-MEX S-Function implemented can be compiled with the following command:
+The C MEX S-Function implemented can be compiled with the following command:
\lstset{language=bash}
\begin{lstlisting}
<matlabroot>/bin/mex sfunction_{mnemonic}.c
\end{lstlisting}
-As noted the standard is to always prefix S-Function with \textsc{sfunction\_}
+As noted the standard is to always prefix S-Function with \texttt{sfunction\_}
and use lower case mnemonic of the block.
-Also a script called \textsc{compile\_blocks.m} is included. The script that
-allows all \textsc{sfunctions\_*.c} to be fed to the \textsc{mex} compiler so
+Also a script called \texttt{compile\_blocks.m} is included. The script that
+allows all \texttt{sfunctions\_*.c} to be fed to the \texttt{mex} compiler so
all S-Functions are compiled at once. To use this script, in Matlab do:
\lstset{language=Matlab}
In order to generate code for each one of the S-Functions, every S-Function implements a TLC file
for \textit{inlining} the S-Function on the generated code. The TLC files describe how to
-generate code for a specific C-MEX S-Function block. They are programmed using TLC own language and
+generate code for a specific C MEX S-Function block. They are programmed using TLC own language and
include C code within TLC instructions, just like LaTeX files include normal text in between LaTeX
macros.
-The standard for a TLC file is to be located under the \textsc{tlc\_c} subfolder from where the
-S-Function is located and to use the very exact file name as the S-Function but with the \textsc{.tlc}
-extension: \textsc{sfunction\_foo.c} \noindent$\rightarrow$ \textsc{tlc\_c/sfunction\_foo.tlc}
+The standard for a TLC file is to be located under the \texttt{tlc\_c} subfolder from where the
+S-Function is located and to use the very exact file name as the S-Function but with the \texttt{.tlc}
+extension: \texttt{sfunction\_foo.c} \noindent$\rightarrow$ \texttt{tlc\_c/sfunction\_foo.tlc}
The TLC files implemented for this project use 3 hook functions in particular (other are available,
see TLC reference documentation):
\begin{itemize}
-\item \textsc{BlockTypeSetup}: \newline{}
+\item \texttt{BlockTypeSetup}: \newline{}
BlockTypeSetup executes once per block type before code generation begins.
This function can be used to include elements required by this block type, like includes or
definitions.
-\item \textsc{Start}: \newline{}
- Code here will be placed in the \textsc{void
+\item \texttt{Start}: \newline{}
+ Code here will be placed in the \texttt{void
$\langle$modelname$\rangle$\_initialize(void)}. Code placed here will execute
only once.
-\item \textsc{Outputs}: \newline{}
- Code here will be placed in the \textsc{void
+\item \texttt{Outputs}: \newline{}
+ Code here will be placed in the \texttt{void
$\langle$modelname$\rangle$\_step(void)} function. Should be used to get the
-inputs o a block and/or to set the outputs of that block.
+inputs of a block and/or to set the outputs of that block.
\end{itemize}
-The general layout of the TLC files implemented for this project are:
+The general layout of the TLC files implemented for this project is:
\begin{itemize}
-\item In \textsc{BlockTypeSetup}: \newline{}
- Call common function \textsc{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
- \textsc{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
-\item \textsc{Start}: \newline{}
+\item In \texttt{BlockTypeSetup}: \newline{}
+ Call common function \texttt{\%$<$RppCommonBlockTypeSetup(block, system)$>$} that will include the
+ \texttt{rpp/rpp\i\_mnemonic.h} header file (can be called multiple times but header is included only once).
+\item \texttt{Start}: \newline{}
Call setup routines from RPP Layer for the specific block type, like HBR enable, DIN pin setup,
DAC value initialization, SCI baud rate setup, among others.
-\item \textsc{Outputs}: \newline{}
+\item \texttt{Outputs}: \newline{}
Call common IO routines from RPP Layer, like DIN read, DAC set, etc. Success of this functions
is checked and in case of failure error is reported to the block using ErrFlag.
\end{itemize}
C code generated from a Simulink model is placed on a file called
-\textsc{$\langle$modelname$\rangle$.c} along with other support files in a
-folder called \textsc{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}.
-For example, the source code generated for model \textsc{foobar} will be placed
-in current Matlab directory \textsc{foobar\_rpp/foobar.c}.
+\texttt{$\langle$modelname$\rangle$.c} along with other support files in a
+folder called \texttt{$\langle$modelname$\rangle$\_$\langle$target$\rangle$/}.
+For example, the source code generated for model \texttt{foobar} will be placed
+in current Matlab directory \texttt{foobar\_rpp/foobar.c}.
-The file \textsc{$\langle$modelname$\rangle$.c} has 3 main functions:
+The file \texttt{$\langle$modelname$\rangle$.c} has 3 main functions:
\begin{compactitem}
-\item \textsc{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
+\item \texttt{void $\langle$modelname$\rangle$\_step(void)}: \newline{}
This function recalculates all the outputs of the blocks and should be called once per step. This
is the main working function.
-\item \textsc{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
+\item \texttt{void $\langle$modelname$\rangle$\_initialize(void)}: \newline{}
This function is called only once before the first step is issued. Default values for blocks IOs
should be placed here.
-\item \textsc{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
- This function is called when terminating the model. This should be used to free memory of revert
- other operations made on the initialization function. With current implementation this function
+\item \texttt{void $\langle$modelname$\rangle$\_terminate(void)}: \newline{}
+ This function is called when terminating the model. This should be used to free memory or revert
+ other operations made in the initialization function. With current implementation this function
should never be called unless an error is detected and in most models it is empty.
\end{compactitem}
This section describes each one of the Simulink blocks present in the Simulink
RPP block library, shown in Figure \ref{fig-block-library}.
-\begin{figure}
-\includegraphics[width=\textwidth]{images/block_library.png}
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=\textwidth]{images/block_library.png}
+ \end{center}
\caption{Simulink RPP Block Library.}
\label{fig-block-library}
\end{figure}
"C:\ti\ccsv5\utils\bin\"gmake.exe lib
\end{lstlisting}
-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}.
+Both commands will create a directory for each compiled demo, which will contain the generated C code and binary file with the firmware. To download the firmware to the board and run it, see Section \ref{sec-running-software-on-hw}.
+\end{enumerate}
+
+ \section{Adding new functionality}
+\label{sec:adding-new-funct}
+This section describes how to create new Simulink blocks and how to add them to the RPP
+blocks library. The new block creation process consists of several steps:
+\begin{enumerate}
+ \item Addition of the new functionality to the RPP C support library.
+ \item Definition of the block interface as a C MEX S-Function
+ (Section~\ref{sec:block-definition-c})
+ \item Compilation of the block definition to MEX file
+ (Section~\ref{sec:c-mex-file})
+ \item Creation of the code generator template (TLC) file
+ (Section~\ref{sec:tlc-file-creation}).
+ \item Creation of an S-Function block in the RPP block library
+ and ``connecting'' this block with the C MEX and TLC files
+ (Section~\ref{sec:creation-an-s})
+ \item Optional: Creation of the mask for the new block. The mask
+ specifies graphical representation of the block as well as
+ the content of the block parameters dialog box.
\end{enumerate}
+The following subsections demonstrate the procedure on an example of a simple user defined block.
+
+\subsection{Block interface definition in a C MEX S-function}
+\label{sec:block-definition-c}
+In order to use a custom block in the Simulink model, Simulink must know
+a certain number of block attributes, such as the number and type of
+block inputs, outputs and parameters. These attributes are specified
+by a set of functions in a C file. This C file gets compiled by the MEX
+compiler into a MEX file and is then used in an S-Function block.
+Simulink calls the functions in the C MEX file to obtain the above
+mentioned block attributes. In case of RPP blocks, no other
+functionality is present in the C MEX file.
+
+The C files are stored in \texttt{\repo/rpp/blocks} directory and are named as
+\texttt{sfunction\_$\langle$name$\rangle$.c}. Feel free to open any of
+the C files as a reference.
+
+Every C file that will be used with the RPP library should begin with
+a comment in YAML\footnote{\url{http://yaml.org/},
+ \url{https://en.wikipedia.org/wiki/YAML}} format. The information in
+this block is used to automatically generate both printed and on-line
+documentation. Although this block is not mandatory, it is highly
+recommended, as it helps keeping the documentation consistent and
+up-to-date.
+
+The YAML documentation block may look like this:
+\begin{lstlisting}[language=c,basicstyle=\tt\footnotesize]
+/*
+%YAML 1.2
+---
+Name: Name Of The Block
+Category: IO blocks
+Header: rpp/sci.h
+Mnemonic: MBLK
+
+Inputs:
+ - { name: "Some Input Signal", type: "bool" }
+
+Outputs:
+ - { name: "Some Output Signal", type: "bool" }
+
+Parameters:
+
+# Description and Help is in Markdown mark-up
+Description: |
+
+ This is a stub of an example block.
+
+Help: |
+
+ This block is a part of an example about how to create
+ new Matlab Simulink blocks for RPP board.
+
+Status: Unstable
+
+RPP API functions used:
+ - rpp_sci_print()
+
+Relevant demos:
+...
+*/
+\end{lstlisting}
+
+Following parts are obligatory and the block will not work without them. It starts with a
+definition of the block name and inclusion of a common source file:
+
+\begin{lstlisting}[language=c]
+#define S_FUNCTION_NAME sfunction_myblock
+#include "header.c"
+\end{lstlisting}
+
+To let Simulink know the type of the inputs, outputs and how many parameters
+will the block have, the \texttt{mdlInitializeSizes()} function has to be defined like this:
+
+\begin{lstlisting}[language=c]
+static void mdlInitializeSizes(SimStruct *S)
+{
+ /* The block will have no parameters. */
+ if (!rppSetNumParams(S, 0)) {
+ return;
+ }
+ /* The block will have one input signal. */
+ if (!ssSetNumInputPorts(S, 1)) {
+ return;
+ }
+ /* The input signal will be of type boolean */
+ rppAddInputPort(S, 0, SS_BOOLEAN);
+ /* The block will have one output signal */
+ if (!ssSetNumOutputPorts(S, 1)) {
+ return;
+ }
+ /* The output signal will be of type boolean */
+ rppAddOutputPort(S, 0, SS_BOOLEAN);
+
+ rppSetStandardOptions(S);
+}
+\end{lstlisting}
+
+The C file may contain several other optional functions definitions for parameters check,
+run-time parameters definition and so on. For information about those functions refer the comments
+in the header.c file, trailer.c file and documentation of Simulink S-Functions.
+
+The minimal C file compilable into C MEX has to contain following
+macros to avoid linker error messages about some of the optional
+functions not being defined:
+\begin{lstlisting}[language=c]
+#define COMMON_MDLINITIALIZESAMPLETIMES_INHERIT
+#define UNUSED_MDLCHECKPARAMETERS
+#define UNUSED_MDLOUTPUTS
+#define UNUSED_MDLTERMINATE
+\end{lstlisting}
+
+Every C file should end by inclusion of a common trailer source file:
+
+\begin{lstlisting}[language=c]
+#include "trailer.c"
+\end{lstlisting}
+
+\subsection{C MEX file compilation}
+\label{sec:c-mex-file}
+In order to compile the created C file, the development environment
+has to be configured first as described in
+Section~\ref{sec-matlab-simulink-usage}.
+
+All C files in the directory \texttt{\repo/rpp/blocks} can be compiled
+into C MEX by running script
+\texttt{\repo/rpp/blocks/compile\_blocks.m} from Matlab command
+prompt. If your block requires some special compiler options, edit the
+script and add a branch for your block.
+
+To compile only one block run the \texttt{mex sfunction\_myblock.c}
+from Matlab command prompt.
+
+\subsection{TLC file creation}
+\label{sec:tlc-file-creation}
+The TLC file is a template used by the code generator to generate the
+C code for the RPP board. The TLC files are stored in
+\texttt{\repo/rpp/blocks/tlc\_c} folder and their names must be the
+same (except for the extension) as the names of the corresponding
+S-Functions, i.e. \texttt{sfunction\_$\langle$name$\rangle$.tlc}. Feel
+free to open any of the TLC files as a reference.
+
+TLC files for RPP blocks should contain a header:
+\begin{lstlisting}[language=c]
+%implements sfunction_myblock "C"
+%include "common.tlc"
+\end{lstlisting}
+
+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:
+\begin{enumerate}
+ \item BlockTypeSetup
+ \item BlockInstanceSetup
+ \item Start
+ \item Outputs
+\end{enumerate}
+
+For detailed description about each one of those functions, refer to
+\cite{targetlanguagecompiler2013}. A simple TLC file, which generates
+some code may look like this:
+\begin{lstlisting}[language=c]
+%implements sfunction_myblock "C"
+%include "common.tlc"
+
+%function BlockTypeSetup(block, system) void
+ %% Ensure required header files are included
+ %<RppCommonBlockTypeSetup(block, system)>
+ %<LibAddToCommonIncludes("rpp/sci.h")>
+%endfunction
+
+%function Outputs(block, system) Output
+ %if !SLibCodeGenForSim()
+ %assign in_signal = LibBlockInputSignal(0, "", "", 0)
+ %assign out_signal = LibBlockOutputSignal(0, "", "", 0)
+
+ %<out_signal> = !%<in_signal>;
+ rpp_sci_printf("Value: %d\r\n", %<in_signal>);
+%endif
+%endfunction
+%% [EOF]
+\end{lstlisting}
+
+The above template causes the generated code to contain
+\texttt{\#include "rpp/sci.h"} line and whenever the block is
+executed, its output will be the negation of its input and the value
+of the input signal will be printed to the serial line.
+
+\subsection{Creation of an S-Function block in the RPP block library}
+\label{sec:creation-an-s}
+User defined Simulink blocks can be included in the model as
+S-Function blocks. Follow this procedure to create a new block in the
+RPP block library:
+\begin{enumerate}
+\item Create a new Simulink library by selecting
+ \textsc{File$\rightarrow$New$\rightarrow$Library} and save it as
+ \texttt{\repo\-/rpp/blocks/rpp\_$\langle$name$\rangle$.slx}.
+ Alternatively, open an existing library.
+\item In case of opening an existing library, unlock it for editing by
+ choosing \textsc{Diagram$\rightarrow$Unlock Library}.
+\item Open a Simulink Library Browser
+ (\textsc{View$\rightarrow$Library Browser}) open
+ \textsc{Simulink$\rightarrow$User-Defined Functions} and drag the
+ \textsc{S-Function} block into the newly created library.
+\item Double click on the just created \textsc{S-Function} block and
+ fill in the \textsc{S-function name} field. Put there the name
+ (without the extension) of the created C MEX S-Function, e.g.
+ sfunction\_myblock. The result should like like in
+ Figure~\ref{fig-simulink_s_fun_cfg}.
+ \begin{figure}[h]\begin{center}
+ \noindent
+ \includegraphics[scale=.45]{images/simulink_s_fun_config.png}
+ \caption{Configuration dialog for user defined S-function.}
+ \label{fig-simulink_s_fun_cfg}
+ \end{center}\end{figure}
+\item If your block has some parameters, write their names (you can
+ choose them arbitrarily) in the \textsc{S-function parameters}
+ field, separated by commas. \label{item:1}
+\item Now you should see the new Simulink block with the right number
+ of inputs and outputs.
+\item Optional: Every user-defined block can have a \emph{mask}, which
+ provides some useful information about the name of the block,
+ configuration dialog for parameters and names of the IO signals. The
+ block can be used even without the mask, but it is not as user
+ friendly as with proper mask. Right-click the block and select
+ \textsc{Mask$\rightarrow$Create Mask...}. In the definition of
+ parameters, use the same names as in step~\ref{item:1}. See
+ \cite[Section ``Block Masks'']{mathworks13:simul_2013b} for more
+ information.
+\item Save the library and run \texttt{rpp\_setup} (or just
+ \texttt{rpp\_generate\_lib}) from Matlab command line to add the newly
+ created block to RPP block library (\texttt{rpp\_lib.slx}).
+\end{enumerate}
+
+Now, you can start using the new block in Simulink models as described
+in Section~\ref{sec-crating-new-model}.
+
\section{Demos reference}
The Simulink RPP Demo Library is a set of Simulink models that use blocks from
In the reference below you can find a complete description for each of the demos.
-\subsection{Analog pass-through}
+\subsection{ADC demo}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_analog_passthrough.png}
-\caption{Analog Passthrough Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_adc.png}
+\caption{Example of the usage of the Analog Input blocks for RPP.}
\end{center}\end{figure}
\textbf{Description:}
-This demo will read analog input 1 and write it to analog output 1.
-
-In laboratory the minimum read value for analog input a 0 volts is 107. The maximum read at 12
-volts is 2478. The map subsystem will map the input domain (ADC)\textsc{[110, 2400]} to the output domain
-(DAC)\textsc{[0, 4095]}.
+Demostrates how to use Analog Input blocks in order to measure voltage. This demo
+measures voltage on every available Analog Input and prints the values on the
+Serial Interface.
-\subsection{Analog sinewave}
+\subsection{Simple CAN demo}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_analog_sinewave.png}
-\caption{Analog Sinewave Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_simple_can.png}
+\caption{The simplest CAN demonstration.}
\end{center}\end{figure}
\textbf{Description:}
-This demo will generate a sinewave on analog output 1. The frequency
-of the sine wave is 10Hz and sampling rate is set to
-1000Hz (driven from Simulink step of 1ms, same as operating system). Amplitude is set to use DAC
-full range [0-4095] which means output amplitude will be [0-12] volts.
-
-The Software oscilloscope shown should match an external one connected to DAC 1.
-
-Note that the driver configuration of the MCP4922 is set to unbuffered (which should eventually
-be changed to buffered) and thus the last resolution millivolts are lost.
+The simplest possible usage of the CAN bus. This demo is above all designed for
+testing the CAN configuration and transmission.
\subsection{CAN transmit}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_cantransmit.png}
+\includegraphics[scale=.45]{images/demo_cantransmit.png}
\caption{Example of the usage of the CAN blocks for RPP.}
\end{center}\end{figure}
\item Use function-call mechanism to process received messages
\end{compactenum}
-\subsection{CAN demo}
-
+\subsection{Continuous time demo}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_can_demo.png}
-\caption{CAN bus demo for RPP.}
+\includegraphics[scale=.45]{images/demo_continuous.png}
+\caption{The demonstration of contiuous time.}
\end{center}\end{figure}
\textbf{Description:}
-This demo demonstrates simple processing of received messages.
+This demo contains two integrators, which are running at continuous time. The main goal
+of this demo is to verify that the generated code is compilable and is working even when
+discrete and continuous time blocks are combined together.
-\subsection{Digital pass-through}
+\subsection{Simulink Demo model}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=400px]{images/demo_digital_passthrough.png}
-\caption{Digital Pass-through Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_board.png}
+\caption{Model of the complex demonstration of the boards peripherals.}
\end{center}\end{figure}
\textbf{Description:}
-This demo will directly pass the digital values read on DIN [1-8] to LOUT [1-8], and thus acting
-as a digital pass-through or gateway.
+This model demonstrates the usage of RPP Simulink blocks in a complex and interactive
+application. The TI HDK kit has eight LEDs placed around the MCU. The application
+rotates the light around the MCU in one direction. Every time the user presses the button
+on the HDK, the direction is switched.
+
+The state of the LEDs is sent on the CAN bus as a message with ID 0x1. The button can
+be emulated by CAN messages with ID 0x0. The message 0x00000000 simulates button release
+and the message 0xFFFFFFFF simulates the button press.
-Also note that all the ErrFlag are aggregated on a global ErrFlag.
+Information about the state of the application are printed on the Serial Interface.
\subsection{Echo char}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_echo_char.png}
+\includegraphics[scale=.45]{images/demo_echo_char.png}
\caption{Echo Character Simulink demo for RPP.}
\end{center}\end{figure}
\textbf{Description:}
-This demo will echo twice (print back) any character received through the Serial Communication
-Interface (9600-8-N-1).
+This demo will echo (print back) any character received through the Serial Communication
+Interface (115200-8-N-1).
Note that the send subsystem is implemented a as \textit{triggered} subsystem and will execute only
if data is received, that is, Serial Receive output is non-negative. Negative values are errors.
-
-\subsection{H-bridge analog control}
+\subsection{GIO demo}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_hbridge_analog_control.png}
-\caption{H-Bridge Analog Control Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_gio.png}
+\caption{Demonstration of DIN and DOUT blocks}
\end{center}\end{figure}
\textbf{Description:}
-This demo will read values from the analog input, map them, and control the H-Bridge. This allows
-a motor connected to the H-Bridge to be controlled with a potentiometer connected to Analog Input 1.
-
-Setting the potentiometer to output around 6 volts will stop the motor. Less (or greater) than 6
-volts will trigger the motor in one sense (or in the other sense) and speed proportional with 1\%
-resolution.
-
-In laboratory the minimum read value for analog input is 107 at 0 volts. The maximum read at 12 volts
-is 2478. The map subsystem will map the input domain (ADC)\textsc{[110, 2400]} to the output domain
-(HBR)\textsc{[-1.0, 1.0]}.
-
-
-\subsection{H-bridge digital control}
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=450px]{images/demo_hbridge_digital_control.png}
-\caption{H-Bridge Digital Control Simulink demo for RPP.}
-\end{center}\end{figure}
-
-\textbf{Description:}
-
-This demo toggle the H-Bridge from stop to full speed in one direction using digital input 1.
-So basically is a ON/OFF switch on DIN 1 for a motor connected on the HBR. Note the data type
-conversion because the output of the DIN is a boolean and the input to the HBR is a double.
-
-\subsection{H-bridge sine wave control}
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=300px]{images/demo_hbridge_sinewave_control.png}
-\caption{H-Bridge Sinewave Control Simulink demo for RPP.}
-\end{center}\end{figure}
-
-\textbf{Description:}
-
-This demo will generate a sine wave to control the H-Bridge. Sine wave is one period per 20
-seconds or 0.05Hz. Sampling rate is 20Hz or 100 samples per 1/4 of period (for 1\% speed
-resolution change).
-
-Note that the Software oscilloscope should is not the output of the H-Bridge, the H-Bridge will
-change current sense and the duty cycle of the pulse that drive it (PWM), it does not output
-analog values. The Software oscilloscope just shows what the input to the HBR block is.
+The model demonstrates how to use the DIN blocks and DOUT blocks, configured in every mode. The DOUTs
+are pushed high and low with period 1 second. The DINs are reading inputs and printing the values
+on the Serial Interface with the same period.
\subsection{Hello world}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_hello_world.png}
+\includegraphics[scale=.45]{images/demo_hello_world.png}
\caption{Hello World Simulink demo for RPP.}
\end{center}\end{figure}
\textbf{Description:}
-This demo will print \textsc{"Hello Simulink"} to the Serial Communication Interface (9600-8-N-1) one
+This demo will print \texttt{Hello Simulink} to the Serial Communication Interface (115200-8-N-1) one
character per second. The output speed is driven by the Simulink model step which is set to one
second.
-\subsection{IRC input}
-\begin{figure}[H]\begin{center}
-
-\noindent
-\includegraphics[width=450px]{images/demo_irc_input.png}
-\caption{LED Blink Simulink demo for RPP.}
-\end{center}\end{figure}
+\subsection{Multi-rate SingleTasking demo}
+\label{sec:mult-single-thre}
-\textbf{Description:}
-
-This demo is printing IRC sensor (connected to DIN10 and DIN11) value to the Serial Communication
-Interface (115200-8-N-1) with six values to one line.
-
-\subsection{LED blink}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=450px]{images/demo_led_blink.png}
-\caption{LED Blink Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_multirate_st.png}
+\caption{Multi-rate SingleTasking Simulink demo for RPP.}
\end{center}\end{figure}
\textbf{Description:}
-This the simplest demo of all that shows the basics of using the RPP target and blocks. The
-goal of this demo is to show the configuration of the model (not shown on the picture above),
-that is, how the RPP Simulink Coder Target is setup, general model setup and step setup.
+This demo will toggle LEDs on the Hercules Development Kit with
+different rate. This is implemented with multiple Simulink tasks, each
+running at different rate. In the generated code, these tasks are
+called from a singe thread and therefore no task can preempt another
+one. See Section \ref{sec-singlet-mode} for more details.
-This demo will toggle each second a LED connected on LOUT 1. The timing is set by the Simulink
-model step which is set to 1 second.
+The state of each LED is printed to the Serial Communication Interface
+(115200-8-N-1) when toggled.
-\subsection{LED blink all}
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=350px]{images/demo_led_blink_all.png}
-\caption{LED Blink All Simulink demo for RPP.}
-\end{center}\end{figure}
-
-\textbf{Description:}
-
-This demo will toggle all LEDs connected to the LOUT port. Even outputs pins will be negated.
-Toggle will happen each second. The timing is driven by Simulink model step configuration that
-is set to 1 second. All blocks ErrFlags are aggregated into one global ErrFlag.
-
-\subsection{Log analog input}
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=450px]{images/demo_log_analog_input.png}
-\caption{Log Analog Input Simulink demo for RPP.}
-\end{center}\end{figure}
-
-\textbf{Description:}
+\begin{center}
+ \begin{tabular}{lll}
+ \rowcolor[gray]{0.9}
+ LED & pin & rate [s] \\
+ 1 & NHET1\_25 & 0.3 \\
+ 2 & NHET1\_05 & 0.5 \\
+ 3 & NHET1\_00 & 1.0 \\
+ \end{tabular}
+ \captionof{table}{LEDs connection and rate}
+ \label{tab:multirate_st_led_desc}
+\end{center}
-This demo will log once per second the value read on the analog input 1. User can read the log
-using the SCI logging integrated command processor (9600-8-N-1). Logging block ID set to 1. The
-timing is driven by Simulink model step configuration that is set to 1 second.
+\subsection{Multi-rate MultiTasking demo}
+\label{sec:mult-multi-thre}
-\subsection{Power toggle}
\begin{figure}[H]\begin{center}
\noindent
-\includegraphics[width=300px]{images/demo_power_toggle.png}
-\caption{Power Toggle Simulink demo for RPP.}
+\includegraphics[scale=.45]{images/demo_multirate_mt.png}
+\caption{Multi-rate MultiTasking Simulink demo for RPP.}
+\label{fig:multitasking-demo}
\end{center}\end{figure}
\textbf{Description:}
-This demo will toggle the power output once per second. If an error is detected on at least one of
-the outputs a generic error message is printed to the serial line. The timing is driven by Simulink
-model step configuration that is set to 1 second. Power outputs can drive a load up to 2A, so please
-take into account required safety considerations.
-
-\subsection{Simulink Demo board}
-Model for demo board has 6 subsystems. Every subsystem will be described separately.
-\begin{figure}[H]\begin{center}
-\noindent
-\includegraphics[width=0.8\textwidth]{images/demo_board-connection_scheme.pdf}
-\caption{Demo board connection and usage scheme.}
-\end{center}\end{figure}
-
-\subsubsection{Potentiometer regulation of motor speed}
-This is example of driving motor with input signal. Motor can be rotated in
-various speed in both directions and stopping motor means setting potentiometer
-to half of its range. Potentiometer value is also transmitted through CAN.
-
-\subsubsection{Color music}
-This is showing abilities of RPP board to generate analog signals. Bargraphs on
-demo board are showing value of analog outputs. Speed of change can be changed
-with potentiometer and in one case is used motor 2 IRC. There are five different
-modes. Three of them are derived from sinus and rest of them are counter value
-and direct control. Modes can be changed with black button. First mod selected
-after board start is fifth.
-\begin{enumerate}
-\item Sinus signal is sequential delayed by 10 steps for second and third bargraph.
-\item Sinus signal on second bargraph is shifted by 120° and on third one is shifted by 240°.
-\item Sinus signal for second and third bargraphs are shifted same as in
-previous mode, but as counter value is used IRC value with appropriate divider
-no potentiometer value.
-\item Visualizing counter value which speed is changed
-with potentiometer.
-\item Potentiometer value is passed to all bargraphs with appropriate multiplier.
-\end{enumerate}
-
-\subsubsection{Buttons and LEDs}
-This is example of digital input/output. LEDs on demo board can be driven with
-four different subprograms. These subprograms can be changed with red button and
-are influenced with green and blue buttons.
-\begin{enumerate}
-\item One LED is always ON and others are OFF. Every 0.1 sec is neighborhood LED
-switched on and previous one is switched off. With buttons you can change
-direction.
-\item Same as previous mode, but change is not done after 0.1 sec
-but only when button is pressed.
-\item In this mode you can record message in Morse code (max 64 chars including
-spaces) and after delay it is repetitively replayed. To record message use green
-button as dash and blue button as dot.
-\item Simple game in which you must determine if light is moving left or right
-and press green or blue button according to it. Speed of movement is increasing
-and in case of wrong answer or long delay is game ends with lights flashing.
-\end{enumerate}
+This demo toggles LEDs on the Hercules Development Kit with different
+rate (different colors in Figure~\ref{fig:multitasking-demo}). This is
+implemented with multiple Simulink tasks, each running at different
+rate. In the generated code, every subrate task runs in its own
+operating system thread. See Section \ref{sec-multit-mode} for more
+details.
-\subsubsection{IRC to CAN}
-IRC value from Motor 2 is sent every tenth step via CAN2 with message ID 0x4.
+The state of each LED is also printed to the Serial Communication
+Interface (115200-8-N-1) when toggled.
-\subsubsection{CAN receive -- Button press emulation}
-You can simulate press of all four buttons by sending message through CAN2 to
-board with message ID 0x0 and value according to button number.
+\begin{center}
+ \begin{tabular}{lll}
+ \rowcolor[gray]{0.9}
+ LED & pin & rate [s] \\
+ 1 & NHET1\_25 & 0.3 \\
+ 2 & NHET1\_05 & 0.5 \\
+ 3 & NHET1\_00 & 1.0 \\
+ \end{tabular}
+ \captionof{table}{LEDs connection and rate}
+ \label{tab:multirate_mt_led_desc}
+\end{center}
-\subsubsection{Configuration and error handling}
-RPP supports some basic runtime error handling. Every block can set its error
-flag, all these error flags are joined in this demo together and when some
-problem is detected CAN2 message of ID 0x10 is transmitted. Also in case of
-board overrun (exhaustion of time quanta) is transmitted message through CAN2
-with ID 0x11.\\ When model is build without external mode, errors are also
-printed to SCI.
-\subsubsection{Full list of CAN communication}
-The board produces CAN frames with the following IDs:
-\begin{itemize}
-\item 0x05: Potentiometer 1 value.
-\item 0x06: Potentiometer 2 value.
-\item 0x08: Selected mod of color music.
-\item 0x09: Active subprogram of buttons and LEDs.
-\item 0x10: Transmitted only in case of error flag of some block, error code.
-\item 0x11: Transmitted only in case of board overrun, no data.
-\end{itemize}
-The board reacts to CAN frames with following IDs:
-\begin{itemize}
-\item 0x00: Simulate button press, accepts value 1--4.
-\end{itemize}
\chapter{Command line testing tool}
\label{chap-rpp-test-software}
\section{Introduction}
\label{sec-rpp-test-sw-intro}
-The \textsc{rpp-test-suite} is a RPP application developed testing and direct
+The \texttt{rpp-test-suite} is a RPP application developed testing and direct
control of the RPP hardware. The test suite implements a command processor,
-which is listening for a commands and prints some output related to the commands
+which is listening for commands and prints some output related to the commands
on the serial interface. The command processor is modular and each peripheral
-has its commands in a separated module.
+has its commands in a separate module.
-The command processor is implemented in \textsc{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
-modules are implemented in \textsc{$\langle$rpp-test-sw$\rangle$/commands} directory.
+The command processor is implemented in \texttt{$\langle$rpp-test-sw$\rangle$/cmdproc} and commands
+modules are implemented in \texttt{$\langle$rpp-test-sw$\rangle$/commands} directory.
The application enables a command processor using the SCI at
\textbf{115200-8-N-1}. When the software starts, the received welcome message
and prompt should look like:
+
+\ifx\tgtId\tgtIdTMSRPP
+\begin{verbatim}
+Rapid Prototyping Platform v00.01-001
+Test Software version v0.2-261-gb6361ca
+CTU in Prague 2014
+-->
+\end{verbatim}
+\else
\begin{verbatim}
-TODO: FILL
+Ti HDK \mcuname, FreeRTOS 7.0.2
+Test Software version eaton-0.1-beta-8-g91419f5
+CTU in Prague 10/2014
+-->
\end{verbatim}
+\fi
Type in command help for a complete list of available command, or help command
for a description of concrete command.
\section{Compilation}
\label{sec-rpp-test-sw-compilation}
-Before the Testing tool can be compiled, the RPP Library has to be built and the binary file \textsc{rpp-lib.lib} has to be present in the \textsc{\repo/rpp-lib/} directory. Once this requirement is fulfilled, there are two ways how to compile the Testing tool.
+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.
\begin{enumerate}
\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}.
\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}.
\textit{Analog Output.} \newline{}
Mnemonic to refer to or something related to the analog output (DAC) hardware module.
+\item[API] \textit{Application Programming Interface}
+
\item[CAN]
\textit{Controller Area Network.} \newline{}
The CAN Bus is a vehicle bus standard designed to allow microcontrollers and devices to
In this project it is also used as mnemonic to refer to or something related to the CAN
hardware module.
+\item[CCS] \textit{Code Composer Studio} \\
+ Eclipse-based IDE provided by Texas Instruments.
+
\item[CGT]
\textit{Code Generation Tools.} \newline{}
Name given to the tool set produced by Texas Instruments used to compile, link, optimize,
Matlab tool that allows to generate source code for S-Functions given the descriptor of a C
function call.
-\item[LIN]
- \textit{Local Interconnect Network.} \newline{}
- The LIN is a serial network protocol used for communication between components in vehicles.
- In this project it is also used as mnemonic to refer to or something related to the LIN
- hardware module.
-
-\item[LOUT]
- \textit{Logic Output.} \newline{}
- Mnemonic to refer to or something related to the digital output hardware module.
- It is logic output (100mA), as opposed to power outputs (2A, 10A).
-
\item[MBD]
\textit{Model-Based Design.} \newline{}
Model-Based Design (MBD) is a mathematical and visual method of addressing problems associated
used is `C MEX S-Function", which means Matlab executable written in C that implements a system
function.
-\item[MOUT]
- \textit{(Motor) Power Output.} \newline{}
- Mnemonic to refer to or something related to the 2A push/pull power output hardware module.
-
\item[PWM]
\textit{Pulse-width modulation.} \newline{}
Technique for getting analog results with digital means. Digital control is used to create a
the time that the signal spends off. The duration of ``on time" is called the pulse width or
\textit{duty cycle}.
-\item[RPP]
- \textit{Rapid Prototyping Platform.} \newline{}
- Name of the automotive hardware board. Also generic term to define something related
- to the board, like the RPP Library, RPP Layer, RPP API, etc.
+\item[RPP] \textit{Rapid Prototyping Platform.} \newline{} Name of the
+ developed platform, that includes both hardware and software.
\item[SCI]
\textit{Serial Communication Interface.} \newline{}
Hardware circuitry that translates data between parallel and serial forms.
\end{description}
-\bibliography{rpp_simulink}
-\bibliographystyle{plain}
+\printbibliography
\end{document}
-% LocalWords: FreeRTOS RPP POSIX
+% LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests
+% LocalWords: MCU UART microcontrollers DAC CCS simulink SPI GPIO
+% LocalWords: IOs HDK TMDSRM
projects / pes-rpp / rpp-simulink.git / blobdiff