EFI BLOCK IO PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol provides control over block devices.

Contents

GUID

#define EFI_BLOCK_IO_PROTOCOL_GUID \
  {0x964e5b21,0x6459,0x11d2,0x8e,0x39,0x00,0xa0,0xc9,0x69,0x72,0x3b}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(BlockIo)
extern EFI_GUID gEfiBlockIoProtocolGuid;
typedef struct _EFI_BLOCK_IO_PROTOCOL {
  UINT64             Revision;
  EFI_BLOCK_IO_MEDIA *Media;
  EFI_BLOCK_RESET    Reset;
  EFI_BLOCK_READ     ReadBlocks;
  EFI_BLOCK_WRITE    WriteBlocks;
  EFI_BLOCK_FLUSH    FlushBlocks;
} EFI_BLOCK_IO_PROTOCOL;
#define EFI_BLOCK_IO_PROTOCOL_REVISION 0x00010000

Members

Member Description
Revision The revision to which the block IO interface adheres. All future revisions must be backwards compatible. If a future version is not back wards compatible it is not the same GUID.
Media A pointer to the EFI_BLOCK_IO_MEDIA data for this device.
Reset Resets the block device hardware.
ReadBlocks Reads the requested number of blocks from the device.
WriteBlocks Writes the requested number of blocks to the device.
FlushBlocks Flushes and cache blocks. This function is optional and only needs to be supported on block devices that cache writes.

Description

The firmware is responsible for adding an EFI_DISK_IO_PROTOCOL interface to every EFI_BLOCK_IO_PROTOCOL interface in the system. The EFI_DISK_IO_PROTOCOL interface allows byte-level access to devices.

Reset()

Resets the block device hardware.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BLOCK_RESET) (
  IN EFI_BLOCK_IO_PROTOCOL *This,
  IN BOOLEAN ExtendedVerification);

Parameters

Member Description
This Indicates a pointer to the calling context.
ExtendedVerification Indicates that the driver may perform a more exhaustive verification operation of the device during reset.

Description
The Reset() function resets the block device hardware.

As part of the initialization process, the firmware/device will make a quick but reasonable attempt to verify that the device is functioning. If the ExtendedVerification flag is TRUE the firmware may take an extended amount of time to verify the device is operating on reset.

Otherwise the reset operation is to occur as quickly as possible.

The hardware verification process is not defined by this specification and is left up to the platform firmware or driver to implement.

Status Codes Returned

Status Code Description
EFI_SUCCESS The block device was reset.
EFI_DEVICE_ERROR The block device is not functioning correctly and could not be reset.

ReadBlocks()

Reads the requested number of blocks from the device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BLOCK_READ) (
  IN EFI_BLOCK_IO_PROTOCOL *This,
  IN UINT32 MediaId,
  IN EFI_LBA LBA,
  IN UINTN BufferSize,
  OUT VOID *Buffer);

Parameters

Parameter Description
This Indicates a pointer to the calling context.
MediaId The media ID that the read request is for.
LBA The starting logical block address to read from on the device.
BufferSize The size of the Buffer in bytes. This must be a multiple of the intrinsic block size of the device.
Buffer A pointer to the destination buffer for the data. The caller is responsible for either having implicit or explicit ownership of the buffer.

Description
The ReadBlocks() function reads the requested number of blocks from the device. All the blocks are read, or an error is returned.

If there is no media in the device, the function returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, the function returns EFI_MEDIA_CHANGED.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read correctly from the device.
EFI_DEVICE_ERROR The device reported an error while attempting to perform the read operation.
EFI_NO_MEDIA There is no media in the device.
EFI_MEDIA_CHANGED The MediaId is not for the current media.
EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, or the buffer is not on proper alignment.

WriteBlocks()

Writes a specified number of blocks to the device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BLOCK_WRITE) (
  IN EFI_BLOCK_IO_PROTOCOL *This,
  IN UINT32 MediaId,
  IN EFI_LBA LBA,
  IN UINTN BufferSize,
  IN VOID *Buffer);

Parameters

Parameter Description
This Indicates a pointer to the calling context.
MediaId The media ID that the write request is for.
LBA The starting logical block address to be written. The caller is responsible for writing to only legitimate locations.
BufferSize The size in bytes of Buffer. This must be a multiple of the intrinsic block size of the device.
Buffer A pointer to the source buffer for the data.

Description
The WriteBlocks() function writes the requested number of blocks to the device. All blocks are written, or an error is returned.

If there is no media in the device, the function returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, the function returns EFI_MEDIA_CHANGED.

Status Codes Returned

Parameter Description
EFI_SUCCESS The data were written correctly to the device.
EFI_WRITE_PROTECTED The device cannot be written to.
EFI_NO_MEDIA There is no media in the device.
EFI_MEDIA_CHANGED The MediaId is not for the current media.
EFI_DEVICE_ERROR The device reported an error while attempting to perform the write operation.
EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, or the buffer is not on proper alignment.

FlushBlocks()

Flushes all modified data to a physical block device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BLOCK_FLUSH) (IN EFI_BLOCK_IO_PROTOCOL *This);

Parameters

Parameter Description
This Indicates a pointer to the calling context.

Description
The FlushBlocks() function flushes all modified data to the physical block device.

All data written to the device prior to the flush must be physically written before returning EFI_SUCCESS from this function. This would include any cached data the driver may have cached, and cached data the device may have cached. A flush may cause a read request following the flush to force a device access.

Status Codes Returned

Status Code Description
EFI_SUCCESS All outstanding data were written correctly to the device.
EFI_DEVICE_ERROR The device reported an error while attempting to write data.
EFI_NO_MEDIA There is no media in the device.

Copyright (C) 2008-2009 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools