michaelh/zephyr
1
0
Fork 0
Code Releases Activity

drivers: uart: Cleanup not supported API handling

Browse source 
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 <krzysztof.chruscinski@nordicsemi.no>
This commit is contained in:
Krzysztof Chruscinski 2021-09-27 13:28:40 +02:00 • committed by Anas Nashif
commit 581c20e242
1 changed files with 64 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

90
include/drivers/uart.h
View file

@ -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);