c7358c23 |
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}. |
de6b6757 |
8 | \item The program must be able to list a tape image's contents. |
c7358c23 |
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:\\ |
de6b6757 |
17 | A paper tape reader connected to the computer's serial port could be motion-controlled |
c7358c23 |
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} |
290011d2 |
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 | |
ad324d29 |
56 | \rd{chk001}{Block integrity check}{ |
57 | Every data block's integrity shall be checked by the means of |
290011d2 |
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 | |
290011d2 |
81 | |
82 | %******************************************************************************* |
ad324d29 |
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 |
290011d2 |
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 | } |
de6b6757 |
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} |
290011d2 |
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 | %******************************************************************************* |
ad324d29 |
146 | \newpage |
290011d2 |
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 | |
de6b6757 |
163 | \rd{dp003}{Split into numbered blocks}{ |
164 | The whole tape is split into one named and numbered file for each block. |
165 | } |
166 | |
c7358c23 |
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}{ |
de6b6757 |
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.\\ |
c7358c23 |
187 | The following distinguished error types shall exist: |
188 | \begin{itemize} |
189 | \item Input/output error:\\ |
de6b6757 |
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. |
c7358c23 |
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}{ |
de6b6757 |
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] |
c7358c23 |
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\\ |
de6b6757 |
237 | Success with warnings & 99 \\ |
c7358c23 |
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}{ |
de6b6757 |
247 | Every warning or error case shall cause an appropriate error respective |
248 | warning message.\\ |
c7358c23 |
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 | |
874a2bd8 |
283 | \rd{err006}{Informational messages}{ |
284 | Any informational messages go to standard error. |
285 | } |
286 | |
287 | |
290011d2 |
288 | %******************************************************************************* |
ad324d29 |
289 | \newpage |
290011d2 |
290 | \subsection{Program configuration} |
291 | |
292 | \rd{cfg001}{Configuration process}{ |
ad324d29 |
293 | The following sequence shall be used to acquire the working |
294 | configuration: |
290011d2 |
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 |
ad324d29 |
304 | override values found in the previously read |
305 | configuration file. |
290011d2 |
306 | \item Configuration parameters passed via the command line:\\ |
307 | Parameters passed on the command line will override |
c7358c23 |
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. |
290011d2 |
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:\\ |
ad324d29 |
318 | A switch is a binary value which can have the value true or |
319 | false. |
290011d2 |
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 | |
ad324d29 |
326 | \newpage |
290011d2 |
327 | \rd{cfg003}{Switch parameters}{ |
328 | The following switch parameters shall be accepted: |
329 | \begin{table}[H]\begin{center} |
ad324d29 |
330 | \begin{tabular}{|r|p{2.5em}|p{23em}|} |
290011d2 |
331 | \hline |
332 | \bf Long Form & \bf Short form & \bf Description\\ |
333 | \hline |
334 | help & h & Show help message (\req{h001})\\ |
ad324d29 |
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}).\\ |
de6b6757 |
346 | split\_blocks & B & Split tape into named and numbered block |
347 | files (\req{dp003}).\\ |
ad324d29 |
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}).\\ |
de6b6757 |
352 | % pause\_on\_checksum\_error & p & Wait for user input on checksum error |
353 | % (\req{chk005}).\\ |
ad324d29 |
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}).\\ |
874a2bd8 |
360 | quiet & q & Suppress all non-critical messages |
d65ad4d7 |
361 | (warnings, informational text)\\ |
290011d2 |
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 |
ad324d29 |
375 | in\_file & i & Set input file (\req{inp001}). \\ |
376 | out\_file & o & Set output file for text output(\req{dp008}).\\ |
290011d2 |
377 | \hline |
378 | \end{tabular}\end{center} |
379 | \caption{Configuration strings} |
380 | \end{table} |
381 | |
382 | } |
ad324d29 |
383 | \newpage |
290011d2 |
384 | \rd{cfg005}{Configuration file syntax}{ |
385 | The configuration file must comply two the following grammar, given in EBNF: |
386 | } |
de6b6757 |
387 | |
388 | % | "pause_on_checksum_error" |
389 | |
290011d2 |
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" |
de6b6757 |
398 | | "output_unsatisfied" | "split_objects" [ "_numbered" ] |
399 | | "split_blocks" |
290011d2 |
400 | | "ignore_block_errors" | "ignore_checksum_errors |
290011d2 |
401 | | "ignore_unknown_block_errors" |
874a2bd8 |
402 | | "ignore_object_integrity" |
403 | | "quiet" ; |
290011d2 |
404 | StrLong = "out_file" | "in_file" ; |
405 | BoolValue = TrueStr | FalseStr ; |
406 | String = { ? Every character except newline ?} ; |
407 | TrueStr = "yes" | "1" | "true" ; |
de6b6757 |
408 | FalseStr = "no" | "0" | "false" ; |
ad324d29 |
409 | \end{verbatim} |
290011d2 |
410 | |
ad324d29 |
411 | \rd{cfg006}{Command Line syntax}{ |
290011d2 |
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 ; |
de6b6757 |
427 | SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" | "B" |
874a2bd8 |
428 | | "b" | "k" | "p" | "n" | "g" | "q"; |
ad324d29 |
429 | SwLong = "help" |
430 | | "output_info" | "ouput_called" | "output_exported" |
de6b6757 |
431 | | "output_unsatisfied" | "split_objects" [ "_numbered" ] |
ad324d29 |
432 | | "ignore_block_errors" | "ignore_checksum_errors" |
290011d2 |
433 | | "ignore_unknown_block_errors" |
874a2bd8 |
434 | | "ignore_object_integrity" |
435 | | "quiet" ; |
ad324d29 |
436 | StrShort = "o" ; |
290011d2 |
437 | StrLong = "out_file" ; |
438 | \end{verbatim} |
de6b6757 |
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" |
290011d2 |
444 | |
ad324d29 |
445 | \newpage |
290011d2 |
446 | \rd{cfg007}{Configuration implications}{ |
447 | \begin{itemize} |
de6b6757 |
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 |
874a2bd8 |
452 | tape information output (\req{da001}). |
c7358c23 |
453 | \item \emph{help} inhibits all other actions. |
290011d2 |
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. |
874a2bd8 |
462 | \item Tape information according to \req{da001} is output to standard output. |
290011d2 |
463 | \end{itemize} |
464 | } |