\chapter{User Guide} \section{Start-up of the Tool} The tool and five files of test data are stored in /usr/fsb/wlw/ogg on {\rm crown} and \\ /user/csplw1/ogg on {\rm forth}. Start up the program by typing: \\ \hspace*{20mm} {\it newogg $<$filename$>$} \\ \\ $<$filename$>$ could be one of the following data files: \begin{itemize} \item g1.dat contains most of the instructions whose function codes are group 1. \item g2.dat contains most of the instructions whose function codes are group 2. \item g3.dat contains most of the instructions whose function codes are group 3. \item trap.dat contains instructions of trap service routine and other general instructions with function codes of three groups. \item stack.dat contains instructions of stack frame and others. \end{itemize} If you want to visualise the operation of group one instructions, for instance, you type \\ \hspace*{20mm}{\it newogg g1.dat} \\ at the moment, the screen will display the machine name and then several lines of introduction message. Before the end of the message, you will see the instruction says : \\ {\it Now if you are ready, press any key to start the program.} \\ If a key has been pressed, it means the program has started running and the screen shows the first output for the first instruction executed. It is time for you to trace the operation now by examining the changing data on screen. At the bottom right, you will see the message saying : \\ \\ {\it Press q for exit and any other keys for next instruction.} \\ \\ So if you want to exit the tool and go back to UNIX system, press `q' or `Q', and then the screen will display `End of Program Run' and bring you back to UNIX; or if you want to continue using the tool, just press any key except `q' or `Q', until the tool demonstrates the last instruction of each data file `stp', at which point when you press any key, the screen will display \\ \hspace*{20mm}{\it End of Program Run} \\ at the bottom, and bring you back to UNIX. \\ If you want to learn about or examine other instructions, type \\ \hspace*{20mm} {\it newogg $<$filename$>$} again. \section{Error Messages} Sometimes, the user might forget to type the filename and just type \\ \hspace*{20mm} {\it newogg} rather than {\it newogg $<$filename$>$} \\ At the moment the screen will display : \\ \hspace*{20mm} {\it Usage is newogg datafile} \\ If the user types : \\ \hspace*{20mm} {\it newogg $<$filename1$>$ $<$filename2$>$} \\ the following message is shown : \\ \hspace*{20mm} {\it only one file is allowed} \\ It is rather possible for the user to type the name of data file wrongly. They may type \\ {\it newogg g1.dt} instead of {\it newogg g1.dat}. \\ The tool cannot find the data file, g1.dt, the error message : \\ \hspace*{20mm} {\it No such file or directory} \\ will appear at second line of the screen. \section{Design of Data Files} If users want to run their own data file, they can create a data file in the format of \\ \begin{it} \begin{tabbing} lllllllll \= llll \kill \> block address \\ \> block size \\ \> data \\ \> :::: \\ \> block address \\ \> block size \\ \> data \\ \> :::: \\ \end{tabbing} \end{it} each line of the data file is octal constants of six digits. For example: \begin{tabbing} 123456789 \= llllllllllll \= l \kill \> 000000 \> ------- block address \\ \> 000006 \> ------- block size ( No. of instructions ) \\ \> 030200 \> ------- first instruction \\ \> 016000 \> \\ \> 120100 \> \\ \> 026000 \> \\ \> 000010 \> \\ \> 000000 \> ------- last instruction of this block \\ \> 000100 \> ------- next block address \\ \> 000003 \> ------- next block size \\ \> 000003 \> \\ \> 040001 \> \\ \> 000001 \> \\ \end{tabbing} When you run your own data file, four possible error messages you might get due to improper constants or wrong format of your data file : \begin{enumerate} \item Missing case limb $<$line no.$>$ \\ This means something has gone wrong with the {\it newogg} program. \item Unrecognised opcode xxxxxx in group x at location xxxxxx. \\ When the opcode is decoded, but does not match any instruction. \item Invalid address \\ When the access location out of the range of 0 to 1023. \item Invalid constant \\ When the input constant data is out of the range 0 to 65535, which would give an {\rm oggin} value outside the range -32768 to 32767. \end{enumerate} These error messages are displayed on the {\it user\_win} and then the program stops running immediately. In such cases, you need to correct your data file until it can be run properly. But if the error is missing case limb, you need to ask someone to have a look of {\rm newogg} program itself. \\ \\ Note that if a {\it rts} or a {\it pul} instruction is encountered before a {\it jsr} or {\it psh}, then the {\it sp} will be incremented into `non-existant' memory without generating an error. This oversight is due to no range checking being performed on {\it sp}. This should not cause many problems as the user's program should not try to remove something from the stack with {\it rts} or {\it pul} before it is put anything on it with {\it jsr} or {\it psh}.