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