% Format: latex

% $Header: J:\MICROP\56PTWS0\RCS\sim68k.tex 1.1 1996/01/14 12:51:12 Nick Exp Nick $

% $Log: sim68k.tex $
% Revision 1.1  1996/01/14  12:51:12  Nick
% Initial revision
%

\documentclass[%
   %a4paper,%
   a5paper,%
   titlepage,%
   twoside,%
   %11pt%
   %12pt%
   ]{article}

\usepackage{%
   %a4,%
   vmargin,%
   varioref,%
   %multicol,%
   fancyhea,%
   booktabs,%
   verbatim,%
   %fullpage,%
   %emlines2,%
   %xr,%
   acro,%
   cols,%
   key,%
   prog,%
   %nbox,%
   %amssymb,%
   amsmath,%
   %lgrind,%
   %tabularx,%
   ifthen,%
   nick%
}

\newboolean{smallBook}
\setboolean{smallBook}{true}

\ifthenelse{\boolean{smallBook}}%
{%
   % Half A4 size:
   \setpapersize{A5}%
   \setmarginsrb{15mm}% left
                {9mm}% top
                {15mm}% right
                {10mm}% bottom
                {12pt}% headheight---increase to stop fancyhead warn
                {4mm}%  headsep
                {0pt}%  footheight
                {8mm}% footskip
}%
%else
{%
   \setmarginsrb{30mm}% left
                {18mm}% top
                {30mm}% right
                {10mm}% bottom
                {15pt}% headheight---increase to stop fancyhead warn
                {8mm}%  headsep
                {0pt}%  footheight
                {11mm}% footskip
} % End of if small book ... else.

\pagestyle{fancy}
\lhead%
[\fancyplain{}{}\textbf{\upshape A guide to using assembly language in
  the laboratory and at home}]
{\fancyplain{}{}\textbf{\thepage}}

\rhead%
[\fancyplain{}{}\textbf{\upshape \thepage}]
{\fancyplain{}{}\textbf{\upshape A guide to using assembly language in
  the laboratory and at home}}

\lfoot[]{\fancyplain{}{}\tiny Nick Urbanik}
\rfoot[\fancyplain{}{}\tiny Nick Urbanik]{}
\cfoot{}

\title{A guide to using assembly language in
  the laboratory and at home}
\author{Nick Urbanik}
\date{\normalsize 14 January 1995}

\pagestyle{fancy}

\newcommand*{\simk}{\textsf{sim68k}\xspace}
\newcommand*{\asmk}{\textsf{asm68k}\xspace}
\newcommand*{\ECB}{\acro{ECB}\xspace}
\newcommand*{\CR}{\acro{CR}\xspace}
\newcommand*{\LF}{\acro{LF}\xspace}

\begin{document}
\maketitle
\setcounter{page}{1}

\tableofcontents

%\thispagestyle{empty}

\section{Example of using \simk}

Follow the procedure:

\begin{enumerate}
\item At the \DOS prompt, type

\texttt{edit ex1.asm} \meta{Enter}

\item Type the following program: (note that it is the same as
  \texttt{ex1.asm} in Workshop~2 for part-time classes but the addresses
  \inst{data} and \inst{prog} were changed to match \simk).
\begin{prog}
data    equ     $1000           (note the addresses are different from the
prog    equ     $1100           \FLIGHT{} board using in the laboratory)

        org     data
value1  dc.l    $12345678       first value
value2  dc.l    $87654321       second value
result  ds.l    1               reserve long word storage

        org     prog
        movem.l value1,d0/d1    load values to be compared
        cmp.l   d0,d1           compare 32 bit values
        bhi     store           if value2 > value1 then goto store
        move.l  d0,d1           else d1 = value1
store   move.l  d1,result       store larger value
        nop                     (note: no trap #11 instruction)
        END
\end{prog}
\item Select File$\rightarrow$Exit from the editor menu and press \meta{Enter}.

\item At the \DOS prompt, type

\texttt{asm68k ex1.asm} \meta{Enter}

\item type

\texttt{sim68k} \meta{Enter}

\item Press \meta{CapsLock} to switch to capital letters since the
  simulator \emph{only} accepts CAPITAL LETTERS!

\item Type
       
\texttt{LO ex1.s} \meta{Enter}\\
\texttt{MD 1100 13;DI} \meta{Enter}
    
The screen will display the instructions of your program.

\item \label{itm:seeMem}Type

\texttt{MD 1000 10} \meta{Enter}
    
Record the contents of the memory.

\item Type 

\texttt{BR 1112} \meta{Enter} \\
\texttt{GO 1100} \meta{Enter}
    
The program will execute from address 1100\hex and stop at 1112\hex.

\item Type

\texttt{MD 1000 10} \meta{Enter}

Record the contents of the memory again and compare the result with
(\ref{itm:seeMem}).

\item Type

\texttt{EX} \meta{Enter}

The program will exit and return to \DOS.
\end{enumerate}


\section{The \simk simulator}

Here are the commands that the \simk simulator can use.  For a full
description of the simulator and assembler, see the book,
\emph{Computer Organisation and the MC68000}, by Panos E. Livadas and
Christopher Ward, Prentice-Hall, 1993\e.  The authors of the book
wrote the simulator and assembler and are making them freely
available.


\subsection{The Simulator}

The simulator is able to simulate the Motorola ``Educational Computer
Board'', or \ECB.  The \ECB has a rather different address map from the
\FLIGHT.  Also the \ECB has similar firmware commands, but they have
different letters.  These are listed below.  The name of the simulator
is \simk.  The firmware in the \ECB is called \emph{Tutor}.

\subsection{The Memory Map of the \ECB (and \simk)}

\begin{center}
\begin{tabular}{@{}r@{--}lcl@{}}
\toprule
\multicolumn{2}{c}{Address range} & Device & Use \\
\midrule
000000 & 000007 & \ROM &   Reset vector \\
000008 & 0003FF & \RAM &   Vector table \\
000400 & 0008FF & \RAM &   Tutor scratch pad \\
000900 & 007FFF & \RAM &   \textbf{USER
  MEMORY}\makebox[0pt][l]{\large{} $\pmb{\Longleftarrow}$} \\
008000 & 00BFFF & \ROM &   Tutor firmware \\
00C000 & 00FFFF &     &   Unused \\
\bottomrule
\end{tabular}
\end{center}


A 68230 \PIT and two 6850 \acro{UART}s are mapped above 00FFFF\hex,
but the address space there is otherwise empty.

\eemph{Note} that your program \eemph{must} be loaded into addresses \emph{lower} than \$7FFF,
but higher than \$8FF.  The stack is usually at the top of \RAM.

\section{\simk firmware commands}

The \simk simulator is just software that runs on the \PC and of
course contains no real firmware, but these are Tutor firmware
commands on the \ECB.

ALL COMMANDS MUST BE ENTERED IN UPPER CASE LIKE THIS!

\subsection{Getting started}
\begin{tabular}{>{\bfseries}ll>{\ttfamily}l}
1. & Assemble your program with the assembler, \asmk. & asm68k
\meta{filename}.\meta{ext} \\
2. & Load your program into the simulator:   &     LO
\meta{filename}.s \\
3. & Set the status register to \$0700:  &          .SR 0700 \\
4. & Set the stack pointer to \$7800: &             .US 7800 \\
5. & Single step (``Trace'') your program: &         TR
[\meta{address}] \\
& \quad OR & \\
&   Execute your program: &                   GO [\meta{address}]
\end{tabular}

\subsection{List of firmware commands}

A summary of the commands recognised by \simk is shown in
table~\vref{tab:commands}.  In that table, \texttt{[...]} means that
\texttt{...} is optional.

\begin{table}
{\small
\begin{tabularx}{\linewidth}{@{}>{\ttfamily}lY@{}}
\toprule
\normalfont Command & \multicolumn{1}{c}{Action} \\
\midrule
DF              & ``Display Formatted''---display the registers, like
the \FLIGHT command \meta{r}\meta{d}.\\
MD \meta{address} &   Memory dump \\
MD \meta{address} ;DI &       Disassemble \\
EX             & Exit the simulator \\
.\meta{register} &    Display \meta{register}, e.g.,
    \begin{tabular}[t]{@{}>{\ttfamily}l<{\space}@{}l@{}}
                                        .D0 & will display D0 \\
                                        .A6 & will display A6 \\
                                        .A7 & will display A7 \\
                                        .SR & will display SR \\
                                        .PC & will display PC.
                                      \end{tabular}
                                      \\
.\meta{register} \meta{data} & Modify \meta{register}, e.g.,
 \begin{tabular}[t]{@{}>{\ttfamily}l<{\space}@{}l@{}}
                                        .D0 \meta{data} & will modify D0 \\
                                        .A6 \meta{data} & will modify
                                        A6 \\
                                        .A7 \meta{data} & will modify
                                        A7 \\
                                        .SR \meta{data} & will modify
                                        SR \\
                                        .PC \meta{data} & will modify
                                        PC.
                                      \end{tabular} \\
GO [\meta{address}] & Run program non-stop \\
TR [\meta{address}] & Single step \\
BR [\meta{address}] & Set/display breakpoints---up to a maximum of eight. \\
NOBR [\meta{address}] & Clear breakpoints \\
LO \meta{filename} & Load \meta{filename} into \simk.  File contains Motorola
S records. \\
ST \meta{filename} \meta{address} \meta{count} & load \meta{count} bytes starting at
                                        \meta{address} and store into
                                        \meta{filename}. \\
BF \meta{address1} \meta{address2} \meta{data} & Copy the hexadecimal word in \meta{data} to
                        all addresses from \meta{address1} to
                        \meta{address2}. \\
MM \meta{address}   & Modify one byte of memory.  Type . to
terminate. \\
MM \meta{address};W & Modify one word of memory at a time. \\
\bottomrule
\end{tabularx}%
}%
\caption{A list of commands recognised by \simk.  These are compatible
  with the Motorola Tutor firmware commands.}
\label{tab:commands}
\end{table}


The firmware remembers the last command you entered.  If you just type
a carriage return at the prompt, the last command will be processed
again.

Dissassembly works on one instruction the first time.  If you press
\meta{Enter} straight after, you get 16 instructions dissassembled.


\subsection{Monitor software interrupts}

Like the \FLIGHT, the \ECB supports software interrupts.  There is a
difference in the way they are used: load a function number as a byte
into the D7 register then execute the instruction \inst{trap \#14}.

\begin{prog}
        move.b  #\meta{function number},d7
        trap    #14
\end{prog}

Here is a list of these \IO functions.  The function numbers are given
in decimal.

\begin{tabularx}{\linewidth}{@{}llY@{}}
\toprule
\multicolumn{2}{c}{Function}& \\
\cmidrule(r){1-2}
number    &      name & purpose \\
\midrule
241 & \inst{PORTIN1} & Read string from keyboard into A6, terminate
                        with \CR \LF.\\
247 & \inst{INCHE}   & As for \inst{PORTIN1} but terminated
with CR with no LF \\
243 & \inst{OUTPUT}  & Output string A6 points to to the screen \\
227 & \inst{OUT1CR}  & As \inst{OUTPUT} but also send \CR \LF. \\
248 & \inst{OUTCH}   & Byte in D0 is output to screen \\
228 & \inst{EXIT}    & Give termination message if Supervisor bit
clear.\\
\bottomrule
\end{tabularx}

For more information see Appendix C of Livadas.

\subsection{Use the correct simulator and assembler}

Note that there are \emph{three} simulators in the \texttt{f:\bs sim68k}
directory.  Use \texttt{sim68k.exe}.  There is one, \texttt{xsim68k},
that will run only under \UNIX.  The other, \texttt{sim68.exe}, is a
simulator for a simplified 68000.

Similarly there are two assemblers: use \texttt{asm68k}.  The other,
\texttt{asm68}, is an assembler for the simplified simulator.

\section{Using \asmk}

Syntax:
\begin{alltt}
asm68k \meta{filename} [-l[x]] [-r]
\end{alltt}
\begin{tabularx}{\linewidth}{>{\ttfamily}lY}
-l  & causes the assembler to produce a listing file.\\
-lx & produces a listing file containing a cross-reference table\\
-r  & produces a relocatable object file that can be linked; output file
    will have the extension ``\texttt{.o}''.
\end{tabularx}

\section{How to obtain the simulator and assembler}

To obtain the simulator, go to the \MPA, room D226, and:
\begin{itemize}
  \item Turn on one of the computers
\item Select the ``Novell network'' option from the boot menu
\item type:

\texttt{f:} \meta{Enter}
\item Type:

\texttt{cd \bs sim68k}

\item Put a formatted floppy disk into the 3\fracSl14'' drive

\item Run the batch file \texttt{copyit.bat} by typing:

\texttt{copyit} \meta{Enter}

\item When disk activity stops, remove your floppy disk
\item Take the floppy disk home
\item Make a directory on your computer by typing

\texttt{md \bs sim68k} \meta{Enter}
\item Change to that directory with

\texttt{cd \bs sim68k} \meta{Enter}

\item Copy the programs from your floppy disk to your computer's hard
  disk by typing:

\texttt{xcopy a:\bs sim68k\bs *.* .} \meta{Enter}
\end{itemize}
\end{document}



