Serial UART Communication#
This API contains the HAL interfaces that applications must implement for the high-level serial code.
This header describes the interface between the high-level serial APIs in serial/serial.h and the low level UART implementation.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus return values.
See hal/micro/serial.h for source code.
Serial HAL APIs#
These functions must be implemented by the HAL in order for the serial code to operate. Only the higher-level serial code uses these functions, so they should not be called directly. The HAL should also implement the appropriate interrupt handlers to drain the TX queues and fill the RX FIFO queue.
Initializes the UART to the given settings (same parameters as ::emberSerialInit() ).
This function is typically called by halPowerDown() and it is responsible for performing all the work internal to the UART needed to stop the UART before a sleep cycle.
This function is typically called by halPowerUp() and it is responsible for performing all the work internal to the UART needed to restart the UART after a sleep cycle.
Called by serial code whenever anything is queued for transmission to start any interrupt-driven transmission. May be called when transmission is already in progess.
Called by serial code to stop any interrupt-driven serial transmission currently in progress.
Directly writes a byte to the UART for transmission, regardless of anything currently queued for transmission. Should wait for anything currently in the UART hardware registers to finish transmission first, and block until data
is finished being sent.
Directly reads a byte from the UART for reception, regardless of anything currently queued for reception. Does not block if a data byte has not been received.
Blocks until the UART has finished transmitting any data in its hardware registers.
This function is typically called by ::halInternalPowerUpBoard() and it is responsible for performing all the work internal to the UART needed to restart the UART after a sleep cycle. (For example, resyncing the DMA hardware and the serial FIFO.)
Checks to see if the host is allowed to send serial data to the ncp - i.e., it is not being held off by nCTS or an XOFF. Returns true is the host is able to send.
When Xon/Xoff flow control is used, returns true if the host is not being held off and XON refreshing is complete.
Returns true if the uart transmitter is idle, including the transmit shift register.
Testing function implemented by the upper layer. Determines whether the next packet should be dropped. Returns true if the next packet should be dropped, false otherwise.
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
This function exists only in software UART (SOFTUART) mode on the EM3xx. This function is called by ::emberSerialReadByte(). It is responsible for maintaining synchronization between the emSerialRxQueue and the UART DMA.
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
Virtual UART API#
API used by the stack in debug builds to receive data arriving over the virtual UART.
When using a debug build with virtual UART support, this API is called by the stack when virtual UART data has been received over the debug channel.
Serial Mode Definitions#
These are numerical definitions for the possible serial modes so that code can test for the one being used. There may be additional modes defined in the micro-specific micro.h.
A numerical definition for a possible serial mode the code can test for.
A numerical definition for a possible serial mode the code can test for.
A numerical definition for a possible serial mode the code can test for.
FIFO Utility Macros#
These macros manipulate the FIFO queue data structures to add and remove data.
Macro that enqueues a byte of data in a FIFO queue.
Macro that de-queues a byte of data from a FIFO queue.
Enumerations#
Assign numerical values for variables that hold Baud Rate parameters.
CORTEXM3_EFM32_MICRO.
Functions#
Serial HAL APIs Documentation#
halInternalUartInit#
EmberStatus halInternalUartInit (uint8_t port, SerialBaudRate rate, SerialParity parity, uint8_t stopBits)
Initializes the UART to the given settings (same parameters as ::emberSerialInit() ).
N/A | port | Serial port number (0 or 1). |
N/A | rate | Baud rate (see SerialBaudRate). |
N/A | parity | Parity value (see SerialParity). |
N/A | stopBits | Number of stop bits. |
Returns
An error code if initialization failed (such as invalid baud rate), otherise EMBER_SUCCESS.
410
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalPowerDownUart#
void halInternalPowerDownUart (void )
This function is typically called by halPowerDown() and it is responsible for performing all the work internal to the UART needed to stop the UART before a sleep cycle.
N/A |
419
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalPowerUpUart#
void halInternalPowerUpUart (void )
This function is typically called by halPowerUp() and it is responsible for performing all the work internal to the UART needed to restart the UART after a sleep cycle.
N/A |
425
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalStartUartTx#
void halInternalStartUartTx (uint8_t port)
Called by serial code whenever anything is queued for transmission to start any interrupt-driven transmission. May be called when transmission is already in progess.
N/A | port | Serial port number (0 or 1). |
433
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalStopUartTx#
void halInternalStopUartTx (uint8_t port)
Called by serial code to stop any interrupt-driven serial transmission currently in progress.
N/A | port | Serial port number (0 or 1). |
440
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalForceWriteUartData#
EmberStatus halInternalForceWriteUartData (uint8_t port, uint8_t * data, uint8_t length)
Directly writes a byte to the UART for transmission, regardless of anything currently queued for transmission. Should wait for anything currently in the UART hardware registers to finish transmission first, and block until data
is finished being sent.
N/A | port | Serial port number (0 or 1). |
N/A | data | Pointer to the data to be transmitted. |
N/A | length | The length of data to be transmitted |
453
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalForceReadUartByte#
EmberStatus halInternalForceReadUartByte (uint8_t port, uint8_t * dataByte)
Directly reads a byte from the UART for reception, regardless of anything currently queued for reception. Does not block if a data byte has not been received.
N/A | port | Serial port number (0 or 1). |
N/A | dataByte | The byte to receive data into. |
463
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalWaitUartTxComplete#
void halInternalWaitUartTxComplete (uint8_t port)
Blocks until the UART has finished transmitting any data in its hardware registers.
N/A | port | Serial port number (0 or 1). |
470
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalRestartUart#
void halInternalRestartUart (void )
This function is typically called by ::halInternalPowerUpBoard() and it is responsible for performing all the work internal to the UART needed to restart the UART after a sleep cycle. (For example, resyncing the DMA hardware and the serial FIFO.)
N/A |
506
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUartFlowControlRxIsEnabled#
bool halInternalUartFlowControlRxIsEnabled (uint8_t port)
Checks to see if the host is allowed to send serial data to the ncp - i.e., it is not being held off by nCTS or an XOFF. Returns true is the host is able to send.
N/A | port |
513
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUartXonRefreshDone#
bool halInternalUartXonRefreshDone (uint8_t port)
When Xon/Xoff flow control is used, returns true if the host is not being held off and XON refreshing is complete.
N/A | port |
525
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUartTxIsIdle#
bool halInternalUartTxIsIdle (uint8_t port)
Returns true if the uart transmitter is idle, including the transmit shift register.
N/A | port |
537
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
serialDropPacket#
bool serialDropPacket (void )
Testing function implemented by the upper layer. Determines whether the next packet should be dropped. Returns true if the next packet should be dropped, false otherwise.
N/A |
547
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUartFlowControl#
#define halInternalUartFlowControlValue:
(port)
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
484
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUartRxPump#
#define halInternalUartRxPumpValue:
(port)
This function exists only in software UART (SOFTUART) mode on the EM3xx. This function is called by ::emberSerialReadByte(). It is responsible for maintaining synchronization between the emSerialRxQueue and the UART DMA.
498
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUart1FlowControlRxIsEnabled#
#define halInternalUart1FlowControlRxIsEnabledValue:
()
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
516
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUart1XonRefreshDone#
#define halInternalUart1XonRefreshDoneValue:
()
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
528
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halInternalUart1TxIsIdle#
#define halInternalUart1TxIsIdleValue:
()
This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(), and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resume transmission.
541
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
Virtual UART API Documentation#
halStackReceiveVuartMessage#
void halStackReceiveVuartMessage (uint8_t * data, uint8_t length)
When using a debug build with virtual UART support, this API is called by the stack when virtual UART data has been received over the debug channel.
N/A | data | Pointer to the the data received |
N/A | length | Length of the data received |
574
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
Serial Mode Definitions Documentation#
EMBER_SERIAL_UNUSED#
#define EMBER_SERIAL_UNUSEDValue:
0
A numerical definition for a possible serial mode the code can test for.
91
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
EMBER_SERIAL_FIFO#
#define EMBER_SERIAL_FIFOValue:
1
A numerical definition for a possible serial mode the code can test for.
92
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
EMBER_SERIAL_LOWLEVEL#
#define EMBER_SERIAL_LOWLEVELValue:
2
A numerical definition for a possible serial mode the code can test for.
93
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
FIFO Utility Macros Documentation#
FIFO_ENQUEUE#
#define FIFO_ENQUEUEValue:
Macro that enqueues a byte of data in a FIFO queue.
272
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
FIFO_DEQUEUE#
#define FIFO_DEQUEUEValue:
Macro that de-queues a byte of data from a FIFO queue.
287
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
Enumeration Documentation#
SerialBaudRate#
SerialBaudRate
Assign numerical values for variables that hold Baud Rate parameters.
Enumerator | |
---|---|
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD | |
DEFINE_BAUD |
300
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
SerialParity#
SerialParity
CORTEXM3_EFM32_MICRO.
Assign numerical values for the types of parity. Use for variables that hold Parity parameters.
Enumerator | |
---|---|
DEFINE_PARITY | |
DEFINE_PARITY | |
DEFINE_PARITY |
370
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
Function Documentation#
halHostFlushBuffers#
void halHostFlushBuffers (void )
N/A |
585
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halHostEnqueueTx#
uint16_t halHostEnqueueTx (const uint8_t * data, uint16_t length)
N/A | data | |
N/A | length |
586
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
halHostFlushTx#
void halHostFlushTx (void )
N/A |
587
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
serialCopyFromRx#
uint16_t serialCopyFromRx (const uint8_t * data, uint16_t length)
N/A | data | |
N/A | length |
590
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h
emLoadSerialTx#
void emLoadSerialTx (void )
N/A |
593
of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/platform/base/hal/micro/serial.h