dms.h

AMD公司官方版FLASH文件系统。有详细说明文档和Windows仿真测试环境。

/**
 *
 *  Dms.h
 *  DMS api.
 *
 */

#ifndef _DMS_H_
#define _DMS_H_

#ifdef cplusplus
extern "C"
}
#endif

#include "ffs.h"

/**
 * dms_Format
 *
 * This function prepares the device for use by the DMS.
 * Here all cells and their sizes are defined and written
 *   into the flash. 
 * This function requires the a global variable of name
 *   and type as folllows:
 *   SECTOR_DESCRIPTIOR gpDeviceArchitecture[];
 *   This is an array of structures that contain the flash
 *   structure information.  See Ffs.h for more information.
 * The global variable gpDeviceArchitecture must have the same
 *   value when dms_Format() and dms_Intialize() are called.
 *   After these two functions are complete this variable
 *   is no longer used.
 * Each cell size within the array, must be evenly
 *   divisible by DATABLOCK_SIZE, insuring even DataBlock
 *   boundaries.
 *
 * The total number of blocks in the DMS cannot exceed 2^16
 *
 * Arguments
 *   aCellSize       Array of DWORDS that contains the
 *                   size, in bytes, of each cell.
 *                   The array index is the Cell number
 *                   and the value in the index is the
 *                   size of the cell.                       
 *   awCellCount     The number of elements in the array.
 */
DMS_STATUS dms_Format(DWORD *aCellSize, WORD awCellCount);

/**
 * dms_Initialize()
 *
 * This function initializes the device.  It must
 *   be called prior to accessing the DMS.  In order
 *   for this function to execute the device must first
 *   be formatted.
 * This function requires the a global variable of name
 *   and type as folllows:
 *   SECTOR_DESCRIPTIOR gpDeviceArchitecture[];
 *   This is an array of structures that contain the flash
 *   structure information.  See Ffs.h for more information.
 * The global variable gpDeviceArchitecture must have the same
 *   value when dms_Format() and dms_Intialize() are called.
 *   After these two functions are complete this variable
 *   is no longer used.
 * This function may return Not_Enough_Free_Blocks or 
 *   No_Garbage_Blocks in which case the DMS is too full and
 *   it must be reformated with fewer blocks.
 * dms_Read(), dms_Write(), and dms_Cleanup() cannot be used
 *   until dms_Initialize() completes returning No_Error.
 */
DMS_STATUS dms_Initialize(void);

/**
 * dms_Write()
 *
 * This function writes the contents of the user buffer 
 *   (apBuffer) to the cell specified by aiCellNumber.  
 * Will not return until the write completes. 
 * The old cell data is destroyed when writing of the new
 *   cell has completed.
 * If dms_Write() returns anyting other than Invalid_Arguments_Error 
 *   or No_Error then the DMS software must be shutdown and 
 *   reinitialized before attempting to read or write again. Failure
 *   to do so may cause lose of all data.
 * Will return Dms_Not_Initialized if dms_Initialize() has not
 *   successfully completed.
 */
DMS_STATUS dms_Write(WORD awCellIndex, void *apBuffer);

/**
 *  dms_Read()
 *
 * This function reads the contents of the cell
 *   specified by aiCellNumber.  It stores the data
 *   in the user buffer, apBuffer.  
 * If dms_Read() returns anyting other than Invalid_Arguments_Error 
 *   or No_Error then the DMS software must be shutdown and 
 *   reinitialized before attempting to read or write again. Failure
 *   to do so may cause lose of all data.
 * Will return Dms_Not_Initialized if dms_Initialize() has not
 *   successfully completed.
 */
DMS_STATUS dms_Read(WORD awCellIndex, void *apBuffer);

/**
 * dms_Cleanup()
 * Finds the best sector to erase.  If there are no garbage blocks then
 *   dms_SectorCleanup returns No_Garbage_Blocks.  Otherwise it
 *   cleans one sector and returns No_Error if it was successful.
 * If dms_Cleanup() returns anyting other than No_Garbage_Blocks 
 *   or No_Error then the DMS software must be shutdown and 
 *   reinitialized before attempting to read or write again. Failure
 *   to do so may cause lose of all data.
 * Will return Dms_Not_Initialized if dms_Initialize() has not
 *   successfully completed.
 */
DMS_STATUS dms_Cleanup(void);

/**
 *  dms_Shutdown
 *
 *  This function shuts down the DMS and deallocates 
 *    all memory.
 *  After this function is called then dms_Initialize()
 *    must be called before dms_Write(), dms_Read(), or 
 *    dms_Cleanup() can be used.
 */
void dms_Shutdown(void);

/* Not Supported */
/* int IsBusy(void); */

#ifdef DMS_DEBUG
  char* dmsdbg_ErrorToString(DMS_STATUS e);
#endif /* DMS_DEBUG */

#ifdef cplusplus
} /* #ifdef cplusplus */
#endif

#endif /* _DMS_H_ */