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 <[email protected]>

Author: nordic-krch

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,20 +904,24 @@ 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)
 {
 #ifdef CONFIG_UART_INTERRUPT_DRIVEN
 	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);