This is a HOWTO collection. 
===========================

          I.) How to write your own user/demo programs
         II.) How to write RoBiOS system routines
        III.) How to download user programs
         IV.) How to load RoBiOS into flashrom
          V.) How to flash the HDT
         VI.) How to use more ROM/RAM

I.) How to write your own user/demo programs:
---------------------------------------

Step1:
Take a close look at the provided sample programs.
All you need to do is   #include "eyebot.h"
then use any of the RoBIOS library routines in your
C or C++ program.

Step2:
Compile your program with the shell script (or DOS batch file)
gcc68 myfile.c


Alternative:
Use a Makefile when writing larger application programs,
which use more than one source file (see example programs).

Size restriction:
Your program must fit into ram space. That means at the moment it must
be smaller than 896kB (128kB RAM is used for the RoBIOS operating
system). The real size of your code is not the size of the
coff binary but around half the size of the .hex file plus the size of
variable space. Consider this if you use large arrays. They need RAM !


II.) How to write RoBiOS system routines:
-----------------------------------------

Step1:
Take a close look at the available system routines. At the source files in
mc-src/robios and the stubs and header files in mc/include/librobi/
Functions which do not transfer parameters the C way (on the stack),
should be named func_ASM to avoid calling them from C by accident.

Step2:
Create a new source file (.c or .s) and write your routines into it.
If you are writing assembler routines don`t forget the .section
directives, make your routines global and use the SAVEREGS/
RESTOREREGS macros.  Add the new file with .o extension to
mc-src/robios/Makefile.

If you write C code, do like this, and add the source file to
mc-src/Makefile and run 'make stubs'.

  #include "librobi/impl.h"

  USER_FUNC(MY, Test, XXX, int, (int value))
  {
     return value;
  }

This will make a function 'int MY_Test(int value)' available and add
the required prototypes to the headerfiles and make the userlevel stub
for a function int MYTest(int)'.  XXX must be replaced with the number
fetched from boot.s in step 3.

Step3:
Insert your routines into the jump table in mc-src/robios/boot.s.  If
you wrote a C routine, move to step 5. Step 4 is done automatically
when you run 'make stubs' in mc-src/.

Step4:
If you write in assembly, it becomes a little bit tricky as you have
to create the stubs for your routines in mc-src/robios/asmstubs.c.
Stubs for C routines are done automatically if you do as described
earlier.

Assembler routine stubs are a bit more complicated as you
have to map the parameters to registers:

  USER_FUNC(LCD, Mode, 48, int, (int mode))
  /*                   ^^ jump offset from boot.s */
  {
  /* add registers for your parameters here */
        register int rd1 __asm("%d1"); /* param 'mode' */
        register int res __asm("%d0"); /* return value */


  /* add the assignments here */
        rd1 = mode;

        __asm __volatile ("jsr LCD_Mode_ASM"
  /*                           ^^^^^^^^^^^^ The assembly function */
        : "=r" (res)
  /* add the used registers here */
        : "r" (rd1)

        : "%d0", "%d1", "%a0", "%a1","memory" );
        return res;
  }

You have to add the definitions of the registers you want to use
and assign the values to them.

Step5:
Run 'make stubs' in mc-src/.

ATTENTION !
If you are writing hardware device drivers make sure that they use the
HDT concept.  For further details look at /mc/HDT.


III.) How to download user programs:
------------------------------------
under DOS or Win95:
        - connect the serial cable (interface 1 or 2)
        - use the kermit.tgz (dos) package or hyperterm (win95)
        - terminal settings should be:
                /Baud Rate = 57600         (or 115200 with interface2)
                /Data Bits = 8
                /Parity = None
                /Stop Bits = 1
                /Flow Control = RTS/CTS
        - type "transmit <filename>" in kermit or choose the right menu
                in hyperterm (sorry don`t remember the name :)
under Unix:
        - connect the serial cable (interface 1 or 2)
	- run 'dl <filename>'


IV.) How to load RoBiOS into flashrom:
--------------------------------------
under DOS or Win95:

        - use the bdm.tgz package, unpack it and copy robios.hex to
                the bdm drawer
        - connect the board with the debugger cable to your PC
        - start bd32
        - type "stop" and press reset on the board
        - type "do mapcs"
        - With a 1MBit flashrom installed type
	        "flash 11111110 robios.hex 0"
          With a 4MBit flashrom installed type
	        "flash 11000000 robios.hex 0"
        - after some time the prompt should return and the new bios is
                flashed ( on a 386SX20 it takes over 30 minutes, so
                use a fast PC :)

since V1.4 of RoBiOS there is an easier way to update the RoBiOS:
        - download robios.hex just like a normal user program
        - RoBiOS detects automatically the new RoBiOS and flashes it
        

V.) How to flash the HDT:
-------------------------
under DOS or Win95:

        - use the bdm.tgz package, unpack it and copy hdtdata.hex to
          the bdm drawer
        - connect the board with the debugger cable to your PC
        - start bd32
        - type "stop" and press reset on the board
        - type "do mapcs"

        - With a 1MBit flashrom installed type
                "flash 00000001 hdtdata.hex $1c000"
          With a 4MBit flashrom installed type
                "flash 00100000 hdtdata.hex $20000"
        - after some time the prompt should return and the new hdt is
                flashed

since V1.4 of RoBiOS there is an easier way to update the HDT:
        - download hdtxxx.hex just like a normal user program
        - RoBiOS detects automatically the new HDT and flashes it

