PORTING XMK TO A NEW HARDWARE PLATFORM
==============================================================================
General instructions porting XMK to a target  platform.  NOTE: ONLY the
services listed in this file have dependencies on the target platform and
require porting.


Porting the Kernel (xmk/kernel.h)
------------------------------------------------------------------------------
TIP: Use the xmk/platform/hitachi/h8300l/kernel as your example and/or guide!

1. Create a new platform specific directory tree under the xmk/platform/
   directory.

2. If neccesary provide any platform specific modfications to XMK's 
   basic types (xmk/types.h).  This modification should be in a single
   header file somewhere in your platform directory tree.  It will eventually
   be included by the project's xmkcfg.h header file.

3. The following platform specific methods must be implemented.
        PAL__XMK_disableInts()
        PAL__XMK_enableInts()
        PAL__XMK_areIntsEnabled()
        PAL__XMK_createThreadStackFrame(t,f,s);
        PAL__XMK_fromThreadContextSwitch()  
        PAL__XMK_fromISRSwitchContext()
        PAL__XMK_startIdle()
    Typically, enable/disable interrupts will map to inlined assembly
    or compiler specific intrinsic functions.  The remaining functions will
    probably need to implemented in assembly (with the possible exception of
    PAL__XMK_createThreadStackFrame()).

4. Define the macro _XMK_TOP_OF_STACK(b,s).  This macro is platform specific
   since it contains the information if the stack uses a pre/post decrement
   scheme.

5. Create two interrupt vectors stubs to be used as the templates for building
   the application's interrupt vector table.  One template for non-nested
   interrupts, and the second for nested interrupts.  This will typically be
   done in assembler.

6. Perform a stack analysis on the platform specific code to provide the 
   the values for the following #defines (in .../palkrn.h):
        XMK_ISR_KERNEL_OVERHEAD     
        XMK_ADDER_STACK_APP_THREAD  
        XMK_ADDER_STACK_IDLE_THREAD 

7. Perform a stack analysis on the compiled code of ./schpri/... directories to 
   provide the platform specific value for the following #define (in the
   src/config/<platform>/pal-<xxxx>.h header file):
        XMK_ADDER_SCHPRI_ISR_STACK



Porting the System Timer (xmk/tmsys.h)
------------------------------------------------------------------------------
TIP: Use the xmk/platform/hitachi/h8300l/tmsys as your example and/or guide!

1. Create a new platform specific directory tree under the xmk/platform/
   directory.  The new directory should be a peer to the 'kernel' directory
   created when porting the scheduler.

2. The only platform dependent code for System Timer is in suppling the
   templates for the ISR that drives the timer.  Create two interrupt vectors 
   stubs (non-nested and nested) to be used as the templates for building the 
   application's ISR that is used for the system timer.

3. Perform a stack analysis on the compiled code of _Xmk_sysTickISR() to 
   provide the platform specific value for the following #define (in the
   src/config/<platform>/pal-<xxxx>.h header file):
        XMK_ADDER_TMSYS_ISR_STACK



Porting the System Timer (xmk/sleep.h)
------------------------------------------------------------------------------
TIP: Use the xmk/config/hitachi/pal-h8300l-hew2.h as your example and/or guide!

1. There is no platform dependent code for this interface.
2. Perform a stack analysis on the compiled code of _Xmk_sysTickISR() to 
   provide the platform specific value for the following #define (in the
   src/config/<platform>/pal-<xxxx>.h header file):
        XMK_ADDER_SLEEP_ISR_STACK



Porting the Extended Thread Interface (xmk/xthread.h)
------------------------------------------------------------------------------
TIP: Use the xmk/platform/hitachi/h8300l/xthread as your example and/or guide!

1. Create a new platform specific directory tree under the xmk/platform/
   directory.  The new directory should be a peer to the 'kernel' directory
   created when porting the scheduler.

2. The following platform specific methods must be implemented.
        PAL__XMK_createThreadStackFrameEx()
    PAL__XMK_createThreadStackFrameEx() is very similar to 
    PAL__XMK_createThreadStackFrame(), except that it has the added 
    responsiblity of pushing a thread-exit-handler onto the stack frame.
    It is recommended that you create a method: PAL__Xmk_pushExitHandler(),
    that just creates the necesarry stack frame for an exit-handler.  Then
    the implementation of PAL__XMK_createThreadStackFrameEx() is simply a matter
    of first calling PAL__Xmk_pushExitHandler() and then calling
    PAL__XMK_createThreadStackFrame().

3. Perform a stack analysis on the thread-exit-handler to provide the 
   the values for the following #defines (in .../palxthr.h):
        XMK_STACK_EXIT_HANDLER   


Setting the platform specific configuration
------------------------------------------------------------------------------
Provide the default platform speficic config header file and build list for 
the new platform.  These confg files will be located under the 
src/xmk/config/ directory tree.  

TIP: Use src/xmk/config/hitachi/pal-h8300l-hew2.[h|b] as an examples.