owner-nrf52sdk/nRF5_SDK_17.0.2/components/proprietary_rf/gzll/nrf_gzll.h

/**
 * Copyright (c) 2012 - 2020, 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
 * @brief Gazell Link Layer API.
 */

#ifndef NRF_GZLL_H__
#define NRF_GZLL_H__

#include <stdbool.h>
#include "nrf.h"
#include "nrf_gzll_constants.h"

#ifdef __cplusplus
extern "C" {
#endif


/**
* @defgroup gzll_02_api Gazell Link Layer
* @{
* @ingroup modules_01_gzll
* @brief Gazell Link Layer Application Programming Interface (API).
*/

/**
 * @enum nrf_gzll_mode_t
 * @brief Enumerator used for selecting Gazell mode.
 */
typedef enum
{
    NRF_GZLL_MODE_DEVICE,  ///< Device mode
    NRF_GZLL_MODE_HOST,    ///< Host mode
    NRF_GZLL_MODE_SUSPEND, ///< Suspend mode ("disabled with timer running")
} nrf_gzll_mode_t;

/**
 * @enum nrf_gzll_device_channel_selection_policy_t
 * @brief Enumerator used for selecting Gazell Device channel
 * selection policy.
 */
typedef enum
{
    NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL, ///< Start on previous successful channel
    NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT,    ///< Start on channel currently monitored by Host
} nrf_gzll_device_channel_selection_policy_t;

/**
 * @enum nrf_gzll_tx_power_t
 * @brief Enumerator used for selecting the transmit (TX) power.
 */
typedef enum
{
    NRF_GZLL_TX_POWER_4_DBM,   ///<  4 dBm transmit power.
    NRF_GZLL_TX_POWER_0_DBM,   ///<  0 dBm transmit power.
    NRF_GZLL_TX_POWER_N4_DBM,  ///< -4 dBm transmit power.
    NRF_GZLL_TX_POWER_N8_DBM,  ///< -8 dBm transmit power.
    NRF_GZLL_TX_POWER_N12_DBM, ///< -12 dBm transmit power.
    NRF_GZLL_TX_POWER_N16_DBM, ///< -16 dBm transmit power.
    NRF_GZLL_TX_POWER_N20_DBM  ///< -20 dBm transmit power.
} nrf_gzll_tx_power_t;

/**
 * @enum nrf_gzll_datarate_t
 * @brief Enumerator used for selecting the radio datarate.
 */
typedef enum
{
#ifdef NRF51
    NRF_GZLL_DATARATE_250KBIT = 0, ///<  250 Kbps datarate, available only for the nRF51.
#endif
    NRF_GZLL_DATARATE_1MBIT   = 1, ///<  1 Mbps datarate.
    NRF_GZLL_DATARATE_2MBIT   = 2  ///<  2 Mbps datarate.
} nrf_gzll_datarate_t;

/**
 * @enum nrf_gzll_xosc_ctl_t
 * @brief Enumerator used for specifying whether switching the
 * external 16 MHz oscillator on/off shall be handled automatically
 * inside Gazell or manually by the application.
 */
typedef enum
{
    NRF_GZLL_XOSC_CTL_AUTO,  ///< Switch XOSC on/off automatically
    NRF_GZLL_XOSC_CTL_MANUAL ///< Switch XOSC on/off manually
} nrf_gzll_xosc_ctl_t;

/**
 * @enum nrf_gzll_error_code_t
 * @brief Enumerator used for error codes for Gazell API functions
 */
typedef enum
{
    NRF_GZLL_ERROR_CODE_NO_ERROR                            =  0, ///< No error has been detected.
    NRF_GZLL_ERROR_CODE_FAILED_TO_INITIALIZE                =  1, ///< The function NRF_GZLL_init failed.
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_CONFIGURE_WHEN_ENABLED =  2, ///< A call to a configuration 'set' function was made while Gazell was enabled.
    NRF_GZLL_ERROR_CODE_POINTER_IS_NULL                     =  3, ///< A null pointer was given as an input to a function.
    NRF_GZLL_ERROR_CODE_INVALID_PIPE                        =  4, ///< An invalid pipe number was given as an input to a function.
    NRF_GZLL_ERROR_CODE_INVALID_MODE                        =  5, ///< An invalid value for the nrf_gzll_mode_t enumerator was given as input to a function.
    NRF_GZLL_ERROR_CODE_INVALID_PAYLOAD_LENGTH              =  6, ///< An invalid payload length was given as an input to a function.
    NRF_GZLL_ERROR_CODE_INVALID_CHANNEL_TABLE_SIZE          =  7, ///< An invalid channel table size was given as an input to a function.
    NRF_GZLL_ERROR_CODE_INSUFFICIENT_PACKETS_AVAILABLE      =  8, ///< There are insufficient packets in the Gazell memory pool to successfully execute the operation.
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_ADD_TO_FULL_FIFO       =  9, ///< There is insufficient space in the TX FIFO for the data packet.
    NRF_GZLL_ERROR_CODE_NO_SPACE_IN_RX_FIFO_FOR_ACK         = 10, ///< There is insufficient space in the RX FIFO for the ACK.
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FETCH_FROM_EMPTY_FIFO  = 11, ///< Attempted to fetch a packet from an empty FIFO. Use the functions nrf_gzll_get_tx_fifo_packet_count() or nrf_gzll_get_rx_fifo_packet_count()
    NRF_GZLL_ERROR_CODE_ATTEMPTED_TO_FLUSH_WHEN_ENABLED     = 12, ///< Attempted to fetch a packet from an empty FIFO. Use the functions nrf_gzll_get_tx_fifo_packet_count() or nrf_gzll_get_rx_fifo_packet_count()
    NRF_GZLL_ERROR_CODE_INVALID_PARAMETER                   = 14, ///< Attempted to set a variable which was not valid.
    NRF_GZLL_ERROR_CODE_INTERNAL_ASSERT_OCCURRED            = 15, ///< An internal assert occurred.
    NRF_GZLL_ERROR_CODE_CALLBACK_NOT_IMPLEMENTED            = 16, ///< A callback was called but not implemented by the application.
    NRF_GZLL_ERROR_CODE_INVALID_ADDRESS                     = 17, ///< Invalid pipe 0 address detected, see Anomaly 107 at nRF52832 errata document.
    NRF_GZLL_ERROR_CODE_NUMBER_OF_ERROR_CODES               = 18, ///< Number of possible error codes.
} nrf_gzll_error_code_t;

/**
 * @struct nrf_gzll_device_tx_info_t;
 * @brief Data structure containing information about the last packet
 *        transmission.
 */
typedef struct
{
    bool     payload_received_in_ack;    ///< A payload was received in the ACK.
    uint16_t num_tx_attempts;            ///< Number of attempts used on previous Device packet transmission.
    uint16_t num_channel_switches;       ///< Number of channel switches needed during previous packet transmission.
    int8_t   rssi;                       ///< Received signal strength indicator in dBm. @sa nrf_gzll_enable_rssi().
    uint8_t  rf_channel;                 ///< Channel on which packet has been transmitted.
} nrf_gzll_device_tx_info_t;


/**
 * @struct nrf_gzll_host_rx_info_t;
 * @brief Data structure containing information about the last packet
 *        received.
 */
typedef struct
{
    bool    packet_removed_from_tx_fifo; ///< A payload was received in the ACK.
    int8_t  rssi;                        ///< Received signal strength indicator in dBm. @sa nrf_gzll_enable_rssi().
    uint8_t rf_channel;                  ///< Channel on which packet has been received.
} nrf_gzll_host_rx_info_t;


typedef struct 
{
    uint32_t packets_num;                                             ///< Number of succesfully transmitted packets 
    uint32_t timeouts_num;                                            ///< Total timeouts number 
    uint32_t channel_timeouts[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE]; ///< Transmission timeouts per channel 
    uint32_t channel_packets[NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE];  ///< Succesfully transmitted packets per channel 
} nrf_gzll_tx_statistics_t;


/**< Transmission timeout callback function definition */
typedef void (*nrf_gzll_tx_timeout_callback)(uint32_t pipe, uint8_t rf_channel);


/**< Transmission CRC failure callback function definition */
typedef void (*nrf_gzll_crc_failure_callback)(uint32_t pipe, uint8_t rf_channel);


#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
/**
 * @brief Data structure holding external front
 *        end control configuration.
 */
typedef struct
{
    bool             pa_enabled;                                     ///< Flag indicating if PA control is enabled.
    bool             pa_active_high;                                 ///< Flag indicating if PA is active in high input state.
    uint8_t          pa_gpio_pin;                                    ///< Number of output pin used for PA control.
    uint8_t          pa_gpiote_channel;                              ///< Number of GPIOTE channel used for PA control.
    bool             lna_enabled;                                    ///< Flag indicating if LNA control is enabled.
    bool             lna_active_high;                                ///< Flag indicating if LNA is active in high input state.
    uint8_t          lna_gpio_pin;                                   ///< Number of output pin used for LNA control.
    uint8_t          lna_gpiote_channel;                             ///< Number of GPIOTE channel used for LNA control.
    NRF_TIMER_Type * timer;                                          ///< Pointer to the TIMER instance.
    uint8_t          ppi_channels[NRF_GZLL_PA_LNA_PPI_CHANNELS_NUM]; ///< PPI channels used to control front end.
    uint8_t          ramp_up_time;                                   ///< Determines how early should the PA/LNA be turned one before RADIO activity. Should be less than @ref NRF_GZLL_PA_LNA_MAX_RAMP_UP_TIME.
} nrf_gzll_pa_lna_cfg_t;
#endif

/******************************************************************************/
/** @name General API functions
 *  @{ */
/******************************************************************************/

/**
 * @brief Initialize Gazell.
 *
 * @param mode The mode to initialize Gazell in.
 *
 * @retval true if Gazell initialized.
 * @retval false if Gazell failed to initialize.
 */
bool nrf_gzll_init(nrf_gzll_mode_t mode);

/**
 * @brief Enable Gazell.
 *
 * When enabled the behaviour described for the current Gazell Link Layer mode
 * will apply.
 *
 * @retval false if nrf_gzll_init has not previously been called or invalid address
 *               has been set - see Anomaly 107 at nRF52832 errata document.
 */
bool nrf_gzll_enable(void);

/**
 * @brief Disable Gazell.
 *
 * When calling this function the Gazell Link Layer will begin disabling,
 * and will be fully disabled when Gazell calls nrf_gzll_disabled().
 * If there are any pending notifications, or if any new notifications are
 * being added to the internal notification queue while Gazell is disabling,
 * these will be sent to the application before Gazell is fully disabled.
 *
 * After Gazell has been fully disabled, no more notifications will be sent to
 * the application.
 */
void nrf_gzll_disable(void);

/** Check whether Gazell is enabled or disabled.
 *
 * @retval true  If Gazell is enabled.
 * @retval false If Gazell is disabled.
 */
bool nrf_gzll_is_enabled(void);

/** @} */

/******************************************************************************/
/** @name Device mode callback functions
 *  @{ */
/******************************************************************************/

/**
 * @brief ACK received callback (Device mode only).
 *
 * This callback is made when the Device receives an ACK (acknowledgement)
 * packet.
 * @sa nrf_gzll_ack_payload_received.
 *
 * @param pipe is the pipe on which an ACK packet was received.
 * @param tx_info struct used to indicate whether a payload was received in the
 * ack, as well as the number of TX attempts and channel switches required.
 */
void nrf_gzll_device_tx_success(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);

/**
 * @brief Transmission failed callback (Device mode only).
 *
 * This callback is made when a packet does not receive an ACK after
 * nrf_gzll_max_retries is reached. The packet is deleted by Gazell.
 *
 * @param pipe is the pipe on which the transmission failed.
 * @param tx_info struct used to indicate whether a payload was received
 * in the ack, as well as RSSI and the number of TX attempts and
 * channel switches required.
 */
void nrf_gzll_device_tx_failed(uint32_t pipe, nrf_gzll_device_tx_info_t tx_info);

/** @} */

/******************************************************************************/
/** @name Host mode callback functions
 *  @{ */
/******************************************************************************/

/**
 * @brief Data packet received callback (Host mode only).
 *
 * This callback is made when a Host receives a data packet from a Device.
 *
 * @param pipe is the pipe on which the data packet was received.
 * @param rx_info struct used to indicate whether a payload was removed from the
 * pipe's TX FIFO, as well as RSSI.
 */
void nrf_gzll_host_rx_data_ready(uint32_t pipe, nrf_gzll_host_rx_info_t rx_info);

/** @} */

/******************************************************************************/
/** @name Callback functions for both Device and Host mode
 *  @{ */
/******************************************************************************/

/**
 * @brief Disabled callback.
 *
 * This is called after Gazell enters the disabled state.
 * There is no further CPU use by Gazell, the radio is disabled and the timer is
 * powered down.
 */
void nrf_gzll_disabled(void);

/**
 * @brief Mode changed callbackl.
 *
 * This function is called after the Gazell mode has been changed.
 * This function can only be called when Gazell is enabled.
 */
void nrf_gzll_mode_changed(void);

/** @} */

/******************************************************************************/
/** @name Packet transmission and receiving functions
 *  @{ */
/******************************************************************************/

/**
 * @brief Add a packet to the tail of the TX FIFO.
 *
 * In Device mode, the packet will be added.
 * In Host mode, the payload will be piggybacked onto an ACK.
 *
 * @param pipe      Pipe to which to add the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @param p_payload Pointer to the payload.
 * @param length    Number of bytes of the payload to transmit
 *                  (0 to NRF_GZLL_CONST_MAX_PAYLOAD_LENGTH).
 *
 * @retval true  if the packet was successfully added to the TX FIFO.
 * @retval false if unsuccessful, check nrf_gzll_error_code_t for more information.
 */
bool nrf_gzll_add_packet_to_tx_fifo(uint32_t pipe, uint8_t * p_payload, uint32_t length);

/**
 * @brief Fetch a packet from the head of the RX FIFO.
 *
 * @param pipe      Pipe from which to fetch the payload. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @param p_payload Pointer to copy the payload to.
 * @param p_length  Length must be at least as large as the the number of bytes
 *                  in the received payload length.
 *
 * @retval true  If the fetch was successful.
 * @retval false If unsuccessful, check nrf_gzll_error_code_t for more information.
 */
bool nrf_gzll_fetch_packet_from_rx_fifo(uint32_t pipe, uint8_t * p_payload, uint32_t * p_length);

/**
 * @brief Get the number of packets in the TX FIFO on a specific pipe.
 *
 * @param pipe The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 *
 * @retval >=0 The number of packets in the TX FIFO for the pipe.
 * @retval -1  If the pipe number is invalid.
 */
int32_t nrf_gzll_get_tx_fifo_packet_count(uint32_t pipe);

/**
 * @brief Get the number of packets in the RX FIFO on a specific pipe.
 *
 * @param pipe  The pipe for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @retval >=0  The number of packets in the RX FIFO for the pipe.
 * @retval -1   If the pipe number is invalid.
 */
int32_t nrf_gzll_get_rx_fifo_packet_count(uint32_t pipe);

/**
 * @brief Get the total number of packets residing in all TX and RX FIFOs.
 *
 * Can be used to check against NRF_GZLL_CONST_MAX_TOTAL_PACKETS to
 * determine if there is free space in the memory pool for more packets.
 *
 * @return The number of packets residing in all TX and RX FIFOs.
 */
uint32_t nrf_gzll_get_total_allocated_packet_count(void);

/**
 * @brief Check if adding a packet to a pipe's TX FIFO should be successful.
 *
 * Checks if there is another space in the pipe's TX and RX FIFOs
 * as well as enough overall space in the packet pool.
 *
 * @param pipe The pip for which to check. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 *
 * @retval true  If there is another space.
 * @retval false If there is not enough space, or the pipe is invalid.
 */
bool nrf_gzll_ok_to_add_packet_to_tx_fifo(uint32_t pipe);

/**
 * @brief Flush the RX FIFO for a specific pipe.
 *
 * Delete all the packets and free the memory of the TX FIFO for a
 * specific pipe.
 *
 * Note that it is not allowed to flush a TX FIFO when
 * Gazell is enabled.
 *
 * @param pipe is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @retval true if the pipe was flushed.
 * @retval false if the pipe was not flushed.
 */
bool nrf_gzll_flush_tx_fifo(uint32_t pipe);

/**
 * @brief Flush the RX FIFO for a specific pipe.
 *
 * Delete all the packets and free the memory of the RX FIFO for a
 * specific pipe.
 *
 * @param pipe is the pipe for which to flush. This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @retval true if the pipe was flushed.
 * @retval false if the pipe was not flushed.
 */
bool nrf_gzll_flush_rx_fifo(uint32_t pipe);

/**
 * @brief Function for enabling transmission statistics.
 *
 * @param p_statistics Pointer to the statistics structure.
 *
 * @return True if channel statistics has been enabled, false otherwise.
 */
bool nrf_gzll_tx_statistics_enable(nrf_gzll_tx_statistics_t * p_statistics);

/**
 * @brief Function for disabling transmission statistics.
 */
void nrf_gzll_tx_statistics_disable(void);

/**
 * @brief Function for obtaining number of transmission timeouts for specific channel.
 * 
 * @param[in]  channel_index Channel index in channel table.
 * @param[out] p_timeouts    Pointer for the result.
 *
 * @return True in case of success, false otherwise.
 */
bool nrf_gzll_get_channel_timeouts(uint8_t channel_index, uint32_t *p_timeouts);

/**
 * @brief Function for clearing transmission statistic structure.
 */
void nrf_gzll_reset_tx_statistics(void);

/** @} */

/******************************************************************************/
/** @name Configuration functions
 *
 * Configuration 'set' functions may only be called while Gazell is disabled. The
 * new parameter comes into effect when Gazell is enabled again.
 *
 * Configuration 'get' functions may be called at any time.
 *
 * @{ */
/******************************************************************************/

/**
 * @brief Function for registering callback to be called on the transmission timeout.
 */
void nrf_gzll_tx_timeout_callback_register(nrf_gzll_tx_timeout_callback callback);


/**
 * @brief Function for registering callback to be called on the packet CRC failure.
 */
void nrf_gzll_crc_failure_callback_register(nrf_gzll_crc_failure_callback callback);


/**
 * @brief Set the mode.
 *
 * @param mode The mode to be used.
 *             See nrf_gzll_mode_t for a list of valid modes.
 *
 * It is allowed to change mode when Gazell is enabled. If the mode is
 * being changed while Gazell is enabled, the mode will not change right away.
 * In this case the callback function nrf_gzll_mode_changed() will be called
 * after the mdoe has changed.
 *
 * @retval true  If the parameter was set.
 */
bool nrf_gzll_set_mode(nrf_gzll_mode_t mode);

/**
 * @brief Get function counterpart to nrf_gzll_set_mode().
 *
 * @return The current mode.
 */
nrf_gzll_mode_t nrf_gzll_get_mode(void);

/**
 * @brief Set the base address for pipe 0.
 *
 * The full on-air address for each pipe is composed of a multi-byte base address
 * prepended to a prefix byte.
 *
 * For packets to be received correctly, the most significant byte of
 * the base address should not be an alternating sequence of 0s and 1s i.e.
 * it should not be 0x55 or 0xAA.
 *
 * @param base_address The 4 byte base address. All bytes are used.
 *
 * @note Due to the nRF52 Anomaly 107, pipe 0 address should not have
 *       both prefix and two LSB of base address set to 0.
 *
 * @retval true  If the parameter was set.
 * @return false If Gazell was enabled.
 */
bool nrf_gzll_set_base_address_0(uint32_t base_address);

/**
 * @brief Get function counterpart to nrf_gzll_set_base_address_0().
 *
 * @return Base address 0.
 */
uint32_t nrf_gzll_get_base_address_0(void);

/**
 * @brief Set the base address for pipes 1-7.
 *
 * Pipes 1 through 7 share base_address_1. @sa nrf_gzll_set_base_address_0.
 *
 * @param base_address The 4 byte base address.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_base_address_1(uint32_t base_address);

/**
 * @brief Get function counterpart to nrf_gzll_set_base_address_1().
 *
 * @return Base address 1.
 */
uint32_t nrf_gzll_get_base_address_1(void);

/**
 * @brief Set the address prefix byte for a specific pipe.
 *
 * Each pipe should have its own unique prefix byte.
 *
 * @param pipe                The pipe that the address should apply to.
 *                            This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @param address_prefix_byte The address prefix byte.
 *
 * @note Due to the Anomaly 107, pipe 0 address should not have
 *       both prefix and two LSB of base address set to 0.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled, or if the pipe was invalid.
 */
bool nrf_gzll_set_address_prefix_byte(uint32_t pipe, uint8_t address_prefix_byte);

/**
 * @brief Get function counterpart to nrf_gzll_set_address_prefix_byte().
 *
 * @param pipe                      The pipe for which to get the address.
 *                                  This value must be < NRF_GZLL_CONST_PIPE_COUNT.
 * @param p_out_address_prefix_byte The pointer in which to return the
 *                                  address prefix byte.
 *
 * @retval true If the parameter was returned.
 * @retval false If Gazell was enabled, the pipe was invalid or
 *               out_address was a NULL pointer.
 */
bool nrf_gzll_get_address_prefix_byte(uint32_t pipe, uint8_t * p_out_address_prefix_byte);

/**
 * @brief Set which pipes shall listen for packets in Host mode.
 *
 * This value is a bitmap, and each bit corresponds to a given pipe number.
 * Bit 0 set to "1" enables pipes 0, bit 1 set to "1" enables pipe 1
 * and so forth.
 * The maximum number of pipes is defined by NRF_GZLL_CONST_PIPE_COUNT.
 *
 * @param pipes A bitmap specifying which pipes to monitor.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_rx_pipes_enabled(uint32_t pipes);

/**
 * @brief Get function counterpart to nrf_gzll_set_rx_pipes_enabled().
 *
 * @return Bitmap holding the current enabled pipes.
 */
uint32_t nrf_gzll_get_rx_pipes_enabled(void);

/**
 * @brief Set the timeslot period.
 *
 * The length in microseconds of a Gazell link layer timeslot.
 *
 * The minimum value of the timeslot period is dependent of the
 * radio data rate (@sa nrf_gzll_set_datarate()).
 *
 * - For NRF_GZLL_DATARATE_2MBIT the timeslot period must be >= 600 us.
 * - For NRF_GZLL_DATARATE_1MBIT the timeslot period must be >= 900 us.
 * - For NRF_GZLL_DATARATE_250KBIT the timeslot period must be >= 2700 us.
 *
 * @param period_us The timeslot period in microseconds.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_timeslot_period(uint32_t period_us);

/**
 * @brief Get function counterpart to nrf_gzll_get_timeslot_period().
 *
 * @return The current timeslot period.
 */
uint32_t nrf_gzll_get_timeslot_period(void);

/**
 * @brief Set the Device channel selection policy
 *
 * The policy determines the initial channel when starting a new packet.
 * transmission.
 *
 * @param policy The channel selection policy.
 *
 * @arg NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_SUCCESSFUL specifies
 * that a new packet transmission always shall use the previous
 * successful channel from the channel table. If Gazell is "in sync", Gazell
 * will wait until this channel is being monitored by the Host before starting
 * the transmission.
 *
 * @arg NRF_GZLL_DEVICE_CHANNEL_SELECTION_POLICY_USE_CURRENT specifies that
 * Gazell shall transmit on the channel that is currently being monitored by the
 * Host. This parameter is only used when Gazell is "in sync". When "out of" sync,
 * Gazell will always start using the "previous successful" channel.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled or the policy was invalid.
 */
bool nrf_gzll_set_device_channel_selection_policy(nrf_gzll_device_channel_selection_policy_t policy);

/**
 * @brief Get function counterpart to nrf_gzll_set_device_channel_selection_policy().
 *
 * @return the Device channel selection policy.
 */
nrf_gzll_device_channel_selection_policy_t nrf_gzll_get_device_channel_selection_policy(void);

/**
 * @brief Set the number of timeslots that Gazell shall
 * reside on a single channel before switching to another channel.
 *
 * This parameter applies in Host mode and for a Device that is
 * in the "in sync" state.
 *
 * Since the Device and Host can not be in perfect synchronization, a
 * transmission should overlap to adjacent timeslots on the Host.
 * Therefore this value should be at least 2.
 *
 * @sa nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync
 *
 * @param timeslots The number of timeslots to reside on
 * each channel before channel switch.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_timeslots_per_channel(uint32_t timeslots);

/**
 * @brief Get function counterpart to nrf_gzll_set_timeslots_per_channel().
 *
 * @return The current number of timeslots.
 */
uint32_t nrf_gzll_get_timeslots_per_channel(void);

/**
 * @brief Set the number of timeslots that a Gazell shall
 * reside on a single channel before switching to another channel when
 * in the "out of sync" state.
 *
 * This value should be set so that the Device transmits on one channel
 * while the Host goes through a full channel rotation, i.e.,
 * channel_table_size*timeslots_per_channel.
 * This ensures that the channels on the Device and Host will coincide
 * at some point.
 * Further increasing the value has been observed to provide better performance
 * in the presence of interferers.
 *
 * @param timeslots The number of timeslots to reside on
 * each channel before channel switch.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync(uint32_t timeslots);

/**
 * @brief Get function counterpart to
 * nrf_gzll_set_timeslots_per_channel_when_device_out_of_sync().
 *
 * @return The current number of timeslots.
 */
uint32_t nrf_gzll_get_timeslots_per_channel_when_device_out_of_sync(void);

/**
 * @brief Set the number of timeslots after a successful
 * reception of a Device or Host packet that the Gazell Link Layer shall assume
 * that the link is synchronized. A value of 0 implies that the
 * link is always out of sync.
 *
 * @param lifetime The sync lifetime in number of timeslots.
 *
 * @retval true  If the sync lifetime was set.
 * @retval false If Gazell was enabled.
 */
bool nrf_gzll_set_sync_lifetime(uint32_t lifetime);

/**
 * @brief Get function counterpart to nrf_gzll_set_sync_lifetime().
 *
 * @return The sync lifetime measured in number of timeslots.
 */
uint32_t nrf_gzll_get_sync_lifetime(void);

/**
 * @brief Set the maximum number of TX attempts
 * that can be used for a single packet.
 *
 * After the maximum number of attempts have been spent without
 * receiving any ACK from the Host, the transmission will be terminated
 * and the nrf_gzll_device_tx_failed() callback will be called. A zero
 * value of the function parameter implies the infinite number of TX attempts.
 *
 * @param max_tx_attempts The maximum number of TX attempts.
 */
void nrf_gzll_set_max_tx_attempts(uint16_t max_tx_attempts);

/**
 * @brief Get function counterpart to nrf_gzll_set_max_tx_attempts().
 *
 * @return The current max Device TX attempts.
 */
uint16_t nrf_gzll_get_max_tx_attempts(void);

/**
 * @brief Set the table of Radio Frequency (RF) channels.
 *
 * The valid channels are in the range 0 <= channel <= 125, where the
 * actual centre frequency is (2400 + channel) MHz.
 * The maximum channel table size is defined by
 * NRF_GZLL_CONST_MAX_CHANNEL_TABLE_SIZE.
 *
 * @param p_channel_table Pointer to the channel table.
 * @param size            The size of the channel table.
 *
 * @retval true  If the channel table was set.
 * @retval false If Gazell was enabled, or the channel_table pointer was NULL,
 *               or the size was invalid.
 */
bool nrf_gzll_set_channel_table(uint8_t * p_channel_table, uint32_t size);

/**
 * @brief Get the table of Radio Frequency (RF) channels.
 *
 * @param p_channel_table Pointer to copy the channel table to.
 * @param p_size          Pointer to copy the size of the channel table to.
 *                        The value already at size must be at least the size
 *                        of the channel table.
 *
 * @retval true  If the channel table was copied to channel_table.
 * @retval false If the channel_table pointer was NULL,
 *               or the size was not large enough.
 */
bool nrf_gzll_get_channel_table(uint8_t * p_channel_table, uint32_t * p_size);

/**
 * @brief Get the current channel table size.
 *
 * @return The current channel table size.
 */
uint32_t nrf_gzll_get_channel_table_size(void);

/**
 * @brief Set the radio TX power.
 *
 * @param tx_power TX power.
 *
 * @retval true  If the parameter was set.
 * @retval false If the TX power was invalid.
*/
bool nrf_gzll_set_tx_power(nrf_gzll_tx_power_t tx_power);

/**
 * @brief Get function counterpart to nrf_gzll_set_tx_power().
 *
 * @return The current TX power.
 */
nrf_gzll_tx_power_t nrf_gzll_get_tx_power(void);

/**
 * @brief Set the radio datarate.
 *
 * @param data_rate Datarate.
 *
 * @retval true  If the parameter was set.
 * @retval false If Gazell was enabled or the datarate was invalid.
 */
bool nrf_gzll_set_datarate(nrf_gzll_datarate_t data_rate);

/**
 * @brief Get function counterpart to nrf_gzll_set_datarate().
 *
 * @return The current datarate.
 */
nrf_gzll_datarate_t nrf_gzll_get_datarate(void);

/**
 * @brief Set whether start/stop of external oscillator (XOSC) shall be handled
 * automatically inside Gazell or manually by the application.
 *
 * When controlling the XOSC manually from the application it is
 * required that the XOSC is started before Gazell is enabled.
 *
 * When start/stop of the XOSC is handled automatically by Gazell,
 * the XOSC will only be running when needed, that is when the radio
 * is being used or when Gazell needs to maintain synchronization.
 *
 * It is required that the XOSC is started in order for the radio to be
 * able to send or receive any packets.
 *
 * @param xosc_ctl setting for XOSC control.
 *
 * @retval true  if the parameter was set.
 * @retval false if Gazell was enabled or the xosc_ctl value was invalid.
 */
bool nrf_gzll_set_xosc_ctl(nrf_gzll_xosc_ctl_t xosc_ctl);

/**
 * Get function counterpart for nrf_gzll_set_xosc_ctl();
 *
 * @return The XOSC control setting.
 */
nrf_gzll_xosc_ctl_t nrf_gzll_get_xosc_ctl(void);

/**
 * @brief Set Gazell to disable automatically after a certain number of timeslot ticks.
 *
 * @param num_ticks Number of timeslot ticks.
 *
 */
void nrf_gzll_set_auto_disable(uint32_t num_ticks);

#if defined(NRF52_SERIES) || defined(__SDK_DOXYGEN__)
/**
 * @brief Set up external front end control.
 *
 * @param p_pa_lna_cfg Pointer to the configuration struct.
 */
bool nrf_gzll_set_pa_lna_cfg(nrf_gzll_pa_lna_cfg_t const * p_pa_lna_cfg);
#endif

/**
 * @brief Get the number of timeslot ticks that have occurred since
 *        nrf_gzll_init() was called.
 *
 * @return Number of timeslot ticks.
 *
 */
uint32_t nrf_gzll_get_tick_count(void);

/**
 * @brief Clear the internal timeslot tick count variable that is read
 * by nrf_gzll_get_tick_count().
 *
 */
void nrf_gzll_clear_tick_count(void);

/** @} */

/******************************************************************************/
/** @name Error handling functions
 * @{ */
/******************************************************************************/

/**
 * @brief Gets the Gazell error code.
 *
 * @return The current error code.
 */
nrf_gzll_error_code_t nrf_gzll_get_error_code(void);


/**
 * @brief Reset the Gazell error code.
 *
 * The error code is reset to NRF_GZLL_ERROR_CODE_NO_ERRROR.
 */
void nrf_gzll_reset_error_code(void);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif

#endif