BA / Mbed OS BaBoRo_test2

Backup 1

mbed-os/hal/serial_api.h@0:02dd72d1d465, 2018-04-24 (annotated)

Committer:
borlanic
Date:
Tue Apr 24 11:45:18 2018 +0000
Revision:
0:02dd72d1d465
BaBoRo_test2 - backup 1

Who changed what in which revision?

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