uart: fix return value of send functions
[aversive.git] / 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