From 581c20e24222a2f79edcd897e7cc03c612981398 Mon Sep 17 00:00:00 2001 From: Krzysztof Chruscinski Date: Mon, 27 Sep 2021 13:28:40 +0200 Subject: [PATCH] drivers: uart: Cleanup not supported API handling Fixed discrepancy between documentation and actual returned error code when API is not enabled or not supported by a device. Added detection of case when device does not implement uart_callback_set but ASYNC api is enabled. Returning -ENOSYS in that case. Signed-off-by: Krzysztof Chruscinski --- include/drivers/uart.h | 90 ++++++++++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 26 deletions(-) diff --git a/include/drivers/uart.h b/include/drivers/uart.h index bea7c9296b5a23..4418f6761623a5 100644 --- a/include/drivers/uart.h +++ b/include/drivers/uart.h @@ -447,11 +447,16 @@ __subsystem struct uart_driver_api { /** * @brief Set event handler function. * + * Since it is mandatory to set callback to use other asynchronous functions, + * it can be used to detect if the device supports asynchronous API. Remaining + * API does not have that detection. + * * @param dev UART device structure. * @param callback Event handler. * @param user_data Data to pass to event handler function. * - * @retval -ENOTSUP If not supported. + * @retval -ENOSYS If not supported by the device. + * @retval -ENOTSUP If API not enabled. * @retval 0 If successful, negative errno code otherwise. */ static inline int uart_callback_set(const struct device *dev, @@ -462,6 +467,10 @@ static inline int uart_callback_set(const struct device *dev, const struct uart_driver_api *api = (const struct uart_driver_api *)dev->api; + if (api->callback_set == NULL) { + return -ENOSYS; + } + return api->callback_set(dev, callback, user_data); #else return -ENOTSUP; @@ -637,6 +646,7 @@ static inline int z_impl_uart_rx_disable(const struct device *dev) * * @retval uart_rx_stop_reason If error during receiving occurred. * @retval 0 Otherwise. + * @retval -ENOSYS If this function is not supported. */ __syscall int uart_err_check(const struct device *dev); @@ -648,6 +658,7 @@ static inline int z_impl_uart_err_check(const struct device *dev) if (api->err_check == NULL) { return -ENOSYS; } + return api->err_check(dev); } @@ -661,7 +672,7 @@ static inline int z_impl_uart_err_check(const struct device *dev) * @retval 0 If a character arrived. * @retval -1 If no character was available to read (i.e., the UART * input buffer was empty). - * @retval -ENOTSUP If the operation is not supported. + * @retval -ENOSYS If the operation is not supported. * @retval -EBUSY If reception was enabled using uart_rx_enabled */ __syscall int uart_poll_in(const struct device *dev, unsigned char *p_char); @@ -672,6 +683,10 @@ static inline int z_impl_uart_poll_in(const struct device *dev, const struct uart_driver_api *api = (const struct uart_driver_api *)dev->api; + if (api->poll_in == NULL) { + return -ENOSYS; + } + return api->poll_in(dev, p_char); } @@ -737,7 +752,7 @@ static inline int z_impl_uart_configure(const struct device *dev, * @param dev UART device structure. * @param cfg UART configuration structure. * - * @retval -ENOTSUP If driver does not support getting current configuration. + * @retval -ENOSYS If driver does not support getting current configuration. * @retval 0 If successful, negative errno code otherwise. */ __syscall int uart_config_get(const struct device *dev, @@ -754,7 +769,6 @@ static inline int z_impl_uart_config_get(const struct device *dev, } return api->config_get(dev, cfg); - } /** @@ -774,6 +788,8 @@ static inline int z_impl_uart_config_get(const struct device *dev, * @param size Number of bytes to send. * * @return Number of bytes sent. + * @retval -ENOSYS if this function is not supported + * @retval -ENOTSUP if API is not enabled. */ static inline int uart_fifo_fill(const struct device *dev, const uint8_t *tx_data, @@ -783,12 +799,14 @@ static inline int uart_fifo_fill(const struct device *dev, const struct uart_driver_api *api = (const struct uart_driver_api *)dev->api; - if (api->fifo_fill != NULL) { - return api->fifo_fill(dev, tx_data, size); + if (api->fifo_fill == NULL) { + return -ENOSYS; } + + return api->fifo_fill(dev, tx_data, size); #endif - return 0; + return -ENOTSUP; } /** @@ -812,6 +830,8 @@ static inline int uart_fifo_fill(const struct device *dev, * @param size Container size. * * @return Number of bytes read. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. */ static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data, const int size) @@ -820,12 +840,14 @@ static inline int uart_fifo_read(const struct device *dev, uint8_t *rx_data, const struct uart_driver_api *api = (const struct uart_driver_api *)dev->api; - if (api->fifo_read != NULL) { - return api->fifo_read(dev, rx_data, size); + if (api->fifo_read == NULL) { + return -ENOSYS; } + + return api->fifo_read(dev, rx_data, size); #endif - return 0; + return -ENOTSUP; } /** @@ -882,7 +904,9 @@ static inline void z_impl_uart_irq_tx_disable(const struct device *dev) * @param dev UART device structure. * * @retval 1 If at least one char can be written to UART. - * @retval 0 Otherwise. + * @retval 0 If device is not ready to write a new byte. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. */ static inline int uart_irq_tx_ready(const struct device *dev) { @@ -890,12 +914,14 @@ static inline int uart_irq_tx_ready(const struct device *dev) const struct uart_driver_api *api = (const struct uart_driver_api *)dev->api; - if (api->irq_tx_ready != NULL) { - return api->irq_tx_ready(dev); + if (api->irq_tx_ready == NULL) { + return -ENOSYS; } + + return api->irq_tx_ready(dev); #endif - return 0; + return -ENOTSUP; } /** @@ -955,8 +981,9 @@ static inline void z_impl_uart_irq_rx_disable(const struct device *dev) * @param dev UART device structure. * * @retval 1 If nothing remains to be transmitted. - * @retval 0 Otherwise. - * @retval -ENOTSUP if this function is not supported + * @retval 0 If transmission is not completed. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. */ static inline int uart_irq_tx_complete(const struct device *dev) { @@ -990,8 +1017,9 @@ static inline int uart_irq_tx_complete(const struct device *dev) * @param dev UART device structure. * * @retval 1 If a received char is ready. - * @retval 0 Otherwise. - * @retval -ENOTSUP if this function is not supported + * @retval 0 If a received char is not ready. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. */ static inline int uart_irq_rx_ready(const struct device *dev) { @@ -1005,7 +1033,7 @@ static inline int uart_irq_rx_ready(const struct device *dev) return api->irq_rx_ready(dev); #endif - return 0; + return -ENOTSUP; } /** * @brief Enable error interrupt. @@ -1056,7 +1084,9 @@ static inline void z_impl_uart_irq_err_disable(const struct device *dev) * @param dev UART device structure. * * @retval 1 If an IRQ is pending. - * @retval 0 Otherwise. + * @retval 0 If an IRQ is not pending. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. */ __syscall int uart_irq_is_pending(const struct device *dev); @@ -1071,7 +1101,7 @@ static inline int z_impl_uart_irq_is_pending(const struct device *dev) } return api->irq_is_pending(dev); #endif - return 0; + return -ENOTSUP; } /** @@ -1095,7 +1125,9 @@ static inline int z_impl_uart_irq_is_pending(const struct device *dev) * * @param dev UART device structure. * - * @retval 1 Always. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. + * @retval 1 On success. */ __syscall int uart_irq_update(const struct device *dev); @@ -1110,7 +1142,7 @@ static inline int z_impl_uart_irq_update(const struct device *dev) } return api->irq_update(dev); #endif - return 0; + return -ENOTSUP; } /** @@ -1166,7 +1198,9 @@ static inline void uart_irq_callback_set(const struct device *dev, * @param val Value to set to the line control. * * @retval 0 If successful. - * @retval failed Otherwise. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. + * @retval negative value if failed. */ __syscall int uart_line_ctrl_set(const struct device *dev, uint32_t ctrl, uint32_t val); @@ -1195,7 +1229,9 @@ static inline int z_impl_uart_line_ctrl_set(const struct device *dev, * @param val Pointer to variable where to store the line control value. * * @retval 0 If successful. - * @retval failed Otherwise. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. + * @retval negative value if failed. */ __syscall int uart_line_ctrl_get(const struct device *dev, uint32_t ctrl, uint32_t *val); @@ -1227,7 +1263,9 @@ static inline int z_impl_uart_line_ctrl_get(const struct device *dev, * @param p Parameter to the command. * * @retval 0 If successful. - * @retval failed Otherwise. + * @retval -ENOSYS if this function is not supported. + * @retval -ENOTSUP if API is not enabled. + * @retval negative value if failed. */ __syscall int uart_drv_cmd(const struct device *dev, uint32_t cmd, uint32_t p);