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 fb2cf5c641e6f4e50af24cec1dda981324b6a49a..e81c23dfb45ba5338f2bfb0ed62d5664d43709a4 100644 (file)
--- a/pc-tools/ldc2/doc/req_spec.tex
+++ b/pc-tools/ldc2/doc/req_spec.tex
@@ -5,7 +5,7 @@
 \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 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 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}
 \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}
@@ -14,7 +14,7 @@
 \begin{itemize}
 \item Possibility to split a tape image into single data block files.
 \item Software handshake paper tape reader control:\\
 \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
+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.\\
 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.\\
@@ -78,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}
@@ -101,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.
@@ -148,6 +160,10 @@ 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
 
 %*******************************************************************************
 \newpage
@@ -165,11 +181,15 @@ found in \cite{ser16:progref:bformats}.
 }
 
 \rd{err001}{Error types}{
 }
 
 \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:\\ 
        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.\\
+               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}.\\
                \enosup
        \item Block integrity error:\\
                Caused by failed check according to \req{chk001}.\\
@@ -196,7 +216,11 @@ found in \cite{ser16:progref:bformats}.
 }
 
 \rd{err002}{Program exit codes}{
 }
 
 \rd{err002}{Program exit codes}{
-       \begin{table}[H]
+       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
        \begin{center}
        \begin{tabular}{|r|c|}
                \hline
@@ -210,6 +234,7 @@ found in \cite{ser16:progref:bformats}.
                Unknown block type error & 5\\
                Object integrity error & 6\\
                Usage error & 7\\
                Unknown block type error & 5\\
                Object integrity error & 6\\
                Usage error & 7\\
+                Success with warnings & 99 \\
                Internal program error & 100 \\
                \hline 
        \end{tabular}
                Internal program error & 100 \\
                \hline 
        \end{tabular}
@@ -219,6 +244,8 @@ found in \cite{ser16:progref:bformats}.
 }
 
 \rd{err003}{Error and warning messages}{
 }
 
 \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.\\
        Error messages shall consinst of ''Error:'' and the error reason.\\
        Warning messages shall consist of ''Warning:'' and a descriptive 
        text.\\
@@ -316,12 +343,14 @@ 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\_unknown\_block\_errors    & n  & Ignore errors causes by 
                                                datablocks of   unknown type
                                                 (\req{err001}\req{chk003}).\\
@@ -355,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 ;
@@ -363,9 +395,9 @@ 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_object_integrity"
                     | "quiet" ;
                     | "ignore_unknown_block_errors"
                     | "ignore_object_integrity"
                     | "quiet" ;
@@ -373,7 +405,7 @@ ConfigurationLine = SwitchLine | StringLine | CommentLine ;
         BoolValue = TrueStr | FalseStr ;
            String = { ? Every character except newline ?} ;
           TrueStr = "yes" | "1" | "true" ;
         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}{
@@ -392,27 +424,31 @@ 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"
+    SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" | "B"
               | "b" | "k" | "p" | "n" | "g" | "q";
      SwLong = "help"
               | "output_info" | "ouput_called" | "output_exported"
               | "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"
               | "ignore_object_integrity" 
               | "quiet" ;
    StrShort = "o" ;
     StrLong = "out_file" ;
 \end{verbatim}
               | "ignore_unknown_block_errors"
               | "ignore_object_integrity" 
               | "quiet" ;
    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 \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.
-       \item \emph{output\_*} and \emph{split\_*} inhibit 
+%      \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}
        tape information output (\req{da001}).
        \item \emph{help} inhibits all other actions.
        \end{itemize}
My complete H316 universe