Kernel/include/tpl_drv_disk.h

   1 /**\r
   2  * \file tpl_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 _TPL_DRV_DISK_H\r
  25 #define _TPL_DRV_DISK_H\r
  26 \r
  27 #include <tpl_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 *Region)\r
  44          * \brief Sets the cache importantce and protocol for a section of\r
  45          *        memory.\r
  46          * \param Region        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 Info  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 typedef struct sTplDisk_CacheRegion\r
  61 {\r
  62         Uint64  Base;   //!< Base of cache region\r
  63         Uint64  Length; //!< Size of cache region\r
  64         /**\r
  65          * \brief Cache Protocol & Flags\r
  66          * \r
  67          * The low 4 bits denot the cache protocol to be used by the\r
  68          * region (see ::eTplDisk_CacheProtocols for a list).\r
  69          * The high 4 bits denote flags to apply to the cache (see\r
  70          * ::eTplDisk_CacheFlags)\r
  71          */\r
  72         Uint8   Flags;\r
  73         Uint8   Priority;       //!< Lower is a higher proritory\r
  74         Uint16  CacheSize;      //!< Maximum size of cache, in blocks\r
  75 }       tTplDisk_CacheRegion;\r
  76 \r
  77 /**\r
  78  * \brief Cache protocols to use\r
  79  */\r
  80 enum eTplDisk_CacheProtocols\r
  81 {\r
  82         /**\r
  83          * \brief Region is not cached\r
  84          */\r
  85         DISK_CACHEPROTO_DONTCACHE,\r
  86         /**\r
  87          * \brief Most recently used blocks cached\r
  88          * \note This is the default action for undefined regions\r
  89          */\r
  90         DISK_CACHEPROTO_RECENTLYUSED,\r
  91         /**\r
  92          * \brief Cache the entire region in memory\r
  93          * \r
  94          * This is a faster version of setting Length to CacheSize*BlockSize\r
  95          */\r
  96         DISK_CACHEPROTO_FULLCACHE,\r
  97         \r
  98         /**\r
  99          * \brief Cache only on demand\r
 100          * \r
 101          * Only cache when the ::DISK_IOCTL_PRECACHE ioctl is used\r
 102          */\r
 103         DISK_CACHEPROTO_EXPLICIT\r
 104 };\r
 105 enum eTplDisk_CacheFlags\r
 106 {\r
 107         DISK_CACHEFLAG_WRITETHROUGH\r
 108 };\r
 109 \r
 110 /**\r
 111  * \brief IOCtl name strings\r
 112  */\r
 113 #define DRV_DISK_IOCTLNAMES     "get_block_size", "set_cache_region"\r
 114 \r
 115 /**\r
 116  * \section Disk Driver Utilities\r
 117  */\r
 118 \r
 119 /**\r
 120  * \brief Callback function type used by DrvUtil_ReadBlock and DrvUtil_WriteBlock\r
 121  * \param Address       Zero based block number to read\r
 122  * \param Count Number of blocks to read\r
 123  * \param Buffer        Destination for read blocks\r
 124  * \param Argument      Argument provided in ::DrvUtil_ReadBlock and ::DrvUtil_WriteBlock\r
 125  */\r
 126 typedef Uint    (*tDrvUtil_Callback)(Uint64 Address, Uint Count, void *Buffer, Uint Argument);\r
 127 \r
 128 /**\r
 129  * \brief Reads a range from a block device using aligned reads\r
 130  * \param Start Base byte offset\r
 131  * \param Length        Number of bytes to read\r
 132  * \param Buffer        Destination for read data\r
 133  * \param ReadBlocks    Callback function to read a sequence of blocks\r
 134  * \param BlockSize     Size of an individual block\r
 135  * \param Argument      An argument to pass to \a ReadBlocks\r
 136  * \return Number of bytes read\r
 137  */\r
 138 extern Uint64 DrvUtil_ReadBlock(Uint64 Start, Uint64 Length, void *Buffer,\r
 139         tDrvUtil_Callback ReadBlocks, Uint64 BlockSize, Uint Argument);\r
 140 /**\r
 141  * \brief Writes a range to a block device using aligned writes\r
 142  * \param Start Base byte offset\r
 143  * \param Length        Number of bytes to write\r
 144  * \param Buffer        Destination for read data\r
 145  * \param ReadBlocks    Callback function to read a sequence of blocks\r
 146  * \param WriteBlocks   Callback function to write a sequence of blocks\r
 147  * \param BlockSize     Size of an individual block\r
 148  * \param Argument      An argument to pass to \a ReadBlocks and \a WriteBlocks\r
 149  * \return Number of bytes written\r
 150  */\r
 151 extern Uint64 DrvUtil_WriteBlock(Uint64 Start, Uint64 Length, void *Buffer,\r
 152         tDrvUtil_Callback ReadBlocks, tDrvUtil_Callback WriteBlocks,\r
 153         Uint64 BlockSize, Uint Argument);\r
 154 \r
 155 #endif\r