Kernel - Fixed screen not updating in VT framebuffer mode
[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          * \return Pointer to the name of the item on the heap (will be freed
299          *         by the caller). If the directory end has been reached, NULL
300          *         will be returned.
301          *         If an item is required to be skipped either &::NULLNode,
302          *         ::VFS_SKIP or ::VFS_SKIPN(0...1023) will be returned.
303          */
304         char    *(*ReadDir)(struct sVFS_Node *Node, int Pos);
305         
306         /**
307          * \brief Create a node in a directory
308          * \param Node  Pointer to this node
309          * \param Name  Name of the new child
310          * \param Flags Flags to apply to the new child (directory or symlink)
311          * \return Zero on Success, non-zero on error (see errno.h)
312          */
313          int    (*MkNod)(struct sVFS_Node *Node, const char *Name, Uint Flags);
314         
315         /**
316          * \brief Relink (Rename/Remove) a file/directory
317          * \param Node  Pointer to this node
318          * \param OldName       Name of the item to move/delete
319          * \return Zero on Success, non-zero on error (see errno.h)
320          */
321          int    (*Unlink)(struct sVFS_Node *Node, const char *OldName);
322         
323         /**
324          * \brief Link a node to a name
325          * \param Node  Pointer to this node (directory)
326          * \param NewName       Name for the new link
327          * \param Child Node to create a new link to
328          * \retur Zeron on success, non-zero on error (see errno.h)
329          */
330          int    (*Link)(struct sVFS_Node *Node, const char *NewName, struct sVFS_Node *Child);
331          
332          /**
333           * \}
334           */
335 };
336
337 /**
338  * \brief VFS Driver (Filesystem) Definition
339  */
340 typedef struct sVFS_Driver
341 {
342         /**
343          * \brief Unique Identifier for this filesystem type
344          */
345         const char      *Name;
346         /**
347          * \brief Flags applying to this driver
348          */
349         Uint    Flags;
350         
351         /**
352          * \brief Detect if a volume is accessible using this driver
353          * \return Boolean success (with higher numbers being higher priority)
354          *
355          * E.g. FAT would return 1 as it's the lowest common denominator while ext2 might return 2,
356          * because it can be embedded in a FAT volume (and is a more fully featured filesystem).
357          */
358          int    (*Detect)(int FD);
359
360         /**
361          * \brief Callback to mount a device
362          */
363         tVFS_Node       *(*InitDevice)(const char *Device, const char **Options);
364         /**
365          * \brief Callback to unmount a device
366          */
367         void    (*Unmount)(tVFS_Node *Node);
368         /**
369          * \brief Retrieve a VFS node from an inode
370          */
371         tVFS_Node       *(*GetNodeFromINode)(tVFS_Node *RootNode, Uint64 InodeValue);
372         /**
373          * \brief Used internally (next driver in the chain)
374          */
375         struct sVFS_Driver      *Next;
376 } tVFS_Driver;
377
378 // === GLOBALS ===
379 //! \brief Maximum number of elements that can be skipped in one return
380 #define VFS_MAXSKIP     ((void*)1024)
381 //! \brief Skip a single entry in readdir
382 #define VFS_SKIP        ((void*)1)
383 //! \brief Skip \a n entries in readdir
384 #define VFS_SKIPN(n)    ((void*)(n))
385
386 extern tVFS_Node        NULLNode;       //!< NULL VFS Node (Ignored/Skipped)
387 /**
388  * \name Static ACLs
389  * \brief Simple ACLs to aid writing drivers
390  * \{
391  */
392 extern tVFS_ACL gVFS_ACL_EveryoneRWX;   //!< Everyone Read/Write/Execute
393 extern tVFS_ACL gVFS_ACL_EveryoneRW;    //!< Everyone Read/Write
394 extern tVFS_ACL gVFS_ACL_EveryoneRX;    //!< Everyone Read/Execute
395 extern tVFS_ACL gVFS_ACL_EveryoneRO;    //!< Everyone Read only
396 /**
397  * \}
398  */
399
400 // === FUNCTIONS ===
401 /**
402  * \fn int VFS_AddDriver(tVFS_Driver *Info)
403  * \brief Registers the driver with the DevFS layer
404  * \param Info  Driver information structure
405  */
406 extern int      VFS_AddDriver(tVFS_Driver *Info);
407 /**
408  * \brief Get the information structure of a driver given its name
409  * \param Name  Name of filesystem driver to find
410  */
411 extern tVFS_Driver      *VFS_GetFSByName(const char *Name);
412
413
414 /**
415  * \brief Prepare a node for use
416  */
417 extern void     VFS_InitNode(tVFS_Node *Node);
418
419 /**
420  * \brief Clean up a node, ready for deletion
421  * \note This should ALWAYS be called before a node is freed, as it
422  *       cleans up VFS internal structures.
423  */
424 extern void     VFS_CleanupNode(tVFS_Node *Node);
425
426 /**
427  * \fn tVFS_ACL *VFS_UnixToAcessACL(Uint Mode, Uint Owner, Uint Group)
428  * \brief Transforms Unix Permssions into Acess ACLs
429  * \param Mode  Unix RWXrwxRWX mask
430  * \param Owner UID of the file's owner
431  * \param Group GID of the file's owning group
432  * \return An array of 3 Acess ACLs
433  */
434 extern tVFS_ACL *VFS_UnixToAcessACL(Uint Mode, Uint Owner, Uint Group);
435
436 /**
437  * \brief Flags fro \a TypeFlag of VFS_SelectNode
438  * \{
439  */
440 #define VFS_SELECT_READ 0x01
441 #define VFS_SELECT_WRITE        0x02
442 #define VFS_SELECT_ERROR        0x04
443 /**
444  * \}
445  */
446
447 /**
448  * \brief Wait for an event on a node
449  * \param Node  Node to wait on
450  * \param Type  Type of wait
451  * \param Timeout       Time to wait (NULL for infinite wait)
452  * \param Name  Name to show in debug output
453  * \return Number of nodes that actioned (0 or 1)
454  */
455 extern int      VFS_SelectNode(tVFS_Node *Node, int Type, tTime *Timeout, const char *Name);
456
457 /**
458  * \brief Change the full flag on a node
459  */
460 extern int      VFS_MarkFull(tVFS_Node *Node, BOOL IsBufferFull);
461 /**
462  * \brief Alter the space avaliable flag on a node
463  */
464 extern int      VFS_MarkAvaliable(tVFS_Node *Node, BOOL IsDataAvaliable);
465 /**
466  * \brief Alter the error flags on a node
467  */
468 extern int      VFS_MarkError(tVFS_Node *Node, BOOL IsErrorState);
469
470 // --- Node Cache --
471 /**
472  * \name Node Cache
473  * \brief Functions to allow a node to be cached in memory by the VFS
474  * 
475  * These functions store a node for the driver, to prevent it from having
476  * to re-generate the node on each call to FindDir. It also allows for
477  * fast cleanup when a filesystem is unmounted.
478  * \{
479  */
480 /**
481  * \fn int Inode_GetHandle(void)
482  * \brief Gets a unique handle to the Node Cache
483  * \return A unique handle for use for the rest of the Inode_* functions
484  */
485 extern int      Inode_GetHandle(void);
486 /**
487  * \fn tVFS_Node *Inode_GetCache(int Handle, Uint64 Inode)
488  * \brief Gets an inode from the node cache
489  * \param Handle        A handle returned by Inode_GetHandle()
490  * \param Inode Value of the Inode field of the ::tVFS_Node you want
491  * \return A pointer to the cached node
492  */
493 extern tVFS_Node        *Inode_GetCache(int Handle, Uint64 Inode);
494 /**
495  * \fn tVFS_Node *Inode_CacheNode(int Handle, tVFS_Node *Node)
496  * \brief Caches a node in the Node Cache
497  * \param Handle        A handle returned by Inode_GetHandle()
498  * \param Node  A pointer to the node to be cached (a copy is taken)
499  * \return A pointer to the node in the node cache
500  */
501 extern tVFS_Node        *Inode_CacheNode(int Handle, tVFS_Node *Node);
502 /**
503  * \fn int Inode_UncacheNode(int Handle, Uint64 Inode)
504  * \brief Dereferences (and removes if needed) a node from the cache
505  * \param Handle        A handle returned by Inode_GetHandle()
506  * \param Inode Value of the Inode field of the ::tVFS_Node you want to remove
507  * \return -1: Error (not present), 0: Not freed, 1: Freed
508  */
509 extern int      Inode_UncacheNode(int Handle, Uint64 Inode);
510 /**
511  * \fn void Inode_ClearCache(int Handle)
512  * \brief Clears the cache for a handle
513  * \param Handle        A handle returned by Inode_GetHandle()
514  */
515 extern void     Inode_ClearCache(int Handle);
516
517 /**
518  * \}
519  */
520
521 #endif

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