projects / h316.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
*** empty log message ***
[h316.git] / pc-tools / ldc2 / doc / req_spec.tex
diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex
index 4559aadbfc5bc0d5fe1251b507fd436e6ad8729b..fb2cf5c641e6f4e50af24cec1dda981324b6a49a 100644 (file)
--- a/pc-tools/ldc2/doc/req_spec.tex
+++ b/pc-tools/ldc2/doc/req_spec.tex
@@ -1,4 +1,42 @@
-\section{Functional Specification}
+\section{General Requirements}
+
+\subsection{Must Criteria}
+\begin{itemize}
+\item The program shall run on any computer running GNU/Linux.
+\item It has no graphical user interface but a help option and command line error reporting.
+\item The program shall support and check all block types according to \cite{ser16:progref:bformats}.
+\item The Program must be able to list a tape image's contents.
+\item The program shall be capable of splitting tape images into single object files.
+\item The program's structure must be modular and easily extendable.
+\end{itemize}
+
+\subsection{Optional features}
+\begin{itemize}
+\item Possibility to split a tape image into single data block files.
+\item Software handshake paper tape reader control:\\
+A paper paper tape reader connected to the computer's serial port could be motion-controlled
+by use of XON and XOFF characters. This is useful when error breaks for tape inspection are
+enabled and the paper tape device does not support RTS/CTS hardware handshake.
+\item Full POSIX.1, 2004 edition, compliance.\\
+       This enables the program to be usable under many different UNIX style operating
+       systems.
+\end{itemize}
+
+\subsection{Further additions explicitely beyond the scope of this project}
+\begin{itemize}
+\item Detailed data block analysis:
+       \begin{itemize}
+       \item Linking objects into a virtual memory representation.
+       \item Generating disassembly listings of block contents
+       \end{itemize}
+
+\item   Support for self loading system tapes generated by \emph{PAL-AP} (see \cite{ser16:opmanual}).
+
+\end{itemize}
+
+%*******************************************************************************
+\newpage
+\section{Detailed Functional Specification}
 
 %*******************************************************************************
 \subsection{Data input processing}
 
 %*******************************************************************************
 \subsection{Data input processing}
@@ -110,6 +148,116 @@ found in \cite{ser16:progref:bformats}.
        a zero-padded three digit number and EOT blocks are not suppressed.
 }
 
        a zero-padded three digit number and EOT blocks are not suppressed.
 }
 
+
+%*******************************************************************************
+\newpage
+\subsection{Error handling}
+
+
+\newcommand{\esup}{
+       This error shall lead to an error message and immediate program
+       termination or a warning message and program continuation.
+}
+
+\newcommand{\enosup}{
+       This error shall always lead to an error message and immediate
+       program termination.
+}
+
+\rd{err001}{Error types}{
+       The following distinguished error types shall exist:
+       \begin{itemize}
+       \item Input/output error:\\ 
+               Error occuring during reading from the input file descriptor
+               or during writing to an output file.\\
+               \enosup
+       \item Block integrity error:\\
+               Caused by failed check according to \req{chk001}.\\
+               \esup
+       \item Checksum error:\\
+               Caused by failed check according to \req{chk002}.\\
+               \esup
+       \item Unknown block type error:\\
+               Caused by failed check according to \req{chk003}.\\
+               \esup           
+       \item Object integrity error:\\
+               Caused by failed check according to \req{chk004}.\\
+               \esup
+       \item Usage error:\\
+               Error caused by errors in the program configuration i.e. wrong 
+               parameters or impossible combinations of parameters.\\
+               \enosup \\
+               Additionally, the help (\req{h001}) message is output.
+       \item   Internal program error:\\
+               Error caused by internal program problems.\\
+               This error should never occur.\\
+               \enosup
+       \end{itemize}
+}
+
+\rd{err002}{Program exit codes}{
+       \begin{table}[H]
+       \begin{center}
+       \begin{tabular}{|r|c|}
+               \hline
+               \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\
+               \hline
+               Successfull program completion & 0 \\
+               File open error & 1\\
+               Input/output error & 2\\
+               Block integrity error & 3\\
+               Checksum error & 4\\
+               Unknown block type error & 5\\
+               Object integrity error & 6\\
+               Usage error & 7\\
+               Internal program error & 100 \\
+               \hline 
+       \end{tabular}
+       \caption[Program Exit codes]{Exit codes}
+       \end{center}
+       \end{table}
+}
+
+\rd{err003}{Error and warning messages}{
+       Error messages shall consinst of ''Error:'' and the error reason.\\
+       Warning messages shall consist of ''Warning:'' and a descriptive 
+       text.\\
+       The following texts shall be used to form error and warning messages:
+       \begin{table}[H]
+       \begin{center}
+       \begin{tabular}{|l|l|}
+       \hline
+       \bf Error condition & \bf Descriptive text\\ \hline
+       File open error & Could not open $<$filename$>$ for reading/writing!\\
+       Input error     &     Could not read from $<$filename$>$!\\
+       Output error    &    Could not write to $<$filename$>$!\\
+       Block integrity error & Block integrity check failed!\\
+       Checksum error        & Block checksum wrong!\\
+       Unknown block type    & Unknown block type!\\
+       Object integrity      & Object integrity check failed!\\
+       Usage error           & $<$Specific message describing the problem$>$\\
+       \hline
+       \end{tabular}
+       \end{center}
+       \caption[Error and warning messages]{Messages}
+       \end{table}
+}
+
+\rd{err004}{Error message output}{
+       Any error messages shall be output to standard error.\\
+       There shall be no way to suppress error messages.
+}
+
+\rd{err005}{Warning message output}{
+       Any warning messages shall be output to standard error.\\
+       There shall be a possibility to suppress warning messages.
+}
+
+\rd{err006}{Informational messages}{
+       Any informational messages go to standard error.
+}
+
+
 %*******************************************************************************       
 \newpage
 \subsection{Program configuration}
 %*******************************************************************************       
 \newpage
 \subsection{Program configuration}
@@ -130,7 +278,9 @@ found in \cite{ser16:progref:bformats}.
                        configuration file. 
                \item Configuration parameters passed via the command line:\\
                        Parameters passed on the command line will override
                        configuration file. 
                \item Configuration parameters passed via the command line:\\
                        Parameters passed on the command line will override
-                       values from previously read configuration files.
+                       values from previously read configuration files. If the command line
+                       mentiones a configuration file to read, this file is processed before
+                       the other parameters supplied on the command line.
        \end{enumerate}
 }
 
        \end{enumerate}
 }
 
@@ -178,6 +328,8 @@ found in \cite{ser16:progref:bformats}.
        ignore\_object\_integrity\_errors & g & Ignore errors caused by objects
                                                without proper end block 
                                                (\req{err001}\req{chk004}).\\
        ignore\_object\_integrity\_errors & g & Ignore errors caused by objects
                                                without proper end block 
                                                (\req{err001}\req{chk004}).\\
+       quiet                             & q & Suppress all non-critical  messages 
+                                                 to standard error (warnings, informatianal)\\
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration switches}
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration switches}
@@ -215,7 +367,8 @@ ConfigurationLine = SwitchLine | StringLine | CommentLine ;
                     | "ignore_block_errors" | "ignore_checksum_errors
                     | "pause_on_checksum_error"
                     | "ignore_unknown_block_errors"
                     | "ignore_block_errors" | "ignore_checksum_errors
                     | "pause_on_checksum_error"
                     | "ignore_unknown_block_errors"
-                    | "ignore_object_integrity" ;
+                    | "ignore_object_integrity"
+                    | "quiet" ;
           StrLong = "out_file" | "in_file" ;
         BoolValue = TrueStr | FalseStr ;
            String = { ? Every character except newline ?} ;
           StrLong = "out_file" | "in_file" ;
         BoolValue = TrueStr | FalseStr ;
            String = { ? Every character except newline ?} ;
@@ -240,14 +393,15 @@ ShortSwitch = "-" SwShort ;
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
     SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S"
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
     SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S"
-              | "b" | "k" | "p" | "n" | "g" ;
+              | "b" | "k" | "p" | "n" | "g" | "q";
      SwLong = "help"
               | "output_info" | "ouput_called" | "output_exported"
               | "output_unsatisfied" | "split_objects" [ _"numbered" ]
               | "ignore_block_errors" | "ignore_checksum_errors"
               | "pause_on_checksum_error"
               | "ignore_unknown_block_errors"
      SwLong = "help"
               | "output_info" | "ouput_called" | "output_exported"
               | "output_unsatisfied" | "split_objects" [ _"numbered" ]
               | "ignore_block_errors" | "ignore_checksum_errors"
               | "pause_on_checksum_error"
               | "ignore_unknown_block_errors"
-              | "ignore_object_integrity" ;
+              | "ignore_object_integrity" 
+              | "quiet" ;
    StrShort = "o" ;
     StrLong = "out_file" ;
 \end{verbatim}
    StrShort = "o" ;
     StrLong = "out_file" ;
 \end{verbatim}
@@ -255,11 +409,12 @@ ShortSwitch = "-" SwShort ;
 \newpage
 \rd{cfg007}{Configuration implications}{
        \begin{itemize}
 \newpage
 \rd{cfg007}{Configuration implications}{
        \begin{itemize}
-       \item pause\_on\_checksum\_errors implies ignore\_checksum\_errors.
-       \item pause\_on\_checksum\_errors is completely ignored when input 
+       \item \emph{pause\_on\_checksum\_errors} implies \emph{ignore\_checksum\_errors}.
+       \item \emph{pause\_on\_checksum\_errors} is completely ignored when input 
        is read from standard input.
        is read from standard input.
-       \item output\_* inhibits tape information output (\req{da001}).
-       \item help inhibits all other actions.
+       \item \emph{output\_*} and \emph{split\_*} inhibit 
+       tape information output (\req{da001}).
+       \item \emph{help} inhibits all other actions.
        \end{itemize}
 }
 
        \end{itemize}
 }
 
@@ -268,112 +423,6 @@ ShortSwitch = "-" SwShort ;
        \item Data is read from standard input.
        \item All error conditions result in immediate program termination
                and an error message.
        \item Data is read from standard input.
        \item All error conditions result in immediate program termination
                and an error message.
-       \item Tape information according to \req{da001} is output.
-       \item Text is output to standard output.
+       \item Tape information according to \req{da001} is output to standard output.
        \end{itemize}
 }
        \end{itemize}
 }
-
-%*******************************************************************************
-\newpage
-\subsection{Error handling}
-
-
-\newcommand{\esup}{
-       This error shall lead to an error message and immediate program
-       termination or a warning message and program continuation.
-}
-
-\newcommand{\enosup}{
-       This error shall always lead to an error message and immediate
-       program termination.
-}
-
-\rd{err001}{Error types}{
-       The following distinguished error types shall exist:
-       \begin{itemize}
-       \item Input/output error:\\ 
-               Error occuring during reading from the input file descriptor
-               or during writing to an output file.\\
-               \enosup
-       \item Block integrity error:\\
-               Caused by failed check according to \req{chk001}.\\
-               \esup
-       \item Checksum error:\\
-               Caused by failed check according to \req{chk002}.\\
-               \esup
-       \item Unknown block type error:\\
-               Caused by failed check according to \req{chk003}.\\
-               \esup           
-       \item Object integrity error:\\
-               Caused by failed check according to \req{chk004}.\\
-               \esup
-       \item Usage error:\\
-               Error caused by errors in the program configuration i.e. wrong 
-               parameters or impossible combinations of parameters.\\
-               \enosup \\
-               Additionally, the help (\req{h001}) message is output.
-       \item   Internal program error:\\
-               Error caused by internal program problems.\\
-               This error should never occur.\\
-               \enosup
-       \end{itemize}
-}
-
-\rd{err002}{Program exit codes}{
-       \begin{table}[H]
-       \begin{center}
-       \begin{tabular}{|r|c|}
-               \hline
-               \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\
-               \hline
-               Successfull program completion & 0 \\
-               File open error & 1\\
-               Input/output error & 2\\
-               Block integrity error & 3\\
-               Checksum error & 4\\
-               Unknown block type error & 5\\
-               Object integrity error & 6\\
-               Usage error & 7\\
-               Internal program error & 100 \\
-               \hline 
-       \end{tabular}
-       \caption[Program Exit codes]{Exit codes}
-       \end{center}
-       \end{table}
-}
-
-\rd{err003}{Error and warning messages}{
-       Error messages shall consinst of ''Error:'' and the error reason.\\
-       Warning messages shall consist of ''Warning:'' and a descriptive 
-       text.\\
-       The following texts shall be used to form error and warning messages:
-       \begin{table}[H]
-       \begin{center}
-       \begin{tabular}{|l|l|}
-       \hline
-       \bf Error condition & \bf Descriptive text\\ \hline
-       File open error & Could not open $<$filename$>$ for reading/writing!\\
-       Input error     &     Could not read from $<$filename$>$!\\
-       Output error    &    Could not write to $<$filename$>$!\\
-       Block integrity error & Block integrity check failed!\\
-       Checksum error        & Block checksum wrong!\\
-       Unknown block type    & Unknown block type!\\
-       Object integrity      & Object integrity check failed!\\
-       Usage error           & $<$Specific message describing the problem$>$\\
-       \hline
-       \end{tabular}
-       \end{center}
-       \caption[Program Exit codes]{Exit codes}
-       \end{table}
-}
-
-\rd{err004}{Error message output}{
-       Any error messages shall be output to standard error.\\
-       There shall be no way to suppress error messages.
-}
-
-\rd{err005}{Warning message output}{
-       Any warning messages shall be output to standard error.\\
-       There shall be a possibility to suppress warning messages.
-}
-
My complete H316 universe