mbed official / mbed-src

mbed library sources

Dependents:   Encrypted my_mbed lklk CyaSSL_DTLS_Cellular ... more

Superseded

This library was superseded by mbed-dev - https://os.mbed.com/users/mbed_official/code/mbed-dev/.

Development branch of the mbed library sources. This library is kept in synch with the latest changes from the mbed SDK and it is not guaranteed to work.

If you are looking for a stable and tested release, please import one of the official mbed library releases:

Import librarymbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Last commit 20 Feb 2019 by mbed official

hal/serial_api.h@635:a11c0372f0ba, 2015-09-30 (annotated)

Committer:
mbed_official
Date:
Wed Sep 30 17:00:09 2015 +0100
Revision:
635:a11c0372f0ba
Parent:
563:536c9fb088a0 
Synchronized with git revision d29c98dae61be0946ddf3a3c641c7726056f9452



Full URL: https://github.com/mbedmicro/mbed/commit/d29c98dae61be0946ddf3a3c641c7726056f9452/



Added support for SAMW25

Who changed what in which revision?

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