HCI Transport

nRF5 SDK v12.1.0
Modules | Data Structures | Typedefs | Enumerations | Functions

HCI transport module implementation. More...

Modules

CRC16 compute
This module implements CRC-16-CCITT (polynomial 0x1021) with 0xFFFF initial value. The data can be passed in multiple blocks.
CRC32 compute
This module implements the CRC-32 calculation in the blocks.
HCI transport configuration

Data Structures

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

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...

Enumerations

enum hci_transport_evt_type_t {
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
}
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...

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.

Page-1 Start/End-point Start Start Process.245 TX_STATE_IDLE TX_STATE_IDLE Process.291 TX_STATE_ACTIVE TX_STATE_ACTIVE Process.292 TX_STATE_PENDING TX_STATE_PENDING Flowline2 hci_transport_pkt_write [hci_slip_write(...) == NRF_ERROR_NO_... Straight Edge.28 N Straight Edge.29 N hci_transport_pkt_write [hci_slip_write(...) == NRF_ERROR_NO_MEM] Flowline2.296 app_timer_timeout_handle [m_tx_retry_counter == MAX_RETRY_COU... Straight Edge.28 N Straight Edge.29 N app_timer_timeout_handle [m_tx_retry_counter == MAX_RETRY_COUNT] Flowline2.299 hci_transport_pkt_write [hci_slip_write(...) == NRF_SUCCESS] Straight Edge.28 N Straight Edge.29 N hci_transport_pkt_write [hci_slip_write(...) == NRF_SUCCESS] Flowline1 evt-HCI_SLIP_RX_RDY [valid ACK for Tx packet] / packet_number... evt-HCI_SLIP_RX_RDY [valid ACK for Tx packet] / packet_number_tx_inc() Flowline2.303 evt-HCI_SLIP_TX_DONE / hci_slip_write(...) Straight Edge.28 N Straight Edge.29 N evt-HCI_SLIP_TX_DONE / hci_slip_write(...) Flowline1.306 Sheet.307 hci_transport_pkt_write(...) / return NRF_ERROR_NO_MEM hci_transport_pkt_write(...) / return NRF_ERROR_NO_MEM Sheet.309 entry / STOP retransmit timer send: evt-tx_done(result) entry / STOP retransmit timer send: evt-tx_done(result) Sheet.311 entry / START retransmit timer (continuous mode) m_tx_retry_c... entry / START retransmit timer (continuous mode) m_tx_retry_counter = 0 app_timer_timeout_handle [m_tx_retry_counter == MAX_RETRY_COUNT] / transmit last application packet hci_transport_pkt_write(...) / return NRF_ERROR_NO_MEM
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:

  • MAC_PACKET_SIZE_IN_BITS Maximum size of a single application packet in bits.
  • USED_BAUD_RATE Used uart baudrate.

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

  • MAX_RETRY_COUNT Max retransmission retry count for applicaton packets.

Typedef Documentation

typedef void(* hci_transport_event_handler_t)( hci_transport_evt_t event)

Transport layer generic event callback function type.

Parameters
[in] event Transport 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] result TX done event result code.

Enumeration Type Documentation

enum hci_transport_evt_type_t

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.

enum hci_transport_tx_done_result_t

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.

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_SUCCESS Operation 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_handler The function to be called by the transport layer upon an event.
Return values
NRF_SUCCESS Operation success.
NRF_ERROR_NULL Operation 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_SUCCESS Operation success.
NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
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.
Return values
NRF_SUCCESS Operation success. Packet was added to the transmission queue and an event will be send upon transmission completion.
NRF_ERROR_NO_MEM Operation 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_SIZE Operation failure. Packet size exceeds limit.
NRF_ERROR_NULL Operation failure. NULL pointer supplied.
NRF_ERROR_INVALID_STATE Operation failure. Channel is not open.
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_buffer Pointer to the buffer that has been consumed.
Return values
NRF_SUCCESS Operation success.
NRF_ERROR_NO_MEM Operation failure. No packet available to consume.
NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer.
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_buffer Pointer to the packet data.
[out] p_length Length of packet data in bytes.
Return values
NRF_SUCCESS Operation success. Packet was extracted.
NRF_ERROR_NO_MEM Operation failure. No packet available to extract.
NRF_ERROR_NULL Operation failure. NULL pointer supplied.
uint32_t hci_transport_tx_alloc ( uint8_t ** pp_memory )

Function for allocating tx packet memory.

Parameters
[out] pp_memory Pointer to the packet data.
Return values
NRF_SUCCESS Operation success. Memory was allocated.
NRF_ERROR_NO_MEM Operation failure. No memory available.
NRF_ERROR_NULL Operation 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_handler The function to be called by the transport layer upon TX done event.
Return values
NRF_SUCCESS Operation success.
NRF_ERROR_NULL Operation 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_SUCCESS Operation success. Memory was freed.