The version control system used for this project is **git**. The repository of this project contains all
the files produced during development, including documentation, references, code and graphics. Also the
-GUI application **gitk** was used to easily review changes. To install both execute on a terminal:
+GUI application **giggle** was used to easily review changes. To install both execute on a terminal:
{{{ bash
-sudo apt-get install git gitk
+sudo apt-get install git giggle
}}}
=== TI Code Composer Studio ===[ti_code_composer_studio]
%DONE
-Matlab/Simulink version used is R2012b for Linux 64 bits. The CVUT should provide a license and a network
-licensing server descriptor file.
+Matlab/Simulink version used is R2012b for Linux 64 bits. For in-house development the CVUT should provide a
+network licensing server descriptor file.
=== GtkTerm ===[gtkterm]
%tex% ''' \caption{The RPP connectors pinout.}\end{figure}
-=== Modules diagram ===[modules_diagram]
-
-%tex% ''' \begin{figure}[H]\advance\leftskip-1cm
-[530-blocks.pdf.png]
-%tex% ''' \caption{The RPP board modules.}\end{figure}
-
-
=== Modules description ===[modules_description]
= Simulink RPP Target =[simulink_rpp_target]
-
+% FALTA
== Description ==[description]
== Description ==[description]
-Talk about motivation, work done and compare against origin.
+The RPP Library is the support library used by Simulink models. It is designed from the board user
+perspective and exposes a simplified high-level API to handle the board's peripheral modules in a safe
+manner.
+
+The library as a concept and as a functional unit was introduced by this project. At the beginning of this
+project the RPP board had just one application developed for. This application intended for board testing
+allows the user to issue low-level commands to control and test the peripherals of the board. This application
+was created using a combination of custom code, contributed drivers and generated code from TI tool HalCoGen.
+Library functionality, like drivers and hardware access, and application logic, like command processor and test
+routines, was largely merged in a single layer, 166 source code files long highly coupled application.
+In order to develop independent applications for the RPP board, as it was expected to be each Simulink model,
+the library logic needed to be separated from the application logic. This work implied a heavy refactoring on
+the testing application in order extract from it the library functionality. Because the application files were
+highly coupled in a single layer the refactoring and testing of the library implied roughly 70% of the work done
+on this project.
+
+%tex% ''' \begin{figure}[H]\advance\leftskip-1cm
+[500-adc_dep_before.png]
+%tex% ''' \caption{Dependency graph of the ADC driver before refactoring.}\end{figure}
+
+The above graph shows the dependencies of the ADC driver before the refactoring. Please note the dependency on
+``cmdproc_io_tisci.h`` and ``cmdproc.h``, both application level modules. Also, note the indirect dependency on
+the Operating System is being resolved through the application modules.
+
+%tex% ''' \begin{figure}[H]\begin{center}
+[150-adc_dep_after.png]
+%tex% ''' \caption{Dependency graph of the ADC driver after refactoring.}\end{center}\end{figure}
+
+The above graph shows the current dependencies for the ADC driver in the RPP Library. Please note that it dependents
+only on the system layer low-level driver and that the Operating System indirect dependency is resolved through the
+library foundations ``base.h``.
+
+Some other relevant changes introduced with the refactoring are:
+
+- ADC driver was completely rewritten.
+- MOUT driver was written.
+- DIN driver was slightly modified and extended.
+- DAC driver was slightly modified.
+- HBR driver was largely modified (in particular watchdog functionality).
+- SCI driver was refactored and extended.
+
+
+Also, once the library functionality could be isolated, the resulting API was too low-level to be used by
+applications, in consequence one of the contributions of this projects was the implementation of a high-level API on top
+of this low level API: the RPP Layer.
+
+
+NEWPAGE
=== Architecture ===[architecture]
+The RPP library was structured into 5 layers with the following guidelines:
+
+- Top-down dependency only. No lower layer depends on anything from upper layers.
+- 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).
+- Each layer should provide a unified layer interface (``rpp.h``, ``drv.h``, ``hal.h``, ``sys.h`` and
+ ``os.h``), so top layers depends on that layer interface and not on individual elements from that layer.
+
+
+%tex% ''' \begin{figure}[H]\begin{center}
+[250-layers.pdf.png]
+%tex% ''' \caption{The RPP library layers.}\end{center}\end{figure}
+
+
+As a consequence of this division the source code files and interface files are now placed on private directories
+so the previous prefix based inclusion ``drv_din.h`` is replaced by ``drv/din.h``. With this organization user
+applications only needs to include the top layer interface file (``rpp/rpp.h``) to be able to use the library API.
+Please note the sublayer uLut, which is used only by the SPI driver in order to use thread safe queue mechanisms.
+Because the FreeRTOS already provides thread safe queues and in order to match the order parts of the system it
+would be advisable to drop this dependency in the future.
+
+NEWPAGE
=== Modules ===[modules]
+The RPP Layer was structured into 14 different modules from 4 different categories that match the hardware
+modules on the board:
+
+|| CATEGORY | NAME | MNEMONIC
+ | Logic IO | Digital Input | ``[DIN ]`` |
+ | | Digital (Logic) Output | ``[LOUT]`` |
+ | | Analog Input | ``[AIN ]`` |
+ | | Analog Output | ``[AOUT]`` |
+ | Power output | H-Bridge output | ``[HBR ]`` |
+ | | Power output (12V, 2A) | ``[MOUT]`` |
+ | | High-Power output (12V, 10A) | ``[HOUT]`` |
+ | Communication | CAN Bus | ``[CAN ]`` |
+ | | LIN (Local Interconnect Network) | ``[LIN ]`` |
+ | | FlexRay | ``[FR ]`` |
+ | | Serial Communication Interface | ``[SCI ]`` |
+ | | Ethernet | ``[ETH ]`` |
+ | Logging | SD Card | ``[SDC ]`` |
+ | | SD-RAM | ``[SDR ]`` |
+Please note the mnemonic of each module, as they are constantly used on the Software and documentation.
+
+%tex% ''' \begin{figure}[H]\advance\leftskip-1cm
+[500-blocks.pdf.png]
+%tex% ''' \caption{The RPP Library modules.}\end{figure}
+
=== OS interchangeable layer ===[os_interchangeable_layer]
== Static libraries ==[static_libraries]
+The RPP Library can be compiled as a static library for ARM using TI CGT and for x86(_64) using GCC. CCS
+projects ``rpp-lib`` and ``rpp-lib_posix`` in ``<repo>/rpp/lib/apps/`` allows to generate the static
+libraries. After compilation, as part of the build process, both projects will automatically update the
+version-controlled static libraries in ``<repo>/rpp/lib/``:
+
+- ``rpp-lib.lib``, static library for ARM using TI naming scheme.
+- ``librpp.a``, static library for x86(_64) using standard Linux naming scheme.
+
+
+One future improvement would be the creation of a Makefile for each compilation scheme in order to not depend
+on CCS managed build system. For ARM manual compilation or makefile creation using Texas CGT see the
+``target_tools.mk`` file under the Simulink RPP Target folder.
+
+The relevant aspects for compiling and linking an application using the static libraries are:
+
+**ARM compilation using CCS for the RPP board:**
+
+- Include headers files of the OS for which the library was compiled against. At the time of this writing the OS
+ is FreeRTOS 7.0.2. See [OS interchangeable layer #os_interchangeable_layer] section above.
+- Include header files for the RPP library.
+- Add library ``rpp-lib.lib`` to the linker libraries. The RPP library **MUST** be looked for before Texas
+ Instruments support library ``rtsv7R4_T_be_v3D16_eabi.lib``.
+- Configure linker to retain ``.intvecs`` section from RPP Library:@@
+ ``--retain="rpp-lib.lib<sys_intvecs.obj>(.intvecs)"``
+- Use the provided linker command file ``TMS570LS313xFlashLnk.cmd``.
+
+
+**x86(_64) compilation using GCC for Simulation:**
+
+- Include headers files of the OS for Simulation. At the time of this writting the OS is POSIX FreeRTOS 6.0.4.
+- Include header files for the RPP library.
+- Create a ``RppConfig.h`` override file and drop DRV layer dependency: ``rppCONFIG_DRV 0``. See
+ [Architecture #architecture] section above.
+- Includes must be configured in a way that the ``RppConfig.h`` taken under consideration is the override and not
+ the library one.
+- Add library ``librpp.a`` to the linker libraries.
+- Add ``pthread`` to the linker libraries.
+
+
+As an important note, all the models compiled using Simulink will link against ``rpp-lib.lib``. When compiling a
+Simulink model, Simulink, and then ``make``, will not update the generated binary if the model hasn't changed, and
+then if the source code hasn't changed. Static libraries changes are not considered for re-compilation and
+re-linking. If library development is being done and static library is updated, in order for the Simulink model
+to generate a newly linked version of the binary the whole code generation folder needs to be deleted in order to
+force code generation, compilation and linking with the new static library.
+
== Base application ==[base_application]
projects / jenkicar / rpp-simulink.git / commitdiff
