X-Git-Url: http://gitweb.hachti.de/?a=blobdiff_plain;f=pc-tools%2Fldc2%2Fdoc%2Freq_spec.tex;h=fb2cf5c641e6f4e50af24cec1dda981324b6a49a;hb=874a2bd89fd65e5a1763d88c218f066a424e0d04;hp=4559aadbfc5bc0d5fe1251b507fd436e6ad8729b;hpb=ad324d29d885b9af1608a6e9c1f978bdcd202eb7;p=h316.git diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex index 4559aad..fb2cf5c 100644 --- 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 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} @@ -110,6 +148,116 @@ found in \cite{ser16:progref:bformats}. a zero-padded three digit number and EOT blocks are not suppressed. } + +%******************************************************************************* +\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[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} @@ -130,7 +278,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 - 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} } @@ -178,6 +328,8 @@ found in \cite{ser16:progref:bformats}. 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} @@ -215,7 +367,8 @@ ConfigurationLine = SwitchLine | StringLine | CommentLine ; | "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 ?} ; @@ -240,14 +393,15 @@ ShortSwitch = "-" SwShort ; ShortParam = "-" StrShort String ; LongParam = "--" StrLong "=" String ; SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" - | "b" | "k" | "p" | "n" | "g" ; + | "b" | "k" | "p" | "n" | "g" | "q"; SwLong = "help" | "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" ; + | "ignore_object_integrity" + | "quiet" ; StrShort = "o" ; StrLong = "out_file" ; \end{verbatim} @@ -255,11 +409,12 @@ ShortSwitch = "-" SwShort ; \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 + \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 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} } @@ -268,112 +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 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} } - -%******************************************************************************* -\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. -} -