#\:::  ************************************************************
##\::  Mosaic Industries Kernel Extension Manager Readme File
###\/  http://www.mosaic-industries.com/embedded-systems
##:\/  ************************************************************



Thank you for using our products! This file is automatically generated
for you to provide information about how to install this kernel
extension library.  Following this introductory section in this file
will be specific information about each of the kernel extension packages
you have selected. Please visit http://www.mosaic-industries.com/embedded-systems
for more information, and click Contact Us if you have questions.

WHAT IS A KERNEL EXTENSION?

A kernel extension is modular prebuilt runtime library that enhances the
QED Forth kernel's features and capabilities by providing device drivers
or other useful functions.  These enhancements are fully accessible from
either the C or Forth language.

Mosaic Industries can provide you with a web site link that will enable
you to create a packaged kernel extension that has drivers for all of
the hardware that you have on your system.  In this way the software
drivers are customized to your needs, and you can generate whatever
combination of drivers you need.  When you are finished creating the
kernel extension, you download the resulting "packages.zip" file to your
hard drive.


INSTALLING THE KERNEL EXTENSION

The kernel extension is shipped as a "zipped" file named "packages.zip".
Unzipping it (using, for example, winzip or pkzip) extracts the
following files:

  readme.txt  - Provides summary documentation about the library.
  install.txt - The installation file, to be loaded to COLD-started QED
    Board.
  library.4th - Forth name headers and utilities; prepend to Forth
    programs.
  library.c   - C callers for all functions in library; #include in C
    code.
  library.h   - C prototypes for all functions; #include in extra C
    files.

Library.c and library.h are only needed if you are programming in C.
Library.4th is only needed if you are programming in Forth.  The uses of
all of these files are explained below.

We recommend that you move the relevant files to the my_kernel_extensions
directory of your workspace.  If you are not using the mosaic IDE version
1.2 or newer.

To use the kernel extension, the runtime kernel extension code contained
in the install.txt file must first be loaded into the flash memory of the
QED Board.  Start the QED Terminal software with the QED board connected to
the serial port and turned on.  If you have not yet tested your QED board
and terminal software, please refer to the documentation provided with the
QED Terminal software.  Once you can hit enter and see the 'ok' prompt
returned in the terminal window, type
   COLD
to ensure that the board is ready to accept the kernel extension install
file.  Use the "Send File" menu item of the terminal to download the
install.txt to the QED Board or Panel-Touch Controller.  Now, type
   COLD
again and the kernel has been extended! Once install.txt has been
loaded, it need not be reloaded each time that you revise and reload
your program source code.


USING THE DRIVER CODE WITH C

When using the Mosaic IDE, it is best to place the contents of the
packages.zip file into your workspace's my_kernel_extensions directory.
Then, in your source files, #include the library.h and library.c (in
that order) in at least one of your source code files and #include
the library.h file in any other source files that need access to the
kernel extensions routines.  Assuming your project source files are
in a directory such as mosaic\My_Workspace\Project_1, then you would
include your library files like this:
  #include "../My_Kernel_Extensions/library.c"
  #include "../My_Kernel_Extensions/library.h"


Alternately, you can move the library.c and library.h files into the same
directory as your other C source code files.  You can then use the following
directives in your source code file:
	#include "library.c"
	#include "library.h"

Library.c contains calling primitives that implement the functions in
the kernel extension package.  If you have a project with multiple source
code files, you should only include library.c once, but use the
directive
  #include "library.h" or #include "../My_Kernel_Extensions/library.h"
in every additional source file that references the kernel extension
functions.

Note that all of the functions in the kernel extension are of the _forth
type.  While they are fully callable from C, there are two important
restrictions.  First, _forth functions may not be called as part of a
parameter list of another _forth function.  Second, _forth functions may
not be called from within an interrupt service routine unless the
instructions found in the file named
	\fabius\qedcode\forthirq.c
are followed.

Also, there will be a warning returned by the C compiler complaining
about the redefinition of the variable .VarStart.  This is an internal
variable used by the C linker, and it is normal that you will a warning
about a redefinition since the library.c file redefines the variable.


USING THE DRIVER CODE WITH FORTH

After loading the install.txt file and typing COLD, use the terminal to send
the "library.4th" file to the QED Board.  Library.4th sets up a reasonable
memory map and then defines the constants, structures, and name headers used
by the kernel extension. Library.4th leaves the memory map in the download map.

After library.4th has been loaded, the board is ready to receive your high level
source code files.  Be sure that your software doesn't initialize the memory
management variables DP, VP, or NP, as this could cause memory conflicts.
If you wish to change the memory map, edit the memory map commands at the
top of the library.4th file itself.  The definitions in library.4th share
memory with your Forth code, and are therefore vulnerable to corruption due
to a crash while testing.  If you have problems after reloading your code,
try typing COLD, and reload everything starting with library.4th. It is very
unlikely that the kernel extension runtime code itself (install.txt) can
become corrupted since it is stored in flash on a page that is not typically
accessed by code downloads.

We recommend that your source code file begin with the sequence:

	WHICH.MAP 0=
	IFTRUE 	4 PAGE.TO.RAM  \ if in standard.map...
       		5 PAGE.TO.RAM
       		6 PAGE.TO.RAM
      		DOWNLOAD.MAP
	ENDIFTRUE

This moves all pre-loaded flash contents to RAM if the QED Board is in the
standard (flash-based) memory map, and then establishes the download
(RAM-based) memory map.  At the end of this sequence the QED Board is in
the download map, ready to receive additional code.

We recommend that your source code file end with the sequence:

	4 PAGE.TO.FLASH
	5 PAGE.TO.FLASH
	6 PAGE.TO.FLASH
	STANDARD.MAP
	SAVE

This copies all loaded code from RAM to flash, and sets up the standard
(flash-based) memory map with code located in pages 4, 5 and 6.  The SAVE
command means that you can often recover from a crash and continue working
by typing RESTORE as long as flash pages 4, 5 and 6 haven't been rewritten
with any bad data.


****  End of general section ****
****************************************************************

