Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
serial_api.h
00001 00002 /** \addtogroup hal */ 00003 /** @{*/ 00004 /* mbed Microcontroller Library 00005 * Copyright (c) 2006-2013 ARM Limited 00006 * SPDX-License-Identifier: Apache-2.0 00007 * 00008 * Licensed under the Apache License, Version 2.0 (the "License"); 00009 * you may not use this file except in compliance with the License. 00010 * You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, software 00015 * distributed under the License is distributed on an "AS IS" BASIS, 00016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00017 * See the License for the specific language governing permissions and 00018 * limitations under the License. 00019 */ 00020 #ifndef MBED_SERIAL_API_H 00021 #define MBED_SERIAL_API_H 00022 00023 #include "device.h" 00024 #include "pinmap.h" 00025 #include "hal/buffer.h" 00026 #include "hal/dma_api.h" 00027 00028 #if DEVICE_SERIAL 00029 00030 #define SERIAL_EVENT_TX_SHIFT (2) 00031 #define SERIAL_EVENT_RX_SHIFT (8) 00032 00033 #define SERIAL_EVENT_TX_MASK (0x00FC) 00034 #define SERIAL_EVENT_RX_MASK (0x3F00) 00035 00036 #define SERIAL_EVENT_ERROR (1 << 1) 00037 00038 /** 00039 * @defgroup SerialTXEvents Serial TX Events Macros 00040 * 00041 * @{ 00042 */ 00043 #define SERIAL_EVENT_TX_COMPLETE (1 << (SERIAL_EVENT_TX_SHIFT + 0)) 00044 #define SERIAL_EVENT_TX_ALL (SERIAL_EVENT_TX_COMPLETE) 00045 /**@}*/ 00046 00047 /** 00048 * @defgroup SerialRXEvents Serial RX Events Macros 00049 * 00050 * @{ 00051 */ 00052 #define SERIAL_EVENT_RX_COMPLETE (1 << (SERIAL_EVENT_RX_SHIFT + 0)) 00053 #define SERIAL_EVENT_RX_OVERRUN_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 1)) 00054 #define SERIAL_EVENT_RX_FRAMING_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 2)) 00055 #define SERIAL_EVENT_RX_PARITY_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 3)) 00056 #define SERIAL_EVENT_RX_OVERFLOW (1 << (SERIAL_EVENT_RX_SHIFT + 4)) 00057 #define SERIAL_EVENT_RX_CHARACTER_MATCH (1 << (SERIAL_EVENT_RX_SHIFT + 5)) 00058 #define SERIAL_EVENT_RX_ALL (SERIAL_EVENT_RX_OVERFLOW | SERIAL_EVENT_RX_PARITY_ERROR | \ 00059 SERIAL_EVENT_RX_FRAMING_ERROR | SERIAL_EVENT_RX_OVERRUN_ERROR | \ 00060 SERIAL_EVENT_RX_COMPLETE | SERIAL_EVENT_RX_CHARACTER_MATCH) 00061 /**@}*/ 00062 00063 #define SERIAL_RESERVED_CHAR_MATCH (255) 00064 00065 typedef enum { 00066 ParityNone = 0, 00067 ParityOdd = 1, 00068 ParityEven = 2, 00069 ParityForced1 = 3, 00070 ParityForced0 = 4 00071 } SerialParity; 00072 00073 /** Serial interrupt sources 00074 */ 00075 typedef enum { 00076 RxIrq, /**< Receive Data Register Full */ 00077 TxIrq /**< Transmit Data Register Empty */ 00078 } SerialIrq; 00079 00080 typedef enum { 00081 FlowControlNone, 00082 FlowControlRTS, 00083 FlowControlCTS, 00084 FlowControlRTSCTS 00085 } FlowControl; 00086 00087 typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event); 00088 00089 #if DEVICE_SERIAL_ASYNCH 00090 /** Asynch serial HAL structure 00091 */ 00092 typedef struct { 00093 struct serial_s serial; /**< Target specific serial structure */ 00094 struct buffer_s tx_buff; /**< TX buffer */ 00095 struct buffer_s rx_buff; /**< RX buffer */ 00096 uint8_t char_match; /**< Character to be matched */ 00097 uint8_t char_found; /**< State of the matched character */ 00098 } serial_t; 00099 00100 #else 00101 /** Non-asynch serial HAL structure 00102 */ 00103 typedef struct serial_s serial_t; 00104 00105 #endif 00106 00107 typedef struct { 00108 int peripheral; 00109 PinName tx_pin; 00110 int tx_function; 00111 PinName rx_pin; 00112 int rx_function; 00113 bool stdio_config; 00114 } serial_pinmap_t; 00115 00116 typedef struct { 00117 int peripheral; 00118 PinName tx_flow_pin; 00119 int tx_flow_function; 00120 PinName rx_flow_pin; 00121 int rx_flow_function; 00122 } serial_fc_pinmap_t; 00123 00124 #ifdef __cplusplus 00125 extern "C" { 00126 #endif 00127 00128 /** 00129 * \defgroup hal_GeneralSerial Serial Configuration Functions 00130 * 00131 * # Defined behavior 00132 * * ::serial_init initializes the ::serial_t 00133 * * ::serial_init sets the default parameters for serial peripheral (9600 bps, 8N1 format) 00134 * * ::serial_init configures the specified pins 00135 * * ::serial_free releases the serial peripheral 00136 * * ::serial_baud configures the baud rate 00137 * * at least 9600 bps the baud rate must be supported 00138 * * ::serial_format configures the transmission format (number of bits, parity and the number of stop bits) 00139 * * at least 8N1 format must be supported 00140 * * ::serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires. 00141 * * ::serial_irq_set enables or disables the serial RX or TX IRQ. 00142 * * If `RxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever 00143 * Receive Data Register Full IRQ is generated. 00144 * * If `TxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever 00145 * Transmit Data Register Empty IRQ is generated. 00146 * * If the interrupt condition holds true, when the interrupt is enabled with ::serial_irq_set, 00147 * the ::serial_irq_handler is called instantly. 00148 * * ::serial_getc returns the character from serial buffer. 00149 * * ::serial_getc is a blocking call (waits for the character). 00150 * * ::serial_putc sends a character. 00151 * * ::serial_putc is a blocking call (waits for a peripheral to be available). 00152 * * ::serial_readable returns non-zero value if a character can be read, 0 otherwise. 00153 * * ::serial_writable returns non-zero value if a character can be written, 0 otherwise. 00154 * * ::serial_clear clears the ::serial_t RX/TX buffers 00155 * * ::serial_break_set sets the break signal. 00156 * * ::serial_break_clear clears the break signal. 00157 * * ::serial_pinout_tx configures the TX pin as an output (to be used in half-duplex mode). 00158 * * ::serial_set_flow_control configures serial flow control. 00159 * * ::serial_set_flow_control sets flow control in the hardware if a serial peripheral supports it, 00160 * otherwise software emulation is used. 00161 * * ::serial_tx_asynch starts the serial asynchronous transfer. 00162 * * ::serial_tx_asynch writes `tx_length` bytes from the `tx` to the bus. 00163 * * ::serial_tx_asynch must support 8 data bits 00164 * * The callback given to ::serial_tx_asynch is invoked when the transfer completes. 00165 * * ::serial_tx_asynch specifies the logical OR of events to be registered. 00166 * * The ::serial_tx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm. 00167 * * ::serial_rx_asynch starts the serial asynchronous transfer. 00168 * * ::serial_rx_asynch reads `rx_length` bytes to the `rx` buffer. 00169 * * ::serial_rx_asynch must support 8 data bits 00170 * * The callback given to ::serial_rx_asynch is invoked when the transfer completes. 00171 * * ::serial_rx_asynch specifies the logical OR of events to be registered. 00172 * * The ::serial_rx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm. 00173 * * ::serial_rx_asynch specifies a character in range 0-254 to be matched, 255 is a reserved value. 00174 * * If SERIAL_EVENT_RX_CHARACTER_MATCH event is not registered, the `char_match` is ignored. 00175 * * The SERIAL_EVENT_RX_CHARACTER_MATCH event is set in the callback when SERIAL_EVENT_RX_CHARACTER_MATCH event is 00176 * registered AND `char_match` is present in the received data. 00177 * * ::serial_tx_active returns non-zero if the TX transaction is ongoing, 0 otherwise. 00178 * * ::serial_rx_active returns non-zero if the RX transaction is ongoing, 0 otherwise. 00179 * * ::serial_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0. 00180 * * ::serial_irq_handler_asynch takes no longer than one packet transfer time (packet_bits / baudrate) to execute. 00181 * * ::serial_tx_abort_asynch aborts the ongoing TX transaction. 00182 * * ::serial_tx_abort_asynch disables the enabled interupt for TX. 00183 * * ::serial_tx_abort_asynch flushes the TX hardware buffer if TX FIFO is used. 00184 * * ::serial_rx_abort_asynch aborts the ongoing RX transaction. 00185 * * ::serial_rx_abort_asynch disables the enabled interupt for RX. 00186 * * ::serial_rx_abort_asynch flushes the TX hardware buffer if RX FIFO is used. 00187 * * Correct operation guaranteed when interrupt latency is shorter than one packet transfer time (packet_bits / baudrate) 00188 * if the flow control is not used. 00189 * * Correct operation guaranteed regardless of interrupt latency if the flow control is used. 00190 * 00191 * # Undefined behavior 00192 * * Calling ::serial_init multiple times on the same `serial_t` without ::serial_free. 00193 * * Passing invalid pin to ::serial_init, ::serial_pinout_tx. 00194 * * Calling any function other than ::serial_init on am uninitialized or freed `serial_t`. 00195 * * Passing an invalid pointer as `obj` to any function. 00196 * * Passing an invalid pointer as `handler` to ::serial_irq_handler, ::serial_tx_asynch, ::serial_rx_asynch. 00197 * * Calling ::serial_tx_abort while no async TX transfer is being processed. 00198 * * Calling ::serial_rx_abort while no async RX transfer is being processed. 00199 * * Devices behavior is undefined when the interrupt latency is longer than one packet transfer time 00200 * (packet_bits / baudrate) if the flow control is not used. 00201 * @{ 00202 */ 00203 00204 /** 00205 * \defgroup hal_GeneralSerial_tests Serial hal tests 00206 * The Serial HAL tests ensure driver conformance to defined behavior. 00207 * 00208 * To run the Serial hal tests use the command: 00209 * 00210 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-uart 00211 * 00212 */ 00213 00214 /** Initialize the serial peripheral. It sets the default parameters for serial 00215 * peripheral, and configures its specifieds pins. 00216 * 00217 * @param obj The serial object 00218 * @param tx The TX pin name 00219 * @param rx The RX pin name 00220 */ 00221 void serial_init(serial_t *obj, PinName tx, PinName rx); 00222 00223 /** Initialize the serial peripheral. It sets the default parameters for serial 00224 * peripheral, and configures its specifieds pins. 00225 * 00226 * @param obj The serial object 00227 * @param pinmap pointer to structure which holds static pinmap 00228 */ 00229 void serial_init_direct(serial_t *obj, const serial_pinmap_t *pinmap); 00230 00231 00232 /** Release the serial peripheral, not currently invoked. It requires further 00233 * resource management. 00234 * 00235 * @param obj The serial object 00236 */ 00237 void serial_free(serial_t *obj); 00238 00239 /** Configure the baud rate 00240 * 00241 * @param obj The serial object 00242 * @param baudrate The baud rate to be configured 00243 */ 00244 void serial_baud(serial_t *obj, int baudrate); 00245 00246 /** Configure the format. Set the number of bits, parity and the number of stop bits 00247 * 00248 * @param obj The serial object 00249 * @param data_bits The number of data bits 00250 * @param parity The parity 00251 * @param stop_bits The number of stop bits 00252 */ 00253 void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits); 00254 00255 /** The serial interrupt handler registration 00256 * 00257 * @param obj The serial object 00258 * @param handler The interrupt handler which will be invoked when the interrupt fires 00259 * @param id The SerialBase object 00260 */ 00261 void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id); 00262 00263 /** Configure serial interrupt. This function is used for word-approach 00264 * 00265 * @param obj The serial object 00266 * @param irq The serial IRQ type (RX or TX) 00267 * @param enable Set to non-zero to enable events, or zero to disable them 00268 */ 00269 void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable); 00270 00271 /** Get character. This is a blocking call, waiting for a character 00272 * 00273 * @param obj The serial object 00274 */ 00275 int serial_getc(serial_t *obj); 00276 00277 /** Send a character. This is a blocking call, waiting for a peripheral to be available 00278 * for writing 00279 * 00280 * @param obj The serial object 00281 * @param c The character to be sent 00282 */ 00283 void serial_putc(serial_t *obj, int c); 00284 00285 /** Check if the serial peripheral is readable 00286 * 00287 * @param obj The serial object 00288 * @return Non-zero value if a character can be read, 0 if nothing to read 00289 */ 00290 int serial_readable(serial_t *obj); 00291 00292 /** Check if the serial peripheral is writable 00293 * 00294 * @param obj The serial object 00295 * @return Non-zero value if a character can be written, 0 otherwise. 00296 */ 00297 int serial_writable(serial_t *obj); 00298 00299 /** Clear the serial peripheral 00300 * 00301 * @param obj The serial object 00302 */ 00303 void serial_clear(serial_t *obj); 00304 00305 /** Set the break 00306 * 00307 * @param obj The serial object 00308 */ 00309 void serial_break_set(serial_t *obj); 00310 00311 /** Clear the break 00312 * 00313 * @param obj The serial object 00314 */ 00315 void serial_break_clear(serial_t *obj); 00316 00317 /** Configure the TX pin for UART function. 00318 * 00319 * @param tx The pin name used for TX 00320 */ 00321 void serial_pinout_tx(PinName tx); 00322 00323 #if DEVICE_SERIAL_FC 00324 /** Configure the serial for the flow control. It sets flow control in the hardware 00325 * if a serial peripheral supports it, otherwise software emulation is used. 00326 * 00327 * @param obj The serial object 00328 * @param type The type of the flow control. Look at the available FlowControl types. 00329 * @param rxflow The TX pin name 00330 * @param txflow The RX pin name 00331 */ 00332 void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow); 00333 00334 /** Configure the serial for the flow control. It sets flow control in the hardware 00335 * if a serial peripheral supports it, otherwise software emulation is used. 00336 * 00337 * @param obj The serial object 00338 * @param type The type of the flow control. Look at the available FlowControl types. 00339 * @param pinmap Pointer to structure which holds static pinmap 00340 */ 00341 void serial_set_flow_control_direct(serial_t *obj, FlowControl type, const serial_fc_pinmap_t *pinmap); 00342 #endif 00343 00344 /** Get the pins that support Serial TX 00345 * 00346 * Return a PinMap array of pins that support Serial TX. The 00347 * array is terminated with {NC, NC, 0}. 00348 * 00349 * @return PinMap array 00350 */ 00351 const PinMap *serial_tx_pinmap(void); 00352 00353 /** Get the pins that support Serial RX 00354 * 00355 * Return a PinMap array of pins that support Serial RX. The 00356 * array is terminated with {NC, NC, 0}. 00357 * 00358 * @return PinMap array 00359 */ 00360 const PinMap *serial_rx_pinmap(void); 00361 00362 #if DEVICE_SERIAL_FC 00363 /** Get the pins that support Serial CTS 00364 * 00365 * Return a PinMap array of pins that support Serial CTS. The 00366 * array is terminated with {NC, NC, 0}. 00367 * 00368 * @return PinMap array 00369 */ 00370 const PinMap *serial_cts_pinmap(void); 00371 00372 /** Get the pins that support Serial RTS 00373 * 00374 * Return a PinMap array of pins that support Serial RTS. The 00375 * array is terminated with {NC, NC, 0}. 00376 * 00377 * @return PinMap array 00378 */ 00379 const PinMap *serial_rts_pinmap(void); 00380 #endif 00381 00382 #if DEVICE_SERIAL_ASYNCH 00383 00384 /**@}*/ 00385 00386 /** 00387 * \defgroup hal_AsynchSerial Asynchronous Serial Hardware Abstraction Layer 00388 * @{ 00389 */ 00390 00391 /** Begin asynchronous TX transfer. The used buffer is specified in the serial object, 00392 * tx_buff 00393 * 00394 * @param obj The serial object 00395 * @param tx The transmit buffer 00396 * @param tx_length The number of bytes to transmit 00397 * @param tx_width Deprecated argument 00398 * @param handler The serial handler 00399 * @param event The logical OR of events to be registered 00400 * @param hint A suggestion for how to use DMA with this transfer 00401 * @return Returns number of data transfered, otherwise returns 0 00402 */ 00403 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); 00404 00405 /** Begin asynchronous RX transfer (enable interrupt for data collecting) 00406 * The used buffer is specified in the serial object - rx_buff 00407 * 00408 * @param obj The serial object 00409 * @param rx The receive buffer 00410 * @param rx_length The number of bytes to receive 00411 * @param rx_width Deprecated argument 00412 * @param handler The serial handler 00413 * @param event The logical OR of events to be registered 00414 * @param char_match A character in range 0-254 to be matched 00415 * @param hint A suggestion for how to use DMA with this transfer 00416 */ 00417 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); 00418 00419 /** Attempts to determine if the serial peripheral is already in use for TX 00420 * 00421 * @param obj The serial object 00422 * @return Non-zero if the RX transaction is ongoing, 0 otherwise 00423 */ 00424 uint8_t serial_tx_active(serial_t *obj); 00425 00426 /** Attempts to determine if the serial peripheral is already in use for RX 00427 * 00428 * @param obj The serial object 00429 * @return Non-zero if the RX transaction is ongoing, 0 otherwise 00430 */ 00431 uint8_t serial_rx_active(serial_t *obj); 00432 00433 /** The asynchronous TX and RX handler. 00434 * 00435 * @param obj The serial object 00436 * @return Returns event flags if an RX transfer termination condition was met; otherwise returns 0 00437 */ 00438 int serial_irq_handler_asynch(serial_t *obj); 00439 00440 /** Abort the ongoing TX transaction. It disables the enabled interupt for TX and 00441 * flushes the TX hardware buffer if TX FIFO is used 00442 * 00443 * @param obj The serial object 00444 */ 00445 void serial_tx_abort_asynch(serial_t *obj); 00446 00447 /** Abort the ongoing RX transaction. It disables the enabled interrupt for RX and 00448 * flushes the RX hardware buffer if RX FIFO is used 00449 * 00450 * @param obj The serial object 00451 */ 00452 void serial_rx_abort_asynch(serial_t *obj); 00453 00454 /**@}*/ 00455 00456 #endif 00457 00458 #ifdef __cplusplus 00459 } 00460 #endif 00461 00462 #endif 00463 00464 #endif 00465 00466 /** @}*/
Generated on Tue Jul 12 2022 13:54:49 by
