BlockOperations Struct Reference
[Block device manager and block interface]

Structure of operations for block devices. More...

#include <block.h>


Data Fields

int(* request )(int function,...)
 Requests an operation not included in this structure.
int(* open )(void *handle)
 Opens a block device.
int(* revalidate )(void *handle)
 Revalidates a block device.
int(* close )(void *handle)
 Closes a block device.
int(* get_device_info )(void *handle, BlockDeviceInfo *buf)
 Gets information about a block device.
int(* get_medium_info )(void *handle, BlockMediumInfo *buf)
 Gets information about the medium implementing the block device.
ssize_t(* read )(void *handle, void *buffer, uint64_t start, size_t count, int flags)
 Reads data from a block device.
ssize_t(* write )(void *handle, const void *buffer, uint64_t start, size_t count, int flags)
 Writes data to a block device.
int(* sync )(void *handle)
 Flushes any cached data to the block device.
int(* test_unit_ready )(void *handle)
 Queries the device for medium status.


Detailed Description

Structure of operations for block devices.

Definition at line 181 of file block.h.


Field Documentation

int(* BlockOperations::request)(int function,...)

Requests an operation not included in this structure.

Remarks:
In general it is not required to claim the device using the open operation before calling the request function.

The caller shall release the device when it is no longer needed using REQ_RELEASE.

Arguments and return value depends on the specified function.

int(* BlockOperations::open)(void *handle)

Opens a block device.

Parameters:
handle opaque identifier of the block device.
Returns:
0 on success, or a negative error.
Remarks:
This operation shall be called before using any other operation on a block device (unless the operation is marked with a specific exception) to claim the use of the device.

The block device driver shall perform any required initialization, such as probing the medium format and initializing its cache.

This operation shall try to acquire an exclusive advisory lock, so that the caller can gain exclusive access to the block device. If the lock cannot be successfully acquired, the caller shall not use the block device.

This operation shall be atomic.

int(* BlockOperations::revalidate)(void *handle)

Revalidates a block device.

Parameters:
handle opaque identifier of the block device.
Returns:
0 on success, or a negative error.
Remarks:
This operation shall be called when an error condition requiring to revalidate the device is reported, that is an "attention" sense key (this could happen, for example, due to media change).

The block device driver must perform any required reinitialization, such as probing the medium format, and should keep its cache if it has one.

As a typical consequential action, the caller may read some data structure stored on the block device (such as a serial number) to check for media change, of course disabling any cache to do this read. The caller may cause any subsequent action requiring the old media (for example, a mounted file system) to fail, or may eventually invalidate any cache by closing the device. The caller must assure that these steps are performed atomically in response to an error with an "attention" sense key.

int(* BlockOperations::close)(void *handle)

Closes a block device.

Parameters:
handle opaque identifier of the block device.
Returns:
0 on success, or a negative error.
Remarks:
This operation must be called when the block device is no longer needed to unclaim it.

The block device driver must perform any required cleanup, release its exclusive lock and discard any pending cached data.

Gets information about a block device.

Parameters:
handle opaque identifier of the block device;
buf address of a buffer to obtain device information.
Returns:
0 on success, or a negative error.
Remarks:
Information returned by this operation is not dependent on the medium currently loaded (for example, the drive type), thus this function may be called even if the device has not been claimed using the open operation.

Gets information about the medium implementing the block device.

Parameters:
handle opaque identifier of the block device;
buf address of a buffer to obtain medium information.
Returns:
0 on success, or a negative error.
Remarks:
Information returned by this operation depends on the medium currently loaded, such as its capacity. Thus the medium must be first probed using the open or revalidate operations. In fact, this operation is often called right after open or revalidate.

ssize_t(* BlockOperations::read)(void *handle, void *buffer, uint64_t start, size_t count, int flags)

Reads data from a block device.

Parameters:
handle opaque identifier of the block device;
buffer address of a buffer to obtain the data read;
start block number of the first block to transfer;
count number of block to transfer;
flags a combination of flags specified by enum BlockReadWriteFlags.
Returns:
The non-negative number of blocks transferred (may be less than the required count of blocks near to the end of the device), or a negative error.

ssize_t(* BlockOperations::write)(void *handle, const void *buffer, uint64_t start, size_t count, int flags)

Writes data to a block device.

Parameters:
handle opaque identifier of the block device;
buffer address of a buffer containing the data to write;
start block number of the first block to transfer;
count number of block to transfer.
flags a combination of flags specified by enum BlockReadWriteFlags.
Returns:
The non-negative number of blocks transferred (may be less than the required count of blocks near to the end of the device), or a negative error.

int(* BlockOperations::sync)(void *handle)

Flushes any cached data to the block device.

Parameters:
handle opaque identifier of the block device.
Returns:
0 on success, or a negative error.
Remarks:
The block device driver must write any pending cached data to the block device.

In particular this operation should be called before closing the device in order to save any cached data that would be otherwise discarded. The caller must assure that no other writes occur between the calls to sync and close.

int(* BlockOperations::test_unit_ready)(void *handle)

Queries the device for medium status.

Parameters:
handle opaque identifier of the block device.
Returns:
0 on success, or a negative error.
Remarks:
In particular this operation may fail with a BLOCK_SENSE_ATTENTION sense key, meaning that the medium may have been changed.


The documentation for this struct was generated from the following file:

Generated on Sun Aug 31 13:31:36 2008 for FrankenRTOS by  doxygen 1.5.6