Developer Support Notes
=======================

Version 1.0.  Prepared March 5th, 2000


This file contains a few notes and tips on how to use the Helio Emulator for
development.


Adding debug support to your application
----------------------------------------

In this directory, you should find emudbg.h and emudbg.c.  These files add
emulator-aware debugging capabilities to your application.  They are intended
to be compiled and linked into your application.  When your application
is running under the Helio Emulator, these etended capabilities are
enabled.  When running on the real Helio, they are disabled.


1) Add the emudbg.h and emudbg.c files to your project

   Copy the emudbg.h and emudbg.c files to your project source directory

   Edit your makefile to add emudbg.o to the list of object files that
   make up your application.

   When making a debug version of your application, make sure that the
   -DDEBUG switch is passed to the compiler.  When your application is
   built without the -DDEBUG switch, all of the emudbg macros are quietly
   compiled out of your code to reduce size.  When making your release
   versions, the -DDEBUG switch should be removed.

   You may wish to add a '#include "emudbg.h"' to all of your source files,
   or to some common include file you already have.


2) Let the emulator know about your application

   In one of your application sources, you will have an __main () function
   which needs to call DBG_APP_BEGIN () and DBG_APP_END () so that the
   debugger will be able to see all of your applications memory.  You
   should include "emudbg.h" in this module and update __main () to
   resemble this:

   int __main (WORD cmd, void *cmd_ptr) {
      DBG_APP_BEGIN ();
      DBG_BREAK ();
   	YourAppLaunch (cmd, (void*)cmd_ptr);
      DBG_APP_END ();
   }

   When your application is started, the DBG_BREAK () call will make it
   break to the GDB debugger if it is connected.  If GDB is not connected,
   then the application will continue running.  You can then use the
   GDB 'continue' command to resume execution.  You don't have to
   place DBG_BREAK () here; you can place it anywhere you wish.


3) Adding debug 'trace' statements

   At any point in your program, you can output messages to the Emulator
   Log Window with the DBG_MESSAGE () macro.  eg:

   DBG_MESSAGE ("I'm here\n");


   If you want to format the message, you will have to use sprintf ()
   yourself first. eg:

   #ifdef   DEBUG
      char sz [80];
      sprintf (sz, "Args are %d, %d\n", arg1, arg2);
      DBG_MESSAGE (sz);
   #endif


Using heliogdb with HelioEmu
----------------------------

If you are new to GDB, you can obtain the GDB documentation in HTML from
http://www.delorie.com/gnu/docs/gdb/gdb_toc.html among other places.
A full list of alternative sources can be found from the documentation
links on www.gnu.org

You will need to use the heliogdb.exe version of GDB, instead of the version
that is supplied with the VTech SDK.  heliogdb has support for debugging
over a socket connection, and also has the CPU registers configured correctly
for the Helio.  

1) What files are needed for debugging your app?

   If you are building your application based on the example makefiles with
   the VTech SDK, the make/ build will produce a number of output files.
   Linking your application will produce a 'main.obj' file, or you may have
   a main.exe file.  The 'chop' command will produce main.out.  In the
   examples, this is automated with build.bat.

   Finally, the AppBuilder utility will produce your final myapp.app file.

   In order to enable source level debugging, the main.obj or main.exe file
   is used with GDB


2) How do I load my app into the emulator?

   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.all

   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.


3) How do I start debugging?

   Once your app is loaded, start GDB and connect to the emulator.

   c:\project> heliogdb main.obj
   (gdb) target remote localhost:2000

   At this point, GDB will 'break in' to the emulator and freeze its
   execution.  Stack backtraces etc will not show any useful information
   since its most likely stopped in the operating system.

   Continue execution in GDB.  eg:

   (gdb) c


   Now, in the emulator, switch back to the main application page and
   click on your application.  Assuming that you have a DBG_BREAK () in
   your __main () function, then the application should break to GDB, and
   you will see a stack backtrace indicating its stopped in DbgBreak ()

   You can use the 'finish' command to return from DbgBreak () back to
   your __main () function.  From there on, you can use points, single
   step, examine and change data etc with all of the GDB commands.


4) How do I break into my program while its running?

   If you haven't started GDB, then starting GDB as in step 2 will
   break in.

   If you are running your app under GDB, pressing CTRL-C will usually
   break in and regain control.  

   You may have broken in while the Helio was running in the O/S, so
   your program symbols may not be visible.


5) How do I stop debugging?

   If you are currently stopped in GDB, then enter the 'quit' command.
   You will be prompted to ask if you want to detach from a running
   program.  Enter 'y'

   Once you do this, the emulator will resume execution.


heliogdb comments
-----------------

heliogdb is built using the Cygnus CygWin APIs.  As a result, it will
often prefer '/' instead of '\' as a directory separator.  Simularly,
it may not understand drive letters.  For example, c:\foo\bar.c may
need to be entered as '//c/foo/bar.c'.  This usually only affects
GDB commands for manipulating files and directories and is otherwise OK.


1) If you are trying to examine or change memory (eg using the 'print'
   command), and get an error that the location isn't accessible...

   Helio runs a virtual memory system.  As a result, some locations
   are not always 'visible' to GDB.

   The first step is to ensure that you have added the DBG_APP_BEGIN ()
   and DBG_APP_END () macros in your __main ().  These pass on information
   about your apps virtual memory configuration to the emulator that it
   would otherwise not have access to.

   If that fails, then enable remote protocol debugging and retry
   the command that is failing.  (In GDB, enter 'set remotedebug 1')
   When this is enabled, the GDB component in the emulator will report more
   information on the cause of failure and will describe the MIPS exception
   code that occurred.  You can then turn it off again with 'set remotedebug 0'

   If it reports a Bus Error or Address Error, then the address is incorrect
   or completely inaccessible on the Helio.

   If the reported error is TLB related, again, check that the
   DBG_APP_BEGIN () macros are in your __main () function, and you are
   building with the -DDEBUG compiler switch.

   If you are trying to inspect or modify memory that your application has
   dynamically allocated, you may need to add the DBG_REFRESH_MEM_INFO()
   to your code at the point where the allocation was made.  This
   updates GDBs knowledge of your applications virtual memory configuration.


2) The emulator is behaving strangely after debugging...

   GDB controls execution of your program by placing breakpoints into
   the emulators memory.  If there is an unexpected GDB or emulator
   error, or if you disconnect GDB abruptly (or shut down the emulator
   while GDB is still running), then those breakpoints may still be in
   memory and confuse the Helio O/S

   The best thing to do is to use the 'Reset' menu item on the emulator
   and start over with a fresh session file.


3) I'm debugging my app but when I broke in, I'm stopped in the O/S (eg,
   the stach trace just has addresses instead of function names)
   How  do I find where I am in my app?

   You can change the symbols that GDB sees using the 'symbol-file'
   command.

   You can switch to the O/S symbols, assuming you have the O/S built
   using (specify the path as appropriate for your machine):

   (gdb) symbol-file /vtsdk/vt-os/system/main.obj

   Once the symbols are loaded, you can use the backtrace command to see
   where you are.

   To revert to your application symbols, use

   (gdb) symbol-file main.obj


4) My application crashed and I didn't have GDB connected

   Hope may not be lost.  When this occurs, you should have an error message
   on the Helio screen indicating the address at which the crash happened.

   Typically, if this address starts with 0x1....... then it is an error
   in the application that was running.  If this happens to be your
   application, then start up a debugging session with your apps symbols
   as for a normal debugging session.  If you suspect the O/S (and have
   built the O/S), you can start up GDB with the O/S symbols.

   One way to help track down where it crashed is to disassemble the
   location that is on screen and examine the output to find the
   function containing it:

   (gdb) disas 0x10001020


   If you run your application under the debugger, it will break to
   GDB and give you a chance to debug it first.

   If all else fails, look for a nearby address in the map file that was
   generated when you built your application

5) Calling functions from GDB in my app is really slow

   Calling functions from the GDB command prompt is a really neat feature
   of GDB, but is creates a massive overhead to execute it safely. eg:

   (gdb) call MyFunc (3)

   This may take several seconds to complete, even if MyFunc () is an
   insignificant function.



Generating your own O/S ROM images
----------------------------------

If you're interested in testing new O/S versions on the emulator, built from
the VT-OS source code, you will need to generate a compatible emulator
ROM image and the corresponding device definition file.

This assumes you have built the O/S successfully (generating a PDA.BIN file)

Next, you will need to extract the first 64K from an existing .ROM file that
the emulator can already run (eg the devices\vt-os-1-1-03.rom), using some
utility, or your own program.  The resulting boot.bin and the batch file
below should be placed in the SDK vt-os\system build directory and run after
you have built the O/S to generate the files necessary for the emulator.

   rem Example mkemurom.bat file.  Assumes it is running in the vt-os\system
   rem build dir, and that boot.bin is available.  Generates new Custom-VT-OS
   rem files that can be placed in the emulators Devices subdirectory.

   gcs_bin pda.bin Custom-VT-OS.ok
   cs Custom-VT-OS.ok
   copy/b boot.bin+Custom-VT-OS.ok Custom-VT-OS.rom
   del Custom-VT-OS.ok

   echo>Custom-VT-OS.dev [Device]
   echo>>Custom-VT-OS.dev rom=Custom-VT-OS.rom
   echo>>Custom-VT-OS.dev type=0
   echo>>Custom-VT-OS.dev romtype=0

Finally, copy the resulting Custom-VT-OS.* files to the Devices subdirectory
where the emulator is installed.  The next time you start the emulator,
the new O/S should appear on the Devices list on the Options dialog.
