/* Copyright (c) 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 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.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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.
 *
 */

/**
 * @brief This module defines Radio Arbiter Abstraction Layer interface.
 *
 */

#ifndef NRF_RAAL_API_H_
#define NRF_RAAL_API_H_

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup nrf_raal Radio Arbiter Abstraction Layer
 * @{
 * @ingroup nrf_driver_radio802154
 * @brief Radio Arbiter Abstraction Layer interface.
 */

/**
 * @brief Initialize RAAL.
 *
 * @note This function shall be called once, before any other function from this module.
 *
 * Initialize Radio Arbiter Abstraction Layer client.
 *
 * @note Arbiter starts in inactive mode after initialization. In order to start radio activity
 *       @p nrf_raal_continuous_mode_enter method should be called.
 *
 */
void nrf_raal_init(void);

/**
 * @brief Uninitialize RAAL.
 *
 * Uninitialize Radio Arbiter Abstraction Layer client.
 *
 */
void nrf_raal_uninit(void);

/**
 * @brief Enter arbiter into continuous radio mode.
 *
 * In this mode radio arbiter should try to create long continuous timeslots that will give the
 * radio driver as much radio time as possible while disturbing the other activities as little
 * as possible.
 * The arbiter client shall make sure that high frequency clock is enabled in each timeslot.
 *
 * @note The start of a timeslot will be indicated by @p nrf_raal_timeslot_started call.
 *
 */
void nrf_raal_continuous_mode_enter(void);

/**
 * @brief Exit arbiter from continous mode.
 *
 * In this mode radio arbiter will not extend or allocate any more timeslots for radio driver.
 *
 */
void nrf_raal_continuous_mode_exit(void);

/**
 * @brief Request timeslot for radio communication.
 *
 * This method should be called only after @p nrf_raal_timeslot_started indicated the start
 * of a timeslot.
 *
 * @param[in] length_us  Requested radio timeslot length in microsecond.
 *
 * @retval TRUE  The radio driver now has exclusive access to the RADIO peripheral for the
 *               full length of the timeslot.
 * @retval FALSE Slot cannot be assigned due to other activities.
 *
 */
bool nrf_raal_timeslot_request(uint32_t length_us);

/**
 * @brief Get left time of currently granted timeslot [us].
 *
 * @returns  Number of microseconds left in currently granted timeslot.
 */
uint32_t nrf_raal_timeslot_us_left_get(void);

/**
 * @brief Enter critical section of the module.
 *
 * When this method is called, the execution of the @nrf_raal_timeslot_ended function is blocked.
 *
 */
void nrf_raal_critical_section_enter(void);

/**
 * @brief Exit critical section of the module.
 *
 * When this method is called driver has to expect the execution of the @nrf_raal_timeslot_ended
 * function.
 *
 */
void nrf_raal_critical_section_exit(void);

/**
 * @brief RAAL client calls this method to notify radio driver about the start of a timeslot.
 *
 * The radio driver now has exclusive access to the peripherals until @p nrf_raal_timeslot_ended
 * is called.
 *
 * @note The high frequency clock must be enabled when this function is called.
 * @note The end of the timeslot will be indicated by @p nrf_raal_timeslot_ended function.
 *
 */
extern void nrf_raal_timeslot_started(void);

/**
 * @brief RAAL client calls this method to notify radio driver about the end of a timeslot.
 *
 * Depending on the RAAL client configuration, radio driver has NRF_RAAL_MAX_CLEAN_UP_TIME_US
 * microseconds to do any clean-up actions on RADIO peripheral and stop using it completely.
 * Thus arbiter has to call this function NRF_RAAL_MAX_CLEAN_UP_TIME_US microseconds before
 * timeslot is finished.
 *
 * If RAAL is in the continuous mode, the next timeslot will be indicated again by
 * @p nrf_raal_timeslot_started function.
 *
 * This method shall not be called if @p nrf_raal_continuous_mode_exit has been called. Radio
 * driver shall assume that timeslot has been finished after @p nrf_raal_continuous_mode_exit
 * call.
 *
 * @note Because radio driver needs to stop any operation on RADIO peripheral within
 *       NRF_RAAL_MAX_CLEAN_UP_TIME_US microseconds, this method should be called with high
 *       interrupt priority level to avoid unwanted delays.
 *
 */
extern void nrf_raal_timeslot_ended(void);

/**
 *@}
 **/

#ifdef __cplusplus
}
#endif

#endif /* NRF_RAAL_API_H_ */