Serial UART Communication
This API contains the HAL interfaces that applications must implement for the high-level serial code.
Modules |
|
ASHv3 Functionality for realiable UART communication |
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 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 |
#define EMBER_SERIAL_FIFO 1 |
#define EMBER_SERIAL_LOWLEVEL 3 |
#define EMBER_SERIAL_UNUSED 0 |
#define FIFO_DEQUEUE | ( |
queue,
|
|
size
|
|||
) |
- Parameters
-
queue
Pointer to the FIFO queue. size
Size used to control the wrap-around of the FIFO pointers.
Referenced by USBD_RemoteWakeup() .
#define FIFO_ENQUEUE | ( |
queue,
|
|
data,
|
|||
size
|
|||
) |
- 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) |
- Parameters
-
port
Serial port number (0 or 1). (Does nothing for port 0)
#define halInternalUart1TxIsIdle | ( |
|
) | halInternalUartTxIsIdle (1) |
- Parameters
-
port
Serial port number (0 or 1). (Does nothing for port 0)
#define halInternalUart1XonRefreshDone | ( |
|
) | halInternalUartXonRefreshDone (1) |
- Parameters
-
port
Serial port number (0 or 1). (Does nothing for port 0)
#define halInternalUartFlowControl | ( |
port
|
) | do {} while (false) |
- Parameters
-
port
Serial port number (0 or 1). (Does nothing for port 0)
#define halInternalUartRxPump | ( |
port
|
) | do {} while (false) |
- Parameters
-
port
Serial port number (0 or 1).
Enumeration Type Documentation
enum SerialBaudRate |
enum SerialParity |
Function Documentation
void emLoadSerialTx | ( | void |
|
) |
void emSerialBufferNextBlockIsr | ( | EmSerialBufferQueue * |
q,
|
uint8_t |
port
|
||
) |
- Parameters
-
q
Pointer to the buffer queue structure for the port. port
Serial port number (0 or 1).
void emSerialBufferNextMessageIsr | ( | EmSerialBufferQueue * |
q
|
) |
- 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
|
||
) |
- 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
|
||
) |
- 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 |
|
) |
void halInternalPowerUpUart | ( | void |
|
) |
void halInternalRestartUart | ( | void |
|
) |
void halInternalStartUartTx | ( | uint8_t |
port
|
) |
- Parameters
-
port
Serial port number (0 or 1).
void halInternalStopUartTx | ( | uint8_t |
port
|
) |
- Parameters
-
port
Serial port number (0 or 1).
bool halInternalUartFlowControlRxIsEnabled | ( | uint8_t |
port
|
) |
EmberStatus halInternalUartInit | ( | uint8_t |
port,
|
SerialBaudRate |
rate,
|
||
SerialParity |
parity,
|
||
uint8_t |
stopBits
|
||
) |
- 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
|
) |
bool halInternalUartXonRefreshDone | ( | uint8_t |
port
|
) |
void halInternalWaitUartTxComplete | ( | uint8_t |
port
|
) |
- Parameters
-
port
Serial port number (0 or 1).
void halStackReceiveVuartMessage | ( | uint8_t * |
data,
|
uint8_t |
length
|
||
) |
- 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 |
|
) |