-/**@file\r
+/** @file\r
+ Supporting functions declaration for PCI devices management.\r
\r
-Copyright (c) 2006, Intel Corporation \r
-All rights reserved. This program and the accompanying materials \r
-are licensed and made available under the terms and conditions of the BSD License \r
-which accompanies this distribution. The full text of the license may be found at \r
-http://opensource.org/licenses/bsd-license.php \r
- \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+Copyright (c) 2006 - 2009, Intel Corporation\r
+All rights reserved. This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution. The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
-#ifndef _EFI_PCI_DEVICE_SUPPORT_H\r
-#define _EFI_PCI_DEVICE_SUPPORT_H\r
+#ifndef _EFI_PCI_DEVICE_SUPPORT_H_\r
+#define _EFI_PCI_DEVICE_SUPPORT_H_\r
\r
-EFI_STATUS\r
+/**\r
+ Initialize the PCI devices pool.\r
+\r
+**/\r
+VOID\r
InitializePciDevicePool (\r
VOID\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- None\r
+ );\r
\r
-Returns:\r
+/**\r
+ Insert a root bridge into PCI device pool.\r
\r
- TODO: add return values\r
+ @param RootBridge A pointer to the PCI_IO_DEVICE.\r
\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
+**/\r
+VOID\r
InsertRootBridge (\r
- PCI_IO_DEVICE *RootBridge\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- RootBridge - TODO: add argument description\r
-\r
-Returns:\r
+ IN PCI_IO_DEVICE *RootBridge\r
+ );\r
\r
- TODO: add return values\r
+/**\r
+ This function is used to insert a PCI device node under\r
+ a bridge.\r
\r
---*/\r
-;\r
+ @param Bridge The PCI bridge.\r
+ @param PciDeviceNode The PCI device needs inserting.\r
\r
-EFI_STATUS\r
+**/\r
+VOID\r
InsertPciDevice (\r
- PCI_IO_DEVICE *Bridge,\r
- PCI_IO_DEVICE *PciDeviceNode\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
+ IN PCI_IO_DEVICE *Bridge,\r
+ IN PCI_IO_DEVICE *PciDeviceNode\r
+ );\r
\r
-Arguments:\r
+/**\r
+ Destroy root bridge and remove it from deivce tree.\r
\r
- Bridge - TODO: add argument description\r
- PciDeviceNode - TODO: add argument description\r
+ @param RootBridge The bridge want to be removed.\r
\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
+**/\r
+VOID\r
DestroyRootBridge (\r
- IN PCI_IO_DEVICE *RootBridge\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ IN PCI_IO_DEVICE *RootBridge\r
+ );\r
\r
- RootBridge - TODO: add argument description\r
+/**\r
+ Destroy all the pci device node under the bridge.\r
+ Bridge itself is not included.\r
\r
-Returns:\r
+ @param Bridge A pointer to the PCI_IO_DEVICE.\r
\r
- TODO: add return values\r
-\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
+**/\r
+VOID\r
DestroyPciDeviceTree (\r
- IN PCI_IO_DEVICE *Bridge\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ IN PCI_IO_DEVICE *Bridge\r
+ );\r
\r
- Bridge - TODO: add argument description\r
+/**\r
+ Destroy all device nodes under the root bridge\r
+ specified by Controller.\r
\r
-Returns:\r
+ The root bridge itself is also included.\r
\r
- TODO: add return values\r
+ @param Controller Root bridge handle.\r
\r
---*/\r
-;\r
+ @retval EFI_SUCCESS Destory all devcie nodes successfully.\r
+ @retval EFI_NOT_FOUND Cannot find any PCI device under specified\r
+ root bridge.\r
\r
+**/\r
EFI_STATUS\r
DestroyRootBridgeByHandle (\r
- EFI_HANDLE Controller\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ IN EFI_HANDLE Controller\r
+ );\r
\r
- Controller - TODO: add argument description\r
+/**\r
+ This function registers the PCI IO device.\r
\r
-Returns:\r
+ It creates a handle for this PCI IO device (if the handle does not exist), attaches\r
+ appropriate protocols onto the handle, does necessary initialization, and sets up\r
+ parent/child relationship with its bus controller.\r
\r
- TODO: add return values\r
+ @param Controller An EFI handle for the PCI bus controller.\r
+ @param PciIoDevice A PCI_IO_DEVICE pointer to the PCI IO device to be registered.\r
+ @param Handle A pointer to hold the returned EFI handle for the PCI IO device.\r
\r
---*/\r
-;\r
+ @retval EFI_SUCCESS The PCI device is successfully registered.\r
+ @retval other An error occurred when registering the PCI device.\r
\r
+**/\r
EFI_STATUS\r
RegisterPciDevice (\r
- IN EFI_HANDLE Controller,\r
- IN PCI_IO_DEVICE *PciIoDevice,\r
- OUT EFI_HANDLE *Handle OPTIONAL\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
+ IN EFI_HANDLE Controller,\r
+ IN PCI_IO_DEVICE *PciIoDevice,\r
+ OUT EFI_HANDLE *Handle OPTIONAL\r
+ );\r
\r
-Arguments:\r
+/**\r
+ This function is used to remove the whole PCI devices on the specified bridge from\r
+ the root bridge.\r
\r
- Controller - TODO: add argument description\r
- PciIoDevice - TODO: add argument description\r
- Handle - TODO: add argument description\r
+ @param RootBridgeHandle The root bridge device handle.\r
+ @param Bridge The bridge device to be removed.\r
\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
+**/\r
+VOID\r
RemoveAllPciDeviceOnBridge (\r
EFI_HANDLE RootBridgeHandle,\r
PCI_IO_DEVICE *Bridge\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ );\r
\r
- RootBridgeHandle - TODO: add argument description\r
- Bridge - TODO: add argument description\r
+/**\r
+ This function is used to de-register the PCI IO device.\r
\r
-Returns:\r
+ That includes un-installing PciIo protocol from the specified PCI\r
+ device handle.\r
\r
- TODO: add return values\r
+ @param Controller An EFI handle for the PCI bus controller.\r
+ @param Handle PCI device handle.\r
\r
---*/\r
-;\r
+ @retval EFI_SUCCESS The PCI device is successfully de-registered.\r
+ @retval other An error occurred when de-registering the PCI device.\r
\r
+**/\r
EFI_STATUS\r
DeRegisterPciDevice (\r
IN EFI_HANDLE Controller,\r
IN EFI_HANDLE Handle\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ );\r
\r
- Controller - TODO: add argument description\r
- Handle - TODO: add argument description\r
+/**\r
+ Start to manage the PCI device on specified the root bridge or PCI-PCI Bridge\r
\r
-Returns:\r
+ @param Controller The root bridge handle.\r
+ @param RootBridge A pointer to the PCI_IO_DEVICE.\r
+ @param RemainingDevicePath A pointer to the EFI_DEVICE_PATH_PROTOCOL.\r
+ @param NumberOfChildren Children number.\r
+ @param ChildHandleBuffer A pointer to the child handle buffer.\r
\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @retval EFI_NOT_READY Device is not allocated.\r
+ @retval EFI_UNSUPPORTED Device only support PCI-PCI bridge.\r
+ @retval EFI_NOT_FOUND Can not find the specific device.\r
+ @retval EFI_SUCCESS Success to start Pci device on bridge.\r
\r
+**/\r
EFI_STATUS\r
StartPciDevicesOnBridge (\r
IN EFI_HANDLE Controller,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath,\r
IN OUT UINT8 *NumberOfChildren,\r
IN OUT EFI_HANDLE *ChildHandleBuffer\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
+ );\r
\r
-Arguments:\r
+/**\r
+ Start to manage all the PCI devices it found previously under\r
+ the entire host bridge.\r
\r
- Controller - TODO: add argument description\r
- RootBridge - TODO: add argument description\r
- RemainingDevicePath - TODO: add argument description\r
- NumberOfChildren - TODO: add argument description\r
- ChildHandleBuffer - TODO: add argument description\r
+ @param Controller The root bridge handle.\r
\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @retval EFI_NOT_READY Device is not allocated.\r
+ @retval EFI_SUCCESS Success to start Pci device on host bridge.\r
\r
+**/\r
EFI_STATUS\r
StartPciDevices (\r
IN EFI_HANDLE Controller\r
- )\r
-/*++\r
+ );\r
\r
-Routine Description:\r
+/**\r
+ Create root bridge device.\r
\r
- TODO: Add function description\r
+ @param RootBridgeHandle Specified root bridge hanle.\r
\r
-Arguments:\r
-\r
- Controller - TODO: add argument description\r
-\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @return The crated root bridge device instance, NULL means no\r
+ root bridge device instance created.\r
\r
+**/\r
PCI_IO_DEVICE *\r
CreateRootBridge (\r
- IN EFI_HANDLE RootBridgeHandle\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ IN EFI_HANDLE RootBridgeHandle\r
+ );\r
\r
- RootBridgeHandle - TODO: add argument description\r
+/**\r
+ Get root bridge device instance by specific root bridge handle.\r
\r
-Returns:\r
+ @param RootBridgeHandle Given root bridge handle.\r
\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @return The root bridge device instance, NULL means no root bridge\r
+ device instance found.\r
\r
+**/\r
PCI_IO_DEVICE *\r
GetRootBridgeByHandle (\r
EFI_HANDLE RootBridgeHandle\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
+ );\r
\r
-Arguments:\r
\r
- RootBridgeHandle - TODO: add argument description\r
+/**\r
+ Judege whether Pci device existed.\r
\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
-\r
-BOOLEAN\r
-RootBridgeExisted (\r
- IN EFI_HANDLE RootBridgeHandle\r
- )\r
-/*++\r
+ @param Bridge Parent bridege instance.\r
+ @param PciIoDevice Device instance.\r
\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- RootBridgeHandle - TODO: add argument description\r
-\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @retval TRUE Pci device existed.\r
+ @retval FALSE Pci device did not exist.\r
\r
+**/\r
BOOLEAN\r
PciDeviceExisted (\r
IN PCI_IO_DEVICE *Bridge,\r
IN PCI_IO_DEVICE *PciIoDevice\r
- )\r
-/*++\r
-\r
-Routine Description:\r
+ );\r
\r
- TODO: Add function description\r
+/**\r
+ Get the active VGA device on the same segment.\r
\r
-Arguments:\r
+ @param VgaDevice PCI IO instance for the VGA device.\r
\r
- Bridge - TODO: add argument description\r
- PciIoDevice - TODO: add argument description\r
-\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @return The active VGA device on the same segment.\r
\r
+**/\r
PCI_IO_DEVICE *\r
ActiveVGADeviceOnTheSameSegment (\r
IN PCI_IO_DEVICE *VgaDevice\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ );\r
\r
- VgaDevice - TODO: add argument description\r
+/**\r
+ Get the active VGA device on the root bridge.\r
\r
-Returns:\r
+ @param RootBridge PCI IO instance for the root bridge.\r
\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ @return The active VGA device.\r
\r
+**/\r
PCI_IO_DEVICE *\r
ActiveVGADeviceOnTheRootBridge (\r
IN PCI_IO_DEVICE *RootBridge\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- RootBridge - TODO: add argument description\r
-\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
-GetHpcPciAddress (\r
- IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL *PciRootBridgeIo,\r
- IN EFI_DEVICE_PATH_PROTOCOL *HpcDevicePath,\r
- OUT UINT64 *PciAddress\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- PciRootBridgeIo - TODO: add argument description\r
- HpcDevicePath - TODO: add argument description\r
- PciAddress - TODO: add argument description\r
+ );\r
\r
-Returns:\r
+/**\r
+ Get HPC PCI address according to its device path.\r
\r
- TODO: add return values\r
+ @param RootBridge Root bridege Io instance.\r
+ @param RemainingDevicePath Given searching device path.\r
+ @param PciAddress Buffer holding searched result.\r
\r
---*/\r
-;\r
+ @retval EFI_SUCCESS PCI address was stored in PciAddress.\r
+ @retval EFI_NOT_FOUND Can not find the specific device path.\r
\r
+**/\r
EFI_STATUS\r
GetHpcPciAddressFromRootBridge (\r
IN PCI_IO_DEVICE *RootBridge,\r
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath,\r
OUT UINT64 *PciAddress\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
+ );\r
\r
- RootBridge - TODO: add argument description\r
- RemainingDevicePath - TODO: add argument description\r
- PciAddress - TODO: add argument description\r
+/**\r
+ Destroy a pci device node.\r
\r
-Returns:\r
+ All direct or indirect allocated resource for this node will be freed.\r
\r
- TODO: add return values\r
+ @param PciIoDevice A pointer to the PCI_IO_DEVICE to be destoried.\r
\r
---*/\r
-;\r
-\r
-EFI_STATUS\r
+**/\r
+VOID\r
FreePciDevice (\r
- IN PCI_IO_DEVICE *PciIoDevice\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- TODO: Add function description\r
-\r
-Arguments:\r
-\r
- PciIoDevice - TODO: add argument description\r
-\r
-Returns:\r
-\r
- TODO: add return values\r
-\r
---*/\r
-;\r
+ IN PCI_IO_DEVICE *PciIoDevice\r
+ );\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff