modules/comm/uart/uart.h

   1 /*  \r
   2  *  Copyright Droids Corporation, Microb Technology, Eirbot (2005)\r
   3  * \r
   4  *  This program is free software; you can redistribute it and/or modify\r
   5  *  it under the terms of the GNU General Public License as published by\r
   6  *  the Free Software Foundation; either version 2 of the License, or\r
   7  *  (at your option) any later version.\r
   8  *\r
   9  *  This program is distributed in the hope that it will be useful,\r
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  12  *  GNU General Public License for more details.\r
  13  *\r
  14  *  You should have received a copy of the GNU General Public License\r
  15  *  along with this program; if not, write to the Free Software\r
  16  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\r
  17  *\r
  18  *  Revision : $Id: uart.h,v 1.22.4.4 2008-12-27 16:29:07 zer0 Exp $\r
  19  *\r
  20  */\r
  21 \r
  22 /* Olivier MATZ, 2004 - 2006\r
  23  * Interface of the uart module\r
  24  */\r
  25 \r
  26 /** \file uart.h\r
  27  *  \brief Interface of the UART module.\r
  28  *\r
  29  * This module provides :\r
  30  *   - Tx and Rx with fifo\r
  31  *   - Speed selection\r
  32  *   - Parity selection (if the uC support it)\r
  33  *   - 5 to 8 data bits (if the uC support it).\r
  34  *   - 1 or 2 stop bits (if the uC support it).\r
  35  *   - up to 4 UARTs (if the uC support it).\r
  36  * \r
  37  * Number of bits in frame, parity, stop bits are the same for tx and\r
  38  * rx. TX fifo is useless if interrupts are disabled because the uart\r
  39  * wait that all bytes are transmitted before returning.\r
  40  *\r
  41  * It doesn't support some USART capabilities :\r
  42  *   - Synchronous mode\r
  43  *   - Multiprocessor communication\r
  44  */\r
  45 \r
  46 #ifndef _UART_H_\r
  47 #define _UART_H_\r
  48 \r
  49 #include <stdio.h>\r
  50 #include <aversive.h>\r
  51 #include <uart_config.h>\r
  52 #include <uart_defs.h>\r
  53 \r
  54 #include <cirbuf.h>\r
  55 \r
  56 /** this structure stores the configuration of the uart */\r
  57 struct uart_config {\r
  58       uint8_t enabled          : 1, /**< enable or disable the uart */\r
  59       intr_enabled     : 1, /**< use interruptions or not */\r
  60       use_double_speed : 1, /**< less acurate, but can reach faster baudrate */\r
  61       parity           : 2, /**< none, odd or even */\r
  62       stop_bits        : 1, /**< 1 or 2 bits at the end of the frame */\r
  63       reserved         : 1; /**< nothing for now */\r
  64       uint8_t nbits;                /**< number of bits in frame, 5,6,7,8 or 9 */\r
  65       uint32_t baudrate;             /**< speed of uart */\r
  66 };\r
  67 \r
  68 /** The emission fifo of uart */\r
  69 extern struct cirbuf g_tx_fifo[UART_HW_NUM];\r
  70 \r
  71 /** The reception fifo of uart  */\r
  72 extern struct cirbuf g_rx_fifo[UART_HW_NUM];\r
  73 \r
  74 /** \r
  75  * Initialisation function. This function puts the registers of the\r
  76  * microcontroler in a correct state in order to use the uart.  It\r
  77  * uses the configuration file <uart_config.h> ; this function is\r
  78  * equivalent to call uartX_setconf(NULL) for each uart.\r
  79  */\r
  80 void uart_init(void);\r
  81 \r
  82 /** \r
  83  * Configure the uart 'num' with the given configuration. Returns 0 on\r
  84  * success.\r
  85  */\r
  86 int8_t uart_setconf(uint8_t num, struct uart_config *u);\r
  87 \r
  88 /** Get the current configuration of the uart 'num' */\r
  89 void uart_getconf(uint8_t num, struct uart_config *u);\r
  90 \r
  91 /** \r
  92  * uart_recv returns the next character, taken from the fifo (if\r
  93  * any). If there is nothing to read, the function waits until\r
  94  * something come on the uart.\r
  95  */\r
  96 int uart_recv(uint8_t num);\r
  97 \r
  98 /** \r
  99  * uart_recv returns the next character, taken from the fifo (if\r
 100  * any). If there is nothing to read, the function returns -1.\r
 101  */\r
 102 int uart_recv_nowait(uint8_t num);\r
 103 \r
 104 /**\r
 105  * same than uart_recv with 9 bits.\r
 106  */\r
 107 int uart_9bits_recv(uint8_t num);\r
 108 \r
 109 /** \r
 110  * same than uart_recv_nowait() with 9 bits.\r
 111  */\r
 112 int uart_9bits_recv_nowait(uint8_t num);\r
 113 \r
 114 /**\r
 115  * uart_send_nowait is used to send data to the uart 'num'. The data\r
 116  * is first stored in the FIFO before beeing sent. If the FIFO is\r
 117  * full, data is dropped and the function returns -1, else it returns\r
 118  * the character c.\r
 119  */\r
 120 int uart_send_nowait(uint8_t num, char c);\r
 121 \r
 122 /**\r
 123  * uart_send is used to send data to the uart 'num'. The data is first\r
 124  * stored in the FIFO before beeing sent. If the FIFO is full, the\r
 125  * function wait until the uart is ready. The function returns c.\r
 126  */\r
 127 int uart_send(uint8_t num, char c);\r
 128 \r
 129 /**\r
 130  * uart_send_9bits is the same that uart_send but arg is 16 bits so\r
 131  * data can be 9 bits wide.\r
 132  */\r
 133 int uart_send_9bits_nowait(uint8_t num, int c);\r
 134 \r
 135 /* uart_send_9bits_wait is the same that uart_send_wait but arg is\r
 136  * 16 bits so data can be 9 bits wide.\r
 137  */\r
 138 int uart_send_9bits(uint8_t num, int c);\r
 139 \r
 140 \r
 141 \r
 142 /**\r
 143  * This function is used to register another function which will be\r
 144  * executed at each byte transmission (5, 6 ,7 ,8 bits)\r
 145  */\r
 146 void uart_register_tx_event(uint8_t num, void (*f)(char));\r
 147 \r
 148 /**\r
 149  * This function is used to register another function which will be\r
 150  * executed at each byte reception (5, 6 ,7 ,8 bits)\r
 151  */\r
 152 void uart_register_rx_event(uint8_t num, void (*f)(char));\r
 153 \r
 154 \r
 155 /**\r
 156  * This function is used to register another function which will be\r
 157  * executed at each 9 bits frame transmission. WARNING : it uses the\r
 158  * same internal pointer that the 8 bits event, so be carreful to \r
 159  * unregister 8 bits events when doing 9 bits and vice versa.\r
 160  */\r
 161 void uart_register_tx_9bits_event(uint8_t num, void (*f)(int));\r
 162 \r
 163 /**\r
 164  * This function is used to register another function which will be\r
 165  * executed at each 9 bits reception. WARNING : it uses the\r
 166  * same internal pointer that the 8 bits event, so be carreful to \r
 167  * unregister 8 bits events when doing 9 bits and vice versa.\r
 168  */\r
 169 void uart_register_rx_9bits_event(uint8_t num, void (*f)(int));\r
 170 \r
 171 /* funcs for use with fdevopen (avrlibc > 1.4.0) */\r
 172 int uart0_dev_send_nowait(char c, FILE* f);\r
 173 int uart0_dev_send(char c, FILE* f);\r
 174 int uart0_dev_recv_nowait(FILE* f);\r
 175 int uart0_dev_recv(FILE* f);\r
 176 \r
 177 int uart1_dev_send_nowait(char c, FILE* f);\r
 178 int uart1_dev_send(char c, FILE* f);\r
 179 int uart1_dev_recv_nowait(FILE* f);\r
 180 int uart1_dev_recv(FILE* f);\r
 181 \r
 182 int uart2_dev_send_nowait(char c, FILE* f);\r
 183 int uart2_dev_send(char c, FILE* f);\r
 184 int uart2_dev_recv_nowait(FILE* f);\r
 185 int uart2_dev_recv(FILE* f);\r
 186 \r
 187 int uart3_dev_send_nowait(char c, FILE* f);\r
 188 int uart3_dev_send(char c, FILE* f);\r
 189 int uart3_dev_recv_nowait(FILE* f);\r
 190 int uart3_dev_recv(FILE* f);\r
 191 \r
 192 \r
 193 #endif /* _UART_H_ */\r
 194 \r