/*
 * Copyright (c) 1993-1995, 1999-2008 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

/*
 * The timer_call system is responsible for manipulating timers that call
 * callbacks at a given deadline (with or without some leeway for coalescing).
 *
 * Call timer_call_setup once on a timer_call structure to register the callback
 * function and a context parameter that's passed to it (param0).
 *
 * To arm the timer to fire at a deadline, call any of the timer_call_enter
 * functions.  If the function used accepts a parameter, it will be passed to
 * the callback function when it fires.
 *
 * If the timer needs to be cancelled (like if the timer_call has been armed but
 * now needs to be deallocated), call timer_call_cancel.
 */

#ifndef _KERN_TIMER_CALL_H_
#define _KERN_TIMER_CALL_H_

#include <mach/mach_types.h>
#include <kern/kern_types.h>

#ifdef XNU_KERNEL_PRIVATE

#include <kern/simple_lock.h>

#ifdef MACH_KERNEL_PRIVATE
#include <kern/queue.h>
#include <kern/priority_queue.h>
#include <kern/mpqueue.h>

extern boolean_t mach_timer_coalescing_enabled;
extern void timer_call_queue_init(mpqueue_head_t *);
#endif /* MACH_KERNEL_PRIVATE */

#if XNU_TARGET_OS_OSX
#define TIMER_TRACE     1
#endif

typedef void            *timer_call_param_t;
typedef void            (*timer_call_func_t)(
	timer_call_param_t      param0,
	timer_call_param_t      param1);

typedef struct timer_call {
	uint64_t                                tc_soft_deadline;
	decl_simple_lock_data(, tc_lock);          /* protects tc_queue */
	struct priority_queue_entry_deadline    tc_pqlink;
	queue_head_t                            *tc_queue;
	queue_chain_t                           tc_qlink;
	timer_call_func_t                       tc_func;
	timer_call_param_t                      tc_param0;
	timer_call_param_t                      tc_param1;
	uint64_t                                tc_ttd; /* Time to deadline at creation */
#if TIMER_TRACE
	uint64_t                                tc_entry_time;
#endif
	uint32_t                                tc_flags;
	/* this field is locked by the lock in the object tc_queue points at */
	bool                                    tc_async_dequeue;
} timer_call_data_t, *timer_call_t;

#define EndOfAllTime            0xFFFFFFFFFFFFFFFFULL


/*
 * Flags to alter the default timer/timeout coalescing behavior
 * on a per-timer_call basis.
 *
 * The SYS urgency classes indicate that the timer_call is not
 * directly related to the current thread at the time the timer_call
 * is entered, so it is ignored in the calculation entirely (only
 * the subclass specified is used).
 *
 * The USER flags indicate that both the current thread scheduling and QoS
 * attributes, in addition to the per-timer_call urgency specification,
 * are used to establish coalescing behavior.
 */
#define TIMER_CALL_SYS_NORMAL           TIMEOUT_URGENCY_SYS_NORMAL
#define TIMER_CALL_SYS_CRITICAL         TIMEOUT_URGENCY_SYS_CRITICAL
#define TIMER_CALL_SYS_BACKGROUND       TIMEOUT_URGENCY_SYS_BACKGROUND

#define TIMER_CALL_USER_MASK            TIMEOUT_URGENCY_USER_MASK
#define TIMER_CALL_USER_NORMAL          TIMEOUT_URGENCY_USER_NORMAL
#define TIMER_CALL_USER_CRITICAL        TIMEOUT_URGENCY_USER_CRITICAL
#define TIMER_CALL_USER_BACKGROUND      TIMEOUT_URGENCY_USER_BACKGROUND

#define TIMER_CALL_URGENCY_MASK         TIMEOUT_URGENCY_MASK

/*
 * Indicate that a specific leeway value is being provided (otherwise
 * the leeway parameter is ignored).  This supplied value can currently
 * only be used to extend the leeway calculated internally from the
 * urgency class provided.
 */
#define TIMER_CALL_LEEWAY               TIMEOUT_URGENCY_LEEWAY

/*
 * Non-migratable timer_call
 */
#define TIMER_CALL_LOCAL                TIMEOUT_URGENCY_FIRST_AVAIL
#define TIMER_CALL_RATELIMITED          TIMEOUT_URGENCY_RATELIMITED
extern boolean_t        timer_call_enter(
	timer_call_t    call,
	uint64_t        deadline,
	uint32_t        flags);

extern boolean_t        timer_call_enter1(
	timer_call_t            call,
	timer_call_param_t      param1,
	uint64_t                deadline,
	uint32_t                flags);

extern boolean_t        timer_call_enter_with_leeway(
	timer_call_t            call,
	timer_call_param_t      param1,
	uint64_t                deadline,
	uint64_t                leeway,
	uint32_t                flags,
	boolean_t               ratelimited);

extern boolean_t        timer_call_cancel(
	timer_call_t    call);

extern void             timer_call_setup(
	timer_call_t            call,
	timer_call_func_t       func,
	timer_call_param_t      param0);

extern int timer_get_user_idle_level(void);
extern kern_return_t timer_set_user_idle_level(int ilevel);

#define NUM_LATENCY_QOS_TIERS (6)
typedef struct {
	uint32_t powergate_latency_abstime;

	uint32_t idle_entry_timer_processing_hdeadline_threshold_abstime;
	uint32_t interrupt_timer_coalescing_ilat_threshold_abstime;
	uint32_t timer_resort_threshold_abstime;

	int32_t timer_coalesce_rt_shift;
	int32_t timer_coalesce_bg_shift;
	int32_t timer_coalesce_kt_shift;
	int32_t timer_coalesce_fp_shift;
	int32_t timer_coalesce_ts_shift;

	uint64_t timer_coalesce_rt_abstime_max;
	uint64_t timer_coalesce_bg_abstime_max;
	uint64_t timer_coalesce_kt_abstime_max;
	uint64_t timer_coalesce_fp_abstime_max;
	uint64_t timer_coalesce_ts_abstime_max;

	uint32_t latency_qos_scale[NUM_LATENCY_QOS_TIERS];
	uint64_t latency_qos_abstime_max[NUM_LATENCY_QOS_TIERS];
	boolean_t latency_tier_rate_limited[NUM_LATENCY_QOS_TIERS];
} timer_coalescing_priority_params_t;
extern timer_coalescing_priority_params_t tcoal_prio_params;

/*
 * Initialize the timer call subsystem during system startup.
 */
extern void timer_call_init(void);

#if MACH_KERNEL_PRIVATE

/*
 * Handle deadlines in the past.
 */
uint64_t timer_call_past_deadline_timer_handle(uint64_t deadline,
    uint64_t ctime);

/*
 * Running timers are only active for a given CPU when a non-idle thread
 * is running.
 */

enum running_timer {
	RUNNING_TIMER_QUANTUM,
#if KPERF
	RUNNING_TIMER_KPERF,
#endif /* KPERF */
	RUNNING_TIMER_MAX,
};

/*
 * Get the earliest active deadline for this processor.
 */
uint64_t running_timers_deadline(processor_t processor);

/*
 * Run the expire handler to process any timers past their deadline.  Returns
 * true if any timer was processed, and false otherwise.
 */
bool running_timers_expire(processor_t processor, uint64_t now);

/*
 * Set up a new deadline for the given running timer on the processor, but don't
 * synchronize it with the hardware.  A subsequent call to running_timers_sync
 * is necessary.  This allows thread_dispatch to batch all of the setup and only
 * set the decrementer once.
 */
void running_timer_setup(processor_t processor, enum running_timer timer,
    void *param, uint64_t deadline, uint64_t now);

/*
 * Synchronize the state of any running timers that have been set up with the
 * hardware.
 */
void running_timers_sync(void);

/*
 * Enter a new deadline for the given running timer on the processor and put it
 * into effect.
 */
void running_timer_enter(processor_t processor, enum running_timer timer,
    void *param, uint64_t deadline, uint64_t now);

/*
 * Clear the deadline and parameters for the given running timer on the
 * processor.
 */
void running_timer_clear(processor_t processor, enum running_timer timer);

/*
 * Cancel a running timer on the processor.
 */
void running_timer_cancel(processor_t processor, enum running_timer timer);

/*
 * Activate the running timers for the given, current processor.  Should only be
 * called by thread_dispatch.
 */
void running_timers_activate(processor_t processor);

/*
 * Deactivate the running timers for the given, current processor.  Should only
 * be called by thread_dispatch.
 */
void running_timers_deactivate(processor_t processor);

#endif /* MACH_KERNEL_PRIVATE */

#endif /* XNU_KERNEL_PRIVATE */

#endif /* _KERN_TIMER_CALL_H_ */