Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2023 Fabian Blatz
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Backend API for emulated UART
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_DRIVERS_SERIAL_UART_EMUL_H_
      13             : #define ZEPHYR_INCLUDE_DRIVERS_SERIAL_UART_EMUL_H_
      14             : 
      15             : #include <zephyr/device.h>
      16             : #include <zephyr/types.h>
      17             : 
      18             : #ifdef __cplusplus
      19             : extern "C" {
      20             : #endif
      21             : 
      22             : /**
      23             :  * @brief Define the application callback function signature for
      24             :  * uart_emul_callback_tx_data_ready_set() function.
      25             :  *
      26             :  * @param dev UART device instance
      27             :  * @param size Number of available bytes in TX buffer
      28             :  * @param user_data Arbitrary user data
      29             :  */
      30           1 : typedef void (*uart_emul_callback_tx_data_ready_t)(const struct device *dev, size_t size,
      31             :                                                    void *user_data);
      32             : 
      33             : /**
      34             :  * @brief Set the TX data ready callback
      35             :  *
      36             :  * This sets up the callback that is called every time data
      37             :  * was appended to the TX buffer.
      38             :  *
      39             :  * @param dev The emulated UART device instance
      40             :  * @param cb Pointer to the callback function
      41             :  * @param user_data Data to pass to callback function
      42             :  */
      43           1 : void uart_emul_callback_tx_data_ready_set(const struct device *dev,
      44             :                                           uart_emul_callback_tx_data_ready_t cb, void *user_data);
      45             : 
      46             : /**
      47             :  * @brief Write (copy) data to RX buffer
      48             :  *
      49             :  * @param dev The emulated UART device instance
      50             :  * @param data The data to append
      51             :  * @param size Number of bytes to append
      52             :  *
      53             :  * @return Number of bytes appended
      54             :  */
      55           1 : uint32_t uart_emul_put_rx_data(const struct device *dev, const uint8_t *data, size_t size);
      56             : 
      57             : /**
      58             :  * @brief Read data from TX buffer
      59             :  *
      60             :  * @param dev The emulated UART device instance
      61             :  * @param data The address of the output buffer
      62             :  * @param size Number of bytes to read
      63             :  *
      64             :  * @return Number of bytes written to the output buffer
      65             :  */
      66           1 : uint32_t uart_emul_get_tx_data(const struct device *dev, uint8_t *data, size_t size);
      67             : 
      68             : /**
      69             :  * @brief Clear RX buffer content
      70             :  *
      71             :  * @param dev The emulated UART device instance
      72             :  *
      73             :  * @return Number of cleared bytes
      74             :  */
      75           1 : uint32_t uart_emul_flush_rx_data(const struct device *dev);
      76             : 
      77             : /**
      78             :  * @brief Clear TX buffer content
      79             :  *
      80             :  * @param dev The emulated UART device instance
      81             :  *
      82             :  * @return Number of cleared bytes
      83             :  */
      84           1 : uint32_t uart_emul_flush_tx_data(const struct device *dev);
      85             : 
      86             : /**
      87             :  * @brief Sets one or more driver errors
      88             :  *
      89             :  * @param dev The emulated UART device instance
      90             :  * @param errors The @ref uart_rx_stop_reason errors to set
      91             :  */
      92           1 : void uart_emul_set_errors(const struct device *dev, int errors);
      93             : 
      94             : /**
      95             :  * @brief Configures if rx buffer should be released on timeout, even when only partially filled.
      96             :  *
      97             :  * @param dev The emulated UART device instance
      98             :  * @param release_on_timeout When true, buffer will be released on timeout
      99             :  */
     100           1 : void uart_emul_set_release_buffer_on_timeout(const struct device *dev, bool release_on_timeout);
     101             : 
     102             : #ifdef __cplusplus
     103             : }
     104             : #endif
     105             : 
     106             : #endif /* ZEPHYR_INCLUDE_DRIVERS_SERIAL_UART_EMUL_H_ */