ReadMe to the MicroC/OS-II Port for the M16C/60
***********************************************

    (c) Copyright 2003 by Florian Stassen
    email: ucos-ii@develop4u.de

    This file is part of my M16C/60 port for MicroC/OS-II.

    My M16C/60 port for MicroC/OS-II is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, Version 2, as published by
    the Free Software Foundation.

    My M16C/60 port for MicroC/OS-II is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Foobar; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


History
-------
Version 1.00:
  started 2003-01-18
  last change: 2003-04-01


Introduction
------------
I wrote this Readme for myself during porting MicroC/OS-II to the M16C/62A.
I wrote down my ideas, my problems I found, my thoughts.
So the order is more chronical than by thematic.

The port depends to the MicroC/OS-II Version 2.52.

Feel free to contact me any time with questions and enhancements
related to this port.
email: ucos-ii@develop4u.de


Directory Structure
-------------------
\SOFTWARE\UCOS-II\M16C\NC30WA\SOURCE
  Files ported for the M16C/62A as described in Jean's book.

\SOFTWARE\UCOS-II\M16C\NC30WA\TEST1
  A Testapplication to check my sources and to show times for task switch

\SOFTWARE\UCOS-II\M16C\NC30WA\TEST1\BENCHMARK
  Hardcopies from the logic analyser while running TEST1

\SOFTWARE\UCOS-II\M16C\NC30WA\APPLICATION TEMPLATE
  Files which you need for a new project


Files
-----
I moved all hook functions from OS_CPU_C.C into OS_CPU_HOOK_C.C.
So the files OS_CPU_C.C, OS_CPU_A.A30 and OS_CPU.H are project independet.
OS_CFG.H and OS_CPU_HOOK_C.C depends to the project.

In the port directory (\software\ucos-ii\m16c_60\mc30wa\source) are the files which are port specific,
but not application specific. In directory "Application Template" are standard files for a new
application.

In subdirectory "Test1" I make my test application.
There is also startup code (ncrt30.a30, sect30.inc, inittab.inc) and code for the
timer tick and its ISR. I use timer B5.


Basics to the M16C, the NC30WA compiler and the port
----------------------------------------------------
A PUSH first decrements the SP and then stores the data.
A POP first reads the data und then increments the SP.
The stack can be addressed in bytes, also with PUSH and POP.

Interrupt calls (hardware or software) with vectornumbers less than 32
the U-flag will be cleared so the ISP is used.
With other vectornumbers the U-flag is unchanged.
I-flag (Interrupt Enable) and D-flag (Debug) are always cleared.
All hardware interrupts have vectornumbers less than 32.

ISP and USP will be used.

Parameter pdata in the task functions is passed through register R1.

I use the NC30WA Compiler Version 4.00 release 2.
Defaults of the compiler:
pointers are near (16 bit)
const data are far (32 bit)
code is far


Interrupts and InterruptServiceRoutines
---------------------------------------
Don't mark a function as interrupt for the compiler.
Do it by yourselve !

ISR input sequence:

xxx_ISR:
    PUSHM       R0,R1,R2,R3,A0,A1,SB,FB         ; Save current task's registers

    JSR         _OSIntEnter                     ; OSIntEnter()
    CMP.B       #1,OSIntNesting                 ; if (OSIntNesting == 1) {
    JNE         xxx_ISR1

    MOV.L       OSTCBCur, A0                    ;     OSTCBCur->OSTCBStkPtr = SP
    STC         ISP, [A0]

xxx_ISR1:

    your ISR Code
    .....


ISR output sequence:

    JSR         _OSIntExit                      ; OSIntExit()

    POPM        R0,R1,R2,R3,A0,A1,SB,FB         ; Restore registers from the new task's stack

    REIT


When enter the ISR the ISP is active and the registers are stored on the interrupt stack.
_OSIntExit() tests if a context switch is necessary. If yes in function OSIntCtxSw() the
registers have to be copied to the user stack and the USP corrected. Then we have the same state
as in a normal context switch.
Also the ISP have to be cleaned as the ISR has normally finished.


Compiler optimation "stack_frame_align"
---------------------------------------
I normally use the optimation for "stack_frame_align".
The M16C/60 stores 3 bytes on the stack when calling a subroutine.
With this optimation the compiler stores one dummy byte on the stack so the auto variables
are on a 2 byte alignment.
When a task is started for the first time this dummy byte shifts the SP to an odd address.
To compansate this OSTaskStkInit() builds the initial stack on an odd address. When the task
starts this stack frame will be removed and the SP stay on an even address.


Testenviroment
--------------
MicroC/OS-II: V.2.52
Compiler: NC30WA V.4.00 R2
Compiler-Flags: -c -I$(PRJDIR) -dir $(OUTDIR) -v -g -OR -O5 -OC -OSFA -fER -Wall -dS -DREMOTE_MONITOR=2 -DM16C62A -fETI -finfo -dSL
Debugger: KD30 V3.00 with monitor programm on target
Project Control Programm: TM V.3.10
CPU: M16C/62A (M30624FGAFP), 16 MHz
EVA-Board: from German Distributor Glyn (www.glyn.de)


Credits
-------
Farshad Nourozi for his port to the M16C.
  It shows me very fast to read the book first.

===========================================
EOF
