MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Serial Manager

Modules

 Serial Port SWO
 
 Serial Port USB
 
 Serial Port Uart
 
 Serial Port Virtual USB
 

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_PORT_TYPE_UART   (0U)
 Enable or disable uart 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_USBCDC_VIRTUAL   (0U)
 Enable or disable USB CDC virtual port (1 - enable, 0 - disable)
 
#define SERIAL_MANAGER_WRITE_HANDLE_SIZE   (4U)
 Set serial manager write handle size.
 
#define SERIAL_MANAGER_HANDLE_SIZE   (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 12U)
 SERIAL_PORT_UART_HANDLE_SIZE/SERIAL_PORT_USB_CDC_HANDLE_SIZE + serial manager dedicated size.
 

Typedefs

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_UsbCdcVirtual
}
 serial port 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
}
 serial manager error code More...
 

Functions

serial_manager_status_t SerialManager_Init (serial_handle_t serialHandle, 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...
 

Detailed Description

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.


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.
 
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.
 

Enumeration Type Documentation

Enumerator
kSerialPort_Uart 

Serial port UART.

kSerialPort_UsbCdc 

Serial port USB CDC.

kSerialPort_Swo 

Serial port SWO.

kSerialPort_UsbCdcVirtual 

Serial port USB CDC Virtual.

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.

Function Documentation

serial_manager_status_t SerialManager_Init ( serial_handle_t  serialHandle,
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 two types of serial port, UART (includes UART, USART, LPSCI, LPUART, etc) and USB CDC. Please refer to serial_port_type_t for serial port setting. These two 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 uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];
* static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
* config.ringBuffer = &s_ringBuffer[0];
* config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
* uartConfig.instance = 0;
* uartConfig.clockRate = 24000000;
* uartConfig.baudRate = 115200;
* uartConfig.enableRx = 1;
* uartConfig.enableTx = 1;
* config.portConfig = &uartConfig;
* SerialManager_Init(s_serialHandle, &config);
*

For USB CDC,

* #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
* static uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];
* static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
* config.ringBuffer = &s_ringBuffer[0];
* config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;
* config.portConfig = &usbCdcConfig;
* SerialManager_Init(s_serialHandle, &config);
*
Parameters
serialHandlePointer 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 does not support on some devices.
configPointer to user-defined configuration structure.
Return values
kStatus_SerialManager_ErrorAn error occurred.
kStatus_SerialManager_SuccessThe 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
serialHandleThe serial manager module handle pointer.
Return values
kStatus_SerialManager_SuccessThe serial manager de-initialization succeed.
kStatus_SerialManager_BusyOpened 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
serialHandleThe serial manager module handle pointer. The handle should be 4 byte aligned, because unaligned access does not support on some devices.
writeHandleThe serial manager module writing handle pointer. The handle should be 4 byte aligned, because unaligned access does not support on some devices.
Return values
kStatus_SerialManager_ErrorAn error occurred.
kStatus_SerialManager_HandleConflictThe writing handle was opened.
kStatus_SerialManager_SuccessThe writing handle is opened.

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

* static uint32_t s_serialWriteHandleBuffer1[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /
* sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle1 =
* (serial_write_handle_t)&s_serialWriteHandleBuffer1[0]; static uint8_t s_nonBlockingWelcome1[] = "This is non-blocking
* writing log for task1!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle1);
* SerialManager_InstallTxCallback(s_serialWriteHandle1, Task1_SerialManagerTxCallback, s_serialWriteHandle1);
* SerialManager_WriteNonBlocking(s_serialWriteHandle1, s_nonBlockingWelcome1, sizeof(s_nonBlockingWelcome1) - 1);
*

For task 2,

* static uint32_t s_serialWriteHandleBuffer2[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /
* sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle2 =
* (serial_write_handle_t)&s_serialWriteHandleBuffer2[0]; static uint8_t s_nonBlockingWelcome2[] = "This is non-blocking
* writing log for task2!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle2);
* SerialManager_InstallTxCallback(s_serialWriteHandle2, Task2_SerialManagerTxCallback, s_serialWriteHandle2);
* SerialManager_WriteNonBlocking(s_serialWriteHandle2, s_nonBlockingWelcome2, sizeof(s_nonBlockingWelcome2) - 1);
*
serial_manager_status_t SerialManager_CloseWriteHandle ( serial_write_handle_t  writeHandle)

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

Parameters
writeHandleThe serial manager module writing handle pointer.
Return values
kStatus_SerialManager_SuccessThe 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
serialHandleThe serial manager module handle pointer. The handle should be 4 byte aligned, because unaligned access does not support on some devices.
readHandleThe serial manager module reading handle pointer. The handle should be 4 byte aligned, because unaligned access does not support on some devices.
Return values
kStatus_SerialManager_ErrorAn error occurred.
kStatus_SerialManager_SuccessThe reading handle is opened.
kStatus_SerialManager_BusyPrevious reading handle is not closed.

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

* static uint32_t s_serialReadHandleBuffer[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1) /
* sizeof(uitn32_t))]; static serial_read_handle_t s_serialReadHandle =
* (serial_read_handle_t)&s_serialReadHandleBuffer[0]; SerialManager_OpenReadHandle(serialHandle, s_serialReadHandle);
* static uint8_t s_nonBlockingBuffer[64];
* SerialManager_InstallRxCallback(s_serialReadHandle, APP_SerialManagerRxCallback, s_serialReadHandle);
* SerialManager_ReadNonBlocking(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
readHandleThe serial manager module reading handle pointer.
Return values
kStatus_SerialManager_SuccessThe 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
writeHandleThe serial manager module handle pointer.
bufferStart address of the data to write.
lengthLength of the data to write.
Return values
kStatus_SerialManager_SuccessSuccessfully sent all data.
kStatus_SerialManager_BusyPrevious transmission still not finished; data not all sent yet.
kStatus_SerialManager_ErrorAn 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
readHandleThe serial manager module handle pointer.
bufferStart address of the data to store the received data.
lengthThe length of the data to be received.
Return values
kStatus_SerialManager_SuccessSuccessfully received all data.
kStatus_SerialManager_BusyPrevious transmission still not finished; data not all received yet.
kStatus_SerialManager_ErrorAn error occurred.
serial_manager_status_t SerialManager_EnterLowpower ( serial_handle_t  serialHandle)

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

Parameters
serialHandleThe serial manager module handle pointer.
Return values
kStatus_SerialManager_SuccessSuccessful operation.
serial_manager_status_t SerialManager_ExitLowpower ( serial_handle_t  serialHandle)

This function is used to restore from low power consumption.

Parameters
serialHandleThe serial manager module handle pointer.
Return values
kStatus_SerialManager_SuccessSuccessful operation.