nRF5 SDK v12.1.0
Data Structures | Typedefs | Enumerations | Functions
Serialization HAL Transport

HAL Transport layer for serialization. More...

Data Structures

struct  ser_hal_transport_evt_rx_pkt_received_params_t
 Struct containing parameters of event of type SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED. More...
 
struct  ser_hal_transport_evt_phy_error_params_t
 Struct containing parameters of event of type SER_HAL_TRANSP_EVT_PHY_ERROR. More...
 
struct  ser_hal_transport_evt_t
 Struct containing events from the Serialization HAL Transport layer. More...
 

Typedefs

typedef void(* ser_hal_transport_events_handler_t )(ser_hal_transport_evt_t event)
 Generic callback function type to be used by all Serialization HAL Transport layer events. More...
 

Enumerations

enum  ser_hal_transport_evt_type_t {
  SER_HAL_TRANSP_EVT_TX_PKT_SENT = 0,
  SER_HAL_TRANSP_EVT_RX_PKT_RECEIVING,
  SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED,
  SER_HAL_TRANSP_EVT_RX_PKT_DROPPED,
  SER_HAL_TRANSP_EVT_PHY_ERROR,
  SER_HAL_TRANSP_EVT_TYPE_MAX
}
 Serialization HAL Transport layer event types. More...
 
enum  ser_hal_transport_phy_error_type_t {
  SER_HAL_TRANSP_PHY_ERROR_RX_OVERFLOW = 0,
  SER_HAL_TRANSP_PHY_ERROR_TX_OVERREAD,
  SER_HAL_TRANSP_PHY_ERROR_HW_ERROR,
  SER_HAL_TRANSP_PHY_ERROR_TYPE_MAX
}
 Serialization PHY layer error types. More...
 

Functions

uint32_t ser_hal_transport_open (ser_hal_transport_events_handler_t events_handler)
 Function for opening and initializing the Serialization HAL Transport layer. More...
 
void ser_hal_transport_close (void)
 Function for closing a transport channel. More...
 
uint32_t ser_hal_transport_rx_pkt_free (uint8_t *p_buffer)
 Function for freeing memory allocated for an RX packet. More...
 
uint32_t ser_hal_transport_tx_pkt_alloc (uint8_t **pp_memory, uint16_t *p_num_of_bytes)
 Function for allocating memory for a TX packet. More...
 
uint32_t ser_hal_transport_tx_pkt_send (const uint8_t *p_buffer, uint16_t num_of_bytes)
 Function for transmitting a packet. More...
 
uint32_t ser_hal_transport_tx_pkt_free (uint8_t *p_buffer)
 Function for freeing memory allocated for a TX packet. More...
 

Detailed Description

HAL Transport layer for serialization.

This section contains declarations of functions and typedefs used as API of the HAL Transport layer for serialization. This layer is fully hardware independent. Currently, the HAL Transport layer is responsible for controlling the PHY layer and memory management. In the future, it is possible to add more features to it, such as crc or retransmission.



ser_hal_transport_rx_state_machine.png
RX state machine



ser_hal_transport_tx_state_machine.png
TX state machine


Typedef Documentation

typedef void(* ser_hal_transport_events_handler_t)(ser_hal_transport_evt_t event)

Generic callback function type to be used by all Serialization HAL Transport layer events.

Parameters
[in]eventSerialization HAL Transport layer event.

Enumeration Type Documentation

Serialization HAL Transport layer event types.

Enumerator
SER_HAL_TRANSP_EVT_TX_PKT_SENT 

An event indicating that TX packet has been transmitted.

SER_HAL_TRANSP_EVT_RX_PKT_RECEIVING 

An event indicating that RX packet is being scheduled to receive or to drop.

SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED 

An event indicating that RX packet is ready for read.

SER_HAL_TRANSP_EVT_RX_PKT_DROPPED 

An event indicating that RX packet was dropped because it was longer than available buffer.

SER_HAL_TRANSP_EVT_PHY_ERROR 

An event indicating error on PHY layer.

SER_HAL_TRANSP_EVT_TYPE_MAX 

Enumeration upper bound.

Serialization PHY layer error types.

Enumerator
SER_HAL_TRANSP_PHY_ERROR_RX_OVERFLOW 

An error indicating that more information has been transmitted than the PHY module could handle.

SER_HAL_TRANSP_PHY_ERROR_TX_OVERREAD 

An error indicating that the PHY module was forced to transmit more information than possessed.

SER_HAL_TRANSP_PHY_ERROR_HW_ERROR 

An error indicating a hardware error in the PHY module.

SER_HAL_TRANSP_PHY_ERROR_TYPE_MAX 

Enumeration upper bound.

Function Documentation

void ser_hal_transport_close ( void  )

Function for closing a transport channel.

Note
The function disables the hardware, resets internal module states, and unregisters the events callback function. Can be called multiple times, also for a channel that is not opened.
uint32_t ser_hal_transport_open ( ser_hal_transport_events_handler_t  events_handler)

Function for opening and initializing the Serialization HAL Transport layer.

Note
The function opens the transport channel, initializes a PHY layer, and registers the callback function to be used by all Serialization HAL Transport layer events.
Warning
If the function has been already called, the function ser_hal_transport_close has to be called before ser_hal_transport_open can be called again.
Parameters
[in]events_handlerGeneric callback function to be used by all Serialization HAL Transport layer events.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_PARAMOperation failure. Hardware initialization parameters taken from the configuration file are wrong.
NRF_ERROR_INVALID_STATEOperation failure. The function has been already called. To call it again the function ser_hal_transport_close has to be called first.
NRF_ERROR_INTERNALOperation failure. Internal error ocurred.
uint32_t ser_hal_transport_rx_pkt_free ( uint8_t *  p_buffer)

Function for freeing memory allocated for an RX packet.

Note
The function should be called as a response to an event of type SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED when the received data has beed processed. The function frees the RX memory pointed by p_buffer. The memory, immediately or at a later time, is reused by the underlying transport layer.
Parameters
[in]p_bufferA pointer to the beginning of the buffer that has been processed (has to be the same address as provided in the event of type SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED).
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_ADDROperation failure. Not a valid pointer (provided address is not the starting address of a buffer managed by HAL Transport layer).
NRF_ERROR_INVALID_STATEOperation failure. The function should be called as a response to an event of type SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED.
NRF_ERROR_INTERNALOperation failure. Internal error ocurred.
uint32_t ser_hal_transport_tx_pkt_alloc ( uint8_t **  pp_memory,
uint16_t *  p_num_of_bytes 
)

Function for allocating memory for a TX packet.

Parameters
[out]pp_memoryA pointer to pointer to which an address of the beginning of the allocated buffer is written.
[out]p_num_of_bytesA pointer to a variable to which size in octets of the allocated buffer is written.
Return values
NRF_SUCCESSOperation success. Memory was allocated.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_NO_MEMOperation failure. No memory available.
NRF_ERROR_INVALID_STATEOperation failure. The function was called before calling ser_hal_transport_open function.
uint32_t ser_hal_transport_tx_pkt_free ( uint8_t *  p_buffer)

Function for freeing memory allocated for a TX packet.

Note
The function frees the TX memory pointed by p_buffer. Freeing a TX buffer is possible only if the buffer was allocated by ser_hal_transport_tx_pkt_alloc function and transmittion is not in progress. When transmittion has finished, this function is automatically called by the Serialization HAL Transport layer, so the only case when this function should be used from outside is when a TX buffer was allocated but a transmittion has not been started (ser_hal_transport_tx_pkt_send function has not been called).
Parameters
[in]p_bufferPointer to the beginning of a buffer that has been allocated by ser_hal_transport_tx_pkt_alloc function.
Return values
NRF_SUCCESSOperation success. Memory was freed.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_ADDROperation failure. Not a valid pointer (provided address is not the starting address of a buffer managed by HAL Transport layer).
NRF_ERROR_INVALID_STATEOperation failure. Freeing a TX buffer is possible only if the buffer was allocated by ser_hal_transport_tx_pkt_alloc function and transmittion is not in progress.
uint32_t ser_hal_transport_tx_pkt_send ( const uint8_t *  p_buffer,
uint16_t  num_of_bytes 
)

Function for transmitting a packet.

Note
The function adds a packet pointed by the p_buffer parameter to a transmission queue. A buffer provided to this function must be allocated by the ser_hal_transport_tx_pkt_alloc function.
Warning
Completion of this method does not guarantee that actual peripheral transmission will be completed.
Parameters
[in]p_bufferPointer to the buffer to transmit.
[in]num_of_bytesNumber of octets to transmit. Must be more than 0.
Return values
NRF_SUCCESSOperation success. Packet was added to the transmission queue.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_PARAMOperation failure. num_of_bytes is equal to 0.
NRF_ERROR_INVALID_ADDROperation failure. Not a valid pointer (provided address is not the starting address of a buffer managed by HAL Transport layer).
NRF_ERROR_DATA_SIZEOperation failure. Packet size exceeds limit.
NRF_ERROR_BUSYOperation failure. Transmission queue is full so packet was not added to the transmission queue.
NRF_ERROR_INVALID_STATEOperation failure. Transmittion channel was not opened by ser_hal_transport_open function or provided buffer was not allocated by ser_hal_transport_tx_pkt_alloc function.
NRF_ERROR_INTERNALOperation failure. Internal error ocurred.

Documentation feedback | Developer Zone | Subscribe | Updated