1 /*
2 * Copyright (c) 2018 Linaro Limited
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_INCLUDE_CONSOLE_TTY_H_
8 #define ZEPHYR_INCLUDE_CONSOLE_TTY_H_
9
10 #include <sys/types.h>
11 #include <zephyr/types.h>
12 #include <zephyr/kernel.h>
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 struct tty_serial {
19 const struct device *uart_dev;
20
21 struct k_sem rx_sem;
22 uint8_t *rx_ringbuf;
23 uint32_t rx_ringbuf_sz;
24 uint16_t rx_get, rx_put;
25 int32_t rx_timeout;
26
27 struct k_sem tx_sem;
28 uint8_t *tx_ringbuf;
29 uint32_t tx_ringbuf_sz;
30 uint16_t tx_get, tx_put;
31 int32_t tx_timeout;
32 };
33
34 /**
35 * @brief Initialize serial port object (classically known as tty).
36 *
37 * "tty" device provides support for buffered, interrupt-driven,
38 * timeout-controlled access to an underlying UART device. For
39 * completeness, it also support non-interrupt-driven, busy-polling
40 * access mode. After initialization, tty is in the "most conservative"
41 * unbuffered mode with infinite timeouts (this is guaranteed to work
42 * on any hardware). Users should configure buffers and timeouts as
43 * they need using functions tty_set_rx_buf(), tty_set_tx_buf(),
44 * tty_set_rx_timeout(), tty_set_tx_timeout().
45 *
46 * @param tty tty device structure to initialize
47 * @param uart_dev underlying UART device to use (should support
48 * interrupt-driven operation)
49 *
50 * @return 0 on success, error code (<0) otherwise
51 */
52 int tty_init(struct tty_serial *tty, const struct device *uart_dev);
53
54 /**
55 * @brief Set receive timeout for tty device.
56 *
57 * Set timeout for getchar() operation. Default timeout after
58 * device initialization is SYS_FOREVER_MS.
59 *
60 * @param tty tty device structure
61 * @param timeout timeout in milliseconds, or 0, or SYS_FOREVER_MS.
62 */
tty_set_rx_timeout(struct tty_serial * tty,int32_t timeout)63 static inline void tty_set_rx_timeout(struct tty_serial *tty, int32_t timeout)
64 {
65 tty->rx_timeout = timeout;
66 }
67
68 /**
69 * @brief Set transmit timeout for tty device.
70 *
71 * Set timeout for putchar() operation, for a case when output buffer is full.
72 * Default timeout after device initialization is SYS_FOREVER_MS.
73 *
74 * @param tty tty device structure
75 * @param timeout timeout in milliseconds, or 0, or SYS_FOREVER_MS.
76 */
tty_set_tx_timeout(struct tty_serial * tty,int32_t timeout)77 static inline void tty_set_tx_timeout(struct tty_serial *tty, int32_t timeout)
78 {
79 tty->tx_timeout = timeout;
80 }
81
82 /**
83 * @brief Set receive buffer for tty device.
84 *
85 * Set receive buffer or switch to unbuffered operation for receive.
86 *
87 * @param tty tty device structure
88 * @param buf buffer, or NULL for unbuffered operation
89 * @param size buffer buffer size, 0 for unbuffered operation
90 * @return 0 on success, error code (<0) otherwise:
91 * EINVAL: unsupported buffer (size)
92 */
93 int tty_set_rx_buf(struct tty_serial *tty, void *buf, size_t size);
94
95 /**
96 * @brief Set transmit buffer for tty device.
97 *
98 * Set transmit buffer or switch to unbuffered operation for transmit.
99 * Note that unbuffered mode is implicitly blocking, i.e. behaves as
100 * if tty_set_tx_timeout(SYS_FOREVER_MS) was set.
101 *
102 * @param tty tty device structure
103 * @param buf buffer, or NULL for unbuffered operation
104 * @param size buffer buffer size, 0 for unbuffered operation
105 * @return 0 on success, error code (<0) otherwise:
106 * EINVAL: unsupported buffer (size)
107 */
108 int tty_set_tx_buf(struct tty_serial *tty, void *buf, size_t size);
109
110 /**
111 * @brief Read data from a tty device.
112 *
113 * @param tty tty device structure
114 * @param buf buffer to read data to
115 * @param size maximum number of bytes to read
116 * @return >0, number of actually read bytes (can be less than size param)
117 * =0, for EOF-like condition (e.g., break signaled)
118 * <0, in case of error (e.g. -EAGAIN if timeout expired). errno
119 * variable is also set.
120 */
121 ssize_t tty_read(struct tty_serial *tty, void *buf, size_t size);
122
123 /**
124 * @brief Write data to tty device.
125 *
126 * @param tty tty device structure
127 * @param buf buffer containing data
128 * @param size maximum number of bytes to write
129 * @return =>0, number of actually written bytes (can be less than size param)
130 * <0, in case of error (e.g. -EAGAIN if timeout expired). errno
131 * variable is also set.
132 */
133 ssize_t tty_write(struct tty_serial *tty, const void *buf, size_t size);
134
135 #ifdef __cplusplus
136 }
137 #endif
138
139 #endif /* ZEPHYR_INCLUDE_CONSOLE_TTY_H_ */
140
