mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
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 "hal/buffer.h" 00025 #include "hal/dma_api.h" 00026 00027 #if DEVICE_SERIAL 00028 00029 #define SERIAL_EVENT_TX_SHIFT (2) 00030 #define SERIAL_EVENT_RX_SHIFT (8) 00031 00032 #define SERIAL_EVENT_TX_MASK (0x00FC) 00033 #define SERIAL_EVENT_RX_MASK (0x3F00) 00034 00035 #define SERIAL_EVENT_ERROR (1 << 1) 00036 00037 /** 00038 * @defgroup SerialTXEvents Serial TX Events Macros 00039 * 00040 * @{ 00041 */ 00042 #define SERIAL_EVENT_TX_COMPLETE (1 << (SERIAL_EVENT_TX_SHIFT + 0)) 00043 #define SERIAL_EVENT_TX_ALL (SERIAL_EVENT_TX_COMPLETE) 00044 /**@}*/ 00045 00046 /** 00047 * @defgroup SerialRXEvents Serial RX Events Macros 00048 * 00049 * @{ 00050 */ 00051 #define SERIAL_EVENT_RX_COMPLETE (1 << (SERIAL_EVENT_RX_SHIFT + 0)) 00052 #define SERIAL_EVENT_RX_OVERRUN_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 1)) 00053 #define SERIAL_EVENT_RX_FRAMING_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 2)) 00054 #define SERIAL_EVENT_RX_PARITY_ERROR (1 << (SERIAL_EVENT_RX_SHIFT + 3)) 00055 #define SERIAL_EVENT_RX_OVERFLOW (1 << (SERIAL_EVENT_RX_SHIFT + 4)) 00056 #define SERIAL_EVENT_RX_CHARACTER_MATCH (1 << (SERIAL_EVENT_RX_SHIFT + 5)) 00057 #define SERIAL_EVENT_RX_ALL (SERIAL_EVENT_RX_OVERFLOW | SERIAL_EVENT_RX_PARITY_ERROR | \ 00058 SERIAL_EVENT_RX_FRAMING_ERROR | SERIAL_EVENT_RX_OVERRUN_ERROR | \ 00059 SERIAL_EVENT_RX_COMPLETE | SERIAL_EVENT_RX_CHARACTER_MATCH) 00060 /**@}*/ 00061 00062 #define SERIAL_RESERVED_CHAR_MATCH (255) 00063 00064 typedef enum { 00065 ParityNone = 0, 00066 ParityOdd = 1, 00067 ParityEven = 2, 00068 ParityForced1 = 3, 00069 ParityForced0 = 4 00070 } SerialParity; 00071 00072 typedef enum { 00073 RxIrq, 00074 TxIrq 00075 } SerialIrq; 00076 00077 typedef enum { 00078 FlowControlNone, 00079 FlowControlRTS, 00080 FlowControlCTS, 00081 FlowControlRTSCTS 00082 } FlowControl; 00083 00084 typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event); 00085 00086 #if DEVICE_SERIAL_ASYNCH 00087 /** Asynch serial HAL structure 00088 */ 00089 typedef struct { 00090 struct serial_s serial; /**< Target specific serial structure */ 00091 struct buffer_s tx_buff; /**< TX buffer */ 00092 struct buffer_s rx_buff; /**< RX buffer */ 00093 uint8_t char_match; /**< Character to be matched */ 00094 uint8_t char_found; /**< State of the matched character */ 00095 } serial_t; 00096 00097 #else 00098 /** Non-asynch serial HAL structure 00099 */ 00100 typedef struct serial_s serial_t; 00101 00102 #endif 00103 00104 #ifdef __cplusplus 00105 extern "C" { 00106 #endif 00107 00108 /** 00109 * \defgroup hal_GeneralSerial Serial Configuration Functions 00110 * @{ 00111 */ 00112 00113 /** Initialize the serial peripheral. It sets the default parameters for serial 00114 * peripheral, and configures its specifieds pins. 00115 * 00116 * @param obj The serial object 00117 * @param tx The TX pin name 00118 * @param rx The RX pin name 00119 */ 00120 void serial_init(serial_t *obj, PinName tx, PinName rx); 00121 00122 /** Release the serial peripheral, not currently invoked. It requires further 00123 * resource management. 00124 * 00125 * @param obj The serial object 00126 */ 00127 void serial_free(serial_t *obj); 00128 00129 /** Configure the baud rate 00130 * 00131 * @param obj The serial object 00132 * @param baudrate The baud rate to be configured 00133 */ 00134 void serial_baud(serial_t *obj, int baudrate); 00135 00136 /** Configure the format. Set the number of bits, parity and the number of stop bits 00137 * 00138 * @param obj The serial object 00139 * @param data_bits The number of data bits 00140 * @param parity The parity 00141 * @param stop_bits The number of stop bits 00142 */ 00143 void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits); 00144 00145 /** The serial interrupt handler registration 00146 * 00147 * @param obj The serial object 00148 * @param handler The interrupt handler which will be invoked when the interrupt fires 00149 * @param id The SerialBase object 00150 */ 00151 void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id); 00152 00153 /** Configure serial interrupt. This function is used for word-approach 00154 * 00155 * @param obj The serial object 00156 * @param irq The serial IRQ type (RX or TX) 00157 * @param enable Set to non-zero to enable events, or zero to disable them 00158 */ 00159 void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable); 00160 00161 /** Get character. This is a blocking call, waiting for a character 00162 * 00163 * @param obj The serial object 00164 */ 00165 int serial_getc(serial_t *obj); 00166 00167 /** Send a character. This is a blocking call, waiting for a peripheral to be available 00168 * for writing 00169 * 00170 * @param obj The serial object 00171 * @param c The character to be sent 00172 */ 00173 void serial_putc(serial_t *obj, int c); 00174 00175 /** Check if the serial peripheral is readable 00176 * 00177 * @param obj The serial object 00178 * @return Non-zero value if a character can be read, 0 if nothing to read 00179 */ 00180 int serial_readable(serial_t *obj); 00181 00182 /** Check if the serial peripheral is writable 00183 * 00184 * @param obj The serial object 00185 * @return Non-zero value if a character can be written, 0 otherwise. 00186 */ 00187 int serial_writable(serial_t *obj); 00188 00189 /** Clear the serial peripheral 00190 * 00191 * @param obj The serial object 00192 */ 00193 void serial_clear(serial_t *obj); 00194 00195 /** Set the break 00196 * 00197 * @param obj The serial object 00198 */ 00199 void serial_break_set(serial_t *obj); 00200 00201 /** Clear the break 00202 * 00203 * @param obj The serial object 00204 */ 00205 void serial_break_clear(serial_t *obj); 00206 00207 /** Configure the TX pin for UART function. 00208 * 00209 * @param tx The pin name used for TX 00210 */ 00211 void serial_pinout_tx(PinName tx); 00212 00213 /** Configure the serial for the flow control. It sets flow control in the hardware 00214 * if a serial peripheral supports it, otherwise software emulation is used. 00215 * 00216 * @param obj The serial object 00217 * @param type The type of the flow control. Look at the available FlowControl types. 00218 * @param rxflow The TX pin name 00219 * @param txflow The RX pin name 00220 */ 00221 void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow); 00222 00223 #if DEVICE_SERIAL_ASYNCH 00224 00225 /**@}*/ 00226 00227 /** 00228 * \defgroup hal_AsynchSerial Asynchronous Serial Hardware Abstraction Layer 00229 * @{ 00230 */ 00231 00232 /** Begin asynchronous TX transfer. The used buffer is specified in the serial object, 00233 * tx_buff 00234 * 00235 * @param obj The serial object 00236 * @param tx The transmit buffer 00237 * @param tx_length The number of bytes to transmit 00238 * @param tx_width Deprecated argument 00239 * @param handler The serial handler 00240 * @param event The logical OR of events to be registered 00241 * @param hint A suggestion for how to use DMA with this transfer 00242 * @return Returns number of data transfered, otherwise returns 0 00243 */ 00244 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); 00245 00246 /** Begin asynchronous RX transfer (enable interrupt for data collecting) 00247 * The used buffer is specified in the serial object - rx_buff 00248 * 00249 * @param obj The serial object 00250 * @param rx The receive buffer 00251 * @param rx_length The number of bytes to receive 00252 * @param rx_width Deprecated argument 00253 * @param handler The serial handler 00254 * @param event The logical OR of events to be registered 00255 * @param handler The serial handler 00256 * @param char_match A character in range 0-254 to be matched 00257 * @param hint A suggestion for how to use DMA with this transfer 00258 */ 00259 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); 00260 00261 /** Attempts to determine if the serial peripheral is already in use for TX 00262 * 00263 * @param obj The serial object 00264 * @return Non-zero if the RX transaction is ongoing, 0 otherwise 00265 */ 00266 uint8_t serial_tx_active(serial_t *obj); 00267 00268 /** Attempts to determine if the serial peripheral is already in use for RX 00269 * 00270 * @param obj The serial object 00271 * @return Non-zero if the RX transaction is ongoing, 0 otherwise 00272 */ 00273 uint8_t serial_rx_active(serial_t *obj); 00274 00275 /** The asynchronous TX and RX handler. 00276 * 00277 * @param obj The serial object 00278 * @return Returns event flags if an RX transfer termination condition was met; otherwise returns 0 00279 */ 00280 int serial_irq_handler_asynch(serial_t *obj); 00281 00282 /** Abort the ongoing TX transaction. It disables the enabled interupt for TX and 00283 * flushes the TX hardware buffer if TX FIFO is used 00284 * 00285 * @param obj The serial object 00286 */ 00287 void serial_tx_abort_asynch(serial_t *obj); 00288 00289 /** Abort the ongoing RX transaction. It disables the enabled interrupt for RX and 00290 * flushes the RX hardware buffer if RX FIFO is used 00291 * 00292 * @param obj The serial object 00293 */ 00294 void serial_rx_abort_asynch(serial_t *obj); 00295 00296 /**@}*/ 00297 00298 #endif 00299 00300 #ifdef __cplusplus 00301 } 00302 #endif 00303 00304 #endif 00305 00306 #endif 00307 00308 /** @}*/
Generated on Tue Jul 12 2022 20:41:15 by 1.7.2