source: rtems/c/src/lib/libbsp/mips/genmongoosev/README @ 8536b67

BSP supporting the on-CPU capabilities of the Synova Mongoose-V.
The Synova Mongoose-V is a radiation hardened derivative of the
LSI 33K with on-CPU peripherals.

This BSP assumes that basic HW initialization is performed by PMON.

Status
======
Per-task floating point enable/disable is supported for both immediate
and deferred FPU context swaps.

Interrupt Levels are adapted reasonably well to the MIPS interrupt
model. Bit 0 of the int level is a global enable/disable, corresponding
to bit 0 of the processor's SR register.  Bits 1 thru 6 are configured
as masks for the Int0 thru Int5 interrupts.  The 2 software interrupt
bits are always enabled by default.  Each task maintains its own
Interrupt Level setting, reconfiguring the SR register's interrupt bits
whenever scheduled in.  The software ints, though not addressable via
the various Interrupt Level functions, are maintained on a per-task
basis, so if software manipulates them directly, things should behave as
expected.  At the time of these udpates, the Interrupt Level was only 8
bits, and completely supporting the global enable, software ints and the
hardware ints would require 9 bits.  When more than 8 bits are
available, there is no reason the software interrupts could not be added
to the Interrupt Level.

While supporting the Int0 thru Int5 bits in this way doesn't seem
wonderfully useful, it does increase the level of compliance with the
RTEMS spec.

Interrupt Level 0 corresponds to interrupts globally enabled, software
ints enabled and Int0 thru Int5 enabled.  If values other than 0 are
supplied, they should be formulated to impose the desired bitmask.
Interrupt priority is not a strong concept on this bsp, it is provided
only by the order in which interrupts are checked.  

If during the vectoring of an interrupt, others arrive, they will all be
processed in accordance with their ordering in SR & the peripheral
register.  For example, if while we're vectoring Int4, Int3 and Int5 are
asserted, Int3 will be serviced before Int5.  The peripheral interrupts
are individually vectored as a consequence of Int5 being asserted,
however Int5 is not itself vectored.  Within the set of peripheral
interrupts, bit 0 is vectored first, 31 is last.

Interrupts are not nested for MIPS1 or MIPS3 processors, but are
processed serially as possible.  On an unloaded 50 task RTEMS program,
runnning on a 12mhz MIPS1 processor, worst-case latencies of 100us were
observed, the average being down at 60us or below.


These features are principally a consequence of fixes and tweaks to the
MIPS1 and MIPS3 processor support, and should be equally effective on
both levels of MIPS processors for any of their bsp's.

Address Map
===========
This is the generic address map of the Mongoose-V prototyping board
this BSP was tested on.

0x8000_0000 - 0x8FFF_FFFF   - RAM (KSEG0 cached)
0xA000_0000 - 0xAFFF_FFFF   - RAM (KSEG1, same memory uncached)
0xBFC0_0000 - 0xBFFF_FFFF   - EEPROM
0xFFFE_xxxx                 - on-CPU peripherals

This is the hardware address map of the board used as it was
actually populated.

0x8000_0000 - 0x83FF_FFFF   - 32 MB RAM (KSEG0 cached)
0xA000_0000 - 0xA3FF_FFFF   - 32 MB RAM (KSEG1, same memory uncached)
0xBFC0_0000 - 0xBFDF_FFFF   - 2 MB EEPROM
0xFFFE_xxxx                 - on-CPU peripherals

This is the organization of the EEPROM when fully populated.  Since
the board used to develop this BSP only had the first bank of EEPROM
populated, only the first program image area was used.

0xBFC0_0000 - 0xBFC3_FFFF   - PMON
0xBFC4_0000 - 0xBFC4_FFFF   - reserved for boot loader
0xBFC5_0000 - 0xBFDF_FFFF   - reserved for program 1 image
0xBFE0_0000 - 0xBFFF_FFFF   - reserved for program 2 image

The Mongoose-V on this board is at 12 Mhz.

Downloading
===========

On the breadboard, a locally hacked PMON waits for a space to be pressed
while the board is reset/powered up.  If found, the PMON console is
entered, else PMON jumps to the EEPROM address above, presuming a user
program is located there.

The default output of an RTEMS link is an image linked to run from
0x80020000.  It is suitable for copying to S3 records or can be burned
to ROMs in whatever manner the user desires.  If you want to locate the
image into ROM at some other address, use mips-rtems-objcopy to shift
the LMA.

Operation
=========

A small relocator is supplied in the bsp startup code which copies the
image down to RAM for execution before doing any other initialization.
This locator code is location independent, and will do nothing if the
image is already located at its run location.  The LMA and VMA are both
controlled via the bsp's link script.  The above behavior is produced by
using the default script.  If this is not desirable, something like the
following may be added to the user's RTEMS link statement to override
the default linkcmds with a user-supplied version;

-qnolinkcmds -Wl,-T -Wl,mips-rtems-linkcmds-eprom

this causes the file ./mips-rtems-linkcmds-eprom to override the default
linkcmds.

Before relocating the RTEMS image, the bsp startup routine attempts to
configure the processor into a rational state.  During this process,
status characters are emitted at 19200N81 on UART port 0.

The default link script simply places the image at 0x8002000 with
LMA=VMA, which is conviently located in RAM on our board.  You should
probably consider creating your own linkcmds, putting things where you
want and supply it as above.  

The Mongoose V has a somewhat restricted cache configuration model; you
can only flush it if the code which does so executes within noncached
memory, in our case, code in kseg1.  If you do so from elsewhere the
code will appear to lock up, this is caused by the cache clearing
routine making the instruction fetch always return 0, or nop- leaving
the processor in an endless loop.  The default start.S code detects if
its booting from outside kseg1, it which case it disables the cache
flush code.  This means you cannot flush the cache with the bsp's
functions if you boot your program from outside kseg1.  A more subtle
issue is the bsp keeps a pointer to the location in kseg1 where the
bsp's cache flush code resides.  This is advantageous because you can
relocate the system anywhere and still control the cache, but might
cause trouble if the boot image becomes inaccessible.  If this is
possible, you should probably consider rolling your own cache control &
disabling the bsp's.

As stated above, if you boot from outside kseg1, the bsp disables the
cache flush routines.  This is not desirable in the long run because the
Mongoose V remote debugger stub assumes it can flush caches when exiting
an exception so it might not be able to update code/data properly,
though it should still nominally function.  However, if you're not using
the remote debugger & don't care about flushing caches, then everything
should run just fine.

Our approach has to been locate ROM in kseg1, link the code for VMA in
RAM and relocate the LMA up into kseg1 ROM.  Since the start.S code is
position-independent, it will relocate the entire app down to the VMA
region before starting things up with everything in its proper place.
The cache clear code runs before relocation, so executes from ROM &
things work.

You can prevent including the default start.S by adding;

-qnostartfile

to the link command line in addition to the "nolinkcmds" options above.
Be sure to supply your replacement start.o.



Questions
=========

Why can I send characters slowly to a Mongoose V, but get framing errors
when sending them fast?

- The MongooseV chip seems to <require> that all incoming data have 2
  stop bits.  When typing on a serial terminal, this is not an issue
  because the idle state of an RS232 line looks just like a stop bit-
  but when streaming in data, such pacing is required.  The manual does
  not indicate anything along these lines, instead, we suspect a
  somewhat faulty UART design.


Debugging
=========

After getting Joel's initial port of the gdb stub to the Mongoose bsp, I
worked up & tested this stub on our R3000 board.  It seems to work OK.
Our MIPS has 2 serial ports, the first being dedicated to the console, I
chose to arrange the 2nd one for the remote gdb protocol.  While this
solution is somewhat specific to our board & bsp, I think the technique
is quite generalizable.

The following is a code snippet to be included in the user program;

/***********************************************/

extern int mg5rdbgOpenGDBuart(int);
extern void mg5rdbgCloseGDBuart(void);


void setupgdb(void)
{
   printf("Configuring remote GDB stub...\n");

   /* initialize remote gdb support */
   if( mg5rdbgOpenGDBuart(-1) != RTEMS_SUCCESSFUL )
   {
      printf("Remote GDB stub is disabled.\n\n");
   }
}

/***********************************************/

It allows the program to decide if it wants gdb to be ready to pick up
exceptions or not.  The 2 extern functions are located in the MongooseV
bsp inside gdb-support.c.  They configure & initialize the 2nd serial
port & invoke the vector initialization routine located in cpu_asm.
Note, we call directly down into the MongooseV UART driver- its quite
unfriendly to TERMIO.  I chose this approach because I wanted to
minimize dependence on the I/O subsystems because they might be in a
state just short of collapsing if the program had done something bad to
cause the exception.

If user code leaves the 2nd port alone, then things will work out OK.

Greg Menke
2/27/2002

============================================================================