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 7ca7c1b178989e74ea37d8ec17bcc47ce259bca1..fb2cf5c641e6f4e50af24cec1dda981324b6a49a 100644 (file)
--- a/pc-tools/ldc2/doc/req_spec.tex
+++ b/pc-tools/ldc2/doc/req_spec.tex
@@ -1,4 +1,42 @@
-\section{Requirements 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}
@@ -15,8 +53,8 @@
 The tape data shall be checked against the Honeywell tape block specification
 found in \cite{ser16:progref:bformats}.
  
 The tape data shall be checked against the Honeywell tape block specification
 found in \cite{ser16:progref:bformats}.
  
-\rd{chk001}{Block completeness check}{
-       Every data block's completeness shall be checked by the means of 
+\rd{chk001}{Block integrity check}{
+       Every data block's integrity shall be checked by the means of 
        detecting unexpected end of file while reading in the block.
 }
 
        detecting unexpected end of file while reading in the block.
 }
 
@@ -48,6 +86,14 @@ found in \cite{ser16:progref:bformats}.
 }
 
 %*******************************************************************************
 }
 
 %*******************************************************************************
+\subsection{Additional features}
+
+\rd{h001}{Print help message}{
+       A help message is output to standard error.
+}
+
+%*******************************************************************************
+\newpage
 \subsection{Data analysis}
 
 \rd{da001}{List tape contents}{
 \subsection{Data analysis}
 
 \rd{da001}{List tape contents}{
@@ -85,6 +131,7 @@ found in \cite{ser16:progref:bformats}.
 }
 
 %*******************************************************************************
 }
 
 %*******************************************************************************
+\newpage
 \subsection{Data processing}
 
 \rd{dp001}{Split into object files}{
 \subsection{Data processing}
 
 \rd{dp001}{Split into object files}{
@@ -101,18 +148,123 @@ 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.
 }
 
+
 %*******************************************************************************
 %*******************************************************************************
-\subsection{Additional features}
+\newpage
+\subsection{Error handling}
 
 
-\rd{h001}{Print help message}{
-       A help message shall be output to standard error.
+
+\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}
 
 \rd{cfg001}{Configuration process}{
 \subsection{Program configuration}
 
 \rd{cfg001}{Configuration process}{
-       The following sequence shall be used to acquire the working configuration:
+       The following sequence shall be used to acquire the working 
+       configuration:
        \begin{enumerate}
                \item Configuration file according to environment variable:\\
                        If the environment variable LDC\_CONFIG is set, that
        \begin{enumerate}
                \item Configuration file according to environment variable:\\
                        If the environment variable LDC\_CONFIG is set, that
@@ -122,11 +274,13 @@ found in \cite{ser16:progref:bformats}.
                        file is found,
                        the specified configuration file is parsed.\\
                        Any values in this configuration file
                        file is found,
                        the specified configuration file is parsed.\\
                        Any values in this configuration file
-                       override values found in the previously read configuration 
-                       file. 
+                       override values found in the previously read 
+                       configuration file. 
                \item Configuration parameters passed via the command line:\\
                        Parameters passed on the command line will override
                \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}
 }
 
@@ -134,34 +288,48 @@ found in \cite{ser16:progref:bformats}.
        The program shall accept two types of parameters:
        \begin{itemize}
        \item Switches:\\
        The program shall accept two types of parameters:
        \begin{itemize}
        \item Switches:\\
-               A switch is a binary value which can have the value true or false.
+               A switch is a binary value which can have the value true or 
+               false.
        \item Strings:\\
                A string parameter is a parameter requiring a string value.\\
                A typical use would be a file name for input or output.
        \end{itemize}
 }
 
        \item Strings:\\
                A string parameter is a parameter requiring a string value.\\
                A typical use would be a file name for input or output.
        \end{itemize}
 }
 
+\newpage
 \rd{cfg003}{Switch parameters}{
        The following switch parameters shall be accepted:
        \begin{table}[H]\begin{center}
 \rd{cfg003}{Switch parameters}{
        The following switch parameters shall be accepted:
        \begin{table}[H]\begin{center}
-       \begin{tabular}{|r|p{2.5em}|l|}
+       \begin{tabular}{|r|p{2.5em}|p{23em}|}
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
        help                       & h & Show help message (\req{h001})\\
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
        help                       & h & Show help message (\req{h001})\\
-       output\_info               & a & Output data info according to \req{da005}.\\
-       output\_called             & c & Output a list of called symbols (\req{dp003}).\\ 
-       output\_exported           & e & Output a list of exported symbols (\req{dp002}).\\
-       output\_unsatisfied        & u & Output a list of unsatisfied dependencies (\req{dp004}).\\
-       split\_objects             & s & Split into object files (\req{dp006}.\\
-       split\_objects\_numbered   & S & Split into numbered object files (\req{dp007}).\\
-       ignore\_block\_errors      & b & Ignore block integrity errors (\req{err001}).\\
-       ignore\_checksum\_errors   & k & Ignore Checksum errors (\req{err001}).\\
-       pause\_on\_checksum\_error & p & Wait for user input on checksum error (\req{err003}).\\
-       ignore\_unknown\_block\_errors    & n  & Ignore errors causes by datablocks of 
-                                               unknown type (\req{err001}).\\
-       ignore\_object\_integrity\_errors & g & Ignore errors caused by objects without 
-                                               proper end block (\req{err001}.)\\
+       output\_info               & a & Output data info (\req{da005}) .\\
+       output\_called             & c & Output a list of called symbols 
+                                               (\req{da003}).\\ 
+       output\_exported           & e & Output a list of exported symbols 
+                                               (\req{da002}).\\
+       output\_unsatisfied        & u & Output a list of unsatisfied 
+                                               dependencies (\req{da004}).\\
+       split\_objects             & s & Split into object files 
+                                               (\req{dp001}).\\
+       split\_objects\_numbered   & S & Split into numbered object files 
+                                               (\req{dp002}).\\
+       ignore\_block\_errors      & b & Ignore block integrity errors 
+                                               (\req{err001},\req{chk001}).\\
+       ignore\_checksum\_errors   & k & Ignore Checksum errors 
+                                               (\req{err001}\req{chk002}).\\
+       pause\_on\_checksum\_error & p & Wait for user input on checksum error 
+                                               (\req{chk005}).\\
+       ignore\_unknown\_block\_errors    & n  & Ignore errors causes by 
+                                               datablocks of   unknown type
+                                                (\req{err001}\req{chk003}).\\
+       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}
@@ -175,15 +343,15 @@ found in \cite{ser16:progref:bformats}.
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
        \hline
        \bf Long Form & \bf Short form & \bf Description\\
        \hline
-       in\_file                   & i & Set input file (\req{inp001}) \\
-       out\_file                  & o & Set output file for text output.(\req{dp008})\\
+       in\_file                   & i & Set input file (\req{inp001}). \\
+       out\_file                  & o & Set output file for text output(\req{dp008}).\\
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration strings}
        \end{table}     
 
 }
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration strings}
        \end{table}     
 
 }
-
+\newpage
 \rd{cfg005}{Configuration file syntax}{
        The configuration file must comply two the following grammar, given in EBNF:
 }
 \rd{cfg005}{Configuration file syntax}{
        The configuration file must comply two the following grammar, given in EBNF:
 }
@@ -199,15 +367,16 @@ 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 ?} ;
           TrueStr = "yes" | "1" | "true" ;
          FalseStr = | "no" | "0" | "false" ;
           StrLong = "out_file" | "in_file" ;
         BoolValue = TrueStr | FalseStr ;
            String = { ? Every character except newline ?} ;
           TrueStr = "yes" | "1" | "true" ;
          FalseStr = | "no" | "0" | "false" ;
-       \end{verbatim};
+       \end{verbatim}
 
 
-\rd{cfg006}{Commandline syntax}{
+\rd{cfg006}{Command Line syntax}{
        The command line must comply to the following grammar, given in EBNF:   
 }
 \begin{verbatim}
        The command line must comply to the following grammar, given in EBNF:   
 }
 \begin{verbatim}
@@ -223,25 +392,29 @@ ShortSwitch = "-" SwShort ;
  LongSwitch = "--" SwLong [ "=" BoolValue ] ;
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
  LongSwitch = "--" SwLong [ "=" BoolValue ] ;
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
-    SwShort = "a" | "c" | "e" | "u" | "s" | "S"
-              | "b" | "k" | "p" | "n" | "g" ;
-     SwLong = "output_info" | "ouput_called" | "output_exported"
+    SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S"
+              | "b" | "k" | "p" | "n" | "g" | "q";
+     SwLong = "help"
+              | "output_info" | "ouput_called" | "output_exported"
               | "output_unsatisfied" | "split_objects" [ _"numbered" ]
               | "output_unsatisfied" | "split_objects" [ _"numbered" ]
-              | "ignore_block_errors" | "ignore_checksum_errors
+              | "ignore_block_errors" | "ignore_checksum_errors"
               | "pause_on_checksum_error"
               | "ignore_unknown_block_errors"
               | "pause_on_checksum_error"
               | "ignore_unknown_block_errors"
-              | "ignore_object_integrity" ;
-   StrShort = "o";
+              | "ignore_object_integrity" 
+              | "quiet" ;
+   StrShort = "o" ;
     StrLong = "out_file" ;
 \end{verbatim}
 
     StrLong = "out_file" ;
 \end{verbatim}
 
+\newpage
 \rd{cfg007}{Configuration implications}{
        \begin{itemize}
 \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}
 }
 
@@ -250,111 +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}
 }
-
-%*******************************************************************************
-\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           & $<$Error 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