Update comments to conform to the new, Doxygen friendly, coding standard. These...
authordarylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524>
Fri, 9 Jun 2006 23:41:12 +0000 (23:41 +0000)
committerdarylm503 <darylm503@6f19259b-4bc3-4df7-8a09-765794883524>
Fri, 9 Jun 2006 23:41:12 +0000 (23:41 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@461 6f19259b-4bc3-4df7-8a09-765794883524

18 files changed:
EdkModulePkg/Application/HelloWorld/HelloWorld.c
EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.c
EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/AtapiPassThru.h
EdkModulePkg/Bus/Pci/AtapiPassThru/Dxe/ComponentName.c
EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.c
EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430.h
EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/CirrusLogic5430UgaDraw.c
EdkModulePkg/Bus/Pci/CirrusLogic/Dxe/ComponentName.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/ComponentName.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverConfiguration.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/DriverDiagnostics.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/ata.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/atapi.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/ide.h
EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.c
EdkModulePkg/Bus/Pci/IdeBus/Dxe/idebus.h
EdkModulePkg/Bus/Pci/IdeBus/Dxe/idedata.h

index f3eda07..d3714eb 100644 (file)
@@ -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
-  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
-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
 VOID\r
 Print (\r
index 6fe81d1..1bdce40 100644 (file)
@@ -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
-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
-Module Name:\r
-\r
-    AtapiPassThru.c\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
---*/\r
+**/\r
 \r
 #include "AtapiPassThru.h"\r
 \r
@@ -46,9 +37,9 @@ AtapiScsiPassThruDriverBindingStop (
   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
@@ -56,9 +47,9 @@ static IDE_BASE_REGISTERS   gAtapiIoPortRegisters[2] = {
 \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
@@ -107,6 +98,18 @@ EFI_DRIVER_BINDING_PROTOCOL gAtapiScsiPassThruDriverBinding = {
   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
@@ -114,22 +117,6 @@ AtapiScsiPassThruDriverBindingSupported (
   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
@@ -186,6 +173,18 @@ AtapiScsiPassThruDriverBindingSupported (
   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
@@ -193,22 +192,6 @@ AtapiScsiPassThruDriverBindingStart (
   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
@@ -263,6 +246,19 @@ Done:
   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
@@ -271,23 +267,6 @@ AtapiScsiPassThruDriverBindingStop (
   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
@@ -337,28 +316,25 @@ AtapiScsiPassThruDriverBindingStop (
   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
-/*++\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
@@ -427,6 +403,29 @@ RegisterAtapiScsiPassThru (
   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
@@ -436,34 +435,6 @@ AtapiScsiPassThruFunction (
   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
@@ -515,6 +486,29 @@ AtapiScsiPassThruFunction (
   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
@@ -522,32 +516,6 @@ AtapiScsiPassThruGetNextDevice (
   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
@@ -591,6 +559,33 @@ AtapiScsiPassThruGetNextDevice (
 \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
@@ -599,35 +594,6 @@ AtapiScsiPassThruBuildDevicePath (
   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
@@ -670,6 +636,29 @@ AtapiScsiPassThruBuildDevicePath (
   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
@@ -678,31 +667,6 @@ AtapiScsiPassThruGetTargetLun (
   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
@@ -734,29 +698,26 @@ AtapiScsiPassThruGetTargetLun (
   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
-/*++\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
@@ -813,6 +774,25 @@ AtapiScsiPassThruResetChannel (
   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
@@ -820,28 +800,6 @@ AtapiScsiPassThruResetTarget (
   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
@@ -899,25 +857,24 @@ AtapiScsiPassThruResetTarget (
 }\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
-/*++\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
@@ -941,21 +898,20 @@ CheckSCSIRequestPacket (
   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
-/*++\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
@@ -995,30 +951,25 @@ IsCommandValid (
   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
-/*++\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
@@ -1079,6 +1030,23 @@ Routine Description:
   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
@@ -1087,25 +1055,6 @@ RequestSenseCommand (
   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
@@ -1130,6 +1079,37 @@ Returns:
   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
@@ -1140,42 +1120,6 @@ AtapiPacketCommand (
   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
@@ -1285,6 +1229,35 @@ AtapiPacketCommand (
           );\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
@@ -1293,40 +1266,6 @@ AtapiPassThruPioReadWriteData (
   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
@@ -1420,19 +1359,20 @@ AtapiPassThruPioReadWriteData (
 }\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
-/*++\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
@@ -1449,19 +1389,20 @@ ReadPortB (
 }\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
-/*++\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
@@ -1478,21 +1419,22 @@ ReadPortW (
 }\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
-/*++\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
@@ -1507,21 +1449,22 @@ WritePortB (
 }\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
-/*++\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
@@ -1534,25 +1477,26 @@ WritePortW (
               );\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
-/*++\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
@@ -1613,26 +1557,27 @@ StatusDRQClear (
   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
---*/\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
@@ -1691,25 +1636,26 @@ AltStatusDRQClear (
   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
-/*++\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
@@ -1770,26 +1716,27 @@ StatusDRQReady (
   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
---*/\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
@@ -1849,24 +1796,25 @@ AltStatusDRQReady (
   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
-/*++\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
@@ -1909,24 +1857,25 @@ StatusWaitForBSYClear (
   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
-/*++\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
@@ -1968,26 +1917,27 @@ AltStatusWaitForBSYClear (
   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
---*/\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
@@ -2043,26 +1993,27 @@ StatusDRDYReady (
   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
---*/\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
@@ -2118,19 +2069,20 @@ AltStatusDRDYReady (
   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
-/*++  \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
index d705c65..659b37c 100644 (file)
@@ -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
-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
-Module Name:\r
+  Module Name:  AtapiPassThru.h\r
 \r
-    AtapiPassThru.h\r
-    \r
-Abstract: \r
-    \r
-\r
-Revision History\r
---*/\r
+**/\r
 \r
 #ifndef _APT_H\r
 #define _APT_H\r
@@ -25,12 +18,13 @@ Revision History
 \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
+\r
 //\r
 // IDE Registers\r
 //\r
@@ -49,9 +43,9 @@ typedef union {
   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
@@ -167,21 +161,21 @@ typedef struct {
 //\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
-#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
@@ -201,21 +195,21 @@ typedef struct {
 //\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
-#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
@@ -242,55 +236,63 @@ typedef struct {
 //\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
- /*++\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
-  TODO: add return values\r
+/**\r
+  RegisterAtapiScsiPassThru\r
 \r
---*/\r
-;\r
+  @param  This\r
+  @param  Controller\r
+  @param  PciIo\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
-/*++\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
+  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
@@ -300,27 +302,20 @@ AtapiScsiPassThruFunction (
   IN OUT EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET         *Packet,\r
   IN EFI_EVENT                                          Event OPTIONAL\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiScsiPassThruGetNextDevice\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetNextDevice (\r
@@ -328,25 +323,21 @@ AtapiScsiPassThruGetNextDevice (
   IN OUT UINT32                      *Target,\r
   IN OUT UINT64                      *Lun\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiScsiPassThruBuildDevicePath\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
-;\r
-\r
+**/\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
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiScsiPassThruGetTargetLun\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruGetTargetLun (\r
@@ -383,48 +369,37 @@ AtapiScsiPassThruGetTargetLun (
   OUT UINT32                         *Target,\r
   OUT UINT64                         *Lun\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiScsiPassThruResetChannel\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetChannel (\r
   IN  EFI_SCSI_PASS_THRU_PROTOCOL   *This\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiScsiPassThruResetTarget\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 AtapiScsiPassThruResetTarget (\r
@@ -432,92 +407,74 @@ AtapiScsiPassThruResetTarget (
   IN UINT32                         Target,\r
   IN UINT64                         Lun\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  CheckSCSIRequestPacket\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 CheckSCSIRequestPacket (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET      *Packet\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  SubmitBlockingIoCommand\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
-;\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
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  IsCommandValid\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
-Returns:\r
-\r
-  TODO: add return values\r
+  @return TODO: add return values\r
 \r
 --*/\r
-;\r
-\r
 BOOLEAN\r
 IsCommandValid (\r
   EFI_SCSI_PASS_THRU_SCSI_REQUEST_PACKET   *Packet\r
   )\r
- /*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  RequestSenseCommand\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
-;\r
-\r
+**/\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
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AtapiPacketCommand\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
-;\r
-\r
+**/\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \r
-  TODO: Add function description\r
 \r
-Arguments:\r
+/**\r
+  ReadPortB\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
-Returns:\r
+  @param  PciIo TODO: add argument description\r
+  @param  Port TODO: add argument description\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \r
-  TODO: Add function description\r
 \r
-Arguments:\r
+/**\r
+  ReadPortW\r
 \r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
+  TODO: Add function 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
-;\r
-\r
-\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
-  TODO: Add function description\r
 \r
-Arguments:\r
+/**\r
+  WritePortB\r
 \r
-  PciIo - TODO: add argument description\r
-  Port  - TODO: add argument description\r
+  TODO: Add function 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
-;\r
-\r
-\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
-  TODO: Add function description\r
 \r
-Arguments:\r
+/**\r
+  WritePortW\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
-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
-;\r
-\r
-\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
-Routine Description:\r
+/**\r
+  StatusDRQClear\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 StatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AltStatusDRQClear\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 AltStatusDRQClear (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  StatusDRQReady\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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 StatusDRQReady (\r
   ATAPI_SCSI_PASS_THRU_DEV        *AtapiScsiPrivate,\r
   UINT64                          TimeOutInMicroSeconds\r
   )\r
-/*++\r
+;\r
 \r
-Routine Description:\r
+/**\r
+  AltStatusDRQReady\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
-;\r
-\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
   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
-;\r
-\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
   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
-;\r
-\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
   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
-;\r
-\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
   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
-;\r
-\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
   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
-;\r
-\r
+**/\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \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
-;\r
-\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
index 14658b0..b0b2231 100644 (file)
@@ -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
-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
-Module Name:\r
+  Module Name:  ComponentName.c\r
 \r
-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r
 #include "AtapiPassThru.h"\r
 \r
 //\r
@@ -39,9 +34,9 @@ AtapiScsiPassThruComponentNameGetControllerName (
   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
@@ -53,6 +48,28 @@ static EFI_UNICODE_STRING_TABLE mAtapiScsiPassThruDriverNameTable[] = {
   { 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
@@ -60,32 +77,6 @@ AtapiScsiPassThruComponentNameGetDriverName (
   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
@@ -95,6 +86,47 @@ AtapiScsiPassThruComponentNameGetDriverName (
           );\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
@@ -104,51 +136,6 @@ AtapiScsiPassThruComponentNameGetControllerName (
   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
index 91d6acc..68c4830 100644 (file)
@@ -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
@@ -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
-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
 // Cirrus Logic 5430 Controller Driver\r
@@ -44,6 +35,13 @@ EFI_DRIVER_BINDING_PROTOCOL gCirrusLogic5430DriverBinding = {
   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
@@ -51,20 +49,6 @@ CirrusLogic5430ControllerDriverSupported (
   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
@@ -139,6 +123,13 @@ Done:
   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
@@ -146,20 +137,6 @@ CirrusLogic5430ControllerDriverStart (
   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
@@ -253,6 +230,15 @@ Error:
   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
@@ -261,22 +247,6 @@ CirrusLogic5430ControllerDriverStop (
   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
index 79ca7e0..b1984c8 100644 (file)
@@ -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
-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
+  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
@@ -99,78 +90,67 @@ extern EFI_COMPONENT_NAME_PROTOCOL  gCirrusLogic5430ComponentName;
 //\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 CirrusLogic5430UgaDrawDestructor (\r
   CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
   )\r
-/*++\r
-\r
-Routine Description:\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
-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
-;\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \r
+//\r
+// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface\r
+//\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
-;\r
-\r
-//\r
-// EFI_DRIVER_BINDING_PROTOCOL Protocol Interface\r
-//\r
+**/\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \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
-;\r
-\r
+**/\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
-/*++\r
-\r
-Routine Description:\r
+;\r
 \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
-;\r
-\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 CirrusLogic5430ControllerDriverStop (\r
@@ -231,24 +198,6 @@ CirrusLogic5430ControllerDriverStop (
   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
index c33918b..60e0582 100644 (file)
@@ -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
---*/\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
-// Video Mode structure\r
-//\r
+///\r
+/// Video Mode structure\r
+///\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
-//\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
-//\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
@@ -97,9 +90,9 @@ static UINT16                         Seq_1024_768_256_60[15] = {
   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
@@ -169,6 +162,20 @@ inw (
 //\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
@@ -178,27 +185,6 @@ CirrusLogic5430UgaDrawGetMode (
   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
@@ -223,6 +209,20 @@ Returns:
   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
@@ -232,27 +232,6 @@ CirrusLogic5430UgaDrawSetMode (
   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
@@ -299,6 +278,29 @@ Returns:
   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
@@ -313,36 +315,6 @@ CirrusLogic5430UgaDrawBlt (
   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
@@ -597,23 +569,16 @@ Returns:
 // 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
-/*++\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
@@ -657,50 +622,36 @@ Returns:
   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
-/*++\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
+  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
-/*++\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
@@ -712,29 +663,22 @@ Returns:
                       );\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
-/*++\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
@@ -746,27 +690,20 @@ Returns:
                       );\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
-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
+**/\r
+UINT8\r
+inb (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
+  UINTN                           Address\r
+  )\r
 {\r
   UINT8 Data;\r
 \r
@@ -781,27 +718,20 @@ Returns:
   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
-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
+**/\r
+UINT16\r
+inw (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private,\r
+  UINTN                           Address\r
+  )\r
 {\r
   UINT16  Data;\r
 \r
@@ -816,6 +746,18 @@ Returns:
   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
@@ -824,25 +766,6 @@ SetPaletteColor (
   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
@@ -850,25 +773,18 @@ Returns:
   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
-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
+**/\r
+VOID\r
+SetDefaultPalette (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r
 {\r
   UINTN Index;\r
   UINTN RedIndex;\r
@@ -886,26 +802,19 @@ Returns:
   }\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
-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
+**/\r
+STATIC\r
+VOID\r
+ClearScreen (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r
 {\r
   UINT32  Color;\r
 \r
@@ -920,25 +829,18 @@ Returns:
                         );\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
-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
+**/\r
+VOID\r
+DrawLogo (\r
+  CIRRUS_LOGIC_5430_PRIVATE_DATA  *Private\r
+  )\r
 {\r
   UINTN Offset;\r
   UINTN X;\r
@@ -968,27 +870,20 @@ Returns:
   }\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
-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
+**/\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
index 5c10b6d..933899f 100644 (file)
@@ -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
-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
-Module Name:\r
-\r
-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r
 \r
 #include "CirrusLogic5430.h"\r
 \r
@@ -59,6 +52,28 @@ static EFI_UNICODE_STRING_TABLE mCirrusLogic5430ControllerNameTable[] = {
   { 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
@@ -66,32 +81,6 @@ CirrusLogic5430ComponentNameGetDriverName (
   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
@@ -101,6 +90,46 @@ CirrusLogic5430ComponentNameGetDriverName (
           );\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
@@ -110,50 +139,6 @@ CirrusLogic5430ComponentNameGetControllerName (
   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
index 240a6b0..edead72 100644 (file)
@@ -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
-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
-Module Name:\r
-\r
-  ComponentName.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r
 \r
 #include "idebus.h"\r
 \r
@@ -38,6 +31,28 @@ STATIC EFI_UNICODE_STRING_TABLE mIDEBusControllerNameTable[] = {
   { 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
@@ -45,32 +60,6 @@ IDEBusComponentNameGetDriverName (
   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
@@ -80,6 +69,47 @@ IDEBusComponentNameGetDriverName (
           );\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
@@ -89,51 +119,6 @@ IDEBusComponentNameGetControllerName (
   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
@@ -188,21 +173,16 @@ IDEBusComponentNameGetControllerName (
           );\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
-/*++\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
index 5a23a43..dfe134a 100644 (file)
@@ -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
-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
-Module Name:\r
-\r
-  DriverConfiguration.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r
 \r
 #include "idebus.h"\r
 \r
@@ -63,27 +56,18 @@ EFI_DRIVER_CONFIGURATION_PROTOCOL gIDEBusDriverConfiguration = {
   "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
-/*++\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
@@ -118,6 +102,51 @@ Returns:
   }\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
@@ -126,55 +155,6 @@ IDEBusDriverConfigurationSetOptions (
   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
@@ -232,49 +212,45 @@ IDEBusDriverConfigurationSetOptions (
   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
-/*++\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
@@ -300,6 +276,51 @@ IDEBusDriverConfigurationOptionsValid (
   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
@@ -308,56 +329,6 @@ IDEBusDriverConfigurationForceDefaults (
   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
index d3f2a8e..c7bd30a 100644 (file)
@@ -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
-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
-Module Name:\r
-\r
-  DriverDiagnostics.c\r
-\r
-Abstract:\r
-\r
---*/\r
+**/\r
 \r
 #include "idebus.h"\r
 \r
@@ -44,6 +37,63 @@ EFI_DRIVER_DIAGNOSTICS_PROTOCOL gIDEBusDriverDiagnostics = {
   "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
@@ -55,67 +105,6 @@ IDEBusDriverDiagnosticsRunDiagnostics (
   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
index 88e81c0..9a1542d 100644 (file)
@@ -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
@@ -68,46 +60,34 @@ AtaPioDataOutExt (
   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
-  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
+  @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
-  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
+  @note\r
+  parameter IdeDev will be updated in this function.\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
@@ -213,42 +193,30 @@ ATAIdentify (
 }\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
-  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
-        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
-  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
-  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
@@ -304,33 +272,19 @@ AtaAtapi6Identify (
   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
-/*++\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
@@ -340,6 +294,44 @@ PrintAtaModuleName (
   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
@@ -352,66 +344,6 @@ AtaPioDataIn (
   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
@@ -529,6 +461,29 @@ AtaPioDataIn (
   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
@@ -541,67 +496,6 @@ AtaPioDataOut (
   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
@@ -718,38 +612,23 @@ AtaPioDataOut (
   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
-/*++\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
@@ -841,6 +720,28 @@ CheckErrorStatus (
 \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
@@ -848,43 +749,6 @@ AtaReadSectors (
   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
@@ -974,6 +838,28 @@ AtaReadSectors (
   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
@@ -981,44 +867,6 @@ AtaWriteSectors (
   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
@@ -1095,41 +943,34 @@ AtaWriteSectors (
   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
-/*++\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
@@ -1165,77 +1006,55 @@ AtaSoftReset (
   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
-  Parameters:\r
-      IDE_BLK_IO_DEV    IN    *IdeBlkIoDevice\r
-        Indicates the calling context.\r
+  @param[in] *IdeBlkIoDevice\r
+  Indicates the calling context.\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
-      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
-      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
-      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
-  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
-      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
-  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
@@ -1315,6 +1134,48 @@ AtaBlkIoReadBlocks (
 \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
@@ -1323,70 +1184,6 @@ AtaBlkIoWriteBlocks (
   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
@@ -1457,6 +1254,24 @@ AtaBlkIoWriteBlocks (
   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
@@ -1464,46 +1279,6 @@ AtaReadSectorsExt (
   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
@@ -1562,6 +1337,29 @@ AtaReadSectorsExt (
   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
@@ -1569,46 +1367,6 @@ AtaWriteSectorsExt (
   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
@@ -1668,6 +1426,32 @@ AtaWriteSectorsExt (
   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
@@ -1677,63 +1461,6 @@ AtaPioDataInExt (
   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
@@ -1864,6 +1591,33 @@ AtaPioDataInExt (
   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
@@ -1873,62 +1627,6 @@ AtaPioDataOutExt (
   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
@@ -2055,31 +1753,18 @@ AtaPioDataOutExt (
 }\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
-/*++\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
@@ -2213,6 +1898,20 @@ AtaSMARTSupport (
   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
@@ -2222,27 +1921,6 @@ AtaCommandIssueExt (
   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
@@ -2332,6 +2010,20 @@ Returns:
   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
@@ -2341,27 +2033,6 @@ AtaCommandIssue (
   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
@@ -2437,6 +2108,29 @@ Returns:
   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
@@ -2444,49 +2138,6 @@ AtaUdmaReadExt (
   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
@@ -2752,6 +2403,28 @@ AtaUdmaReadExt (
   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
@@ -2759,49 +2432,6 @@ AtaUdmaRead (
   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
@@ -3066,6 +2696,28 @@ AtaUdmaRead (
   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
@@ -3073,48 +2725,6 @@ AtaUdmaWriteExt (
   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
@@ -3377,6 +2987,32 @@ AtaUdmaWriteExt (
   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
@@ -3384,48 +3020,6 @@ AtaUdmaWrite (
   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
index fa004e3..7043306 100644 (file)
@@ -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
-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
-Module Name:\r
+**/\r
 \r
-  atapi.c\r
-    \r
-Abstract: \r
-    \r
+#include "idebus.h"\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
-#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
+  @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
-/*++\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
@@ -119,43 +102,31 @@ LS120GetMediaStatus (
   }\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
-/*++\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
@@ -211,60 +182,51 @@ LS120EnableMediaStatus (
   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
-/*++\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
@@ -409,35 +371,28 @@ ATAPIIdentify (
   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
-/*++\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
@@ -476,6 +431,36 @@ AtapiInquiry (
   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
@@ -484,50 +469,6 @@ AtapiPacketCommandIn (
   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
@@ -605,6 +546,36 @@ AtapiPacketCommandIn (
   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
@@ -613,51 +584,6 @@ AtapiPacketCommandOut (
   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
@@ -733,6 +659,38 @@ AtapiPacketCommandOut (
   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
@@ -741,54 +699,6 @@ PioReadWriteData (
   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
@@ -888,36 +798,25 @@ PioReadWriteData (
   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
-/*++\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
@@ -935,50 +834,38 @@ AtapiTestUnitReady (
   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
-        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
-        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
-        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
-  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
-        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
-// 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
@@ -1053,45 +940,36 @@ AtapiRequestSense (
   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
-/*++\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
@@ -1207,48 +1085,39 @@ AtapiReadCapacity (
   }\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
+