MCUXpresso SDK API Reference Manual: Serial Manager

| MCUXpresso SDK API Reference Manual Rev 2.11.1 NXP Semiconductors

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Serial Manager

## Overview

This chapter describes the programming interface of the serial manager component.

The serial manager component provides a series of APIs to operate different serial port types. The port types it supports are UART, USB CDC and SWO.

## Modules
| Serial Port SWO
| Serial Port Uart

## Data Structures
struct | serial_manager_config_t
| serial manager config structure More...
struct | serial_manager_callback_message_t
| Callback message structure. More...

## Macros
#define | SERIAL_MANAGER_NON_BLOCKING_MODE (0U)
| Enable or disable serial manager non-blocking mode (1 - enable, 0 - disable)
#define | SERIAL_MANAGER_RING_BUFFER_FLOWCONTROL (0U)
| Enable or ring buffer flow control (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_UART (0U)
| Enable or disable uart port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_UART_DMA (0U)
| Enable or disable uart dma port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_USBCDC (0U)
| Enable or disable USB CDC port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_SWO (0U)
| Enable or disable SWO port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_VIRTUAL (0U)
| Enable or disable USB CDC virtual port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_RPMSG (0U)
| Enable or disable rPMSG port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_SPI_MASTER (0U)
| Enable or disable SPI Master port (1 - enable, 0 - disable)
#define | SERIAL_PORT_TYPE_SPI_SLAVE (0U)
| Enable or disable SPI Slave port (1 - enable, 0 - disable)
#define | SERIAL_MANAGER_TASK_HANDLE_TX (0U)
| Enable or disable SerialManager_Task() handle TX to prevent recursive calling.
#define | SERIAL_MANAGER_WRITE_TIME_DELAY_DEFAULT_VALUE (1U)
| Set the default delay time in ms used by SerialManager_WriteTimeDelay(). More...
#define | SERIAL_MANAGER_READ_TIME_DELAY_DEFAULT_VALUE (1U)
| Set the default delay time in ms used by SerialManager_ReadTimeDelay(). More...
#define | SERIAL_MANAGER_TASK_HANDLE_RX_AVAILABLE_NOTIFY (0U)
| Enable or disable SerialManager_Task() handle RX data available notify.
#define | SERIAL_MANAGER_WRITE_HANDLE_SIZE (4U)
| Set serial manager write handle size.
#define | SERIAL_MANAGER_USE_COMMON_TASK (0U)
| SERIAL_PORT_UART_HANDLE_SIZE/SERIAL_PORT_USB_CDC_HANDLE_SIZE + serial manager dedicated size. More...
#define | SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 12U)
| Macro to determine whether use common task. More...
#define | SERIAL_MANAGER_HANDLE_DEFINE(name) uint32_t name[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
| Defines the serial manager handle. More...
#define | SERIAL_MANAGER_WRITE_HANDLE_DEFINE(name) uint32_t name[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
| Defines the serial manager write handle. More...
#define | SERIAL_MANAGER_READ_HANDLE_DEFINE(name) uint32_t name[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
| Defines the serial manager read handle. More...
#define | SERIAL_MANAGER_TASK_PRIORITY (2U)
| Macro to set serial manager task priority. More...
#define | SERIAL_MANAGER_TASK_STACK_SIZE (1000U)
| Macro to set serial manager task stack size. More...

## Typedefs
typedef void * | serial_handle_t
| The handle of the serial manager module.
typedef void * | serial_write_handle_t
| The write handle of the serial manager module.
typedef void * | serial_read_handle_t
| The read handle of the serial manager module.
typedef void(* | serial_manager_callback_t )(void *callbackParam, serial_manager_callback_message_t *message, serial_manager_status_t status)
| callback function

## Enumerations
enum | serial_port_type_t { kSerialPort_Uart = 1U, kSerialPort_UsbCdc, kSerialPort_Swo, kSerialPort_Virtual, kSerialPort_Rpmsg, kSerialPort_UartDma, kSerialPort_SpiMaster, kSerialPort_SpiSlave, kSerialPort_None }
| serial port type More...
enum | serial_manager_type_t { kSerialManager_NonBlocking = 0x0U, kSerialManager_Blocking = 0x8F41U }
| serial manager type More...
enum | serial_manager_status_t { kStatus_SerialManager_Success = kStatus_Success, kStatus_SerialManager_Error = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 1), kStatus_SerialManager_Busy = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 2), kStatus_SerialManager_Notify = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 3), kStatus_SerialManager_Canceled, kStatus_SerialManager_HandleConflict = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 5), kStatus_SerialManager_RingBufferOverflow, kStatus_SerialManager_NotConnected = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 7) }
| serial manager error code More...

## Functions
serial_manager_status_t | SerialManager_Init (serial_handle_t serialHandle, const serial_manager_config_t *config)
| Initializes a serial manager module with the serial manager handle and the user configuration structure. More...
serial_manager_status_t | SerialManager_Deinit (serial_handle_t serialHandle)
| De-initializes the serial manager module instance. More...
serial_manager_status_t | SerialManager_OpenWriteHandle (serial_handle_t serialHandle, serial_write_handle_t writeHandle)
| Opens a writing handle for the serial manager module. More...
serial_manager_status_t | SerialManager_CloseWriteHandle (serial_write_handle_t writeHandle)
| Closes a writing handle for the serial manager module. More...
serial_manager_status_t | SerialManager_OpenReadHandle (serial_handle_t serialHandle, serial_read_handle_t readHandle)
| Opens a reading handle for the serial manager module. More...
serial_manager_status_t | SerialManager_CloseReadHandle (serial_read_handle_t readHandle)
| Closes a reading for the serial manager module. More...
serial_manager_status_t | SerialManager_WriteBlocking (serial_write_handle_t writeHandle, uint8_t *buffer, uint32_t length)
| Transmits data with the blocking mode. More...
serial_manager_status_t | SerialManager_ReadBlocking (serial_read_handle_t readHandle, uint8_t *buffer, uint32_t length)
| Reads data with the blocking mode. More...
serial_manager_status_t | SerialManager_EnterLowpower (serial_handle_t serialHandle)
| Prepares to enter low power consumption. More...
serial_manager_status_t | SerialManager_ExitLowpower (serial_handle_t serialHandle)
| Restores from low power consumption. More...
static bool | SerialManager_needPollingIsr (void)
| Check if need polling ISR. More...

## Data Structure Documentation

struct serial_manager_config_t

### Data Fields
uint8_t * | ringBuffer
| Ring buffer address, it is used to buffer data received by the hardware. More...
uint32_t | ringBufferSize
| The size of the ring buffer.
serial_port_type_t | type
| Serial port type.
serial_manager_type_t | blockType
| Serial manager port type.
void * | portConfig
| Serial port configuration.

#### Field Documentation

uint8_t* serial_manager_config_t::ringBuffer

Besides, the memory space cannot be free during the lifetime of the serial manager module.

struct serial_manager_callback_message_t

### Data Fields
uint8_t * | buffer
| Transferred buffer.
uint32_t | length
| Transferred data length.

## Macro Definition Documentation

#define SERIAL_MANAGER_WRITE_TIME_DELAY_DEFAULT_VALUE (1U)

#define SERIAL_MANAGER_READ_TIME_DELAY_DEFAULT_VALUE (1U)

#define SERIAL_MANAGER_USE_COMMON_TASK (0U)

Macro to determine whether use common task.

#define SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 12U)

Definition of serial manager handle size.

#define SERIAL_MANAGER_HANDLE_DEFINE | ( |  | name | ) | uint32_t name[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned serial manager handle. Then use "(serial_handle_t)name" to get the serial manager handle.

The macro should be global and could be optional. You could also define serial manager handle by yourself.

This is an example,

* SERIAL_MANAGER_HANDLE_DEFINE(serialManagerHandle);
*

Parameters

  name | The name string of the serial manager handle.

#define SERIAL_MANAGER_WRITE_HANDLE_DEFINE | ( |  | name | ) | uint32_t name[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned serial manager write handle. Then use "(serial_write_handle_t)name" to get the serial manager write handle.

The macro should be global and could be optional. You could also define serial manager write handle by yourself.

This is an example,

* SERIAL_MANAGER_WRITE_HANDLE_DEFINE(serialManagerwriteHandle);
*

Parameters

  name | The name string of the serial manager write handle.

#define SERIAL_MANAGER_READ_HANDLE_DEFINE | ( |  | name | ) | uint32_t name[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned serial manager read handle. Then use "(serial_read_handle_t)name" to get the serial manager read handle.

The macro should be global and could be optional. You could also define serial manager read handle by yourself.

This is an example,

* SERIAL_MANAGER_READ_HANDLE_DEFINE(serialManagerReadHandle);
*

Parameters

  name | The name string of the serial manager read handle.

#define SERIAL_MANAGER_TASK_PRIORITY (2U)

#define SERIAL_MANAGER_TASK_STACK_SIZE (1000U)

## Enumeration Type Documentation

enum serial_port_type_t

Enumerator
kSerialPort_Uart | Serial port UART.
kSerialPort_UsbCdc | Serial port USB CDC.
kSerialPort_Swo | Serial port SWO.
kSerialPort_Virtual | Serial port Virtual.
kSerialPort_Rpmsg | Serial port RPMSG.
kSerialPort_UartDma | Serial port UART DMA.
kSerialPort_SpiMaster | Serial port SPIMASTER.
kSerialPort_SpiSlave | Serial port SPISLAVE.
kSerialPort_None | Serial port is none.

enum serial_manager_type_t

Enumerator
kSerialManager_NonBlocking | None blocking handle.
kSerialManager_Blocking | Blocking handle.

enum serial_manager_status_t

Enumerator
kStatus_SerialManager_Success | Success.
kStatus_SerialManager_Error | Failed.
kStatus_SerialManager_Busy | Busy.
kStatus_SerialManager_Notify | Ring buffer is not empty.
kStatus_SerialManager_Canceled | the non-blocking request is canceled
kStatus_SerialManager_HandleConflict | The handle is opened.
kStatus_SerialManager_RingBufferOverflow | The ring buffer is overflowed.
kStatus_SerialManager_NotConnected | The host is not connected.

## Function Documentation

serial_manager_status_t SerialManager_Init | ( | serial_handle_t | serialHandle,
|  | const serial_manager_config_t * | config
| ) |  |

This function configures the Serial Manager module with user-defined settings. The user can configure the configuration structure. The parameter serialHandle is a pointer to point to a memory space of size SERIAL_MANAGER_HANDLE_SIZE allocated by the caller. The Serial Manager module supports three types of serial port, UART (includes UART, USART, LPSCI, LPUART, etc), USB CDC and swo. Please refer to serial_port_type_t for serial port setting. These three types can be set by using serial_manager_config_t.

Example below shows how to use this API to configure the Serial Manager. For UART,

* #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
* static SERIAL_MANAGER_HANDLE_DEFINE(s_serialHandle);
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
* serial_manager_config_t config;
* serial_port_uart_config_t uartConfig;
* config.type = kSerialPort_Uart;
* config.ringBuffer = &s_ringBuffer[0];
* config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
* uartConfig.instance = 0;
* uartConfig.clockRate = 24000000;
* uartConfig.baudRate = 115200;
* uartConfig.parityMode = kSerialManager_UartParityDisabled;
* uartConfig.stopBitCount = kSerialManager_UartOneStopBit;
* uartConfig.enableRx = 1;
* uartConfig.enableTx = 1;
* uartConfig.enableRxRTS = 0;
* uartConfig.enableTxCTS = 0;
* config.portConfig = &uartConfig;
* SerialManager_Init((serial_handle_t)s_serialHandle, &config);
*

For USB CDC,

* #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
* static SERIAL_MANAGER_HANDLE_DEFINE(s_serialHandle);
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
* serial_manager_config_t config;
* serial_port_usb_cdc_config_t usbCdcConfig;
* config.type = kSerialPort_UsbCdc;
* config.ringBuffer = &s_ringBuffer[0];
* config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
* usbCdcConfig.controllerIndex = kSerialManager_UsbControllerKhci0;
* config.portConfig = &usbCdcConfig;
* SerialManager_Init((serial_handle_t)s_serialHandle, &config);
*

Parameters

  serialHandle | Pointer to point to a memory space of size SERIAL_MANAGER_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: SERIAL_MANAGER_HANDLE_DEFINE(serialHandle); or uint32_t serialHandle[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
  config | Pointer to user-defined configuration structure.

Return values

  kStatus_SerialManager_Error | An error occurred.
  kStatus_SerialManager_Success | The Serial Manager module initialization succeed.

serial_manager_status_t SerialManager_Deinit | ( | serial_handle_t | serialHandle | ) |

This function de-initializes the serial manager module instance. If the opened writing or reading handle is not closed, the function will return kStatus_SerialManager_Busy.

Parameters

  serialHandle | The serial manager module handle pointer.

Return values

  kStatus_SerialManager_Success | The serial manager de-initialization succeed.
  kStatus_SerialManager_Busy | Opened reading or writing handle is not closed.

serial_manager_status_t SerialManager_OpenWriteHandle | ( | serial_handle_t | serialHandle,
|  | serial_write_handle_t | writeHandle
| ) |  |

This function Opens a writing handle for the serial manager module. If the serial manager needs to be used in different tasks, the task should open a dedicated write handle for itself by calling SerialManager_OpenWriteHandle. Since there can only one buffer for transmission for the writing handle at the same time, multiple writing handles need to be opened when the multiple transmission is needed for a task.

Parameters

  serialHandle | The serial manager module handle pointer. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices.
  writeHandle | The serial manager module writing handle pointer. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: SERIAL_MANAGER_WRITE_HANDLE_DEFINE(writeHandle); or uint32_t writeHandle[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];

Return values

  kStatus_SerialManager_Error | An error occurred.
  kStatus_SerialManager_HandleConflict | The writing handle was opened.
  kStatus_SerialManager_Success | The writing handle is opened.

Example below shows how to use this API to write data. For task 1,

* static SERIAL_MANAGER_WRITE_HANDLE_DEFINE(s_serialWriteHandle1);
* static uint8_t s_nonBlockingWelcome1[] = "This is non-blocking writing log for task1!\r\n";
* SerialManager_OpenWriteHandle((serial_handle_t)serialHandle, (serial_write_handle_t)s_serialWriteHandle1);
* SerialManager_InstallTxCallback((serial_write_handle_t)s_serialWriteHandle1,
* Task1_SerialManagerTxCallback,
* s_serialWriteHandle1);
* SerialManager_WriteNonBlocking((serial_write_handle_t)s_serialWriteHandle1,
* s_nonBlockingWelcome1,
* sizeof(s_nonBlockingWelcome1) - 1U);
*

For task 2,

* static SERIAL_MANAGER_WRITE_HANDLE_DEFINE(s_serialWriteHandle2);
* static uint8_t s_nonBlockingWelcome2[] = "This is non-blocking writing log for task2!\r\n";
* SerialManager_OpenWriteHandle((serial_handle_t)serialHandle, (serial_write_handle_t)s_serialWriteHandle2);
* SerialManager_InstallTxCallback((serial_write_handle_t)s_serialWriteHandle2,
* Task2_SerialManagerTxCallback,
* s_serialWriteHandle2);
* SerialManager_WriteNonBlocking((serial_write_handle_t)s_serialWriteHandle2,
* s_nonBlockingWelcome2,
* sizeof(s_nonBlockingWelcome2) - 1U);
*

serial_manager_status_t SerialManager_CloseWriteHandle | ( | serial_write_handle_t | writeHandle | ) |

This function Closes a writing handle for the serial manager module.

Parameters

  writeHandle | The serial manager module writing handle pointer.

Return values

  kStatus_SerialManager_Success | The writing handle is closed.

serial_manager_status_t SerialManager_OpenReadHandle | ( | serial_handle_t | serialHandle,
|  | serial_read_handle_t | readHandle
| ) |  |

This function Opens a reading handle for the serial manager module. The reading handle can not be opened multiple at the same time. The error code kStatus_SerialManager_Busy would be returned when the previous reading handle is not closed. And there can only be one buffer for receiving for the reading handle at the same time.

Parameters

  serialHandle | The serial manager module handle pointer. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices.
  readHandle | The serial manager module reading handle pointer. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: SERIAL_MANAGER_READ_HANDLE_DEFINE(readHandle); or uint32_t readHandle[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];

Return values

  kStatus_SerialManager_Error | An error occurred.
  kStatus_SerialManager_Success | The reading handle is opened.
  kStatus_SerialManager_Busy | Previous reading handle is not closed.

Example below shows how to use this API to read data.

* static SERIAL_MANAGER_READ_HANDLE_DEFINE(s_serialReadHandle);
* SerialManager_OpenReadHandle((serial_handle_t)serialHandle, (serial_read_handle_t)s_serialReadHandle);
* static uint8_t s_nonBlockingBuffer[64];
* SerialManager_InstallRxCallback((serial_read_handle_t)s_serialReadHandle,
* APP_SerialManagerRxCallback,
* s_serialReadHandle);
* SerialManager_ReadNonBlocking((serial_read_handle_t)s_serialReadHandle,
* s_nonBlockingBuffer,
* sizeof(s_nonBlockingBuffer));
*

serial_manager_status_t SerialManager_CloseReadHandle | ( | serial_read_handle_t | readHandle | ) |

This function Closes a reading for the serial manager module.

Parameters

  readHandle | The serial manager module reading handle pointer.

Return values

  kStatus_SerialManager_Success | The reading handle is closed.

serial_manager_status_t SerialManager_WriteBlocking | ( | serial_write_handle_t | writeHandle,
|  | uint8_t * | buffer,
|  | uint32_t | length
| ) |  |

This is a blocking function, which polls the sending queue, waits for the sending queue to be empty. This function sends data using an interrupt method. The interrupt of the hardware could not be disabled. And There can only one buffer for transmission for the writing handle at the same time.

Note
  The function SerialManager_WriteBlocking and the function SerialManager_WriteNonBlocking cannot be used at the same time. And, the function SerialManager_CancelWriting cannot be used to abort the transmission of this function.

Parameters

  writeHandle | The serial manager module handle pointer.
  buffer | Start address of the data to write.
  length | Length of the data to write.

Return values

  kStatus_SerialManager_Success | Successfully sent all data.
  kStatus_SerialManager_Busy | Previous transmission still not finished; data not all sent yet.
  kStatus_SerialManager_Error | An error occurred.

serial_manager_status_t SerialManager_ReadBlocking | ( | serial_read_handle_t | readHandle,
|  | uint8_t * | buffer,
|  | uint32_t | length
| ) |  |

This is a blocking function, which polls the receiving buffer, waits for the receiving buffer to be full. This function receives data using an interrupt method. The interrupt of the hardware could not be disabled. And There can only one buffer for receiving for the reading handle at the same time.

Note
  The function SerialManager_ReadBlocking and the function SerialManager_ReadNonBlocking cannot be used at the same time. And, the function SerialManager_CancelReading cannot be used to abort the transmission of this function.

Parameters

  readHandle | The serial manager module handle pointer.
  buffer | Start address of the data to store the received data.
  length | The length of the data to be received.

Return values

  kStatus_SerialManager_Success | Successfully received all data.
  kStatus_SerialManager_Busy | Previous transmission still not finished; data not all received yet.
  kStatus_SerialManager_Error | An error occurred.

serial_manager_status_t SerialManager_EnterLowpower | ( | serial_handle_t | serialHandle | ) |

This function is used to prepare to enter low power consumption.

Parameters

  serialHandle | The serial manager module handle pointer.

Return values

  kStatus_SerialManager_Success | Successful operation.

serial_manager_status_t SerialManager_ExitLowpower | ( | serial_handle_t | serialHandle | ) |

This function is used to restore from low power consumption.

Parameters

  serialHandle | The serial manager module handle pointer.

Return values

  kStatus_SerialManager_Success | Successful operation.

static bool SerialManager_needPollingIsr | ( | void |  | ) |
| inlinestatic

This function is used to check if need polling ISR.

Return values

  TRUE | if need polling.