BIOS Reference - NCFS Functions
From NanoComputerWiki
NCFS Module Functions
NanoComputer BIOS Reference
NCFS Module
Note: This information may be out of date. For the latest information always check the header files shipped with the NanoComputer SDK.
Last update: Oct 31 2008
// --------------------------------------------------
// Defines
// --------------------------------------------------
// Attributes
#define NCFS_ATTRIBUTE_NONE 0x00
#define NCFS_ATTRIBUTE_HIDDEN 0x01
#define NCFS_ATTRIBUTE_SYSTEM 0x02
// Constants
#define NCFS_FILENAME_MAXCHARS 32
#define NCFS_FILENAME_BUFFERSIZE 33
#define NCFS_RESERVED_PAGES 1
// BlockType
#define NCFS_BLOCKTYPE_FREE 0xFF
#define NCFS_BLOCKTYPE_BAD 0x00
#define NCFS_BLOCKTYPE_OS 0x01
#define NCFS_BLOCKTYPE_RESERVED 0x02
#define NCFS_BLOCKTYPE_FILE 0x03
#define NCFS_BLOCKTYPE_FILE_EXTENDED 0x04
// Errors
#define E_NCFS_FILE_NOT_FOUND -64 // 0xC0
#define E_NCFS_OUT_OF_BOUNDS -65 // 0xBF
#define E_NCFS_TOO_MUCH_DATA -66 // 0xBE
#define E_NCFS_PAGE_SIZE_ERROR -67 // 0xBD
#define E_NCFS_BAD_DATA_SIZE -68 // 0xBC
#define E_NCFS_NO_FREE_BLOCKS -69 // 0xBB
// Format
#define NCFS_FORMAT_FILESYSTEM 0x00
#define NCFS_FORMAT_LOWLEVEL 0x01
// --------------------------------------------------
// Structures & Typedefs
// --------------------------------------------------
// Block Header
struct _NCFS_BlockHeader {
unsigned char Attributes; // See NCFS_ATTRIBUTE_xxx (Flags)
unsigned char BlockType; // See NCFS_BLOCKTYPE_xxx (Enum)
char Filename[NCFS_FILENAME_MAXCHARS]; // Name of the file contained in this block (String)
unsigned short SequenceNumber; // Starts at zero
unsigned long Size; // Size of the file in bytes
};
typedef struct _NCFS_BlockHeader NCFS_BlockHeader;
// Block Info
struct _NCFS_BlockInfo {
NCFS_BlockHeader BlockHeader; // See NCFS_BlockHeader
unsigned long WearIndicator; // Number of times this block has been erased
};
typedef struct _NCFS_BlockInfo NCFS_BlockInfo;
// File Handle
struct _NCFS_FileHandle {
unsigned long BlockNumber; // Current BlockNumber for writing to this file
unsigned long BytesLeft; // Bytes Left to be written to this file
NCFS_BlockHeader Header; // See NCFS_BlockHeader
unsigned short PageNumber; // Current PageNumber for writing to this file
unsigned short PageOffset; // Current Offset into the page for writing
};
typedef struct _NCFS_FileHandle NCFS_FileHandle;
// Info
struct _NCFS_Info {
FLASH_Info FlashInfo; // See FLASH_Info
PARTITION_Info PartitionInfo; // See PARTITION_Info
unsigned short ReservedBlocks; // Number of blocks reserved by the file system in this Partition which cannot be used to store files.
};
typedef struct _NCFS_Info NCFS_Info;
// List Handle
struct _NCFS_ListHandle { // Opaque Handle used for Listing Files (NCFS Internal Use Only)
unsigned long BlockNumber;
};
typedef struct _NCFS_ListHandle NCFS_ListHandle;
// --------------------------------------------------
// Function Prototypes
// --------------------------------------------------
/**
* Erases a file
*
* sFilename - [in] Name of the file to erase (string)
*
* Returns E_OK on success, or other error on failure.
* If the file is not found, still returns E_OK.
**/
char NCFS_EraseFile(char* sFilename);
/**
* Formats a partition
*
* FormatType - [in] Can be NCFS_FORMAT_FILESYSTEM or NCFS_FORMAT_LOWLEVEL
*
* Use NCFS_FORMAT_FILESYSTEM for normal formatting of a partition. This will erase
* the file data in the partition. For a brand new partition used for the first time by
* the NCFS, a NCFS_FORMAT_LOWLEVEL should be performed which will erase the file data in
* the partition and reset all of the WearIndicators to zero. This is not recommended
* to be performed on a partition which already has valid WearIndicators because this will
* erase the WearIndicators and cause the Block Wear Leveling algorithm to have incorrect
* information and shorten the life of the FLASH.
*
* Returns E_OK on success, or other error on failure.
**/
char NCFS_Format(char FormatType);
/**
* Returns information about a block in the NCFS
*
* BlockNumber - [in] The number of the block to return information on. Can be between zero and
* NCFS_Info.PartitionInfo.Size - 1.
*
* Returns E_OK on success, or other error on failure.
**/
char NCFS_GetBlockInfo(unsigned long BlockNumber, NCFS_BlockInfo* pBlockInfo);
/**
* Returns a file handle for a file in the NCFS
*
* sFileName - [in] Name of the file to get handle for (string)
* pFileHandle - [out] NCFS_FileHandle structure which will be filled in with info about the file
*
* Returns E_OK on success, E_NCFS_FILE_NOT_FOUND if file not found, or other error on failure.
**/
char NCFS_GetFileHandle(char* sFilename, NCFS_FileHandle* pFileHandle);
/**
* Returns information about the NCFS File System
*
* pInfo - [out] NCFS_Info structure which will be filled in with info about the file system.
*
* Returns E_OK on success, or other error on failure.
**/
char NCFS_GetInfo(NCFS_Info* pInfo);
/**
* Returns the next file found on the File System
*
* NOTE: Call NCFS_ListFiles with a valid pHandle and a NULL for the FileName parameter in order
* to properly reset the pHandle to the start of a new list before actually enumerating files.
*
* i.e. NCFS_ListFiles(pHandle, NULL) <-- Resets the list
* NCFS_ListFiles(pHandle, pBuffer) <-- Returns first file
* NCFS_ListFiles(pHandle, pBuffer) <-- Returns second file
*
* pHandle - [in/out] Pointer to a NCFS_ListHandle which keeps track of the state of the List
* pFileName - [out] Name of the next file found will be returned in this buffer.
*
* Maximum length of a filename is defined by the NCFS_FILENAME_MAXCHARS constant.
*
* Returns E_OK on success, or other error on failure.
**/
char NCFS_ListFiles(NCFS_ListHandle *pHandle, char* pFileName);
/**
* Reads bytes from a file
*
* pFileHandle - [in] Pointer to file handle of the file to read
* Offset - [in] Offset in bytes from the beginning of the file to start reading at.
* Size - [in] The number of bytes to read from the file.
* pBuf - [out] Bytes read from the file will be written to this buffer.
*
* Returns E_OK on success, E_NCFS_FILE_NOT_FOUND if file not found, or other error on failure.
**/
char NCFS_ReadFile(NCFS_FileHandle* pFileHandle, unsigned long Offset, unsigned short Size, unsigned char* pBuf);
/**
* Creates a new file on the file system
*
* sFileName - [in] The name of the to create. (string)
* Size - [in] The size in bytes of the new file.
* Attributes - [in] The attributes to be set on this new file.
* pFileHandle - [out] Handle used to reference this file when writing data to the file. See NCFS_WriteFile_WriteData
*
* If a file with the same name as sFileName already exists on the File System it will be erased and a
* new file will be created in it's place.
*
* Returns E_OK on success, or other error on failure.
**/
char NCFS_WriteFile_CreateNewFile(char* sFilename, unsigned long Size, unsigned char Attributes, NCFS_FileHandle* pFileHandle);
/**
* Writes data to a file on the file system
*
* pFileHandle - [in] Handle of the file to write data to. Use NCFS_WriteFile_CreateNewFile to create this handle.
* Size - [in] The number of bytes to write.
* pBuf - [in] The buffer containing the data to write.
*
* Size must be the same size as a page in the FLASH, except for the very last write to the file, which can be smaller then
* a full page. The total number of bytes written to the file must be the same as the size of the file declared when the
* file was created. The size of a page in FLASH can be be obtained from NCFS_Info.FlashInfo.PageSize. (See NCFS_GetInfo function)
*
* Returns E_OK on success, E_NCFS_PAGE_SIZE_ERROR if Size is not the same size as a page in FLASH, E_NCFS_BAD_DATA_SIZE if
* the total number of bytes written to this file is more then the size declared when the file was created,
* or other error on failure
**/
char NCFS_WriteFile_WriteData(NCFS_FileHandle* pFileHandle, unsigned short Size, unsigned char *pBuf);
Navigation
- Click on any of the links below to navigate to a new page
