source: trunk/kernel/fs/fatfs.h @ 582

Last change on this file since 582 was 484, checked in by viala@…, 6 years ago

[fs] Add void type to function prototypes with no parameter
File size: 14.8 KB
Line 
1/*
2 * fatfs.h - FATFS file system API definition.
3 *
4 * Author    Mohamed Lamine Karaoui (2014,2015)
5 *           Alain Greiner (2016,2017)
6 *
7 * Copyright (c) UPMC Sorbonne Universites
8 *
9 * This file is part of ALMOS-MKH.
10 *
11 * ALMOS-MKH is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; version 2.0 of the License.
14 *
15 * ALMOS-MKH is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23 */
24
25#ifndef _FATFS_H_
26#define _FATFS_H_
27
28#include <hal_kernel_types.h>
29#include <rwlock.h>
30#include <vfs.h>
31
32
33///////////////////////////////////////////////////////////////////////////////////////////
34// The FATFS File System implements a FAT32 read/write file system.
35//
36// The FATFS extensions to the generic VFS are the following:
37// 1) The vfs_ctx_t "extend" field is a void* pointing on the fatfs_ctx_t structure.
38//    This structure contains various general informations such as the total
39//    number of sectors in FAT region, the number of bytes per sector, the number
40//    of sectors per cluster, the lba of FAT region, the lba of data region, or the
41//    cluster index for the root directory. It contains also an extended pointer
42//    on the FAT mapper.
43// 2) The vfs_inode_t "extend" field is a void*, but contains for each inode,
44//    the first FAT cluster index (after cast to intptr).
45///////////////////////////////////////////////////////////////////////////////////////////
46
47/*************** Partition Boot Sector Format **********************************/
48//                                     offset |  length
49#define BS_JMPBOOT                          0 ,  3
50#define BS_OEMNAME                          3 ,  8
51#define BPB_BYTSPERSEC                     11 ,  2
52#define BPB_SECPERCLUS                     13 ,  1
53#define BPB_RSVDSECCNT                     14 ,  2
54#define BPB_NUMFATS                        16 ,  1
55#define BPB_ROOTENTCNT                     17 ,  2
56#define BPB_TOTSEC16                       19 ,  2
57#define BPB_MEDIA                          21 ,  1
58#define BPB_FATSZ16                        22 ,  2
59#define BPB_SECPERTRK                      24 ,  2
60#define BPB_NUMHEADS                       26 ,  2
61#define BPB_HIDDSEC                        28 ,  4
62#define BPB_TOTSEC32                       32 ,  4
63#define BPB_PARTITION_TABLE               446 , 64
64
65// FAT 32
66#define BPB_FAT32_FATSZ32                  36 ,  4
67#define BPB_FAT32_EXTFLAGS                 40 ,  2
68#define BPB_FAT32_FSVER                    42 ,  2
69#define BPB_FAT32_ROOTCLUS                 44 ,  4
70#define BPB_FAT32_FSINFO                   48 ,  2
71#define BPB_FAT32_BKBOOTSEC                50 ,  2
72#define BS_FAT32_DRVNUM                    64 ,  1
73#define BS_FAT32_BOOTSIG                   66 ,  1
74#define BS_FAT32_VOLID                     67 ,  4
75#define BS_FAT32_VOLLAB                    71 , 11
76#define BS_FAT32_FILSYSTYPE                82 ,  8
77
78// Partitions
79#define FIRST_PARTITION_ACTIVE            446 ,  8
80#define FIRST_PARTITION_BEGIN_LBA         454 ,  4
81#define FIRST_PARTITION_SIZE              458 ,  4
82#define SECOND_PARTITION_ACTIVE           462 ,  8
83#define SECOND_PARTITION_BEGIN_LBA        470 ,  4
84#define SECOND_PARTITION_SIZE             474 ,  4
85#define THIRD_PARTITION_ACTIVE            478 ,  8
86#define THIRD_PARTITION_BEGIN_LBA         486 ,  4
87#define THIRD_PARTITION_SIZE              490 ,  4
88#define FOURTH_PARTITION_ACTIVE           494 ,  8
89#define FOURTH_PARTITION_BEGIN_LBA        502 ,  4
90#define FOURTH_PARTITION_SIZE             506 ,  4   
91/*******************************************************************************/
92
93#define MBR_SIGNATURE_POSITION            510 , 2
94#define MBR_SIGNATURE_VALUE               0xAA55 
95
96/************** FAT_FS_INFO SECTOR  ********************************************/
97#define FS_SIGNATURE_VALUE_1              0x52526141
98#define FS_SIGNATURE_VALUE_2              0x72724161
99#define FS_SIGNATURE_VALUE_3              0x000055AA 
100#define FS_SIGNATURE_POSITION_1           0   , 4 
101#define FS_SIGNATURE_POSITION_2           484 , 4
102#define FS_SIGNATURE_POSITION_3           508 , 4 
103#define FS_FREE_CLUSTERS                  488 , 4
104#define FS_FREE_CLUSTER_HINT              492 , 4
105/*******************************************************************************/
106
107#define DIR_ENTRY_SIZE          32
108                   
109#define NAME_MAX_SIZE           31
110
111/******* Directory Entry Structure (32 bytes) **********************************/
112//                            offset | length
113#define DIR_NAME                   0 , 11   // dir_entry name
114#define DIR_ATTR                  11 ,  1   // attributes
115#define DIR_NTRES                 12 ,  1   // reserved for the OS       
116#define DIR_CRT_TIMES_TENTH       13 ,  1
117#define DIR_FST_CLUS_HI           20 ,  2   // cluster index 16 MSB bits
118#define DIR_WRT_TIME              22 ,  2   // time of last write
119#define DIR_WRT_DATE              24 ,  2   // date of last write
120#define DIR_FST_CLUS_LO           26 ,  2   // cluster index 16 LSB bit
121#define DIR_FILE_SIZE             28 ,  4   // dir_entry size (up to 4 Gbytes)
122/*******************************************************************************/
123
124/******* LFN Directory Entry Structure  (32 bytes) *****************************/
125//                            offset | length
126#define LDIR_ORD                   0 ,  1   // Sequence number (from 0x01 to 0x0f)   
127#define LDIR_NAME_1                1 , 10   // name broken into 3 parts
128#define LDIR_ATTR                 11 ,  1   // attributes (must be 0x0F)
129#define LDIR_TYPE                 12 ,  1   // directory type (must be 0x00)
130#define LDIR_CHKSUM               13 ,  1   // checksum of name in short dir 
131#define LDIR_NAME_2               14 , 12
132#define LDIR_RSVD                 26 ,  2   // artifact of previous fat (must be 0)
133#define LDIR_NAME_3               28 ,  4   
134/*******************************************************************************/
135
136/***********************  DIR_ATTR values  (attributes) ************************/
137#define ATTR_READ_ONLY            0x01
138#define ATTR_HIDDEN               0x02
139#define ATTR_SYSTEM               0x04
140#define ATTR_VOLUME_ID            0x08
141#define ATTR_DIRECTORY            0x10
142#define ATTR_ARCHIVE              0x20
143#define ATTR_LONG_NAME_MASK       0x0f      // READ_ONLY|HIDDEN|SYSTEM|VOLUME_ID
144/*******************************************************************************/
145
146/********************* DIR_ORD special values **********************************/
147#define FREE_ENTRY                0xE5     // this entry is free in the directory
148#define NO_MORE_ENTRY             0x00     // no more entry in the directory
149/*******************************************************************************/
150
151/******************** CLuster Index Special Values *****************************/
152#define FREE_CLUSTER              0x00000000
153#define RESERVED_CLUSTER          0x00000001
154#define BAD_CLUSTER               0x0FFFFFF7
155#define END_OF_CHAIN_CLUSTER_MIN  0x0ffffff8
156#define END_OF_CHAIN_CLUSTER_MAX  0x0fffffff
157/*******************************************************************************/
158
159/****  Forward declarations  ****/
160
161struct mapper_s;
162struct page_s;
163struct vfs_ctx_s;
164struct vfs_inode_s;
165
166/*****************************************************************************************
167 * This structure defines a FATFS specific context (extension to VFS context).
168 ****************************************************************************************/
169
170typedef struct fatfs_ctx_s
171{
172    uint32_t          fat_sectors_count;     /*! number of sectors in FAT region        */
173    uint32_t          bytes_per_sector;      /*! number of bytes per sector             */
174    uint32_t          sectors_per_cluster;   /*! number of sectors per cluster          */
175    uint32_t          fat_begin_lba;         /*! lba of FAT region                      */
176    uint32_t          cluster_begin_lba;     /*! lba of data region                     */
177    uint32_t          root_dir_cluster;      /*! cluster index for the root directory   */
178    uint32_t          last_allocated_sector; /*! TODO ???                               */
179    uint32_t          last_allocated_index;  /*! TODO ???                               */
180    xptr_t            fat_mapper_xp;         /*! FAT mapper (in IO cluster)             */
181}
182fatfs_ctx_t;
183
184//////////////////////////////////////////////////////////////////////////////////////////
185//              FATFS specific extern functions 
186//////////////////////////////////////////////////////////////////////////////////////////
187
188/******************************************************************************************
189 * This function scan the FAT (File Allocation Table), stored in the FAT mapper,
190 * and returns the FATFS cluster index for a given page of a given file.
191 * It must be called by a thread running in the cluster containing the FAT mapper.
192 * We can use a RPC to scan the remote FAT mapper, because the RPC_FIFO will avoid
193 * contention in the cluster containing the FAT mapper, and the RPC latency is not
194 * critical compared to the device access latency.
195 * The FAT is actually an array of uint32_t slots. Each slot in this array contains the
196 * index of another slot in this array, to form one linked list for each file stored on
197 * device in the FATFS file system. This index in the FAT array is also the index of the
198 * FATFS cluster on the device. One FATFS cluster is supposed to contain one PPM page.
199 * For a given file, the entry point in the FAT is simply the index of the FATFS cluster
200 * containing the first page of the file. The mapper being a cache, this function
201 * automatically updates the FAT mapper from informations stored on device in case of miss.
202 ******************************************************************************************
203 * @ mapper                  : local pointer on the FAT mapper.
204 * @ first_cluster       : index of the first FATFS cluster allocated to the file.
205 * @ page_index          : index of searched page in file.
206 * @ searched_cluster_id : [out] found FATFS cluster index.
207 * @ return 0 if success / return EIO if a FAT mapper miss cannot be solved.
208 *****************************************************************************************/
209error_t fatfs_get_cluster( struct mapper_s * mapper,
210                           uint32_t          first_cluster,
211                           uint32_t          page_index,
212                           uint32_t        * searched_cluster_id );
213
214/******************************************************************************************
215 * This function display the content of the FATFS context.
216 *****************************************************************************************/
217void fatfs_ctx_display( void );
218
219
220//////////////////////////////////////////////////////////////////////////////////////////
221// Generic API: These functions are called by the kernel,
222//              and must be implemented by all File Systems.
223//////////////////////////////////////////////////////////////////////////////////////////
224
225/******************************************************************************************
226 * This fuction allocates memory from local cluster for a FATFS context descriptor.
227 ******************************************************************************************
228 * @ return a pointer on the created context / return NULL if failure.
229 *****************************************************************************************/
230fatfs_ctx_t * fatfs_ctx_alloc( void );
231
232/*****************************************************************************************
233 * This function access the boot device, and initialises the FATFS context
234 * from informations contained in the boot record.
235 *****************************************************************************************
236 * @ vfs_ctx   : local pointer on VFS context for FATFS.
237 ****************************************************************************************/
238void fatfs_ctx_init( fatfs_ctx_t * fatfs_ctx );
239
240/*****************************************************************************************
241 * This function releases memory dynamically allocated for the FATFS context extension.
242 *****************************************************************************************
243 * @ vfs_ctx   : local pointer on VFS context.
244 ****************************************************************************************/
245void fatfs_ctx_destroy( fatfs_ctx_t * fatfs_ctx );
246
247/*****************************************************************************************
248 * This function moves a page from/to the mapper to/from the FATFS file system on device.
249 * It must be called by a thread running in cluster containing the mapper.
250 * The pointer on the mapper and the page index in file are found in the page descriptor.
251 * WARNING : The inode field in the mapper MUST be NULL for the FAT mapper, as this
252 * is used to implement a specific behaviour to access the FAT zone on device.
253 *****************************************************************************************
254 * @ page      : local pointer on page descriptor.
255 * @ to_mapper : transfer direction
256 * @ return 0 if success / return EIO if error.
257 ****************************************************************************************/
258error_t fatfs_mapper_move_page( struct page_s * page,
259                                bool_t          to_mapper );
260
261/*****************************************************************************************
262 * This function scan an existing parent directory, identified by the <parent> argument,
263 * to find a directory entry identified by the <name> argument and update the remote
264 * child inode descriptor, identified by the <child_xp> argument.
265 * It set the "type", "size", and "extend" (FAT cluster index) fields in child inode.
266 * It must be called by a thread running in the cluster containing the parent inode.
267 *****************************************************************************************
268 * @ parent_inode    : local pointer on parent inode (directory).
269 * @ name            : child name.
270 * @ child_inode_xp  : extended pointer on remote child inode (file or directory).
271 * @ return 0 if success / return ENOENT if child not found.
272 ****************************************************************************************/
273error_t fatfs_inode_load( struct vfs_inode_s * parent_inode,
274                          char               * name,
275                          xptr_t               child_inode_xp );
276
277#endif  /* _FATFS_H_ */
Note: See TracBrowser for help on using the repository browser.