Fixing API documentation, added Disk cache spec

diff --git a/Kernel/Doxyfile.api b/Kernel/Doxyfile.api
index d445416..5b02591 100644 (file)
--- a/Kernel/Doxyfile.api
+++ b/Kernel/Doxyfile.api
@@ -570,11 +570,15 @@ INPUT                  = include/apidoc_mainpage.h \
                          include/binary.h \
                          include/modules.h \
                          include/vfs.h include/vfs_ext.h \
-                                                include/fs_devfs.h \
+                                                include/fs_devfs.h include/fs_sysfs.h \
                          include/iocache.h \
                          include/apidoc/arch_x86.h \
                          include/tpl_drv_common.h \
-                         include/tpl_drv_video.h
+                         include/tpl_drv_video.h \
+                         include/tpl_drv_terminal.h \
+                         include/tpl_drv_disk.h \
+                         include/tpl_drv_keyboard.h \
+                         include/tpl_drv_network.h
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 

diff --git a/Kernel/include/apidoc_mainpage.h b/Kernel/include/apidoc_mainpage.h
index 29a6c00..ca6a5da 100644 (file)
--- a/Kernel/include/apidoc_mainpage.h
+++ b/Kernel/include/apidoc_mainpage.h
@@ -42,7 +42,7 @@
  * VFS node. This node is used to provide the user access to the
  * driver's functions via IOCtl calls and Reading or Writing to the driver
  * file. Drivers are also able to expose a readonly buffer by using
- * \ref fs_proc.h ProcDev, usually to provide state information or device
+ * \ref fs_sysfs.h "ProcDev", usually to provide state information or device
  * capabilities for the the user.
  * 
  * The device driver interfaces are all based on the core specifcation
@@ -69,4 +69,19 @@
  * framebuffer (this may not be the true framebuffer, to allow for double-buffering)
  * to the user. See the full documentation in tpl_drv_video.h for the
  * complete specifcation.
+ * 
+ * \subsection drv_disk Disk/Storage Devices
+ * Storage devices present themselves as a linear collection of bytes.
+ * Reads and writes to the device need not be aligned to the stated block
+ * size, but it is suggested that users of a storage device file align
+ * their accesses to block boundaries.
+ * The functions DrvUtil_ReadBlock and DrvUtil_WriteBlock are provided
+ * to storage drivers to assist in handling non-alinged reads and writes.
+ * 
+ * \see tpl_drv_common.h Common Spec.
+ * \see tpl_drv_video.h Video Device Spec.
+ * \see tpl_drv_keyboard.h Keyboard Device Spec.
+ * \see tpl_drv_disk.h Disk/Storage Device Spec.
+ * \see tpl_drv_network.h Network Device Spec.
+ * \see tpl_drv_terminal.h Virtual Terminal Spec.
  */

diff --git a/Kernel/include/fs_devfs.h b/Kernel/include/fs_devfs.h
index f75a7ff..5589f4f 100644 (file)
--- a/Kernel/include/fs_devfs.h
+++ b/Kernel/include/fs_devfs.h
@@ -20,7 +20,7 @@ typedef struct sDevFS_Driver
 
 // === FUNCTIONS ===
 /**
- * \fn int DevFS_AddDevice(tDevFS_Driver *Dev)
+ * \fn int DevFS_AddDevice(tDevFS_Driver *Device)
  * \brief Registers a device in the Device Filesystem
  * \param Device       Pointer to a persistant structure that represents the driver
  * \return Boolean success

diff --git a/Kernel/include/tpl_drv_disk.h b/Kernel/include/tpl_drv_disk.h
index 2af6f55..47efb04 100644 (file)
--- a/Kernel/include/tpl_drv_disk.h
+++ b/Kernel/include/tpl_drv_disk.h
@@ -40,10 +40,10 @@ enum eTplDisk_IOCtl {
        DISK_IOCTL_GETBLOCKSIZE = 4,\r
        \r
        /**\r
-        * ioctl(..., tTplDisk_CacheRegion *Region)\r
+        * ioctl(..., tTplDisk_CacheRegion *RegionInfo)\r
         * \brief Sets the cache importantce and protocol for a section of\r
         *        memory.\r
-        * \param Region        Pointer to a region information structure\r
+        * \param RegionInfo    Pointer to a region information structure\r
         * \return Boolean failure\r
         */\r
        DISK_IOCTL_SETCACHEREGION,\r
@@ -51,12 +51,24 @@ enum eTplDisk_IOCtl {
        /**\r
         * ioctl(..., Uint64 *Info[2])\r
         * \brief Asks the driver to precache a region of disk.\r
-        * \param Info  64-bit Address and Size pair describing the area to cache\r
+        * \param Region        64-bit Address and Size pair describing the area to cache\r
         * \return Number of blocks cached\r
         */\r
-       DISK_IOCTL_PRECACHE\r
+       DISK_IOCTL_PRECACHE,\r
+       \r
+       /**\r
+        * ioclt(..., Uint64 *Region[2])\r
+        * \brief Asks to driver to flush the region back to disk\r
+        * \param Region        64-bit Address and Size pair describing the area to flush\r
+        * \note If Region[0] == -1 then the entire disk's cache is flushed\r
+        * \return Number of blocks flushed (or 0 for entire disk)\r
+        */\r
+       DISK_IOCTL_FLUSH\r
 };\r
 \r
+/**\r
+ * \brief Describes the cache parameters of a region on the disk\r
+ */\r
 typedef struct sTplDisk_CacheRegion\r
 {\r
        Uint64  Base;   //!< Base of cache region\r
@@ -71,7 +83,11 @@ typedef struct sTplDisk_CacheRegion
         */\r
        Uint8   Flags;\r
        Uint8   Priority;       //!< Lower is a higher proritory\r
-       Uint16  CacheSize;      //!< Maximum size of cache, in blocks\r
+       /**\r
+        * \brief Maximum size of cache, in blocks\r
+        * \note If CacheSize is zero, the implemenation defined limit is used\r
+        */\r
+       Uint16  CacheSize;\r
 }      tTplDisk_CacheRegion;\r
 \r
 /**\r
@@ -80,8 +96,9 @@ typedef struct sTplDisk_CacheRegion
 enum eTplDisk_CacheProtocols\r
 {\r
        /**\r
-        * \brief Region is not cached\r
+        * \brief Don't cache the region\r
         */\r
+       \r
        DISK_CACHEPROTO_DONTCACHE,\r
        /**\r
         * \brief Most recently used blocks cached\r
@@ -98,22 +115,30 @@ enum eTplDisk_CacheProtocols
        /**\r
         * \brief Cache only on demand\r
         * \r
-        * Only cache when the ::DISK_IOCTL_PRECACHE ioctl is used\r
+        * Only cache when the ::DISK_IOCTL_PRECACHE IOCtl is used\r
         */\r
        DISK_CACHEPROTO_EXPLICIT\r
 };\r
+\r
+/**\r
+ * \brief Flags for the cache\r
+ */\r
 enum eTplDisk_CacheFlags\r
 {\r
-       DISK_CACHEFLAG_WRITETHROUGH\r
+       /**\r
+        * \brief Write all changes to the region straight back to media\r
+        */\r
+       DISK_CACHEFLAG_WRITETHROUGH = 0x10\r
 };\r
 \r
 /**\r
  * \brief IOCtl name strings\r
  */\r
-#define        DRV_DISK_IOCTLNAMES     "get_block_size", "set_cache_region"\r
+#define        DRV_DISK_IOCTLNAMES     "get_block_size","set_cache_region","set_precache"\r
 \r
 /**\r
- * \section Disk Driver Utilities\r
+ * \name Disk Driver Utilities\r
+ * \{\r
  */\r
 \r
 /**\r
@@ -152,4 +177,8 @@ extern Uint64 DrvUtil_WriteBlock(Uint64 Start, Uint64 Length, void *Buffer,
        tDrvUtil_Callback ReadBlocks, tDrvUtil_Callback WriteBlocks,\r
        Uint64 BlockSize, Uint Argument);\r
 \r
+/**\r
+ * \}\r
+ */\r
+\r
 #endif\r