/*
 * Copyright (c) 2020 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#ifndef __SOC_FLASH_NRF_H__
#define __SOC_FLASH_NRF_H__

#include <zephyr/kernel.h>
#include <soc.h>

#define FLASH_OP_DONE    (0) /* 0 for compliance with the driver API. */
#define FLASH_OP_ONGOING  1

struct flash_context {
	uint32_t data_addr;  /* Address of data to write. */
	uint32_t flash_addr; /* Address of flash to write or erase. */
	uint32_t len;        /* Size of data to write or erase [B]. */
#ifndef CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE
	uint8_t  enable_time_limit; /* set execution limited to the execution
				     * window.
				     */
#endif /* !CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE */
#if defined(CONFIG_SOC_FLASH_NRF_PARTIAL_ERASE)
	uint32_t flash_addr_next;
#endif /* CONFIG_SOC_FLASH_NRF_PARTIAL_ERASE */
}; /*< Context type for f. @ref write_op @ref erase_op */

#ifndef CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE

/* The timeout is multiplied by CONFIG_SOC_FLASH_NRF_TIMEOUT_MULTIPLIER/10
 * because switching tasks may take a significant portion of time.
 */
#define FLASH_TIMEOUT_MS ((FLASH_PAGE_ERASE_MAX_TIME_US) * \
			  (FLASH_PAGE_MAX_CNT) / 1000 * \
			  CONFIG_SOC_FLASH_NRF_TIMEOUT_MULTIPLIER / 10)

/**
 * @defgroup nrf_flash_sync sync backend API
 *
 * API declared below contains prototypes of function which shall be
 * implemented by the synchronization backend.
 * @{
 */

/**
 * Callback which executes the flash operation.
 *
 * @param context pointer to flash_context structure.
 * @retval @ref FLASH_OP_DONE once operation was done, @ref FLASH_OP_ONGOING if
 *         operation needs more time for execution and a negative error code if
 *         operation was aborted.
 */
typedef int (*flash_op_handler_t) (void *context);

struct flash_op_desc {
	flash_op_handler_t handler;
	struct flash_context *context; /* [in,out] */
};

/**
 * Synchronization backend driver initialization procedure.
 *
 * This will be run within flash driver initialization
 */
int nrf_flash_sync_init(void);

/**
 * Set synchronization context for synchronous operations.
 *
 * This function set backend's internal context for expected timing parameter.
 *
 * @param duration Duration of the execution window [us]
 */
void nrf_flash_sync_set_context(uint32_t duration);

/**
 * Check if the operation need to be run synchronous with radio.
 *
 * @retval True if operation need to be run synchronously, otherwise False
 */
bool nrf_flash_sync_is_required(void);

/**
 * Execute the flash operation synchronously along the radio operations.
 *
 * Function executes callbacks op_desc->handler() in execution windows according
 * to timing settings requested by nrf_flash_sync_set_context().
 * This routine need to be called the handler as many time as it returns
 * FLASH_OP_ONGOING, however an operation timeout should be implemented.
 * When the handler() returns FLASH_OP_DONE or an error code, no further
 * execution windows are needed so function should return as the handler()
 * finished its operation.
 *
 * @retval 0 if op_desc->handler() was executed and finished its operation
 * successfully. Otherwise (handler returned error, timeout, couldn't schedule
 * execution...) a negative error code.
 *
 *                              execution window
 *            Driver task           task
 *                  |                 |
 *                  |                 |
 * nrf_flash_sync_  #                 |
 * set_context()    #                 |
 *                  |                 |
 *                  |                 |
 * call nrf_flash_  #                 |
 * sync_exe()       #                 |
 *                  #---------------->|
 *                  |                 |
 *                  |                 # execution window 0
 *                  |                 # call flash_op_handler_t handler()
 *                  |                 #
 *                  |                 #
 *                  |                 # flash_op_handler_t handler() return
 *                  |                 #         FLASH_OP_ONGOING
 *                  |                 # {backend request/allow
 *                  |                 |  the next execution window}
 *                  .                 .
 *                  .                 .
 *                  .                 .
 *                  |                 |
 *                  |                 # execution window N
 *                  |                 # call flash_op_handler_t handler()
 *                  |                 #
 *                  |                 #
 *                  |                 #
 *                  |                 # flash_op_handler_t handler() returns
 *                  |                 #         FLASH_OP_DONE
 *                  |<----------------# {backend transfer execution
 *                  #                 |  to the driver back}
 * nrf_flash_       #                 |
 * sync_exe()       |                 |
 * return           |                 |
 */
int nrf_flash_sync_exe(struct flash_op_desc *op_desc);

/**
 * @}
 */

/**
 * @defgroup nrf_flash_sync_timing sync timing backend API
 * @ingroup nrf_flash_sync
 * @{
 *
 * API which is used by nrf flash driver for check where execution fill in
 * the execution window.
 *
 * API is used as follows:
 * begin of execution window
 * call flash_op_handler_t handler()
 *   nrf_flash_sync_get_timestamp_begin()
 *   [does some chunk of work]
 *   nrf_flash_sync_check_time_limit() == false
 *   [does some chunk of work]
 *   nrf_flash_sync_check_time_limit() == false
 *   [does some chunk of work]
 *   ...
 *   nrf_flash_sync_check_time_limit() == true
 *   [preserve work context for next execution window]
 * return form flash_op_handler_t handler()
 * [return from execution window]
 * end of execution window
 */

/**
 * Get timestamp and store it in synchronization backend
 * context data as operation beginning time reference.
 * This timestamp will be used by @ref nrf_flash_sync_check_time_limit()
 * as the execution window begin reference.
 */
void nrf_flash_sync_get_timestamp_begin(void);

/**
 * Estimate whether next iteration will fit in time constraints.
 * This function fetch current timestamp and compare it with the operation
 * beginning timestamp reference stored by
 * @ref nrf_flash_sync_get_timestamp_begin() in the synchronization backend
 * context data.
 *
 * @param iteration iteration number.
 * @retval true if estimated time excess, false otherwise.
 */
bool nrf_flash_sync_check_time_limit(uint32_t iteration);

/**
 * @}
 */

#endif /* !CONFIG_SOC_FLASH_NRF_RADIO_SYNC_NONE */
#endif /* !__SOC_FLASH_NRF_H__ */