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..ba089c5b02493c154cbe3eaf002aa8577f9b9459 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 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}
@@ -40,12 +78,6 @@ found in \cite{ser16:progref:bformats}.
        an end of tape mark is an appropriate end block.
 }
 
        an end of tape mark is an appropriate end block.
 }
 
-\rd{chk005}{Interactive checksum error handling}{
-       The program shall be configurable to pause block processing on
-       detection of a checksum error (\req{chk002}) and resume processing after
-       user intervention.\\
-       This feature is incompatible with data input from standard input.
-}
 
 %*******************************************************************************
 \subsection{Additional features}
 
 %*******************************************************************************
 \subsection{Additional features}
@@ -63,6 +95,24 @@ found in \cite{ser16:progref:bformats}.
        of all blocks contained in the input data.\\
        The output line format shall be unified for all block types.
 }
        of all blocks contained in the input data.\\
        The output line format shall be unified for all block types.
 }
+\vspace{0.5em}
+\par
+Here is an example output for the object \verb|O$PB|: \begin{verbatim}
+O$PB       (0-0)     Subprogram Name
+O$PS       (0-0)         "        "
+O$PLDR     (0-0)         "        "
+           (0-24)    Switch to relocatable mode
+           (0-4)     Data
+           (0-4)     Data
+O$PB       (0-50)    Subprogram Entry Point Definition
+           (0-4)     Data
+           (0-4)     Data
+           (0-4)     Data
+O$PLDR     (0-50)    Subprogram Entry Point Definition
+           (0-4)     Data
+           (0-4)     Data
+           (0-14)    End
+\end{verbatim}
 
 \rd{da002}{List exported symbols}{
        Output a list of all exported symbols.
 
 \rd{da002}{List exported symbols}{
        Output a list of all exported symbols.
@@ -110,6 +160,131 @@ 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.
 }
 
+\rd{dp003}{Split into numbered blocks}{
+       The whole tape is split into one named and numbered file for each block.
+}
+
+
+%*******************************************************************************
+\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 program shall react to several error conditions. Some error
+       conditions can be turned into warnings by program configuration,
+       see \req{cfg003} and \req{cfg004} for details.\\
+       The following distinguished error types shall exist:
+       \begin{itemize}
+       \item Input/output error:\\ 
+               Error occuring during read from the input file descriptor
+               or during write to an output file.\\
+               No recovery from this error is possible.
+               \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}{
+       The application shall return several different exir codes to the
+       execution environment (i.e. the shell). On occurrence of any error,
+       the program shall terminate with the appropriate exit code.\\
+       Program runs with warnings shall return a special exit code.
+       \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\\
+                Success with warnings & 99 \\
+               Internal program error & 100 \\
+               \hline 
+       \end{tabular}
+       \caption[Program Exit codes]{Exit codes}
+       \end{center}
+       \end{table}
+}
+
+\rd{err003}{Error and warning messages}{
+       Every warning or error case shall cause an appropriate error respective 
+       warning message.\\
+       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 +305,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}
 }
 
@@ -166,18 +343,22 @@ found in \cite{ser16:progref:bformats}.
                                                (\req{dp001}).\\
        split\_objects\_numbered   & S & Split into numbered object files 
                                                (\req{dp002}).\\
                                                (\req{dp001}).\\
        split\_objects\_numbered   & S & Split into numbered object files 
                                                (\req{dp002}).\\
+       split\_blocks               & B & Split tape into named and numbered block 
+                                                files (\req{dp003}).\\
        ignore\_block\_errors      & b & Ignore block integrity errors 
                                                (\req{err001},\req{chk001}).\\
        ignore\_checksum\_errors   & k & Ignore Checksum errors 
                                                (\req{err001}\req{chk002}).\\
        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}).\\
+%      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}).\\
        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 
+                                                (warnings, informational text)\\
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration switches}
        \hline 
        \end{tabular}\end{center}
        \caption{Configuration switches}
@@ -203,6 +384,9 @@ found in \cite{ser16:progref:bformats}.
 \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:
 }
+
+%                   | "pause_on_checksum_error"
+
        \begin{verbatim}
 ConfigurationFile = { ConfigurationLine "<EOL>" } ;
 ConfigurationLine = SwitchLine | StringLine | CommentLine ;
        \begin{verbatim}
 ConfigurationFile = { ConfigurationLine "<EOL>" } ;
 ConfigurationLine = SwitchLine | StringLine | CommentLine ;
@@ -211,16 +395,17 @@ ConfigurationLine = SwitchLine | StringLine | CommentLine ;
       CommentLine = WSpace [ "#" String ] ;
            WSpace = { " " } ;
            SwLong = "output_info" | "ouput_called" | "output_exported"
       CommentLine = WSpace [ "#" String ] ;
            WSpace = { " " } ;
            SwLong = "output_info" | "ouput_called" | "output_exported"
-                    | "output_unsatisfied" | "split_objects" [ _"numbered" ]
+                    | "output_unsatisfied" | "split_objects" [ "_numbered" ]
+                    | "split_blocks"
                     | "ignore_block_errors" | "ignore_checksum_errors
                     | "ignore_block_errors" | "ignore_checksum_errors
-                    | "pause_on_checksum_error"
                     | "ignore_unknown_block_errors"
                     | "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" ;
           StrLong = "out_file" | "in_file" ;
         BoolValue = TrueStr | FalseStr ;
            String = { ? Every character except newline ?} ;
           TrueStr = "yes" | "1" | "true" ;
-         FalseStr = | "no" | "0" | "false" ;
+         FalseStr = "no" | "0" | "false" ;
        \end{verbatim}
 
 \rd{cfg006}{Command Line syntax}{
        \end{verbatim}
 
 \rd{cfg006}{Command Line syntax}{
@@ -239,27 +424,33 @@ ShortSwitch = "-" SwShort ;
  LongSwitch = "--" SwLong [ "=" BoolValue ] ;
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
  LongSwitch = "--" SwLong [ "=" BoolValue ] ;
  ShortParam = "-" StrShort String ;
   LongParam = "--" StrLong "=" String ;
-    SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S"
-              | "b" | "k" | "p" | "n" | "g" ;
+    SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" | "B"
+              | "b" | "k" | "p" | "n" | "g" | "q";
      SwLong = "help"
               | "output_info" | "ouput_called" | "output_exported"
      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"
               | "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}
+       Some command line examples:\\
+       \verb|ldc2 -ve --output-file=out.dat in.dat|\\
+       \verb|ldc2 -kb test.obj|\\
+
+%             | "pause_on_checksum_error"
 
 \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 
-       is read from standard input.
-       \item output\_* inhibits tape information output (\req{da001}).
-       \item help inhibits all other actions.
+%      \item \emph{pause\_on\_checksum\_error} implies \emph{ignore\_checksum\_errors}.
+%      \item \emph{pause\_on\_checksum\_error} is completely ignored when input 
+%      is read from standard input.
+       \item \emph{output\_*} inhibit 
+       tape information output (\req{da001}).
+       \item \emph{help} inhibits all other actions.
        \end{itemize}
 }
 
        \end{itemize}
 }
 
@@ -268,112 +459,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