2 * Copyright (c) 2005-2015, Olivier MATZ <zer0@droids-corp.org>
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of the University of California, Berkeley nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #include <ucg_cirbuf.h>
34 * UART interface, using interrupts. Supports 5 to 8 bits characters
39 * Callback type of tx/rx event.
41 typedef void (ucg_uart_cb_t)(char);
46 * Configuration of the uart
48 struct ucg_uart_config {
49 uint8_t enable : 1, /**< enable or disable the uart */
50 parity : 2, /**< none, odd or even */
51 stop_bits : 1, /**< 1 or 2 bits at the end of the frame */
52 reserved : 4; /**< nothing for now */
53 uint8_t nbits; /**< number of bits in frame, 5, 6, 7 or 8 */
54 uint32_t baudrate; /**< speed of uart */
58 * Per-arch uart driver operations
60 struct ucg_uart_driver_ops {
61 void (*disable_tx_irq)(struct ucg_uart *uart); /**< Disable tx intrpt */
62 void (*enable_tx_irq)(struct ucg_uart *uart); /**< Enable tx intrpt */
63 uint8_t (*tx_ready)(struct ucg_uart *uart); /**< Test if tx register empty */
64 uint8_t (*rx_ready)(struct ucg_uart *uart); /**< Test if rx register full */
65 void (*set_udr)(struct ucg_uart *uart, char c); /**< Set uart data register */
66 char (*get_udr)(struct ucg_uart *uart); /**< Get uart data register */
67 int (*set_conf)(struct ucg_uart *uart,
68 const struct ucg_uart_config *conf); /**< Set configuration */
72 * Generic Uart structure
75 struct ucg_uart_config conf; /**< Current configuration */
76 ucg_uart_cb_t *rx_cb; /**< RX callback */
77 ucg_uart_cb_t *tx_cb; /**< TX callback */
78 struct ucg_cirbuf *rx_fifo; /**< RX fifo */
79 struct ucg_cirbuf *tx_fifo; /**< TX fifo */
80 const struct ucg_uart_driver_ops *ops; /**< Pointer to arch uart ops */
81 void *driver_data; /**< Opaque arch uart data */
85 * Uart wait directive, used in rx/tx functions.
88 WAIT, /**< Loop until operation can be done */
89 NOWAIT, /**< Return if operation can't be done now */
93 * Handle TX register empty interrupt
98 void ucg_uart_tx_intr(struct ucg_uart *uart);
101 * Handle RX register empty interrupt
104 * The uart structure.
106 void ucg_uart_rx_intr(struct ucg_uart *uart);
111 * Initialize the per-arch and generic uart structure, the rx and tx
112 * fifos, and configure the uart with the default configuration.
115 * The uart structure.
117 * A pointer to the per-arch uart operations.
119 * A pointer to a per-arch uart data structure (ex: struct ucg_stm32_uart *)
121 * A pointer to an uninitialized cirbuf, used for rx fifo
123 * The buffer used by the rx fifo
125 * The length of rx_buf in bytes
127 * A pointer to an uninitialized cirbuf, used for tx fifo
129 * The buffer used by the tx fifo
131 * The length of tx_buf in bytes
133 * 0 on success, negative on error.
135 int ucg_uart_init(struct ucg_uart *uart,
136 const struct ucg_uart_driver_ops *ops, void *driver_data,
137 struct ucg_cirbuf *rx_cbuf, char *rx_buf, unsigned rx_bufsize,
138 struct ucg_cirbuf *tx_cbuf, char *tx_buf, unsigned tx_bufsize);
141 * Configure the uart with the given configuration.
143 * The function ucg_uart_init() must have been called first.
146 * The uart structure.
148 * The configuration to be applied.
150 * 0 on success, negative on error.
152 int ucg_uart_setconf(struct ucg_uart *uart, const struct ucg_uart_config *conf);
155 * Get the current configuration of the uart.
158 * The uart structure.
160 * The pointer to be filled with the current running configuration.
162 void ucg_uart_getconf(struct ucg_uart *uart, struct ucg_uart_config *conf);
165 * Receive a character.
167 * Receive the next character, taken from the fifo if any. If NOWAIT is
168 * given, the function returns an error if the fifo is empty. If WAIT is
169 * given, the function loops until a new character can be returned.
171 * The function can be called from an interrupt, but it should be used
172 * with care if WAIT is given, as it will loop until a character is
176 * The uart structure.
178 * The wait directive (WAIT or NOWAIT)
180 * Return the character on success (>= 0), or a negative value on error.
182 int ucg_uart_recv(struct ucg_uart *uart, enum ucg_uart_wait wait);
187 * Put a new character in the TX fifo. If NOWAIT is given, the function
188 * returns an error if the fifo is full. If WAIT is given, the function
189 * loops until some room is available in the tx fifo.
191 * The function can be called from an interrupt, but it should be used
192 * with care if WAIT is given, as it will wait that the current
193 * transmission is finished before returning.
196 * The uart structure.
198 * The wait directive (WAIT or NOWAIT)
200 * Return the transmitted character on success (>= 0), or a negative
203 int ucg_uart_send(struct ucg_uart *uart, char c, enum ucg_uart_wait wait);
208 * Loop until the uart TX fifo is empty. The function can be called from
209 * an interrupt, but it should be used with care as it will wait that the
210 * transmission of all bytes of the fifo is finished before returning.
213 * The uart structure.
215 void ucg_uart_flush(struct ucg_uart *uart);
218 * Register a TX callback function
220 * Register a function that will be called after a character is written
221 * in the UART dta register. This function is called with interrupts
222 * locked, and the user is free to access or modify the tx fifo if
223 * required. Note that the character that has just been transmitted is
224 * not in the tx fifo when the callback is invoked.
227 * The uart structure.
229 * The function to call on tx event, can be NULL to disable.
231 * The opaque argument given to the function.
233 void ucg_uart_register_tx_cb(struct ucg_uart *uart, ucg_uart_cb_t *f);
236 * Register a TX callback function
238 * Register a function that will be called after a character is read
239 * from the UART dta register. This function is called with interrupts
240 * locked, and the user is free to access or modify the rx fifo if
241 * required. Note that the character that has just been received is
242 * present in the rx fifo when the callback is invoked.
245 * The uart structure.
247 * The function to call on tx event, can be NULL to disable.
249 * The opaque argument given to the function.
251 void ucg_uart_register_rx_cb(struct ucg_uart *uart, ucg_uart_cb_t *f);
253 #endif /* UCG_UART_H_ */