/////////////////////////////////////////////////////////////////////////-*-C-*- 
//
// Copyright (c) 2002, 2003 Xilinx, Inc.  All rights reserved.
//
// Xilinx, Inc.
//
// XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" AS A 
// COURTESY TO YOU.  BY PROVIDING THIS DESIGN, CODE, OR INFORMATION AS
// ONE POSSIBLE   IMPLEMENTATION OF THIS FEATURE, APPLICATION OR 
// STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION
// IS FREE FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE 
// FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION.  
// XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO 
// THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO 
// ANY WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE 
// FROM CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY 
// AND FITNESS FOR A PARTICULAR PURPOSE.
// 
// File   : xilmfs.h
//
// Description : 
//
// Header file for inclusion in all the modules using Xil MFS.
//
// $Id: xilmfs.h,v 1.4 2003/01/10 19:19:44 mohan Exp $
//
////////////////////////////////////////////////////////////////////////////////

#ifndef MFS_FILESYS_H
#define MFS_FILESYS_H


/* MFS_BLOCK_DATA_SIZE (= number of bytes of data in a file)
 * and MFS_MAX_LOCAL_ENT (= number of directory entries in 
 * a directory block) are related. 
 * see block_data union */
#define MFS_BLOCK_DATA_SIZE 512
#define MFS_MAX_LOCAL_ENT 16
/* block type definitions */
#define MFS_BLOCK_TYPE_DIR 2
#define MFS_BLOCK_TYPE_FILE 1
#define MFS_BLOCK_TYPE_EMPTY 0

/* MFS_MAX_FILENAME_LENGTH determines the size of mfs_dir_ent_block - see below */

#define MFS_MAX_FILENAME_LENGTH 23

/**
 * dir entry contains file name and index of first file block 
 * mfs_dir_entry_blocks are contained in a mfs_dir_block
 * size of mfs_dir_ent_block determines size of mfs_dir_block - see below
 * Make the size  a multiple of 4 bytes to ensure alignment at 4 byte boundaries
 */
struct mfs_dir_ent_block {
  char name[MFS_MAX_FILENAME_LENGTH];
  char deleted; /* value ='y' for deleted files and dirs, 'n' otherwise */
  unsigned int index;
};

/**
 * a mfs_dir_block is contained within a mfs_file_block 
 * each mfs_dir_block contains at least 1 entry (its parent dir) 
 * each dir block can contain at most MFS_MAX_LOCAL_ENT physical entries
 * If num_entries > MFS_MAX_LOCAL_ENT, there must be some 
 * continuation blocks indexed by the next_block entry of the mfs_file_block
 * The size of this block is determined by the size of the dir_ent array
 * The size should be less than or equal to the size of block_data in
 * struct mfs_file_block - see below
 * Make the size  a multiple of 4 bytes to ensure alignment at 4 byte boundaries
 */
struct mfs_dir_block {
  short num_entries;
  short num_deleted;
  struct mfs_dir_ent_block dir_ent[MFS_MAX_LOCAL_ENT];
};

/**
 * mfs_file_block is the basic unit of the file system
 * each block has a type identifier to identify the block as 
 * being part of a file a directory or empty
 * each block has pointers to the next and prev blocks if any,
 * in the file/dir/free-list
 */

struct mfs_file_block {
  unsigned short block_size; /* has meaning for data files only */
  unsigned short block_type; /* 2 = dir, 1 = file, 0 = empty */
  unsigned int next_block; /* points to (index of) next block if any */
  unsigned int prev_block; /* points to (index of) previous block if any */
  unsigned int index; /* index of this block */
  union {
    unsigned char block_data[MFS_BLOCK_DATA_SIZE];
    struct mfs_dir_block dir_data;
  }u;
} ;

#define MFS_MAX_OPEN_FILES 10
#define MFS_MODE_READ 0
#define MFS_MODE_WRITE 1
/* MFS_MODE_CREATE creates a new file and opens it with MFS_MODE_WRITE */
#define MFS_MODE_CREATE 3
#define MFS_MODE_FREE 8
struct mfs_open_file_struct {
  unsigned int first_block; /* first block of file */
  unsigned int current_block; /* currently accessed block */
  unsigned short offset; /* current offset within block */
  unsigned short mode ; /* read or write */
} ;

/* number of mfs_file_blocks that can fit in the memory reserved for the file system */
extern int mfs_max_file_blocks;
/* pointer to block of memory allocated or reserved for the file system */
extern struct mfs_file_block* mfs_file_system; 

/* index of first free block; the next_block value in this one continues the doubly linked free block list; the prev_block value of the first free block is 0 and the next_block value of the last free block is 0 */
extern int mfs_free_block_list;
/* the current directory is initialized to 0 for the top level directory, and is modified by change_dir() calls
*/
extern int mfs_current_dir;

/* information about files/dirs that are currently open for reading/writing */
extern struct mfs_open_file_struct mfs_open_files[MFS_MAX_OPEN_FILES];
extern int mfs_num_open_files; /* the number of open_files */

/* codes for initializing memory for MFS; see below for more info */
#define MFSINIT_NEW 0
#define MFSINIT_IMAGE 1
#define MFSINIT_ROM_IMAGE 2

/**
 * initialize the file system;
 * this function must be called before any file system operations 
 * @param numbytes is the number of bytes allocated or reserved for this file system
 * @param address is the starting address of the memory block
 * Note: address must be word aligned (4 byte boundary)
 * @param status is one of 
 * MFSINIT_NEW for creating empty read/write filesystem
 * MFSINIT_IMAGE for creating read/write filesystem with predefined data
 * MFSINIT_ROM_IMAGE for creating read-only filesystem with predefined data
 */
void mfs_init_fs(int numbytes, char *address, int status) ; 

/** 
 * modify global mfs_current_dir to index of newdir if it exists
 * mfs_current_dir is not modified otherwise
 * @param newdir is the name of the new directory
 * @return 1 for success and 0 for failure
 */
int mfs_change_dir(const char *newdir) ;

/**
 * delete a file
 * @param filename is the name of the file to be deleted
 * delete the data blocks corresponding to the file and then delete the
 * file entry from its directory
 * @return 1 on success, 0 on failure
 * delete will not work on a directory unless the directory is empty
 */
int mfs_delete_file (char *filename) ;

/**
 * create a new empty directory inside the current directory
 * @param newdir is the name of the directory
 * @return index of new directory in file system if success, 0 if failure 
 */
int mfs_create_dir(char *newdir);

/**
 * delete the directory named newdir if it exists, and is empty
 * return 1 on success, 0 on failure
 * cannot delete . or ..
 */
int mfs_delete_dir (char *newdir) ;

/**
 * rename from_file to to_file
 * works for dirs as well as files
 * cannot rename to something that already exists
 * @param from_file
 * @param to_file
 * @return 1 on success, 0 on failure
 */
int mfs_rename_file(char *from_file, char *to_file);

/**
 * check if a file exists
 * @param filename is the name of the file
 * @return 0 if filename is not a file in the current directory
 * @return 1 if filename is a file in the current directory
 * @return 2 if filename is a directory in the current directory
 */
int mfs_exists_file(char *filename);

/**
 * get the name of the current directory 
 * @param dirname =  pre_allocated buffer of at least MFS_MAX_FILENAME_SIZE+1 chars
 * The directory name is copied to this buffer
 * @return 1 if success, 0 if failure
 */
int mfs_get_current_dir_name(char *dirname);

/**
 * get the number of used blocks and the number of free blocks in the file system through pointers
 * @param num_blocks_used
 * @param num_blocks_free
 * the return value is  1 (for success) and 0 for failure to obtain the numbers
 */
int mfs_get_usage(int *num_blocks_used, int *num_blocks_free);

/**
 * open a directory for reading
 * each subsequent call to mfs_dir_read() returns one directory entry until
 * end of directory
 * @param dirname is the name of the directory to open
 * @return index of dir in array mfs_open_files or -1
 */
int mfs_dir_open(const char *dirname);

/**
 * close a directory - same as closing a file
 * @param fd is the descriptor of the directory to close
 * @return  1 on success, 0 otherwise
 */
int mfs_dir_close(int fd);

/**
 * read values from the next valid directory entry
 * The last 3 parameters are output values
 * @param fd is the file descriptor for an open directory file
 * @param filename is a pointer to the filename within the MFS itself
 * @param filesize is the size in bytes for a regular file or 
 * the number of entries in a directory
 * @param filetype is MFS_BLOCK_TYPE_FILE or MFS_BLOCK_TYPE_DIR
 * @return 1 for success and 0 for failure or end of dir
 */
int mfs_dir_read(int fd, char **filename, int *filesize, int *filetype);

/**
 * open a file
 * @param filename is the name of the file to open
 * @param mode is MFS_MODE_READ or MFS_MODE_WRITE or MFS_MODE_CREATE
 * this function should be used for FILEs and not DIRs
 * no error checking (is this FILE and not DIR?) is done for MFS_MODE_READ
 * MFS_MODE_CREATE automatically creates a FILE and not a DIR
 * MFS_MODE_WRITE fails if the specified file is a DIR
 * @return index of file in array mfs_open_files or -1 
 */
int mfs_file_open(const char *filename, int mode) ;

/**
 * read characters to a file
 * @param fd is a descriptor for the file from which the characters are read
 * @param buf is a pre allocated buffer that will contain the read characters
 * @param buflen is the number of characters from buf to be read
 * fd should be a valid index in mfs_open_files array
 * Works only if fd points to a file and not a dir
 * buf should be a pointer to a pre-allocated buffer of size buflen or more
 * buflen chars are read and placed in buf
 * if fewer than buflen chars are available then only that many chars are read
 * @return num bytes read or 0 for error=no bytes read
*/
int mfs_file_read(int fd, char *buf, int buflen) ;

/**
 * write characters to a file
 * @param fd is a descriptor for the file to which the characters are written
 * @param buf is a buffer containing the characters to be written out
 * @param buflen is the number of characters from buf to be written out
 * fd should be a valid index in mfs_open_files array
 * buf should be a pointer to a pre-allocated buffer of size buflen or more
 * buflen chars are read from buf and written to 1 or more blocks of the file
 * @return 1 for success or 0 for error=unable to write to file
*/ 
int mfs_file_write (int fd, const char *buf, int buflen) ;

/**
 * close an open file and
 * recover the file table entry in mfs_open_files corresponding to the fd
 * if the fd is not valid, return 0
 * fd is not valid if the index in mfs_open_files is out of range, or
 * if the corresponding entry is not an open file
 * @param fd is the file descriptor for the file to be closed
 * @return 1 on success, 0 otherwise
 */
int mfs_file_close(int fd);

/* constants used in the lseek function - see below */
#define MFS_SEEK_SET 0
#define MFS_SEEK_CUR 1
#define MFS_SEEK_END 2

/**
 * seek to a given offset within the file
 * @param fd should be a valid file descriptor for an open file
 * @param whence is one of MFS_SEEK_SET, MFS_SEEK_CUR or MFS_SEEK_END
 * @param offset is the offset from the beginning, end or current position as specified by the whence parameter
 * if MFS_SEEK_END is specified, the offset can be either 0 or negative
 * otherwise offset should be positive or 0
 * it is an error to seek before beginning of file or after the end of file
 * @return 0 on failure, 1 on success
 */
long mfs_file_lseek(int fd, long offset, int whence);
#endif // MFS_FILESYS_H
