
	The 8051 Family Emulator for Linux

The 8051 micro-controller is a 8 bit CPU. It is equipped with internal RAM,
a USART and a couple of Counter/Timer.
Scope of this emulator is to avoid the use of expensive "In Circuit Emulator"
to debug embedded software developed with this amusing CPU.
I have developed this emulator for two reasons:
  - to pass a university test
  - to have a friendly environment to debug my home controller: a
    8052 based card to control the house temperature, and the alarm.
To have other information conct me at:
firpo@educ.disi.unige.it
-------------------------------------------------------------------------
Introduction
------------
The 8051 microcontroller is provided in several configurations each of 
them have a peculiar functionality and, therefore, a different part number.
For this reason the tag "8051" indicates the uP family.
All microcontrollers use the same instruction-set but a different set of
devices (RAM,USART,TIMERS); the differences can be devided in 2 sub-family:
8051/31 e 8052/32
I the following table are listed the differences between this 2 family:

    Family     RAM         16 bit Timer
    8051/31    128 bytes       2
    8052/32    256 bytes       3

Both family can be simulated choosing a different set-up before the sources
compilation.
To obtain a generic emulator for both you can choose the 8052/32 family, 
this family is compatible with the 8051/31.
This is the unique static setting of the emulator.

Sim8051 is able to load and execute hex files coded according to the Intel
standard format produced by every 8051 software factory.
Normally this file is used to burn EPROM/ROM.
In the Appendix B is described the Intel file format.

-------------------------------------------------------------------------
The 8051 microcontroller 
------------------------
Refer to the "Data Sheets" ((Intel, Amd, Matra Harris, etc) to understand 
deeply this uP!!
In the follow is only explained some Notation used in this document.

  - Regiser banks.
     ACC   :  Accumulator
     B     :  B Register 
     PSW   :  Program Status Word (flags)
     SP    :  Stack Pointer
     PC    :  Program Counter (16 bit)
     DPTR  :  Data Pointer (2 bytes: DPH e DPL)
     R0-R7 : 8 bit general purpose registers 
  R0-R7 regs are stored in 4 different banksselected by means of 2 PSW bits.
  PSW register:
     Carry     : Carry Out for ALU operations
     Aux Carry : for ALU BCD operations
     Overflow  : for ALU operations
     Parity    : Accumulator parity bit .
     Register Bank Select: to select one R0-7 bank
     User Definable Flag and General Purpose Flag.

  - Memory organization:
  The 8051 address space is 64K bytes for program (ROM) and 64K bytes for
  data (RAM). Some application can use an external circuit to merge the
  2 address space to obtain 64K bytes accessable as program as data (program
  and data merging mode).
  Internal RAM:
  128 bytes called SFR (Special Function Register), usable only by 
  means of direct addressing , in which are contained the described 
  registers (R0-7 excluded) and the registers used to configure all
  other functions.
  128 bytes of RAM usable by direct and indirect addressing; the indirect
  access is useb by the stack pointer to push/pop datas. 
  The first chunck of this area is bit addressable.
  The 8052/32 family supports 128 byte too for the indirect access (stack).
  The following schema describes the address space:

  +------+ FFFF   +------+ FFFF                  +-------------+
  |      |        |      |                    FF |  INDIRECT   |
  |      |        |  E   |                +------------+ ONLY  |
  |  P   |        |  X   |             FF | SFRs       |       |
  |  R   |        |  T   |                | DIRECT     |       |
  |  O   |        |      |                | ADDRESSING |-------+
  |  G   |        |  D   |                | ONLY       |
  |  R   |        |  A   |             80 +------------+
  |  A   |        |  T   |             7F |            |
  |  M   |        |  A   |                | DIRECT &   |
  |      |        |      |                | INDIRECT   | Bit Address. Area
  |      |        |      |                | ADDRESSING | Register Bank
  +------+ 0000   +------+ 0000        00 +------------+

  Of course the emulator suppports these spaces also for the "program & data
  merging" mode.

-------------------------------------------------------------------------
Using the emulator
------------------

Commands are devided in 3 classes:
  -Configuration
  -Execution & breakpoints
  -display and change (patch) of memory locations
0|1 indicates the possibility to disable/enable the indicated function.
The sim- prefix is used for the simulated entities (ex: sim-instruction =
a 8051 emulated instruction).

 -Configuration
 ser_tty "file"
  Redirects in Tx/Rx the USART sim-device to a Unix file.
  Can be used to redirect the USART to a "raw" tty.
  In the Appendix B there is a simple script to use a tty in this mode.

 set sms "0|1"
  Sets the address mode in the "program & data merging mode".

 ser_show_hex "0|1"
  When the USART is redirected to a file (tty) this flag can be used
  to get print the USART output in the hexadecimal base ([XX]).

 ser_real_speed "0|1"
  Emulate the USART "busy" time during the chars transmission/reception.
  The busy time depends by the speed configured to approximate the real
  busy time.
  If the option is not used the busy time is zero.

 trace_int "0|1"
  Traces all sim-served interrupts.

 show conf
  Shows the configurations state.

 -Execution & breakpoints
 reset
  Sets the sim-microcontroller in the Power-On Reset state.
  Program and data memories are NOT changed.

 go
 go "address"
  Starts the sim-instruction execution.
  If an address is specified the Program Counter is loaded with this
  address before to start.

 s
 s "n"
 step
 step "n"
  Executes 1 or n sim-instructions (if n is present). After each instruction
  the complete register state will be printed (see dr command).

 break "address"
  Defines a breakpoint to the specified address. 
  When the instruction stored at this address is reached the emulator
  stops it and prints the complete register state (see dr command).
  You can specify up to 10 breakpoints.
  During the execution the Ctrl-C key combination causes an asyncronous
  breakpoint.

 delete "n"
  Deletes the specified breakpoint. 

 delete *
  Delete all breakpoints.

 blist
  Lists the defined breakpoints. 

 -Display and change of memory locations
 load "file"
  Load in the program  memory the code contained in the specified file 
  according to Intel-Standard format.
  The file name can be passed as parameter in the invokation (inplicit).

 l
 l "address"
 list
 list "address"
  Disassembles 10 sim-instructions. 

 dr
  Print the register state according the following format:
    PC ACC B  R0 R1 R2 R3 R4 R5 R6 R7 DPTR SP    PSW       2S1100PEND  CYCLES
   0000 00 00 00 00 00 00 00 00 00 00 0000 07 caf00ofp(00) __txtx(00)  0
   0000 00         NOP
  The bits of the PSW register are shown directly: lower case indicates
  a 0, uppercase indicates a 1.
  The pending interrupts are printed in the following format:
   2: Timer/External 2 (8052/32 Only)     T:TF2 bit   E:EXF2 bit   B:both
   S: USART     T:TI bit (Tx)    R:RI bit (Rx)    B:both
   1t: Timer 1       t=not pending   T=pending
   1x: External 1    x=not pending   X=pending
   0t: Timer 0       t=not pending   T=pending
   0x: External 0    x=not pending   X=pending
  CYCLES indicates the executed sim-cycles ; each cycle is equivalent to
  500 nSec. (therefore 2 cycles = 1 usec).

 dc
 dc "address"
  Display of the program memory content at the specified address.

 dx
 dx "address"
  Display of the data memory content at the specified address.

 dd
 dd "address"
  Display of the internal data memory content at the specified address.
  
 di
 di "address"
  Display of the internal indirect data memory content at the 
  specified address.
  
 pc "address" "val"
  Patches the program memory content at the specified address with val.

 px "address" "val"
  Patches the data memory content at the specified address with val.

 pd "address" "val"
  Patches the internal data memory content at the specified address with val.

 pi "address" "val"
  Patches the internal indirect data memory content at the specified 
  address with val.

 -general purpose
 !"command"
  Executes the specified shell command.

 quit
  Leaves the emulator.

-------------------------------------------------------------------------
AppendiX A :  The Intel-Standard format
-----------
The file is composed by records with all information in hexadecimal form.

   :nnoooo00ddddddcc    Data record (nn=num of dd from 01 to 10)
                        (dd=data, cc=checksum, oooo=offset/address)
   :00oooo01FF		End of file record (Last)
   			(oooo=program entry address)

The sum of all bytes (modulo 256) checksum included must be 0.

-------------------------------------------------------------------------
AppendiX B :  Script to set the Raw mode on a tty
-----------
#
/bin/echo "termsim    Ver.: 1.0"
save_file=/tmp/termsim$RANDOM.$$

function autokill()
{
	echo " "
	echo Restoring TTY...
	stty `cat $save_file `
	/bin/rm -f $save_file
	echo Bye
	exit
}

echo "Use:   kill $$   to terminate this terminal emulation (wait 15 seconds)"
echo "This is tty: " `tty` 
echo " "
trap "autokill" SIGTERM
echo  Saving TTY configuration...
stty --save > $save_file
echo  Changing TTY configuration...
stty raw -echo

#wait forever
while (true) 
do
  # to not charge the CPU
  nice sleep 15s
done
exit

