xilflash.h File Reference

#include "xil_types.h"
#include "xstatus.h"
#include "xilflash_properties.h"
#include "xparameters.h"
#include <string.h>


Data Structures
struct	XFlash_UserInputs
struct	XFlashGeometry
struct	XFlashTag
Defines
#define	XFL_CMDSET_INTEL_STANDARD 3
#define	XFL_CMDSET_INTEL_EXTENDED 1
#define	XFL_CMDSET_AMD_STANDARD 2
#define	XFL_CMDSET_AMD_EXTENDED 4
#define	XFL_CMDSET_INTEL_G18 0x200
#define	XFLASH_BUSY 101
#define	XFLASH_READY 102
#define	XFLASH_ERROR 103
#define	XFLASH_ERASE_SUSPENDED 104
#define	XFLASH_WRITE_SUSPENDED 105
#define	XFLASH_PART_NOT_SUPPORTED 106
#define	XFLASH_NOT_SUPPORTED 107
#define	XFLASH_TOO_MANY_REGIONS 108
#define	XFLASH_TIMEOUT_ERROR 109
#define	XFLASH_ADDRESS_ERROR 110
#define	XFLASH_ALIGNMENT_ERROR 111
#define	XFLASH_BLOCKING_CALL_ERROR 112
#define	XFLASH_CFI_QUERY_ERROR 113
#define	XFLASH_BLOCK_PROTECTED 114
#define	XFL_LAYOUT_X16_X8_X1 0x02020101
#define	XFL_LAYOUT_X16_X16_X1 0x02020201
#define	XFL_LAYOUT_X16_X16_X2 0x04020202
#define	XFL_LAYOUT_X16_X16_X4 0x08020204
#define	XFL_DEVCTL_GET_LAST_ERROR 1
#define	XFL_DEVCTL_GET_GEOMETRY 2
#define	XFL_DEVCTL_GET_PROPERTIES 3
#define	XFL_DEVCTL_SET_RYBY 4
#define	XFL_DEVCTL_ERASE_RESUME 5
#define	XFL_DEVCTL_ERASE_SUSPEND 6
#define	XFL_DEVCTL_ENTER_EXT_MODE 7
#define	XFL_DEVCTL_EXIT_EXT_MODE 8
#define	XFL_DEVCTL_CHIP_ERASE 9
#define	XFL_DEVCTL_PROTECTION_STATUS 10
#define	XFL_INTEL_MAX_ERASE_REGIONS 20
#define	XFL_GEOMETRY_INCREMENT(GeometryPtr, Region, Block)
#define	XFL_GEOMETRY_BLOCK_DIFF(GeometryPtr, StartRegion, StartBlock, EndRegion, EndBlock)
#define	XFL_GEOMETRY_IS_ABSOLUTE_VALID(GeometryPtr, Offset) ((Offset) < (GeometryPtr)->DeviceSize)
#define	XFL_GEOMETRY_IS_BLOCK_VALID(GeometryPtr, Region, Block, BlockOffset)
Typedefs
typedef XFlashTag	XFlash
Functions
int	XFlash_Initialize (XFlash *InstancePtr, u32 BaseAddress, u8 BusWidth, int IsPlatformFlash)
int	XFlash_Reset (XFlash *InstancePtr)
int	XFlash_DeviceControl (XFlash InstancePtr, u32 Command, DeviceCtrlParam Parameters)
int	XFlash_Read (XFlash InstancePtr, u32 Offset, u32 Bytes, void DestPtr)
int	XFlash_Write (XFlash InstancePtr, u32 Offset, u32 Bytes, void SrcPtr)
int	XFlash_Erase (XFlash *InstancePtr, u32 Offset, u32 Bytes)
int	XFlash_Lock (XFlash *InstancePtr, u32 Offset, u32 Bytes)
int	XFlash_Unlock (XFlash *InstancePtr, u32 Offset, u32 Bytes)
int	XFlash_IsReady (XFlash *InstancePtr)

Detailed Description

This module implements the functionality for flash memory devices that conform to the "Common Flash Interface" (CFI) standard. CFI allows a single flash library to be used for an entire family of parts.

This is not a library for a specific device, but for a set of command read/write/erase algorithms. CFI allows us to determine which algorithm to utilize at runtime.

Library Initialization

The function call XFlash_Initialize() should be called by the application before any other function in the library. The initialization function checks for the device family and initializes the XFlash instance with the family specific data. The VT table (Contains the function pointers to family specific API's) is setup and family specific initialization routine is called.

Device Geometry

The Device geometry varies for different flash device families. The following list describes geometry of different flash device families:

Intel Flash Device Geometry

Flash memory space is segmented into areas called blocks. The size of each block is based on a power of 2. A region is defined as a contiguous set of blocks of the same size. Some parts have several regions while others have one. The arrangement of blocks and regions is refered to by this module as the part's geometry. Some Intel flash supports multiple banks on the same device. This library supports single and multiple bank flash devices.

AMD Flash Device Geometry

Flash memory space is segmented into areas called banks and further in to regions and blocks. The size of each block is based on a power of 2. A region is defined as a contiguous set of blocks of the same size. Some parts have several regions while others have one. A bank is defined as a contiguous set of blocks. The bank may contain blocks of different size. The arrangement of blocks, regions and banks is referred to by this module as the part's geometry.

The cells within the part can be programmed from a logic 1 to a logic 0 and not the other way around. To change a cell back to a logic 1, the entire block containing that cell must be erased. When a block is erased all bytes contain the value 0xFF. The number of times a block can be erased is finite. Eventually the block will wear out and will no longer be capable of erasure. As of this writing, the typical flash block can be erased 100,000 or more times.

Write Operation

The write call can be used to write a minimum of zero bytes and a maximum entire flash. If the Offset Address specified to write is out of flash or if the number of bytes specified from the Offset address exceed flash boundaries an error is reported back to the user. The write is blocking in nature in that the control is returned back to user only after the write operation is completed successfully or an error is reported.

Read Operation

The read call can be used to read a minimum of zero bytes and maximum of entire flash. If the Offset Address specified to write is out of flash boundary an error is reported back to the user. The read function reads memory locations beyond Flash boundary. Care should be taken by the user to make sure that the Number of Bytes + Offset address is within the Flash address boundaries. The write is blocking in nature in that the control is returned back to user only after the read operation is completed successfully or an error is reported.

Erase Operation

The erase operations are provided to erase a Block in the Flash memory. The erase call is blocking in nature in that the control is returned back to user only after the erase operation is completed successfully or an error is reported.

Sector Protection

The Flash Device is divided into Blocks. Each Block can be protected individually from unwarranted writing/erasing. The Block locking can be achieved using XFlash_Lock() lock. All the memory locations from the Offset address specified will be locked. The block can be unlocked using XFlash_UnLock() call. All the Blocks which are previously locked will be unlocked. The Lock and Unlock calls are blocking in nature in that the control is returned back to user only after the operation is completed successfully or an error is reported. The AMD flash device requires high voltage on Reset pin to perform lock and unlock operation. User must provide this high voltage (As defined in datasheet) to reset pin before calling lock and unlock API for AMD flash devices. Lock and Unlock features are not tested for AMD flash device.

Device Control

Functionalities specific to a Flash Device Family are implemented as Device Control.

The following are the Intel specific device control:

Retrieve the last error data.
Get Device geometry.
Get Device properties.
Set RYBY pin mode.
Set the Configuration register (Platform Flash only).

The following are the AMD specific device control:

Get Device geometry.
Get Device properties.
Erase Resume.
Erase Suspend.
Enter Extended Mode.
Exit Extended Mode.
Get Protection Status of Block Group.
Erase Chip.

Note:

This library needs to know the type of EMC core (AXI or XPS) used to access the cfi flash, to map the correct APIs. This library should be used with the emc driver, v3_01_a and above, so that this information can be automatically obtained from the emc driver.

This library is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads, mutual exclusion, virtual memory, cache control, or HW write protection management must be satisfied by the layer above this library.

All writes to flash occur in units of bus-width bytes. If more than one part exists on the data bus, then the parts are written in parallel. Reads from flash are performed in any width up to the width of the data bus. It is assumed that the flash bus controller or local bus supports these types of accesses.

 MODIFICATION HISTORY:

 Ver   Who  Date      Changes
 ----- ---- -------- -----------------------------------------------
 1.00a rmm  10/25/07 First release
 1.00a mta  10/25/07 Updated to flash library
 1.01a ksu  04/10/08 Added support for AMD CFI Interface
 1.02a ksu  06/16/09 Added support for multiple banks in Intel flash
		      Removed unused defines (XFL_MAX_NUM_BANKS, XFL_BANK1,
		      XFL_BANK2)
		      Added IOCTL to set configuration register of platform
		      flash
 1.03a ksu  10/07/09 Added support for large buffer size flash (CR535564)
 2.00a ktn  12/04/09 Updated to use the HAL processor APIs/macros
 2.01a ktn  03/31/10 Updated the AMD code to support uniform sector WP modes
 2.02a sdm  06/30/10 Updated to support AXI EMC with Little Endian Processor
 2.02a sdm  07/07/10 Updated XFlashAmd_Initialize() to NOT change the erase
		      region information of a top boot device, when the number
		      of erase regions is not more than 1.
 3.00a sdm  03/03/11 Removed static parameters in mld and updated code to
		      determine these parameters from the CFI data.
 3.00a sdm  03/23/11 Added two new parameters in mld for flash families. Users
		      can enable support for either of the flash devices or both
		      of them.
 3.01a srt  03/02/12 Added support for Micron G18 Flash device to fix
		      CRs 648372, 648282.
		      Modified XFlashIntel_Reset function to reset all the
		      partitions.
		      Added DATA_SYNC to fix the CR 644750.
 3.02a srt  05/30/12 Changed Implementation for Micron G18 Flash, which
		      fixes the CR 662317.
		      CR 662317 Description - Xilinx Platform Flash on ML605
		      fails to work.
 3.03a srt  11/04/12 Increased AMD maximum erase regions (CR 668730)
 		      Fixed CR 679937  - 
		      Description: Non-word aligned data write to flash fails
		      with AXI interface.
 3.04a srt  02/18/13 Fixed CR 700553.

Define Documentation

#define XFL_CMDSET_AMD_EXTENDED 4

Includes Fujitsu/STM

#define XFL_CMDSET_AMD_STANDARD 2

Includes Fujitsu/STM

#define XFL_CMDSET_INTEL_EXTENDED 1

Includes Micron/Sharp

#define XFL_CMDSET_INTEL_G18 0x200

Micron G18 Flash

#define XFL_CMDSET_INTEL_STANDARD 3

Vendor command set codes. Refer to industry document "CFI publication 100" for the latest list Includes Micron/Sharp

#define XFL_DEVCTL_CHIP_ERASE 9

Erase whole chip

#define XFL_DEVCTL_ENTER_EXT_MODE 7

Enter Extended mode

#define XFL_DEVCTL_ERASE_RESUME 5

Resume Erase

#define XFL_DEVCTL_ERASE_SUSPEND 6

Suspend Erase

#define XFL_DEVCTL_EXIT_EXT_MODE 8

Exit Extended mode

#define XFL_DEVCTL_GET_GEOMETRY 2

Get Device geometry

#define XFL_DEVCTL_GET_LAST_ERROR 1

Retrieve the last error data

#define XFL_DEVCTL_GET_PROPERTIES 3

Get Device Properties

#define XFL_DEVCTL_PROTECTION_STATUS 10

Check block protection status

#define XFL_DEVCTL_SET_RYBY 4

Set RYBY pin mode

#define XFL_GEOMETRY_BLOCK_DIFF ( GeometryPtr,
StartRegion,
StartBlock,
EndRegion,
EndBlock )

Value:
(((GeometryPtr)->EraseRegion[EndRegion].AbsoluteBlock + (EndBlock)) - \ ((GeometryPtr)->EraseRegion[StartRegion].AbsoluteBlock + \ (StartBlock)) + 1)
Calculates the number of blocks between the given start and end coordinates.

Parameters:

GeometryPtr is the geometry instance that defines flash addressing.

StartRegion is the starting region.

StartBlock is the starting block.

EndRegion is the ending region.

EndBlock is the ending block.

Returns:
The number of blocks between start Region/Block and end Region/Block(inclusive).

#define XFL_GEOMETRY_INCREMENT ( GeometryPtr,
Region,
Block )

Value:
{ \ if ((GeometryPtr)->EraseRegion[Region].Number <= ++(Block)) \ { \ (Region)++; \ (Block) = 0; \ } \ }
Increments the given Region and Block to the next block address.

Parameters:

GeometryPtr is the geometry instance that defines flash addressing.

Region is the starting region.

Block is the starting block.

Returns:
Region parameter is incremented if the next block starts in a new region. Block parameter is set to zero if the next block starts in a new region, otherwise it is incremented by one.

#define XFL_GEOMETRY_IS_ABSOLUTE_VALID ( GeometryPtr,
Offset ) ((Offset) < (GeometryPtr)->DeviceSize)

Tests the given absolute Offset to verify it lies within the bounds of the address space defined by a geometry instance.

Parameters:

GeometryPtr is the geometry instance that defines flash addressing.

Offset is the offset to test.

Returns:

0 if Offset do not lie within the address space described by GeometryPtr.
1 if Offset are within the address space.

#define XFL_GEOMETRY_IS_BLOCK_VALID ( GeometryPtr,
Region,
Block,
BlockOffset )

Value:
(((Region) < ( GeometryPtr)->NumEraseRegions) && \ ((Block) < (GeometryPtr)->EraseRegion[Region].Number) && \ ((BlockOffset) < (GeometryPtr)->EraseRegion[Region].Size))
Tests the given Region, Block, and Offset to verify they lie within the address space defined by a geometry instance.

Parameters:

GeometryPtr is the geometry instance that defines flash addressing

Region is the region to test

Block is the block to test

BlockOffset is the offset within block

Returns:

0 if Region, Block, & BlockOffset do not lie within the address space described by GeometryPtr.
1 if Region, Block, & BlockOffset are within the address space

#define XFL_INTEL_MAX_ERASE_REGIONS 20

A block region is defined as a set of consecutive erase blocks of the same size. Most flash devices only have a handful of regions. If a part has more regions than defined by this constant, then the constant must be modified to accommodate the part. The minimum value of this constant is 1 and there is no maximum value. Note that increasing this value also increases the amount of memory used by the geometry structure approximately 12 bytes per increment.

#define XFL_LAYOUT_X16_X16_X1 0x02020201

One 16-bit part operating in 16-bit mode. Total data bus width is 16-bits. This layout is supported in AMD and Intel flash devices

#define XFL_LAYOUT_X16_X16_X2 0x04020202

Two 16-bit parts operating in 16-bit mode. Total data bus width is 32-bits. This layout is only supported in Intel flash devices

#define XFL_LAYOUT_X16_X16_X4 0x08020204

Four 16-bit parts operating in 16-bit mode. Total data bus width is 64-bits. This layout is only supported in Intel flash devices

#define XFL_LAYOUT_X16_X8_X1 0x02020101

Supported part arrangements. This enumeration defines the supported arrangements of parts on the data-bus. The naming convention for these constants is as follows:
XFL_LAYOUT_Xa_Xb_Xc, where
Xa is the part's physical data bus width. Xb is the is the part's selected data bus width (this field is required because a x16 part can be placed in x8 mode). Xc is the number of interleaved parts. For example one part can be tied to D0-D15 and a second to data lines D15-D31.
Parts arranged in series should be treated as separate instances. An example of this layout: Two X16 parts operating in X16 mode. The first part occupies address space FF000000 - FF0FFFFF and a second from FF100000 - FF1FFFFF.
These constants are encoded using bit masks defined in the next section. One 16-bit part operating in 8-bit mode. Total data bus width is 8-bits. This layout is only supported in AMD flash devices

#define XFLASH_ADDRESS_ERROR 110

Accessed flash outside its addressable range

#define XFLASH_ALIGNMENT_ERROR 111

Write alignment error

#define XFLASH_BLOCK_PROTECTED 114

Block is protected

#define XFLASH_BLOCKING_CALL_ERROR 112

Couldn't return immediately from write/erase function with XFL_NON_BLOCKING_WRITE/ERASE option cleared

#define XFLASH_BUSY 101

Flash is erasing or programming

#define XFLASH_CFI_QUERY_ERROR 113

Failed to query the device

#define XFLASH_ERASE_SUSPENDED 104

Flash is in suspended erase state

#define XFLASH_ERROR 103

Flash had detected an internal error. Use XFlash_DeviceControl to retrieve device specific codes

#define XFLASH_NOT_SUPPORTED 107

Operation not supported

#define XFLASH_PART_NOT_SUPPORTED 106

Flash type not supported by library

#define XFLASH_READY 102

Flash is ready for commands

#define XFLASH_TIMEOUT_ERROR 109

Programming or erase operation aborted due to a timeout

#define XFLASH_TOO_MANY_REGIONS 108

Too many erase regions

#define XFLASH_WRITE_SUSPENDED 105

Flash is in suspended write state

Typedef Documentation

typedef struct XFlashTag XFlash

The XFlash library instance data. The user is required to allocate a variable of this type for every flash device in the system. A pointer to a variable of this type is then passed to the library API functions.

Function Documentation

int XFlash_DeviceControl ( XFlash * InstancePtr,

u32 Command,

DeviceCtrlParam * Parameters

)

This function is used to execute device specific commands. For a list of device specific commands, see the xilflash.h.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Command is the device specific command to issue.

Parameters specifies the arguments passed to the device control function.

Returns:

XST_SUCCESS if successful.
XFLASH_NOT_SUPPORTED if the command is not recognized/supported by the device(s).

Note:
None.

int XFlash_Erase ( XFlash * InstancePtr,

u32 Offset,

u32 Bytes

)

This function erases the specified address range in the flash device. The number of bytes to erase can be any number as long as it is within the bounds of the device(s).
The device is polled until an error or the operation completes successfully.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Offset is the offset into the device(s) address space from which to begin erasure.

Bytes is the number of bytes to erase.

Returns:

XST_SUCCESS if successful.
XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s).

Note:
Due to flash memory design, the range actually erased may be larger than what was specified by the Offset & Bytes parameters. This will occur if the parameters do not align to block boundaries.

int XFlash_Initialize ( XFlash * InstancePtr,

u32 BaseAddress,

u8 BusWidth,

int IsPlatformFlash

)

Initializes a specific XFlash instance. The initialization entails:

Check the Device family type.
Issuing the CFI query command.
Get and translate relevant CFI query information.
Set default options for the instance.
Setup the VTable.
Call the family initialize function of the instance.
Initialize the Xilinx Platform Flash XL to Async mode if the user selects to use the Platform Flash XL in the MLD. The Platform Flash XL is an Intel CFI complaint device.

Parameters:

InstancePtr is a pointer to the XFlash instance.

BaseAddress is the base address of the flash memory.

BusWidth is the total width of the flash memory, in bytes.

IsPlatformFlash is used to specify if the flash is a platform flash.

Returns:

XST_SUCCESS if successful.
XFLASH_PART_NOT_SUPPORTED if the command set algorithm or Layout is not supported by any flash family compiled into the system.
XFLASH_CFI_QUERY_ERROR if the device would not enter CFI query mode. Either the device(s) do not support CFI, the wrong BaseAddress param was used, an unsupported part layout exists, or a hardware problem exists with the part.

Note:
BusWidth is not the width of an individual part. Its the total operating width. For example, if there are two 16-bit parts, with one tied to data lines D0-D15 and other tied to D15-D31, BusWidth would be (32 / 8) = 4. If a single 16-bit flash is in 8-bit mode, then BusWidth should be (8 / 8) = 1.

int XFlash_IsReady ( XFlash * InstancePtr )

Checks the readiness of the device, which means it has been successfully initialized.

Parameters:

InstancePtr is a pointer to the XFlash instance.

Returns:
TRUE if the device has been initialized (but not necessarily started), and FALSE otherwise.

Note:
None.

int XFlash_Lock ( XFlash * InstancePtr,

u32 Offset,

u32 Bytes

)

This function Locks the blocks in the specified range of the flash device(s).
The device is polled until an error or the operation completes successfully.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Offset is the offset into the device(s) address space from which to begin block locking. The first three bytes of every block is reserved for special purpose. The offset should be atleast three bytes from start of the block.

Bytes indicates the number of bytes to Lock in the Block starting from Offset.

Returns:

XST_SUCCESS if successful.
XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s).

Note:
Due to flash memory design, the range actually locked may be larger than what was specified by the Offset & Bytes parameters. This will occur if the parameters do not align to block boundaries.

int XFlash_Read ( XFlash * InstancePtr,

u32 Offset,

u32 Bytes,

void * DestPtr

)

This function reads the data from the Flash device and copies it into the specified user buffer. The source and destination addresses can be on any alignment supported by the processor.
The device is polled until an error or the operation completes successfully.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Offset is the offset into the device(s) address space from which to read.

Bytes is the number of bytes to copy.

DestPtr is the destination address to copy data to.

Returns:

XST_SUCCESS if successful.
XFLASH_ADDRESS_ERROR if the source address does not start within the addressable areas of the device(s).

Note:
This function allows the transfer of data past the end of the device's address space. If this occurs, then results are undefined.

int XFlash_Reset ( XFlash * InstancePtr )

This function resets the flash device and places it in read mode.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Returns:

XST_SUCCESS if successful.
XFLASH_BUSY if the flash devices were in the middle of an operation and could not be reset.
XFLASH_ERROR if the device(s) have experienced an internal error during the operation. XFlash_DeviceControl() must be used to access the cause of the device specific error. condition.

Note:
None.

int XFlash_Unlock ( XFlash * InstancePtr,

u32 Offset,

u32 Bytes

)

This function Unlocks the blocks in the specified range of the flash device(s).
The device is polled until an error or the operation completes successfully.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Offset is the offset into the device(s) address space from which to begin block UnLocking. The first three bytes of every block is reserved for special purpose. The offset should be atleast three bytes from start of the block.

Bytes indicates the number of bytes to UnLock in the Block starting from Offset.

Returns:

XST_SUCCESS if successful.
XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s).

Note:
None.

int XFlash_Write ( XFlash * InstancePtr,

u32 Offset,

u32 Bytes,

void * SrcPtr

)

This function programs the flash device(s) with data specified in the user buffer. The source and destination address must be aligned to the width of the flash's data bus.
The device is polled until an error or the operation completes successfully.

Parameters:

InstancePtr is the pointer to the XFlash instance.

Offset is the offset into the device(s) address space from which to begin programming. Must be aligned to the width of the flash's data bus.

Bytes is the number of bytes to program.

SrcPtr is the source address containing data to be programmed. Must be aligned to the width of the flash's data bus. The SrcPtr doesn't have to be aligned to the flash width if the processor supports unaligned access. But, since this library is generic, and some processors (eg. Microblaze) do not support unaligned access; this API requires the SrcPtr to be aligned.

Returns:

XST_SUCCESS if successful.
XFLASH_ERROR if a write error occurred. This error is usually device specific. Use XFlash_DeviceControl() to retrieve specific error conditions. When this error is returned, it is possible that the target address range was only partially programmed.

Note:
None.

Generated on Thu Feb 13 14:37:13 2014 for 2014.1_doc by

1.4.5

xilflash.h File Reference

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation