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}. |
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 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} |
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 | |
81 | \rd{chk005}{Interactive checksum error handling}{ |
82 | The program shall be configurable to pause block processing on |
83 | detection of a checksum error (\req{chk002}) and resume processing after |
84 | user intervention.\\ |
85 | This feature is incompatible with data input from standard input. |
86 | } |
87 | |
88 | %******************************************************************************* |
ad324d29 |
89 | \subsection{Additional features} |
90 | |
91 | \rd{h001}{Print help message}{ |
92 | A help message is output to standard error. |
93 | } |
94 | |
95 | %******************************************************************************* |
96 | \newpage |
290011d2 |
97 | \subsection{Data analysis} |
98 | |
99 | \rd{da001}{List tape contents}{ |
100 | Output a list containing a human-readable fixed-format description |
101 | of all blocks contained in the input data.\\ |
102 | The output line format shall be unified for all block types. |
103 | } |
104 | |
105 | \rd{da002}{List exported symbols}{ |
106 | Output a list of all exported symbols. |
107 | } |
108 | |
109 | \rd{da003}{List called symbols}{ |
110 | Output a list of all called symbols. |
111 | } |
112 | |
113 | \rd{da004}{List unsatisfied dependencies}{ |
114 | Output a list of all unsatisfied dependencies i.e. |
115 | all called symbols that appear in the output of \req{dp003} but |
116 | not in the output of \req{dp002}. |
117 | } |
118 | |
119 | \rd{da005}{Tape information output}{ |
120 | It shall be possible to output a line containing at least |
121 | the following information about a tape image: |
122 | \begin{itemize} |
123 | \item Number of bytes read from data source |
124 | \item Number of blocks read in |
125 | \end{itemize} |
126 | } |
127 | |
128 | \rd{da006}{Text output}{ |
129 | Text from \req{da001},\req{da002},\req{da003}, \req{da004}, |
130 | and \req{da005} is output to standard output or to a file. |
131 | } |
132 | |
133 | %******************************************************************************* |
ad324d29 |
134 | \newpage |
290011d2 |
135 | \subsection{Data processing} |
136 | |
137 | \rd{dp001}{Split into object files}{ |
138 | The tape data shall be divided into self-contained object files.\\ |
139 | The generated file names are derived from the first symbol name |
140 | defined in the current object.\\ |
141 | Example: If an object exports the symbols SONNE, MOND |
142 | and STERNE, the resulting file name will be SONNE.\\ |
143 | EOT (end of tape) blocks shall not be output in this mode of operation. |
144 | } |
145 | |
146 | \rd{dp002}{Split into numbered object files}{ |
147 | Similar to \req{dp006}, but the object file names are prepended with |
148 | a zero-padded three digit number and EOT blocks are not suppressed. |
149 | } |
150 | |
c7358c23 |
151 | |
152 | %******************************************************************************* |
153 | \newpage |
154 | \subsection{Error handling} |
155 | |
156 | |
157 | \newcommand{\esup}{ |
158 | This error shall lead to an error message and immediate program |
159 | termination or a warning message and program continuation. |
160 | } |
161 | |
162 | \newcommand{\enosup}{ |
163 | This error shall always lead to an error message and immediate |
164 | program termination. |
165 | } |
166 | |
167 | \rd{err001}{Error types}{ |
168 | The following distinguished error types shall exist: |
169 | \begin{itemize} |
170 | \item Input/output error:\\ |
171 | Error occuring during reading from the input file descriptor |
172 | or during writing to an output file.\\ |
173 | \enosup |
174 | \item Block integrity error:\\ |
175 | Caused by failed check according to \req{chk001}.\\ |
176 | \esup |
177 | \item Checksum error:\\ |
178 | Caused by failed check according to \req{chk002}.\\ |
179 | \esup |
180 | \item Unknown block type error:\\ |
181 | Caused by failed check according to \req{chk003}.\\ |
182 | \esup |
183 | \item Object integrity error:\\ |
184 | Caused by failed check according to \req{chk004}.\\ |
185 | \esup |
186 | \item Usage error:\\ |
187 | Error caused by errors in the program configuration i.e. wrong |
188 | parameters or impossible combinations of parameters.\\ |
189 | \enosup \\ |
190 | Additionally, the help (\req{h001}) message is output. |
191 | \item Internal program error:\\ |
192 | Error caused by internal program problems.\\ |
193 | This error should never occur.\\ |
194 | \enosup |
195 | \end{itemize} |
196 | } |
197 | |
198 | \rd{err002}{Program exit codes}{ |
199 | \begin{table}[H] |
200 | \begin{center} |
201 | \begin{tabular}{|r|c|} |
202 | \hline |
203 | \multicolumn{1}{|c|}{\bf Exit condition} & \bf Return code\\ |
204 | \hline |
205 | Successfull program completion & 0 \\ |
206 | File open error & 1\\ |
207 | Input/output error & 2\\ |
208 | Block integrity error & 3\\ |
209 | Checksum error & 4\\ |
210 | Unknown block type error & 5\\ |
211 | Object integrity error & 6\\ |
212 | Usage error & 7\\ |
213 | Internal program error & 100 \\ |
214 | \hline |
215 | \end{tabular} |
216 | \caption[Program Exit codes]{Exit codes} |
217 | \end{center} |
218 | \end{table} |
219 | } |
220 | |
221 | \rd{err003}{Error and warning messages}{ |
222 | Error messages shall consinst of ''Error:'' and the error reason.\\ |
223 | Warning messages shall consist of ''Warning:'' and a descriptive |
224 | text.\\ |
225 | The following texts shall be used to form error and warning messages: |
226 | \begin{table}[H] |
227 | \begin{center} |
228 | \begin{tabular}{|l|l|} |
229 | \hline |
230 | \bf Error condition & \bf Descriptive text\\ \hline |
231 | File open error & Could not open $<$filename$>$ for reading/writing!\\ |
232 | Input error & Could not read from $<$filename$>$!\\ |
233 | Output error & Could not write to $<$filename$>$!\\ |
234 | Block integrity error & Block integrity check failed!\\ |
235 | Checksum error & Block checksum wrong!\\ |
236 | Unknown block type & Unknown block type!\\ |
237 | Object integrity & Object integrity check failed!\\ |
238 | Usage error & $<$Specific message describing the problem$>$\\ |
239 | \hline |
240 | \end{tabular} |
241 | \end{center} |
242 | \caption[Error and warning messages]{Messages} |
243 | \end{table} |
244 | } |
245 | |
246 | \rd{err004}{Error message output}{ |
247 | Any error messages shall be output to standard error.\\ |
248 | There shall be no way to suppress error messages. |
249 | } |
250 | |
251 | \rd{err005}{Warning message output}{ |
252 | Any warning messages shall be output to standard error.\\ |
253 | There shall be a possibility to suppress warning messages. |
254 | } |
255 | |
290011d2 |
256 | %******************************************************************************* |
ad324d29 |
257 | \newpage |
290011d2 |
258 | \subsection{Program configuration} |
259 | |
260 | \rd{cfg001}{Configuration process}{ |
ad324d29 |
261 | The following sequence shall be used to acquire the working |
262 | configuration: |
290011d2 |
263 | \begin{enumerate} |
264 | \item Configuration file according to environment variable:\\ |
265 | If the environment variable LDC\_CONFIG is set, that |
266 | file shall be parsed. |
267 | \item Configuration file according to command line parameter:\\ |
268 | If the command line parameter specifying a configuration |
269 | file is found, |
270 | the specified configuration file is parsed.\\ |
271 | Any values in this configuration file |
ad324d29 |
272 | override values found in the previously read |
273 | configuration file. |
290011d2 |
274 | \item Configuration parameters passed via the command line:\\ |
275 | Parameters passed on the command line will override |
c7358c23 |
276 | values from previously read configuration files. If the command line |
277 | mentiones a configuration file to read, this file is processed before |
278 | the other parameters supplied on the command line. |
290011d2 |
279 | \end{enumerate} |
280 | } |
281 | |
282 | \rd{cfg002}{Parameter types}{ |
283 | The program shall accept two types of parameters: |
284 | \begin{itemize} |
285 | \item Switches:\\ |
ad324d29 |
286 | A switch is a binary value which can have the value true or |
287 | false. |
290011d2 |
288 | \item Strings:\\ |
289 | A string parameter is a parameter requiring a string value.\\ |
290 | A typical use would be a file name for input or output. |
291 | \end{itemize} |
292 | } |
293 | |
ad324d29 |
294 | \newpage |
290011d2 |
295 | \rd{cfg003}{Switch parameters}{ |
296 | The following switch parameters shall be accepted: |
297 | \begin{table}[H]\begin{center} |
ad324d29 |
298 | \begin{tabular}{|r|p{2.5em}|p{23em}|} |
290011d2 |
299 | \hline |
300 | \bf Long Form & \bf Short form & \bf Description\\ |
301 | \hline |
302 | help & h & Show help message (\req{h001})\\ |
ad324d29 |
303 | output\_info & a & Output data info (\req{da005}) .\\ |
304 | output\_called & c & Output a list of called symbols |
305 | (\req{da003}).\\ |
306 | output\_exported & e & Output a list of exported symbols |
307 | (\req{da002}).\\ |
308 | output\_unsatisfied & u & Output a list of unsatisfied |
309 | dependencies (\req{da004}).\\ |
310 | split\_objects & s & Split into object files |
311 | (\req{dp001}).\\ |
312 | split\_objects\_numbered & S & Split into numbered object files |
313 | (\req{dp002}).\\ |
314 | ignore\_block\_errors & b & Ignore block integrity errors |
315 | (\req{err001},\req{chk001}).\\ |
316 | ignore\_checksum\_errors & k & Ignore Checksum errors |
317 | (\req{err001}\req{chk002}).\\ |
318 | pause\_on\_checksum\_error & p & Wait for user input on checksum error |
319 | (\req{chk005}).\\ |
320 | ignore\_unknown\_block\_errors & n & Ignore errors causes by |
321 | datablocks of unknown type |
322 | (\req{err001}\req{chk003}).\\ |
323 | ignore\_object\_integrity\_errors & g & Ignore errors caused by objects |
324 | without proper end block |
325 | (\req{err001}\req{chk004}).\\ |
290011d2 |
326 | \hline |
327 | \end{tabular}\end{center} |
328 | \caption{Configuration switches} |
329 | \end{table} |
330 | } |
331 | |
332 | \rd{cfg004}{String parameters}{ |
333 | The following string parameters shall be accepted: |
334 | \begin{table}[H]\begin{center} |
335 | \begin{tabular}{|r|p{2.5em}|l|} |
336 | \hline |
337 | \bf Long Form & \bf Short form & \bf Description\\ |
338 | \hline |
ad324d29 |
339 | in\_file & i & Set input file (\req{inp001}). \\ |
340 | out\_file & o & Set output file for text output(\req{dp008}).\\ |
290011d2 |
341 | \hline |
342 | \end{tabular}\end{center} |
343 | \caption{Configuration strings} |
344 | \end{table} |
345 | |
346 | } |
ad324d29 |
347 | \newpage |
290011d2 |
348 | \rd{cfg005}{Configuration file syntax}{ |
349 | The configuration file must comply two the following grammar, given in EBNF: |
350 | } |
351 | \begin{verbatim} |
352 | ConfigurationFile = { ConfigurationLine "<EOL>" } ; |
353 | ConfigurationLine = SwitchLine | StringLine | CommentLine ; |
354 | SwitchLine = WSpace SwLong WSpace "=" BoolValue ; |
355 | StringLine = WSpace StrLong WSpace "=" String ; |
356 | CommentLine = WSpace [ "#" String ] ; |
357 | WSpace = { " " } ; |
358 | SwLong = "output_info" | "ouput_called" | "output_exported" |
359 | | "output_unsatisfied" | "split_objects" [ _"numbered" ] |
360 | | "ignore_block_errors" | "ignore_checksum_errors |
361 | | "pause_on_checksum_error" |
362 | | "ignore_unknown_block_errors" |
363 | | "ignore_object_integrity" ; |
364 | StrLong = "out_file" | "in_file" ; |
365 | BoolValue = TrueStr | FalseStr ; |
366 | String = { ? Every character except newline ?} ; |
367 | TrueStr = "yes" | "1" | "true" ; |
368 | FalseStr = | "no" | "0" | "false" ; |
ad324d29 |
369 | \end{verbatim} |
290011d2 |
370 | |
ad324d29 |
371 | \rd{cfg006}{Command Line syntax}{ |
290011d2 |
372 | The command line must comply to the following grammar, given in EBNF: |
373 | } |
374 | \begin{verbatim} |
375 | CommandLine = ProgramName Arguments ; |
376 | ProgramName = String ; |
377 | Arguments = { " " } { " " Argument } [ " " InfileName ] ; |
378 | Argument = { Switch | Parameter } |
379 | InfileName = String ; |
380 | Switch = ShortSwitch | LongSwitch ; |
381 | Parameter = ShortParam | LongParam ; |
382 | String = { ? Every character except newline ? } ; |
383 | ShortSwitch = "-" SwShort ; |
384 | LongSwitch = "--" SwLong [ "=" BoolValue ] ; |
385 | ShortParam = "-" StrShort String ; |
386 | LongParam = "--" StrLong "=" String ; |
ad324d29 |
387 | SwShort = "h" | "a" | "c" | "e" | "u" | "s" | "S" |
290011d2 |
388 | | "b" | "k" | "p" | "n" | "g" ; |
ad324d29 |
389 | SwLong = "help" |
390 | | "output_info" | "ouput_called" | "output_exported" |
290011d2 |
391 | | "output_unsatisfied" | "split_objects" [ _"numbered" ] |
ad324d29 |
392 | | "ignore_block_errors" | "ignore_checksum_errors" |
290011d2 |
393 | | "pause_on_checksum_error" |
394 | | "ignore_unknown_block_errors" |
395 | | "ignore_object_integrity" ; |
ad324d29 |
396 | StrShort = "o" ; |
290011d2 |
397 | StrLong = "out_file" ; |
398 | \end{verbatim} |
399 | |
ad324d29 |
400 | \newpage |
290011d2 |
401 | \rd{cfg007}{Configuration implications}{ |
402 | \begin{itemize} |
c7358c23 |
403 | \item \emph{pause\_on\_checksum\_errors} implies \emph{ignore\_checksum\_errors}. |
404 | \item \emph{pause\_on\_checksum\_errors} is completely ignored when input |
290011d2 |
405 | is read from standard input. |
c7358c23 |
406 | \item \emph{output\_*} inhibits tape information output (\req{da001}). |
407 | \item \emph{help} inhibits all other actions. |
290011d2 |
408 | \end{itemize} |
409 | } |
410 | |
411 | \rd{cfg008}{Default behaviour}{ |
412 | \begin{itemize} |
413 | \item Data is read from standard input. |
414 | \item All error conditions result in immediate program termination |
415 | and an error message. |
416 | \item Tape information according to \req{da001} is output. |
c7358c23 |
417 | \item Normal Text is output to standard output. |
418 | \item Error messages are output to standard error. |
290011d2 |
419 | \end{itemize} |
420 | } |