Added Appendix B to the documentation

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
index 2afeb9b..1a4753a 100644
--- a/doc/source/introduction.rst
+++ b/doc/source/introduction.rst
@@ -12,6 +12,8 @@ ECos
 ECos is a configurable real-time operating system intended for use in embedded applications.
 The documentation for eCos 3.0, which is the most recent version of the system as well as the one ported to Colibri VF61, can be found at http://ecos.sourceware.org/docs-3.0/.
 
+A comprehensive PDF `eCos Reference Guide`_ is also available from the eCos website.
+
 Licence
 -------
 
@@ -36,6 +38,9 @@ This eCos port provides the following software packages specific for Toradex Col
 * Flex Timer Module
 * GPIO handling
 
+Also, the port has been verified to work with the standard eCos POSIX an µITRON compatibility layers.
+See :ref:`compat` for more information on this.
+
 Version information
 -------------------
 
@@ -47,6 +52,7 @@ Version information
    Michael Gielda,Prerequisites & compiling sample programs,2014-03-27,0.3.0
    Michael Gielda,Running programs,2014-03-28,0.3.1
    Michael Gielda,Further updates,2014-04-02,0.3.2
+   Michael Gielda,Further updates & Appendix B,2014-04-07,0.4.0
 
 Compiling the system
 ====================
@@ -404,4 +410,51 @@ The associated parameters are:
 * CYG_HAL_STARTUP_PLF (ByVariant / DRAM)
 * CYG_HAL_STARTUP_VAR  (OCRAM / TCML) 
 
+.. _compat:
+
+Appendix B: POSIX and µITRON compatibility
+==========================================
+
+By default, eCos allows the user to enable POSIX or µITRON compatibility, which may be beneficial for many applications.
+This Appendix explains briefly how to use them with this eCos port.
+
+For more information refer to the `eCos Reference Guide`_, Chapters XIII and XIV.
+
+POSIX
+-----
+
+:abbr:`POSIX (Portable Operating System Interface)`, is a well-known family of OS standards.
+:abbr:`POSIX` defines the primitives, nomenclature and API which makes it easier to provide software compliance between operating systems.
+
+This is especially useful with regard to programming heterogeneous devices like the Colibri VF61,
+where (especially with the :abbr:`POSIX` compatibility layer enabled),
+the programming style for eCos applications dedicated for the Cortex-M4 core can vastly resemble that of Linux programs running on the Cortex-A5 core,
+lowering the entry barrier for programmers.
+
+.. todo::
+
+   Describe how to enable POSIX compatibility, and point to a sample program.
+
+µITRON
+------
+
+µITRON is a the name of an Japanese open standard for RTOS, originally undertaken in 1984 under the guidance of Ken Sakamura.
+eCos supports the µITRON version 3.02 specification, with complete "Standard functionality" (level S), plus many "Extended" (level E) functions.
+
+More about ITRON and µITRON can be read in the following sources: 
+
+* `introduction to ITRON project <http://www.ertl.jp/ITRON/panph98/panph98-e.html>`_
+* `µITRON3.0 specification <http://www.ertl.jp/ITRON/spec-e.html#ITRON3>`_
+* Dr. Sakamura’s book: uITRON 3.0, An Open and Portable Real Time Operating System for Embedded Systems
+
+Since eCos was designed with the µITRON guidelines in mind, it is not strictly necessary to "activate" this compatibility layer, as an eCos application may fulfill the standard anyway.
+However, eCos provides a package named ``CYKPKG_UITRON`` setting some additional constraints, and adding it to the kernel is recommended for applications meant to be µITRON compliant.
+To activate this package, use either :program:`ecosconfig` (``ecosconfig add CYGPKG_UITRON``) or :program:`configtool`:
+
+#. Choose :menuselection:`Build --> Packages`
+#. Select :guilabel:`uITRON compatibility` and click :guilabel:`Add >>`, then :guilabel:`OK`
+#. A new package, ``uITRON compatibility layer`` should appear in the package list - save your :abbr:`.ecc` file and exit. 
+
+A sample application, verified to work as expected using the port can be found inside the port code, in the subdirectory :file:`compat/uitron/current/tests/test3.c`
 
+.. _eCos Reference Guide: http://ecos.sourceware.org/docs-3.0/pdf/ecos-3.0-ref-a4.pdf