READJ3.TXT for Intel(R) J3 Template Algorithm 
Reference Source Copyright (C) Intel Corp

05-April-2005

Current source versions:	J3 Template V1.0 

This read me file, for the template reference source,
code is organized into the following sections:

1.0 Purpose
2.0 What's New
3.0 Source Organization and Contents
4.0 Software Generation


1.0 Purpose
************
The included source archive file contains the reference source
code for the associated Intel(R) Template Algorithm software.  
This code is ANSI C compliant and is intended to be used by 
programmers developing flash software applications for Intel 
flash devices.  This code implements all device functionality 
as documented in the datasheet for the device. 


2.0 What's New
***************

*** Please see the accompanying "ISSUES.TXT" for any issues 
*** related to the code and/or documentation

05-April-2005 Release 1.0 (Final)
 1. Re-released under new licensing.

12-May-2000 Release 1.0 (Final)
 1. Feature complete. 


3.0 Source Organization and Contents
****************************************

After extracting the original archive file,  you will 
find the following files:

    READJ3.TXT   - This file

    \DOC
    | | 
    | |   SQANOTES.TXT - Description of Software Quality Assurance of this release 
    | +-- ISSUES.TXT   - List of known operational issues in this release
    | 
    \SRC 
      |
      +--\J3  - J3 specific device source code
      |    |  
      |    |  device.h
      |    +- device.c
      |
      +--\common - template common source code
           |
           |  template.h
           +- template.c



4.0 Software Generation
**************************

The J3 template algorithm reference code has been written
to ANSI C standards and is intended to be compiled with
any ANSI C compliant compiler/development environment.

No makefiles are provided as this code represents a set of
individually usable subroutines and is intended to be 
integrated into existing software development packages.  
These source code modules do  not, on their own define a
standalone executable program.

J3 template as delivered is configured for: 
   x16 J3 device(s).  
See software notes below for details on how to customize the 
template to match the target device.

The template algorithm package is written to comply with the
J3 datasheet documented functionality for each function.  Please
see the datasheet for details of each function.  The comments
in the source code should not serve as a replacement for the
detailed documentation provided by the datasheet.

While the template algorithm code has been designed to be ANSI C
compliant, the code is only known to compile succesfully using
Borland and Microsoft compilers.  

Software developers using the J3 template algorithm
package will follow these steps to prepare the
package for their specific needs:
----------------------------------------------------

   1) verify/change the following #define constants
      in the device.h header file to match the 
	  J3 device that will be supported:

      - #define CLIENT_GET_FPTR (TRUE/FALSE) 
	    (flag to indicate if the client will implement a 
            custom version of the TMPL_GetFptr subroutine.  
            This may be necessary if special addressing 
            requirements exist in the developers environment.  
            The J3 template package version of TMPL_GetFptr 
            defaults to converting all flash addresses passed 
            into template subroutines to straight 'C' pointers.)

      - #define BIG_ENDIAN_ARCHITECTURE (TRUE/FALSE)
	    (flag to specify byte ordering on the target 
            platform.)

      - #define J3_32_M, j3_64_M, J3_128_M (TRUE/FALSE)
	    (set only 1 of these to TRUE to indicate size of
            target device.)

      - #define TMPL_ERASE_TIMEOUT, TMPL_PROGRAM_TIMEOUT
	    (these constant values are generally CPU dependent
            and may need to be changed as appropriately for the
            target platform.  The values are arbitrarily high.)

   2) Implement the subroutine TMPL_GetFptr external to
      the template package if necessary to deal with
      custom addressing issues on the target platform.
      (see step 1 above for the #define CLIENT_GET_FPTR
      for more details on this.)  The default TMPL_GetFptr
      function provided with the template package can be 
      used if there are no addressing issues.

   3) The client software will include ONLY the template.h
      file which defines the application programmers 
      interface (API) for the complete template package. 
      The client should NOT directly include the device.h
      configuration file as this file is included by 
      template.h.

   4) The template functions can be called as needed to 
      provide low level device interface support.  The template
      design does not assume sequence or ordering of 
      function calls and does not retain any state
      information about the device or the software
      itself.  The client is expected to use the template
      algorithm package in a manner consistent with the
      functionality and behavior of the supported device as
      documented in the datasheet(s).

   5) All template functions which would, when called, result
      in updates to the device status register have a boolean
      subroutine parameter: ReturnSR which, when set to TRUE,
      tells that template function to manage the status register
      by first clearing the register prior to executing the called 
      function, and then returning the status register 
      value when finished.   If the caller sets ReturnSR to 
      FALSE when calling the relevant functions the status
      register will not be cleared by, or returned by the
      function and therefore the client is expected to manage
      the status (if required) using the TMPL_ClearStatus
      and TMPL_ReadStatus functions external to the called
      template function.  See the device datasheet(s) for
      details on recommended use of the status registers for
      these functions.


	
Copyright (C) Intel Corporation 2005

This document as well as the software described in it is furnished 
under license and may only be used or copied in accordance with the 
terms of the license. The information in this manual is furnished 
for informational use only, is subject to change without notice, 
and should not be construed as a commitment by Intel Corporation. 
Intel Corporation assumes no responsibility or liability for any 
errors or inaccuracies that may appear in this document or any 
software that may be provided in association with this document. 

Except as permitted by such license, no part of this document may 
be reproduced, stored in a retrieval system, or transmitted in any 
form or by any means without the express written consent of Intel 
Corporation.     

*
 Other names and brands may be claimed as the property of others.