test_src/uart_i.h

   1 /* uart_i.h */
   2 /*
   3     This file is part of the AVR-uart_ni.
   4     Copyright (C) 2006-2015 Daniel Otte (bg@nerilex.org)
   5
   6     This program is free software: you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation, either version 3 of the License, or
   9     (at your option) any later version.
  10
  11     This program is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19 /**
  20  * \file     uart_i.h
  21  * \email    bg@nerilex.org
  22  * \author   Daniel Otte
  23  * \date     2009-07-24
  24  * \license  GPLv3 or later
  25  * \defgroup uart_i
  26  * \brief    declaration for interrupt based uart
  27  * \details
  28  * This implementation of the uart-interface of AVR microcontrollers uses the
  29  * interrup architecture and can be used to handle serial communication in the
  30  * background.
  31  * The uart is configured at compile-time by some special defines starting with
  32  * \a UART0_ for configuring the first uart and \a UART1_ for the second.
  33  * Some settings use symbolic values defined in uart_defs.h .
  34  * The following options are available:
  35  *   - \a *_I enables the interrupt based driver for this uart
  36  *      - \a 0 disables driver
  37  *      - \a 1 enables driver
  38  *   - \a *_BAUD_RATE sets the baudrate for this uart (value is the baudrate)
  39  *   - \a *_STOPBITS sets the amount of stop bits for this uart
  40  *      - \a UART_STOPBITS_1 for one stop bit
  41  *      - \a UART_STOPBITS_2 for two stop bits
  42  *   - \a *_DATABITS sets the amount of data bits for this uart
  43  *      - \a UART_DATABITS_5 for five data bits
  44  *      - \a UART_DATABITS_6 for six data bits
  45  *      - \a UART_DATABITS_7 for seven data bits
  46  *      - \a UART_DATABITS_8 for eight data bits
  47  *   - \a *_PARATY sets the mode for paraty calculation for this uart
  48  *      - \a UART_PARATY_NONE ignore paraty
  49  *      - \a UART_PARATY_ODD  odd paraty
  50  *      - \a UART_PARATY_EVEN even paraty
  51  *   - \a *_RXBUFFER_SIZE size of the recieve buffer in bytes
  52  *   - \a *_TXBUFFER_SIZE size of the transmitt buffer in bytes
  53  *   - \a *_SWFLOWCTRL enable/diasable software flow control (via XON & XOFF)
  54  *      - \a 0 disable software flow control
  55  *      - \a 1 enable software flow control
  56  *   - \a *_THRESH_HIGH set upper limit for the rx buffer, which causes an XOFF
  57  *                      to be send when crossed (only relevant if software flow
  58  *                                            control is enabled)
  59  *   - \a *_THRESH_LOW set lower limit for the rx buffer, which causes an XON to
  60  *                      be send when crossed and an XOFF has been send previously
  61  *                      (only relevant if software flow control is enabled)
  62  *   - \a *_HOOK enable/disable implementation of the hook feature
  63  *               (\ref uart0_sethook())
  64  *      - \a 0 disable hook feature
  65  *      - \a 1 enable hook feature
  66  *
  67  */
  68
  69 /*@{*/
  70 #ifndef UART_I_H_
  71 #define UART_I_H_
  72
  73 #include "config.h"
  74 #include "circularbytebuffer.h"
  75 #include <stdint.h>
  76
  77 /**
  78  * \brief storage type for uart0 context
  79  *
  80  * This type is used to store uart0 specific global variables.
  81  * It contains a pointer to the buffer instances and when neccessary
  82  * a pointer to the hook function and an indicator if the hook is
  83  * currently executed.
  84  * If software flow control is enabled it also contains flags for flow control.
  85  */
  86 typedef struct{
  87         circularbytebuffer_t rxb; /**< recieve buffer */
  88         circularbytebuffer_t txb; /**< transmitt buffer*/
  89 #if UART0_HOOK
  90         void(*hook)(uint8_t);     /**< pointer to the hook function */
  91         volatile uint8_t hook_running; /**< flag indicating if the hook is running */
  92 #endif
  93 #if UART0_SWFLOWCTRL
  94         volatile uint8_t txon;  /**< flag indicating if we are allowed to send data */
  95         volatile uint8_t rxon;  /**< flag indicating if we have send an \a XOFF */
  96 #endif
  97 } uart0_ctx_t;
  98
  99
 100 /**
 101  * \brief storage type for uart1 context
 102  *
 103  * This type is used to store uart1 specific global variables.
 104  * It contains a pointer to the buffer instances and when neccessary
 105  * a pointer to the hook function and an indicator if the hook is
 106  * currently executed.
 107  * If software flow control is enabled it also contains flags for flow control.
 108  */
 109 typedef struct{
 110         circularbytebuffer_t rxb; /**< recieve buffer */
 111         circularbytebuffer_t txb; /**< transmitt buffer */
 112 #if UART1_HOOK
 113         void(*hook)(uint8_t);     /**< pointer to the hook function */
 114         volatile uint8_t hook_running; /**< flag indicating if the hook is running */
 115 #endif
 116 #if UART1_SWFLOWCTRL
 117         volatile uint8_t txon;  /**< flag indicating if we are allowed to send data */
 118         volatile uint8_t rxon;  /**< flag indicating if we have send a XOFF */
 119 #endif
 120 } uart1_ctx_t;
 121
 122 #if UART0_I
 123
 124 /**
 125  * \brief initialize uart0.
 126  *
 127  * This function initializes the first uart according to the parameter specified
 128  * in config.h .
 129  */
 130 void uart0_init(void);
 131
 132 /**
 133  * \brief send data through uart0.
 134  *
 135  * This function sends data through the first uart
 136  * (the data size is debfined in config.h).
 137  * \param c data to send
 138  */
 139 void uart0_putc(uint16_t c);
 140
 141 /**
 142  * \brief read data from uart0.
 143  *
 144  * This function reads data from the first uart
 145  * (the data size is debfined in config.h).
 146  * \return data recived by uart0
 147  */
 148 uint16_t uart0_getc(void);
 149
 150 /**
 151  * \brief checks if data is available.
 152  *
 153  * This function checks the state of the input buffer of uart0 and
 154  * returns if data is available or not.
 155  * \return zero if no data is available else a value different from zero is returned
 156  */
 157 uint8_t uart0_dataavail(void);
 158
 159 /**
 160  * \brief flushes the internal transmit buffer.
 161  *
 162  * This function function waits until all data was send (the transmit-buffer
 163  * does not contain any data).
 164  */
 165 void uart0_flush(void);
 166
 167
 168 #if     UART0_HOOK
 169 /**
 170  * \brief sets the hook for uart0.
 171  *
 172  * This function modifys the way the software handels incomming data.
 173  * When the hook is set to \a NULL (which is the default) incomming data is buffered
 174  * in a special ringbuffer and read by \ref uart0_getc(). If the hook is set to a
 175  * different value, this value is interpret as a function pointer. The hook (the
 176  * function where the function pointer points to) is called with the recieved data
 177  * as single parameter. Any value returned by the hook is discarded.
 178
 179  * \note If the hook is set \ref uart0_getc() will not return, as the
 180  * ringbuffer is bypassed.
 181  * \param fpt pointer to thae handler function for recieved data
 182  */
 183 void uart0_sethook(void(*fpt)(uint8_t));
 184 #endif
 185
 186
 187 #endif /* UART0_I */
 188
 189 #if UART1_I
 190 /**
 191  * \brief initialize uart1.
 192  *
 193  * This function initializes the second uart according to the parameter specifyed
 194  * in config.h .
 195  */
 196 void uart1_init(void);
 197
 198 /**
 199  * \brief send data through uart1.
 200  *
 201  * This function sends data through the second uart
 202  * (the data size is debfined in config.h).
 203  * \param c data to send
 204  */
 205 void uart1_putc(uint16_t c);
 206
 207 /**
 208  * \brief read data from uart1.
 209  *
 210  * This function reads data from the second uart
 211  * (the data size is debfined in config.h).
 212  * \return data recived by uart1
 213  */
 214 uint16_t uart1_getc(void);
 215
 216 /**
 217  * \brief checks if data is available.
 218  *
 219  * This function checks the state of the input buffer of uart1 and
 220  * returns if data is available or not.
 221  * \return zero if no data is available else a value different from zero is returned
 222  */
 223 uint8_t uart1_dataavail(void);
 224
 225 /**
 226  * \brief sets the hook for uart1.
 227  *
 228  * This function modifys the way the software handels incomming data.
 229  * When the hook is set to \a NULL (which is the default) incomming data is buffered
 230  * in a special ringbuffer and read by \ref uart1_getc(). If the hook is set to a
 231  * different value, this value is interpret as a function pointer. The hook (the
 232  * function where the function pointer points to) is called with the recieved data
 233  * as single parameter. Any value returned by the hook is discarded.
 234
 235  * \note If the hook is set \ref uart1_getc() will not return, as the
 236  * ringbuffer is bypassed.
 237  * \param fpt pointer to thae handler function for recieved data
 238  */
 239 void uart1_sethook(void(*fpt)(uint8_t));
 240 #endif
 241
 242 /*@}*/
 243
 244 #endif /* UART_I_H_ */