nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Serialization PHY

PHY layer layer for serialization. More...

Data Structures

struct  ser_phy_evt_rx_buf_request_params_t
 A struct containing parameters of the event of type SER_PHY_EVT_RX_BUF_REQUEST. More...
 
struct  ser_phy_evt_rx_pkt_received_params_t
 A struct containing parameters of the event of type SER_PHY_EVT_RX_PKT_RECEIVED. More...
 
struct  ser_phy_evt_hw_error_params_t
 A struct containing parameters of the event of type SER_PHY_EVT_HW_ERROR. More...
 
struct  ser_phy_evt_t
 A struct containing events from a Serialization PHY module. More...
 

Typedefs

typedef void(* ser_phy_events_handler_t )(ser_phy_evt_t event)
 A type of generic callback function handler to be used by all PHY module events. More...
 

Enumerations

enum  ser_phy_evt_type_t {
  SER_PHY_EVT_TX_PKT_SENT = 0,
  SER_PHY_EVT_RX_BUF_REQUEST,
  SER_PHY_EVT_RX_PKT_RECEIVED,
  SER_PHY_EVT_RX_PKT_DROPPED,
  SER_PHY_EVT_RX_OVERFLOW_ERROR,
  SER_PHY_EVT_TX_OVERREAD_ERROR,
  SER_PHY_EVT_HW_ERROR,
  SER_PHY_EVT_TYPE_MAX
}
 Serialization PHY module events types. More...
 

Functions

uint32_t ser_phy_open (ser_phy_events_handler_t events_handler)
 A function for opening and initializing a PHY module. More...
 
uint32_t ser_phy_tx_pkt_send (const uint8_t *p_buffer, uint16_t num_of_bytes)
 A function for transmitting a packet. More...
 
uint32_t ser_phy_rx_buf_set (uint8_t *p_buffer)
 A function for setting an RX buffer and enabling reception of data (the PHY flow). More...
 
void ser_phy_close (void)
 A function for closing a PHY module. More...
 
void ser_phy_interrupts_enable (void)
 A function for enabling a PHY module interrupts. More...
 
void ser_phy_interrupts_disable (void)
 A function for disabling a PHY module interrupts. More...
 

Detailed Description

PHY layer layer for serialization.

This file contains declarations of functions and definitions of data structures and identifiers (typedef enum) used as API of the serialization PHY layer.

Rationale
Each specific PHY layer (SPI, I2C, UART, low power UART etc.) should provide the same API. This allows the layer above (the HAL Transport layer) which is responsible for controlling the PHY layer, memory management, crc, retransmission etc. to be hardware independent.
Interlayer communication and control
The PHY layer is controlled by the HAL Transport layer by calling functions declared in this file. The PHY layer communicates events to the HAL Transport layer by calling a callback function. A handler to this function is passed in the ser_phy_open function. This callback function should be called with parameter of type ser_phy_evt_t filled accordingly to an event to be passed. Types of supported events are defined in ser_phy_evt_type_t. For example to pass an event indicating that RX packet has been successfully received first a struct of type ser_phy_evt_t has to be filled: ser_phy_evt_t phy_evt; phy_evt.evt_type = SER_PHY_EVT_RX_PKT_RECEIVED; phy_evt.evt_params.rx_pkt_received.p_buffer = (pointer to the RX buffer); phy_evt.evt_params.rx_pkt_received.num_of_bytes = (number of received bytes); and then the callback function has to be called: events_handler(phy_evt); All functions declared in this file are obligatory to implement. Some events specified in the ser_phy_evt_type_t are optional to implement.
Transmitting a packet
Each PHY layer is responsible for adding the PHY header to a packet to be sent. This header shall consists of 16-bit field carrying the packet length (the uint16_encode function defined in app_util.h should be used to ensure endianness independence). A pointer to a packet to be sent and a length of the packet are parameters of the ser_phy_tx_pkt_send function. When a packet has been transmitted an event of type SER_PHY_EVT_TX_PKT_SENT should be emitted.
ser_phy_transport_tx.png
TX - interlayer communication
Receiving a packet
The PHY layer should be able to store only the PHY header (16-bit field carrying the packet length). After the PHY header has been received the transmission shall be halted and the PHY layer has to sent a request to the HAL Transport layer for a memory to store a packet - an event of type SER_PHY_EVT_RX_BUF_REQUEST with event parameters defined in ser_phy_evt_rx_buf_request_params_t (the uint16_decode function defined in app_util.h should be used for header decoding to ensure endianness independence). The transmission should be resumed when ser_phy_rx_buf_set function has been called.

When ser_phy_rx_buf_set function parameter is equal to NULL it means that there is not enough memory to store the packet, however the packet shall be received to dummy location to ensure continuous communication. After receiving has finished an event of type SER_PHY_EVT_RX_PKT_DROPPED shall be generated.

ser_phy_transport_rx_dropped.png
RX dropping - interlayer communication

When ser_phy_rx_buf_set function parameter is different from NULL the packet should be received to a buffer pointed by it. After receiving has finished an event of type SER_PHY_EVT_RX_PKT_RECEIVED shall be generated with event parameters defined in ser_phy_evt_rx_pkt_received_params_t.

ser_phy_transport_rx_received.png
RX - interlayer communication
PHY layer errors
PHY layer errors can be signaled by an event of type SER_PHY_EVT_RX_OVERFLOW_ERROR or SER_PHY_EVT_TX_OVERREAD_ERROR or SER_PHY_EVT_HW_ERROR with event parameters defined in ser_phy_evt_hw_error_params_t.

Typedef Documentation

typedef void(* ser_phy_events_handler_t)(ser_phy_evt_t event)

A type of generic callback function handler to be used by all PHY module events.

Parameters
[in]eventSerialization PHY module event.

Enumeration Type Documentation

Serialization PHY module events types.

Enumerator
SER_PHY_EVT_TX_PKT_SENT 

Obligatory to implement. An event indicating that TX packet has been transmitted.

SER_PHY_EVT_RX_BUF_REQUEST 

Obligatory to implement. An event indicating that phy layer needs a buffer for RX packet. A PHY flow should be blocked until ser_phy_rx_buf_set function is called.

SER_PHY_EVT_RX_PKT_RECEIVED 

Obligatory to implement. An event indicating that RX packet has been successfully received.

SER_PHY_EVT_RX_PKT_DROPPED 

Obligatory to implement. An event indicating that RX packet receiving has been finished but packet was discarded because it was longer than available buffer.

SER_PHY_EVT_RX_OVERFLOW_ERROR 

Optional to implement. An event indicating that more information has been transmitted than phy module could handle.

SER_PHY_EVT_TX_OVERREAD_ERROR 

Optional to implement. An event indicating that phy module was forced to transmit more information than possessed.

SER_PHY_EVT_HW_ERROR 

Optional to implement. An event indicating a hardware error in phy module.

SER_PHY_EVT_TYPE_MAX 

Enumeration upper bound.

Function Documentation

void ser_phy_close ( void  )

A function for closing a PHY module.

Note
The function disables hardware, resets internal module states and unregisters events callback function.
void ser_phy_interrupts_disable ( void  )

A function for disabling a PHY module interrupts.

Note
The function disables all interrupts that are used by a PHY module (and only those).
void ser_phy_interrupts_enable ( void  )

A function for enabling a PHY module interrupts.

Note
The function enables all interrupts that are used by a PHY module (and only those).
uint32_t ser_phy_open ( ser_phy_events_handler_t  events_handler)

A function for opening and initializing a PHY module.

Note
The function initializes hardware and internal module states, and registers callback function to be used by all PHY module events.
Warning
If the function has been already called, the function ser_phy_close has to be called before ser_phy_open can be called again.
Parameters
[in]events_handlerGeneric callback function handler to be used by all PHY module events.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_INVALID_STATEOperation failure. The function has been already called. To call it again the function ser_phy_close has to be called previously.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_PARAMOperation failure. Hardware initialization parameters are not supported.
uint32_t ser_phy_rx_buf_set ( uint8_t *  p_buffer)

A function for setting an RX buffer and enabling reception of data (the PHY flow).

Note
The function has to be called as a response to an event of type SER_PHY_EVT_RX_BUF_REQUEST. The function sets an RX buffer and enables reception of data (enables the PHY flow). Size of a buffer pointed by the p_buffer parameter should be at least equal to the num_of_bytes parameter passed within the event (ser_phy_evt_rx_buf_request_params_t) or p_buffer should be equal to NULL if there is not enough memory. When p_buffer is different from NULL and num_of_bytes octets has been received an event of type SER_PHY_EVT_RX_PKT_RECEIVED is generated (ser_phy_evt_rx_pkt_received_params_t). When p_buffer is equal to NULL data are received to dummy location to ensure continuous communication. Then if num_of_bytes octets has been received an event of type SER_PHY_EVT_RX_PKT_DROPPED is generated.
Parameters
[in]p_bufferPointer to an RX buffer where to receive.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_INVALID_STATEOperation failure. A buffer was set without request.
uint32_t ser_phy_tx_pkt_send ( const uint8_t *  p_buffer,
uint16_t  num_of_bytes 
)

A function for transmitting a packet.

Note
The function adds a packet pointed by p_buffer parameter to a transmission queue and schedules generating an event of type SER_PHY_EVT_TX_PKT_SENT upon transmission completion.
Parameters
[in]p_bufferPointer to a 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 and event will be send upon transmission completion.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_PARAMOperation failure. The num_of_bytes parameter equal to 0.
NRF_ERROR_BUSYOperation failure. Transmitting of a packet in progress.