Second set of changes based on a review of the code comments in the Include directory...

[mirror_edk2.git] / MdePkg / Include / Library / SerialPortLib.h

diff --git a/MdePkg/Include/Library/SerialPortLib.h b/MdePkg/Include/Library/SerialPortLib.h
index 73a89389e437f9c7597d3112dbba1caa00752359..60d32122976b7ce8fc15af91bc235b5da8fc9c2e 100644 (file)
--- a/MdePkg/Include/Library/SerialPortLib.h
+++ b/MdePkg/Include/Library/SerialPortLib.h
@@ -1,17 +1,14 @@
-\r
 /** @file\r
-  Serial I/O Port library functions with no library constructor/destructor\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
+  This library class provides common serial I/O port functions.\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
+Copyright (c) 2006 - 2008, 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
-  Module Name:  SerialPortLib.h\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
 **/\r
 \r
@@ -19,10 +16,14 @@
 #define __SERIAL_PORT_LIB__\r
 \r
 /**\r
-\r
-  Programmed hardware of Serial port.\r
-\r
-  @return  Status of Serial Port Device initialization.\r
+  Initialize the serial device hardware.\r
+  \r
+  If no initialization is required, then return RETURN_SUCCESS.\r
+  If the serial device was successfully initialized, then return RETURN_SUCCESS.\r
+  If the serial device could not be initialized, then return RETURN_DEVICE_ERROR.\r
+  \r
+  @retval RETURN_SUCCESS        The serial device was initialized.\r
+  @retval RETURN_DEVICE_ERROR   The serial device could not be initialized.\r
 \r
 **/\r
 RETURN_STATUS\r
@@ -32,45 +33,68 @@ SerialPortInitialize (
   );\r
 \r
 /**\r
-  Write data to serial device. \r
+  Write data from buffer to serial device. \r
  \r
-  If the buffer is NULL, then return 0; \r
-  if NumberOfBytes is zero, then return 0. \r
+  Writes NumberOfBytes data bytes from Buffer to the serial device.  \r
+  The number of bytes actually written to the serial device is returned.\r
+  If the return value is less than NumberOfBytes, then the write operation failed.\r
+  If Buffer is NULL, then ASSERT(). \r
+  If NumberOfBytes is zero, then return 0.\r
 \r
-  @param  Buffer           Point of data buffer which need to be writed.\r
-  @param  NumberOfBytes    Number of output bytes which are cached in Buffer.\r
+  @param  Buffer           Pointer to the data buffer to be written.\r
+  @param  NumberOfBytes    Number of bytes to written to the serial device.\r
 \r
-  @retval 0                Write data failed.\r
-  @retval !0               Actual number of bytes writed to serial device.\r
+  @retval 0                NumberOfBytes is 0.\r
+  @retval >0               The number of bytes written to the serial device.  \r
+                           If this value is less than NumberOfBytes, then the read operation failed.\r
 \r
 **/\r
 UINTN\r
 EFIAPI\r
 SerialPortWrite (\r
-  IN UINT8        *Buffer,\r
-  IN UINTN        NumberOfBytes\r
+  IN UINT8     *Buffer,\r
+  IN UINTN     NumberOfBytes\r
   );\r
 \r
 \r
 /**\r
   Read data from serial device and save the datas in buffer.\r
  \r
-  If the buffer is NULL, then return zero;\r
-  if NumberOfBytes is zero, then return zero.\r
+  Reads NumberOfBytes data bytes from a serial device into the buffer\r
+  specified by Buffer. The number of bytes actually read is returned. \r
+  If the return value is less than NumberOfBytes, then the rest operation failed.\r
+  If Buffer is NULL, then ASSERT(). \r
+  If NumberOfBytes is zero, then return 0.\r
 \r
-  @param  Buffer           Point of data buffer which need to be writed.\r
-  @param  NumberOfBytes    Number of output bytes which are cached in Buffer.\r
+  @param  Buffer           Pointer to the data buffer to store the data read from the serial device.\r
+  @param  NumberOfBytes    Number of bytes which will be read.\r
 \r
-  @retval 0                Read data failed.\r
-  @retval !0               Aactual number of bytes read from serial device.\r
+  @retval 0                Read data failed, no data is to be read.\r
+  @retval >0               Actual number of bytes read from serial device.\r
 \r
 **/\r
 UINTN\r
 EFIAPI\r
 SerialPortRead (\r
-  OUT UINT8    *Buffer,\r
-  IN  UINTN    NumberOfBytes\r
+  OUT UINT8   *Buffer,\r
+  IN  UINTN   NumberOfBytes\r
   );\r
 \r
+/**\r
+  Polls a serial device to see if there is any data waiting to be read.\r
+\r
+  Polls a serial device to see if there is any data waiting to be read.\r
+  If there is data waiting to be read from the serial device, then TRUE is returned.\r
+  If there is no data waiting to be read from the serial device, then FALSE is returned.\r
+\r
+  @retval TRUE             Data is waiting to be read from the serial device.\r
+  @retval FALSE            There is no data waiting to be read from the serial device.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+SerialPortPoll (\r
+  VOID\r
+  );\r
 \r
 #endif\r