include/tpl_drv_disk.h File Reference

---

Detailed Description

Disk Driver Interface Definitions.

Author:

John Hodge (thePowersGang)

Nomeclature

All addreses are 64-bit counts of bytes from the logical beginning of the disk unless explicitly stated.

VFS Layout

Disk drivers have a flexible directory layout. The root directory can contain subdirectories, with the only conditions being that all nodes must support eTplDrv_IOCtl with DRV_IOCTL_TYPE returning DRV_TYPE_DISK. And all file nodes representing disk devices (or partitions) and implemeting eTplDisk_IOCtl fully

Files

When a read or write occurs on a normal file in the disk driver it will read/write the represented device. The accesses need not be aligned to the block size, however aligned reads/writes should be handled specially to improve speed (this can be aided by using DrvUtil_ReadBlock and DrvUtil_WriteBlock)

Go to the source code of this file.

Data Structures
struct	tTplDisk_CacheRegion
	Describes the cache parameters of a region on the disk. More...
Defines
#define	DRV_DISK_IOCTLNAMES   "get_block_size","set_cache_region","set_precache"
	IOCtl name strings.
Enumerations
enum	eTplDisk_IOCtl { DISK_IOCTL_GETBLOCKSIZE = 4, DISK_IOCTL_SETCACHEREGION, DISK_IOCTL_PRECACHE, DISK_IOCTL_FLUSH }
	Common Disk IOCtl Calls. More...
enum	eTplDisk_CacheProtocols { DISK_CACHEPROTO_DONTCACHE, DISK_CACHEPROTO_RECENTLYUSED, DISK_CACHEPROTO_FULLCACHE, DISK_CACHEPROTO_EXPLICIT }
	Cache protocols to use. More...
enum	eTplDisk_CacheFlags { DISK_CACHEFLAG_WRITETHROUGH = 0x10 }
	Flags for the cache. More...
Disk Driver Utilities
typedef Uint(*	tDrvUtil_Callback )(Uint64 Address, Uint Count, void *Buffer, Uint Argument)
	Callback function type used by DrvUtil_ReadBlock and DrvUtil_WriteBlock.
Uint64	DrvUtil_ReadBlock (Uint64 Start, Uint64 Length, void *Buffer, tDrvUtil_Callback ReadBlocks, Uint64 BlockSize, Uint Argument)
	Reads a range from a block device using aligned reads.
Uint64	DrvUtil_WriteBlock (Uint64 Start, Uint64 Length, void *Buffer, tDrvUtil_Callback ReadBlocks, tDrvUtil_Callback WriteBlocks, Uint64 BlockSize, Uint Argument)
	Writes a range to a block device using aligned writes.

---

Typedef Documentation

typedef Uint(* tDrvUtil_Callback)(Uint64 Address, Uint Count, void *Buffer, Uint Argument)

Callback function type used by DrvUtil_ReadBlock and DrvUtil_WriteBlock.

Parameters:

	Address	Zero based block number to read
	Count	Number of blocks to read
	Buffer	Destination for read blocks
	Argument	Argument provided in DrvUtil_ReadBlock and DrvUtil_WriteBlock

---

Enumeration Type Documentation

enum eTplDisk_CacheFlags

Flags for the cache.

Enumerator:

DISK_CACHEFLAG_WRITETHROUGH

Write all changes to the region straight back to media.

enum eTplDisk_CacheProtocols

Cache protocols to use.

Enumerator:

DISK_CACHEPROTO_DONTCACHE	Don't cache the region.
DISK_CACHEPROTO_RECENTLYUSED	Most recently used blocks cached. Note: This is the default action for undefined regions
DISK_CACHEPROTO_FULLCACHE	Cache the entire region in memory. This is a faster version of setting Length to CacheSize*BlockSize
DISK_CACHEPROTO_EXPLICIT	Cache only on demand. Only cache when the DISK_IOCTL_PRECACHE IOCtl is used

enum eTplDisk_IOCtl

Common Disk IOCtl Calls.

Enumerator:

DISK_IOCTL_GETBLOCKSIZE	Get the block size. ioctl(..., void) Returns: Size of a hardware block for this device
DISK_IOCTL_SETCACHEREGION	Sets the cache importantce and protocol for a section of memory. ioctl(..., tTplDisk_CacheRegion *RegionInfo) Parameters: RegionInfo  Pointer to a region information structure Returns: Boolean failure
DISK_IOCTL_PRECACHE	Asks the driver to precache a region of disk. ioctl(..., Uint64 *Info[2]) Parameters: Region  64-bit Address and Size pair describing the area to cache Returns: Number of blocks cached
DISK_IOCTL_FLUSH	Asks to driver to flush the region back to disk. ioclt(..., Uint64 *Region[2]) Parameters: 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 Returns: Number of blocks flushed (or 0 for entire disk)

---

Function Documentation

Uint64 DrvUtil_ReadBlock	(	Uint64	Start,
		Uint64	Length,
		void *	Buffer,
		tDrvUtil_Callback	ReadBlocks,
		Uint64	BlockSize,
		Uint	Argument
	)

Reads a range from a block device using aligned reads.

Parameters:

	Start	Base byte offset
	Length	Number of bytes to read
	Buffer	Destination for read data
	ReadBlocks	Callback function to read a sequence of blocks
	BlockSize	Size of an individual block
	Argument	An argument to pass to ReadBlocks

Returns:

Number of bytes read

Uint64 DrvUtil_WriteBlock	(	Uint64	Start,
		Uint64	Length,
		void *	Buffer,
		tDrvUtil_Callback	ReadBlocks,
		tDrvUtil_Callback	WriteBlocks,
		Uint64	BlockSize,
		Uint	Argument
	)

Writes a range to a block device using aligned writes.

Parameters:

	Start	Base byte offset
	Length	Number of bytes to write
	Buffer	Destination for read data
	ReadBlocks	Callback function to read a sequence of blocks
	WriteBlocks	Callback function to write a sequence of blocks
	BlockSize	Size of an individual block
	Argument	An argument to pass to ReadBlocks and WriteBlocks

Returns:

Number of bytes written