This API contains the HAL interfaces that applications must implement for the high-level serial code.

Enumerations
enum	SerialBaudRate { DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0, DEFINE_BAUD =(300) = 0 }
	Assign numerical values for variables that hold Baud Rate parameters.

enum	SerialParity { DEFINE_PARITY =(NONE) = 0U, DEFINE_PARITY =(NONE) = 0U, DEFINE_PARITY =(NONE) = 0U }
	CORTEXM3_EFM32_MICRO.

Functions
void	halHostFlushBuffers (void)

uint16_t	halHostEnqueueTx (const uint8_t *data, uint16_t length)

void	halHostFlushTx (void)

uint16_t	serialCopyFromRx (const uint8_t *data, uint16_t length)

void	emLoadSerialTx (void)

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.
#define	EMBER_SERIAL_UNUSED 0
	A numerical definition for a possible serial mode the code can test for.

#define	EMBER_SERIAL_FIFO 1
	A numerical definition for a possible serial mode the code can test for.

#define	EMBER_SERIAL_BUFFER 2
	A numerical definition for a possible serial mode the code can test for.

#define	EMBER_SERIAL_LOWLEVEL 3
	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.
#define	FIFO_ENQUEUE (queue, data, size)
	Macro that enqueues a byte of data in a FIFO queue.

#define	FIFO_DEQUEUE (queue, size)
	Macro that de-queues a byte of data from a FIFO queue.

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.
EmberStatus	halInternalUartInit (uint8_t port, SerialBaudRate rate, SerialParity parity, uint8_t stopBits)
	Initializes the UART to the given settings (same parameters as ::emberSerialInit() ).

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.

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.

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.

void	halInternalStopUartTx (uint8_t port)
	Called by serial code to stop any interrupt-driven serial transmission currently in progress.

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.

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.

void	halInternalWaitUartTxComplete (uint8_t port)
	Blocks until the UART has finished transmitting any data in its hardware registers.

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

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.

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.

bool	halInternalUartTxIsIdle (uint8_t port)
	Returns true if the uart transmitter is idle, including the transmit shift register.

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.

#define	halInternalUartFlowControl (port) do {} while (false)
	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.

#define	halInternalUartRxPump (port) do {} while (false)
	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.

#define	halInternalUart1FlowControlRxIsEnabled () halInternalUartFlowControlRxIsEnabled (1)
	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.

#define	halInternalUart1XonRefreshDone () halInternalUartXonRefreshDone (1)
	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.

#define	halInternalUart1TxIsIdle () halInternalUartTxIsIdle (1)
	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.

Buffered Serial Utility APIs
The higher-level serial code implements these APIs, which the HAL uses to deal with buffered serial output.
void	emSerialBufferNextMessageIsr (EmSerialBufferQueue *q)
	When new serial transmission is started and `bufferQueue->nextByte` is equal to NULL, this can be called to set up `nextByte` and `lastByte` for the next message.

void	emSerialBufferNextBlockIsr (EmSerialBufferQueue *q, uint8_t port)
	When a serial transmission is in progress and `bufferQueue->nextByte` has been sent and incremented leaving it equal to lastByte, this should be called to set up `nextByte` and `lastByte` for the next block.

Virtual UART API
API used by the stack in debug builds to receive data arriving over the virtual UART.
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.

Detailed Description

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.

Macro Definition Documentation

#define EMBER_SERIAL_BUFFER 2

A numerical definition for a possible serial mode the code can test for.

#define EMBER_SERIAL_FIFO 1

A numerical definition for a possible serial mode the code can test for.

#define EMBER_SERIAL_LOWLEVEL 3

A numerical definition for a possible serial mode the code can test for.

#define EMBER_SERIAL_UNUSED 0

A numerical definition for a possible serial mode the code can test for.

#define FIFO_DEQUEUE	(	`queue,`
		`size`
	)

Value:

         (queue)->fifo[(queue)->tail];                   \
        
         (queue)->tail = (((queue)->tail + 1) % (size)); \
        
         (queue)->used--

Macro that de-queues a byte of data from a FIFO queue.

Parameters

`queue`	Pointer to the FIFO queue.
`size`	Size used to control the wrap-around of the FIFO pointers.

#define FIFO_ENQUEUE	(	`queue,`
		`data,`
		`size`
	)

Value:

         
          do
         
         {                                              \
        
         (queue)->fifo[(queue)->head] = (data);          \
        
         (queue)->head = (((queue)->head + 1) % (size)); \
        
         (queue)->used++;                                \
        
         }
         
          while
         
         (0)

Macro that enqueues a byte of data in a FIFO queue.

Parameters

`queue`	Pointer to the FIFO queue.
`data`	Data byte to be enqueued.
`size`	Size used to control the wrap-around of the FIFO pointers.

#define halInternalUart1FlowControlRxIsEnabled ( ) halInternalUartFlowControlRxIsEnabled (1)

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.

Parameters

port Serial port number (0 or 1). (Does nothing for port 0)

#define halInternalUart1TxIsIdle ( ) halInternalUartTxIsIdle (1)

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.

Parameters

port Serial port number (0 or 1). (Does nothing for port 0)

#define halInternalUart1XonRefreshDone ( ) halInternalUartXonRefreshDone (1)

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.

Parameters

port Serial port number (0 or 1). (Does nothing for port 0)

#define halInternalUartFlowControl ( port ) do {} while (false)

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.

Parameters

port Serial port number (0 or 1). (Does nothing for port 0)

#define halInternalUartRxPump ( port ) do {} while (false)

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.

Parameters

port Serial port number (0 or 1).

Enumeration Type Documentation

enum 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

enum 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

Function Documentation

void emLoadSerialTx ( void )

void emSerialBufferNextBlockIsr	(	EmSerialBufferQueue *	`q,`
		uint8_t	`port`
	)

When a serial transmission is in progress and bufferQueue->nextByte has been sent and incremented leaving it equal to lastByte, this should be called to set up nextByte and lastByte for the next block.

Parameters

`q`	Pointer to the buffer queue structure for the port.
`port`	Serial port number (0 or 1).

void emSerialBufferNextMessageIsr ( EmSerialBufferQueue * q )

When new serial transmission is started and bufferQueue->nextByte is equal to NULL, this can be called to set up nextByte and lastByte for the next message.

Parameters

`q`	Pointer to the buffer queue structure for the port.

uint16_t halHostEnqueueTx	(	const uint8_t *	`data,`
		uint16_t	`length`
	)

void halHostFlushBuffers ( void )

void halHostFlushTx ( void )

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.

Parameters

`port`	Serial port number (0 or 1).
`dataByte`	The byte to receive data into.

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.

Parameters

`port`	Serial port number (0 or 1).
`data`	Pointer to the data to be transmitted.
`length`	The length of data to be transmitted

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.

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.

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

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.

Parameters

port Serial port number (0 or 1).

void halInternalStopUartTx ( uint8_t port )

Called by serial code to stop any interrupt-driven serial transmission currently in progress.

Parameters

port Serial port number (0 or 1).

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.

EmberStatus halInternalUartInit	(	uint8_t	`port,`
		SerialBaudRate	`rate,`
		SerialParity	`parity,`
		uint8_t	`stopBits`
	)

Initializes the UART to the given settings (same parameters as ::emberSerialInit() ).

Parameters

`port`	Serial port number (0 or 1).
`rate`	Baud rate (see SerialBaudRate).
`parity`	Parity value (see SerialParity).
`stopBits`	Number of stop bits.

Returns: An error code if initialization failed (such as invalid baud rate), otherise EMBER_SUCCESS.

bool halInternalUartTxIsIdle ( uint8_t port )

Returns true if the uart transmitter is idle, including the transmit shift register.

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.

void halInternalWaitUartTxComplete ( uint8_t port )

Blocks until the UART has finished transmitting any data in its hardware registers.

Parameters

port Serial port number (0 or 1).

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.

Parameters

`data`	Pointer to the the data received
`length`	Length of the data received

uint16_t serialCopyFromRx	(	const uint8_t *	`data,`
		uint16_t	`length`
	)

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.

Serial UART Communication Hardware Abstraction Layer (HAL) API Reference > Sample APIs for Peripheral Access

Enumerations

Functions

Serial Mode Definitions

FIFO Utility Macros

Serial HAL APIs

Buffered Serial Utility APIs

Virtual UART API

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Serial UART Communication
Hardware Abstraction Layer (HAL) API Reference > Sample APIs for Peripheral Access