source: trunk/kernel/vfs/fatfs.h @ 226

/*
 * fatfs.h - FATFS file system API definition.
 *
 * Author    Mohamed Lamine Karaoui (2014,2015)
 *           Alain Greiner (2016,2017)
 *
 * Copyright (c) UPMC Sorbonne Universites
 *
 * This file is part of ALMOS-MKH.
 *
 * ALMOS-MKH is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2.0 of the License.
 *
 * ALMOS-MKH is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef _FATFS_H_
#define _FATFS_H_

#include <hal_types.h>
#include <rwlock.h>
#include <vfs.h>


///////////////////////////////////////////////////////////////////////////////////////////
// The FATFS File System implements a FAT32 read/write file system.
///////////////////////////////////////////////////////////////////////////////////////////

/*************** Partition Boot Sector Format **********************************/
//                                     offset |  length
#define BS_JMPBOOT                          0 ,  3
#define BS_OEMNAME                          3 ,  8
#define BPB_BYTSPERSEC                     11 ,  2
#define BPB_SECPERCLUS                     13 ,  1
#define BPB_RSVDSECCNT                     14 ,  2
#define BPB_NUMFATS                        16 ,  1
#define BPB_ROOTENTCNT                     17 ,  2
#define BPB_TOTSEC16                       19 ,  2
#define BPB_MEDIA                          21 ,  1
#define BPB_FATSZ16                        22 ,  2
#define BPB_SECPERTRK                      24 ,  2
#define BPB_NUMHEADS                       26 ,  2
#define BPB_HIDDSEC                        28 ,  4
#define BPB_TOTSEC32                       32 ,  4
#define BPB_PARTITION_TABLE               446 , 64 

// FAT 32
#define BPB_FAT32_FATSZ32                  36 ,  4
#define BPB_FAT32_EXTFLAGS                 40 ,  2
#define BPB_FAT32_FSVER                    42 ,  2
#define BPB_FAT32_ROOTCLUS                 44 ,  4
#define BPB_FAT32_FSINFO                   48 ,  2
#define BPB_FAT32_BKBOOTSEC                50 ,  2
#define BS_FAT32_DRVNUM                    64 ,  1
#define BS_FAT32_BOOTSIG                   66 ,  1
#define BS_FAT32_VOLID                     67 ,  4
#define BS_FAT32_VOLLAB                    71 , 11
#define BS_FAT32_FILSYSTYPE                82 ,  8

// Partitions
#define FIRST_PARTITION_ACTIVE            446 ,  8
#define FIRST_PARTITION_BEGIN_LBA         454 ,  4
#define FIRST_PARTITION_SIZE              458 ,  4 
#define SECOND_PARTITION_ACTIVE           462 ,  8
#define SECOND_PARTITION_BEGIN_LBA        470 ,  4
#define SECOND_PARTITION_SIZE             474 ,  4
#define THIRD_PARTITION_ACTIVE            478 ,  8
#define THIRD_PARTITION_BEGIN_LBA         486 ,  4
#define THIRD_PARTITION_SIZE              490 ,  4
#define FOURTH_PARTITION_ACTIVE           494 ,  8
#define FOURTH_PARTITION_BEGIN_LBA        502 ,  4
#define FOURTH_PARTITION_SIZE             506 ,  4    
/*******************************************************************************/

#define MBR_SIGNATURE_POSITION            510 , 2
#define MBR_SIGNATURE_VALUE               0xAA55  

/************** FAT_FS_INFO SECTOR  ********************************************/
#define FS_SIGNATURE_VALUE_1              0x52526141
#define FS_SIGNATURE_VALUE_2              0x72724161
#define FS_SIGNATURE_VALUE_3              0x000055AA  
#define FS_SIGNATURE_POSITION_1           0   , 4  
#define FS_SIGNATURE_POSITION_2           484 , 4
#define FS_SIGNATURE_POSITION_3           508 , 4  
#define FS_FREE_CLUSTERS                  488 , 4
#define FS_FREE_CLUSTER_HINT              492 , 4
/*******************************************************************************/

#define DIR_ENTRY_SIZE          32
                   
#define NAME_MAX_SIZE           31

/******* Directory Entry Structure (32 bytes) **********************************/
//                            offset | length
#define DIR_NAME                   0 , 11   // dir_entry name
#define DIR_ATTR                  11 ,  1   // attributes
#define DIR_NTRES                 12 ,  1   // reserved for the OS        
#define DIR_CRT_TIMES_TENTH       13 ,  1 
#define DIR_FST_CLUS_HI           20 ,  2   // cluster index 16 MSB bits
#define DIR_WRT_TIME              22 ,  2   // time of last write
#define DIR_WRT_DATE              24 ,  2   // date of last write
#define DIR_FST_CLUS_LO           26 ,  2   // cluster index 16 LSB bit
#define DIR_FILE_SIZE             28 ,  4   // dir_entry size (up to 4 Gbytes)
/*******************************************************************************/

/******* LFN Directory Entry Structure  (32 bytes) *****************************/
//                            offset | length
#define LDIR_ORD                   0 ,  1   // Sequence number (from 0x01 to 0x0f)    
#define LDIR_NAME_1                1 , 10   // name broken into 3 parts 
#define LDIR_ATTR                 11 ,  1   // attributes (must be 0x0F) 
#define LDIR_TYPE                 12 ,  1   // directory type (must be 0x00)
#define LDIR_CHKSUM               13 ,  1   // checksum of name in short dir  
#define LDIR_NAME_2               14 , 12 
#define LDIR_RSVD                 26 ,  2   // artifact of previous fat (must be 0)
#define LDIR_NAME_3               28 ,  4   
/*******************************************************************************/

/***********************  DIR_ATTR values  (attributes) ************************/
#define ATTR_READ_ONLY            0x01
#define ATTR_HIDDEN               0x02
#define ATTR_SYSTEM               0x04
#define ATTR_VOLUME_ID            0x08
#define ATTR_DIRECTORY            0x10
#define ATTR_ARCHIVE              0x20
#define ATTR_LONG_NAME_MASK       0x0f      // READ_ONLY|HIDDEN|SYSTEM|VOLUME_ID
/*******************************************************************************/

/********************* DIR_ORD special values **********************************/
#define FREE_ENTRY                0xE5     // this entry is free in the directory
#define NO_MORE_ENTRY             0x00     // no more entry in the directory
/*******************************************************************************/

/******************** CLuster Index Special Values *****************************/
#define FREE_CLUSTER              0x00000000
#define RESERVED_CLUSTER          0x00000001
#define BAD_CLUSTER               0x0FFFFFF7
#define END_OF_CHAIN_CLUSTER_MIN  0x0ffffff8
#define END_OF_CHAIN_CLUSTER_MAX  0x0fffffff
/*******************************************************************************/

/****  Forward declarations  ****/

struct mapper_s;
struct page_s;
struct vfs_ctx_s;
struct vfs_inode_s;

/*****************************************************************************************
 * This structure defines a FATFS specific context (extension to VFS context). 
 ****************************************************************************************/

typedef struct fatfs_ctx_s
{
    uint32_t          fat_sectors_count;     /*! number of sectors in FAT region        */
    uint32_t          bytes_per_sector;      /*! number of bytes per sector             */
    uint32_t          sectors_per_cluster;   /*! number of sectors per cluster          */
    uint32_t          fat_begin_lba;         /*! lba of FAT region                      */
    uint32_t          cluster_begin_lba;     /*! lba of data region                     */
    uint32_t          root_dir_cluster;      /*! cluster index for the root directory   */
    uint32_t          last_allocated_sector; /*! TODO ???                               */
    uint32_t          last_allocated_index;  /*! TODO ???                               */
    xptr_t            fat_mapper_xp;         /*! FAT mapper (in IO cluster)             */
}
fatfs_ctx_t;

//////////////////////////////////////////////////////////////////////////////////////////
// Generic API: These functions are called by the kernel,
//              and must be implemented by all File Systems.
//////////////////////////////////////////////////////////////////////////////////////////

/******************************************************************************************
 * This fuction allocates memory from local cluster for a FATFS context descriptor.
 ******************************************************************************************
 * @ return a pointer on the created context / return NULL if failure.
 *****************************************************************************************/
fatfs_ctx_t * fatfs_ctx_alloc();

/*****************************************************************************************
 * This function access the external boot device, and initialises it
 * from informations contained in the boot record. 
 *****************************************************************************************
 * @ vfs_ctx   : local pointer on VFS context for FATFS.
 ****************************************************************************************/
void fatfs_ctx_init( fatfs_ctx_t * fatfs_ctx );

/*****************************************************************************************
 * This function releases memory dynamically allocated for the FATFS context extension.
 *****************************************************************************************
 * @ vfs_ctx   : local pointer on VFS context.
 ****************************************************************************************/
void fatfs_ctx_destroy( fatfs_ctx_t * fatfs_ctx );

/*****************************************************************************************
 * This function moves a page from the mapper to the FATFS file system on device.
 * It must be called by a thread running in cluster containing the mapper.
 * The pointer on the mapper and the page index in file are registered
 * in the page descriptor. 
 *****************************************************************************************
 * @ page    : local pointer on page descriptor.
 * @ return 0 if success / return EIO if error. 
 ****************************************************************************************/
error_t fatfs_write_page( struct page_s * page );

/*****************************************************************************************
 * This function moves a page from the FATFS file system on device to the mapper.
 * It must be called by a thread running in cluster containing the mapper.
 * The pointer on the mapper and the page index in file are registered
 * in the page descriptor. 
 *****************************************************************************************
 * @ page    : local pointer on page descriptor.
 * @ return 0 if success / return EIO if error. 
 ****************************************************************************************/
error_t fatfs_read_page( struct page_s * page );

/*****************************************************************************************
 * This function scan the FAT (File Allocation Table), stored in the FAT mapper,
 * and return the FATFS cluster index for a given page of a given file.
 * It must be called by a thread running in the cluster containing the FAT mapper
 * (can be a local thread or a RPC thread).
 * The FAT is actually an array of uint32_t slots. Each slot in this array contains the 
 * index of another slot in this array, to form one linked list for each file stored on
 * device in the RAMFS file system. This index in the FAT array is also the index of the
 * FATFS cluster on the device. One FATFS cluster is supposed to contain one PPM page. 
 * For a given file, the entry point in the FAT is simply the index of the FATFS cluster 
 * containing the first page of the file. The mapper being a cache, this function 
 * automatically updates the FAT mapper from informations stored on device in case of miss.
 *****************************************************************************************
 * @ mapper              : local pointer on the FAT mapper.
 * @ first_cluster       : index of the first FATFS cluster allocated to the file.
 * @ searched_page   : index of searched page in the file.
 * @ cluster         : [out] pointer on buffer for the found FATFS cluster index.
 * @ return 0 if success / return EIO if FAT mapper miss cannot be solved.
 ****************************************************************************************/
error_t fatfs_get_cluster( struct mapper_s * mapper,
                           uint32_t          first_cluster,
                           uint32_t          searched_page,
                           uint32_t *        cluster );

#endif  /* _FATFS_H_ */