From 78c2ffb5a7172b9c5fbef15b5edc7aae3de5d4f2 Mon Sep 17 00:00:00 2001 From: eric_tian Date: Tue, 8 Jul 2008 10:26:16 +0000 Subject: [PATCH] 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@5427 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Bus/Pci/EhciDxe/ComponentName.c | 8 +- MdeModulePkg/Bus/Pci/EhciDxe/Ehci.c | 391 +++++++++---------- MdeModulePkg/Bus/Pci/EhciDxe/Ehci.h | 22 +- MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.c | 41 +- MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.h | 26 +- MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.c | 195 +++++---- MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.h | 134 +++---- MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.c | 149 +++---- MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.h | 109 +++--- MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.c | 119 +++--- MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h | 84 ++-- MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.c | 103 +++-- MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.h | 75 ++-- 13 files changed, 638 insertions(+), 818 deletions(-) diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/ComponentName.c b/MdeModulePkg/Bus/Pci/EhciDxe/ComponentName.c index 660dd5500c..84532ef1bd 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/ComponentName.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/ComponentName.c @@ -1,4 +1,5 @@ /** @file + UEFI Component Name(2) protocol implementation for EHCI driver. Copyright (c) 2006 - 2007, Intel Corporation @@ -11,13 +12,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: - - **/ #include "Ehci.h" diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.c b/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.c index f72ba55127..9dccd6f00d 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.c @@ -1,4 +1,6 @@ /** @file + + The Ehci controller driver. Copyright (c) 2006 - 2008, Intel Corporation All rights reserved. This program and the accompanying materials @@ -9,15 +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: - - Ehci.c - -Abstract: - - -Revision History - **/ @@ -47,17 +40,16 @@ USB_PORT_STATE_MAP mUsbPortChangeMap[] = { /** Retrieves the capablility of root hub ports. - @param This This EFI_USB_HC_PROTOCOL instance. - @param MaxSpeed Max speed supported by the controller - @param PortNumber Number of the root hub ports. - @param Is64BitCapable Whether the controller supports 64-bit memory - addressing. + @param This This EFI_USB_HC_PROTOCOL instance. + @param MaxSpeed Max speed supported by the controller. + @param PortNumber Number of the root hub ports. + @param Is64BitCapable Whether the controller supports 64-bit memory + addressing. - @return EFI_SUCCESS : host controller capability were retrieved successfully. - @return EFI_INVALID_PARAMETER : Either of the three capability pointer is NULL + @retval EFI_SUCCESS Host controller capability were retrieved successfully. + @retval EFI_INVALID_PARAMETER Either of the three capability pointer is NULL. **/ -STATIC EFI_STATUS EFIAPI EhcGetCapability ( @@ -91,17 +83,16 @@ EhcGetCapability ( /** Provides software reset for the USB host controller. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param Attributes A bit mask of the reset operation to perform. + @param This This EFI_USB2_HC_PROTOCOL instance. + @param Attributes A bit mask of the reset operation to perform. - @return EFI_SUCCESS : The reset operation succeeded. - @return EFI_INVALID_PARAMETER : Attributes is not valid. - @return EFI_UNSUPPOURTED : The type of reset specified by Attributes is - @return not currently supported by the host controller. - @return EFI_DEVICE_ERROR : Host controller isn't halted to reset. + @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. **/ -STATIC EFI_STATUS EFIAPI EhcReset ( @@ -170,17 +161,16 @@ ON_EXIT: /** Retrieve the current state of the USB host controller. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param State Variable to return the current host controller - state. + @param This This EFI_USB2_HC_PROTOCOL instance. + @param State Variable to return the current host controller + state. - @return EFI_SUCCESS : Host controller state was returned in State. - @return EFI_INVALID_PARAMETER : State is NULL. - @return EFI_DEVICE_ERROR : An error was encountered while attempting to - @return retrieve the host controller's current state. + @retval EFI_SUCCESS Host controller state was returned in State. + @retval EFI_INVALID_PARAMETER State is NULL. + @retval EFI_DEVICE_ERROR An error was encountered while attempting to + retrieve the host controller's current state. **/ -STATIC EFI_STATUS EFIAPI EhcGetState ( @@ -214,16 +204,15 @@ EhcGetState ( /** Sets the USB host controller to a specific state. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param State The state of the host controller that will be set. + @param This This EFI_USB2_HC_PROTOCOL instance. + @param State The state of the host controller that will be set. - @return EFI_SUCCESS : The USB host controller was successfully placed - @return in the state specified by State. - @return EFI_INVALID_PARAMETER : State is invalid. - @return EFI_DEVICE_ERROR : Failed to set the state due to device error. + @retval EFI_SUCCESS The USB host controller was successfully placed + in the state specified by State. + @retval EFI_INVALID_PARAMETER State is invalid. + @retval EFI_DEVICE_ERROR Failed to set the state due to device error. **/ -STATIC EFI_STATUS EFIAPI EhcSetState ( @@ -290,18 +279,17 @@ EhcSetState ( /** Retrieves the current status of a USB root hub port. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param PortNumber The root hub port to retrieve the state from. This - value is zero-based. - @param PortStatus Variable to receive the port state + @param This This EFI_USB2_HC_PROTOCOL instance. + @param PortNumber The root hub port to retrieve the state from. + This value is zero-based. + @param PortStatus Variable to receive the port state. - @return EFI_SUCCESS : The status of the USB root hub port specified - @return by PortNumber was returned in PortStatus. - @return EFI_INVALID_PARAMETER : PortNumber is invalid. - @return EFI_DEVICE_ERROR : Can't read register + @retval EFI_SUCCESS The status of the USB root hub port specified. + by PortNumber was returned in PortStatus. + @retval EFI_INVALID_PARAMETER PortNumber is invalid. + @retval EFI_DEVICE_ERROR Can't read register. **/ -STATIC EFI_STATUS EFIAPI EhcGetRootHubPortStatus ( @@ -382,16 +370,15 @@ ON_EXIT: /** Sets a feature for the specified root hub port. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param PortNumber Root hub port to set. - @param PortFeature Feature to set + @param This This EFI_USB2_HC_PROTOCOL instance. + @param PortNumber Root hub port to set. + @param PortFeature Feature to set. - @return EFI_SUCCESS : The feature specified by PortFeature was set - @return EFI_INVALID_PARAMETER : PortNumber is invalid or PortFeature is invalid. - @return EFI_DEVICE_ERROR : Can't read register + @retval EFI_SUCCESS The feature specified by PortFeature was set. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid. + @retval EFI_DEVICE_ERROR Can't read register. **/ -STATIC EFI_STATUS EFIAPI EhcSetRootHubPortFeature ( @@ -490,19 +477,18 @@ ON_EXIT: /** Clears a feature for the specified root hub port. - @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. - @param PortNumber Specifies the root hub port whose feature is - requested to be cleared. - @param PortFeature Indicates the feature selector associated with the - feature clear request. + @param This A pointer to the EFI_USB2_HC_PROTOCOL instance. + @param PortNumber Specifies the root hub port whose feature is + requested to be cleared. + @param PortFeature Indicates the feature selector associated with the + feature clear request. - @return EFI_SUCCESS : The feature specified by PortFeature was cleared - @return for the USB root hub port specified by PortNumber. - @return EFI_INVALID_PARAMETER : PortNumber is invalid or PortFeature is invalid. - @return EFI_DEVICE_ERROR : Can't read register + @retval EFI_SUCCESS The feature specified by PortFeature was cleared + for the USB root hub port specified by PortNumber. + @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid. + @retval EFI_DEVICE_ERROR Can't read register. **/ -STATIC EFI_STATUS EFIAPI EhcClearRootHubPortFeature ( @@ -617,28 +603,27 @@ ON_EXIT: /** Submits control transfer to a target USB device. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress The target device address - @param DeviceSpeed Target device speed. - @param MaximumPacketLength Maximum packet size the default control transfer - endpoint is capable of sending or receiving. - @param Request USB device request to send - @param TransferDirection Specifies the data direction for the data stage - @param Data Data buffer to be transmitted or received from USB - device. - @param DataLength The size (in bytes) of the data buffer - @param TimeOut Indicates the maximum timeout, in millisecond, - @param Translator Transaction translator to be used by this device. - @param TransferResult Return the result of this control transfer. - - @return EFI_SUCCESS : Transfer was completed successfully. - @return EFI_OUT_OF_RESOURCES : The transfer failed due to lack of resources. - @return EFI_INVALID_PARAMETER : Some parameters are invalid. - @return EFI_TIMEOUT : Transfer failed due to timeout. - @return EFI_DEVICE_ERROR : Transfer failed due to host controller or device error. + @param This This EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress The target device address. + @param DeviceSpeed Target device speed. + @param MaximumPacketLength Maximum packet size the default control transfer + endpoint is capable of sending or receiving. + @param Request USB device request to send. + @param TransferDirection Specifies the data direction for the data stage + @param Data Data buffer to be transmitted or received from USB + device. + @param DataLength The size (in bytes) of the data buffer. + @param TimeOut Indicates the maximum timeout, in millisecond. + @param Translator Transaction translator to be used by this device. + @param TransferResult Return the result of this control transfer. + + @retval EFI_SUCCESS Transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resources. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT Transfer failed due to timeout. + @retval EFI_DEVICE_ERROR Transfer failed due to host controller or device error. **/ -STATIC EFI_STATUS EFIAPI EhcControlTransfer ( @@ -775,35 +760,33 @@ ON_EXIT: /** Submits bulk transfer to a bulk endpoint of a USB device. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress Target device address - @param EndPointAddress Endpoint number and its direction in bit 7. . - @param DeviceSpeed Device speed, Low speed device doesn't support bulk - transfer. - @param MaximumPacketLength Maximum packet size the endpoint is capable of - sending or receiving. - @param DataBuffersNumber Number of data buffers prepared for the transfer. - @param Data Array of pointers to the buffers of data to transmit + @param This This EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Target device address. + @param EndPointAddress Endpoint number and its direction in bit 7. + @param DeviceSpeed Device speed, Low speed device doesn't support bulk + transfer. + @param MaximumPacketLength Maximum packet size the endpoint is capable of + sending or receiving. + @param DataBuffersNumber Number of data buffers prepared for the transfer. + @param Data Array of pointers to the buffers of data to transmit from or receive into. - @param DataLength The lenght of the data buffer - @param DataToggle On input, the initial data toggle for the transfer; - On output, it is updated to to next data toggle to - use of the subsequent bulk - transfer. - @param Translator A pointr to the transaction translator data. - @param TimeOut Indicates the maximum time, in millisecond, which - the transfer is allowed to complete. - @param TransferResult A pointer to the detailed result information of the - bulk transfer. - - @return EFI_SUCCESS : The transfer was completed successfully. - @return EFI_OUT_OF_RESOURCES : The transfer failed due to lack of resource. - @return EFI_INVALID_PARAMETER : Some parameters are invalid. - @return EFI_TIMEOUT : The transfer failed due to timeout. - @return EFI_DEVICE_ERROR : The transfer failed due to host controller error. + @param DataLength The lenght of the data buffer. + @param DataToggle On input, the initial data toggle for the transfer; + On output, it is updated to to next data toggle to + use of the subsequent bulk transfer. + @param TimeOut Indicates the maximum time, in millisecond, which + the transfer is allowed to complete. + @param Translator A pointr to the transaction translator data. + @param TransferResult A pointer to the detailed result information of the + bulk transfer. + + @retval EFI_SUCCESS The transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The transfer failed due to host controller error. **/ -STATIC EFI_STATUS EFIAPI EhcBulkTransfer ( @@ -918,32 +901,31 @@ ON_EXIT: Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress Target device address - @param EndPointAddress Endpoint number and its direction encoded in bit 7 - @param DeviceSpeed Indicates device speed. - @param MaximumPacketLength Maximum packet size the target endpoint is capable - @param IsNewTransfer If TRUE, to submit an new asynchronous interrupt - transfer If FALSE, to remove the specified - asynchronous interrupt - @param DataToggle On input, the initial data toggle to use; on output, - it is updated to indicate the next data toggle - @param PollingInterval The he interval, in milliseconds, that the transfer - is polled. - @param DataLength The length of data to receive at the rate specified - by PollingInterval. - @param Translator Transaction translator to use. - @param CallBackFunction Function to call at the rate specified by - PollingInterval - @param Context Context to CallBackFunction. - - @return EFI_SUCCESS : The request has been successfully submitted or canceled. - @return EFI_INVALID_PARAMETER : Some parameters are invalid. - @return EFI_OUT_OF_RESOURCES : The request failed due to a lack of resources. - @return EFI_DEVICE_ERROR : The transfer failed due to host controller error. + @param This This EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Target device address. + @param EndPointAddress Endpoint number and its direction encoded in bit 7 + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Maximum packet size the target endpoint is capable + @param IsNewTransfer If TRUE, to submit an new asynchronous interrupt + transfer If FALSE, to remove the specified + asynchronous interrupt. + @param DataToggle On input, the initial data toggle to use; on output, + it is updated to indicate the next data toggle. + @param PollingInterval The he interval, in milliseconds, that the transfer + is polled. + @param DataLength The length of data to receive at the rate specified + by PollingInterval. + @param Translator Transaction translator to use. + @param CallBackFunction Function to call at the rate specified by + PollingInterval. + @param Context Context to CallBackFunction. + + @retval EFI_SUCCESS The request has been successfully submitted or canceled. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_OUT_OF_RESOURCES The request failed due to a lack of resources. + @retval EFI_DEVICE_ERROR The transfer failed due to host controller error. **/ -STATIC EFI_STATUS EFIAPI EhcAsyncInterruptTransfer ( @@ -1067,30 +1049,29 @@ ON_EXIT: Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. - @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress Target device address - @param EndPointAddress Endpoint number and its direction encoded in bit 7 - @param DeviceSpeed Indicates device speed. - @param MaximumPacketLength Maximum packet size the target endpoint is capable - of sending or receiving. - @param Data Buffer of data that will be transmitted to USB - device or received from USB device. - @param DataLength On input, the size, in bytes, of the data buffer; On - output, the number of bytes transferred. - @param DataToggle On input, the initial data toggle to use; on output, - it is updated to indicate the next data toggle - @param TimeOut Maximum time, in second, to complete - @param Translator Transaction translator to use. - @param TransferResult Variable to receive the transfer result - - @return EFI_SUCCESS : The transfer was completed successfully. - @return EFI_OUT_OF_RESOURCES : The transfer failed due to lack of resource. - @return EFI_INVALID_PARAMETER : Some parameters are invalid. - @return EFI_TIMEOUT : The transfer failed due to timeout. - @return EFI_DEVICE_ERROR : The failed due to host controller or device error + @param This This EFI_USB2_HC_PROTOCOL instance. + @param DeviceAddress Target device address. + @param EndPointAddress Endpoint number and its direction encoded in bit 7 + @param DeviceSpeed Indicates device speed. + @param MaximumPacketLength Maximum packet size the target endpoint is capable + of sending or receiving. + @param Data Buffer of data that will be transmitted to USB + device or received from USB device. + @param DataLength On input, the size, in bytes, of the data buffer; On + output, the number of bytes transferred. + @param DataToggle On input, the initial data toggle to use; on output, + it is updated to indicate the next data toggle. + @param TimeOut Maximum time, in second, to complete. + @param Translator Transaction translator to use. + @param TransferResult Variable to receive the transfer result. + + @return EFI_SUCCESS The transfer was completed successfully. + @return EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource. + @return EFI_INVALID_PARAMETER Some parameters are invalid. + @return EFI_TIMEOUT The transfer failed due to timeout. + @return EFI_DEVICE_ERROR The failed due to host controller or device error **/ -STATIC EFI_STATUS EFIAPI EhcSyncInterruptTransfer ( @@ -1201,8 +1182,8 @@ ON_EXIT: Submits isochronous transfer to a target USB device. @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress Target device address - @param EndPointAddress End point address with its direction + @param DeviceAddress Target device address. + @param EndPointAddress End point address with its direction. @param DeviceSpeed Device speed, Low speed device doesn't support this type. @param MaximumPacketLength Maximum packet size that the endpoint is capable of @@ -1211,14 +1192,13 @@ ON_EXIT: @param Data Array of pointers to the buffers of data that will be transmitted to USB device or received from USB device. - @param DataLength The size, in bytes, of the data buffer + @param DataLength The size, in bytes, of the data buffer. @param Translator Transaction translator to use. - @param TransferResult Variable to receive the transfer result + @param TransferResult Variable to receive the transfer result. - @return EFI_UNSUPPORTED : Isochronous transfer is unsupported. + @return EFI_UNSUPPORTED Isochronous transfer is unsupported. **/ -STATIC EFI_STATUS EFIAPI EhcIsochronousTransfer ( @@ -1242,8 +1222,8 @@ EhcIsochronousTransfer ( Submits Async isochronous transfer to a target USB device. @param This This EFI_USB2_HC_PROTOCOL instance. - @param DeviceAddress Target device address - @param EndPointAddress End point address with its direction + @param DeviceAddress Target device address. + @param EndPointAddress End point address with its direction. @param DeviceSpeed Device speed, Low speed device doesn't support this type. @param MaximumPacketLength Maximum packet size that the endpoint is capable of @@ -1252,16 +1232,15 @@ EhcIsochronousTransfer ( @param Data Array of pointers to the buffers of data that will be transmitted to USB device or received from USB device. - @param DataLength The size, in bytes, of the data buffer + @param DataLength The size, in bytes, of the data buffer. @param Translator Transaction translator to use. - @param IsochronousCallBack Function to be called when the transfer complete + @param IsochronousCallBack Function to be called when the transfer complete. @param Context Context passed to the call back function as - parameter + parameter. - @return EFI_UNSUPPORTED : Isochronous transfer isn't supported + @return EFI_UNSUPPORTED Isochronous transfer isn't supported. **/ -STATIC EFI_STATUS EFIAPI EhcAsyncIsochronousTransfer ( @@ -1281,29 +1260,22 @@ EhcAsyncIsochronousTransfer ( return EFI_UNSUPPORTED; } +/** + Entry point for EFI drivers. + + @param ImageHandle EFI_HANDLE. + @param SystemTable EFI_SYSTEM_TABLE. + + @return EFI_SUCCESS Success. + EFI_DEVICE_ERROR Fail. + +**/ EFI_STATUS EFIAPI EhcDriverEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: - - Entry point for EFI drivers. - -Arguments: - - ImageHandle - EFI_HANDLE - SystemTable - EFI_SYSTEM_TABLE - -Returns: - - EFI_SUCCESS Success - EFI_DEVICE_ERROR Fail - ---*/ { return EfiLibInstallDriverBindingComponentName2 ( ImageHandle, @@ -1322,11 +1294,11 @@ Returns: be supported. @param This Protocol instance pointer. - @param Controlle Handle of device to test - @param RemainingDevicePath Not used + @param Controller Handle of device to test. + @param RemainingDevicePath Not used. - @return EFI_SUCCESS : This driver supports this device. - @return EFI_UNSUPPORTED : This driver does not support this device. + @return EFI_SUCCESS This driver supports this device. + @return EFI_UNSUPPORTED This driver does not support this device. **/ EFI_STATUS @@ -1393,16 +1365,15 @@ ON_EXIT: /** - Create and initialize a USB2_HC_DEV + Create and initialize a USB2_HC_DEV. - @param PciIo The PciIo on this device - @param OriginalPciAttributes Original PCI attributes + @param PciIo The PciIo on this device. + @param OriginalPciAttributes Original PCI attributes. - @return The allocated and initialized USB2_HC_DEV structure - @return if created, otherwise NULL. + @return The allocated and initialized USB2_HC_DEV structure if created, + otherwise NULL. **/ -STATIC USB2_HC_DEV * EhcCreateUsb2Hc ( IN EFI_PCI_IO_PROTOCOL *PciIo, @@ -1471,16 +1442,16 @@ EhcCreateUsb2Hc ( /** - Starting the Usb EHCI Driver + Starting the Usb EHCI Driver. @param This Protocol instance pointer. - @param Controller Handle of device to test - @param RemainingDevicePath Not used + @param Controller Handle of device to test. + @param RemainingDevicePath Not used. - @return EFI_SUCCESS : supports this device. - @return EFI_UNSUPPORTED : do not support this device. - @return EFI_DEVICE_ERROR : cannot be started due to device Error - @return EFI_OUT_OF_RESOURCES : cannot allocate resources + @return EFI_SUCCESS supports this device. + @return EFI_UNSUPPORTED do not support this device. + @return EFI_DEVICE_ERROR cannot be started due to device Error. + @return EFI_OUT_OF_RESOURCES cannot allocate resources. **/ EFI_STATUS @@ -1668,12 +1639,12 @@ CLOSE_PCIIO: created by this driver. @param This Protocol instance pointer. - @param Controller Handle of device to stop driver on - @param NumberOfChildren Number of Children in the ChildHandleBuffer + @param Controller Handle of device to stop driver on. + @param NumberOfChildren Number of Children in the ChildHandleBuffer. @param ChildHandleBuffer List of handles for the children we need to stop. - @return EFI_SUCCESS Success - @return EFI_DEVICE_ERROR Fail + @return EFI_SUCCESS Success. + @return EFI_DEVICE_ERROR Fail. **/ EFI_STATUS @@ -1734,7 +1705,7 @@ EhcDriverBindingStop ( EhcFreeSched (Ehc); - if (Ehc->ControllerNameTable) { + if (Ehc->ControllerNameTable != NULL) { FreeUnicodeStringTable (Ehc->ControllerNameTable); } diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.h b/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.h index 94e415e2a5..ec2e913dc0 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/Ehci.h @@ -1,5 +1,7 @@ /** @file + Provides some data struct used by EHCI controller driver. + Copyright (c) 2006 - 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,15 +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: - - Ehci.h - -Abstract: - - -Revision History - **/ #ifndef _EFI_EHCI_H_ @@ -48,7 +41,7 @@ typedef struct _USB2_HC_DEV USB2_HC_DEV; #include "EhciSched.h" #include "EhciDebug.h" -enum { +typedef enum { EHC_1_MICROSECOND = 1, EHC_1_MILLISECOND = 1000 * EHC_1_MICROSECOND, EHC_1_SECOND = 1000 * EHC_1_MILLISECOND, @@ -69,16 +62,17 @@ enum { // and the unit of Async is 100us, means 50ms as interval. // EHC_SYNC_POLL_INTERVAL = 20 * EHC_1_MICROSECOND, - EHC_ASYNC_POLL_INTERVAL = 50 * 10000U, + EHC_ASYNC_POLL_INTERVAL = 50 * 10000U +} EHC_TIMEOUT_EXPERIENCE_VALUE; + // // EHC raises TPL to TPL_NOTIFY to serialize all its operations // to protect shared data structures. // - EHC_TPL = TPL_NOTIFY, +#define EHC_TPL TPL_NOTIFY - USB2_HC_DEV_SIGNATURE = EFI_SIGNATURE_32 ('e', 'h', 'c', 'i') -}; +#define USB2_HC_DEV_SIGNATURE EFI_SIGNATURE_32 ('e', 'h', 'c', 'i') // //Iterate through the doule linked list. NOT delete safe diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.c b/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.c index 25a4dbff9b..bdc8f2ff03 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.c @@ -1,5 +1,7 @@ /** @file + This file provides the information dump support for EHCI when in debug mode. + 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,30 +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: - - EhciDebug.c - -Abstract: - This file provides the information dump support for EHCI when in debug mode. - -Revision History - **/ #include "Ehci.h" /** - Dump the status byte in QTD/QH to a more friendly - format + Dump the status byte in QTD/QH to a more friendly format. - @param State The state in the QTD/QH + @param State The state in the QTD/QH. - @return None + @return None. **/ -STATIC VOID EhcDumpStatus ( IN UINT32 State @@ -75,10 +66,10 @@ EhcDumpStatus ( /** - Dump the fields of a QTD + Dump the fields of a QTD. - @param Qtd The QTD to dump - @param Msg The message to print before the dump + @param Qtd The QTD to dump. + @param Msg The message to print before the dump. @return None @@ -129,11 +120,11 @@ EhcDumpQtd ( /** - Dump the queue head + Dump the queue head. - @param Qh The queue head to dump - @param Msg The message to print before the dump - @param DumpBuf Whether to dump the memory buffer of the associated QTD + @param Qh The queue head to dump. + @param Msg The message to print before the dump. + @param DumpBuf Whether to dump the memory buffer of the associated QTD. @return None @@ -218,12 +209,12 @@ EhcDumpQh ( /** - Dump the buffer in the form of hex + Dump the buffer in the form of hex. - @param Buf The buffer to dump - @param Len The length of buffer + @param Buf The buffer to dump. + @param Len The length of buffer. - @return None + @return None. **/ VOID diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.h b/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.h index 3dd4074bd4..c07e2c248b 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciDebug.h @@ -26,12 +26,12 @@ Revision History /** - Dump the fields of a QTD + Dump the fields of a QTD. - @param Qtd The QTD to dump - @param Msg The message to print before the dump + @param Qtd The QTD to dump. + @param Msg The message to print before the dump. - @return None + @return None. **/ VOID @@ -44,13 +44,13 @@ EhcDumpQtd ( /** - Dump the queue head + Dump the queue head. - @param Qh The queue head to dump - @param Msg The message to print before the dump - @param DumpBuf Whether to dump the memory buffer of the associated QTD + @param Qh The queue head to dump. + @param Msg The message to print before the dump. + @param DumpBuf Whether to dump the memory buffer of the associated QTD. - @return None + @return None. **/ VOID @@ -64,12 +64,12 @@ EhcDumpQh ( /** - Dump the buffer in the form of hex + Dump the buffer in the form of hex. - @param Buf The buffer to dump - @param Len The length of buffer + @param Buf The buffer to dump. + @param Len The length of buffer. - @return None + @return None. **/ VOID diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.c b/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.c index b40b0115e9..87a41e1e88 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.c @@ -1,5 +1,7 @@ /** @file + The EHCI register operation routines. + 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: - - EhciReg.c - -Abstract: - - The EHCI register operation routines. - - -Revision History - **/ @@ -27,12 +18,13 @@ Revision History /** - Read EHCI capability register + Read EHCI capability register. - @param Ehc The Ehc device - @param Offset Capability register address + @param Ehc The EHCI device. + @param Offset Capability register address. - @return The register content read + @return The register content read. + @retval If err, return 0xffff. **/ UINT32 @@ -63,12 +55,13 @@ EhcReadCapRegister ( /** - Read Ehc Operation register + Read EHCI Operation register. - @param Ehc The EHCI device - @param Offset The operation register offset + @param Ehc The EHCI device. + @param Offset The operation register offset. - @return The register content read + @return The register content read. + @retval If err, return 0xffff. **/ UINT32 @@ -101,13 +94,13 @@ EhcReadOpReg ( /** - Write the data to the EHCI operation register + Write the data to the EHCI operation register. - @param Ehc The EHCI device - @param Offset EHCI operation register offset - @param Data The data to write + @param Ehc The EHCI device. + @param Offset EHCI operation register offset. + @param Data The data to write. - @return None + @return None. **/ VOID @@ -137,16 +130,15 @@ EhcWriteOpReg ( /** - Set one bit of the operational register while keeping other bits + Set one bit of the operational register while keeping other bits. - @param Ehc The EHCI device - @param Offset The offset of the operational register - @param Bit The bit mask of the register to set + @param Ehc The EHCI device. + @param Offset The offset of the operational register. + @param Bit The bit mask of the register to set. - @return None + @return None. **/ -STATIC VOID EhcSetOpRegBit ( IN USB2_HC_DEV *Ehc, @@ -163,16 +155,15 @@ EhcSetOpRegBit ( /** - Clear one bit of the operational register while keeping other bits + Clear one bit of the operational register while keeping other bits. - @param Ehc The EHCI device - @param Offset The offset of the operational register - @param Bit The bit mask of the register to clear + @param Ehc The EHCI device. + @param Offset The offset of the operational register. + @param Bit The bit mask of the register to clear. - @return None + @return None. **/ -STATIC VOID EhcClearOpRegBit ( IN USB2_HC_DEV *Ehc, @@ -190,19 +181,18 @@ EhcClearOpRegBit ( /** Wait the operation register's bit as specified by Bit - to become set (or clear) + to become set (or clear). - @param Ehc The EHCI device - @param Offset The offset of the operation register - @param Bit The bit of the register to wait for - @param WaitToSet Wait the bit to set or clear - @param Timeout The time to wait before abort (in millisecond) + @param Ehc The EHCI device. + @param Offset The offset of the operation register. + @param Bit The bit of the register to wait for. + @param WaitToSet Wait the bit to set or clear. + @param Timeout The time to wait before abort (in millisecond). - @retval EFI_SUCCESS The bit successfully changed by host controller - @retval EFI_TIMEOUT The time out occurred + @retval EFI_SUCCESS The bit successfully changed by host controller. + @retval EFI_TIMEOUT The time out occurred. **/ -STATIC EFI_STATUS EhcWaitOpRegBit ( IN USB2_HC_DEV *Ehc, @@ -228,11 +218,11 @@ EhcWaitOpRegBit ( /** Add support for UEFI Over Legacy (UoL) feature, stop - the legacy USB SMI support + the legacy USB SMI support. @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -258,7 +248,7 @@ EhcClearLegacySupport ( PciIo->Pci.Write (PciIo, EfiPciIoWidthUint32, ExtendCap, 1, &Value); TimeOut = 40; - while (TimeOut--) { + while (TimeOut-- != 0) { gBS->Stall (500); PciIo->Pci.Read (PciIo, EfiPciIoWidthUint32, ExtendCap, 1, &Value); @@ -278,11 +268,11 @@ EhcClearLegacySupport ( Set door bell and wait it to be ACKed by host controller. This function is used to synchronize with the hardware. - @param Ehc The EHCI device - @param Timeout The time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout The time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : Synchronized with the hardware - @return EFI_TIMEOUT : Time out happened while waiting door bell to set + @retval EFI_SUCCESS Synchronized with the hardware. + @retval EFI_TIMEOUT Time out happened while waiting door bell to set. **/ EFI_STATUS @@ -314,11 +304,11 @@ EhcSetAndWaitDoorBell ( /** Clear all the interrutp status bits, these bits - are Write-Clean + are Write-Clean. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -334,14 +324,13 @@ EhcAckAllInterrupt ( Enable the periodic schedule then wait EHC to actually enable it. - @param Ehc The EHCI device - @param Timeout The time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout The time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : The periodical schedule is enabled - @return EFI_TIMEOUT : Time out happened while enabling periodic schedule + @retval EFI_SUCCESS The periodical schedule is enabled. + @retval EFI_TIMEOUT Time out happened while enabling periodic schedule. **/ -STATIC EFI_STATUS EhcEnablePeriodSchd ( IN USB2_HC_DEV *Ehc, @@ -357,15 +346,14 @@ EhcEnablePeriodSchd ( } - /** - Disable periodic schedule + Disable periodic schedule. - @param Ehc The EHCI device - @param Timeout Time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout Time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : Periodic schedule is disabled. - @return EFI_DEVICE_ERROR : Fail to disable periodic schedule + @retval EFI_SUCCESS Periodic schedule is disabled. + @retval EFI_DEVICE_ERROR Fail to disable periodic schedule. **/ EFI_STATUS @@ -385,16 +373,15 @@ EhcDisablePeriodSchd ( /** - Enable asynchrounous schedule + Enable asynchrounous schedule. - @param Ehc The EHCI device - @param Timeout Time to wait before abort + @param Ehc The EHCI device. + @param Timeout Time to wait before abort. - @return EFI_SUCCESS : The EHCI asynchronous schedule is enabled - @return Others : Failed to enable the asynchronous scheudle + @retval EFI_SUCCESS The EHCI asynchronous schedule is enabled. + @return Others Failed to enable the asynchronous scheudle. **/ -STATIC EFI_STATUS EhcEnableAsyncSchd ( IN USB2_HC_DEV *Ehc, @@ -412,13 +399,13 @@ EhcEnableAsyncSchd ( /** - Disable asynchrounous schedule + Disable asynchrounous schedule. - @param Ehc The EHCI device - @param Timeout Time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout Time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : The asynchronous schedule is disabled - @return Others : Failed to disable the asynchronous schedule + @retval EFI_SUCCESS The asynchronous schedule is disabled. + @return Others Failed to disable the asynchronous schedule. **/ EFI_STATUS @@ -438,12 +425,12 @@ EhcDisableAsyncSchd ( /** - Whether Ehc is halted + Whether Ehc is halted. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return TRUE : The controller is halted - @return FALSE : It isn't halted + @retval TRUE The controller is halted. + @retval FALSE It isn't halted. **/ BOOLEAN @@ -456,12 +443,12 @@ EhcIsHalt ( /** - Whether system error occurred + Whether system error occurred. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return TRUE : System error happened - @return FALSE : No system error + @return TRUE System error happened. + @return FALSE No system error. **/ BOOLEAN @@ -474,13 +461,13 @@ EhcIsSysError ( /** - Reset the host controller + Reset the host controller. - @param Ehc The EHCI device - @param Timeout Time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout Time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : The host controller is reset - @return Others : Failed to reset the host + @retval EFI_SUCCESS The host controller is reset. + @return Others Failed to reset the host. **/ EFI_STATUS @@ -509,13 +496,13 @@ EhcResetHC ( /** - Halt the host controller + Halt the host controller. - @param Ehc The EHCI device - @param Timeout Time to wait before abort + @param Ehc The EHCI device. + @param Timeout Time to wait before abort. - @return EFI_SUCCESS : The EHCI is halt - @return EFI_TIMEOUT : Failed to halt the controller before Timeout + @retval EFI_SUCCESS The EHCI is halt. + @retval EFI_TIMEOUT Failed to halt the controller before Timeout. **/ EFI_STATUS @@ -533,13 +520,13 @@ EhcHaltHC ( /** - Set the EHCI to run + Set the EHCI to run. - @param Ehc The EHCI device - @param Timeout Time to wait before abort + @param Ehc The EHCI device. + @param Timeout Time to wait before abort. - @return EFI_SUCCESS : The EHCI is running - @return Others : Failed to set the EHCI to run + @retval EFI_SUCCESS The EHCI is running. + @return Others Failed to set the EHCI to run. **/ EFI_STATUS @@ -558,17 +545,17 @@ EhcRunHC ( /** Initialize the HC hardware. - EHCI spec lists the five things to do to initialize the hardware + EHCI spec lists the five things to do to initialize the hardware: 1. Program CTRLDSSEGMENT 2. Set USBINTR to enable interrupts 3. Set periodic list base 4. Set USBCMD, interrupt threshold, frame list size etc 5. Write 1 to CONFIGFLAG to route all ports to EHCI - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return EFI_SUCCESS : The EHCI has come out of halt state - @return EFI_TIMEOUT : Time out happened + @return EFI_SUCCESS The EHCI has come out of halt state. + @return EFI_TIMEOUT Time out happened. **/ EFI_STATUS diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.h b/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.h index 929bd22a37..00406e549b 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciReg.h @@ -1,5 +1,7 @@ /** @file + This file contains the definination for host controller register operation routines. + 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,23 +11,13 @@ 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: - - EhciReg.h - -Abstract: - - This file contains the definination for host controller register operation routines - -Revision History - **/ #ifndef _EFI_EHCI_REG_H_ #define _EFI_EHCI_REG_H_ -enum { +typedef enum { // // Capability register offset // @@ -94,7 +86,7 @@ enum { EHC_PCI_CLASSC = 0x09, EHC_PCI_CLASSC_PI = 0x20, EHC_BAR_INDEX = 0 /* how many bytes away from USB_BASE to 0x10 */ -}; +}EHCI_REGISTER_OFFSET; #define EHC_LINK_TERMINATED(Link) (((Link) & 0x01) != 0) @@ -123,38 +115,30 @@ typedef struct { } USB_CLASSC; #pragma pack() +/** + Read EHCI capability register. + + @param Ehc The EHCI device. + @param Offset Capability register address. + + @return The register content. +**/ UINT32 EhcReadCapRegister ( IN USB2_HC_DEV *Ehc, IN UINT32 Offset ) -/*++ - -Routine Description: - - Read EHCI capability register - -Arguments: - - Ehc - The Ehc device - Offset - Capability register address - -Returns: - - The register content read - ---*/ ; /** - Read Ehc Operation register + Read EHCI Operation register. - @param Ehc The EHCI device - @param Offset The operation register offset + @param Ehc The EHCI device. + @param Offset The operation register offset. - @return The register content read + @return The register content. **/ UINT32 @@ -166,13 +150,13 @@ EhcReadOpReg ( /** - Write the data to the EHCI operation register + Write the data to the EHCI operation register. - @param Ehc The EHCI device - @param Offset EHCI operation register offset - @param Data The data to write + @param Ehc The EHCI device. + @param Offset EHCI operation register offset. + @param Data The data to write. - @return None + @return None. **/ VOID @@ -186,11 +170,11 @@ EhcWriteOpReg ( /** Add support for UEFI Over Legacy (UoL) feature, stop - the legacy USB SMI support + the legacy USB SMI support. @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -205,11 +189,11 @@ EhcClearLegacySupport ( Set door bell and wait it to be ACKed by host controller. This function is used to synchronize with the hardware. - @param Ehc The EHCI device - @param Timeout The time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout The time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : Synchronized with the hardware - @return EFI_TIMEOUT : Time out happened while waiting door bell to set + @retval EFI_SUCCESS Synchronized with the hardware. + @retval EFI_TIMEOUT Time out happened while waiting door bell to set. **/ EFI_STATUS @@ -221,12 +205,11 @@ EhcSetAndWaitDoorBell ( /** - Clear all the interrutp status bits, these bits - are Write-Clean + Clear all the interrutp status bits, these bits are Write-Clean. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -238,12 +221,12 @@ EhcAckAllInterrupt ( /** - Whether Ehc is halted + Whether Ehc is halted. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return TRUE : The controller is halted - @return FALSE : It isn't halted + @retval TRUE The controller is halted. + @retval FALSE It isn't halted. **/ BOOLEAN @@ -254,12 +237,12 @@ EhcIsHalt ( /** - Whether system error occurred + Whether system error occurred. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return TRUE : System error happened - @return FALSE : No system error + @retval TRUE System error happened. + @retval FALSE No system error. **/ BOOLEAN @@ -269,15 +252,14 @@ EhcIsSysError ( ; - /** - Reset the host controller + Reset the host controller. - @param Ehc The EHCI device - @param Timeout Time to wait before abort (in millisecond, ms) + @param Ehc The EHCI device. + @param Timeout Time to wait before abort (in millisecond, ms). - @return EFI_SUCCESS : The host controller is reset - @return Others : Failed to reset the host + @retval EFI_SUCCESS The host controller is reset. + @return Others Failed to reset the host. **/ EFI_STATUS @@ -288,15 +270,14 @@ EhcResetHC ( ; - /** - Halt the host controller + Halt the host controller. - @param Ehc The EHCI device - @param Timeout Time to wait before abort + @param Ehc The EHCI device. + @param Timeout Time to wait before abort. - @return EFI_SUCCESS : The EHCI is halt - @return EFI_TIMEOUT : Failed to halt the controller before Timeout + @return EFI_SUCCESS The EHCI is halt. + @return EFI_TIMEOUT Failed to halt the controller before Timeout. **/ EFI_STATUS @@ -307,15 +288,14 @@ EhcHaltHC ( ; - /** - Set the EHCI to run + Set the EHCI to run. - @param Ehc The EHCI device - @param Timeout Time to wait before abort + @param Ehc The EHCI device. + @param Timeout Time to wait before abort. - @return EFI_SUCCESS : The EHCI is running - @return Others : Failed to set the EHCI to run + @return EFI_SUCCESS The EHCI is running. + @return Others Failed to set the EHCI to run. **/ EFI_STATUS @@ -329,17 +309,17 @@ EhcRunHC ( /** Initialize the HC hardware. - EHCI spec lists the five things to do to initialize the hardware + EHCI spec lists the five things to do to initialize the hardware: 1. Program CTRLDSSEGMENT 2. Set USBINTR to enable interrupts 3. Set periodic list base 4. Set USBCMD, interrupt threshold, frame list size etc 5. Write 1 to CONFIGFLAG to route all ports to EHCI - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return EFI_SUCCESS : The EHCI has come out of halt state - @return EFI_TIMEOUT : Time out happened + @return EFI_SUCCESS The EHCI has come out of halt state. + @return EFI_TIMEOUT Time out happened. **/ EFI_STATUS diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.c b/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.c index 60b095f31e..522f2d0633 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.c @@ -1,5 +1,7 @@ /** @file + EHCI transfer scheduling routines. + 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,20 @@ 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: - - EhciSched.c - -Abstract: - - EHCI transfer scheduling routines - -Revision History - **/ #include "Ehci.h" /** - Create helper QTD/QH for the EHCI device + Create helper QTD/QH for the EHCI device. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for helper QTD/QH - @retval EFI_SUCCESS Helper QH/QTD are created + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for helper QTD/QH. + @retval EFI_SUCCESS Helper QH/QTD are created. **/ -STATIC EFI_STATUS EhcCreateHelpQ ( IN USB2_HC_DEV *Ehc @@ -102,14 +93,13 @@ EhcCreateHelpQ ( } - /** - Initialize the schedule data structure such as frame list + Initialize the schedule data structure such as frame list. - @param Ehc The EHCI device to init schedule data for + @param Ehc The EHCI device to init schedule data. - @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to init schedule data - @retval EFI_SUCCESS The schedule data is initialized + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to init schedule data. + @retval EFI_SUCCESS The schedule data is initialized. **/ EFI_STATUS @@ -213,13 +203,12 @@ EhcInitSched ( } - /** Free the schedule data. It may be partially initialized. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -269,7 +258,6 @@ EhcFreeSched ( } - /** Link the queue head to the asynchronous schedule list. UEFI only supports one CTRL/BULK transfer at a time @@ -277,10 +265,10 @@ EhcFreeSched ( management: A reclamation header is always linked to the AsyncListAddr, the only active QH is appended to it. - @param Ehc The EHCI device - @param Qh The queue head to link + @param Ehc The EHCI device. + @param Qh The queue head to link. - @return None + @return None. **/ VOID @@ -308,12 +296,12 @@ EhcLinkQhToAsync ( /** Unlink a queue head from the asynchronous schedule list. - Need to synchronize with hardware + Need to synchronize with hardware. - @param Ehc The EHCI device - @param Qh The queue head to unlink + @param Ehc The EHCI device. + @param Qh The queue head to unlink. - @return None + @return None. **/ VOID @@ -355,10 +343,10 @@ EhcUnlinkQhFromAsync ( schedule frame list. This code is very much the same as that in UHCI. - @param Ehc The EHCI device - @param Qh The queue head to link + @param Ehc The EHCI device. + @param Qh The queue head to link. - @return None + @return None. **/ VOID @@ -454,12 +442,12 @@ EhcLinkQhToPeriod ( /** Unlink an interrupt queue head from the periodic - schedule frame list + schedule frame list. - @param Ehc The EHCI device - @param Qh The queue head to unlink + @param Ehc The EHCI device. + @param Qh The queue head to unlink. - @return None + @return None. **/ VOID @@ -514,18 +502,16 @@ EhcUnlinkQhFromPeriod ( } - /** Check the URB's execution result and update the URB's result accordingly. - @param Ehc The EHCI device - @param Urb The URB to check result + @param Ehc The EHCI device. + @param Urb The URB to check result. @return Whether the result of URB transfer is finialized. **/ -STATIC BOOLEAN EhcCheckUrbResult ( IN USB2_HC_DEV *Ehc, @@ -637,13 +623,13 @@ ON_EXIT: /** Execute the transfer by polling the URB. This is a synchronous operation. - @param Ehc The EHCI device - @param Urb The URB to execute - @param TimeOut The time to wait before abort, in millisecond. + @param Ehc The EHCI device. + @param Urb The URB to execute. + @param TimeOut The time to wait before abort, in millisecond. - @return EFI_DEVICE_ERROR : The transfer failed due to transfer error - @return EFI_TIMEOUT : The transfer failed due to time out - @return EFI_SUCCESS : The transfer finished OK + @return EFI_DEVICE_ERROR The transfer failed due to transfer error. + @return EFI_TIMEOUT The transfer failed due to time out. + @return EFI_SUCCESS The transfer finished OK. **/ EFI_STATUS @@ -691,15 +677,15 @@ EhcExecTransfer ( /** Delete a single asynchronous interrupt transfer for - the device and endpoint + the device and endpoint. - @param Ehc The EHCI device - @param DevAddr The address of the target device - @param EpNum The endpoint of the target - @param DataToggle Return the next data toggle to use + @param Ehc The EHCI device. + @param DevAddr The address of the target device. + @param EpNum The endpoint of the target. + @param DataToggle Return the next data toggle to use. - @retval EFI_SUCCESS An asynchronous transfer is removed - @retval EFI_NOT_FOUND No transfer for the device is found + @retval EFI_SUCCESS An asynchronous transfer is removed. + @retval EFI_NOT_FOUND No transfer for the device is found. **/ EFI_STATUS @@ -715,7 +701,7 @@ EhciDelAsyncIntTransfer ( URB *Urb; EFI_USB_DATA_DIRECTION Direction; - Direction = ((EpNum & 0x80) ? EfiUsbDataIn : EfiUsbDataOut); + Direction = (((EpNum & 0x80) != 0) ? EfiUsbDataIn : EfiUsbDataOut); EpNum &= 0x0F; EFI_LIST_FOR_EACH_SAFE (Entry, Next, &Ehc->AsyncIntTransfers) { @@ -744,11 +730,11 @@ EhciDelAsyncIntTransfer ( /** - Remove all the asynchronous interrutp transfers + Remove all the asynchronous interrutp transfers. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -771,30 +757,23 @@ EhciDelAllAsyncIntTransfers ( } } -STATIC -EFI_STATUS -EhcFlushAsyncIntMap ( - IN USB2_HC_DEV *Ehc, - IN URB *Urb - ) -/*++ - -Routine Description: +/** Flush data from PCI controller specific address to mapped system memory address. -Arguments: + @param Ehc The EHCI device. + @param Urb The URB to unmap. - Ehc - The EHCI device - Urb - The URB to unmap + @retval EFI_SUCCESS Success to flush data to mapped system memory. + @retval EFI_DEVICE_ERROR Fail to flush data to mapped system memory. -Returns: - - EFI_SUCCESS - Success to flush data to mapped system memory - EFI_DEVICE_ERROR - Fail to flush data to mapped system memory - ---*/ +**/ +EFI_STATUS +EhcFlushAsyncIntMap ( + IN USB2_HC_DEV *Ehc, + IN URB *Urb + ) { EFI_STATUS Status; EFI_PHYSICAL_ADDRESS PhyAddr; @@ -833,16 +812,14 @@ ON_ERROR: } - /** - Update the queue head for next round of asynchronous transfer + Update the queue head for next round of asynchronous transfer. - @param Urb The URB to update + @param Urb The URB to update. - @return None + @return None. **/ -STATIC VOID EhcUpdateAsyncRequest ( IN URB *Urb @@ -913,12 +890,12 @@ EhcUpdateAsyncRequest ( /** - Interrupt transfer periodic check handler + Interrupt transfer periodic check handler. - @param Event Interrupt event - @param Context Pointer to USB2_HC_DEV + @param Event Interrupt event. + @param Context Pointer to USB2_HC_DEV. - @return None + @return None. **/ VOID diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.h b/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.h index d8f2661059..13f7b5ad41 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciSched.h @@ -1,5 +1,7 @@ /** @file + This file contains the definination for host controller schedule routines. + 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,49 +11,32 @@ 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: +**/ - EhciSched.h +#ifndef _EFI_EHCI_SCHED_H_ +#define _EFI_EHCI_SCHED_H_ -Abstract: - This file contains the definination for host controller schedule routines +/** + Initialize the schedule data structure such as frame list. -Revision History + @param Ehc The EHCI device to init schedule data for. -**/ - -#ifndef _EFI_EHCI_SCHED_H_ -#define _EFI_EHCI_SCHED_H_ + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to init schedule data. + @retval EFI_SUCCESS The schedule data is initialized. +**/ EFI_STATUS EhcInitSched ( IN USB2_HC_DEV *Ehc ) -/*++ - -Routine Description: - - Initialize the schedule data structure such as frame list - -Arguments: - - Ehc - The EHCI device to init schedule data for - -Returns: - - EFI_OUT_OF_RESOURCES - Failed to allocate resource to init schedule data - EFI_SUCCESS - The schedule data is initialized - ---*/ ; - /** Free the schedule data. It may be partially initialized. - @param Ehc The EHCI device + @param Ehc The EHCI device. @return None @@ -63,7 +48,6 @@ EhcFreeSched ( ; - /** Link the queue head to the asynchronous schedule list. UEFI only supports one CTRL/BULK transfer at a time @@ -71,10 +55,10 @@ EhcFreeSched ( management: A reclamation header is always linked to the AsyncListAddr, the only active QH is appended to it. - @param Ehc The EHCI device - @param Qh The queue head to link + @param Ehc The EHCI device. + @param Qh The queue head to link. - @return None + @return None. **/ VOID @@ -87,12 +71,12 @@ EhcLinkQhToAsync ( /** Unlink a queue head from the asynchronous schedule list. - Need to synchronize with hardware + Need to synchronize with hardware. - @param Ehc The EHCI device - @param Qh The queue head to unlink + @param Ehc The EHCI device. + @param Qh The queue head to unlink. - @return None + @return None. **/ VOID @@ -108,10 +92,10 @@ EhcUnlinkQhFromAsync ( schedule frame list. This code is very much the same as that in UHCI. - @param Ehc The EHCI device - @param Qh The queue head to link + @param Ehc The EHCI device. + @param Qh The queue head to link. - @return None + @return None. **/ VOID @@ -124,12 +108,12 @@ EhcLinkQhToPeriod ( /** Unlink an interrupt queue head from the periodic - schedule frame list + schedule frame list. - @param Ehc The EHCI device - @param Qh The queue head to unlink + @param Ehc The EHCI device. + @param Qh The queue head to unlink. - @return None + @return None. **/ VOID @@ -144,13 +128,13 @@ EhcUnlinkQhFromPeriod ( /** Execute the transfer by polling the URB. This is a synchronous operation. - @param Ehc The EHCI device - @param Urb The URB to execute - @param TimeOut The time to wait before abort, in millisecond. + @param Ehc The EHCI device. + @param Urb The URB to execute. + @param TimeOut The time to wait before abort, in millisecond. - @return EFI_DEVICE_ERROR : The transfer failed due to transfer error - @return EFI_TIMEOUT : The transfer failed due to time out - @return EFI_SUCCESS : The transfer finished OK + @retval EFI_DEVICE_ERROR The transfer failed due to transfer error. + @retval EFI_TIMEOUT The transfer failed due to time out. + @retval EFI_SUCCESS The transfer finished OK. **/ EFI_STATUS @@ -164,15 +148,15 @@ EhcExecTransfer ( /** Delete a single asynchronous interrupt transfer for - the device and endpoint + the device and endpoint. - @param Ehc The EHCI device - @param DevAddr The address of the target device - @param EpNum The endpoint of the target - @param DataToggle Return the next data toggle to use + @param Ehc The EHCI device. + @param DevAddr The address of the target device. + @param EpNum The endpoint of the target. + @param DataToggle Return the next data toggle to use. - @retval EFI_SUCCESS An asynchronous transfer is removed - @retval EFI_NOT_FOUND No transfer for the device is found + @retval EFI_SUCCESS An asynchronous transfer is removed. + @retval EFI_NOT_FOUND No transfer for the device is found. **/ EFI_STATUS @@ -186,11 +170,11 @@ EhciDelAsyncIntTransfer ( /** - Remove all the asynchronous interrutp transfers + Remove all the asynchronous interrutp transfers. - @param Ehc The EHCI device + @param Ehc The EHCI device. - @return None + @return None. **/ VOID @@ -200,14 +184,13 @@ EhciDelAllAsyncIntTransfers ( ; - /** - Interrupt transfer periodic check handler + Interrupt transfer periodic check handler. - @param Event Interrupt event - @param Context Pointer to USB2_HC_DEV + @param Event Interrupt event. + @param Context Pointer to USB2_HC_DEV. - @return None + @return None. **/ VOID diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.c b/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.c index bb272cc8de..4d8e38be2c 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.c @@ -1,5 +1,8 @@ /** @file + This file contains URB request, each request is warpped in a + URB (Usb Request Block). + 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,33 +12,22 @@ 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: - - EhciUrb.c - -Abstract: - - This file contains URB request, each request is warpped in a - URB (Usb Request Block) - -Revision History - **/ #include "Ehci.h" /** - Create a single QTD to hold the data + Create a single QTD to hold the data. - @param Ehc The EHCI device - @param Data Current data not associated with a QTD - @param DataLen The length of the data - @param PktId Packet ID to use in the QTD - @param Toggle Data toggle to use in the QTD - @param MaxPacket Maximu packet length of the endpoint + @param Ehc The EHCI device. + @param Data Current data not associated with a QTD. + @param DataLen The length of the data. + @param PktId Packet ID to use in the QTD. + @param Toggle Data toggle to use in the QTD. + @param MaxPacket Maximu packet length of the endpoint. - @return Created QTD or NULL if failed to create one + @return Created QTD or NULL if failed to create one. **/ EHC_QTD * @@ -130,13 +122,12 @@ EhcCreateQtd ( 2. Microframe S-mask 3. Microframe C-mask - @param Ep The queue head's related endpoint - @param QhHw The queue head to initialize + @param Ep The queue head's related endpoint. + @param QhHw The queue head to initialize. - @return None + @return None. **/ -STATIC VOID EhcInitIntQh ( IN USB_ENDPOINT *Ep, @@ -173,12 +164,12 @@ EhcInitIntQh ( /** - Allocate and initialize a EHCI queue head + Allocate and initialize a EHCI queue head. - @param Ehci The EHCI device - @param Ep The endpoint to create queue head for + @param Ehci The EHCI device. + @param Ep The endpoint to create queue head for. - @return Created queue head or NULL if failed to create one + @return Created queue head or NULL if failed to create one. **/ EHC_QH * @@ -258,21 +249,19 @@ EhcCreateQh ( } - /** Convert the poll interval from application to that be used by EHCI interface data structure. Only need to get the max 2^n that is less than interval. UEFI can't support high speed endpoint with a interval less than 8 microframe because interval is specified in - the unit of ms (millisecond) + the unit of ms (millisecond). - @param Interval The interval to convert + @param Interval The interval to convert. - @return The converted interval + @return The converted interval. **/ -STATIC UINTN EhcConvertPollRate ( IN UINTN Interval @@ -298,17 +287,15 @@ EhcConvertPollRate ( } - /** - Free a list of QTDs + Free a list of QTDs. - @param Ehc The EHCI device - @param Qtds The list head of the QTD + @param Ehc The EHCI device. + @param Qtds The list head of the QTD. - @return None + @return None. **/ -STATIC VOID EhcFreeQtds ( IN USB2_HC_DEV *Ehc, @@ -331,10 +318,10 @@ EhcFreeQtds ( /** Free an allocated URB. It is possible for it to be partially inited. - @param Ehc The EHCI device - @param Urb The URB to free + @param Ehc The EHCI device. + @param Urb The URB to free. - @return None + @return None. **/ VOID @@ -368,18 +355,16 @@ EhcFreeUrb ( } - /** - Create a list of QTDs for the URB + Create a list of QTDs for the URB. - @param Ehc The EHCI device - @param Urb The URB to create QTDs for + @param Ehc The EHCI device. + @param Urb The URB to create QTDs for. - @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for QTD - @retval EFI_SUCCESS The QTDs are allocated for the URB + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for QTD. + @retval EFI_SUCCESS The QTDs are allocated for the URB. **/ -STATIC EFI_STATUS EhcCreateQtds ( IN USB2_HC_DEV *Ehc, @@ -530,24 +515,24 @@ ON_ERROR: /** - Create a new URB and its associated QTD - - @param Ehc The EHCI device - @param DevAddr The device address - @param EpAddr Endpoint addrress & its direction - @param DevSpeed The device speed - @param Toggle Initial data toggle to use - @param MaxPacket The max packet length of the endpoint - @param Hub The transaction translator to use - @param Type The transaction type - @param Request The standard USB request for control transfer - @param Data The user data to transfer - @param DataLen The length of data buffer - @param Callback The function to call when data is transferred - @param Context The context to the callback - @param Interval The interval for interrupt transfer - - @return Created URB or NULL + Create a new URB and its associated QTD. + + @param Ehc The EHCI device. + @param DevAddr The device address. + @param EpAddr Endpoint addrress & its direction. + @param DevSpeed The device speed. + @param Toggle Initial data toggle to use. + @param MaxPacket The max packet length of the endpoint. + @param Hub The transaction translator to use. + @param Type The transaction type. + @param Request The standard USB request for control transfer. + @param Data The user data to transfer. + @param DataLen The length of data buffer. + @param Callback The function to call when data is transferred. + @param Context The context to the callback. + @param Interval The interval for interrupt transfer. + + @return Created URB or NULL. **/ URB * @@ -589,7 +574,7 @@ EhcCreateUrb ( Ep = &Urb->Ep; Ep->DevAddr = DevAddr; Ep->EpAddr = (UINT8) (EpAddr & 0x0F); - Ep->Direction = ((EpAddr & 0x80) ? EfiUsbDataIn : EfiUsbDataOut); + Ep->Direction = (((EpAddr & 0x80) != 0) ? EfiUsbDataIn : EfiUsbDataOut); Ep->DevSpeed = DevSpeed; Ep->MaxPacket = MaxPacket; diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h b/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h index a1dc8e6c0a..5cda230a01 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h @@ -1,5 +1,8 @@ /** @file + This file contains URB request, each request is warpped in a + URB (Usb Request Block). + 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 +12,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: - - EhciUrb.h - -Abstract: - - This file contains URB request, each request is warpped in a - URB (Usb Request Block) - -Revision History - **/ #ifndef _EFI_EHCI_URB_H_ @@ -30,7 +22,7 @@ typedef struct _EHC_QTD EHC_QTD; typedef struct _EHC_QH EHC_QH; typedef struct _URB URB; -enum { +typedef enum { // // Transfer types, used in URB to identify the transfer type // @@ -84,7 +76,7 @@ enum { QH_MICROFRAME_7 = 0x80, USB_ERR_SHORT_PACKET = 0x200 -}; +}EHCI_URB_FLAG_VALUE; // // Fill in the hardware link point: pass in a EHC_QH/QH_HW @@ -249,16 +241,16 @@ struct _URB { /** - Create a single QTD to hold the data + Create a single QTD to hold the data. - @param Ehc The EHCI device - @param Data Current data not associated with a QTD - @param DataLen The length of the data - @param PktId Packet ID to use in the QTD - @param Toggle Data toggle to use in the QTD - @param MaxPacket Maximu packet length of the endpoint + @param Ehc The EHCI device. + @param Data Current data not associated with a QTD. + @param DataLen The length of the data. + @param PktId Packet ID to use in the QTD. + @param Toggle Data toggle to use in the QTD. + @param MaxPacket Maximu packet length of the endpoint. - @return Created QTD or NULL if failed to create one + @return Created QTD or NULL if failed to create one. **/ EHC_QTD * @@ -275,12 +267,12 @@ EhcCreateQtd ( /** - Allocate and initialize a EHCI queue head + Allocate and initialize a EHCI queue head. - @param Ehci The EHCI device - @param Ep The endpoint to create queue head for + @param Ehci The EHCI device. + @param Ep The endpoint to create queue head for. - @return Created queue head or NULL if failed to create one + @return Created queue head or NULL if failed to create one. **/ EHC_QH * @@ -294,10 +286,10 @@ EhcCreateQh ( /** Free an allocated URB. It is possible for it to be partially inited. - @param Ehc The EHCI device - @param Urb The URB to free + @param Ehc The EHCI device. + @param Urb The URB to free. - @return None + @return None. **/ VOID @@ -309,24 +301,24 @@ EhcFreeUrb ( /** - Create a new URB and its associated QTD - - @param Ehc The EHCI device - @param DevAddr The device address - @param EpAddr Endpoint addrress & its direction - @param DevSpeed The device speed - @param Toggle Initial data toggle to use - @param MaxPacket The max packet length of the endpoint - @param Hub The transaction translator to use - @param Type The transaction type - @param Request The standard USB request for control transfer - @param Data The user data to transfer - @param DataLen The length of data buffer - @param Callback The function to call when data is transferred - @param Context The context to the callback - @param Interval The interval for interrupt transfer - - @return Created URB or NULL + Create a new URB and its associated QTD. + + @param Ehc The EHCI device. + @param DevAddr The device address. + @param EpAddr Endpoint addrress & its direction. + @param DevSpeed The device speed. + @param Toggle Initial data toggle to use. + @param MaxPacket The max packet length of the endpoint. + @param Hub The transaction translator to use. + @param Type The transaction type. + @param Request The standard USB request for control transfer. + @param Data The user data to transfer. + @param DataLen The length of data buffer. + @param Callback The function to call when data is transferred. + @param Context The context to the callback. + @param Interval The interval for interrupt transfer. + + @return Created URB or NULL. **/ URB * diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.c b/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.c index d038ebc20d..92d7bf7a84 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.c +++ b/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.c @@ -1,5 +1,7 @@ /** @file + Routine procedures for memory allocate/free. + 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,15 +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: - - EhciMem.c - -Abstract: - - -Revision History - **/ @@ -25,15 +18,14 @@ Revision History /** - Allocate a block of memory to be used by the buffer pool + Allocate a block of memory to be used by the buffer pool. - @param Pool The buffer pool to allocate memory for - @param Pages How many pages to allocate + @param Pool The buffer pool to allocate memory for. + @param Pages How many pages to allocate. - @return The allocated memory block or NULL if failed + @return The allocated memory block or NULL if failed. **/ -STATIC USBHC_MEM_BLOCK * UsbHcAllocMemBlock ( IN USBHC_MEM_POOL *Pool, @@ -127,15 +119,14 @@ FREE_BITARRAY: /** - Free the memory block from the memory pool + Free the memory block from the memory pool. - @param Pool The memory pool to free the block from - @param Block The memory block to free + @param Pool The memory pool to free the block from. + @param Block The memory block to free. - @return VOID + @return None. **/ -STATIC VOID UsbHcFreeMemBlock ( IN USBHC_MEM_POOL *Pool, @@ -160,17 +151,15 @@ UsbHcFreeMemBlock ( /** - Alloc some memory from the block + Alloc some memory from the block. - @param Block The memory block to allocate memory from - @param Mem The variable to store the memory allocated - @param Units Number of memory units to allocate + @param Block The memory block to allocate memory from. + @param Units Number of memory units to allocate. - @return EFI_SUCCESS : The needed memory is allocated - @return EFI_NOT_FOUND : Can't find the free memory + @return The pointer to the allocated memory. If couldn't allocate the needed memory, + the return value is NULL. **/ -STATIC VOID * UsbHcAllocMemFromBlock ( IN USBHC_MEM_BLOCK *Block, @@ -236,15 +225,14 @@ UsbHcAllocMemFromBlock ( /** - Insert the memory block to the pool's list of the blocks + Insert the memory block to the pool's list of the blocks. - @param Head The head of the memory pool's block list - @param Block The memory block to insert + @param Head The head of the memory pool's block list. + @param Block The memory block to insert. - @return VOID + @return None. **/ -STATIC VOID UsbHcInsertMemBlockToPool ( IN USBHC_MEM_BLOCK *Head, @@ -260,13 +248,12 @@ UsbHcInsertMemBlockToPool ( /** Is the memory block empty? - @param Block The memory block to check + @param Block The memory block to check. - @return TRUE : The memory block is empty - @return FALSE : The memory block isn't empty + @retval TRUE The memory block is empty. + @retval FALSE The memory block isn't empty. **/ -STATIC BOOLEAN UsbHcIsMemBlockEmpty ( IN USBHC_MEM_BLOCK *Block @@ -285,15 +272,14 @@ UsbHcIsMemBlockEmpty ( /** - Unlink the memory block from the pool's list + Unlink the memory block from the pool's list. - @param Head The block list head of the memory's pool + @param Head The block list head of the memory's pool. @param BlockToUnlink The memory block to unlink. - @return VOID + @return None. **/ -STATIC VOID UsbHcUnlinkMemBlock ( IN USBHC_MEM_BLOCK *Head, @@ -315,16 +301,15 @@ UsbHcUnlinkMemBlock ( /** - Initialize the memory management pool for the host controller + Initialize the memory management pool for the host controller. - @param Pool The USB memory pool to initialize - @param PciIo The PciIo that can be used to access the host controller - @param Check4G Whether the host controller requires allocated memory - from one 4G address space. - @param Which4G The 4G memory area each memory allocated should be from + @param PciIo The PciIo that can be used to access the host controller. + @param Check4G Whether the host controller requires allocated memory + from one 4G address space. + @param Which4G The 4G memory area each memory allocated should be from. - @return EFI_SUCCESS : The memory pool is initialized - @return EFI_OUT_OF_RESOURCE : Fail to init the memory pool + @retval EFI_SUCCESS The memory pool is initialized. + @retval EFI_OUT_OF_RESOURCE Fail to init the memory pool. **/ USBHC_MEM_POOL * @@ -357,12 +342,12 @@ UsbHcInitMemPool ( /** - Release the memory management pool + Release the memory management pool. - @param Pool The USB memory pool to free + @param Pool The USB memory pool to free. - @return EFI_SUCCESS : The memory pool is freed - @return EFI_DEVICE_ERROR : Failed to free the memory pool + @retval EFI_SUCCESS The memory pool is freed. + @retval EFI_DEVICE_ERROR Failed to free the memory pool. **/ EFI_STATUS @@ -394,10 +379,10 @@ UsbHcFreeMemPool ( Allocate some memory from the host controller's memory pool which can be used to communicate with host controller. - @param Pool The host controller's memory pool - @param Size Size of the memory to allocate + @param Pool The host controller's memory pool. + @param Size Size of the memory to allocate. - @return The allocated memory or NULL + @return The allocated memory or NULL. **/ VOID * @@ -468,13 +453,13 @@ UsbHcAllocateMem ( /** - Free the allocated memory back to the memory pool + Free the allocated memory back to the memory pool. - @param Pool The memory pool of the host controller - @param Mem The memory to free - @param Size The size of the memory to free + @param Pool The memory pool of the host controller. + @param Mem The memory to free. + @param Size The size of the memory to free. - @return VOID + @return None. **/ VOID diff --git a/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.h b/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.h index 09fd162529..7fda8a528c 100644 --- a/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.h +++ b/MdeModulePkg/Bus/Pci/EhciDxe/UsbHcMem.h @@ -1,5 +1,7 @@ /** @file + This file contains the definination for host controller memory management routines. + 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,16 +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: - - EhciMem.h - -Abstract: - - This file contains the definination for host controller memory management routines - -Revision History - **/ #ifndef _EFI_EHCI_MEM_H_ @@ -59,12 +51,12 @@ typedef struct _USBHC_MEM_POOL { USBHC_MEM_BLOCK *Head; } USBHC_MEM_POOL; -enum { +typedef enum { USBHC_MEM_UNIT = 64, // Memory allocation unit, must be 2^n, n>4 USBHC_MEM_UNIT_MASK = USBHC_MEM_UNIT - 1, USBHC_MEM_DEFAULT_PAGES = 16 -}; +} USBHC_MEM_UNIT_DATA; #define USBHC_MEM_ROUND(Len) (((Len) + USBHC_MEM_UNIT_MASK) & (~USBHC_MEM_UNIT_MASK)) @@ -82,43 +74,34 @@ enum { +/** + Initialize the memory management pool for the host controller. + + @param PciIo The PciIo that can be used to access the host controller. + @param Check4G Whether the host controller requires allocated memory + from one 4G address space. + @param Which4G The 4G memory area each memory allocated should be from. + + @retval EFI_SUCCESS The memory pool is initialized. + @retval EFI_OUT_OF_RESOURCE Fail to init the memory pool. + +**/ USBHC_MEM_POOL * UsbHcInitMemPool ( IN EFI_PCI_IO_PROTOCOL *PciIo, IN BOOLEAN Check4G, IN UINT32 Which4G ) -/*++ - -Routine Description: - - Initialize the memory management pool for the host controller - -Arguments: - - Pool - The USB memory pool to initialize - PciIo - The PciIo that can be used to access the host controller - Check4G - Whether the host controller requires allocated memory - from one 4G address space. - Which4G - The 4G memory area each memory allocated should be from - -Returns: - - EFI_SUCCESS : The memory pool is initialized - EFI_OUT_OF_RESOURCE : Fail to init the memory pool - ---*/ ; - /** - Release the memory management pool + Release the memory management pool. - @param Pool The USB memory pool to free + @param Pool The USB memory pool to free. - @return EFI_SUCCESS : The memory pool is freed - @return EFI_DEVICE_ERROR : Failed to free the memory pool + @retval EFI_SUCCESS The memory pool is freed. + @retval EFI_DEVICE_ERROR Failed to free the memory pool. **/ EFI_STATUS @@ -128,15 +111,14 @@ UsbHcFreeMemPool ( ; - /** Allocate some memory from the host controller's memory pool which can be used to communicate with host controller. - @param Pool The host controller's memory pool - @param Size Size of the memory to allocate + @param Pool The host controller's memory pool. + @param Size Size of the memory to allocate. - @return The allocated memory or NULL + @return The allocated memory or NULL. **/ VOID * @@ -147,15 +129,14 @@ UsbHcAllocateMem ( ; - /** - Free the allocated memory back to the memory pool + Free the allocated memory back to the memory pool. - @param Pool The memory pool of the host controller - @param Mem The memory to free - @param Size The size of the memory to free + @param Pool The memory pool of the host controller. + @param Mem The memory to free. + @param Size The size of the memory to free. - @return VOID + @return None. **/ VOID -- 2.39.2