/** @file
Provides some data structure definitions used by the XHCI host controller driver.
Copyright (c) 2011 - 2012, 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.
**/
#ifndef _EFI_XHCI_H_
#define _EFI_XHCI_H_
#include <Uefi.h>
#include <Protocol/Usb2HostController.h>
#include <Guid/EventGroup.h>
#include <Library/BaseMemoryLib.h>
#include <Library/UefiDriverEntryPoint.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/DebugLib.h>
#include <IndustryStandard/Pci.h>
#include "XhciReg.h"
#include "XhciSched.h"
#include "ComponentName.h"
//
// Convert millisecond to microsecond.
//
//
// XHC generic timeout experience values.
// The unit is microsecond, setting it as 10ms.
//
//
// XHC reset timeout experience values.
// The unit is microsecond, setting it as 1s.
//
//
// XHC delay experience value for polling operation.
// The unit is microsecond, set it as 1ms.
//
//
// XHC async transfer timer interval, set by experience.
// The unit is 100us, takes 50ms as interval.
//
//
// XHC raises TPL to TPL_NOTIFY to serialize all its operations
// to protect shared data structures.
//
#define CMD_INTER 0
//
// Iterate through the doule linked list. This is delete-safe.
// Don't touch NextEntry
//
//
// The RequestType in EFI_USB_DEVICE_REQUEST is composed of
// three fields: One bit direction, 2 bit type, and 5 bit
// target.
//
//
// Xhci Data and Ctrl Structures
//
#pragma pack(1)
typedef struct {
} USB_CLASSC;
typedef struct {
#pragma pack()
struct _USB_DEV_CONTEXT {
//
// Whether this entry in UsbDevContext array is used or not.
//
//
// The slot id assigned to the new device through XHCI's Enable_Slot cmd.
//
//
// The route string presented an attached usb device.
//
//
// The route string of parent device if it exists. Otherwise it's zero.
//
//
// The actual device address assigned by XHCI through Address_Device command.
//
//
// The requested device address from UsbBus driver through Set_Address standard usb request.
// As XHCI spec replaces this request with Address_Device command, we have to record the
// requested device address and establish a mapping relationship with the actual device address.
// Then UsbBus driver just need to be aware of the requested device address to access usb device
// through EFI_USB2_HC_PROTOCOL. Xhci driver would be responsible for translating it to actual
// device address and access the actual device.
//
//
// The pointer to the input device context.
//
//
// The pointer to the output device context.
//
//
// The transfer queue for every endpoint.
//
//
// The device descriptor which is stored to support XHCI's Evaluate_Context cmd.
//
//
// As a usb device may include multiple configuration descriptors, we dynamically allocate an array
// to store them.
// Note that every configuration descriptor stored here includes those lower level descriptors,
// such as Interface descriptor, Endpoint descriptor, and so on.
// These information is used to support XHCI's Config_Endpoint cmd.
//
};
struct _USB_XHCI_INSTANCE {
//
// ExitBootServicesEvent is used to set OS semaphore and
// stop the XHC DMA operation after exit boot service.
//
//
// Cmd Transfer Ring
//
//
// EventRing
//
//
// Misc
//
//
// Store device contexts managed by XHCI instance
// The array supports up to 255 devices, entry 0 is reserved and should not be used.
//
};
/**
Test to see if this driver supports ControllerHandle. Any
ControllerHandle that has Usb2HcProtocol installed will
be supported.
@param This Protocol instance pointer.
@param Controller Handle of device to test.
@param RemainingDevicePath Not used.
@return EFI_SUCCESS This driver supports this device.
@return EFI_UNSUPPORTED This driver does not support this device.
**/
);
/**
Starting the Usb XHCI Driver.
@param This Protocol instance pointer.
@param Controller Handle of device to test.
@param RemainingDevicePath Not used.
@return EFI_SUCCESS supports this device.
@return EFI_UNSUPPORTED do not support this device.
@return EFI_DEVICE_ERROR cannot be started due to device Error.
@return EFI_OUT_OF_RESOURCES cannot allocate resources.
**/
);
/**
Stop this driver on ControllerHandle. Support stoping any child handles
created by this driver.
@param This Protocol instance pointer.
@param Controller Handle of device to stop driver on.
@param NumberOfChildren Number of Children in the ChildHandleBuffer.
@param ChildHandleBuffer List of handles for the children we need to stop.
@return EFI_SUCCESS Success.
@return EFI_DEVICE_ERROR Fail.
**/
);
/**
Retrieves the capability of root hub ports.
@param This The EFI_USB2_HC_PROTOCOL instance.
@param MaxSpeed Max speed supported by the controller.
@param PortNumber Number of the root hub ports.
@param Is64BitCapable Whether the controller supports 64-bit memory
addressing.
@retval EFI_SUCCESS Host controller capability were retrieved successfully.
@retval EFI_INVALID_PARAMETER Either of the three capability pointer is NULL.
**/
);
/**
Provides software reset for the USB host controller.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param Attributes A bit mask of the reset operation to perform.
@retval EFI_SUCCESS The reset operation succeeded.
@retval EFI_INVALID_PARAMETER Attributes is not valid.
@retval EFI_UNSUPPOURTED The type of reset specified by Attributes is
not currently supported by the host controller.
@retval EFI_DEVICE_ERROR Host controller isn't halted to reset.
**/
XhcReset (
);
/**
Retrieve the current state of the USB host controller.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param State Variable to return the current host controller
state.
@retval EFI_SUCCESS Host controller state was returned in State.
@retval EFI_INVALID_PARAMETER State is NULL.
@retval EFI_DEVICE_ERROR An error was encountered while attempting to
retrieve the host controller's current state.
**/
);
/**
Sets the USB host controller to a specific state.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param State The state of the host controller that will be set.
@retval EFI_SUCCESS The USB host controller was successfully placed
in the state specified by State.
@retval EFI_INVALID_PARAMETER State is invalid.
@retval EFI_DEVICE_ERROR Failed to set the state due to device error.
**/
);
/**
Retrieves the current status of a USB root hub port.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param PortNumber The root hub port to retrieve the state from.
This value is zero-based.
@param PortStatus Variable to receive the port state.
@retval EFI_SUCCESS The status of the USB root hub port specified.
by PortNumber was returned in PortStatus.
@retval EFI_INVALID_PARAMETER PortNumber is invalid.
@retval EFI_DEVICE_ERROR Can't read register.
**/
);
/**
Sets a feature for the specified root hub port.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param PortNumber Root hub port to set.
@param PortFeature Feature to set.
@retval EFI_SUCCESS The feature specified by PortFeature was set.
@retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
@retval EFI_DEVICE_ERROR Can't read register.
**/
);
/**
Clears a feature for the specified root hub port.
@param This A pointer to the EFI_USB2_HC_PROTOCOL instance.
@param PortNumber Specifies the root hub port whose feature is
requested to be cleared.
@param PortFeature Indicates the feature selector associated with the
feature clear request.
@retval EFI_SUCCESS The feature specified by PortFeature was cleared
for the USB root hub port specified by PortNumber.
@retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
@retval EFI_DEVICE_ERROR Can't read register.
**/
);
/**
Submits control transfer to a target USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress The target device address.
@param DeviceSpeed Target device speed.
@param MaximumPacketLength Maximum packet size the default control transfer
endpoint is capable of sending or receiving.
@param Request USB device request to send.
@param TransferDirection Specifies the data direction for the data stage
@param Data Data buffer to be transmitted or received from USB
device.
@param DataLength The size (in bytes) of the data buffer.
@param Timeout Indicates the maximum timeout, in millisecond.
@param Translator Transaction translator to be used by this device.
@param TransferResult Return the result of this control transfer.
@retval EFI_SUCCESS Transfer was completed successfully.
@retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resources.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval EFI_TIMEOUT Transfer failed due to timeout.
@retval EFI_DEVICE_ERROR Transfer failed due to host controller or device error.
**/
);
/**
Submits bulk transfer to a bulk endpoint of a USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress Target device address.
@param EndPointAddress Endpoint number and its direction in bit 7.
@param DeviceSpeed Device speed, Low speed device doesn't support bulk
transfer.
@param MaximumPacketLength Maximum packet size the endpoint is capable of
sending or receiving.
@param DataBuffersNumber Number of data buffers prepared for the transfer.
@param Data Array of pointers to the buffers of data to transmit
from or receive into.
@param DataLength The lenght of the data buffer.
@param DataToggle On input, the initial data toggle for the transfer;
On output, it is updated to to next data toggle to
use of the subsequent bulk transfer.
@param Timeout Indicates the maximum time, in millisecond, which
the transfer is allowed to complete.
@param Translator A pointr to the transaction translator data.
@param TransferResult A pointer to the detailed result information of the
bulk transfer.
@retval EFI_SUCCESS The transfer was completed successfully.
@retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval EFI_TIMEOUT The transfer failed due to timeout.
@retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
**/
);
/**
Submits an asynchronous interrupt transfer to an
interrupt endpoint of a USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress Target device address.
@param EndPointAddress Endpoint number and its direction encoded in bit 7
@param DeviceSpeed Indicates device speed.
@param MaximumPacketLength Maximum packet size the target endpoint is capable
@param IsNewTransfer If TRUE, to submit an new asynchronous interrupt
transfer If FALSE, to remove the specified
asynchronous interrupt.
@param DataToggle On input, the initial data toggle to use; on output,
it is updated to indicate the next data toggle.
@param PollingInterval The he interval, in milliseconds, that the transfer
is polled.
@param DataLength The length of data to receive at the rate specified
by PollingInterval.
@param Translator Transaction translator to use.
@param CallBackFunction Function to call at the rate specified by
PollingInterval.
@param Context Context to CallBackFunction.
@retval EFI_SUCCESS The request has been successfully submitted or canceled.
@retval EFI_INVALID_PARAMETER Some parameters are invalid.
@retval EFI_OUT_OF_RESOURCES The request failed due to a lack of resources.
@retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
**/
);
/**
Submits synchronous interrupt transfer to an interrupt endpoint
of a USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress Target device address.
@param EndPointAddress Endpoint number and its direction encoded in bit 7
@param DeviceSpeed Indicates device speed.
@param MaximumPacketLength Maximum packet size the target endpoint is capable
of sending or receiving.
@param Data Buffer of data that will be transmitted to USB
device or received from USB device.
@param DataLength On input, the size, in bytes, of the data buffer; On
output, the number of bytes transferred.
@param DataToggle On input, the initial data toggle to use; on output,
it is updated to indicate the next data toggle.
@param Timeout Maximum time, in second, to complete.
@param Translator Transaction translator to use.
@param TransferResult Variable to receive the transfer result.
@return EFI_SUCCESS The transfer was completed successfully.
@return EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
@return EFI_INVALID_PARAMETER Some parameters are invalid.
@return EFI_TIMEOUT The transfer failed due to timeout.
@return EFI_DEVICE_ERROR The failed due to host controller or device error
**/
);
/**
Submits isochronous transfer to a target USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress Target device address.
@param EndPointAddress End point address with its direction.
@param DeviceSpeed Device speed, Low speed device doesn't support this
type.
@param MaximumPacketLength Maximum packet size that the endpoint is capable of
sending or receiving.
@param DataBuffersNumber Number of data buffers prepared for the transfer.
@param Data Array of pointers to the buffers of data that will
be transmitted to USB device or received from USB
device.
@param DataLength The size, in bytes, of the data buffer.
@param Translator Transaction translator to use.
@param TransferResult Variable to receive the transfer result.
@return EFI_UNSUPPORTED Isochronous transfer is unsupported.
**/
);
/**
Submits Async isochronous transfer to a target USB device.
@param This This EFI_USB2_HC_PROTOCOL instance.
@param DeviceAddress Target device address.
@param EndPointAddress End point address with its direction.
@param DeviceSpeed Device speed, Low speed device doesn't support this
type.
@param MaximumPacketLength Maximum packet size that the endpoint is capable of
sending or receiving.
@param DataBuffersNumber Number of data buffers prepared for the transfer.
@param Data Array of pointers to the buffers of data that will
be transmitted to USB device or received from USB
device.
@param DataLength The size, in bytes, of the data buffer.
@param Translator Transaction translator to use.
@param IsochronousCallBack Function to be called when the transfer complete.
@param Context Context passed to the call back function as
parameter.
@return EFI_UNSUPPORTED Isochronous transfer isn't supported.
**/
);
#endif