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