ECC clean up for DebugPort Module.

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

2 files changed, 266 insertions, 194 deletions

diff --git a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.c b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.c
index e5844dc9fa..b91003f212 100644
--- a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.c
+++ b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.c
@@ -15,30 +15,34 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 **/

 

-

 #include "DebugPort.h"

 

 //

-// Misc. functions local to this module..

+// Globals

 //

-VOID

-GetDebugPortVariable (

-  DEBUGPORT_DEVICE            *DebugPortDevice

-  )

-/*++

-

-Routine Description:

-  Local worker function to obtain device path information from DebugPort variable.

-  Records requested settings in DebugPort device structure.

+EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding = {

+  DebugPortSupported,

+  DebugPortStart,

+  DebugPortStop,

+  DEBUGPORT_DRIVER_VERSION,

+  NULL,

+  NULL

+};

 

-Arguments:

-  DEBUGPORT_DEVICE  *DebugPortDevice,

+DEBUGPORT_DEVICE  *gDebugPortDevice;

 

-Returns:

+/**

+  Local worker function to obtain device path information from DebugPort variable.

 

-  Nothing

+  Records requested settings in DebugPort device structure.

+  

+  @param  DebugPortDevice    Pointer to instance of dubug port device.

 

---*/

+**/

+VOID

+GetDebugPortVariable (

+  DEBUGPORT_DEVICE            *DebugPortDevice

+  )

 {

   UINTN                     DataSize;

   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;

@@ -69,7 +73,7 @@ Returns:
             DebugPortDevice->DebugPortVariable

             );

       DevicePath = (EFI_DEVICE_PATH_PROTOCOL *) DebugPortDevice->DebugPortVariable;

-      while (!EfiIsDevicePathEnd (DevicePath) && !EfiIsUartDevicePath (DevicePath)) {

+      while (!EfiIsDevicePathEnd (DevicePath) && !IS_UART_DEVICEPATH (DevicePath)) {

         DevicePath = EfiNextDevicePathNode (DevicePath);

       }

 

@@ -104,50 +108,32 @@ Returns:
   }

 }

 

+

 //

-// Globals

+// implementation code

 //

 

-EFI_DRIVER_BINDING_PROTOCOL gDebugPortDriverBinding = {

-  DebugPortSupported,

-  DebugPortStart,

-  DebugPortStop,

-  DEBUGPORT_DRIVER_VERSION,

-  NULL,

-  NULL

-};

+/**

+  Debug Port Driver entry pointo. 

 

-DEBUGPORT_DEVICE  *gDebugPortDevice;

+  Reads DebugPort variable to determine what device and settings to use as the

+  debug port.  Binds exclusively to SerialIo. Reverts to defaults if no variable

+  is found.

 

-//

-// implementation code

-//

+  @param[in] ImageHandle       The firmware allocated handle for the EFI image.  

+  @param[in] SystemTable       A pointer to the EFI System Table.

+  

+  @retval EFI_SUCCESS          The entry point is executed successfully.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval other                Some error occurs when executing this entry point.

 

+**/

 EFI_STATUS

 EFIAPI

 InitializeDebugPortDriver (

   IN EFI_HANDLE             ImageHandle,

   IN EFI_SYSTEM_TABLE       *SystemTable

   )

-/*++

-

-Routine Description:

-  Driver entry point.  Reads DebugPort variable to determine what device and settings

-  to use as the debug port.  Binds exclusively to SerialIo. Reverts to defaults \

-  if no variable is found.

-

-  Creates debugport and devicepath protocols on new handle.

-

-Arguments:

-  ImageHandle,

-  SystemTable

-

-Returns:

-

-  EFI_UNSUPPORTED

-  EFI_OUT_OF_RESOURCES

-

---*/

 {

   EFI_STATUS    Status;

 

@@ -189,42 +175,35 @@ Returns:
 

   return EFI_SUCCESS;

 }

-//

-// DebugPort driver binding member functions...

-//

-EFI_STATUS

-EFIAPI

-DebugPortSupported (

-  IN EFI_DRIVER_BINDING_PROTOCOL    *This,

-  IN EFI_HANDLE                     ControllerHandle,

-  IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

-  )

-/*++

 

-Routine Description:

-  Checks to see that there's not already a DebugPort interface somewhere.  If so,

-  fail.

+/**

+  Checks to see if there's not already a DebugPort interface somewhere. 

 

   If there's a DEBUGPORT variable, the device path must match exactly.  If there's

   no DEBUGPORT variable, then device path is not checked and does not matter.

-

   Checks to see that there's a serial io interface on the controller handle

   that can be bound BY_DRIVER | EXCLUSIVE.

-

   If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED

   or other error returned by OpenProtocol.

 

-Arguments:

-  This

-  ControllerHandle

-  RemainingDevicePath

+  @param  This                 Protocol instance pointer.

+  @param  ControllerHandle     Handle of device to test.

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

+                               device to start.

 

-Returns:

-  EFI_UNSUPPORTED

-  EFI_OUT_OF_RESOURCES

-  EFI_SUCCESS

+  @retval EFI_SUCCESS          This driver supports this device.

+  @retval EFI_UNSUPPORTED      Debug Port device is not supported.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval others               Some error occurs.

 

---*/

+**/

+EFI_STATUS

+EFIAPI

+DebugPortSupported (

+  IN EFI_DRIVER_BINDING_PROTOCOL    *This,

+  IN EFI_HANDLE                     ControllerHandle,

+  IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

+  )

 {

   EFI_STATUS                Status;

   EFI_DEVICE_PATH_PROTOCOL  *Dp1;

@@ -304,6 +283,20 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  Binds exclusively to serial io on the controller handle, Produces DebugPort

+  protocol and DevicePath on new handle.

+

+  @param  This                 Protocol instance pointer.

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

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

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval others               Some error occurs.                

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortStart (

@@ -311,21 +304,6 @@ DebugPortStart (
   IN EFI_HANDLE                     ControllerHandle,

   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   )

-/*++

-

-Routine Description:

-  Binds exclusively to serial io on the controller handle.  Produces DebugPort

-  protocol and DevicePath on new handle.

-

-Arguments:

-  This

-  ControllerHandle

-  RemainingDevicePath

-

-Returns:

-  EFI_OUT_OF_RESOURCES

-  EFI_SUCCESS

---*/

 {

   EFI_STATUS                Status;

   DEBUGPORT_DEVICE_PATH     DebugPortDP;

@@ -474,6 +452,20 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  Stop this driver on ControllerHandle by removing Serial IO protocol on

+  the ControllerHandle.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

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

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle.

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

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortStop (

@@ -482,20 +474,6 @@ DebugPortStop (
   IN  UINTN                          NumberOfChildren,

   IN  EFI_HANDLE                     *ChildHandleBuffer

   )

-/*++

-

-Routine Description:

-  We're never intending to be stopped via the driver model so this just returns

-  EFI_UNSUPPORTED

-

-Arguments:

-  Per UEFI 2.0 driver model

-

-Returns:

-  EFI_UNSUPPORTED

-  EFI_SUCCESS

-

---*/

 {

   EFI_STATUS  Status;

 

@@ -564,17 +542,8 @@ Returns:
 

   return Status;

 }

-//

-// Debugport protocol member functions

-//

-EFI_STATUS

-EFIAPI

-DebugPortReset (

-  IN EFI_DEBUGPORT_PROTOCOL   *This

-  )

-/*++

 

-Routine Description:

+/**

   DebugPort protocol member function.  Calls SerialIo:GetControl to flush buffer.

   We cannot call SerialIo:SetAttributes because it uses pool services, which use

   locks, which affect TPL, so it's not interrupt context safe or re-entrant.

@@ -582,14 +551,16 @@ Routine Description:
 

   The port itself should be fine since it was set up during initialization.

 

-Arguments:

-  This

-

-Returns:

+  @param  This              Protocol instance pointer.   

 

-  EFI_SUCCESS

+  @return EFI_SUCCESS       Always.

 

---*/

+**/  

+EFI_STATUS

+EFIAPI

+DebugPortReset (

+  IN EFI_DEBUGPORT_PROTOCOL   *This

+  )

 {

   UINTN             BufferSize;

   UINTN             BitBucket;

@@ -602,6 +573,20 @@ Returns:
   return EFI_SUCCESS;

 }

 

+/**

+  DebugPort protocol member function.  Calls SerialIo:Read() after setting

+  if it's different than the last SerialIo access.

+

+  @param  This                Pointer to DebugPort protocol.

+  @param  Timeout             Timeout value.

+  @param  BufferSize          On input, the size of Buffer.

+                              On output, the amount of data actually written.

+  @param  Buffer              Pointer to buffer to read.

+

+  @retval EFI_SUCCESS         

+  @retval others              

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortRead (

@@ -610,23 +595,6 @@ DebugPortRead (
   IN OUT UINTN                *BufferSize,

   IN VOID                     *Buffer

   )

-/*++

-

-Routine Description:

-  DebugPort protocol member function.  Calls SerialIo:Read() after setting

-  if it's different than the last SerialIo access.

-

-Arguments:

-  IN EFI_DEBUGPORT_PROTOCOL   *This

-  IN UINT32                   Timeout,

-  IN OUT UINTN                *BufferSize,

-  IN VOID                     *Buffer

-

-Returns:

-

-  EFI_STATUS

-

---*/

 {

   DEBUGPORT_DEVICE  *DebugPortDevice;

   UINTN             LocalBufferSize;

@@ -661,6 +629,21 @@ Returns:
   return Status;

 }

 

+/**

+  DebugPort protocol member function.  Calls SerialIo:Write() Writes 8 bytes at

+  a time and does a GetControl between 8 byte writes to help insure reads are

+  interspersed This is poor-man's flow control.

+

+  @param  This                Pointer to DebugPort protocol.

+  @param  Timeout             Timeout value.

+  @param  BufferSize          On input, the size of Buffer.

+                              On output, the amount of data actually written.

+  @param  Buffer              Pointer to buffer to read.

+

+  @retval EFI_SUCCESS         The data was written.

+  @retval others              Fails when writting datas to debug port device.

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortWrite (

@@ -669,26 +652,6 @@ DebugPortWrite (
   IN OUT UINTN                *BufferSize,

   OUT VOID                    *Buffer

   )

-/*++

-

-Routine Description:

-  DebugPort protocol member function.  Calls SerialIo:Write() Writes 8 bytes at

-  a time and does a GetControl between 8 byte writes to help insure reads are

-  interspersed This is poor-man's flow control..

-

-Arguments:

-  This               - Pointer to DebugPort protocol

-  Timeout            - Timeout value

-  BufferSize         - On input, the size of Buffer.

-                       On output, the amount of data actually written.

-  Buffer             - Pointer to buffer to write

-

-Returns:

-  EFI_SUCCESS        - The data was written.

-  EFI_DEVICE_ERROR   - The device reported an error.

-  EFI_TIMEOUT        - The data write was stopped due to a timeout.

-

---*/

 {

   DEBUGPORT_DEVICE  *DebugPortDevice;

   UINTN             Position;

@@ -720,26 +683,24 @@ Returns:
   return Status;

 }

 

-EFI_STATUS

-EFIAPI

-DebugPortPoll (

-  IN EFI_DEBUGPORT_PROTOCOL   *This

-  )

-/*++

-

-Routine Description:

+/**

   DebugPort protocol member function.  Calls SerialIo:Write() after setting

   if it's different than the last SerialIo access.

 

-Arguments:

-  IN EFI_DEBUGPORT_PROTOCOL   *This

+  @param  This                Pointer to DebugPort protocol.

 

-Returns:

-  EFI_SUCCESS - At least 1 character is ready to be read from the DebugPort interface

-  EFI_NOT_READY - There are no characters ready to read from the DebugPort interface

-  EFI_DEVICE_ERROR - A hardware failure occured... (from SerialIo)

+  @retval EFI_SUCCESS         At least 1 character is ready to be read from

+                              the DebugPort interface.

+  @retval EFI_NOT_READY       There are no characters ready to read from the

+                              DebugPort interface

+  @retval EFI_DEVICE_ERROR    A hardware failure occured... (from SerialIo)

 

---*/

+**/   

+EFI_STATUS

+EFIAPI

+DebugPortPoll (

+  IN EFI_DEBUGPORT_PROTOCOL   *This

+  )

 {

   EFI_STATUS        Status;

   UINT32            SerialControl;

@@ -753,7 +714,7 @@ Returns:
                                               );

 

   if (!EFI_ERROR (Status)) {

-    if (SerialControl & EFI_SERIAL_INPUT_BUFFER_EMPTY) {

+    if ((SerialControl & EFI_SERIAL_INPUT_BUFFER_EMPTY) != 0) {

       Status = EFI_NOT_READY;

     } else {

       Status = EFI_SUCCESS;

@@ -763,26 +724,23 @@ Returns:
   return Status;

 }

 

-EFI_STATUS

-EFIAPI

-ImageUnloadHandler (

-  EFI_HANDLE ImageHandle

-  )

-/*++

-

-Routine Description:

+/**

   Unload function that is registered in the LoadImage protocol.  It un-installs

   protocols produced and deallocates pool used by the driver.  Called by the core

   when unloading the driver.

 

-Arguments:

-  EFI_HANDLE ImageHandle

-

-Returns:

+  @param  ImageHandle

 

-  EFI_SUCCESS

+  @retval EFI_SUCCESS     Unload Debug Port driver successfully.

+  @retval EFI_ABORTED     Serial IO is still binding.

+  @retval others          Fails to unload Debug Port driver.

 

---*/

+**/

+EFI_STATUS

+EFIAPI

+ImageUnloadHandler (

+  EFI_HANDLE ImageHandle

+  )

 {

   EFI_STATUS  Status;

 

diff --git a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h
index 535bddde13..852cae9481 100644
--- a/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h
+++ b/MdeModulePkg/Universal/DebugPortDxe/DebugPort.h
@@ -83,22 +83,56 @@ typedef struct {
 

 #define DEBUGPORT_DRIVER_VERSION          1

 

-#define EfiIsUartDevicePath(dp)           (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)

+#define IS_UART_DEVICEPATH(dp)           (DevicePathType (dp) == MESSAGING_DEVICE_PATH && DevicePathSubType (dp) == MSG_UART_DP)

 

 //

 // globals

 //

 extern DEBUGPORT_DEVICE  *gDebugPortDevice;

 

-//

-// Driver binding interface functions...

-//

+/**

+  Debug Port Driver entry pointo. 

+

+  Reads DebugPort variable to determine what device and settings to use as the

+  debug port.  Binds exclusively to SerialIo. Reverts to defaults if no variable

+  is found.

+

+  @param[in] ImageHandle       The firmware allocated handle for the EFI image.  

+  @param[in] SystemTable       A pointer to the EFI System Table.

+  

+  @retval EFI_SUCCESS          The entry point is executed successfully.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval other                Some error occurs when executing this entry point.

+

+**/

 EFI_STATUS

-DebugPortEntryPoint (

+EFIAPI

+InitializeDebugPortDriver (

   IN EFI_HANDLE                     ImageHandle,

   IN EFI_SYSTEM_TABLE               *SystemTable

   );

 

+/**

+  Checks to see if there's not already a DebugPort interface somewhere. 

+

+  If there's a DEBUGPORT variable, the device path must match exactly.  If there's

+  no DEBUGPORT variable, then device path is not checked and does not matter.

+  Checks to see that there's a serial io interface on the controller handle

+  that can be bound BY_DRIVER | EXCLUSIVE.

+  If all these tests succeed, then we return EFI_SUCCESS, else, EFI_UNSUPPORTED

+  or other error returned by OpenProtocol.

+

+  @param  This                 Protocol instance pointer.

+  @param  ControllerHandle     Handle of device to test.

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

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver supports this device.

+  @retval EFI_UNSUPPORTED      Debug Port device is not supported.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval others               Some error occurs.

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortSupported (

@@ -107,6 +141,20 @@ DebugPortSupported (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Binds exclusively to serial io on the controller handle, Produces DebugPort

+  protocol and DevicePath on new handle.

+

+  @param  This                 Protocol instance pointer.

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

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

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle.

+  @retval EFI_OUT_OF_RESOURCES Fails to allocate memory for device.

+  @retval others               Some error occurs.                

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortStart (

@@ -115,6 +163,20 @@ DebugPortStart (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Stop this driver on ControllerHandle by removing Serial IO protocol on

+  the ControllerHandle.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

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

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle.

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

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortStop (

@@ -254,15 +316,39 @@ DebugPortComponentNameGetControllerName (
   );

 

 

-//

-// DebugPort member functions

-//

+/**

+  DebugPort protocol member function.  Calls SerialIo:GetControl to flush buffer.

+  We cannot call SerialIo:SetAttributes because it uses pool services, which use

+  locks, which affect TPL, so it's not interrupt context safe or re-entrant.

+  SerialIo:Reset() calls SetAttributes, so it can't be used either.

+

+  The port itself should be fine since it was set up during initialization.

+

+  @param  This              Protocol instance pointer.   

+

+  @return EFI_SUCCESS       Always.

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortReset (

   IN EFI_DEBUGPORT_PROTOCOL         *This

   );

 

+/**

+  DebugPort protocol member function.  Calls SerialIo:Read() after setting

+  if it's different than the last SerialIo access.

+

+  @param  This                Pointer to DebugPort protocol.

+  @param  Timeout             Timeout value.

+  @param  BufferSize          On input, the size of Buffer.

+                              On output, the amount of data actually written.

+  @param  Buffer              Pointer to buffer to read.

+

+  @retval EFI_SUCCESS         

+  @retval others              

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortRead (

@@ -272,6 +358,21 @@ DebugPortRead (
   IN VOID                           *Buffer

   );

 

+/**

+  DebugPort protocol member function.  Calls SerialIo:Write() Writes 8 bytes at

+  a time and does a GetControl between 8 byte writes to help insure reads are

+  interspersed This is poor-man's flow control.

+

+  @param  This                Pointer to DebugPort protocol.

+  @param  Timeout             Timeout value.

+  @param  BufferSize          On input, the size of Buffer.

+                              On output, the amount of data actually written.

+  @param  Buffer              Pointer to buffer to read.

+

+  @retval EFI_SUCCESS         The data was written.

+  @retval others              Fails when writting datas to debug port device.

+

+**/

 EFI_STATUS

 EFIAPI

 DebugPortWrite (

@@ -281,6 +382,19 @@ DebugPortWrite (
   OUT VOID                          *Buffer

   );

 

+/**

+  DebugPort protocol member function.  Calls SerialIo:Write() after setting

+  if it's different than the last SerialIo access.

+

+  @param  This                Pointer to DebugPort protocol.

+

+  @retval EFI_SUCCESS         At least 1 character is ready to be read from

+                              the DebugPort interface.

+  @retval EFI_NOT_READY       There are no characters ready to read from the

+                              DebugPort interface

+  @retval EFI_DEVICE_ERROR    A hardware failure occured... (from SerialIo)

+

+**/ 

 EFI_STATUS

 EFIAPI

 DebugPortPoll (