\section{Project Installation}
\label{sec-project-installation}
-The RPP project is distributed in three packages and a standalone pdf file,
+The RPP software is distributed in three packages and a standalone pdf file,
containing this documentation. Every package is named like
\texttt{package\_name-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-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 applications in the other two packages. The compile
+ procedure can be found in Section \ref{sec-compilation}.
+\item[rpp-simulink] Contains source code of Matlab Simulink blocks,
+ demo models and scripts for downloading the generated 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 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 interactive testing and
+ control of the RPP board over the serial interface.
+
+ The package also contains the binary of the RPP Library and all
+ headers and other files necessary for building and downloading the
+ application.
\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.
+
+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 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 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 \texttt{rpp/lib} folder.
- \item In the rpp-test-sw application the library binary file is
-present in \texttt{rpp-lib} folder.
- \end{itemize}
+ \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 the procedure from Section
+ \ref{sec-compilation}. The compiled library \texttt{rpp-lib.lib}
+ will appear in the project root directory.
+ \item Copy the compiled library to the application, where you want
+ to test and use the new library version.
+ \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
+ \texttt{rpp-lib} folder.
+ \end{itemize}
\end{enumerate}
\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 install the rpp-simulink project, which is
+needed to try the demo models or to build your own models that use RPP
+blocks.
\begin{enumerate}
- \item Unzip the \texttt{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 instruction 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 real 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 \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 \texttt{rpp-lib} and
-the \texttt{rpp-test-sw} projects.
+ \item Follow the procedure for opening the projects in CCS in
+ Section \ref{sec-openning-of-existing-project} and open both
+ \texttt{rpp-lib} and \texttt{rpp-test-sw} projects.
\item Right click on the \texttt{rpp-test-sw} project in the
-\textsc{Project Explorer} and select \textsc{Build Project}. Ignore any errors
-in the \texttt{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
-\texttt{rpp-lib} project. Do not mind them and click to the \textsc{Proceed} button
-to continue.
+ \textsc{Project Explorer} and select \textsc{Build Project}.
+ Ignore any errors in the \texttt{rpp-lib} project. % TODO why there are errors?
+ \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 whether
+ to proceed with the detected errors in \texttt{rpp-lib} project.
+ Ignore them and click the \textsc{Proceed} button to continue.
\end{enumerate}
\section{Code Composer Studio usage}
\subsection{Opening of 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}
\subsection{Creating new project}
\label{sec-creating-new-project}
-In \texttt{\repo/rpp/lib/apps/} there are two RPP based
-applications, \texttt{helloworld} and \texttt{helloworld\_posix}, that are
-already configured for the RPP Library. It is advised that new applications use
-this project as a foundation.
+In \texttt{\repo/rpp/lib/apps/}, there are two simple RPP applications
+\texttt{helloworld} and \texttt{helloworld\_posix}, that are already
+configured for the RPP Library. It is advised that new applications
+use this project as a template.
-To create a new application copy this directory and rename it. Now open files
-\texttt{.project}, \texttt{.cproject} and \texttt{.ccsproject} (if available)
-and change any occurrence of the work \texttt{helloworld}
-with the name of your project. Use lower case ASCII letters and underscores only.
+To create a new application copy \texttt{helloworld} directory to a
+new location and rename it. Now open files \texttt{.project},
+\texttt{.cproject} and \texttt{.ccsproject} (if available) and change
+any occurrence of the word \texttt{helloworld} to the name of your new
+project. Use lower case ASCII letters and underscores only.
-\textbf{Steps to configure a new CCS (ARM, using CGT) RPP application:}
+\subsubsection{Steps to configure new RPP application in CCS:}
+Follow these steps to create an application for RM48 MCU compiled with
+CGT.
+\newpage
\begin{compactenum}
- \item Create a new CCS project. \newline{}
-\noindent\includegraphics[width=400px]{images/base_1.png}
- \item Create a normal folder \texttt{include}.
- \item Create a source folder \texttt{src}.
- \item Add common \texttt{.gitignore} to the root of that project:
-\lstset{language=}
+\item Create a new CCS project.\\
+ \noindent\includegraphics[width=400px]{images/base_1.png}
+\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 Add new variable \texttt{RPP\_LIB\_ROOT} and point to this
-repository branch root.\newline{}
-\noindent\includegraphics[width=400px]{images/base_2.png}
- \item Add \texttt{rpp-lib.lib} static library to linker libraries and
-add \texttt{RPP\_LIB\_ROOT} to the library search path.\newline{}
+ \newpage
+\item In project \textsc{Properties}, add new variable
+ \texttt{RPP\_LIB\_ROOT} and point to this repository branch
+ root.\\
+ \noindent\includegraphics[width=400px]{images/base_2.png}
+\item Add \texttt{rpp-lib.lib} static library to list of linked
+ libraries and add \texttt{RPP\_LIB\_ROOT} to the library search
+ path.\newline{}
\noindent\includegraphics[width=400px]{images/base_3.png}
\newpage
- \item Configure linker to retain \texttt{.intvecs} from RPP static
-library.\newline{} \noindent\includegraphics[width=350px]{images/base_4.png}
+\item Configure linker to retain the \texttt{.intvecs} section
+ from the RPP library.\\
+ \noindent\includegraphics[width=350px]{images/base_4.png}
\item Configure compiler to include local includes, OS includes for
RM48 and RPP includes, in that order.\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{}
+\item Import and link (\emph{do not copy!}) linker file and board
+ upload descriptor.\\ % TODO Ktere soubory to jsou a jak se
+ % na windows linkuje?
\noindent\includegraphics[width=200px]{images/base_7.png}
\end{compactenum}
-\textbf{Steps to configure a new GCC (x86(\_64)) RPP simulated application:}
+\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.
\noindent\includegraphics[width=400px]{images/base_posix_3.png}
\end{compactenum}
-\textbf{In general any RPP application uses the layout/template:}
+\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. % TODO ref
+ \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 */
\begin{itemize}
\item \texttt{vApplicationMallocFailedHook()} allows to catch memory allocation
errors.
- \item \texttt{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}
-\label{sec-running-software-on-hw}
+\subsection{Downloading and running the software}
+\label{sec-running-software-on-hw} %TODO: continue review from here
\subsubsection{Code Composer Studio Project}
\label{sec-ccs-run-project}
When the application is distributed as a CCS project, you have to open the
\end{document}
% LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests
-% LocalWords: MCU UART microcontrollers DAC
+% LocalWords: MCU UART microcontrollers DAC CCS simulink
projects / jenkicar / rpp-simulink.git / commitdiff