UsbBus.c revision 4fd606d1f5abe38e1f42c38de1d2e895166bd0f4
/** @file
Usb Bus Driver Binding and Bus IO Protocol.
Copyright (c) 2004 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#include "UsbBus.h"
};
0xa,
NULL,
};
/**
USB_IO function to execute a control transfer. This
function will execute the USB transfer. If transfer
successes, it will sync the internal state of USB bus
with device state.
@param This The USB_IO instance
@param Request The control transfer request
@param Direction Direction for data stage
@param Timeout The time to wait before timeout
@param Data The buffer holding the data
@param DataLength Then length of the data
@param UsbStatus USB result
@retval EFI_INVALID_PARAMETER The parameters are invalid
@retval EFI_SUCCESS The control transfer succeeded.
@retval Others Failed to execute the transfer
**/
)
{
return EFI_INVALID_PARAMETER;
}
Data,
&Dev->Translator,
);
//
// Clear the TRANSLATOR TT buffer, not parent's buffer
//
0,
);
}
goto ON_EXIT;
}
//
// Some control transfer will change the device's internal
// status, such as Set_Configuration and Set_Interface.
// We must synchronize the bus driver's status with that in
// device. We ignore the Set_Descriptor request because it's
// hardly used by any device, especially in pre-boot environment
//
//
// Reset the endpoint toggle when endpoint stall is cleared
//
USB_TARGET_ENDPOINT)) &&
}
}
//
// Select a new configuration. This is a dangerous action. Upper driver
// should stop use its current UsbIo after calling this driver. The old
// UsbIo will be uninstalled and new UsbIo be installed. We can't use
// ReinstallProtocol since interfaces in different configuration may be
// completely irrelevant.
//
USB_TARGET_DEVICE))) {
//
// Don't re-create the USB interfaces if configuration isn't changed.
//
goto ON_EXIT;
}
}
}
//
// Exit now, Old USB_IO is invalid now
//
goto ON_EXIT;
}
//
// A new alternative setting is selected for the interface.
// No need to reinstall UsbIo in this case because only
// underlying communication endpoints are changed. Functionality
// should remains the same.
//
USB_TARGET_INTERFACE)) &&
}
}
return Status;
}
/**
Execute a bulk transfer to the device endpoint.
@param This The USB IO instance.
@param Endpoint The device endpoint.
@param Data The data to transfer.
@param DataLength The length of the data to transfer.
@param Timeout Time to wait before timeout.
@param UsbStatus The result of USB transfer.
@retval EFI_SUCCESS The bulk transfer is OK.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval Others Failed to execute transfer, reason returned in
UsbStatus.
**/
)
{
return EFI_INVALID_PARAMETER;
}
goto ON_EXIT;
}
BufNum = 1;
&Data,
&Toggle,
&Dev->Translator,
);
//
// Clear the TRANSLATOR TT buffer, not parent's buffer
//
0,
);
}
}
return Status;
}
/**
Execute a synchronous interrupt transfer.
@param This The USB IO instance.
@param Endpoint The device endpoint.
@param Data The data to transfer.
@param DataLength The length of the data to transfer.
@param Timeout Time to wait before timeout.
@param UsbStatus The result of USB transfer.
@retval EFI_SUCCESS The synchronous interrupt transfer is OK.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval Others Failed to execute transfer, reason returned in
UsbStatus.
**/
)
{
return EFI_INVALID_PARAMETER;
}
goto ON_EXIT;
}
Data,
&Toggle,
&Dev->Translator,
);
return Status;
}
/**
Queue a new asynchronous interrupt transfer, or remove the old
request if (IsNewTransfer == FALSE).
@param This The USB_IO instance.
@param Endpoint The device endpoint.
@param IsNewTransfer Whether this is a new request, if it's old, remove
the request.
@param PollInterval The interval to poll the transfer result, (in ms).
@param DataLength The length of perodic data transfer.
@param Callback The function to call periodicaly when transfer is
ready.
@param Context The context to the callback.
@retval EFI_SUCCESS New transfer is queued or old request is removed.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval Others Failed to queue the new request or remove the old
request.
**/
)
{
return EFI_INVALID_PARAMETER;
}
goto ON_EXIT;
}
&Toggle,
&Dev->Translator,
);
return Status;
}
/**
Execute a synchronous isochronous transfer.
@param This The USB IO instance.
@param DeviceEndpoint The device endpoint.
@param Data The data to transfer.
@param DataLength The length of the data to transfer.
@param UsbStatus The result of USB transfer.
@retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
**/
)
{
return EFI_UNSUPPORTED;
}
/**
Queue an asynchronous isochronous transfer.
@param This The USB_IO instance.
@param DeviceEndpoint The device endpoint.
@param Data The data to transfer.
@param DataLength The length of perodic data transfer.
@param IsochronousCallBack The function to call periodicaly when transfer is
ready.
@param Context The context to the callback.
@retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
**/
)
{
return EFI_UNSUPPORTED;
}
/**
Retrieve the device descriptor of the device.
@param This The USB IO instance.
@param Descriptor The variable to receive the device descriptor.
@retval EFI_SUCCESS The device descriptor is returned.
@retval EFI_INVALID_PARAMETER The parameter is invalid.
**/
)
{
if (Descriptor == NULL) {
return EFI_INVALID_PARAMETER;
}
return EFI_SUCCESS;
}
/**
Return the configuration descriptor of the current active configuration.
@param This The USB IO instance.
@param Descriptor The USB configuration descriptor.
@retval EFI_SUCCESS The active configuration descriptor is returned.
@retval EFI_INVALID_PARAMETER Some parameter is invalid.
@retval EFI_NOT_FOUND Currently no active configuration is selected.
**/
)
{
if (Descriptor == NULL) {
return EFI_INVALID_PARAMETER;
}
goto ON_EXIT;
}
return Status;
}
/**
Retrieve the active interface setting descriptor for this USB IO instance.
@param This The USB IO instance.
@param Descriptor The variable to receive active interface setting.
@retval EFI_SUCCESS The active interface setting is returned.
@retval EFI_INVALID_PARAMETER Some parameter is invalid.
**/
)
{
if (Descriptor == NULL) {
return EFI_INVALID_PARAMETER;
}
return EFI_SUCCESS;
}
/**
Retrieve the endpoint descriptor from this interface setting.
@param This The USB IO instance.
@param Index The index (start from zero) of the endpoint to
retrieve.
@param Descriptor The variable to receive the descriptor.
@retval EFI_SUCCESS The endpoint descriptor is returned.
@retval EFI_INVALID_PARAMETER Some parameter is invalid.
**/
)
{
return EFI_INVALID_PARAMETER;
}
return EFI_NOT_FOUND;
}
CopyMem (
sizeof (EFI_USB_ENDPOINT_DESCRIPTOR)
);
return EFI_SUCCESS;
}
/**
Retrieve the supported language ID table from the device.
@param This The USB IO instance.
@param LangIDTable The table to return the language IDs.
@param TableSize The size, in bytes, of the table LangIDTable.
@retval EFI_SUCCESS The language ID is return.
**/
)
{
return EFI_SUCCESS;
}
/**
Retrieve an indexed string in the language of LangID.
@param This The USB IO instance.
@param LangID The language ID of the string to retrieve.
@param StringIndex The index of the string.
@param String The variable to receive the string.
@retval EFI_SUCCESS The string is returned.
@retval EFI_NOT_FOUND No such string existed.
**/
)
{
if ((StringIndex == 0) || (LangID == 0)) {
return EFI_NOT_FOUND;
}
//
// Check whether language ID is supported
//
break;
}
}
goto ON_EXIT;
}
//
// Retrieve the string descriptor then allocate a buffer
// to hold the string itself.
//
goto ON_EXIT;
}
goto FREE_STR;
}
goto FREE_STR;
}
return Status;
}
/**
Reset the device, then if that succeeds, reconfigure the
device with its address and current active configuration.
@param This The USB IO instance.
@retval EFI_SUCCESS The device is reset and configured.
@retval Others Failed to reset the device.
**/
)
{
goto ON_EXIT;
}
goto ON_EXIT;
}
//
// Reset the device to its current address. The device now has an address
// of ZERO after port reset, so need to set Dev->Address to the device again for
// host to communicate with it.
//
//
// It may fail due to device disconnection or other reasons.
//
goto ON_EXIT;
}
//
// Reset the current active configure, after this device
// is in CONFIGURED state.
//
}
}
return Status;
}
/**
Install Usb Bus Protocol on host controller, and start the Usb bus.
@param This The USB bus driver binding instance.
@param Controller The controller to check.
@param RemainingDevicePath The remaining device patch.
@retval EFI_SUCCESS The controller is controlled by the usb bus.
@retval EFI_ALREADY_STARTED The controller is already controlled by the usb bus.
@retval EFI_OUT_OF_RESOURCES Failed to allocate resources.
**/
)
{
return EFI_OUT_OF_RESOURCES;
}
);
return Status;
}
//
// This is for backward compatibility with EFI 1.x. In UEFI
// 2.x, USB_HC2 replaces USB_HC. We will open both USB_HC2
// and USB_HC because EHCI driver will install both protocols
// (for the same reason). If we don't consume both of them,
// the unconsumed one may be opened by others.
//
);
);
goto CLOSE_HC;
}
//
// The EFI_USB2_HC_PROTOCOL is produced for XHCI support.
// Then its max supported devices are 256. Otherwise it's 128.
//
}
}
//
// Install an EFI_USB_BUS_PROTOCOL to host controller to identify it.
//
);
goto CLOSE_HC;
}
//
// Initial the wanted child device path list, and add first RemainingDevicePath
//
//
// Create a fake usb device for root hub
//
goto UNINSTALL_USBBUS;
}
goto FREE_ROOTHUB;
}
goto FREE_ROOTHUB;
}
return EFI_SUCCESS;
}
}
gBS->CloseProtocol (
);
}
gBS->CloseProtocol (
);
}
gBS->CloseProtocol (
);
return Status;
}
/**
The USB bus driver entry pointer.
@param ImageHandle The driver image handle.
@param SystemTable The system table.
@return EFI_SUCCESS The component name protocol is installed.
@return Others Failed to init the usb driver.
**/
)
{
);
}
/**
Check whether USB bus driver support this device.
@param This The USB bus driver binding protocol.
@param Controller The controller handle to check.
@param RemainingDevicePath The remaining device path.
@retval EFI_SUCCESS The bus supports this controller.
@retval EFI_UNSUPPORTED This device isn't supported.
**/
)
{
//
// Check whether device path is valid
//
if (RemainingDevicePath != NULL) {
//
// Check if RemainingDevicePath is the End of Device Path Node,
// if yes, go on checking other conditions
//
if (!IsDevicePathEnd (RemainingDevicePath)) {
//
// If RemainingDevicePath isn't the End of Device Path Node,
// check its validation
//
)) {
return EFI_UNSUPPORTED;
}
}
}
//
// Check whether USB_HC2 protocol is installed
//
);
if (Status == EFI_ALREADY_STARTED) {
return EFI_SUCCESS;
}
//
// If failed to open USB_HC2, fall back to USB_HC
//
);
if (Status == EFI_ALREADY_STARTED) {
return EFI_SUCCESS;
}
return Status;
}
//
// Close the USB_HC used to perform the supported test
//
gBS->CloseProtocol (
);
} else {
//
// Close the USB_HC2 used to perform the supported test
//
gBS->CloseProtocol (
);
}
//
// Open the EFI Device Path protocol needed to perform the supported test
//
(VOID **) &ParentDevicePath,
);
if (Status == EFI_ALREADY_STARTED) {
return EFI_SUCCESS;
}
//
// Close protocol, don't use device path protocol in the Support() function
//
gBS->CloseProtocol (
);
return EFI_SUCCESS;
}
return Status;
}
/**
Start to process the controller.
@param This The USB bus driver binding instance.
@param Controller The controller to check.
@param RemainingDevicePath The remaining device patch.
@retval EFI_SUCCESS The controller is controlled by the usb bus.
@retval EFI_ALREADY_STARTED The controller is already controlled by the usb
bus.
@retval EFI_OUT_OF_RESOURCES Failed to allocate resources.
**/
)
{
//
// Locate the USB bus protocol, if it is found, USB bus
// is already started on this controller.
//
);
//
// If first start, build the bus execute environment and install bus protocol
//
return Status;
}
//
// Try get the Usb Bus protocol interface again
//
);
} else {
//
// USB Bus driver need to control the recursive connect policy of the bus, only those wanted
// usb child device will be recursively connected.
// The RemainingDevicePath indicate the child usb device which user want to fully recursively connecte this time.
// All wanted usb child devices will be remembered by the usb bus driver itself.
// If RemainingDevicePath == NULL, all the usb child devices in the usb bus are wanted devices.
//
// Save the passed in RemainingDevicePath this time
//
if (RemainingDevicePath != NULL) {
if (IsDevicePathEnd (RemainingDevicePath)) {
//
// If RemainingDevicePath is the End of Device Path Node,
// skip enumerate any device and return EFI_SUCESSS
//
return EFI_SUCCESS;
}
}
//
// Ensure all wanted child usb devices are fully recursively connected
//
}
return EFI_SUCCESS;
}
/**
Stop handle the controller by this USB bus driver.
@param This The USB bus driver binding protocol.
@param Controller The controller to release.
@param NumberOfChildren The child of USB bus that opened controller
BY_CHILD.
@param ChildHandleBuffer The array of child handle.
@retval EFI_SUCCESS The controller or children are stopped.
@retval EFI_DEVICE_ERROR Failed to stop the driver.
**/
)
{
if (NumberOfChildren > 0) {
//
// BugBug: Raise TPL to callback level instead of USB_BUS_TPL to avoid TPL conflict
//
);
//
// It is possible that the child has already been released:
// 1. For combo device, free one device will release others.
// 2. If a hub is released, all devices on its down facing
// ports are released also.
//
continue;
}
}
return EFI_SUCCESS;
}
//
// Locate USB_BUS for the current host controller
//
);
return Status;
}
//
// Stop the root hub, then free all the devices
//
// BugBug: Raise TPL to callback level instead of USB_BUS_TPL to avoid TPL conflict
//
}
}
//
//
gBS->CloseProtocol (
);
}
gBS->CloseProtocol (
);
}
gBS->CloseProtocol (
);
return Status;
}