diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy_hci.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy_hci.h | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy_hci.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy_hci.h new file mode 100644 index 0000000..c2993fd --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy_hci.h @@ -0,0 +1,183 @@ +/** + * Copyright (c) 2014 - 2018, Nordic Semiconductor ASA + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form, except as embedded into a Nordic + * Semiconductor ASA integrated circuit in a product or a software update for + * such product, must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * 3. Neither the name of Nordic Semiconductor ASA nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * 4. This software, with or without modification, must only be used with a + * Nordic Semiconductor ASA integrated circuit. + * + * 5. Any software provided in binary form under this license must not be reverse + * engineered, decompiled, modified and/or disassembled. + * + * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS + * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ +/** @file + * + * @defgroup ser_phy_hci HCI Serialization PHY + * @{ + * @ingroup ble_sdk_lib_serialization + * + * @brief HCI PHY layer for serialization. + * + * @details This file contains declarations of functions and definitions of data structures and + * identifiers (typedef enum) used as API of the serialization HCI PHY layer. + * + * + */ + +#ifndef SER_PHY_HCI_H__ +#define SER_PHY_HCI_H__ + +#include <stdint.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/**@brief Serialization PHY HCI module events types. */ +typedef enum +{ + SER_PHY_HCI_SLIP_EVT_PKT_SENT = 0, /**< An event indicating that packet has been transmitted. */ + SER_PHY_HCI_SLIP_EVT_ACK_SENT, /**< An event indicating that ack packet has been transmitted. */ + SER_PHY_HCI_SLIP_EVT_PKT_RECEIVED, /**< An event indicating that packet has been received. */ + SER_PHY_HCI_SLIP_EVT_HW_ERROR, /**< An event indicating a hardware error in PHY HCI module. */ + SER_PHY_HCI_SLIP_EVT_TYPE_MAX /**< Enumeration upper bound. */ +} ser_phy_hci_slip_evt_type_t; + +/**@brief Struct representing a PHY HCI packet. */ +typedef struct +{ + uint8_t * p_buffer; /**< Pointer to a buffer containing a packet. */ + uint16_t num_of_bytes; /**< Length of a packet in octets. */ +} ser_phy_hci_pkt_params_t; + + +/**@brief Struct containing parameters of event of type @ref SER_PHY_HCI_SLIP_EVT_HW_ERROR. */ +typedef struct +{ + uint32_t error_code; /**< Hardware error code - specific for a microcontroller. */ +} ser_phy_hci_evt_hw_error_params_t; + + +/**@brief Struct containing events from the Serialization PHY module. + * + * @note Some events do not have parameters, then the whole information is contained in the evt_type. + */ +typedef struct +{ + ser_phy_hci_slip_evt_type_t evt_type; /**< Type of an event. */ + union /**< Union alternative identified by evt_type in the enclosing struct. */ + { + /** Parameters of event of type @ref SER_PHY_HCI_SLIP_EVT_PKT_RECEIVED. */ + ser_phy_hci_pkt_params_t received_pkt; + /** Parameters of event of type @ref SER_PHY_HCI_SLIP_EVT_HW_ERROR. */ + ser_phy_hci_evt_hw_error_params_t hw_error; + } evt_params; +} ser_phy_hci_slip_evt_t; + + +/**@brief Type of generic callback function handler to be used by all PHY HCI events. + * + * @param[in] event Serialization PHY HCI module event. + */ +typedef void (*ser_phy_hci_slip_event_handler_t)(ser_phy_hci_slip_evt_t *p_event); + +/**@brief Function for opening and initializing a HCI SLIP PHY module. + * + * @note The function initializes hardware and internal module states and registers callback + * function to be used by all PHY HCI module events. + * + * @warning If the function has been already called, the function @ref ser_phy_hci_slip_close has to be + * called before ser_phy_hci_slip_open can be called again. + * + * @param[in] events_handler Generic callback function handler to be used by all PHY HCI module + * events. + * + * @retval NRF_SUCCESS Operation success. + * @retval NRF_ERROR_INVALID_STATE Operation failure. The function has been already called. + * To call it again, the function @ref ser_phy_hci_slip_close has to + * be called first. + * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied. + * @retval NRF_ERROR_INVALID_PARAM Operation failure. Hardware initialization parameters are not + * supported. + */ +uint32_t ser_phy_hci_slip_open(ser_phy_hci_slip_event_handler_t events_handler); + + +/**@brief A function for transmitting a HCI SLIP packet. + * + * @note The function adds a packet pointed by p_buffer parameter to a transmission queue and + * schedules generation of an event of type @ref SER_PHY_HCI_SLIP_EVT_PKT_SENT upon transmission + * completion. + * + * @param[in] p_header Pointer to ser_phy_hci_pkt_params_t structure representing packet header. + * @param[in] p_payload Pointer to ser_phy_hci_pkt_params_t structure representing packet payload. + * @param[in] p_crc Pointer to ser_phy_hci_pkt_params_t structure representing packet crc. + * + * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue + * and event will be sent upon transmission completion. + * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied in p_header parameter. + * NULL pointer is allowed for p_payload and p_crc parameters. + * @retval NRF_ERROR_INVALID_PARAM Operation failure. Number of bytes to be sent equals 0. + * @retval NRF_ERROR_BUSY Operation failure. Transmitting of a packet in progress. + */ +uint32_t ser_phy_hci_slip_tx_pkt_send(const ser_phy_hci_pkt_params_t * p_header, + const ser_phy_hci_pkt_params_t * p_payload, + const ser_phy_hci_pkt_params_t * p_crc); + + +/**@brief A function for freeing an RX buffer. + * + * @note The function has to be called as a response to event @ref SER_PHY_HCI_SLIP_EVT_PKT_RECEIVED + * when an RX packet has been processed. The function frees the RX buffer and therefore enables + * reception of next incoming data. + + * @param[in] p_buffer Pointer to an RX buffer which must be freed. + * + * @retval NRF_SUCCESS Operation success. + * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied. + * @retval NRF_ERROR_INVALID_STATE Operation failure. A buffer was already free. + */ +uint32_t ser_phy_hci_slip_rx_buf_free(uint8_t * p_buffer); + + +/**@brief A function for closing a PHY HCI module. + * + * @note The function disables hardware, resets internal module states, and unregisters the events + * callback function. + */ +void ser_phy_hci_slip_close(void); + + +#ifdef __cplusplus +} +#endif + +#endif /* SER_PHY_HCI_H__ */ +/** @} */ |