From d69107aadc8f3d9fd186544b17e02603e3fd5627 Mon Sep 17 00:00:00 2001 From: eric_tian Date: Tue, 7 Oct 2008 09:01:12 +0000 Subject: 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 --- MdePkg/Include/Library/SerialPortLib.h | 42 ++++++++++++++-------- .../Library/SerialPortLibNull/SerialPortLibNull.c | 40 ++++++++++++++------- 2 files changed, 56 insertions(+), 26 deletions(-) (limited to 'MdePkg') 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 /** - 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 -- cgit v1.2.3