Kernel - Fixed screen not updating in VT framebuffer mode
[tpg/acess2.git] / KernelLand / Kernel / include / iocache.h
1 /*
2  * Acess2 Kernel
3  * - IO Cache
4  * 
5  * By thePowersGang (John Hodge)
6  */
7 /**
8  * \file iocache.h
9  * \brief I/O Caching Helper Subsystem
10  * 
11  * The IO Cache abstracts caching of disk sectors away from the device
12  * driver to reduce code duplication and allow a central location for
13  * disk cache management that can be flushed simply by the kernel, without
14  * having to ask each driver to do it indivitually.
15  */
16 #ifndef _IOCHACHE_H_
17 #define _IOCHACHE_H_
18
19 // === TYPES ===
20 /**
21  * \brief IO Cache Handle
22  */
23 typedef struct sIOCache tIOCache;
24 /**
25  * \brief Write Callback
26  * 
27  * Called to write a sector back to the device
28  */
29 typedef int     (*tIOCache_WriteCallback)(Uint32 ID, Uint64 Sector, void *Buffer);
30
31 // === CONSTANTS ===
32 /**
33  * \brief I/O Cache handling modes
34  */
35 enum eIOCache_Modess {
36         /**
37          * \brief Writeback
38          * 
39          * Transparently writes data straight to the device when the cache
40          * is written to.
41          */
42         IOCACHE_WRITEBACK,
43         /**
44          * \brief Delay Write
45          * 
46          * Only writes when instructed to (by ::IOCache_Flush) or when a
47          * cached sector is being reallocated.
48          */
49         IOCACHE_DELAYWRITE,
50         /**
51          * \brief Virtual - No Writes
52          * 
53          * Changes to the cache contents are only reflected in memory,
54          * any calls to ::IOCache_Flush will silently return without doing
55          * anything and if a sector is reallocated, all changes will be lost
56          */
57         IOCACHE_VIRTUAL
58 };
59
60 // === FUNCTIONS ===
61 /**
62  * \brief Creates a new IO Cache
63  * \param Write Function to call to write a sector to the device
64  * \param ID    ID to pass to \a Write
65  * \param SectorSize    Size of a cached sector
66  * \param CacheSize     Maximum number of objects that can be in the cache at one time
67  */
68 tIOCache        *IOCache_Create( tIOCache_WriteCallback Write, Uint32 ID, int SectorSize, int CacheSize );
69
70 /**
71  * \brief Reads from a cached sector
72  * \param Cache Cache handle returned by ::IOCache_Create
73  * \param Sector        Sector's ID number
74  * \param Buffer        Destination for the data read
75  * \return      1 if the data was read, 0 if the sector is not cached, -1 on error
76  */
77  int    IOCache_Read( tIOCache *Cache, Uint64 Sector, void *Buffer );
78
79 /**
80  * \brief Adds a sector to the cache
81  * \param Cache Cache handle returned by ::IOCache_Create
82  * \param Sector        Sector's ID number
83  * \param Buffer        Data to cache
84  * \return      1 on success, 0 if the sector is already cached, -1 on error
85  */
86  int    IOCache_Add( tIOCache *Cache, Uint64 Sector, void *Buffer );
87
88 /**
89  * \brief Writes to a cached sector
90  * \param Cache Cache handle returned by ::IOCache_Create
91  * \param Sector        Sector's ID number
92  * \param Buffer        Data to write to the cache
93  * \return      1 if the data was read, 0 if the sector is not cached, -1 on error
94  * 
95  * If the sector is in the cache, it is updated.
96  * Wether the Write callback is called depends on the selected caching
97  * behaviour.
98  */
99  int    IOCache_Write( tIOCache *Cache, Uint64 Sector, void *Buffer );
100
101 /**
102  * \brief Flush altered sectors out to the device
103  * \param Cache Cache handle returned by ::IOCache_Create
104  * 
105  * This will call the cache's write callback on each altered sector
106  * to flush the write cache.
107  */
108 void    IOCache_Flush( tIOCache *Cache );
109
110 /**
111  * \brief Flushes the cache and then removes it
112  * \param Cache Cache handle returned by ::IOCache_Create
113  * \note After this is called \a Cache is no longer valid
114  * 
115  * IOCache_Destroy writes all changed sectors to the device and then
116  * deallocates the cache for other systems to use.
117  */
118 void    IOCache_Destroy( tIOCache *Cache );
119
120 #endif

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