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 example source and its makefile in
/mc/demos/example.

Step2:
Make your own dir under /mc/demos and copy over the provided Makefile
(or Makefile.dos) and main.c.

Step3:
Change the Makefile, were it is marked, to your needs i.e. the name
your program shall have and the objects you want to be linked.

Step4:
Modify and expand the main.c to your needs and/or add further source
files or libraries.

Size restriction:
Your program must fit into ram space. That means at the moment it must
be smaller than 100kB (128kB RAM is available, but leave space for
heap and stack).  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

VI.) How to use more ROM/RAM:
-----------------------------

RoBiOS was developed on an Eyebot Platform with 128Kb Flashrom and
256kB RAM and thats the default configuration.  The Eyebot Platform
can be expanded to a maximum of 512kB Flashrom and 1024Kb RAM.  RoBiOS
should run on a RAM-expanded system and automatically use the
additional RAM.  By using a 4MBit flashrom the upper 3 MBit (384KB)
are managed by RoBiOS to store up to three user programs. This can be
controlled in the 'USR'-menu of RoBiOS.
