From: jino.cho Date: Fri, 12 May 2017 06:34:54 +0000 (+0900) Subject: Add description for uart APIs X-Git-Tag: accepted/tizen/unified/20170602.054034~29 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=86db2fdda86f5c20bd043892e0dc3571c95738f4;p=platform%2Fcore%2Fapi%2Fperipheral-io.git Add description for uart APIs This patch Adds description for uart APIs and modify uart handle. Change-Id: I0f5387ab0441cf822cfdc792ce4da28dfef86de4 Signed-off-by: jino.cho --- diff --git a/include/peripheral_internal.h b/include/peripheral_internal.h index 338f75e..290fb28 100644 --- a/include/peripheral_internal.h +++ b/include/peripheral_internal.h @@ -33,4 +33,11 @@ struct _peripheral_i2c_s { uint handle; }; +/** + * @brief Internal struct for uart context + */ +struct _peripheral_uart_s { + uint handle; +}; + #endif /* __PERIPHERAL_INTERNAL_H__ */ diff --git a/include/peripheral_io.h b/include/peripheral_io.h index 6c62c1f..568c7a3 100644 --- a/include/peripheral_io.h +++ b/include/peripheral_io.h @@ -439,34 +439,195 @@ int peripheral_adc_close(peripheral_adc_context_h dev); * @addtogroup CAPI_SYSTEM_PERIPHERAL_UART_MODULE * @{ */ -struct _peripheral_uart_s { - int fd; -}; +/** + * @brief The handle to the uart device + * @since_tizen 4.0 + */ +typedef struct _peripheral_uart_s *peripheral_uart_h; -typedef struct _peripheral_uart_s* peripheral_uart_context_h; +/** + * @brief Enumeration for Baud Rate. + */ +typedef enum { + PERIPHERAL_UART_BAUDRATE_0 = 0, + PERIPHERAL_UART_BAUDRATE_50, + PERIPHERAL_UART_BAUDRATE_75, + PERIPHERAL_UART_BAUDRATE_110, + PERIPHERAL_UART_BAUDRATE_134, + PERIPHERAL_UART_BAUDRATE_150, + PERIPHERAL_UART_BAUDRATE_200, + PERIPHERAL_UART_BAUDRATE_300, + PERIPHERAL_UART_BAUDRATE_600, + PERIPHERAL_UART_BAUDRATE_1200, + PERIPHERAL_UART_BAUDRATE_1800, + PERIPHERAL_UART_BAUDRATE_2400, + PERIPHERAL_UART_BAUDRATE_4800, + PERIPHERAL_UART_BAUDRATE_9600, + PERIPHERAL_UART_BAUDRATE_19200, + PERIPHERAL_UART_BAUDRATE_38400, + PERIPHERAL_UART_BAUDRATE_57600, + PERIPHERAL_UART_BAUDRATE_115200, + PERIPHERAL_UART_BAUDRATE_230400 +} peripheral_uart_baudrate_e; + +/** + * @brief Enumeration for Byte Size. + */ +typedef enum { + PERIPHERAL_UART_BYTESIZE_5BIT = 0, + PERIPHERAL_UART_BYTESIZE_6BIT, + PERIPHERAL_UART_BYTESIZE_7BIT, + PERIPHERAL_UART_BYTESIZE_8BIT +} peripheral_uart_bytesize_e; +/** + * @brief Enumeration for Parity Bit. + */ typedef enum { PERIPHERAL_UART_PARITY_NONE = 0, PERIPHERAL_UART_PARITY_EVEN, - PERIPHERAL_UART_PARITY_ODD, + PERIPHERAL_UART_PARITY_ODD } peripheral_uart_parity_e; -peripheral_uart_context_h peripheral_uart_init(const char *path); +/** + * @brief Enumeration for Stop Bits. + */ +typedef enum { + PERIPHERAL_UART_STOPBITS_1BIT = 0, + PERIPHERAL_UART_STOPBITS_2BIT +} peripheral_uart_stopbits_e; -int peripheral_uart_stop(peripheral_uart_context_h hnd); +/** + * @brief Initializes uart communication and creates uart handle. + * @since_tizen 4.0 + * + * @param[in] port The uart port number that the slave device is connected + * @param[out] uart The uart handle is created on success + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_uart_close() + */ +int peripheral_uart_open(int port, peripheral_uart_h *uart); -int peripheral_uart_flush(peripheral_uart_context_h hnd); +/** + * @brief Destory the uart handle and release the communication. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_uart_open() + */ +int peripheral_uart_close(peripheral_uart_h uart); -int peripheral_uart_set_baudrate(peripheral_uart_context_h hnd, unsigned int baud); +/** + * @brief Flush all input that has received but not yet been read by the uart + * device, or all output written but not transmitted to the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The uart handle + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + */ +int peripheral_uart_flush(peripheral_uart_h uart); -int peripheral_uart_set_mode(peripheral_uart_context_h hnd, int bytesize, peripheral_uart_parity_e parity, int stopbits); +/** + * @brief Sets baudrate of the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device to set + * @param[in] baud Baudrate of the uart device + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + */ +int peripheral_uart_set_baudrate(peripheral_uart_h uart, peripheral_uart_baudrate_e baud); -int peripheral_uart_set_flowcontrol(peripheral_uart_context_h hnd, int xonxoff, int rtscts); +/** + * @brief Sets mode of the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device to set + * @param[in] bytesize Byte size of the uart device + * @param[in] parity Parity bits of the uart device + * @param[in] stopbits Stop bits of the uart device + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + */ +int peripheral_uart_set_mode(peripheral_uart_h uart, peripheral_uart_bytesize_e bytesize, peripheral_uart_parity_e parity, peripheral_uart_stopbits_e stopbits); -int peripheral_uart_read(peripheral_uart_context_h hnd, char *buf, unsigned int length); +/** + * @brief Sets flow control of the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device to set + * @param[in] xonxoff Turns a transmitter on or off + * @param[in] rtscts Turns "Request to Send/Clear to Send" on or off + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + */ +int peripheral_uart_set_flowcontrol(peripheral_uart_h uart, bool xonxoff, bool rtscts); + +/** + * @brief Reads data from the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device + * @param[out] data The address of read buffer + * @param[out] length The size of data buffer (in bytes) + * + * @return the number of bytes read on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + */ +int peripheral_uart_read(peripheral_uart_h uart, char *data, int length); -int peripheral_uart_write(peripheral_uart_context_h hnd, const char *buf, unsigned int length); +/** + * @brief Write data to the uart device. + * @since_tizen 4.0 + * + * @param[in] uart The handle to the uart device + * @param[in] data The address of buffer to write + * @param[in] length The size of data (in bytes) + * + * @return the number of bytes write on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + */ +int peripheral_uart_write(peripheral_uart_h uart, const char *data, int length); /** * @}