EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

hal/serial_api.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

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