fixed ECC and Klocwork issues.

[mirror_edk2.git] / IntelFrameworkModulePkg / Bus / Pci / PciBusDxe / PciDeviceSupport.h

diff --git a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h
index b32dfe214a14f6f59f14fffd01855b460fa2c9d7..af162dc198c3423323545af182abb70c03a0b4ae 100644 (file)
--- a/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h
+++ b/IntelFrameworkModulePkg/Bus/Pci/PciBusDxe/PciDeviceSupport.h
@@ -1,4 +1,4 @@
-/**@file\r
+/** @file\r

 \r
 Copyright (c) 2006, Intel Corporation                                                         \r
 All rights reserved. This program and the accompanying materials                          \r
 \r
 Copyright (c) 2006, Intel Corporation                                                         \r
 All rights reserved. This program and the accompanying materials                          \r


@@ -11,208 +11,144 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 \r
 **/\r
 \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
 \r

+/**\r
+  Initialize the gPciDevicePool.\r
+**/\r

 EFI_STATUS\r
 InitializePciDevicePool (\r
   VOID\r
 EFI_STATUS\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
 \r

-Returns:\r
+/**\r
+  Insert a root bridge into PCI device pool\r

 \r
 \r

-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param RootBridge    - A pointer to the PCI_IO_DEVICE.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 InsertRootBridge (\r
   PCI_IO_DEVICE *RootBridge\r
 EFI_STATUS\r
 InsertRootBridge (\r
   PCI_IO_DEVICE *RootBridge\r

-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
+  );\r

 \r
 \r

-Arguments:\r
+/**\r
+  This function is used to insert a PCI device node under\r
+  a bridge\r

 \r
 \r

-  RootBridge  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param Bridge         A pointer to the PCI_IO_DEVICE.\r
+  @param PciDeviceNode  A pointer to the PCI_IO_DEVICE.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 InsertPciDevice (\r
   PCI_IO_DEVICE *Bridge,\r
   PCI_IO_DEVICE *PciDeviceNode\r
 EFI_STATUS\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
-\r
-Arguments:\r
-\r
-  Bridge        - TODO: add argument description\r
-  PciDeviceNode - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  );\r

 \r
 \r

+/**\r
+  Destroy root bridge and remove it from deivce tree.\r
+  \r
+  @param RootBridge   The bridge want to be removed\r
+  \r
+**/\r

 EFI_STATUS\r
 DestroyRootBridge (\r
   IN PCI_IO_DEVICE *RootBridge\r
 EFI_STATUS\r
 DestroyRootBridge (\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

 \r
 \r

-  TODO: add return values\r
+/**\r
+  Destroy all the pci device node under the bridge.\r
+  Bridge itself is not included.\r

 \r
 \r

---*/\r
-;\r
+  @param Bridge   A pointer to the PCI_IO_DEVICE.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 DestroyPciDeviceTree (\r
   IN PCI_IO_DEVICE *Bridge\r
 EFI_STATUS\r
 DestroyPciDeviceTree (\r
   IN PCI_IO_DEVICE *Bridge\r

-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
+  );\r

 \r
 \r

-  Bridge  - TODO: add argument description\r
+/**\r
+  Destroy all device nodes under the root bridge\r
+  specified by Controller.\r
+  The root bridge itself is also included.\r

 \r
 \r

-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param Controller   An efi handle.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 DestroyRootBridgeByHandle (\r
   EFI_HANDLE Controller\r
 EFI_STATUS\r
 DestroyRootBridgeByHandle (\r
   EFI_HANDLE Controller\r

-  )\r
-/*++\r
-\r
-Routine Description:\r
+  );\r

 \r
 \r

-  TODO: Add function description\r
+/**\r
+  This function registers the PCI IO device. It creates a handle for this PCI IO device\r
+  (if the handle does not exist), attaches appropriate protocols onto the handle, does\r
+  necessary initialization, and sets up parent/child relationship with its bus controller.\r

 \r
 \r

-Arguments:\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 EFI handle for the PCI IO device.\r

 \r
 \r

-  Controller  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @retval EFI_SUCCESS   - The PCI device is successfully registered.\r
+  @retval Others        - An error occurred when registering the PCI device.\r

 \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
 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
-\r
-Arguments:\r
-\r
-  Controller  - TODO: add argument description\r
-  PciIoDevice - TODO: add argument description\r
-  Handle      - TODO: add argument description\r
-\r
-Returns:\r
+  );\r

 \r
 \r

-  TODO: add return values\r
+/**\r
+  This function is used to remove the whole PCI devices from the bridge.\r

 \r
 \r

---*/\r
-;\r
+  @param RootBridgeHandle   An efi handle.\r
+  @param Bridge             A pointer to the PCI_IO_DEVICE.\r

 \r
 \r

+  @retval EFI_SUCCESS\r
+**/\r

 EFI_STATUS\r
 RemoveAllPciDeviceOnBridge (\r
   EFI_HANDLE               RootBridgeHandle,\r
   PCI_IO_DEVICE            *Bridge\r
 EFI_STATUS\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
 \r

-  RootBridgeHandle  - TODO: add argument description\r
-  Bridge            - TODO: add argument description\r
+/**\r

 \r
 \r

-Returns:\r
+  This function is used to de-register the PCI device from the EFI,\r
+  That includes un-installing PciIo protocol from the specified PCI\r
+  device handle.\r

 \r
 \r

-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param Controller   - controller handle\r
+  @param Handle       - device handle\r

 \r
 \r

+  @return Status of de-register pci device\r
+**/\r

 EFI_STATUS\r
 DeRegisterPciDevice (\r
   IN  EFI_HANDLE                     Controller,\r
   IN  EFI_HANDLE                     Handle\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

 \r
 \r

-Arguments:\r
+/**\r
+  Start to manage the PCI device on specified the root bridge or PCI-PCI Bridge\r

 \r
 \r

-  Controller  - TODO: add argument description\r
-  Handle      - TODO: add argument description\r
+  @param Controller          An efi 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
 \r

-Returns:\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

+**/\r

 EFI_STATUS\r
 StartPciDevicesOnBridge (\r
   IN EFI_HANDLE                          Controller,\r
 EFI_STATUS\r
 StartPciDevicesOnBridge (\r
   IN EFI_HANDLE                          Controller,\r


@@ -220,246 +156,135 @@ StartPciDevicesOnBridge (
   IN EFI_DEVICE_PATH_PROTOCOL            *RemainingDevicePath,\r
   IN OUT UINT8                           *NumberOfChildren,\r
   IN OUT EFI_HANDLE                      *ChildHandleBuffer\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
 \r

-Arguments:\r
+/**\r
+  Start to manage all the PCI devices it found previously under \r
+  the entire host bridge.\r

 \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
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param Controller          - root bridge handle.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 StartPciDevices (\r
   IN EFI_HANDLE                         Controller\r
 EFI_STATUS\r
 StartPciDevices (\r
   IN EFI_HANDLE                         Controller\r

-  )\r
-/*++\r
+  );\r

 \r
 \r

-Routine Description:\r
+/**\r
+  Create root bridge device\r

 \r
 \r

-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  Controller          - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param RootBridgeHandle   - Parent bridge handle.\r

 \r
 \r

+  @return pointer to new root bridge \r
+**/\r

 PCI_IO_DEVICE *\r
 CreateRootBridge (\r
   IN EFI_HANDLE RootBridgeHandle\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

 \r
 \r

-Arguments:\r
+/**\r
+  Get root bridge device instance by specific handle.\r

 \r
 \r

-  RootBridgeHandle  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
+  @param RootBridgeHandle    Given root bridge handle.\r

 \r
 \r

+  @return root bridge device instance.\r
+**/\r

 PCI_IO_DEVICE *\r
 GetRootBridgeByHandle (\r
   EFI_HANDLE RootBridgeHandle\r
 PCI_IO_DEVICE *\r
 GetRootBridgeByHandle (\r
   EFI_HANDLE RootBridgeHandle\r

-  )\r
-/*++\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

 \r
 \r

-  TODO: add return values\r
+/**\r
+  Check root bridge device is existed or not.\r

 \r
 \r

---*/\r
-;\r
+  @param RootBridgeHandle    Given root bridge handle.\r

 \r
 \r

+  @return root bridge device is existed or not.\r
+**/\r

 BOOLEAN\r
 RootBridgeExisted (\r
   IN EFI_HANDLE RootBridgeHandle\r
 BOOLEAN\r
 RootBridgeExisted (\r
   IN EFI_HANDLE RootBridgeHandle\r

-  )\r
-/*++\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
-\r
+  );\r
+\r
+/**\r
+  Judege whether Pci device existed.\r
+  \r
+  @param Bridge       Parent bridege instance. \r
+  @param PciIoDevice  Device instance.\r
+  \r
+  @return whether Pci device existed.\r
+**/\r

 BOOLEAN\r
 PciDeviceExisted (\r
   IN PCI_IO_DEVICE    *Bridge,\r
   IN PCI_IO_DEVICE    *PciIoDevice\r
 BOOLEAN\r
 PciDeviceExisted (\r
   IN PCI_IO_DEVICE    *Bridge,\r
   IN PCI_IO_DEVICE    *PciIoDevice\r

-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\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
-\r
+  );\r
+\r
+/**\r
+  Active VGA device.\r
+  \r
+  @param VgaDevice device instance for VGA.\r
+  \r
+  @return device instance.\r
+**/\r

 PCI_IO_DEVICE *\r
 ActiveVGADeviceOnTheSameSegment (\r
   IN PCI_IO_DEVICE        *VgaDevice\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
-  VgaDevice - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
-\r
+  );\r
+\r
+/**\r
+  Active VGA device on root bridge.\r
+  \r
+  @param RootBridge  Root bridge device instance.\r
+  \r
+  @return VGA device instance.\r
+**/\r

 PCI_IO_DEVICE *\r
 ActiveVGADeviceOnTheRootBridge (\r
   IN PCI_IO_DEVICE        *RootBridge\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
+  );\r
+\r
+/**\r
+  Get HPC PCI address according to its device path.\r
+  @param PciRootBridgeIo   Root bridege Io instance.\r
+  @param HpcDevicePath     Given searching device path.\r
+  @param PciAddress        Buffer holding searched result.\r
+  \r
+  @retval EFI_NOT_FOUND Can not find the specific device path.\r
+  @retval EFI_SUCCESS   Success to get the device path.\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
 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
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r
-;\r
-\r
+  );\r
+\r
+/**\r
+  Get HPC PCI address according to its device path.\r
+  @param RootBridge           Root bridege Io instance.\r
+  @param RemainingDevicePath  Given searching device path.\r
+  @param PciAddress           Buffer holding searched result.\r
+  \r
+  @retval EFI_NOT_FOUND Can not find the specific device path.\r
+**/\r

 EFI_STATUS\r
 GetHpcPciAddressFromRootBridge (\r
   IN  PCI_IO_DEVICE                    *RootBridge,\r
   IN  EFI_DEVICE_PATH_PROTOCOL         *RemainingDevicePath,\r
   OUT UINT64                           *PciAddress\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
-  RootBridge          - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-  PciAddress          - TODO: add argument description\r
-\r
-Returns:\r
+  );\r

 \r
 \r

-  TODO: add return values\r
+/**\r
+  Destroy a pci device node.\r
+  Also all direct or indirect allocated resource for this node will be freed.\r

 \r
 \r

---*/\r
-;\r
+  @param PciIoDevice  A pointer to the PCI_IO_DEVICE.\r

 \r
 \r

+**/\r

 EFI_STATUS\r
 FreePciDevice (\r
   IN PCI_IO_DEVICE *PciIoDevice\r
 EFI_STATUS\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
+  );\r

 \r
 #endif\r
 \r
 #endif\r