X-Git-Url: http://gitweb.hachti.de/?a=blobdiff_plain;f=pc-tools%2Fldc2%2Fdoc%2Freq_spec.tex;fp=pc-tools%2Fldc2%2Fdoc%2Freq_spec.tex;h=38ec9c9d48e24960e18701b7b324b19ef8f4ab10;hb=c7358c239dea2dd30ab2a3f586efa2e4382c3c6c;hp=4559aadbfc5bc0d5fe1251b507fd436e6ad8729b;hpb=040533c5d1dece81aaaf2194b5ea24d908bea481;p=h316.git diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex index 4559aad..38ec9c9 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,111 @@ 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. +} + %******************************************************************************* \newpage \subsection{Program configuration} @@ -130,7 +273,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} } @@ -255,11 +400,11 @@ 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\_*} inhibits tape information output (\req{da001}). + \item \emph{help} inhibits all other actions. \end{itemize} } @@ -269,111 +414,7 @@ ShortSwitch = "-" SwShort ; \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} -} - -%******************************************************************************* -\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 + \item Normal Text is output to standard output. + \item Error messages are output to standard error. \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. -} -