From 17a15a00acf4ada88b639f85ae796b37bf28c845 Mon Sep 17 00:00:00 2001 From: Michal Sojka Date: Thu, 29 Jan 2015 00:48:32 +0100 Subject: [PATCH] doc: More fixes --- doc/rpp_simulink.tex | 248 ++++++++++++++++++++++++------------------- 1 file changed, 136 insertions(+), 112 deletions(-) diff --git a/doc/rpp_simulink.tex b/doc/rpp_simulink.tex index 51ded27..f260553 100644 --- a/doc/rpp_simulink.tex +++ b/doc/rpp_simulink.tex @@ -619,90 +619,97 @@ For Windows, the C/C++ compiler is a part of Windows SDK, which is available fro \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} @@ -710,19 +717,21 @@ to continue. \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} @@ -739,52 +748,63 @@ section so that the result looks like in Figure \ref{fig-select-project}. \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. @@ -812,29 +832,32 @@ includes, OS includes for POSIX and RPP includes, in that order.\newline{} \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 /* 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 /* 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) { @@ -853,11 +876,12 @@ 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} @@ -868,7 +892,7 @@ void main(void) 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 */ @@ -903,8 +927,8 @@ void main(void) \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} @@ -942,8 +966,8 @@ void vApplicationStackOverflowHook(xTaskHandle xTask, \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 @@ -2199,4 +2223,4 @@ same description is also available in the program itself via the \end{document} % LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests -% LocalWords: MCU UART microcontrollers DAC +% LocalWords: MCU UART microcontrollers DAC CCS simulink -- 2.39.2