ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
fsl_uart_driver.h
Go to the documentation of this file.
1 /*!
2 ********************************************************************************
3 * File: fsl_uart_driver.h
4 *
5 * Copyright (c) 2014, Freescale Semiconductor, Inc.
6 *
7 *******************************************************************************/
8 /*!
9 * @file fsl_uart_driver.h
10 * @brief \b fsl_uart_driver.h defines structures and types for the i2c master driver.
11 */
12 #ifndef FSL_UART_DRIVER_H_
13 #define FSL_UART_DRIVER_H_
14 
15 #include <stdint.h>
16 #include <stdbool.h>
17 #include "PE_Types.h"
18 #include "mqxlite.h"
19 #include "lwevent.h"
20 #include "fsl_uart_hal.h"
21 
22 /*!
23  * @addtogroup uart_driver
24  * @{
25  */
26 
27 /*******************************************************************************
28  * Definitions
29  ******************************************************************************/
30 
31 /*!
32  * @brief Runtime state of the UART driver.
33  *
34  * This struct holds data that are used by the UART peripheral driver to
35  * communicate between the transfer function and the interrupt handler. The
36  * interrupt handler also uses this information to keep track of its progress.
37  * The user is only responsible to pass in the memory for this run-time state structure where the
38  * UART driver will take care of filling out the members.
39  */
40 typedef struct UartState {
41  uint32_t instance; /*!< UART module instance number. */
42  LDD_TDeviceData* pDeviceHandle; /*!< Pointer to the device handle.*/
43  LWEVENT_STRUCT uartEventHandler;
44 } uart_state_t;
45 
46 #define UART_PEX_WRITE_EVENT_SUCCESS (1)
47 #define UART_PEX_WRITE_EVENT_ERROR (UART_PEX_WRITE_EVENT_SUCCESS << 1)
48 #define UART_PEX_READ_EVENT_SUCCESS (UART_PEX_WRITE_EVENT_ERROR << 1)
49 #define UART_PEX_READ_EVENT_ERROR (UART_PEX_READ_EVENT_SUCCESS << 1)
50 /*!
51  * @brief User configuration structure for UART driver.
52  *
53  * Use an instance of this struct with uart_init(). This allows you to configure the
54  * most common settings of the UART peripheral with a single function call. Settings include:
55  * UART baud rate; UART parity mode: disabled (default), or even or odd; the number of stop bits;
56  * the number of bits per data word.
57  */
58 typedef struct UartUserConfig {
59  uint32_t baudRate; /*!< UART baud rate*/
60  uart_parity_mode_t parityMode; /*!< parity mode, disabled (default), even, odd */
61  uart_stop_bit_count_t stopBitCount; /*!< number of stop bits, 1 stop bit (default)
62  or 2 stop bits */
63  uart_bit_count_per_char_t bitCountPerChar; /*!< number of bits, 8-bit (default) or 9-bit in
64  a word (up to 10-bits in some UART instances) */
66 
67 /*******************************************************************************
68  * API
69  ******************************************************************************/
70 
71 #if defined(__cplusplus)
72 extern "C" {
73 #endif
74 
75 /*!
76  * @brief This function initializes a UART instance for operation.
77  *
78  * This function will initialize the run-time state structure to keep track of the on-going
79  * transfers, ungate the clock to the UART module, initialize the module
80  * to user defined settings and default settings, configure the IRQ state structure and enable
81  * the module-level interrupt to the core, and enable the UART module transmitter and receiver.
82  * The following is an example of how to set up the uart_state_t and the
83  * uart_user_config_t parameters and how to call the uart_init function by passing
84  * in these parameters:
85  @code
86  uart_user_config_t uartConfig;
87  uartConfig.baudRate = 9600;
88  uartConfig.bitCountPerChar = kUart8BitsPerChar;
89  uartConfig.parityMode = kUartParityDisabled;
90  uartConfig.stopBitCount = kUartOneStopBit;
91  uart_state_t uartState;
92  uart_init(uartInstance, &uartState, &uartConfig);
93  @endcode
94  *
95  * @param uartInstance The UART module instance number.
96  * @param uartState A pointer to the UART driver state structure memory. The user is only
97  * responsible to pass in the memory for this run-time state structure where the UART driver
98  * will take care of filling out the members. This run-time state structure keeps track of the
99  * current transfer in progress.
100  * @param uartUserConfig The user configuration structure of type uart_user_config_t. The user
101  * is responsbile to fill out the members of this structure and to pass the pointer of this struct
102  * into this function.
103  * @return An error code or kStatus_UART_Success.
104  */
105 uart_status_t uart_init(uint32_t uartInstance, uart_state_t * uartState,
106  const uart_user_config_t * uartUserConfig);
107 
108 /*!
109  * @brief This function sends (transmits) data out through the UART module using a blocking method.
110  *
111  * A blocking (also known as synchronous) function means that the function does not return until
112  * the transmit is complete. This blocking function is used to send data through the UART port.
113  *
114  * @param uartState The UART module internal state information.
115  * @param sendBuffer A pointer to the source buffer containing 8-bit data chars to send.
116  * @param txByteCount The number of bytes to send.
117  * @param timeout A timeout value for RTOS abstraction sync control in milli-seconds (ms).
118  * @return An error code or kStatus_UART_Success.
119  */
120 uart_status_t uart_send_data(uart_state_t * uartState, const uint8_t * sendBuffer,
121  uint32_t txByteCount, uint32_t timeout);
122 
123 /*!
124  * @brief This function sends (transmits) data through the UART module using a non-blocking method.
125  *
126  * A non-blocking (also known as synchronous) function means that the function returns
127  * immediately after initiating the transmit function. The application has to get the
128  * transmit status to see when the transmit is complete. In other words, after calling non-blocking
129  * (asynchronous) send function, the application must get the transmit status to check if transmit
130  * is completed or not.
131  * The asynchronous method of transmitting and receiving allows the UART to perform a full duplex
132  * operation (simultaneously transmit and receive).
133  *
134  * @param uartState A pointer to the UART driver state structure.
135  * @param sendBuffer A pointer to the source buffer containing 8-bit data chars to send.
136  * @param txByteCount The number of bytes to send.
137  * @return An error code or kStatus_UART_Success.
138  */
139 uart_status_t uart_send_data_async(uart_state_t * uartState, const uint8_t * sendBuffer,
140  uint32_t txByteCount);
141 
142 /*!
143  * @brief This function returns whether the previous UART transmit has finished.
144  *
145  * When performing an async transmit, the user can call this function to ascertain the state of the
146  * current transmission: in progress (or busy) or complete (success). In addition, if the
147  * transmission is still in progress, the user can obtain the number of words that have been
148  * currently transferred.
149  *
150  * @param uartState A pointer to the UART driver state structure.
151  * @param bytesTransmitted A pointer to a value that is filled in with the number of bytes that
152  * are sent in the active transfer.
153  *
154  * @retval kStatus_UART_Success The transmit has completed successfully.
155  * @retval kStatus_UART_TxBusy The transmit is still in progress. @a bytesTransmitted is
156  * filled with the number of bytes which are transmitted up to that point.
157  */
158 uart_status_t uart_get_transmit_status(uart_state_t * uartState, uint32_t * bytesTransmitted);
159 
160 /*!
161  * @brief This function returns whether the previous UART receive is complete.
162  *
163  * When performing an async receive, the user can call this function to ascertain the state of the
164  * current receive progress: in progress (or busy) or complete (success). In addition, if the
165  * receive is still in progress, the user can obtain the number of words that have been
166  * currently received.
167  *
168  * @param uartState A pointer to the UART driver state structure.
169  * @param bytesReceived A pointer to a value that is filled in with the number of bytes which
170  * are received in the active transfer.
171  *
172  * @retval kStatus_UART_Success The receive has completed successfully.
173  * @retval kStatus_UART_RxBusy The receive is still in progress. @a bytesReceived is
174  * filled with the number of bytes which are received up to that point.
175  */
176 uart_status_t uart_get_receive_status(uart_state_t * uartState, uint32_t * bytesReceived);
177 
178 /*!
179  * @brief This function gets (receives) data from the UART module using a blocking method.
180  *
181  * A blocking (also known as synchronous) function means that the function does not return until
182  * the receive is complete. This blocking function is used to send data through the UART port.
183  *
184  * @param uartState A pointer to the UART driver state structure.
185  * @param rxBuffer A pointer to the buffer containing 8-bit read data chars received.
186  * @param requestedByteCount The number of bytes to receive.
187  * @param timeout A timeout value for RTOS abstraction sync control in milli-seconds (ms).
188  * @return An error code or kStatus_UART_Success.
189  */
190 uart_status_t uart_receive_data(uart_state_t * uartState, uint8_t * rxBuffer,
191  uint32_t requestedByteCount, uint32_t timeout);
192 
193 /*!
194  * @brief This function gets (receives) data from the UART module using a non-blocking method.
195  *
196  * A non-blocking (also known as synchronous) function means that the function returns
197  * immediately after initiating the receive function. The application has to get the
198  * receive status to see when the receive is complete. In other words, after calling non-blocking
199  * (asynchronous) get function, the application must get the receive status to check if receive
200  * is completed or not.
201  * The asynchronous method of transmitting and receiving allows the UART to perform a full duplex
202  * operation (simultaneously transmit and receive).
203  *
204  * @param uartState A pointer to the UART driver state structure.
205  * @param rxBuffer A pointer to the buffer containing 8-bit read data chars received.
206  * @param requestedByteCount The number of bytes to receive.
207  * @return An error code or kStatus_UART_Success.
208  */
209 uart_status_t uart_receive_data_async(uart_state_t * uartState, uint8_t * rxBuffer,
210  uint32_t requestedByteCount);
211 
212 
213 #if defined(__cplusplus)
214 }
215 #endif
216 
217 /*******************************************************************************
218  * EOF
219  ******************************************************************************/
220 
221 /*! @}*/
222 #endif /* FSL_UART_DRIVER_H_ */
223 
User configuration structure for UART driver.
uart_status_t uart_receive_data_async(uart_state_t *uartState, uint8_t *rxBuffer, uint32_t requestedByteCount)
This function gets (receives) data from the UART module using a non-blocking method.
uart_status_t uart_get_transmit_status(uart_state_t *uartState, uint32_t *bytesTransmitted)
This function returns whether the previous UART transmit has finished.
uint32_t instance
enum _uart_stop_bit_count uart_stop_bit_count_t
UART number of stop bits.
uart_parity_mode_t parityMode
uart_status_t uart_get_receive_status(uart_state_t *uartState, uint32_t *bytesReceived)
This function returns whether the previous UART receive is complete.
enum _uart_parity_mode uart_parity_mode_t
UART parity mode.
Runtime state of the UART driver.
enum _uart_bit_count_per_char uart_bit_count_per_char_t
UART number of bits in a character.
uart_status_t uart_send_data_async(uart_state_t *uartState, const uint8_t *sendBuffer, uint32_t txByteCount)
This function sends (transmits) data through the UART module using a non-blocking method...
uart_status_t uart_init(uint32_t uartInstance, uart_state_t *uartState, const uart_user_config_t *uartUserConfig)
This function initializes a UART instance for operation.
enum _uart_status uart_status_t
Error codes for the UART driver.
uart_bit_count_per_char_t bitCountPerChar
uart_status_t uart_receive_data(uart_state_t *uartState, uint8_t *rxBuffer, uint32_t requestedByteCount, uint32_t timeout)
This function gets (receives) data from the UART module using a blocking method.
uart_status_t uart_send_data(uart_state_t *uartState, const uint8_t *sendBuffer, uint32_t txByteCount, uint32_t timeout)
This function sends (transmits) data out through the UART module using a blocking method...
uart_stop_bit_count_t stopBitCount
LDD_TDeviceData * pDeviceHandle
LWEVENT_STRUCT uartEventHandler
fsl_uart_hal.h defines structures and types for the i2c master HAL layer.
struct UartUserConfig uart_user_config_t
User configuration structure for UART driver.
struct UartState uart_state_t
Runtime state of the UART driver.