/************************************************************************************************* *** Copyright (C) Intel Corporation 2006 *** All Rights Reserved. *** --------------------------------------------------------------------------------------------- *** PROJECT NAME: Intel StrataFlash(R) Cellular Memory (M18) Template Reference Code *** *** FILE: M18-Readme.txt *** *** VERSION: 1.0 *** *** DATE: 04/13/06 *** *** AUTHOR: Ronald Richardson *** *** PURPOSE: Brief discussion of the M18 Template Software Driver, *** and driver use-case examples. *** ************************************************************************************************* *** NOTICE OF LICENSE AGREEMENT *** *** This code is provided by Intel Corp., and the use is governed *** under the terms of a license agreement. See license agreement *** for complete terms of license. *** *** YOU MAY ONLY USE THE SOFTWARE WITH INTEL FLASH PRODUCTS. YOUR *** USE OF THE SOFTWARE WITH ANY OTHER FLASH PRODUCTS IS EXPRESSLY *** PROHIBITED UNLESS AND UNTIL YOU APPLY FOR, AND ARE GRANTED IN *** INTEL'S SOLE DISCRETION, A SEPARATE WRITTEN SOFTWARE LICENSE *** FROM INTEL LICENSING ANY SUCH USE. *************************************************************************************************/ This template algorithm is for Intel StrataFlash(R) Cellular Memory (M18) components. 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 5.0 Breakdown Explained 6.0 Simple Use Cases and Examples 7.0 Status Disclaimer 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 13-April-2006 Release 1.0 (Final) 1. Feature complete initial release. 3.0 Source Organization and Contents **************************************** After extracting the original archive file, you will find the following files: +-/ DOC = Documentation Folder | | | - Issues.txt - List of known operational issues in this release | | | - M18-Readme.txt - This file | | +-/ SRC = Template Source Code Folder | - target.h - Base function (interact with HW) signatures & | documentation | - target.c - Base function implementations, & HW definitions | - template.h - All M18 Driver function signatures, opcodes, structs, | masks, and header/method documentation. | - template.c - M18 Driver algortihm implementations, inline documentation only. 4.0 Software Generation ************************** The M18 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. M18 template as delivered is configured for: x16 M18 devices. 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 M18 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 Metrowerks' compiler. Software developers using the M18 template algorithm package will follow these steps to prepare the package for their specific needs: ---------------------------------------------------- 1) Modify the following definitions in the first section of template.h "User-customizable Features:" Please see the headers to each definition in template.h for explanations of each definition: - ADDRESS_PIN_LEFT_OFFSET and USE_ADDRESS_PIN_OFFSET - RUNTIME_SAFETY_CHECKS To be used during developemnt. - enum ErrorTypes May be added to - only should be used during development. - typedef struct flash_info Used throughout driver, can contain any information necessary for driver operation on the target platform. - TMPL_DEF_PARTITION_ADDR 2) In target.c, implement the following methods to suite the target hardware: void TMPL_InitHardware () { ... } void TMPL_WriteWord ( ... ) { ... } uint16 TMPL_ReadWord ( .. ) { ... } TMPL_InitHardware will be called before any other driver methods, and must prepare the target platform to use the M18 device. In most instances, this will be empty. TMPL_WriteWord must write the uint16 'word' to the address 'addr' with respect to the M18 address space. The device's base address with respect to the HW's address space is provided for you in 'info->baseAddr.' The default implementation of this method would appear as follows: void TMPL_WriteWord(const flash_info * info, uint32 addr, uint16 word) { info->baseAddr[addr] = word; } TMPL_ReadWord must read a uint16 word from the address 'addr' with respect to the M18 address space. The device's base address with respect to the HW's address space is again provided for you in 'info->baseAddr.' The default implementation of this method would appear as follows: uint16 TMPL_ReadWord(const flash_info * info, uint32 addr) { return info->baseAddr[addr]; } 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 target.h configuration file as this file is included by template.h. 4) The template design 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) The TMPL_HandleError(.) skeleton subroutine should be implemented to provide any helpful debugging information necessary. This method is called when the driver software detects a SR or Runtime-check error. This is not intented for use in final compilations of the driver. 5.0 Breakdown Explained ************************** This template driver is broken into two parts, Template and Target. The target code contains the basic ReadWord, WriteWord, and InitHardware functionality. All references to the target hardware should be made from these files (target.h and target.c) and these files alone. The template code contains abstract implementations of the M18 device functions that make refernce to target. No target-specific constants should be used, nor references made from these files (template.h and template.c). The functionality implemented in this driver is taken almost directly from the device datasheet. Please read the datasheet for a better understand of the devices behaviour and operation. This should be of special concern if the device is to be used in a non-sequential way. 5.0 Simple Use Cases and Examples *********************************** The beaviour of the device is complex. Depending on the needs of the application, this driver can be used in various ways to meet the needs of the application. Since the device has eight independant main array partitions, each partition assumes its own state, and can be used independantly of the others. However, only one program or erase operation can be in operation for the whole device. Interrupting a program or erase operation can happen if a more urgent operation must be executed first. Please see the datasheet section "Suspend and Resume" for more information on allowed concurrent states. Please note: This code is meant as an intuitive guide. It has not been (nor is meant to be) compiled. It is for clarification purposes only. Examples of usual operations are shown below: Basic Data and Setup: -------------------- /* In this case, all operations happen sequentially */ uint16 myDataText[0x100]; uint16 myDataRead_A[0x100]; uint16 myDataRead_B[0x100]; uint32 myAddress_A = 0x54000; uint32 myAddress_B = 0xF0000; uint32 myAddress_C = 0x000C0; flash_info myInfo; /* ... Code to initialize myData, etc... */ /* Initialization: */ TMPL_InitFlashInfo(&myInfo, 0x03000000, 0x00, TMPL_PARTITION_SIZE_256); TMPL_ProgramReadConfigReg(&myInfo, 0xF907); TMPL_ClearStatReg(&myInfo); TMPL_ChangeArrayState(&myInfo, myAddress_A, TMPL_asReadArray); TMPL_ChangeArrayState(&myInfo, myAddress_B, TMPL_asReadArray); Sequential Operations: (we wait on all operations to complete) --------------------- TMPL_ReadWords(&myInfo, myAddress_A, 0x100, 0, myDataRead_A); TMPL_IssueLockCommand(&myInfo, myAddress_A, TMPL_lcUnlockBlock, 0); TMPL_BlockErase(&myInfo, myAddress_A, 0); while (! TMPL_isProgramComplete(&myInfo) ) ; TMPL_BufferedProgram(&myInfo, myAddress_A, myDataText, 0x100, 0); while (! TMPL_isProgramComplete(&myInfo) ) ; TMPL_ChangeArrayState(&myInfo, myAddress_A, TMPL_asReadArray); TMPL_ReadWords(&myInfo, myAddress_A, 0x100, 0, myDataRead_B); Concurrent Operations: (we suspend active operations to perform others) --------------------- TMPL_IssueLockCommand(&myInfo, myAddress_A, TMPL_lcUnlockBlock, 0); TMPL_BlockErase(&myInfo, myAddress_A, 0); /* Now interrupt with a programming operation at address B */ TMPL_Suspend(&myInfo); /* Issued to myInfo->defPartitionAddr partition */ /* Wait for SR Ready */ while (! TMPL_isProgramComplete(&myInfo) ) ; if (TMPL_isEraseSuspended(&myInfo)) { printf("Erase operation was suspended."); } else { printf("Erase operation completed before tSUSP and no operation is suspended."); } /* Initiate Programming operation */ TMPL_BufferedProgram(&myInfo, myAddress_B, myDataText, 0x100, 0); TMPL_ChangeArrayState(&myInfo, myAddress, TMPL_asReadArray); TMPL_ReadWords(&myInfo, myAddress, 0x100, 0, myDataRead_B); 7.0 Status Disclaimer *********************** This is a reference code only release. The following characteristics describe this software release: * The code's core functionality is coded. * The code's features are likely complete. * Unit and system testing by the developers have been performed. * No formal Software Quality Assurance testing has been performed. * The software and design specifications are likely under review. * The user's guide, if any, is complete. * Unknown program issues probably exist. Known issues are being fixed, or will be. This information is being provided to insure that you are aware of this software's status. If you have any questions, please contact your Flash technical marketing representative via your field software representative or via e-mail at flash.software@intel.com ************************** Copyright (C) Intel Corporation 2006 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.