From 990163cee7bc86c0c6123034234264abb7bbf53c Mon Sep 17 00:00:00 2001 From: John Hodge Date: Wed, 14 Apr 2010 12:22:27 +0800 Subject: [PATCH] Fixing API documentation, added Disk cache spec --- Kernel/Doxyfile.api | 8 ++++-- Kernel/include/apidoc_mainpage.h | 17 ++++++++++- Kernel/include/fs_devfs.h | 2 +- Kernel/include/tpl_drv_disk.h | 49 +++++++++++++++++++++++++------- 4 files changed, 62 insertions(+), 14 deletions(-) diff --git a/Kernel/Doxyfile.api b/Kernel/Doxyfile.api index d4454162..5b02591a 100644 --- 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 29a6c007..ca6a5da7 100644 --- 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 f75a7ffe..5589f4f9 100644 --- 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 2af6f551..47efb049 100644 --- 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, /** - * ioctl(..., tTplDisk_CacheRegion *Region) + * ioctl(..., tTplDisk_CacheRegion *RegionInfo) * \brief Sets the cache importantce and protocol for a section of * memory. - * \param Region Pointer to a region information structure + * \param RegionInfo Pointer to a region information structure * \return Boolean failure */ DISK_IOCTL_SETCACHEREGION, @@ -51,12 +51,24 @@ enum eTplDisk_IOCtl { /** * ioctl(..., Uint64 *Info[2]) * \brief Asks the driver to precache a region of disk. - * \param Info 64-bit Address and Size pair describing the area to cache + * \param Region 64-bit Address and Size pair describing the area to cache * \return Number of blocks cached */ - DISK_IOCTL_PRECACHE + DISK_IOCTL_PRECACHE, + + /** + * ioclt(..., Uint64 *Region[2]) + * \brief Asks to driver to flush the region back to disk + * \param Region 64-bit Address and Size pair describing the area to flush + * \note If Region[0] == -1 then the entire disk's cache is flushed + * \return Number of blocks flushed (or 0 for entire disk) + */ + DISK_IOCTL_FLUSH }; +/** + * \brief Describes the cache parameters of a region on the disk + */ typedef struct sTplDisk_CacheRegion { Uint64 Base; //!< Base of cache region @@ -71,7 +83,11 @@ typedef struct sTplDisk_CacheRegion */ Uint8 Flags; Uint8 Priority; //!< Lower is a higher proritory - Uint16 CacheSize; //!< Maximum size of cache, in blocks + /** + * \brief Maximum size of cache, in blocks + * \note If CacheSize is zero, the implemenation defined limit is used + */ + Uint16 CacheSize; } tTplDisk_CacheRegion; /** @@ -80,8 +96,9 @@ typedef struct sTplDisk_CacheRegion enum eTplDisk_CacheProtocols { /** - * \brief Region is not cached + * \brief Don't cache the region */ + DISK_CACHEPROTO_DONTCACHE, /** * \brief Most recently used blocks cached @@ -98,22 +115,30 @@ enum eTplDisk_CacheProtocols /** * \brief Cache only on demand * - * Only cache when the ::DISK_IOCTL_PRECACHE ioctl is used + * Only cache when the ::DISK_IOCTL_PRECACHE IOCtl is used */ DISK_CACHEPROTO_EXPLICIT }; + +/** + * \brief Flags for the cache + */ enum eTplDisk_CacheFlags { - DISK_CACHEFLAG_WRITETHROUGH + /** + * \brief Write all changes to the region straight back to media + */ + DISK_CACHEFLAG_WRITETHROUGH = 0x10 }; /** * \brief IOCtl name strings */ -#define DRV_DISK_IOCTLNAMES "get_block_size", "set_cache_region" +#define DRV_DISK_IOCTLNAMES "get_block_size","set_cache_region","set_precache" /** - * \section Disk Driver Utilities + * \name Disk Driver Utilities + * \{ */ /** @@ -152,4 +177,8 @@ extern Uint64 DrvUtil_WriteBlock(Uint64 Start, Uint64 Length, void *Buffer, tDrvUtil_Callback ReadBlocks, tDrvUtil_Callback WriteBlocks, Uint64 BlockSize, Uint Argument); +/** + * \} + */ + #endif -- 2.20.1