diff options
author | eric_tian <eric_tian@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-07-09 10:02:26 +0000 |
---|---|---|
committer | eric_tian <eric_tian@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-07-09 10:02:26 +0000 |
commit | 8616fc4c134d866cb6298faaa5d2dd17242dae9c (patch) | |
tree | 73e2b211bc1023c568cc8eb1ec666110606ba7b0 | |
parent | 78f64f281ae77848694035bd878caffdd19c1f59 (diff) | |
download | edk2-platforms-8616fc4c134d866cb6298faaa5d2dd17242dae9c.tar.xz |
modify coding style to pass ecc tool and provide comments that complied with Doxgen.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5436 6f19259b-4bc3-4df7-8a09-765794883524
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/ComponentName.c | 12 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.c | 267 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h | 74 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.c | 185 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h | 115 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c | 138 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.h | 80 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c | 306 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.h | 54 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.c | 365 | ||||
-rw-r--r-- | MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h | 234 |
11 files changed, 1047 insertions, 783 deletions
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/ComponentName.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/ComponentName.c index ece469f002..529c76c541 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/ComponentName.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/ComponentName.c @@ -1,5 +1,7 @@ /** @file
+ UEFI Component Name(2) protocol implementation for Usb Bus driver.
+
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,13 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-Module Name:
-
- ComponentName.c
-
-Abstract:
-
-
**/
@@ -25,9 +20,6 @@ Abstract: #include <Library/UefiLib.h>
-//
-// EFI Component Name Functions
-//
/**
Retrieves a Unicode string that is the user readable name of the driver.
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.c index f2b7f8bd93..13038fa8af 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.c @@ -1,5 +1,7 @@ /** @file
+ Usb Bus Driver Binding and Bus IO Protocol.
+
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbBus.c
-
- Abstract:
-
- Usb Bus Driver Binding and Bus IO Protocol
-
- Revision History
-
-
**/
#include "UsbBus.h"
@@ -49,7 +40,6 @@ EFI_GUID mUsbBusProtocolGuid = EFI_USB_BUS_PROTOCOL_GUID; @retval Others Failed to execute the transfer
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoControlTransfer (
@@ -191,22 +181,21 @@ ON_EXIT: /**
- Execute a bulk transfer to the device endpoint
+ 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
+ @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 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
+ UsbStatus.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoBulkTransfer (
@@ -286,22 +275,21 @@ ON_EXIT: /**
- Execute a synchronous interrupt transfer
+ 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
+ @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 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
+ UsbStatus.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoSyncInterruptTransfer (
@@ -363,25 +351,24 @@ ON_EXIT: /**
Queue a new asynchronous interrupt transfer, or remove the old
- request if (IsNewTransfer == FALSE)
+ request if (IsNewTransfer == FALSE).
- @param This The USB_IO instance
- @param Endpoint The device endpoint
+ @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
+ 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
+ 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 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
+ request.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoAsyncInterruptTransfer (
@@ -441,18 +428,17 @@ ON_EXIT: /**
- Execute a synchronous isochronous transfer
+ 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
+ @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
+ @retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoIsochronousTransfer (
@@ -468,19 +454,19 @@ UsbIoIsochronousTransfer ( /**
- Queue an asynchronous isochronous transfer
+ Queue an asynchronous isochronous transfer.
- @param This The USB_IO instance
- @param DeviceEndpoint The device endpoint
- @param DataLength The length of perodic data 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
+ ready.
+ @param Context The context to the callback.
- @retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported
+ @retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoAsyncIsochronousTransfer (
@@ -497,16 +483,15 @@ UsbIoAsyncIsochronousTransfer ( /**
- Retrieve the device descriptor of the device
+ Retrieve the device descriptor of the device.
- @param This The USB IO instance
- @param Descriptor The variable to receive the device descriptor
+ @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
+ @retval EFI_SUCCESS The device descriptor is returned.
+ @retval EFI_INVALID_PARAMETER The parameter is invalid.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetDeviceDescriptor (
@@ -535,17 +520,16 @@ UsbIoGetDeviceDescriptor ( /**
- Return the configuration descriptor of the current active configuration
+ Return the configuration descriptor of the current active configuration.
- @param This The USB IO instance
- @param Descriptor The USB configuration descriptor
+ @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_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.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetActiveConfigDescriptor (
@@ -582,16 +566,15 @@ ON_EXIT: /**
- Retrieve the active interface setting descriptor for this USB IO instance
+ 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
+ @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
+ @retval EFI_SUCCESS The active interface setting is returned.
+ @retval EFI_INVALID_PARAMETER Some parameter is invalid.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetInterfaceDescriptor (
@@ -617,18 +600,17 @@ UsbIoGetInterfaceDescriptor ( /**
- Retrieve the endpoint descriptor from this interface setting
+ Retrieve the endpoint descriptor from this interface setting.
- @param This The USB IO instance
+ @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
+ 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
+ @retval EFI_SUCCESS The endpoint descriptor is returned.
+ @retval EFI_INVALID_PARAMETER Some parameter is invalid.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetEndpointDescriptor (
@@ -666,16 +648,15 @@ UsbIoGetEndpointDescriptor ( /**
- Retrieve the supported language ID table from the device
+ 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 number of supported languanges
+ @param This The USB IO instance.
+ @param LangIDTable The table to return the language IDs.
+ @param TableSize The number of supported languanges.
- @retval EFI_SUCCESS The language ID is return
+ @retval EFI_SUCCESS The language ID is return.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetSupportedLanguages (
@@ -702,18 +683,17 @@ UsbIoGetSupportedLanguages ( /**
- Retrieve an indexed string in the language of LangID
+ 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
+ @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
+ @retval EFI_SUCCESS The string is returned.
+ @retval EFI_NOT_FOUND No such string existed.
**/
-STATIC
EFI_STATUS
EFIAPI
UsbIoGetStringDescriptor (
@@ -793,10 +773,10 @@ ON_EXIT: Reset the device, then if that succeeds, reconfigure the
device with its address and current active configuration.
- @param This The USB IO instance
+ @param This The USB IO instance.
- @retval EFI_SUCCESS The device is reset and configured
- @retval Others Failed to reset the device
+ @retval EFI_SUCCESS The device is reset and configured.
+ @retval Others Failed to reset the device.
**/
EFI_STATUS
@@ -873,15 +853,15 @@ ON_EXIT: /**
- Install Usb Bus Protocol on host controller, and start the Usb bus
+ 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
+ @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
+ @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.
**/
EFI_STATUS
@@ -1074,29 +1054,22 @@ EFI_USB_IO_PROTOCOL mUsbIoProtocol = { };
+/**
+ 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.
+
+**/
EFI_STATUS
EFIAPI
UsbBusDriverEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
-
- The USB bus driver entry pointer
-
-Arguments:
-
- ImageHandle - The driver image handle
- SystemTable - The system table
-
-Returns:
-
- EFI_SUCCESS - The component name protocol is installed
- Others - Failed to init the usb driver
-
---*/
{
return EfiLibInstallDriverBindingComponentName2 (
ImageHandle,
@@ -1110,14 +1083,14 @@ Returns: /**
- Check whether USB bus driver support this device
+ Check whether USB bus driver support this device.
- @param This The USB bus driver binding protocol
- @param Controller The controller handle to test againist
- @param RemainingDevicePath The remaining device path
+ @param This The USB bus driver binding protocol.
+ @param Controller The controller handle to test againist.
+ @param RemainingDevicePath The remaining device path.
@retval EFI_SUCCESS The bus supports this controller.
- @retval EFI_UNSUPPORTED This device isn't supported
+ @retval EFI_UNSUPPORTED This device isn't supported.
**/
EFI_STATUS
@@ -1231,16 +1204,16 @@ UsbBusControllerDriverSupported ( /**
- Start to process the controller
+ 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
+ @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_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
+ bus.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resources.
**/
EFI_STATUS
@@ -1312,16 +1285,16 @@ UsbBusControllerDriverStart ( /**
- Stop handle the controller by this USB bus driver
+ Stop handle the controller by this USB bus driver.
- @param This The USB bus driver binding protocol
- @param Controller The controller to release
+ @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
+ 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
+ @retval EFI_SUCCESS The controller or children are stopped.
+ @retval EFI_DEVICE_ERROR Failed to stop the driver.
**/
EFI_STATUS
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h index 21d1b304bf..4bee1836f9 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h @@ -1,4 +1,7 @@ /** @file
+
+ Usb Bus Driver Binding and Bus IO Protocol.
+
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -8,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbBus.h
-
- Abstract:
-
- Usb Bus Driver Binding and Bus IO Protocol
-
- Revision History
-
-
**/
#ifndef _EFI_USB_BUS_H_
@@ -55,7 +47,7 @@ typedef struct _USB_HUB_API USB_HUB_API; #include "UsbHub.h"
#include "UsbEnumer.h"
-enum {
+typedef enum {
USB_MAX_LANG_ID = 16,
USB_MAX_INTERFACE = 16,
USB_MAX_DEVICES = 128,
@@ -125,17 +117,17 @@ enum { //
// Send clear feature request timeout, set by experience
//
- USB_CLEAR_FEATURE_REQUEST_TIMEOUT = 10 * USB_BUS_1_MILLISECOND,
+ USB_CLEAR_FEATURE_REQUEST_TIMEOUT = 10 * USB_BUS_1_MILLISECOND
+}USB_BUS_TIMEOUT_EXPERIENCE_VALUE;
- //
- // Bus raises TPL to TPL_NOTIFY to serialize all its operations
- // to protect shared data structures.
- //
- USB_BUS_TPL = TPL_NOTIFY,
+//
+// Bus raises TPL to TPL_NOTIFY to serialize all its operations
+// to protect shared data structures.
+//
+#define USB_BUS_TPL TPL_NOTIFY
- USB_INTERFACE_SIGNATURE = EFI_SIGNATURE_32 ('U', 'S', 'B', 'I'),
- USB_BUS_SIGNATURE = EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')
-};
+#define USB_INTERFACE_SIGNATURE EFI_SIGNATURE_32 ('U', 'S', 'B', 'I')
+#define USB_BUS_SIGNATURE EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')
#define USB_BIT(a) ((UINTN)(1 << (a)))
#define USB_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
@@ -279,12 +271,32 @@ typedef struct { EFI_DEVICE_PATH_PROTOCOL End;
} USB_CLASS_FORMAT_DEVICE_PATH;
+/**
+ Free a DEVICE_PATH_LIST_ITEM list.
+
+ @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list pointer.
+
+ @retval EFI_INVALID_PARAMETER If parameters are invalid, return this value.
+ @retval EFI_SUCCESS If free operation is successful, return this value.
+
+**/
EFI_STATUS
EFIAPI
UsbBusFreeUsbDPList (
IN LIST_ENTRY *UsbIoDPList
);
+/**
+ Store a wanted usb child device info (its Usb part of device path) which is indicated by
+ RemainingDevicePath in a Usb bus which is indicated by UsbBusId.
+
+ @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
+ @param RemainingDevicePath The remaining device patch.
+
+ @retval EFI_SUCCESS Add operation is successful.
+ @retval EFI_INVALID_PARAMETER The parameters are invalid.
+
+**/
EFI_STATUS
EFIAPI
UsbBusAddWantedUsbIoDP (
@@ -292,6 +304,16 @@ UsbBusAddWantedUsbIoDP ( IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
);
+/**
+ Check whether a usb child device is the wanted device in a bus.
+
+ @param Bus The Usb bus's private data pointer.
+ @param UsbIf The usb child device inferface.
+
+ @retval True If a usb child device is the wanted device in a bus.
+ @retval False If a usb child device is *NOT* the wanted device in a bus.
+
+**/
BOOLEAN
EFIAPI
UsbBusIsWantedUsbIO (
@@ -299,6 +321,16 @@ UsbBusIsWantedUsbIO ( IN USB_INTERFACE *UsbIf
);
+/**
+ Recursively connnect every wanted usb child device to ensure they all fully connected.
+ Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.
+
+ @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
+
+ @retval EFI_SUCCESS Connect is done successfully.
+ @retval EFI_INVALID_PARAMETER The parameter is invalid.
+
+**/
EFI_STATUS
EFIAPI
UsbBusRecursivelyConnectWantedUsbIo (
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.c index c9e1755fde..269dcbf81b 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.c @@ -1,5 +1,7 @@ /** @file
+ Manage Usb Descriptor List
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,31 +11,19 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbDesc.c
-
- Abstract:
-
- Manage Usb Descriptor List
-
- Revision History
-
-
**/
#include "UsbBus.h"
/**
- Free the interface setting descriptor
+ Free the interface setting descriptor.
- @param Setting The descriptor to free
+ @param Setting The descriptor to free.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbFreeInterfaceDesc (
IN USB_INTERFACE_SETTING *Setting
@@ -61,17 +51,15 @@ UsbFreeInterfaceDesc ( }
-
/**
Free a configuration descriptor with its interface
- descriptors. It may be initialized partially
+ descriptors. It may be initialized partially.
- @param Config The configuration descriptor to free
+ @param Config The configuration descriptor to free.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbFreeConfigDesc (
IN USB_CONFIG_DESC *Config
@@ -112,13 +100,12 @@ UsbFreeConfigDesc ( }
-
/**
- Free a device descriptor with its configurations
+ Free a device descriptor with its configurations.
- @param DevDesc The device descriptor
+ @param DevDesc The device descriptor.
- @return None
+ @return None.
**/
VOID
@@ -143,17 +130,16 @@ UsbFreeDevDesc ( /**
- Create a descriptor
+ Create a descriptor.
- @param DescBuf The buffer of raw descriptor
- @param Len The lenght of the raw descriptor buffer
- @param Type The type of descriptor to create
- @param Consumed Number of bytes consumed
+ @param DescBuf The buffer of raw descriptor.
+ @param Len The lenght of the raw descriptor buffer.
+ @param Type The type of descriptor to create.
+ @param Consumed Number of bytes consumed.
- @return Created descriptor or NULL
+ @return Created descriptor or NULL.
**/
-STATIC
VOID *
UsbCreateDesc (
IN UINT8 *DescBuf,
@@ -226,16 +212,15 @@ UsbCreateDesc ( /**
- Parse an interface desciptor and its endpoints
+ Parse an interface desciptor and its endpoints.
- @param DescBuf The buffer of raw descriptor
- @param Len The lenght of the raw descriptor buffer
- @param Consumed The number of raw descriptor consumed
+ @param DescBuf The buffer of raw descriptor.
+ @param Len The lenght of the raw descriptor buffer.
+ @param Consumed The number of raw descriptor consumed.
- @return The create interface setting or NULL if failed
+ @return The create interface setting or NULL if failed.
**/
-STATIC
USB_INTERFACE_SETTING *
UsbParseInterfaceDesc (
IN UINT8 *DescBuf,
@@ -307,13 +292,12 @@ ON_ERROR: /**
Parse the configuration descriptor and its interfaces.
- @param DescBuf The buffer of raw descriptor
- @param Len The lenght of the raw descriptor buffer
+ @param DescBuf The buffer of raw descriptor.
+ @param Len The lenght of the raw descriptor buffer.
- @return The created configuration descriptor
+ @return The created configuration descriptor.
**/
-STATIC
USB_CONFIG_DESC *
UsbParseConfigDesc (
IN UINT8 *DescBuf,
@@ -407,25 +391,24 @@ ON_ERROR: }
-
/**
USB standard control transfer support routine. This
function is used by USB device. It is possible that
the device's interfaces are still waiting to be
enumerated.
- @param UsbDev The usb device
- @param Direction The direction of data transfer
- @param Type Standard / class specific / vendor specific
- @param Target The receiving target
- @param Request Which request
- @param Value The wValue parameter of the request
- @param Index The wIndex parameter of the request
- @param Buf The buffer to receive data into / transmit from
- @param Length The length of the buffer
+ @param UsbDev The usb device.
+ @param Direction The direction of data transfer.
+ @param Type Standard / class specific / vendor specific.
+ @param Target The receiving target.
+ @param Request Which request.
+ @param Value The wValue parameter of the request.
+ @param Index The wIndex parameter of the request.
+ @param Buf The buffer to receive data into / transmit from.
+ @param Length The length of the buffer.
- @retval EFI_SUCCESS The control request is executed
- @retval EFI_DEVICE_ERROR Failed to execute the control transfer
+ @retval EFI_SUCCESS The control request is executed.
+ @retval EFI_DEVICE_ERROR Failed to execute the control transfer.
**/
EFI_STATUS
@@ -473,23 +456,21 @@ UsbCtrlRequest ( }
-
/**
Get the standard descriptors.
- @param UsbDev The USB device to read descriptor from
- @param DescType The type of descriptor to read
- @param DescIndex The index of descriptor to read
+ @param UsbDev The USB device to read descriptor from.
+ @param DescType The type of descriptor to read.
+ @param DescIndex The index of descriptor to read.
@param LangId Language ID, only used to get string, otherwise set
- it to 0
- @param Buf The buffer to hold the descriptor read
- @param Length The length of the buffer
+ it to 0.
+ @param Buf The buffer to hold the descriptor read.
+ @param Length The length of the buffer.
- @retval EFI_SUCCESS The descriptor is read OK
- @retval Others Failed to retrieve the descriptor
+ @retval EFI_SUCCESS The descriptor is read OK.
+ @retval Others Failed to retrieve the descriptor.
**/
-STATIC
EFI_STATUS
UsbCtrlGetDesc (
IN USB_DEVICE *UsbDev,
@@ -518,16 +499,15 @@ UsbCtrlGetDesc ( }
-
/**
Return the max packet size for endpoint zero. This function
is the first function called to get descriptors during bus
enumeration.
- @param UsbDev The usb device
+ @param UsbDev The usb device.
- @retval EFI_SUCCESS The max packet size of endpoint zero is retrieved
- @retval EFI_DEVICE_ERROR Failed to retrieve it
+ @retval EFI_SUCCESS The max packet size of endpoint zero is retrieved.
+ @retval EFI_DEVICE_ERROR Failed to retrieve it.
**/
EFI_STATUS
@@ -561,17 +541,15 @@ UsbGetMaxPacketSize0 ( }
-
/**
Get the device descriptor for the device.
- @param UsbDev The Usb device to retrieve descriptor from
+ @param UsbDev The Usb device to retrieve descriptor from.
- @retval EFI_SUCCESS The device descriptor is returned
- @retval EFI_OUT_OF_RESOURCES Failed to allocate memory
+ @retval EFI_SUCCESS The device descriptor is returned.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
**/
-STATIC
EFI_STATUS
UsbGetDevDesc (
IN USB_DEVICE *UsbDev
@@ -605,17 +583,16 @@ UsbGetDevDesc ( }
-
/**
Retrieve the indexed string for the language. It requires two
steps to get a string, first to get the string's length. Then
the string itself.
- @param UsbDev The usb device
- @param Index The index the string to retrieve
- @param LangId Language ID
+ @param UsbDev The usb device.
+ @param Index The index the string to retrieve.
+ @param LangId Language ID.
- @return The created string descriptor or NULL
+ @return The created string descriptor or NULL.
**/
EFI_USB_STRING_DESCRIPTOR *
@@ -662,16 +639,14 @@ UsbGetOneString ( }
-
/**
- Build the language ID table for string descriptors
+ Build the language ID table for string descriptors.
- @param UsbDev The Usb device
+ @param UsbDev The Usb device.
- @retval EFI_UNSUPPORTED This device doesn't support string table
+ @retval EFI_UNSUPPORTED This device doesn't support string table.
**/
-STATIC
EFI_STATUS
UsbBuildLangTable (
IN USB_DEVICE *UsbDev
@@ -716,20 +691,18 @@ ON_EXIT: }
-
/**
Retrieve the indexed configure for the device. USB device
returns the configuration togetther with the interfaces for
this configuration. Configuration descriptor is also of
- variable length
+ variable length.
- @param UsbDev The Usb interface
- @param Index The index of the configuration
+ @param UsbDev The Usb interface.
+ @param Index The index of the configuration.
- @return The created configuration descriptor
+ @return The created configuration descriptor.
**/
-STATIC
EFI_USB_CONFIG_DESCRIPTOR *
UsbGetOneConfig (
IN USB_DEVICE *UsbDev,
@@ -774,16 +747,15 @@ UsbGetOneConfig ( }
-
/**
Build the whole array of descriptors. This function must
be called after UsbGetMaxPacketSize0 returns the max packet
size correctly for endpoint 0.
- @param UsbDev The Usb device
+ @param UsbDev The Usb device.
- @retval EFI_SUCCESS The descriptor table is build
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the descriptor
+ @retval EFI_SUCCESS The descriptor table is build.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the descriptor.
**/
EFI_STATUS
@@ -877,11 +849,11 @@ UsbBuildDescTable ( /**
Set the device's address.
- @param UsbDev The device to set address to
- @param Address The address to set
+ @param UsbDev The device to set address to.
+ @param Address The address to set.
- @retval EFI_SUCCESS The device is set to the address
- @retval Others Failed to set the device address
+ @retval EFI_SUCCESS The device is set to the address.
+ @retval Others Failed to set the device address.
**/
EFI_STATUS
@@ -913,11 +885,11 @@ UsbSetAddress ( the device's internal state. UsbSelectConfig changes
the Usb bus's internal state.
- @param UsbDev The USB device to set configure to
- @param ConfigIndex The configure index to set
+ @param UsbDev The USB device to set configure to.
+ @param ConfigIndex The configure index to set.
- @retval EFI_SUCCESS The device is configured now
- @retval Others Failed to set the device configure
+ @retval EFI_SUCCESS The device is configured now.
+ @retval Others Failed to set the device configure.
**/
EFI_STATUS
@@ -944,19 +916,18 @@ UsbSetConfig ( }
-
/**
Usb UsbIo interface to clear the feature. This is should
only be used by HUB which is considered a device driver
on top of the UsbIo interface.
- @param UsbIo The UsbIo interface
- @param Target The target of the transfer: endpoint/device
- @param Feature The feature to clear
- @param Index The wIndex parameter
+ @param UsbIo The UsbIo interface.
+ @param Target The target of the transfer: endpoint/device.
+ @param Feature The feature to clear.
+ @param Index The wIndex parameter.
- @retval EFI_SUCCESS The device feature is cleared
- @retval Others Failed to clear the feature
+ @retval EFI_SUCCESS The device feature is cleared.
+ @retval Others Failed to clear the feature.
**/
EFI_STATUS
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h index 14f3c7feb0..dd7868bc1d 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h @@ -1,5 +1,7 @@ /** @file
+ Manage Usb Descriptor List
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,25 +11,14 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbDesc.h
-
- Abstract:
-
- Manage Usb Descriptor List
-
- Revision History
-
-
**/
#ifndef _USB_DESCRIPTOR_H_
#define _USB_DESCRIPTOR_H_
-enum {
+typedef enum {
USB_MAX_INTERFACE_SETTING = 8
-};
+}USB_INTERFACE_SETTING_MAX;
//
// The RequestType in EFI_USB_DEVICE_REQUEST is composed of
@@ -89,6 +80,26 @@ typedef struct { USB_CONFIG_DESC **Configs;
} USB_DEVICE_DESC;
+/**
+ USB standard control transfer support routine. This
+ function is used by USB device. It is possible that
+ the device's interfaces are still waiting to be
+ enumerated.
+
+ @param UsbDev The usb device.
+ @param Direction The direction of data transfer.
+ @param Type Standard / class specific / vendor specific.
+ @param Target The receiving target.
+ @param Request Which request.
+ @param Value The wValue parameter of the request.
+ @param Index The wIndex parameter of the request.
+ @param Buf The buffer to receive data into / transmit from.
+ @param Length The length of the buffer.
+
+ @retval EFI_SUCCESS The control request is executed.
+ @retval EFI_DEVICE_ERROR Failed to execute the control transfer.
+
+**/
EFI_STATUS
UsbCtrlRequest (
IN USB_DEVICE *UsbDev,
@@ -102,16 +113,47 @@ UsbCtrlRequest ( IN UINTN Length
);
+/**
+ Return the max packet size for endpoint zero. This function
+ is the first function called to get descriptors during bus
+ enumeration.
+
+ @param UsbDev The usb device.
+
+ @retval EFI_SUCCESS The max packet size of endpoint zero is retrieved.
+ @retval EFI_DEVICE_ERROR Failed to retrieve it.
+
+**/
EFI_STATUS
UsbGetMaxPacketSize0 (
IN USB_DEVICE *UsbDev
);
+/**
+ Free a device descriptor with its configurations.
+
+ @param DevDesc The device descriptor.
+
+ @return None.
+
+**/
VOID
UsbFreeDevDesc (
IN USB_DEVICE_DESC *DevDesc
);
+/**
+ Retrieve the indexed string for the language. It requires two
+ steps to get a string, first to get the string's length. Then
+ the string itself.
+
+ @param UsbDev The usb device.
+ @param StringIndex The index of the string to retrieve.
+ @param LangId Language ID.
+
+ @return The created string descriptor or NULL.
+
+**/
EFI_USB_STRING_DESCRIPTOR*
UsbGetOneString (
IN USB_DEVICE *UsbDev,
@@ -119,23 +161,70 @@ UsbGetOneString ( IN UINT16 LangId
);
+/**
+ Build the whole array of descriptors. This function must
+ be called after UsbGetMaxPacketSize0 returns the max packet
+ size correctly for endpoint 0.
+
+ @param UsbDev The Usb device.
+
+ @retval EFI_SUCCESS The descriptor table is build.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the descriptor.
+
+**/
EFI_STATUS
UsbBuildDescTable (
IN USB_DEVICE *UsbDev
);
+/**
+ Set the device's address.
+
+ @param UsbDev The device to set address to.
+ @param Address The address to set.
+
+ @retval EFI_SUCCESS The device is set to the address.
+ @retval Others Failed to set the device address.
+
+**/
EFI_STATUS
UsbSetAddress (
IN USB_DEVICE *UsbDev,
IN UINT8 Address
);
+/**
+ Set the device's configuration. This function changes
+ the device's internal state. UsbSelectConfig changes
+ the Usb bus's internal state.
+
+ @param UsbDev The USB device to set configure to.
+ @param ConfigIndex The configure index to set.
+
+ @retval EFI_SUCCESS The device is configured now.
+ @retval Others Failed to set the device configure.
+
+**/
EFI_STATUS
UsbSetConfig (
IN USB_DEVICE *UsbDev,
IN UINT8 ConfigIndex
);
+/**
+ Usb UsbIo interface to clear the feature. This is should
+ only be used by HUB which is considered a device driver
+ on top of the UsbIo interface.
+
+ @param UsbIo The UsbIo interface.
+ @param Target The target of the transfer: endpoint/device.
+ @param Feature The feature to clear.
+ @param Index The wIndex parameter.
+
+ @retval EFI_SUCCESS The device feature is cleared.
+ @retval Others Failed to clear the feature.
+
+**/
EFI_STATUS
UsbIoClearFeature (
IN EFI_USB_IO_PROTOCOL *UsbIo,
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c index b7c66fec83..3a2b8bc017 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c @@ -1,5 +1,7 @@ /** @file
+ Usb bus enumeration support.
+
Copyright (c) 2007 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,29 +11,18 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbEnumer.c
-
- Abstract:
-
- Usb bus enumeration support
-
- Revision History
-
-
**/
#include "UsbBus.h"
/**
- Return the endpoint descriptor in this interface
+ Return the endpoint descriptor in this interface.
- @param UsbIf The interface to search in
- @param EpAddr The address of the endpoint to return
+ @param UsbIf The interface to search in.
+ @param EpAddr The address of the endpoint to return.
- @return The endpoint descriptor or NULL
+ @return The endpoint descriptor or NULL.
**/
USB_ENDPOINT_DESC *
@@ -56,14 +47,13 @@ UsbGetEndpointDesc ( /**
- Free the resource used by USB interface
+ Free the resource used by USB interface.
- @param UsbIf The USB interface to free
+ @param UsbIf The USB interface to free.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbFreeInterface (
IN USB_INTERFACE *UsbIf
@@ -92,13 +82,12 @@ UsbFreeInterface ( Create an interface for the descriptor IfDesc. Each
device's configuration can have several interfaces.
- @param Device The device has the interface descriptor
- @param IfDesc The interface descriptor
+ @param Device The device has the interface descriptor.
+ @param IfDesc The interface descriptor.
@return The created USB interface for the descriptor, or NULL.
**/
-STATIC
USB_INTERFACE *
UsbCreateInterface (
IN USB_DEVICE *Device,
@@ -185,7 +174,7 @@ UsbCreateInterface ( return UsbIf;
ON_ERROR:
- if (UsbIf->DevicePath) {
+ if (UsbIf->DevicePath != NULL) {
gBS->FreePool (UsbIf->DevicePath);
}
@@ -195,14 +184,13 @@ ON_ERROR: /**
- Free the resource used by this USB device
+ Free the resource used by this USB device.
- @param Device The USB device to free
+ @param Device The USB device to free.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbFreeDevice (
IN USB_DEVICE *Device
@@ -219,13 +207,12 @@ UsbFreeDevice ( /**
Create a device which is on the parent's ParentPort port.
- @param ParentIf The parent HUB interface
- @param ParentPort The port on the HUB this device is connected to
+ @param ParentIf The parent HUB interface.
+ @param ParentPort The port on the HUB this device is connected to.
- @return Created USB device
+ @return Created USB device, Or NULL.
**/
-STATIC
USB_DEVICE *
UsbCreateDevice (
IN USB_INTERFACE *ParentIf,
@@ -255,13 +242,12 @@ UsbCreateDevice ( Connect the USB interface with its driver. EFI USB bus will
create a USB interface for each seperate interface descriptor.
- @param UsbIf The interface to connect driver to
+ @param UsbIf The interface to connect driver to.
- @return EFI_SUCCESS : Interface is managed by some driver
- @return Others : Failed to locate a driver for this interface
+ @return EFI_SUCCESS Interface is managed by some driver.
+ @return Others Failed to locate a driver for this interface.
**/
-STATIC
EFI_STATUS
UsbConnectDriver (
IN USB_INTERFACE *UsbIf
@@ -318,10 +304,10 @@ UsbConnectDriver ( settings. Only one setting is active. It will
also reset its endpoints' toggle to zero.
- @param IfDesc The interface descriptor to set
- @param Alternate The alternate setting number to locate
+ @param IfDesc The interface descriptor to set.
+ @param Alternate The alternate setting number to locate.
- @retval EFI_NOT_FOUND There is no setting with this alternate index
+ @retval EFI_NOT_FOUND There is no setting with this alternate index.
@retval EFI_SUCCESS The interface is set to Alternate setting.
**/
@@ -371,11 +357,11 @@ UsbSelectSetting ( Select a new configuration for the device. Each
device may support several configurations.
- @param Device The device to select configuration
- @param ConfigValue The index of the configuration ( != 0)
+ @param Device The device to select configuration.
+ @param ConfigValue The index of the configuration ( != 0).
- @retval EFI_NOT_FOUND There is no configuration with the index
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource
+ @retval EFI_NOT_FOUND There is no configuration with the index.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource.
@retval EFI_SUCCESS The configuration is selected.
**/
@@ -455,16 +441,14 @@ UsbSelectConfig ( }
-
/**
Disconnect the USB interface with its driver.
- @param UsbIf The interface to disconnect driver from
+ @param UsbIf The interface to disconnect driver from.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbDisconnectDriver (
IN USB_INTERFACE *UsbIf
@@ -503,13 +487,12 @@ UsbDisconnectDriver ( }
-
/**
- Remove the current device configuration
+ Remove the current device configuration.
- @param Device The USB device to remove configuration from
+ @param Device The USB device to remove configuration from.
- @return None
+ @return None.
**/
VOID
@@ -540,13 +523,12 @@ UsbRemoveConfig ( }
-
/**
Remove the device and all its children from the bus.
- @param Device The device to remove
+ @param Device The device to remove.
- @retval EFI_SUCCESS The device is removed
+ @retval EFI_SUCCESS The device is removed.
**/
EFI_STATUS
@@ -592,15 +574,14 @@ UsbRemoveDevice ( /**
- Find the child device on the hub's port
+ Find the child device on the hub's port.
- @param HubIf The hub interface
- @param Port The port of the hub this child is connected to
+ @param HubIf The hub interface.
+ @param Port The port of the hub this child is connected to.
- @return The device on the hub's port, or NULL if there is none
+ @return The device on the hub's port, or NULL if there is none.
**/
-STATIC
USB_DEVICE *
UsbFindChild (
IN USB_INTERFACE *HubIf,
@@ -630,19 +611,17 @@ UsbFindChild ( }
-
/**
Enumerate and configure the new device on the port of this HUB interface.
- @param HubIf The HUB that has the device connected
- @param Port The port index of the hub (started with zero)
+ @param HubIf The HUB that has the device connected.
+ @param Port The port index of the hub (started with zero).
- @retval EFI_SUCCESS The device is enumerated (added or removed)
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the device
- @retval Others Failed to enumerate the device
+ @retval EFI_SUCCESS The device is enumerated (added or removed).
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the device.
+ @retval Others Failed to enumerate the device.
**/
-STATIC
EFI_STATUS
UsbEnumerateNewDev (
IN USB_INTERFACE *HubIf,
@@ -832,19 +811,17 @@ ON_ERROR: }
-
/**
Process the events on the port.
- @param HubIf The HUB that has the device connected
- @param Port The port index of the hub (started with zero)
+ @param HubIf The HUB that has the device connected.
+ @param Port The port index of the hub (started with zero).
- @retval EFI_SUCCESS The device is enumerated (added or removed)
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the device
- @retval Others Failed to enumerate the device
+ @retval EFI_SUCCESS The device is enumerated (added or removed).
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the device.
+ @retval Others Failed to enumerate the device.
**/
-STATIC
EFI_STATUS
UsbEnumeratePort (
IN USB_INTERFACE *HubIf,
@@ -949,15 +926,16 @@ UsbEnumeratePort ( /**
- Enumerate all the changed hub ports
+ Enumerate all the changed hub ports.
- @param Event The event that is triggered
- @param Context The context to the event
+ @param Event The event that is triggered.
+ @param Context The context to the event.
- @return None
+ @return None.
**/
VOID
+EFIAPI
UsbHubEnumeration (
IN EFI_EVENT Event,
IN VOID *Context
@@ -999,12 +977,12 @@ UsbHubEnumeration ( /**
- Enumerate all the changed hub ports
+ Enumerate all the changed hub ports.
- @param Event The event that is triggered
- @param Context The context to the event
+ @param Event The event that is triggered.
+ @param Context The context to the event.
- @return None
+ @return None.
**/
VOID
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.h index 54f4dd2ca0..1b36a6d853 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.h +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.h @@ -1,5 +1,7 @@ /** @file
+ USB bus enumeration interface.
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbEnumer.h
-
- Abstract:
-
- USB bus enumeration interface
-
- Revision History
-
-
**/
#ifndef _USB_ENUMERATION_H_
@@ -110,35 +101,93 @@ struct _USB_HUB_API{ USB_HUB_RELEASE Release;
};
+/**
+ Return the endpoint descriptor in this interface.
+
+ @param UsbIf The interface to search in.
+ @param EpAddr The address of the endpoint to return.
+
+ @return The endpoint descriptor or NULL.
+
+**/
USB_ENDPOINT_DESC*
UsbGetEndpointDesc (
IN USB_INTERFACE *UsbIf,
IN UINT8 EpAddr
);
+/**
+ Select an alternate setting for the interface.
+ Each interface can have several mutually exclusive
+ settings. Only one setting is active. It will
+ also reset its endpoints' toggle to zero.
+
+ @param IfDesc The interface descriptor to set.
+ @param Alternate The alternate setting number to locate.
+
+ @retval EFI_NOT_FOUND There is no setting with this alternate index.
+ @retval EFI_SUCCESS The interface is set to Alternate setting.
+**/
EFI_STATUS
UsbSelectSetting (
IN USB_INTERFACE_DESC *IfDesc,
IN UINT8 Alternate
);
+/**
+ Select a new configuration for the device. Each
+ device may support several configurations.
+
+ @param Device The device to select configuration.
+ @param ConfigIndex The index of the configuration ( != 0).
+
+ @retval EFI_NOT_FOUND There is no configuration with the index.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource.
+ @retval EFI_SUCCESS The configuration is selected.
+
+**/
EFI_STATUS
UsbSelectConfig (
IN USB_DEVICE *Device,
IN UINT8 ConfigIndex
);
+/**
+ Remove the current device configuration.
+
+ @param Device The USB device to remove configuration from.
+
+ @return None.
+
+**/
VOID
UsbRemoveConfig (
IN USB_DEVICE *Device
);
+/**
+ Remove the device and all its children from the bus.
+
+ @param Device The device to remove.
+
+ @retval EFI_SUCCESS The device is removed.
+
+**/
EFI_STATUS
UsbRemoveDevice (
IN USB_DEVICE *Device
);
+/**
+ Enumerate all the changed hub ports.
+
+ @param Event The event that is triggered.
+ @param Context The context to the event.
+
+ @return None.
+
+**/
VOID
EFIAPI
UsbHubEnumeration (
@@ -146,6 +195,15 @@ UsbHubEnumeration ( IN VOID *Context
);
+/**
+ Enumerate all the changed hub ports.
+
+ @param Event The event that is triggered.
+ @param Context The context to the event.
+
+ @return None.
+
+**/
VOID
EFIAPI
UsbRootHubEnumeration (
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c index 171a780d0c..58e0ef194f 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c @@ -1,5 +1,7 @@ /** @file
+ Unified interface for RootHub and Hub.
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbHub.c
-
- Abstract:
-
- Unified interface for RootHub and Hub
-
- Revision History
-
-
**/
#include "UsbBus.h"
@@ -32,16 +23,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /**
- USB hub control transfer to clear the hub feature
+ USB hub control transfer to clear the hub feature.
- @param HubDev The device of the hub
- @param Feature The feature to clear
+ @param HubDev The device of the hub.
+ @param Feature The feature to clear.
- @retval EFI_SUCCESS Feature of the hub is cleared
- @retval Others Failed to clear the feature
+ @retval EFI_SUCCESS Feature of the hub is cleared.
+ @retval Others Failed to clear the feature.
**/
-STATIC
EFI_STATUS
UsbHubCtrlClearHubFeature (
IN USB_DEVICE *HubDev,
@@ -67,17 +57,16 @@ UsbHubCtrlClearHubFeature ( /**
- Clear the feature of the device's port
+ Clear the feature of the device's port.
- @param HubDev The hub device
- @param Port The port to clear feature
- @param Feature The feature to clear
+ @param HubDev The hub device.
+ @param Port The port to clear feature.
+ @param Feature The feature to clear.
@retval EFI_SUCCESS The feature of the port is cleared.
@retval Others Failed to clear the feature.
**/
-STATIC
EFI_STATUS
UsbHubCtrlClearPortFeature (
IN USB_DEVICE *HubDev,
@@ -107,7 +96,6 @@ UsbHubCtrlClearPortFeature ( }
-
/**
Clear the transaction translate buffer if full/low
speed control/bulk transfer failed and the transfer
@@ -115,14 +103,14 @@ UsbHubCtrlClearPortFeature ( buffer of transaction translator, not that of the
parent.
- @param HubDev The hub device
- @param Port The port of the hub
- @param DevAddr Address of the failed transaction
- @param EpNum The endpoint number of the failed transaction
- @param EpType The type of failed transaction
+ @param HubDev The hub device.
+ @param Port The port of the hub.
+ @param DevAddr Address of the failed transaction.
+ @param EpNum The endpoint number of the failed transaction.
+ @param EpType The type of failed transaction.
- @retval EFI_SUCCESS The TT buffer is cleared
- @retval Others Failed to clear the TT buffer
+ @retval EFI_SUCCESS The TT buffer is cleared.
+ @retval Others Failed to clear the TT buffer.
**/
EFI_STATUS
@@ -160,17 +148,16 @@ UsbHubCtrlClearTTBuffer ( /**
- Usb hub control transfer to get the hub descriptor
+ Usb hub control transfer to get the hub descriptor.
- @param HubDev The hub device
- @param Buf The buffer to hold the descriptor
- @param Len The length to retrieve
+ @param HubDev The hub device.
+ @param Buf The buffer to hold the descriptor.
+ @param Len The length to retrieve.
- @retval EFI_SUCCESS The hub descriptor is retrieved
- @retval Others Failed to retrieve the hub descriptor
+ @retval EFI_SUCCESS The hub descriptor is retrieved.
+ @retval Others Failed to retrieve the hub descriptor.
**/
-STATIC
EFI_STATUS
UsbHubCtrlGetHubDesc (
IN USB_DEVICE *HubDev,
@@ -197,16 +184,15 @@ UsbHubCtrlGetHubDesc ( /**
- Usb hub control transfer to get the hub status
+ Usb hub control transfer to get the hub status.
- @param HubDev The hub device
- @param State The variable to return the status
+ @param HubDev The hub device.
+ @param State The variable to return the status.
- @retval EFI_SUCCESS The hub status is returned in State
- @retval Others Failed to get the hub status
+ @retval EFI_SUCCESS The hub status is returned in State.
+ @retval Others Failed to get the hub status.
**/
-STATIC
EFI_STATUS
UsbHubCtrlGetHubStatus (
IN USB_DEVICE *HubDev,
@@ -232,17 +218,16 @@ UsbHubCtrlGetHubStatus ( /**
- Usb hub control transfer to get the port status
+ Usb hub control transfer to get the port status.
- @param HubDev The hub device
- @param Port The port of the hub
- @param State Variable to return the hub port state
+ @param HubDev The hub device.
+ @param Port The port of the hub.
+ @param State Variable to return the hub port state.
- @retval EFI_SUCCESS The port state is returned in State
- @retval Others Failed to retrive the port state
+ @retval EFI_SUCCESS The port state is returned in State.
+ @retval Others Failed to retrive the port state.
**/
-STATIC
EFI_STATUS
UsbHubCtrlGetPortStatus (
IN USB_DEVICE *HubDev,
@@ -275,13 +260,13 @@ UsbHubCtrlGetPortStatus ( /**
- Usb hub control transfer to reset the TT (Transaction Transaltor)
+ Usb hub control transfer to reset the TT (Transaction Transaltor).
- @param HubDev The hub device
- @param Port The port of the hub
+ @param HubDev The hub device.
+ @param Port The port of the hub.
- @retval EFI_SUCCESS The TT of the hub is reset
- @retval Others Failed to reset the port
+ @retval EFI_SUCCESS The TT of the hub is reset.
+ @retval Others Failed to reset the port.
**/
EFI_STATUS
@@ -309,13 +294,13 @@ UsbHubCtrlResetTT ( /**
- Usb hub control transfer to set the hub feature
+ Usb hub control transfer to set the hub feature.
- @param HubDev The hub device
- @param Feature The feature to set
+ @param HubDev The hub device.
+ @param Feature The feature to set.
- @retval EFI_SUCESS The feature is set for the hub
- @retval Others Failed to set the feature
+ @retval EFI_SUCESS The feature is set for the hub.
+ @retval Others Failed to set the feature.
**/
EFI_STATUS
@@ -343,17 +328,16 @@ UsbHubCtrlSetHubFeature ( /**
- Usb hub control transfer to set the port feature
+ Usb hub control transfer to set the port feature.
- @param HubDev The Usb hub device
- @param Port The Usb port to set feature for
- @param Feature The feature to set
+ @param HubDev The Usb hub device.
+ @param Port The Usb port to set feature for.
+ @param Feature The feature to set.
- @retval EFI_SUCCESS The feature is set for the port
- @retval Others Failed to set the feature
+ @retval EFI_SUCCESS The feature is set for the port.
+ @retval Others Failed to set the feature.
**/
-STATIC
EFI_STATUS
UsbHubCtrlSetPortFeature (
IN USB_DEVICE *HubDev,
@@ -386,16 +370,15 @@ UsbHubCtrlSetPortFeature ( /**
Read the whole usb hub descriptor. It is necessary
to do it in two steps because hub descriptor is of
- variable length
+ variable length.
- @param HubDev The hub device
- @param HubDesc The variable to return the descriptor
+ @param HubDev The hub device.
+ @param HubDesc The variable to return the descriptor.
- @retval EFI_SUCCESS The hub descriptor is read
- @retval Others Failed to read the hub descriptor
+ @retval EFI_SUCCESS The hub descriptor is read.
+ @retval Others Failed to read the hub descriptor.
**/
-STATIC
EFI_STATUS
UsbHubReadDesc (
IN USB_DEVICE *HubDev,
@@ -427,10 +410,10 @@ UsbHubReadDesc ( Ack the hub change bits. If these bits are not ACKed, Hub will
always return changed bit map from its interrupt endpoint.
- @param HubDev The hub device
+ @param HubDev The hub device.
- @retval EFI_SUCCESS The hub change status is ACKed
- @retval Others Failed to ACK the hub status
+ @retval EFI_SUCCESS The hub change status is ACKed.
+ @retval Others Failed to ACK the hub status.
**/
EFI_STATUS
@@ -462,10 +445,10 @@ UsbHubAckHubStatus ( /**
Test whether the interface is a hub interface.
- @param UsbIf The interface to test
+ @param UsbIf The interface to test.
- @retval TRUE The interface is a hub interface
- @retval FALSE The interface isn't a hub interface
+ @retval TRUE The interface is a hub interface.
+ @retval FALSE The interface isn't a hub interface.
**/
BOOLEAN
@@ -496,16 +479,15 @@ UsbIsHubInterface ( interrupt endpoint. It is called periodically by
the underlying host controller.
- @param Data The data read
- @param DataLength The length of the data read
- @param Context The context
- @param Result The result of the last interrupt transfer
+ @param Data The data read.
+ @param DataLength The length of the data read.
+ @param Context The context.
+ @param Result The result of the last interrupt transfer.
- @retval EFI_SUCCESS The process is OK
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource
+ @retval EFI_SUCCESS The process is OK.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource.
**/
-STATIC
EFI_STATUS
UsbOnHubInterrupt (
IN VOID *Data,
@@ -624,15 +606,14 @@ USB_CHANGE_FEATURE_MAP mRootHubFeatureMap[USB_ROOT_HUB_MAP_SIZE] = { /**
- Initialize the device for a non-root hub
+ Initialize the device for a non-root hub.
- @param HubIf The USB hub interface
+ @param HubIf The USB hub interface.
- @retval EFI_SUCCESS The hub is initialized
- @retval EFI_DEVICE_ERROR Failed to initialize the hub
+ @retval EFI_SUCCESS The hub is initialized.
+ @retval EFI_DEVICE_ERROR Failed to initialize the hub.
**/
-STATIC
EFI_STATUS
UsbHubInit (
IN USB_INTERFACE *HubIf
@@ -760,15 +741,14 @@ UsbHubInit ( the port changes in PortState. Bus enumeration code
doesn't need to ACK the port change bits.
- @param HubIf The hub interface
- @param Port The port of the hub to get state
- @param PortState Variable to return the port state
+ @param HubIf The hub interface.
+ @param Port The port of the hub to get state.
+ @param PortState Variable to return the port state.
- @retval EFI_SUCCESS The port status is successfully returned
- @retval Others Failed to return the status
+ @retval EFI_SUCCESS The port status is successfully returned.
+ @retval Others Failed to return the status.
**/
-STATIC
EFI_STATUS
UsbHubGetPortStatus (
IN USB_INTERFACE *HubIf,
@@ -788,13 +768,12 @@ UsbHubGetPortStatus ( /**
Clear the port change status.
- @param HubIf The hub interface
- @param Port The hub port
+ @param HubIf The hub interface.
+ @param Port The hub port.
- @return None
+ @return None.
**/
-STATIC
VOID
UsbHubClearPortChange (
IN USB_INTERFACE *HubIf,
@@ -830,17 +809,16 @@ UsbHubClearPortChange ( /**
- Function to set the port feature for non-root hub
+ Function to set the port feature for non-root hub.
- @param HubIf The hub interface
- @param Port The port of the hub
- @param Feature The feature of the port to set
+ @param HubIf The hub interface.
+ @param Port The port of the hub.
+ @param Feature The feature of the port to set.
- @retval EFI_SUCCESS The hub port feature is set
- @retval Others Failed to set the port feature
+ @retval EFI_SUCCESS The hub port feature is set.
+ @retval Others Failed to set the port feature.
**/
-STATIC
EFI_STATUS
UsbHubSetPortFeature (
IN USB_INTERFACE *HubIf,
@@ -857,17 +835,16 @@ UsbHubSetPortFeature ( /**
- Interface function to clear the port feature for non-root hub
+ Interface function to clear the port feature for non-root hub.
- @param HubIf The hub interface
- @param Port The port of the hub to clear feature for
- @param Feature The feature to clear
+ @param HubIf The hub interface.
+ @param Port The port of the hub to clear feature for.
+ @param Feature The feature to clear.
- @retval EFI_SUCCESS The port feature is cleared
- @retval Others Failed to clear the port feature
+ @retval EFI_SUCCESS The port feature is cleared.
+ @retval Others Failed to clear the port feature.
**/
-STATIC
EFI_STATUS
UsbHubClearPortFeature (
IN USB_INTERFACE *HubIf,
@@ -884,17 +861,16 @@ UsbHubClearPortFeature ( /**
- Interface funtion to reset the port
+ Interface funtion to reset the port.
- @param HubIf The hub interface
- @param Port The port to reset
+ @param HubIf The hub interface.
+ @param Port The port to reset.
- @retval EFI_SUCCESS The hub port is reset
- @retval EFI_TIMEOUT Failed to reset the port in time
- @retval Others Failed to reset the port
+ @retval EFI_SUCCESS The hub port is reset.
+ @retval EFI_TIMEOUT Failed to reset the port in time.
+ @retval Others Failed to reset the port.
**/
-STATIC
EFI_STATUS
UsbHubResetPort (
IN USB_INTERFACE *HubIf,
@@ -939,14 +915,13 @@ UsbHubResetPort ( /**
- Release the hub's control of the interface
+ Release the hub's control of the interface.
- @param HubIf The hub interface
+ @param HubIf The hub interface.
- @retval EFI_SUCCESS The interface is release of hub control
+ @retval EFI_SUCCESS The interface is release of hub control.
**/
-STATIC
EFI_STATUS
UsbHubRelease (
IN USB_INTERFACE *HubIf
@@ -984,15 +959,14 @@ UsbHubRelease ( /**
- Initialize the interface for root hub
+ Initialize the interface for root hub.
- @param HubIf The root hub interface
+ @param HubIf The root hub interface.
- @retval EFI_SUCCESS The interface is initialied for root hub
- @retval Others Failed to initialize the hub
+ @retval EFI_SUCCESS The interface is initialied for root hub.
+ @retval Others Failed to initialize the hub.
**/
-STATIC
EFI_STATUS
UsbRootHubInit (
IN USB_INTERFACE *HubIf
@@ -1054,22 +1028,20 @@ UsbRootHubInit ( }
-
/**
Get the port status. This function is required to
ACK the port change bits although it will return
the port changes in PortState. Bus enumeration code
doesn't need to ACK the port change bits.
- @param HubIf The root hub interface
- @param Port The root hub port to get the state
- @param PortState Variable to return the port state
+ @param HubIf The root hub interface.
+ @param Port The root hub port to get the state.
+ @param PortState Variable to return the port state.
- @retval EFI_SUCCESS The port state is returned
- @retval Others Failed to retrieve the port state
+ @retval EFI_SUCCESS The port state is returned.
+ @retval Others Failed to retrieve the port state.
**/
-STATIC
EFI_STATUS
UsbRootHubGetPortStatus (
IN USB_INTERFACE *HubIf,
@@ -1090,14 +1062,13 @@ UsbRootHubGetPortStatus ( /**
Clear the port change status.
- @param HubIf The root hub interface
- @param Port The root hub port
+ @param HubIf The root hub interface.
+ @param Port The root hub port.
- @retval EFI_SUCCESS The port state is returned
- @retval Others Failed to retrieve the port state
+ @retval EFI_SUCCESS The port state is returned.
+ @retval Others Failed to retrieve the port state.
**/
-STATIC
VOID
UsbRootHubClearPortChange (
IN USB_INTERFACE *HubIf,
@@ -1131,19 +1102,17 @@ UsbRootHubClearPortChange ( }
-
/**
- Set the root hub port feature
+ Set the root hub port feature.
- @param HubIf The Usb hub interface
- @param Port The hub port
- @param Feature The feature to set
+ @param HubIf The Usb hub interface.
+ @param Port The hub port.
+ @param Feature The feature to set.
- @retval EFI_SUCCESS The root hub port is set with the feature
- @retval Others Failed to set the feature
+ @retval EFI_SUCCESS The root hub port is set with the feature.
+ @retval Others Failed to set the feature.
**/
-STATIC
EFI_STATUS
UsbRootHubSetPortFeature (
IN USB_INTERFACE *HubIf,
@@ -1160,17 +1129,16 @@ UsbRootHubSetPortFeature ( /**
- Clear the root hub port feature
+ Clear the root hub port feature.
- @param HubIf The root hub interface
- @param Port The root hub port
- @param Feature The feature to clear
+ @param HubIf The root hub interface.
+ @param Port The root hub port.
+ @param Feature The feature to clear.
- @retval EFI_SUCCESS The root hub port is cleared of the feature
- @retval Others Failed to clear the feature
+ @retval EFI_SUCCESS The root hub port is cleared of the feature.
+ @retval Others Failed to clear the feature.
**/
-STATIC
EFI_STATUS
UsbRootHubClearPortFeature (
IN USB_INTERFACE *HubIf,
@@ -1187,19 +1155,18 @@ UsbRootHubClearPortFeature ( /**
- Interface funtion to reset the root hub port
+ Interface funtion to reset the root hub port.
- @param RootIf The root hub interface
- @param Port The port to reset
+ @param RootIf The root hub interface.
+ @param Port The port to reset.
- @retval EFI_SUCCESS The hub port is reset
- @retval EFI_TIMEOUT Failed to reset the port in time
- @retval EFI_NOT_FOUND The low/full speed device connected to high speed
- root hub is released to the companion UHCI
- @retval Others Failed to reset the port
+ @retval EFI_SUCCESS The hub port is reset.
+ @retval EFI_TIMEOUT Failed to reset the port in time.
+ @retval EFI_NOT_FOUND The low/full speed device connected to high speed.
+ root hub is released to the companion UHCI.
+ @retval Others Failed to reset the port.
**/
-STATIC
EFI_STATUS
UsbRootHubResetPort (
IN USB_INTERFACE *RootIf,
@@ -1295,15 +1262,14 @@ UsbRootHubResetPort ( /**
- Release the root hub's control of the interface
+ Release the root hub's control of the interface.
- @param HubIf The root hub interface
+ @param HubIf The root hub interface.
@retval EFI_SUCCESS The root hub's control of the interface is
released.
**/
-STATIC
EFI_STATUS
UsbRootHubRelease (
IN USB_INTERFACE *HubIf
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.h index e31ba27586..af4897a74b 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.h +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.h @@ -1,5 +1,7 @@ /** @file
+ The definition for USB hub.
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbHub.h
-
- Abstract:
-
- The definition for USB hub
-
- Revision History
-
-
**/
#ifndef _USB_HUB_H_
@@ -30,7 +21,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define USB_ENDPOINT_ADDR(EpAddr) ((EpAddr) & 0x7F)
#define USB_ENDPOINT_TYPE(Desc) ((Desc)->Attributes & USB_ENDPOINT_TYPE_MASK)
-enum {
+typedef enum {
USB_DESC_TYPE_HUB = 0x29,
//
@@ -95,7 +86,7 @@ enum { // after 500ms(LOOP * STALL = 100 * 5ms), set by experience
//
USB_WAIT_PORT_STS_CHANGE_LOOP = 100
-};
+}USB_HUB_FLAGS_VALUE;
#pragma pack(1)
//
@@ -119,6 +110,23 @@ typedef struct { } USB_CHANGE_FEATURE_MAP;
+/**
+ Clear the transaction translate buffer if full/low
+ speed control/bulk transfer failed and the transfer
+ uses this hub as translator.Remember to clear the TT
+ buffer of transaction translator, not that of the
+ parent.
+
+ @param UsbDev The Usb device.
+ @param Port The port of the hub.
+ @param DevAddr Address of the failed transaction.
+ @param EpNum The endpoint number of the failed transaction.
+ @param EpType The type of failed transaction.
+
+ @retval EFI_SUCCESS The TT buffer is cleared.
+ @retval Others Failed to clear the TT buffer.
+
+**/
EFI_STATUS
UsbHubCtrlClearTTBuffer (
IN USB_DEVICE *UsbDev,
@@ -129,11 +137,31 @@ UsbHubCtrlClearTTBuffer ( );
+/**
+ Test whether the interface is a hub interface.
+
+ @param UsbIf The interface to test.
+
+ @retval TRUE The interface is a hub interface.
+ @retval FALSE The interface isn't a hub interface.
+
+**/
BOOLEAN
UsbIsHubInterface (
IN USB_INTERFACE *UsbIf
);
+
+/**
+ Ack the hub change bits. If these bits are not ACKed, Hub will
+ always return changed bit map from its interrupt endpoint.
+
+ @param UsbDev The Usb device.
+
+ @retval EFI_SUCCESS The hub change status is ACKed.
+ @retval Others Failed to ACK the hub status.
+
+**/
EFI_STATUS
UsbHubAckHubStatus (
IN USB_DEVICE *UsbDev
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.c b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.c index e7a0c28412..c9d4f7030c 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.c +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.c @@ -1,5 +1,7 @@ /** @file
+ Wrapper function for usb host controller interface.
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,17 +11,6 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbUtility.c
-
- Abstract:
-
- Wrapper function for usb host controller interface
-
- Revision History
-
-
**/
@@ -59,14 +50,14 @@ STATIC USB_CLASS_FORMAT_DEVICE_PATH mAllUsbClassDevicePath = { /**
- Get the capability of the host controller
+ Get the capability of the host controller.
- @param UsbBus The usb driver
- @param MaxSpeed The maximum speed this host controller supports
- @param NumOfPort The number of the root hub port
- @param Is64BitCapable Whether this controller support 64 bit addressing
+ @param UsbBus The usb driver.
+ @param MaxSpeed The maximum speed this host controller supports.
+ @param NumOfPort The number of the root hub port.
+ @param Is64BitCapable Whether this controller support 64 bit addressing.
- @retval EFI_SUCCESS The host controller capability is returned
+ @retval EFI_SUCCESS The host controller capability is returned.
@retval Others Failed to retrieve the host controller capability.
**/
@@ -100,13 +91,16 @@ UsbHcGetCapability ( /**
- Reset the host controller
-
- @param UsbBus The usb bus driver
- @param Attributes The reset type, only global reset is used by this driver
+ Reset the host controller.
- @return GC_TODO: add return values
+ @param UsbBus The usb bus driver.
+ @param Attributes The reset type, only global reset is used by this driver.
+ @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.
**/
EFI_STATUS
UsbHcReset (
@@ -127,13 +121,13 @@ UsbHcReset ( /**
- Get the current operation state of the host controller
+ Get the current operation state of the host controller.
- @param UsbBus The USB bus driver
- @param State The host controller operation state
+ @param UsbBus The USB bus driver.
+ @param State The host controller operation state.
- @retval EFI_SUCCESS The operation state is returned in State
- @retval Others Failed to get the host controller state
+ @retval EFI_SUCCESS The operation state is returned in State.
+ @retval Others Failed to get the host controller state.
**/
EFI_STATUS
@@ -155,13 +149,13 @@ UsbHcGetState ( /**
- Set the host controller operation state
+ Set the host controller operation state.
- @param UsbBus The USB bus driver
- @param State The state to set
+ @param UsbBus The USB bus driver.
+ @param State The state to set.
- @retval EFI_SUCCESS The host controller is now working at State
- @retval Others Failed to set operation state
+ @retval EFI_SUCCESS The host controller is now working at State.
+ @retval Others Failed to set operation state.
**/
EFI_STATUS
@@ -183,14 +177,14 @@ UsbHcSetState ( /**
- Get the root hub port state
+ Get the root hub port state.
- @param UsbBus The USB bus driver
- @param PortIndex The index of port
- @param PortStatus The variable to save port state
+ @param UsbBus The USB bus driver.
+ @param PortIndex The index of port.
+ @param PortStatus The variable to save port state.
- @retval EFI_SUCCESS The root port state is returned in
- @retval Others Failed to get the root hub port state
+ @retval EFI_SUCCESS The root port state is returned in.
+ @retval Others Failed to get the root hub port state.
**/
EFI_STATUS
@@ -213,14 +207,14 @@ UsbHcGetRootHubPortStatus ( /**
- Set the root hub port feature
+ Set the root hub port feature.
- @param UsbBus The USB bus driver
- @param PortIndex The port index
- @param Feature The port feature to set
+ @param UsbBus The USB bus driver.
+ @param PortIndex The port index.
+ @param Feature The port feature to set.
- @retval EFI_SUCCESS The port feature is set
- @retval Others Failed to set port feature
+ @retval EFI_SUCCESS The port feature is set.
+ @retval Others Failed to set port feature.
**/
EFI_STATUS
@@ -244,14 +238,14 @@ UsbHcSetRootHubPortFeature ( /**
- Clear the root hub port feature
+ Clear the root hub port feature.
- @param UsbBus The USB bus driver
- @param PortIndex The port index
- @param Feature The port feature to clear
+ @param UsbBus The USB bus driver.
+ @param PortIndex The port index.
+ @param Feature The port feature to clear.
- @retval EFI_SUCCESS The port feature is clear
- @retval Others Failed to clear port feature
+ @retval EFI_SUCCESS The port feature is clear.
+ @retval Others Failed to clear port feature.
**/
EFI_STATUS
@@ -274,22 +268,22 @@ UsbHcClearRootHubPortFeature ( /**
- Execute a control transfer to the device
-
- @param UsbBus The USB bus driver
- @param DevAddr The device address
- @param DevSpeed The device speed
- @param MaxPacket Maximum packet size of endpoint 0
- @param Request The control transfer request
- @param Direction The direction of data stage
- @param Data The buffer holding data
- @param DataLength The length of the data
- @param TimeOut Timeout (in ms) to wait until timeout
- @param Translator The transaction translator for low/full speed device
- @param UsbResult The result of transfer
-
- @retval EFI_SUCCESS The control transfer finished without error
- @retval Others The control transfer failed, reason returned in UsbReslt
+ Execute a control transfer to the device.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The device address.
+ @param DevSpeed The device speed.
+ @param MaxPacket Maximum packet size of endpoint 0.
+ @param Request The control transfer request.
+ @param Direction The direction of data stage.
+ @param Data The buffer holding data.
+ @param DataLength The length of the data.
+ @param TimeOut Timeout (in ms) to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of transfer.
+
+ @retval EFI_SUCCESS The control transfer finished without error.
+ @retval Others The control transfer failed, reason returned in UsbReslt.
**/
EFI_STATUS
@@ -346,25 +340,25 @@ UsbHcControlTransfer ( /**
- Execute a bulk transfer to the device's endpoint
+ Execute a bulk transfer to the device's endpoint.
- @param UsbBus The USB bus driver
- @param DevAddr The target device address
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
@param EpAddr The target endpoint address, with direction encoded in
- bit 7
- @param DevSpeed The device's speed
- @param MaxPacket The endpoint's max packet size
- @param BufferNum The number of data buffer
- @param Data Array of pointers to data buffer
- @param DataLength The length of data buffer
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
@param DataToggle On input, the initial data toggle to use, also return
the next toggle on output.
- @param TimeOut The time to wait until timeout
- @param Translator The transaction translator for low/full speed device
- @param UsbResult The result of USB execution
+ @param TimeOut The time to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
- @retval EFI_SUCCESS The bulk transfer is finished without error
- @retval Others Failed to execute bulk transfer, result in UsbResult
+ @retval EFI_SUCCESS The bulk transfer is finished without error.
+ @retval Others Failed to execute bulk transfer, result in UsbResult.
**/
EFI_STATUS
@@ -419,25 +413,25 @@ UsbHcBulkTransfer ( /**
- Queue or cancel an asynchronous interrupt transfer
+ Queue or cancel an asynchronous interrupt transfer.
- @param UsbBus The USB bus driver
- @param DevAddr The target device address
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
@param EpAddr The target endpoint address, with direction encoded in
- bit 7
- @param DevSpeed The device's speed
- @param MaxPacket The endpoint's max packet size
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
@param IsNewTransfer Whether this is a new request. If not, cancel the old
- request
- @param DataToggle Data toggle to use on input, next toggle on output
- @param PollingInterval The interval to poll the interrupt transfer (in ms)
- @param DataLength The length of periodical data receive
- @param Translator The transaction translator for low/full speed device
- @param Callback Function to call when data is received
- @param Context The context to the callback
+ request.
+ @param DataToggle Data toggle to use on input, next toggle on output.
+ @param PollingInterval The interval to poll the interrupt transfer (in ms).
+ @param DataLength The length of periodical data receive.
+ @param Translator The transaction translator for low/full speed device.
+ @param Callback Function to call when data is received.
+ @param Context The context to the callback.
- @retval EFI_SUCCESS The asynchronous transfer is queued
- @retval Others Failed to queue the transfer
+ @retval EFI_SUCCESS The asynchronous transfer is queued.
+ @retval Others Failed to queue the transfer.
**/
EFI_STATUS
@@ -497,24 +491,24 @@ UsbHcAsyncInterruptTransfer ( /**
- Execute a synchronous interrupt transfer to the target endpoint
+ Execute a synchronous interrupt transfer to the target endpoint.
- @param UsbBus The USB bus driver
- @param DevAddr The target device address
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
@param EpAddr The target endpoint address, with direction encoded in
- bit 7
- @param DevSpeed The device's speed
- @param MaxPacket The endpoint's max packet size
- @param Data Pointer to data buffer
- @param DataLength The length of data buffer
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param Data Pointer to data buffer.
+ @param DataLength The length of data buffer.
@param DataToggle On input, the initial data toggle to use, also return
the next toggle on output.
- @param TimeOut The time to wait until timeout
- @param Translator The transaction translator for low/full speed device
- @param UsbResult The result of USB execution
+ @param TimeOut The time to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
- @retval EFI_SUCCESS The synchronous interrupt transfer is OK
- @retval Others Failed to execute the synchronous interrupt transfer
+ @retval EFI_SUCCESS The synchronous interrupt transfer is OK.
+ @retval Others Failed to execute the synchronous interrupt transfer.
**/
EFI_STATUS
@@ -570,21 +564,21 @@ UsbHcSyncInterruptTransfer ( /**
- Execute a synchronous Isochronous USB transfer
+ Execute a synchronous Isochronous USB transfer.
- @param UsbBus The USB bus driver
- @param DevAddr The target device address
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
@param EpAddr The target endpoint address, with direction encoded in
- bit 7
- @param DevSpeed The device's speed
- @param MaxPacket The endpoint's max packet size
- @param BufferNum The number of data buffer
- @param Data Array of pointers to data buffer
- @param DataLength The length of data buffer
- @param Translator The transaction translator for low/full speed device
- @param UsbResult The result of USB execution
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
- @retval EFI_UNSUPPORTED The isochronous transfer isn't supported now
+ @retval EFI_UNSUPPORTED The isochronous transfer isn't supported now.
**/
EFI_STATUS
@@ -606,22 +600,22 @@ UsbHcIsochronousTransfer ( /**
- Queue an asynchronous isochronous transfer
+ Queue an asynchronous isochronous transfer.
- @param UsbBus The USB bus driver
- @param DevAddr The target device address
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
@param EpAddr The target endpoint address, with direction encoded in
- bit 7
- @param DevSpeed The device's speed
- @param MaxPacket The endpoint's max packet size
- @param BufferNum The number of data buffer
- @param Data Array of pointers to data buffer
- @param DataLength The length of data buffer
- @param Translator The transaction translator for low/full speed device
- @param Callback The function to call when data is transferred
- @param Context The context to the callback function
-
- @retval EFI_UNSUPPORTED The asynchronous isochronous transfer isn't supported
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
+ @param Translator The transaction translator for low/full speed device.
+ @param Callback The function to call when data is transferred.
+ @param Context The context to the callback function.
+
+ @retval EFI_UNSUPPORTED The asynchronous isochronous transfer isn't supported.
**/
EFI_STATUS
@@ -644,12 +638,12 @@ UsbHcAsyncIsochronousTransfer ( /**
- Open the USB host controller protocol BY_CHILD
+ Open the USB host controller protocol BY_CHILD.
- @param Bus The USB bus driver
- @param Child The child handle
+ @param Bus The USB bus driver.
+ @param Child The child handle.
- @return The open protocol return
+ @return The open protocol return.
**/
EFI_STATUS
@@ -688,12 +682,12 @@ UsbOpenHostProtoByChild ( /**
- Close the USB host controller protocol BY_CHILD
+ Close the USB host controller protocol BY_CHILD.
- @param Bus The USB bus driver
- @param Child The child handle
+ @param Bus The USB bus driver.
+ @param Child The child handle.
- @return None
+ @return None.
**/
VOID
@@ -721,13 +715,12 @@ UsbCloseHostProtoByChild ( }
-
/**
return the current TPL, copied from the EDKII glue lib.
- VOID
+ @param VOID.
- @return Current TPL
+ @return Current TPL.
**/
EFI_TPL
@@ -744,11 +737,11 @@ UsbGetCurrentTpl ( }
/**
- Create a new device path which only contain the first Usb part of the DevicePath
+ Create a new device path which only contain the first Usb part of the DevicePath.
- @param DevicePath A full device path which contain the usb nodes
+ @param DevicePath A full device path which contain the usb nodes.
- @return A new device path which only contain the Usb part of the DevicePath
+ @return A new device path which only contain the Usb part of the DevicePath.
**/
EFI_DEVICE_PATH_PROTOCOL *
@@ -816,11 +809,11 @@ GetUsbDPFromFullDP ( /**
Check whether a usb device path is in a DEVICE_PATH_LIST_ITEM list.
- @param UsbDP a usb device path of DEVICE_PATH_LIST_ITEM
- @parem UsbIoDPList a DEVICE_PATH_LIST_ITEM list
+ @param UsbDP a usb device path of DEVICE_PATH_LIST_ITEM.
+ @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list.
- @retval TRUE there is a DEVICE_PATH_LIST_ITEM in UsbIoDPList which contains the passed in UsbDP
- @retval FALSE there is no DEVICE_PATH_LIST_ITEM in UsbIoDPList which contains the passed in UsbDP
+ @retval TRUE there is a DEVICE_PATH_LIST_ITEM in UsbIoDPList which contains the passed in UsbDP.
+ @retval FALSE there is no DEVICE_PATH_LIST_ITEM in UsbIoDPList which contains the passed in UsbDP.
**/
BOOLEAN
@@ -867,11 +860,11 @@ SearchUsbDPInList ( /**
Add a usb device path into the DEVICE_PATH_LIST_ITEM list.
- @param UsbDP a usb device path of DEVICE_PATH_LIST_ITEM
- @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list
+ @param UsbDP a usb device path of DEVICE_PATH_LIST_ITEM.
+ @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list.
- @retval EFI_INVALID_PARAMETER
- @retval EFI_SUCCESS
+ @retval EFI_INVALID_PARAMETER If parameters are invalid, return this value.
+ @retval EFI_SUCCESS If Add operation is successful, return this value.
**/
EFI_STATUS
@@ -909,13 +902,13 @@ AddUsbDPToList ( /**
Check whether usb device, whose interface is UsbIf, matches the usb class which indicated by
- UsbClassDevicePathPtr whose is a short form usb class device path
+ UsbClassDevicePathPtr whose is a short form usb class device path.
- @param UsbClassDevicePathPtr a short form usb class device path
- @param UsbIf a usb device interface
+ @param UsbClassDevicePathPtr a short form usb class device path.
+ @param UsbIf a usb device interface.
- @retval TRUE the usb device match the usb class
- @retval FALSE the usb device does not match the usb class
+ @retval TRUE the usb device match the usb class.
+ @retval FALSE the usb device does not match the usb class.
**/
BOOLEAN
@@ -989,16 +982,15 @@ MatchUsbClass ( /**
Check whether usb device, whose interface is UsbIf, matches the usb WWID requirement which indicated by
- UsbWWIDDevicePathPtr whose is a short form usb WWID device path
+ UsbWWIDDevicePathPtr whose is a short form usb WWID device path.
- @param UsbClassDevicePathPtr a short form usb WWID device path
- @param UsbIf a usb device interface
+ @param UsbWWIDDevicePathPtr a short form usb WWID device path.
+ @param UsbIf a usb device interface.
- @retval TRUE the usb device match the usb WWID requirement
- @retval FALSE the usb device does not match the usb WWID requirement
+ @retval TRUE the usb device match the usb WWID requirement.
+ @retval FALSE the usb device does not match the usb WWID requirement.
**/
-STATIC
BOOLEAN
MatchUsbWwid (
IN USB_WWID_DEVICE_PATH *UsbWWIDDevicePathPtr,
@@ -1047,12 +1039,12 @@ MatchUsbWwid ( }
/**
- Free a DEVICE_PATH_LIST_ITEM list
+ Free a DEVICE_PATH_LIST_ITEM list.
- @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list pointer
+ @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list pointer.
- @retval EFI_INVALID_PARAMETER
- @retval EFI_SUCCESS
+ @retval EFI_INVALID_PARAMETER If parameters are invalid, return this value.
+ @retval EFI_SUCCESS If free operation is successful, return this value.
**/
EFI_STATUS
@@ -1094,14 +1086,13 @@ UsbBusFreeUsbDPList ( /**
Store a wanted usb child device info (its Usb part of device path) which is indicated by
- RemainingDevicePath in a Usb bus which is indicated by UsbBusId
+ RemainingDevicePath in a Usb bus which is indicated by UsbBusId.
- @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface
- @param RemainingDevicePath The remaining device patch
+ @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
+ @param RemainingDevicePath The remaining device patch.
- @retval EFI_SUCCESS
- @retval EFI_INVALID_PARAMETER
- @retval EFI_OUT_OF_RESOURCES
+ @retval EFI_SUCCESS Add operation is successful.
+ @retval EFI_INVALID_PARAMETER The parameters are invalid.
**/
EFI_STATUS
@@ -1158,14 +1149,13 @@ UsbBusAddWantedUsbIoDP ( }
/**
- Check whether a usb child device is the wanted device in a bus
+ Check whether a usb child device is the wanted device in a bus.
- @param Bus The Usb bus's private data pointer
- @param UsbIf The usb child device inferface
+ @param Bus The Usb bus's private data pointer.
+ @param UsbIf The usb child device inferface.
- @retval EFI_SUCCESS
- @retval EFI_INVALID_PARAMETER
- @retval EFI_OUT_OF_RESOURCES
+ @retval True If a usb child device is the wanted device in a bus.
+ @retval False If a usb child device is *NOT* the wanted device in a bus.
**/
BOOLEAN
@@ -1265,13 +1255,12 @@ UsbBusIsWantedUsbIO ( /**
Recursively connnect every wanted usb child device to ensure they all fully connected.
- Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device
+ Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.
- @param UsbBusId point to EFI_USB_BUS_PROTOCOL interface
+ @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
- @retval EFI_SUCCESS
- @retval EFI_INVALID_PARAMETER
- @retval EFI_OUT_OF_RESOURCES
+ @retval EFI_SUCCESS Connect is done successfully.
+ @retval EFI_INVALID_PARAMETER The parameter is invalid.
**/
EFI_STATUS
diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h index ee44c6acd0..23cf700bf3 100644 --- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h +++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h @@ -1,5 +1,7 @@ /** @file
+ Manage Usb Port/Hc/Etc.
+
Copyright (c) 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
@@ -9,22 +11,23 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
- Module Name:
-
- UsbUtility.h
+**/
- Abstract:
+#ifndef _EFI_USB_UTILITY_H_
+#define _EFI_USB_UTILITY_H_
- Manage Usb Port/Hc/Etc
+/**
+ Get the capability of the host controller.
- Revision History
+ @param UsbBus The usb driver.
+ @param MaxSpeed The maximum speed this host controller supports.
+ @param NumOfPort The number of the root hub port.
+ @param Is64BitCapable Whether this controller support 64 bit addressing.
+ @retval EFI_SUCCESS The host controller capability is returned.
+ @retval Others Failed to retrieve the host controller capability.
**/
-
-#ifndef _USB_UTILITY_H
-#define _USB_UTILITY_H
-
EFI_STATUS
UsbHcGetCapability (
IN USB_BUS *UsbBus,
@@ -33,27 +36,67 @@ UsbHcGetCapability ( OUT UINT8 *Is64BitCapable
);
+/**
+ Reset the host controller.
+
+ @param UsbBus The usb bus driver.
+ @param Attributes The reset type, only global reset is used by this driver.
+
+ @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.
+**/
EFI_STATUS
UsbHcReset (
IN USB_BUS *UsbBus,
IN UINT16 Attributes
);
+/**
+ Get the current operation state of the host controller.
+
+ @param UsbBus The USB bus driver.
+ @param State The host controller operation state.
+
+ @retval EFI_SUCCESS The operation state is returned in State.
+ @retval Others Failed to get the host controller state.
+**/
EFI_STATUS
UsbHcGetState (
IN USB_BUS *UsbBus,
OUT EFI_USB_HC_STATE *State
);
+/**
+ Set the host controller operation state.
+
+ @param UsbBus The USB bus driver.
+ @param State The state to set.
+
+ @retval EFI_SUCCESS The host controller is now working at State.
+ @retval Others Failed to set operation state.
+**/
EFI_STATUS
UsbHcSetState (
IN USB_BUS *UsbBus,
IN EFI_USB_HC_STATE State
);
+/**
+ Get the root hub port state.
+
+ @param UsbBus The USB bus driver.
+ @param PortIndex The index of port.
+ @param PortStatus The variable to save port state.
+ @retval EFI_SUCCESS The root port state is returned in.
+ @retval Others Failed to get the root hub port state.
+
+**/
EFI_STATUS
UsbHcGetRootHubPortStatus (
IN USB_BUS *UsbBus,
@@ -61,7 +104,17 @@ UsbHcGetRootHubPortStatus ( OUT EFI_USB_PORT_STATUS *PortStatus
);
+/**
+ Set the root hub port feature.
+ @param UsbBus The USB bus driver.
+ @param PortIndex The port index.
+ @param Feature The port feature to set.
+
+ @retval EFI_SUCCESS The port feature is set.
+ @retval Others Failed to set port feature.
+
+**/
EFI_STATUS
UsbHcSetRootHubPortFeature (
IN USB_BUS *UsbBus,
@@ -69,7 +122,17 @@ UsbHcSetRootHubPortFeature ( IN EFI_USB_PORT_FEATURE Feature
);
+/**
+ Clear the root hub port feature.
+ @param UsbBus The USB bus driver.
+ @param PortIndex The port index.
+ @param Feature The port feature to clear.
+
+ @retval EFI_SUCCESS The port feature is clear.
+ @retval Others Failed to clear port feature.
+
+**/
EFI_STATUS
UsbHcClearRootHubPortFeature (
IN USB_BUS *UsbBus,
@@ -77,7 +140,25 @@ UsbHcClearRootHubPortFeature ( IN EFI_USB_PORT_FEATURE Feature
);
+/**
+ Execute a control transfer to the device.
+ @param UsbBus The USB bus driver.
+ @param DevAddr The device address.
+ @param DevSpeed The device speed.
+ @param MaxPacket Maximum packet size of endpoint 0.
+ @param Request The control transfer request.
+ @param Direction The direction of data stage.
+ @param Data The buffer holding data.
+ @param DataLength The length of the data.
+ @param TimeOut Timeout (in ms) to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of transfer.
+
+ @retval EFI_SUCCESS The control transfer finished without error.
+ @retval Others The control transfer failed, reason returned in UsbReslt.
+
+**/
EFI_STATUS
UsbHcControlTransfer (
IN USB_BUS *UsbBus,
@@ -93,7 +174,28 @@ UsbHcControlTransfer ( OUT UINT32 *UsbResult
);
+/**
+ Execute a bulk transfer to the device's endpoint.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
+ @param EpAddr The target endpoint address, with direction encoded in
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
+ @param DataToggle On input, the initial data toggle to use, also return
+ the next toggle on output.
+ @param TimeOut The time to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
+
+ @retval EFI_SUCCESS The bulk transfer is finished without error.
+ @retval Others Failed to execute bulk transfer, result in UsbResult.
+**/
EFI_STATUS
UsbHcBulkTransfer (
IN USB_BUS *UsbBus,
@@ -110,7 +212,28 @@ UsbHcBulkTransfer ( OUT UINT32 *UsbResult
);
+/**
+ Queue or cancel an asynchronous interrupt transfer.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
+ @param EpAddr The target endpoint address, with direction encoded in
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param IsNewTransfer Whether this is a new request. If not, cancel the old
+ request.
+ @param DataToggle Data toggle to use on input, next toggle on output.
+ @param PollingInterval The interval to poll the interrupt transfer (in ms).
+ @param DataLength The length of periodical data receive.
+ @param Translator The transaction translator for low/full speed device.
+ @param Callback Function to call when data is received.
+ @param Context The context to the callback.
+
+ @retval EFI_SUCCESS The asynchronous transfer is queued.
+ @retval Others Failed to queue the transfer.
+**/
EFI_STATUS
UsbHcAsyncInterruptTransfer (
IN USB_BUS *UsbBus,
@@ -127,7 +250,27 @@ UsbHcAsyncInterruptTransfer ( IN VOID *Context OPTIONAL
);
+/**
+ Execute a synchronous interrupt transfer to the target endpoint.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
+ @param EpAddr The target endpoint address, with direction encoded in
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param Data Pointer to data buffer.
+ @param DataLength The length of data buffer.
+ @param DataToggle On input, the initial data toggle to use, also return
+ the next toggle on output.
+ @param TimeOut The time to wait until timeout.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
+
+ @retval EFI_SUCCESS The synchronous interrupt transfer is OK.
+ @retval Others Failed to execute the synchronous interrupt transfer.
+**/
EFI_STATUS
UsbHcSyncInterruptTransfer (
IN USB_BUS *UsbBus,
@@ -143,7 +286,24 @@ UsbHcSyncInterruptTransfer ( OUT UINT32 *UsbResult
);
+/**
+ Execute a synchronous Isochronous USB transfer.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
+ @param EpAddr The target endpoint address, with direction encoded in
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
+ @param Translator The transaction translator for low/full speed device.
+ @param UsbResult The result of USB execution.
+ @retval EFI_UNSUPPORTED The isochronous transfer isn't supported now.
+
+**/
EFI_STATUS
UsbHcIsochronousTransfer (
IN USB_BUS *UsbBus,
@@ -158,7 +318,25 @@ UsbHcIsochronousTransfer ( OUT UINT32 *UsbResult
);
+/**
+ Queue an asynchronous isochronous transfer.
+
+ @param UsbBus The USB bus driver.
+ @param DevAddr The target device address.
+ @param EpAddr The target endpoint address, with direction encoded in
+ bit 7.
+ @param DevSpeed The device's speed.
+ @param MaxPacket The endpoint's max packet size.
+ @param BufferNum The number of data buffer.
+ @param Data Array of pointers to data buffer.
+ @param DataLength The length of data buffer.
+ @param Translator The transaction translator for low/full speed device.
+ @param Callback The function to call when data is transferred.
+ @param Context The context to the callback function.
+ @retval EFI_UNSUPPORTED The asynchronous isochronous transfer isn't supported.
+
+**/
EFI_STATUS
UsbHcAsyncIsochronousTransfer (
IN USB_BUS *UsbBus,
@@ -174,37 +352,47 @@ UsbHcAsyncIsochronousTransfer ( IN VOID *Context
);
+/**
+ Open the USB host controller protocol BY_CHILD.
+
+ @param Bus The USB bus driver.
+ @param Child The child handle.
+ @return The open protocol return.
+
+**/
EFI_STATUS
UsbOpenHostProtoByChild (
IN USB_BUS *Bus,
IN EFI_HANDLE Child
);
+/**
+ Close the USB host controller protocol BY_CHILD.
+
+ @param Bus The USB bus driver.
+ @param Child The child handle.
+ @return None.
+
+**/
VOID
UsbCloseHostProtoByChild (
IN USB_BUS *Bus,
IN EFI_HANDLE Child
);
+/**
+ return the current TPL, copied from the EDKII glue lib.
+
+ @param VOID.
+ @return Current TPL.
+
+**/
EFI_TPL
UsbGetCurrentTpl (
VOID
);
-
-VOID
-UsbDebug (
- IN CHAR8 *Format,
- ...
- );
-
-
-VOID
-UsbError (
- IN CHAR8 *Format,
- ...
- );
#endif
|