pc-tools/ldc2/doc/req_spec.tex

   1 \section{General Requirements}
   2
   3 \subsection{Must Criteria}
   4 \begin{itemize}
   5 \item The program shall run on any computer running GNU/Linux.
   6 \item It has no graphical user interface but a help option and command line error reporting.
   7 \item The program shall support and check all block types according to \cite{ser16:progref:bformats}.
   8 \item The program must be able to list a tape image's contents.
   9 \item The program shall be capable of splitting tape images into single object files.
  10 \item The program's structure must be modular and easily extendable.
  11 \end{itemize}
  12
  13 \subsection{Optional features}
  14 \begin{itemize}
  15 \item Possibility to split a tape image into single data block files.
  16 \item Software handshake paper tape reader control:\\
  17 A paper tape reader connected to the computer's serial port could be motion-controlled
  18 by use of XON and XOFF characters. This is useful when error breaks for tape inspection are
  19 enabled and the paper tape device does not support RTS/CTS hardware handshake.
  20 \item Full POSIX.1, 2004 edition, compliance.\\
  21         This enables the program to be usable under many different UNIX style operating
  22         systems.
  23 \end{itemize}
  24
  25 \subsection{Further additions explicitely beyond the scope of this project}
  26 \begin{itemize}
  27 \item Detailed data block analysis:
  28         \begin{itemize}
  29         \item Linking objects into a virtual memory representation.
  30         \item Generating disassembly listings of block contents
  31         \end{itemize}
  32
  33 \item    Support for self loading system tapes generated by \emph{PAL-AP} (see \cite{ser16:opmanual}).
  34
  35 \end{itemize}
  36
  37 %*******************************************************************************
  38 \newpage
  39 \section{Detailed Functional Specification}
  40
  41 %*******************************************************************************
  42 \subsection{Data input processing}
  43
  44 \rd{inp001}{Data source select}{
  45         The tape data in Honeywell silent 4/6/6 code
  46         \cite{ser16:progref:bformats} shall be read in from standard input or
  47         from an input file.
  48 }
  49
  50 %*******************************************************************************
  51 \subsection{Data integrity checks}
  52
  53 The tape data shall be checked against the Honeywell tape block specification
  54 found in \cite{ser16:progref:bformats}.
  55
  56 \rd{chk001}{Block integrity check}{
  57         Every data block's integrity shall be checked by the means of
  58         detecting unexpected end of file while reading in the block.
  59 }
  60
  61 \rd{chk002}{Block checksum check}{
  62         Every data block's checksum shall be calculated and checked according
  63         to \cite{ser16:progref:bformats}.
  64 }
  65
  66 \rd{chk003}{Block type check}{
  67         Every data block contains its blocktype encoded in a specified location.
  68         It shall be checked that each data block's type field contains one of
  69         the type codes described in \cite{ser16:progref:bformats}.
  70 }
  71
  72 \rd{chk004}{Object integrity check}{
  73         Every object on the tape (i.e. the output of one DAP-16 or FORTRAN IV
  74         compiler run) consists of multiple data blocks.
  75         According to \cite{ser16:progref:bformats}, the last block of each
  76         object must be of one of the end block types.\\
  77         It shall be checked if the last data block read before end of input or
  78         an end of tape mark is an appropriate end block.
  79 }
  80
  81
  82 %*******************************************************************************
  83 \subsection{Additional features}
  84
  85 \rd{h001}{Print help message}{
  86         A help message is output to standard error.
  87 }
  88
  89 %*******************************************************************************
  90 \newpage
  91 \subsection{Data analysis}
  92
  93 \rd{da001}{List tape contents}{
  94         Output a list containing a human-readable fixed-format description
  95         of all blocks contained in the input data.\\
  96         The output line format shall be unified for all block types.
  97 }
  98 \vspace{0.5em}
  99 \par
 100 Here is an example output for the object \verb|O$PB|: \begin{verbatim}
 101 O$PB       (0-0)     Subprogram Name
 102 O$PS       (0-0)         "        "
 103 O$PLDR     (0-0)         "        "
 104            (0-24)    Switch to relocatable mode
 105            (0-4)     Data
 106            (0-4)     Data
 107 O$PB       (0-50)    Subprogram Entry Point Definition
 108            (0-4)     Data
 109            (0-4)     Data
 110            (0-4)     Data
 111 O$PLDR     (0-50)    Subprogram Entry Point Definition
 112            (0-4)     Data
 113            (0-4)     Data
 114            (0-14)    End
 115 \end{verbatim}
 116
 117 \rd{da002}{List exported symbols}{
 118         Output a list of all exported symbols.
 119 }
 120
 121 \rd{da003}{List called symbols}{
 122         Output a list of all called symbols.
 123 }
 124
 125 \rd{da004}{List unsatisfied dependencies}{
 126         Output a list of all unsatisfied dependencies i.e.
 127         all called symbols that appear in the output of \req{dp003} but
 128         not in the output of \req{dp002}.
 129 }
 130
 131 \rd{da005}{Tape information output}{
 132         It shall be possible to output a line containing at least
 133         the following information about a tape image:
 134         \begin{itemize}
 135         \item Number of bytes read from data source
 136         \item Number of blocks read in
 137         \end{itemize}
 138 }
 139
 140 \rd{da006}{Text output}{
 141         Text from \req{da001},\req{da002},\req{da003}, \req{da004},
 142          and \req{da005} is output to standard output or to a file.
 143 }
 144
 145 %*******************************************************************************
 146 \newpage
 147 \subsection{Data processing}
 148
 149 \rd{dp001}{Split into object files}{
 150         The tape data shall be divided into self-contained object files.\\
 151         The generated file names are derived from the first symbol name
 152         defined in the current object.\\
 153         Example: If an object exports the symbols SONNE, MOND
 154         and STERNE, the resulting file name will be SONNE.\\
 155         EOT (end of tape) blocks shall not be output in this mode of operation.
 156 }
 157
 158 \rd{dp002}{Split into numbered object files}{
 159         Similar to \req{dp006}, but the object file names are prepended with
 160         a zero-padded three digit number and EOT blocks are not suppressed.
 161 }
 162
 163 \rd{dp003}{Split into numbered blocks}{
 164         The whole tape is split into one named and numbered file for each block.
 165 }
 166
 167
 168 %*******************************************************************************
 169 \newpage
 170 \subsection{Error handling}
 171
 172
 173 \newcommand{\esup}{
 174         This error shall lead to an error message and immediate program
 175         termination or a warning message and program continuation.
 176 }
 177
 178 \newcommand{\enosup}{
 179         This error shall always lead to an error message and immediate
 180         program termination.
 181 }
 182
 183 \rd{err001}{Error types}{
 184         The program shall react to several error conditions. Some error
 185         conditions can be turned into warnings by program configuration,
 186         see \req{cfg003} and \req{cfg004} for details.\\
 187         The following distinguished error types shall exist:
 188         \begin{itemize}
 189         \item Input/output error:\\
 190                 Error occuring during read from the input file descriptor
 191                 or during write to an output file.\\
 192                 No recovery from this error is possible.
 193                 \enosup
 194         \item Block integrity error:\\
 195                 Caused by failed check according to \req{chk001}.\\
 196                 \esup
 197         \item Checksum error:\\
 198                 Caused by failed check according to \req{chk002}.\\
 199                 \esup
 200         \item Unknown block type error:\\
 201                 Caused by failed check according to \req{chk003}.\\
 202                 \esup
 203         \item Object integrity error:\\
 204                 Caused by failed check according to \req{chk004}.\\
 205                 \esup
 206         \item Usage error:\\
 207                 Error caused by errors in the program configuration i.e. wrong
 208                 parameters or impossible combinations of parameters.\\
 209                 \enosup \\
 210                 Additionally, the help (\req{h001}) message is output.
 211         \item   Internal program error:\\
 212                 Error caused by internal program problems.\\
 213                 This error should never occur.\\
 214                 \enosup
 215         \end{itemize}
 216 }
 217
 218 \rd{err002}{Program exit codes}{
 219         The application shall return several different exir codes to the
 220         execution environment (i.e. the shell). On occurrence of any error,
 221         the program shall terminate with the appropriate exit code.\\
 222         Program runs with warnings shall return a special exit code.
 223         \begin{table}[H]
 224         \begin{center}
 225         \begin{tabular}{|r|c|}
 226                 \hline
 227                 \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\
 228                 \hline
 229                 Successfull program completion & 0 \\
 230                 File open error & 1\\
 231                 Input/output error & 2\\
 232                 Block integrity error & 3\\
 233                 Checksum error & 4\\
 234                 Unknown block type error & 5\\
 235                 Object integrity error & 6\\
 236                 Usage error & 7\\
 237                 Success with warnings & 99 \\
 238                 Internal program error & 100 \\
 239                 \hline
 240         \end{tabular}
 241         \caption[Program Exit codes]{Exit codes}
 242         \end{center}
 243         \end{table}
 244 }
 245
 246 \rd{err003}{Error and warning messages}{
 247         Every warning or error case shall cause an appropriate error respective
 248         warning message.\\
 249         Error messages shall consinst of ''Error:'' and the error reason.\\
 250         Warning messages shall consist of ''Warning:'' and a descriptive
 251         text.\\
 252         The following texts shall be used to form error and warning messages:
 253         \begin{table}[H]
 254         \begin{center}
 255         \begin{tabular}{|l|l|}
 256         \hline
 257         \bf Error condition & \bf Descriptive text\\ \hline
 258         File open error & Could not open $<$filename$>$ for reading/writing!\\
 259         Input error     &     Could not read from $<$filename$>$!\\
 260         Output error    &    Could not write to $<$filename$>$!\\
 261         Block integrity error & Block integrity check failed!\\
 262         Checksum error        & Block checksum wrong!\\
 263         Unknown block type    & Unknown block type!\\
 264         Object integrity      & Object integrity check failed!\\
 265         Usage error           & $<$Specific message describing the problem$>$\\
 266         \hline
 267         \end{tabular}
 268         \end{center}
 269         \caption[Error and warning messages]{Messages}
 270         \end{table}
 271 }
 272
 273 \rd{err004}{Error message output}{
 274         Any error messages shall be output to standard error.\\
 275         There shall be no way to suppress error messages.
 276 }
 277
 278 \rd{err005}{Warning message output}{
 279         Any warning messages shall be output to standard error.\\
 280         There shall be a possibility to suppress warning messages.
 281 }
 282
 283 \rd{err006}{Informational messages}{
 284         Any informational messages go to standard error.
 285 }
 286
 287
 288 %*******************************************************************************
 289 \newpage
 290 \subsection{Program configuration}
 291
 292 \rd{cfg001}{Configuration process}{
 293         The following sequence shall be used to acquire the working
 294         configuration:
 295         \begin{enumerate}
 296                 \item Configuration file according to environment variable:\\
 297                         If the environment variable LDC\_CONFIG is set, that
 298                         file shall be parsed.
 299                 \item Configuration file according to command line parameter:\\
 300                         If the command line parameter specifying a configuration
 301                         file is found,
 302                         the specified configuration file is parsed.\\
 303                         Any values in this configuration file
 304                         override values found in the previously read
 305                         configuration file.
 306                 \item Configuration parameters passed via the command line:\\
 307                         Parameters passed on the command line will override
 308                         values from previously read configuration files. If the command line
 309                         mentiones a configuration file to read, this file is processed before
 310                         the other parameters supplied on the command line.
 311         \end{enumerate}
 312 }
 313
 314 \rd{cfg002}{Parameter types}{
 315         The program shall accept two types of parameters:
 316         \begin{itemize}
 317         \item Switches:\\
 318                 A switch is a binary value which can have the value true or
 319                 false.
 320         \item Strings:\\
 321                 A string parameter is a parameter requiring a string value.\\
 322                 A typical use would be a file name for input or output.
 323         \end{itemize}
 324 }
 325
 326 \newpage
 327 \rd{cfg003}{Switch parameters}{
 328         The following switch parameters shall be accepted:
 329         \begin{table}[H]\begin{center}
 330         \begin{tabular}{|r|p{2.5em}|p{23em}|}
 331         \hline
 332         \bf Long Form & \bf Short form & \bf Description\\
 333         \hline
 334         help                       & h & Show help message (\req{h001})\\
 335         output\_info               & a & Output data info (\req{da005}) .\\
 336         output\_called             & c & Output a list of called symbols
 337                                                 (\req{da003}).\\
 338         output\_exported           & e & Output a list of exported symbols
 339                                                 (\req{da002}).\\
 340         output\_unsatisfied        & u & Output a list of unsatisfied
 341                                                 dependencies (\req{da004}).\\
 342         split\_objects             & s & Split into object files
 343                                                 (\req{dp001}).\\
 344         split\_objects\_numbered   & S & Split into numbered object files
 345                                                 (\req{dp002}).\\
 346         split\_blocks               & B & Split tape into named and numbered block
 347                                                 files (\req{dp003}).\\
 348         ignore\_block\_errors      & b & Ignore block integrity errors
 349                                                 (\req{err001},\req{chk001}).\\
 350         ignore\_checksum\_errors   & k & Ignore Checksum errors
 351                                                 (\req{err001}\req{chk002}).\\
 352 %       pause\_on\_checksum\_error & p & Wait for user input on checksum error
 353 %                                               (\req{chk005}).\\
 354         ignore\_unknown\_block\_errors    & n  & Ignore errors causes by
 355                                                 datablocks of   unknown type
 356                                                  (\req{err001}\req{chk003}).\\
 357         ignore\_object\_integrity\_errors & g & Ignore errors caused by objects
 358                                                 without proper end block
 359                                                 (\req{err001}\req{chk004}).\\
 360         quiet                             & q & Suppress all non-critical  messages
 361                                                  to standard error (warnings, informatianal)\\
 362         \hline
 363         \end{tabular}\end{center}
 364         \caption{Configuration switches}
 365         \end{table}
 366 }
 367
 368 \rd{cfg004}{String parameters}{
 369         The following string parameters shall be accepted:
 370         \begin{table}[H]\begin{center}
 371         \begin{tabular}{|r|p{2.5em}|l|}
 372         \hline
 373         \bf Long Form & \bf Short form & \bf Description\\
 374         \hline
 375         in\_file                   & i & Set input file (\req{inp001}). \\
 376         out\_file                  & o & Set output file for text output(\req{dp008}).\\
 377         \hline
 378         \end{tabular}\end{center}
 379         \caption{Configuration strings}
 380         \end{table}
 381
 382 }
 383 \newpage
 384 \rd{cfg005}{Configuration file syntax}{
 385         The configuration file must comply two the following grammar, given in EBNF:
 386 }
 387
 388 %                   | "pause_on_checksum_error"
 389
 390         \begin{verbatim}
 391 ConfigurationFile = { ConfigurationLine "<EOL>" } ;
 392 ConfigurationLine = SwitchLine | StringLine | CommentLine ;
 393        SwitchLine = WSpace SwLong  WSpace "=" BoolValue ;
 394        StringLine = WSpace StrLong WSpace "=" String ;
 395       CommentLine = WSpace [ "#" String ] ;
 396            WSpace = { " " } ;
 397            SwLong = "output_info" | "ouput_called" | "output_exported"
 398                     | "output_unsatisfied" | "split_objects" [ "_numbered" ]
 399                     | "split_blocks"
 400                     | "ignore_block_errors" | "ignore_checksum_errors
 401                     | "ignore_unknown_block_errors"
 402                     | "ignore_object_integrity"
 403                     | "quiet" ;
 404           StrLong = "out_file" | "in_file" ;
 405         BoolValue = TrueStr | FalseStr ;
 406            String = { ? Every character except newline ?} ;
 407           TrueStr = "yes" | "1" | "true" ;
 408          FalseStr = "no" | "0" | "false" ;
 409         \end{verbatim}
 410
 411 \rd{cfg006}{Command Line syntax}{
 412         The command line must comply to the following grammar, given in EBNF:
 413 }
 414 \begin{verbatim}
 415 CommandLine = ProgramName Arguments ;
 416 ProgramName = String ;
 417   Arguments = { " " } { " " Argument } [ " " InfileName ] ;
 418    Argument = { Switch | Parameter }
 419  InfileName = String ;
 420      Switch = ShortSwitch | LongSwitch ;
 421   Parameter = ShortParam | LongParam ;
 422      String = { ? Every character except newline ? } ;
 423 ShortSwitch = "-" SwShort ;
 424  LongSwitch = "--" SwLong [ "=" BoolValue ] ;
 425  ShortParam = "-" StrShort String ;
 426   LongParam = "--" StrLong "=" String ;
 427     SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" | "B"
 428               | "b" | "k" | "p" | "n" | "g" | "q";
 429      SwLong = "help"
 430               | "output_info" | "ouput_called" | "output_exported"
 431               | "output_unsatisfied" | "split_objects" [ "_numbered" ]
 432               | "ignore_block_errors" | "ignore_checksum_errors"
 433               | "ignore_unknown_block_errors"
 434               | "ignore_object_integrity"
 435               | "quiet" ;
 436    StrShort = "o" ;
 437     StrLong = "out_file" ;
 438 \end{verbatim}
 439         Some command line examples:\\
 440         \verb|ldc2 -ve --output-file=out.dat in.dat|\\
 441         \verb|ldc2 -kb test.obj|\\
 442
 443 %             | "pause_on_checksum_error"
 444
 445 \newpage
 446 \rd{cfg007}{Configuration implications}{
 447         \begin{itemize}
 448 %       \item \emph{pause\_on\_checksum\_error} implies \emph{ignore\_checksum\_errors}.
 449 %       \item \emph{pause\_on\_checksum\_error} is completely ignored when input
 450 %       is read from standard input.
 451         \item \emph{output\_*} inhibit
 452         tape information output (\req{da001}).
 453         \item \emph{help} inhibits all other actions.
 454         \end{itemize}
 455 }
 456
 457 \rd{cfg008}{Default behaviour}{
 458         \begin{itemize}
 459         \item Data is read from standard input.
 460         \item All error conditions result in immediate program termination
 461                 and an error message.
 462         \item Tape information according to \req{da001} is output to standard output.
 463         \end{itemize}
 464 }