diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy.h | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy.h new file mode 100644 index 0000000..d40c06e --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/serialization/common/transport/ser_phy/ser_phy.h @@ -0,0 +1,308 @@ +/** + * 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 Serialization PHY + * @{ + * @ingroup ble_sdk_lib_serialization + * + * @brief PHY layer for serialization. + * + * @details The @ref ser_phy library declares functions and definitions of data structures and + * identifiers (typedef enum) that are used as API of the serialization PHY layer. + * + * \par Rationale + * Each specific PHY layer (SPI, I2C, UART, low power UART etc.) should provide the same API. This + * allows the layer above (the HAL Transport layer), which is responsible for controlling the PHY + * layer, memory management, CRC, retransmission etc., to be hardware independent. + * + * + * \par Interlayer communication and control + * The PHY layer is controlled by the HAL transport layer by calling functions declared in + * the @ref ser_phy library. + * + * @par + * The PHY layer communicates events to the HAL transport layer by calling a callback function. + * A handler to this function is passed in the @ref ser_phy_open function. This callback function + * should be called with a parameter of type @ref ser_phy_evt_t, filled accordingly to an event to be + * passed. Types of supported events are defined in @ref ser_phy_evt_type_t. + * + * @par + * For example, to pass an event indicating that an RX packet has been successfully received, first a + * struct of type @ref ser_phy_evt_t must be filled: + * @code + * ser_phy_evt_t phy_evt; + * phy_evt.evt_type = SER_PHY_EVT_RX_PKT_RECEIVED; + * phy_evt.evt_params.rx_pkt_received.p_buffer = (pointer to the RX buffer); + * phy_evt.evt_params.rx_pkt_received.num_of_bytes = (number of received bytes); + * @endcode + * Then, the callback function must be called: + * @code + * events_handler(phy_evt); + * @endcode + * All functions declared in the @ref ser_phy file (ser_phy.h) must be implemented. Some events specified in + * @ref ser_phy_evt_type_t are optional to implement. + * + * \par Transmitting a packet + * Each PHY layer is responsible for adding the PHY header to a packet to be sent. This header + * consists of a 16-bit field that carries the packet length (the uint16_encode function defined in + * app_util.h should be used to ensure endianness independence). A pointer to a packet to be sent + * and length of the packet are parameters of the @ref ser_phy_tx_pkt_send function. When a packet + * has been transmitted, an event of type @ref SER_PHY_EVT_TX_PKT_SENT should be emitted. + * + * \image html ser_phy_transport_tx.svg "TX - interlayer communication" + * + * \par Receiving a packet + * The PHY layer should be able to store only the PHY header (16-bit field carrying the packet + * length). After the PHY header has been received, the transmission is stopped and the PHY + * layer must send a request to the HAL transport layer for memory to store the packet - an event + * of type @ref SER_PHY_EVT_RX_BUF_REQUEST with event parameters defined in + * @ref ser_phy_evt_rx_buf_request_params_t (the uint16_decode function defined in app_util.h should + * be used for header decoding to ensure endianness independence). The transmission should be + * resumed when the @ref ser_phy_rx_buf_set function has been called. + * + * @par + * When the @ref ser_phy_rx_buf_set function parameter equals NULL, there is not + * enough memory to store the packet. However, the packet will be received to a dummy location to + * ensure continuous communication. After receiving has finished, an event of type + * @ref SER_PHY_EVT_RX_PKT_DROPPED is generated. + * + * \image html ser_phy_transport_rx_dropped.svg "RX dropping - interlayer communication" + * + * @par + * When the @ref ser_phy_rx_buf_set function parameter is different than NULL, the packet is + * received to a buffer pointed to by it. After receiving has finished, an event of type + * @ref SER_PHY_EVT_RX_PKT_RECEIVED is generated with event parameters defined in + * @ref ser_phy_evt_rx_pkt_received_params_t. + * + * \image html ser_phy_transport_rx_received.svg "RX - interlayer communication" + * + * \par PHY layer errors + * PHY layer errors can be signaled by an event of type @ref SER_PHY_EVT_RX_OVERFLOW_ERROR or + * @ref SER_PHY_EVT_TX_OVERREAD_ERROR or @ref SER_PHY_EVT_HW_ERROR with event parameters defined in + * @ref ser_phy_evt_hw_error_params_t. + * + * @par Available PHY layers + * The following PHY layers are available: + * - @ref ser_phy_spi_page + * - @ref ser_phy_spi_5W_page + * - @ref ser_phy_uart_page + * - @ref ser_phy_uart_hci_page + * <!-- - @ref ser_phy_usb_hci_page --> + * + */ + +#ifndef SER_PHY_H__ +#define SER_PHY_H__ + +#include <stdint.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/**@brief Serialization PHY module event types. */ +typedef enum +{ + SER_PHY_EVT_TX_PKT_SENT = 0, /**< Obligatory to implement. An event indicating that a TX packet + * has been transmitted. */ + SER_PHY_EVT_RX_BUF_REQUEST, /**< Obligatory to implement. An event indicating that the PHY layer + * needs a buffer for an RX packet. The PHY flow should be blocked + * until the @ref ser_phy_rx_buf_set function is called. */ + SER_PHY_EVT_RX_PKT_RECEIVED, /**< Obligatory to implement. An event indicating that an RX packet + * has been successfully received. */ + SER_PHY_EVT_RX_PKT_DROPPED, /**< Obligatory to implement. An event indicating that the RX packet + * receiving has been finished but the packet was discarded because + * it was longer than available the buffer. */ + + SER_PHY_EVT_RX_OVERFLOW_ERROR, /**< Optional to implement. An event indicating that more + * information has been transmitted than the PHY module could + * handle. */ + SER_PHY_EVT_TX_OVERREAD_ERROR, /**< Optional to implement. An event indicating that the PHY module + * was forced to transmit more information than possessed. */ + SER_PHY_EVT_HW_ERROR, /**< Optional to implement. An event indicating a hardware error + * in the PHY module. */ + SER_PHY_EVT_TYPE_MAX /**< Enumeration upper bound. */ +} ser_phy_evt_type_t; + + +/**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_RX_BUF_REQUEST. */ +typedef struct +{ + uint16_t num_of_bytes; /**< Length of a buffer in octets that the layer above the PHY module should + * deliver, so that the PHY module can receive a packet. */ +} ser_phy_evt_rx_buf_request_params_t; + + +/**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_RX_PKT_RECEIVED. */ +typedef struct +{ + uint8_t * p_buffer; /**< Pointer to a buffer containing the received packet. */ + uint16_t num_of_bytes; /**< Length of the received packet in octets. */ +} ser_phy_evt_rx_pkt_received_params_t; + + +/**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_HW_ERROR. */ +typedef struct +{ + uint32_t error_code; /**< Hardware error code - specific for a microcontroller. */ + uint8_t * p_buffer; /**< Pointer to the buffer that was processed when error occured. */ +} ser_phy_evt_hw_error_params_t; + + +/**@brief A struct containing events from a Serialization PHY module. + * + * @note Some events do not have parameters, then whole information is contained in the evt_type. + */ +typedef struct +{ + ser_phy_evt_type_t evt_type; /**< Type of event. */ + + union /**< Union alternative identified by evt_type in enclosing struct. */ + { + /** Parameters of event of type @ref SER_PHY_EVT_RX_BUF_REQUEST. */ + ser_phy_evt_rx_buf_request_params_t rx_buf_request; + /** Parameters of event of type @ref SER_PHY_EVT_RX_PKT_RECEIVED. */ + ser_phy_evt_rx_pkt_received_params_t rx_pkt_received; + /** Parameters of the event of type @ref SER_PHY_EVT_HW_ERROR. */ + ser_phy_evt_hw_error_params_t hw_error; + } evt_params; +} ser_phy_evt_t; + + +/**@brief A type of generic callback function handler to be used by all PHY module events. + * + * @param[in] event Serialization PHY module event. + */ +typedef void (*ser_phy_events_handler_t)(ser_phy_evt_t event); + + +/**@brief Function for opening and initializing the PHY module. + * + * @note The function initializes hardware and internal module states, and registers callback + * function to be used by all PHY module events. + * + * @warning If the function has been already called, the function @ref ser_phy_close has to be + * called before ser_phy_open can be called again. + * + * @param[in] events_handler Generic callback function handler to be used by all PHY 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_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_open(ser_phy_events_handler_t events_handler); + + +/**@brief Function for transmitting a 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_EVT_TX_PKT_SENT upon transmission + * completion. + * + * @param[in] p_buffer Pointer to a buffer to transmit. + * @param[in] num_of_bytes Number of octets to transmit. Must be more than 0. + * + * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue + * and event will be send upon transmission completion. + * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied. + * @retval NRF_ERROR_INVALID_PARAM Operation failure. The num_of_bytes parameter equal to 0. + * @retval NRF_ERROR_BUSY Operation failure. Transmitting of a packet in progress. + */ +uint32_t ser_phy_tx_pkt_send(const uint8_t * p_buffer, uint16_t num_of_bytes); + + +/**@brief Function for setting an RX buffer and enabling reception of data (the PHY flow). + * + * @note The function has to be called as a response to an event of type + * @ref SER_PHY_EVT_RX_BUF_REQUEST. The function sets an RX buffer and enables reception of + * data (enables the PHY flow). + * Size of a buffer pointed by the p_buffer parameter should be at least equal to the + * num_of_bytes parameter passed within the event (@ref ser_phy_evt_rx_buf_request_params_t), + * or p_buffer should be equal to NULL if there is not enough memory. + * When p_buffer is different from NULL and num_of_bytes octets have been received, an event of + * type @ref SER_PHY_EVT_RX_PKT_RECEIVED is generated + * (@ref ser_phy_evt_rx_pkt_received_params_t). + * When p_buffer is equal to NULL, data is received to dummy location to ensure continuous + * communication. Then, if num_of_bytes octets have been received, an event of type + * @ref SER_PHY_EVT_RX_PKT_DROPPED is generated. + * + * @param[in] p_buffer Pointer to an RX buffer in which to receive. + * + * @retval NRF_SUCCESS Operation success. + * @retval NRF_ERROR_INVALID_STATE Operation failure. A buffer was set without request. + */ +uint32_t ser_phy_rx_buf_set(uint8_t * p_buffer); + + +/**@brief Function for closing the PHY module. + * + * @note The function disables hardware, resets internal module states, and unregisters the events + * callback function. + */ +void ser_phy_close(void); + + +/**@brief Function for enabling the PHY module interrupts. + * + * @note The function enables all interrupts that are used by the PHY module (and only those). + */ +void ser_phy_interrupts_enable(void); + + +/**@brief Function for disabling the PHY module interrupts. + * + * @note The function disables all interrupts that are used by the PHY module (and only those). + */ +void ser_phy_interrupts_disable(void); + + + +#ifdef __cplusplus +} +#endif + +#endif /* SER_PHY_H__ */ +/** @} */ |