1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2013 ARM Limited
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *     http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19 #ifndef MBED_SERIAL_API_H
20 #define MBED_SERIAL_API_H
21 
22 #include "device.h"
23 #include "hal/buffer.h"
24 #include "hal/dma_api.h"
25 
26 #if DEVICE_SERIAL
27 
28 #define SERIAL_EVENT_TX_SHIFT (2)
29 #define SERIAL_EVENT_RX_SHIFT (8)
30 
31 #define SERIAL_EVENT_TX_MASK (0x00FC)
32 #define SERIAL_EVENT_RX_MASK (0x3F00)
33 
34 #define SERIAL_EVENT_ERROR (1 << 1)
35 
36 /**
37  * @defgroup SerialTXEvents Serial TX Events Macros
38  *
39  * @{
40  */
41 #define SERIAL_EVENT_TX_COMPLETE (1 << (SERIAL_EVENT_TX_SHIFT + 0))
42 #define SERIAL_EVENT_TX_ALL      (SERIAL_EVENT_TX_COMPLETE)
43 /**@}*/
44 
45 /**
46  * @defgroup SerialRXEvents Serial RX Events Macros
47  *
48  * @{
49  */
50 #define SERIAL_EVENT_RX_COMPLETE        (1 << (SERIAL_EVENT_RX_SHIFT + 0))
51 #define SERIAL_EVENT_RX_OVERRUN_ERROR   (1 << (SERIAL_EVENT_RX_SHIFT + 1))
52 #define SERIAL_EVENT_RX_FRAMING_ERROR   (1 << (SERIAL_EVENT_RX_SHIFT + 2))
53 #define SERIAL_EVENT_RX_PARITY_ERROR    (1 << (SERIAL_EVENT_RX_SHIFT + 3))
54 #define SERIAL_EVENT_RX_OVERFLOW        (1 << (SERIAL_EVENT_RX_SHIFT + 4))
55 #define SERIAL_EVENT_RX_CHARACTER_MATCH (1 << (SERIAL_EVENT_RX_SHIFT + 5))
56 #define SERIAL_EVENT_RX_ALL             (SERIAL_EVENT_RX_OVERFLOW | SERIAL_EVENT_RX_PARITY_ERROR | \
57                                          SERIAL_EVENT_RX_FRAMING_ERROR | SERIAL_EVENT_RX_OVERRUN_ERROR | \
58                                          SERIAL_EVENT_RX_COMPLETE | SERIAL_EVENT_RX_CHARACTER_MATCH)
59 /**@}*/
60 
61 #define SERIAL_RESERVED_CHAR_MATCH (255)
62 
63 typedef enum {
64     ParityNone = 0,
65     ParityOdd = 1,
66     ParityEven = 2,
67     ParityForced1 = 3,
68     ParityForced0 = 4
69 } SerialParity;
70 
71 typedef enum {
72     RxIrq,
73     TxIrq
74 } SerialIrq;
75 
76 typedef enum {
77     FlowControlNone,
78     FlowControlRTS,
79     FlowControlCTS,
80     FlowControlRTSCTS
81 } FlowControl;
82 
83 typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event);
84 
85 #if DEVICE_SERIAL_ASYNCH
86 /** Asynch serial HAL structure
87  */
88 typedef struct {
89     struct serial_s serial;  /**< Target specific serial structure */
90     struct buffer_s tx_buff; /**< TX buffer */
91     struct buffer_s rx_buff; /**< RX buffer */
92     uint8_t char_match;      /**< Character to be matched */
93     uint8_t char_found;      /**< State of the matched character */
94 } serial_t;
95 
96 #else
97 /** Non-asynch serial HAL structure
98  */
99 typedef struct serial_s serial_t;
100 
101 #endif
102 
103 #ifdef __cplusplus
104 extern "C" {
105 #endif
106 
107 /**
108  * \defgroup hal_GeneralSerial Serial Configuration Functions
109  * @{
110  */
111 
112 /** Initialize the serial peripheral. It sets the default parameters for serial
113  *  peripheral, and configures its specifieds pins.
114  *
115  * @param obj The serial object
116  * @param tx  The TX pin name
117  * @param rx  The RX pin name
118  */
119 void serial_init(serial_t *obj, PinName tx, PinName rx);
120 
121 /** Release the serial peripheral, not currently invoked. It requires further
122  *  resource management.
123  *
124  * @param obj The serial object
125  */
126 void serial_free(serial_t *obj);
127 
128 /** Configure the baud rate
129  *
130  * @param obj      The serial object
131  * @param baudrate The baud rate to be configured
132  */
133 void serial_baud(serial_t *obj, int baudrate);
134 
135 /** Configure the format. Set the number of bits, parity and the number of stop bits
136  *
137  * @param obj       The serial object
138  * @param data_bits The number of data bits
139  * @param parity    The parity
140  * @param stop_bits The number of stop bits
141  */
142 void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits);
143 
144 /** The serial interrupt handler registration
145  *
146  * @param obj     The serial object
147  * @param handler The interrupt handler which will be invoked when the interrupt fires
148  * @param id      The SerialBase object
149  */
150 void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id);
151 
152 /** Configure serial interrupt. This function is used for word-approach
153  *
154  * @param obj    The serial object
155  * @param irq    The serial IRQ type (RX or TX)
156  * @param enable Set to non-zero to enable events, or zero to disable them
157  */
158 void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable);
159 
160 /** Get character. This is a blocking call, waiting for a character
161  *
162  * @param obj The serial object
163  */
164 int  serial_getc(serial_t *obj);
165 
166 /** Send a character. This is a blocking call, waiting for a peripheral to be available
167  *  for writing
168  *
169  * @param obj The serial object
170  * @param c   The character to be sent
171  */
172 void serial_putc(serial_t *obj, int c);
173 
174 /** Check if the serial peripheral is readable
175  *
176  * @param obj The serial object
177  * @return Non-zero value if a character can be read, 0 if nothing to read
178  */
179 int  serial_readable(serial_t *obj);
180 
181 /** Check if the serial peripheral is writable
182  *
183  * @param obj The serial object
184  * @return Non-zero value if a character can be written, 0 otherwise.
185  */
186 int  serial_writable(serial_t *obj);
187 
188 /** Clear the serial peripheral
189  *
190  * @param obj The serial object
191  */
192 void serial_clear(serial_t *obj);
193 
194 /** Set the break
195  *
196  * @param obj The serial object
197  */
198 void serial_break_set(serial_t *obj);
199 
200 /** Clear the break
201  *
202  * @param obj The serial object
203  */
204 void serial_break_clear(serial_t *obj);
205 
206 /** Configure the TX pin for UART function.
207  *
208  * @param tx The pin name used for TX
209  */
210 void serial_pinout_tx(PinName tx);
211 
212 /** Configure the serial for the flow control. It sets flow control in the hardware
213  *  if a serial peripheral supports it, otherwise software emulation is used.
214  *
215  * @param obj    The serial object
216  * @param type   The type of the flow control. Look at the available FlowControl types.
217  * @param rxflow The TX pin name
218  * @param txflow The RX pin name
219  */
220 void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow);
221 
222 #if DEVICE_SERIAL_ASYNCH
223 
224 /**@}*/
225 
226 /**
227  * \defgroup hal_AsynchSerial Asynchronous Serial Hardware Abstraction Layer
228  * @{
229  */
230 
231 /** Begin asynchronous TX transfer. The used buffer is specified in the serial object,
232  *  tx_buff
233  *
234  * @param obj       The serial object
235  * @param tx        The transmit buffer
236  * @param tx_length The number of bytes to transmit
237  * @param tx_width  Deprecated argument
238  * @param handler   The serial handler
239  * @param event     The logical OR of events to be registered
240  * @param hint      A suggestion for how to use DMA with this transfer
241  * @return Returns number of data transfered, otherwise returns 0
242  */
243 int serial_tx_asynch(serial_t *obj, const void *tx, size_t tx_length, uint8_t tx_width, uint32_t handler, uint32_t event, DMAUsage hint);
244 
245 /** Begin asynchronous RX transfer (enable interrupt for data collecting)
246  *  The used buffer is specified in the serial object - rx_buff
247  *
248  * @param obj        The serial object
249  * @param rx         The receive buffer
250  * @param rx_length  The number of bytes to receive
251  * @param rx_width   Deprecated argument
252  * @param handler    The serial handler
253  * @param event      The logical OR of events to be registered
254  * @param handler    The serial handler
255  * @param char_match A character in range 0-254 to be matched
256  * @param hint       A suggestion for how to use DMA with this transfer
257  */
258 void serial_rx_asynch(serial_t *obj, void *rx, size_t rx_length, uint8_t rx_width, uint32_t handler, uint32_t event, uint8_t char_match, DMAUsage hint);
259 
260 /** Attempts to determine if the serial peripheral is already in use for TX
261  *
262  * @param obj The serial object
263  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
264  */
265 uint8_t serial_tx_active(serial_t *obj);
266 
267 /** Attempts to determine if the serial peripheral is already in use for RX
268  *
269  * @param obj The serial object
270  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
271  */
272 uint8_t serial_rx_active(serial_t *obj);
273 
274 /** The asynchronous TX and RX handler.
275  *
276  * @param obj The serial object
277  * @return Returns event flags if an RX transfer termination condition was met; otherwise returns 0
278  */
279 int serial_irq_handler_asynch(serial_t *obj);
280 
281 /** Abort the ongoing TX transaction. It disables the enabled interupt for TX and
282  *  flushes the TX hardware buffer if TX FIFO is used
283  *
284  * @param obj The serial object
285  */
286 void serial_tx_abort_asynch(serial_t *obj);
287 
288 /** Abort the ongoing RX transaction. It disables the enabled interrupt for RX and
289  *  flushes the RX hardware buffer if RX FIFO is used
290  *
291  * @param obj The serial object
292  */
293 void serial_rx_abort_asynch(serial_t *obj);
294 
295 /**@}*/
296 
297 #endif
298 
299 #ifdef __cplusplus
300 }
301 #endif
302 
303 #endif
304 
305 #endif
306 
307 /** @}*/
308