HELIO EMULATOR README
=====================

Version 1.0.6

* Copyright (c) 2000 Frank Somers/Denis Hennessy, Ground Zero Development
* <frank@g0dev.com>, <denis@g0dev.com>
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the
* Free Software Foundation; either version 2 of the License, or (at your
* option) any later version.
* 
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
* for more details.
* 
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.


This is HelioEmu, version 1.0, a full system emulator for the
Helio PDA by VTech (www.vtechinfo.com)


If you have any questions about how this code works, check the developer
forums on www.vtechinfo.com, or email us.

   Frank Somers <frank@g0dev.com>
   Denis Hennessy <denis@g0dev.com>

From time to time, check www.g0dev.com/helio for updates.

Enjoy!
-Ground Zero Development (www.g0dev.com)


------------------------------------------------------------------------
Loading Applications
------------------------------------------------------------------------

   Start up the emulator

   Change directory to wherever your source code is and use vsyncapp to
   load your application into the emulator (it should have been installed
   with the emulator, but you may have to put it on your path).  eg:

      vsyncapp myapp.app

   This will hotsync the app into the emulator over a socket.  It assumes
   that you have the emulator configured to run UART A over a socket on
   port 2001.  It is also assumed that the 'auto hotsync on UART A' option
   is set in the emulator.  If you are using a different port, you will
   have to add a '-p <port>' option to vsyncapp.  If you don't have
   auto hotsync enabled, you will have to use the emulators HotSync menu
   to start a hotsync.

   NOTE: With Helio O/S 1.1.03 and the current vsyncapp, you have to
         manually remove the application from the emulator before you can
         load a new version.

   To remove an older version of your application, go to the Helio main
   application screen and click on the 'System Setup' icon.  From there,
   click on the 'System Information' icon.  From there, click on the
   'Delete Apps' button; select your application and delete it.


------------------------------------------------------------------------
Creating your own Skins
------------------------------------------------------------------------

Each skin for the emulator is made up of three files, stored in the 'skins'
subdirectory beneath the install directory. The three files are:

myskin.bmp - the bitmap image for the skin
myskin.map - a text file describing the location and shape of the buttons
myskin.skn - identifies the bitmap and map file to use

The .skn file is what appears in the options dialog. It contains the filenames
of the other two files. Here's a sample:

[Skin]
Bitmap=clear_blue.bmp
Map=clear_blue.map

The .bmp file is the image to use when displaying the emulator case. The map
file is formatted as a html map file which makes it possible to edit with any
html/graphic editor which supports maps. I use Fireworks but there are many
others. This file contains the location of important shapes on the bitmap:

'case' - the outline of the case.
'screen' - the location and size of the screen
'todolist', 'phonebook', etc. - the location of the hard buttons

Take a look at clear_blue.map to see how this is formatted if you're creating
one yourself. If you make any good-looking skins, be sure and mail us a copy!!

------------------------------------------------------------------------
References
------------------------------------------------------------------------

[SMR]
"See MIPS Run"
By Dominic Sweetman
Published by Morgan Kaufmann, 1999
ISBN 1-55860-410-3

* This is the *best* book on MIPS I've seen to date.  Lots of advice, tips,
  tricks and pitfalls discussed.


[MRA]
"MIPS RISC Architecture",
By Gerry Kane and Joe Heinrich,
Published by Prentice-Hall, 1992
ISBN 0-13-590472-2

* The ultimate guide to the raw instruction set and architecture


[PR31700UG]
"PR31700 Users Guide", v0.3, September 20th, 1998
Philips Semiconductors


[UCB1200UG]
"UCB1200 Users Guide", July 22nd, 1998
Philips Semiconductors


------------------------------------------------------------------------
Source Guide
------------------------------------------------------------------------

A brief collection of notes about the source code; unfortunately not
fully up to date at this time.  Funny how engineering type docs are always
the last thing to get done... This will be expanded in subsequent updates


   O/S abstraction services for the core
   -------------------------------------

   A thin wrapper over calls to appropriate native services.  These are not
   supposed to be full-blown abstractions; they just need to provide the
   basics, as per their useage in the emulator


   Persistent device sessions
   ---------------------------

   All physical devices (and some other things in the core) can be persisted.
   The persistence mechanism is (based on OS services) implemented as a
   read/ write memory mapped file.  Extensions can back their storage
   directly onto the mapped file (which is provided by the persist manager)

   This mechanism is more flexible than most traditional emulators, but when
   fully implemented, should mean start/ stop are fast, and more importantly,
   when the emu is started, it doesn't have to fall back on a hard-boot
   of the emulated device.


   Emulating target exceptions
   ---------------------------

   Target synchronous exceptions are emulated with host C++ exceptions.
   Asynchronous events (eg from UI etc) are picked up periodically from
   an event queue.  This is not checked every instruction in order to 
   reduce execution overhead


   Physical Memory extensions
   --------------------------

   These are registered thru the pmem APIs.  The registered extensions 
   will get correctly aligned read/ write calls.  The full 32-bit phys
   address space can be modelled, with independent views for 'kmode' and
   'umode' if necessary

   The address space is divided in coarse-grained lumps (currently 1Mb)

   Backend changes to the physical address space layout should be detected
   and the pmem interface notified.  It will in turn ensure that the core
   reflects the changes

   When invalid addresses are accessed, vector through the provided funcs
   in the pmem interface.  Based on configuration, these may return dummy
   values for reads of invalid addresses, or throw a host exception


------------------------------------------------------------------------
Porting
------------------------------------------------------------------------

This project hasn't yet been ported to non Win32 platforms.  There are
several caveats; notably there are missing 'hooks' for hosting on a
big-endian system, and obviously, there isn't an X User Interface
implemented... We hope to make it easier in subsequent updates

   General comments
   ----------------

   During development, we have tried to isolate portability issues in the
   emulator core, and to provide a framework to ease porting.  A port
   *has not* however been undertaken, and whats ther should be taken only
   as a guideline for the required work


   Host O/S requirements
   ---------------------

   The host must support multithreading, critical sections

   Memory mapped file support is highly desirable but sufficient hooks
   are available in OsMemMappedFile so that its possible to implement
   it by reading everything into a buffer and writing it back out later

   Check ossvc.h for details


   Compiler requirements
   ---------------------

   The C++ compiler must support *THREAD SAFE* exceptions

   The C++ compiler must support templates

   If you are doing an optimised build, be careful of 'aliasing' bugs.  There
   are several cases where assuming no aliasing will break down, though at
   present, they should only occur across function calls.  Specifically,
   the SVMemMap structure, and the attached insn cache has demonstrated
   problems (often showing up as crashes in the Insn cache queue insert/ remove
   functions).

   So far, its been tested with 'assume no aliasing, but assume aliasing can
   occur across function calls' and run correctly (VC++ -Oa -Ow switches)


   Endian swapping issues
   ----------------------

   The bit-fields in the unions for I/O registers may need to be reversed
   depending on the host compiler and host endianness.  Theres a config
   option in <config.h> to describe the host compilers behaviour

   The virtual memory system is not yet capable of dealing with endian
   swapping.  Mostly, the relevant parts of the code have #error marks
   to indicate them.


------------------------------------------------------------------------
Limitations
------------------------------------------------------------------------

This isn't all of them, but its a start...

Doesn't emulate flashable memory yet

Doesn't emulate 3910 single-step mode yet

Doesn't emulate 3910 $config halt/doze mode; just ioreg doze/halt

Timers do not run precisely accurately and are CPU speed dependent since
they are largely tied to instruction execution rate.

