serial_api.h

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