XDK API  3.6.0
Documentation
Files | Data Structures | Macros | Typedefs | Enumerations | Functions
UARTTransceiver

Advanced API functions for sending and reveiving via UART and LEUART. More...

+ Collaboration diagram for UARTTransceiver:

Files

file  BCDS_UARTTransceiver.h
 

Data Structures

struct  _UARTTransceiver_S
 

Macros

#define UART_TRANSCEIVER_DECLARE_LOOP_CALLBACK(transceiver)
 Generates a UART loop callback. More...
 

Typedefs

typedef void(* UARTransceiver_Callback_T )(struct MCU_UART_Event_S event)
 
typedef bool(* UARTTransceiver_EndofFrameCheckFunc_T )(uint8_t lastByte)
 
typedef struct _UARTTransceiver_S UARTTransceiver_T
 

Enumerations

enum  UARTTransceiver_Mode_E
 
enum  UARTTransceiver_State_E
 
enum  UARTTransceiver_UartType_E
 

Functions

Retcode_T UARTTransceiver_Deinitialize (UARTTransceiver_T *transceiver)
 De-initializes the transceiver. More...
 
Retcode_T UARTTransceiver_Initialize (UARTTransceiver_T *transceiver, HWHandle_T handle, uint8_t *rawRxBuffer, uint32_t rawRxBufferSize, enum UARTTransceiver_UartType_E type)
 Initializes the transceiver for the use with the passed UART or LEUART handle. More...
 
void UARTTransceiver_LoopCallback (UARTTransceiver_T *transceiver, struct MCU_UART_Event_S event)
 Function to loop the UART/LEUART callback. More...
 
Retcode_T UARTTransceiver_ReadData (UARTTransceiver_T *transceiver, uint8_t *buffer, uint32_t size, uint32_t *length, uint32_t timeout_ms)
 It reads the data received by the transceiver. More...
 
Retcode_T UARTTransceiver_Resume (UARTTransceiver_T *transceiver)
 It resumes the transceiver after it has been suspended. More...
 
Retcode_T UARTTransceiver_Start (UARTTransceiver_T *transceiver, UARTTransceiver_EndofFrameCheckFunc_T frameEndCheckFunc)
 It activates the transceiver to start receiving and sending in the synchronous operation mode. More...
 
Retcode_T UARTTransceiver_StartInAsyncMode (UARTTransceiver_T *transceiver, UARTTransceiver_EndofFrameCheckFunc_T frameEndCheckFunc, UARTransceiver_Callback_T callback)
 It activates the transceiver to start receiving and sending in the asynchronous operation mode. More...
 
Retcode_T UARTTransceiver_Stop (UARTTransceiver_T *transceiver)
 It stops the transceiver. More...
 
Retcode_T UARTTransceiver_Suspend (UARTTransceiver_T *transceiver)
 It suspends the transceiver. More...
 
Retcode_T UARTTransceiver_WriteData (UARTTransceiver_T *transceiver, uint8_t *data, uint32_t length, uint32_t timeout_ms)
 It writes the data for sending. More...
 

Detailed Description

The UARTTransceiver encapsulates the handling of buffers and the control flow.

The typical use of the UARTTransceiver starts with initializing it.

The transceiver supports two operation modes: synchronous mode and asynchronous mode.The transceiver is started in the synchronous mode by calling the function UARTTransceiver_Start(). In order to operate the transceiver in the asynchronous mode, the function UARTTransceiver_StartInAsyncMode() should be used instead. After the start, the transceiver starts to receive bytes, in the ISR context, and store them internally into a ring buffer. While receiving the transceiver applies the end-of-frame check function to every received byte. If it returns true, then the transceiver will perform one of the following action depending on its operation mode:

  1. In the asynchronous mode, the registered callback is invoked to notify the upper-layer. The upper-layer will fetch the data from the transceiver's buffer using the function UARTTransceiver_ReadData().
  2. In the synchronous mode, the upper-layer is expected to call UARTTransceiver_ReadData(). The call is blocking. When the end-of-frame check function returns true, the semaphore is released such that the call of UARTTransceiver_ReadData() returns, where the frame is copied into the buffer which was passed as a parameter.

The function UARTTransceiver_WriteData() sends data via the under-laying UART or LEUART. In the asynchronous mode, the write operation triggers the sending and returns. A callback follows to inform the upper-layer about the success or failure of the operation. In the synchronous mode, the write operation blocks until all bytes are sent. No callback will follow.

UARTTransceiver provides also the functions UARTTransceiver_Suspend(), UARTTransceiver_Resume(), UARTTransceiver_Stop() to control the activity of the transceiver, in particular the receiving activity in the background.

Note
UARTTransceiver is a passive component without an own task. It is driven by the caller task and the interrupts coming form UART or LEUART.
UARTTransceiver maintains its context in a struct which makes it ready for multiple-instance use. This means, multiple UARTTransceiver instances may co-exist in the same application. However, they must operate on different UART or LEUART ports.

Data Structure Documentation

struct _UARTTransceiver_S
+ Collaboration diagram for _UARTTransceiver_S:

Data Fields

union MCU_UART_Event_U AsyncEvent
 
UARTransceiver_Callback_T callback
 
UARTTransceiver_EndofFrameCheckFunc_T EndOfFrameCheck
 
enum Retcode_General_E errorCode
 
HWHandle_T handle
 
uint8_t LastByte
 
enum UARTTransceiver_Mode_E Mode
 
uint8_t * RawRxBuffer
 
uint32_t RawRxBufferSize
 
SemaphoreHandle_t RxSemaphore
 
enum UARTTransceiver_State_E State
 
SemaphoreHandle_t TxSemaphore
 
RingBuffer_T UartRxBufDescr
 
enum UARTTransceiver_UartType_E UartType
 

Field Documentation

union MCU_UART_Event_U AsyncEvent
enum Retcode_General_E errorCode
HWHandle_T handle
uint8_t LastByte
uint8_t* RawRxBuffer
uint32_t RawRxBufferSize
SemaphoreHandle_t RxSemaphore
SemaphoreHandle_t TxSemaphore
RingBuffer_T UartRxBufDescr

Macro Definition Documentation

#define UART_TRANSCEIVER_DECLARE_LOOP_CALLBACK (   transceiver)
Value:
static BCDS_ALWAYS_INLINE void UARTTransceiverLoopCallback(UART_T uart, struct MCU_UART_Event_S event) \
{ \
UARTTransceiver_LoopCallback(&transceiver, event);\
}
void UARTTransceiver_LoopCallback(UARTTransceiver_T *transceiver, struct MCU_UART_Event_S event)
Function to loop the UART/LEUART callback.
#define BCDS_ALWAYS_INLINE
Macro to force the compiler to always inline an inline function.
Definition: BCDS_Basics.h:159

The middle-layer driver, which uses UART/LEUART and UARTTransceiver, may use this macro in oder to generate a callback function to initialize UART/LEUART with it. The generated function loops the callback to the transceiver by calling the function UARTTransceiver_LoopCallback().

Parameters
[in]transceiverThe variable name of the transceiver. It must be a pointer to the context structure but the context structure itself.

Typedef Documentation

typedef void(* UARTransceiver_Callback_T)(struct MCU_UART_Event_S event)
typedef bool(* UARTTransceiver_EndofFrameCheckFunc_T)(uint8_t lastByte)

Enumeration Type Documentation

Enumerator
UART_TRANSCEIVER_MODE_NONE 
UART_TRANSCEIVER_MODE_SYNCH 
UART_TRANSCEIVER_MODE_ASYNCH 
Enumerator
UART_TRANSCEIVER_STATE_RESET 
UART_TRANSCEIVER_STATE_IDLE 
UART_TRANSCEIVER_STATE_INITIALIZED 
UART_TRANSCEIVER_STATE_ACTIVE 
UART_TRANSCEIVER_STATE_STOPPED 
UART_TRANSCEIVER_STATE_SUSPENDED 
Enumerator
UART_TRANSCEIVER_UART_TYPE_NONE 
UART_TRANSCEIVER_UART_TYPE_UART 
UART_TRANSCEIVER_UART_TYPE_LEUART 

Function Documentation

Retcode_T UARTTransceiver_Deinitialize ( UARTTransceiver_T transceiver)

The transceiver must not be used after calling this function.

Parameters
[in]transceivera pointer to the transceiver context structure to be de-initialized
Return values
RETCODE_OKif successfully deinitialize
RETCODE_INVALID_PARAMif the transceiver pointer parameter is NULL

+ Here is the caller graph for this function:

Retcode_T UARTTransceiver_Initialize ( UARTTransceiver_T transceiver,
HWHandle_T  handle,
uint8_t *  rawRxBuffer,
uint32_t  rawRxBufferSize,
enum UARTTransceiver_UartType_E  type 
)
Parameters
[in]transceivera pointer to the transceiver context structure to be initialized
[in]handlethe handle of the UART or LEUART to be used by the transceiver. The handle must be initialized before passing it here.
[in]modeThe mode in which the transceiver will operate, i.e. synchronous or asynchronous.

@ rawRxBuffer The buffer which will be used by the transceiver internally to save the received bytes. It must not be NULL.

Parameters
[in]rawRxBufferSizeThe size of the rawRxBuffer. It must be larger than zero.
Return values
RETCODE_OKif successfully initialized
RETCODE_INVALID_PARAMif any of the parameter is NULL
RETCODE_SEMAPHORE_ERRORif the semaphores are not created (see UARTTransceiver_T.TxSemaphore and UARTTransceiver_T.RxSemaphore)
RETCODE_DOPPLE_INITIALIZATIONif you are trying to initialized the transceiver again

+ Here is the caller graph for this function:

void UARTTransceiver_LoopCallback ( UARTTransceiver_T transceiver,
struct MCU_UART_Event_S  event 
)

It is necessary for the UARTTransceiver to loop the UART/LEUART callback. This means, the middle-layer driver which uses UART/LEUART and UARTTransceiver must initialize UART/LEUART with a callback function which invokes this function in order to loop the callbacks from UART/LEUART to the transceiver.

The middle-layer driver may use the macro UART_TRANSCEIVER_DECLARE_LOOP_CALLBACK can be used to generate such a callback.

Parameters
[in]transceiverThe transceiver
[in]eventThe event which is notified by the callback

+ Here is the caller graph for this function:

Retcode_T UARTTransceiver_ReadData ( UARTTransceiver_T transceiver,
uint8_t *  buffer,
uint32_t  size,
uint32_t *  length,
uint32_t  timeout_ms 
)

The transceiver must be started and not suspended when calling this function.

In the synchronous mode, this call will return only after the End-of-Frame check function which is used by the transceiver returns true. This holds even if the number of the received bytes exceeds the given buffer size. In the asynchronous mode, the function copies the bytes which have been already received an returns immediately. In both cases, the number bytes saved to the given buffer never exceeds the given buffer size. If more bytes are available in the transceiver internal buffer, they will reside there.

Parameters
[in]transceivera pointer to the transceiver
[in]bufferThe buffer which the bytes are copied to.
[in]sizeThe buffer size. Independent of the number of the bytes which the transceiver has received, no more bytes are saved to the given buffer than the given size.
[out]lengthThe number of received bytes which were saved to the given buffer.
[in]timeout_msin synchronous modeThe function will return with an error if this time elapsed before receiving the end of frame character
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif any parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an active state (see UARTTransceiver_State_E)
RETCODE_SEMAPHORE_ERRORif semaphore could not be taken with given timeout (see UARTTransceiver_T.RxSemaphore)

+ Here is the caller graph for this function:

Retcode_T UARTTransceiver_Resume ( UARTTransceiver_T transceiver)

The transceiver must be suspended when calling this function.

Parameters
[in]transceivera pointer to the transceiver to be resumed.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif transceiver pointer parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an suspended state (see UARTTransceiver_State_E)
Retcode_T UARTTransceiver_Start ( UARTTransceiver_T transceiver,
UARTTransceiver_EndofFrameCheckFunc_T  frameEndCheckFunc 
)
Parameters
[in]transceivera pointer to the transceiver to be started.
[in]frameEndCheckFuncA function pointer which is used by the transceiver to detect the end of the frame in order to invoke the callback.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif transceiver pointer parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an initialized state (see UARTTransceiver_State_E)
Retcode_T UARTTransceiver_StartInAsyncMode ( UARTTransceiver_T transceiver,
UARTTransceiver_EndofFrameCheckFunc_T  frameEndCheckFunc,
UARTransceiver_Callback_T  callback 
)
Note
Beside the operation mode, this function does the same as the function UARTTransceiver_Start().
Parameters
[in]transceivera pointer to the transceiver to be started.
[in]frameEndCheckFuncA function pointer which is used by the transceiver to detect the end of the frame in order to invoke the callback.
[in]callbackA callback function which will be invoked on RX and TX events, e.g. errors or operation completeness in the asynchronous mode.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif transceiver pointer parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an initialized state (see UARTTransceiver_State_E)

+ Here is the caller graph for this function:

Retcode_T UARTTransceiver_Stop ( UARTTransceiver_T transceiver)

The transceiver must be started when calling this function. When the transceiver is stopped, read or write operations are not permitted. Resuming the transceiver after stopping it is not possible. It must be started using the UARTTransceiver_Start() function.

Parameters
[in]transceivera pointer to the transceiver to be suspended.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif transceiver pointer parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an active or already suspended state (see UARTTransceiver_State_E)
Retcode_T UARTTransceiver_Suspend ( UARTTransceiver_T transceiver)

The transceiver must be started when calling this function. When the transceiver is suspended read or write operations are not permitted.

Parameters
[in]transceivera pointer to the transceiver to be suspended.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif transceiver pointer parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an active state (see UARTTransceiver_State_E)
Retcode_T UARTTransceiver_WriteData ( UARTTransceiver_T transceiver,
uint8_t *  data,
uint32_t  length,
uint32_t  timeout_ms 
)

The transceiver must be started and not suspended when calling this function.

In the synchronous mode, this call will return only after the passed bytes have been send over UART/LEUART. In the asynchronous mode, the function triggers the sending and returns immediately. A callback follows to inform about the success or failure of the send operation.

Parameters
[in]transceivera pointer to the transceiver
[in]bufferThe buffer which the bytes are copied to.
[in]lengthThe buffer length and the number of bytes to be copied.
[in]timeout_msThe time afterwhich if the function does not succeed for any reason it will return an semaphore error.
Return values
RETCODE_OKif successfully started
RETCODE_INVALID_PARAMif any parameter is NULL
RETCODE_INCONSITENT_STATEif the transceiver is not in an active state (see UARTTransceiver_State_E)
RETCODE_SEMAPHORE_ERRORif semaphore could not be taken with given timeout (see UARTTransceiver_T.TxSemaphore)

+ Here is the caller graph for this function:


All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:52 by doxygen 1.8.8