From 290011d228d5b323d61c77542a8761dfa69b034b Mon Sep 17 00:00:00 2001 From: hachti Date: Wed, 29 Nov 2006 01:43:40 +0000 Subject: [PATCH] *** empty log message *** --- pc-tools/ldc2/doc/body.tex | 3 +- pc-tools/ldc2/doc/defs.tex | 14 ++ pc-tools/ldc2/doc/main.tex | 2 +- pc-tools/ldc2/doc/req_spec.tex | 360 ++++++++++++++++++++++++++++++++- 4 files changed, 375 insertions(+), 4 deletions(-) create mode 100644 pc-tools/ldc2/doc/defs.tex diff --git a/pc-tools/ldc2/doc/body.tex b/pc-tools/ldc2/doc/body.tex index e72446c..f740f7f 100644 --- a/pc-tools/ldc2/doc/body.tex +++ b/pc-tools/ldc2/doc/body.tex @@ -1,5 +1,4 @@ -\newcommand{\pname}{ \emph{LDC2} } - +\input defs \input intro \newpage \input req_spec diff --git a/pc-tools/ldc2/doc/defs.tex b/pc-tools/ldc2/doc/defs.tex new file mode 100644 index 0000000..1cf3e74 --- /dev/null +++ b/pc-tools/ldc2/doc/defs.tex @@ -0,0 +1,14 @@ +% own commands +\newcommand{\pname}{\emph{LDC2} } + +\newcommand{\req}[1]{/#1/} + +%\newcommand{\rd2}[2]{ +% \subsubsection*{\req{#1}} +% #2 +%} + +\newcommand{\rd}[3]{ + \subsubsection*{\req{#1} -- #2 } + #3 +} diff --git a/pc-tools/ldc2/doc/main.tex b/pc-tools/ldc2/doc/main.tex index e39d480..d97e374 100644 --- a/pc-tools/ldc2/doc/main.tex +++ b/pc-tools/ldc2/doc/main.tex @@ -2,6 +2,7 @@ \usepackage{a4wide} \usepackage[latin1]{inputenc} % \usepackage[german]{babel} +\usepackage{float} \usepackage{graphics} \begin{document} \bibliographystyle{unsrt} @@ -22,5 +23,4 @@ % plain für unten, empty für leer \input{body} - \end{document} \ No newline at end of file diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex index b387a01..7ca7c1b 100644 --- a/pc-tools/ldc2/doc/req_spec.tex +++ b/pc-tools/ldc2/doc/req_spec.tex @@ -1,2 +1,360 @@ \section{Requirements Specification} -What do we require? \ No newline at end of file + +%******************************************************************************* +\subsection{Data input processing} + +\rd{inp001}{Data source select}{ + The tape data in Honeywell silent 4/6/6 code + \cite{ser16:progref:bformats} shall be read in from standard input or + from an input file. +} + +%******************************************************************************* +\subsection{Data integrity checks} + +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 + detecting unexpected end of file while reading in the block. +} + +\rd{chk002}{Block checksum check}{ + Every data block's checksum shall be calculated and checked according + to \cite{ser16:progref:bformats}. +} + +\rd{chk003}{Block type check}{ + Every data block contains its blocktype encoded in a specified location. + It shall be checked that each data block's type field contains one of + the type codes described in \cite{ser16:progref:bformats}. +} + +\rd{chk004}{Object integrity check}{ + Every object on the tape (i.e. the output of one DAP-16 or FORTRAN IV + compiler run) consists of multiple data blocks. + According to \cite{ser16:progref:bformats}, the last block of each + object must be of one of the end block types.\\ + It shall be checked if the last data block read before end of input or + 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{Data analysis} + +\rd{da001}{List tape contents}{ + Output a list containing a human-readable fixed-format description + of all blocks contained in the input data.\\ + The output line format shall be unified for all block types. +} + +\rd{da002}{List exported symbols}{ + Output a list of all exported symbols. +} + +\rd{da003}{List called symbols}{ + Output a list of all called symbols. +} + +\rd{da004}{List unsatisfied dependencies}{ + Output a list of all unsatisfied dependencies i.e. + all called symbols that appear in the output of \req{dp003} but + not in the output of \req{dp002}. +} + +\rd{da005}{Tape information output}{ + It shall be possible to output a line containing at least + the following information about a tape image: + \begin{itemize} + \item Number of bytes read from data source + \item Number of blocks read in + \end{itemize} +} + +\rd{da006}{Text output}{ + Text from \req{da001},\req{da002},\req{da003}, \req{da004}, + and \req{da005} is output to standard output or to a file. +} + +%******************************************************************************* +\subsection{Data processing} + +\rd{dp001}{Split into object files}{ + The tape data shall be divided into self-contained object files.\\ + The generated file names are derived from the first symbol name + defined in the current object.\\ + Example: If an object exports the symbols SONNE, MOND + and STERNE, the resulting file name will be SONNE.\\ + EOT (end of tape) blocks shall not be output in this mode of operation. +} + +\rd{dp002}{Split into numbered object files}{ + Similar to \req{dp006}, but the object file names are prepended with + a zero-padded three digit number and EOT blocks are not suppressed. +} + +%******************************************************************************* +\subsection{Additional features} + +\rd{h001}{Print help message}{ + A help message shall be output to standard error. +} + +%******************************************************************************* +\subsection{Program configuration} + +\rd{cfg001}{Configuration process}{ + 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 + file shall be parsed. + \item Configuration file according to command line parameter:\\ + If the command line parameter specifying a configuration + file is found, + the specified configuration file is parsed.\\ + Any values in this 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 + values from previously read configuration files. + \end{enumerate} +} + +\rd{cfg002}{Parameter types}{ + 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. + \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} +} + +\rd{cfg003}{Switch parameters}{ + The following switch parameters shall be accepted: + \begin{table}[H]\begin{center} + \begin{tabular}{|r|p{2.5em}|l|} + \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}.)\\ + \hline + \end{tabular}\end{center} + \caption{Configuration switches} + \end{table} +} + +\rd{cfg004}{String parameters}{ + The following string parameters shall be accepted: + \begin{table}[H]\begin{center} + \begin{tabular}{|r|p{2.5em}|l|} + \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})\\ + \hline + \end{tabular}\end{center} + \caption{Configuration strings} + \end{table} + +} + +\rd{cfg005}{Configuration file syntax}{ + The configuration file must comply two the following grammar, given in EBNF: +} + \begin{verbatim} +ConfigurationFile = { ConfigurationLine "" } ; +ConfigurationLine = SwitchLine | StringLine | CommentLine ; + SwitchLine = WSpace SwLong WSpace "=" BoolValue ; + StringLine = WSpace StrLong WSpace "=" String ; + CommentLine = WSpace [ "#" String ] ; + WSpace = { " " } ; + SwLong = "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" ; + StrLong = "out_file" | "in_file" ; + BoolValue = TrueStr | FalseStr ; + String = { ? Every character except newline ?} ; + TrueStr = "yes" | "1" | "true" ; + FalseStr = | "no" | "0" | "false" ; + \end{verbatim}; + +\rd{cfg006}{Commandline syntax}{ + The command line must comply to the following grammar, given in EBNF: +} +\begin{verbatim} +CommandLine = ProgramName Arguments ; +ProgramName = String ; + Arguments = { " " } { " " Argument } [ " " InfileName ] ; + Argument = { Switch | Parameter } + InfileName = String ; + Switch = ShortSwitch | LongSwitch ; + Parameter = ShortParam | LongParam ; + String = { ? Every character except newline ? } ; +ShortSwitch = "-" SwShort ; + 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" + | "output_unsatisfied" | "split_objects" [ _"numbered" ] + | "ignore_block_errors" | "ignore_checksum_errors + | "pause_on_checksum_error" + | "ignore_unknown_block_errors" + | "ignore_object_integrity" ; + StrShort = "o"; + StrLong = "out_file" ; +\end{verbatim} + +\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. + \end{itemize} +} + +\rd{cfg008}{Default behaviour}{ + \begin{itemize} + \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. + \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. +} + -- 2.32.0