X-Git-Url: http://gitweb.hachti.de/?a=blobdiff_plain;f=pc-tools%2Fldc2%2Fdoc%2Freq_spec.tex;h=fb2cf5c641e6f4e50af24cec1dda981324b6a49a;hb=874a2bd89fd65e5a1763d88c218f066a424e0d04;hp=b387a01626e20d5a6907c2fef86749cfe2e63f1f;hpb=70896a91a15781c49bce37b0101466c83c51dd24;p=h316.git

diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex
index b387a01..fb2cf5c 100644
--- a/pc-tools/ldc2/doc/req_spec.tex
+++ b/pc-tools/ldc2/doc/req_spec.tex
@@ -1,2 +1,428 @@
-\section{Requirements Specification}
-What do we require?
\ No newline at end of file
+\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}
+
+\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 integrity check}{
+	Every data block's integrity 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{Additional features}
+
+\rd{h001}{Print help message}{
+	A help message is output to standard error.
+}
+
+%*******************************************************************************
+\newpage
+\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.
+}
+
+%*******************************************************************************
+\newpage
+\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.
+}
+
+
+%*******************************************************************************
+\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}
+
+\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. 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}
+}
+
+\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}
+}
+
+\newpage
+\rd{cfg003}{Switch parameters}{
+	The following switch parameters shall be accepted:
+	\begin{table}[H]\begin{center}
+	\begin{tabular}{|r|p{2.5em}|p{23em}|}
+	\hline
+	\bf Long Form & \bf Short form & \bf Description\\
+	\hline
+ 	help                       & h & Show help message (\req{h001})\\
+	output\_info		   & a & Output data info (\req{da005})	.\\
+	output\_called             & c & Output a list of called symbols 
+						(\req{da003}).\\ 
+	output\_exported           & e & Output a list of exported symbols 
+						(\req{da002}).\\
+	output\_unsatisfied        & u & Output a list of unsatisfied 
+						dependencies (\req{da004}).\\
+	split\_objects             & s & Split into object files 
+						(\req{dp001}).\\
+	split\_objects\_numbered   & S & Split into numbered object files 
+						(\req{dp002}).\\
+	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}).\\
+	ignore\_unknown\_block\_errors    & n  & Ignore errors causes by 
+						datablocks of 	unknown type
+						 (\req{err001}\req{chk003}).\\
+	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}
+	\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}	
+
+}
+\newpage
+\rd{cfg005}{Configuration file syntax}{
+	The configuration file must comply two the following grammar, given in EBNF:
+}
+	\begin{verbatim}
+ConfigurationFile = { ConfigurationLine "<EOL>" } ;
+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"
+                    | "quiet" ;
+          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}{Command Line 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 = "h" | "a" | "c" | "e" | "u" | "s" | "S"
+              | "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" 
+              | "quiet" ;
+   StrShort = "o" ;
+    StrLong = "out_file" ;
+\end{verbatim}
+
+\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 
+	tape information output (\req{da001}).
+	\item \emph{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 to standard output.
+	\end{itemize}
+}