From c7358c239dea2dd30ab2a3f586efa2e4382c3c6c Mon Sep 17 00:00:00 2001 From: hachti Date: Sun, 10 Dec 2006 22:42:50 +0000 Subject: [PATCH] *** empty log message *** --- pc-tools/ldc2/doc/body.tex | 2 +- pc-tools/ldc2/doc/cover.tex | 5 +- pc-tools/ldc2/doc/impl_spec.tex | 2 +- pc-tools/ldc2/doc/intro.tex | 27 ++-- pc-tools/ldc2/doc/literature.bib | 9 ++ pc-tools/ldc2/doc/req_spec.tex | 265 ++++++++++++++++++------------- pc-tools/ldc2/doc/test_spec.tex | 2 +- 7 files changed, 183 insertions(+), 129 deletions(-) diff --git a/pc-tools/ldc2/doc/body.tex b/pc-tools/ldc2/doc/body.tex index f740f7f..83d4402 100644 --- a/pc-tools/ldc2/doc/body.tex +++ b/pc-tools/ldc2/doc/body.tex @@ -4,7 +4,7 @@ \input req_spec \newpage \input impl_spec -\newpage +%\newpage \input test_spec \newpage \input appendix diff --git a/pc-tools/ldc2/doc/cover.tex b/pc-tools/ldc2/doc/cover.tex index 007a0a8..5924d6a 100644 --- a/pc-tools/ldc2/doc/cover.tex +++ b/pc-tools/ldc2/doc/cover.tex @@ -4,7 +4,7 @@ \small Hochschule Bremen, Fachbereich 4: Elektrotechnik und Informatik\\ \vspace{1.5cm} \Large -- Projektbericht --\\ -\vspace{5cm} +\vspace{4cm} \Huge {\tt $\star$\hspace{0.5cm}LDC2\footnote{Name may be subject of change}\hspace{0.5cm}$\star$}\\ \vspace{1cm} @@ -13,10 +13,13 @@ Object Program Analysis Tool\\ \vspace{3cm} \large Philipp Hachtmann, Mat.-Nr. 124370 \\ +\vspace{0.5cm} +10. Dezember 2006\\ \vspace{3.5cm} \normalsize Labor Softwaretechnik 2\\ Prof. Andreas Spillner\\ \vspace{3cm} \small Wintersemester 2006/2007\\ + \end{center} } \ No newline at end of file diff --git a/pc-tools/ldc2/doc/impl_spec.tex b/pc-tools/ldc2/doc/impl_spec.tex index 7166117..ae7a6d7 100644 --- a/pc-tools/ldc2/doc/impl_spec.tex +++ b/pc-tools/ldc2/doc/impl_spec.tex @@ -1,2 +1,2 @@ \section{Implementation Specification} ---- nothing yet --- +--- To be done --- diff --git a/pc-tools/ldc2/doc/intro.tex b/pc-tools/ldc2/doc/intro.tex index c5ce904..0558e23 100644 --- a/pc-tools/ldc2/doc/intro.tex +++ b/pc-tools/ldc2/doc/intro.tex @@ -17,7 +17,7 @@ with sometimes obscure names written on it.\\ We can neither verify the correctness of the data on the tapes nor get any information about a tape's exact contents, exported symbols, and dependencies.\\ -So there is a need for the collector to verify, analyze, sort, split, and +So there is a need for the collector to verify, analyse, sort, split, and recombine his paper tape software.\\ The \pname program provides a handy approach to help doing this using a newer computer with an UNIX style operating system, @@ -27,10 +27,10 @@ disk drives, and some kind of paper tape reading facility. The Honeywell Series 16 assembly program DAP-16 \cite{ser16:dap16:manual} and the FOTRAN IV compiler program \cite{ser16:frtn:manual} read source code from punched paper tape and translate it into relocatable -object code which is then punched out on paper tape again. +object code which then again is punched out on paper tape. See \cite{ser16:progref} for operation details.\\ -The object data is organized in blocks of variable layout and length consisting -of 16 bit wide native machine words. The block format is described +The object data is organised in blocks of variable layout and length consisting +of 16 bit wide native Series 16 machine words. The block format is described in \cite{ser16:progref}, pages 5-21ff. \\ To store the object blocks on punched paper tapes, each word in the block is divided into three parts: the first one is 4 bits wide, the second and @@ -38,7 +38,7 @@ third one are 6 bits wide.\\ Each frame is now translated so that the resulting paper tape frames don't contain any printable or control characters. Then the block is enclosed by control characters and sent out to the paper tape punch device.\\ -The resulting ''silent 4/6/6 code'' can be easily processed by the ASR 33 +The resulting ''silent 4/6/6 code'' can be easily processed by the ASR 33/35 printing terminal. It is even possible to mix listing and object code on one tape because the text between the silent data blocks is ignored by the loader.\\ @@ -46,19 +46,20 @@ See \cite{ddp516:users_guide}, page 10-1ff for more information about this concept, but be aware that the translation table in the document contains \emph{severe} errors.\\ -\subsection{Functional Overview} -\pname is a program which is capable of analyzing object tapes.\\ +\subsection{\pname Functionality} +\pname is a program which is capable of object and library tape image analysis.\\ It reads in the data from a file or a serial line, retranslates -the mangled characters, and reassembles the data blocks into an internal +the mangled characters (4/6/6 code, see above), and reassembles the data blocks into an internal representation.\\ The block checksum is checked immediately after a block has been read in. This provides for immediate error reporting and -handling. One input data error handling possibility is to immediately +handling. + One input data error handling possibility is to immediately stop a tape reader connected to a serial port so that the user has a clue where to look for faulty regions on the paper tape. This is very useful when reading in last existing copies of old software.\\ After the error-free blocks are present in the program's memory, it is -possible to do various operations on it. Examples are extracting and -listing of symbol names, split up the data of a library into several files -or even reverse assembly and relocating into a virtual Series 16 main memory -(not in the base variant of the program). +possible to do various operations on it. Examples are symbol name extraction and listing, +splitting up a tape image's contents into several distinct files, +or even reverse assembly and relocating into a virtual Series 16 main memory. + diff --git a/pc-tools/ldc2/doc/literature.bib b/pc-tools/ldc2/doc/literature.bib index 959b93d..08a094c 100644 --- a/pc-tools/ldc2/doc/literature.bib +++ b/pc-tools/ldc2/doc/literature.bib @@ -74,3 +74,12 @@ string{hon_author=""} note = hdoc # "70130071364A" } +@Manual{ser16:opmanual, + title = {"Series 16 Equipment operators' manual"}, + author = hon_author, + organization = hon_organization, + month = nov, + year = 1973, + note = hdoc # "70130072165F" +} + diff --git a/pc-tools/ldc2/doc/req_spec.tex b/pc-tools/ldc2/doc/req_spec.tex index 4559aad..38ec9c9 100644 --- a/pc-tools/ldc2/doc/req_spec.tex +++ b/pc-tools/ldc2/doc/req_spec.tex @@ -1,4 +1,42 @@ -\section{Functional Specification} +\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} @@ -110,6 +148,111 @@ found in \cite{ser16:progref:bformats}. 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} @@ -130,7 +273,9 @@ found in \cite{ser16:progref:bformats}. configuration file. \item Configuration parameters passed via the command line:\\ Parameters passed on the command line will override - values from previously read configuration files. + 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} } @@ -255,11 +400,11 @@ ShortSwitch = "-" SwShort ; \newpage \rd{cfg007}{Configuration implications}{ \begin{itemize} - \item pause\_on\_checksum\_errors implies ignore\_checksum\_errors. - \item pause\_on\_checksum\_errors is completely ignored when input + \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 output\_* inhibits tape information output (\req{da001}). - \item help inhibits all other actions. + \item \emph{output\_*} inhibits tape information output (\req{da001}). + \item \emph{help} inhibits all other actions. \end{itemize} } @@ -269,111 +414,7 @@ ShortSwitch = "-" SwShort ; \item All error conditions result in immediate program termination and an error message. \item Tape information according to \req{da001} is output. - \item Text is output to standard output. - \end{itemize} -} - -%******************************************************************************* -\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 + \item Normal Text is output to standard output. + \item Error messages are output to standard error. \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[Program Exit codes]{Exit codes} - \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. -} - diff --git a/pc-tools/ldc2/doc/test_spec.tex b/pc-tools/ldc2/doc/test_spec.tex index 468368d..6e73a85 100644 --- a/pc-tools/ldc2/doc/test_spec.tex +++ b/pc-tools/ldc2/doc/test_spec.tex @@ -1,2 +1,2 @@ \section{Test Specification} ---- nothing yet --- \ No newline at end of file +--- To be done --- \ No newline at end of file -- 2.32.0