Kernel/include/api_drv_disk.h

   1 /**\r
   2  * \file api_drv_disk.h\r
   3  * \brief Disk Driver Interface Definitions\r
   4  * \author John Hodge (thePowersGang)\r
   5  * \r
   6  * \section Nomeclature\r
   7  * All addreses are 64-bit counts of bytes from the logical beginning of\r
   8  * the disk unless explicitly stated.\r
   9  * \r
  10  * \section dirs VFS Layout\r
  11  * Disk drivers have a flexible directory layout. The root directory can\r
  12  * contain subdirectories, with the only conditions being that all nodes\r
  13  * must support ::eTplDrv_IOCtl with DRV_IOCTL_TYPE returning DRV_TYPE_DISK.\r
  14  * And all file nodes representing disk devices (or partitions) and implemeting\r
  15  * ::eTplDisk_IOCtl fully\r
  16  * \r
  17  * \section files Files\r
  18  * When a read or write occurs on a normal file in the disk driver it will\r
  19  * read/write the represented device. The accesses need not be aligned to\r
  20  * the block size, however aligned reads/writes should be handled specially\r
  21  * to improve speed (this can be aided by using ::DrvUtil_ReadBlock and\r
  22  * ::DrvUtil_WriteBlock)\r
  23  */\r
  24 #ifndef _API_DRV_DISK_H\r
  25 #define _API_DRV_DISK_H\r
  26 \r
  27 #include <api_drv_common.h>\r
  28 \r
  29 /**\r
  30  * \enum eTplDisk_IOCtl\r
  31  * \brief Common Disk IOCtl Calls\r
  32  * \extends eTplDrv_IOCtl\r
  33  */\r
  34 enum eTplDisk_IOCtl {\r
  35         /**\r
  36          * ioctl(..., void)\r
  37          * \brief Get the block size\r
  38          * \return Size of a hardware block for this device\r
  39          */\r
  40         DISK_IOCTL_GETBLOCKSIZE = 4,\r
  41         \r
  42         /**\r
  43          * ioctl(..., tTplDisk_CacheRegion *RegionInfo)\r
  44          * \brief Sets the cache importantce and protocol for a section of\r
  45          *        memory.\r
  46          * \param RegionInfo    Pointer to a region information structure\r
  47          * \return Boolean failure\r
  48          */\r
  49         DISK_IOCTL_SETCACHEREGION,\r
  50         \r
  51         /**\r
  52          * ioctl(..., Uint64 *Info[2])\r
  53          * \brief Asks the driver to precache a region of disk.\r
  54          * \param Region        64-bit Address and Size pair describing the area to cache\r
  55          * \return Number of blocks cached\r
  56          */\r
  57         DISK_IOCTL_PRECACHE,\r
  58         \r
  59         /**\r
  60          * ioclt(..., Uint64 *Region[2])\r
  61          * \brief Asks to driver to flush the region back to disk\r
  62          * \param Region        64-bit Address and Size pair describing the area to flush\r
  63          * \note If Region[0] == -1 then the entire disk's cache is flushed\r
  64          * \return Number of blocks flushed (or 0 for entire disk)\r
  65          */\r
  66         DISK_IOCTL_FLUSH\r
  67 };\r
  68 \r
  69 /**\r
  70  * \brief Describes the cache parameters of a region on the disk\r
  71  */\r
  72 typedef struct sTplDisk_CacheRegion\r
  73 {\r
  74         Uint64  Base;   //!< Base of cache region\r
  75         Uint64  Length; //!< Size of cache region\r
  76         /**\r
  77          * \brief Cache Protocol & Flags\r
  78          * \r
  79          * The low 4 bits denot the cache protocol to be used by the\r
  80          * region (see ::eTplDisk_CacheProtocols for a list).\r
  81          * The high 4 bits denote flags to apply to the cache (see\r
  82          * ::eTplDisk_CacheFlags)\r
  83          */\r
  84         Uint8   Flags;\r
  85         Uint8   Priority;       //!< Lower is a higher proritory\r
  86         /**\r
  87          * \brief Maximum size of cache, in blocks\r
  88          * \note If CacheSize is zero, the implemenation defined limit is used\r
  89          */\r
  90         Uint16  CacheSize;\r
  91 }       tTplDisk_CacheRegion;\r
  92 \r
  93 /**\r
  94  * \brief Cache protocols to use\r
  95  */\r
  96 enum eTplDisk_CacheProtocols\r
  97 {\r
  98         /**\r
  99          * \brief Don't cache the region\r
 100          */\r
 101         \r
 102         DISK_CACHEPROTO_DONTCACHE,\r
 103         /**\r
 104          * \brief Most recently used blocks cached\r
 105          * \note This is the default action for undefined regions\r
 106          */\r
 107         DISK_CACHEPROTO_RECENTLYUSED,\r
 108         /**\r
 109          * \brief Cache the entire region in memory\r
 110          * \r
 111          * This is a faster version of setting Length to CacheSize*BlockSize\r
 112          */\r
 113         DISK_CACHEPROTO_FULLCACHE,\r
 114         \r
 115         /**\r
 116          * \brief Cache only on demand\r
 117          * \r
 118          * Only cache when the ::DISK_IOCTL_PRECACHE IOCtl is used\r
 119          */\r
 120         DISK_CACHEPROTO_EXPLICIT\r
 121 };\r
 122 \r
 123 /**\r
 124  * \brief Flags for the cache\r
 125  */\r
 126 enum eTplDisk_CacheFlags\r
 127 {\r
 128         /**\r
 129          * \brief Write all changes to the region straight back to media\r
 130          */\r
 131         DISK_CACHEFLAG_WRITETHROUGH = 0x10\r
 132 };\r
 133 \r
 134 /**\r
 135  * \brief IOCtl name strings\r
 136  */\r
 137 #define DRV_DISK_IOCTLNAMES     "get_block_size","set_cache_region","set_precache"\r
 138 \r
 139 /**\r
 140  * \name Disk Driver Utilities\r
 141  * \{\r
 142  */\r
 143 \r
 144 /**\r
 145  * \brief Callback function type used by DrvUtil_ReadBlock and DrvUtil_WriteBlock\r
 146  * \param Address       Zero based block number to read\r
 147  * \param Count Number of blocks to read\r
 148  * \param Buffer        Destination for read blocks\r
 149  * \param Argument      Argument provided in ::DrvUtil_ReadBlock and ::DrvUtil_WriteBlock\r
 150  */\r
 151 typedef Uint    (*tDrvUtil_Read_Callback)(Uint64 Address, Uint Count, void *Buffer, Uint Argument);\r
 152 typedef Uint    (*tDrvUtil_Write_Callback)(Uint64 Address, Uint Count, const void *Buffer, Uint Argument);\r
 153 \r
 154 /**\r
 155  * \brief Reads a range from a block device using aligned reads\r
 156  * \param Start Base byte offset\r
 157  * \param Length        Number of bytes to read\r
 158  * \param Buffer        Destination for read data\r
 159  * \param ReadBlocks    Callback function to read a sequence of blocks\r
 160  * \param BlockSize     Size of an individual block\r
 161  * \param Argument      An argument to pass to \a ReadBlocks\r
 162  * \return Number of bytes read\r
 163  */\r
 164 extern Uint64 DrvUtil_ReadBlock(Uint64 Start, Uint64 Length, void *Buffer,\r
 165         tDrvUtil_Read_Callback ReadBlocks, Uint64 BlockSize, Uint Argument);\r
 166 /**\r
 167  * \brief Writes a range to a block device using aligned writes\r
 168  * \param Start Base byte offset\r
 169  * \param Length        Number of bytes to write\r
 170  * \param Buffer        Destination for read data\r
 171  * \param ReadBlocks    Callback function to read a sequence of blocks\r
 172  * \param WriteBlocks   Callback function to write a sequence of blocks\r
 173  * \param BlockSize     Size of an individual block\r
 174  * \param Argument      An argument to pass to \a ReadBlocks and \a WriteBlocks\r
 175  * \return Number of bytes written\r
 176  */\r
 177 extern Uint64 DrvUtil_WriteBlock(Uint64 Start, Uint64 Length, const void *Buffer,\r
 178         tDrvUtil_Read_Callback ReadBlocks, tDrvUtil_Write_Callback WriteBlocks,\r
 179         Uint64 BlockSize, Uint Argument);\r
 180 \r
 181 /**\r
 182  * \}\r
 183  */\r
 184 \r
 185 #endif\r