3 * All rights reserved.
\r
6 * SPDX-License-Identifier: BSD-3-Clause
\r
9 #ifndef __SERIAL_MANAGER_H__
\r
10 #define __SERIAL_MANAGER_H__
\r
13 * @addtogroup serialmanager
\r
17 /*******************************************************************************
\r
19 ******************************************************************************/
\r
20 #ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING
\r
21 /*! @brief Enable or disable serial manager non-blocking mode (1 - enable, 0 - disable) */
\r
22 #define SERIAL_MANAGER_NON_BLOCKING_MODE (1U)
\r
24 #ifndef SERIAL_MANAGER_NON_BLOCKING_MODE
\r
25 #define SERIAL_MANAGER_NON_BLOCKING_MODE (0U)
\r
29 /*! @brief Enable or disable uart port (1 - enable, 0 - disable) */
\r
30 #ifndef SERIAL_PORT_TYPE_UART
\r
31 #define SERIAL_PORT_TYPE_UART (0U)
\r
34 /*! @brief Enable or disable USB CDC port (1 - enable, 0 - disable) */
\r
35 #ifndef SERIAL_PORT_TYPE_USBCDC
\r
36 #define SERIAL_PORT_TYPE_USBCDC (0U)
\r
39 /*! @brief Enable or disable SWO port (1 - enable, 0 - disable) */
\r
40 #ifndef SERIAL_PORT_TYPE_SWO
\r
41 #define SERIAL_PORT_TYPE_SWO (0U)
\r
44 /*! @brief Enable or disable USB CDC virtual port (1 - enable, 0 - disable) */
\r
45 #ifndef SERIAL_PORT_TYPE_USBCDC_VIRTUAL
\r
46 #define SERIAL_PORT_TYPE_USBCDC_VIRTUAL (0U)
\r
49 /*! @brief Set serial manager write handle size */
\r
50 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))
\r
51 #define SERIAL_MANAGER_WRITE_HANDLE_SIZE (44U)
\r
52 #define SERIAL_MANAGER_READ_HANDLE_SIZE (44U)
\r
54 #define SERIAL_MANAGER_WRITE_HANDLE_SIZE (4U)
\r
55 #define SERIAL_MANAGER_READ_HANDLE_SIZE (4U)
\r
58 #if (defined(SERIAL_PORT_TYPE_UART) && (SERIAL_PORT_TYPE_UART > 0U))
\r
59 #include "serial_port_uart.h"
\r
62 #if (defined(SERIAL_PORT_TYPE_USBCDC) && (SERIAL_PORT_TYPE_USBCDC > 0U))
\r
64 #if !(defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))
\r
65 #error The serial manager blocking mode cannot be supported for USB CDC.
\r
68 #include "serial_port_usb.h"
\r
71 #if (defined(SERIAL_PORT_TYPE_SWO) && (SERIAL_PORT_TYPE_SWO > 0U))
\r
72 #include "serial_port_swo.h"
\r
75 #if (defined(SERIAL_PORT_TYPE_USBCDC_VIRTUAL) && (SERIAL_PORT_TYPE_USBCDC_VIRTUAL > 0U))
\r
77 #if !(defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))
\r
78 #error The serial manager blocking mode cannot be supported for USB CDC.
\r
81 #include "serial_port_usb_virtual.h"
\r
84 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP 0U
\r
85 #if (defined(SERIAL_PORT_TYPE_UART) && (SERIAL_PORT_TYPE_UART > 0U))
\r
87 #if (SERIAL_PORT_UART_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)
\r
88 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP
\r
89 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_UART_HANDLE_SIZE
\r
94 #if (defined(SERIAL_PORT_TYPE_USBCDC) && (SERIAL_PORT_TYPE_USBCDC > 0U))
\r
96 #if (SERIAL_PORT_USB_CDC_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)
\r
97 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP
\r
98 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_USB_CDC_HANDLE_SIZE
\r
103 #if (defined(SERIAL_PORT_TYPE_SWO) && (SERIAL_PORT_TYPE_SWO > 0U))
\r
105 #if (SERIAL_PORT_SWO_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)
\r
106 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP
\r
107 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_SWO_HANDLE_SIZE
\r
112 #if (defined(SERIAL_PORT_TYPE_USBCDC_VIRTUAL) && (SERIAL_PORT_TYPE_USBCDC_VIRTUAL > 0U))
\r
114 #if (SERIAL_PORT_USB_VIRTUAL_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)
\r
115 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP
\r
116 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_USB_VIRTUAL_HANDLE_SIZE
\r
121 /*! @brief SERIAL_PORT_UART_HANDLE_SIZE/SERIAL_PORT_USB_CDC_HANDLE_SIZE + serial manager dedicated size */
\r
122 #if ((defined(SERIAL_MANAGER_HANDLE_SIZE_TEMP) && (SERIAL_MANAGER_HANDLE_SIZE_TEMP > 0U)))
\r
124 #error SERIAL_PORT_TYPE_UART, SERIAL_PORT_TYPE_USBCDC, SERIAL_PORT_TYPE_SWO and SERIAL_PORT_TYPE_USBCDC_VIRTUAL should not be cleared at same time.
\r
127 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))
\r
128 #define SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 120U)
\r
130 #define SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 12U)
\r
133 #define SERIAL_MANAGER_USE_COMMON_TASK (1U)
\r
134 #define SERIAL_MANAGER_TASK_PRIORITY (2U)
\r
135 #define SERIAL_MANAGER_TASK_STACK_SIZE (1000U)
\r
137 typedef void *serial_handle_t;
\r
138 typedef void *serial_write_handle_t;
\r
139 typedef void *serial_read_handle_t;
\r
141 /*! @brief serial port type*/
\r
142 typedef enum _serial_port_type
\r
144 kSerialPort_Uart = 1U, /*!< Serial port UART */
\r
145 kSerialPort_UsbCdc, /*!< Serial port USB CDC */
\r
146 kSerialPort_Swo, /*!< Serial port SWO */
\r
147 kSerialPort_UsbCdcVirtual, /*!< Serial port USB CDC Virtual */
\r
148 } serial_port_type_t;
\r
150 /*! @brief serial manager config structure*/
\r
151 typedef struct _serial_manager_config
\r
153 uint8_t *ringBuffer; /*!< Ring buffer address, it is used to buffer data received by the hardware.
\r
154 Besides, the memory space cannot be free during the lifetime of the serial
\r
156 uint32_t ringBufferSize; /*!< The size of the ring buffer */
\r
157 serial_port_type_t type; /*!< Serial port type */
\r
158 void *portConfig; /*!< Serial port configuration */
\r
159 } serial_manager_config_t;
\r
161 /*! @brief serial manager error code*/
\r
162 typedef enum _serial_manager_status
\r
164 kStatus_SerialManager_Success = kStatus_Success, /*!< Success */
\r
165 kStatus_SerialManager_Error = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 1), /*!< Failed */
\r
166 kStatus_SerialManager_Busy = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 2), /*!< Busy */
\r
167 kStatus_SerialManager_Notify = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 3), /*!< Ring buffer is not empty */
\r
168 kStatus_SerialManager_Canceled =
\r
169 MAKE_STATUS(kStatusGroup_SERIALMANAGER, 4), /*!< the non-blocking request is canceled */
\r
170 kStatus_SerialManager_HandleConflict = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 5), /*!< The handle is opened */
\r
171 kStatus_SerialManager_RingBufferOverflow =
\r
172 MAKE_STATUS(kStatusGroup_SERIALMANAGER, 6), /*!< The ring buffer is overflowed */
\r
173 } serial_manager_status_t;
\r
175 /*! @brief Callback message structure */
\r
176 typedef struct _serial_manager_callback_message
\r
178 uint8_t *buffer; /*!< Transferred buffer */
\r
179 uint32_t length; /*!< Transferred data length */
\r
180 } serial_manager_callback_message_t;
\r
182 /*! @brief callback function */
\r
183 typedef void (*serial_manager_callback_t)(void *callbackParam,
\r
184 serial_manager_callback_message_t *message,
\r
185 serial_manager_status_t status);
\r
187 /*******************************************************************************
\r
189 ******************************************************************************/
\r
191 #if defined(__cplusplus)
\r
193 #endif /* _cplusplus */
\r
196 * @brief Initializes a serial manager module with the serial manager handle and the user configuration structure.
\r
198 * This function configures the Serial Manager module with user-defined settings. The user can configure the
\r
200 * structure. The parameter serialHandle is a pointer to point to a memory space of size #SERIAL_MANAGER_HANDLE_SIZE
\r
201 * allocated by the caller.
\r
202 * The Serial Manager module supports two types of serial port, UART (includes UART, USART, LPSCI, LPUART, etc) and USB
\r
204 * Please refer to #serial_port_type_t for serial port setting. These two types can be set by using
\r
205 * #serial_manager_config_t.
\r
207 * Example below shows how to use this API to configure the Serial Manager.
\r
210 * #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
\r
211 * static uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];
\r
212 * static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
\r
213 * static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
\r
215 * serial_manager_config_t config;
\r
216 * serial_port_uart_config_t uartConfig;
\r
217 * config.type = kSerialPort_Uart;
\r
218 * config.ringBuffer = &s_ringBuffer[0];
\r
219 * config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
\r
220 * uartConfig.instance = 0;
\r
221 * uartConfig.clockRate = 24000000;
\r
222 * uartConfig.baudRate = 115200;
\r
223 * uartConfig.parityMode = kSerialManager_UartParityDisabled;
\r
224 * uartConfig.stopBitCount = kSerialManager_UartOneStopBit;
\r
225 * uartConfig.enableRx = 1;
\r
226 * uartConfig.enableTx = 1;
\r
227 * config.portConfig = &uartConfig;
\r
228 * SerialManager_Init(s_serialHandle, &config);
\r
232 * #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
\r
233 * static uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];
\r
234 * static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
\r
235 * static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
\r
237 * serial_manager_config_t config;
\r
238 * serial_port_usb_cdc_config_t usbCdcConfig;
\r
239 * config.type = kSerialPort_UsbCdc;
\r
240 * config.ringBuffer = &s_ringBuffer[0];
\r
241 * config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
\r
242 * usbCdcConfig.controllerIndex = kSerialManager_UsbControllerKhci0;
\r
243 * config.portConfig = &usbCdcConfig;
\r
244 * SerialManager_Init(s_serialHandle, &config);
\r
247 * @param serialHandle Pointer to point to a memory space of size #SERIAL_MANAGER_HANDLE_SIZE allocated by the caller.
\r
248 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
249 * @param config Pointer to user-defined configuration structure.
\r
250 * @retval kStatus_SerialManager_Error An error occurred.
\r
251 * @retval kStatus_SerialManager_Success The Serial Manager module initialization succeed.
\r
253 serial_manager_status_t SerialManager_Init(serial_handle_t serialHandle, serial_manager_config_t *config);
\r
256 * @brief De-initializes the serial manager module instance.
\r
258 * This function de-initializes the serial manager module instance. If the opened writing or
\r
259 * reading handle is not closed, the function will return kStatus_SerialManager_Busy.
\r
261 * @param serialHandle The serial manager module handle pointer.
\r
262 * @retval kStatus_SerialManager_Success The serial manager de-initialization succeed.
\r
263 * @retval kStatus_SerialManager_Busy Opened reading or writing handle is not closed.
\r
265 serial_manager_status_t SerialManager_Deinit(serial_handle_t serialHandle);
\r
268 * @brief Opens a writing handle for the serial manager module.
\r
270 * This function Opens a writing handle for the serial manager module. If the serial manager needs to
\r
271 * be used in different tasks, the task should open a dedicated write handle for itself by calling
\r
272 * #SerialManager_OpenWriteHandle. Since there can only one buffer for transmission for the writing
\r
273 * handle at the same time, multiple writing handles need to be opened when the multiple transmission
\r
274 * is needed for a task.
\r
276 * @param serialHandle The serial manager module handle pointer.
\r
277 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
278 * @param writeHandle The serial manager module writing handle pointer.
\r
279 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
280 * @retval kStatus_SerialManager_Error An error occurred.
\r
281 * @retval kStatus_SerialManager_HandleConflict The writing handle was opened.
\r
282 * @retval kStatus_SerialManager_Success The writing handle is opened.
\r
284 * Example below shows how to use this API to write data.
\r
287 * static uint32_t s_serialWriteHandleBuffer1[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /
\r
288 * sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle1 =
\r
289 * (serial_write_handle_t)&s_serialWriteHandleBuffer1[0]; static uint8_t s_nonBlockingWelcome1[] = "This is non-blocking
\r
290 * writing log for task1!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle1);
\r
291 * SerialManager_InstallTxCallback(s_serialWriteHandle1, Task1_SerialManagerTxCallback, s_serialWriteHandle1);
\r
292 * SerialManager_WriteNonBlocking(s_serialWriteHandle1, s_nonBlockingWelcome1, sizeof(s_nonBlockingWelcome1) - 1);
\r
296 * static uint32_t s_serialWriteHandleBuffer2[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /
\r
297 * sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle2 =
\r
298 * (serial_write_handle_t)&s_serialWriteHandleBuffer2[0]; static uint8_t s_nonBlockingWelcome2[] = "This is non-blocking
\r
299 * writing log for task2!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle2);
\r
300 * SerialManager_InstallTxCallback(s_serialWriteHandle2, Task2_SerialManagerTxCallback, s_serialWriteHandle2);
\r
301 * SerialManager_WriteNonBlocking(s_serialWriteHandle2, s_nonBlockingWelcome2, sizeof(s_nonBlockingWelcome2) - 1);
\r
304 serial_manager_status_t SerialManager_OpenWriteHandle(serial_handle_t serialHandle, serial_write_handle_t writeHandle);
\r
307 * @brief Closes a writing handle for the serial manager module.
\r
309 * This function Closes a writing handle for the serial manager module.
\r
311 * @param writeHandle The serial manager module writing handle pointer.
\r
312 * @retval kStatus_SerialManager_Success The writing handle is closed.
\r
314 serial_manager_status_t SerialManager_CloseWriteHandle(serial_write_handle_t writeHandle);
\r
317 * @brief Opens a reading handle for the serial manager module.
\r
319 * This function Opens a reading handle for the serial manager module. The reading handle can not be
\r
320 * opened multiple at the same time. The error code kStatus_SerialManager_Busy would be returned when
\r
321 * the previous reading handle is not closed. And There can only be one buffer for receiving for the
\r
322 * reading handle at the same time.
\r
324 * @param serialHandle The serial manager module handle pointer.
\r
325 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
326 * @param readHandle The serial manager module reading handle pointer.
\r
327 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
328 * @retval kStatus_SerialManager_Error An error occurred.
\r
329 * @retval kStatus_SerialManager_Success The reading handle is opened.
\r
330 * @retval kStatus_SerialManager_Busy Previous reading handle is not closed.
\r
332 * Example below shows how to use this API to read data.
\r
334 * static uint32_t s_serialReadHandleBuffer[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1) /
\r
335 * sizeof(uitn32_t))]; static serial_read_handle_t s_serialReadHandle =
\r
336 * (serial_read_handle_t)&s_serialReadHandleBuffer[0]; SerialManager_OpenReadHandle(serialHandle, s_serialReadHandle);
\r
337 * static uint8_t s_nonBlockingBuffer[64];
\r
338 * SerialManager_InstallRxCallback(s_serialReadHandle, APP_SerialManagerRxCallback, s_serialReadHandle);
\r
339 * SerialManager_ReadNonBlocking(s_serialReadHandle, s_nonBlockingBuffer, sizeof(s_nonBlockingBuffer));
\r
342 serial_manager_status_t SerialManager_OpenReadHandle(serial_handle_t serialHandle, serial_read_handle_t readHandle);
\r
345 * @brief Closes a reading for the serial manager module.
\r
347 * This function Closes a reading for the serial manager module.
\r
349 * @param readHandle The serial manager module reading handle pointer.
\r
350 * @retval kStatus_SerialManager_Success The reading handle is closed.
\r
352 serial_manager_status_t SerialManager_CloseReadHandle(serial_read_handle_t readHandle);
\r
355 * @brief Transmits data with the blocking mode.
\r
357 * This is a blocking function, which polls the sending queue, waits for the sending queue to be empty.
\r
358 * This function sends data using an interrupt method. The interrupt of the hardware could not be disabled.
\r
359 * And There can only one buffer for transmission for the writing handle at the same time.
\r
361 * @note The function #SerialManager_WriteBlocking and the function #SerialManager_WriteNonBlocking
\r
362 * cannot be used at the same time.
\r
363 * And, the function #SerialManager_CancelWriting cannot be used to abort the transmission of this function.
\r
365 * @param writeHandle The serial manager module handle pointer.
\r
366 * @param buffer Start address of the data to write.
\r
367 * @param length Length of the data to write.
\r
368 * @retval kStatus_SerialManager_Success Successfully sent all data.
\r
369 * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all sent yet.
\r
370 * @retval kStatus_SerialManager_Error An error occurred.
\r
372 serial_manager_status_t SerialManager_WriteBlocking(serial_write_handle_t writeHandle,
\r
377 * @brief Reads data with the blocking mode.
\r
379 * This is a blocking function, which polls the receiving buffer, waits for the receiving buffer to be full.
\r
380 * This function receives data using an interrupt method. The interrupt of the hardware could not be disabled.
\r
381 * And There can only one buffer for receiving for the reading handle at the same time.
\r
383 * @note The function #SerialManager_ReadBlocking and the function #SerialManager_ReadNonBlocking
\r
384 * cannot be used at the same time.
\r
385 * And, the function #SerialManager_CancelReading cannot be used to abort the transmission of this function.
\r
387 * @param readHandle The serial manager module handle pointer.
\r
388 * @param buffer Start address of the data to store the received data.
\r
389 * @param length The length of the data to be received.
\r
390 * @retval kStatus_SerialManager_Success Successfully received all data.
\r
391 * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.
\r
392 * @retval kStatus_SerialManager_Error An error occurred.
\r
394 serial_manager_status_t SerialManager_ReadBlocking(serial_read_handle_t readHandle, uint8_t *buffer, uint32_t length);
\r
396 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))
\r
398 * @brief Transmits data with the non-blocking mode.
\r
400 * This is a non-blocking function, which returns directly without waiting for all data to be sent.
\r
401 * When all data is sent, the module notifies the upper layer through a TX callback function and passes
\r
402 * the status parameter @ref kStatus_SerialManager_Success.
\r
403 * This function sends data using an interrupt method. The interrupt of the hardware could not be disabled.
\r
404 * And There can only one buffer for transmission for the writing handle at the same time.
\r
406 * @note The function #SerialManager_WriteBlocking and the function #SerialManager_WriteNonBlocking
\r
407 * cannot be used at the same time. And, the TX callback is mandatory before the function could be used.
\r
409 * @param writeHandle The serial manager module handle pointer.
\r
410 * @param buffer Start address of the data to write.
\r
411 * @param length Length of the data to write.
\r
412 * @retval kStatus_SerialManager_Success Successfully sent all data.
\r
413 * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all sent yet.
\r
414 * @retval kStatus_SerialManager_Error An error occurred.
\r
416 serial_manager_status_t SerialManager_WriteNonBlocking(serial_write_handle_t writeHandle,
\r
421 * @brief Reads data with the non-blocking mode.
\r
423 * This is a non-blocking function, which returns directly without waiting for all data to be received.
\r
424 * When all data is received, the module driver notifies the upper layer
\r
425 * through a RX callback function and passes the status parameter @ref kStatus_SerialManager_Success.
\r
426 * This function receives data using an interrupt method. The interrupt of the hardware could not be disabled.
\r
427 * And There can only one buffer for receiving for the reading handle at the same time.
\r
429 * @note The function #SerialManager_ReadBlocking and the function #SerialManager_ReadNonBlocking
\r
430 * cannot be used at the same time. And, the RX callback is mandatory before the function could be used.
\r
432 * @param readHandle The serial manager module handle pointer.
\r
433 * @param buffer Start address of the data to store the received data.
\r
434 * @param length The length of the data to be received.
\r
435 * @retval kStatus_SerialManager_Success Successfully received all data.
\r
436 * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.
\r
437 * @retval kStatus_SerialManager_Error An error occurred.
\r
439 serial_manager_status_t SerialManager_ReadNonBlocking(serial_read_handle_t readHandle,
\r
444 * @brief Tries to read data.
\r
446 * The function tries to read data from internal ring buffer. If the ring buffer is not empty, the data will be
\r
447 * copied from ring buffer to up layer buffer. The copied length is the minimum of the ring buffer and up layer length.
\r
448 * After the data is copied, the actual data length is passed by the parameter length.
\r
449 * And There can only one buffer for receiving for the reading handle at the same time.
\r
451 * @param readHandle The serial manager module handle pointer.
\r
452 * @param buffer Start address of the data to store the received data.
\r
453 * @param length The length of the data to be received.
\r
454 * @param receivedLength Length received from the ring buffer directly.
\r
455 * @retval kStatus_SerialManager_Success Successfully received all data.
\r
456 * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.
\r
457 * @retval kStatus_SerialManager_Error An error occurred.
\r
459 serial_manager_status_t SerialManager_TryRead(serial_read_handle_t readHandle,
\r
462 uint32_t *receivedLength);
\r
465 * @brief Cancels unfinished send transmission.
\r
467 * The function cancels unfinished send transmission. When the transfer is canceled, the module notifies the upper layer
\r
468 * through a TX callback function and passes the status parameter @ref kStatus_SerialManager_Canceled.
\r
470 * @note The function #SerialManager_CancelWriting cannot be used to abort the transmission of
\r
471 * the function #SerialManager_WriteBlocking.
\r
473 * @param writeHandle The serial manager module handle pointer.
\r
474 * @retval kStatus_SerialManager_Success Get successfully abort the sending.
\r
475 * @retval kStatus_SerialManager_Error An error occurred.
\r
477 serial_manager_status_t SerialManager_CancelWriting(serial_write_handle_t writeHandle);
\r
480 * @brief Cancels unfinished receive transmission.
\r
482 * The function cancels unfinished receive transmission. When the transfer is canceled, the module notifies the upper
\r
484 * through a RX callback function and passes the status parameter @ref kStatus_SerialManager_Canceled.
\r
486 * @note The function #SerialManager_CancelReading cannot be used to abort the transmission of
\r
487 * the function #SerialManager_ReadBlocking.
\r
489 * @param readHandle The serial manager module handle pointer.
\r
490 * @retval kStatus_SerialManager_Success Get successfully abort the receiving.
\r
491 * @retval kStatus_SerialManager_Error An error occurred.
\r
493 serial_manager_status_t SerialManager_CancelReading(serial_read_handle_t readHandle);
\r
496 * @brief Installs a TX callback and callback parameter.
\r
498 * This function is used to install the TX callback and callback parameter for the serial manager module.
\r
499 * When any status of TX transmission changed, the driver will notify the upper layer by the installed callback
\r
500 * function. And the status is also passed as status parameter when the callback is called.
\r
502 * @param writeHandle The serial manager module handle pointer.
\r
503 * @param callback The callback function.
\r
504 * @param callbackParam The parameter of the callback function.
\r
505 * @retval kStatus_SerialManager_Success Successfully install the callback.
\r
507 serial_manager_status_t SerialManager_InstallTxCallback(serial_write_handle_t writeHandle,
\r
508 serial_manager_callback_t callback,
\r
509 void *callbackParam);
\r
512 * @brief Installs a RX callback and callback parameter.
\r
514 * This function is used to install the RX callback and callback parameter for the serial manager module.
\r
515 * When any status of RX transmission changed, the driver will notify the upper layer by the installed callback
\r
516 * function. And the status is also passed as status parameter when the callback is called.
\r
518 * @param readHandle The serial manager module handle pointer.
\r
519 * @param callback The callback function.
\r
520 * @param callbackParam The parameter of the callback function.
\r
521 * @retval kStatus_SerialManager_Success Successfully install the callback.
\r
523 serial_manager_status_t SerialManager_InstallRxCallback(serial_read_handle_t readHandle,
\r
524 serial_manager_callback_t callback,
\r
525 void *callbackParam);
\r
530 * @brief Prepares to enter low power consumption.
\r
532 * This function is used to prepare to enter low power consumption.
\r
534 * @param serialHandle The serial manager module handle pointer.
\r
535 * @retval kStatus_SerialManager_Success Successful operation.
\r
537 serial_manager_status_t SerialManager_EnterLowpower(serial_handle_t serialHandle);
\r
540 * @brief Restores from low power consumption.
\r
542 * This function is used to restore from low power consumption.
\r
544 * @param serialHandle The serial manager module handle pointer.
\r
545 * @retval kStatus_SerialManager_Success Successful operation.
\r
547 serial_manager_status_t SerialManager_ExitLowpower(serial_handle_t serialHandle);
\r
549 #if defined(__cplusplus)
\r
553 #endif /* __SERIAL_MANAGER_H__ */
\r