doc: add software requirements and architectural design

Documentation/OS/README

+
+requirements first, then architecture
+
+compile with:
+
+xelatex --interaction=nonstopmode <file>
+
+makeglossaries <file>
+
+biber <file>
+
+then recompile
+
+
+TODO: Makefile
+

Documentation/OS/demo/demo.tex

+\input{../shared/template/univie.tex}
+\input{../shared/template/titlepage.tex}
+\input{../shared/template/traceability.tex}
+
+
+\begin{document}
+
+\uvietitlepage%
+{Polarregionen im Klimawandel --\\Bedeutung für Europa und die Welt}%
+{Präsentation des neuen\\Österreichischen Polarforschungsinstituts}%
+{../shared/images/pyramid.eps}
+
+
+
+\requirement{SRT-0142} {Dynamic Allocation is kewl}{%
+Functions requiring memory allocation (such as message sends, partition creation) shall %
+use shares of static buffers instead of dynamic memory allocation during multi-tasking.%
+As such, at the time of starting the multi tasking, the memory requirements of %
+shall be frozen and within the limits given by the size of the static buffers.
+}{}%
+
+\requirement{SRT-0143} {Dynamic Allocation is kewl}{%
+Functions requiring memory allocation (such as message sends, partition creation) shall %
+use shares of static buffers instead of dynamic memory allocation during multi-tasking.%
+As such, at the time of starting the multi tasking, the memory requirements of %
+shall be frozen and within the limits given by the size of the static buffers.
+}{%
+This should catch dumbass stack pointer corruptions.
+}%
+
+\requirement{SRT-0145} {I R Baboon}{%
+	I M Weasel
+}{%
+LOLcats are awesome.
+}%
+
+
+\begin{description}
+  \item\design{SRT-0001} First design. \meetsreq{SRT-0143}
+  \item\design{SRT-0002} Second design. \meetsreq{SRT-0142}
+  \begin{description}
+    \item\design{SRT-0002.1} Third design. \meetsreq{SRT-0145}
+    \item\design{SRT-0002.2} Fourth design\meetsreq{SRT-0142, SRT-0145}
+  \end{description}
+\end{description}
+
+
+\traceabilitymatrix
+
+
+\end{document}

Documentation/OS/requirements/software_requirements.tex

+
+
+\title{Software Requirements Specification}
+\def \documentid {LEANOS-UVIE-SRS-001}
+\date{Issue 0.2, May 2, 2016}
+
+\newcommand\affil[1]{\textsuperscript#1}
+
+\def\preparedby {Armin Luntzer\affil{1}}
+\def\checkedby {Roland Ottensamer\affil{1}}
+\def\approvedby {Franz Kerschbaum\affil{1}}
+
+\def\affiliations{
+	\affil{1} Department of Astrophysics, University of Vienna
+}
+
+
+
+
+\input{../shared/template/univie.tex}
+\input{../shared/template/titlepage.tex}
+\input{../shared/template/traceability.tex}
+\input{../shared/glossary.tex}
+
+\usepackage{vhistory}
+
+\usepackage{biblatex}
+\addbibresource{../shared/bibliography.bib}
+
+\rereadauxrequirementlabels
+
+\exportrequirements
+
+
+\begin{document}
+
+
+\setmainfont{MyriadPro-SemiCondensed}
+\uvietitlepage%
+{Lean OS --\\ An operating system for the SSDP}%
+{\doctitle}%
+{../shared/images/logo2.pdf}
+\setmainfont{MyriadPro}
+
+\approvalpage
+
+\tableofcontents
+\newpage
+
+
+\chapter*{List of Requirements}
+\the\requirementlist
+
+
+\begin{versionhistory}
+  \vhEntry{0.0}{16.07.2015}{AL}{draft requirements created based on \gls{NGAPP}}
+  \vhEntry{0.1}{16.03.2016}{AL}{initial version with specifications from \gls{MPPB}v2}
+  \vhEntry{0.2}{02.05.2016}{AL}{revised after internal design review}
+\end{versionhistory}
+
+
+\chapter{Introduction}
+
+\section{Purpose of the Document}
+
+This document specifies the software requirements for the operating system
+kernel LeanOS. LeanOS targets the \gls{SSDP}, and to a lesser extent, its
+compatible predecessor, the \gls{MPPB} v2.x \cite{MPPB}.
+It is intended to be used in unmanned space applications of at least
+Software Criticality Level C. Readers must be familiar with the basic concepts
+of event driven real time operating systems and the target hardware. \\
+
+\noindent
+This document follows the document structure for software requirement
+specifications found in Annex D of ECSS-E-ST-40C \cite{ECSS40C}.
+
+\section{Scope of the Software}
+
+LeanOS is a lightweight operating system targeting the particular
+characteristics of the \gls{SSDP} and is focused on driving the \gls{NoC} and
+its attached \gls{Xentium} \gls{DSP} cores.
+
+\chapter{Applicable and Reference Documents} % does not break automatically for some reason
+
+\printbibliography[heading=none]
+
+
+\chapter{Terms, Definitions and Abbreviated Items}
+\printglossary[type=acronym]
+\printglossary[type=main, style=altlist]
+
+
+
+\chapter{Software Overview}
+
+\section{Function and Purpose}
+
+In the course of the \gls{NGAPP} activities, an evaluation of the \gls{MPPB}
+was performed in a joint effort of \gls{RSA} and the Department of Astrophysics
+of the \gls{UVIE}. While the original intent of the work of \gls{UVIE} was to
+quantify the performance of the \gls{Xentium} \glspl{DSP} and the \gls{MPPB} as a
+whole with regard to on-board data treatment and reduction in an astronomical
+mission setting, it was found that, given the highly innovative nature of this new
+processing platform, a novel approach was needed concerning the management of
+system resources, \gls{DMA} mechanics and \gls{DSP} program design for best
+efficiency and turnover rates. Consequently, \gls{UVIE} developed an experimental
+operating system to stably drive the \gls{DSP} cores and the \gls{MPPB} close
+to its performance limit. LeanOS is a development based on this operating system
+concept. Along with its intended functionality, it provides full software test
+coverage, example applications and good documentation that supports all aspects
+of the software.
+
+
+\section{Environmental considerations}
+
+LeanOS is only required to support the \gls{SSDP}, but will also support the
+\gls{MPPB} v2.x. Ultimately, this does allow reuse of the operating system core
+for \gls{LEON2} and \gls{LEON3} based platforms with minor adaptations.
+Even though the \gls{SSDP} does not contain multi-core \gls{LEON3} processor,
+\gls{SMP} support will be prepared in LeanOS, as this will likely change with
+newer versions of the \gls{SSDP}.
+LeanOS is released under an open source license, so compatible development tools should
+be available under such licenses as well. Note that it might still be necessary
+to use a commercial product to target particular configurations or proprietary
+hardware functionality.
+
+
+\section{Relation to other systems}
+
+LeanOS is a stand-alone software product.
+
+
+\section{Constraints}
+
+LeanOS primarily targets the \gls{SSDP}, which effectively limits the hardware
+support the the characteristics of this platform. \\
+\noindent
+The source code is written in C and if required, \gls{SPARC} v8 compatible
+assembly. This is necessary as hardware interaction of a machine level requires
+programming languages designed for that purpose.
+
+
+
+\chapter{Requirements}
+
+\section{General}
+
+%\begin{figure}[ht]
+%\begin{center}
+%	\includegraphics{images/OS_fundamental_architecture}
+%	\caption{The fundamental architecture of LeanOS.}
+%	%\label{fig:blackbody_curves}
+%\end{center}
+%\end{figure}
+
+\requirement{GEN-0001} {No external dependecies}{%
+LeanOS shall not make use of external libraries, including C-Runtime libraries.
+}{}%
+
+\requirement{GEN-0002} {Custom libc functionality}{%
+LeanOS shall, as part of its code-base and as needed, provide its own
+implementations of typical C-libary functions with an \gls{API} conforming to
+their \gls{POSIX} definitions.
+}{%
+The collection of these functions can also form the base or a subset of a
+C-Libary to be used by applications.}%
+
+\requirement{GEN-0003} {Application libc usage}{%
+LeanOS shall optionally call a function that initialises a C-Library on startup.
+It is up to the user to define and link the implementation of this function and
+the according C library.
+}{%
+The function \_\_libc\_start\_main() is declared as a weak symbol and tested
+before execution.
+}%
+
+
+% TODO: to interface requirements?
+% example:
+%
+% declare:
+% __libc\_start\_main() __attribute__((weak));
+%
+% optional execution:
+%
+% if (__libc_start_main())
+%	__libc_start_main();
+% }
+% it is executed if the function is actually defined or linked in:
+%
+%  int __libc_start_main()
+% {
+%	...
+% }
+
+\requirement{GEN-0004} {Fatal Error Management}{%
+If a non-recoverable error state is detected in LeanOS, it shall optionally
+call an error handling routine provided by the user before issuing a reboot.
+LeanOS shall provide a directive to register such a function.
+}{%
+This gives the user the possiblity to perform a clean shutdown of critical
+tasks in their particular environment.}%
+
+
+\requirement{GEN-0006} {Core runtime}{%
+In its basic configuration, LeanOS shall restrict itself to the initialisation
+of its core services on a single processor, thereby configuring traps, memories
+and timers. All other services or device drivers shall be configured and added
+via the build system.
+}{}%
+
+\requirement{GEN-0601} {Error Logging}{%
+LeanOS shall maintain an error message log that is readable by the user.
+}{}%
+
+\requirement{GEN-0602} {Coding Style}{%
+LeanOS code shall use the Linux kernel coding style. Source files and patches
+shall be checked using the checkpatch.pl utility found in the Linux kernel
+source tree.
+}{%
+A major point of LeanOS is that it does not only come with an open source
+license, but should ideally only use tools that are distributable under a
+similar license. The Linux kernel is used in billions of devices word-wide,
+its coding style is hence arguably well-suited for use in successful software.
+}%
+
+
+\section{Functional Requirements}
+
+\requirement{FUN-0007} {SMP support}{%
+LeanOS shall be able to run on a multi-core configuration of a LEON3 processor.
+}{}%
+
+\requirement{FUN-0803} {MMU support}{%
+LeanOS shall support the use of the MMU of the LEON3 processor.
+}{}%
+
+\requirement{FUN-0008} {Supervisor Mode}{%
+The LeanOS kernel shall execute with the SPARC supervisor mode enabled.
+Application code shall run with supervisor mode disabled.
+}{}%
+
+\requirement{FUN-0011} {Timing}{%
+LeanOS shall provide access to typical time keeping, time taking and delay
+timing functionality expected by an operating system.
+}{}%
+
+
+\requirement{FUN-0012} {Task Support}{%
+LeanOS shall provide means to create new tasks.
+}{}%
+
+\requirement{FUN-0013} {Task priorites and deadlines}{%
+LeanOS shall support the assignment of a priority and a deadline to a task.
+}{}%
+
+\requirement{FUN-0014} {Task scheduling}{%
+LeanOS shall offer a fixed priority scheduler with priority inversion handling.
+}{}%
+
+\goal{FUN-0015} {Other schedulers}{%
+LeanOS should offer an Earliest Deadline First scheduler supporting priority
+execution in overload conditions.
+}{%
+Along with dynamic ticking, this is an option to optimise thread CPU utilisation
+with the added benefit of predictable execution for certain high-priority
+threads in conditions where the total load unexpectedly would exceed 100\%.
+}%
+
+\requirement{FUN-0016} {Kernel Ticks}{%
+LeanOS shall operate in tickless (non-periodic) timed wakeup mode by default.
+}{%
+Tickless timing avoids unnecessary wake-ups of the CPU if no task is running
+and improves performance by only switching to kernel mode from regular tasks
+when absolutely necessary.
+}%
+
+\requirement{FUN-0017} {Tickless Timing}{%
+LeanOS timing functionality shall be able to operate in tickless mode, where 
+a queue of wakeup times is maintained and a hardware timer is used in such a way
+that its next underflow (resulting in an interrupt) is programmed to coincide
+with the next wakeup time. New wakeup times shall be inserted into the queue as
+needed to maintain the desired timeline of events and the hardware timer
+be readjusted accordingly.
+}{}%
+
+\requirement{FUN-0019} {Semaphores and Mutexes}{%
+LeanOS shall provide semaphores and mutexes as part of its task functionality.
+Task priorities shall be protected by the priority ceiling protocol.
+}{}%
+
+\requirement{FUN-0020} {Tasks and \gls{SMP}}{%
+LeanOS shall support task migration between \glspl{CPU} and track and ensure
+atomicity of related functions (e.g. mutexes) across multiple processors.
+}{}%
+
+\requirement{FUN-0021} {Message Queues}{%
+LeanOS shall support message queues for inter-process communication.
+Atomicity of queues shall be ensured across multiple processors.
+}{}%
+
+\requirement{FUN-0022} {Kernel Modules}{%
+LeanOS shall offer loadable module support infrastructure.
+}{}%
+
+\requirement{FUN-0804} {Kernel-Userspace Initialisation}{%
+LeanOS shall offer a configurable initialisation point that executes a
+user-space setup procedure.
+}{This is the point where the application software is loaded.}%
+
+\requirement{FUN-0023} {System Control Interface}{%
+LeanOS shall offer a way for drivers or other functional modules to export
+configuration or state variables into an logical tree maintained by
+the operating system. This logical tree shall be accessible by other modules and
+the user as a character-based interface.
+}{%
+This is supposed to be a centrally organised, generic parseable interface to
+get or set configuration states or system statistics.
+}%
+
+\requirement{FUN-0024} {Binary System Control Interface}{%
+LeanOS shall offer the possibility to install binary exchange nodes within the
+System Control Interface tree that may be used for larger amouts of binary data.
+The binary format shall be defined by the creator of the node. Any users of the
+node shall be responsible to read or write in the correct format expected by the
+node.%
+}{%
+Sometimes, a binary dump to or from a subsystem is needed that is only parseable
+with special knowledge. This could, for example, be an internal memory dump or
+some calibration data.
+}%
+
+\goal{FUN-0025} {Device Drivers}{%
+LeanOS should come with device drivers for all hardware functionality of the SSDP.
+}{}%
+
+\requirement{FUN-0026} {Xentium Scheduler}{%
+LeanOS shall offer a way to define and load Xentium data processing code.
+}{}%
+
+\requirement{FUN-0027} {Xentium Data Buffers}{%
+LeanOS shall provide packet-driven meta-data buffers to Xentium programs that
+can link to arbitrary data sets and routing tables that define the path of
+a data packet through a series of Xentium program nodes.
+}{%
+Datagrams propagate through processing nodes as defined in their routing table,
+which represents their individual ``processing chain''.}%
+
+
+\section{Performance Requirements}
+
+\requirement{GEN-0009} {Traps/Interrupts}{%
+LeanOS trap entry and exit code shall not exceed 500 instructions.
+}{%
+This does not include the callback functions for a trap or interrupt
+service routine.
+}%
+
+\requirement{GEN-0018} {Deferred saving of \gls{FPU} registers}{%
+In trap mode, LeanOS shall defer saving of \gls{FPU} registers until it is
+accessed.
+}{%
+This approach saves many clock cycles, as the \gls{FPU} is not typically used
+as part of an \gls{ISR}.
+}%
+
+
+\requirement{GEN-0010} {Interrupt downtime}{%
+\glspl{ISR} that execute longer than 50 µs shall be set to be executed in
+deferred mode at a later time if feasible given the type and rate of an \gls{ISR}.
+}{
+Interrupt mode should be left as fast as possible, so regular processing can
+continue. Most \glspl{ISR} requiring long processing times perform actions on
+data, which can typically be moved into a dedicated thread, with the \gls{ISR}
+acting as a signalling function.
+}%
+
+\requirement{GEN-0028} {Real-Time Thread Support}{%
+LeanOS shall offer support for a class of real time threads that may also
+preempt the operating sytem with the exception of \glspl{ISR}.
+}{%
+Some application real time tasks may be so timing sensitive, that even
+operating system code must be preemptible to guarantee a timely response.
+}%
+
+\section{Interface Requirements}
+
+\requirement{GEN-2001} {Interface Documentation}{%
+The internal and external interfaces of LeanOS shall be described as part
+of its source code in Doxygen markup.
+}{
+The interfaces of a complex piece of software such as an operating system
+often change over time, as it is adapted to new circumstances or improved
+implementation of particular functionality or just subtle changes that may not
+always propagate into other documents as they should. It is therefore better to
+maintain interface documentation together with the code it describes, where it
+will be more likely to be updated on the spot.
+}%
+
+
+\section{Operational Requirements}
+
+No operational requirements have been identified.
+
+
+\section{Resources Requirements}
+
+\requirement{GEN-0101} {Target Platform}{%
+LeanOS shall execute on the \gls{SSDP}, in particular the \gls{LEON3-FT}
+processor of the platform. It should also execute on the \gls{MPPB} v2.x.
+}{}%
+
+
+\section{Design Requirements and Implementation Constraints}
+
+
+\requirement{GEN-0801}{Modular Design}{%
+All components of LeanOS shall be written such that a particular component does
+contain its intended functionality as much as possible.
+}{
+If something is mostly self-contained, it is easier to modify and re-use in
+another software project.
+}%
+
+\requirement{GEN-0802}{Software Hierarchy}{%
+All components shall make use and rely only on functionality that is lower
+in hierarchy. The use of functionality that is hierarchially equal or higher
+shall be explicitly forbidden.
+}{
+Note that hierarchy refers to the abstraction level of a component. An \gls{ISR}
+is of higher level than the interrupt dispatcher. Even though it is called by
+the latter, the actual registration of the \gls{ISR} is done by a higher level
+component. Such constructs are legal, the reliance on user-space provided
+functionality, e.g. an error reporting function, which sends messages via some
+packet interface on the other hand, is not.
+}%
+
+
+\requirement{GEN-0805}{Programming Language}{%
+The programming language shall be C. \gls{SPARC}v8 compatible assembly shall be
+used when necessitated by performance or timing constraints and interface
+requirements.
+}{}%
+
+
+
+
+\section{Security and Privacy Requirements}
+
+No security or privacy requirements have been identified.
+
+\section{Software Quality Requirements}
+
+\goal{GEN-0201} {Product Metrics}{%
+LeanOS should have a cyclomatic complexity of at most 15 and a nesting level of
+at most 6 per function. Each function shall have a single exit point for the 
+nominal case.
+}{}%
+
+\section{Software Reliability Requirements}
+
+No software reliability requirements have been identified.
+
+\section{Software Maintainability Requirements}
+
+\requirement{GEN-0301} {Version Identification}{%
+It shall be possible to identifiy the version of compiled binary software
+components by reading their identifier from a special memory segment.
+}{
+The build identifier or version number should be set and defined when building
+the binary.
+}%
+
+
+\section{Software Safety Requirements}
+
+\requirement{GEN-0401} {Stack Pointer Checks}{%
+The stack pointer of a task shall be checked for feasibility before scheduling
+the latter.
+}{
+}%
+
+\requirement{GEN-0402} {Correctable Traps}{%
+LeanOS shall provide handlers for correctable traps caused by kernel or user
+code and either correctly execute the desired operation (e.g. unaligned access)
+or replace the result with a default value (e.g. divison by zero) and skip the
+offending code instruction to continue.
+}{
+}
+
+\requirement{GEN-0403} {Trap Error Reporting}{%
+LeanOS shall make an entry into its error message log when a trap event occurs,
+describing the nature and source of the trap.
+}{
+}
+
+
+
+\section{Software Configuration and Delivery Requirements}
+
+\requirement{GEN-0005} {Build configuration}{%
+LeanOS shall make use of the Linux Kernel Build System (kbuild) for its
+configuration.
+}{}%
+
+
+\section{Data Definition and Database Requirements}
+
+No data definition or database requirements have been identified.
+
+
+\section{Human Factors Related Requirements}
+
+No human factors related requirements have been identified.
+
+\section{Adaptation and Installation Requirements}
+
+No adaptation and installation requirements have been identified.
+
+
+\chapter{Validation Requirements}
+
+\requirement{GEN-1001} {Verification Method}{%
+The verification method and verification activity shall be specified 
+in a Software Qualification Test Plan for each requirement.
+}{}%
+
+\requirement{GEN-1002} {Qualification Testing}{%
+SW qualification testing shall be performed with various configurations of
+LeanOS.
+}{}%
+
+
+%\begin{description}
+%  \item\design{SRT-0001} First design. \meetsreq{GEN-0001}
+%  \item\design{SRT-0002} Second design. \meetsreq{GEN-0001}
+%  \begin{description}
+%    \item\design{SRT-0002.1} Third design. \meetsreq{GEN-0002}
+%    \item\design{SRT-0002.2} Fourth design \meetsreq{GEN-0004, GEN-0005}
+%  \end{description}
+%\end{description}
+
+%\traceabilitymatrix
+
+
+\chapter{Traceability}
+
+The requirements in this document are both user and system requirements.
+Traces from design and test to the software requirements are given in the
+respective documents.
+
+
+\chapter{Logical Model Description}
+
+\begin{figure}[htb]
+\begin{center}
+	\includegraphics[width=\columnwidth]{images/OS_logical}
+	\caption{The logical model of LeanOS. Here, the "hardware" layer
+	represents both the hardware and the hardware abstraction layer of
+	the software.}
+	\label{fig:logical_model}
+\end{center}
+\end{figure}
+
+In LeanOS, the \gls{SSDP} hardware is accessed in multiple layers of
+abstraction (see \fig{fig:logical_model}). Typical \gls{CPU} tasks such as thread/task
+management and timer operation are used as part of the operating system kernel
+and are also accessible by user applications via a system call interface.
+Other functional hardware components of the \gls{SSDP} such as the \gls{NoC}
+\gls{DMA} have their own driver modules. These are in turn used by the
+\gls{Xentium} scheduler and other higher level modules in the operating system.
+Configuration of and access to the latter from user space is done via a system
+call interface. The system control interface serves as an intermediate between
+all layers of the operating system, where system or module states and hardware
+modes or usage statistics may be exported by individual components for external
+(user) access.
+
+
+
+%\chapter*{Document Change History}
+
+
+\end{document}

Documentation/OS/shared/bibliography.bib

+@book{SPARCv8,
+	title		= "The SPARC Architecture Manual Version 8",
+	organization	= "SPARC International, Inc.",
+	year		= "1991, 1992",
+	version		= "Revision SAV080SI9308",
+}
+
+@book{MPPB,
+	title		= "Massively Parallel Processor Breadboarding Datasheet",
+	organization	= "Recore Systems BV",
+	year		= "2016",
+	version		= "4.02",
+}
+
+@book{ECSS40C,
+	title		= "ECSS-E-ST-40C Space engineering - Software",
+	organization	= "European Space Agency",
+	year		= "2009",
+	publisher	= "ESA Requirements and Standards Division",
+}
+