cc y / mbed

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed by mbed official

TARGET_SEEED_TINY_BLE/TARGET_NORDIC/TARGET_MCU_NRF51822/Lib/nrf-sdk/app_common/hal_transport.h@94:9ad691361fac, 2015-02-16 (annotated)

Committer:
Kojto
Date:
Mon Feb 16 16:32:49 2015 +0000
Revision:
94:9ad691361fac
Parent:
TARGET_BLE_SMURFS/TARGET_NORDIC/TARGET_MCU_NRF51822/Lib/nrf-sdk/app_common/hal_transport.h@93:e188a91d3eaa 
Release 94 of the mbed library



Main changes:



- LPC11U68 - ARM toolchain addition

- Nordic - IAR toolchain addition

- LPC8xx - I2c Slave functionality addition

- fix for HRM1017 regarding clock init

- new target - MicroNFCBoard

- exit() move to retarget

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kojto 93:e188a91d3eaa 1 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
Kojto 93:e188a91d3eaa 2 *
Kojto 93:e188a91d3eaa 3 * The information contained herein is property of Nordic Semiconductor ASA.
Kojto 93:e188a91d3eaa 4 * Terms and conditions of usage are described in detail in NORDIC
Kojto 93:e188a91d3eaa 5 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
Kojto 93:e188a91d3eaa 6 *
Kojto 93:e188a91d3eaa 7 * Licensees are granted free, non-transferable use of the information. NO
Kojto 93:e188a91d3eaa 8 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
Kojto 93:e188a91d3eaa 9 * the file.
Kojto 93:e188a91d3eaa 10 *
Kojto 93:e188a91d3eaa 11 */
Kojto 93:e188a91d3eaa 12
Kojto 93:e188a91d3eaa 13 /**@file
Kojto 93:e188a91d3eaa 14 *
Kojto 93:e188a91d3eaa 15 * @defgroup hci_transport HCI Transport
Kojto 93:e188a91d3eaa 16 * @{
Kojto 93:e188a91d3eaa 17 * @ingroup app_common
Kojto 93:e188a91d3eaa 18 *
Kojto 93:e188a91d3eaa 19 * @brief HCI transport module implementation.
Kojto 93:e188a91d3eaa 20 *
Kojto 93:e188a91d3eaa 21 * This module implements certain specific features from the three-wire UART transport layer,
Kojto 93:e188a91d3eaa 22 * defined by the Bluetooth specification version 4.0 [Vol 4] part D.
Kojto 93:e188a91d3eaa 23 *
Kojto 93:e188a91d3eaa 24 * \par Features supported
Kojto 93:e188a91d3eaa 25 * - Transmission and reception of Vendor Specific HCI packet type application packets.
Kojto 93:e188a91d3eaa 26 * - Transmission and reception of reliable packets: defined by chapter 6 of the specification.
Kojto 93:e188a91d3eaa 27 *
Kojto 93:e188a91d3eaa 28 * \par Features not supported
Kojto 93:e188a91d3eaa 29 * - Link establishment procedure: defined by chapter 8 of the specification.
Kojto 93:e188a91d3eaa 30 * - Low power: defined by chapter 9 of the specification.
Kojto 93:e188a91d3eaa 31 *
Kojto 93:e188a91d3eaa 32 * \par Implementation specific behaviour
Kojto 93:e188a91d3eaa 33 * - As Link establishment procedure is not supported following static link configuration parameters
Kojto 93:e188a91d3eaa 34 * are used:
Kojto 93:e188a91d3eaa 35 * + TX window size is 1.
Kojto 93:e188a91d3eaa 36 * + 16 bit CCITT-CRC must be used.
Kojto 93:e188a91d3eaa 37 * + Out of frame software flow control not supported.
Kojto 93:e188a91d3eaa 38 * + Parameters specific for resending reliable packets are compile time configurable (clarifed
Kojto 93:e188a91d3eaa 39 * later in this document).
Kojto 93:e188a91d3eaa 40 * + Acknowledgement packet transmissions are not timeout driven , meaning they are delivered for
Kojto 93:e188a91d3eaa 41 * transmission within same context which the corresponding application packet was received.
Kojto 93:e188a91d3eaa 42 *
Kojto 93:e188a91d3eaa 43 * \par Implementation specific limitations
Kojto 93:e188a91d3eaa 44 * Current implementation has the following limitations which will have impact to system wide
Kojto 93:e188a91d3eaa 45 * behaviour:
Kojto 93:e188a91d3eaa 46 * - Delayed acknowledgement scheduling not implemented:
Kojto 93:e188a91d3eaa 47 * There exists a possibility that acknowledgement TX packet and application TX packet will collide
Kojto 93:e188a91d3eaa 48 * in the TX pipeline having the end result that acknowledgement packet will be excluded from the TX
Kojto 93:e188a91d3eaa 49 * pipeline which will trigger the retransmission algorithm within the peer protocol entity.
Kojto 93:e188a91d3eaa 50 * - Delayed retransmission scheduling not implemented:
Kojto 93:e188a91d3eaa 51 * There exists a possibility that retransmitted application TX packet and acknowledgement TX packet
Kojto 93:e188a91d3eaa 52 * will collide in the TX pipeline having the end result that retransmitted application TX packet
Kojto 93:e188a91d3eaa 53 * will be excluded from the TX pipeline.
Kojto 93:e188a91d3eaa 54 * - Processing of the acknowledgement number from RX application packets:
Kojto 93:e188a91d3eaa 55 * Acknowledgement number is not processed from the RX application packets having the end result
Kojto 93:e188a91d3eaa 56 * that unnecessary application packet retransmissions can occur.
Kojto 93:e188a91d3eaa 57 *
Kojto 93:e188a91d3eaa 58 * The application TX packet processing flow is illustrated by the statemachine below.
Kojto 93:e188a91d3eaa 59 *
Kojto 93:e188a91d3eaa 60 * @image html hci_transport_tx_sm.png "TX - application packet statemachine"
Kojto 93:e188a91d3eaa 61 *
Kojto 93:e188a91d3eaa 62 * \par Component specific configuration options
Kojto 93:e188a91d3eaa 63 *
Kojto 93:e188a91d3eaa 64 * The following compile time configuration options are available, and used to configure the
Kojto 93:e188a91d3eaa 65 * application TX packet retransmission interval, in order to suite various application specific
Kojto 93:e188a91d3eaa 66 * implementations:
Kojto 93:e188a91d3eaa 67 * - MAC_PACKET_SIZE_IN_BITS Maximum size of a single application packet in bits.
Kojto 93:e188a91d3eaa 68 * - USED_BAUD_RATE Used uart baudrate.
Kojto 93:e188a91d3eaa 69 *
Kojto 93:e188a91d3eaa 70 * The following compile time configuration option is available to configure module specific
Kojto 93:e188a91d3eaa 71 * behaviour:
Kojto 93:e188a91d3eaa 72 * - MAX_RETRY_COUNT Max retransmission retry count for applicaton packets.
Kojto 93:e188a91d3eaa 73 */
Kojto 93:e188a91d3eaa 74
Kojto 93:e188a91d3eaa 75 #ifndef HCI_TRANSPORT_H__
Kojto 93:e188a91d3eaa 76 #define HCI_TRANSPORT_H__
Kojto 93:e188a91d3eaa 77
Kojto 93:e188a91d3eaa 78 #include <stdint.h>
Kojto 93:e188a91d3eaa 79 #include "nrf_error.h"
Kojto 93:e188a91d3eaa 80
Kojto 93:e188a91d3eaa 81 #define HCI_TRANSPORT_PKT_HEADER_SIZE (2) /**< Size of transport packet header */
Kojto 93:e188a91d3eaa 82
Kojto 93:e188a91d3eaa 83 /**@brief Generic event callback function events. */
Kojto 93:e188a91d3eaa 84 typedef enum
Kojto 93:e188a91d3eaa 85 {
Kojto 93:e188a91d3eaa 86 HCI_TRANSPORT_RX_RDY, /**< An event indicating that RX packet is ready for read. */
Kojto 93:e188a91d3eaa 87 HCI_TRANSPORT_EVT_TYPE_MAX /**< Enumeration upper bound. */
Kojto 93:e188a91d3eaa 88 } hci_transport_evt_type_t;
Kojto 93:e188a91d3eaa 89
Kojto 93:e188a91d3eaa 90 /**@brief Struct containing events from the Transport layer.
Kojto 93:e188a91d3eaa 91 */
Kojto 93:e188a91d3eaa 92 typedef struct
Kojto 93:e188a91d3eaa 93 {
Kojto 93:e188a91d3eaa 94 hci_transport_evt_type_t evt_type; /**< Type of event. */
Kojto 93:e188a91d3eaa 95 } hci_transport_evt_t;
Kojto 93:e188a91d3eaa 96
Kojto 93:e188a91d3eaa 97 /**@brief Transport layer generic event callback function type.
Kojto 93:e188a91d3eaa 98 *
Kojto 93:e188a91d3eaa 99 * @param[in] event Transport layer event.
Kojto 93:e188a91d3eaa 100 */
Kojto 93:e188a91d3eaa 101 typedef void (*hci_transport_event_handler_t)(hci_transport_evt_t event);
Kojto 93:e188a91d3eaa 102
Kojto 93:e188a91d3eaa 103 /**@brief TX done event callback function result codes. */
Kojto 93:e188a91d3eaa 104 typedef enum
Kojto 93:e188a91d3eaa 105 {
Kojto 93:e188a91d3eaa 106 HCI_TRANSPORT_TX_DONE_SUCCESS, /**< Transmission success, peer transport entity has acknowledged the transmission. */
Kojto 93:e188a91d3eaa 107 HCI_TRANSPORT_TX_DONE_FAILURE /**< Transmission failure. */
Kojto 93:e188a91d3eaa 108 } hci_transport_tx_done_result_t;
Kojto 93:e188a91d3eaa 109
Kojto 93:e188a91d3eaa 110 /**@brief Transport layer TX done event callback function type.
Kojto 93:e188a91d3eaa 111 *
Kojto 93:e188a91d3eaa 112 * @param[in] result TX done event result code.
Kojto 93:e188a91d3eaa 113 */
Kojto 93:e188a91d3eaa 114 typedef void (*hci_transport_tx_done_handler_t)(hci_transport_tx_done_result_t result);
Kojto 93:e188a91d3eaa 115
Kojto 93:e188a91d3eaa 116 /**@brief Function for registering a generic event handler.
Kojto 93:e188a91d3eaa 117 *
Kojto 93:e188a91d3eaa 118 * @note Multiple registration requests will overwrite any possible existing registration.
Kojto 93:e188a91d3eaa 119 *
Kojto 93:e188a91d3eaa 120 * @param[in] event_handler The function to be called by the transport layer upon an event.
Kojto 93:e188a91d3eaa 121 *
Kojto 93:e188a91d3eaa 122 * @retval NRF_SUCCESS Operation success.
Kojto 93:e188a91d3eaa 123 * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
Kojto 93:e188a91d3eaa 124 */
Kojto 93:e188a91d3eaa 125 uint32_t hci_transport_evt_handler_reg(hci_transport_event_handler_t event_handler);
Kojto 93:e188a91d3eaa 126
Kojto 93:e188a91d3eaa 127 /**@brief Function for registering a handler for TX done event.
Kojto 93:e188a91d3eaa 128 *
Kojto 93:e188a91d3eaa 129 * @note Multiple registration requests will overwrite any possible existing registration.
Kojto 93:e188a91d3eaa 130 *
Kojto 93:e188a91d3eaa 131 * @param[in] event_handler The function to be called by the transport layer upon TX done
Kojto 93:e188a91d3eaa 132 * event.
Kojto 93:e188a91d3eaa 133 *
Kojto 93:e188a91d3eaa 134 * @retval NRF_SUCCESS Operation success.
Kojto 93:e188a91d3eaa 135 * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
Kojto 93:e188a91d3eaa 136 */
Kojto 93:e188a91d3eaa 137 uint32_t hci_transport_tx_done_register(hci_transport_tx_done_handler_t event_handler);
Kojto 93:e188a91d3eaa 138
Kojto 93:e188a91d3eaa 139 /**@brief Function for opening the transport channel and initializing the transport layer.
Kojto 93:e188a91d3eaa 140 *
Kojto 93:e188a91d3eaa 141 * @warning Must not be called for a channel which has been allready opened.
Kojto 93:e188a91d3eaa 142 *
Kojto 93:e188a91d3eaa 143 * @retval NRF_SUCCESS Operation success.
Kojto 93:e188a91d3eaa 144 * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
Kojto 93:e188a91d3eaa 145 */
Kojto 93:e188a91d3eaa 146 uint32_t hci_transport_open(void);
Kojto 93:e188a91d3eaa 147
Kojto 93:e188a91d3eaa 148 /**@brief Function for closing the transport channel.
Kojto 93:e188a91d3eaa 149 *
Kojto 93:e188a91d3eaa 150 * @note Can be called multiple times and also for not opened channel.
Kojto 93:e188a91d3eaa 151 *
Kojto 93:e188a91d3eaa 152 * @retval NRF_SUCCESS Operation success.
Kojto 93:e188a91d3eaa 153 */
Kojto 93:e188a91d3eaa 154 uint32_t hci_transport_close(void);
Kojto 93:e188a91d3eaa 155
Kojto 93:e188a91d3eaa 156 /**@brief Function for allocating tx packet memory.
Kojto 93:e188a91d3eaa 157 *
Kojto 93:e188a91d3eaa 158 * @param[out] pp_memory Pointer to the packet data.
Kojto 93:e188a91d3eaa 159 *
Kojto 93:e188a91d3eaa 160 * @retval NRF_SUCCESS Operation success. Memory was allocated.
Kojto 93:e188a91d3eaa 161 * @retval NRF_ERROR_NO_MEM Operation failure. No memory available.
Kojto 93:e188a91d3eaa 162 * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
Kojto 93:e188a91d3eaa 163 */
Kojto 93:e188a91d3eaa 164 uint32_t hci_transport_tx_alloc(uint8_t ** pp_memory);
Kojto 93:e188a91d3eaa 165
Kojto 93:e188a91d3eaa 166 /**@brief Function for freeing tx packet memory.
Kojto 93:e188a91d3eaa 167 *
Kojto 93:e188a91d3eaa 168 * @note Memory management works in FIFO principle meaning that free order must match the alloc
Kojto 93:e188a91d3eaa 169 * order.
Kojto 93:e188a91d3eaa 170 *
Kojto 93:e188a91d3eaa 171 * @retval NRF_SUCCESS Operation success. Memory was freed.
Kojto 93:e188a91d3eaa 172 */
Kojto 93:e188a91d3eaa 173 uint32_t hci_transport_tx_free(void);
Kojto 93:e188a91d3eaa 174
Kojto 93:e188a91d3eaa 175 /**@brief Function for writing a packet.
Kojto 93:e188a91d3eaa 176 *
Kojto 93:e188a91d3eaa 177 * @note Completion of this method does not guarantee that actual peripheral transmission would
Kojto 93:e188a91d3eaa 178 * have completed.
Kojto 93:e188a91d3eaa 179 *
Kojto 93:e188a91d3eaa 180 * @note In case of 0 byte packet length write request, message will consist of only transport
Kojto 93:e188a91d3eaa 181 * module specific headers.
Kojto 93:e188a91d3eaa 182 *
Kojto 93:e188a91d3eaa 183 * @note The buffer provided to this function must be allocated through @ref hci_transport_tx_alloc
Kojto 93:e188a91d3eaa 184 * function.
Kojto 93:e188a91d3eaa 185 *
Kojto 93:e188a91d3eaa 186 * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue
Kojto 93:e188a91d3eaa 187 * and an event will be send upon transmission completion.
Kojto 93:e188a91d3eaa 188 * @retval NRF_ERROR_NO_MEM Operation failure. Transmission queue is full and packet was not
Kojto 93:e188a91d3eaa 189 * added to the transmission queue. User should wait for
Kojto 93:e188a91d3eaa 190 * a appropriate event prior issuing this operation again.
Kojto 93:e188a91d3eaa 191 * @retval NRF_ERROR_DATA_SIZE Operation failure. Packet size exceeds limit.
Kojto 93:e188a91d3eaa 192 * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
Kojto 93:e188a91d3eaa 193 * @retval NRF_ERROR_INVALID_STATE Operation failure. Channel is not open.
Kojto 93:e188a91d3eaa 194 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Buffer provided is not allocated through
Kojto 93:e188a91d3eaa 195 * hci_transport_tx_alloc function.
Kojto 93:e188a91d3eaa 196 */
Kojto 93:e188a91d3eaa 197 uint32_t hci_transport_pkt_write(const uint8_t * p_buffer, uint16_t length);
Kojto 93:e188a91d3eaa 198
Kojto 93:e188a91d3eaa 199 /**@brief Function for extracting received packet.
Kojto 93:e188a91d3eaa 200 *
Kojto 93:e188a91d3eaa 201 * @note Extracted memory can't be reused by the underlying transport layer untill freed by call to
Kojto 93:e188a91d3eaa 202 * hci_transport_rx_pkt_consume().
Kojto 93:e188a91d3eaa 203 *
Kojto 93:e188a91d3eaa 204 * @param[out] pp_buffer Pointer to the packet data.
Kojto 93:e188a91d3eaa 205 * @param[out] p_length Length of packet data in bytes.
Kojto 93:e188a91d3eaa 206 *
Kojto 93:e188a91d3eaa 207 * @retval NRF_SUCCESS Operation success. Packet was extracted.
Kojto 93:e188a91d3eaa 208 * @retval NRF_ERROR_NO_MEM Operation failure. No packet available to extract.
Kojto 93:e188a91d3eaa 209 * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
Kojto 93:e188a91d3eaa 210 */
Kojto 93:e188a91d3eaa 211 uint32_t hci_transport_rx_pkt_extract(uint8_t ** pp_buffer, uint16_t * p_length);
Kojto 93:e188a91d3eaa 212
Kojto 93:e188a91d3eaa 213 /**@brief Function for consuming extracted packet described by p_buffer.
Kojto 93:e188a91d3eaa 214 *
Kojto 93:e188a91d3eaa 215 * RX memory pointed to by p_buffer is freed and can be reused by the underlying transport layer.
Kojto 93:e188a91d3eaa 216 *
Kojto 93:e188a91d3eaa 217 * @param[in] p_buffer Pointer to the buffer that has been consumed.
Kojto 93:e188a91d3eaa 218 *
Kojto 93:e188a91d3eaa 219 * @retval NRF_SUCCESS Operation success.
Kojto 93:e188a91d3eaa 220 * @retval NRF_ERROR_NO_MEM Operation failure. No packet available to consume.
Kojto 93:e188a91d3eaa 221 * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer.
Kojto 93:e188a91d3eaa 222 */
Kojto 93:e188a91d3eaa 223 uint32_t hci_transport_rx_pkt_consume(uint8_t * p_buffer);
Kojto 93:e188a91d3eaa 224
Kojto 93:e188a91d3eaa 225 #endif // HCI_TRANSPORT_H__
Kojto 93:e188a91d3eaa 226
Kojto 93:e188a91d3eaa 227 /** @} */