EmbeddedPkg: Clarify the declaration of SerialPortSetControl()

Rework of PL011UartSetControl() as a consequence as well as update of
function header comment blocks.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
Reviewed-By: Olivier Martin <olivier.martin@arm.com>



git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@16251 6f19259b-4bc3-4df7-8a09-765794883524

3 files changed, 95 insertions, 41 deletions

diff --git a/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c b/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
index fd686799b2..a40e269d07 100644
--- a/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
+++ b/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
@@ -2,7 +2,7 @@
   Serial I/O Port library functions with no library constructor/destructor

 

   Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>

-  Copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR>

+  Copyright (c) 2011 - 2014, ARM Ltd. All rights reserved.<BR>

 

   This program and the accompanying materials

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

@@ -20,6 +20,12 @@
 

 #include <Drivers/PL011Uart.h>

 

+//

+// EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE is the only

+// control bit that is not supported.

+//

+STATIC CONST UINT32 mInvalidControlBits = EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE;

+

 /*

 

   Initialise the serial port to the specified settings.

@@ -159,53 +165,69 @@ PL011UartInitializePort (
 }

 

 /**

-  Set the serial device control bits.

 

-  @param  UartBase                The base address of the PL011 UART.

-  @param  Control                 Control bits which are to be set on the serial device.

-

-  @retval EFI_SUCCESS             The new control bits were set on the serial device.

-  @retval EFI_UNSUPPORTED         The serial device does not support this operation.

-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.

+  Assert or deassert the control signals on a serial port.

+  The following control signals are set according their bit settings :

+  . Request to Send

+  . Data Terminal Ready

+

+  @param[in]  UartBase  UART registers base address

+  @param[in]  Control   The following bits are taken into account :

+                        . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the

+                          "Request To Send" control signal if this bit is

+                          equal to one/zero.

+                        . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert

+                          the "Data Terminal Ready" control signal if this

+                          bit is equal to one/zero.

+                        . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable

+                          the hardware loopback if this bit is equal to

+                          one/zero.

+                        . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.

+                        . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/

+                          disable the hardware flow control based on CTS (Clear

+                          To Send) and RTS (Ready To Send) control signals.

+

+  @retval  RETURN_SUCCESS      The new control bits were set on the serial device.

+  @retval  RETURN_UNSUPPORTED  The serial device does not support this operation.

 

 **/

 RETURN_STATUS

 EFIAPI

 PL011UartSetControl (

-    IN UINTN                    UartBase,

-    IN UINT32                   Control

+    IN UINTN   UartBase,

+    IN UINT32  Control

   )

 {

-  UINT32      Bits;

-  UINT32      ValidControlBits;

-

-  ValidControlBits = (  EFI_SERIAL_REQUEST_TO_SEND

-                      | EFI_SERIAL_DATA_TERMINAL_READY

-  //                  | EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE       // Not implemented yet.

-  //                  | EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE       // Not implemented yet.

-                      | EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE

-                     );

-

-  if (Control & (~ValidControlBits)) {

-    return EFI_UNSUPPORTED;

+  UINT32  Bits;

+

+  if (Control & (mInvalidControlBits)) {

+    return RETURN_UNSUPPORTED;

   }

 

   Bits = MmioRead32 (UartBase + UARTCR);

 

   if (Control & EFI_SERIAL_REQUEST_TO_SEND) {

     Bits |= PL011_UARTCR_RTS;

+  } else {

+    Bits &= ~PL011_UARTCR_RTS;

   }

 

   if (Control & EFI_SERIAL_DATA_TERMINAL_READY) {

     Bits |= PL011_UARTCR_DTR;

+  } else {

+    Bits &= ~PL011_UARTCR_DTR;

   }

 

   if (Control & EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE) {

     Bits |= PL011_UARTCR_LBE;

+  } else {

+    Bits &= ~PL011_UARTCR_LBE;

   }

 

   if (Control & EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE) {

-    Bits |= (PL011_UARTCR_CTSEN & PL011_UARTCR_RTSEN);

+    Bits |= (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);

+  } else {

+    Bits &= ~(PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);

   }

 

   MmioWrite32 (UartBase + UARTCR, Bits);

diff --git a/ArmPlatformPkg/Include/Drivers/PL011Uart.h b/ArmPlatformPkg/Include/Drivers/PL011Uart.h
index a36347e529..f8e4a083aa 100644
--- a/ArmPlatformPkg/Include/Drivers/PL011Uart.h
+++ b/ArmPlatformPkg/Include/Drivers/PL011Uart.h
@@ -1,6 +1,6 @@
 /** @file

 *

-*  Copyright (c) 2011-2012, ARM Limited. All rights reserved.

+*  Copyright (c) 2011-2014, ARM Limited. All rights reserved.

 *

 *  This program and the accompanying materials

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

@@ -100,21 +100,37 @@ PL011UartInitializePort (
   );

 

 /**

-  Set the serial device control bits.

 

-  @param  UartBase                The base address of the PL011 UART.

-  @param  Control                 Control bits which are to be set on the serial device.

-

-  @retval EFI_SUCCESS             The new control bits were set on the serial device.

-  @retval EFI_UNSUPPORTED         The serial device does not support this operation.

-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.

+  Assert or deassert the control signals on a serial port.

+  The following control signals are set according their bit settings :

+  . Request to Send

+  . Data Terminal Ready

+

+  @param[in]  UartBase  UART registers base address

+  @param[in]  Control   The following bits are taken into account :

+                        . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the

+                          "Request To Send" control signal if this bit is

+                          equal to one/zero.

+                        . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert

+                          the "Data Terminal Ready" control signal if this

+                          bit is equal to one/zero.

+                        . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable

+                          the hardware loopback if this bit is equal to

+                          one/zero.

+                        . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.

+                        . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/

+                          disable the hardware flow control based on CTS (Clear

+                          To Send) and RTS (Ready To Send) control signals.

+

+  @retval  RETURN_SUCCESS      The new control bits were set on the serial device.

+  @retval  RETURN_UNSUPPORTED  The serial device does not support this operation.

 

 **/

 RETURN_STATUS

 EFIAPI

 PL011UartSetControl (

-    IN UINTN                    UartBase,

-    IN UINT32                   Control

+  IN UINTN   UartBase,

+  IN UINT32  Control

   );

 

 /**

diff --git a/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c b/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
index 723a1b1624..7b3cd89298 100644
--- a/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
+++ b/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
@@ -1,7 +1,7 @@
 /** @file

   Serial I/O Port library functions with no library constructor/destructor

 

-  Copyright (c) 2012-2013, ARM Ltd. All rights reserved.<BR>

+  Copyright (c) 2012-2014, ARM Ltd. All rights reserved.<BR>

 

   This program and the accompanying materials

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

@@ -65,19 +65,35 @@ SerialPortSetAttributes (
 }

 

 /**

-  Set the serial device control bits.

 

-  @param  Control                 Control bits which are to be set on the serial device.

-

-  @retval EFI_SUCCESS             The new control bits were set on the serial device.

-  @retval EFI_UNSUPPORTED         The serial device does not support this operation.

-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.

+  Assert or deassert the control signals on a serial port.

+  The following control signals are set according their bit settings :

+  . Request to Send

+  . Data Terminal Ready

+

+  @param[in]  Control  The following bits are taken into account :

+                       . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the

+                         "Request To Send" control signal if this bit is

+                         equal to one/zero.

+                       . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert

+                         the "Data Terminal Ready" control signal if this

+                         bit is equal to one/zero.

+                       . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable

+                         the hardware loopback if this bit is equal to

+                         one/zero.

+                       . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.

+                       . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/

+                         disable the hardware flow control based on CTS (Clear

+                         To Send) and RTS (Ready To Send) control signals.

+

+  @retval  RETURN_SUCCESS      The new control bits were set on the serial device.

+  @retval  RETURN_UNSUPPORTED  The serial device does not support this operation.

 

 **/

 RETURN_STATUS

 EFIAPI

 SerialPortSetControl (

-  IN UINT32                  Control

+  IN UINT32  Control

   )

 {

   return PL011UartSetControl ((UINTN)PcdGet64 (PcdSerialRegisterBase), Control);