sync the comments of serialportlib library class with Mde Library Spec.

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

2 files changed, 56 insertions, 26 deletions

diff --git a/MdePkg/Include/Library/SerialPortLib.h b/MdePkg/Include/Library/SerialPortLib.h
index 59c5c27e3f..d6eb376ff6 100644
--- a/MdePkg/Include/Library/SerialPortLib.h
+++ b/MdePkg/Include/Library/SerialPortLib.h
@@ -16,10 +16,14 @@
 #define __SERIAL_PORT_LIB__

 

 /**

-

-  Programmed hardware of Serial port.

-

-  @return  Status of Serial Port Device initialization.

+  Initialize the serial device hardware.

+  

+  If no initialization is required, then return RETURN_SUCCESS.

+  If the serial device was successfuly initialized, then return RETURN_SUCCESS.

+  If the serial device could not be initialized, then return RETURN_DEVICE_ERROR.

+  

+  @retval RETURN_SUCCESS        The serial device was initialized.

+  @retval RETURN_DEVICE_ERROR   The serail device could not be initialized.

 

 **/

 RETURN_STATUS

@@ -31,14 +35,20 @@ SerialPortInitialize (
 /**

   Write data from buffer to serial device. 

  

-  If the Buffer is NULL, then return 0; 

-  if NumberOfBytes is zero, then return 0. 

+  Writes NumberOfBytes data bytes from Buffer to the serial device.  

+  The number of bytes actually written to the serial device is returned.

+  If the return value is less than NumberOfBytes, then the write operation failed.

+

+  If Buffer is NULL, then ASSERT(). 

 

-  @param  Buffer           Point of data buffer which need to be writed.

-  @param  NumberOfBytes    Number of output bytes which are cached in Buffer.

+  If NumberOfBytes is zero, then return 0.

 

-  @retval 0                Write data failed, or No data is to be written.

-  @retval !0               Actual number of bytes writed to serial device.

+  @param  Buffer           Pointer to the data buffer to be written.

+  @param  NumberOfBytes    Number of bytes to written to the serial device.

+

+  @retval 0                NumberOfBytes is 0.

+  @retval >0               The number of bytes written to the serial device.  

+                           If this value is less than NumberOfBytes, then the read operation failed.

 

 **/

 UINTN

@@ -52,11 +62,15 @@ SerialPortWrite (
 /**

   Read data from serial device and save the datas in buffer.

  

-  If the Buffer is NULL, then return zero;

-  if NumberOfBytes is zero, then return zero.

+  Reads NumberOfBytes data bytes from a serial device into the buffer

+  specified by Buffer. The number of bytes actually read is returned. 

+  If the return value is less than NumberOfBytes, then the rest operation failed.

+

+  If Buffer is NULL, then ASSERT(). 

+

+  If NumberOfBytes is zero, then return 0.

 

-  @param  Buffer           Point of data buffer, which contains the data 

-                           returned from the serial device.

+  @param  Buffer           Pointer to the data buffer to store the data read from the serial device.

   @param  NumberOfBytes    Number of bytes which will be read.

 

   @retval 0                Read data failed, No data is to be read.

diff --git a/MdePkg/Library/SerialPortLibNull/SerialPortLibNull.c b/MdePkg/Library/SerialPortLibNull/SerialPortLibNull.c
index 79b4e925ed..e6b3c63365 100644
--- a/MdePkg/Library/SerialPortLibNull/SerialPortLibNull.c
+++ b/MdePkg/Library/SerialPortLibNull/SerialPortLibNull.c
@@ -19,9 +19,14 @@
 #include <Library/SerialPortLib.h>

 

 /**

-  Programmed hardware of Serial port.

-

-  @return    Always return RETURN_UNSUPPORTED.

+  Initialize the serial device hardware.

+  

+  If no initialization is required, then return RETURN_SUCCESS.

+  If the serial device was successfuly initialized, then return RETURN_SUCCESS.

+  If the serial device could not be initialized, then return RETURN_DEVICE_ERROR.

+  

+  @retval RETURN_SUCCESS        The serial device was initialized.

+  @retval RETURN_DEVICE_ERROR   The serail device could not be initialized.

 

 **/

 RETURN_STATUS

@@ -34,12 +39,22 @@ SerialPortInitialize (
 }

 

 /**

-  Write data to serial device.

+  Write data from buffer to serial device. 

+ 

+  Writes NumberOfBytes data bytes from Buffer to the serial device.  

+  The number of bytes actually written to the serial device is returned.

+  If the return value is less than NumberOfBytes, then the write operation failed.

+

+  If Buffer is NULL, then ASSERT(). 

+

+  If NumberOfBytes is zero, then return 0.

 

-  @param  Buffer           Point of data buffer which need to be writed.

-  @param  NumberOfBytes    Number of output bytes which are cached in Buffer.

+  @param  Buffer           Pointer to the data buffer to be written.

+  @param  NumberOfBytes    Number of bytes to written to the serial device.

 

-  @retval 0                No data is to be written.

+  @retval 0                NumberOfBytes is 0.

+  @retval >0               The number of bytes written to the serial device.  

+                           If this value is less than NumberOfBytes, then the read operation failed.

 

 **/

 UINTN

@@ -54,13 +69,14 @@ SerialPortWrite (
 

 

 /**

-  Read data from serial device and save the datas in buffer.

+  Reads data from a serial device into a buffer.

 

-  @param  Buffer           Point of data buffer, which contains the data

-                           returned from the serial device.

-  @param  NumberOfBytes    Number of bytes which will be read.

+  @param  Buffer           Pointer to the data buffer to store the data read from the serial device.

+  @param  NumberOfBytes    Number of bytes to read from the serial device.

 

-  @retval 0                No data is to be read.

+  @retval 0                NumberOfBytes is 0.

+  @retval >0               The number of bytes read from the serial device.  

+                           If this value is less than NumberOfBytes, then the read operation failed.

 

 **/

 UINTN