serial_api.h

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