nRF51 SDK: HCI Transport

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
HCI Transport
SDK Common Libraries

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.