EmbeddedPkg: Clarify the declaration of SerialPortGetControl()

Rework the PL011UartGetControl() function removing a TODO by the way.
Update of the header comment blocks of (PL011Uart|SerialPort)GetControl() functions.

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@16252 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c b/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
index a40e269d07e3106a13278fcf8b231f9c4a986156..7e74a05df7fcdea37621da6a56f8a6b7caa8ba55 100644 (file)
--- a/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
+++ b/ArmPlatformPkg/Drivers/PL011Uart/PL011Uart.c
@@ -236,20 +236,39 @@ PL011UartSetControl (
 }\r
 \r
 /**\r
-  Get the serial device control bits.\r
 \r
-  @param  UartBase                The base address of the PL011 UART.\r
-  @param  Control                 Control signals read from the serial device.\r
-\r
-  @retval EFI_SUCCESS             The control bits were read from the serial device.\r
-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.\r
+  Retrieve the status of the control bits on a serial device.\r
+\r
+  @param[in]   UartBase  UART registers base address\r
+  @param[out]  Control   Status of the control bits on a serial device :\r
+\r
+                         . EFI_SERIAL_DATA_CLEAR_TO_SEND, EFI_SERIAL_DATA_SET_READY,\r
+                           EFI_SERIAL_RING_INDICATE, EFI_SERIAL_CARRIER_DETECT,\r
+                           EFI_SERIAL_REQUEST_TO_SEND, EFI_SERIAL_DATA_TERMINAL_READY\r
+                           are all related to the DTE (Data Terminal Equipment) and\r
+                           DCE (Data Communication Equipment) modes of operation of\r
+                           the serial device.\r
+                         . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the receive\r
+                           buffer is empty, 0 otherwise.\r
+                         . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the transmit\r
+                           buffer is empty, 0 otherwise.\r
+                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if the\r
+                           hardware loopback is enabled (the ouput feeds the receive\r
+                           buffer), 0 otherwise.\r
+                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if a\r
+                           loopback is accomplished by software, 0 otherwise.\r
+                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to one if the\r
+                           hardware flow control based on CTS (Clear To Send) and RTS\r
+                           (Ready To Send) control signals is enabled, 0 otherwise.\r
+\r
+  @retval RETURN_SUCCESS  The control bits were read from the serial device.\r
 \r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
 PL011UartGetControl (\r
-    IN UINTN                    UartBase,\r
-    OUT UINT32                  *Control\r
+    IN UINTN     UartBase,\r
+    OUT UINT32  *Control\r
   )\r
 {\r
   UINT32      FlagRegister;\r
@@ -293,22 +312,15 @@ PL011UartGetControl (
     *Control |= EFI_SERIAL_OUTPUT_BUFFER_EMPTY;\r
   }\r
 \r
-  if ((ControlRegister & (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN)) == (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN)) {\r
+  if ((ControlRegister & (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN))\r
+       == (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN)) {\r
     *Control |= EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE;\r
   }\r
 \r
-#ifdef NEVER\r
-  // ToDo: Implement EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE\r
   if ((ControlRegister & PL011_UARTCR_LBE) == PL011_UARTCR_LBE) {\r
     *Control |= EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE;\r
   }\r
 \r
-  // ToDo: Implement EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE\r
-  if (SoftwareLoopbackEnable) {\r
-    *Control |= EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE;\r
-  }\r
-#endif\r
-\r
   return RETURN_SUCCESS;\r
 }\r
 \r

diff --git a/ArmPlatformPkg/Include/Drivers/PL011Uart.h b/ArmPlatformPkg/Include/Drivers/PL011Uart.h
index f8e4a083aa1701f1311866d1fdb633fa40f14adf..6675cefeb38a3e652266ae85436706be22955260 100644 (file)
--- a/ArmPlatformPkg/Include/Drivers/PL011Uart.h
+++ b/ArmPlatformPkg/Include/Drivers/PL011Uart.h
@@ -134,20 +134,40 @@ PL011UartSetControl (
   );\r
 \r
 /**\r
-  Get the serial device control bits.\r
 \r
-  @param  UartBase                The base address of the PL011 UART.\r
-  @param  Control                 Control signals read from the serial device.\r
-\r
-  @retval EFI_SUCCESS             The control bits were read from the serial device.\r
-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.\r
+  Retrieve the status of the control bits on a serial device.\r
+\r
+  @param[in]   UartBase  UART registers base address\r
+  @param[out]  Control   Status of the control bits on a serial device :\r
+\r
+                         . EFI_SERIAL_DATA_CLEAR_TO_SEND, EFI_SERIAL_DATA_SET_READY,\r
+                           EFI_SERIAL_RING_INDICATE, EFI_SERIAL_CARRIER_DETECT,\r
+                           EFI_SERIAL_REQUEST_TO_SEND, EFI_SERIAL_DATA_TERMINAL_READY\r
+                           are all related to the DTE (Data Terminal Equipment) and\r
+                           DCE (Data Communication Equipment) modes of operation of\r
+                           the serial device.\r
+                         . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the receive\r
+                           buffer is empty, 0 otherwise.\r
+                         . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the transmit\r
+                           buffer is empty, 0 otherwise.\r
+                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if the\r
+                           hardware loopback is enabled (the ouput feeds the receive\r
+                           buffer), 0 otherwise.\r
+                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if a\r
+                           loopback is accomplished by software, 0 otherwise.\r
+                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to one if the\r
+                           hardware flow control based on CTS (Clear To Send) and RTS\r
+                           (Ready To Send) control signals is enabled, 0 otherwise.\r
+\r
+\r
+  @retval RETURN_SUCCESS  The control bits were read from the serial device.\r
 \r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
 PL011UartGetControl (\r
-    IN UINTN                    UartBase,\r
-    OUT UINT32                  *Control\r
+  IN UINTN     UartBase,\r
+  OUT UINT32  *Control\r
   );\r
 \r
 /**\r

diff --git a/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c b/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
index 7b3cd89298d8e6ddfee1b353d0ee464e90bb4d52..44fe78f4f46b1933fc1a88f8e8d14cee246a07c0 100644 (file)
--- a/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
+++ b/ArmPlatformPkg/Library/PL011SerialPortLib/PL011SerialPortExtLib.c
@@ -100,20 +100,38 @@ SerialPortSetControl (
 }\r
 \r
 /**\r
-  Get the serial device control bits.\r
 \r
-  @param  Control                 Control signals read from the serial device.\r
-\r
-  @retval EFI_SUCCESS             The control bits were read from the serial device.\r
-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.\r
+  Retrieve the status of the control bits on a serial device.\r
+\r
+  @param[out]  Control  Status of the control bits on a serial device :\r
+\r
+                        . EFI_SERIAL_DATA_CLEAR_TO_SEND, EFI_SERIAL_DATA_SET_READY,\r
+                          EFI_SERIAL_RING_INDICATE, EFI_SERIAL_CARRIER_DETECT,\r
+                          EFI_SERIAL_REQUEST_TO_SEND, EFI_SERIAL_DATA_TERMINAL_READY\r
+                          are all related to the DTE (Data Terminal Equipment) and\r
+                          DCE (Data Communication Equipment) modes of operation of\r
+                          the serial device.\r
+                        . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the receive\r
+                          buffer is empty, 0 otherwise.\r
+                        . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the transmit\r
+                          buffer is empty, 0 otherwise.\r
+                        . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if the\r
+                          hardware loopback is enabled (the ouput feeds the receive\r
+                          buffer), 0 otherwise.\r
+                        . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if a\r
+                          loopback is accomplished by software, 0 otherwise.\r
+                        . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to one if the\r
+                          hardware flow control based on CTS (Clear To Send) and RTS\r
+                          (Ready To Send) control signals is enabled, 0 otherwise.\r
+\r
+  @retval RETURN_SUCCESS  The control bits were read from the serial device.\r
 \r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
 SerialPortGetControl (\r
-  OUT UINT32                  *Control\r
+  OUT UINT32  *Control\r
   )\r
 {\r
   return PL011UartGetControl ((UINTN)PcdGet64 (PcdSerialRegisterBase), Control);\r
 }\r
-\r

diff --git a/EmbeddedPkg/Include/Library/SerialPortExtLib.h b/EmbeddedPkg/Include/Library/SerialPortExtLib.h
index 28705f0f20d8db483b5c9d01a44da1f79040bf8e..0d0abb35ff54320a9c95e08f92be1bb3f58e4b09 100644 (file)
--- a/EmbeddedPkg/Include/Library/SerialPortExtLib.h
+++ b/EmbeddedPkg/Include/Library/SerialPortExtLib.h
@@ -61,18 +61,38 @@ SerialPortSetControl (
   );\r
 \r
 /**\r
-  Get the serial device control bits.\r
 \r
-  @param  Control                 Control signals read from the serial device.\r
-\r
-  @retval EFI_SUCCESS             The control bits were read from the serial device.\r
-  @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.\r
+  Retrieve the status of the control bits on a serial device.\r
+\r
+  @param[out]  Control  Status of the control bits on a serial device :\r
+\r
+                        . EFI_SERIAL_DATA_CLEAR_TO_SEND, EFI_SERIAL_DATA_SET_READY,\r
+                          EFI_SERIAL_RING_INDICATE, EFI_SERIAL_CARRIER_DETECT,\r
+                          EFI_SERIAL_REQUEST_TO_SEND, EFI_SERIAL_DATA_TERMINAL_READY\r
+                          are all related to the DTE (Data Terminal Equipment) and\r
+                          DCE (Data Communication Equipment) modes of operation of\r
+                          the serial device.\r
+                        . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the receive\r
+                          buffer is empty, 0 otherwise.\r
+                        . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the transmit\r
+                          buffer is empty, 0 otherwise.\r
+                        . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if the\r
+                          hardware loopback is enabled (the ouput feeds the receive\r
+                          buffer), 0 otherwise.\r
+                        . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if a\r
+                          loopback is accomplished by software, 0 otherwise.\r
+                        . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to one if the\r
+                          hardware flow control based on CTS (Clear To Send) and RTS\r
+                          (Ready To Send) control signals is enabled, 0 otherwise.\r
+\r
+  @retval RETURN_SUCCESS       The control bits were read from the serial device.\r
+  @retval RETURN_DEVICE_ERROR  The serial device is not functioning correctly.\r
 \r
 **/\r
 RETURN_STATUS\r
 EFIAPI\r
 SerialPortGetControl (\r
-  OUT UINT32                  *Control\r
+  OUT UINT32  *Control\r
   );\r
 \r
 /**\r

diff --git a/EmbeddedPkg/Library/TemplateSerialPortExtLib/TemplateSerialPortExtLib.c b/EmbeddedPkg/Library/TemplateSerialPortExtLib/TemplateSerialPortExtLib.c
index 2c2b4382d22b6bcbf0cd21fb48d25da2f7cad009..f0f8465cb6d43e0be1bded008bc47c46de41c7c2 100644 (file)
--- a/EmbeddedPkg/Library/TemplateSerialPortExtLib/TemplateSerialPortExtLib.c
+++ b/EmbeddedPkg/Library/TemplateSerialPortExtLib/TemplateSerialPortExtLib.c
@@ -36,7 +36,7 @@ SerialPortSetControl (
 /**\r
   Get the serial device control bits.\r
 \r
-  @param  Control                 Control signals read from the serial device.\r
+  @param  Control  Control signals read from the serial device.\r
 \r
   @retval EFI_SUCCESS             The control bits were read from the serial device.\r
   @retval EFI_DEVICE_ERROR        The serial device is not functioning correctly.\r
@@ -45,7 +45,7 @@ SerialPortSetControl (
 RETURN_STATUS\r
 EFIAPI\r
 SerialPortGetControl (\r
-  OUT UINT32                  *Control\r
+  OUT UINT32  *Control\r
   )\r
 {\r
   if (SerialPortPoll ()) {\r
@@ -54,7 +54,7 @@ SerialPortGetControl (
   } else {\r
     *Control = EFI_SERIAL_INPUT_BUFFER_EMPTY | EFI_SERIAL_OUTPUT_BUFFER_EMPTY;\r
   }\r
-  return EFI_SUCCESS;\r
+  return RETURN_SUCCESS;\r
 }\r
 \r
 /**\r