|
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...
|
|
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.
struct serial_manager_config_t |
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.
|
|
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.
|
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 serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
*
For USB CDC,
* #define SERIAL_MANAGER_RING_BUFFER_SIZE (256U)
* static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];
* static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];
*
*
- 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 does not support on some devices. |
config | Pointer to user-defined configuration structure. |
- Return values
-
kStatus_SerialManager_Error | An error occurred. |
kStatus_SerialManager_Success | The Serial Manager module initialization succeed. |
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 does not support on some devices. |
writeHandle | The 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_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,
* 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
* SerialManager_InstallTxCallback(s_serialWriteHandle1, Task1_SerialManagerTxCallback, s_serialWriteHandle1);
* SerialManager_WriteNonBlocking(s_serialWriteHandle1, s_nonBlockingWelcome1, sizeof(s_nonBlockingWelcome1) - 1);
*
For task 2,
* 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
* SerialManager_InstallTxCallback(s_serialWriteHandle2, Task2_SerialManagerTxCallback, s_serialWriteHandle2);
* SerialManager_WriteNonBlocking(s_serialWriteHandle2, s_nonBlockingWelcome2, sizeof(s_nonBlockingWelcome2) - 1);
*
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 does not support on some devices. |
readHandle | The 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_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 uint32_t s_serialReadHandleBuffer[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1) /
* sizeof(uitn32_t))]; static serial_read_handle_t 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));
*
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. |
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. |
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. |