[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.
}

%*******************************************************************************        
\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}).\\
        \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" ;
          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" ;
     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" ;
   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\_*} inhibits 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.
        \item Normal Text is output to standard output.
        \item Error messages are output to standard error.
        \end{itemize}
}