nRF51 SDK - S210 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

HCI transport module implementation. More...

Modules

 CRC compute
 This module implements the CRC-16 calculation in the blocks.
 

Data Structures

struct  hci_transport_evt_t
 Struct containing events from the Transport layer. More...
 

Macros

#define HCI_TRANSPORT_PKT_HEADER_SIZE   (2)
 

Typedefs

typedef void(* hci_transport_event_handler_t )(hci_transport_evt_t event)
 Transport layer generic event callback function type. More...
 
typedef void(* hci_transport_tx_done_handler_t )(hci_transport_tx_done_result_t result)
 Transport layer TX done event callback function type. More...
 
typedef void(* hci_transport_event_handler_t )(hci_transport_evt_t event)
 Transport layer generic event callback function type. More...
 
typedef void(* hci_transport_tx_done_handler_t )(hci_transport_tx_done_result_t result)
 Transport layer TX done event callback function type. More...
 

Enumerations

enum  hci_transport_evt_type_t {
  HCI_TRANSPORT_RX_RDY,
  HCI_TRANSPORT_EVT_TYPE_MAX,
  HCI_TRANSPORT_RX_RDY,
  HCI_TRANSPORT_EVT_TYPE_MAX
}
 Generic event callback function events. More...
 
enum  hci_transport_tx_done_result_t {
  HCI_TRANSPORT_TX_DONE_SUCCESS,
  HCI_TRANSPORT_TX_DONE_FAILURE,
  HCI_TRANSPORT_TX_DONE_SUCCESS,
  HCI_TRANSPORT_TX_DONE_FAILURE
}
 TX done event callback function result codes. More...
 
enum  hci_transport_evt_type_t {
  HCI_TRANSPORT_RX_RDY,
  HCI_TRANSPORT_EVT_TYPE_MAX,
  HCI_TRANSPORT_RX_RDY,
  HCI_TRANSPORT_EVT_TYPE_MAX
}
 Generic event callback function events. More...
 
enum  hci_transport_tx_done_result_t {
  HCI_TRANSPORT_TX_DONE_SUCCESS,
  HCI_TRANSPORT_TX_DONE_FAILURE,
  HCI_TRANSPORT_TX_DONE_SUCCESS,
  HCI_TRANSPORT_TX_DONE_FAILURE
}
 TX done event callback function result codes. More...
 

Functions

uint32_t hci_transport_evt_handler_reg (hci_transport_event_handler_t event_handler)
 Function for registering a generic event handler. More...
 
uint32_t hci_transport_tx_done_register (hci_transport_tx_done_handler_t event_handler)
 Function for registering a handler for TX done event. More...
 
uint32_t hci_transport_open (void)
 Function for opening the transport channel and initializing the transport layer. More...
 
uint32_t hci_transport_close (void)
 Function for closing the transport channel. More...
 
uint32_t hci_transport_tx_alloc (uint8_t **pp_memory)
 Function for allocating tx packet memory. More...
 
uint32_t hci_transport_tx_free (void)
 Function for freeing tx packet memory. More...
 
uint32_t hci_transport_pkt_write (const uint8_t *p_buffer, uint16_t length)
 Function for writing a packet. More...
 
uint32_t hci_transport_rx_pkt_extract (uint8_t **pp_buffer, uint16_t *p_length)
 Function for extracting received packet. More...
 
uint32_t hci_transport_rx_pkt_consume (uint8_t *p_buffer)
 Function for consuming extracted packet described by p_buffer. More...
 
uint32_t hci_transport_pkt_write (const uint8_t *p_buffer, uint32_t length)
 Function for writing a packet. More...
 
uint32_t hci_transport_rx_pkt_extract (uint8_t **pp_buffer, uint32_t *p_length)
 Function for extracting received packet. More...
 

Detailed Description

HCI transport module implementation.

This module implements certain specific features from the three-wire UART transport layer, defined by the Bluetooth specification version 4.0 [Vol 4] part D.

Features supported
  • Transmission and reception of Vendor Specific HCI packet type application packets.
  • Transmission and reception of reliable packets: defined by chapter 6 of the specification.
Features not supported
  • Link establishment procedure: defined by chapter 8 of the specification.
  • Low power: defined by chapter 9 of the specification.
Implementation specific behaviour
  • As Link establishment procedure is not supported following static link configuration parameters are used:
  • TX window size is 1.
  • 16 bit CCITT-CRC must be used.
  • Out of frame software flow control not supported.
  • Parameters specific for resending reliable packets are compile time configurable (clarifed later in this document).
  • Acknowledgement packet transmissions are not timeout driven , meaning they are delivered for transmission within same context which the corresponding application packet was received.
Implementation specific limitations
Current implementation has the following limitations which will have impact to system wide behaviour:
  • Delayed acknowledgement scheduling not implemented: There exists a possibility that acknowledgement TX packet and application TX packet will collide in the TX pipeline having the end result that acknowledgement packet will be excluded from the TX pipeline which will trigger the retransmission algorithm within the peer protocol entity.
  • Delayed retransmission scheduling not implemented: There exists a possibility that retransmitted application TX packet and acknowledgement TX packet will collide in the TX pipeline having the end result that retransmitted application TX packet will be excluded from the TX pipeline.
  • Processing of the acknowledgement number from RX application packets: Acknowledgement number is not processed from the RX application packets having the end result that unnecessary application packet retransmissions can occur.

The application TX packet processing flow is illustrated by the statemachine below.

hci_transport_tx_sm.png
TX - application packet statemachine
Component specific configuration options

The following compile time configuration options are available, and used to configure the application TX packet retransmission interval, in order to suite various application specific implementations:

The following compile time configuration option is available to configure module specific behaviour:

Macro Definition Documentation

#define HCI_TRANSPORT_PKT_HEADER_SIZE   (2)

Size of transport packet header

Typedef Documentation

typedef void(* hci_transport_event_handler_t)(hci_transport_evt_t event)

Transport layer generic event callback function type.

Parameters
[in]eventTransport layer event.
typedef void(* hci_transport_event_handler_t)(hci_transport_evt_t event)

Transport layer generic event callback function type.

Parameters
[in]eventTransport layer event.
typedef void(* hci_transport_tx_done_handler_t)(hci_transport_tx_done_result_t result)

Transport layer TX done event callback function type.

Parameters
[in]resultTX done event result code.
typedef void(* hci_transport_tx_done_handler_t)(hci_transport_tx_done_result_t result)

Transport layer TX done event callback function type.

Parameters
[in]resultTX done event result code.

Enumeration Type Documentation

Generic event callback function events.

Enumerator
HCI_TRANSPORT_RX_RDY 

An event indicating that RX packet is ready for read.

HCI_TRANSPORT_EVT_TYPE_MAX 

Enumeration upper bound.

HCI_TRANSPORT_RX_RDY 

An event indicating that RX packet is ready for read.

HCI_TRANSPORT_EVT_TYPE_MAX 

Enumeration upper bound.

Generic event callback function events.

Enumerator
HCI_TRANSPORT_RX_RDY 

An event indicating that RX packet is ready for read.

HCI_TRANSPORT_EVT_TYPE_MAX 

Enumeration upper bound.

HCI_TRANSPORT_RX_RDY 

An event indicating that RX packet is ready for read.

HCI_TRANSPORT_EVT_TYPE_MAX 

Enumeration upper bound.

TX done event callback function result codes.

Enumerator
HCI_TRANSPORT_TX_DONE_SUCCESS 

Transmission success, peer transport entity has acknowledged the transmission.

HCI_TRANSPORT_TX_DONE_FAILURE 

Transmission failure.

HCI_TRANSPORT_TX_DONE_SUCCESS 

Transmission success, peer transport entity has acknowledged the transmission.

HCI_TRANSPORT_TX_DONE_FAILURE 

Transmission failure.

TX done event callback function result codes.

Enumerator
HCI_TRANSPORT_TX_DONE_SUCCESS 

Transmission success, peer transport entity has acknowledged the transmission.

HCI_TRANSPORT_TX_DONE_FAILURE 

Transmission failure.

HCI_TRANSPORT_TX_DONE_SUCCESS 

Transmission success, peer transport entity has acknowledged the transmission.

HCI_TRANSPORT_TX_DONE_FAILURE 

Transmission failure.

Function Documentation

uint32_t hci_transport_close ( void  )

Function for closing the transport channel.

Note
Can be called multiple times and also for not opened channel.
Return values
NRF_SUCCESSOperation success.
uint32_t hci_transport_evt_handler_reg ( hci_transport_event_handler_t  event_handler)

Function for registering a generic event handler.

Note
Multiple registration requests will overwrite any possible existing registration.
Parameters
[in]event_handlerThe function to be called by the transport layer upon an event.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
uint32_t hci_transport_open ( void  )

Function for opening the transport channel and initializing the transport layer.

Warning
Must not be called for a channel which has been allready opened.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_INTERNALOperation failure. Internal error ocurred.
uint32_t hci_transport_pkt_write ( const uint8_t *  p_buffer,
uint32_t  length 
)

Function for writing a packet.

Note
Completion of this method does not guarantee that actual peripheral transmission would have completed.
In case of 0 byte packet length write request, message will consist of only transport module specific headers.
Return values
NRF_SUCCESSOperation success. Packet was added to the transmission queue and an event will be send upon transmission completion.
NRF_ERROR_NO_MEMOperation failure. Transmission queue is full and packet was not added to the transmission queue. User should wait for a appropriate event prior issuing this operation again.
NRF_ERROR_DATA_SIZEOperation failure. Packet size exceeds limit.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_STATEOperation failure. Channel is not open.
uint32_t hci_transport_pkt_write ( const uint8_t *  p_buffer,
uint16_t  length 
)

Function for writing a packet.

Note
Completion of this method does not guarantee that actual peripheral transmission would have completed.
In case of 0 byte packet length write request, message will consist of only transport module specific headers.
The buffer provided to this function must be allocated through hci_transport_tx_alloc function.
Return values
NRF_SUCCESSOperation success. Packet was added to the transmission queue and an event will be send upon transmission completion.
NRF_ERROR_NO_MEMOperation failure. Transmission queue is full and packet was not added to the transmission queue. User should wait for a appropriate event prior issuing this operation again.
NRF_ERROR_DATA_SIZEOperation failure. Packet size exceeds limit.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
NRF_ERROR_INVALID_STATEOperation failure. Channel is not open.
NRF_ERROR_INVALID_ADDROperation failure. Buffer provided is not allocated through hci_transport_tx_alloc function.
uint32_t hci_transport_rx_pkt_consume ( uint8_t *  p_buffer)

Function for consuming extracted packet described by p_buffer.

RX memory pointed to by p_buffer is freed and can be reused by the underlying transport layer.

Parameters
[in]p_bufferPointer to the buffer that has been consumed.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NO_MEMOperation failure. No packet available to consume.
NRF_ERROR_INVALID_ADDROperation failure. Not a valid pointer.
uint32_t hci_transport_rx_pkt_extract ( uint8_t **  pp_buffer,
uint32_t *  p_length 
)

Function for extracting received packet.

Note
Extracted memory can't be reused by the underlying transport layer untill freed by call to hci_transport_rx_pkt_consume().
Parameters
[out]pp_bufferPointer to the packet data.
[out]p_lengthLength of packet data in bytes.
Return values
NRF_SUCCESSOperation success. Packet was extracted.
NRF_ERROR_NO_MEMOperation failure. No packet available to extract.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
uint32_t hci_transport_rx_pkt_extract ( uint8_t **  pp_buffer,
uint16_t *  p_length 
)

Function for extracting received packet.

Note
Extracted memory can't be reused by the underlying transport layer untill freed by call to hci_transport_rx_pkt_consume().
Parameters
[out]pp_bufferPointer to the packet data.
[out]p_lengthLength of packet data in bytes.
Return values
NRF_SUCCESSOperation success. Packet was extracted.
NRF_ERROR_NO_MEMOperation failure. No packet available to extract.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
uint32_t hci_transport_tx_alloc ( uint8_t **  pp_memory)

Function for allocating tx packet memory.

Parameters
[out]pp_memoryPointer to the packet data.
Return values
NRF_SUCCESSOperation success. Memory was allocated.
NRF_ERROR_NO_MEMOperation failure. No memory available.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
uint32_t hci_transport_tx_done_register ( hci_transport_tx_done_handler_t  event_handler)

Function for registering a handler for TX done event.

Note
Multiple registration requests will overwrite any possible existing registration.
Parameters
[in]event_handlerThe function to be called by the transport layer upon TX done event.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NULLOperation failure. NULL pointer supplied.
uint32_t hci_transport_tx_free ( void  )

Function for freeing tx packet memory.

Note
Memory management works in FIFO principle meaning that free order must match the alloc order.
Return values
NRF_SUCCESSOperation success. Memory was freed.