From 63413a6e856ea40b49b2d5edf9c4ba2591841233 Mon Sep 17 00:00:00 2001 From: Michal Sojka Date: Wed, 28 Jan 2015 16:27:07 +0100 Subject: [PATCH] Updated doc up to Section 2.2 --- doc/rpp_simulink.bib | 11 +- doc/rpp_simulink.tex | 696 ++++++++++++++++++++++--------------------- 2 files changed, 361 insertions(+), 346 deletions(-) diff --git a/doc/rpp_simulink.bib b/doc/rpp_simulink.bib index 90d9c87..309b88b 100644 --- a/doc/rpp_simulink.bib +++ b/doc/rpp_simulink.bib @@ -61,16 +61,17 @@ howpublished = {\url{http://en.wikipedia.org/wiki/Model-based_design}} year = "2013" } @TECHREPORT {rm48xtechnicalreferencemanual2013, - author = "Texas Instruments", + author = "{Texas Instruments}", title = "{RM48x} 16/32-Bit {RISC} Flash Microcontroller -- {T}echnical Reference Manual", - institution = "Texas Instruments", + institution = "{Texas Instruments}", year = "2013" } @TECHREPORT {rm48hdkusersguide2013, - author = "Texas Instruments", + author = "{Texas Instruments}", title = "{RM48} Hercules Development Kit ({HDK}) -- {U}ser's Guide", - institution = "Texas Instruments", - year = "2013" + institution = "{Texas Instruments}", + year = "2013", + url = "http://www.ti.com/lit/ug/spnu508b/spnu508b.pdf", } @BOOK {usingthefreertos2009, author = "Richard Barry", diff --git a/doc/rpp_simulink.tex b/doc/rpp_simulink.tex index 1706e98..51ded27 100644 --- a/doc/rpp_simulink.tex +++ b/doc/rpp_simulink.tex @@ -152,82 +152,179 @@ Michal \textsc{Sojka}\\[\baselineskip] \chapter{Introduction} \label{chap-introduction} -This text serves as a documentation for the Rapid Prototyping Platform -(RPP) project based on Texas Instruments RM48 safety microcontroller. +This text documents software part of Rapid Prototyping Platform (RPP) +project for Texas Instruments RM48 safety microcontroller. 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 TMS570 microcontroller and the port to RM48 was derived from it under a contract with Eaton -Corporation. As this document is still in beta version, some +Corporation. +% TODO remove it +As this document is still in beta version, some references to the original TMS570-based RPP remain in it. - 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 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. +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{rm48xtechnicalreferencemanual2013} -for details. +The Rapid Prototyping Platform is an control unit based on TMDSRM48HDK +development kit from Texas Instruments. Cental to the kit is the +RM48L952 MCU -- 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{rm48xtechnicalreferencemanual2013} 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 replacinf 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} + +This section provides a brief description of the Texas Instrument +TMDSRM48HDK development kit. For a more detailed information refer to +\cite{rm48hdkusersguide2013}. The kit is depicted in +Figure~\ref{fig-board_photo}. + +\begin{figure}\begin{center} + \noindent + \includegraphics[width=300px]{images/board.png} + \caption{The TMDSRM48HDK kit \cite[p. 8]{rm48hdkusersguide2013}} + \label{fig-board_photo} +\end{center}\end{figure} + +Only a subset of peripherals available on the kit is currently +supported by the RPP software. A block diagram in +Figure~\ref{fig-blocks} ilustrates the supported peripherals and their +connection to the MCU, expansion connectors and other components on +the development kit. For pinout description of the implemented +peripherals refer the RM48HDK User's Guide +\cite{rm48hdkusersguide2013}. The main features of supported +peripherals are provided in the following subsections. + +\begin{figure}\begin{center} + \noindent + \includegraphics[width=400px]{images/blocks.png} + \caption{Block diagram of supported peripherals} + \label{fig-blocks} +\end{center}\end{figure} + +\subsection{Digital Inputs and Outputs (DIN and DOUT)} +\label{par-digital-inputs-outputs} + \begin{compactitem} + \item 46 pins available on Expansion connector J11. + \item 8 pins available on GIOA + \item 8 pins available on GIOB + \item 30 pins available on NHET1. Pins NHET1 6 and NHET1 13 are disabled. + \item All the pins are configurable as inputs and outputs with different modes: + \begin{compactitem} + \item Push/Pull or Open Drain for Output configuration. + \item Pull up, Pull down or tri-stated for Input configuration. + \end{compactitem} + \item Some of the pins are connected to LEDs or to a button. See + Figure~\ref{fig-blocks} or refer to~\cite{rm48hdkusersguide2013}. + \end{compactitem} + +\subsection{Analog Input (ADC)} +\label{par-analog-input} +\vbox{% Keep this on the same page + \begin{compactitem} + \item 16 channels available on the Expansion connector J9. + \item Range for 0 -- 5 Volts. + \item 12 bits resolution. + \end{compactitem} +} +\subsection{CAN bus (CAN)} +\label{par-can} +\begin{compactitem} + \item Up to three CAN ports + \begin{compactitem} + \item 2 ports equipped with physical layer CAN transciever + connected to J2 and J3 connectors. + \item All 3 ports available as link-level interface on the + Expansion connector J11. + \end{compactitem} + \item High speed. + \item Recovery from errors. + \item Detection of network errors. +\end{compactitem} + +\subsection{Serial Communication Interface (SCI)} +\label{par-sci} +\begin{compactitem} + \item 1 port available on connector J7. + \item Configurable baud rate. Tested with 9600 and 115200 bps. + \item RS232 compatible. +\end{compactitem} + \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 @@ -235,12 +332,13 @@ 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} +\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 top layers depends on the layer interface + and not on individual elements from that layer. +\end{compactitem} -\begin{figure}[H] +\begin{figure} \begin{center} \noindent \includegraphics[width=250px]{images/layers.pdf} @@ -250,186 +348,110 @@ individual elements from that layer. \end{compactitem} \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 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 + \item[7.0.2] Preferred 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 RM48 MCU. +% TODO: Do these new version work or not? \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}. +Large part of this layer was generated by the HalCoGen tool (see +Section~\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. +Hardware Abstraction Layer (HAL) provides an abstraction over the real +hardware. For example imagine an IO port with 8 pins. First four pins +are connected directly to the GPIO pins on the MCU, another four pins +are connected to an external integrated circuit, communicating with +the MCU via SPI. +% TODO: Is this the case on TMDSRM48HDK? +This layer allows to control the IO pins independently of how that are +connected to the MCU, providing a single unified API. + +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. +\texttt{$\langle$rpp\_lib$\rangle$/rpp/src/hal} and the header files can +be found in \texttt{$\langle$rpp\_lib$\rangle$/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, 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 +layers 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 +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} - -The Rapid Prototyping Platform is based on a TMDSRM48HDK development kit developed and distributed by Texas Instruments. The kit is depicted in Figure \ref{fig-board_photo}. - -\begin{figure}[H]\begin{center} - \noindent - \includegraphics[width=300px]{images/board.png} - \caption{The RPP board \cite[p. 8]{rm48hdkusersguide2013}} - \label{fig-board_photo} -\end{center}\end{figure} - -Only a subset of the peripherals available on the kit is implemented in the control software. A block scheme in Figure \ref{fig-blocks} ilustrates the implemented peripherals and their connection with the MCU, expansion connectors and other components on the development kit. - -\begin{figure}[H]\begin{center} - \noindent - \includegraphics[width=400px]{images/blocks.png} - \caption{The peripherals block scheme.} - \label{fig-blocks} -\end{center}\end{figure} - -For pinout description of the implemented peripherals refer the RM48HDK User's Guide \cite{rm48hdkusersguide2013}. - -\subsection{Logic IO} -\label{sec-logic-io} - -\subsubsection{Digital Inputs and Outputs (DIN and DOUT)} -\label{par-digital-inputs-outputs} - \begin{compactitem} - \item 46 pins available on Expansion connector J11. - \item 8 pins available on GIOA - \item 8 pins available on GIOB - \item 30 pins available on NHET1. Pins NHET1 6 and NHET1 13 are disabled. - \item All the pins are configurable as inputs and outputs with different modes: - \begin{compactitem} - \item Push/Pull or Open Drain for Output configuration. - \item Pull up, Pull down or tri-stated for Input configuration. - \end{compactitem} - \item Some of the pins are connected to LEDs or to a button. See Figure \ref{fig-blocks} or refer \cite{rm48hdkusersguide2013} for the connection description. - \end{compactitem} - -\subsubsection{Analog Input (ADC)} -\label{par-analog-input} - \begin{compactitem} - \item 16 channels available on the Expansion connector J9. - \item Range for 0-5 volts. - \item 12 bits resolution. - \item Using CPU ADC. - \end{compactitem} - -\subsection{Communication} -\label{sec-communication} -\subsubsection{CAN bus (CAN)} -\label{par-can} -\begin{compactitem} - \item 2 ports available ready for connection to the CAN bus on connector J2 and J3. - \item 3 ports available as an interface for external CAN bus drivers on the Expansion connector J11. - \item High speed. - \item Recover from error. - \item Detection of network errors. -\end{compactitem} - -\subsubsection{Serial Comm. Interface (SCI)} -\label{par-sci} -\begin{compactitem} - \item 1 port available on connector J7. - \item Variable baud rate. Tested on 9600 and 115200. - \item RS232 standard compatible. -\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} @@ -468,29 +490,27 @@ example). \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} @@ -507,7 +527,8 @@ cd /ccsv5/eclipse/ \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} @@ -518,30 +539,24 @@ If the application crashes with a segmentation fault edit file: \lstset{language=bash} \begin{lstlisting} -nano -/ccsv5/eclipse/plugins/com.ti.ccstudio.branding_/plugin_customization.ini +nano /ccsv5/eclipse/plugins/com.ti.ccstudio.branding_/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} @@ -549,25 +564,30 @@ 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 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} +\begin{quotation} \url{http://www.ti.com/tool/halcogen?keyMatch=halcogen&tisearch=Search-EN} - \end{quotation} +\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 application. 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 (test with 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: @@ -578,11 +598,8 @@ sudo apt-get install gtkterm \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} @@ -597,18 +614,14 @@ command 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} \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: +\texttt{package\_name-version.zip}. The three packages are: \begin{description} \item[rpp-lib] Contains the source codes of the RPP Library, @@ -638,7 +651,7 @@ in development environment and how to use the resulting static library in an application. \begin{enumerate} - \item Unzip the \textsc{rpp-lib-version.zip} file. + \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 @@ -648,9 +661,9 @@ The binary file will appear in the project root directory. 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. +present in \texttt{rpp/lib} folder. \item In the rpp-test-sw application the library binary file is -present in \textsc{rpp-lib} folder. +present in \texttt{rpp-lib} folder. \end{itemize} \end{enumerate} @@ -660,7 +673,7 @@ If you want to access the demo models or build your own models using the RPP blo 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. \begin{enumerate} - \item Unzip the \textsc{rpp-simulink-version.zip} file. + \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. @@ -677,18 +690,18 @@ modifications in the RPP Library follow this procedure for the rpp-test-sw application installation. \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 +\ref{sec-openning-of-existing-project} and open both, the \texttt{rpp-lib} and +the \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 \textsc{rpp-lib} project. +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 -\textsc{rpp-lib} project. Do not mind them and click to the \textsc{Proceed} button +\texttt{rpp-lib} project. Do not mind them and click to the \textsc{Proceed} button to continue. \end{enumerate} @@ -726,14 +739,14 @@ section so that the result looks like in Figure \ref{fig-select-project}. \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 +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. 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} +\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. \textbf{Steps to configure a new CCS (ARM, using CGT) RPP application:} @@ -741,9 +754,9 @@ with the name of your project. Use lower case ASCII letters and underscores only \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: + \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=} \begin{lstlisting} Debug @@ -751,14 +764,14 @@ Release .settings/* \end{lstlisting} \newpage - \item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this + \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 \textsc{rpp-lib.lib} static library to linker libraries and -add \textsc{RPP\_LIB\_ROOT} to the library search path.\newline{} + \item Add \texttt{rpp-lib.lib} static library to linker 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 \textsc{.intvecs} from RPP static + \item Configure linker to retain \texttt{.intvecs} from RPP static library.\newline{} \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{} @@ -775,11 +788,11 @@ upload descriptor.\newline{} \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 + \item Create a source folder \texttt{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: + \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 @@ -787,15 +800,15 @@ Release .settings/* \end{lstlisting} \newpage - \item Add new variable \textsc{RPP\_LIB\_ROOT} and point to this + \item Add new variable \texttt{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{} + \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=400px]{images/base_posix_3.png} \end{compactenum} @@ -888,9 +901,9 @@ void main(void) \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 + \item \texttt{vApplicationStackOverflowHook()} allows to catch if a task overflows it's stack. \lstset{language=c++} @@ -1036,7 +1049,7 @@ Before any work or experiments with the RPP blocks and models can be done, the R 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 On Windows you have to tell the \texttt{mex} which C compiler it should be using. Open the command line, run the \texttt{mex} tool from the Matlab installation folder and select the C compiler. \begin{lstlisting}[language=bash] C:\Program Files\MATLAB\R2013b\bin>mex -setup @@ -1100,7 +1113,7 @@ rpp_setup \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} @@ -1114,14 +1127,14 @@ blocks for user's architecture (using Matlab's mex command line tool). \item Create new model or load a demo: -Demos are located on \textsc{\repo/rpp/demo} or you can start a new model and +Demos are located on \texttt{\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. \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 +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 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 @@ -1168,7 +1181,7 @@ source blocks to run once per tick. \end{compactitem} \item Code generation (Figure~\ref{fig-code-gen-settings}): \begin{compactitem} - \item Set to \textsc{rpp.tlc}. + \item Set to \texttt{rpp.tlc}. \begin{figure} \centering \includegraphics[width=400px]{images/simulink_code.png} @@ -1183,7 +1196,7 @@ you want your generated code to appear, e.g.: 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{\_rpp}, where \textsc{model} is the name +the subdirectory will be \texttt{\_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}. @@ -1264,7 +1277,7 @@ 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}. +\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 @@ -1289,19 +1302,19 @@ and intended for developers, not users. Documentation here is optional and at 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 +other words, never \texttt{\#include "foo/foo.h"} in any RPP Layer interface file. \end{compactitem} @@ -1361,26 +1374,26 @@ 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 +implementations files for given \texttt{\{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()} +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 -\textsc{\{mnemonic\}} module. +\texttt{\{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. +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, if you want to use only a subset of the library functions. \item[rpp/src/rpp/rpp\_\{mnemonic\}.c] Module implementation. -Implementation of \textsc{rpp\_\{mnemonic\}.h}'s functions on top of the DRV +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} @@ -1394,13 +1407,13 @@ update the generated binary static library file 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 +Composer studio project \texttt{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 +If the build process is successful, the \texttt{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 +prone, there is a \texttt{Makefile} that allows to compile the libraries from the Linux terminal: \begin{lstlisting}[language=bash] @@ -1419,8 +1432,8 @@ set CCS_UTILS_DIR=C:\ti\ccsv5\utils 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}. +can be set manually for one session by the \texttt{set} command like in the +previous example or permanently in \texttt{\repo/Debug/GNUMakefile}. Note that the Makefile still requires the Code Composer Studio (ARM compiler) to be installed because of the CGT. @@ -1436,14 +1449,14 @@ 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. + \item Add library \texttt{rpp-lib.lib} to the linker libraries. The RPP library \textbf{MUST} be looked for before Texas Instruments support -library \textsc{rtsv7R4\_T\_le\_v3D16\_eabi.lib}. - \item Configure linker to retain \textsc{.intvecs} section from +library \texttt{rtsv7R4\_T\_le\_v3D16\_eabi.lib}. + \item Configure linker to retain \texttt{.intvecs} section from RPP Library:\newline{} -\textsc{--retain="rpp-lib.lib$\langle$sys\_intvecs.obj$\rangle$(.intvecs)"} +\texttt{--retain="rpp-lib.lib$\langle$sys\_intvecs.obj$\rangle$(.intvecs)"} \item Use the provided linker command file -\textsc{RM48L952FlashLnk.cmd}. +\texttt{RM48L952FlashLnk.cmd}. \end{compactitem} \item \textbf{x86(\_64) compilation using GCC for Simulation:} \begin{compactitem} @@ -1451,14 +1464,14 @@ RPP Library:\newline{} 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 Add library \texttt{librpp.a} to the linker libraries. + \item Add \texttt{pthread} to the linker libraries. \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 +\texttt{rpp-lib.lib}. When compiling a Simulink model, neither Simulink nor the +\texttt{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 @@ -1479,7 +1492,7 @@ make 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/lib/rpp/doc/api/content} are used for the API reference generation are their name is self-explanatory: \begin{verbatim} @@ -1501,7 +1514,7 @@ compile it and download to the board. 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 @@ -1525,7 +1538,7 @@ board. \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} @@ -1550,7 +1563,7 @@ configurable per model under \textsc{Code Generation} \noindent$\rightarrow$ 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 @@ -1565,18 +1578,18 @@ passed to the \textsc{xTaskCreate()} that 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} /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. @@ -1584,8 +1597,8 @@ the loaded program a manual reset of the board is required. 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 +from Ti loading script \texttt{loadti.sh} to OpenOCD script +\texttt{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: @@ -1621,7 +1634,7 @@ 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 +the Matlab Simulink and \texttt{rpp\_lib.slx}, which is the Simulink RPP Library, containing all the Simulink blocks for RPP. \item[rpp/blocks/tlc\_c]Contains the templates for C code generation from the Matlab Simulink model. @@ -1695,10 +1708,10 @@ output for simulations. 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. @@ -1711,12 +1724,12 @@ The implementation of the S-Functions in the RPP project has following layout: \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} @@ -1724,7 +1737,7 @@ The implementation of the S-Functions in the RPP project has following layout: \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: @@ -1734,11 +1747,11 @@ The C-MEX S-Function implemented can be compiled with the following command: /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} @@ -1756,55 +1769,55 @@ generate code for a specific C-MEX S-Function block. They are programmed using T 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. \end{itemize} The general layout of the TLC files implemented for this project are: \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{} +\item \texttt{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 should never be called unless an error is detected and in most models it is empty. @@ -1933,7 +1946,7 @@ Demostrates how to use CAN Receive blocks in order to: \textbf{Description:} 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 +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. @@ -1968,7 +1981,7 @@ if data is received, that is, Serial Receive output is non-negative. Negative va \textbf{Description:} The model demonstrates how to use the DIN blocks and DOUT blocks, configured in every mode. The DOUTs -are pusched high and low with period 1 second. The DINs are reading inputs and printing the values +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} @@ -1980,7 +1993,7 @@ on the Serial Interface with the same period. \textbf{Description:} -This demo will print \textsc{"Hello Simulink"} to the Serial Communication Interface (115200-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. @@ -1988,14 +2001,14 @@ second. \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 on the serial interface. The command processor is modular and each peripheral has its commands in a separated 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 @@ -2010,7 +2023,7 @@ 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}. @@ -2185,4 +2198,5 @@ same description is also available in the program itself via the \end{document} -% LocalWords: FreeRTOS RPP POSIX +% LocalWords: FreeRTOS RPP POSIX microcontroller HalCoGen selftests +% LocalWords: MCU UART microcontrollers DAC -- 2.39.2