\addtolength{\parskip}{\baselineskip} % Paragraph spacing
\chapter{Introduction}
-\label{chap: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
provides an overall description of the hardware design and architecture of its control software.
\section{Background}
-\label{sec: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.
Besides the right MCU, an operating system is necessary for nontrivial applications. The RPP board runs FreeRTOS, which is opensource operating system with real-time kernel not only for embedded systems. The FreeRTOS provides an API for creation and managing multiple tasks, scheduler, memory manager, semaphores, queues, mutexes, timers and lots of other features that can be used in the applications. TODO: add ref to FreeRTOS pages
-Even with the operating system it is quite hard and non-intuitive to control the hardware directly. That is the point when abstraction comes in the play. RPP software is made of several layers implementing from the bottom to the top driver to the hardware itself, hardware abstraction for common functionality on different hardware and final API which is easy for the user to use. The whole thing, the operating system and the control software, can be compiled as a library and easily used in any project. More details about this can be found in Chapter 3 TODO: add link to the C Library chapter
+Even with the operating system it is quite hard and non-intuitive to control the hardware directly. That is the point when abstraction comes in the play. RPP software is made of several layers implementing from the bottom to the top driver to the hardware itself, hardware abstraction for common functionality on different hardware and final API which is easy for the user to use. The whole thing, 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}.
-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 room for making mistakes has to be as small as possible. An approach called Model-based development has been introduced. In Simulink the application is developed as a model made of blocks connected together. 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 room for making mistakes during the application development has significantly decreased and developers can focus on the functionality instead of the hardware and control software implementation. More information about Code generation can be found in Chapter 4. TODO: add link to the chapter 4
+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 room for making mistakes has to be as small as possible. An approach called Model-based development has been introduced. In Simulink the application is developed as a model made of blocks connected together. 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 room for making mistakes during the application development has significantly decreased and developers can focus on the functionality instead of the hardware and control software implementation. More information about Code generation can be found in Chapter \ref{chap-simulink-coder-target}.
\section{Software architecture}
-\label{sec:software_architecture}
-The RPP control software, also called RPP library, is structured into 5 layers, described in Figure \ref{layers}, with the following guidelines:
+\label{sec-software-architecture}
+The RPP control software, also called RPP library, is structured into 5 layers, described in Figure \ref{fig-layers}, with the following guidelines:
\begin{compactitem}
\item Top-down dependency only. No lower layer depends on anything from upper layers.
\noindent
\includegraphics[width=250px]{images/layers.pdf}
\caption{The RPP library layers.}
-\label{layers}
+\label{fig-layers}
\end{center}
\end{figure}
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. Thanks to this layer it is possible 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 <lib\_root>/os folder.
TODO: add description of the available FreeRTOS versions
\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 code for controlling some of the MCU peripherals. The source files can be found in <lib-root>/rpp/src/sys, the header files can be found in <lib-root>/rpp/include/sys folder.
\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 and names the pins 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 <library-root>/rpp/src/hal and the header files can be found in <library-root>/rpp/include/hal folder.
\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, which would not be very intuitive for the user. For example the H-bridge need a watchdog reset task to be started before the bridge is enabled.
The source files can be found in <library-root>/rpp/src/drv and the header files can be found in <library-root>/rpp/include/drv folder.
\subsection{RPP Layer}
The RPP Layer is the highest layer of the control software. This layer provides the easiest set of functions for every peripheral and requires only basic knowledge about them. For example the H-bridge again from the previous section. The user can call just 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.
+\label{sec-rpp-layer}
The source files can be found in <library-root>/rpp/src/rpp and the header files can be found in <library-root>/rpp/include/rpp folder.
\section{Hardware description}
+\label{sec-hardware-description}
This section provides reference documentation for the RPP board:
\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.
\subsection{Connectors pinout}
+\label{sec-connector-pinout}
The pinout of the board, described by the Figure \ref{pinout}, follows the layout. 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
\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
\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{}
\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.
\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.
\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.
\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.
\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.
\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.
\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.
\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.
\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}
\section{Document structure}
+\label{sec-document-structure}
The general layout of this document is as follows:
\chapter{Getting started}
-\label{sec:getting-started}
+\label{chap-getting-started}
\section{Software requirements}
+\label{sec-software-requirements}
The RPP software stack was developed to be functional on both platforms Windows and Linux. Despite of older and newer versions of the software and tools might work as well, usage of the following versions is suggested:
-\subsection{Linux environment}
+\subsection{Linux environment}
+\label{sec-linux-environment}
\begin{itemize}
\item Debian based 64b Linux distribution (Debian 7.0 or Ubuntu 14.4 for example).
\item Kernel version 3.11.0-12.
\end{itemize}
\subsection{Windows environment}
+\label{sec-windows-environment}
\begin{itemize}
\item Windows 7 Enterprise 64b Service Pack 1.
\item C/C++ compiler from Windows SDK
\end{itemize}
\section{Software and tools}
+\label{sec-software-and-tools}
\subsection{TI Code Composer Studio}
+\label{sec-ti-ccs}
Code Composer Studio (CCS) is the official Integrated Development Environment (IDE) for developing
The version used in this project is the 5.5.0.00077.
\subsubsection{Installation on Linux}
+\label{sec-installation-on-linux}
Download CCS for Linux from:
And change key \textsc{org.eclipse.ui/showIntro} to 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:
Once downloaded run the ccs\_setup\_5.5.0.00077.exe and install the CCS.
\subsubsection{ First launch }
+\label{sec-first-launch}
If another licence is not available, Choose ``FREE License - for use with XDS100 JTAG Emulators" on the licensing options. Code download
for the board is using that particular hardware.
\subsection{Matlab/Simulink}
+\label{sec-matlab-simulink}
Matlab Simulink is a set of tools, runtime environment and development environment for Model-Based applications development, simulations and generation code for target platforms.
Supported Matlab/Simulink version is R2013b for 64 bits Linux and Windows.
\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 Linux and Bray terminal for Windows.
\end{quotation}
\subsection{C Compiler}
+\label{sec-c-compiler}
In order to be able to compile Matlab Simulink blocks S-functions a C language compiler has to be available on the development system.
For Linux a GCC 4.8.1 compiler is recommended and can be installed with command
\end{quotation}
\section{Code Composer Studio usage}
+\label{sec-code-composerpstudio-usage}
\subsection{Opening of existing project}
+\label{sec-openning-of-existing-project}
The project opening procedure is similar to standard Eclipse project opening.
\begin{enumerate}
\item Launch Code Composer Studio
\item Select File->Import
- \item In the dialog window select Code Composer Studio -> Existing CCS Eclipse project as an import source as depicted in Figure \ref{fig:import-project}.
+ \item In the dialog window select Code Composer Studio -> Existing CCS Eclipse project as an import source as depicted in Figure \ref{fig-import-project}.
\item In the next dialog window click on Browse button and find the root directory of the project.
- \item Select the requested project in the Discovered project section so that the result looks like in Figure \ref{fig:select-project}.
+ \item Select the requested project in the Discovered project section so that the result looks like in Figure \ref{fig-select-project}.
\item Click on Finish button.
\end{enumerate}
\begin{center}
\includegraphics[scale=1.00]{images/import_project.png}
\captionof{figure}{Import project dialog}
- \label{fig:import-project}
+ \label{fig-import-project}
\end{center}
\begin{center}
\includegraphics[scale=1.00]{images/select_project.png}
\captionof{figure}{Select project dialog}
- \label{fig:select-project}
+ \label{fig-select-project}
\end{center}
\subsection{Creating new project}
+\label{sec-creating-new-project}
In \textsc{\repo/rpp/lib/apps/} there are two RPP base
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
\end{center}
\section{Matlab Simulink usage}
+\label{sec-matlab-simulink-usage}
\subsection{Configuring Simulink for RPP}
+\label{sec-configuration-simulink-for-rpp}
\begin{enumerate}
\item Download and install CCS for Linux:
The same procedure can be used to openning any other models.
\subsection{Creating new model}
+\label{sec-crating-new-model}
\begin{enumerate}
\item Open or create a model you want to generate code from.
\item Make sure that the model is configured (Simulation $\rightarrow$
\item Generate the code by choosing ``Code $\rightarrow$ C/C++ Code
$\rightarrow$ Build Model''.
\item If \emph{Download compiled binary to RPP} was selected in
- \emph{RPP Options} pane (see Section \ref{sec:rpp-target-options}),
+ \emph{RPP Options} pane (see Section \ref{sec-rpp-target-options}),
the compiled binary will be downloaded to the to the board. The program
will start running right after the loading is finished.
TODO: implement
\chapter{C Support Library}
+\label{chap-c-support-library}
This chapter describes the implementation of a C support library (RPP Library) to provide an overall
insight for future development.
\section{Description}
+\label{sec-description}
TODO create links to chapters
The RPP C Support Library (also called RPP library) defines the API for communication with the board. It includes drivers and operating system. This support library is used in modules described in Chapter X and X. It 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 with the name rpp-lib.lib and can be found in <library-root>.
The RPP library can be used in any project, where the RPP hardware support is required and is also used in two modules, described later in this document. The Command line testing tool, described in Chapter and Simulink Coder target, described in Chapter.
TODO: Doplnit odkazy na kapitoly
-For details about the library architecture, refer the Section \ref{sec:software_architecture} in Chapter \ref{chap:introduction}
+For details about the library architecture, refer the Section \ref{sec-software-architecture} in Chapter \ref{chap-introduction}
\section{API development guidelines}
+\label{sec-api-development-guidlines}
The following are the development guidelines used for developing the RPP API:
\end{compactitem}
\section{Coding style}
+\label{sec-coding-style}
In order to keep the code as clean as possible, a unified coding style should be followed by any contributor to the code. The rpp-lib 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 they were following the suggestions. This does not causes problems as long as the contributor follows the committing procedure described in next paragraph.
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-subdirectory-content-description}
\begin{description}
\item[librpp.a and rpp-lib.lib] Version controlled RPP static libraries.
\end{description}
\section{Compilation}
+\label{sec-compilation}
The RPP Library can be compiled as a static library for ARM using TI CGT and for x86(\_64) using GCC. The library can be compiled for ARM under Linux and Windows using a Code Composer Studio project. The POSIX version is available for Linux and can be compiled in Linux system using an Eclipse project. After the compilation, as part of the build process, both procedures will automatically update the version-controlled static libraries in the library root.
\end{verbatim}
\chapter{Simulink Coder Target}
+\label{chap-simulink-coder-target}
The Simulink Coder Target allows to convert Simulink models to C code,
compile it and download to the board.
\hypertarget{description}{}
\section{Introduction}
+\label{sec-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
\end{center}\end{figure}
\section{Features}
-\label{sec:features}
+\label{sec-features}
\begin{itemize}
\item Support only single tasking. If multitasking is required, it has to be implemented in a new file \textsc{rpp\_mrmain.tlc} in \textsc{\repo/rpp/rpp/} and \textsc{rpp\_file\_process.tlc} has to be edited to use that file, when multitasking is selected.
\item No External mode support
-\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 OPTS="-O0 -g"}.
+\item Custom compiler options, available via OPTS variable in \emph{Make command} at \emph{Code Generation} tab (see Figure ). For example \textsc{make\_rtw OPTS="-O0 -g"}.
\end{itemize}
\section{RPP Options pane}
-\label{sec:rpp-target-options}
+\label{sec-rpp-target-options}
The RPP Target includes the following configuration options, all of them configurable per model
under \textsc{Code Generation} \noindent$\rightarrow$ \textsc{RPP Options}:
code. See below. Default value is 4096.
\item \textbf{C system heap size}:
- \label{sec:rpp-target-options-heap-size} this parameter is passed
+ \label{sec-rpp-target-options-heap-size} this parameter is passed
directly to the linker for the allocation of the heap. Currently,
the heap is not used, but will be used by the external mode in the future. 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
\end{itemize}
\section{Subdirectory content description}
+\label{sec-subdirectory-content-description}
This section describes the directories of the Simulink Coder. If you are interested in particular file, refer the description at the beginning of the file.
\begin{description}
\item[doc/] Contains the sources of the documentation, you are now reading.
\end{description}
\section{Block Library Overview}
+\label{sec-block-library-overview}
The Simulink Block Library is a set of blocks that allows Simulink models to use board IO and
communication peripherals. The available blocks are summarized in
Table~\ref{tab:block-lib-status} and more detailed description is
-given in Section~\ref{sec:blocks-description}.
+given in Section~\ref{sec-blocks-description}.
\begin{table}
\begin{center}\begin{tabular}{lp{5cm}lll}
\end{table}
\subsection{Blocks implementation}
+\label{sec-blocks-implementation}
All of the blocks are implemented as a C Mex S-Function coded by hand. In this section the
approach taken is briefly explained.
\subsubsection{C MEX S-Functions}
+\label{sec-c-mex-functions}
\begin{compactitem}
\item C : Implemented in C language. Other options are Fortran and Matlab language itself.
\item MEX: Matlab Executable. They are compiled by Matlab - C compiler wrapper called MEX.
\end{lstlisting}
\subsubsection{Target Language Compiler files}
+\label{sec-target-language-compiler-files}
In order to generate code for each one of those functions each S-Function implements a TLC file
for \textit{inlining} the S-Function on the generated code. The TLC files are files that describe how to
\end{compactitem}
\subsection{Blocks description}
-\label{sec:blocks-description}
+\label{sec-blocks-description}
-This section describes each one of the Simulink blocks present in the Simulink RPP Library, illustrated in Figure \ref{fig:block-library}:
+This section describes each one of the Simulink blocks present in the Simulink RPP Library, illustrated in Figure \ref{fig-block-library}:
\begin{figure}[H]
\advance
\noindent
\includegraphics[width=530px]{images/block_library.png}
\caption{Simulink RPP Block Library.}
-\label{fig:block-library}
+\label{fig-block-library}
\end{figure}
% Include automatically generated documentation
projects / jenkicar / rpp-simulink.git / commitdiff