/** * Copyright (c) 2014 - 2017, 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 * * */ #ifndef SER_PHY_H__ #define SER_PHY_H__ #include #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__ */ /** @} */