/** @file wlan_mac_schedule.c
 *  @brief Scheduler subsystem for high MAC framework
 *
 *  This set of functions allows upper-level MAC implementations
 *	to schedule the execution of a provided callback for some point
 *	in the future.
 *
 *  @copyright Copyright 2014-2019, Mango Communications. All rights reserved.
 *          Distributed under the Mango Communications Reference Design License
 *              See LICENSE.txt included in the design archive or
 *              at http://mangocomm.com/802.11/license
 *
 *  This file is part of the Mango 802.11 Reference Design (https://mangocomm.com/802.11)
 */

/***************************** Include Files *********************************/
#include "wlan_mac_high_sw_config.h"

#include "xil_types.h"
#include "xil_exception.h"

#include "wlan_platform_high.h"
#include "wlan_platform_common.h"
#include "wlan_platform_timer.h"

#include "wlan_mac_high.h"
#include "wlan_mac_dl_list.h"
#include "wlan_mac_schedule.h"


/*************************** Variable Definitions ****************************/
// Global counter for assigning unique event IDs
static volatile u32 sched_event_id_cntr;

// Global to count number of currently-defined scheduled events
static int total_num_scheduled_events;

// Global array of schedules; reference code defines two by default
#define NUM_SCHEDULES 2
static wlan_schedule_t wlan_schedules[NUM_SCHEDULES];

/******************************** Functions **********************************/

/*****************************************************************************/
/**
 * Initializes the scheduler subsystem.
 *
 * @param    None
 *
 * @return   WLAN_SUCCESS
 *
 *****************************************************************************/
int wlan_mac_schedule_init(){
	int i;

	// Initialize globals
	total_num_scheduled_events = 0;

	// Counter increments as events are assigned unique IDs upon creation
	// Event IDs are globally unique and do not need to be densely packed
	//  First event assigned ID 1 by convention
	sched_event_id_cntr = 1;

	// Initialize each schedule's event list
	for(i=0; i<NUM_SCHEDULES; i++) {
		dl_list_init(&(wlan_schedules[i].event_list));
	}

	// Define the default schedules
	// By convention schedules are ordered most-frequent (#0) to least-frequent

	// Fine schedule - executes on every timer ISR
	wlan_schedules[SCHEDULE_ID_FINE].exec_interval = 0;
	wlan_schedules[SCHEDULE_ID_FINE].polls_to_next_exec = 0;

	// Coarse schedule - executes every 4096 timer ISRs (2.6msec for 64usec timer interval)
	wlan_schedules[SCHEDULE_ID_COARSE].exec_interval = 4096;
	wlan_schedules[SCHEDULE_ID_COARSE].polls_to_next_exec = 4095;

	return WLAN_SUCCESS;
}

/*****************************************************************************/
/**
 * Schedules the execution of a callback for some time in the future
 *
 * @param   scheduler_sel    - SCHEDULE_ID_COARSE or SCHEDULE_ID_FINE
 * @param   interval_us      - Interval (in microseconds) until callback should be called
 * @param   num_calls        - Number of repetitions or SCHEDULE_REPEAT_FOREVER for permanent periodic
 * @param   callback         - Function pointer to callback
 *
 * @return  id               - ID of scheduled event or SCHEDULE_FAILURE if error
 *
 *****************************************************************************/
u32 wlan_mac_schedule_add_event(u8 schedule_sel, u32 interval_us, u32 num_calls, void(*callback)()) {
	u32 id;
	dl_entry* event_entry_ptr;
	wlan_sched_event_t* event_ptr;
	u64 curr_system_time;

	if(schedule_sel >= NUM_SCHEDULES) {
		xil_printf("WARNING: invalid schedule selection %d\n", schedule_sel);
		return SCHEDULE_FAILURE;
	}

	// Allocate memory for data structures
	event_entry_ptr = wlan_mac_high_malloc(sizeof(dl_entry));
	if (event_entry_ptr == NULL) {
		return SCHEDULE_FAILURE;
	}

	event_ptr = wlan_mac_high_malloc(sizeof(wlan_sched_event_t));
	if (event_ptr == NULL) {
		wlan_mac_high_free(event_entry_ptr);
		return SCHEDULE_FAILURE;
	}

	// Attach the schedule struct to this dl_entry
	event_entry_ptr->data = event_ptr;

	// Get unique scheduled event ID from global counter
	// TODO: handle (very unlikely) case of exhausting all scheduled event IDs; this while loop would run forever as-is
	do{
		id = (sched_event_id_cntr++);

		// Check if we hit the section of reserved IDs; Wrap back to 0 and start again
		if ((id >= SCHEDULE_ID_RESERVED_MIN) && (id <= SCHEDULE_ID_RESERVED_MAX)) { id = 1; }

		// Check if this candidate id is already allocated
	} while(wlan_mac_schedule_find_event(id, NULL) != NULL);

	// Get the current system time
	curr_system_time = get_system_time_usec();

	// Initialize the scheduled event struct
	event_ptr->enabled	   = 1;
	event_ptr->id          = id;
	event_ptr->interval_us = interval_us;
	event_ptr->num_calls   = num_calls;
	event_ptr->target_us   = curr_system_time + (u64)(interval_us);
	event_ptr->callback    = (function_ptr_t)callback;

	// Add new scheduled event to the schedule's list of events
	total_num_scheduled_events++;
	dl_entry_insertEnd(&(wlan_schedules[schedule_sel].event_list), event_entry_ptr);

	// Check if this new scheduled event will be the only scheduled event
	// If so the timer must be started - the timer is stopped when there are
	//  no scheduled events to avoid unnecessary interrupts
	if(total_num_scheduled_events == 1) {
		wlan_timer_start();
	}

	return id;
}


int wlan_mac_schedule_disable_event(u32 event_id) {
	dl_entry* event_entry;

	// Check if event_id is valid
	event_entry = wlan_mac_schedule_find_event(event_id, NULL);

	if(event_entry == NULL) {
		xil_printf("WARNING: attempted to disable unknown event ID %d\n", event_id);
		return WLAN_FAILURE;
	}

	((wlan_sched_event_t*)(event_entry->data))->enabled = 0;

	return WLAN_SUCCESS;
}

int wlan_mac_schedule_enable_event(u32 event_id) {
	dl_entry* event_entry;

	// Check if event_id is valid
	event_entry = wlan_mac_schedule_find_event(event_id, NULL);

	if(event_entry == NULL) {
		xil_printf("WARNING: attempted to enable unknown event ID %d\n", event_id);
		return WLAN_FAILURE;
	}

	// Enable the event and schedule its next execution
	((wlan_sched_event_t*)(event_entry->data))->enabled = 1;
	((wlan_sched_event_t*)(event_entry->data))->target_us = get_system_time_usec() + ((wlan_sched_event_t*)(event_entry->data))->interval_us;

	return WLAN_SUCCESS;
}


/*****************************************************************************/
/**
 * @brief  Deletes a scheduled event
 *
 * @param   event_id - ID of scheduled event to remove
 *
 * @return  int status - WLAN SUCCESS or WLAN_FAILURE
 *
 *****************************************************************************/
int wlan_mac_schedule_remove_event(u32 event_id) {
	wlan_sched_event_t* event_ptr = NULL;
	dl_entry* event_entry_ptr = NULL;
	dl_list* event_list = NULL;

	// Lookup the event list entry from the event ID
	event_entry_ptr = wlan_mac_schedule_find_event(event_id, &event_list);

	if(event_entry_ptr == NULL) {
		xil_printf("WARNING: attempted to remove unknown schedule ID %d\n", event_id);
		return WLAN_FAILURE;
	}

	if(event_list == NULL) {
		xil_printf("WARNING: wlan_mac_schedule_find_event() returned NULL list for event ID %d\n", event_id);
		return WLAN_FAILURE;
	}

	// Extract the scheduled event struct from the dl_entry
	event_ptr = (wlan_sched_event_t*)(event_entry_ptr->data);

	if(event_ptr == NULL) {
		xil_printf("WARNING: schedule entry for ID %d had NULL data\n", event_id);
		return WLAN_FAILURE;
	}

	// Remove the list entry and free the entry/data memory allocations
	dl_entry_remove(event_list, event_entry_ptr);
	wlan_mac_high_free(event_entry_ptr);
	wlan_mac_high_free(event_ptr);

	total_num_scheduled_events--;

	// Stop the timer if there are now zero scheduled events
	if(total_num_scheduled_events == 0) {
		wlan_timer_stop();
	}

	return WLAN_SUCCESS;
}


/*****************************************************************************/
/**
 * This function is called periodically (typically by a timer ISR) to
 * evaluate all schedules and scheduled events.
 *
 * @return  Returns WLAN_SUCCESS
 *
 *****************************************************************************/
int wlan_mac_schedule_poll() {

	wlan_schedule_t* sched;
	dl_list* event_list;

	dl_entry* event_entry_ptr;
	wlan_sched_event_t* event_ptr;
	int event_id;
	function_ptr_t event_callback;

	int sched_id;
	int l_iter;

	// Record the current system time once here to avoid race conditions
	//  when evaluating multiple schedules/events below
	u64 curr_system_time = get_system_time_usec();

	// Evaluate every schedule
	for(sched_id=0; sched_id < NUM_SCHEDULES; sched_id++) {
		sched = &(wlan_schedules[sched_id]);
		event_list = &(wlan_schedules[sched_id].event_list);

		// Check if this schedule is due for evaluation
		//  Scheduled events are only considered (via the while loop below)
		//   when their parent schedule is evaluated. This saves loop iterations
		//   and u64 comparisons for groups of infrequently-executed events
		if(sched->polls_to_next_exec > 0) {
			// Schedule not due for evaluation - decrement its poll counter and continue
			sched->polls_to_next_exec--;

		} else {
			// Schedule is due for evaluation - iterate over all its events

			// Initialize the dl_entry pointer to the head of the event_list
			event_entry_ptr = event_list->first;
			l_iter = event_list->length;

			while((event_entry_ptr != NULL) && (l_iter-- > 0)) {
				event_ptr = (wlan_sched_event_t*)event_entry_ptr->data;

				// Update the dl_entry pointer for the next iteration
				//  This happens before the callback in case the callback removes the
				//  event (callbacks shouldn't do this, but just in case)
				// TODO: consider making this even safer - what happens if callback N
				//  removes scheduled event N+1? This pointer would be bogus. Perhaps
				//  record the next pointer here then again below, punting if they differ?
				event_entry_ptr = dl_entry_next(event_entry_ptr);

				// Call the event's callback if it's enabled and its next execution time has passed
				//  Evaluate 'enabled' first to avoid unnecessary u64 comparisons
				if((event_ptr->enabled == 1) && (curr_system_time >= (event_ptr->target_us))) {
					// Decrement the number of remaining calls for this event only if event
					//  has finite and non-zero number of remaining calls
					if ((event_ptr->num_calls != SCHEDULE_REPEAT_FOREVER) &&
						(event_ptr->num_calls != 0)) {

						(event_ptr->num_calls)--;
					}

					// Call the scheduled event's callback
					event_id       = event_ptr->id;
					event_callback = event_ptr->callback;
					event_callback(event_id);

					// Update or remove the scheduled event *after* the callback in case the
					//  callback changed the event's parameters. For example the callback might
					//  reset the num_calls value, indicating the event should not be removed
					if(event_ptr->num_calls == 0) {
						// Remove event after its final execution
						wlan_mac_schedule_remove_event(event_id);
					} else {
						// Update target time for next execution
						event_ptr->target_us = curr_system_time + (u64)(event_ptr->interval_us);
					}
				} //END if(curr_system_time > event.target)
			}

			// Update the schedule after evaluating all its scheduled events
			//  The fastest schedule always has exec_interval=polls_to_next_exec=0,
			if(sched->exec_interval != 0) {
				sched->polls_to_next_exec = sched->exec_interval;
			}

		} //END else of if(polls_to_next_exec > 0)
	} //END for(sched_id in wlan_schedules)

	return WLAN_SUCCESS;
}



/*****************************************************************************/
/**
 * Find schedule that corresponds to a given ID
 *
 * @param   event_id        - ID of the scheduled event to find
 * @param   dl_list**   - Return param for list containing the scheduled event,
 *                        if event_id is found. Pass NULL if list pointer is
 *                        not required by calling context.
 *
 * @return  dl_entry*   - Pointer to the list entry for the scheduled event
 *
 *****************************************************************************/
dl_entry* wlan_mac_schedule_find_event(u32 event_id, dl_list** sched_list_ret) {
	int i, iter;

	dl_list*  event_list;
	dl_entry* curr_dl_entry;
	dl_entry* next_dl_entry;
	wlan_sched_event_t* curr_event;

	// Check all event lists for the matching ID
	for(i=0; i < NUM_SCHEDULES; i++) {
		event_list = &(wlan_schedules[i].event_list);

		// Initialize the loop variables
		iter = event_list->length;
		next_dl_entry = event_list->first;

		// Search the event_list for this event_id
		while ((next_dl_entry != NULL) && (iter-- > 0)) {
			curr_dl_entry   = next_dl_entry;
			next_dl_entry   = dl_entry_next(next_dl_entry);
			curr_event      = (wlan_sched_event_t*)(curr_dl_entry->data);

			if(curr_event->id == event_id) {
				// Found a matching event - populate the return list argument
				//  if the caller asked for it
				if(sched_list_ret != NULL) {
					*sched_list_ret = event_list;
				}
				return curr_dl_entry;
			}
		}
	}

	// Matching event not found
	return NULL;
}