doc: OS replacement updates

diff --git a/doc/rpp_simulink.tex b/doc/rpp_simulink.tex
index 6baf693bcdda0c66f2f58f7905f287af158f5290..75f15a1d1b6d60468a3f1f42257f72a15693f7ca 100644 (file)
--- a/doc/rpp_simulink.tex
+++ b/doc/rpp_simulink.tex
@@ -1610,12 +1610,13 @@ main_page.dox
 
 \section{Changing operating system}
 \label{sec-changing-os}
-The C Support Library contains by default the FreeRTOS operating system in
-version 7.0.2. However newer versions up to 8.1.2 are supported and should
-be working, no functional tests have been done for them. This section
-describes all changes necessary for replacing the operating system.
+The C Support Library contains by default the FreeRTOS operating
+system in version 7.0.2. This section describes what is necessary to
+change in the library and other packages in order to replace the
+operating system.
+
+\subsection{Operating system code and API}
 
-\subsection{API}
 The source and header files of the current operating system (OS) are
 stored in directory \texttt{\repo/rpp/lib/os}. The files of the new
 operating system should also be placed in this directory.
@@ -1624,53 +1625,58 @@ To make the methods and resources of the new OS available to the C Support
 Library, modify the \texttt{\repo/rpp/lib/rpp/include/base.h} file to include
 the operating system header files.
 
-Our implementation for FreeRTOS includes one header file
-\texttt{\repo/rpp/lib/os/i/7.0.2\_rm48/include/os.h}, which contains all
-necessary inclusions and macro definitions for the FreeRTOS. We suggest to
-define similar header file for your operating system as well.
-
-The API for SCI in file \texttt{\repo/rpp/lib/rpp/src/sci.c} contains a 
-FreeRTOS constant \texttt{portMAX\_DELAY}, defining infinite waiting time
-for Queues and Semaphores, that has to be replaced.
-
-\subsection{Drivers}
-Drivers for SCI and ADC contain dependencies on the FreeRTOS. Those files should be modified:
+Current implementation for FreeRTOS includes a header file
+\texttt{\repo/rpp/lib/os/i/\-7.0.2\_rm48/\-include/os.h}, which
+contains all necessary declarations and definitions for the FreeRTOS.
+We suggest to provide a similar header file for your operating system as
+well.
+
+In order to compile another operating system into the library, it is
+necessary to modify \texttt{\repo/rpp/lib/Makefile.var} file, which
+contains a list of files that are compiled into the library. All lines
+starting with \texttt{os/} should be updated. 
+
+\subsection{Device drivers}
+Drivers for SCI and ADC depend on the FreeRTOS features. These
+features need to be replaced by equivalent features of the new
+operating system. Those files should be modified:
 \begin{description}
-\item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data structure,
-       containing definitions of Queue and Semaphore.
-\item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Contains FreeRTOS Queue and
-       Semaphore data types and functions.
-\item[\repo/rpp/lib/rpp/include/drv/sci.h] Contains a \texttt{portTickType}, defining
-       a data type for timing in miliseconds
-\item[\repo/rpp/lib/rpp/src/drv/sci.c] Contains references to Semaphore,
-       Queue data types and functions, data type for return values
-       (\texttt{portBASE\_TYPE}) and critical sections, determined by
-       \texttt{taskENTER\_CRITICAL} and \texttt{taskEXIT\_CRITICAL} macros,
-       where preemtion is disabled.
-\item[\repo/rpp/lib/rpp/src/drv/adc.c] Contains FreeRTOS Semaphore data types,
-       functions and contains data type for return values (\texttt{portBASE\_TYPE})
-       and FreeRTOS constant \texttt{portMAX\_DELAY}, defining infinite waiting time.
+\item[\repo/rpp/lib/rpp/include/sys/ti\_drv\_sci.h] Defines a data
+  structure, referring to FreeRTOS queue and semaphore.
+\item[\repo/rpp/lib/rpp/src/sys/ti\_drv\_sci.c] Uses FreeRTOS queues
+  and semaphores.
+\item[\repo/rpp/lib/rpp/include/drv/sci.h] Declaration of
+  \texttt{drv\_sci\_receive()} contains \texttt{portTick\-Type}. We
+  suggest replacing this with OS independent type, e.g. number of
+  milliseconds to wait, with $-1$ meaning infinite waiting time.
+\item[\repo/rpp/lib/rpp/src/drv/sci.c] uses the following FreeRTOS
+  specific features: semaphores, queues, data types
+  (\texttt{portBASE\_TYPE}) and
+  critical sections (\texttt{taskENTER\_CRITICAL} and
+  \texttt{task\-EXIT\_CRITICAL}). Inside FreeRTOS critical sections,
+  task preemption is disabled. The same should be ensured by the other
+  operating system or the driver should be rewritten to use other
+  synchronization primitives.
+\item[\repo/rpp/lib/rpp/src/drv/adc.c] uses FreeRTOS semaphores.
 \end{description}
 
 \subsection{System start}
 The initialization of the MCU and the system is in the
-\texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} source file. If your
-system relies on interrupts generated by Real-Time Interrupt module, the
-pointer to the Interrupt Service Routine (ISR) \texttt{vPreemptiveTick}
-has to be replaced.
+\texttt{\repo/rpp/lib/rpp/src/sys/sys\_startup.c} file. If the new
+operating system needs to handle interrupts generated by the Real-Time
+Interrupt module, the pointer to the Interrupt Service Routine (ISR)
+\texttt{vPreemptiveTick} has to be replaced.
 
 \subsection{Simulink template for main function}
-The template for generation of the \texttt{ert\_main.c} file, containing
+
+When the operating system in the library is replaced, the users of the
+library must be changes as well. In case of Simulink code generation
+target, described in Chapter~\ref{chap-simulink-coder-target}, the
+template for generation of the \texttt{ert\_main.c} file, containing
 the main function, has to be modified to use proper functions for task
-creation, task timing and semaphores. The template is defined in
+creation, task timing and semaphores. The template is stored in
 \texttt{\repo/rpp/rpp/rpp\_srmain.tlc} file.
 
-\subsection{Makefile}
-To be able to build the C Support Library with the new operating system,
-the \texttt{\repo/rpp/lib/Makefile.var} file, containing paths to the
-source and header files, has to be modified to contain paths to the files
-of the new OS.
-
 \chapter{Simulink Coder Target}
 \label{chap-simulink-coder-target}