Update comments to conform to the new, Doxygen friendly, coding standard. These...

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

diff --git a/EdkModulePkg/Application/HelloWorld/HelloWorld.c b/EdkModulePkg/Application/HelloWorld/HelloWorld.c
index f3eda071e45870095435e70c37a0145f155d811b..d3714ebca581be718d6305cf7a142626b2545660 100644 (file)
--- a/EdkModulePkg/Application/HelloWorld/HelloWorld.c
+++ b/EdkModulePkg/Application/HelloWorld/HelloWorld.c
@@ -1,23 +1,16 @@
-/*++\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
-\r
-Module Name:\r
+/** @file\r
+  This driver supports platform security service\r

 \r
 \r

-  HelloWorld.c\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
 \r

-Abstract:\r
-  \r
-  This driver supports platform security service\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
+**/\r

 \r
 VOID\r
 Print (\r
 \r
 VOID\r
 Print (\r

diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c
index 6fe81d1521d8e4cd7aff471f81e3029a2ad66481..1bdce40f67d0c36552ec3551a04d16f74a225202 100644 (file)
--- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c
+++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c
@@ -1,23 +1,14 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-    AtapiPassThru.c\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
---*/\r
+**/\r

 \r
 #include "AtapiPassThru.h"\r
 \r
 \r
 #include "AtapiPassThru.h"\r
 \r


@@ -46,9 +37,9 @@ AtapiScsiPassThruDriverBindingStop (
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   );\r
 \r
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   );\r
 \r

-//\r
-// IDE registers' fixed address\r
-//\r
+///\r
+/// IDE registers' fixed address\r
+///\r

 static IDE_BASE_REGISTERS   gAtapiIoPortRegisters[2] = {\r
   { 0x1f0, { 0x1f1 }, 0x1f2, 0x1f3, 0x1f4, 0x1f5, 0x1f6, { 0x1f7 }, { 0x3f6 }, 0x3f7, 0 },\r
   { 0x170, { 0x171 }, 0x172, 0x173, 0x174, 0x175, 0x176, { 0x177 }, { 0x376 }, 0x377, 0 } \r
 static IDE_BASE_REGISTERS   gAtapiIoPortRegisters[2] = {\r
   { 0x1f0, { 0x1f1 }, 0x1f2, 0x1f3, 0x1f4, 0x1f5, 0x1f6, { 0x1f7 }, { 0x3f6 }, 0x3f7, 0 },\r
   { 0x170, { 0x171 }, 0x172, 0x173, 0x174, 0x175, 0x176, { 0x177 }, { 0x376 }, 0x377, 0 } \r


@@ -56,9 +47,9 @@ static IDE_BASE_REGISTERS   gAtapiIoPortRegisters[2] = {
 \r
 static SCSI_COMMAND_SET     gEndTable = { 0xff, 0xff };\r
 \r
 \r
 static SCSI_COMMAND_SET     gEndTable = { 0xff, 0xff };\r
 \r

-//\r
-// This table contains all the supported ATAPI commands.\r
-//\r
+///\r
+/// This table contains all the supported ATAPI commands.\r
+///\r

 static SCSI_COMMAND_SET     gSupportedATAPICommands[] = {\r
   { OP_INQUIRY,                     DataIn  },\r
   { OP_LOAD_UNLOAD_CD,              NoData  },\r
 static SCSI_COMMAND_SET     gSupportedATAPICommands[] = {\r
   { OP_INQUIRY,                     DataIn  },\r
   { OP_LOAD_UNLOAD_CD,              NoData  },\r


@@ -107,6 +98,18 @@ EFI_DRIVER_BINDING_PROTOCOL gAtapiScsiPassThruDriverBinding = {
   NULL\r
 };\r
 \r
   NULL\r
 };\r
 \r

+/**\r
+  Supported.\r
+\r
+  (Standard DriverBinding Protocol Supported() function)\r
+\r
+  @return EFI_STATUS\r
+\r
+  @todo    This - add argument and description to function comment\r
+  @todo    Controller - add argument and description to function comment\r
+  @todo    RemainingDevicePath - add argument and description to function comment\r
+  @todo    EFI_UNSUPPORTED - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingSupported (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingSupported (\r


@@ -114,22 +117,6 @@ AtapiScsiPassThruDriverBindingSupported (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

-/*++\r
-  \r
-  Routine Description:\r
-    Supported.\r
-    \r
-  Arguments:\r
-    (Standard DriverBinding Protocol Supported() function)\r
-    \r
-  Returns:\r
-    EFI_STATUS\r
-  \r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    RemainingDevicePath - add argument and description to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r

 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r
 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r


@@ -186,6 +173,18 @@ AtapiScsiPassThruDriverBindingSupported (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Create handles for IDE channels specified by RemainingDevicePath.\r
+  Install SCSI Pass Thru Protocol onto each created handle.\r
+\r
+  (Standard DriverBinding Protocol Start() function)\r
+\r
+  @return EFI_STATUS\r
+\r
+  @todo    This - add argument and description to function comment\r
+  @todo    Controller - add argument and description to function comment\r
+  @todo    RemainingDevicePath - add argument and description to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingStart (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingStart (\r


@@ -193,22 +192,6 @@ AtapiScsiPassThruDriverBindingStart (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

-/*++\r
-  \r
-  Routine Description:\r
-    Create handles for IDE channels specified by RemainingDevicePath.\r
-    Install SCSI Pass Thru Protocol onto each created handle.\r
-  \r
-  Arguments:\r
-    (Standard DriverBinding Protocol Start() function)\r
-    \r
-  Returns:\r
-    EFI_STATUS\r
-    \r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    RemainingDevicePath - add argument and description to function comment\r

 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r
 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r


@@ -263,6 +246,19 @@ Done:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Stop.\r
+\r
+  (Standard DriverBinding Protocol Stop() function)\r
+\r
+  @return EFI_STATUS\r
+\r
+  @todo    This - add argument and description to function comment\r
+  @todo    Controller - add argument and description to function comment\r
+  @todo    NumberOfChildren - add argument and description to function comment\r
+  @todo    ChildHandleBuffer - add argument and description to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingStop (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverBindingStop (\r


@@ -271,23 +267,6 @@ AtapiScsiPassThruDriverBindingStop (
   IN  UINTN                           NumberOfChildren,\r
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   )\r
   IN  UINTN                           NumberOfChildren,\r
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   )\r

-/*++\r
-  \r
-  Routine Description:\r
-    Stop.\r
-  \r
-  Arguments:\r
-    (Standard DriverBinding Protocol Stop() function)\r
-  \r
-  Returns:\r
-    EFI_STATUS\r
-  \r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    NumberOfChildren - add argument and description to function comment\r
-// TODO:    ChildHandleBuffer - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   EFI_STATUS                  Status;\r
   EFI_SCSI_PASS_THRU_PROTOCOL *ScsiPassThru;\r
 {\r
   EFI_STATUS                  Status;\r
   EFI_SCSI_PASS_THRU_PROTOCOL *ScsiPassThru;\r


@@ -337,28 +316,25 @@ AtapiScsiPassThruDriverBindingStop (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Attaches SCSI Pass Thru Protocol for specified IDE channel.\r
+\r
+  @param Controller:       Parent device handle to the IDE channel.\r
+  @param PciIo:            PCI I/O protocol attached on the "Controller".\r
+\r
+  @return EFI_SUCCESS Always returned unless installing SCSI Pass Thru Protocol failed.\r
+\r
+  @todo    This - add argument and description to function comment\r
+  @todo    Controller - add argument and description to function comment\r
+  @todo    PciIo - add argument and description to function comment\r
+  @todo    EFI_OUT_OF_RESOURCES - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 RegisterAtapiScsiPassThru (\r
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN  EFI_HANDLE                  Controller,\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo\r
   )\r
 EFI_STATUS\r
 RegisterAtapiScsiPassThru (\r
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN  EFI_HANDLE                  Controller,\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo\r
   )\r

-/*++\r
-  \r
-  Routine Description:\r
-    Attaches SCSI Pass Thru Protocol for specified IDE channel.\r
-    \r
-  Arguments:\r
-    Controller:       Parent device handle to the IDE channel.    \r
-    PciIo:            PCI I/O protocol attached on the "Controller".                        \r
-  \r
-  Returns:\r
-    Always return EFI_SUCCESS unless installing SCSI Pass Thru Protocol failed.\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    PciIo - add argument and description to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r

 {\r
   EFI_STATUS                Status;\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
 {\r
   EFI_STATUS                Status;\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r


@@ -427,6 +403,29 @@ RegisterAtapiScsiPassThru (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Implements EFI_SCSI_PASS_THRU_PROTOCOL.PassThru() function.\r
+\r
+  @param This     The EFI_SCSI_PASS_THRU_PROTOCOL instance.\r
+  @param Target   The Target ID of the ATAPI device to send the SCSI\r
+  Request Packet. To ATAPI devices attached on an IDE\r
+  Channel, Target ID 0 indicates Master device;Target\r
+  ID 1 indicates Slave device.\r
+  @param Lun      The LUN of the ATAPI device to send the SCSI Request\r
+  Packet. To the ATAPI device, Lun is always 0.\r
+  @param Packet   The SCSI Request Packet to send to the ATAPI device\r
+  specified by Target and Lun.\r
+  @param Event    If non-blocking I/O is not supported then Event is ignored,\r
+  and blocking I/O is performed.<br>\r
+  If Event is NULL, then blocking I/O is performed.<br>\r
+  If Event is not NULL and non blocking I/O is supported,\r
+  then non-blocking I/O is performed, and Event will be signaled\r
+  when the SCSI Request Packet completes.\r
+\r
+  @todo    This - add argument and description to function comment\r
+  @todo    EFI_INVALID_PARAMETER - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruFunction (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruFunction (\r


@@ -436,34 +435,6 @@ AtapiScsiPassThruFunction (
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET         *Packet,\r
   IN EFI_EVENT                                          Event OPTIONAL\r
   )\r
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET         *Packet,\r
   IN EFI_EVENT                                          Event OPTIONAL\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Implements EFI_SCSI_PASS_THRU_PROTOCOL.PassThru() function.\r
-  \r
-  Arguments:\r
-    This:     The EFI_SCSI_PASS_THRU_PROTOCOL instance.\r
-    Target:   The Target ID of the ATAPI device to send the SCSI \r
-              Request Packet. To ATAPI devices attached on an IDE\r
-              Channel, Target ID 0 indicates Master device;Target\r
-              ID 1 indicates Slave device.\r
-    Lun:      The LUN of the ATAPI device to send the SCSI Request\r
-              Packet. To the ATAPI device, Lun is always 0.\r
-    Packet:   The SCSI Request Packet to send to the ATAPI device \r
-              specified by Target and Lun.\r
-    Event:    If non-blocking I/O is not supported then Event is ignored, \r
-              and blocking I/O is performed.\r
-              If Event is NULL, then blocking I/O is performed.\r
-              If Event is not NULL and non blocking I/O is supported, \r
-              then non-blocking I/O is performed, and Event will be signaled \r
-              when the SCSI Request Packet completes.      \r
-    \r
-  Returns:  \r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    EFI_INVALID_PARAMETER - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   EFI_STATUS                Status;\r
 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   EFI_STATUS                Status;\r


@@ -515,6 +486,29 @@ AtapiScsiPassThruFunction (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Used to retrieve the list of legal Target IDs for SCSI devices \r
+  on a SCSI channel.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  Target On input, a pointer to the Target ID of a SCSI\r
+  device present on the SCSI channel.  On output,\r
+  a pointer to the Target ID of the next SCSI device\r
+  present on a SCSI channel.  An input value of\r
+  0xFFFFFFFF retrieves the Target ID of the first\r
+  SCSI device present on a SCSI channel.\r
+  @param  Lun On input, a pointer to the LUN of a SCSI device\r
+  present on the SCSI channel. On output, a pointer\r
+  to the LUN of the next SCSI device present on\r
+  a SCSI channel.\r
+\r
+  @retval  EFI_SUCCESS The Target ID and Lun of the next SCSI device\r
+  on the SCSI channel was returned in Target and Lun.\r
+  @retval  EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel.\r
+  @retval  EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF,and Target and Lun were not\r
+  returned on a previous call to GetNextDevice().\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetNextDevice (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetNextDevice (\r


@@ -522,32 +516,6 @@ AtapiScsiPassThruGetNextDevice (
   IN OUT UINT32                      *Target,\r
   IN OUT UINT64                      *Lun\r
   )\r
   IN OUT UINT32                      *Target,\r
   IN OUT UINT64                      *Lun\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Used to retrieve the list of legal Target IDs for SCSI devices \r
-    on a SCSI channel.\r
-\r
-  Arguments:\r
-    This                  - Protocol instance pointer.\r
-    Target                - On input, a pointer to the Target ID of a SCSI \r
-                            device present on the SCSI channel.  On output, \r
-                            a pointer to the Target ID of the next SCSI device\r
-                             present on a SCSI channel.  An input value of \r
-                             0xFFFFFFFF retrieves the Target ID of the first \r
-                             SCSI device present on a SCSI channel.\r
-    Lun                   - On input, a pointer to the LUN of a SCSI device\r
-                            present on the SCSI channel. On output, a pointer\r
-                            to the LUN of the next SCSI device present on \r
-                            a SCSI channel.\r
-    \r
-  Returns:\r
-    EFI_SUCCESS           - The Target ID and Lun of the next SCSI device \r
-                            on the SCSI channel was returned in Target and Lun.\r
-    EFI_NOT_FOUND         - There are no more SCSI devices on this SCSI channel.\r
-    EFI_INVALID_PARAMETER - Target is not 0xFFFFFFFF,and Target and Lun were not\r
-                            returned on a previous call to GetNextDevice().\r
---*/\r

 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
 \r
 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
 \r


@@ -591,6 +559,33 @@ AtapiScsiPassThruGetNextDevice (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  Used to allocate and build a device path node for a SCSI device \r
+  on a SCSI channel. Would not build device path for a SCSI Host Controller.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  Target The Target ID of the SCSI device for which\r
+  a device path node is to be allocated and built.\r
+  @param  Lun The LUN of the SCSI device for which a device\r
+  path node is to be allocated and built.\r
+  @param  DevicePath A pointer to a single device path node that\r
+  describes the SCSI device specified by\r
+  Target and Lun. This function is responsible\r
+  for allocating the buffer DevicePath with the boot\r
+  service AllocatePool().  It is the caller's\r
+  responsibility to free DevicePath when the caller\r
+  is finished with DevicePath.\r
+\r
+  @retval  EFI_SUCCESS The device path node that describes the SCSI device\r
+  specified by Target and Lun was allocated and\r
+  returned in DevicePath.\r
+  @retval  EFI_NOT_FOUND The SCSI devices specified by Target and Lun does\r
+  not exist on the SCSI channel.\r
+  @retval  EFI_INVALID_PARAMETER DevicePath is NULL.\r
+  @retval  EFI_OUT_OF_RESOURCES There are not enough resources to allocate\r
+  DevicePath.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruBuildDevicePath (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruBuildDevicePath (\r


@@ -599,35 +594,6 @@ AtapiScsiPassThruBuildDevicePath (
   IN     UINT64                         Lun,\r
   IN OUT EFI_DEVICE_PATH_PROTOCOL       **DevicePath\r
   )\r
   IN     UINT64                         Lun,\r
   IN OUT EFI_DEVICE_PATH_PROTOCOL       **DevicePath\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Used to allocate and build a device path node for a SCSI device \r
-    on a SCSI channel. Would not build device path for a SCSI Host Controller.\r
-\r
-  Arguments:\r
-    This                  - Protocol instance pointer.\r
-    Target                - The Target ID of the SCSI device for which\r
-                            a device path node is to be allocated and built.\r
-    Lun                   - The LUN of the SCSI device for which a device \r
-                            path node is to be allocated and built.\r
-    DevicePath            - A pointer to a single device path node that \r
-                            describes the SCSI device specified by \r
-                            Target and Lun. This function is responsible \r
-                            for allocating the buffer DevicePath with the boot\r
-                            service AllocatePool().  It is the caller's \r
-                            responsibility to free DevicePath when the caller\r
-                            is finished with DevicePath.    \r
-  Returns:\r
-    EFI_SUCCESS           - The device path node that describes the SCSI device\r
-                            specified by Target and Lun was allocated and \r
-                            returned in DevicePath.\r
-    EFI_NOT_FOUND         - The SCSI devices specified by Target and Lun does\r
-                            not exist on the SCSI channel.\r
-    EFI_INVALID_PARAMETER - DevicePath is NULL.\r
-    EFI_OUT_OF_RESOURCES  - There are not enough resources to allocate \r
-                            DevicePath.\r
---*/\r

 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   EFI_DEV_PATH              *Node;\r
 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   EFI_DEV_PATH              *Node;\r


@@ -670,6 +636,29 @@ AtapiScsiPassThruBuildDevicePath (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Used to translate a device path node to a Target ID and LUN.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  DevicePath A pointer to the device path node that\r
+  describes a SCSI device on the SCSI channel.\r
+  @param  Target A pointer to the Target ID of a SCSI device\r
+  on the SCSI channel.\r
+  @param  Lun A pointer to the LUN of a SCSI device on\r
+  the SCSI channel.\r
+\r
+  @retval  EFI_SUCCESS DevicePath was successfully translated to a\r
+  Target ID and LUN, and they were returned\r
+  in Target and Lun.\r
+  @retval  EFI_INVALID_PARAMETER DevicePath is NULL.\r
+  @retval  EFI_INVALID_PARAMETER Target is NULL.\r
+  @retval  EFI_INVALID_PARAMETER Lun is NULL.\r
+  @retval  EFI_UNSUPPORTED This driver does not support the device path\r
+  node type in DevicePath.\r
+  @retval  EFI_NOT_FOUND A valid translation from DevicePath to a\r
+  Target ID and LUN does not exist.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetTargetLun (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetTargetLun (\r


@@ -678,31 +667,6 @@ AtapiScsiPassThruGetTargetLun (
   OUT UINT32                         *Target,\r
   OUT UINT64                         *Lun\r
   )\r
   OUT UINT32                         *Target,\r
   OUT UINT64                         *Lun\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Used to translate a device path node to a Target ID and LUN.\r
-\r
-  Arguments:\r
-    This                  - Protocol instance pointer.\r
-    DevicePath            - A pointer to the device path node that \r
-                            describes a SCSI device on the SCSI channel.\r
-    Target                - A pointer to the Target ID of a SCSI device \r
-                            on the SCSI channel. \r
-    Lun                   - A pointer to the LUN of a SCSI device on \r
-                            the SCSI channel.    \r
-  Returns:\r
-    EFI_SUCCESS           - DevicePath was successfully translated to a \r
-                            Target ID and LUN, and they were returned \r
-                            in Target and Lun.\r
-    EFI_INVALID_PARAMETER - DevicePath is NULL.\r
-    EFI_INVALID_PARAMETER - Target is NULL.\r
-    EFI_INVALID_PARAMETER - Lun is NULL.\r
-    EFI_UNSUPPORTED       - This driver does not support the device path \r
-                            node type in DevicePath.\r
-    EFI_NOT_FOUND         - A valid translation from DevicePath to a \r
-                            Target ID and LUN does not exist.\r
---*/\r

 {\r
   EFI_DEV_PATH  *Node;\r
 \r
 {\r
   EFI_DEV_PATH  *Node;\r
 \r


@@ -734,29 +698,26 @@ AtapiScsiPassThruGetTargetLun (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Resets a SCSI channel.This operation resets all the \r
+  SCSI devices connected to the SCSI channel.\r
+\r
+  @param  This Protocol instance pointer.\r
+\r
+  @retval  EFI_SUCCESS The SCSI channel was reset.\r
+  @retval  EFI_UNSUPPORTED The SCSI channel does not support\r
+  a channel reset operation.\r
+  @retval  EFI_DEVICE_ERROR A device error occurred while\r
+  attempting to reset the SCSI channel.\r
+  @retval  EFI_TIMEOUT A timeout occurred while attempting\r
+  to reset the SCSI channel.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetChannel (\r
   IN  EFI_SCSI_PASS_THRU_PROTOCOL   *This\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetChannel (\r
   IN  EFI_SCSI_PASS_THRU_PROTOCOL   *This\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Resets a SCSI channel.This operation resets all the \r
-    SCSI devices connected to the SCSI channel.\r
-\r
-  Arguments:\r
-    This                  - Protocol instance pointer.\r
-    \r
-  Returns:\r
-    EFI_SUCCESS           - The SCSI channel was reset.\r
-    EFI_UNSUPPORTED       - The SCSI channel does not support \r
-                            a channel reset operation.\r
-    EFI_DEVICE_ERROR      - A device error occurred while \r
-                            attempting to reset the SCSI channel.\r
-    EFI_TIMEOUT           - A timeout occurred while attempting \r
-                            to reset the SCSI channel.\r
---*/\r

 {\r
   UINT8                     DeviceControlValue;\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
 {\r
   UINT8                     DeviceControlValue;\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r


@@ -813,6 +774,25 @@ AtapiScsiPassThruResetChannel (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Resets a SCSI device that is connected to a SCSI channel.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  Target The Target ID of the SCSI device to reset.\r
+  @param  Lun The LUN of the SCSI device to reset.\r
+\r
+  @retval  EFI_SUCCESS The SCSI device specified by Target and\r
+  Lun was reset.\r
+  @retval  EFI_UNSUPPORTED The SCSI channel does not support a target\r
+  reset operation.\r
+  @retval  EFI_INVALID_PARAMETER Target or Lun are invalid.\r
+  @retval  EFI_DEVICE_ERROR A device error occurred while attempting\r
+  to reset the SCSI device specified by Target\r
+  and Lun.\r
+  @retval  EFI_TIMEOUT A timeout occurred while attempting to reset\r
+  the SCSI device specified by Target and Lun.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetTarget (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetTarget (\r


@@ -820,28 +800,6 @@ AtapiScsiPassThruResetTarget (
   IN UINT32                         Target,\r
   IN UINT64                         Lun\r
   )\r
   IN UINT32                         Target,\r
   IN UINT64                         Lun\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Resets a SCSI device that is connected to a SCSI channel.\r
-\r
-  Arguments:\r
-    This                  - Protocol instance pointer.\r
-    Target                - The Target ID of the SCSI device to reset. \r
-    Lun                   - The LUN of the SCSI device to reset.\r
-        \r
-  Returns:\r
-    EFI_SUCCESS           - The SCSI device specified by Target and \r
-                            Lun was reset.\r
-    EFI_UNSUPPORTED       - The SCSI channel does not support a target\r
-                            reset operation.\r
-    EFI_INVALID_PARAMETER - Target or Lun are invalid.\r
-    EFI_DEVICE_ERROR      - A device error occurred while attempting \r
-                            to reset the SCSI device specified by Target \r
-                            and Lun.\r
-    EFI_TIMEOUT           - A timeout occurred while attempting to reset \r
-                            the SCSI device specified by Target and Lun.\r
---*/\r

 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   UINT8                     Command;\r
 {\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate;\r
   UINT8                     Command;\r


@@ -899,25 +857,24 @@ AtapiScsiPassThruResetTarget (
 }\r
 \r
     \r
 }\r
 \r
     \r

+/**\r
+  Checks the parameters in the SCSI Request Packet to make sure\r
+  they are valid for a SCSI Pass Thru request.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    Packet - add argument and description to function comment\r
+  @todo    EFI_INVALID_PARAMETER - add return value to function comment\r
+  @todo    EFI_INVALID_PARAMETER - add return value to function comment\r
+  @todo    EFI_INVALID_PARAMETER - add return value to function comment\r
+  @todo    EFI_UNSUPPORTED - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 CheckSCSIRequestPacket (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET      *Packet\r
   )\r
 EFI_STATUS\r
 CheckSCSIRequestPacket (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET      *Packet\r
   )\r

-/*++\r
-  \r
-  Checks the parameters in the SCSI Request Packet to make sure\r
-  they are valid for a SCSI Pass Thru request.\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    Packet - add argument and description to function comment\r
-// TODO:    EFI_INVALID_PARAMETER - add return value to function comment\r
-// TODO:    EFI_INVALID_PARAMETER - add return value to function comment\r
-// TODO:    EFI_INVALID_PARAMETER - add return value to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   if (Packet == NULL) {\r
     return EFI_INVALID_PARAMETER;\r
 {\r
   if (Packet == NULL) {\r
     return EFI_INVALID_PARAMETER;\r


@@ -941,21 +898,20 @@ CheckSCSIRequestPacket (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Checks the requested SCSI command: \r
+  Is it supported by this driver?\r
+  Is the Data transfer direction reasonable?\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    Packet - add argument and description to function comment\r
+**/\r

 BOOLEAN\r
 IsCommandValid (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET   *Packet\r
   )\r
 BOOLEAN\r
 IsCommandValid (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET   *Packet\r
   )\r

-/*++\r
-  \r
-  Checks the requested SCSI command: \r
-    Is it supported by this driver?\r
-    Is the Data transfer direction reasonable?\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    Packet - add argument and description to function comment\r

 {\r
   UINT8 Index;\r
   UINT8 *OpCode;\r
 {\r
   UINT8 Index;\r
   UINT8 *OpCode;\r


@@ -995,30 +951,25 @@ IsCommandValid (
   return FALSE;\r
 }\r
 \r
   return FALSE;\r
 }\r
 \r

+/**\r
+  Performs blocking I/O request.\r
+\r
+  @param AtapiScsiPrivate   Private data structure for the specified channel.\r
+  @param Target             The Target ID of the ATAPI device to send the SCSI\r
+  Request Packet. To ATAPI devices attached on an IDE\r
+  Channel, Target ID 0 indicates Master device;Target\r
+  ID 1 indicates Slave device.\r
+  @param Packet             The SCSI Request Packet to send to the ATAPI device\r
+  specified by Target.\r
+\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+**/\r

 EFI_STATUS\r
 SubmitBlockingIoCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r
   UINT32                                    Target,\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET    *Packet\r
   )\r
 EFI_STATUS\r
 SubmitBlockingIoCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r
   UINT32                                    Target,\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET    *Packet\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-    Performs blocking I/O request.\r
-    \r
-  Arguments:\r
-    AtapiScsiPrivate:   Private data structure for the specified channel.\r
-    Target:             The Target ID of the ATAPI device to send the SCSI \r
-                        Request Packet. To ATAPI devices attached on an IDE\r
-                        Channel, Target ID 0 indicates Master device;Target\r
-                        ID 1 indicates Slave device.\r
-    Packet:             The SCSI Request Packet to send to the ATAPI device \r
-                        specified by Target.\r
-  \r
-  Returns:\r
-  \r
---*/\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r

 {\r
   UINT8       PacketCommand[12];\r
   UINT64      TimeoutInMicroSeconds;\r
 {\r
   UINT8       PacketCommand[12];\r
   UINT64      TimeoutInMicroSeconds;\r


@@ -1079,6 +1030,23 @@ Routine Description:
   return PacketCommandStatus;\r
 }\r
 \r
   return PacketCommandStatus;\r
 }\r
 \r

+/**\r
+  RequestSenseCommand\r
+\r
+  @param  AtapiScsiPrivate\r
+  @param  Target\r
+  @param  Timeout\r
+  @param  SenseData\r
+  @param  SenseDataLength\r
+\r
+  @todo Add function description\r
+  @todo  AtapiScsiPrivate TODO: add argument description\r
+  @todo  Target TODO: add argument description\r
+  @todo  Timeout TODO: add argument description\r
+  @todo  SenseData TODO: add argument description\r
+  @todo  SenseDataLength TODO: add argument description\r
+  @todo add return values\r
+**/\r

 EFI_STATUS\r
 RequestSenseCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
 EFI_STATUS\r
 RequestSenseCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r


@@ -1087,25 +1055,6 @@ RequestSenseCommand (
   VOID                        *SenseData,\r
   UINT8                       *SenseDataLength\r
   )\r
   VOID                        *SenseData,\r
   UINT8                       *SenseDataLength\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  AtapiScsiPrivate  - TODO: add argument description\r
-  Target            - TODO: add argument description\r
-  Timeout           - TODO: add argument description\r
-  SenseData         - TODO: add argument description\r
-  SenseDataLength   - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  Packet;\r
   UINT8                                   Cdb[12];\r
 {\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  Packet;\r
   UINT8                                   Cdb[12];\r


@@ -1130,6 +1079,37 @@ Returns:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Submits ATAPI command packet to the specified ATAPI device.\r
+\r
+  @param AtapiScsiPrivate:   Private data structure for the specified channel.\r
+  @param Target:             The Target ID of the ATAPI device to send the SCSI\r
+  Request Packet. To ATAPI devices attached on an IDE\r
+  Channel, Target ID 0 indicates Master device;Target\r
+  ID 1 indicates Slave device.\r
+  @param PacketCommand:      Points to the ATAPI command packet.\r
+  @param Buffer:             Points to the transferred data.\r
+  @param ByteCount:          When input,indicates the buffer size; when output,\r
+  indicates the actually transferred data size.\r
+  @param Direction:          Indicates the data transfer direction.\r
+  @param TimeoutInMicroSeconds: The timeout, in micro second units,\r
+  to use for the execution of this ATAPI command.\r
+  A TimeoutInMicroSeconds value of 0 means that\r
+  this function will wait indefinitely for the ATAPI\r
+  command to execute.\r
+  <P>\r
+  If TimeoutInMicroSeconds is greater than zero, then\r
+  this function will return EFI_TIMEOUT if the time\r
+  required to execute the ATAPI command is greater\r
+  than TimeoutInMicroSeconds.\r
+  </P>\r
+\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    PacketCommand - add argument and description to function comment\r
+  @todo    Buffer - add argument and description to function comment\r
+  @todo    ByteCount - add argument and description to function comment\r
+  @todo    Direction - add argument and description to function comment\r
+**/\r

 EFI_STATUS\r
 AtapiPacketCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
 EFI_STATUS\r
 AtapiPacketCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r


@@ -1140,42 +1120,6 @@ AtapiPacketCommand (
   DATA_DIRECTION              Direction,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
   DATA_DIRECTION              Direction,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Submits ATAPI command packet to the specified ATAPI device.\r
-    \r
-  Arguments:\r
-    AtapiScsiPrivate:   Private data structure for the specified channel.\r
-    Target:             The Target ID of the ATAPI device to send the SCSI \r
-                        Request Packet. To ATAPI devices attached on an IDE\r
-                        Channel, Target ID 0 indicates Master device;Target\r
-                        ID 1 indicates Slave device.\r
-    PacketCommand:      Points to the ATAPI command packet.\r
-    Buffer:             Points to the transferred data.\r
-    ByteCount:          When input,indicates the buffer size; when output,\r
-                        indicates the actually transferred data size.\r
-    Direction:          Indicates the data transfer direction. \r
-    TimeoutInMicroSeconds:\r
-                        The timeout, in micro second units, to use for the \r
-                        execution of this ATAPI command.\r
-                        A TimeoutInMicroSeconds value of 0 means that \r
-                        this function will wait indefinitely for the ATAPI \r
-                        command to execute.\r
-                        If TimeoutInMicroSeconds is greater than zero, then \r
-                        this function will return EFI_TIMEOUT if the time \r
-                        required to execute the ATAPI command is greater \r
-                        than TimeoutInMicroSeconds.\r
-  \r
-  Returns:\r
-\r
-\r
---*/\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    PacketCommand - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    Direction - add argument and description to function comment\r

 {\r
 \r
   UINT16      *CommandIndex;\r
 {\r
 \r
   UINT16      *CommandIndex;\r


@@ -1285,6 +1229,35 @@ AtapiPacketCommand (
           );\r
 }\r
 \r
           );\r
 }\r
 \r

+/**\r
+  Performs data transfer between ATAPI device and host after the\r
+  ATAPI command packet is sent.\r
+\r
+  @param AtapiScsiPrivate:   Private data structure for the specified channel.\r
+  @param Buffer:             Points to the transferred data.\r
+  @param ByteCount:          When input,indicates the buffer size; when output,\r
+  indicates the actually transferred data size.\r
+  @param Direction:          Indicates the data transfer direction.\r
+  @param TimeoutInMicroSeconds: The timeout, in micro second units,\r
+  to use for the execution of this ATAPI command.\r
+  A TimeoutInMicroSeconds value of 0 means that\r
+  this function will wait indefinitely for the ATAPI\r
+  command to execute.\r
+  <P>\r
+  If TimeoutInMicroSeconds is greater than zero, then\r
+  this function will return EFI_TIMEOUT if the time\r
+  required to execute the ATAPI command is greater\r
+  than TimeoutInMicroSeconds.\r
+  </P>\r
+\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    Buffer - add argument and description to function comment\r
+  @todo    ByteCount - add argument and description to function comment\r
+  @todo    Direction - add argument and description to function comment\r
+  @todo    EFI_DEVICE_ERROR - add return value to function comment\r
+  @todo    EFI_DEVICE_ERROR - add return value to function comment\r
+  @todo    EFI_WARN_BUFFER_TOO_SMALL - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtapiPassThruPioReadWriteData (\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate,\r
 EFI_STATUS\r
 AtapiPassThruPioReadWriteData (\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate,\r


@@ -1293,40 +1266,6 @@ AtapiPassThruPioReadWriteData (
   DATA_DIRECTION            Direction,\r
   UINT64                    TimeoutInMicroSeconds\r
   )\r
   DATA_DIRECTION            Direction,\r
   UINT64                    TimeoutInMicroSeconds\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Performs data transfer between ATAPI device and host after the\r
-    ATAPI command packet is sent.\r
-    \r
-  Arguments:\r
-    AtapiScsiPrivate:   Private data structure for the specified channel.    \r
-    Buffer:             Points to the transferred data.\r
-    ByteCount:          When input,indicates the buffer size; when output,\r
-                        indicates the actually transferred data size.\r
-    Direction:          Indicates the data transfer direction. \r
-    TimeoutInMicroSeconds:\r
-                        The timeout, in micro second units, to use for the \r
-                        execution of this ATAPI command.\r
-                        A TimeoutInMicroSeconds value of 0 means that \r
-                        this function will wait indefinitely for the ATAPI \r
-                        command to execute.\r
-                        If TimeoutInMicroSeconds is greater than zero, then \r
-                        this function will return EFI_TIMEOUT if the time \r
-                        required to execute the ATAPI command is greater \r
-                        than TimeoutInMicroSeconds.\r
-\r
-  Returns:\r
-\r
-\r
---*/\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    Direction - add argument and description to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_WARN_BUFFER_TOO_SMALL - add return value to function comment\r

 {\r
   UINT32      Index;\r
   UINT32      RequiredWordCount;\r
 {\r
   UINT32      Index;\r
   UINT32      RequiredWordCount;\r


@@ -1420,19 +1359,20 @@ AtapiPassThruPioReadWriteData (
 }\r
 \r
 \r
 }\r
 \r
 \r

+/**\r
+  Read one byte from a specified I/O port.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    PciIo - add argument and description to function comment\r
+  @todo    Port - add argument and description to function comment\r
+**/\r

 UINT8\r
 ReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r
 UINT8\r
 ReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r

-/*++\r
-  Read one byte from a specified I/O port.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    PciIo - add argument and description to function comment\r
-// TODO:    Port - add argument and description to function comment\r

 {\r
   UINT8 Data;\r
 \r
 {\r
   UINT8 Data;\r
 \r


@@ -1449,19 +1389,20 @@ ReadPortB (
 }\r
 \r
 \r
 }\r
 \r
 \r

+/**\r
+  Read one word from a specified I/O port.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    PciIo - add argument and description to function comment\r
+  @todo    Port - add argument and description to function comment\r
+**/\r

 UINT16\r
 ReadPortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r
 UINT16\r
 ReadPortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r

-/*++\r
-  Read one word from a specified I/O port.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    PciIo - add argument and description to function comment\r
-// TODO:    Port - add argument and description to function comment\r

 {\r
   UINT16  Data;\r
 \r
 {\r
   UINT16  Data;\r
 \r


@@ -1478,21 +1419,22 @@ ReadPortW (
 }\r
 \r
 \r
 }\r
 \r
 \r

+/**\r
+  Write one byte to a specified I/O port.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    PciIo - add argument and description to function comment\r
+  @todo    Port - add argument and description to function comment\r
+  @todo    Data - add argument and description to function comment\r
+**/\r

 VOID\r
 WritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r
 VOID\r
 WritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r

-/*++\r
-  Write one byte to a specified I/O port.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    PciIo - add argument and description to function comment\r
-// TODO:    Port - add argument and description to function comment\r
-// TODO:    Data - add argument and description to function comment\r

 {\r
 \r
   PciIo->Io.Write (\r
 {\r
 \r
   PciIo->Io.Write (\r


@@ -1507,21 +1449,22 @@ WritePortB (
 }\r
 \r
 \r
 }\r
 \r
 \r

+/**\r
+  Write one word to a specified I/O port.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    PciIo - add argument and description to function comment\r
+  @todo    Port - add argument and description to function comment\r
+  @todo    Data - add argument and description to function comment\r
+**/\r

 VOID\r
 WritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r
 VOID\r
 WritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r

-/*++\r
-  Write one word to a specified I/O port.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    PciIo - add argument and description to function comment\r
-// TODO:    Port - add argument and description to function comment\r
-// TODO:    Data - add argument and description to function comment\r

 {\r
 \r
   PciIo->Io.Write (\r
 {\r
 \r
   PciIo->Io.Write (\r


@@ -1534,25 +1477,26 @@ WritePortW (
               );\r
 }\r
 \r
               );\r
 }\r
 \r

+/**\r
+  Check whether DRQ is clear in the Status Register. (BSY must also be cleared)\r
+  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
+  DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
+  elapsed.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 StatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeoutInMicroSeconds\r
   )\r

-/*++\r
-  Check whether DRQ is clear in the Status Register. (BSY must also be cleared)\r
-  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
-  DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
-  elapsed.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r


@@ -1613,26 +1557,27 @@ StatusDRQClear (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-AltStatusDRQClear (\r
-  ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
-  UINT64                          TimeoutInMicroSeconds\r
-  )\r
-/*++\r
+/**\r

   Check whether DRQ is clear in the Alternate Status Register. \r
   (BSY must also be cleared).\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r
   Check whether DRQ is clear in the Alternate Status Register. \r
   (BSY must also be cleared).\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRQ clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r

---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+AltStatusDRQClear (\r
+  ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
+  UINT64                          TimeoutInMicroSeconds\r
+  )\r

 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r


@@ -1691,25 +1636,26 @@ AltStatusDRQClear (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Check whether DRQ is ready in the Status Register. (BSY must also be cleared)\r
+  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
+  DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
+  elapsed.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 StatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeoutInMicroSeconds\r
   )\r

-/*++\r
-  Check whether DRQ is ready in the Status Register. (BSY must also be cleared)\r
-  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
-  DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
-  elapsed.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r


@@ -1770,26 +1716,27 @@ StatusDRQReady (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-AltStatusDRQReady (\r
-  ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
-  UINT64                          TimeoutInMicroSeconds\r
-  )\r
-/*++\r
+/**\r

   Check whether DRQ is ready in the Alternate Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r
   Check whether DRQ is ready in the Alternate Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRQ ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r

---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+AltStatusDRQReady (\r
+  ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
+  UINT64                          TimeoutInMicroSeconds\r
+  )\r

 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r


@@ -1849,24 +1796,25 @@ AltStatusDRQReady (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Check whether BSY is clear in the Status Register.\r
+  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
+  BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
+  elapsed.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 StatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

-/*++\r
-  Check whether BSY is clear in the Status Register.\r
-  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
-  BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
-  elapsed.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r


@@ -1909,24 +1857,25 @@ StatusWaitForBSYClear (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Check whether BSY is clear in the Alternate Status Register.\r
+  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
+  BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
+  elapsed.\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AltStatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 AltStatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

-/*++\r
-  Check whether BSY is clear in the Alternate Status Register.\r
-  If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
-  BSY clear. Otherwise, it will return EFI_TIMEOUT when specified time is \r
-  elapsed.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r


@@ -1968,26 +1917,27 @@ AltStatusWaitForBSYClear (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-StatusDRDYReady (\r
-  ATAPI_SCSI_PASS_THRU_DEV     *AtapiScsiPrivate,\r
-  UINT64                       TimeoutInMicroSeconds\r
-  )\r
-/*++\r
+/**\r

   Check whether DRDY is ready in the Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r
   Check whether DRDY is ready in the Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r

---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+StatusDRDYReady (\r
+  ATAPI_SCSI_PASS_THRU_DEV     *AtapiScsiPrivate,\r
+  UINT64                       TimeoutInMicroSeconds\r
+  )\r

 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   StatusRegister;\r


@@ -2043,26 +1993,27 @@ StatusDRDYReady (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-AltStatusDRDYReady (\r
-  ATAPI_SCSI_PASS_THRU_DEV     *AtapiScsiPrivate,\r
-  UINT64                       TimeoutInMicroSeconds\r
-  )\r
-/*++\r
+/**\r

   Check whether DRDY is ready in the Alternate Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r
   Check whether DRDY is ready in the Alternate Status Register. \r
   (BSY must also be cleared)\r
   If TimeoutInMicroSeconds is zero, this routine should wait infinitely for\r
   DRDY ready. Otherwise, it will return EFI_TIMEOUT when specified time is \r
   elapsed.\r

---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    TimeoutInMicroSeconds - add argument and description to function comment\r
-// TODO:    EFI_ABORTED - add return value to function comment\r
-// TODO:    EFI_TIMEOUT - add return value to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    TimeoutInMicroSeconds - add argument and description to function comment\r
+  @todo    EFI_ABORTED - add return value to function comment\r
+  @todo    EFI_TIMEOUT - add return value to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+AltStatusDRDYReady (\r
+  ATAPI_SCSI_PASS_THRU_DEV     *AtapiScsiPrivate,\r
+  UINT64                       TimeoutInMicroSeconds\r
+  )\r

 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r
 {\r
   UINT64  Delay;\r
   UINT8   AltStatusRegister;\r


@@ -2118,19 +2069,20 @@ AltStatusDRDYReady (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Check Error Register for Error Information. \r
+\r
+  @todo function comment is missing 'Routine Description:'\r
+  @todo function comment is missing 'Arguments:'\r
+  @todo function comment is missing 'Returns:'\r
+  @todo    AtapiScsiPrivate - add argument and description to function comment\r
+  @todo    EFI_SUCCESS - add return value to function comment\r
+  @todo    EFI_DEVICE_ERROR - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtapiPassThruCheckErrorStatus (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate\r
   )\r
 EFI_STATUS\r
 AtapiPassThruCheckErrorStatus (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate\r
   )\r

-/*++  \r
-  Check Error Register for Error Information. \r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO: function comment is missing 'Returns:'\r
-// TODO:    AtapiScsiPrivate - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   UINT8 StatusRegister;\r
 \r
 {\r
   UINT8 StatusRegister;\r
 \r

diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h
index d705c65949ff286ade6b496aae355edb9fa37c32..659b37c87601256bc44b60fb2590599aaf7f4ace 100644 (file)
--- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h
+++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h
@@ -1,23 +1,16 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
+  Module Name:  AtapiPassThru.h\r

 \r
 \r

-    AtapiPassThru.h\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
---*/\r
+**/\r

 \r
 #ifndef _APT_H\r
 #define _APT_H\r
 \r
 #ifndef _APT_H\r
 #define _APT_H\r


@@ -25,12 +18,13 @@ Revision History
 \r
 #include <IndustryStandard/pci22.h>\r
 \r
 \r
 #include <IndustryStandard/pci22.h>\r
 \r

-//\r
-// bit definition\r
-//\r
+///\r
+/// bit definition\r
+///\r

 #define bit(a)        1 << (a)\r
 \r
 #define MAX_TARGET_ID 4\r
 #define bit(a)        1 << (a)\r
 \r
 #define MAX_TARGET_ID 4\r

+\r

 //\r
 // IDE Registers\r
 //\r
 //\r
 // IDE Registers\r
 //\r


@@ -49,9 +43,9 @@ typedef union {
   UINT16  DeviceControl;  /* when write */\r
 } IDE_AltStatus_OR_DeviceControl;\r
 \r
   UINT16  DeviceControl;  /* when write */\r
 } IDE_AltStatus_OR_DeviceControl;\r
 \r

-//\r
-// IDE registers set\r
-//\r
+///\r
+/// IDE registers set\r
+///\r

 typedef struct {\r
   UINT16                          Data;\r
   IDE_ERROR_OR_FEATURE            Reg1;\r
 typedef struct {\r
   UINT16                          Data;\r
   IDE_ERROR_OR_FEATURE            Reg1;\r


@@ -167,21 +161,21 @@ typedef struct {
 //\r
 // ATA Err Reg bitmap\r
 //\r
 //\r
 // ATA Err Reg bitmap\r
 //\r

-#define BBK_ERR   bit (7) /* Bad block detected */\r
-#define UNC_ERR   bit (6) /* Uncorrectable Data */\r
-#define MC_ERR    bit (5) /* Media Change */\r
-#define IDNF_ERR  bit (4) /* ID Not Found */\r
-#define MCR_ERR   bit (3) /* Media Change Requested */\r
-#define ABRT_ERR  bit (2) /* Aborted Command */\r
-#define TK0NF_ERR bit (1) /* Track 0 Not Found */\r
-#define AMNF_ERR  bit (0) /* Address Mark Not Found */\r
+#define BBK_ERR   bit (7) ///< Bad block detected\r
+#define UNC_ERR   bit (6) ///< Uncorrectable Data\r
+#define MC_ERR    bit (5) ///< Media Change\r
+#define IDNF_ERR  bit (4) ///< ID Not Found\r
+#define MCR_ERR   bit (3) ///< Media Change Requested\r
+#define ABRT_ERR  bit (2) ///< Aborted Command\r
+#define TK0NF_ERR bit (1) ///< Track 0 Not Found\r
+#define AMNF_ERR  bit (0) ///< Address Mark Not Found\r

 \r
 //\r
 // ATAPI Err Reg bitmap\r
 //\r
 #define SENSE_KEY_ERR (bit (7) | bit (6) | bit (5) | bit (4))\r
 \r
 //\r
 // ATAPI Err Reg bitmap\r
 //\r
 #define SENSE_KEY_ERR (bit (7) | bit (6) | bit (5) | bit (4))\r

-#define EOM_ERR bit (1) /* End of Media Detected */\r
-#define ILI_ERR bit (0) /* Illegal Length Indication */\r
+#define EOM_ERR bit (1) ///< End of Media Detected\r
+#define ILI_ERR bit (0) ///< Illegal Length Indication\r

 \r
 //\r
 // Device/Head Reg\r
 \r
 //\r
 // Device/Head Reg\r


@@ -201,21 +195,21 @@ typedef struct {
 //\r
 // Status Reg\r
 //\r
 //\r
 // Status Reg\r
 //\r

-#define BSY   bit (7) /* Controller Busy */\r
-#define DRDY  bit (6) /* Drive Ready */\r
-#define DWF   bit (5) /* Drive Write Fault */\r
-#define DSC   bit (4) /* Disk Seek Complete */\r
-#define DRQ   bit (3) /* Data Request */\r
-#define CORR  bit (2) /* Corrected Data */\r
-#define IDX   bit (1) /* Index */\r
-#define ERR   bit (0) /* Error */\r
-#define CHECK bit (0) /* Check bit for ATAPI Status Reg */\r
+#define BSY   bit (7) ///< Controller Busy\r
+#define DRDY  bit (6) ///< Drive Ready\r
+#define DWF   bit (5) ///< Drive Write Fault\r
+#define DSC   bit (4) ///< Disk Seek Complete\r
+#define DRQ   bit (3) ///< Data Request\r
+#define CORR  bit (2) ///< Corrected Data\r
+#define IDX   bit (1) ///< Index\r
+#define ERR   bit (0) ///< Error\r
+#define CHECK bit (0) ///< Check bit for ATAPI Status Reg\r

 \r
 //\r
 // Device Control Reg\r
 //\r
 \r
 //\r
 // Device Control Reg\r
 //\r

-#define SRST  bit (2) /* Software Reset */\r
-#define IEN_L bit (1) /* Interrupt Enable #*/\r
+#define SRST  bit (2) ///< Software Reset\r
+#define IEN_L bit (1) ///< Interrupt Enable\r

 \r
 //\r
 // ATAPI Feature Register\r
 \r
 //\r
 // ATAPI Feature Register\r


@@ -242,55 +236,63 @@ typedef struct {
 //\r
 // function prototype\r
 //\r
 //\r
 // function prototype\r
 //\r

+/**\r
+  AtapiScsiPassThruDriverEntryPoint\r
+\r
+  @param ImageHandle\r
+  @param SystemTable\r
+\r
+  @todo Add function description\r
+  @todo ImageHandle - add argument description\r
+  @todo SystemTable - add argument description\r
+  @todo add return values\r
+--*/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverEntryPoint (\r
   IN EFI_HANDLE         ImageHandle,\r
   IN EFI_SYSTEM_TABLE   *SystemTable\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruDriverEntryPoint (\r
   IN EFI_HANDLE         ImageHandle,\r
   IN EFI_SYSTEM_TABLE   *SystemTable\r
   )\r

- /*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  ImageHandle - TODO: add argument description\r
-  SystemTable - TODO: add argument description\r
-\r
-Returns:\r
+;\r

 \r
 \r

-  TODO: add return values\r
+/**\r
+  RegisterAtapiScsiPassThru\r

 \r
 \r

---*/\r
-;\r
+  @param  This\r
+  @param  Controller\r
+  @param  PciIo\r

 \r
 \r

+  @todo Add function description\r
+  @todo This add argument description\r
+  @todo Controller add argument description\r
+  @todo PciIo add argument description\r
+  @todo add return values\r
+**/\r

 EFI_STATUS\r
 RegisterAtapiScsiPassThru (\r
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN  EFI_HANDLE                  Controller,\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo\r
   )\r
 EFI_STATUS\r
 RegisterAtapiScsiPassThru (\r
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN  EFI_HANDLE                  Controller,\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  Controller  - TODO: add argument description\r
-  PciIo       - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 ;\r
 \r
 ;\r
 \r

+/**\r
+  AtapiScsiPassThruFunction\r
+\r
+  @param  This\r
+  @param  Target\r
+  @param  Lun\r
+  @param  Packet\r
+  @param  Event\r
+\r
+  @todo Add function description\r
+  @todo  This - add argument description\r
+  @todo  Target - add argument description\r
+  @todo  Lun - add argument description\r
+  @todo  Packet - add argument description\r
+  @todo  Event - add argument description\r
+  @todo add return values\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruFunction (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruFunction (\r


@@ -300,27 +302,20 @@ AtapiScsiPassThruFunction (
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET         *Packet,\r
   IN EFI_EVENT                                          Event OPTIONAL\r
   )\r
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET         *Packet,\r
   IN EFI_EVENT                                          Event OPTIONAL\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiScsiPassThruGetNextDevice\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This    - TODO: add argument description\r
-  Target  - TODO: add argument description\r
-  Lun     - TODO: add argument description\r
-  Packet  - TODO: add argument description\r
-  Event   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Lun TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetNextDevice (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetNextDevice (\r


@@ -328,25 +323,21 @@ AtapiScsiPassThruGetNextDevice (
   IN OUT UINT32                      *Target,\r
   IN OUT UINT64                      *Lun\r
   )\r
   IN OUT UINT32                      *Target,\r
   IN OUT UINT64                      *Lun\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiScsiPassThruBuildDevicePath\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This    - TODO: add argument description\r
-  Target  - TODO: add argument description\r
-  Lun     - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Lun TODO: add argument description\r
+  @param  DevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruBuildDevicePath (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruBuildDevicePath (\r


@@ -355,26 +346,21 @@ AtapiScsiPassThruBuildDevicePath (
   IN     UINT64                         Lun,\r
   IN OUT EFI_DEVICE_PATH_PROTOCOL       **DevicePath\r
   )\r
   IN     UINT64                         Lun,\r
   IN OUT EFI_DEVICE_PATH_PROTOCOL       **DevicePath\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiScsiPassThruGetTargetLun\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  Target      - TODO: add argument description\r
-  Lun         - TODO: add argument description\r
-  DevicePath  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  DevicePath TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Lun TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetTargetLun (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetTargetLun (\r


@@ -383,48 +369,37 @@ AtapiScsiPassThruGetTargetLun (
   OUT UINT32                         *Target,\r
   OUT UINT64                         *Lun\r
   )\r
   OUT UINT32                         *Target,\r
   OUT UINT64                         *Lun\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiScsiPassThruResetChannel\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  DevicePath  - TODO: add argument description\r
-  Target      - TODO: add argument description\r
-  Lun         - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetChannel (\r
   IN  EFI_SCSI_PASS_THRU_PROTOCOL   *This\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetChannel (\r
   IN  EFI_SCSI_PASS_THRU_PROTOCOL   *This\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiScsiPassThruResetTarget\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Lun TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetTarget (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetTarget (\r


@@ -432,92 +407,74 @@ AtapiScsiPassThruResetTarget (
   IN UINT32                         Target,\r
   IN UINT64                         Lun\r
   )\r
   IN UINT32                         Target,\r
   IN UINT64                         Lun\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  CheckSCSIRequestPacket\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This    - TODO: add argument description\r
-  Target  - TODO: add argument description\r
-  Lun     - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Packet TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 CheckSCSIRequestPacket (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET      *Packet\r
   )\r
 EFI_STATUS\r
 CheckSCSIRequestPacket (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET      *Packet\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  SubmitBlockingIoCommand\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Packet  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Packet TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 SubmitBlockingIoCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r
   UINT32                                    Target,\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET    *Packet\r
   )\r
 EFI_STATUS\r
 SubmitBlockingIoCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r
   UINT32                                    Target,\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET    *Packet\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  IsCommandValid\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate  - TODO: add argument description\r
-  Target            - TODO: add argument description\r
-  Packet            - TODO: add argument description\r
+  @param Packet  - TODO: add argument description\r

 \r
 \r

-Returns:\r
-\r
-  TODO: add return values\r
+  @return TODO: add return values\r

 \r
 --*/\r
 \r
 --*/\r

-;\r
-\r

 BOOLEAN\r
 IsCommandValid (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET   *Packet\r
   )\r
 BOOLEAN\r
 IsCommandValid (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET   *Packet\r
   )\r

- /*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  RequestSenseCommand\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Packet  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  Timeout TODO: add argument description\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseDataLength TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 RequestSenseCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
 EFI_STATUS\r
 RequestSenseCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r


@@ -526,27 +483,24 @@ RequestSenseCommand (
   VOID                        *SenseData,\r
   UINT8                       *SenseDataLength\r
   )\r
   VOID                        *SenseData,\r
   UINT8                       *SenseDataLength\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AtapiPacketCommand\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate  - TODO: add argument description\r
-  Target            - TODO: add argument description\r
-  Timeout           - TODO: add argument description\r
-  SenseData         - TODO: add argument description\r
-  SenseDataLength   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  Target TODO: add argument description\r
+  @param  PacketCommand TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  Direction TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiPacketCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r
 EFI_STATUS\r
 AtapiPacketCommand (\r
   ATAPI_SCSI_PASS_THRU_DEV                  *AtapiScsiPrivate,\r


@@ -557,313 +511,236 @@ AtapiPacketCommand (
   DATA_DIRECTION                            Direction,\r
   UINT64                                    TimeOutInMicroSeconds\r
   )\r
   DATA_DIRECTION                            Direction,\r
   UINT64                                    TimeOutInMicroSeconds\r
   )\r

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

 \r
 \r

-  TODO: Add function description\r

 \r
 \r

-Arguments:\r
+/**\r
+  ReadPortB\r

 \r
 \r

-  AtapiScsiPrivate      - TODO: add argument description\r
-  Target                - TODO: add argument description\r
-  PacketCommand         - TODO: add argument description\r
-  Buffer                - TODO: add argument description\r
-  ByteCount             - TODO: add argument description\r
-  Direction             - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
+  TODO: Add function description\r

 \r
 \r

-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 UINT8\r
 ReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r
 UINT8\r
 ReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r

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

 \r
 \r

-  TODO: Add function description\r

 \r
 \r

-Arguments:\r
+/**\r
+  ReadPortW\r

 \r
 \r

-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
+  TODO: Add function description\r

 \r
 \r

-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 UINT16\r
 ReadPortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r
 UINT16\r
 ReadPortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r

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

 \r
 \r

-  TODO: Add function description\r

 \r
 \r

-Arguments:\r
+/**\r
+  WritePortB\r

 \r
 \r

-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
+  TODO: Add function description\r

 \r
 \r

-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 WritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r
 VOID\r
 WritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r

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

 \r
 \r

-  TODO: Add function description\r

 \r
 \r

-Arguments:\r
+/**\r
+  WritePortW\r

 \r
 \r

-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
+  TODO: Add function description\r

 \r
 \r

-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 WritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r
 VOID\r
 WritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  StatusDRQClear\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 StatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AltStatusDRQClear\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AltStatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 AltStatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  StatusDRQReady\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 StatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r
+/**\r
+  AltStatusDRQReady\r

 \r
   TODO: Add function description\r
 \r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AltStatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 AltStatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeoutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 StatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeoutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeoutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AltStatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 AltStatusWaitForBSYClear (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeoutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeoutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 StatusDRDYReady (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 StatusDRDYReady (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeoutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  TimeoutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AltStatusDRDYReady (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r
 EFI_STATUS\r
 AltStatusDRDYReady (\r
   ATAPI_SCSI_PASS_THRU_DEV    *AtapiScsiPrivate,\r
   UINT64                      TimeoutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  TimeoutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  Direction TODO: add argument description\r
+  @param  TimeOutInMicroSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiPassThruPioReadWriteData (\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate,\r
 EFI_STATUS\r
 AtapiPassThruPioReadWriteData (\r
   ATAPI_SCSI_PASS_THRU_DEV  *AtapiScsiPrivate,\r


@@ -872,45 +749,19 @@ AtapiPassThruPioReadWriteData (
   DATA_DIRECTION            Direction,\r
   UINT64                    TimeOutInMicroSeconds\r
   )\r
   DATA_DIRECTION            Direction,\r
   UINT64                    TimeOutInMicroSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  AtapiScsiPrivate      - TODO: add argument description\r
-  Buffer                - TODO: add argument description\r
-  ByteCount             - TODO: add argument description\r
-  Direction             - TODO: add argument description\r
-  TimeOutInMicroSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  AtapiScsiPrivate TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiPassThruCheckErrorStatus (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate\r
   )\r
 EFI_STATUS\r
 AtapiPassThruCheckErrorStatus (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  AtapiScsiPrivate  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

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

diff --git a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c
index 14658b0ace9cc255641f06d3f052316eabbcf802..b0b22317055d6d474d41c37bf05c729ecf30e704 100644 (file)
--- a/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c
+++ b/EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c
@@ -1,21 +1,16 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
+  Module Name:  ComponentName.c\r

 \r
 \r

-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r

 #include "AtapiPassThru.h"\r
 \r
 //\r
 #include "AtapiPassThru.h"\r
 \r
 //\r


@@ -39,9 +34,9 @@ AtapiScsiPassThruComponentNameGetControllerName (
   OUT CHAR16                                          **ControllerName\r
   );\r
 \r
   OUT CHAR16                                          **ControllerName\r
   );\r
 \r

-//\r
-// EFI Component Name Protocol\r
-//\r
+///\r
+/// EFI Component Name Protocol\r
+///\r

 EFI_COMPONENT_NAME_PROTOCOL     gAtapiScsiPassThruComponentName = {\r
   AtapiScsiPassThruComponentNameGetDriverName,\r
   AtapiScsiPassThruComponentNameGetControllerName,\r
 EFI_COMPONENT_NAME_PROTOCOL     gAtapiScsiPassThruComponentName = {\r
   AtapiScsiPassThruComponentNameGetDriverName,\r
   AtapiScsiPassThruComponentNameGetControllerName,\r


@@ -53,6 +48,28 @@ static EFI_UNICODE_STRING_TABLE mAtapiScsiPassThruDriverNameTable[] = {
   { NULL , NULL }\r
 };\r
 \r
   { NULL , NULL }\r
 };\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  Language A pointer to a three character ISO 639-2 language identifier.\r
+  This is the language of the driver name that that the caller\r
+  is requesting, and it must match one of the languages specified\r
+  in SupportedLanguages.  The number of languages supported by a\r
+  driver is up to the driver writer.\r
+  @param  DriverName A pointer to the Unicode string to return.  This Unicode string\r
+  is the name of the driver specified by This in the language\r
+  specified by Language.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the Driver specified by This\r
+  and the language specified by Language was returned\r
+  in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER DriverName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruComponentNameGetDriverName (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruComponentNameGetDriverName (\r


@@ -60,32 +77,6 @@ AtapiScsiPassThruComponentNameGetDriverName (
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
-\r
-  Arguments:\r
-    This       - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    Language   - A pointer to a three character ISO 639-2 language identifier.\r
-                 This is the language of the driver name that that the caller \r
-                 is requesting, and it must match one of the languages specified\r
-                 in SupportedLanguages.  The number of languages supported by a \r
-                 driver is up to the driver writer.\r
-    DriverName - A pointer to the Unicode string to return.  This Unicode string\r
-                 is the name of the driver specified by This in the language \r
-                 specified by Language.\r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the Driver specified by This\r
-                            and the language specified by Language was returned \r
-                            in DriverName.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - DriverName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   return LookupUnicodeString (\r
           Language,\r
 {\r
   return LookupUnicodeString (\r
           Language,\r


@@ -95,6 +86,47 @@ AtapiScsiPassThruComponentNameGetDriverName (
           );\r
 }\r
 \r
           );\r
 }\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the controller\r
+  that is being managed by an EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  ControllerHandle The handle of a controller that the driver specified by\r
+  This is managing.  This handle specifies the controller\r
+  whose name is to be returned.\r
+  @param  ChildHandle The handle of the child controller to retrieve the name\r
+  of.  This is an optional parameter that may be NULL.  It\r
+  will be NULL for device drivers.  It will also be NULL\r
+  for a bus drivers that wish to retrieve the name of the\r
+  bus controller.  It will not be NULL for a bus driver\r
+  that wishes to retrieve the name of a child controller.\r
+  @param  Language A pointer to a three character ISO 639-2 language\r
+  identifier.  This is the language of the controller name\r
+  that that the caller is requesting, and it must match one\r
+  of the languages specified in SupportedLanguages.  The\r
+  number of languages supported by a driver is up to the\r
+  driver writer.\r
+  @param  ControllerName A pointer to the Unicode string to return.  This Unicode\r
+  string is the name of the controller specified by\r
+  ControllerHandle and ChildHandle in the language\r
+  specified by Language from the point of view of the\r
+  driver specified by This.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the user readable name in the\r
+  language specified by Language for the driver\r
+  specified by This was returned in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+  EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER ControllerName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This is not currently\r
+  managing the controller specified by\r
+  ControllerHandle and ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruComponentNameGetControllerName (\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruComponentNameGetControllerName (\r


@@ -104,51 +136,6 @@ AtapiScsiPassThruComponentNameGetControllerName (
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the controller\r
-    that is being managed by an EFI Driver.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    ControllerHandle - The handle of a controller that the driver specified by \r
-                       This is managing.  This handle specifies the controller \r
-                       whose name is to be returned.\r
-    ChildHandle      - The handle of the child controller to retrieve the name \r
-                       of.  This is an optional parameter that may be NULL.  It \r
-                       will be NULL for device drivers.  It will also be NULL \r
-                       for a bus drivers that wish to retrieve the name of the \r
-                       bus controller.  It will not be NULL for a bus driver \r
-                       that wishes to retrieve the name of a child controller.\r
-    Language         - A pointer to a three character ISO 639-2 language \r
-                       identifier.  This is the language of the controller name \r
-                       that that the caller is requesting, and it must match one\r
-                       of the languages specified in SupportedLanguages.  The \r
-                       number of languages supported by a driver is up to the \r
-                       driver writer.\r
-    ControllerName   - A pointer to the Unicode string to return.  This Unicode\r
-                       string is the name of the controller specified by \r
-                       ControllerHandle and ChildHandle in the language \r
-                       specified by Language from the point of view of the \r
-                       driver specified by This. \r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the user readable name in the \r
-                            language specified by Language for the driver \r
-                            specified by This was returned in DriverName.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid \r
-                            EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - ControllerName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This is not currently \r
-                            managing the controller specified by \r
-                            ControllerHandle and ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   return EFI_UNSUPPORTED;\r
 }\r
 {\r
   return EFI_UNSUPPORTED;\r
 }\r

diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c
index 91d6accd99bfca2b9a017c699bfccd0c5dc5202f..68c483071cfda4bce1e4ec75d675e3241718971d 100644 (file)
--- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c
+++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c
@@ -1,20 +1,4 @@
-/*++\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
-\r
-Module Name:\r
-\r
-  CirrusLogic5430.c\r
-    \r
-Abstract:\r
-\r
+/** @file\r

   Cirrus Logic 5430 Controller Driver.\r
   This driver is a sample implementation of the UGA Draw Protocol for the\r
   Cirrus Logic 5430 family of PCI video controllers.  This driver is only\r
   Cirrus Logic 5430 Controller Driver.\r
   This driver is a sample implementation of the UGA Draw Protocol for the\r
   Cirrus Logic 5430 family of PCI video controllers.  This driver is only\r


@@ -25,9 +9,16 @@ Abstract:
   documentation on UGA for details on how to write a UGA driver that is able\r
   to function both in the EFI pre-boot environment and from the OS runtime.\r
 \r
   documentation on UGA for details on how to write a UGA driver that is able\r
   to function both in the EFI pre-boot environment and from the OS runtime.\r
 \r

-Revision History:\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

 \r
 \r

---*/\r
+**/\r

 \r
 //\r
 // Cirrus Logic 5430 Controller Driver\r
 \r
 //\r
 // Cirrus Logic 5430 Controller Driver\r


@@ -44,6 +35,13 @@ EFI_DRIVER_BINDING_PROTOCOL gCirrusLogic5430DriverBinding = {
   NULL\r
 };\r
 \r
   NULL\r
 };\r
 \r

+/**\r
+  CirrusLogic5430ControllerDriverSupported\r
+\r
+  TODO:    This - add argument and description to function comment\r
+  TODO:    Controller - add argument and description to function comment\r
+  TODO:    RemainingDevicePath - add argument and description to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverSupported (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverSupported (\r


@@ -51,20 +49,6 @@ CirrusLogic5430ControllerDriverSupported (
   IN EFI_HANDLE                     Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                     Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-    None\r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    RemainingDevicePath - add argument and description to function comment\r

 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r
 {\r
   EFI_STATUS          Status;\r
   EFI_PCI_IO_PROTOCOL *PciIo;\r


@@ -139,6 +123,13 @@ Done:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  CirrusLogic5430ControllerDriverStart\r
+\r
+  TODO:    This - add argument and description to function comment\r
+  TODO:    Controller - add argument and description to function comment\r
+  TODO:    RemainingDevicePath - add argument and description to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStart (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStart (\r


@@ -146,20 +137,6 @@ CirrusLogic5430ControllerDriverStart (
   IN EFI_HANDLE                     Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                     Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-    None\r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    RemainingDevicePath - add argument and description to function comment\r

 {\r
   EFI_STATUS                      Status;\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
 {\r
   EFI_STATUS                      Status;\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r


@@ -253,6 +230,15 @@ Error:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  CirrusLogic5430ControllerDriverStop\r
+\r
+  TODO:    This - add argument and description to function comment\r
+  TODO:    Controller - add argument and description to function comment\r
+  TODO:    NumberOfChildren - add argument and description to function comment\r
+  TODO:    ChildHandleBuffer - add argument and description to function comment\r
+  TODO:    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStop (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStop (\r


@@ -261,22 +247,6 @@ CirrusLogic5430ControllerDriverStop (
   IN UINTN                          NumberOfChildren,\r
   IN EFI_HANDLE                     *ChildHandleBuffer\r
   )\r
   IN UINTN                          NumberOfChildren,\r
   IN EFI_HANDLE                     *ChildHandleBuffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-    None\r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    Controller - add argument and description to function comment\r
-// TODO:    NumberOfChildren - add argument and description to function comment\r
-// TODO:    ChildHandleBuffer - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   EFI_UGA_DRAW_PROTOCOL           *UgaDraw;\r
   EFI_STATUS                      Status;\r
 {\r
   EFI_UGA_DRAW_PROTOCOL           *UgaDraw;\r
   EFI_STATUS                      Status;\r

diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h
index 79ca7e0293d1295c1dfb7d42256db8d697864eb6..b1984c8865473d578f7fa25924046f88f3881647 100644 (file)
--- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h
+++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h
@@ -1,25 +1,16 @@
-/*++\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
-\r
-Module Name:\r
-\r
-  CirrusLogic5430.h\r
-    \r
-Abstract:\r
-\r
+/** @file\r

   Cirrus Logic 5430 Controller Driver\r
 \r
   Cirrus Logic 5430 Controller Driver\r
 \r

-Revision History\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
 \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
 //\r
 // Cirrus Logic 5430 Controller Driver\r
 \r
 //\r
 // Cirrus Logic 5430 Controller Driver\r


@@ -99,78 +90,67 @@ extern EFI_COMPONENT_NAME_PROTOCOL  gCirrusLogic5430ComponentName;
 //\r
 // UGA Draw Hardware abstraction internal worker functions\r
 //\r
 //\r
 // UGA Draw Hardware abstraction internal worker functions\r
 //\r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  Private TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 EFI_STATUS\r
 CirrusLogic5430UgaDrawConstructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r
 EFI_STATUS\r
 CirrusLogic5430UgaDrawConstructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 CirrusLogic5430UgaDrawDestructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r
 EFI_STATUS\r
 CirrusLogic5430UgaDrawDestructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r

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

 \r
 \r

+//\r
+// EFI 1.1 driver model prototypes for Cirrus Logic 5430 UGA Draw\r
+//\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-\r
-Returns:\r
+  @param  ImageHandle TODO: add argument description\r
+  @param  SystemTable TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
-;\r
-\r
-//\r
-// EFI 1.1 driver model prototypes for Cirrus Logic 5430 UGA Draw\r
-//\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430DriverEntryPoint (\r
   IN EFI_HANDLE        ImageHandle,\r
   IN EFI_SYSTEM_TABLE  *SystemTable\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430DriverEntryPoint (\r
   IN EFI_HANDLE        ImageHandle,\r
   IN EFI_SYSTEM_TABLE  *SystemTable\r
   )\r

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

 \r
 \r

+//\r
+// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface\r
+//\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  ImageHandle - TODO: add argument description\r
-  SystemTable - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  RemainingDevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
-;\r
-\r
-//\r
-// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface\r
-//\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverSupported (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverSupported (\r


@@ -178,25 +158,18 @@ CirrusLogic5430ControllerDriverSupported (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This                - TODO: add argument description\r
-  Controller          - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  RemainingDevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStart (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStart (\r


@@ -204,25 +177,19 @@ CirrusLogic5430ControllerDriverStart (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This                - TODO: add argument description\r
-  Controller          - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  NumberOfChildren TODO: add argument description\r
+  @param  ChildHandleBuffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStop (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStop (\r


@@ -231,24 +198,6 @@ CirrusLogic5430ControllerDriverStop (
   IN UINTN                        NumberOfChildren,\r
   IN EFI_HANDLE                   *ChildHandleBuffer\r
   )\r
   IN UINTN                        NumberOfChildren,\r
   IN EFI_HANDLE                   *ChildHandleBuffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This              - TODO: add argument description\r
-  Controller        - 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
 \r
 #endif\r
 ;\r
 \r
 #endif\r

diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c
index c33918b67549e0859168066b2f7a4bf8cdd242ab..60e0582cf07b21ff9bf0a792c262fe7de449d5cb 100644 (file)
--- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c
+++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c
@@ -1,31 +1,24 @@
-/*++\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
-\r
-Module Name:\r
-\r
-  CirrusLogic5430UgaDraw.c\r
-\r
-Abstract:\r
-\r
+/** @file\r

   This file produces the graphics abstration of UGA Draw. It is called by \r
   CirrusLogic5430.c file which deals with the EFI 1.1 driver model. \r
   This file just does graphics.\r
 \r
   This file produces the graphics abstration of UGA Draw. It is called by \r
   CirrusLogic5430.c file which deals with the EFI 1.1 driver model. \r
   This file just does graphics.\r
 \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
+\r
+**/\r

 \r
 #include "CirrusLogic5430.h"\r
 \r
 \r
 #include "CirrusLogic5430.h"\r
 \r

-//\r
-// Video Mode structure\r
-//\r
+///\r
+/// Video Mode structure\r
+///\r

 typedef struct {\r
   UINT32  Width;\r
   UINT32  Height;\r
 typedef struct {\r
   UINT32  Width;\r
   UINT32  Height;\r


@@ -36,18 +29,18 @@ typedef struct {
   UINT8   MiscSetting;\r
 } CIRRUS_LOGIC_5430_VIDEO_MODES;\r
 \r
   UINT8   MiscSetting;\r
 } CIRRUS_LOGIC_5430_VIDEO_MODES;\r
 \r

-//\r
-// Generic Attribute Controller Register Settings\r
-//\r
+///\r
+/// Generic Attribute Controller Register Settings\r
+///\r

 static UINT8                          AttributeController[21] = {\r
   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, \r
   0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, \r
   0x41, 0x00, 0x0F, 0x00, 0x00\r
 };\r
 \r
 static UINT8                          AttributeController[21] = {\r
   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, \r
   0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, \r
   0x41, 0x00, 0x0F, 0x00, 0x00\r
 };\r
 \r

-//\r
-// Generic Graphics Controller Register Settings\r
-//\r
+///\r
+/// Generic Graphics Controller Register Settings\r
+///\r

 static UINT8 GraphicsController[9] = {\r
   0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x05, 0x0F, 0xFF\r
 };\r
 static UINT8 GraphicsController[9] = {\r
   0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x05, 0x0F, 0xFF\r
 };\r


@@ -97,9 +90,9 @@ static UINT16                         Seq_1024_768_256_60[15] = {
   0x5b0c, 0x450d, 0x760e, 0x2b1b, 0x2f1c, 0x301d, 0x341e\r
 };\r
 \r
   0x5b0c, 0x450d, 0x760e, 0x2b1b, 0x2f1c, 0x301d, 0x341e\r
 };\r
 \r

-//\r
-// Table of supported video modes\r
-//\r
+///\r
+/// Table of supported video modes\r
+///\r

 static CIRRUS_LOGIC_5430_VIDEO_MODES  CirrusLogic5430VideoModes[] = {\r
   {  640, 480, 8, 60, Crtc_640_480_256_60,  Seq_640_480_256_60,  0xe3 },\r
   {  800, 600, 8, 60, Crtc_800_600_256_60,  Seq_800_600_256_60,  0xef }, \r
 static CIRRUS_LOGIC_5430_VIDEO_MODES  CirrusLogic5430VideoModes[] = {\r
   {  640, 480, 8, 60, Crtc_640_480_256_60,  Seq_640_480_256_60,  0xe3 },\r
   {  800, 600, 8, 60, Crtc_800_600_256_60,  Seq_800_600_256_60,  0xef }, \r


@@ -169,6 +162,20 @@ inw (
 //\r
 // UGA Draw Protocol Member Functions\r
 //\r
 //\r
 // UGA Draw Protocol Member Functions\r
 //\r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  This TODO: add argument description\r
+  @param  HorizontalResolution TODO: add argument description\r
+  @param  VerticalResolution TODO: add argument description\r
+  @param  ColorDepth TODO: add argument description\r
+  @param  RefreshRate TODO: add argument description\r
+\r
+  @retval  EFI_NOT_STARTED TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawGetMode (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawGetMode (\r


@@ -178,27 +185,6 @@ CirrusLogic5430UgaDrawGetMode (
   OUT UINT32                *ColorDepth,\r
   OUT UINT32                *RefreshRate\r
   )\r
   OUT UINT32                *ColorDepth,\r
   OUT UINT32                *RefreshRate\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This                  - TODO: add argument description\r
-  HorizontalResolution  - TODO: add argument description\r
-  VerticalResolution    - TODO: add argument description\r
-  ColorDepth            - TODO: add argument description\r
-  RefreshRate           - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  EFI_NOT_STARTED - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_SUCCESS - TODO: Add description for return value\r
-\r
---*/\r

 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
 \r
 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
 \r


@@ -223,6 +209,20 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  This TODO: add argument description\r
+  @param  HorizontalResolution TODO: add argument description\r
+  @param  VerticalResolution TODO: add argument description\r
+  @param  ColorDepth TODO: add argument description\r
+  @param  RefreshRate TODO: add argument description\r
+\r
+  @retval  EFI_OUT_OF_RESOURCES TODO: Add description for return value\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r
+  @retval  EFI_NOT_FOUND TODO: Add description for return value\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawSetMode (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawSetMode (\r


@@ -232,27 +232,6 @@ CirrusLogic5430UgaDrawSetMode (
   IN  UINT32                ColorDepth,\r
   IN  UINT32                RefreshRate\r
   )\r
   IN  UINT32                ColorDepth,\r
   IN  UINT32                RefreshRate\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This                  - TODO: add argument description\r
-  HorizontalResolution  - TODO: add argument description\r
-  VerticalResolution    - TODO: add argument description\r
-  ColorDepth            - TODO: add argument description\r
-  RefreshRate           - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  EFI_OUT_OF_RESOURCES - TODO: Add description for return value\r
-  EFI_SUCCESS - TODO: Add description for return value\r
-  EFI_NOT_FOUND - TODO: Add description for return value\r
-\r
---*/\r

 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
   UINTN                           Index;\r
 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
   UINTN                           Index;\r


@@ -299,6 +278,29 @@ Returns:
   return EFI_NOT_FOUND;\r
 }\r
 \r
   return EFI_NOT_FOUND;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  This TODO: add argument description\r
+  @param  BltBuffer TODO: add argument description\r
+  @param  BltOperation TODO: add argument description\r
+  @param  SourceX TODO: add argument description\r
+  @param  SourceY TODO: add argument description\r
+  @param  DestinationX TODO: add argument description\r
+  @param  DestinationY TODO: add argument description\r
+  @param  Width TODO: add argument description\r
+  @param  Height TODO: add argument description\r
+  @param  Delta TODO: add argument description\r
+\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_INVALID_PARAMETER TODO: Add description for return value\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawBlt (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430UgaDrawBlt (\r


@@ -313,36 +315,6 @@ CirrusLogic5430UgaDrawBlt (
   IN  UINTN                     Height,\r
   IN  UINTN                     Delta\r
   )\r
   IN  UINTN                     Height,\r
   IN  UINTN                     Delta\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This          - TODO: add argument description\r
-  BltBuffer     - TODO: add argument description\r
-  BltOperation  - TODO: add argument description\r
-  SourceX       - TODO: add argument description\r
-  SourceY       - TODO: add argument description\r
-  DestinationX  - TODO: add argument description\r
-  DestinationY  - TODO: add argument description\r
-  Width         - TODO: add argument description\r
-  Height        - TODO: add argument description\r
-  Delta         - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_INVALID_PARAMETER - TODO: Add description for return value\r
-  EFI_SUCCESS - TODO: Add description for return value\r
-\r
---*/\r

 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
   EFI_TPL                         OriginalTPL;\r
 {\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private;\r
   EFI_TPL                         OriginalTPL;\r


@@ -597,23 +569,16 @@ Returns:
 // Construction and Destruction functions\r
 //\r
 \r
 // Construction and Destruction functions\r
 //\r
 \r

+/**\r
+  CirrusLogic5430UgaDrawConstructor\r
+\r
+  TODO:    Private - add argument and description to function comment\r
+  TODO:    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 CirrusLogic5430UgaDrawConstructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r
 EFI_STATUS\r
 CirrusLogic5430UgaDrawConstructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
---*/\r
-// TODO:    Private - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   EFI_UGA_DRAW_PROTOCOL *UgaDraw;\r
   UINTN                 Index;\r
 {\r
   EFI_UGA_DRAW_PROTOCOL *UgaDraw;\r
   UINTN                 Index;\r


@@ -657,50 +622,36 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  CirrusLogic5430UgaDrawDestructor\r
+\r
+  TODO:    Private - add argument and description to function comment\r
+  TODO:    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 CirrusLogic5430UgaDrawDestructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r
 EFI_STATUS\r
 CirrusLogic5430UgaDrawDestructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
---*/\r
-// TODO:    Private - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   return EFI_SUCCESS;\r
 }\r
 \r
 {\r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  Private TODO: add argument description\r
+  @param  Address TODO: add argument description\r
+  @param  Data TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 VOID\r
 outb (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
   UINTN                           Address,\r
   UINT8                           Data\r
   )\r
 VOID\r
 outb (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
   UINTN                           Address,\r
   UINT8                           Data\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-  Address - TODO: add argument description\r
-  Data    - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   Private->PciIo->Io.Write (\r
                       Private->PciIo,\r
 {\r
   Private->PciIo->Io.Write (\r
                       Private->PciIo,\r


@@ -712,29 +663,22 @@ Returns:
                       );\r
 }\r
 \r
                       );\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  Private TODO: add argument description\r
+  @param  Address TODO: add argument description\r
+  @param  Data TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 VOID\r
 outw (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
   UINTN                           Address,\r
   UINT16                          Data\r
   )\r
 VOID\r
 outw (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
   UINTN                           Address,\r
   UINT16                          Data\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-  Address - TODO: add argument description\r
-  Data    - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   Private->PciIo->Io.Write (\r
                       Private->PciIo,\r
 {\r
   Private->PciIo->Io.Write (\r
                       Private->PciIo,\r


@@ -746,27 +690,20 @@ Returns:
                       );\r
 }\r
 \r
                       );\r
 }\r
 \r

-UINT8\r
-inb (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
-  UINTN                           Address\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-  Address - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r
+  @param  Address TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+UINT8\r
+inb (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
+  UINTN                           Address\r
+  )\r

 {\r
   UINT8 Data;\r
 \r
 {\r
   UINT8 Data;\r
 \r


@@ -781,27 +718,20 @@ Returns:
   return Data;\r
 }\r
 \r
   return Data;\r
 }\r
 \r

-UINT16\r
-inw (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
-  UINTN                           Address\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-  Address - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r
+  @param  Address TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+UINT16\r
+inw (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
+  UINTN                           Address\r
+  )\r

 {\r
   UINT16  Data;\r
 \r
 {\r
   UINT16  Data;\r
 \r


@@ -816,6 +746,18 @@ Returns:
   return Data;\r
 }\r
 \r
   return Data;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  Private TODO: add argument description\r
+  @param  Index TODO: add argument description\r
+  @param  Red TODO: add argument description\r
+  @param  Green TODO: add argument description\r
+  @param  Blue TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 VOID\r
 SetPaletteColor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
 VOID\r
 SetPaletteColor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r


@@ -824,25 +766,6 @@ SetPaletteColor (
   UINT8                           Green,\r
   UINT8                           Blue\r
   )\r
   UINT8                           Green,\r
   UINT8                           Blue\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-  Index   - TODO: add argument description\r
-  Red     - TODO: add argument description\r
-  Green   - TODO: add argument description\r
-  Blue    - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   outb (Private, PALETTE_INDEX_REGISTER, (UINT8) Index);\r
   outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Red >> 2));\r
 {\r
   outb (Private, PALETTE_INDEX_REGISTER, (UINT8) Index);\r
   outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Red >> 2));\r


@@ -850,25 +773,18 @@ Returns:
   outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Blue >> 2));\r
 }\r
 \r
   outb (Private, PALETTE_DATA_REGISTER, (UINT8) (Blue >> 2));\r
 }\r
 \r

-VOID\r
-SetDefaultPalette (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+VOID\r
+SetDefaultPalette (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r

 {\r
   UINTN Index;\r
   UINTN RedIndex;\r
 {\r
   UINTN Index;\r
   UINTN RedIndex;\r


@@ -886,26 +802,19 @@ Returns:
   }\r
 }\r
 \r
   }\r
 }\r
 \r

-STATIC\r
-VOID\r
-ClearScreen (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+STATIC\r
+VOID\r
+ClearScreen (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r

 {\r
   UINT32  Color;\r
 \r
 {\r
   UINT32  Color;\r
 \r


@@ -920,25 +829,18 @@ Returns:
                         );\r
 }\r
 \r
                         );\r
 }\r
 \r

-VOID\r
-DrawLogo (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+VOID\r
+DrawLogo (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r

 {\r
   UINTN Offset;\r
   UINTN X;\r
 {\r
   UINTN Offset;\r
   UINTN X;\r


@@ -968,27 +870,20 @@ Returns:
   }\r
 }\r
 \r
   }\r
 }\r
 \r

-VOID\r
-InitializeGraphicsMode (\r
-  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
-  CIRRUS_LOGIC_5430_VIDEO_MODES   *ModeData\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Private   - TODO: add argument description\r
-  ModeData  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Private TODO: add argument description\r
+  @param  ModeData TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+VOID\r
+InitializeGraphicsMode (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
+  CIRRUS_LOGIC_5430_VIDEO_MODES   *ModeData\r
+  )\r

 {\r
   UINT8 Byte;\r
   UINTN Index;\r
 {\r
   UINT8 Byte;\r
   UINTN Index;\r

diff --git a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c
index 5c10b6d7b487f85f69537c08f656970a3ab30dc6..933899fa1206d8d13bf2fb7babcccb3e2c05ae7a 100644 (file)
--- a/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c
+++ b/EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c
@@ -1,21 +1,14 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r

 \r
 #include "CirrusLogic5430.h"\r
 \r
 \r
 #include "CirrusLogic5430.h"\r
 \r


@@ -59,6 +52,28 @@ static EFI_UNICODE_STRING_TABLE mCirrusLogic5430ControllerNameTable[] = {
   { NULL , NULL }\r
 };\r
 \r
   { NULL , NULL }\r
 };\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  Language A pointer to a three character ISO 639-2 language identifier.\r
+  This is the language of the driver name that that the caller\r
+  is requesting, and it must match one of the languages specified\r
+  in SupportedLanguages.  The number of languages supported by a\r
+  driver is up to the driver writer.\r
+  @param  DriverName A pointer to the Unicode string to return.  This Unicode string\r
+  is the name of the driver specified by This in the language\r
+  specified by Language.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the Driver specified by This\r
+  and the language specified by Language was returned\r
+  in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER DriverName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ComponentNameGetDriverName (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ComponentNameGetDriverName (\r


@@ -66,32 +81,6 @@ CirrusLogic5430ComponentNameGetDriverName (
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
-\r
-  Arguments:\r
-    This       - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    Language   - A pointer to a three character ISO 639-2 language identifier.\r
-                 This is the language of the driver name that that the caller \r
-                 is requesting, and it must match one of the languages specified\r
-                 in SupportedLanguages.  The number of languages supported by a \r
-                 driver is up to the driver writer.\r
-    DriverName - A pointer to the Unicode string to return.  This Unicode string\r
-                 is the name of the driver specified by This in the language \r
-                 specified by Language.\r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the Driver specified by This\r
-                            and the language specified by Language was returned \r
-                            in DriverName.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - DriverName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   return LookupUnicodeString (\r
           Language,\r
 {\r
   return LookupUnicodeString (\r
           Language,\r


@@ -101,6 +90,46 @@ CirrusLogic5430ComponentNameGetDriverName (
           );\r
 }\r
 \r
           );\r
 }\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the controller\r
+  that is being managed by an EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  ControllerHandle The handle of a controller that the driver specified by\r
+  This is managing.  This handle specifies the controller\r
+  whose name is to be returned.\r
+  @param  ChildHandle The handle of the child controller to retrieve the name\r
+  of.  This is an optional parameter that may be NULL.  It\r
+  will be NULL for device drivers.  It will also be NULL\r
+  for a bus drivers that wish to retrieve the name of the\r
+  bus controller.  It will not be NULL for a bus driver\r
+  that wishes to retrieve the name of a child controller.\r
+  @param  Language A pointer to a three character ISO 639-2 language\r
+  identifier.  This is the language of the controller name\r
+  that that the caller is requesting, and it must match one\r
+  of the languages specified in SupportedLanguages.  The\r
+  number of languages supported by a driver is up to the\r
+  driver writer.\r
+  @param  ControllerName A pointer to the Unicode string to return.  This Unicode\r
+  string is the name of the controller specified by\r
+  ControllerHandle and ChildHandle in the language specified\r
+  by Language from the point of view of the driver specified\r
+  by This.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the user readable name in the\r
+  language specified by Language for the driver\r
+  specified by This was returned in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER ControllerName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This is not currently managing\r
+  the controller specified by ControllerHandle and\r
+  ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ComponentNameGetControllerName (\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ComponentNameGetControllerName (\r


@@ -110,50 +139,6 @@ CirrusLogic5430ComponentNameGetControllerName (
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the controller\r
-    that is being managed by an EFI Driver.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    ControllerHandle - The handle of a controller that the driver specified by \r
-                       This is managing.  This handle specifies the controller \r
-                       whose name is to be returned.\r
-    ChildHandle      - The handle of the child controller to retrieve the name \r
-                       of.  This is an optional parameter that may be NULL.  It \r
-                       will be NULL for device drivers.  It will also be NULL \r
-                       for a bus drivers that wish to retrieve the name of the \r
-                       bus controller.  It will not be NULL for a bus driver \r
-                       that wishes to retrieve the name of a child controller.\r
-    Language         - A pointer to a three character ISO 639-2 language \r
-                       identifier.  This is the language of the controller name \r
-                       that that the caller is requesting, and it must match one\r
-                       of the languages specified in SupportedLanguages.  The \r
-                       number of languages supported by a driver is up to the \r
-                       driver writer.\r
-    ControllerName   - A pointer to the Unicode string to return.  This Unicode\r
-                       string is the name of the controller specified by \r
-                       ControllerHandle and ChildHandle in the language specified\r
-                       by Language from the point of view of the driver specified\r
-                       by This. \r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the user readable name in the \r
-                            language specified by Language for the driver \r
-                            specified by This was returned in DriverName.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - ControllerName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This is not currently managing \r
-                            the controller specified by ControllerHandle and \r
-                            ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   EFI_UGA_DRAW_PROTOCOL           *UgaDraw;\r
   EFI_STATUS                      Status;\r
 {\r
   EFI_UGA_DRAW_PROTOCOL           *UgaDraw;\r
   EFI_STATUS                      Status;\r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c
index 240a6b00829cb0103da49d41f2bb5305a89e7008..edead729b40d5d12fe9866cc029d763dadd0d414 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c
@@ -1,21 +1,14 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 \r
 #include "idebus.h"\r
 \r


@@ -38,6 +31,28 @@ STATIC EFI_UNICODE_STRING_TABLE mIDEBusControllerNameTable[] = {
   { NULL , NULL }\r
 };\r
 \r
   { NULL , NULL }\r
 };\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  Language A pointer to a three character ISO 639-2 language identifier.\r
+  This is the language of the driver name that that the caller\r
+  is requesting, and it must match one of the languages specified\r
+  in SupportedLanguages.  The number of languages supported by a\r
+  driver is up to the driver writer.\r
+  @param  DriverName A pointer to the Unicode string to return.  This Unicode string\r
+  is the name of the driver specified by This in the language\r
+  specified by Language.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the Driver specified by This\r
+  and the language specified by Language was returned\r
+  in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER DriverName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusComponentNameGetDriverName (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusComponentNameGetDriverName (\r


@@ -45,32 +60,6 @@ IDEBusComponentNameGetDriverName (
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r
   IN  CHAR8                        *Language,\r
   OUT CHAR16                       **DriverName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the EFI Driver.\r
-\r
-  Arguments:\r
-    This       - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    Language   - A pointer to a three character ISO 639-2 language identifier.\r
-                 This is the language of the driver name that that the caller \r
-                 is requesting, and it must match one of the languages specified\r
-                 in SupportedLanguages.  The number of languages supported by a \r
-                 driver is up to the driver writer.\r
-    DriverName - A pointer to the Unicode string to return.  This Unicode string\r
-                 is the name of the driver specified by This in the language \r
-                 specified by Language.\r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the Driver specified by This\r
-                            and the language specified by Language was returned \r
-                            in DriverName.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - DriverName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   return LookupUnicodeString (\r
           Language,\r
 {\r
   return LookupUnicodeString (\r
           Language,\r


@@ -80,6 +69,47 @@ IDEBusComponentNameGetDriverName (
           );\r
 }\r
 \r
           );\r
 }\r
 \r

+/**\r
+  Retrieves a Unicode string that is the user readable name of the controller\r
+  that is being managed by an EFI Driver.\r
+\r
+  @param  This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
+  @param  ControllerHandle The handle of a controller that the driver specified by\r
+  This is managing.  This handle specifies the controller\r
+  whose name is to be returned.\r
+  @param  ChildHandle The handle of the child controller to retrieve the name\r
+  of.  This is an optional parameter that may be NULL.  It\r
+  will be NULL for device drivers.  It will also be NULL\r
+  for a bus drivers that wish to retrieve the name of the\r
+  bus controller.  It will not be NULL for a bus driver\r
+  that wishes to retrieve the name of a child controller.\r
+  @param  Language A pointer to a three character ISO 639-2 language\r
+  identifier.  This is the language of the controller name\r
+  that that the caller is requesting, and it must match one\r
+  of the languages specified in SupportedLanguages.  The\r
+  number of languages supported by a driver is up to the\r
+  driver writer.\r
+  @param  ControllerName A pointer to the Unicode string to return.  This Unicode\r
+  string is the name of the controller specified by\r
+  ControllerHandle and ChildHandle in the language\r
+  specified by Language from the point of view of the\r
+  driver specified by This.\r
+\r
+  @retval  EFI_SUCCESS The Unicode string for the user readable name in the\r
+  language specified by Language for the driver\r
+  specified by This was returned in DriverName.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+  EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER ControllerName is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This is not currently\r
+  managing the controller specified by\r
+  ControllerHandle and ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusComponentNameGetControllerName (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusComponentNameGetControllerName (\r


@@ -89,51 +119,6 @@ IDEBusComponentNameGetControllerName (
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r
   IN  CHAR8                                           *Language,\r
   OUT CHAR16                                          **ControllerName\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Retrieves a Unicode string that is the user readable name of the controller\r
-    that is being managed by an EFI Driver.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.\r
-    ControllerHandle - The handle of a controller that the driver specified by \r
-                       This is managing.  This handle specifies the controller \r
-                       whose name is to be returned.\r
-    ChildHandle      - The handle of the child controller to retrieve the name \r
-                       of.  This is an optional parameter that may be NULL.  It \r
-                       will be NULL for device drivers.  It will also be NULL \r
-                       for a bus drivers that wish to retrieve the name of the \r
-                       bus controller.  It will not be NULL for a bus driver \r
-                       that wishes to retrieve the name of a child controller.\r
-    Language         - A pointer to a three character ISO 639-2 language \r
-                       identifier.  This is the language of the controller name \r
-                       that that the caller is requesting, and it must match one\r
-                       of the languages specified in SupportedLanguages.  The \r
-                       number of languages supported by a driver is up to the \r
-                       driver writer.\r
-    ControllerName   - A pointer to the Unicode string to return.  This Unicode\r
-                       string is the name of the controller specified by \r
-                       ControllerHandle and ChildHandle in the language \r
-                       specified by Language from the point of view of the \r
-                       driver specified by This. \r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The Unicode string for the user readable name in the \r
-                            language specified by Language for the driver \r
-                            specified by This was returned in DriverName.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid \r
-                            EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - ControllerName is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This is not currently \r
-                            managing the controller specified by \r
-                            ControllerHandle and ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-\r
---*/\r

 {\r
   EFI_STATUS            Status;\r
   EFI_BLOCK_IO_PROTOCOL *BlockIo;\r
 {\r
   EFI_STATUS            Status;\r
   EFI_BLOCK_IO_PROTOCOL *BlockIo;\r


@@ -188,21 +173,16 @@ IDEBusComponentNameGetControllerName (
           );\r
 }\r
 \r
           );\r
 }\r
 \r

+/**\r
+  Add the component name for the IDE/ATAPI device\r
+\r
+  @param  IdeBlkIoDevicePtr A pointer to the IDE_BLK_IO_DEV instance.\r
+\r
+**/\r

 VOID\r
 AddName (\r
   IN  IDE_BLK_IO_DEV               *IdeBlkIoDevicePtr\r
   )\r
 VOID\r
 AddName (\r
   IN  IDE_BLK_IO_DEV               *IdeBlkIoDevicePtr\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Add the component name for the IDE/ATAPI device\r
-\r
-  Arguments:\r
-    IdeBlkIoDevicePtr     - A pointer to the IDE_BLK_IO_DEV instance.\r
-\r
-  Returns:\r
-\r
---*/\r

 {\r
   UINTN   StringIndex;\r
   CHAR16  ModelName[41];\r
 {\r
   UINTN   StringIndex;\r
   CHAR16  ModelName[41];\r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c
index 5a23a43189fdc68c41c18ae60635ece452d64005..dfe134a2ee860a74fcf2b95689372a942aa3d422 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c
@@ -1,21 +1,14 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-  DriverConfiguration.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 \r
 #include "idebus.h"\r
 \r


@@ -63,27 +56,18 @@ EFI_DRIVER_CONFIGURATION_PROTOCOL gIDEBusDriverConfiguration = {
   "eng"\r
 };\r
 \r
   "eng"\r
 };\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @retval  EFI_ABORTED TODO: Add description for return value\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r
+  @retval  EFI_NOT_FOUND TODO: Add description for return value\r
+\r
+**/\r

 EFI_STATUS\r
 GetResponse (\r
   VOID\r
   )\r
 EFI_STATUS\r
 GetResponse (\r
   VOID\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  None\r
-\r
-Returns:\r
-\r
-  EFI_ABORTED - TODO: Add description for return value\r
-  EFI_SUCCESS - TODO: Add description for return value\r
-  EFI_NOT_FOUND - TODO: Add description for return value\r
-\r
---*/\r

 {\r
   EFI_STATUS    Status;\r
   EFI_INPUT_KEY Key;\r
 {\r
   EFI_STATUS    Status;\r
   EFI_INPUT_KEY Key;\r


@@ -118,6 +102,51 @@ Returns:
   }\r
 }\r
 \r
   }\r
 }\r
 \r

+/**\r
+  Allows the user to set controller specific options for a controller that a \r
+  driver is currently managing.\r
+\r
+  @param  This A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL\r
+  instance.\r
+  @param  ControllerHandle The handle of the controller to set options on.\r
+  @param  ChildHandle The handle of the child controller to set options on.\r
+  This is an optional parameter that may be NULL.\r
+  It will be NULL for device drivers, and for a bus drivers\r
+  that wish to set options for the bus controller.\r
+  It will not be NULL for a bus driver that wishes to set\r
+  options for one of its child controllers.\r
+  @param  Language A pointer to a three character ISO 639-2 language\r
+  identifier. This is the language of the user interface\r
+  that should be presented to the user, and it must match\r
+  one of the languages specified in SupportedLanguages.\r
+  The number of languages supported by a driver is up to\r
+  the driver writer.\r
+  @param  ActionRequired A pointer to the action that the calling agent is\r
+  required to perform when this function returns.\r
+  See "Related Definitions" for a list of the actions that\r
+  the calling agent is required to perform prior to\r
+  accessing ControllerHandle again.\r
+\r
+  @retval  EFI_SUCCESS The driver specified by This successfully set the\r
+  configuration options for the controller specified\r
+  by ControllerHandle..\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a\r
+  valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ActionRequired is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support\r
+  setting configuration options for the controller\r
+  specified by ControllerHandle and ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+  @retval  EFI_DEVICE_ERROR A device error occurred while attempt to set the\r
+  configuration options for the controller specified\r
+  by ControllerHandle and ChildHandle.\r
+  @retval  EFI_OUT_RESOURCES There are not enough resources available to set the\r
+  configuration options for the controller specified\r
+  by ControllerHandle and ChildHandle.\r
+\r
+**/\r

 EFI_STATUS\r
 IDEBusDriverConfigurationSetOptions (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL                      *This,\r
 EFI_STATUS\r
 IDEBusDriverConfigurationSetOptions (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL                      *This,\r


@@ -126,55 +155,6 @@ IDEBusDriverConfigurationSetOptions (
   IN  CHAR8                                                  *Language,\r
   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED               *ActionRequired\r
   )\r
   IN  CHAR8                                                  *Language,\r
   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED               *ActionRequired\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Allows the user to set controller specific options for a controller that a \r
-    driver is currently managing.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL \r
-                       instance.\r
-    ControllerHandle - The handle of the controller to set options on.\r
-    ChildHandle      - The handle of the child controller to set options on.  \r
-                       This is an optional parameter that may be NULL.  \r
-                       It will be NULL for device drivers, and for a bus drivers\r
-                       that wish to set options for the bus controller.  \r
-                       It will not be NULL for a bus driver that wishes to set \r
-                       options for one of its child controllers.\r
-    Language         - A pointer to a three character ISO 639-2 language \r
-                       identifier. This is the language of the user interface \r
-                       that should be presented to the user, and it must match \r
-                       one of the languages specified in SupportedLanguages.  \r
-                       The number of languages supported by a driver is up to \r
-                       the driver writer.\r
-    ActionRequired   - A pointer to the action that the calling agent is \r
-                       required to perform when this function returns.  \r
-                       See "Related Definitions" for a list of the actions that\r
-                       the calling agent is required to perform prior to \r
-                       accessing ControllerHandle again.\r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The driver specified by This successfully set the \r
-                            configuration options for the controller specified \r
-                            by ControllerHandle..\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a \r
-                            valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ActionRequired is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support \r
-                            setting configuration options for the controller \r
-                            specified by ControllerHandle and ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-    EFI_DEVICE_ERROR      - A device error occurred while attempt to set the \r
-                            configuration options for the controller specified \r
-                            by ControllerHandle and ChildHandle.\r
-    EFI_OUT_RESOURCES     - There are not enough resources available to set the \r
-                            configuration options for the controller specified \r
-                            by ControllerHandle and ChildHandle.\r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       Value;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       Value;\r


@@ -232,49 +212,45 @@ IDEBusDriverConfigurationSetOptions (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Tests to see if a controller's current configuration options are valid.\r
+\r
+  @param  This A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL\r
+  instance.\r
+  @param  ControllerHandle The handle of the controller to test if it's current\r
+  configuration options are valid.\r
+  @param  ChildHandle The handle of the child controller to test if it's\r
+  current\r
+  configuration options are valid.  This is an optional\r
+  parameter that may be NULL.  It will be NULL for device\r
+  drivers.  It will also be NULL for a bus drivers that\r
+  wish to test the configuration options for the bus\r
+  controller. It will not be NULL for a bus driver that\r
+  wishes to test configuration options for one of\r
+  its child controllers.\r
+\r
+  @retval  EFI_SUCCESS The controller specified by ControllerHandle and\r
+  ChildHandle that is being managed by the driver\r
+  specified by This has a valid set of  configuration\r
+  options.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+  EFI_HANDLE.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This is not currently\r
+  managing the controller specified by\r
+  ControllerHandle and ChildHandle.\r
+  @retval  EFI_DEVICE_ERROR The controller specified by ControllerHandle and\r
+  ChildHandle that is being managed by the driver\r
+  specified by This has an invalid set of\r
+  configuration options.\r
+\r
+**/\r

 EFI_STATUS\r
 IDEBusDriverConfigurationOptionsValid (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL               *This,\r
   IN  EFI_HANDLE                                      ControllerHandle,\r
   IN  EFI_HANDLE                                      ChildHandle  OPTIONAL\r
   )\r
 EFI_STATUS\r
 IDEBusDriverConfigurationOptionsValid (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL               *This,\r
   IN  EFI_HANDLE                                      ControllerHandle,\r
   IN  EFI_HANDLE                                      ChildHandle  OPTIONAL\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Tests to see if a controller's current configuration options are valid.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_DRIVER_CONFIGURATION_PROTOCOL \r
-                       instance.\r
-    ControllerHandle - The handle of the controller to test if it's current \r
-                       configuration options are valid.\r
-    ChildHandle      - The handle of the child controller to test if it's \r
-                       current\r
-                       configuration options are valid.  This is an optional \r
-                       parameter that may be NULL.  It will be NULL for device \r
-                       drivers.  It will also be NULL for a bus drivers that \r
-                       wish to test the configuration options for the bus \r
-                       controller. It will not be NULL for a bus driver that \r
-                       wishes to test configuration options for one of \r
-                       its child controllers.\r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The controller specified by ControllerHandle and \r
-                            ChildHandle that is being managed by the driver \r
-                            specified by This has a valid set of  configuration\r
-                            options.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid \r
-                            EFI_HANDLE.\r
-    EFI_UNSUPPORTED       - The driver specified by This is not currently \r
-                            managing the controller specified by \r
-                            ControllerHandle and ChildHandle.\r
-    EFI_DEVICE_ERROR      - The controller specified by ControllerHandle and \r
-                            ChildHandle that is being managed by the driver \r
-                            specified by This has an invalid set of \r
-                            configuration options.\r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       Value;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       Value;\r


@@ -300,6 +276,51 @@ IDEBusDriverConfigurationOptionsValid (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Forces a driver to set the default configuration options for a controller.\r
+\r
+  @param  This A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL\r
+  instance.\r
+  @param  ControllerHandle The handle of the controller to force default\r
+  configuration options on.\r
+  @param  ChildHandle The handle of the child controller to force default\r
+  configuration options on  This is an optional parameter\r
+  that may be NULL.  It will be NULL for device drivers.\r
+  It will also be NULL for a bus drivers that wish to\r
+  force default configuration options for the bus\r
+  controller.  It will not be NULL for a bus driver that\r
+  wishes to force default configuration options for one\r
+  of its child controllers.\r
+  @param  DefaultType The type of default configuration options to force on\r
+  the controller specified by ControllerHandle and\r
+  ChildHandle.  See Table 9-1 for legal values.\r
+  A DefaultType of 0x00000000 must be supported\r
+  by this protocol.\r
+  @param  ActionRequired A pointer to the action that the calling agent\r
+  is required to perform when this function returns.\r
+\r
+  @retval  EFI_SUCCESS The driver specified by This successfully forced\r
+  the default configuration options on the\r
+  controller specified by ControllerHandle and\r
+  ChildHandle.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a\r
+  valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ActionRequired is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support\r
+  forcing the default configuration options on\r
+  the controller specified by ControllerHandle\r
+  and ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support\r
+  the configuration type specified by DefaultType.\r
+  @retval  EFI_DEVICE_ERROR A device error occurred while attempt to force\r
+  the default configuration options on the controller\r
+  specified by  ControllerHandle and ChildHandle.\r
+  @retval  EFI_OUT_RESOURCES There are not enough resources available to force\r
+  the default configuration options on the controller\r
+  specified by ControllerHandle and ChildHandle.\r
+\r
+**/\r

 EFI_STATUS\r
 IDEBusDriverConfigurationForceDefaults (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL                      *This,\r
 EFI_STATUS\r
 IDEBusDriverConfigurationForceDefaults (\r
   IN  EFI_DRIVER_CONFIGURATION_PROTOCOL                      *This,\r


@@ -308,56 +329,6 @@ IDEBusDriverConfigurationForceDefaults (
   IN  UINT32                                                 DefaultType,\r
   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED               *ActionRequired\r
   )\r
   IN  UINT32                                                 DefaultType,\r
   OUT EFI_DRIVER_CONFIGURATION_ACTION_REQUIRED               *ActionRequired\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Forces a driver to set the default configuration options for a controller.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_DRIVER_CONFIGURATION_ PROTOCOL \r
-                       instance.\r
-    ControllerHandle - The handle of the controller to force default \r
-                       configuration options on.\r
-    ChildHandle      - The handle of the child controller to force default \r
-                       configuration options on  This is an optional parameter \r
-                       that may be NULL.  It will be NULL for device drivers.  \r
-                       It will also be NULL for a bus drivers that wish to \r
-                       force default configuration options for the bus \r
-                       controller.  It will not be NULL for a bus driver that \r
-                       wishes to force default configuration options for one \r
-                       of its child controllers.\r
-    DefaultType      - The type of default configuration options to force on \r
-                       the controller specified by ControllerHandle and \r
-                       ChildHandle.  See Table 9-1 for legal values.  \r
-                       A DefaultType of 0x00000000 must be supported \r
-                       by this protocol.\r
-    ActionRequired   - A pointer to the action that the calling agent \r
-                       is required to perform when this function returns.  \r
-                       \r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The driver specified by This successfully forced \r
-                            the default configuration options on the \r
-                            controller specified by ControllerHandle and \r
-                            ChildHandle.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a \r
-                            valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ActionRequired is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support \r
-                            forcing the default configuration options on \r
-                            the controller specified by ControllerHandle \r
-                            and ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support \r
-                            the configuration type specified by DefaultType.\r
-    EFI_DEVICE_ERROR      - A device error occurred while attempt to force \r
-                            the default configuration options on the controller \r
-                            specified by  ControllerHandle and ChildHandle.\r
-    EFI_OUT_RESOURCES     - There are not enough resources available to force \r
-                            the default configuration options on the controller \r
-                            specified by ControllerHandle and ChildHandle.\r
-\r
---*/\r

 {\r
   UINT8 Value;\r
 \r
 {\r
   UINT8 Value;\r
 \r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c
index d3f2a8e31cdf3d19d674e781524df94b3bea1b05..c7bd30aa9496e418765984bf4558f618c8f2f6a2 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c
@@ -1,21 +1,14 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-  DriverDiagnostics.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 \r
 #include "idebus.h"\r
 \r


@@ -44,6 +37,63 @@ EFI_DRIVER_DIAGNOSTICS_PROTOCOL gIDEBusDriverDiagnostics = {
   "eng"\r
 };\r
 \r
   "eng"\r
 };\r
 \r

+/**\r
+  Runs diagnostics on a controller.\r
+\r
+  @param  This A pointer to the EFI_DRIVER_DIAGNOSTICS_PROTOCOL\r
+  instance.\r
+  @param  ControllerHandle The handle of the controller to run diagnostics on.\r
+  @param  ChildHandle The handle of the child controller to run diagnostics on\r
+  This is an optional parameter that may be NULL.  It will\r
+  be NULL for device drivers.  It will also be NULL for a\r
+  bus drivers that wish to run diagnostics on the bus\r
+  controller.  It will not be NULL for a bus driver that\r
+  wishes to run diagnostics on one of its child\r
+  controllers.\r
+  @param  DiagnosticType Indicates type of diagnostics to perform on the\r
+  controller specified by ControllerHandle and ChildHandle.\r
+  See "Related Definitions" for the list of supported\r
+  types.\r
+  @param  Language A pointer to a three character ISO 639-2 language\r
+  identifier.  This is the language in which the optional\r
+  error message should be returned in Buffer, and it must\r
+  match one of the languages specified in\r
+  SupportedLanguages. The number of languages supported by\r
+  a driver is up to the driver writer.\r
+  @param  ErrorType A GUID that defines the format of the data returned in\r
+  Buffer.\r
+  @param  BufferSize The size, in bytes, of the data returned in Buffer.\r
+  @param  Buffer A buffer that contains a Null-terminated Unicode string\r
+  plus some additional data whose format is defined by\r
+  ErrorType.  Buffer is allocated by this function with\r
+  AllocatePool(), and it is the caller's responsibility\r
+  to free it with a call to FreePool().\r
+\r
+  @retval  EFI_SUCCESS The controller specified by ControllerHandle and\r
+  ChildHandle passed the diagnostic.\r
+  @retval  EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+  EFI_HANDLE.\r
+  @retval  EFI_INVALID_PARAMETER Language is NULL.\r
+  @retval  EFI_INVALID_PARAMETER ErrorType is NULL.\r
+  @retval  EFI_INVALID_PARAMETER BufferType is NULL.\r
+  @retval  EFI_INVALID_PARAMETER Buffer is NULL.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support\r
+  running diagnostics for the controller specified\r
+  by ControllerHandle and ChildHandle.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  type of diagnostic specified by DiagnosticType.\r
+  @retval  EFI_UNSUPPORTED The driver specified by This does not support the\r
+  language specified by Language.\r
+  @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to complete\r
+  the diagnostics.\r
+  @retval  EFI_OUT_OF_RESOURCES There are not enough resources available to return\r
+  the status information in ErrorType, BufferSize,\r
+  and Buffer.\r
+  @retval  EFI_DEVICE_ERROR The controller specified by ControllerHandle and\r
+  ChildHandle did not pass the diagnostic.\r
+\r
+**/\r

 EFI_STATUS\r
 IDEBusDriverDiagnosticsRunDiagnostics (\r
   IN  EFI_DRIVER_DIAGNOSTICS_PROTOCOL               *This,\r
 EFI_STATUS\r
 IDEBusDriverDiagnosticsRunDiagnostics (\r
   IN  EFI_DRIVER_DIAGNOSTICS_PROTOCOL               *This,\r


@@ -55,67 +105,6 @@ IDEBusDriverDiagnosticsRunDiagnostics (
   OUT UINTN                                         *BufferSize,\r
   OUT CHAR16                                        **Buffer\r
   )\r
   OUT UINTN                                         *BufferSize,\r
   OUT CHAR16                                        **Buffer\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Runs diagnostics on a controller.\r
-\r
-  Arguments:\r
-    This             - A pointer to the EFI_DRIVER_DIAGNOSTICS_PROTOCOL \r
-                       instance.\r
-    ControllerHandle - The handle of the controller to run diagnostics on.\r
-    ChildHandle      - The handle of the child controller to run diagnostics on  \r
-                       This is an optional parameter that may be NULL.  It will \r
-                       be NULL for device drivers.  It will also be NULL for a \r
-                       bus drivers that wish to run diagnostics on the bus \r
-                       controller.  It will not be NULL for a bus driver that \r
-                       wishes to run diagnostics on one of its child \r
-                       controllers.\r
-    DiagnosticType   - Indicates type of diagnostics to perform on the \r
-                       controller specified by ControllerHandle and ChildHandle.\r
-                       See "Related Definitions" for the list of supported \r
-                       types.\r
-    Language         - A pointer to a three character ISO 639-2 language \r
-                       identifier.  This is the language in which the optional \r
-                       error message should be returned in Buffer, and it must \r
-                       match one of the languages specified in \r
-                       SupportedLanguages. The number of languages supported by\r
-                       a driver is up to the driver writer.\r
-    ErrorType        - A GUID that defines the format of the data returned in \r
-                       Buffer.  \r
-    BufferSize       - The size, in bytes, of the data returned in Buffer.  \r
-    Buffer           - A buffer that contains a Null-terminated Unicode string \r
-                       plus some additional data whose format is defined by \r
-                       ErrorType.  Buffer is allocated by this function with \r
-                       AllocatePool(), and it is the caller's responsibility \r
-                       to free it with a call to FreePool().  \r
-\r
-  Returns:\r
-    EFI_SUCCESS           - The controller specified by ControllerHandle and \r
-                            ChildHandle passed the diagnostic.\r
-    EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid \r
-                            EFI_HANDLE.\r
-    EFI_INVALID_PARAMETER - Language is NULL.\r
-    EFI_INVALID_PARAMETER - ErrorType is NULL.\r
-    EFI_INVALID_PARAMETER - BufferType is NULL.\r
-    EFI_INVALID_PARAMETER - Buffer is NULL.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support \r
-                            running diagnostics for the controller specified \r
-                            by ControllerHandle and ChildHandle.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            type of diagnostic specified by DiagnosticType.\r
-    EFI_UNSUPPORTED       - The driver specified by This does not support the \r
-                            language specified by Language.\r
-    EFI_OUT_OF_RESOURCES  - There are not enough resources available to complete\r
-                            the diagnostics.\r
-    EFI_OUT_OF_RESOURCES  - There are not enough resources available to return\r
-                            the status information in ErrorType, BufferSize, \r
-                            and Buffer.\r
-    EFI_DEVICE_ERROR      - The controller specified by ControllerHandle and \r
-                            ChildHandle did not pass the diagnostic.\r
-\r
---*/\r

 {\r
   EFI_STATUS            Status;\r
   EFI_PCI_IO_PROTOCOL   *PciIo;\r
 {\r
   EFI_STATUS            Status;\r
   EFI_PCI_IO_PROTOCOL   *PciIo;\r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c
index 88e81c0ada92d6e7f436249335fe72f1108fee97..9a1542d0ea649f1efac2f92d5790336fce762e26 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c
@@ -1,33 +1,25 @@
-/*++\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
-\r
-Module Name:\r
-\r
-    ata.c\r
-    \r
-Abstract: \r
-    \r
-Revision History\r
-\r
-    2002-6: Add Atapi6 enhancement, support >120GB hard disk, including\r
-            update - ATAIdentity() func\r
-            update - AtaBlockIoReadBlocks() func\r
-            update - AtaBlockIoWriteBlocks() func\r
-            add    - AtaAtapi6Identify() func\r
-            add    - AtaReadSectorsExt() func\r
-            add    - AtaWriteSectorsExt() func\r
-            add    - AtaPioDataInExt() func\r
-            add    - AtaPioDataOutExt() func\r
-            \r
---*/\r
+/** @file\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
+\r
+  @par Revision Reference:\r
+  2002-6: Add Atapi6 enhancement, support >120GB hard disk, including\r
+  update - ATAIdentity() func\r
+  update - AtaBlockIoReadBlocks() func\r
+  update - AtaBlockIoWriteBlocks() func\r
+  add    - AtaAtapi6Identify() func\r
+  add    - AtaReadSectorsExt() func\r
+  add    - AtaWriteSectorsExt() func\r
+  add    - AtaPioDataInExt() func\r
+  add    - AtaPioDataOutExt() func\r
+\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 \r
 #include "idebus.h"\r
 \r


@@ -68,46 +60,34 @@ AtaPioDataOutExt (
   IN  UINT16          SectorCount\r
   );\r
 \r
   IN  UINT16          SectorCount\r
   );\r
 \r

-EFI_STATUS\r
-ATAIdentify (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev\r
-  )\r
-/*++\r
-  Name:\r
-        ATAIdentify\r
-\r
+/**\r
+  Sends out an ATA Identify Command to the specified device.\r

 \r
 \r

-  Purpose: \r
-        This function is called by DiscoverIdeDevice() during its device\r
-        identification. It sends out the ATA Identify Command to the \r
-        specified device. Only ATA device responses to this command. If \r
-        the command succeeds, it returns the Identify data structure which \r
-        contains information about the device. This function extracts the \r
-        information it needs to fill the IDE_BLK_IO_DEV data structure, \r
-        including device type, media block size, media capacity, and etc.\r
+  This function is called by DiscoverIdeDevice() during its device\r
+  identification. It sends out the ATA Identify Command to the \r
+  specified device. Only ATA device responses to this command. If \r
+  the command succeeds, it returns the Identify data structure which \r
+  contains information about the device. This function extracts the \r
+  information it needs to fill the IDE_BLK_IO_DEV data structure, \r
+  including device type, media block size, media capacity, and etc.\r

 \r
 \r

+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure,used\r
+  to record all the information of the IDE device.\r

 \r
 \r

-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure,used\r
-          to record all the information of the IDE device.\r
-\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Identify ATA device successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          ATA Identify Device Command failed or device is not \r
-          ATA device.\r
+  @retval EFI_SUCCESS Identify ATA device successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR ATA Identify Device Command failed or\r
+  device is not ATA device.\r

 \r
 \r

+  @note\r
+  parameter IdeDev will be updated in this function.\r

 \r
 \r

-  Notes:\r
-        parameter IdeDev will be updated in this function.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
+**/\r
+EFI_STATUS\r
+ATAIdentify (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev\r
+  )\r

 {\r
   EFI_STATUS        Status;\r
   EFI_IDENTIFY_DATA *AtaIdentifyPointer;\r
 {\r
   EFI_STATUS        Status;\r
   EFI_IDENTIFY_DATA *AtaIdentifyPointer;\r


@@ -213,42 +193,30 @@ ATAIdentify (
 }\r
 \r
 \r
 }\r
 \r
 \r

-EFI_STATUS\r
-AtaAtapi6Identify (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev\r
-  )\r
-/*++\r
-  Name:\r
-  \r
-        AtaAtapi6Identify\r
+/**\r
+  This function is called by ATAIdentify() to identity whether this disk\r
+  supports ATA/ATAPI6 48bit addressing, ie support >120G capacity\r

 \r
 \r

-  Purpose: \r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval  EFI_SUCCESS The disk specified by IdeDev is a Atapi6 supported one\r
+  and 48-bit addressing must be used\r

   \r
   \r

-        This function is called by ATAIdentify() to identity whether this disk\r
-        supports ATA/ATAPI6 48bit addressing, ie support >120G capacity\r
+  @retval  EFI_UNSUPPORTED The disk dosn't not support Atapi6 or it supports but\r
+  the capacity is below 120G, 48bit addressing is not\r
+  needed\r

 \r
 \r

-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
+  @note\r
+  This function must be called after DEVICE_IDENTITY command has been \r
+  successfully returned\r

 \r
 \r

-  Returns:  \r
-  \r
-        EFI_SUCCESS     - The disk specified by IdeDev is a Atapi6 supported one\r
-                          and 48-bit addressing must be used\r
-\r
-        EFI_UNSUPPORTED - The disk dosn't not support Atapi6 or it supports but\r
-                          the capacity is below 120G, 48bit addressing is not \r
-                          needed\r
-                          \r
-  Notes:\r
-\r
-       This function must be called after DEVICE_IDENTITY command has been \r
-       successfully returned\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
+**/\r
+EFI_STATUS\r
+AtaAtapi6Identify (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev\r
+  )\r

 {\r
   UINT8             Index;\r
   EFI_LBA           TmpLba;\r
 {\r
   UINT8             Index;\r
   EFI_LBA           TmpLba;\r


@@ -304,33 +272,19 @@ AtaAtapi6Identify (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
   return EFI_UNSUPPORTED;\r
 }\r
 \r

+/**\r
+  This function is called by ATAIdentify() or ATAPIIdentify()\r
+  to print device's module name. \r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+**/\r

 VOID\r
 PrintAtaModuleName (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 VOID\r
 PrintAtaModuleName (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        PrintAtaModuleName\r
-\r
-\r
-  Purpose: \r
-        This function is called by ATAIdentify() or ATAPIIdentify()\r
-        to print device's module name. \r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        no returns.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   if (IdeDev->pIdData == NULL) {\r
     return ;\r
 {\r
   if (IdeDev->pIdData == NULL) {\r
     return ;\r


@@ -340,6 +294,44 @@ PrintAtaModuleName (
   IdeDev->ModelName[40] = 0x00;\r
 }\r
 \r
   IdeDev->ModelName[40] = 0x00;\r
 }\r
 \r

+/**\r
+  This function is used to send out ATA commands conforms to the \r
+  PIO Data In Protocol.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Buffer\r
+  buffer contained data transferred from device to host.\r
+\r
+  @param[in] ByteCount\r
+  data size in byte unit of the buffer.\r
+\r
+  @param[in] AtaCommand\r
+  value of the Command Register\r
+\r
+  @param[in] Head\r
+  value of the Head/Device Register\r
+\r
+  @param[in] SectorCount\r
+  value of the Sector Count Register\r
+\r
+  @param[in] SectorNumber\r
+  value of the Sector Number Register\r
+\r
+  @param[in] CylinderLsb\r
+  value of the low byte of the Cylinder Register\r
+\r
+  @param[in] CylinderMsb\r
+  value of the high byte of the Cylinder Register\r
+\r
+  @retval EFI_SUCCESS send out the ATA command and device send required\r
+  data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR command sent failed.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaPioDataIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -352,66 +344,6 @@ AtaPioDataIn (
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r

-/*++\r
-  Name:\r
-        AtaPioDataIn\r
-\r
-\r
-  Purpose: \r
-        This function is used to send out ATA commands conforms to the \r
-        PIO Data In Protocol.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          buffer contained data transferred from device to host.\r
-\r
-        UINT32      IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINT8     IN    AtaCommand\r
-          value of the Command Register\r
-\r
-        UINT8     IN    Head\r
-          value of the Head/Device Register\r
-\r
-        UINT8     IN    SectorCount\r
-          value of the Sector Count Register\r
-\r
-        UINT8     IN    SectorNumber\r
-          value of the Sector Number Register\r
-\r
-        UINT8     IN    CylinderLsb\r
-          value of the low byte of the Cylinder Register\r
-\r
-        UINT8     IN    CylinderMsb\r
-          value of the high byte of the Cylinder Register\r
-\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          send out the ATA command and device send required\r
-          data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          command sent failed.\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    AtaCommand - add argument and description to function comment\r
-// TODO:    Head - add argument and description to function comment\r
-// TODO:    SectorCount - add argument and description to function comment\r
-// TODO:    SectorNumber - add argument and description to function comment\r
-// TODO:    CylinderLsb - add argument and description to function comment\r
-// TODO:    CylinderMsb - add argument and description to function comment\r

 {\r
   UINTN       WordCount;\r
   UINTN       Increment;\r
 {\r
   UINTN       WordCount;\r
   UINTN       Increment;\r


@@ -529,6 +461,29 @@ AtaPioDataIn (
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r

+/**\r
+  This function is used to send out ATA commands conforms to the \r
+  PIO Data Out Protocol.\r
+\r
+  @param *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param *Buffer      buffer contained data transferred from host to device.\r
+  @param ByteCount    data size in byte unit of the buffer.\r
+  @param AtaCommand   value of the Command Register\r
+  @param Head         value of the Head/Device Register\r
+  @param SectorCount  value of the Sector Count Register\r
+  @param SectorNumber value of the Sector Number Register\r
+  @param CylinderLsb  value of the low byte of the Cylinder Register\r
+  @param CylinderMsb  value of the high byte of the Cylinder Register\r
+\r
+  @retval EFI_SUCCESS send out the ATA command and device received required\r
+  data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR command sent failed.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaPioDataOut (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataOut (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -541,67 +496,6 @@ AtaPioDataOut (
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r

-/*++\r
-  Name:\r
-        AtaPioDataOut\r
-\r
-\r
-  Purpose: \r
-        This function is used to send out ATA commands conforms to the \r
-        PIO Data Out Protocol.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          buffer contained data transferred from host to device.\r
-\r
-        UINT32      IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINT8     IN    AtaCommand\r
-          value of the Command Register\r
-\r
-        UINT8     IN    Head\r
-          value of the Head/Device Register\r
-\r
-        UINT8     IN    SectorCount\r
-          value of the Sector Count Register\r
-\r
-        UINT8     IN    SectorNumber\r
-          value of the Sector Number Register\r
-\r
-        UINT8     IN    CylinderLsb\r
-          value of the low byte of the Cylinder Register\r
-\r
-        UINT8     IN    CylinderMsb\r
-          value of the high byte of the Cylinder Register\r
-\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          send out the ATA command and device received required\r
-          data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          command sent failed. \r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    AtaCommand - add argument and description to function comment\r
-// TODO:    Head - add argument and description to function comment\r
-// TODO:    SectorCount - add argument and description to function comment\r
-// TODO:    SectorNumber - add argument and description to function comment\r
-// TODO:    CylinderLsb - add argument and description to function comment\r
-// TODO:    CylinderMsb - add argument and description to function comment\r

 {\r
   UINTN       WordCount;\r
   UINTN       Increment;\r
 {\r
   UINTN       WordCount;\r
   UINTN       Increment;\r


@@ -718,38 +612,23 @@ AtaPioDataOut (
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r

+/**\r
+  This function is used to analyze the Status Register and print out \r
+  some debug information and if there is ERR bit set in the Status\r
+  Register, the Error Register's value is also be parsed and print out.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS       No err information in the Status Register.\r
+  @retval EFI_DEVICE_ERROR  Any err information in the Status Register.\r
+\r
+**/\r

 EFI_STATUS\r
 CheckErrorStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 CheckErrorStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        CheckErrorStatus\r
-\r
-\r
-  Purpose: \r
-        This function is used to analyze the Status Register and print out \r
-        some debug information and if there is ERR bit set in the Status\r
-        Register, the Error Register's value is also be parsed and print out.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          No err information in the Status Register.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Any err information in the Status Register.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   UINT8 StatusRegister;\r
 \r
 {\r
   UINT8 StatusRegister;\r
 \r


@@ -841,6 +720,28 @@ CheckErrorStatus (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoReadBlocks() to perform\r
+  reading from media in block unit.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer\r
+  A pointer to the destination buffer for the data. \r
+\r
+  @param[in] Lba\r
+  The starting logical block address to read from \r
+  on the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return return status is fully dependent on the return status\r
+  of AtaPioDataIn() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -848,43 +749,6 @@ AtaReadSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-        AtaReadSectors\r
-\r
-\r
-  Purpose: \r
-        This function is called by the AtaBlkIoReadBlocks() to perform\r
-        reading from media in block unit.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the destination buffer for the data. \r
-\r
-        EFI_LBA     IN    Lba\r
-          The starting logical block address to read from \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-        return status is fully dependent on the return status\r
-        of AtaPioDataIn() function.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    Lba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r
 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r


@@ -974,6 +838,28 @@ AtaReadSectors (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoWriteBlocks() to perform\r
+  writing onto media in block unit.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure,used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *BufferData\r
+  A pointer to the source buffer for the data. \r
+\r
+  @param[in] Lba\r
+  The starting logical block address to write onto \r
+  the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return return status is fully dependent on the return status\r
+  of AtaPioDataOut() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -981,44 +867,6 @@ AtaWriteSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-        AtaWriteSectors\r
-\r
-\r
-  Purpose: \r
-        This function is called by the AtaBlkIoWriteBlocks() to perform\r
-        writing onto media in block unit.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure,used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *BufferData\r
-          A pointer to the source buffer for the data. \r
-\r
-        EFI_LBA     IN    Lba\r
-          The starting logical block address to write onto \r
-          the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-\r
-  Returns:  \r
-        return status is fully dependent on the return status\r
-        of AtaPioDataOut() function.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    BufferData - add argument and description to function comment\r
-// TODO:    Lba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r
 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r


@@ -1095,41 +943,34 @@ AtaWriteSectors (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is used to implement the Soft Reset on the specified\r
+  device. But, the ATA Soft Reset mechanism is so strong a reset method \r
+  that it will force resetting on both devices connected to the \r
+  same cable.\r
+\r
+  It is called by IdeBlkIoReset(), a interface function of Block\r
+  I/O protocol.\r
+\r
+  This function can also be used by the ATAPI device to perform reset when\r
+  ATAPI Reset command is failed.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS       Soft reset completes successfully.\r
+  @retval EFI_DEVICE_ERROR  Any step during the reset process is failed.\r
+\r
+  @note\r
+  The registers initial values after ATA soft reset are different\r
+  to the ATA device and ATAPI device.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtaSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        AtaSoftReset\r
-\r
-  Purpose: \r
-        This function is used to implement the Soft Reset on the specified\r
-        device. But, the ATA Soft Reset mechanism is so strong a reset method \r
-        that it will force resetting on both devices connected to the \r
-        same cable.\r
-        It is called by IdeBlkIoReset(), a interface function of Block\r
-        I/O protocol.\r
-        This function can also be used by the ATAPI device to perform reset when\r
-        ATAPI Reset command is failed.\r
-            \r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Soft reset completes successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Any step during the reset process is failed.\r
-  Notes:\r
-        The registers initial values after ATA soft reset are different\r
-        to the ATA device and ATAPI device.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
 \r
   UINT8 DeviceControl;\r
 {\r
 \r
   UINT8 DeviceControl;\r


@@ -1165,77 +1006,55 @@ AtaSoftReset (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-AtaBlkIoReadBlocks (\r
-  IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
-  IN UINT32           MediaId,\r
-  IN EFI_LBA          LBA,\r
-  IN UINTN            BufferSize,\r
-  OUT VOID            *Buffer\r
-  )\r
-/*++\r
-  Name:\r
-      AtaBlkIoReadBlocks\r
-\r
-\r
-  Purpose: \r
-      This function is the ATA implementation for ReadBlocks in the\r
-      Block I/O Protocol interface.\r
-\r
+/**\r
+  This function is the ATA implementation for ReadBlocks in the\r
+  Block I/O Protocol interface.\r

 \r
 \r

-  Parameters:\r
-      IDE_BLK_IO_DEV    IN    *IdeBlkIoDevice\r
-        Indicates the calling context.\r
+  @param[in] *IdeBlkIoDevice\r
+  Indicates the calling context.\r

 \r
 \r

-      UINT32      IN    MediaId\r
-        The media id that the read request is for.\r
+  @param[in] MediaId\r
+  The media id that the read request is for.\r

 \r
 \r

-      EFI_LBA     IN    LBA\r
-        The starting logical block address to read from \r
-        on the device.\r
+  @param[in] LBA\r
+  The starting logical block address to read from \r
+  on the device.\r

 \r
 \r

-      UINTN     IN    BufferSize\r
-        The size of the Buffer in bytes. This must be a\r
-        multiple of the intrinsic block size of the device.\r
+  @param[in] BufferSize\r
+  The size of the Buffer in bytes. This must be a\r
+  multiple of the intrinsic block size of the device.\r

 \r
 \r

-      VOID      OUT   *Buffer\r
-        A pointer to the destination buffer for the data. \r
-        The caller is responsible for either having implicit\r
-        or explicit ownership of the memory that data is read into.\r
+  @param[out] *Buffer\r
+  A pointer to the destination buffer for the data. \r
+  The caller is responsible for either having implicit\r
+  or explicit ownership of the memory that data is read into.\r

 \r
 \r

-  Returns:  \r
-      EFI_SUCCESS \r
-        Read Blocks successfully.\r
-\r
-      EFI_DEVICE_ERROR\r
-        Read Blocks failed.\r
-\r
-      EFI_NO_MEDIA\r
-        There is no media in the device.\r
-\r
-      EFI_MEDIA_CHANGE\r
-        The MediaId is not for the current media.\r
-\r
-      EFI_BAD_BUFFER_SIZE\r
-        The BufferSize parameter is not a multiple of the \r
-        intrinsic block size of the device.\r
+  @retval EFI_SUCCESS       Read Blocks successfully.\r
+  @retval EFI_DEVICE_ERROR  Read Blocks failed.\r
+  @retval EFI_NO_MEDIA      There is no media in the device.\r
+  @retval EFI_MEDIA_CHANGE  The MediaId is not for the current media.\r
+  \r
+  @retval EFI_BAD_BUFFER_SIZE\r
+  The BufferSize parameter is not a multiple of the\r
+  intrinsic block size of the device.\r
+  \r
+  @retval EFI_INVALID_PARAMETER\r
+  The read request contains LBAs that are not valid,\r
+  or the data buffer is not valid.\r

 \r
 \r

-      EFI_INVALID_PARAMETER\r
-        The read request contains LBAs that are not valid,\r
-        or the data buffer is not valid.\r
+  @note\r
+  If Read Block error because of device error, this function will call\r
+  AtaSoftReset() function to reset device.\r

 \r
 \r

-  Notes:\r
-      If Read Block error because of device error, this function will call\r
-      AtaSoftReset() function to reset device.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeBlkIoDevice - add argument and description to function comment\r
-// TODO:    MediaId - add argument and description to function comment\r
-// TODO:    LBA - add argument and description to function comment\r
-// TODO:    BufferSize - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    EFI_MEDIA_CHANGED - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+AtaBlkIoReadBlocks (\r
+  IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
+  IN UINT32           MediaId,\r
+  IN EFI_LBA          LBA,\r
+  IN UINTN            BufferSize,\r
+  OUT VOID            *Buffer\r
+  )\r

 {\r
   EFI_BLOCK_IO_MEDIA  *Media;\r
   UINTN               BlockSize;\r
 {\r
   EFI_BLOCK_IO_MEDIA  *Media;\r
   UINTN               BlockSize;\r


@@ -1315,6 +1134,48 @@ AtaBlkIoReadBlocks (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  This function is the ATA implementation for WriteBlocks in the\r
+  Block I/O Protocol interface.\r
+\r
+  @param[in] *IdeBlkIoDevice\r
+  Indicates the calling context.\r
+\r
+  @param[in] MediaId\r
+  The media id that the write request is for.\r
+\r
+  @param[in] LBA\r
+  The starting logical block address to write onto \r
+  the device.\r
+\r
+  @param[in] BufferSize\r
+  The size of the Buffer in bytes. This must be a\r
+  multiple of the intrinsic block size of the device.\r
+\r
+  @param[out] *Buffer\r
+  A pointer to the source buffer for the data. \r
+  The caller is responsible for either having implicit\r
+  or explicit ownership of the memory that data is \r
+  written from.\r
+\r
+  @retval EFI_SUCCESS       Write Blocks successfully.\r
+  @retval EFI_DEVICE_ERROR  Write Blocks failed.\r
+  @retval EFI_NO_MEDIA      There is no media in the device.\r
+  @retval EFI_MEDIA_CHANGE  The MediaId is not for the current media.\r
+  \r
+  @retval EFI_BAD_BUFFER_SIZE\r
+  The BufferSize parameter is not a multiple of the\r
+  intrinsic block size of the device.\r
+  \r
+  @retval EFI_INVALID_PARAMETER\r
+  The write request contains LBAs that are not valid,\r
+  or the data buffer is not valid.\r
+\r
+  @note\r
+  If Write Block error because of device error, this function will call\r
+  AtaSoftReset() function to reset device.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaBlkIoWriteBlocks (\r
   IN  IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtaBlkIoWriteBlocks (\r
   IN  IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -1323,70 +1184,6 @@ AtaBlkIoWriteBlocks (
   IN  UINTN            BufferSize,\r
   OUT VOID             *Buffer\r
   )\r
   IN  UINTN            BufferSize,\r
   OUT VOID             *Buffer\r
   )\r

-/*++\r
-  Name:\r
-        AtaBlkIoWriteBlocks\r
-\r
-\r
-  Purpose: \r
-        This function is the ATA implementation for WriteBlocks in the\r
-        Block I/O Protocol interface.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV   IN    *IdeBlkIoDevice\r
-          Indicates the calling context.\r
-\r
-        UINT32      IN    MediaId\r
-          The media id that the write request is for.\r
-\r
-        EFI_LBA     IN    LBA\r
-          The starting logical block address to write onto \r
-          the device.\r
-\r
-        UINTN     IN    BufferSize\r
-          The size of the Buffer in bytes. This must be a\r
-          multiple of the intrinsic block size of the device.\r
-\r
-        VOID      OUT   *Buffer\r
-          A pointer to the source buffer for the data. \r
-          The caller is responsible for either having implicit\r
-          or explicit ownership of the memory that data is \r
-          written from.\r
-\r
-\r
-  Returns:  \r
-        EFI_SUCCESS \r
-          Write Blocks successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Write Blocks failed.\r
-\r
-        EFI_NO_MEDIA\r
-          There is no media in the device.\r
-\r
-        EFI_MEDIA_CHANGE\r
-          The MediaId is not for the current media.\r
-\r
-        EFI_BAD_BUFFER_SIZE\r
-          The BufferSize parameter is not a multiple of the \r
-          intrinsic block size of the device.\r
-\r
-        EFI_INVALID_PARAMETER\r
-          The write request contains LBAs that are not valid,\r
-          or the data buffer is not valid.\r
-\r
-  Notes:\r
-        If Write Block error because of device error, this function will call\r
-        AtaSoftReset() function to reset device.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeBlkIoDevice - add argument and description to function comment\r
-// TODO:    MediaId - add argument and description to function comment\r
-// TODO:    LBA - add argument and description to function comment\r
-// TODO:    BufferSize - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    EFI_MEDIA_CHANGED - add return value to function comment\r

 {\r
 \r
   EFI_BLOCK_IO_MEDIA  *Media;\r
 {\r
 \r
   EFI_BLOCK_IO_MEDIA  *Media;\r


@@ -1457,6 +1254,24 @@ AtaBlkIoWriteBlocks (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoReadBlocks() to perform\r
+  reading from media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer    A pointer to the destination buffer for the data. \r
+  @param[in] StartLba       The starting logical block address to read from \r
+  on the device media.\r
+  @param[in] NumberOfBlocks The number of transfer data blocks.\r
+\r
+  @return return status is fully dependent on the return status\r
+  of AtaPioDataInExt() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaReadSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaReadSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1464,46 +1279,6 @@ AtaReadSectorsExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaReadSectorsExt\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoReadBlocks() to perform\r
-        reading from media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the destination buffer for the data. \r
-\r
-        EFI_LBA     IN    StartLba\r
-          The starting logical block address to read from \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-  \r
-        return status is fully dependent on the return status\r
-        of AtaPioDataInExt() function.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r
 {\r
   EFI_STATUS  Status;\r
   UINTN       BlocksRemaining;\r


@@ -1562,6 +1337,29 @@ AtaReadSectorsExt (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoWriteBlocks() to perform\r
+  writing onto media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure,used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer\r
+  A pointer to the source buffer for the data. \r
+\r
+  @param[in] Lba\r
+  The starting logical block address to write onto \r
+  the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return status is fully dependent on the return status\r
+  of AtaPioDataOutExt() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaWriteSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaWriteSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1569,46 +1367,6 @@ AtaWriteSectorsExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaWriteSectorsExt\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoWriteBlocks() to perform\r
-        writing onto media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure,used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the source buffer for the data. \r
-\r
-        EFI_LBA   IN    Lba\r
-          The starting logical block address to write onto \r
-          the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-  \r
-        return status is fully dependent on the return status\r
-        of AtaPioDataOutExt() function.\r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
   EFI_STATUS  Status;\r
   EFI_LBA     Lba64;\r
 {\r
   EFI_STATUS  Status;\r
   EFI_LBA     Lba64;\r


@@ -1668,6 +1426,32 @@ AtaWriteSectorsExt (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is used to send out ATA commands conforms to the \r
+  PIO Data In Protocol, supporting ATA/ATAPI-6 standard\r
+\r
+  Comparing with ATA-3 data in protocol, we have two differents here:<BR>\r
+  1. Do NOT wait for DRQ clear before sending command into IDE device.(the\r
+  wait will frequently fail... cause writing function return error)\r
+\r
+  2. Do NOT wait for DRQ clear after all data readed.(the wait greatly \r
+  slow down writing performance by 100 times!)\r
+\r
+  @param[in] *IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in,out] *Buffer  buffer contained data transferred from device to host.\r
+  @param[in] ByteCount    data size in byte unit of the buffer.\r
+  @param[in] AtaCommand   value of the Command Register\r
+  @param[in] StartLba     the start LBA of this transaction\r
+  @param[in] SectorCount  the count of sectors to be transfered\r
+\r
+  @retval EFI_SUCCESS send out the ATA command and device send required\r
+  data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR command sent failed.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaPioDataInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1677,63 +1461,6 @@ AtaPioDataInExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaPioDataInExt\r
-\r
-  Purpose: \r
-  \r
-        This function is used to send out ATA commands conforms to the \r
-        PIO Data In Protocol, supporting ATA/ATAPI-6 standard\r
-\r
-        Comparing with ATA-3 data in protocol, we have two differents here:\r
-        1. Do NOT wait for DRQ clear before sending command into IDE device.(the\r
-           wait will frequently fail... cause writing function return error)\r
-           \r
-        2. Do NOT wait for DRQ clear after all data readed.(the wait greatly \r
-           slow down writing performance by 100 times!)\r
-\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN  OUT     *Buffer\r
-          buffer contained data transferred from device to host.\r
-\r
-        UINT32    IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINT8     IN    AtaCommand\r
-          value of the Command Register\r
-\r
-        EFI_LBA   IN    StartLba\r
-          the start LBA of this transaction\r
-          \r
-        UINT16    IN    SectorCount\r
-          the count of sectors to be transfered\r
-\r
-  Returns:  \r
-  \r
-        EFI_SUCCESS\r
-          send out the ATA command and device send required\r
-          data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          command sent failed.\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    AtaCommand - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    SectorCount - add argument and description to function comment\r

 {\r
   UINT8       DevSel;\r
   UINT8       SectorCount8;\r
 {\r
   UINT8       DevSel;\r
   UINT8       SectorCount8;\r


@@ -1864,6 +1591,33 @@ AtaPioDataInExt (
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r

+/**\r
+  This function is used to send out ATA commands conforms to the \r
+  PIO Data Out Protocol, supporting ATA/ATAPI-6 standard\r
+\r
+  Comparing with ATA-3 data out protocol, we have two differents here:<BR>\r
+  1. Do NOT wait for DRQ clear before sending command into IDE device.(the\r
+  wait will frequently fail... cause writing function return error)\r
+\r
+  2. Do NOT wait for DRQ clear after all data readed.(the wait greatly \r
+  slow down writing performance by 100 times!)\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Buffer      buffer contained data transferred from host to device.\r
+  @param[in] ByteCount    data size in byte unit of the buffer.\r
+  @param[in] AtaCommand   value of the Command Register\r
+  @param[in] StartLba     the start LBA of this transaction\r
+  @param[in] SectorCount  the count of sectors to be transfered\r
+\r
+  @retval EFI_SUCCESS send out the ATA command and device receive required\r
+  data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR command sent failed.\r
+\r
+**/\r

 EFI_STATUS\r
 AtaPioDataOutExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataOutExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1873,62 +1627,6 @@ AtaPioDataOutExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaPioDataOutExt\r
-\r
-  Purpose: \r
-  \r
-        This function is used to send out ATA commands conforms to the \r
-        PIO Data Out Protocol, supporting ATA/ATAPI-6 standard\r
-\r
-        Comparing with ATA-3 data out protocol, we have two differents here:\r
-        1. Do NOT wait for DRQ clear before sending command into IDE device.(the\r
-           wait will frequently fail... cause writing function return error)\r
-           \r
-        2. Do NOT wait for DRQ clear after all data readed.(the wait greatly \r
-           slow down writing performance by 100 times!)\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          buffer contained data transferred from host to device.\r
-\r
-        UINT32    IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINT8     IN    AtaCommand\r
-          value of the Command Register\r
-\r
-        EFI_LBA   IN    StartLba\r
-          the start LBA of this transaction\r
-          \r
-        UINT16    IN    SectorCount\r
-          the count of sectors to be transfered\r
-\r
-  Returns:  \r
-  \r
-        EFI_SUCCESS\r
-          send out the ATA command and device receive required\r
-          data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          command sent failed.\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    AtaCommand - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    SectorCount - add argument and description to function comment\r

 {\r
   UINT8       DevSel;\r
   UINT8       SectorCount8;\r
 {\r
   UINT8       DevSel;\r
   UINT8       SectorCount8;\r


@@ -2055,31 +1753,18 @@ AtaPioDataOutExt (
 }\r
 \r
 \r
 }\r
 \r
 \r

+/**\r
+  Enable SMART of the disk if supported\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure,used\r
+  to record all the information of the IDE device.\r
+\r
+**/\r

 VOID\r
 AtaSMARTSupport (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 VOID\r
 AtaSMARTSupport (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:  \r
-        AtaSMARTSupport\r
-\r
-  Purpose: \r
-\r
-        Enable SMART of the disk if supported\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure,used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-  \r
-        NONE\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   EFI_STATUS        Status;\r
   BOOLEAN           SMARTSupported;\r
 {\r
   EFI_STATUS        Status;\r
   BOOLEAN           SMARTSupported;\r


@@ -2213,6 +1898,20 @@ AtaSMARTSupport (
   return ;\r
 }\r
 \r
   return ;\r
 }\r
 \r

+/**\r
+  Send ATA Ext command into device with NON_DATA protocol\r
+\r
+  @param  IdeDev Standard IDE device private data structure\r
+  @param  AtaCommand The ATA command to be sent\r
+  @param  Device The value in Device register\r
+  @param  Feature The value in Feature register\r
+  @param  SectorCount The value in SectorCount register\r
+  @param  LbaAddress The LBA address in 48-bit mode\r
+\r
+  @retval  EFI_SUCCESS Reading succeed\r
+  @retval  EFI_DEVICE_ERROR Error executing commands on this device\r
+\r
+**/\r

 EFI_STATUS\r
 AtaCommandIssueExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaCommandIssueExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -2222,27 +1921,6 @@ AtaCommandIssueExt (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Send ATA Ext command into device with NON_DATA protocol\r
-\r
-Arguments:\r
-\r
-  IdeDev      - Standard IDE device private data structure\r
-  AtaCommand  - The ATA command to be sent\r
-  Device      - The value in Device register\r
-  Feature     - The value in Feature register\r
-  SectorCount - The value in SectorCount register \r
-  LbaAddress - The LBA address in 48-bit mode\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS      - Reading succeed\r
-  EFI_DEVICE_ERROR - Error executing commands on this device \r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       SectorCount8;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       SectorCount8;\r


@@ -2332,6 +2010,20 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Send ATA Ext command into device with NON_DATA protocol\r
+\r
+  @param  IdeDev Standard IDE device private data structure\r
+  @param  AtaCommand The ATA command to be sent\r
+  @param  Device The value in Device register\r
+  @param  Feature The value in Feature register\r
+  @param  SectorCount The value in SectorCount register\r
+  @param  LbaAddress The LBA address in 48-bit mode\r
+\r
+  @retval  EFI_SUCCESS Reading succeed\r
+  @retval  EFI_DEVICE_ERROR Error executing commands on this device\r
+\r
+**/\r

 EFI_STATUS\r
 AtaCommandIssue (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaCommandIssue (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -2341,27 +2033,6 @@ AtaCommandIssue (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Send ATA Ext command into device with NON_DATA protocol\r
-\r
-Arguments:\r
-\r
-  IdeDev      - Standard IDE device private data structure\r
-  AtaCommand  - The ATA command to be sent\r
-  Device      - The value in Device register\r
-  Feature     - The value in Feature register\r
-  SectorCount - The value in SectorCount register \r
-  LbaAddress - The LBA address in 48-bit mode\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS      - Reading succeed\r
-  EFI_DEVICE_ERROR - Error executing commands on this device \r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       SectorCount8;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       SectorCount8;\r


@@ -2437,6 +2108,29 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoReadBlocks() to perform\r
+  reading from media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer A pointer to the destination buffer for the data. \r
+\r
+  @param[in] StartLba The starting logical block address to read from \r
+  on the device media.\r
+\r
+  @param[in] NumberOfBlocks The number of transfer data blocks.\r
+\r
+  @return The device status of UDMA operation. If the operation is\r
+  successful, return EFI_SUCCESS.\r
+\r
+  TODO:    EFI_UNSUPPORTED - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtaUdmaReadExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaReadExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -2444,49 +2138,6 @@ AtaUdmaReadExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaUdmaReadExt\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoReadBlocks() to perform\r
-        reading from media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the destination buffer for the data. \r
-\r
-        EFI_LBA     IN    StartLba\r
-          The starting logical block address to read from \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-\r
-        The device status of UDMA operation. If the operation is \r
-         successful, return EFI_SUCCESS.\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r
 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r


@@ -2752,6 +2403,28 @@ AtaUdmaReadExt (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoReadBlocks() to perform\r
+  reading from media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer    A pointer to the destination buffer for the data. \r
+  @param[in] StartLba       The starting logical block address to read from \r
+  on the device media.\r
+  @param[in] NumberOfBlocks The number of transfer data blocks.\r
+\r
+  @return The device status of UDMA operation. If the operation is\r
+  successful, return EFI_SUCCESS.\r
+\r
+  TODO:    EFI_UNSUPPORTED - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtaUdmaRead (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaRead (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -2759,49 +2432,6 @@ AtaUdmaRead (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaUdmaRead\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoReadBlocks() to perform\r
-        reading from media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the destination buffer for the data. \r
-\r
-        EFI_LBA     IN    StartLba\r
-          The starting logical block address to read from \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-\r
-        The device status of UDMA operation. If the operation is \r
-         successful, return EFI_SUCCESS.\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r
 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r


@@ -3066,6 +2696,28 @@ AtaUdmaRead (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoWriteBlocks() to perform\r
+  writing to media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer A pointer to the source buffer for the data. \r
+\r
+  @param[in] StartLba The starting logical block address to write to \r
+  on the device media.\r
+\r
+  @param[in] NumberOfBlocks The number of transfer data blocks.\r
+\r
+  @return The device status of UDMA operation. If the operation is\r
+  successful, return EFI_SUCCESS.\r
+\r
+  TODO:    EFI_UNSUPPORTED - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtaUdmaWriteExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaWriteExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -3073,48 +2725,6 @@ AtaUdmaWriteExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaUdmaWriteExt\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoWriteBlocks() to perform\r
-        writing to media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the source buffer for the data. \r
-\r
-        EFI_LBA     IN    StartLba\r
-          The starting logical block address to write to \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-\r
-        The device status of UDMA operation. If the operation is \r
-         successful, return EFI_SUCCESS.\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r
 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r


@@ -3377,6 +2987,32 @@ AtaUdmaWriteExt (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by the AtaBlkIoWriteBlocks() to perform\r
+  writing to media in block unit. The function has been enhanced to \r
+  support >120GB access and transfer at most 65536 blocks per command\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *DataBuffer\r
+  A pointer to the source buffer for the data. \r
+\r
+  @param[in] StartLba\r
+  The starting logical block address to write to \r
+  on the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return The device status of UDMA operation. If the operation is\r
+  successful, return EFI_SUCCESS.\r
+\r
+  TODO:    EFI_UNSUPPORTED - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtaUdmaWrite (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaWrite (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -3384,48 +3020,6 @@ AtaUdmaWrite (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-  \r
-        AtaUdmaWrite\r
-\r
-  Purpose: \r
-  \r
-        This function is called by the AtaBlkIoWriteBlocks() to perform\r
-        writing to media in block unit. The function has been enhanced to \r
-        support >120GB access and transfer at most 65536 blocks per command\r
-\r
-  Parameters:\r
-  \r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *DataBuffer\r
-          A pointer to the source buffer for the data. \r
-\r
-        EFI_LBA     IN    StartLba\r
-          The starting logical block address to write to \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-\r
-        The device status of UDMA operation. If the operation is \r
-         successful, return EFI_SUCCESS.\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    DataBuffer - add argument and description to function comment\r
-// TODO:    StartLba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r
-// TODO:    EFI_UNSUPPORTED - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r
 {\r
   IDE_DMA_PRD *PrdAddr;\r
   IDE_DMA_PRD *UsedPrdAddr;\r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c
index fa004e3d7f999e286f63869bbbae190d3e980a3c..70433066420bba4c74dafc4e683ae8033fc7b286 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c
@@ -1,67 +1,50 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
+**/\r

 \r
 \r

-  atapi.c\r
-    \r
-Abstract: \r
-    \r
+#include "idebus.h"\r

 \r
 \r

-Revision History\r
---*/\r
+/**\r
+  This function is used to get the current status of the media residing\r
+  in the LS-120 drive or ZIP drive. The media status is returned in the \r
+  Error Status.\r

 \r
 \r

-#include "idebus.h"\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  The media status is achieved successfully and the media\r
+  can be read/written.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Get Media Status Command is failed.\r
+  \r
+  @retval EFI_NO_MEDIA\r
+  There is no media in the drive.\r
+  \r
+  @retval EFI_WRITE_PROTECTED\r
+  The media is writing protected.\r

 \r
 \r

+  @note\r
+  This function must be called after the LS120EnableMediaStatus() \r
+  with second parameter set to TRUE \r
+  (means enable media status notification) is called.\r
+\r
+**/\r

 STATIC\r
 EFI_STATUS\r
 LS120GetMediaStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 STATIC\r
 EFI_STATUS\r
 LS120GetMediaStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        LS120GetMediaStatus\r
-\r
-  Purpose: \r
-        This function is used to get the current status of the media residing\r
-        in the LS-120 drive or ZIP drive. The media status is returned in the \r
-        Error Status.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          The media status is achieved successfully and the media\r
-          can be read/written.             \r
-    \r
-        EFI_DEVICE_ERROR\r
-          Get Media Status Command is failed.\r
-\r
-        EFI_NO_MEDIA\r
-          There is no media in the drive.\r
-\r
-        EFI_WRITE_PROTECTED\r
-          The media is writing protected. \r
-\r
-  Notes:                \r
-        This function must be called after the LS120EnableMediaStatus() \r
-        with second parameter set to TRUE \r
-        (means enable media status notification) is called.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   UINT8       DeviceSelect;\r
   UINT8       StatusValue;\r
 {\r
   UINT8       DeviceSelect;\r
   UINT8       StatusValue;\r


@@ -119,43 +102,31 @@ LS120GetMediaStatus (
   }\r
 }\r
 \r
   }\r
 }\r
 \r

+/**\r
+  This function is used to send Enable Media Status Notification Command\r
+  or Disable Media Status Notification Command.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] Enable\r
+  a flag that indicates whether enable or disable media\r
+  status notification.\r
+\r
+  @retval EFI_SUCCESS\r
+  If command completes successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  If command failed.\r
+\r
+**/\r

 STATIC\r
 EFI_STATUS\r
 LS120EnableMediaStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  BOOLEAN         Enable\r
   )\r
 STATIC\r
 EFI_STATUS\r
 LS120EnableMediaStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  BOOLEAN         Enable\r
   )\r

-/*++\r
-  Name:\r
-        LS120EnableMediaStatus\r
-\r
-  Purpose: \r
-        This function is used to send Enable Media Status Notification Command\r
-        or Disable Media Status Notification Command.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        BOOLEAN     IN    Enable\r
-          a flag that indicates whether enable or disable media\r
-          status notification.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          If command completes successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          If command failed.\r
-\r
-\r
-  Notes:                \r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Enable - add argument and description to function comment\r

 {\r
   UINT8       DeviceSelect;\r
   EFI_STATUS  Status;\r
 {\r
   UINT8       DeviceSelect;\r
   EFI_STATUS  Status;\r


@@ -211,60 +182,51 @@ LS120EnableMediaStatus (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is called by DiscoverIdeDevice() during its device\r
+  identification.\r
+\r
+  Its main purpose is to get enough information for the device media\r
+  to fill in the Media data structure of the Block I/O Protocol interface.\r
+\r
+  There are 5 steps to reach such objective:\r
+\r
+  1. Sends out the ATAPI Identify Command to the specified device. \r
+  Only ATAPI device responses to this command. If the command succeeds,\r
+  it returns the Identify data structure which filled with information \r
+  about the device. Since the ATAPI device contains removable media, \r
+  the only meaningful information is the device module name.\r
+\r
+  2. Sends out ATAPI Inquiry Packet Command to the specified device.\r
+  This command will return inquiry data of the device, which contains\r
+  the device type information.\r
+\r
+  3. Allocate sense data space for future use. We don't detect the media\r
+  presence here to improvement boot performance, especially when CD \r
+  media is present. The media detection will be performed just before\r
+  each BLK_IO read/write\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  Identify ATAPI device successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  ATAPI Identify Device Command failed or device type\r
+  is not supported by this IDE driver.\r
+\r
+  @note\r
+  Parameter "IdeDev" will be updated in this function.\r
+\r
+  TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
+  TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 ATAPIIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 ATAPIIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        ATAPIIdentify\r
-\r
-\r
-  Purpose: \r
-        This function is called by DiscoverIdeDevice() during its device\r
-        identification.\r
-\r
-        Its main purpose is to get enough information for the device media\r
-        to fill in the Media data structure of the Block I/O Protocol interface.\r
-\r
-        There are 5 steps to reach such objective:\r
-\r
-        1. Sends out the ATAPI Identify Command to the specified device. \r
-           Only ATAPI device responses to this command. If the command succeeds,\r
-           it returns the Identify data structure which filled with information \r
-           about the device. Since the ATAPI device contains removable media, \r
-           the only meaningful information is the device module name.\r
-\r
-        2. Sends out ATAPI Inquiry Packet Command to the specified device.\r
-           This command will return inquiry data of the device, which contains\r
-           the device type information.\r
-\r
-        3. Allocate sense data space for future use. We don't detect the media\r
-           presence here to improvement boot performance, especially when CD \r
-           media is present. The media detection will be performed just before\r
-           each BLK_IO read/write\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Identify ATAPI device successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          ATAPI Identify Device Command failed or device type \r
-          is not supported by this IDE driver.\r
-\r
-  Notes:\r
-        Parameter "IdeDev" will be updated in this function.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r
-// TODO:    EFI_OUT_OF_RESOURCES - add return value to function comment\r

 {\r
   EFI_IDENTIFY_DATA *AtapiIdentifyPointer;\r
   UINT8             DeviceSelect;\r
 {\r
   EFI_IDENTIFY_DATA *AtapiIdentifyPointer;\r
   UINT8             DeviceSelect;\r


@@ -409,35 +371,28 @@ ATAPIIdentify (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Sends out ATAPI Inquiry Packet Command to the specified device.\r
+  This command will return INQUIRY data of the device.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  Inquiry command completes successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Inquiry command failed.\r
+\r
+  @note\r
+  Parameter "IdeDev" will be updated in this function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiInquiry (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiInquiry (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        AtapiInquiry\r
-\r
-  Purpose: \r
-        Sends out ATAPI Inquiry Packet Command to the specified device.\r
-        This command will return INQUIRY data of the device.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Inquiry command completes successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Inquiry command failed.\r
-  Notes:\r
-        Parameter "IdeDev" will be updated in this function.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   ATAPI_PACKET_COMMAND  Packet;\r
   EFI_STATUS            Status;\r
 {\r
   ATAPI_PACKET_COMMAND  Packet;\r
   EFI_STATUS            Status;\r


@@ -476,6 +431,36 @@ AtapiInquiry (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is used to send out ATAPI commands conforms to the \r
+  Packet Command with PIO Data In Protocol.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Packet\r
+  pointer pointing to ATAPI_PACKET_COMMAND data structure\r
+  which contains the contents of the command.     \r
+\r
+  @param[in] *Buffer\r
+  buffer contained data transferred from device to host.\r
+\r
+  @param[in] ByteCount\r
+  data size in byte unit of the buffer.\r
+\r
+  @param[in] TimeOut\r
+  this parameter is used to specify the timeout \r
+  value for the PioReadWriteData() function. \r
+\r
+  @retval EFI_SUCCESS\r
+  send out the ATAPI packet command successfully\r
+  and device sends data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  the device failed to send data.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiPacketCommandIn (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r
 EFI_STATUS\r
 AtapiPacketCommandIn (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r


@@ -484,50 +469,6 @@ AtapiPacketCommandIn (
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r

-/*++\r
-  Name:\r
-        AtapiPacketCommandIn\r
-\r
-  Purpose: \r
-        This function is used to send out ATAPI commands conforms to the \r
-        Packet Command with PIO Data In Protocol.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        ATAPI_PACKET_COMMAND  IN  *Packet\r
-          pointer pointing to ATAPI_PACKET_COMMAND data structure\r
-          which contains the contents of the command.     \r
-              \r
-        UINT16      IN    *Buffer\r
-          buffer contained data transferred from device to host.\r
-\r
-        UINT32      IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINTN     IN    TimeOut\r
-          this parameter is used to specify the timeout \r
-          value for the PioReadWriteData() function. \r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          send out the ATAPI packet command successfully \r
-          and device sends data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          the device failed to send data.                 \r
-\r
-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Packet - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    TimeOut - add argument and description to function comment\r

 {\r
   UINT16      *CommandIndex;\r
   EFI_STATUS  Status;\r
 {\r
   UINT16      *CommandIndex;\r
   EFI_STATUS  Status;\r


@@ -605,6 +546,36 @@ AtapiPacketCommandIn (
   return PioReadWriteData (IdeDev, Buffer, ByteCount, 1, TimeOut);\r
 }\r
 \r
   return PioReadWriteData (IdeDev, Buffer, ByteCount, 1, TimeOut);\r
 }\r
 \r

+/**\r
+  This function is used to send out ATAPI commands conforms to the \r
+  Packet Command with PIO Data Out Protocol.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Packet\r
+  pointer pointing to ATAPI_PACKET_COMMAND data structure\r
+  which contains the contents of the command.\r
+\r
+  @param[in] *Buffer\r
+  buffer contained data transferred from host to device.\r
+\r
+  @param[in] ByteCount\r
+  data size in byte unit of the buffer.\r
+\r
+  @param[in] TimeOut\r
+  this parameter is used to specify the timeout \r
+  value for the PioReadWriteData() function. \r
+\r
+  @retval EFI_SUCCESS\r
+  send out the ATAPI packet command successfully\r
+  and device received data successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  the device failed to send data.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiPacketCommandOut (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r
 EFI_STATUS\r
 AtapiPacketCommandOut (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r


@@ -613,51 +584,6 @@ AtapiPacketCommandOut (
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r

-/*++\r
-  Name:\r
-        AtapiPacketCommandOut\r
-\r
-  Purpose: \r
-        This function is used to send out ATAPI commands conforms to the \r
-        Packet Command with PIO Data Out Protocol.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        ATAPI_PACKET_COMMAND  IN  *Packet\r
-          pointer pointing to ATAPI_PACKET_COMMAND data structure\r
-          which contains the contents of the command.\r
-\r
-        VOID      IN    *Buffer\r
-          buffer contained data transferred from host to device.\r
-\r
-        UINT32      IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        UINTN     IN    TimeOut\r
-          this parameter is used to specify the timeout \r
-          value for the PioReadWriteData() function. \r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          send out the ATAPI packet command successfully \r
-          and device received data successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          the device failed to send data. \r
-\r
-  Notes:\r
-  \r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Packet - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    TimeOut - add argument and description to function comment\r

 {\r
   UINT16      *CommandIndex;\r
   EFI_STATUS  Status;\r
 {\r
   UINT16      *CommandIndex;\r
   EFI_STATUS  Status;\r


@@ -733,6 +659,38 @@ AtapiPacketCommandOut (
   return PioReadWriteData (IdeDev, Buffer, ByteCount, 0, TimeOut);\r
 }\r
 \r
   return PioReadWriteData (IdeDev, Buffer, ByteCount, 0, TimeOut);\r
 }\r
 \r

+/**\r
+  This function is called by either AtapiPacketCommandIn() or \r
+  AtapiPacketCommandOut(). It is used to transfer data between\r
+  host and device. The data direction is specified by the fourth\r
+  parameter.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Buffer\r
+  buffer contained data transferred between host and device.\r
+\r
+  @param[in] ByteCount\r
+  data size in byte unit of the buffer.\r
+\r
+  @param[in] Read\r
+  flag used to determine the data transfer direction.\r
+  Read equals 1, means data transferred from device to host;\r
+  Read equals 0, means data transferred from host to device.\r
+\r
+  @param[in] TimeOut\r
+  timeout value for wait DRQ ready before each data \r
+  stream's transfer.\r
+\r
+  @retval EFI_SUCCESS\r
+  data is transferred successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  the device failed to transfer data.\r
+\r
+**/\r

 EFI_STATUS\r
 PioReadWriteData (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 PioReadWriteData (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -741,54 +699,6 @@ PioReadWriteData (
   IN  BOOLEAN         Read,\r
   IN  UINTN           TimeOut\r
   )\r
   IN  BOOLEAN         Read,\r
   IN  UINTN           TimeOut\r
   )\r

-/*++\r
-  Name:\r
-        PioReadWriteData\r
-\r
-  Purpose: \r
-        This function is called by either AtapiPacketCommandIn() or \r
-        AtapiPacketCommandOut(). It is used to transfer data between\r
-        host and device. The data direction is specified by the fourth\r
-        parameter.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          buffer contained data transferred between host and device.\r
-\r
-        UINT32      IN    ByteCount\r
-          data size in byte unit of the buffer.\r
-\r
-        BOOLEAN     IN    Read\r
-          flag used to determine the data transfer direction.\r
-          Read equals 1, means data transferred from device to host;\r
-          Read equals 0, means data transferred from host to device.\r
-\r
-        UINTN     IN    TimeOut\r
-          timeout value for wait DRQ ready before each data \r
-          stream's transfer.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          data is transferred successfully.  \r
-\r
-        EFI_DEVICE_ERROR\r
-          the device failed to transfer data.                 \r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    ByteCount - add argument and description to function comment\r
-// TODO:    Read - add argument and description to function comment\r
-// TODO:    TimeOut - add argument and description to function comment\r

 {\r
   //\r
   // required transfer data in word unit.\r
 {\r
   //\r
   // required transfer data in word unit.\r


@@ -888,36 +798,25 @@ PioReadWriteData (
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r
   return CheckErrorStatus (IdeDev);\r
 }\r
 \r

+/**\r
+  Sends out ATAPI Test Unit Ready Packet Command to the specified device\r
+  to find out whether device is accessible.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  device is accessible.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  device is not accessible.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiTestUnitReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiTestUnitReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        AtapiTestUnitReady\r
-\r
-  Purpose: \r
-        Sends out ATAPI Test Unit Ready Packet Command to the specified device\r
-        to find out whether device is accessible.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          device is accessible.\r
-\r
-        EFI_DEVICE_ERROR\r
-          device is not accessible.\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   ATAPI_PACKET_COMMAND  Packet;\r
   EFI_STATUS            Status;\r
 {\r
   ATAPI_PACKET_COMMAND  Packet;\r
   EFI_STATUS            Status;\r


@@ -935,50 +834,38 @@ AtapiTestUnitReady (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

-EFI_STATUS\r
-AtapiRequestSense (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev,\r
-  OUT UINTN           *SenseCounts\r
-  )\r
-/*++\r
-  Name:\r
-        AtapiRequestSense\r
-\r
-  Purpose: \r
-        Sends out ATAPI Request Sense Packet Command to the specified device.\r
-        This command will return all the current Sense data in the device. \r
-        This function will pack all the Sense data in one single buffer.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
+/**\r
+  Sends out ATAPI Request Sense Packet Command to the specified device.\r
+  This command will return all the current Sense data in the device. \r
+  This function will pack all the Sense data in one single buffer.\r

 \r
 \r

-        UINT16      OUT   **SenseBuffers\r
-          allocated in this function, and freed by the calling function.\r
-          This buffer is used to accommodate all the sense data returned \r
-          by the device.\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r

 \r
 \r

-        UINTN     OUT   *BufUnit\r
-          record the unit size of the sense data block in the SenseBuffers,\r
+  @param[out] **SenseBuffers\r
+  allocated in this function, and freed by the calling function.\r
+  This buffer is used to accommodate all the sense data returned \r
+  by the device.\r

 \r
 \r

-        UINTN     OUT   *BufNumbers\r
-          record the number of units in the SenseBuffers.\r
+  @param[out] *BufUnit\r
+  record the unit size of the sense data block in the SenseBuffers,\r

 \r
 \r

-  Returns:  \r
-        EFI_SUCCESS\r
-          Request Sense command completes successfully.\r
+  @param[out] *BufNumbers\r
+  record the number of units in the SenseBuffers.\r

 \r
 \r

-        EFI_DEVICE_ERROR\r
-          Request Sense command failed.\r
-\r
-  Notes:\r
+  @retval EFI_SUCCESS\r
+  Request Sense command completes successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Request Sense command failed.\r

 \r
 \r

---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    SenseCounts - add argument and description to function comment\r
+**/\r
+EFI_STATUS\r
+AtapiRequestSense (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev,\r
+  OUT UINTN           *SenseCounts\r
+  )\r

 {\r
   EFI_STATUS            Status;\r
   REQUEST_SENSE_DATA    *Sense;\r
 {\r
   EFI_STATUS            Status;\r
   REQUEST_SENSE_DATA    *Sense;\r


@@ -1053,45 +940,36 @@ AtapiRequestSense (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Sends out ATAPI Read Capacity Packet Command to the specified device.\r
+  This command will return the information regarding the capacity of the\r
+  media in the device.\r
+\r
+  Current device status will impact device's response to the Read Capacity\r
+  Command. For example, if the device once reset, the Read Capacity\r
+  Command will fail. The Sense data record the current device status, so \r
+  if the Read Capacity Command failed, the Sense data must be requested\r
+  and be analyzed to determine if the Read Capacity Command should retry.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  Read Capacity Command finally completes successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Read Capacity Command failed because of device error.\r
+\r
+  @note\r
+  parameter "IdeDev" will be updated in this function.\r
+\r
+  TODO:    EFI_NOT_READY - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtapiReadCapacity (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiReadCapacity (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        AtapiReadCapacity\r
-\r
-  Purpose: \r
-        Sends out ATAPI Read Capacity Packet Command to the specified device.\r
-        This command will return the information regarding the capacity of the\r
-        media in the device.\r
-\r
-        Current device status will impact device's response to the Read Capacity\r
-        Command. For example, if the device once reset, the Read Capacity\r
-        Command will fail. The Sense data record the current device status, so \r
-        if the Read Capacity Command failed, the Sense data must be requested\r
-        and be analyzed to determine if the Read Capacity Command should retry.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Read Capacity Command finally completes successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Read Capacity Command failed because of device error.\r
-\r
-  Notes:\r
-        parameter "IdeDev" will be updated in this function.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    EFI_NOT_READY - add return value to function comment\r

 {\r
   //\r
   // status returned by Read Capacity Packet Command\r
 {\r
   //\r
   // status returned by Read Capacity Packet Command\r


@@ -1207,48 +1085,39 @@ AtapiReadCapacity (
   }\r
 }\r
 \r
   }\r
 }\r
 \r

+/**\r
+  Used before read/write blocks from/to ATAPI device media. \r
+  Since ATAPI device media is removable, it is necessary to detect\r
+  whether media is present and get current present media's\r
+  information, and if media has been changed, Block I/O Protocol\r
+  need to be reinstalled.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[out] *MediaChange\r
+  return value that indicates if the media of the device has been\r
+  changed.\r
+\r
+  @retval EFI_SUCCESS\r
+  media found successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  any error encounters during media detection.\r
+  \r
+  @retval EFI_NO_MEDIA\r
+  media not found.\r
+\r
+  @note\r
+  parameter IdeDev may be updated in this function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiDetectMedia (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT BOOLEAN         *MediaChange\r
   )\r
 EFI_STATUS\r
 AtapiDetectMedia (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT BOOLEAN         *MediaChange\r
   )\r

-/*++\r
-  Name:\r
-        AtapiDetectMedia\r
-\r
-  Purpose: \r
-        Used before read/write blocks from/to ATAPI device media. \r
-        Since ATAPI device media is removable, it is necessary to detect\r
-        whether media is present and get current present media's\r
-        information, and if media has been changed, Block I/O Protocol\r
-        need to be reinstalled.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        BOOLEAN         OUT   *MediaChange\r
-          return value that indicates if the media of the device has been\r
-          changed.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          media found successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          any error encounters during media detection.\r
-          \r
-        EFI_NO_MEDIA\r
-          media not found.\r
-\r
-  Notes:\r
-        parameter IdeDev may be updated in this function.\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    MediaChange - add argument and description to function comment\r

 {\r
   EFI_STATUS          Status;\r
   EFI_STATUS          ReadCapacityStatus;\r
 {\r
   EFI_STATUS          Status;\r
   EFI_STATUS          ReadCapacityStatus;\r


@@ -1558,6 +1427,35 @@ AtapiDetectMedia (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  This function is called by the AtapiBlkIoReadBlocks() to perform\r
+  read from media in block unit.\r
+\r
+  The main command used to access media here is READ(10) Command. \r
+  READ(10) Command requests that the ATAPI device media transfer \r
+  specified data to the host. Data is transferred in block(sector) \r
+  unit. The maximum number of blocks that can be transferred once is\r
+  65536. This is the main difference between READ(10) and READ(12) \r
+  Command. The maximum number of blocks in READ(12) is 2 power 32.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Buffer\r
+  A pointer to the destination buffer for the data. \r
+\r
+  @param[in] Lba\r
+  The starting logical block address to read from \r
+  on the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return status is fully dependent on the return status\r
+  of AtapiPacketCommandIn() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtapiReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1565,49 +1463,6 @@ AtapiReadSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-        AtapiReadSectors\r
-\r
-  Purpose: \r
-        This function is called by the AtapiBlkIoReadBlocks() to perform\r
-        read from media in block unit.\r
-\r
-        The main command used to access media here is READ(10) Command. \r
-        READ(10) Command requests that the ATAPI device media transfer \r
-        specified data to the host. Data is transferred in block(sector) \r
-        unit. The maximum number of blocks that can be transferred once is\r
-        65536. This is the main difference between READ(10) and READ(12) \r
-        Command. The maximum number of blocks in READ(12) is 2 power 32.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          A pointer to the destination buffer for the data. \r
-\r
-        EFI_LBA     IN    Lba\r
-          The starting logical block address to read from \r
-          on the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-        return status is fully dependent on the return status\r
-        of AtapiPacketCommandIn() function.\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    Lba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
 \r
   ATAPI_PACKET_COMMAND  Packet;\r
 {\r
 \r
   ATAPI_PACKET_COMMAND  Packet;\r


@@ -1699,6 +1554,33 @@ AtapiReadSectors (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is called by the AtapiBlkIoWriteBlocks() to perform\r
+  write onto media in block unit.\r
+  The main command used to access media here is Write(10) Command. \r
+  Write(10) Command requests that the ATAPI device media transfer \r
+  specified data to the host. Data is transferred in block (sector) \r
+  unit. The maximum number of blocks that can be transferred once is\r
+  65536. \r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @param[in] *Buffer\r
+  A pointer to the source buffer for the data. \r
+\r
+  @param[in] Lba\r
+  The starting logical block address to write onto \r
+  the device media.\r
+\r
+  @param[in] NumberOfBlocks\r
+  The number of transfer data blocks.\r
+\r
+  @return status is fully dependent on the return status\r
+  of AtapiPacketCommandOut() function.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtapiWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1706,47 +1588,6 @@ AtapiWriteSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

-/*++\r
-  Name:\r
-        AtapiWriteSectors\r
-\r
-  Purpose: \r
-        This function is called by the AtapiBlkIoWriteBlocks() to perform\r
-        write onto media in block unit.\r
-        The main command used to access media here is Write(10) Command. \r
-        Write(10) Command requests that the ATAPI device media transfer \r
-        specified data to the host. Data is transferred in block (sector) \r
-        unit. The maximum number of blocks that can be transferred once is\r
-        65536. \r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        VOID      IN    *Buffer\r
-          A pointer to the source buffer for the data. \r
-\r
-        EFI_LBA     IN    Lba\r
-          The starting logical block address to write onto \r
-          the device media.\r
-\r
-        UINTN     IN    NumberOfBlocks\r
-          The number of transfer data blocks.\r
-\r
-  Returns:  \r
-        return status is fully dependent on the return status\r
-        of AtapiPacketCommandOut() function.\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    Lba - add argument and description to function comment\r
-// TODO:    NumberOfBlocks - add argument and description to function comment\r

 {\r
 \r
   ATAPI_PACKET_COMMAND  Packet;\r
 {\r
 \r
   ATAPI_PACKET_COMMAND  Packet;\r


@@ -1834,45 +1675,33 @@ AtapiWriteSectors (
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  This function is used to implement the Soft Reset on the specified\r
+  ATAPI device. Different from the AtaSoftReset(), here reset is a ATA\r
+  Soft Reset Command special for ATAPI device, and it only take effects\r
+  on the specified ATAPI device, not on the whole IDE bus.\r
+  Since the ATAPI soft reset is needed when device is in exceptional\r
+  condition (such as BSY bit is always set ), I think the Soft Reset\r
+  command should be sent without waiting for the BSY clear and DRDY\r
+  set.\r
+  This function is called by IdeBlkIoReset(), \r
+  a interface function of Block I/O protocol.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+\r
+  @retval EFI_SUCCESS\r
+  Soft reset completes successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Any step during the reset process is failed.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
-  Name:\r
-        AtapiSoftReset\r
-\r
-  Purpose: \r
-        This function is used to implement the Soft Reset on the specified\r
-        ATAPI device. Different from the AtaSoftReset(), here reset is a ATA\r
-        Soft Reset Command special for ATAPI device, and it only take effects\r
-        on the specified ATAPI device, not on the whole IDE bus.\r
-        Since the ATAPI soft reset is needed when device is in exceptional\r
-        condition (such as BSY bit is always set ), I think the Soft Reset\r
-        command should be sent without waiting for the BSY clear and DRDY\r
-        set.\r
-        This function is called by IdeBlkIoReset(), \r
-        a interface function of Block I/O protocol.\r
-\r
-            \r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          Soft reset completes successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Any step during the reset process is failed.\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r

 {\r
   UINT8       Command;\r
   UINT8       DeviceSelect;\r
 {\r
   UINT8       Command;\r
   UINT8       DeviceSelect;\r


@@ -1906,6 +1735,50 @@ AtapiSoftReset (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is the ATAPI implementation for ReadBlocks in the\r
+  Block I/O Protocol interface.\r
+\r
+  @param[in] *IdeBlkIoDev\r
+  Indicates the calling context.\r
+\r
+  @param[in] MediaId\r
+  The media id that the read request is for.\r
+\r
+  @param[in] LBA\r
+  The starting logical block address to read from \r
+  on the device.\r
+\r
+  @param[in] BufferSize\r
+  The size of the Buffer in bytes. This must be a\r
+  multiple of the intrinsic block size of the device.\r
+\r
+  @param[out] *Buffer\r
+  A pointer to the destination buffer for the data. \r
+  The caller is responsible for either having implicit\r
+  or explicit ownership of the memory that data is read into.\r
+\r
+  @retval EFI_SUCCESS\r
+  Read Blocks successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Read Blocks failed.\r
+  \r
+  @retval EFI_NO_MEDIA\r
+  There is no media in the device.\r
+  \r
+  @retval EFI_MEDIA_CHANGED\r
+  The MediaId is not for the current media.\r
+  \r
+  @retval EFI_BAD_BUFFER_SIZE\r
+  The BufferSize parameter is not a multiple of the\r
+  intrinsic block size of the device.\r
+  \r
+  @retval EFI_INVALID_PARAMETER\r
+  The read request contains LBAs that are not valid,\r
+  or the data buffer is not valid.\r
+\r
+**/\r

 EFI_STATUS\r
 AtapiBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtapiBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -1914,65 +1787,6 @@ AtapiBlkIoReadBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

-/*++\r
-  Name:\r
-        AtapiBlkIoReadBlocks\r
-\r
-  Purpose: \r
-        This function is the ATAPI implementation for ReadBlocks in the\r
-        Block I/O Protocol interface.\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeBlkIoDev\r
-          Indicates the calling context.\r
-\r
-        UINT32      IN    MediaId\r
-          The media id that the read request is for.\r
-\r
-        EFI_LBA     IN    LBA\r
-          The starting logical block address to read from \r
-          on the device.\r
-\r
-        UINTN     IN    BufferSize\r
-          The size of the Buffer in bytes. This must be a\r
-          multiple of the intrinsic block size of the device.\r
-\r
-        VOID      OUT   *Buffer\r
-          A pointer to the destination buffer for the data. \r
-          The caller is responsible for either having implicit\r
-          or explicit ownership of the memory that data is read into.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS \r
-          Read Blocks successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Read Blocks failed.\r
-\r
-        EFI_NO_MEDIA\r
-          There is no media in the device.\r
-\r
-        EFI_MEDIA_CHANGED\r
-          The MediaId is not for the current media.\r
-\r
-        EFI_BAD_BUFFER_SIZE\r
-          The BufferSize parameter is not a multiple of the \r
-          intrinsic block size of the device.\r
-\r
-        EFI_INVALID_PARAMETER\r
-          The read request contains LBAs that are not valid,\r
-          or the data buffer is not valid.\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeBlkIoDevice - add argument and description to function comment\r
-// TODO:    MediaId - add argument and description to function comment\r
-// TODO:    LBA - add argument and description to function comment\r
-// TODO:    BufferSize - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r

 {\r
   EFI_BLOCK_IO_MEDIA  *Media;\r
   UINTN               BlockSize;\r
 {\r
   EFI_BLOCK_IO_MEDIA  *Media;\r
   UINTN               BlockSize;\r


@@ -2074,6 +1888,53 @@ AtapiBlkIoReadBlocks (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  This function is the ATAPI implementation for WriteBlocks in the\r
+  Block I/O Protocol interface.\r
+\r
+  @param[in] *This\r
+  Indicates the calling context.\r
+\r
+  @param[in] MediaId\r
+  The media id that the write request is for.\r
+\r
+  @param[in] LBA\r
+  The starting logical block address to write onto \r
+  the device.\r
+\r
+  @param[in] BufferSize\r
+  The size of the Buffer in bytes. This must be a\r
+  multiple of the intrinsic block size of the device.\r
+\r
+  @param[out] *Buffer\r
+  A pointer to the source buffer for the data. \r
+  The caller is responsible for either having implicit\r
+  or explicit ownership of the memory that data is \r
+  written from.\r
+\r
+  @retval EFI_SUCCESS\r
+  Write Blocks successfully.\r
+  \r
+  @retval EFI_DEVICE_ERROR\r
+  Write Blocks failed.\r
+  \r
+  @retval EFI_NO_MEDIA\r
+  There is no media in the device.\r
+  \r
+  @retval EFI_MEDIA_CHANGE\r
+  The MediaId is not for the current media.\r
+  \r
+  @retval EFI_BAD_BUFFER_SIZE\r
+  The BufferSize parameter is not a multiple of the\r
+  intrinsic block size of the device.\r
+  \r
+  @retval EFI_INVALID_PARAMETER\r
+  The write request contains LBAs that are not valid,\r
+  or the data buffer is not valid.\r
+\r
+  TODO:    EFI_MEDIA_CHANGED - add return value to function comment\r
+  TODO:    EFI_WRITE_PROTECTED - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 AtapiBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtapiBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -2082,68 +1943,6 @@ AtapiBlkIoWriteBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

-/*++\r
-  Name:\r
-        AtapiBlkIoWriteBlocks\r
-\r
-  Purpose: \r
-        This function is the ATAPI implementation for WriteBlocks in the\r
-        Block I/O Protocol interface.\r
-\r
-  Parameters:\r
-        EFI_BLOCK_IO  IN    *This\r
-          Indicates the calling context.\r
-\r
-        UINT32      IN    MediaId\r
-          The media id that the write request is for.\r
-\r
-        EFI_LBA     IN    LBA\r
-          The starting logical block address to write onto \r
-          the device.\r
-\r
-        UINTN     IN    BufferSize\r
-          The size of the Buffer in bytes. This must be a\r
-          multiple of the intrinsic block size of the device.\r
-\r
-        VOID      OUT   *Buffer\r
-          A pointer to the source buffer for the data. \r
-          The caller is responsible for either having implicit\r
-          or explicit ownership of the memory that data is \r
-          written from.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS \r
-          Write Blocks successfully.\r
-\r
-        EFI_DEVICE_ERROR\r
-          Write Blocks failed.\r
-\r
-        EFI_NO_MEDIA\r
-          There is no media in the device.\r
-\r
-        EFI_MEDIA_CHANGE\r
-          The MediaId is not for the current media.\r
-\r
-        EFI_BAD_BUFFER_SIZE\r
-          The BufferSize parameter is not a multiple of the \r
-          intrinsic block size of the device.\r
-\r
-        EFI_INVALID_PARAMETER\r
-          The write request contains LBAs that are not valid,\r
-          or the data buffer is not valid. \r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeBlkIoDevice - add argument and description to function comment\r
-// TODO:    MediaId - add argument and description to function comment\r
-// TODO:    LBA - add argument and description to function comment\r
-// TODO:    BufferSize - add argument and description to function comment\r
-// TODO:    Buffer - add argument and description to function comment\r
-// TODO:    EFI_MEDIA_CHANGED - add return value to function comment\r
-// TODO:    EFI_WRITE_PROTECTED - add return value to function comment\r

 {\r
 \r
   EFI_BLOCK_IO_MEDIA  *Media;\r
 {\r
 \r
   EFI_BLOCK_IO_MEDIA  *Media;\r


@@ -2243,27 +2042,20 @@ AtapiBlkIoWriteBlocks (
 // which are used to parse sense key returned by the device.\r
 //\r
 \r
 // which are used to parse sense key returned by the device.\r
 //\r
 \r

-BOOLEAN\r
-IsNoMedia (\r
-  IN  REQUEST_SENSE_DATA    *SenseData,\r
-  IN  UINTN                 SenseCounts\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+BOOLEAN\r
+IsNoMedia (\r
+  IN  REQUEST_SENSE_DATA    *SenseData,\r
+  IN  UINTN                 SenseCounts\r
+  )\r

 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r
 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r


@@ -2289,35 +2081,23 @@ Returns:
   return NoMedia;\r
 }\r
 \r
   return NoMedia;\r
 }\r
 \r

+/**\r
+  Test if the device meets a media error after media changed\r
+\r
+  @param[in] *SenseData\r
+  pointer pointing to ATAPI device sense data list.\r
+  @param[in] SenseCounts\r
+  sense data number of the list          \r
+\r
+  @retval TRUE Device meets a media error\r
+  @retval FALSE No media error\r
+\r
+**/\r

 BOOLEAN\r
 IsMediaError (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r
 BOOLEAN\r
 IsMediaError (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r

-/*++\r
-  Name:\r
-        IsMediaError\r
-\r
-  Purpose: \r
-        Test if the device meets a media error after media changed\r
-\r
-  Parameters:\r
-        EQUEST_SENSE_DATA   IN  *SenseData\r
-          pointer pointing to ATAPI device sense data list.\r
-        UINTN               IN  SenseCounts\r
-          sense data number of the list          \r
-\r
-  Returns:  \r
-        TRUE\r
-          Device meets a media error\r
-\r
-        FALSE\r
-          No media error\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    SenseData - add argument and description to function comment\r
-// TODO:    SenseCounts - add argument and description to function comment\r

 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r
 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r


@@ -2375,27 +2155,20 @@ IsMediaError (
   return IsError;\r
 }\r
 \r
   return IsError;\r
 }\r
 \r

-BOOLEAN\r
-IsMediaChange (\r
-  IN  REQUEST_SENSE_DATA    *SenseData,\r
-  IN  UINTN                 SenseCounts\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+BOOLEAN\r
+IsMediaChange (\r
+  IN  REQUEST_SENSE_DATA    *SenseData,\r
+  IN  UINTN                 SenseCounts\r
+  )\r

 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r
 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r


@@ -2420,29 +2193,22 @@ Returns:
   return IsMediaChange;\r
 }\r
 \r
   return IsMediaChange;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r
+  @param  NeedRetry TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 BOOLEAN\r
 IsDriveReady (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts,\r
   OUT BOOLEAN               *NeedRetry\r
   )\r
 BOOLEAN\r
 IsDriveReady (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts,\r
   OUT BOOLEAN               *NeedRetry\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-  NeedRetry   - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r
 {\r
   REQUEST_SENSE_DATA  *SensePointer;\r
   UINTN               Index;\r


@@ -2496,27 +2262,20 @@ Returns:
   return IsReady;\r
 }\r
 \r
   return IsReady;\r
 }\r
 \r

-BOOLEAN\r
-HaveSenseKey (\r
-  IN  REQUEST_SENSE_DATA    *SenseData,\r
-  IN  UINTN                 SenseCounts\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+BOOLEAN\r
+HaveSenseKey (\r
+  IN  REQUEST_SENSE_DATA    *SenseData,\r
+  IN  UINTN                 SenseCounts\r
+  )\r

 {\r
   BOOLEAN Have;\r
 \r
 {\r
   BOOLEAN Have;\r
 \r


@@ -2533,29 +2292,22 @@ Returns:
   return Have;\r
 }\r
 \r
   return Have;\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  IdeDev TODO: add argument description\r
+  @param  WriteProtected TODO: add argument description\r
+\r
+  @retval  EFI_DEVICE_ERROR TODO: Add description for return value\r
+  @retval  EFI_DEVICE_ERROR TODO: Add description for return value\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r
+\r
+**/\r

 EFI_STATUS\r
 IsLS120orZipWriteProtected (\r
   IN  IDE_BLK_IO_DEV    *IdeDev,\r
   OUT BOOLEAN           *WriteProtected\r
   )\r
 EFI_STATUS\r
 IsLS120orZipWriteProtected (\r
   IN  IDE_BLK_IO_DEV    *IdeDev,\r
   OUT BOOLEAN           *WriteProtected\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  WriteProtected  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  EFI_DEVICE_ERROR - TODO: Add description for return value\r
-  EFI_DEVICE_ERROR - TODO: Add description for return value\r
-  EFI_SUCCESS - TODO: Add description for return value\r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
 \r
 {\r
   EFI_STATUS  Status;\r
 \r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c
index d318fd23df98c4188be7f8ae3b85c9abd1ff97e3..c41d9958792eb3d06896bf6049982b48d010d09e 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c
@@ -1,50 +1,34 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-    ide.c\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
---*/\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 BOOLEAN SlaveDeviceExist  = FALSE;\r
 BOOLEAN MasterDeviceExist = FALSE;\r
 \r
 \r
 #include "idebus.h"\r
 \r
 BOOLEAN SlaveDeviceExist  = FALSE;\r
 BOOLEAN MasterDeviceExist = FALSE;\r
 \r

-UINT8\r
-IDEReadPortB (\r
-  IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
-  IN  UINT16                Port\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+UINT8\r
+IDEReadPortB (\r
+  IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
+  IN  UINT16                Port\r
+  )\r

 {\r
   UINT8 Data;\r
 \r
 {\r
   UINT8 Data;\r
 \r


@@ -63,6 +47,17 @@ Returns:
   return Data;\r
 }\r
 \r
   return Data;\r
 }\r
 \r

+/**\r
+  Reads multiple words of data from the IDE data port. \r
+  Call the IO abstraction once to do the complete read,\r
+  not one word at a time\r
+\r
+  @param  PciIo Pointer to the EFI_PCI_IO instance\r
+  @param  Port IO port to read\r
+  @param  Count No. of UINT16's to read\r
+  @param  Buffer Pointer to the data buffer for read\r
+\r
+**/\r

 VOID\r
 IDEReadPortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
 VOID\r
 IDEReadPortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r


@@ -70,23 +65,6 @@ IDEReadPortWMultiple (
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-  Reads multiple words of data from the IDE data port. \r
-  Call the IO abstraction once to do the complete read,\r
-  not one word at a time\r
-  \r
-\r
-Arguments:\r
-  PciIo   - Pointer to the EFI_PCI_IO instance\r
-  Port    - IO port to read\r
-  Count   - No. of UINT16's to read\r
-  Buffer  - Pointer to the data buffer for read\r
-\r
-++*/\r
-// TODO: function comment should end with '--*/'\r
-// TODO: function comment is missing 'Returns:'\r

 {\r
   UINT16  *AlignedBuffer;\r
   UINT16  *WorkingBuffer;\r
 {\r
   UINT16  *AlignedBuffer;\r
   UINT16  *WorkingBuffer;\r


@@ -127,29 +105,22 @@ Arguments:
   gBS->FreePool (WorkingBuffer);\r
 }\r
 \r
   gBS->FreePool (WorkingBuffer);\r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 VOID\r
 IDEWritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r
 VOID\r
 IDEWritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   //\r
   // perform 1-byte data write to register\r
 {\r
   //\r
   // perform 1-byte data write to register\r


@@ -165,29 +136,22 @@ Returns:
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 VOID\r
 IDEWritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r
 VOID\r
 IDEWritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

 {\r
   //\r
   // perform 1-word data write to register\r
 {\r
   //\r
   // perform 1-word data write to register\r


@@ -202,6 +166,17 @@ Returns:
               );\r
 }\r
 \r
               );\r
 }\r
 \r

+/**\r
+  Write multiple words of data to the IDE data port. \r
+  Call the IO abstraction once to do the complete read,\r
+  not one word at a time\r
+\r
+  @param  PciIo Pointer to the EFI_PCI_IO instance\r
+  @param  Port IO port to read\r
+  @param  Count No. of UINT16's to read\r
+  @param  Buffer Pointer to the data buffer for read\r
+\r
+**/\r

 VOID\r
 IDEWritePortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
 VOID\r
 IDEWritePortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r


@@ -209,23 +184,6 @@ IDEWritePortWMultiple (
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-  Write multiple words of data to the IDE data port. \r
-  Call the IO abstraction once to do the complete read,\r
-  not one word at a time\r
-  \r
-\r
-Arguments:\r
-  PciIo   - Pointer to the EFI_PCI_IO instance\r
-  Port    - IO port to read\r
-  Count   - No. of UINT16's to read\r
-  Buffer  - Pointer to the data buffer for read\r
-\r
-++*/\r
-// TODO: function comment should end with '--*/'\r
-// TODO: function comment is missing 'Returns:'\r

 {\r
   UINT16  *AlignedBuffer;\r
   UINT32  *WorkingBuffer;\r
 {\r
   UINT16  *AlignedBuffer;\r
   UINT32  *WorkingBuffer;\r


@@ -267,25 +225,18 @@ Arguments:
   gBS->FreePool (WorkingBuffer);\r
 }\r
 \r
   gBS->FreePool (WorkingBuffer);\r
 }\r
 \r

-BOOLEAN\r
-BadIdeDeviceCheck (\r
-  IN IDE_BLK_IO_DEV *IdeDev\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
+**/\r
+BOOLEAN\r
+BadIdeDeviceCheck (\r
+  IN IDE_BLK_IO_DEV *IdeDev\r
+  )\r

 {\r
   //\r
   //  check whether all registers return 0xff,\r
 {\r
   //\r
   //  check whether all registers return 0xff,\r


@@ -341,63 +292,62 @@ Returns:
 //\r
 // GetIdeRegistersBaseAddr\r
 //\r
 //\r
 // GetIdeRegistersBaseAddr\r
 //\r

-EFI_STATUS\r
-GetIdeRegistersBaseAddr (\r
-  IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
-  OUT IDE_REGISTERS_BASE_ADDR     *IdeRegsBaseAddr\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
+/**\r

   Get IDE IO port registers' base addresses by mode. In 'Compatibility' mode,\r
   use fixed addresses. In Native-PCI mode, get base addresses from BARs in\r
   the PCI IDE controller's Configuration Space.\r
   Get IDE IO port registers' base addresses by mode. In 'Compatibility' mode,\r
   use fixed addresses. In Native-PCI mode, get base addresses from BARs in\r
   the PCI IDE controller's Configuration Space.\r

-  \r
+\r

   The steps to get IDE IO port registers' base addresses for each channel \r
   as follows:\r
 \r
   1. Examine the Programming Interface byte of the Class Code fields in PCI IDE \r
   The steps to get IDE IO port registers' base addresses for each channel \r
   as follows:\r
 \r
   1. Examine the Programming Interface byte of the Class Code fields in PCI IDE \r

-     controller's Configuration Space to determine the operating mode.\r
-     \r
+  controller's Configuration Space to determine the operating mode.\r
+\r

   2. a) In 'Compatibility' mode, use fixed addresses shown in the Table 1 below.\r
   2. a) In 'Compatibility' mode, use fixed addresses shown in the Table 1 below.\r

-                 ___________________________________________\r
-                |           | Command Block | Control Block |\r
-                |  Channel  |   Registers   |   Registers   |\r
-                |___________|_______________|_______________|\r
-                |  Primary  |  1F0h - 1F7h  |  3F6h - 3F7h  |\r
-                |___________|_______________|_______________|\r
-                | Secondary |  170h - 177h  |  376h - 377h  |\r
-                |___________|_______________|_______________|\r
-        \r
-                  Table 1. Compatibility resource mappings\r
-        \r
-     b) In Native-PCI mode, IDE registers are mapped into IO space using the BARs\r
-        in IDE controller's PCI Configuration Space, shown in the Table 2 below.\r
-               ___________________________________________________\r
-              |           |   Command Block   |   Control Block   |\r
-              |  Channel  |     Registers     |     Registers     |\r
-              |___________|___________________|___________________|\r
-              |  Primary  | BAR at offset 0x10| BAR at offset 0x14|\r
-              |___________|___________________|___________________|\r
-              | Secondary | BAR at offset 0x18| BAR at offset 0x1C|\r
-              |___________|___________________|___________________|\r
-      \r
-                        Table 2. BARs for Register Mapping\r
-        Note: Refer to Intel ICH4 datasheet, Control Block Offset: 03F4h for \r
-              primary, 0374h for secondary. So 2 bytes extra offset should be \r
-              added to the base addresses read from BARs.\r
-  \r
+  <pre>\r
+  ___________________________________________\r
+  |           | Command Block | Control Block |\r
+  |  Channel  |   Registers   |   Registers   |\r
+  |___________|_______________|_______________|\r
+  |  Primary  |  1F0h - 1F7h  |  3F6h - 3F7h  |\r
+  |___________|_______________|_______________|\r
+  | Secondary |  170h - 177h  |  376h - 377h  |\r
+  |___________|_______________|_______________|\r
+\r
+  Table 1. Compatibility resource mappings\r
+  </pre>\r
+\r
+  b) In Native-PCI mode, IDE registers are mapped into IO space using the BARs\r
+  in IDE controller's PCI Configuration Space, shown in the Table 2 below.\r
+  <pre>\r
+  ___________________________________________________\r
+  |           |   Command Block   |   Control Block   |\r
+  |  Channel  |     Registers     |     Registers     |\r
+  |___________|___________________|___________________|\r
+  |  Primary  | BAR at offset 0x10| BAR at offset 0x14|\r
+  |___________|___________________|___________________|\r
+  | Secondary | BAR at offset 0x18| BAR at offset 0x1C|\r
+  |___________|___________________|___________________|\r
+\r
+  Table 2. BARs for Register Mapping\r
+  </pre>\r
+  @note Refer to Intel ICH4 datasheet, Control Block Offset: 03F4h for \r
+  primary, 0374h for secondary. So 2 bytes extra offset should be \r
+  added to the base addresses read from BARs.\r
+\r

   For more details, please refer to PCI IDE Controller Specification and Intel \r
   ICH4 Datasheet.\r
   For more details, please refer to PCI IDE Controller Specification and Intel \r
   ICH4 Datasheet.\r

-  \r
-Arguments:\r
-  PciIo             - Pointer to the EFI_PCI_IO_PROTOCOL instance\r
-  IdeRegsBaseAddr   - Pointer to IDE_REGISTERS_BASE_ADDR to \r
-                      receive IDE IO port registers' base addresses\r
-                      \r
-Returns:\r
-    \r
---*/\r
+\r
+  @param  PciIo Pointer to the EFI_PCI_IO_PROTOCOL instance\r
+  @param  IdeRegsBaseAddr Pointer to IDE_REGISTERS_BASE_ADDR to\r
+  receive IDE IO port registers' base addresses\r
+\r
+**/\r
+EFI_STATUS\r
+GetIdeRegistersBaseAddr (\r
+  IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
+  OUT IDE_REGISTERS_BASE_ADDR     *IdeRegsBaseAddr\r
+  )\r

 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r


@@ -464,24 +414,19 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-ReassignIdeResources (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
+/**\r

   This function is used to requery IDE resources. The IDE controller will \r
   probably switch between native and legacy modes during the EFI->CSM->OS \r
   transfer. We do this everytime before an BlkIo operation to ensure its\r
   succeess.\r
   This function is used to requery IDE resources. The IDE controller will \r
   probably switch between native and legacy modes during the EFI->CSM->OS \r
   transfer. We do this everytime before an BlkIo operation to ensure its\r
   succeess.\r

-  \r
-Arguments:\r
-  IdeDev - The BLK_IO private data which specifies the IDE device\r
-  \r
-++*/\r
-// TODO: function comment should end with '--*/'\r
-// TODO: function comment is missing 'Returns:'\r
+\r
+  @param  IdeDev The BLK_IO private data which specifies the IDE device\r
+\r
+**/\r
+EFI_STATUS\r
+ReassignIdeResources (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev\r
+  )\r

 // TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS              Status;\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS              Status;\r


@@ -519,22 +464,16 @@ Arguments:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Read SATA registers to detect SATA disks\r
+\r
+  @param  IdeDev The BLK_IO private data which specifies the IDE device\r
+\r
+**/\r

 EFI_STATUS\r
 CheckPowerMode (\r
   IDE_BLK_IO_DEV    *IdeDev\r
   )\r
 EFI_STATUS\r
 CheckPowerMode (\r
   IDE_BLK_IO_DEV    *IdeDev\r
   )\r

-/*++\r
- Routine Description:\r
- \r
-  Read SATA registers to detect SATA disks\r
-\r
- Arguments:\r
-\r
-  IdeDev - The BLK_IO private data which specifies the IDE device\r
-  \r
-++*/\r
-// TODO: function comment should end with '--*/'\r
-// TODO: function comment is missing 'Returns:'\r

 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r


@@ -579,22 +518,16 @@ CheckPowerMode (
 //\r
 // DiscoverIdeDevice\r
 //\r
 //\r
 // DiscoverIdeDevice\r
 //\r

+/**\r
+  Detect if there is disk connected to this port\r
+\r
+  @param  IdeDev The BLK_IO private data which specifies the IDE device\r
+\r
+**/\r

 EFI_STATUS\r
 DiscoverIdeDevice (\r
   IN IDE_BLK_IO_DEV *IdeDev\r
   )\r
 EFI_STATUS\r
 DiscoverIdeDevice (\r
   IN IDE_BLK_IO_DEV *IdeDev\r
   )\r

-/*++\r
- Routine Description:\r
- \r
-  Detect if there is disk connected to this port\r
-\r
- Arguments:\r
-\r
-  IdeDev - The BLK_IO private data which specifies the IDE device\r
-  \r
-++*/\r
-// TODO: function comment should end with '--*/'\r
-// TODO: function comment is missing 'Returns:'\r

 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_NOT_FOUND - add return value to function comment\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r


@@ -662,54 +595,42 @@ DiscoverIdeDevice (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-DetectIDEController (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev\r
-  )\r
-/*++\r
-  \r
-  Name: DetectIDEController\r
-\r
-\r
-  Purpose: \r
-      This function is called by DiscoverIdeDevice(). It is used for detect \r
-      whether the IDE device exists in the specified Channel as the specified \r
-      Device Number.\r
-\r
-      There is two IDE channels: one is Primary Channel, the other is \r
-      Secondary Channel.(Channel is the logical name for the physical "Cable".) \r
-      Different channel has different register group.\r
+/**\r
+  This function is called by DiscoverIdeDevice(). It is used for detect \r
+  whether the IDE device exists in the specified Channel as the specified \r
+  Device Number.\r

 \r
 \r

-      On each IDE channel, at most two IDE devices attach, \r
-      one is called Device 0 (Master device), the other is called Device 1 \r
-      (Slave device). The devices on the same channel co-use the same register \r
-      group, so before sending out a command for a specified device via command \r
-      register, it is a must to select the current device to accept the command \r
-      by set the device number in the Head/Device Register.\r
- \r
-            \r
-  Parameters:\r
-      IDE_BLK_IO_DEV  IN    *IdeDev\r
-            pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-            to record all the information of the IDE device.\r
+  There is two IDE channels: one is Primary Channel, the other is \r
+  Secondary Channel.(Channel is the logical name for the physical "Cable".) \r
+  Different channel has different register group.\r

 \r
 \r

+  On each IDE channel, at most two IDE devices attach, \r
+  one is called Device 0 (Master device), the other is called Device 1 \r
+  (Slave device). The devices on the same channel co-use the same register \r
+  group, so before sending out a command for a specified device via command \r
+  register, it is a must to select the current device to accept the command \r
+  by set the device number in the Head/Device Register.\r

 \r
 \r

-  Returns:    \r
-      TRUE      \r
-            successfully detects device.\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r

 \r
 \r

-      FALSE\r
-            any failure during detection process will return this\r
-            value.\r
+  @retval TRUE\r
+  successfully detects device.\r
+  \r
+  @retval FALSE\r
+  any failure during detection process will return this\r
+  value.\r

 \r
 \r

+  @note\r
+  TODO:    EFI_SUCCESS - add return value to function comment\r
+  TODO:    EFI_NOT_FOUND - add return value to function comment\r

 \r
 \r

-  Notes:\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    IdeDev - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r
-// TODO:    EFI_NOT_FOUND - add return value to function comment\r
+**/\r
+EFI_STATUS\r
+DetectIDEController (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev\r
+  )\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       ErrorReg;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       ErrorReg;\r


@@ -846,40 +767,33 @@ DetectIDEController (
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  This function is used to poll for the DRQ bit clear in the Status \r
+  Register. DRQ is cleared when the device is finished transferring data. \r
+  So this function is called after data transfer is finished.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ clear.\r
+\r
+  @retval EFI_SUCCESS\r
+  DRQ bit clear within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRQ bit not clear within the time out.\r
+\r
+  @note\r
+  Read Status Register will clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 DRQClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

-/*++\r
-  Name:   DRQClear\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the DRQ bit clear in the Status \r
-        Register. DRQ is cleared when the device is finished transferring data. \r
-        So this function is called after data transfer is finished.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-            pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-            to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-            used to designate the timeout for the DRQ clear.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-            DRQ bit clear within the time out.\r
-\r
-        EFI_TIMEOUT\r
-            DRQ bit not clear within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Status Register will clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -926,41 +840,34 @@ DRQClear (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is used to poll for the DRQ bit clear in the Alternate \r
+  Status Register. DRQ is cleared when the device is finished \r
+  transferring data. So this function is called after data transfer\r
+  is finished.\r
+\r
+  @param[in] *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ clear.\r
+\r
+  @retval EFI_SUCCESS\r
+  DRQ bit clear within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRQ bit not clear within the time out.\r
+\r
+  @note\r
+  Read Alternate Status Register will not clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 DRQClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

-/*++\r
-  Name:   DRQClear2\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the DRQ bit clear in the Alternate \r
-        Status Register. DRQ is cleared when the device is finished \r
-        transferring data. So this function is called after data transfer\r
-        is finished.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ clear.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          DRQ bit clear within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          DRQ bit not clear within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Alternate Status Register will not clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1007,46 +914,38 @@ DRQClear2 (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

-EFI_STATUS\r
-DRQReady (\r
-  IN  IDE_BLK_IO_DEV  *IdeDev,\r
-  IN  UINTN           TimeoutInMilliSeconds\r
-  )\r
-/*++\r
-  Name:   DRQReady\r
+/**\r
+  This function is used to poll for the DRQ bit set in the \r
+  Status Register.\r
+  DRQ is set when the device is ready to transfer data. So this function\r
+  is called after the command is sent to the device and before required \r
+  data is transferred.\r

 \r
 \r

+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure,used\r
+  to record all the information of the IDE device.\r

   \r
   \r

-  Purpose: \r
-        This function is used to poll for the DRQ bit set in the \r
-        Status Register.\r
-        DRQ is set when the device is ready to transfer data. So this function\r
-        is called after the command is sent to the device and before required \r
-        data is transferred.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-            pointer pointing to IDE_BLK_IO_DEV data structure,used\r
-            to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-            used to designate the timeout for the DRQ ready.\r
-\r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r

 \r
 \r

-  Returns:  \r
-        EFI_SUCCESS\r
-            DRQ bit set within the time out.\r
-\r
-        EFI_TIMEOUT\r
-            DRQ bit not set within the time out.\r
-            \r
-        EFI_ABORTED\r
-            DRQ bit not set caused by the command abort.\r
+  @retval EFI_SUCCESS\r
+  DRQ bit set within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRQ bit not set within the time out.\r
+  \r
+  @retval EFI_ABORTED\r
+  DRQ bit not set caused by the command abort.\r

 \r
 \r

-  Notes:\r
-        Read Status Register will clear interrupt status.\r
+  @note\r
+  Read Status Register will clear interrupt status.\r

 \r
 \r

---*/\r
+**/\r
+EFI_STATUS\r
+DRQReady (\r
+  IN  IDE_BLK_IO_DEV  *IdeDev,\r
+  IN  UINTN           TimeoutInMilliSeconds\r
+  )\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1093,43 +992,37 @@ DRQReady (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is used to poll for the DRQ bit set in the \r
+  Alternate Status Register. DRQ is set when the device is ready to \r
+  transfer data. So this function is called after the command \r
+  is sent to the device and before required data is transferred.\r
+\r
+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r
+\r
+  @retval EFI_SUCCESS\r
+  DRQ bit set within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRQ bit not set within the time out.\r
+  \r
+  @retval EFI_ABORTED\r
+  DRQ bit not set caused by the command abort.\r
+\r
+  @note\r
+  Read Alternate Status Register will not clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 DRQReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

-/*++\r
-  Name:   DRQReady2\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the DRQ bit set in the \r
-        Alternate Status Register. DRQ is set when the device is ready to \r
-        transfer data. So this function is called after the command \r
-        is sent to the device and before required data is transferred.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ ready.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          DRQ bit set within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          DRQ bit not set within the time out. \r
-        \r
-        EFI_ABORTED\r
-            DRQ bit not set caused by the command abort.\r
-\r
-  Notes:\r
-        Read Alternate Status Register will not clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1176,41 +1069,33 @@ DRQReady2 (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  This function is used to poll for the BSY bit clear in the \r
+  Status Register. BSY is clear when the device is not busy.\r
+  Every command must be sent after device is not busy.\r
+\r
+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r
+\r
+  @retval EFI_SUCCESS\r
+  BSY bit clear within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  BSY bit not clear within the time out.\r
+\r
+  @note\r
+  Read Status Register will clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 WaitForBSYClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 WaitForBSYClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

-/*++\r
-  Name:\r
-        WaitForBSYClear\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the BSY bit clear in the \r
-        Status Register. BSY is clear when the device is not busy.\r
-        Every command must be sent after device is not busy.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ ready.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          BSY bit clear within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          BSY bit not clear within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Status Register will clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1245,41 +1130,33 @@ WaitForBSYClear (
 //\r
 // WaitForBSYClear2\r
 //\r
 //\r
 // WaitForBSYClear2\r
 //\r

+/**\r
+  This function is used to poll for the BSY bit clear in the \r
+  Alternate Status Register. BSY is clear when the device is not busy.\r
+  Every command must be sent after device is not busy.\r
+\r
+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r
+\r
+  @retval EFI_SUCCESS\r
+  BSY bit clear within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  BSY bit not clear within the time out.\r
+\r
+  @note\r
+  Read Alternate Status Register will not clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 WaitForBSYClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 WaitForBSYClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

-/*++\r
-  Name:\r
-        WaitForBSYClear2\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the BSY bit clear in the \r
-        Alternate Status Register. BSY is clear when the device is not busy.\r
-        Every command must be sent after device is not busy.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ ready.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          BSY bit clear within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          BSY bit not clear within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Alternate Status Register will not clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1311,42 +1188,34 @@ WaitForBSYClear2 (
 //\r
 // DRDYReady\r
 //\r
 //\r
 // DRDYReady\r
 //\r

+/**\r
+  This function is used to poll for the DRDY bit set in the \r
+  Status Register. DRDY bit is set when the device is ready \r
+  to accept command. Most ATA commands must be sent after \r
+  DRDY set except the ATAPI Packet Command.\r
+\r
+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r
+\r
+  @retval EFI_SUCCESS\r
+  DRDY bit set within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRDY bit not set within the time out.\r
+\r
+  @note\r
+  Read Status Register will clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 DRDYReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRDYReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r

-/*++\r
-  Name:\r
-        DRDYReady\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the DRDY bit set in the \r
-        Status Register. DRDY bit is set when the device is ready \r
-        to accept command. Most ATA commands must be sent after \r
-        DRDY set except the ATAPI Packet Command.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ ready.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          DRDY bit set within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          DRDY bit not set within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Status Register will clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1390,42 +1259,34 @@ DRDYReady (
 //\r
 // DRDYReady2\r
 //\r
 //\r
 // DRDYReady2\r
 //\r

+/**\r
+  This function is used to poll for the DRDY bit set in the \r
+  Alternate Status Register. DRDY bit is set when the device is ready \r
+  to accept command. Most ATA commands must be sent after \r
+  DRDY set except the ATAPI Packet Command.\r
+\r
+  @param[in] IDE_BLK_IO_DEV  IN    *IdeDev\r
+  pointer pointing to IDE_BLK_IO_DEV data structure, used\r
+  to record all the information of the IDE device.\r
+  \r
+  @param[in] UINTN     IN    TimeoutInMilliSeconds\r
+  used to designate the timeout for the DRQ ready.\r
+\r
+  @retval EFI_SUCCESS\r
+  DRDY bit set within the time out.\r
+  \r
+  @retval EFI_TIMEOUT\r
+  DRDY bit not set within the time out.\r
+\r
+  @note\r
+  Read Alternate Status Register will clear interrupt status.\r
+\r
+**/\r

 EFI_STATUS\r
 DRDYReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRDYReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r

-/*++\r
-  Name:\r
-        DRDYReady2\r
-\r
-\r
-  Purpose: \r
-        This function is used to poll for the DRDY bit set in the \r
-        Alternate Status Register. DRDY bit is set when the device is ready \r
-        to accept command. Most ATA commands must be sent after \r
-        DRDY set except the ATAPI Packet Command.\r
-\r
-\r
-  Parameters:\r
-        IDE_BLK_IO_DEV  IN    *IdeDev\r
-          pointer pointing to IDE_BLK_IO_DEV data structure, used\r
-          to record all the information of the IDE device.\r
-\r
-        UINTN     IN    TimeoutInMilliSeconds\r
-          used to designate the timeout for the DRQ ready.\r
-\r
-  Returns:  \r
-        EFI_SUCCESS\r
-          DRDY bit set within the time out.\r
-\r
-        EFI_TIMEOUT\r
-          DRDY bit not set within the time out. \r
-\r
-\r
-  Notes:\r
-        Read Alternate Status Register will clear interrupt status.\r
---*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r
 // TODO: function comment is missing 'Routine Description:'\r
 // TODO: function comment is missing 'Arguments:'\r
 // TODO:    IdeDev - add argument and description to function comment\r


@@ -1469,52 +1330,34 @@ DRDYReady2 (
 //\r
 // SwapStringChars\r
 //\r
 //\r
 // SwapStringChars\r
 //\r

+/**\r
+  This function is a helper function used to change the char order in a \r
+  string. It is designed specially for the PrintAtaModuleName() function.\r
+  After the IDE device is detected, the IDE driver gets the device module\r
+  name by sending ATA command called ATA Identify Command or ATAPI \r
+  Identify Command to the specified IDE device. The module name returned \r
+  is a string of ASCII characters: the first character is bit8--bit15 \r
+  of the first word, the second character is bit0--bit7 of the first word \r
+  and so on. Thus the string can not be print directly before it is \r
+  preprocessed by this func to change the order of characters in \r
+  each word in the string.\r
+\r
+  @param[in] CHAR8 IN    *Destination\r
+  Indicates the destination string.\r
+  \r
+  @param[in] CHAR8 IN    *Source\r
+  Indicates the source string.\r
+  \r
+  @param[in] UINT8 IN    Size\r
+  the length of the string\r
+\r
+**/\r

 VOID\r
 SwapStringChars (\r
   IN CHAR8  *Destination,\r
   IN CHAR8  *Source,\r
   IN UINT32 Size\r
   )\r
 VOID\r
 SwapStringChars (\r
   IN CHAR8  *Destination,\r
   IN CHAR8  *Source,\r
   IN UINT32 Size\r
   )\r

-/*++\r
-  Name:\r
-        SwapStringChars\r
-\r
-\r
-  Purpose: \r
-        This function is a helper function used to change the char order in a \r
-        string. It is designed specially for the PrintAtaModuleName() function.\r
-        After the IDE device is detected, the IDE driver gets the device module\r
-        name by sending ATA command called ATA Identify Command or ATAPI \r
-        Identify Command to the specified IDE device. The module name returned \r
-        is a string of ASCII characters: the first character is bit8--bit15 \r
-        of the first word, the second character is bit0--bit7 of the first word \r
-        and so on. Thus the string can not be print directly before it is \r
-        preprocessed by this func to change the order of characters in \r
-        each word in the string.\r
-\r
-\r
-  Parameters:\r
-        CHAR8 IN    *Destination\r
-          Indicates the destination string.\r
-\r
-        CHAR8 IN    *Source\r
-          Indicates the source string.\r
-\r
-        UINT8 IN    Size\r
-          the length of the string\r
-\r
-\r
-  Returns:  \r
-        none\r
-\r
-  Notes:\r
-\r
---*/\r
-// TODO: function comment is missing 'Routine Description:'\r
-// TODO: function comment is missing 'Arguments:'\r
-// TODO:    Destination - add argument and description to function comment\r
-// TODO:    Source - add argument and description to function comment\r
-// TODO:    Size - add argument and description to function comment\r

 {\r
   UINT32  Index;\r
   CHAR8   Temp;\r
 {\r
   UINT32  Index;\r
   CHAR8   Temp;\r


@@ -1530,26 +1373,16 @@ SwapStringChars (
 //\r
 // ReleaseIdeResources\r
 //\r
 //\r
 // ReleaseIdeResources\r
 //\r

+/**\r
+  Release resources of an IDE device before stopping it.\r
+\r
+  @param[in] *IdeBlkIoDevice  Standard IDE device private data structure\r
+\r
+**/\r

 VOID\r
 ReleaseIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeBlkIoDevice\r
   )\r
 VOID\r
 ReleaseIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeBlkIoDevice\r
   )\r

-/*++\r
-Routing Description:\r
-\r
-  Release resources of an IDE device before stopping it.\r
-\r
-Arguments:\r
-\r
-  IdeBlkIoDevice  --  Standard IDE device private data structure\r
-\r
-\r
-Returns:\r
-\r
-    NONE\r
-    \r
----*/\r
-// TODO: function comment is missing 'Routine Description:'\r

 {\r
   if (IdeBlkIoDevice == NULL) {\r
     return ;\r
 {\r
   if (IdeBlkIoDevice == NULL) {\r
     return ;\r


@@ -1601,26 +1434,20 @@ Returns:
 //\r
 // SetDeviceTransferMode\r
 //\r
 //\r
 // SetDeviceTransferMode\r
 //\r

+/**\r
+  Set the calculated Best transfer mode to a detected device\r
+\r
+  @param[in] *IdeDev       Standard IDE device private data structure\r
+  @param[in] *TransferMode The device transfer mode to be set\r
+\r
+  @return Set transfer mode Command execute status\r
+\r
+**/\r

 EFI_STATUS\r
 SetDeviceTransferMode (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_TRANSFER_MODE    *TransferMode\r
   )\r
 EFI_STATUS\r
 SetDeviceTransferMode (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_TRANSFER_MODE    *TransferMode\r
   )\r

-/*++\r
-Routing Description:\r
-\r
-  Set the calculated Best transfer mode to a detected device\r
-\r
-Arguments:\r
-\r
-  IdeDev       --  Standard IDE device private data structure\r
-  TransferMode --  The device transfer mode to be set\r
-\r
-Returns:\r
-\r
-    Set transfer mode Command execute status\r
-    \r
----*/\r

 // TODO: function comment is missing 'Routine Description:'\r
 {\r
   EFI_STATUS  Status;\r
 // TODO: function comment is missing 'Routine Description:'\r
 {\r
   EFI_STATUS  Status;\r


@@ -1648,6 +1475,23 @@ Returns:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Send ATA command into device with NON_DATA protocol\r
+\r
+  @param  IdeDev Standard IDE device private data structure\r
+  @param  AtaCommand The ATA command to be sent\r
+  @param  Device The value in Device register\r
+  @param  Feature The value in Feature register\r
+  @param  SectorCount The value in SectorCount register\r
+  @param  LbaLow The value in LBA_LOW register\r
+  @param  LbaMiddle The value in LBA_MIDDLE register\r
+  @param  LbaHigh The value in LBA_HIGH register\r
+\r
+  @retval  EFI_SUCCESS Reading succeed\r
+  @retval  EFI_ABORTED Command failed\r
+  @retval  EFI_DEVICE_ERROR Device status error\r
+\r
+**/\r

 EFI_STATUS\r
 AtaNonDataCommandIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaNonDataCommandIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1659,30 +1503,6 @@ AtaNonDataCommandIn (
   IN  UINT8           LbaMiddle,\r
   IN  UINT8           LbaHigh\r
   )\r
   IN  UINT8           LbaMiddle,\r
   IN  UINT8           LbaHigh\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Send ATA command into device with NON_DATA protocol\r
-\r
-Arguments:\r
-\r
-  IdeDev      - Standard IDE device private data structure\r
-  AtaCommand  - The ATA command to be sent\r
-  Device      - The value in Device register\r
-  Feature     - The value in Feature register\r
-  SectorCount - The value in SectorCount register \r
-  LbaLow      - The value in LBA_LOW register\r
-  LbaMiddle   - The value in LBA_MIDDLE register\r
-  LbaHigh     - The value in LBA_HIGH register\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS      - Reading succeed\r
-  EFI_ABORTED      - Command failed\r
-  EFI_DEVICE_ERROR - Device status error\r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       StatusRegister;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       StatusRegister;\r


@@ -1743,6 +1563,21 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Send ATA Ext command into device with NON_DATA protocol\r
+\r
+  @param  IdeDev Standard IDE device private data structure\r
+  @param  AtaCommand The ATA command to be sent\r
+  @param  Device The value in Device register\r
+  @param  Feature The value in Feature register\r
+  @param  SectorCount The value in SectorCount register\r
+  @param  LbaAddress The LBA address in 48-bit mode\r
+\r
+  @retval  EFI_SUCCESS Reading succeed\r
+  @retval  EFI_ABORTED Command failed\r
+  @retval  EFI_DEVICE_ERROR Device status error\r
+\r
+**/\r

 EFI_STATUS\r
 AtaNonDataCommandInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaNonDataCommandInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1752,28 +1587,6 @@ AtaNonDataCommandInExt (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Send ATA Ext command into device with NON_DATA protocol\r
-\r
-Arguments:\r
-\r
-  IdeDev      - Standard IDE device private data structure\r
-  AtaCommand  - The ATA command to be sent\r
-  Device      - The value in Device register\r
-  Feature     - The value in Feature register\r
-  SectorCount - The value in SectorCount register \r
-  LbaAddress - The LBA address in 48-bit mode\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS      - Reading succeed\r
-  EFI_ABORTED      - Command failed\r
-  EFI_DEVICE_ERROR - Device status error\r
-\r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       StatusRegister;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       StatusRegister;\r


@@ -1872,26 +1685,20 @@ Returns:
 //\r
 // SetDriveParameters\r
 //\r
 //\r
 // SetDriveParameters\r
 //\r

+/**\r
+  Set drive parameters for devices not support PACKETS command\r
+\r
+  @param[in] IdeDev       Standard IDE device private data structure\r
+  @param[in] DriveParameters The device parameters to be set into the disk\r
+\r
+  @return SetParameters Command execute status\r
+\r
+**/\r

 EFI_STATUS\r
 SetDriveParameters (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_DRIVE_PARMS      *DriveParameters\r
   )\r
 EFI_STATUS\r
 SetDriveParameters (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_DRIVE_PARMS      *DriveParameters\r
   )\r

-/*++\r
-Routine Description: \r
-\r
-  Set drive parameters for devices not support PACKETS command\r
-\r
-Arguments:\r
-\r
-  IdeDev       --  Standard IDE device private data structure\r
-  DriveParameters --  The device parameters to be set into the disk\r
-\r
-Returns:\r
-\r
-  SetParameters Command execute status\r
-    \r
---*/\r

 {\r
   EFI_STATUS  Status;\r
   UINT8       DeviceSelect;\r
 {\r
   EFI_STATUS  Status;\r
   UINT8       DeviceSelect;\r


@@ -1932,25 +1739,18 @@ Returns:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

-EFI_STATUS\r
-EnableInterrupt (\r
-  IN IDE_BLK_IO_DEV       *IdeDev\r
-  )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
+  @param  IdeDev TODO: add argument description\r

 \r
 \r

-Returns:\r
+  @retval  EFI_SUCCESS TODO: Add description for return value\r

 \r
 \r

-  EFI_SUCCESS - TODO: Add description for return value\r
-\r
---*/\r
+**/\r
+EFI_STATUS\r
+EnableInterrupt (\r
+  IN IDE_BLK_IO_DEV       *IdeDev\r
+  )\r

 {\r
   UINT8 DeviceControl;\r
 \r
 {\r
   UINT8 DeviceControl;\r
 \r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h
index 4c43ab94cd6c85424f5f070976a9ae3ec3c82e32..177e842714b6f24b196818aec97c7dd0481d5b96 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h
@@ -1,62 +1,58 @@
-/*++\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
+/** @file\r
+  Header file for IDE Bus Driver, containing the helper functions' \r
+  entire prototype.\r

 \r
 \r

-Module Name:\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
 \r

-    ide.h\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

-Abstract:\r
+  @par Revision Reference:\r
+  2002-6: Add Atapi6 enhancement, support >120GB hard disk, including\r
+  Add - IDEBlkIoReadBlocksExt() func definition\r
+  Add - IDEBlkIoWriteBlocksExt() func definition\r

 \r
 \r

-    Header file for IDE Bus Driver, containing the helper functions' \r
-    entire prototype.\r
+**/\r

 \r
 \r

-Revision History\r
-\r
-    2002-6: Add Atapi6 enhancement, support >120GB hard disk, including\r
-            Add - IDEBlkIoReadBlocksExt() func definition\r
-            Add - IDEBlkIoWriteBlocksExt() func definition\r
-            \r
-++*/\r
-\r
-// TODO: fix comment to end with --*/\r

 #ifndef _IDE_H\r
 #define _IDE_H\r
 \r
 //\r
 // Helper functions Prototype\r
 //\r
 #ifndef _IDE_H\r
 #define _IDE_H\r
 \r
 //\r
 // Helper functions Prototype\r
 //\r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  Handle TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 EFI_STATUS\r
 DeRegisterIdeDevice (\r
   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,\r
   IN  EFI_HANDLE                     Controller,\r
   IN  EFI_HANDLE                     Handle\r
   )\r
 EFI_STATUS\r
 DeRegisterIdeDevice (\r
   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,\r
   IN  EFI_HANDLE                     Controller,\r
   IN  EFI_HANDLE                     Handle\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  Controller  - TODO: add argument description\r
-  Handle      - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Controller TODO: add argument description\r
+  @param  PciIo TODO: add argument description\r
+  @param  ParentDevicePath TODO: add argument description\r
+  @param  RemainingDevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

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


@@ -64,49 +60,35 @@ EnableIdeDevice (
   IN EFI_DEVICE_PATH_PROTOCOL            *ParentDevicePath,\r
   IN EFI_DEVICE_PATH_PROTOCOL            *RemainingDevicePath\r
   )\r
   IN EFI_DEVICE_PATH_PROTOCOL            *ParentDevicePath,\r
   IN EFI_DEVICE_PATH_PROTOCOL            *RemainingDevicePath\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Controller          - TODO: add argument description\r
-  PciIo               - TODO: add argument description\r
-  ParentDevicePath    - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 UINT8\r
 IDEReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r
 UINT8\r
 IDEReadPortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Count TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 IDEReadPortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
 VOID\r
 IDEReadPortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r


@@ -114,76 +96,55 @@ IDEReadPortWMultiple (
   IN  UINTN                 Count,\r
   OUT  VOID                 *Buffer\r
   )\r
   IN  UINTN                 Count,\r
   OUT  VOID                 *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo   - TODO: add argument description\r
-  Port    - TODO: add argument description\r
-  Count   - TODO: add argument description\r
-  Buffer  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 IDEWritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r
 VOID\r
 IDEWritePortB (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT8                 Data\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Data TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 IDEWritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r
 VOID\r
 IDEWritePortW (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
   IN  UINT16                Port,\r
   IN  UINT16                Data\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
-  Data  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\r
+  @param  Count TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 IDEWritePortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r
 VOID\r
 IDEWritePortWMultiple (\r
   IN  EFI_PCI_IO_PROTOCOL   *PciIo,\r


@@ -191,366 +152,259 @@ IDEWritePortWMultiple (
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r
   IN  UINTN                 Count,\r
   IN  VOID                  *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo   - TODO: add argument description\r
-  Port    - TODO: add argument description\r
-  Count   - TODO: add argument description\r
-  Buffer  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  IdeRegsBaseAddr TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 GetIdeRegistersBaseAddr (\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
   OUT IDE_REGISTERS_BASE_ADDR     *IdeRegsBaseAddr\r
   )\r
 EFI_STATUS\r
 GetIdeRegistersBaseAddr (\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
   OUT IDE_REGISTERS_BASE_ADDR     *IdeRegsBaseAddr\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo           - TODO: add argument description\r
-  IdeRegsBaseAddr - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 ReassignIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 ReassignIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DiscoverIdeDevice (\r
   IN IDE_BLK_IO_DEV *IdeDev\r
   )\r
 EFI_STATUS\r
 DiscoverIdeDevice (\r
   IN IDE_BLK_IO_DEV *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DetectIDEController (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 DetectIDEController (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRQClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRQClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRQReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRQReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRQReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 WaitForBSYClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 WaitForBSYClear (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TimeoutInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 WaitForBSYClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r
 EFI_STATUS\r
 WaitForBSYClear2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           TimeoutInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev                - TODO: add argument description\r
-  TimeoutInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DelayInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRDYReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRDYReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev              - TODO: add argument description\r
-  DelayInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DelayInMilliSeconds TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 DRDYReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r
 EFI_STATUS\r
 DRDYReady2 (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   IN  UINTN           DelayInMilliSeconds\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev              - TODO: add argument description\r
-  DelayInMilliSeconds - TODO: add argument description\r
-\r
-Returns:\r
+  @param  Destination TODO: add argument description\r
+  @param  Source TODO: add argument description\r
+  @param  Size TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 SwapStringChars (\r
   IN CHAR8  *Destination,\r
   IN CHAR8  *Source,\r
   IN UINT32 Size\r
   )\r
 VOID\r
 SwapStringChars (\r
   IN CHAR8  *Destination,\r
   IN CHAR8  *Source,\r
   IN UINT32 Size\r
   )\r

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

 \r
 \r

+//\r
+//  ATA device functions' prototype\r
+//\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  Destination - TODO: add argument description\r
-  Source      - TODO: add argument description\r
-  Size        - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
-;\r
-\r
-//\r
-//  ATA device functions' prototype\r
-//\r
+**/\r

 EFI_STATUS\r
 ATAIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 ATAIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 PrintAtaModuleName (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 VOID\r
 PrintAtaModuleName (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Head TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  SectorNumber TODO: add argument description\r
+  @param  CylinderLsb TODO: add argument description\r
+  @param  CylinderMsb TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaPioDataIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -563,31 +417,24 @@ AtaPioDataIn (
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev        - TODO: add argument description\r
-  Buffer        - TODO: add argument description\r
-  ByteCount     - TODO: add argument description\r
-  AtaCommand    - TODO: add argument description\r
-  Head          - TODO: add argument description\r
-  SectorCount   - TODO: add argument description\r
-  SectorNumber  - TODO: add argument description\r
-  CylinderLsb   - TODO: add argument description\r
-  CylinderMsb   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Head TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  SectorNumber TODO: add argument description\r
+  @param  CylinderLsb TODO: add argument description\r
+  @param  CylinderMsb TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaPioDataOut (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataOut (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -600,52 +447,33 @@ AtaPioDataOut (
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r
   IN  UINT8           CylinderLsb,\r
   IN  UINT8           CylinderMsb\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev        - TODO: add argument description\r
-  Buffer        - TODO: add argument description\r
-  ByteCount     - TODO: add argument description\r
-  AtaCommand    - TODO: add argument description\r
-  Head          - TODO: add argument description\r
-  SectorCount   - TODO: add argument description\r
-  SectorNumber  - TODO: add argument description\r
-  CylinderLsb   - TODO: add argument description\r
-  CylinderMsb   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 CheckErrorStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 CheckErrorStatus (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  Lba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -653,26 +481,19 @@ AtaReadSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  BufferData TODO: add argument description\r
+  @param  Lba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -680,47 +501,34 @@ AtaWriteSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  BufferData      - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtaSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeBlkIoDevice TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtaBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -729,27 +537,20 @@ AtaBlkIoReadBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeBlkIoDevice  - TODO: add argument description\r
-  MediaId         - TODO: add argument description\r
-  LBA             - TODO: add argument description\r
-  BufferSize      - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeBlkIoDevice TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtaBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -758,72 +559,51 @@ AtaBlkIoWriteBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

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

 \r
 \r

+//\r
+// ATAPI device functions' prototype\r
+//\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeBlkIoDevice  - TODO: add argument description\r
-  MediaId         - TODO: add argument description\r
-  LBA             - TODO: add argument description\r
-  BufferSize      - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
-;\r
-\r
-//\r
-// ATAPI device functions' prototype\r
-//\r
+**/\r

 EFI_STATUS\r
 ATAPIIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 ATAPIIdentify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiInquiry (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiInquiry (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Packet TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  TimeOut TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiPacketCommandIn (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r
 EFI_STATUS\r
 AtapiPacketCommandIn (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r


@@ -832,27 +612,20 @@ AtapiPacketCommandIn (
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev    - TODO: add argument description\r
-  Packet    - TODO: add argument description\r
-  Buffer    - TODO: add argument description\r
-  ByteCount - TODO: add argument description\r
-  TimeOut   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Packet TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  TimeOut TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiPacketCommandOut (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r
 EFI_STATUS\r
 AtapiPacketCommandOut (\r
   IN  IDE_BLK_IO_DEV        *IdeDev,\r


@@ -861,27 +634,20 @@ AtapiPacketCommandOut (
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r
   IN  UINT32                ByteCount,\r
   IN  UINTN                 TimeOut\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev    - TODO: add argument description\r
-  Packet    - TODO: add argument description\r
-  Buffer    - TODO: add argument description\r
-  ByteCount - TODO: add argument description\r
-  TimeOut   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  Read TODO: add argument description\r
+  @param  TimeOut TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 PioReadWriteData (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 PioReadWriteData (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -890,115 +656,79 @@ PioReadWriteData (
   IN  BOOLEAN         Read,\r
   IN  UINTN           TimeOut\r
   )\r
   IN  BOOLEAN         Read,\r
   IN  UINTN           TimeOut\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev    - TODO: add argument description\r
-  Buffer    - TODO: add argument description\r
-  ByteCount - TODO: add argument description\r
-  Read      - TODO: add argument description\r
-  TimeOut   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiTestUnitReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiTestUnitReady (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiRequestSense (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT UINTN           *SenseCounts\r
   )\r
 EFI_STATUS\r
 AtapiRequestSense (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT UINTN           *SenseCounts\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiReadCapacity (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiReadCapacity (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  MediaChange TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiDetectMedia (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT BOOLEAN         *MediaChange\r
   )\r
 EFI_STATUS\r
 AtapiDetectMedia (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
   OUT BOOLEAN         *MediaChange\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  MediaChange - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  Lba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtapiReadSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1006,26 +736,19 @@ AtapiReadSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  Lba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtapiWriteSectors (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1033,47 +756,34 @@ AtapiWriteSectors (
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         Lba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-  Lba             - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtapiSoftReset (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeBlkIoDevice TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtapiBlkIoReadBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -1082,27 +792,20 @@ AtapiBlkIoReadBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeBlkIoDevice  - TODO: add argument description\r
-  MediaId         - TODO: add argument description\r
-  LBA             - TODO: add argument description\r
-  BufferSize      - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeBlkIoDevice TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtapiBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r
 EFI_STATUS\r
 AtapiBlkIoWriteBlocks (\r
   IN IDE_BLK_IO_DEV   *IdeBlkIoDevice,\r


@@ -1111,259 +814,185 @@ AtapiBlkIoWriteBlocks (
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r
   IN UINTN            BufferSize,\r
   OUT VOID            *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeBlkIoDevice  - TODO: add argument description\r
-  MediaId         - TODO: add argument description\r
-  LBA             - TODO: add argument description\r
-  BufferSize      - TODO: add argument description\r
-  Buffer          - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 BOOLEAN\r
 IsNoMedia (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r
 BOOLEAN\r
 IsNoMedia (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 BOOLEAN\r
 IsMediaError (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r
 BOOLEAN\r
 IsMediaError (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 BOOLEAN\r
 IsMediaChange (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r
 BOOLEAN\r
 IsMediaChange (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r
+  @param  NeedRetry TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 BOOLEAN\r
 IsDriveReady (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts,\r
   OUT BOOLEAN               *NeedRetry\r
   )\r
 BOOLEAN\r
 IsDriveReady (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts,\r
   OUT BOOLEAN               *NeedRetry\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-  NeedRetry   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseCounts TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 BOOLEAN\r
 HaveSenseKey (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r
 BOOLEAN\r
 HaveSenseKey (\r
   IN  REQUEST_SENSE_DATA    *SenseData,\r
   IN  UINTN                 SenseCounts\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  SenseData   - TODO: add argument description\r
-  SenseCounts - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  WriteProtected TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 IsLS120orZipWriteProtected (\r
   IN  IDE_BLK_IO_DEV    *IdeDev,\r
   OUT BOOLEAN           *WriteProtected\r
   )\r
 EFI_STATUS\r
 IsLS120orZipWriteProtected (\r
   IN  IDE_BLK_IO_DEV    *IdeDev,\r
   OUT BOOLEAN           *WriteProtected\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  WriteProtected  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeBlkIoDevice TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 ReleaseIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeBlkIoDevice\r
   )\r
 VOID\r
 ReleaseIdeResources (\r
   IN  IDE_BLK_IO_DEV  *IdeBlkIoDevice\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeBlkIoDevice  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  TransferMode TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 SetDeviceTransferMode (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_TRANSFER_MODE    *TransferMode\r
   )\r
 EFI_STATUS\r
 SetDeviceTransferMode (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_TRANSFER_MODE    *TransferMode\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev        - TODO: add argument description\r
-  TransferMode  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  NativeMaxAddress TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 ReadNativeMaxAddress (\r
   IN  IDE_BLK_IO_DEV                *IdeDev,\r
   OUT EFI_LBA                       *NativeMaxAddress\r
   )\r
 EFI_STATUS\r
 ReadNativeMaxAddress (\r
   IN  IDE_BLK_IO_DEV                *IdeDev,\r
   OUT EFI_LBA                       *NativeMaxAddress\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev            - TODO: add argument description\r
-  NativeMaxAddress  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  MaxAddress TODO: add argument description\r
+  @param  bVolatile TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 SetMaxAddress (\r
   IN  IDE_BLK_IO_DEV                *IdeDev,\r
   IN  EFI_LBA                       MaxAddress,\r
   IN  BOOLEAN                       bVolatile\r
   )\r
 EFI_STATUS\r
 SetMaxAddress (\r
   IN  IDE_BLK_IO_DEV                *IdeDev,\r
   IN  EFI_LBA                       MaxAddress,\r
   IN  BOOLEAN                       bVolatile\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  MaxAddress  - TODO: add argument description\r
-  bVolatile   - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Device TODO: add argument description\r
+  @param  Feature TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  LbaLow TODO: add argument description\r
+  @param  LbaMiddle TODO: add argument description\r
+  @param  LbaHigh TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaNonDataCommandIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaNonDataCommandIn (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1375,30 +1004,21 @@ AtaNonDataCommandIn (
   IN  UINT8           LbaMiddle,\r
   IN  UINT8           LbaHigh\r
   )\r
   IN  UINT8           LbaMiddle,\r
   IN  UINT8           LbaHigh\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  Device      - TODO: add argument description\r
-  Feature     - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-  LbaLow      - TODO: add argument description\r
-  LbaMiddle   - TODO: add argument description\r
-  LbaHigh     - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Device TODO: add argument description\r
+  @param  Feature TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  LbaAddress TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaNonDataCommandInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaNonDataCommandInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1408,28 +1028,19 @@ AtaNonDataCommandInExt (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  Device      - TODO: add argument description\r
-  Feature     - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-  LbaAddress  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaReadSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaReadSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1437,26 +1048,19 @@ AtaReadSectorsExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaWriteSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaWriteSectorsExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1464,26 +1068,19 @@ AtaWriteSectorsExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaUdmaReadExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaReadExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1491,26 +1088,19 @@ AtaUdmaReadExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaUdmaRead (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaRead (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1518,26 +1108,19 @@ AtaUdmaRead (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaUdmaWriteExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaWriteExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1545,26 +1128,19 @@ AtaUdmaWriteExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DataBuffer TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  NumberOfBlocks TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaUdmaWrite (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaUdmaWrite (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1572,26 +1148,21 @@ AtaUdmaWrite (
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINTN           NumberOfBlocks\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DataBuffer      - TODO: add argument description\r
-  StartLba        - TODO: add argument description\r
-  NumberOfBlocks  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Device TODO: add argument description\r
+  @param  Feature TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  LbaAddress TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaCommandIssueExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaCommandIssueExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1601,28 +1172,21 @@ AtaCommandIssueExt (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  Device      - TODO: add argument description\r
-  Feature     - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-  LbaAddress  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  Device TODO: add argument description\r
+  @param  Feature TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r
+  @param  LbaAddress TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaCommandIssue (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaCommandIssue (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1632,71 +1196,50 @@ AtaCommandIssue (
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r
   IN  UINT16          SectorCount,\r
   IN  EFI_LBA         LbaAddress\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  Device      - TODO: add argument description\r
-  Feature     - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-  LbaAddress  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaAtapi6Identify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 EFI_STATUS\r
 AtaAtapi6Identify (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

-/*++\r
+;\r

 \r
 \r

-Routine Description:\r

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 VOID\r
 AtaSMARTSupport (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r
 VOID\r
 AtaSMARTSupport (\r
   IN  IDE_BLK_IO_DEV  *IdeDev\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaPioDataInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataInExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1706,28 +1249,21 @@ AtaPioDataInExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
-  ByteCount   - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  StartLba    - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r
+  @param  ByteCount TODO: add argument description\r
+  @param  AtaCommand TODO: add argument description\r
+  @param  StartLba TODO: add argument description\r
+  @param  SectorCount TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 AtaPioDataOutExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r
 EFI_STATUS\r
 AtaPioDataOutExt (\r
   IN  IDE_BLK_IO_DEV  *IdeDev,\r


@@ -1737,70 +1273,36 @@ AtaPioDataOutExt (
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r
   IN  EFI_LBA         StartLba,\r
   IN  UINT16          SectorCount\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev      - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
-  ByteCount   - TODO: add argument description\r
-  AtaCommand  - TODO: add argument description\r
-  StartLba    - TODO: add argument description\r
-  SectorCount - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r
+  @param  DriveParameters TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 SetDriveParameters (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_DRIVE_PARMS      *DriveParameters\r
   )\r
 EFI_STATUS\r
 SetDriveParameters (\r
   IN IDE_BLK_IO_DEV       *IdeDev,\r
   IN ATA_DRIVE_PARMS      *DriveParameters\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  IdeDev          - TODO: add argument description\r
-  DriveParameters - TODO: add argument description\r
-\r
-Returns:\r
+  @param  IdeDev TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EnableInterrupt (\r
   IN IDE_BLK_IO_DEV       *IdeDev\r
   )\r
 EFI_STATUS\r
 EnableInterrupt (\r
   IN IDE_BLK_IO_DEV       *IdeDev\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IdeDev  - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

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

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c
index 4cf882eb00f01d4abc4f6513eeedddbc95eda43e..e5157dab70831fd838144e51e4c09b914ceff9f5 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c
@@ -1,25 +1,17 @@
-/*++\r
+/** @file\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
 \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
+  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

-Module Name:\r
-\r
-  idebus.c\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
+  @par Revision Reference:\r

   This module is modified from DXE\IDE module for Ide Contriller Init support\r
 \r
   This module is modified from DXE\IDE module for Ide Contriller Init support\r
 \r

---*/\r
+**/\r

 \r
 #include "idebus.h"\r
 \r
 \r
 #include "idebus.h"\r
 \r


@@ -44,6 +36,17 @@ EFI_DRIVER_BINDING_PROTOCOL gIDEBusDriverBinding = {
 // IDEBusDriverBindingSupported\r
 // ***********************************************************************************\r
 //\r
 // IDEBusDriverBindingSupported\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  Register Driver Binding protocol for this driver.\r
+\r
+  @param[in] This   -- A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+  @param[in] ControllerHandle    -- The handle of the controller to test.\r
+  @param[in] RemainingDevicePath -- A pointer to the remaining portion of a device path.\r
+\r
+  @retval  EFI_SUCCESS Driver loaded.\r
+  @retval  other Driver not loaded.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingSupported (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingSupported (\r


@@ -51,20 +54,6 @@ IDEBusDriverBindingSupported (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

-/*++\r
-  \r
-Routine Description:\r
-  Register Driver Binding protocol for this driver.\r
-  \r
-Arguments:\r
-  This   -- A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
-  ControllerHandle    -- The handle of the controller to test.\r
-  RemainingDevicePath -- A pointer to the remaining portion of a device path.\r
-\r
-Returns: \r
-  EFI_SUCCESS - Driver loaded.\r
-  other       - Driver not loaded.\r
---*/\r

 // TODO:    Controller - add argument and description to function comment\r
 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 {\r
 // TODO:    Controller - add argument and description to function comment\r
 // TODO:    EFI_UNSUPPORTED - add return value to function comment\r
 {\r


@@ -150,6 +139,19 @@ Returns:
 // IDEBusDriverBindingStart\r
 // ***********************************************************************************\r
 //\r
 // IDEBusDriverBindingStart\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  Start this driver on Controller by detecting all disks and installing \r
+  BlockIo protocol on them.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  Controller Handle of device to bind driver to.\r
+  @param  RemainingDevicePath Not used, always produce all possible children.\r
+\r
+  @retval  EFI_SUCCESS This driver is added to ControllerHandle.\r
+  @retval  EFI_ALREADY_STARTED This driver is already running on ControllerHandle.\r
+  @retval  other This driver does not support this device.\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStart (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStart (\r


@@ -157,23 +159,6 @@ IDEBusDriverBindingStart (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Start this driver on Controller by detecting all disks and installing \r
-      BlockIo protocol on them.\r
-\r
-  Arguments:\r
-    This                - Protocol instance pointer.\r
-    Controller          - Handle of device to bind driver to.\r
-    RemainingDevicePath - Not used, always produce all possible children.\r
-\r
-  Returns:\r
-    EFI_SUCCESS         - This driver is added to ControllerHandle.\r
-    EFI_ALREADY_STARTED - This driver is already running on ControllerHandle.\r
-    other               - This driver does not support this device.\r
-\r
---*/\r

 {\r
   EFI_STATUS                        Status;\r
   EFI_STATUS                        SavedStatus;\r
 {\r
   EFI_STATUS                        Status;\r
   EFI_STATUS                        SavedStatus;\r


@@ -791,6 +776,18 @@ ErrorExit:
 // IDEBusDriverBindingStop\r
 // ***********************************************************************************\r
 //\r
 // IDEBusDriverBindingStop\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  Stop this driver on Controller Handle. \r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  DeviceHandle Handle of device to stop driver on\r
+  @param  NumberOfChildren Not used\r
+  @param  ChildHandleBuffer Not used\r
+\r
+  @retval  EFI_SUCCESS This driver is removed DeviceHandle\r
+  @retval  other This driver was not removed from this device\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStop (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStop (\r


@@ -799,22 +796,6 @@ IDEBusDriverBindingStop (
   IN  UINTN                           NumberOfChildren,\r
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   )\r
   IN  UINTN                           NumberOfChildren,\r
   IN  EFI_HANDLE                      *ChildHandleBuffer\r
   )\r

-/*++\r
-  \r
-  Routine Description:\r
-    Stop this driver on Controller Handle. \r
-\r
-  Arguments:\r
-    This              - Protocol instance pointer.\r
-    DeviceHandle      - Handle of device to stop driver on \r
-    NumberOfChildren  - Not used\r
-    ChildHandleBuffer - Not used\r
-\r
-  Returns:\r
-    EFI_SUCCESS       - This driver is removed DeviceHandle\r
-    other             - This driver was not removed from this device\r
-  \r
---*/\r

 // TODO:    Controller - add argument and description to function comment\r
 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r
 // TODO:    Controller - add argument and description to function comment\r
 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r


@@ -912,29 +893,22 @@ IDEBusDriverBindingStop (
 // DeRegisterIdeDevice\r
 // ***********************************************************************************\r
 //\r
 // DeRegisterIdeDevice\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  Deregister an IDE device and free resources\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  Controller Ide device handle\r
+  @param  Handle Handle of device to deregister driver on\r
+\r
+  @return EFI_STATUS\r
+\r
+**/\r

 EFI_STATUS\r
 DeRegisterIdeDevice (\r
   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,\r
   IN  EFI_HANDLE                     Controller,\r
   IN  EFI_HANDLE                     Handle\r
   )\r
 EFI_STATUS\r
 DeRegisterIdeDevice (\r
   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,\r
   IN  EFI_HANDLE                     Controller,\r
   IN  EFI_HANDLE                     Handle\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Deregister an IDE device and free resources\r
-  \r
-Arguments:\r
-\r
-  This            - Protocol instance pointer.\r
-  Controller      - Ide device handle\r
-  Handle          - Handle of device to deregister driver on \r
-  \r
-Returns:\r
-\r
-  EFI_STATUS\r
-\r
---*/\r

 // TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS            Status;\r
 // TODO:    EFI_SUCCESS - add return value to function comment\r
 {\r
   EFI_STATUS            Status;\r


@@ -1015,26 +989,18 @@ Returns:
 // IDEBlkIoReset\r
 // ***********************************************************************************\r
 //\r
 // IDEBlkIoReset\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  TODO:    This - add argument and description to function comment\r
+  TODO:    ExtendedVerification - add argument and description to function comment\r
+  TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReset (\r
   IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
   IN  BOOLEAN                 ExtendedVerification\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReset (\r
   IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
   IN  BOOLEAN                 ExtendedVerification\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    ExtendedVerification - add argument and description to function comment\r
-// TODO:    EFI_DEVICE_ERROR - add return value to function comment\r

 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
   EFI_STATUS      Status;\r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
   EFI_STATUS      Status;\r


@@ -1067,6 +1033,18 @@ Returns:
   return Status;\r
 }\r
 \r
   return Status;\r
 }\r
 \r

+/**\r
+  Read data from block io device\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  MediaId The media ID of the device\r
+  @param  LBA Starting LBA address to read data\r
+  @param  BufferSize The size of data to be read\r
+  @param  Buffer Caller supplied buffer to save data\r
+\r
+  @return read data status\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReadBlocks (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReadBlocks (\r


@@ -1076,25 +1054,6 @@ IDEBlkIoReadBlocks (
   IN  UINTN                   BufferSize,\r
   OUT VOID                    *Buffer\r
   )\r
   IN  UINTN                   BufferSize,\r
   OUT VOID                    *Buffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Read data from block io device\r
-  \r
-Arguments:\r
-\r
-  This            - Protocol instance pointer.\r
-  MediaId         - The media ID of the device\r
-  LBA             - Starting LBA address to read data\r
-  BufferSize      - The size of data to be read\r
-  Buffer          - Caller supplied buffer to save data\r
-  \r
-Returns:\r
-\r
-  read data status\r
-\r
---*/\r

 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r


@@ -1137,6 +1096,18 @@ Returns:
 \r
 }\r
 \r
 \r
 }\r
 \r

+/**\r
+  Write data to block io device\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  MediaId The media ID of the device\r
+  @param  LBA Starting LBA address to write data\r
+  @param  BufferSize The size of data to be written\r
+  @param  Buffer Caller supplied buffer to save data\r
+\r
+  @return write data status\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoWriteBlocks (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoWriteBlocks (\r


@@ -1146,25 +1117,6 @@ IDEBlkIoWriteBlocks (
   IN  UINTN                   BufferSize,\r
   IN  VOID                    *Buffer\r
   )\r
   IN  UINTN                   BufferSize,\r
   IN  VOID                    *Buffer\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  Write data to block io device\r
-  \r
-Arguments:\r
-\r
-  This            - Protocol instance pointer.\r
-  MediaId         - The media ID of the device\r
-  LBA             - Starting LBA address to write data\r
-  BufferSize      - The size of data to be written\r
-  Buffer          - Caller supplied buffer to save data\r
-  \r
-Returns:\r
-\r
-  write data status\r
-\r
---*/\r

 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 // TODO:    EFI_DEVICE_ERROR - add return value to function comment\r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r


@@ -1211,24 +1163,15 @@ Returns:
 // IDEBlkIoFlushBlocks\r
 // ***********************************************************************************\r
 //\r
 // IDEBlkIoFlushBlocks\r
 // ***********************************************************************************\r
 //\r

+/**\r
+  TODO:    This - add argument and description to function comment\r
+  TODO:    EFI_SUCCESS - add return value to function comment\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoFlushBlocks (\r
   IN  EFI_BLOCK_IO_PROTOCOL   *This\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoFlushBlocks (\r
   IN  EFI_BLOCK_IO_PROTOCOL   *This\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
-  None\r
-\r
---*/\r
-// TODO:    This - add argument and description to function comment\r
-// TODO:    EFI_SUCCESS - add return value to function comment\r

 {\r
   //\r
   // return directly\r
 {\r
   //\r
   // return directly\r


@@ -1236,6 +1179,20 @@ Returns:
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Return the results of the Inquiry command to a drive in InquiryData.\r
+  Data format of Inquiry data is defined by the Interface GUID.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  InquiryData Results of Inquiry command to device\r
+  @param  InquiryDataSize Size of InquiryData in bytes.\r
+\r
+  @retval  EFI_SUCCESS InquiryData valid\r
+  @retval  EFI_NOT_FOUND Device does not support this data class\r
+  @retval  EFI_DEVICE_ERROR Error reading InquiryData from device\r
+  @retval  EFI_BUFFER_TOO_SMALL IntquiryDataSize not big enough\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoInquiry (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoInquiry (\r


@@ -1243,24 +1200,6 @@ IDEDiskInfoInquiry (
   IN OUT VOID                     *InquiryData,\r
   IN OUT UINT32                   *InquiryDataSize\r
   )\r
   IN OUT VOID                     *InquiryData,\r
   IN OUT UINT32                   *InquiryDataSize\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Return the results of the Inquiry command to a drive in InquiryData.\r
-    Data format of Inquiry data is defined by the Interface GUID.\r
-\r
-  Arguments:\r
-    This        - Protocol instance pointer.\r
-    InquiryData - Results of Inquiry command to device\r
-    InquiryDataSize - Size of InquiryData in bytes.\r
-\r
-  Returns:\r
-    EFI_SUCCESS       - InquiryData valid\r
-    EFI_NOT_FOUND     - Device does not support this data class\r
-    EFI_DEVICE_ERROR  - Error reading InquiryData from device \r
-    EFI_BUFFER_TOO_SMALL - IntquiryDataSize not big enough\r
-\r
---*/\r

 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r


@@ -1281,6 +1220,20 @@ IDEDiskInfoInquiry (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Return the results of the Identify command to a drive in IdentifyData.\r
+  Data format of Identify data is defined by the Interface GUID.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  IdentifyData Results of Identify command to device\r
+  @param  IdentifyDataSize Size of IdentifyData in bytes.\r
+\r
+  @retval  EFI_SUCCESS IdentifyData valid\r
+  @retval  EFI_NOT_FOUND Device does not support this data class\r
+  @retval  EFI_DEVICE_ERROR Error reading IdentifyData from device\r
+  @retval  EFI_BUFFER_TOO_SMALL IdentifyDataSize not big enough\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoIdentify (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoIdentify (\r


@@ -1288,24 +1241,6 @@ IDEDiskInfoIdentify (
   IN OUT VOID                     *IdentifyData,\r
   IN OUT UINT32                   *IdentifyDataSize\r
   )\r
   IN OUT VOID                     *IdentifyData,\r
   IN OUT UINT32                   *IdentifyDataSize\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Return the results of the Identify command to a drive in IdentifyData.\r
-    Data format of Identify data is defined by the Interface GUID.\r
-\r
-  Arguments:\r
-    This        - Protocol instance pointer.\r
-    IdentifyData - Results of Identify command to device\r
-    IdentifyDataSize - Size of IdentifyData in bytes.\r
-\r
-  Returns:\r
-    EFI_SUCCESS       - IdentifyData valid\r
-    EFI_NOT_FOUND     - Device does not support this data class\r
-    EFI_DEVICE_ERROR  - Error reading IdentifyData from device \r
-    EFI_BUFFER_TOO_SMALL - IdentifyDataSize not big enough\r
-\r
---*/\r

 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r


@@ -1326,6 +1261,21 @@ IDEDiskInfoIdentify (
   return EFI_SUCCESS;\r
 }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r

+/**\r
+  Return the results of the Request Sense command to a drive in SenseData.\r
+  Data format of Sense data is defined by the Interface GUID.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  SenseData Results of Request Sense command to device\r
+  @param  SenseDataSize Size of SenseData in bytes.\r
+  @param  SenseDataNumber Type of SenseData\r
+\r
+  @retval  EFI_SUCCESS InquiryData valid\r
+  @retval  EFI_NOT_FOUND Device does not support this data class\r
+  @retval  EFI_DEVICE_ERROR Error reading InquiryData from device\r
+  @retval  EFI_BUFFER_TOO_SMALL SenseDataSize not big enough\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoSenseData (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoSenseData (\r


@@ -1334,29 +1284,22 @@ IDEDiskInfoSenseData (
   IN OUT UINT32                   *SenseDataSize,\r
   OUT    UINT8                    *SenseDataNumber\r
   )\r
   IN OUT UINT32                   *SenseDataSize,\r
   OUT    UINT8                    *SenseDataNumber\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Return the results of the Request Sense command to a drive in SenseData.\r
-    Data format of Sense data is defined by the Interface GUID.\r
-\r
-  Arguments:\r
-    This            - Protocol instance pointer.\r
-    SenseData       - Results of Request Sense command to device\r
-    SenseDataSize   - Size of SenseData in bytes.\r
-    SenseDataNumber - Type of SenseData\r
-\r
-  Returns:\r
-    EFI_SUCCESS       - InquiryData valid\r
-    EFI_NOT_FOUND     - Device does not support this data class\r
-    EFI_DEVICE_ERROR  - Error reading InquiryData from device \r
-    EFI_BUFFER_TOO_SMALL - SenseDataSize not big enough\r
-\r
---*/\r

 {\r
   return EFI_NOT_FOUND;\r
 }\r
 \r
 {\r
   return EFI_NOT_FOUND;\r
 }\r
 \r

+/**\r
+  Return the results of the Request Sense command to a drive in SenseData.\r
+  Data format of Sense data is defined by the Interface GUID.\r
+\r
+  @param  This Protocol instance pointer.\r
+  @param  IdeChannel Primary or Secondary\r
+  @param  IdeDevice Master or Slave\r
+\r
+  @retval  EFI_SUCCESS IdeChannel and IdeDevice are valid\r
+  @retval  EFI_UNSUPPORTED This is not an IDE device\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoWhichIde (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoWhichIde (\r


@@ -1364,22 +1307,6 @@ IDEDiskInfoWhichIde (
   OUT UINT32                   *IdeChannel,\r
   OUT UINT32                   *IdeDevice\r
   )\r
   OUT UINT32                   *IdeChannel,\r
   OUT UINT32                   *IdeDevice\r
   )\r

-/*++\r
-\r
-  Routine Description:\r
-    Return the results of the Request Sense command to a drive in SenseData.\r
-    Data format of Sense data is defined by the Interface GUID.\r
-\r
-  Arguments:\r
-    This        - Protocol instance pointer.\r
-    IdeChannel  - Primary or Secondary\r
-    IdeDevice   - Master or Slave\r
-\r
-  Returns:\r
-    EFI_SUCCESS       - IdeChannel and IdeDevice are valid\r
-    EFI_UNSUPPORTED   - This is not an IDE device\r
-\r
---*/\r

 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r
 {\r
   IDE_BLK_IO_DEV  *IdeBlkIoDevice;\r
 \r

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h
index 428dffa65d42373e75c865728f08058120096e8e..d1721b956fc3b5a474956fac7a9601c222d7595b 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h
@@ -1,25 +1,17 @@
-/*++\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
+/** @file\r
+  Header file for IDE Bus Driver.\r

 \r
 \r

-Module Name:\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
 \r

-    idebus.h\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

-Abstract:\r
+**/\r

 \r
 \r

-    Header file for IDE Bus Driver.\r
-\r
-Revision History\r
-++*/\r
-\r
-// TODO: fix comment to end with --*/\r

 #ifndef _IDE_BUS_H\r
 #define _IDE_BUS_H\r
 \r
 #ifndef _IDE_BUS_H\r
 #define _IDE_BUS_H\r
 \r


@@ -94,30 +86,33 @@ extern EFI_DRIVER_BINDING_PROTOCOL  gIDEBusDriverBinding;
 // Prototypes\r
 // Driver model protocol interface\r
 //\r
 // Prototypes\r
 // Driver model protocol interface\r
 //\r

+/**\r
+  TODO: Add function description\r
+\r
+  @param  ImageHandle TODO: add argument description\r
+  @param  SystemTable TODO: add argument description\r
+\r
+  TODO: add return values\r
+\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBusControllerDriverEntryPoint (\r
   IN EFI_HANDLE                   ImageHandle,\r
   IN EFI_SYSTEM_TABLE             *SystemTable\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusControllerDriverEntryPoint (\r
   IN EFI_HANDLE                   ImageHandle,\r
   IN EFI_SYSTEM_TABLE             *SystemTable\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  ImageHandle - TODO: add argument description\r
-  SystemTable - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  RemainingDevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingSupported (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingSupported (\r


@@ -125,25 +120,18 @@ IDEBusDriverBindingSupported (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This                - TODO: add argument description\r
-  Controller          - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  RemainingDevicePath TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStart (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStart (\r


@@ -151,25 +139,19 @@ IDEBusDriverBindingStart (
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r
   IN EFI_HANDLE                   Controller,\r
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This                - TODO: add argument description\r
-  Controller          - TODO: add argument description\r
-  RemainingDevicePath - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  Controller TODO: add argument description\r
+  @param  NumberOfChildren TODO: add argument description\r
+  @param  ChildHandleBuffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStop (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBusDriverBindingStop (\r


@@ -178,53 +160,40 @@ IDEBusDriverBindingStop (
   IN  UINTN                       NumberOfChildren,\r
   IN  EFI_HANDLE                  *ChildHandleBuffer\r
   )\r
   IN  UINTN                       NumberOfChildren,\r
   IN  EFI_HANDLE                  *ChildHandleBuffer\r
   )\r

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

 \r
 \r

+//\r
+// Block I/O Protocol Interface\r
+//\r
+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This              - TODO: add argument description\r
-  Controller        - TODO: add argument description\r
-  NumberOfChildren  - TODO: add argument description\r
-  ChildHandleBuffer - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  ExtendedVerification TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

---*/\r
-;\r
-\r
-//\r
-// Block I/O Protocol Interface\r
-//\r
+**/\r

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReset (\r
   IN  EFI_BLOCK_IO_PROTOCOL       *This,\r
   IN  BOOLEAN                     ExtendedVerification\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReset (\r
   IN  EFI_BLOCK_IO_PROTOCOL       *This,\r
   IN  BOOLEAN                     ExtendedVerification\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This                  - TODO: add argument description\r
-  ExtendedVerification  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReadBlocks (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoReadBlocks (\r


@@ -234,27 +203,20 @@ IDEBlkIoReadBlocks (
   IN  UINTN                       BufferSize,\r
   OUT VOID                        *Buffer\r
   )\r
   IN  UINTN                       BufferSize,\r
   OUT VOID                        *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  MediaId     - TODO: add argument description\r
-  LBA         - TODO: add argument description\r
-  BufferSize  - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  MediaId TODO: add argument description\r
+  @param  LBA TODO: add argument description\r
+  @param  BufferSize TODO: add argument description\r
+  @param  Buffer TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoWriteBlocks (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoWriteBlocks (\r


@@ -264,72 +226,49 @@ IDEBlkIoWriteBlocks (
   IN  UINTN                       BufferSize,\r
   IN  VOID                        *Buffer\r
   )\r
   IN  UINTN                       BufferSize,\r
   IN  VOID                        *Buffer\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  MediaId     - TODO: add argument description\r
-  LBA         - TODO: add argument description\r
-  BufferSize  - TODO: add argument description\r
-  Buffer      - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoFlushBlocks (\r
   IN  EFI_BLOCK_IO_PROTOCOL       *This\r
   )\r
 EFI_STATUS\r
 EFIAPI\r
 IDEBlkIoFlushBlocks (\r
   IN  EFI_BLOCK_IO_PROTOCOL       *This\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Enable TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 IDERegisterDecodeEnableorDisable (\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
   IN  BOOLEAN                     Enable\r
   )\r
 EFI_STATUS\r
 IDERegisterDecodeEnableorDisable (\r
   IN  EFI_PCI_IO_PROTOCOL         *PciIo,\r
   IN  BOOLEAN                     Enable\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  PciIo   - TODO: add argument description\r
-  Enable  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  InquiryData TODO: add argument description\r
+  @param  IntquiryDataSize TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoInquiry (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoInquiry (\r


@@ -337,25 +276,18 @@ IDEDiskInfoInquiry (
   IN OUT VOID                     *InquiryData,\r
   IN OUT UINT32                   *IntquiryDataSize\r
   )\r
   IN OUT VOID                     *InquiryData,\r
   IN OUT UINT32                   *IntquiryDataSize\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This              - TODO: add argument description\r
-  InquiryData       - TODO: add argument description\r
-  IntquiryDataSize  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  IdentifyData TODO: add argument description\r
+  @param  IdentifyDataSize TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoIdentify (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoIdentify (\r


@@ -363,25 +295,19 @@ IDEDiskInfoIdentify (
   IN OUT VOID                     *IdentifyData,\r
   IN OUT UINT32                   *IdentifyDataSize\r
   )\r
   IN OUT VOID                     *IdentifyData,\r
   IN OUT UINT32                   *IdentifyDataSize\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This              - TODO: add argument description\r
-  IdentifyData      - TODO: add argument description\r
-  IdentifyDataSize  - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  SenseData TODO: add argument description\r
+  @param  SenseDataSize TODO: add argument description\r
+  @param  SenseDataNumber TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoSenseData (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoSenseData (\r


@@ -390,26 +316,18 @@ IDEDiskInfoSenseData (
   IN OUT UINT32                   *SenseDataSize,\r
   OUT UINT8                       *SenseDataNumber\r
   )\r
   IN OUT UINT32                   *SenseDataSize,\r
   OUT UINT8                       *SenseDataNumber\r
   )\r

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

 \r
 \r

+/**\r

   TODO: Add function description\r
 \r
   TODO: Add function description\r
 \r

-Arguments:\r
-\r
-  This            - TODO: add argument description\r
-  SenseData       - TODO: add argument description\r
-  SenseDataSize   - TODO: add argument description\r
-  SenseDataNumber - TODO: add argument description\r
-\r
-Returns:\r
+  @param  This TODO: add argument description\r
+  @param  IdeChannel TODO: add argument description\r
+  @param  IdeDevice TODO: add argument description\r

 \r
   TODO: add return values\r
 \r
 \r
   TODO: add return values\r
 \r

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

 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoWhichIde (\r
 EFI_STATUS\r
 EFIAPI\r
 IDEDiskInfoWhichIde (\r


@@ -417,23 +335,6 @@ IDEDiskInfoWhichIde (
   OUT UINT32                      *IdeChannel,\r
   OUT UINT32                      *IdeDevice\r
   )\r
   OUT UINT32                      *IdeChannel,\r
   OUT UINT32                      *IdeDevice\r
   )\r

-/*++\r
-\r
-Routine Description:\r
-\r
-  TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  This        - TODO: add argument description\r
-  IdeChannel  - TODO: add argument description\r
-  IdeDevice   - TODO: add argument description\r
-\r
-Returns:\r
-\r
-  TODO: add return values\r
-\r
---*/\r

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

diff --git a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h
index 50b1f05a47f9befc4c2e1296eb1b5ceccb6e69ab..55ae217d442d68ccff706d0732077115188d379e 100644 (file)
--- a/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h
+++ b/EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h
@@ -1,25 +1,17 @@
-/*++\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
+/** @file\r
+  Header file for IDE Bus Driver's Data Structures\r

 \r
 \r

-Module Name:\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
 \r

-    idedata.h\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

-Abstract:\r
+**/\r

 \r
 \r

-    Header file for IDE Bus Driver's Data Structures\r
-\r
-Revision History\r
-++*/\r
-\r
-// TODO: fix comment to end with --*/\r

 #ifndef _IDE_DATA_H\r
 #define _IDE_DATA_H\r
 \r
 #ifndef _IDE_DATA_H\r
 #define _IDE_DATA_H\r
 \r