Line data    Source code

       1           0 : /*
       2             :  * Copyright 2022 The ChromiumOS Authors.
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_DRIVERS_UART_SERIAL_TEST_H_
       8             : #define ZEPHYR_INCLUDE_DRIVERS_UART_SERIAL_TEST_H_
       9             : 
      10             : #include <errno.h>
      11             : 
      12             : #include <zephyr/device.h>
      13             : 
      14             : #ifdef __cplusplus
      15             : extern "C" {
      16             : #endif /* __cplusplus */
      17             : 
      18             : /**
      19             :  * @brief Queues data to be read by the virtual serial port.
      20             :  *
      21             :  * @warning
      22             :  * Use cases involving multiple writers virtual serial port must prevent
      23             :  * concurrent write operations, either by preventing all writers from
      24             :  * being preempted or by using a mutex to govern writes.
      25             :  *
      26             :  * @param dev Address of virtual serial port.
      27             :  * @param data Address of data.
      28             :  * @param size Data size (in bytes).
      29             :  *
      30             :  * @retval Number of bytes written.
      31             :  */
      32           1 : int serial_vnd_queue_in_data(const struct device *dev, const unsigned char *data, uint32_t size);
      33             : 
      34             : /**
      35             :  * @brief Returns size of unread written data.
      36             :  *
      37             :  * @param dev Address of virtual serial port.
      38             :  *
      39             :  * @return Output data size (in bytes).
      40             :  */
      41           1 : uint32_t serial_vnd_out_data_size_get(const struct device *dev);
      42             : 
      43             : /**
      44             :  * @brief Read data written to virtual serial port.
      45             :  *
      46             :  * Consumes the data, such that future calls to serial_vnd_read_out_data() will
      47             :  * not include this data. Requires CONFIG_RING_BUFFER.
      48             :  *
      49             :  * @warning
      50             :  * Use cases involving multiple reads of the data must prevent
      51             :  * concurrent read operations, either by preventing all readers from
      52             :  * being preempted or by using a mutex to govern reads.
      53             :  *
      54             :  *
      55             :  * @param dev Address of virtual serial port.
      56             :  * @param data Address of the output buffer. Can be NULL to discard data.
      57             :  * @param size Data size (in bytes).
      58             :  *
      59             :  * @retval Number of bytes written to the output buffer.
      60             :  */
      61           1 : uint32_t serial_vnd_read_out_data(const struct device *dev, unsigned char *data, uint32_t size);
      62             : 
      63             : /**
      64             :  * @brief Peek at data written to virtual serial port.
      65             :  *
      66             :  * Reads the data without consuming it. Future calls to serial_vnd_peek_out_data() or
      67             :  * serial_vnd_read_out_data() will return this data again.  Requires CONFIG_RING_BUFFER.
      68             :  *
      69             :  * @warning
      70             :  * Use cases involving multiple reads of the data must prevent
      71             :  * concurrent read operations, either by preventing all readers from
      72             :  * being preempted or by using a mutex to govern reads.
      73             :  *
      74             :  *
      75             :  * @param dev Address of virtual serial port.
      76             :  * @param data Address of the output buffer. Cannot be NULL.
      77             :  * @param size Data size (in bytes).
      78             :  *
      79             :  * @retval Number of bytes written to the output buffer.
      80             :  */
      81           1 : uint32_t serial_vnd_peek_out_data(const struct device *dev, unsigned char *data, uint32_t size);
      82             : 
      83             : /**
      84             :  * @brief Callback called after bytes written to the virtual serial port.
      85             :  *
      86             :  * @param dev Address of virtual serial port.
      87             :  * @param user_data User data.
      88             :  */
      89           1 : typedef void (*serial_vnd_write_cb_t)(const struct device *dev, void *user_data);
      90             : 
      91             : /**
      92             :  * @brief Sets the write callback on a virtual serial port.
      93             :  *
      94             :  * @param dev Address of virtual serial port.
      95             :  * @param callback Function to call after each write to the port.
      96             :  * @param user_data Opaque data to pass to the callback.
      97             :  *
      98             :  */
      99           1 : void serial_vnd_set_callback(const struct device *dev, serial_vnd_write_cb_t callback,
     100             :                              void *user_data);
     101             : 
     102             : #ifdef __cplusplus
     103             : }
     104             : #endif /* __cplusplus */
     105             : 
     106             : #endif /* ZEPHYR_INCLUDE_DRIVERS_UART_SERIAL_TEST_H_ */