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 "pinmap.h"
00025 #include "hal/buffer.h"
00026 #include "hal/dma_api.h"
00027 
00028 #if DEVICE_SERIAL
00029 
00030 #define SERIAL_EVENT_TX_SHIFT (2)
00031 #define SERIAL_EVENT_RX_SHIFT (8)
00032 
00033 #define SERIAL_EVENT_TX_MASK (0x00FC)
00034 #define SERIAL_EVENT_RX_MASK (0x3F00)
00035 
00036 #define SERIAL_EVENT_ERROR (1 << 1)
00037 
00038 /**
00039  * @defgroup SerialTXEvents Serial TX Events Macros
00040  *
00041  * @{
00042  */
00043 #define SERIAL_EVENT_TX_COMPLETE (1 << (SERIAL_EVENT_TX_SHIFT + 0))
00044 #define SERIAL_EVENT_TX_ALL      (SERIAL_EVENT_TX_COMPLETE)
00045 /**@}*/
00046 
00047 /**
00048  * @defgroup SerialRXEvents Serial RX Events Macros
00049  *
00050  * @{
00051  */
00052 #define SERIAL_EVENT_RX_COMPLETE        (1 << (SERIAL_EVENT_RX_SHIFT + 0))
00053 #define SERIAL_EVENT_RX_OVERRUN_ERROR   (1 << (SERIAL_EVENT_RX_SHIFT + 1))
00054 #define SERIAL_EVENT_RX_FRAMING_ERROR   (1 << (SERIAL_EVENT_RX_SHIFT + 2))
00055 #define SERIAL_EVENT_RX_PARITY_ERROR    (1 << (SERIAL_EVENT_RX_SHIFT + 3))
00056 #define SERIAL_EVENT_RX_OVERFLOW        (1 << (SERIAL_EVENT_RX_SHIFT + 4))
00057 #define SERIAL_EVENT_RX_CHARACTER_MATCH (1 << (SERIAL_EVENT_RX_SHIFT + 5))
00058 #define SERIAL_EVENT_RX_ALL             (SERIAL_EVENT_RX_OVERFLOW | SERIAL_EVENT_RX_PARITY_ERROR | \
00059                                          SERIAL_EVENT_RX_FRAMING_ERROR | SERIAL_EVENT_RX_OVERRUN_ERROR | \
00060                                          SERIAL_EVENT_RX_COMPLETE | SERIAL_EVENT_RX_CHARACTER_MATCH)
00061 /**@}*/
00062 
00063 #define SERIAL_RESERVED_CHAR_MATCH (255)
00064 
00065 typedef enum {
00066     ParityNone = 0,
00067     ParityOdd = 1,
00068     ParityEven = 2,
00069     ParityForced1 = 3,
00070     ParityForced0 = 4
00071 } SerialParity;
00072 
00073 /** Serial interrupt sources
00074  */
00075 typedef enum {
00076     RxIrq,      /**< Receive Data Register Full */
00077     TxIrq       /**< Transmit Data Register Empty */
00078 } SerialIrq;
00079 
00080 typedef enum {
00081     FlowControlNone,
00082     FlowControlRTS,
00083     FlowControlCTS,
00084     FlowControlRTSCTS
00085 } FlowControl;
00086 
00087 typedef void (*uart_irq_handler)(uint32_t id, SerialIrq event);
00088 
00089 #if DEVICE_SERIAL_ASYNCH
00090 /** Asynch serial HAL structure
00091  */
00092 typedef struct {
00093     struct serial_s serial;  /**< Target specific serial structure */
00094     struct buffer_s tx_buff; /**< TX buffer */
00095     struct buffer_s rx_buff; /**< RX buffer */
00096     uint8_t char_match;      /**< Character to be matched */
00097     uint8_t char_found;      /**< State of the matched character */
00098 } serial_t;
00099 
00100 #else
00101 /** Non-asynch serial HAL structure
00102  */
00103 typedef struct serial_s serial_t;
00104 
00105 #endif
00106 
00107 typedef struct {
00108     int peripheral;
00109     PinName tx_pin;
00110     int tx_function;
00111     PinName rx_pin;
00112     int rx_function;
00113     bool stdio_config;
00114 } serial_pinmap_t;
00115 
00116 typedef struct {
00117     int peripheral;
00118     PinName tx_flow_pin;
00119     int tx_flow_function;
00120     PinName rx_flow_pin;
00121     int rx_flow_function;
00122 } serial_fc_pinmap_t;
00123 
00124 #ifdef __cplusplus
00125 extern "C" {
00126 #endif
00127 
00128 /**
00129  * \defgroup hal_GeneralSerial Serial Configuration Functions
00130  *
00131  * # Defined behavior
00132  * * ::serial_init initializes the ::serial_t
00133  * * ::serial_init sets the default parameters for serial peripheral (9600 bps, 8N1 format)
00134  * * ::serial_init configures the specified pins
00135  * * ::serial_free releases the serial peripheral
00136  * * ::serial_baud configures the baud rate
00137  * * at least 9600 bps the baud rate  must be supported
00138  * * ::serial_format configures the transmission format (number of bits, parity and the number of stop bits)
00139  * * at least 8N1 format must be supported
00140  * * ::serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires.
00141  * * ::serial_irq_set enables or disables the serial RX or TX IRQ.
00142  * * If `RxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever
00143  * Receive Data Register Full IRQ is generated.
00144  * * If `TxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever
00145  * Transmit Data Register Empty IRQ is generated.
00146  * * If the interrupt condition holds true, when the interrupt is enabled with ::serial_irq_set,
00147  * the ::serial_irq_handler is called instantly.
00148  * * ::serial_getc returns the character from serial buffer.
00149  * * ::serial_getc is a blocking call (waits for the character).
00150  * * ::serial_putc sends a character.
00151  * * ::serial_putc is a blocking call (waits for a peripheral to be available).
00152  * * ::serial_readable returns non-zero value if a character can be read, 0 otherwise.
00153  * * ::serial_writable returns non-zero value if a character can be written, 0 otherwise.
00154  * * ::serial_clear clears the ::serial_t RX/TX buffers
00155  * * ::serial_break_set sets the break signal.
00156  * * ::serial_break_clear clears the break signal.
00157  * * ::serial_pinout_tx configures the TX pin as an output (to be used in half-duplex mode).
00158  * * ::serial_set_flow_control configures serial flow control.
00159  * * ::serial_set_flow_control sets flow control in the hardware if a serial peripheral supports it,
00160  * otherwise software emulation is used.
00161  * * ::serial_tx_asynch starts the serial asynchronous transfer.
00162  * * ::serial_tx_asynch writes `tx_length` bytes from the `tx` to the bus.
00163  * * ::serial_tx_asynch must support 8 data bits
00164  * * The callback given to ::serial_tx_asynch is invoked when the transfer completes.
00165  * * ::serial_tx_asynch specifies the logical OR of events to be registered.
00166  * * The ::serial_tx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
00167  * * ::serial_rx_asynch starts the serial asynchronous transfer.
00168  * * ::serial_rx_asynch reads `rx_length` bytes to the `rx` buffer.
00169  * * ::serial_rx_asynch must support 8 data bits
00170  * * The callback given to ::serial_rx_asynch is invoked when the transfer completes.
00171  * * ::serial_rx_asynch specifies the logical OR of events to be registered.
00172  * * The ::serial_rx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
00173  * * ::serial_rx_asynch specifies a character in range 0-254 to be matched, 255 is a reserved value.
00174  * * If SERIAL_EVENT_RX_CHARACTER_MATCH event is not registered, the `char_match` is ignored.
00175  * * The SERIAL_EVENT_RX_CHARACTER_MATCH event is set in the callback when SERIAL_EVENT_RX_CHARACTER_MATCH event is
00176  * registered AND `char_match` is present in the received data.
00177  * * ::serial_tx_active returns non-zero if the TX transaction is ongoing, 0 otherwise.
00178  * * ::serial_rx_active returns non-zero if the RX transaction is ongoing, 0 otherwise.
00179  * * ::serial_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
00180  * * ::serial_irq_handler_asynch takes no longer than one packet transfer time (packet_bits / baudrate) to execute.
00181  * * ::serial_tx_abort_asynch aborts the ongoing TX transaction.
00182  * * ::serial_tx_abort_asynch disables the enabled interupt for TX.
00183  * * ::serial_tx_abort_asynch flushes the TX hardware buffer if TX FIFO is used.
00184  * * ::serial_rx_abort_asynch aborts the ongoing RX transaction.
00185  * * ::serial_rx_abort_asynch disables the enabled interupt for RX.
00186  * * ::serial_rx_abort_asynch flushes the TX hardware buffer if RX FIFO is used.
00187  * * Correct operation guaranteed when interrupt latency is shorter than one packet transfer time (packet_bits / baudrate)
00188  * if the flow control is not used.
00189  * * Correct operation guaranteed regardless of interrupt latency if the flow control is used.
00190  *
00191  * # Undefined behavior
00192  * * Calling ::serial_init multiple times on the same `serial_t` without ::serial_free.
00193  * * Passing invalid pin to ::serial_init, ::serial_pinout_tx.
00194  * * Calling any function other than ::serial_init on am uninitialized or freed `serial_t`.
00195  * * Passing an invalid pointer as `obj` to any function.
00196  * * Passing an invalid pointer as `handler` to ::serial_irq_handler, ::serial_tx_asynch, ::serial_rx_asynch.
00197  * * Calling ::serial_tx_abort while no async TX transfer is being processed.
00198  * * Calling ::serial_rx_abort while no async RX transfer is being processed.
00199  * * Devices behavior is undefined when the interrupt latency is longer than one packet transfer time
00200  * (packet_bits / baudrate) if the flow control is not used.
00201  * @{
00202  */
00203 
00204 /**
00205  * \defgroup hal_GeneralSerial_tests Serial hal tests
00206  * The Serial HAL tests ensure driver conformance to defined behavior.
00207  *
00208  * To run the Serial hal tests use the command:
00209  *
00210  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-uart
00211  *
00212  */
00213 
00214 /** Initialize the serial peripheral. It sets the default parameters for serial
00215  *  peripheral, and configures its specifieds pins.
00216  *
00217  * @param obj The serial object
00218  * @param tx  The TX pin name
00219  * @param rx  The RX pin name
00220  */
00221 void serial_init(serial_t *obj, PinName tx, PinName rx);
00222 
00223 /** Initialize the serial peripheral. It sets the default parameters for serial
00224  *  peripheral, and configures its specifieds pins.
00225  *
00226  * @param obj The serial object
00227  * @param pinmap pointer to structure which holds static pinmap
00228  */
00229 void serial_init_direct(serial_t *obj, const serial_pinmap_t *pinmap);
00230 
00231 
00232 /** Release the serial peripheral, not currently invoked. It requires further
00233  *  resource management.
00234  *
00235  * @param obj The serial object
00236  */
00237 void serial_free(serial_t *obj);
00238 
00239 /** Configure the baud rate
00240  *
00241  * @param obj      The serial object
00242  * @param baudrate The baud rate to be configured
00243  */
00244 void serial_baud(serial_t *obj, int baudrate);
00245 
00246 /** Configure the format. Set the number of bits, parity and the number of stop bits
00247  *
00248  * @param obj       The serial object
00249  * @param data_bits The number of data bits
00250  * @param parity    The parity
00251  * @param stop_bits The number of stop bits
00252  */
00253 void serial_format(serial_t *obj, int data_bits, SerialParity parity, int stop_bits);
00254 
00255 /** The serial interrupt handler registration
00256  *
00257  * @param obj     The serial object
00258  * @param handler The interrupt handler which will be invoked when the interrupt fires
00259  * @param id      The SerialBase object
00260  */
00261 void serial_irq_handler(serial_t *obj, uart_irq_handler handler, uint32_t id);
00262 
00263 /** Configure serial interrupt. This function is used for word-approach
00264  *
00265  * @param obj    The serial object
00266  * @param irq    The serial IRQ type (RX or TX)
00267  * @param enable Set to non-zero to enable events, or zero to disable them
00268  */
00269 void serial_irq_set(serial_t *obj, SerialIrq irq, uint32_t enable);
00270 
00271 /** Get character. This is a blocking call, waiting for a character
00272  *
00273  * @param obj The serial object
00274  */
00275 int  serial_getc(serial_t *obj);
00276 
00277 /** Send a character. This is a blocking call, waiting for a peripheral to be available
00278  *  for writing
00279  *
00280  * @param obj The serial object
00281  * @param c   The character to be sent
00282  */
00283 void serial_putc(serial_t *obj, int c);
00284 
00285 /** Check if the serial peripheral is readable
00286  *
00287  * @param obj The serial object
00288  * @return Non-zero value if a character can be read, 0 if nothing to read
00289  */
00290 int  serial_readable(serial_t *obj);
00291 
00292 /** Check if the serial peripheral is writable
00293  *
00294  * @param obj The serial object
00295  * @return Non-zero value if a character can be written, 0 otherwise.
00296  */
00297 int  serial_writable(serial_t *obj);
00298 
00299 /** Clear the serial peripheral
00300  *
00301  * @param obj The serial object
00302  */
00303 void serial_clear(serial_t *obj);
00304 
00305 /** Set the break
00306  *
00307  * @param obj The serial object
00308  */
00309 void serial_break_set(serial_t *obj);
00310 
00311 /** Clear the break
00312  *
00313  * @param obj The serial object
00314  */
00315 void serial_break_clear(serial_t *obj);
00316 
00317 /** Configure the TX pin for UART function.
00318  *
00319  * @param tx The pin name used for TX
00320  */
00321 void serial_pinout_tx(PinName tx);
00322 
00323 #if DEVICE_SERIAL_FC
00324 /** Configure the serial for the flow control. It sets flow control in the hardware
00325  *  if a serial peripheral supports it, otherwise software emulation is used.
00326  *
00327  * @param obj    The serial object
00328  * @param type   The type of the flow control. Look at the available FlowControl types.
00329  * @param rxflow The TX pin name
00330  * @param txflow The RX pin name
00331  */
00332 void serial_set_flow_control(serial_t *obj, FlowControl type, PinName rxflow, PinName txflow);
00333 
00334 /** Configure the serial for the flow control. It sets flow control in the hardware
00335  *  if a serial peripheral supports it, otherwise software emulation is used.
00336  *
00337  * @param obj    The serial object
00338  * @param type   The type of the flow control. Look at the available FlowControl types.
00339  * @param pinmap Pointer to structure which holds static pinmap
00340  */
00341 void serial_set_flow_control_direct(serial_t *obj, FlowControl type, const serial_fc_pinmap_t *pinmap);
00342 #endif
00343 
00344 /** Get the pins that support Serial TX
00345  *
00346  * Return a PinMap array of pins that support Serial TX. The
00347  * array is terminated with {NC, NC, 0}.
00348  *
00349  * @return PinMap array
00350  */
00351 const PinMap *serial_tx_pinmap(void);
00352 
00353 /** Get the pins that support Serial RX
00354  *
00355  * Return a PinMap array of pins that support Serial RX. The
00356  * array is terminated with {NC, NC, 0}.
00357  *
00358  * @return PinMap array
00359  */
00360 const PinMap *serial_rx_pinmap(void);
00361 
00362 #if DEVICE_SERIAL_FC
00363 /** Get the pins that support Serial CTS
00364  *
00365  * Return a PinMap array of pins that support Serial CTS. The
00366  * array is terminated with {NC, NC, 0}.
00367  *
00368  * @return PinMap array
00369  */
00370 const PinMap *serial_cts_pinmap(void);
00371 
00372 /** Get the pins that support Serial RTS
00373  *
00374  * Return a PinMap array of pins that support Serial RTS. The
00375  * array is terminated with {NC, NC, 0}.
00376  *
00377  * @return PinMap array
00378  */
00379 const PinMap *serial_rts_pinmap(void);
00380 #endif
00381 
00382 #if DEVICE_SERIAL_ASYNCH
00383 
00384 /**@}*/
00385 
00386 /**
00387  * \defgroup hal_AsynchSerial Asynchronous Serial Hardware Abstraction Layer
00388  * @{
00389  */
00390 
00391 /** Begin asynchronous TX transfer. The used buffer is specified in the serial object,
00392  *  tx_buff
00393  *
00394  * @param obj       The serial object
00395  * @param tx        The transmit buffer
00396  * @param tx_length The number of bytes to transmit
00397  * @param tx_width  Deprecated argument
00398  * @param handler   The serial handler
00399  * @param event     The logical OR of events to be registered
00400  * @param hint      A suggestion for how to use DMA with this transfer
00401  * @return Returns number of data transfered, otherwise returns 0
00402  */
00403 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);
00404 
00405 /** Begin asynchronous RX transfer (enable interrupt for data collecting)
00406  *  The used buffer is specified in the serial object - rx_buff
00407  *
00408  * @param obj        The serial object
00409  * @param rx         The receive buffer
00410  * @param rx_length  The number of bytes to receive
00411  * @param rx_width   Deprecated argument
00412  * @param handler    The serial handler
00413  * @param event      The logical OR of events to be registered
00414  * @param char_match A character in range 0-254 to be matched
00415  * @param hint       A suggestion for how to use DMA with this transfer
00416  */
00417 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);
00418 
00419 /** Attempts to determine if the serial peripheral is already in use for TX
00420  *
00421  * @param obj The serial object
00422  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
00423  */
00424 uint8_t serial_tx_active(serial_t *obj);
00425 
00426 /** Attempts to determine if the serial peripheral is already in use for RX
00427  *
00428  * @param obj The serial object
00429  * @return Non-zero if the RX transaction is ongoing, 0 otherwise
00430  */
00431 uint8_t serial_rx_active(serial_t *obj);
00432 
00433 /** The asynchronous TX and RX handler.
00434  *
00435  * @param obj The serial object
00436  * @return Returns event flags if an RX transfer termination condition was met; otherwise returns 0
00437  */
00438 int serial_irq_handler_asynch(serial_t *obj);
00439 
00440 /** Abort the ongoing TX transaction. It disables the enabled interupt for TX and
00441  *  flushes the TX hardware buffer if TX FIFO is used
00442  *
00443  * @param obj The serial object
00444  */
00445 void serial_tx_abort_asynch(serial_t *obj);
00446 
00447 /** Abort the ongoing RX transaction. It disables the enabled interrupt for RX and
00448  *  flushes the RX hardware buffer if RX FIFO is used
00449  *
00450  * @param obj The serial object
00451  */
00452 void serial_rx_abort_asynch(serial_t *obj);
00453 
00454 /**@}*/
00455 
00456 #endif
00457 
00458 #ifdef __cplusplus
00459 }
00460 #endif
00461 
00462 #endif
00463 
00464 #endif
00465 
00466 /** @}*/