Refine the file/function comments to follow doxygen format

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@10359 6f19259b-4bc3-4df7-8a09-765794883524

5 files changed, 485 insertions, 252 deletions

diff --git a/PcAtChipsetPkg/IsaAcpiDxe/ComponentName.c b/PcAtChipsetPkg/IsaAcpiDxe/ComponentName.c
index 9b88dcf..5240486 100644
--- a/PcAtChipsetPkg/IsaAcpiDxe/ComponentName.c
+++ b/PcAtChipsetPkg/IsaAcpiDxe/ComponentName.c
@@ -1,28 +1,60 @@
-/*++

+/** @file

+    UEFI Component Name(2) protocol implementation for IsaAcpi driver.

 

-Copyright (c) 2006 - 2007, Intel Corporation                                                         

-All rights reserved. This program and the accompanying materials                          

+Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved. <BR>

+This program and the accompanying materials                          

 are licensed and made available under the terms and conditions of the BSD License         

 which accompanies this distribution.  The full text of the license may be found at        

 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.             

+**/

 

+#include "PcatIsaAcpi.h"

 

-Module Name:

+//

+// EFI Component Name Functions

+//

+/**

+  Retrieves a Unicode string that is the user readable name of the driver.

 

-  ComponentName.c

+  This function retrieves the user readable name of a driver in the form of a

+  Unicode string. If the driver specified by This has a user readable name in

+  the language specified by Language, then a pointer to the driver name is

+  returned in DriverName, and EFI_SUCCESS is returned. If the driver specified

+  by This does not support the language specified by Language,

+  then EFI_UNSUPPORTED is returned.

 

-Abstract:

+  @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or

+                                EFI_COMPONENT_NAME_PROTOCOL instance.

 

---*/

+  @param  Language[in]          A pointer to a Null-terminated ASCII string

+                                array indicating the language. This is the

+                                language of the driver name that the caller is

+                                requesting, and it must match one of the

+                                languages specified in SupportedLanguages. The

+                                number of languages supported by a driver is up

+                                to the driver writer. Language is specified

+                                in RFC 4646 or ISO 639-2 language code format.

 

-#include "PcatIsaAcpi.h"

+  @param  DriverName[out]       A pointer to the Unicode string to return.

+                                This Unicode string is the name of the

+                                driver specified by This in the language

+                                specified by Language.

 

-//

-// EFI Component Name Functions

-//

+  @retval EFI_SUCCESS           The Unicode string for the Driver specified by

+                                This and the language specified by Language was

+                                returned in DriverName.

+

+  @retval EFI_INVALID_PARAMETER Language is NULL.

+

+  @retval EFI_INVALID_PARAMETER DriverName is NULL.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This does not support

+                                the language specified by Language.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiComponentNameGetDriverName (

@@ -31,6 +63,74 @@ PcatIsaAcpiComponentNameGetDriverName (
   OUT CHAR16                       **DriverName

   );

 

+/**

+  Retrieves a Unicode string that is the user readable name of the controller

+  that is being managed by a driver.

+

+  This function retrieves the user readable name of the controller specified by

+  ControllerHandle and ChildHandle in the form of a Unicode string. If the

+  driver specified by This has a user readable name in the language specified by

+  Language, then a pointer to the controller name is returned in ControllerName,

+  and EFI_SUCCESS is returned.  If the driver specified by This is not currently

+  managing the controller specified by ControllerHandle and ChildHandle,

+  then EFI_UNSUPPORTED is returned.  If the driver specified by This does not

+  support the language specified by Language, then EFI_UNSUPPORTED is returned.

+

+  @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or

+                                EFI_COMPONENT_NAME_PROTOCOL instance.

+

+  @param  ControllerHandle[in]  The handle of a controller that the driver

+                                specified by This is managing.  This handle

+                                specifies the controller whose name is to be

+                                returned.

+

+  @param  ChildHandle[in]       The handle of the child controller to retrieve

+                                the name of.  This is an optional parameter that

+                                may be NULL.  It will be NULL for device

+                                drivers.  It will also be NULL for a bus drivers

+                                that wish to retrieve the name of the bus

+                                controller.  It will not be NULL for a bus

+                                driver that wishes to retrieve the name of a

+                                child controller.

+

+  @param  Language[in]          A pointer to a Null-terminated ASCII string

+                                array indicating the language.  This is the

+                                language of the driver name that the caller is

+                                requesting, and it must match one of the

+                                languages specified in SupportedLanguages. The

+                                number of languages supported by a driver is up

+                                to the driver writer. Language is specified in

+                                RFC 4646 or ISO 639-2 language code format.

+

+  @param  ControllerName[out]   A pointer to the Unicode string to return.

+                                This Unicode string is the name of the

+                                controller specified by ControllerHandle and

+                                ChildHandle in the language specified by

+                                Language from the point of view of the driver

+                                specified by This.

+

+  @retval EFI_SUCCESS           The Unicode string for the user readable name in

+                                the language specified by Language for the

+                                driver specified by This was returned in

+                                DriverName.

+

+  @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.

+

+  @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid

+                                EFI_HANDLE.

+

+  @retval EFI_INVALID_PARAMETER Language is NULL.

+

+  @retval EFI_INVALID_PARAMETER ControllerName is NULL.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This is not currently

+                                managing the controller specified by

+                                ControllerHandle and ChildHandle.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This does not support

+                                the language specified by Language.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiComponentNameGetControllerName (

@@ -69,6 +169,45 @@ EFI_UNICODE_STRING_TABLE mPcatIsaAcpiDriverNameTable[] = {
   }

 };

 

+/**

+  Retrieves a Unicode string that is the user readable name of the driver.

+

+  This function retrieves the user readable name of a driver in the form of a

+  Unicode string. If the driver specified by This has a user readable name in

+  the language specified by Language, then a pointer to the driver name is

+  returned in DriverName, and EFI_SUCCESS is returned. If the driver specified

+  by This does not support the language specified by Language,

+  then EFI_UNSUPPORTED is returned.

+

+  @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or

+                                EFI_COMPONENT_NAME_PROTOCOL instance.

+

+  @param  Language[in]          A pointer to a Null-terminated ASCII string

+                                array indicating the language. This is the

+                                language of the driver name that the caller is

+                                requesting, and it must match one of the

+                                languages specified in SupportedLanguages. The

+                                number of languages supported by a driver is up

+                                to the driver writer. Language is specified

+                                in RFC 4646 or ISO 639-2 language code format.

+

+  @param  DriverName[out]       A pointer to the Unicode string to return.

+                                This Unicode string is the name of the

+                                driver specified by This in the language

+                                specified by Language.

+

+  @retval EFI_SUCCESS           The Unicode string for the Driver specified by

+                                This and the language specified by Language was

+                                returned in DriverName.

+

+  @retval EFI_INVALID_PARAMETER Language is NULL.

+

+  @retval EFI_INVALID_PARAMETER DriverName is NULL.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This does not support

+                                the language specified by Language.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiComponentNameGetDriverName (

@@ -76,32 +215,6 @@ PcatIsaAcpiComponentNameGetDriverName (
   IN  CHAR8                        *Language,

   OUT CHAR16                       **DriverName

   )

-/*++

-

-  Routine Description:

-    Retrieves a Unicode string that is the user readable name of the EFI Driver.

-

-  Arguments:

-    This       - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.

-    Language   - A pointer to a three character ISO 639-2 language identifier.

-                 This is the language of the driver name that that the caller 

-                 is requesting, and it must match one of the languages specified

-                 in SupportedLanguages.  The number of languages supported by a 

-                 driver is up to the driver writer.

-    DriverName - A pointer to the Unicode string to return.  This Unicode string

-                 is the name of the driver specified by This in the language 

-                 specified by Language.

-

-  Returns:

-    EFI_SUCCES            - The Unicode string for the Driver specified by This

-                            and the language specified by Language was returned 

-                            in DriverName.

-    EFI_INVALID_PARAMETER - Language is NULL.

-    EFI_INVALID_PARAMETER - DriverName is NULL.

-    EFI_UNSUPPORTED       - The driver specified by This does not support the 

-                            language specified by Language.

-

---*/

 {

   return LookupUnicodeString2 (

            Language,

@@ -112,6 +225,74 @@ PcatIsaAcpiComponentNameGetDriverName (
            );

 }

 

+/**

+  Retrieves a Unicode string that is the user readable name of the controller

+  that is being managed by a driver.

+

+  This function retrieves the user readable name of the controller specified by

+  ControllerHandle and ChildHandle in the form of a Unicode string. If the

+  driver specified by This has a user readable name in the language specified by

+  Language, then a pointer to the controller name is returned in ControllerName,

+  and EFI_SUCCESS is returned.  If the driver specified by This is not currently

+  managing the controller specified by ControllerHandle and ChildHandle,

+  then EFI_UNSUPPORTED is returned.  If the driver specified by This does not

+  support the language specified by Language, then EFI_UNSUPPORTED is returned.

+

+  @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or

+                                EFI_COMPONENT_NAME_PROTOCOL instance.

+

+  @param  ControllerHandle[in]  The handle of a controller that the driver

+                                specified by This is managing.  This handle

+                                specifies the controller whose name is to be

+                                returned.

+

+  @param  ChildHandle[in]       The handle of the child controller to retrieve

+                                the name of.  This is an optional parameter that

+                                may be NULL.  It will be NULL for device

+                                drivers.  It will also be NULL for a bus drivers

+                                that wish to retrieve the name of the bus

+                                controller.  It will not be NULL for a bus

+                                driver that wishes to retrieve the name of a

+                                child controller.

+

+  @param  Language[in]          A pointer to a Null-terminated ASCII string

+                                array indicating the language.  This is the

+                                language of the driver name that the caller is

+                                requesting, and it must match one of the

+                                languages specified in SupportedLanguages. The

+                                number of languages supported by a driver is up

+                                to the driver writer. Language is specified in

+                                RFC 4646 or ISO 639-2 language code format.

+

+  @param  ControllerName[out]   A pointer to the Unicode string to return.

+                                This Unicode string is the name of the

+                                controller specified by ControllerHandle and

+                                ChildHandle in the language specified by

+                                Language from the point of view of the driver

+                                specified by This.

+

+  @retval EFI_SUCCESS           The Unicode string for the user readable name in

+                                the language specified by Language for the

+                                driver specified by This was returned in

+                                DriverName.

+

+  @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.

+

+  @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid

+                                EFI_HANDLE.

+

+  @retval EFI_INVALID_PARAMETER Language is NULL.

+

+  @retval EFI_INVALID_PARAMETER ControllerName is NULL.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This is not currently

+                                managing the controller specified by

+                                ControllerHandle and ChildHandle.

+

+  @retval EFI_UNSUPPORTED       The driver specified by This does not support

+                                the language specified by Language.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiComponentNameGetControllerName (

@@ -121,50 +302,6 @@ PcatIsaAcpiComponentNameGetControllerName (
   IN  CHAR8                        *Language,

   OUT CHAR16                       **ControllerName

   )

-/*++

-

-  Routine Description:

-    Retrieves a Unicode string that is the user readable name of the controller

-    that is being managed by an EFI Driver.

-

-  Arguments:

-    This             - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.

-    ControllerHandle - The handle of a controller that the driver specified by 

-                       This is managing.  This handle specifies the controller 

-                       whose name is to be returned.

-    ChildHandle      - The handle of the child controller to retrieve the name 

-                       of.  This is an optional parameter that may be NULL.  It 

-                       will be NULL for device drivers.  It will also be NULL 

-                       for a bus drivers that wish to retrieve the name of the 

-                       bus controller.  It will not be NULL for a bus driver 

-                       that wishes to retrieve the name of a child controller.

-    Language         - A pointer to a three character ISO 639-2 language 

-                       identifier.  This is the language of the controller name 

-                       that that the caller is requesting, and it must match one

-                       of the languages specified in SupportedLanguages.  The 

-                       number of languages supported by a driver is up to the 

-                       driver writer.

-    ControllerName   - A pointer to the Unicode string to return.  This Unicode

-                       string is the name of the controller specified by 

-                       ControllerHandle and ChildHandle in the language specified

-                       by Language from the point of view of the driver specified

-                       by This. 

-

-  Returns:

-    EFI_SUCCESS           - The Unicode string for the user readable name in the 

-                            language specified by Language for the driver 

-                            specified by This was returned in DriverName.

-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.

-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE.

-    EFI_INVALID_PARAMETER - Language is NULL.

-    EFI_INVALID_PARAMETER - ControllerName is NULL.

-    EFI_UNSUPPORTED       - The driver specified by This is not currently managing 

-                            the controller specified by ControllerHandle and 

-                            ChildHandle.

-    EFI_UNSUPPORTED       - The driver specified by This does not support the 

-                            language specified by Language.

-

---*/

 {

   return EFI_UNSUPPORTED;

 }

diff --git a/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.c b/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.c
index 5eba859..65b54d9 100644
--- a/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.c
+++ b/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.c
@@ -1,26 +1,15 @@
-/*++

+/** @file

+  ISA ACPI Protocol Implementation

 

-Copyright (c) 2006, Intel Corporation                                                         

-All rights reserved. This program and the accompanying materials                          

+Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved. <BR>

+This program and the accompanying materials                          

 are licensed and made available under the terms and conditions of the BSD License         

 which accompanies this distribution.  The full text of the license may be found at        

 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:

-

-  IsaAcpi.c

-    

-Abstract: 

-  

-    ISA ACPI Protocol Implementation

-

-Revision History

-

---*/

+**/

 

 #include "PcatIsaAcpi.h"

 

@@ -90,22 +79,19 @@ EFI_ISA_ACPI_RESOURCE_LIST gPcatIsaAcpiDeviceList[] = {
 //

 // ISA ACPI Protocol Functions

 //

+/**

+  Enumerate the ISA devices on the ISA bus.

+

+  @param Device             Point to device ID instance 

+  @param IsaAcpiDevice      On return, point to resource data for Isa device

+  @param NextIsaAcpiDevice  On return, point to resource data for next Isa device

+**/

 VOID

 IsaDeviceLookup (

   IN  EFI_ISA_ACPI_DEVICE_ID      *Device,

   OUT EFI_ISA_ACPI_RESOURCE_LIST  **IsaAcpiDevice,

   OUT EFI_ISA_ACPI_RESOURCE_LIST  **NextIsaAcpiDevice

   )

-/*++

-

-Routine Description:

-  Enumerate the ISA devices on the ISA bus

-

-Arguments:

-

-Returns:

-

---*/

 {

   UINTN  Index;

 

@@ -133,22 +119,23 @@ Returns:
   }

 }

 

+/**

+  Enumerate the ISA devices on the ISA bus

+

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+

+  @retval EFI_NOT_FOUND Can not found the next Isa device.

+  @retval EFI_SUCESS    Success retrieve the next Isa device for enumration.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaDeviceEnumerate (

   IN  EFI_ISA_ACPI_PROTOCOL   *This,

   OUT EFI_ISA_ACPI_DEVICE_ID  **Device

   )

-/*++

-

-Routine Description:

-  Enumerate the ISA devices on the ISA bus

-

-Arguments:

-

-Returns:

-

---*/

 {

   EFI_ISA_ACPI_RESOURCE_LIST  *IsaAcpiDevice;

   EFI_ISA_ACPI_RESOURCE_LIST  *NextIsaAcpiDevice;

@@ -161,6 +148,17 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  Set ISA device power

+

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param OnOff           TRUE for setting isa device power on,

+                         FALSE for setting isa device power off

+

+  @return EFI_SUCCESS    Sucess to change power status for isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaDeviceSetPower (

@@ -168,20 +166,20 @@ IsaDeviceSetPower (
   IN EFI_ISA_ACPI_DEVICE_ID  *Device,

   IN BOOLEAN                 OnOff

   )

-/*++

-

-Routine Description:

-  Set ISA device power 

-

-Arguments:

-

-Returns:

-

---*/

 {

   return EFI_SUCCESS;

 } 

 

+/**

+  Get current resource for the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    On return, point to resources instances for given isa device

+

+  @retval EFI_NOT_FOUND Can not found the resource instance for given isa device

+  @retval EFI_SUCCESS   Success to get resource instance for given isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaGetCurrentResource (

@@ -189,16 +187,6 @@ IsaGetCurrentResource (
   IN  EFI_ISA_ACPI_DEVICE_ID      *Device,  

   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList

   )

-/*++

-

-Routine Description:

-  Get current Resource of the specific ISA device

-

-Arguments:

-

-Returns:

-

---*/

 {

   IsaDeviceLookup (Device, ResourceList, NULL);

   if (*ResourceList == NULL) {

@@ -207,6 +195,15 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  Get possible resource for the specific ISA device.

+  

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    On return, point to resources instances for given isa device

+

+  @retval EFI_SUCCESS   Success to get resource instance for given isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaGetPossibleResource (

@@ -214,19 +211,20 @@ IsaGetPossibleResource (
   IN  EFI_ISA_ACPI_DEVICE_ID      *Device,  

   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList

   )

-/*++

-

-Routine Description:

-

-Arguments:

-

-Returns:

-

---*/ 

 {

   return EFI_SUCCESS;

 }

 

+/**

+  Set resource for the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    Point to resources instances for given isa device

+

+  @return EFI_SUCESS  Success to set resource.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaSetResource (

@@ -234,19 +232,20 @@ IsaSetResource (
   IN EFI_ISA_ACPI_DEVICE_ID      *Device,  

   IN EFI_ISA_ACPI_RESOURCE_LIST  *ResourceList

   )

-/*++

-

-Routine Description:

-

-Arguments:

-

-Returns:

-

---*/

 {

   return EFI_SUCCESS;

 }

         

+/**

+  Enable/Disable the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param Enable          Enable/Disable

+

+  @return EFI_SUCESS  Success to enable/disable.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaEnableDevice (

@@ -254,53 +253,43 @@ IsaEnableDevice (
   IN EFI_ISA_ACPI_DEVICE_ID  *Device,

   IN BOOLEAN                 Enable

   )

-/*++

-

-Routine Description:

-

-Arguments:

-

-Returns:

-

---*/

 {

   return EFI_SUCCESS;  

 }

 

+/**

+  Initialize the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+

+  @return EFI_SUCESS  Success to initialize.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaInitDevice (

   IN EFI_ISA_ACPI_PROTOCOL   *This,

   IN EFI_ISA_ACPI_DEVICE_ID  *Device

   )

-/*++

-

-Routine Description:

-

-Arguments:

-

-Returns:

-

---*/

 {

   return EFI_SUCCESS;

 }

 

 

+/**

+  Initialize the ISA interface.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+

+  @return EFI_SUCESS  Success to initialize ISA interface.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaInterfaceInit (

   IN EFI_ISA_ACPI_PROTOCOL  *This

 )  

-/*++

-

-Routine Description:

-

-Arguments:

-

-Returns:

-

---*/

 {

   return EFI_SUCCESS;

 }  

diff --git a/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.inf b/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.inf
index 144263c..d49458a 100644
--- a/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.inf
+++ b/PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.inf
@@ -1,7 +1,8 @@
 ## @file

-# 

-# Copyright (c) 2005 - 2010, Intel Corporation                                                         

-# All rights reserved. This program and the accompanying materials                          

+#   Component description file for PCAT ISA ACPI driver

+#

+# Copyright (c) 2005 - 2010, Intel Corporation. All rights reserved. <BR>

+# This program and the accompanying materials                          

 # are licensed and made available under the terms and conditions of the BSD License         

 # which accompanies this distribution.  The full text of the license may be found at        

 # http://opensource.org/licenses/bsd-license.php                                            

@@ -9,11 +10,6 @@
 # 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:

-#   IsaAcpi.inf

-#

-#  Abstract:

-#    Component description file for PCAT ISA ACPI driver

 #

 ##

 

diff --git a/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.c b/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.c
index 9de878f..3965547 100644
--- a/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.c
+++ b/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.c
@@ -1,14 +1,14 @@
 /** @file

   EFI PCAT ISA ACPI Driver for a Generic PC Platform

 

-  Copyright (c) 2006, 2009, 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

-  which accompanies this distribution.  The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php

+Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved. <BR>

+This program and the accompanying materials

+are licensed and made available under the terms and conditions of the BSD License

+which accompanies this distribution.  The full text of the license may be found at

+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.

+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

 **/

 

@@ -26,22 +26,20 @@ EFI_DRIVER_BINDING_PROTOCOL gPcatIsaAcpiDriverBinding = {
   NULL

 };

 

+/**

+  the entry point of the PcatIsaAcpi driver.

+

+  @param ImageHandle     Handle for driver image

+  @param SystemTable     Point to EFI_SYSTEM_TABLE

+

+  @return Sucess or not for installing driver binding protocol

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverEntryPoint (

   IN EFI_HANDLE        ImageHandle,

   IN EFI_SYSTEM_TABLE  *SystemTable

   )

-/*++

-  

-  Routine Description:

-    the entry point of the PcatIsaAcpi driver

-  

-  Arguments:

-  

-  Returns:

-    

---*/                

 {

   return EfiLibInstallDriverBindingComponentName2 (

            ImageHandle, 

@@ -53,6 +51,17 @@ PcatIsaAcpiDriverEntryPoint (
            );

 }

 

+/**

+  ControllerDriver Protocol Method

+

+  @param This                 Driver Binding protocol instance pointer.   

+  @param Controller           Handle of device to test.

+  @param RemainingDevicePath  Optional parameter use to pick a specific child

+                              device to start.

+  @retval EFI_SUCCESS         This driver supports this device.

+  @retval other               This driver does not support this device.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingSupported (

@@ -60,17 +69,6 @@ PcatIsaAcpiDriverBindingSupported (
   IN EFI_HANDLE                   Controller,

   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   )

-/*++

-

-Routine Description:

-

-  ControllerDriver Protocol Method

-

-Arguments:

-

-Returns:

-

---*/

 {

   EFI_STATUS           Status;

   EFI_PCI_IO_PROTOCOL  *PciIo;

@@ -131,6 +129,18 @@ Returns:
   return Status;

 }

 

+/**

+  Install EFI_ISA_ACPI_PROTOCOL.

+

+  @param  This                 Driver Binding protocol instance pointer.

+  @param  ControllerHandle     Handle of device to bind driver to.

+  @param  RemainingDevicePath  Optional parameter use to pick a specific child

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle

+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

+  @retval other                This driver does not support this device

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingStart (

@@ -138,16 +148,6 @@ PcatIsaAcpiDriverBindingStart (
   IN EFI_HANDLE                   Controller,

   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   )

-/*++

-

-Routine Description:

-  Install EFI_ISA_ACPI_PROTOCOL

-

-Arguments:

-

-Returns:

-

---*/

 {

   EFI_STATUS           Status;

   EFI_PCI_IO_PROTOCOL  *PciIo;

@@ -246,6 +246,21 @@ Done:
   return EFI_SUCCESS;

 }

 

+

+/**

+  Stop this driver on ControllerHandle. Support stopping any child handles

+  created by this driver.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle

+  @retval other             This driver was not removed from this device

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingStop (

@@ -254,15 +269,6 @@ PcatIsaAcpiDriverBindingStop (
   IN UINTN                        NumberOfChildren,

   IN EFI_HANDLE                   *ChildHandleBuffer

   )

-/*++

-

-  Routine Description:

-

-  Arguments:

-

-  Returns:

-

---*/

 {

   EFI_STATUS             Status;

   EFI_ISA_ACPI_PROTOCOL  *IsaAcpi;

diff --git a/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.h b/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.h
index 8608156b..955162c 100644
--- a/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.h
+++ b/PcAtChipsetPkg/IsaAcpiDxe/PcatIsaAcpi.h
@@ -1,7 +1,8 @@
-/*++

+/** @file

+  EFI PCAT ISA ACPI Driver for a Generic PC Platform

 

-Copyright (c) 2006 - 2007, Intel Corporation                                                         

-All rights reserved. This program and the accompanying materials                          

+Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved. <BR>

+This program and the accompanying materials                          

 are licensed and made available under the terms and conditions of the BSD License         

 which accompanies this distribution.  The full text of the license may be found at        

 http://opensource.org/licenses/bsd-license.php                                            

@@ -9,18 +10,7 @@ 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:

-

-    PcatIsaAcpi.h

-    

-Abstract:

-

-    EFI PCAT ISA ACPI Driver for a Generic PC Platform

-

-Revision History

-

---*/

+**/

 

 #ifndef _PCAT_ISA_ACPI_H_

 #define _PCAT_ISA_ACPI_H_

@@ -68,6 +58,17 @@ extern EFI_COMPONENT_NAME_PROTOCOL  gPcatIsaAcpiComponentName;
 //

 // Prototypes for Driver model protocol interface

 //

+/**

+  ControllerDriver Protocol Method

+

+  @param This                 Driver Binding protocol instance pointer.   

+  @param Controller           Handle of device to test.

+  @param RemainingDevicePath  Optional parameter use to pick a specific child

+                              device to start.

+  @retval EFI_SUCCESS         This driver supports this device.

+  @retval other               This driver does not support this device.

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingSupported (

@@ -76,6 +77,18 @@ PcatIsaAcpiDriverBindingSupported (
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   );

 

+/**

+  Install EFI_ISA_ACPI_PROTOCOL.

+

+  @param  This                 Driver Binding protocol instance pointer.

+  @param  ControllerHandle     Handle of device to bind driver to.

+  @param  RemainingDevicePath  Optional parameter use to pick a specific child

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle

+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

+  @retval other                This driver does not support this device

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingStart (

@@ -84,6 +97,20 @@ PcatIsaAcpiDriverBindingStart (
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   );

 

+/**

+  Stop this driver on ControllerHandle. Support stopping any child handles

+  created by this driver.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle

+  @retval other             This driver was not removed from this device

+

+**/

 EFI_STATUS

 EFIAPI

 PcatIsaAcpiDriverBindingStop (

@@ -96,6 +123,17 @@ PcatIsaAcpiDriverBindingStop (
 //

 // Prototypes for the ISA ACPI protocol interface

 //

+/**

+  Enumerate the ISA devices on the ISA bus

+

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+

+  @retval EFI_NOT_FOUND Can not found the next Isa device.

+  @retval EFI_SUCESS    Success retrieve the next Isa device for enumration.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaDeviceEnumerate (

@@ -103,6 +141,17 @@ IsaDeviceEnumerate (
   OUT EFI_ISA_ACPI_DEVICE_ID  **Device

   );

 

+/**

+  Set ISA device power

+

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param OnOff           TRUE for setting isa device power on,

+                         FALSE for setting isa device power off

+

+  @return EFI_SUCCESS    Sucess to change power status for isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaDeviceSetPower (

@@ -111,6 +160,16 @@ IsaDeviceSetPower (
   IN BOOLEAN                 OnOff

   );

   

+/**

+  Get current resource for the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    On return, point to resources instances for given isa device

+

+  @retval EFI_NOT_FOUND Can not found the resource instance for given isa device

+  @retval EFI_SUCCESS   Success to get resource instance for given isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaGetCurrentResource (

@@ -119,6 +178,15 @@ IsaGetCurrentResource (
   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList

   );

   

+/**

+  Get possible resource for the specific ISA device.

+  

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    On return, point to resources instances for given isa device

+

+  @retval EFI_SUCCESS   Success to get resource instance for given isa device.

+**/

 EFI_STATUS

 EFIAPI

 IsaGetPossibleResource (

@@ -127,6 +195,16 @@ IsaGetPossibleResource (
   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList

   );

   

+/**

+  Set resource for the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param ResourceList    Point to resources instances for given isa device

+

+  @return EFI_SUCESS  Success to set resource.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaSetResource (

@@ -135,6 +213,16 @@ IsaSetResource (
   IN EFI_ISA_ACPI_RESOURCE_LIST  *ResourceList

   );

   

+/**

+  Enable/Disable the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+  @param Enable          Enable/Disable

+

+  @return EFI_SUCESS  Success to enable/disable.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaEnableDevice (

@@ -143,6 +231,15 @@ IsaEnableDevice (
   IN BOOLEAN                 Enable

   );

 

+/**

+  Initialize the specific ISA device.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+  @param Device          Point to device ID instance 

+

+  @return EFI_SUCESS  Success to initialize.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaInitDevice (

@@ -150,6 +247,14 @@ IsaInitDevice (
   IN EFI_ISA_ACPI_DEVICE_ID  *Device

   );

   

+/**

+  Initialize the ISA interface.

+

+  @param This            Point to instance of EFI_ISA_ACPI_PROTOCOL

+

+  @return EFI_SUCESS  Success to initialize ISA interface.

+

+**/

 EFI_STATUS

 EFIAPI

 IsaInterfaceInit (