lib/uart/include/ucg_uart.h

   1 /*
   2  * Copyright (c) 2005-2015, Olivier MATZ <zer0@droids-corp.org>
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   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.
  15  *
  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.
  26  */
  27
  28 #ifndef UCG_UART_H_
  29 #define UCG_UART_H_
  30
  31 #include <ucg_cirbuf.h>
  32
  33 /**
  34  * UART interface, using interrupts. Supports 5 to 8 bits characters
  35  * (not 9 bits).
  36  */
  37
  38 /**
  39  * Callback type of tx/rx event.
  40  */
  41 typedef void (ucg_uart_cb_t)(char);
  42
  43 struct ucg_uart;
  44
  45 /**
  46  * Configuration of the uart
  47  */
  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 */
  55 };
  56
  57 /**
  58  * Per-arch uart driver operations
  59  */
  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 */
  69 };
  70
  71 /**
  72  * Generic Uart structure
  73  */
  74 struct ucg_uart {
  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 */
  82 };
  83
  84 /**
  85  * Uart wait directive, used in rx/tx functions.
  86  */
  87 enum ucg_uart_wait {
  88         WAIT,     /**< Loop until operation can be done */
  89         NOWAIT,   /**< Return if operation can't be done now */
  90 };
  91
  92 /**
  93  * Handle TX register empty interrupt
  94  *
  95  * @param uart
  96  *   The uart structure.
  97  */
  98 void ucg_uart_tx_intr(struct ucg_uart *uart);
  99
 100 /**
 101  * Handle RX register empty interrupt
 102  *
 103  * @param uart
 104  *   The uart structure.
 105  */
 106 void ucg_uart_rx_intr(struct ucg_uart *uart);
 107
 108 /**
 109  * Initialize uart
 110  *
 111  * Initialize the per-arch and generic uart structure, the rx and tx
 112  * fifos, and configure the uart with the default configuration.
 113  *
 114  * @param uart
 115  *   The uart structure.
 116  * @param ops
 117  *   A pointer to the per-arch uart operations.
 118  * @param driver_data
 119  *   A pointer to a per-arch uart data structure (ex: struct ucg_stm32_uart *)
 120  * @param rx_cbuf
 121  *   A pointer to an uninitialized cirbuf, used for rx fifo
 122  * @param rx_buf
 123  *   The buffer used by the rx fifo
 124  * @param rx_bufsize
 125  *   The length of rx_buf in bytes
 126  * @param tx_cbuf
 127  *   A pointer to an uninitialized cirbuf, used for tx fifo
 128  * @param tx_buf
 129  *   The buffer used by the tx fifo
 130  * @param tx_bufsize
 131  *   The length of tx_buf in bytes
 132  * @return
 133  *   0 on success, negative on error.
 134  */
 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);
 139
 140 /**
 141  * Configure the uart with the given configuration.
 142  *
 143  * The function ucg_uart_init() must have been called first.
 144  *
 145  * @param uart
 146  *   The uart structure.
 147  * @param conf
 148  *   The configuration to be applied.
 149  * @return
 150  *   0 on success, negative on error.
 151  */
 152 int ucg_uart_setconf(struct ucg_uart *uart, const struct ucg_uart_config *conf);
 153
 154 /**
 155  * Get the current configuration of the uart.
 156  *
 157  * @param uart
 158  *   The uart structure.
 159  * @param conf
 160  *   The pointer to be filled with the current running configuration.
 161  */
 162 void ucg_uart_getconf(struct ucg_uart *uart, struct ucg_uart_config *conf);
 163
 164 /**
 165  * Receive a character.
 166  *
 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.
 170  *
 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
 173  * received.
 174  *
 175  * @param uart
 176  *   The uart structure.
 177  * @param wait
 178  *   The wait directive (WAIT or NOWAIT)
 179  * @return
 180  *   Return the character on success (>= 0), or a negative value on error.
 181  */
 182 int ucg_uart_recv(struct ucg_uart *uart, enum ucg_uart_wait wait);
 183
 184 /**
 185  * Send a character.
 186  *
 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.
 190  *
 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.
 194  *
 195  * @param uart
 196  *   The uart structure.
 197  * @param wait
 198  *   The wait directive (WAIT or NOWAIT)
 199  * @return
 200  *   Return the transmitted character on success (>= 0), or a negative
 201  *   value on error.
 202  */
 203 int ucg_uart_send(struct ucg_uart *uart, char c, enum ucg_uart_wait wait);
 204
 205 /**
 206  * Flush the TX fifo
 207  *
 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.
 211  *
 212  * @param uart
 213  *   The uart structure.
 214  */
 215 void ucg_uart_flush(struct ucg_uart *uart);
 216
 217 /**
 218  * Register a TX callback function
 219  *
 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.
 225  *
 226  * @param uart
 227  *   The uart structure.
 228  * @param f
 229  *   The function to call on tx event, can be NULL to disable.
 230  * @param arg
 231  *   The opaque argument given to the function.
 232  */
 233 void ucg_uart_register_tx_cb(struct ucg_uart *uart, ucg_uart_cb_t *f);
 234
 235 /**
 236  * Register a TX callback function
 237  *
 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.
 243  *
 244  * @param uart
 245  *   The uart structure.
 246  * @param f
 247  *   The function to call on tx event, can be NULL to disable.
 248  * @param arg
 249  *   The opaque argument given to the function.
 250  */
 251 void ucg_uart_register_rx_cb(struct ucg_uart *uart, ucg_uart_cb_t *f);
 252
 253 #endif /* UCG_UART_H_ */