Mistake on this page?
Report an issue in GitHub or email us
serial_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2013 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_SERIAL_API_H
21 #define MBED_SERIAL_API_H
22 
23 #include "device.h"
24 #include "pinmap.h"
25 #include "hal/buffer.h"
26 #include "hal/dma_api.h"
27 
28 #if DEVICE_SERIAL
29 
30 #define SERIAL_EVENT_TX_SHIFT (2)
31 #define SERIAL_EVENT_RX_SHIFT (8)
32 
33 #define SERIAL_EVENT_TX_MASK (0x00FC)
34 #define SERIAL_EVENT_RX_MASK (0x3F00)
35 
36 #define SERIAL_EVENT_ERROR (1 << 1)
37 
38 /**
39  * @defgroup SerialTXEvents Serial TX Events Macros
40  *
41  * @{
42  */
43 #define SERIAL_EVENT_TX_COMPLETE (1 << (SERIAL_EVENT_TX_SHIFT + 0))
44 #define SERIAL_EVENT_TX_ALL (SERIAL_EVENT_TX_COMPLETE)
45 /**@}*/
46 
47 /**
48  * @defgroup SerialRXEvents Serial RX Events Macros
49  *
50  * @{
51  */
52 #define SERIAL_EVENT_RX_COMPLETE (1 << (SERIAL_EVENT_RX_SHIFT + 0))
53 #define SERIAL_EVENT_RX_OVERRUN_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 1))
54 #define SERIAL_EVENT_RX_FRAMING_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 2))
55 #define SERIAL_EVENT_RX_PARITY_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 3))
56 #define SERIAL_EVENT_RX_OVERFLOW (1 << (SERIAL_EVENT_RX_SHIFT + 4))
57 #define SERIAL_EVENT_RX_CHARACTER_MATCH (1 << (SERIAL_EVENT_RX_SHIFT + 5))
58 #define SERIAL_EVENT_RX_ALL (SERIAL_EVENT_RX_OVERFLOW | SERIAL_EVENT_RX_PARITY_ERROR | \
59  SERIAL_EVENT_RX_FRAMING_ERROR | SERIAL_EVENT_RX_OVERRUN_ERROR | \
60  SERIAL_EVENT_RX_COMPLETE | SERIAL_EVENT_RX_CHARACTER_MATCH)
61 /**@}*/
62 
63 #define SERIAL_RESERVED_CHAR_MATCH (255)
64 
65 typedef enum {
66  ParityNone = 0,
67  ParityOdd = 1,
68  ParityEven = 2,
69  ParityForced1 = 3,
70  ParityForced0 = 4
71 } SerialParity;
72 
73 /** Serial interrupt sources
74  */
75 typedef enum {
76  RxIrq, /**< Receive Data Register Full */
77  TxIrq /**< Transmit Data Register Empty */
78 } SerialIrq;
79 
80 typedef enum {
81  FlowControlNone,
82  FlowControlRTS,
83  FlowControlCTS,
84  FlowControlRTSCTS
85 } FlowControl;
86 
87 typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event);
88 
89 #if DEVICE_SERIAL_ASYNCH
90 /** Asynch serial HAL structure
91  */
92 typedef struct {
93  struct serial_s serial; /**< Target specific serial structure */
94  struct buffer_s tx_buff; /**< TX buffer */
95  struct buffer_s rx_buff; /**< RX buffer */
96  uint8_t char_match; /**< Character to be matched */
97  uint8_t char_found; /**< State of the matched character */
98 } serial_t;
99 
100 #else
101 /** Non-asynch serial HAL structure
102  */
103 typedef struct serial_s serial_t;
104 
105 #endif
106 
107 typedef struct {
108  int peripheral;
109  PinName tx_pin;
110  int tx_function;
111  PinName rx_pin;
112  int rx_function;
113  bool stdio_config;
115 
116 typedef struct {
117  int peripheral;
118  PinName tx_flow_pin;
119  int tx_flow_function;
120  PinName rx_flow_pin;
121  int rx_flow_function;
123 
124 #ifdef __cplusplus
125 extern "C" {
126 #endif
127 
128 /**
129  * \defgroup hal_GeneralSerial Serial Configuration Functions
130  *
131  * # Defined behavior
132  * * ::serial_init initializes the ::serial_t
133  * * ::serial_init sets the default parameters for serial peripheral (9600 bps, 8N1 format)
134  * * ::serial_init configures the specified pins
135  * * ::serial_free releases the serial peripheral
136  * * ::serial_baud configures the baud rate
137  * * at least 9600 bps the baud rate must be supported
138  * * ::serial_format configures the transmission format (number of bits, parity and the number of stop bits)
139  * * at least 8N1 format must be supported
140  * * ::serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires.
141  * * ::serial_irq_set enables or disables the serial RX or TX IRQ.
142  * * If `RxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever
143  * Receive Data Register Full IRQ is generated.
144  * * If `TxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever
145  * Transmit Data Register Empty IRQ is generated.
146  * * If the interrupt condition holds true, when the interrupt is enabled with ::serial_irq_set,
147  * the ::serial_irq_handler is called instantly.
148  * * ::serial_getc returns the character from serial buffer.
149  * * ::serial_getc is a blocking call (waits for the character).
150  * * ::serial_putc sends a character.
151  * * ::serial_putc is a blocking call (waits for a peripheral to be available).
152  * * ::serial_readable returns non-zero value if a character can be read, 0 otherwise.
153  * * ::serial_writable returns non-zero value if a character can be written, 0 otherwise.
154  * * ::serial_clear clears the ::serial_t RX/TX buffers
155  * * ::serial_break_set sets the break signal.
156  * * ::serial_break_clear clears the break signal.
157  * * ::serial_pinout_tx configures the TX pin as an output (to be used in half-duplex mode).
158  * * ::serial_set_flow_control configures serial flow control.
159  * * ::serial_set_flow_control sets flow control in the hardware if a serial peripheral supports it,
160  * otherwise software emulation is used.
161  * * ::serial_tx_asynch starts the serial asynchronous transfer.
162  * * ::serial_tx_asynch writes `tx_length` bytes from the `tx` to the bus.
163  * * ::serial_tx_asynch must support 8 data bits
164  * * The callback given to ::serial_tx_asynch is invoked when the transfer completes.
165  * * ::serial_tx_asynch specifies the logical OR of events to be registered.
166  * * The ::serial_tx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
167  * * ::serial_rx_asynch starts the serial asynchronous transfer.
168  * * ::serial_rx_asynch reads `rx_length` bytes to the `rx` buffer.
169  * * ::serial_rx_asynch must support 8 data bits
170  * * The callback given to ::serial_rx_asynch is invoked when the transfer completes.
171  * * ::serial_rx_asynch specifies the logical OR of events to be registered.
172  * * The ::serial_rx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
173  * * ::serial_rx_asynch specifies a character in range 0-254 to be matched, 255 is a reserved value.
174  * * If SERIAL_EVENT_RX_CHARACTER_MATCH event is not registered, the `char_match` is ignored.
175  * * The SERIAL_EVENT_RX_CHARACTER_MATCH event is set in the callback when SERIAL_EVENT_RX_CHARACTER_MATCH event is
176  * registered AND `char_match` is present in the received data.
177  * * ::serial_tx_active returns non-zero if the TX transaction is ongoing, 0 otherwise.
178  * * ::serial_rx_active returns non-zero if the RX transaction is ongoing, 0 otherwise.
179  * * ::serial_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
180  * * ::serial_irq_handler_asynch takes no longer than one packet transfer time (packet_bits / baudrate) to execute.
181  * * ::serial_tx_abort_asynch aborts the ongoing TX transaction.
182  * * ::serial_tx_abort_asynch disables the enabled interupt for TX.
183  * * ::serial_tx_abort_asynch flushes the TX hardware buffer if TX FIFO is used.
184  * * ::serial_rx_abort_asynch aborts the ongoing RX transaction.
185  * * ::serial_rx_abort_asynch disables the enabled interupt for RX.
186  * * ::serial_rx_abort_asynch flushes the TX hardware buffer if RX FIFO is used.
187  * * Correct operation guaranteed when interrupt latency is shorter than one packet transfer time (packet_bits / baudrate)
188  * if the flow control is not used.
189  * * Correct operation guaranteed regardless of interrupt latency if the flow control is used.
190  *
191  * # Undefined behavior
192  * * Calling ::serial_init multiple times on the same `serial_t` without ::serial_free.
193  * * Passing invalid pin to ::serial_init, ::serial_pinout_tx.
194  * * Calling any function other than ::serial_init on am uninitialized or freed `serial_t`.
195  * * Passing an invalid pointer as `obj` to any function.
196  * * Passing an invalid pointer as `handler` to ::serial_irq_handler, ::serial_tx_asynch, ::serial_rx_asynch.
197  * * Calling ::serial_tx_abort while no async TX transfer is being processed.
198  * * Calling ::serial_rx_abort while no async RX transfer is being processed.
199  * * Devices behavior is undefined when the interrupt latency is longer than one packet transfer time
200  * (packet_bits / baudrate) if the flow control is not used.
201  * @{
202  */
203 
204 /**
205  * \defgroup hal_GeneralSerial_tests Serial hal tests
206  * The Serial HAL tests ensure driver conformance to defined behavior.
207  *
208  * To run the Serial hal tests use the command:
209  *
210  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-uart
211  *
212  */
213 
214 /** Initialize the serial peripheral. It sets the default parameters for serial
215  * peripheral, and configures its specifieds pins.
216  *
217  * @param obj The serial object
218  * @param tx The TX pin name
219  * @param rx The RX pin name
220  */
221 void serial_init(serial_t *obj, PinName tx, PinName rx);
222 
223 /** Initialize the serial peripheral. It sets the default parameters for serial
224  * peripheral, and configures its specifieds pins.
225  *
226  * @param obj The serial object
227  * @param pinmap pointer to structure which holds static pinmap
228  */
229 void serial_init_direct(serial_t *obj, const serial_pinmap_t *pinmap);
230 
231 
232 /** Release the serial peripheral, not currently invoked. It requires further
233  * resource management.
234  *
235  * @param obj The serial object
236  */
237 void serial_free(serial_t *obj);
238 
239 /** Configure the baud rate
240  *
241  * @param obj The serial object
242  * @param baudrate The baud rate to be configured
243  */
244 void serial_baud(serial_t *obj, int baudrate);
245 
246 /** Configure the format. Set the number of bits, parity and the number of stop bits
247  *
248  * @param obj The serial object
249  * @param data_bits The number of data bits
250  * @param parity The parity
251  * @param stop_bits The number of stop bits
252  */
253 void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits);
254 
255 /** The serial interrupt handler registration
256  *
257  * @param obj The serial object
258  * @param handler The interrupt handler which will be invoked when the interrupt fires
259  * @param id The SerialBase object
260  */
261 void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id);
262 
263 /** Configure serial interrupt. This function is used for word-approach
264  *
265  * @param obj The serial object
266  * @param irq The serial IRQ type (RX or TX)
267  * @param enable Set to non-zero to enable events, or zero to disable them
268  */
269 void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable);
270 
271 /** Get character. This is a blocking call, waiting for a character
272  *
273  * @param obj The serial object
274  */
275 int serial_getc(serial_t *obj);
276 
277 /** Send a character. This is a blocking call, waiting for a peripheral to be available
278  * for writing
279  *
280  * @param obj The serial object
281  * @param c The character to be sent
282  */
283 void serial_putc(serial_t *obj, int c);
284 
285 /** Check if the serial peripheral is readable
286  *
287  * @param obj The serial object
288  * @return Non-zero value if a character can be read, 0 if nothing to read
289  */
290 int serial_readable(serial_t *obj);
291 
292 /** Check if the serial peripheral is writable
293  *
294  * @param obj The serial object
295  * @return Non-zero value if a character can be written, 0 otherwise.
296  */
297 int serial_writable(serial_t *obj);
298 
299 /** Clear the serial peripheral
300  *
301  * @param obj The serial object
302  */
303 void serial_clear(serial_t *obj);
304 
305 /** Set the break
306  *
307  * @param obj The serial object
308  */
309 void serial_break_set(serial_t *obj);
310 
311 /** Clear the break
312  *
313  * @param obj The serial object
314  */
315 void serial_break_clear(serial_t *obj);
316 
317 /** Configure the TX pin for UART function.
318  *
319  * @param tx The pin name used for TX
320  */
321 void serial_pinout_tx(PinName tx);
322 
323 #if DEVICE_SERIAL_FC
324 /** Configure the serial for the flow control. It sets flow control in the hardware
325  * if a serial peripheral supports it, otherwise software emulation is used.
326  *
327  * @param obj The serial object
328  * @param type The type of the flow control. Look at the available FlowControl types.
329  * @param rxflow The TX pin name
330  * @param txflow The RX pin name
331  */
332 void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow);
333 
334 /** Configure the serial for the flow control. It sets flow control in the hardware
335  * if a serial peripheral supports it, otherwise software emulation is used.
336  *
337  * @param obj The serial object
338  * @param type The type of the flow control. Look at the available FlowControl types.
339  * @param pinmap Pointer to structure which holds static pinmap
340  */
341 void serial_set_flow_control_direct(serial_t *obj, FlowControl type, const serial_fc_pinmap_t *pinmap);
342 #endif
343 
344 /** Get the pins that support Serial TX
345  *
346  * Return a PinMap array of pins that support Serial TX. The
347  * array is terminated with {NC, NC, 0}.
348  *
349  * @return PinMap array
350  */
351 const PinMap *serial_tx_pinmap(void);
352 
353 /** Get the pins that support Serial RX
354  *
355  * Return a PinMap array of pins that support Serial RX. The
356  * array is terminated with {NC, NC, 0}.
357  *
358  * @return PinMap array
359  */
360 const PinMap *serial_rx_pinmap(void);
361 
362 #if DEVICE_SERIAL_FC
363 /** Get the pins that support Serial CTS
364  *
365  * Return a PinMap array of pins that support Serial CTS. The
366  * array is terminated with {NC, NC, 0}.
367  *
368  * @return PinMap array
369  */
370 const PinMap *serial_cts_pinmap(void);
371 
372 /** Get the pins that support Serial RTS
373  *
374  * Return a PinMap array of pins that support Serial RTS. The
375  * array is terminated with {NC, NC, 0}.
376  *
377  * @return PinMap array
378  */
379 const PinMap *serial_rts_pinmap(void);
380 #endif
381 
382 #if DEVICE_SERIAL_ASYNCH
383 
384 /**@}*/
385 
386 /**
387  * \defgroup hal_AsynchSerial Asynchronous Serial Hardware Abstraction Layer
388  * @{
389  */
390 
391 /** Begin asynchronous TX transfer. The used buffer is specified in the serial object,
392  * tx_buff
393  *
394  * @param obj The serial object
395  * @param tx The transmit buffer
396  * @param tx_length The number of bytes to transmit
397  * @param tx_width Deprecated argument
398  * @param handler The serial handler
399  * @param event The logical OR of events to be registered
400  * @param hint A suggestion for how to use DMA with this transfer
401  * @return Returns number of data transfered, otherwise returns 0
402  */
403 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);
404 
405 /** Begin asynchronous RX transfer (enable interrupt for data collecting)
406  * The used buffer is specified in the serial object - rx_buff
407  *
408  * @param obj The serial object
409  * @param rx The receive buffer
410  * @param rx_length The number of bytes to receive
411  * @param rx_width Deprecated argument
412  * @param handler The serial handler
413  * @param event The logical OR of events to be registered
414  * @param char_match A character in range 0-254 to be matched
415  * @param hint A suggestion for how to use DMA with this transfer
416  */
417 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);
418 
419 /** Attempts to determine if the serial peripheral is already in use for TX
420  *
421  * @param obj The serial object
422  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
423  */
424 uint8_t serial_tx_active(serial_t *obj);
425 
426 /** Attempts to determine if the serial peripheral is already in use for RX
427  *
428  * @param obj The serial object
429  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
430  */
431 uint8_t serial_rx_active(serial_t *obj);
432 
433 /** The asynchronous TX and RX handler.
434  *
435  * @param obj The serial object
436  * @return Returns event flags if an RX transfer termination condition was met; otherwise returns 0
437  */
439 
440 /** Abort the ongoing TX transaction. It disables the enabled interupt for TX and
441  * flushes the TX hardware buffer if TX FIFO is used
442  *
443  * @param obj The serial object
444  */
446 
447 /** Abort the ongoing RX transaction. It disables the enabled interrupt for RX and
448  * flushes the RX hardware buffer if RX FIFO is used
449  *
450  * @param obj The serial object
451  */
453 
454 /**@}*/
455 
456 #endif
457 
458 #ifdef __cplusplus
459 }
460 #endif
461 
462 #endif
463 
464 #endif
465 
466 /** @}*/
const PinMap * serial_tx_pinmap(void)
Get the pins that support Serial TX.
void serial_baud(serial_t *obj, int baudrate)
Configure the baud rate.
Generic buffer structure.
Definition: buffer.h:27
void serial_tx_abort_asynch(serial_t *obj)
Abort the ongoing TX transaction.
Transmit Data Register Empty.
Definition: serial_api.h:77
void serial_break_clear(serial_t *obj)
Clear the break.
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)
Begin asynchronous RX transfer (enable interrupt for data collecting) The used buffer is specified in...
int serial_writable(serial_t *obj)
Check if the serial peripheral is writable.
int serial_getc(serial_t *obj)
Get character.
void serial_init_direct(serial_t *obj, const serial_pinmap_t *pinmap)
Initialize the serial peripheral.
const PinMap * serial_cts_pinmap(void)
Get the pins that support Serial CTS.
int serial_irq_handler_asynch(serial_t *obj)
The asynchronous TX and RX handler.
uint8_t char_match
Character to be matched.
Definition: serial_api.h:96
void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits)
Configure the format.
void serial_free(serial_t *obj)
Release the serial peripheral, not currently invoked.
SerialIrq
Serial interrupt sources.
Definition: serial_api.h:75
void serial_rx_abort_asynch(serial_t *obj)
Abort the ongoing RX transaction.
void serial_init(serial_t *obj, PinName tx, PinName rx)
Initialize the serial peripheral.
void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id)
The serial interrupt handler registration.
Receive Data Register Full.
Definition: serial_api.h:76
const PinMap * serial_rts_pinmap(void)
Get the pins that support Serial RTS.
void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable)
Configure serial interrupt.
void serial_set_flow_control_direct(serial_t *obj, FlowControl type, const serial_fc_pinmap_t *pinmap)
Configure the serial for the flow control.
const PinMap * serial_rx_pinmap(void)
Get the pins that support Serial RX.
void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow)
Configure the serial for the flow control.
Definition: pinmap.h:31
Asynch serial HAL structure.
Definition: serial_api.h:92
uint8_t serial_rx_active(serial_t *obj)
Attempts to determine if the serial peripheral is already in use for RX.
uint8_t char_found
State of the matched character.
Definition: serial_api.h:97
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)
Begin asynchronous TX transfer.
void serial_clear(serial_t *obj)
Clear the serial peripheral.
void serial_break_set(serial_t *obj)
Set the break.
void serial_pinout_tx(PinName tx)
Configure the TX pin for UART function.
uint8_t serial_tx_active(serial_t *obj)
Attempts to determine if the serial peripheral is already in use for TX.
void serial_putc(serial_t *obj, int c)
Send a character.
int serial_readable(serial_t *obj)
Check if the serial peripheral is readable.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.