Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/mbed-dev-bin/serial_api.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

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