*** empty log message ***

[h316.git] / pc-tools / ldc2 / doc / req_spec.tex

\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}
}