59824e23907f0fe87b6584a43d1a4223c03fe661
[tpg/acess2.git] / KernelLand / Kernel / include / vfs.h
1 /* 
2  * Acess2
3  * VFS Common Header
4  */
5 /**
6  * \file vfs.h
7  * \brief Acess VFS Layer
8  * 
9  * The Acess Virtual File System (VFS) provides abstraction of multiple
10  * physical filesystems, network storage and devices (both hardware and
11  * virtual) to the user.
12  * 
13  * The core of the VFS is the concept of a \ref tVFS_Node "VFS Node".
14  * A VFS Node represents a "file" in the VFS tree, this can be any sort
15  * of file (an ordinary file, a directory, a symbolic link or a device)
16  * depending on the bits set in the \ref tVFS_Node.Flags Flags field.
17  * - For more information see "VFS Node Flags"
18  */
19 #ifndef _VFS_H
20 #define _VFS_H
21
22 #include <acess.h>
23 #include <mutex.h>
24
25 /**
26  * \brief Thread list datatype for VFS_Select
27  */
28 typedef struct sVFS_SelectList  tVFS_SelectList;
29
30 typedef struct sVFS_NodeType    tVFS_NodeType;
31
32 /**
33  * \name tVFS_Node Flags
34  * \brief Flag values for tVFS_Node.Flags
35  * \{
36  */
37 //! \todo Is this still needed
38 #define VFS_FFLAG_READONLY      0x01    //!< Readonly File
39 /**
40  * \brief Directory Flag
41  * 
42  * This flag marks the tVFS_Node as describing a directory, and says
43  * that the tVFS_Node.FindDir, tVFS_Node.ReadDir, tVFS_Node.MkNod and
44  * tVFS_Node.Relink function pointers are valid.
45  * For a directory the tVFS_Node.Size field contains the number of files
46  * within the directory, or -1 for undetermined.
47  */
48 #define VFS_FFLAG_DIRECTORY     0x02
49 /**
50  * \brief Symbolic Link Flag
51  * 
52  * Marks a file as a symbolic link
53  */
54 #define VFS_FFLAG_SYMLINK       0x04
55 /**
56  * \brief Set User ID Flag
57  * 
58  * Allows an executable file to change it's executing user to the file's
59  * owner.
60  * In the case of a directory, it means that all immediate children will
61  * inherit the UID of the parent.
62  */
63 #define VFS_FFLAG_SETUID        0x08
64 /**
65  * \brief Set Group ID Flag
66  * 
67  * Allows an executable file to change it's executing group to the file's
68  * owning group.
69  * In the case of a directory, it means that all immediate children will
70  * inherit the GID of the parent.
71  */
72 #define VFS_FFLAG_SETGID        0x10
73
74 /**
75  * \brief "Don't do Write-Back" Flag
76  *
77  * Stops the VFS from calling tVFS_Node.Write on dirty pages when a region
78  * is unmapped. Nice for read-only files and memory-only files (or 
79  * pseudo-readonly filesystems)
80  */
81 #define VFS_FFLAG_NOWRITEBACK   0x1000
82
83 /**
84  * \brief "Dirty Metadata" Flag
85  *
86  * Indicates that the node's metadata has been altered since the flag was last
87  * cleared. Tells the driver that it should update the inode at the next flush.
88  */
89 #define VFS_FFLAG_DIRTY         0x8000
90 /**
91  * \}
92  */
93
94 /**
95  * \brief Represents a node (file or directory) in the VFS tree
96  * 
97  * This structure provides the VFS with the functions required to read/write
98  * the file (or directory) that it represents.
99  */
100 typedef struct sVFS_Node
101 {
102         /**
103          * \brief Functions associated with the node
104          */
105         tVFS_NodeType   *Type;
106         
107         /**
108          * \name Identifiers
109          * \brief Fields used by the driver to identify what data this node
110          *        corresponds to.
111          * \{
112          */
113         Uint64  Inode;  //!< Inode ID - Must identify the node uniquely if tVFS_Driver.GetNodeFromINode is non-NULL
114         Uint    ImplInt;        //!< Implementation Usable Integer
115         void    *ImplPtr;       //!< Implementation Usable Pointer
116         /**
117          * \}
118          */
119         
120         /**
121          * \name Node State
122          * \brief Stores the misc information about the node
123          * \{
124          */
125          int    ReferenceCount; //!< Number of times the node is used
126         
127         Uint64  Size;   //!< File Size
128         
129         Uint32  Flags;  //!< File Flags
130         
131         /**
132          * \brief Pointer to cached data (FS Specific)
133          * \note The Inode_* functions will free when the node is uncached
134          *       this if needed
135          */
136         void    *Data;
137         
138         /**
139          * \brief Node mutex
140          * \note Provided for the Filesystem driver's use
141          */
142         tMutex  Lock;
143         
144         /**
145          * \}
146          */
147         
148         /**
149          * \name Times
150          * \{
151          */
152         tTime   ATime;  //!< Last Accessed Time
153         tTime   MTime;  //!< Last Modified Time
154         tTime   CTime;  //!< Creation Time
155         /**
156          * \}
157          */
158         
159         /**
160          * \name Access control
161          * \{
162          */
163         tUID    UID;    //!< ID of Owning User
164         tGID    GID;    //!< ID of Owning Group
165         
166          int    NumACLs;        //!< Number of ACL entries
167         tVFS_ACL        *ACLs;  //!< Access Controll List pointer
168         /**
169          * \}
170          */
171         
172         /**
173          * \name VFS_Select() fields
174          * \note Used by the VFS internals, drivers should use VFS_Mark*
175          * \{
176          */
177          int    DataAvaliable;
178         tVFS_SelectList *ReadThreads;   //!< Threads waiting to read
179          int    BufferFull;
180         tVFS_SelectList *WriteThreads;  //!< Threads waiting to write
181          int    ErrorOccurred;
182         tVFS_SelectList *ErrorThreads;  //!< Threads waiting for an error
183         /**
184          * \}
185          */
186
187         /**
188          * \name VFS_MMap() fields
189          * \{
190          */
191         void    *MMapInfo;
192         /**
193          * \}
194          */
195 } tVFS_Node;
196
197 /**
198  * \brief Functions for a specific node type
199  */
200 struct sVFS_NodeType
201 {
202         /**
203          * \brief Debug name for the type
204          */
205         const char      *TypeName;
206
207         /**
208          * \name Common Functions
209          * \brief Functions that are used no matter the value of .Flags
210          * \{
211          */
212         /**
213          * \brief Reference the node
214          * \param Node Pointer to this node
215          */
216         void    (*Reference)(struct sVFS_Node *Node);
217         /**
218          * \brief Close (dereference) the node
219          * \param Node  Pointer to this node
220          * 
221          * Usually .Close is used to write any changes to the node back to
222          * the persistent storage.
223          */
224         void    (*Close)(struct sVFS_Node *Node);
225         
226         /**
227          * \brief Send an IO Control
228          * \param Node  Pointer to this node
229          * \param Id    IOCtl call number
230          * \param Data  Pointer to data to pass to the driver
231          * \return Implementation defined
232          */
233          int    (*IOCtl)(struct sVFS_Node *Node, int Id, void *Data);
234         
235         /**
236          * \}
237          */
238         
239         /**
240          * \name Buffer Functions
241          * \brief Functions for accessing a buffer-type file (normal file or
242          *        symbolic link)
243          * \{
244          */
245         
246         /**
247          * \brief Read from the file
248          * \param Node  Pointer to this node
249          * \param Offset        Byte offset in the file
250          * \param Length        Number of bytes to read
251          * \param Buffer        Destination for read data
252          * \return Number of bytes read
253          */
254         size_t  (*Read)(struct sVFS_Node *Node, off_t Offset, size_t Length, void *Buffer);
255         /**
256          * \brief Write to the file
257          * \param Node  Pointer to this node
258          * \param Offset        Byte offser in the file
259          * \param Length        Number of bytes to write
260          * \param Buffer        Source of written data
261          * \return Number of bytes read
262          */
263         size_t  (*Write)(struct sVFS_Node *Node, off_t Offset, size_t Length, const void *Buffer);
264
265         /**
266          * \brief Map a region of a file into memory
267          * \param Node  Pointer to this node
268          * \param Offset        Start of the region (page aligned)
269          * \param Length        Length of the region (page aligned)
270          * \param Dest  Location to which to map
271          * \return Boolean Failure
272          * \note If NULL, the VFS implements it using .Read
273          */
274          int    (*MMap)(struct sVFS_Node *Node, off_t Offset, int Length, void *Dest);
275         
276         /**
277          * \}
278          */
279         
280         /**
281          * \name Directory Functions
282          * \{
283          */
284         /**
285          * \brief Find an directory entry by name
286          * \param Node  Pointer to this node
287          * \param Name  Name of the file wanted
288          * \return Pointer to the requested node or NULL if it cannot be found
289          * \note The node returned must be accessable until ::tVFS_Node.Close
290          *       is called and ReferenceCount reaches zero.
291          */
292         struct sVFS_Node        *(*FindDir)(struct sVFS_Node *Node, const char *Name);
293         
294         /**
295          * \brief Read from a directory
296          * \param Node  Pointer to this node
297          * \param Pos   Offset in the directory
298          * \param Dest  Destination for filename
299          * \return Zero on success, negative on error or +ve for ignore entry
300          */
301          int    (*ReadDir)(struct sVFS_Node *Node, int Pos, char Dest[FILENAME_MAX]);
302         
303         /**
304          * \brief Create a node in a directory
305          * \param Node  Pointer to this node
306          * \param Name  Name of the new child
307          * \param Flags Flags to apply to the new child (directory or symlink)
308          * \return Created node or NULL on error
309          */
310         tVFS_Node       *(*MkNod)(struct sVFS_Node *Node, const char *Name, Uint Flags);
311         
312         /**
313          * \brief Relink (Rename/Remove) a file/directory
314          * \param Node  Pointer to this node
315          * \param OldName       Name of the item to move/delete
316          * \return Zero on Success, non-zero on error (see errno.h)
317          */
318          int    (*Unlink)(struct sVFS_Node *Node, const char *OldName);
319         
320         /**
321          * \brief Link a node to a name
322          * \param Node  Pointer to this node (directory)
323          * \param NewName       Name for the new link
324          * \param Child Node to create a new link to
325          * \retur Zeron on success, non-zero on error (see errno.h)
326          */
327          int    (*Link)(struct sVFS_Node *Node, const char *NewName, struct sVFS_Node *Child);
328          
329          /**
330           * \}
331           */
332 };
333
334 /**
335  * \brief VFS Driver (Filesystem) Definition
336  */
337 typedef struct sVFS_Driver
338 {
339         /**
340          * \brief Unique Identifier for this filesystem type
341          */
342         const char      *Name;
343         /**
344          * \brief Flags applying to this driver
345          */
346         Uint    Flags;
347         
348         /**
349          * \brief Detect if a volume is accessible using this driver
350          * \return Boolean success (with higher numbers being higher priority)
351          *
352          * E.g. FAT would return 1 as it's the lowest common denominator while ext2 might return 2,
353          * because it can be embedded in a FAT volume (and is a more fully featured filesystem).
354          */
355          int    (*Detect)(int FD);
356
357         /**
358          * \brief Callback to mount a device
359          */
360         tVFS_Node       *(*InitDevice)(const char *Device, const char **Options);
361         /**
362          * \brief Callback to unmount a device
363          */
364         void    (*Unmount)(tVFS_Node *Node);
365         /**
366          * \brief Retrieve a VFS node from an inode
367          */
368         tVFS_Node       *(*GetNodeFromINode)(tVFS_Node *RootNode, Uint64 InodeValue);
369         /**
370          * \brief Used internally (next driver in the chain)
371          */
372         struct sVFS_Driver      *Next;
373 } tVFS_Driver;
374
375 // === GLOBALS ===
376 //! \brief Maximum number of elements that can be skipped in one return
377 #define VFS_MAXSKIP     ((void*)1024)
378 //! \brief Skip a single entry in readdir
379 #define VFS_SKIP        ((void*)1)
380 //! \brief Skip \a n entries in readdir
381 #define VFS_SKIPN(n)    ((void*)(n))
382
383 extern tVFS_Node        NULLNode;       //!< NULL VFS Node (Ignored/Skipped)
384 /**
385  * \name Static ACLs
386  * \brief Simple ACLs to aid writing drivers
387  * \{
388  */
389 extern tVFS_ACL gVFS_ACL_EveryoneRWX;   //!< Everyone Read/Write/Execute
390 extern tVFS_ACL gVFS_ACL_EveryoneRW;    //!< Everyone Read/Write
391 extern tVFS_ACL gVFS_ACL_EveryoneRX;    //!< Everyone Read/Execute
392 extern tVFS_ACL gVFS_ACL_EveryoneRO;    //!< Everyone Read only
393 /**
394  * \}
395  */
396
397 // === FUNCTIONS ===
398 /**
399  * \fn int VFS_AddDriver(tVFS_Driver *Info)
400  * \brief Registers the driver with the DevFS layer
401  * \param Info  Driver information structure
402  */
403 extern int      VFS_AddDriver(tVFS_Driver *Info);
404 /**
405  * \brief Get the information structure of a driver given its name
406  * \param Name  Name of filesystem driver to find
407  */
408 extern tVFS_Driver      *VFS_GetFSByName(const char *Name);
409
410
411 /**
412  * \brief Prepare a node for use
413  */
414 extern void     VFS_InitNode(tVFS_Node *Node);
415
416 /**
417  * \brief Clean up a node, ready for deletion
418  * \note This should ALWAYS be called before a node is freed, as it
419  *       cleans up VFS internal structures.
420  */
421 extern void     VFS_CleanupNode(tVFS_Node *Node);
422
423 /**
424  * \fn tVFS_ACL *VFS_UnixToAcessACL(Uint Mode, Uint Owner, Uint Group)
425  * \brief Transforms Unix Permssions into Acess ACLs
426  * \param Mode  Unix RWXrwxRWX mask
427  * \param Owner UID of the file's owner
428  * \param Group GID of the file's owning group
429  * \return An array of 3 Acess ACLs
430  */
431 extern tVFS_ACL *VFS_UnixToAcessACL(Uint Mode, Uint Owner, Uint Group);
432
433 /**
434  * \brief Flags fro \a TypeFlag of VFS_SelectNode
435  * \{
436  */
437 #define VFS_SELECT_READ 0x01
438 #define VFS_SELECT_WRITE        0x02
439 #define VFS_SELECT_ERROR        0x04
440 /**
441  * \}
442  */
443
444 /**
445  * \brief Wait for an event on a node
446  * \param Node  Node to wait on
447  * \param Type  Type of wait
448  * \param Timeout       Time to wait (NULL for infinite wait)
449  * \param Name  Name to show in debug output
450  * \return Number of nodes that actioned (0 or 1)
451  */
452 extern int      VFS_SelectNode(tVFS_Node *Node, int Type, tTime *Timeout, const char *Name);
453
454 /**
455  * \brief Change the full flag on a node
456  */
457 extern int      VFS_MarkFull(tVFS_Node *Node, BOOL IsBufferFull);
458 /**
459  * \brief Alter the space avaliable flag on a node
460  */
461 extern int      VFS_MarkAvaliable(tVFS_Node *Node, BOOL IsDataAvaliable);
462 /**
463  * \brief Alter the error flags on a node
464  */
465 extern int      VFS_MarkError(tVFS_Node *Node, BOOL IsErrorState);
466
467 // --- Node Cache --
468 /**
469  * \name Node Cache
470  * \brief Functions to allow a node to be cached in memory by the VFS
471  * 
472  * These functions store a node for the driver, to prevent it from having
473  * to re-generate the node on each call to FindDir. It also allows for
474  * fast cleanup when a filesystem is unmounted.
475  * \{
476  */
477 /**
478  * \fn int Inode_GetHandle(void)
479  * \brief Gets a unique handle to the Node Cache
480  * \return A unique handle for use for the rest of the Inode_* functions
481  */
482 extern int      Inode_GetHandle(void);
483 /**
484  * \fn tVFS_Node *Inode_GetCache(int Handle, Uint64 Inode)
485  * \brief Gets an inode from the node cache
486  * \param Handle        A handle returned by Inode_GetHandle()
487  * \param Inode Value of the Inode field of the ::tVFS_Node you want
488  * \return A pointer to the cached node
489  */
490 extern tVFS_Node        *Inode_GetCache(int Handle, Uint64 Inode);
491 /**
492  * \fn tVFS_Node *Inode_CacheNode(int Handle, tVFS_Node *Node)
493  * \brief Caches a node in the Node Cache
494  * \param Handle        A handle returned by Inode_GetHandle()
495  * \param Node  A pointer to the node to be cached (a copy is taken)
496  * \return A pointer to the node in the node cache
497  */
498 extern tVFS_Node        *Inode_CacheNode(int Handle, tVFS_Node *Node);
499 /**
500  * \fn int Inode_UncacheNode(int Handle, Uint64 Inode)
501  * \brief Dereferences (and removes if needed) a node from the cache
502  * \param Handle        A handle returned by Inode_GetHandle()
503  * \param Inode Value of the Inode field of the ::tVFS_Node you want to remove
504  * \return -1: Error (not present), 0: Not freed, 1: Freed
505  */
506 extern int      Inode_UncacheNode(int Handle, Uint64 Inode);
507 /**
508  * \fn void Inode_ClearCache(int Handle)
509  * \brief Clears the cache for a handle
510  * \param Handle        A handle returned by Inode_GetHandle()
511  */
512 extern void     Inode_ClearCache(int Handle);
513
514 /**
515  * \}
516  */
517
518 #endif

UCC git Repository :: git.ucc.asn.au