Kernel/VFS - Fixed debug in open.c
[tpg/acess2.git] / KernelLand / 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, void *Argument);\r
152 typedef Uint    (*tDrvUtil_Write_Callback)(Uint64 Address, Uint Count, const void *Buffer, void *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, void *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, void *Argument);\r
180 \r
181 /**\r
182  * \}\r
183  */\r
184 \r
185 #endif\r

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