/** @file | |
Definitions of functions for Driver Binding Protocol and Block I/O Protocol, | |
and other internal definitions. | |
Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> | |
SPDX-License-Identifier: BSD-2-Clause-Patent | |
**/ | |
#ifndef _EFI_USBMASS_IMPL_H_ | |
#define _EFI_USBMASS_IMPL_H_ | |
#define USB_MASS_SIGNATURE SIGNATURE_32 ('U', 's', 'b', 'M') | |
#define USB_MASS_DEVICE_FROM_BLOCK_IO(a) \ | |
CR (a, USB_MASS_DEVICE, BlockIo, USB_MASS_SIGNATURE) | |
#define USB_MASS_DEVICE_FROM_DISK_INFO(a) \ | |
CR (a, USB_MASS_DEVICE, DiskInfo, USB_MASS_SIGNATURE) | |
extern EFI_COMPONENT_NAME_PROTOCOL gUsbMassStorageComponentName; | |
extern EFI_COMPONENT_NAME2_PROTOCOL gUsbMassStorageComponentName2; | |
// | |
// Functions for Driver Binding Protocol | |
// | |
/** | |
Check whether the controller is a supported USB mass storage. | |
@param This The USB mass storage driver binding protocol. | |
@param Controller The controller handle to check. | |
@param RemainingDevicePath The remaining device path. | |
@retval EFI_SUCCESS The driver supports this controller. | |
@retval other This device isn't supported. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
USBMassDriverBindingSupported ( | |
IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
IN EFI_HANDLE Controller, | |
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath | |
); | |
/** | |
Starts the USB mass storage device with this driver. | |
This function consumes USB I/O Protocol, initializes USB mass storage device, | |
installs Block I/O Protocol, and submits Asynchronous Interrupt | |
Transfer to manage the USB mass storage device. | |
@param This The USB mass storage driver binding protocol. | |
@param Controller The USB mass storage device to start on | |
@param RemainingDevicePath The remaining device path. | |
@retval EFI_SUCCESS This driver supports this device. | |
@retval EFI_UNSUPPORTED This driver does not support this device. | |
@retval EFI_DEVICE_ERROR This driver cannot be started due to device Error. | |
@retval EFI_OUT_OF_RESOURCES Can't allocate memory resources. | |
@retval EFI_ALREADY_STARTED This driver has been started. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
USBMassDriverBindingStart ( | |
IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
IN EFI_HANDLE Controller, | |
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath | |
); | |
/** | |
Stop controlling the device. | |
@param This The USB mass storage driver binding | |
@param Controller The device controller controlled by the driver. | |
@param NumberOfChildren The number of children of this device | |
@param ChildHandleBuffer The buffer of children handle. | |
@retval EFI_SUCCESS The driver stopped from controlling the device. | |
@retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. | |
@retval EFI_UNSUPPORTED Block I/O Protocol is not installed on Controller. | |
@retval Others Failed to stop the driver | |
**/ | |
EFI_STATUS | |
EFIAPI | |
USBMassDriverBindingStop ( | |
IN EFI_DRIVER_BINDING_PROTOCOL *This, | |
IN EFI_HANDLE Controller, | |
IN UINTN NumberOfChildren, | |
IN EFI_HANDLE *ChildHandleBuffer | |
); | |
// | |
// Functions for Block I/O Protocol | |
// | |
/** | |
Reset the block device. | |
This function implements EFI_BLOCK_IO_PROTOCOL.Reset(). | |
It resets the block device hardware. | |
ExtendedVerification is ignored in this implementation. | |
@param This Indicates a pointer to the calling context. | |
@param ExtendedVerification Indicates that the driver may perform a more exhaustive | |
verification operation of the device during reset. | |
@retval EFI_SUCCESS The block device was reset. | |
@retval EFI_DEVICE_ERROR The block device is not functioning correctly and could not be reset. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassReset ( | |
IN EFI_BLOCK_IO_PROTOCOL *This, | |
IN BOOLEAN ExtendedVerification | |
); | |
/** | |
Reads the requested number of blocks from the device. | |
This function implements EFI_BLOCK_IO_PROTOCOL.ReadBlocks(). | |
It reads the requested number of blocks from the device. | |
All the blocks are read, or an error is returned. | |
@param This Indicates a pointer to the calling context. | |
@param MediaId The media ID that the read request is for. | |
@param Lba The starting logical block address to read from on the device. | |
@param BufferSize The size of the Buffer in bytes. | |
This must be a multiple of the intrinsic block size of the device. | |
@param Buffer A pointer to the destination buffer for the data. The caller is | |
responsible for either having implicit or explicit ownership of the buffer. | |
@retval EFI_SUCCESS The data was read correctly from the device. | |
@retval EFI_DEVICE_ERROR The device reported an error while attempting to perform the read operation. | |
@retval EFI_NO_MEDIA There is no media in the device. | |
@retval EFI_MEDIA_CHANGED The MediaId is not for the current media. | |
@retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device. | |
@retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, | |
or the buffer is not on proper alignment. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassReadBlocks ( | |
IN EFI_BLOCK_IO_PROTOCOL *This, | |
IN UINT32 MediaId, | |
IN EFI_LBA Lba, | |
IN UINTN BufferSize, | |
OUT VOID *Buffer | |
); | |
/** | |
Writes a specified number of blocks to the device. | |
This function implements EFI_BLOCK_IO_PROTOCOL.WriteBlocks(). | |
It writes a specified number of blocks to the device. | |
All blocks are written, or an error is returned. | |
@param This Indicates a pointer to the calling context. | |
@param MediaId The media ID that the write request is for. | |
@param Lba The starting logical block address to be written. | |
@param BufferSize The size of the Buffer in bytes. | |
This must be a multiple of the intrinsic block size of the device. | |
@param Buffer Pointer to the source buffer for the data. | |
@retval EFI_SUCCESS The data were written correctly to the device. | |
@retval EFI_WRITE_PROTECTED The device cannot be written to. | |
@retval EFI_NO_MEDIA There is no media in the device. | |
@retval EFI_MEDIA_CHANGED The MediaId is not for the current media. | |
@retval EFI_DEVICE_ERROR The device reported an error while attempting to perform the write operation. | |
@retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic | |
block size of the device. | |
@retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, | |
or the buffer is not on proper alignment. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassWriteBlocks ( | |
IN EFI_BLOCK_IO_PROTOCOL *This, | |
IN UINT32 MediaId, | |
IN EFI_LBA Lba, | |
IN UINTN BufferSize, | |
IN VOID *Buffer | |
); | |
/** | |
Flushes all modified data to a physical block device. | |
This function implements EFI_BLOCK_IO_PROTOCOL.FlushBlocks(). | |
USB mass storage device doesn't support write cache, | |
so return EFI_SUCCESS directly. | |
@param This Indicates a pointer to the calling context. | |
@retval EFI_SUCCESS All outstanding data were written correctly to the device. | |
@retval EFI_DEVICE_ERROR The device reported an error while attempting to write data. | |
@retval EFI_NO_MEDIA There is no media in the device. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassFlushBlocks ( | |
IN EFI_BLOCK_IO_PROTOCOL *This | |
); | |
// | |
// EFI Component Name Functions | |
// | |
/** | |
Retrieves a Unicode string that is the user readable name of the driver. | |
This function retrieves the user readable name of a driver in the form of a | |
Unicode string. If the driver specified by This has a user readable name in | |
the language specified by Language, then a pointer to the driver name is | |
returned in DriverName, and EFI_SUCCESS is returned. If the driver specified | |
by This does not support the language specified by Language, | |
then EFI_UNSUPPORTED is returned. | |
@param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or | |
EFI_COMPONENT_NAME_PROTOCOL instance. | |
@param Language A pointer to a Null-terminated ASCII string | |
array indicating the language. This is the | |
language of the driver name that the caller is | |
requesting, and it must match one of the | |
languages specified in SupportedLanguages. The | |
number of languages supported by a driver is up | |
to the driver writer. Language is specified | |
in RFC 4646 or ISO 639-2 language code format. | |
@param DriverName A pointer to the Unicode string to return. | |
This Unicode string is the name of the | |
driver specified by This in the language | |
specified by Language. | |
@retval EFI_SUCCESS The Unicode string for the Driver specified by | |
This and the language specified by Language was | |
returned in DriverName. | |
@retval EFI_INVALID_PARAMETER Language is NULL. | |
@retval EFI_INVALID_PARAMETER DriverName is NULL. | |
@retval EFI_UNSUPPORTED The driver specified by This does not support | |
the language specified by Language. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassStorageGetDriverName ( | |
IN EFI_COMPONENT_NAME_PROTOCOL *This, | |
IN CHAR8 *Language, | |
OUT CHAR16 **DriverName | |
); | |
/** | |
Retrieves a Unicode string that is the user readable name of the controller | |
that is being managed by a driver. | |
This function retrieves the user readable name of the controller specified by | |
ControllerHandle and ChildHandle in the form of a Unicode string. If the | |
driver specified by This has a user readable name in the language specified by | |
Language, then a pointer to the controller name is returned in ControllerName, | |
and EFI_SUCCESS is returned. If the driver specified by This is not currently | |
managing the controller specified by ControllerHandle and ChildHandle, | |
then EFI_UNSUPPORTED is returned. If the driver specified by This does not | |
support the language specified by Language, then EFI_UNSUPPORTED is returned. | |
@param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or | |
EFI_COMPONENT_NAME_PROTOCOL instance. | |
@param ControllerHandle The handle of a controller that the driver | |
specified by This is managing. This handle | |
specifies the controller whose name is to be | |
returned. | |
@param ChildHandle The handle of the child controller to retrieve | |
the name of. This is an optional parameter that | |
may be NULL. It will be NULL for device | |
drivers. It will also be NULL for a bus drivers | |
that wish to retrieve the name of the bus | |
controller. It will not be NULL for a bus | |
driver that wishes to retrieve the name of a | |
child controller. | |
@param Language A pointer to a Null-terminated ASCII string | |
array indicating the language. This is the | |
language of the driver name that the caller is | |
requesting, and it must match one of the | |
languages specified in SupportedLanguages. The | |
number of languages supported by a driver is up | |
to the driver writer. Language is specified in | |
RFC 4646 or ISO 639-2 language code format. | |
@param ControllerName A pointer to the Unicode string to return. | |
This Unicode string is the name of the | |
controller specified by ControllerHandle and | |
ChildHandle in the language specified by | |
Language from the point of view of the driver | |
specified by This. | |
@retval EFI_SUCCESS The Unicode string for the user readable name in | |
the language specified by Language for the | |
driver specified by This was returned in | |
DriverName. | |
@retval EFI_INVALID_PARAMETER ControllerHandle is NULL. | |
@retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid | |
EFI_HANDLE. | |
@retval EFI_INVALID_PARAMETER Language is NULL. | |
@retval EFI_INVALID_PARAMETER ControllerName is NULL. | |
@retval EFI_UNSUPPORTED The driver specified by This is not currently | |
managing the controller specified by | |
ControllerHandle and ChildHandle. | |
@retval EFI_UNSUPPORTED The driver specified by This does not support | |
the language specified by Language. | |
**/ | |
EFI_STATUS | |
EFIAPI | |
UsbMassStorageGetControllerName ( | |
IN EFI_COMPONENT_NAME_PROTOCOL *This, | |
IN EFI_HANDLE ControllerHandle, | |
IN EFI_HANDLE ChildHandle OPTIONAL, | |
IN CHAR8 *Language, | |
OUT CHAR16 **ControllerName | |
); | |
#endif |