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

Last change on this file since 179 was 23, checked in by alain, 7 years ago

Introduce syscalls.
File size: 16.7 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_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
37/*************** Partition Boot Sector Format **********************************/
38//                                     offset |  length
39#define BS_JMPBOOT                          0 ,  3
40#define BS_OEMNAME                          3 ,  8
41#define BPB_BYTSPERSEC                     11 ,  2
42#define BPB_SECPERCLUS                     13 ,  1
43#define BPB_RSVDSECCNT                     14 ,  2
44#define BPB_NUMFATS                        16 ,  1
45#define BPB_ROOTENTCNT                     17 ,  2
46#define BPB_TOTSEC16                       19 ,  2
47#define BPB_MEDIA                          21 ,  1
48#define BPB_FATSZ16                        22 ,  2
49#define BPB_SECPERTRK                      24 ,  2
50#define BPB_NUMHEADS                       26 ,  2
51#define BPB_HIDDSEC                        28 ,  4
52#define BPB_TOTSEC32                       32 ,  4
53#define BPB_PARTITION_TABLE               446 , 64
54
55// FAT 32
56#define BPB_FAT32_FATSZ32                  36 ,  4
57#define BPB_FAT32_EXTFLAGS                 40 ,  2
58#define BPB_FAT32_FSVER                    42 ,  2
59#define BPB_FAT32_ROOTCLUS                 44 ,  4
60#define BPB_FAT32_FSINFO                   48 ,  2
61#define BPB_FAT32_BKBOOTSEC                50 ,  2
62#define BS_FAT32_DRVNUM                    64 ,  1
63#define BS_FAT32_BOOTSIG                   66 ,  1
64#define BS_FAT32_VOLID                     67 ,  4
65#define BS_FAT32_VOLLAB                    71 , 11
66#define BS_FAT32_FILSYSTYPE                82 ,  8
67
68// Partitions
69#define FIRST_PARTITION_ACTIVE            446 ,  8
70#define FIRST_PARTITION_BEGIN_LBA         454 ,  4
71#define FIRST_PARTITION_SIZE              458 ,  4
72#define SECOND_PARTITION_ACTIVE           462 ,  8
73#define SECOND_PARTITION_BEGIN_LBA        470 ,  4
74#define SECOND_PARTITION_SIZE             474 ,  4
75#define THIRD_PARTITION_ACTIVE            478 ,  8
76#define THIRD_PARTITION_BEGIN_LBA         486 ,  4
77#define THIRD_PARTITION_SIZE              490 ,  4
78#define FOURTH_PARTITION_ACTIVE           494 ,  8
79#define FOURTH_PARTITION_BEGIN_LBA        502 ,  4
80#define FOURTH_PARTITION_SIZE             506 ,  4   
81/*******************************************************************************/
82
83#define MBR_SIGNATURE_POSITION            510 , 2
84#define MBR_SIGNATURE_VALUE               0xAA55 
85
86/************** FAT_FS_INFO SECTOR  ********************************************/
87#define FS_SIGNATURE_VALUE_1              0x52526141
88#define FS_SIGNATURE_VALUE_2              0x72724161
89#define FS_SIGNATURE_VALUE_3              0x000055AA 
90#define FS_SIGNATURE_POSITION_1           0   , 4 
91#define FS_SIGNATURE_POSITION_2           484 , 4
92#define FS_SIGNATURE_POSITION_3           508 , 4 
93#define FS_FREE_CLUSTERS                  488 , 4
94#define FS_FREE_CLUSTER_HINT              492 , 4
95/*******************************************************************************/
96
97#define DIR_ENTRY_SIZE          32
98                   
99#define NAME_MAX_SIZE           31
100
101/******* Directory Entry Structure (32 bytes) **********************************/
102//                            offset | length
103#define DIR_NAME                   0 , 11   // dir_entry name
104#define DIR_ATTR                  11 ,  1   // attributes
105#define DIR_NTRES                 12 ,  1   // reserved for the OS       
106#define DIR_CRT_TIMES_TENTH       13 ,  1
107#define DIR_FST_CLUS_HI           20 ,  2   // cluster index 16 MSB bits
108#define DIR_WRT_TIME              22 ,  2   // time of last write
109#define DIR_WRT_DATE              24 ,  2   // date of last write
110#define DIR_FST_CLUS_LO           26 ,  2   // cluster index 16 LSB bit
111#define DIR_FILE_SIZE             28 ,  4   // dir_entry size (up to 4 Gbytes)
112/*******************************************************************************/
113
114/******* LFN Directory Entry Structure  (32 bytes) *****************************/
115//                            offset | length
116#define LDIR_ORD                   0 ,  1   // Sequence number (from 0x01 to 0x0f)   
117#define LDIR_NAME_1                1 , 10   // name broken into 3 parts
118#define LDIR_ATTR                 11 ,  1   // attributes (must be 0x0F)
119#define LDIR_TYPE                 12 ,  1   // directory type (must be 0x00)
120#define LDIR_CHKSUM               13 ,  1   // checksum of name in short dir 
121#define LDIR_NAME_2               14 , 12
122#define LDIR_RSVD                 26 ,  2   // artifact of previous fat (must be 0)
123#define LDIR_NAME_3               28 ,  4   
124/*******************************************************************************/
125
126/***********************  DIR_ATTR values  (attributes) ************************/
127#define ATTR_READ_ONLY            0x01
128#define ATTR_HIDDEN               0x02
129#define ATTR_SYSTEM               0x04
130#define ATTR_VOLUME_ID            0x08
131#define ATTR_DIRECTORY            0x10
132#define ATTR_ARCHIVE              0x20
133#define ATTR_LONG_NAME_MASK       0x0f      // READ_ONLY|HIDDEN|SYSTEM|VOLUME_ID
134/*******************************************************************************/
135
136/********************* DIR_ORD special values **********************************/
137#define FREE_ENTRY                0xE5     // this entry is free in the directory
138#define NO_MORE_ENTRY             0x00     // no more entry in the directory
139/*******************************************************************************/
140
141/******************** CLuster Index Special Values *****************************/
142#define FREE_CLUSTER              0x00000000
143#define RESERVED_CLUSTER          0x00000001
144#define BAD_CLUSTER               0x0FFFFFF7
145#define END_OF_CHAIN_CLUSTER_MIN  0x0ffffff8
146#define END_OF_CHAIN_CLUSTER_MAX  0x0fffffff
147/*******************************************************************************/
148
149/****  Forward declarations  ****/
150
151struct mapper_s;
152struct page_s;
153struct vfs_ctx_s;
154struct vfs_inode_s;
155
156/*****************************************************************************************
157 * This structure defines a FATFS specific context (extension to VFS context).
158 ****************************************************************************************/
159
160typedef struct fatfs_ctx_s
161{
162    uint32_t          fat_begin_lba;         /*! lba of FAT region                      */
163    uint32_t          fat_sectors_count;     /*! number of sectors in FAT region        */
164    uint32_t          bytes_per_sector;      /*!                                        */
165    uint32_t          bytes_per_cluster;     /*!                                        */
166    uint32_t          cluster_begin_lba;     /*! lba of data region                     */
167    uint32_t          sectors_per_cluster;   /*! cluster index for root directory       */
168    uint32_t          root_dir_cluster;      /*!                                        */
169    uint32_t          last_allocated_sector; /*! TODO ???                               */
170    uint32_t          last_allocated_index;  /*! TODO ???                               */
171    xptr_t            fat_mapper_xp;         /*! FAT mapper (in IO cluster)             */
172}
173fatfs_ctx_t;
174
175/*****************************************************************************************
176 * This structure defines the FATFS specific inode (extension to VFS inode).
177 ****************************************************************************************/
178
179typedef struct fatfs_inode_s
180{
181        uint32_t          first_cluster;         /*! first cluster for this file/dir        */ 
182}
183fatfs_inode_t;
184
185
186
187
188//////////////////////////////////////////////////////////////////////////////////////////
189// These functions are specific to the FATFS, and cannot be called by the VFS.
190//////////////////////////////////////////////////////////////////////////////////////////
191
192/*****************************************************************************************
193 * This function returns the LBA of the first sector of a FAT cluster.
194 * This function can be called by any thread running in any cluster.
195 *****************************************************************************************
196 * @ ctx          :     pointer on FATFS context.
197 * @ cluster  : cluster index in FATFS.
198 * @ return the lba value.
199 ****************************************************************************************/
200inline uint32_t fatfs_lba_from_cluster( fatfs_ctx_t * ctx,
201                                        uint32_t      cluster );
202
203/*****************************************************************************************
204 * This function scan the FAT (File Allocation Table), stored in the FAT mapper,
205 * and return the FATFS cluster index for a given page of a given file.
206 * It must be called by a thread running in the cluster containing the FAT mapper
207 * (can be a local thread or a RPC thread).
208 * The FAT is actually an array of uint32_t slots. Each slot in this array contains the
209 * index of another slot in this array, to form one linked list for each file stored on
210 * device in the RAMFS file system. This index in the FAT array is also the index of the
211 * FATFS cluster on the device. One FATFS cluster is supposed to contain one PPM page.
212 * For a given file, the entry point in the FAT is simply the index of the FATFS cluster
213 * containing the first page of the file. The mapper being a cache, this function
214 * automatically updates the FAT mapper from informations stored on device in case of miss.
215 *****************************************************************************************
216 * @ mapper      : local pointer on the FAT mapper.
217 * @ first       : index of the first FATFS cluster allocated to the file.
218 * @ page    : index of searched page in the file.
219 * @ cluster : [out] pointer on buffer for the found FATFS cluster index.
220 * @ return 0 if success / return EIO if FAT mapper miss cannot be solved.
221 ****************************************************************************************/
222error_t fatfs_get_cluster( struct mapper_s * mapper,
223                           uint32_t          first_cluster,
224                           uint32_t          searched_page,
225                           uint32_t        * cluster );
226
227
228
229
230//////////////////////////////////////////////////////////////////////////////////////////
231// These functions are called by the VFS, and must be implemented by all File Systems.
232//////////////////////////////////////////////////////////////////////////////////////////
233
234/******************************************************************************************
235 * This function initializes the FATFS file system as the root FS.
236 * It is executed cooperatively during kernel init by all CP0s in all clusters.
237 * The initilisation is made in three phases, separated by synchronisation barrier:     
238 * - phase 1 : all CP0s in all clusters allocate memory for the local copy of
239 *   the FATFS context.
240 * - phase 2 : cluster_0 only creates the root inode descriptor, access the external
241 *   device to get information stored on the boot record, and initialises both
242 *   the VFS context, and the FATFS context.
243 * - phase 3 : all other clusters initialize their local VFS context and FATFS context
244 *   from values contained in cluster_0, using hal_remote_memcpy().
245 ******************************************************************************************
246 * @ return an extended pointer on the created root inode / return XPTR_NULL if failure.
247 *****************************************************************************************/
248xptr_t fatfs_init();
249
250/******************************************************************************************
251 * This function mount the FATFS on the root FS.
252 * TODO not implemented [AG]
253 ******************************************************************************************
254 * @ parent_inode_xp : extended pointer on the parent inode.
255 *****************************************************************************************/
256error_t fatfs_mount( xptr_t parent_inode_xp );
257
258
259/*****************************************************************************************
260 * This function  initializes both the VFS context and the FATFS context.
261 * Both the VFS context and the FATFS context must have been previously allocated.
262 * It access the device to read the boot record, and is supposed to be called only
263 * in cluster_0 (in other clusters these contexts are replicated from values
264 * contained in cluster_0).
265 *****************************************************************************************
266 * @ vfs_ctx        : local pointer on VFS context for FATFS.
267 * @ fatfs_ctx      : local pointer on specific FATFS context.
268 * @ root_inode_xp  : extended pointer on VFS root inode.
269 ****************************************************************************************/
270error_t fatfs_ctx_init( struct vfs_ctx_s   * vfs_ctx,
271                        struct fatfs_ctx_s * fatfs_ctx,
272                        xptr_t               root_inode_xp );
273
274/*****************************************************************************************
275 * This function releases memory dynamically allocated for the FATFS context extension.
276 *****************************************************************************************
277 * @ vfs_ctx   : local pointer on VFS context.
278 ****************************************************************************************/
279void fatfs_ctx_destroy( struct vfs_ctx_s * vfs_ctx );
280
281
282
283/*****************************************************************************************
284 * This function allocates memory for a FATFS inode, initializes it,
285 * and link it to the VFS inode.
286 *****************************************************************************************
287 * @ inode         : local pointer on the VFS inode.
288 * @ first_cluster : first cluster index in the FAT32.
289 * @ return 0 if success / return ENOMEM if error.
290 ****************************************************************************************/
291error_t fatfs_inode_create( struct vfs_inode_s * inode,
292                            uint32_t             first_cluster);
293
294/*****************************************************************************************
295 * This function releases memory allocated for a FATFS inode.
296 *****************************************************************************************
297 * @ inode   : local pointer on vfs_inode.
298 ****************************************************************************************/
299void fatfs_inode_destroy( struct vfs_inode_s * inode );
300
301
302
303/*****************************************************************************************
304 * This function moves a page from the mapper to the FATFS file system on device.
305 * It must be called by a thread running in cluster containing the mapper.
306 * The pointer on the mapper and the page index in file are registered
307 * in the page descriptor.
308 *****************************************************************************************
309 * @ page    : local pointer on page descriptor.
310 * @ return 0 if success / return EIO if error.
311 ****************************************************************************************/
312error_t fatfs_write_page( struct page_s * page );
313
314/*****************************************************************************************
315 * This function moves a page from the FATFS file system on device to the mapper.
316 * It must be called by a thread running in cluster containing the mapper.
317 * The pointer on the mapper and the page index in file are registered
318 * in the page descriptor.
319 *****************************************************************************************
320 * @ page    : local pointer on page descriptor.
321 * @ return 0 if success / return EIO if error.
322 ****************************************************************************************/
323error_t fatfs_read_page( struct page_s * page );
324
325
326
327
328#endif  /* _FATFS_H_ */
Note: See TracBrowser for help on using the repository browser.