X-Git-Url: http://gitweb.hachti.de/?a=blobdiff_plain;f=pc-tools%2Fldc2%2Fdoc%2Freq_spec.tex;h=e81c23dfb45ba5338f2bfb0ed62d5664d43709a4;hb=de6b6757167b76f4c363177d66f3ac4502811b42;hp=fb2cf5c641e6f4e50af24cec1dda981324b6a49a;hpb=469fccad06f660330da12c66f0e95582f3e646a4;p=h316.git diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex index fb2cf5c..e81c23d 100644 --- 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 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} @@ -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:\\ -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.\\ @@ -78,12 +78,6 @@ found in \cite{ser16:progref:bformats}. 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} @@ -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. } +\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. @@ -148,6 +160,10 @@ found in \cite{ser16:progref:bformats}. 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 @@ -165,11 +181,15 @@ found in \cite{ser16:progref:bformats}. } \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 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}.\\ @@ -196,7 +216,11 @@ found in \cite{ser16:progref:bformats}. } \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 @@ -210,6 +234,7 @@ found in \cite{ser16:progref:bformats}. Unknown block type error & 5\\ Object integrity error & 6\\ Usage error & 7\\ + Success with warnings & 99 \\ Internal program error & 100 \\ \hline \end{tabular} @@ -219,6 +244,8 @@ found in \cite{ser16:progref:bformats}. } \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.\\ @@ -316,12 +343,14 @@ found in \cite{ser16:progref:bformats}. (\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}).\\ - 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}).\\ @@ -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: } + +% | "pause_on_checksum_error" + \begin{verbatim} ConfigurationFile = { ConfigurationLine "" } ; ConfigurationLine = SwitchLine | StringLine | CommentLine ; @@ -363,9 +395,9 @@ ConfigurationLine = SwitchLine | StringLine | CommentLine ; 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 - | "pause_on_checksum_error" | "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" ; - FalseStr = | "no" | "0" | "false" ; + FalseStr = "no" | "0" | "false" ; \end{verbatim} \rd{cfg006}{Command Line syntax}{ @@ -392,27 +424,31 @@ ShortSwitch = "-" SwShort ; 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" - | "output_unsatisfied" | "split_objects" [ _"numbered" ] + | "output_unsatisfied" | "split_objects" [ "_numbered" ] | "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} + 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} - \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}