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.

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.

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] event Transport layer event.

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.

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.
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_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.
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.
HCI_TRANSPORT_TX_DONE_SUCCESS	Transmission success, peer transport entity has acknowledged the transmission.
HCI_TRANSPORT_TX_DONE_FAILURE	Transmission failure.

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.
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,
		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_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_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_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.
NRF_ERROR_INVALID_ADDR	Operation 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_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,
		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_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_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.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation