cmxread.doc

CMEX source code RTOS for atmel atmega128

**************************************************************************
*									 *
*                 Supplemental Documentation File 			 *
* 	  for CMX version IAR AVR version 5.30 as of 10/27/99 		 *
*		    Copyright(c) CMX Co. 1999.				 *
*	     Also this release includes CMXBug ver 1.1			 *									 *
*	   Also this release includes CMXTracker ver 1.0		 *									 *
*									 *									 *
**************************************************************************

TRADEMARKS:
IAR is a trademark of IAR Systems AB.
CMX is a trademark of CMX Co.

************************************************************
			WARNING:

	The biggest error that user does, is forget to use the
CMX cxtend function just before the task end brace. This MUST
be done, unless the task will NEVER execute it's end brace. If
this is not done, serious undesirable consequences may and will
happen.

************************************************************
************************************************************
			WARNING:
 All the CMX source code, was compiled or assembled by the
above IAR Compiler, Linker, Assembler, and Librarian versions.
ALL CMX "C" demo modules (functions) were compiled with the
-ms -v3 (produces SMALL code for MEGA103).
If the user is working with a different memory
model, then the mkavr??.mak file must be used to declare the
proper memory model, and then follow the steps outlined below.
If the user has different versions of IAR versions then above,
then they MUST use their version to compile ALL CMX functions, ALL CMX
assembly files, and use the Librarian to create a new CMX library.
This is not hard to do. Just run the make.exe on the mkavr??.mak file
for the memory model that the user would like and then re-assemble 
the cxsk53s.s90 file. 

Also the supplied sample programs are tailored for the mega103 processor.
This is in regards ONLY to the vector addresses. Please see the cmxstrtm.s90
module, which sets the 16 bit timer interrupt vectors. 

**************************************************************

NOTE: user may want to print this document out. It is suggested that the
printer be in the compressed mode and then perform the next step:
COPY readcmx.doc LPT1	
	or
COPY readcmx.doc LPT2	

NOTE: All users should read this whole document, even if all does not apply.


For users working with IAR compiler.
_____________________________________________________

****************************************************************
WARNING: All interrupt code should be written in only assembler  
to ensure proper saving and restoring of the contexts. The user
should read the AVR processor specific chapter, that explains
how to work with interrupts and the CMX interrupt pipe. The interrupt
code is then free to call a "C" coded routine if they want to.
Must follow IAR rules for interrupts with regard to "C"
functions and library functions. 
****************************************************************

NOTE: The CMXBug and CMXTracker must NOT be linked into an application 
program together. This means one or the other may be linked in, but
not both at the same time.

Working with the IAR linker.
_____________________________________________

	CMX needs external ram. The amount needed is determined by the
questions answered by the user when works with the cxconfig.h file.

	CMX needs code space. Again the amount needed is determined by
the user. If a call is made to access a function out of the lbavr3s library, 
that particular module will be linked in.

The following should be linked in for CMX to perform properly

1. the cmx_init.c (or copy of cmx_init.c file) which includes the
file cxconfig.h (or copy of cxconfig.h). Make sure the cmx_init
file gets compiled if any change is made to it's cxconfig.h file

2. the file cxsk53s.s90 which is the CMX assembly file, that does 
the context switching, interrupt handler, CMX timer task, etc. 

3. The user should also specify the proper CMX library lbavr3s.r90 
file, which contains all the CMX library calls (for that memory model)

4. IAR "C" library for the proper "C" memory model.

5. all user's modules that pertain to the program that the user is creating

NOTE: it is advisable for the user to create a username.xcl file
which is a command file that the linker will read and process, so the
user does not have to specify all the link options when linking. This
command file creation is descibed in detail in the IAR manual.


For all users:
______________

******************************* UPDATE ********************************

	The cxconfig.h file has 4 additional "defines" that are not
explained in the manual. The defines are shown below and a description
of each.

#define CMXBUG_ENABLE 0	/* ENABLE or DISABLE CMXBug(TM) inclusion.
			Set to 1 to ENABLE, set to 0 (zero) to DISABLE
			The use still must link in cmxbug.obj, for the 
			CMXBug code to be functional, if set to 1 */

#define CMX_RAM_INIT 0	/* ENABLE or DISABLE the initialization of CMX RAM
			variables. Usually done by Compiler start up code
			in most cases. If not, MUST be ENABLED. Normally
			compiler code will set GLOBAL variables that are
			initialized and set non-initialize variables to
			0 (zero). Set to 1 to ENABLE CMX code to initialize
			it's variables, set to 0 (zero) to DISABLE */

#define CMXTRACKER_ENABLE 0 	/* ENABLE or DISABLE CMXTracker(TM) inclusion.
				Set to 1 to ENABLE, set to 0 (zero) to DISABLE */

#define CMXTRACKER_SIZE 4096 	/* SIZE IN BYTES of the buffer to hold the 
				CMXTracker COMPRESSED information. */

	Also the function cxtname has been added, to allow the user
to NAME a task, thus helping the user to know what task is what, when
the user is working with the CMX CMXBug debugger. The function prototype
and an example is below.

byte cxtname(byte task_slot,char *name);

	Where task_slot is the task's slot of the task they are
	about to name.

	Where name is the address of where this task names resides.

	There are 2 values that are returned. The value AERR indicates
	that the task slot number supplied, has not been created yet or
	that the task has been removed. The value AOK, indicates that
	this function was successful.

	NOTE: The task MUST have been created first, with the cxtcre
	function, before naming this task.

Example:
	status = cxtcre(5,&task1_slot,task1,128);	/* create task 1 */
	status = cxtname(task1_slot,"TASK1");		/* Name for task */


The cmx_tic function has been moved from the CMX library and now
resides in the cmx_init "C" module. This was done to better support
the CMXBug debugger.

The following functions have also been added to the cmx_init "C" module
to also support the CMXBug debugger:

void setup_bug(void);
byte bug_getchr(byte *ptr);
void bug_putchr(char);

Also there are other CMX variables that have been added to cmx_init "C" 
module to also support the CMXBug debugger:

long stat_array[CC_MAX_TASKS+1];
char *task_name[CC_MAX_TASKS + 1];
byte CMXBUG_ACTIVE;
byte BUG_WAIT_TICKS;

The most the user will possibly need to modify are the following, which
really only effect how the CMXBug debugger interfaces to the UART and
the number of ticks to wait, before seeing if the CMXBug wake char is 
present. NOTE: all the following reside IN the cmx_init.c "C" module.

BUG_WAIT_TICKS = 10;	/* located in cmx_init function */

setup_bug function: user is free to modify BAUD rate, BAUD rate generator
and what ever to meet their debugging needs.

**********************************************************************

	The user should read the manual COMPLETELY, before attempting
to work with CMX. The "processor specific chapter is of critical
importance.

	The user should study the examples shipped by CMX. The user should 
try initially small and non-complex programs, as to understand how
CMX works and ties together with the IAR "C" compiler, linker,
assembler, and librarian.

	The user should study the cmxsamp.c and cmxsampb.s90 files that 
shows the user, 1 way to create the scheduling frequency with the timer 0
(one) interrupt. It is up to the user to create the CODE for invoking 
the CMX cmx_tic call and choosing their specific scheduling frequency.

	Below is a list of all files shipped by CMX and an explanation
of each.

 FILE:
version.cmx	;Text file which shows what version of CMX is supplied
		;Should not be modified, Used for telephone support only

cxconfig.h	;This file is edited by the user and is the configuration 
		;file. (note: could be a copy of this and renamed).
		;Each time this or a copy of this file gets edited and 
		;changes made, the user MUST compile the cmx_init.c file
		;which includes this file. NOTE: if the user creates or
		;has a copy of this file under a different name, they
		;should go in to the cmx_init.c file (or copy) and change
		;the #include to bring in the proper .h module.