From 2a7d2ac0c6e76292281686c85fb796315e9657e2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Carlos=20Miguel=20Jenkins=20P=C3=A9rez?= Date: Wed, 19 Jun 2013 08:02:28 +0200 Subject: [PATCH] Improved documentation. --- doc/reports/report/header.tex | 3 + doc/reports/report/report.t2t | 582 ++++++++++++++++++++++++++++++++-- 2 files changed, 562 insertions(+), 23 deletions(-) diff --git a/doc/reports/report/header.tex b/doc/reports/report/header.tex index 5772652..f071a8c 100644 --- a/doc/reports/report/header.tex +++ b/doc/reports/report/header.tex @@ -53,3 +53,6 @@ % \renewcommand{\familydefault}{\sfdefault} % Better PDF font \usepackage{lmodern} + +% Multiple columns +\usepackage{multicol} diff --git a/doc/reports/report/report.t2t b/doc/reports/report/report.t2t index 9d72a78..7b93b8f 100644 --- a/doc/reports/report/report.t2t +++ b/doc/reports/report/report.t2t @@ -567,9 +567,9 @@ the Operating System is being resolved through the application modules. [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``. +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: @@ -582,8 +582,8 @@ Some other relevant changes introduced with the refactoring are: 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. +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 @@ -614,12 +614,12 @@ would be advisable to drop this dependency in the future. NEWPAGE -=== Modules ===[modules] +=== RPP Layer Modules ===[rpp_layer_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 +|| Category | Description | MNEMONIC | Logic IO | Digital Input | ``[DIN ]`` | | | Digital (Logic) Output | ``[LOUT]`` | | | Analog Input | ``[AIN ]`` | @@ -636,38 +636,416 @@ modules on the board: | | SD-RAM | ``[SDR ]`` | -Please note the mnemonic of each module, as they are constantly used on the Software and documentation. +Please note the mnemonic of each module, as they are constantly used on the Software and documentation. +Also note that only the following modules where implemented as part of this project: + +%tex% ''' \begin{multicols}{2} +- DIN. +- LOUT. +- AIN. +- AOUT. +- HBR. +- MOUT. +- SCI. +- SDR. + + +%tex% ''' \end{multicols} + +Modules for which there is a low-level API available on the library but no high-level module was implemented: + +%tex% ''' \begin{multicols}{2} +- CAN. +- LIN. +- FR. + + +%tex% ''' \end{multicols} + +Modules that are not yet available on the library at all: + +%tex% ''' \begin{multicols}{2} +- ETH (in the works). +- SDC. +- HOUT (partial). + + +%tex% ''' \end{multicols} + +The following graphic shows the library modules and the connectors on the hardware they map to. %tex% ''' \begin{figure}[H]\advance\leftskip-1cm [500-blocks.pdf.png] %tex% ''' \caption{The RPP Library modules.}\end{figure} +NEWPAGE + === OS interchangeable layer ===[os_interchangeable_layer] +The OS Layer is composed by the FreeRTOS source code files. Because the FreeRTOS exposes an stable +API the OS layer can be changed in order to upgrade the Operating System or use a different port of the +OS, without changing the upper layers source code. The OS Layers currently available for the RPP Library +at ``/rpp/lib/os/`` at the time of this writing are: + +- Version 6.0.4 using POSIX port. This layer is the one that should be used when compiling a program for + x86(_64) simulation. The port uses the ``pthread`` library and because of this the port is not true + real time and this is considered a simulator. +- Version 7.0.2 using HalCoGen port for TMS570. This layer is the one currently supported and tested. It was + originally included in the testing application and was generated by an older version of TI code generation + tool HalCoGen. +- Version 7.4.0 using HalCoGen port for TMS570. This layer was extracted from a newly generated project using + a newer version of HalCoGen. This layer is untested but //should// work out of the box. +- Version 7.4.2 using ARM Cortex R4 official port for CCS. This layer was created from vanilla FreeRTOS 7.4.2 + release. It is tested but non-working. Ticks are proved to be executed in time but applications using this + kernel runs at full-speed. The reason if this is currently unknown. + + +The general layout of all the layers are as following: + +- Common source code (kernel): + +``` + src/os/croutine.c (Optional) + src/os/list.c + src/os/queue.c + src/os/tasks.c + src/os/timers.c (Optional) +``` + +Originally found in vanilla distribution in: ``/FreeRTOS/Source`` + +- Common interface files: + +``` + include/os/croutine.h + include/os/FreeRTOS.h + include/os/list.h + include/os/mpu_wrappers.h + include/os/portable.h (with minor editions) + include/os/projdefs.h + include/os/queue.h + include/os/semphr.h + include/os/StackMacros.h + include/os/task.h + include/os/timers.h +``` + +Originally found in vanilla distribution in: ``/FreeRTOS/Source/include`` + +- Memory management file: + +``` + src/os/heap.c (One of 4 version available, see Appendix A). +``` + +Originally found in vanilla distribution in: ``/FreeRTOS/Source/portable/MemMang`` + +- Port specific files: + +``` + src/os/port.c + src/os/portASM.asm + include/os/portmacro.h + include/os/FreeRTOSConfig.h +``` + +This depend of the port. In the case of the 7.4.2 TMS570 / ARM Cortex R4 for CCS port: + + - First three files can be found in vanilla distribution in ``/FreeRTOS/Source/portable/CCS/ARM_Cortex-R4``. + - Last file in ``/FreeRTOS/Demo/CORTEX_R4_RM48_TMS570_CCS5``. + + +In general, the following changes were applied to the source code base of all kernels: + +- Replaced include directives to adapt to RPP library standard: + +``#include "`` with ``#include "os/`` + +- Line ending character set to UNIX '\n' and tabs replaced by 4 spaces. -=== Development guidelines ===[development_guidelines] +NEWPAGE + +=== API development guidelines ===[api_development_guidelines] + +The following are the development guidelines use for developing the RPP API: + +- User documentation should be placed in header files, not in source code, and should be Doxygen formatted + using autobrief. Documentation for each function present is mandatory. +- Function declarations on the headers files is for public functions only. Do not declare local/static/private + functions on the header. +- Documentation on source code files should be non-doxygen formatted and intended for developers, not users. + Documentation here is optional. +- Always use standard data types for IO when possible. Use custom structs as very last resort. +- Use prefix based functions names to avoid clash. The prefix is of the form ``[layer]_[module]_``, for example + ``rpp_din_update()`` for the update function of the DIN module in the RPP Layer. +- To 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 externed (variable) from application. As a rule of + thumb declare all global variables as static. + -- Documentation in headers. -- Non-doxygen documentation in source code is intended for developpers, not users. -- Standard datatypes for IO when possible. Use custom structs as last resort. -- Prefix based functions names. -- To be careful about symbol export. === Further improvements ===[further_improvements] -- Change name of GPIO MOUT1_EN to MOUT1_DIAG -- Change name of GPIO MOUT1_IN to MOUT1_EN -This are misleading. +The following are recommendations for future improvements of the library: + +- General code revision to remove local-only methods and variables from being exported. +- General code revision and refactoring to normalize the functions naming scheme. Normalize DRV and HAL + to use prefix based scheme, not all the functions and exported variables do. Refactor the SYS layer, + most of it generated by HalCoGen and that uses ``thisNamingScheme`` to use library standards (see + [RPP API #rpp_api] programming standards). +- Simplify doxygen documentation on the SYS layer, because is clunky, doesn't add any value and is + repetitive. Move it the header files. +- The HAL layer currently two elements: + - CPU and chips abstractions. This should stay. + - Command descriptor. This is remaining elements from the testing applications and should be moved to + application layer. + + +Recommendations for changes on the electrical diagrams: + +- Change name of GPIO MOUT1_EN to MOUT1_DIAG. +- Change name of GPIO MOUT1_IN to MOUT1_EN. + +This are misleading. == Repository branch description ==[repository_branch_description] +-> ``apps/`` + +Applications related to the RPP library. This include . + + + +Library file layout: + + -> include/rpp/rpp.h + + Main library header file. + + To use this library just include this file and this file only. Also, + before using any library function please call rpp_init() function for + hardware initialization. + + + -> include/rpp/RppConfig.h + + Library configuration file. + Please refer to the API documentation and header file comments for + specific documentation for each configuration parameter. + + + -> include/rpp/rpp_{mnemonic}.h + + Header file for {mnemonic} module. + + This files includes function definitions, pin definitions, etc, specific + to {mnemonic} module. The inclusion of this header can be configured + in RppConfig.h using rppCONFIG_INCLUDE_{MNEMONIC} directive. + + + -> src/rpp/rpp_{mnemonic}.c + + Module implementation. + + Implementation of rpp_{mnemonic}.h's functions on top of the DRV + library. + + + -> src/rpp/rpp.c + + Implementation of library-wide functions. + + + -> doc/doxygen.conf + + Configuration file for Doxygen code documentation generation tool. + + + +NEWPAGE == Test Suite ==[test_suite] +The ``rpp-test-suite`` is a RPP application developed as part of this project that includes a series of +test tasks or test commands to verify the correct behavior and functionality of the RPP layer modules. +There is one command per module, and the command use the same mnemonic that the module. + +This test suite can be found in ``/rpp/lib/apps/rpp-test-suite`` for the ARM version and in +``/rpp/lib/apps/rpp-test-suite_posix`` for the simulated version. + +The application enables a command processor using the SCI at **115200-8-N-1**: + +``` +RPP Library Test Suite. +=========================================================== +[Type a module to test or 'help'] +--> help +Available commands: + help - Display this help. + ain - Test Analog Input. + aout - Test Analog Output. + can - Test CAN communication. + din - Test Digital Inputs. + eth - Test Ethernet communication. + fr - Test Frame Relay communication. + hbr - Test H-Bridge. + hout - Test High Power Output. + lin - Test LIN communication. + lout - Test Digital Outputs. + mout - Test Power Outputs. + sci - Test Serial Communication Interface. + sdc - Test SD-Card. + sdr - Test SD-RAM. +``` + +Current modules with tests implemented are: + +%tex% ''' \begin{multicols}{2} +- AIN. +- AOUT. +- DIN. +- HBR. +- LOUT. +- MOUT. +- SCI. (the test-suite itself) +- SDR. + + +%tex% ''' \end{multicols} + +NEWPAGE + +=== AIN test description ===[ain_test_description] + +This test will read all the analog inputs at a rate of 100 times per second and print the result. + +``` +--> ain +Analog Inputs Test [1-12]: +=========================================================== + 1 2 3 4 5 6 7 8 9 10 11 12 + 0 0 0 0 0 0 0 0 0 0 0 0 +``` + +Status: **PASSED**. + +=== AOUT test description ===[aout_test_description] + +This test will generate a 10Hz sinus wave on all the analog outputs with a sampling rate of 1kHz. +The sinus wave of each analog output channel is sifted by (1/4)pi. + +``` +--> aout +Analog Output Test at 10 Hz: +=========================================================== +Samples: 7331 +``` + +Status: **PASSED**. + +=== DIN test description ===[din_test_description] + +This test will read all 16 + 8 the digital inputs at a rate of 100 times per second, using both low speed +SPI chip and variable threshold high-speed inputs. + +``` +--> din +Digital Inputs Test [1-16]: +=========================================================== + 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 A B C D E F G H + 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +``` + +Status: + - Low speed fixed threshold [1-16]: **PASSED**. + - High speed variable threshold [A-H]: **FAILED**. + +=== HBR test description ===[hbr_test_description] + +This test will generate a sinus wave to control the H-Bridge of one period per 20 seconds (0.05Hz) at a +sampling rate of 20Hz. + +``` +--> hbr +H-Bridge Test at 0.05 Hz: +=========================================================== +Samples: 72 +``` + +Status: **PASSED**. + +=== LOUT test description ===[lout_test_description] + +This test will show in the digital outputs the value in binary of a counter, incrementing the counter +once per second. The counter is 8 bits, the same as the outputs, so 255 seconds are required for an +overflow/restart of the counting. + +``` +--> lout +Digital Output Test: +=========================================================== +Counter: 40 +``` + +Status: **PASSED**. + +=== MOUT test description ===[mout_test_description] + +This test will toggle the power outputs one by one per second, then wait 10 seconds in that state while +constantly verifying the diagnostics. + +``` +--> mout +Power Output Test: +=========================================================== +1 2 3 4 5 6 +1: OK 1: OK 1: OK 1: OK 1: OK 1: OK +``` +Status: **PASSED**. + +=== SCI test description ===[sci_test_description] + +A more comprehensive test is not implemented. The very use of this test-suite implies the correct function +of the SCI module. Nevertheless, as a future improvement, a test that will verify run-time baud rate changes +and test some other RPP SCI functions is desirable. + +``` +--> sci +You're using the SCI, reading this and typing this command. +Press any key to continue... +``` + +Status: **PASSED**. + +=== SDR test description ===[sdr_test_description] + +This test will launch a noise generator task that will log noise and then start the library included SD-RAM +logging command processor, allowing the user to see and handle the log on the SD-RAM. + +``` +--> sdr +Log control: 1024kB available. +=========================================================== +--> log +[ 1239864] This is the noise generator at iteration 1 putting some noise value 279735017. +[ 1240779] This is the noise generator at iteration 2 putting some noise value 1943579783. + +--> available +1023 kB of 1024 kB available. + +--> clear +Done. + +--> exit +``` + +Status: **PASSED**. + +NEWPAGE == Static libraries ==[static_libraries] @@ -682,9 +1060,8 @@ version-controlled static libraries in ``/rpp/lib/``: 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: +``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:** @@ -700,10 +1077,9 @@ The relevant aspects for compiling and linking an application using the static l **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 headers files of the OS for Simulation. At the time of this writing 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. +- Create a ``RppConfig.h`` override file and drop DRV layer dependency: ``rppCONFIG_DRV 0``. - 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. @@ -718,15 +1094,175 @@ to generate a newly linked version of the binary the whole code generation folde force code generation, compilation and linking with the new static library. +NEWPAGE == Base application ==[base_application] +In ``/rpp/lib/apps/`` there is two RPP base applications, ``base`` and ``base_posix``, that +already configured for the RPP Library. It is advised that new applications uses this projects a foundations. + +To create a new application copy this directory and rename it. Now open files ``.project``, ``.cproject`` and +``.ccsproject`` (if available) and change any occurrence of the work ``base`` with the name of your project. +Use only lower case ASCII letters and underscores. + +**Steps to configure a new CCS (ARM, using CGT) RPP application:** + ++ Create a new CCS project.@@ +[400-base_1.png] ++ Create a normal folder ``include``. ++ Create a source folder ``src``. ++ Add common ``.gitignore`` to the root of that project: +{{{ plain +Debug +Release +.settings/* +}}} +NEWPAGE ++ Add new variable ``RPP_LIB_ROOT`` and point to this repository branch root.@@ +[400-base_2.png] ++ Add ``rpp-lib.lib`` static library to linker libraries and add ``RPP_LIB_ROOT`` to the library search path.@@ +[400-base_3.png] +NEWPAGE ++ Configure linker to retain ``.intvecs`` from RPP static library.@@ +[350-base_4.png] ++ Configure compiler to include local includes, OS includes for TMS570 and RPP includes, in that order.@@ +[350-base_5.png] +NEWPAGE ++ Configure compiler to allow GCC extensions.@@ +[400-base_6.png] ++ Import and link (__do not copy!__) linker file and board upload descriptor.@@ +[200-base_7.png] + + +**Steps to configure a new GCC (x86(_64)) RPP simulated application:** + ++ Create a new managed C project that uses Linux GCC toolchain. ++ Create a source folder ``src``. Link all files from original CCS application to this folder. ++ Create a normal folder ``include``. Create a folder ``rpp`` inside of it. ++ Add common ``.gitignore`` to the root of that project: +{{{ plain +Debug +Release +.settings/* +}}} +NEWPAGE ++ Add new variable ``RPP_LIB_ROOT`` and point to this repository branch root.@@ +[400-base_posix_1.png] ++ Configure compiler to include local includes, CCS application includes, OS includes for POSIX and + RPP includes, in that order.@@ +[400-base_posix_2.png] +NEWPAGE ++ Add ``rpp`` and ``pthread``to linker libraries and add ``RPP_LIB_ROOT`` to the library search path.@@ +[400-base_posix_3.png] ++ Copy ``RppConfig.h`` from RPP Library to a new folder ``include/rpp`` and configure it drop DRV layer + dependency: ``rppCONFIG_DRV 0``.@@ +[200-base_posix_4.png] + + +**In general any RPP application uses the layout/template:** + ++ Include RPP library header file. +{{{ cpp +#include "rpp/rpp.h" +}}} + +NEWPAGE ++ Create one or as many FreeRTOS task function definitions as required. Those + tasks should use functions from this library. +{{{ cpp +void my_task(void* p) +{ + static const portTickType freq_ticks = 1000 / portTICK_RATE_MS; + portTickType last_wake_time = xTaskGetTickCount(); + while(TRUE) { + /* Wait until next step */ + vTaskDelayUntil(&last_wake_time, freq_ticks); + rpp_sci_printf((const char*)"Hello RPP.\r\n"); + } +} +}}} + ++ Create the main function that will: + - Initialize the RPP board. + - Spawn the tasks the application requires. Refer to FreeRTOS API for + details. + - Start the FreeRTOS Scheduler. Refer to FreeRTOS API for details. + - Catch if idle task could not be created. ++ +{{{ cpp +void main(void) +{ + /* Initialize RPP board */ + rpp_init(); + + /* Spawn tasks */ + if(xTaskCreate(my_task, (const signed char*)"my_task", + 512, NULL, 0, NULL) != pdPASS) { + #ifdef DEBUG + rpp_sci_printf((const char*) + "ERROR: Cannot spawn control task.\r\n" + ); + #endif + while(TRUE) { asm(" nop"); } + } + + /* Start the FreeRTOS Scheduler */ + vTaskStartScheduler(); + + /* Catch scheduler start error */ + #ifdef DEBUG + rpp_sci_printf((const char*) + "ERROR: Problem allocating memory for idle task.\r\n" + ); + #endif + while(TRUE) { asm(" nop"); } +} +}}} + ++ Create hook functions for FreeRTOS: + - ``vApplicationMallocFailedHook()`` allows to catch memory allocation errors. + - ``vApplicationStackOverflowHook()`` allows to catch if a task overflows it's + stack. ++ +{{{ cpp +#if configUSE_MALLOC_FAILED_HOOK == 1 +/** + * FreeRTOS malloc() failed hook. + */ +void vApplicationMallocFailedHook(void) { + #ifdef DEBUG + rpp_sci_printf((const char*) + "ERROR: manual memory allocation failed.\r\n" + ); + #endif +} +#endif + + +#if configCHECK_FOR_STACK_OVERFLOW > 0 +/** + * FreeRTOS stack overflow hook. + */ +void vApplicationStackOverflowHook(xTaskHandle xTask, + signed portCHAR *pcTaskName) { + #ifdef DEBUG + rpp_sci_printf((const char*) + "ERROR: Stack overflow : \"%s\".\r\n", pcTaskName + ); + #endif +} +#endif +}}} + +NEWPAGE == API generation ==[api_generation] +doxygen doxygen.conf + == API Reference ==[api_reference] -- 2.39.2