README.TXT

	    Motorola Coldfire MCF5307 port to MicroC/OS-II

1. General Notes
1.1 Files included

    The following files are included in this release:

    README.TXT		This file
    MCF5307\		Port folder
      os_cpu.h		Port include file
      mcf5307.h		Definitions of on-chip registers
      os_cpu_a.s	Port assembly source
      os_cpu_c.c	Port C source
    EX_MCF\
      makefile		NMAKE Makefile to build sample
      main.c		Example startup, hardware init, etc
      test.c		Example task
      includes.h	Project central include file
      os_cfg.h		OS configuration include file


1.2 Development Environment

    This port has been developed with the Diab Data C compiler
    version 4.2a, the SDS SingleStep BDM debugger version 7.3, and
    the Arnewsh SBC5307 evaluation board.  Since I am also a Windows
    developer and have Microsoft tools installed on my NT box, I have
    used NMAKE for project maintenance.  The included example program
    includes an NMAKE makefile which may be readily configured for
    other projects.

1.3 Writing ISRs

    The implementation of OSIntCtxSw() requires that a constant
    adjustment be made to A7 to find the stack frame at the time of
    the interrupt in order to correctly handle context switches. This
    has two consequences.

    First, *all* ISR routines which call OSIntEnter() must put the
    stack in a state similar to that supplied by OSTickISR().  That
    is, the exception frame generated by the CPU is immediately
    followed by a save of D0-D7 and A0-A6, and A7 points to the saved
    value of D0 at the lowest address.

    Second, either the -X36=1 compiler option must be used or the
    constant offset supplied by OSIntCtxSw() must be modified. As
    Jean Labrosse points out, this offset is a common source of
    trouble, all the more so since it can be affected by compile time
    options.

1.4 Enabling the timer

    The example code shows how to setup TIMER1 on the MCF5307 to act
    as a 100 Hz tick interrupt source.  This port assumes that your
    code does this setup, hooks the correct vector, and enables the
    timer in the first task executed by the call to OSStart().

    The example demonstrates one way to do this.

1.5 Mystery exceptions from MCF5307

    The ColdFire seems to occasionally generate an incorrect
    exception frame unless the internal chip select module is
    completely setup.  At a minimum, make certain that CS0 has valid
    settings. This is done for you by dBUG in the Arnewsh card, but
    may not be done completely by the SingleStep configuration.
    Again, the example code shows how to do this.  There is also a
    workaround involving the MPARK register shown in the example. See
    the function EarlyInit() in main.c for comments and details.

2. Extensions to MicroC/OS-II porting model
2.1 Returning from a task function

    This port arranges the stack frame generated by OSTaskStkInit()
    to contain a return address from a faked call site. This allows a
    task function which accidentally exits to take some well-defined
    action on that failure, such as displaying a message, halting, or
    simply deleting the task and continuing.

2.2 CPUSetSR() inline function

    If the Diab compiler is used, then an inline function is defined
    in os_cpu.h which permits the SR to be modified. The CPUSetSR()
    function takes an INT16U value which will be loaded into the SR.
    Be careful to always include the S bit in that value, or you may
    end up in user-mode hell with no way back!  The return value from
    CPUSetSR() is the prior value of the status register.

    If the macro OS_CPU_CAREFUL_CRITICAL is defined in includes.h
    ahead of the inclusion of os_cpu.h then the OS_ENTER_CRITICAL()
    and OS_EXIT_CRITICAL() macros will use CPUSetSR() to save and
    restore the current SR value around critical sections.  This is
    potentially important for ISRs which need to make system calls
    without lowering the priority level to zero.

3. Support and Company Plug
3.1 Support

    I will try to answer email about this port to the extent that my
    current crash project allows.  In addition, Cheshire is available
    on a consulting basis for projects of nearly any scale.  See our
    web site for more information about us and our capabilities.

3.1 Credits

    MicroC/OS-II is the long-awaited update to uC/OS by Jean
    Labrosse. Find out more about it, get the book and sources, or
    find other ports at the official web site: www.ucos-ii.com.

    This port to the ColdFire MCF5307 is by:

    Ross Berteig
    Cheshire Engineering Corp
    650 Sierra Madre Villa, Suite 201
    Pasadena  CA 91107
    +1-626-351-5493       +1-626-351-8645 FAX
    Ross@CheshireEng.com, www.CheshireEng.com

    Copyright (C) 1998 Cheshire Engineering Corporation.
    Based on a port to uCOS version 1.x by David Fiddes.
    Portions Copyright (C) 1997 David Fiddes, D.J.Fiddes@hw.ac.uk
    Anything that no longer works is probably not his fault.