xnu-2050.7.9.tar.gz

[apple/xnu.git] / osfmk / pmc / pmc.c

/*
 * Copyright (c) 2009 Apple Inc. All rights reserved.
 *
 * @APPLE_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. 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_LICENSE_HEADER_END@
 */

#include <kern/kalloc.h>
#include <kern/kern_types.h>
#include <kern/locks.h>
#include <kern/misc_protos.h>
#include <kern/task.h>
#include <kern/thread.h>
#include <kern/zalloc.h>
#include <machine/machine_cpu.h>

#include <pmc/pmc.h>

#include <libkern/OSAtomic.h>

#if defined(__i386__) || defined(__x86_64__)
#include <i386/mp.h>
#endif

#if CONFIG_COUNTERS

/* various debug logging enable */
#undef DEBUG_COUNTERS

typedef uint8_t pmc_state_event_t;

#define PMC_STATE_EVENT_START                           0
#define PMC_STATE_EVENT_STOP                            1
#define PMC_STATE_EVENT_FREE                            2
#define PMC_STATE_EVENT_INTERRUPT                       3
#define PMC_STATE_EVENT_END_OF_INTERRUPT        4
#define PMC_STATE_EVENT_CONTEXT_IN                      5
#define PMC_STATE_EVENT_CONTEXT_OUT                     6
#define PMC_STATE_EVENT_LOAD_FINISHED           7
#define PMC_STATE_EVENT_STORE_FINISHED          8

/* PMC spin timeouts */
#define PMC_SPIN_THRESHOLD      10      /* Number of spins to allow before checking mach_absolute_time() */
#define PMC_SPIN_TIMEOUT_US     10      /* Time in microseconds before the spin causes an assert */

uint64_t pmc_spin_timeout_count = 0;    /* Number of times where a PMC spin loop causes a timeout */

#ifdef DEBUG_COUNTERS
#       include <pexpert/pexpert.h>
#       define COUNTER_DEBUG(...) \
        do { \
                kprintf("[%s:%s][%u] ", __FILE__, __PRETTY_FUNCTION__, cpu_number()); \
                kprintf(__VA_ARGS__); \
        } while(0)

#       define PRINT_PERF_MON(x)        \
        do { \
                kprintf("perfmon: %p (obj: %p refCt: %u switchable: %u)\n", \
                        x, x->object, x->useCount, \
                        (x->methods.flags & PERFMON_FLAG_SUPPORTS_CONTEXT_SWITCHING) ? \
                        1 : 0); \
        } while(0)

static const char const * pmc_state_state_name(pmc_state_t state) {
        switch (PMC_STATE_STATE(state)) {
                case PMC_STATE_STATE_INVALID:
                        return "INVALID";
                case PMC_STATE_STATE_STOP:
                        return "STOP";
                case PMC_STATE_STATE_CAN_RUN:
                        return "CAN_RUN";
                case PMC_STATE_STATE_LOAD:
                        return "LOAD";
                case PMC_STATE_STATE_RUN:
                        return "RUN";
                case PMC_STATE_STATE_STORE:
                        return "STORE";
                case PMC_STATE_STATE_INTERRUPT:
                        return "INTERRUPT";
                case PMC_STATE_STATE_DEALLOC:
                        return "DEALLOC";
                default:
                        return "UNKNOWN";
        }
}

static const char const * pmc_state_event_name(pmc_state_event_t event) {
        switch (event) {
                case PMC_STATE_EVENT_START:
                        return "START";
                case PMC_STATE_EVENT_STOP:
                        return "STOP";
                case PMC_STATE_EVENT_FREE:
                        return "FREE";
                case PMC_STATE_EVENT_INTERRUPT:
                        return "INTERRUPT";
                case PMC_STATE_EVENT_END_OF_INTERRUPT:
                        return "END OF INTERRUPT";
                case PMC_STATE_EVENT_CONTEXT_IN:
                        return "CONTEXT IN";
                case PMC_STATE_EVENT_CONTEXT_OUT:
                        return "CONTEXT OUT";
                case PMC_STATE_EVENT_LOAD_FINISHED:
                        return "LOAD_FINISHED";
                case PMC_STATE_EVENT_STORE_FINISHED:
                        return "STORE_FINISHED";
                default:
                        return "UNKNOWN";
        }
}

#       define PMC_STATE_FORMAT "<%s, %u, %s%s%s>"
#       define PMC_STATE_ARGS(x)        pmc_state_state_name(x), PMC_STATE_CONTEXT_COUNT(x), ((PMC_STATE_FLAGS(x) & PMC_STATE_FLAGS_INTERRUPTING) ? "I" : ""), \
                                        ((PMC_STATE_FLAGS(x) & PMC_STATE_FLAGS_STOPPING) ? "S" : ""), ((PMC_STATE_FLAGS(x) & PMC_STATE_FLAGS_DEALLOCING) ? "D" : "")
#else
#       define COUNTER_DEBUG(...)
#       define PRINT_PERF_MON(x)
#       define PMC_STATE_FORMAT
#       define PMC_STATE_ARGS(x)
#endif

/*!struct
 * pmc_config is the data behind a pmc_config_t.
 * @member object A pointer to an instance of IOPerformanceCounterConfiguration
 * @member method A pointer to a method to call to handle PMI.
 * @member interrupt_after_value Cause a PMI after the counter counts this many
 * events.
 * @member refCon Passed to the @method method as the refCon argument.
 */
struct pmc_config {
        pmc_config_object_t object;
        volatile pmc_interrupt_method_t method;
        uint64_t interrupt_after_value;
        void *refCon;
};

/*
 * Allocation Zones
 * 
 * Two allocation zones - Perf zone small and Perf zone big.
 * Each zone has associated maximums, defined below.
 * The small zone is the max of the smallest allocation objects (all sizes on
 * K64):
 *      perf_monitor_t - 48 bytes
 *              perf_monitor_methods_t - 28 bytes
 *      pmc_reservation_t - 48 bytes
 *  pmc_config_t - 32 bytes
 * perf_small_zone unit size is (on K64) 48 bytes
 * perf_small_zone max count must be max number of perf monitors, plus (max
 * number of reservations * 2). The "*2" is because each reservation has a
 * pmc_config_t within.
 *
 * Big zone is max of the larger allocation units
 *      pmc_t - 144 bytes
 *              pmc_methods_t - 116 bytes
 * perf_big_zone unit size is (on K64) 144 bytes
 * perf_big_zone max count is the max number of PMCs we support.
 */

static zone_t perf_small_zone = NULL;
#define MAX_PERF_SMALLS         (256 + 8196 + 8196)
#define PERF_SMALL_UNIT_SZ      (MAX(MAX(sizeof(struct perf_monitor), \
        sizeof(struct pmc_reservation)), sizeof(struct pmc_config))) 

static zone_t perf_big_zone = NULL;
#define MAX_PERF_BIGS           (1024)
#define PERF_BIG_UNIT_SZ        (sizeof(struct pmc))

/*
 * Locks and Lock groups
 */
static lck_grp_t *pmc_lock_grp = LCK_GRP_NULL;
static lck_grp_attr_t *pmc_lock_grp_attr;
static lck_attr_t *pmc_lock_attr;

/* PMC tracking queue locks */

static lck_mtx_t  cpu_monitor_queue_mutex;   /* protects per-cpu queues at initialisation time */
static lck_spin_t perf_monitor_queue_spin;   /* protects adding and removing from queue */
static lck_spin_t perf_counters_queue_spin;  /* protects adding and removing from queue */

/* Reservation tracking queues lock */
static lck_spin_t reservations_spin;

/*
 * Tracking queues
 *
 * Keeps track of registered perf monitors and perf counters
 */

static queue_head_t **cpu_monitor_queues = NULL;

static queue_head_t *perf_monitors_queue = NULL;
static volatile uint32_t perf_monitors_count = 0U;

static queue_head_t *perf_counters_queue = NULL;
static volatile uint32_t perf_counters_count = 0U;

/* 
 * Reservation queues
 *
 * Keeps track of all system, task, and thread-level reservations (both active and
 * inactive).
 *
 * We track them all here (rather than in their respective task or thread only)
 * so that we can inspect our tracking data directly (rather than peeking at
 * every task and thread) to determine if/when a new reservation would
 * constitute a conflict.
 */
 
static queue_head_t *system_reservations = NULL;
static volatile uint32_t system_reservation_count = 0U;

static queue_head_t *task_reservations = NULL;
static volatile uint32_t task_reservation_count = 0U;

static queue_head_t *thread_reservations = NULL;
static volatile uint32_t thread_reservation_count = 0U;

#if XNU_KERNEL_PRIVATE

/*
 * init_pmc_locks creates and initializes all the locks and lock groups and lock
 * attributes required for the pmc sub-system.
 */
static void init_pmc_locks(void) {
        pmc_lock_attr = lck_attr_alloc_init();
        assert(pmc_lock_attr);

        pmc_lock_grp_attr = lck_grp_attr_alloc_init();
        assert(pmc_lock_grp_attr);

        pmc_lock_grp = lck_grp_alloc_init("pmc", pmc_lock_grp_attr);
        assert(pmc_lock_grp);

        lck_spin_init(&perf_monitor_queue_spin, pmc_lock_grp, pmc_lock_attr);
        lck_spin_init(&perf_counters_queue_spin, pmc_lock_grp, pmc_lock_attr);

        lck_spin_init(&reservations_spin, pmc_lock_grp, pmc_lock_attr);

        lck_mtx_init(&cpu_monitor_queue_mutex, pmc_lock_grp, pmc_lock_attr);
}

/*
 * init_pmc_zones initializes the allocation zones used by the pmc subsystem
 */
static void init_pmc_zones(void) {
        perf_small_zone = zinit(PERF_SMALL_UNIT_SZ, 
                MAX_PERF_SMALLS * PERF_SMALL_UNIT_SZ, MAX_PERF_SMALLS, 
                "pmc.small zone");

        assert(perf_small_zone);

        perf_big_zone = zinit(PERF_BIG_UNIT_SZ,
                MAX_PERF_BIGS * PERF_BIG_UNIT_SZ, MAX_PERF_BIGS, 
                "pmc.big zone");

        assert(perf_big_zone);
}

/*
 * init_pmc_queues allocates and initializes the tracking queues for
 * registering and reserving individual pmcs and perf monitors.
 */
static void init_pmc_queues(void) {
    
        perf_monitors_queue = (queue_head_t*)kalloc(sizeof(queue_head_t));
        assert(perf_monitors_queue);

        queue_init(perf_monitors_queue);

        perf_counters_queue = (queue_head_t*)kalloc(sizeof(queue_head_t));
        assert(perf_counters_queue);

        queue_init(perf_counters_queue);

        system_reservations = (queue_head_t*)kalloc(sizeof(queue_t));
        assert(system_reservations);

        queue_init(system_reservations);

        task_reservations = (queue_head_t*)kalloc(sizeof(queue_head_t));
        assert(task_reservations);

        queue_init(task_reservations);

        thread_reservations = (queue_head_t*)kalloc(sizeof(queue_head_t));
        assert(thread_reservations);

        queue_init(thread_reservations);
}

/*
 * pmc_bootstrap brings up all the necessary infrastructure required to use the
 * pmc sub-system.
 */
__private_extern__
void pmc_bootstrap(void) {
        /* build our alloc zones */
        init_pmc_zones();

        /* build the locks */
        init_pmc_locks();

        /* build our tracking queues */
        init_pmc_queues();
}

#endif /* XNU_KERNEL_PRIVATE */

/*
 * Perf Monitor Internals
 */

static perf_monitor_t perf_monitor_alloc(void) {
        /* perf monitors come from the perf small zone */
        return (perf_monitor_t)zalloc(perf_small_zone);
}

static void perf_monitor_free(void *pm) {
        zfree(perf_small_zone, pm);
}

static void perf_monitor_init(perf_monitor_t pm, int cpu) {
        assert(pm);

        pm->object = NULL;

        bzero(&(pm->methods), sizeof(perf_monitor_methods_t));

        pm->useCount = 1;       /* initial retain count of 1, for caller */
        
        pm->reservedCounters = 0;
    
        pm->cpu = cpu;

        pm->link.next = pm->link.prev = (queue_entry_t)NULL;
        pm->cpu_link.next = pm->cpu_link.prev = (queue_entry_t)NULL;
}

/*
 * perf_monitor_dequeue removes the given perf_monitor_t from the
 * perf_monitor_queue, thereby unregistering it with the system.
 */
static void perf_monitor_dequeue(perf_monitor_t pm) {
        lck_spin_lock(&perf_monitor_queue_spin);
        
        if (pm->methods.flags & PERFMON_FLAG_REQUIRES_IDLE_NOTIFICATIONS) {
                /* If this flag is set, the monitor is already validated to be 
                 * accessible from a single cpu only.
                 */
                queue_remove(cpu_monitor_queues[pm->cpu], pm, perf_monitor_t, cpu_link); 
        }
        
        /* 
         * remove the @pm object from the @perf_monitor_queue queue (it is of type
         * <perf_monitor_t> and has a field called @link that is the queue_link_t
         */
        queue_remove(perf_monitors_queue, pm, perf_monitor_t, link);

        perf_monitors_count--;

        lck_spin_unlock(&perf_monitor_queue_spin);
}

/*
 * perf_monitor_enqueue adds the given perf_monitor_t to the perf_monitor_queue,
 * thereby registering it for use with the system.
 */
static void perf_monitor_enqueue(perf_monitor_t pm) {
    
        lck_mtx_lock(&cpu_monitor_queue_mutex);
        lck_spin_lock(&perf_monitor_queue_spin);

        if (pm->cpu >= 0) {
                /* Deferred initialisation; saves memory and permits ml_get_max_cpus()
                 * to block until cpu initialisation is complete.
                 */
                if (!cpu_monitor_queues) {
                        uint32_t max_cpus;
                        queue_head_t **queues;
                        uint32_t i;
                
                        lck_spin_unlock(&perf_monitor_queue_spin);
                
                        max_cpus = ml_get_max_cpus();

                        queues = (queue_head_t**)kalloc(sizeof(queue_head_t*) * max_cpus);
                        assert(queues);
                        for (i = 0; i < max_cpus; i++) {
                                queue_head_t *queue = (queue_head_t*)kalloc(sizeof(queue_head_t));
                                assert(queue);
                                queue_init(queue);
                                queues[i] = queue;
                        }
                
                        lck_spin_lock(&perf_monitor_queue_spin);
                
                        cpu_monitor_queues = queues;
                }
            
                queue_enter(cpu_monitor_queues[pm->cpu], pm, perf_monitor_t, cpu_link);
        }
        
        queue_enter(perf_monitors_queue, pm, perf_monitor_t, link);
        perf_monitors_count++;
        
        lck_spin_unlock(&perf_monitor_queue_spin);
        lck_mtx_unlock(&cpu_monitor_queue_mutex);
}

/*
 * perf_monitor_reference increments the reference count for the given
 * perf_monitor_t.
 */
static void perf_monitor_reference(perf_monitor_t pm) {
        assert(pm);

        OSIncrementAtomic(&(pm->useCount));
}

/*
 * perf_monitor_deallocate decrements the reference count for the given
 * perf_monitor_t.  If the reference count hits 0, the object is released back
 * to the perf_small_zone via a call to perf_monitor_free().
 */
static void perf_monitor_deallocate(perf_monitor_t pm) {
        assert(pm);

        /* If we just removed the last reference count */
        if(1 == OSDecrementAtomic(&(pm->useCount))) {
                /* Free the object */
                perf_monitor_free(pm);
        }
}

/*
 * perf_monitor_find attempts to find a perf_monitor_t that corresponds to the
 * given C++ object pointer that was used when registering with the subsystem.
 *
 * If found, the method returns the perf_monitor_t with an extra reference 
 * placed on the object (or NULL if not
 * found).
 *
 * NOTE: Caller must use perf_monitor_deallocate to remove the extra reference after
 * calling perf_monitor_find.
 */
static perf_monitor_t perf_monitor_find(perf_monitor_object_t monitor) {
        assert(monitor);
        perf_monitor_t element = NULL;
        perf_monitor_t found = NULL;

        lck_spin_lock(&perf_monitor_queue_spin);
        
        queue_iterate(perf_monitors_queue, element, perf_monitor_t, link) {
                if(element->object == monitor) {
                        perf_monitor_reference(element);
                        found = element;
                        break;
                }
        }

        lck_spin_unlock(&perf_monitor_queue_spin);

        return found;
}

/*
 * perf_monitor_add_pmc adds a newly registered PMC to the perf monitor it is
 * associated with.
 */

static void perf_monitor_add_pmc(perf_monitor_t pm, pmc_t pmc __unused) {
        assert(pm);
        assert(pmc);

        /* Today, we merely add a reference count now that a new pmc is attached */
        perf_monitor_reference(pm);
}

/*
 * perf_monitor_remove_pmc removes a newly *un*registered PMC from the perf
 * monitor it is associated with.
 */
static void perf_monitor_remove_pmc(perf_monitor_t pm, pmc_t pmc __unused) {
        assert(pm);
        assert(pmc);

        /* Today, we merely remove a reference count now that the pmc is detached */
        perf_monitor_deallocate(pm);
}

/*
 * Perf Counter internals
 */

static pmc_t pmc_alloc(void) {
        return (pmc_t)zalloc(perf_big_zone);
}

static void pmc_free(void *pmc) {
        zfree(perf_big_zone, pmc);
}

/*
 * pmc_init initializes a newly allocated pmc_t
 */
static void pmc_init(pmc_t pmc) {
        assert(pmc);

        pmc->object = NULL;
        pmc->monitor = NULL;

        bzero(&pmc->methods, sizeof(pmc_methods_t));

        /* One reference for the caller */
        pmc->useCount = 1;
}

/*
 * pmc_reference increments the reference count of the given pmc_t
 */
static void pmc_reference(pmc_t pmc) {
        assert(pmc);

        OSIncrementAtomic(&(pmc->useCount));
}

/*
 * pmc_deallocate decrements the reference count of the given pmc_t. If the
 * reference count hits zero, the given pmc_t is deallocated and released back
 * to the allocation zone.
 */
static void pmc_deallocate(pmc_t pmc) {
        assert(pmc);

        /* If we just removed the last reference count */
        if(1 == OSDecrementAtomic(&(pmc->useCount))) {
                /* Free the pmc */
                pmc_free(pmc);
        }
}

/*
 * pmc_dequeue removes the given, newly *un*registered pmc from the
 * perf_counters_queue.
 */
static void pmc_dequeue(pmc_t pmc) {
        lck_spin_lock(&perf_counters_queue_spin);

        queue_remove(perf_counters_queue, pmc, pmc_t, link);

        perf_counters_count--;

        lck_spin_unlock(&perf_counters_queue_spin);
}

/*
 * pmc_enqueue adds the given, newly registered pmc to the perf_counters_queue
 */
static void pmc_enqueue(pmc_t pmc) {
        lck_spin_lock(&perf_counters_queue_spin);

        queue_enter(perf_counters_queue, pmc, pmc_t, link);

        perf_counters_count++;

        lck_spin_unlock(&perf_counters_queue_spin);
}

/*
 * pmc_find attempts to locate a pmc_t that was registered with the given
 * pmc_object_t pointer.  If found, it returns the pmc_t with an extra reference
 * which must be dropped by the caller by calling pmc_deallocate().
 */
static pmc_t pmc_find(pmc_object_t object) {
        assert(object);

        lck_spin_lock(&perf_counters_queue_spin);
        
        pmc_t element = NULL;
        pmc_t found = NULL;

        queue_iterate(perf_counters_queue, element, pmc_t, link) {
                if(element->object == object) {
                        pmc_reference(element);
                        found = element;
                        break;
                }
        }

        lck_spin_unlock(&perf_counters_queue_spin);

        return found;
}

/*
 * Config internals
 */

/* Allocate a pmc_config_t */
static pmc_config_t pmc_config_alloc(pmc_t pmc __unused) {
        return (pmc_config_t)zalloc(perf_small_zone);
}

/* Free a pmc_config_t, and underlying pmc_config_object_t (if needed) */
static void pmc_config_free(pmc_t pmc, pmc_config_t config) {
        assert(pmc);
        assert(config);

        if(config->object) {
                pmc->methods.free_config(pmc->object, config->object);
                config->object = NULL;
        }

        zfree(perf_small_zone, config);
}

static kern_return_t pmc_open(pmc_t pmc) {
        assert(pmc);
        assert(pmc->object);
        assert(pmc->open_object);

        return pmc->methods.open(pmc->object, pmc->open_object);
}

static kern_return_t pmc_close(pmc_t pmc) {
        assert(pmc);
        assert(pmc->object);
        assert(pmc->open_object);

        return pmc->methods.close(pmc->object, pmc->open_object);
}

/*
 * Reservation Internals
 */

static kern_return_t pmc_internal_reservation_set_pmc(pmc_reservation_t resv, pmc_t pmc);
static void pmc_internal_reservation_store(pmc_reservation_t reservation);
static void pmc_internal_reservation_load(pmc_reservation_t reservation);

static pmc_reservation_t reservation_alloc(void) {
        /* pmc reservations come from the perf small zone */
        return (pmc_reservation_t)zalloc(perf_small_zone);
}

/*
 * reservation_free deallocates and releases all resources associated with the
 * given pmc_reservation_t.  This includes freeing the config used to create the
 * reservation, decrementing the reference count for the pmc used to create the
 * reservation, and deallocating the reservation's memory.
 */
static void reservation_free(pmc_reservation_t resv) {
        /* Free config */
        if(resv->config) {
                assert(resv->pmc);

                pmc_free_config(resv->pmc, resv->config);

                resv->config = NULL;
        }

        /* release PMC */
        (void)pmc_internal_reservation_set_pmc(resv, NULL);

        /* Free reservation */
        zfree(perf_small_zone, resv);
}

/*
 * reservation_init initializes a newly created reservation.
 */
static void reservation_init(pmc_reservation_t resv) {
        assert(resv);

        resv->pmc = NULL;
        resv->config = NULL;
        resv->value = 0ULL;

        resv->flags = 0U;
        resv->state = PMC_STATE(PMC_STATE_STATE_STOP, 0, 0);
        resv->active_last_context_in = 0U;

        /*
         * Since this member is a union, we only need to set either the task 
         * or thread to NULL.
         */
        resv->task = TASK_NULL;
}

/*
 * pmc_internal_reservation_set_pmc sets the pmc associated with the reservation object. If
 * there was one set already, it is deallocated (reference is dropped) before
 * the new one is set.  This methods increases the reference count of the given
 * pmc_t.
 *
 * NOTE: It is okay to pass NULL as the pmc_t - this will have the effect of
 * dropping the reference on any previously set pmc, and setting the reservation
 * to having no pmc set.
 */
static kern_return_t pmc_internal_reservation_set_pmc(pmc_reservation_t resv, pmc_t pmc) {
        assert(resv);

        if(resv->pmc) {
                (void)pmc_close(resv->pmc);
                pmc_deallocate(resv->pmc);
                resv->pmc = NULL;
        }

        resv->pmc = pmc;

        if(resv->pmc) {
                pmc_reference(resv->pmc);
                if(KERN_SUCCESS != pmc_open(resv->pmc)) {
                        pmc_deallocate(resv->pmc);
                        resv->pmc = NULL;

                        return KERN_FAILURE;
                }
        }

        return KERN_SUCCESS;
}

/* 
 * Used to place reservation into one of the system, task, and thread queues
 * Assumes the queue's spin lock is already held.
 */
static void pmc_internal_reservation_enqueue(queue_t queue, pmc_reservation_t resv) {
        assert(queue);
        assert(resv);

        queue_enter(queue, resv, pmc_reservation_t, link);
}

static void pmc_internal_reservation_dequeue(queue_t queue, pmc_reservation_t resv) {
        assert(queue);
        assert(resv);

        queue_remove(queue, resv, pmc_reservation_t, link);
}

/* Returns TRUE if the reservation applies to the current execution context */
static boolean_t pmc_internal_reservation_matches_context(pmc_reservation_t resv) {
        boolean_t ret = FALSE;
        assert(resv);

        if(PMC_FLAG_IS_SYSTEM_SCOPE(resv->flags)) {
                ret = TRUE;
        } else if(PMC_FLAG_IS_TASK_SCOPE(resv->flags)) {
                if(current_task() == resv->task) {
                        ret = TRUE;
                }
        } else if(PMC_FLAG_IS_THREAD_SCOPE(resv->flags)) {
                if(current_thread() == resv->thread) {
                        ret = TRUE;
                }
        }

        return ret;
}

/*
 * pmc_accessible_core_count returns the number of logical cores that can access
 * a given @pmc.  0 means every core in the system.
 */
static uint32_t pmc_accessible_core_count(pmc_t pmc) {
        assert(pmc);

        uint32_t *cores = NULL;
        size_t coreCt = 0UL;

        if(KERN_SUCCESS != pmc->methods.accessible_cores(pmc->object,
                &cores, &coreCt)) {
                coreCt = 0U;
        }

        return (uint32_t)coreCt;
}

/* spin lock for the queue must already be held */
/*
 * This method will inspect the task/thread of the reservation to see if it
 * matches the new incoming one (for thread/task reservations only).  Will only
 * return TRUE if the task/thread matches.
 */
static boolean_t pmc_internal_reservation_queue_contains_pmc(queue_t queue, pmc_reservation_t resv) {
        assert(queue);
        assert(resv);

        boolean_t ret = FALSE;
        pmc_reservation_t tmp = NULL;

        queue_iterate(queue, tmp, pmc_reservation_t, link) {
                if(tmp->pmc == resv->pmc) {
                        /* PMC matches - make sure scope matches first */
                        switch(PMC_FLAG_SCOPE(tmp->flags)) {
                                case PMC_FLAG_SCOPE_SYSTEM:
                                        /*
                                         * Found a reservation in system queue with same pmc - always a
                                         * conflict.
                                         */
                                        ret = TRUE;
                                        break;
                                case PMC_FLAG_SCOPE_THREAD:
                                        /*
                                         * Found one in thread queue with the same PMC as the
                                         * argument. Only a conflict if argument scope isn't
                                         * thread or system, or the threads match.
                                         */
                                        ret = (PMC_FLAG_SCOPE(resv->flags) != PMC_FLAG_SCOPE_THREAD) || 
                                                (tmp->thread == resv->thread);

                                        if(!ret) {
                                                /*
                                                 * so far, no conflict - check that the pmc that is
                                                 * being reserved isn't accessible from more than
                                                 * one core, if it is, we need to say it's already
                                                 * taken.
                                                 */
                                                if(1 != pmc_accessible_core_count(tmp->pmc)) {
                                                        ret = TRUE;
                                                }
                                        }
                                        break;
                                case PMC_FLAG_SCOPE_TASK:
                                        /* 
                                         * Follow similar semantics for task scope.
                                         */

                                        ret = (PMC_FLAG_SCOPE(resv->flags) != PMC_FLAG_SCOPE_TASK) ||
                                                (tmp->task == resv->task);
                                        if(!ret) {
                                                /*
                                                 * so far, no conflict - check that the pmc that is
                                                 * being reserved isn't accessible from more than
                                                 * one core, if it is, we need to say it's already
                                                 * taken.
                                                 */
                                                if(1 != pmc_accessible_core_count(tmp->pmc)) {
                                                        ret = TRUE;
                                                }
                                        }

                                        break;
                        }

                        if(ret) break;
                }
        }

        return ret;
}

/*
 * pmc_internal_reservation_validate_for_pmc returns TRUE if the given reservation can be 
 * added to its target queue without creating conflicts (target queue is 
 * determined by the reservation's scope flags). Further, this method returns
 * FALSE if any level contains a reservation for a PMC that can be accessed from
 * more than just 1 core, and the given reservation also wants the same PMC.
 */
static boolean_t pmc_internal_reservation_validate_for_pmc(pmc_reservation_t resv) {
        assert(resv);
        boolean_t ret = TRUE;

        if(pmc_internal_reservation_queue_contains_pmc(system_reservations, resv) ||
                pmc_internal_reservation_queue_contains_pmc(task_reservations, resv) ||
                pmc_internal_reservation_queue_contains_pmc(thread_reservations, resv)) {
                ret = FALSE;
        }

        return ret;
}

static void pmc_internal_update_thread_flag(thread_t thread, boolean_t newFlag) {
        assert(thread);

        /* See if this thread needs it's PMC flag set */
        pmc_reservation_t tmp = NULL;

        if(!newFlag) {
                /*
                 * If the parent task just dropped its reservation, iterate the thread
                 * reservations to see if we need to keep the pmc flag set for the given
                 * thread or not.
                 */
                lck_spin_lock(&reservations_spin);
        
                queue_iterate(thread_reservations, tmp, pmc_reservation_t, link) {
                        if(tmp->thread == thread) {
                                newFlag = TRUE;
                                break;
                        }
                }

                lck_spin_unlock(&reservations_spin);
        }

        if(newFlag) {
                OSBitOrAtomic(THREAD_PMC_FLAG, &thread->t_chud);
        } else {
                OSBitAndAtomic(~(THREAD_PMC_FLAG), &thread->t_chud);
        }
}

/* 
 * This operation is (worst case) O(N*M) where N is number of threads in the
 * given task, and M is the number of thread reservations in our system.
 */
static void pmc_internal_update_task_flag(task_t task, boolean_t newFlag) {
        assert(task);
        thread_t thread = NULL;

        if(newFlag) {
                OSBitOrAtomic(TASK_PMC_FLAG, &task->t_chud);
        } else {
                OSBitAndAtomic(~(TASK_PMC_FLAG), &task->t_chud);
        }

        task_lock(task);

        queue_iterate(&task->threads, thread, thread_t, task_threads) {
                /* propagate the task's mask down to each thread  */
                pmc_internal_update_thread_flag(thread, newFlag);
        }

        task_unlock(task);
}

/*
 * pmc_internal_reservation_add adds a reservation to the global tracking queues after
 * ensuring there are no reservation conflicts.  To do this, it takes all the
 * spin locks for all the queue (to ensure no other core goes and adds a
 * reservation for the same pmc to a queue that has already been checked).
 */
static boolean_t pmc_internal_reservation_add(pmc_reservation_t resv) {
        assert(resv);

        boolean_t ret = FALSE;

        /* always lock all three in the same order */
        lck_spin_lock(&reservations_spin);

        /* Check if the reservation can be added without conflicts */
        if(pmc_internal_reservation_validate_for_pmc(resv)) {
            
                /* add reservation to appropriate scope */
                switch(PMC_FLAG_SCOPE(resv->flags)) {
                case PMC_FLAG_SCOPE_SYSTEM:
                        /* Simply add it to the system queue */
                        pmc_internal_reservation_enqueue(system_reservations, resv);
                        system_reservation_count++;
                        
                        lck_spin_unlock(&reservations_spin);

                        break;

                case PMC_FLAG_SCOPE_TASK:
                        assert(resv->task);

                        /* Not only do we enqueue it in our local queue for tracking */
                        pmc_internal_reservation_enqueue(task_reservations, resv);
                        task_reservation_count++;

                        lck_spin_unlock(&reservations_spin);

                        /* update the task mask, and propagate it to existing threads */
                        pmc_internal_update_task_flag(resv->task, TRUE);
                        break;

                /* Thread-switched counter */
                case PMC_FLAG_SCOPE_THREAD:
                        assert(resv->thread);

                        /*
                         * Works the same as a task-switched counter, only at
                         * thread-scope
                         */

                        pmc_internal_reservation_enqueue(thread_reservations, resv);
                        thread_reservation_count++;

                        lck_spin_unlock(&reservations_spin);
                        
                        pmc_internal_update_thread_flag(resv->thread, TRUE);
                        break;
                }
                
                ret = TRUE;
        } else {
                lck_spin_unlock(&reservations_spin);
        }                       
        
        return ret;
}

static void pmc_internal_reservation_broadcast(pmc_reservation_t reservation, void (*action_func)(void *)) {
        uint32_t * cores;
        size_t core_cnt;
        
        /* Get the list of accessible cores */
        if (KERN_SUCCESS == pmc_get_accessible_core_list(reservation->pmc, &cores, &core_cnt)) {
                boolean_t intrs_enabled = ml_set_interrupts_enabled(FALSE);

                /* Fast case: the PMC is only accessible from one core and we happen to be on it */
                if (core_cnt == 1 && cores[0] == (uint32_t)cpu_number()) {
                        action_func(reservation);
                } else {
                        /* Call action_func on every accessible core */
#if defined(__i386__) || defined(__x86_64__)
                        size_t ii;
                        cpumask_t mask = 0;
                        
                        /* Build a mask for the accessible cores */
                        if (core_cnt > 0) {
                                for (ii = 0; ii < core_cnt; ii++) {
                                        mask |= cpu_to_cpumask(cores[ii]);
                                }
                        } else {
                                /* core_cnt = 0 really means all cpus */
                                mask = CPUMASK_ALL;
                        }
                        mp_cpus_call(mask, ASYNC, action_func, reservation);
#else
#error pmc_reservation_interrupt needs an inter-processor method invocation mechanism for this architecture
#endif
                }

                ml_set_interrupts_enabled(intrs_enabled);
        }
        
}

/*
 * pmc_internal_reservation_remove removes the given reservation from the appropriate
 * reservation queue according to its scope. 
 *
 * NOTE: The scope flag must have been set for this method to function.
 */
static void pmc_internal_reservation_remove(pmc_reservation_t resv) {
        assert(resv);

        /*
         * Due to the way the macros are written, we can't just blindly queue-remove
         * the reservation without knowing which queue it's in. We figure this out
         * using the reservation's scope flags.
         */

        /* Lock the global spin lock */
        lck_spin_lock(&reservations_spin);

        switch(PMC_FLAG_SCOPE(resv->flags)) {

                case PMC_FLAG_SCOPE_SYSTEM:
                        pmc_internal_reservation_dequeue(system_reservations, resv);
                        system_reservation_count--;
                        
                        lck_spin_unlock(&reservations_spin);
                        
                        break;

                case PMC_FLAG_SCOPE_TASK:
                        /* remove from the global queue */
                        pmc_internal_reservation_dequeue(task_reservations, resv);
                        task_reservation_count--;

                        /* unlock the global */
                        lck_spin_unlock(&reservations_spin);

                        /* Recalculate task's counter mask */
                        pmc_internal_update_task_flag(resv->task, FALSE);
                        
                        break;

                case PMC_FLAG_SCOPE_THREAD:
                        pmc_internal_reservation_dequeue(thread_reservations, resv);
                        thread_reservation_count--;

                        lck_spin_unlock(&reservations_spin);

                        /* recalculate the thread's counter mask */
                        pmc_internal_update_thread_flag(resv->thread, FALSE);

                        break;
        }
}

/* Reservation State Machine
 *
 * The PMC subsystem uses a 3-tuple of state information packed into a 32-bit quantity and a 
 * set of 9 events to provide MP-safe bookkeeping and control flow.  The 3-tuple is comprised 
 * of a state, a count of active contexts, and a set of modifier flags.  A state machine defines
 * the possible transitions at each event point given the current 3-tuple.  Atomicity is handled
 * by reading the current 3-tuple, applying the transformations indicated by the state machine
 * and then attempting to OSCompareAndSwap the transformed value.  If the OSCompareAndSwap fails,
 * the process is repeated until either the OSCompareAndSwap succeeds or not valid transitions are
 * available.
 *
 * The state machine is described using tuple notation for the current state and a related notation
 * for describing the transformations.  For concisness, the flag and state names are abbreviated as
 * follows:
 * 
 * states:
 * S = STOP
 * CR = CAN_RUN
 * L = LOAD
 * R = RUN
 * ST = STORE
 * I = INTERRUPT
 * D = DEALLOC
 *
 * flags:
 *
 * S = STOPPING
 * D = DEALLOCING
 * I = INTERRUPTING
 *
 * The tuple notation is formed from the following pattern:
 *
 * tuple = < state, active-context-count, flags >
 * state = S | CR | L | R | ST | I | D
 * active-context-count = 0 | >0 | 1 | >1
 * flags = flags flag | blank
 * flag = S | D | I
 *
 * The transform notation is similar, but only describes the modifications made to the current state.
 * The notation is formed from the following pattern:
 * 
 * transform = < state, active-context-count, flags >
 * state = S | CR | L | R | ST | I | D
 * active-context-count = + | - | blank
 * flags = flags flag | flags !flag | blank
 * flag = S | D | I
 *
 * And now for the state machine:
 * State                Start           Stop            Free            Interrupt               End Interrupt           Context In              Context Out     Load Finished           Store Finished
 * <CR, 0, >                            <S, , >         <D, , >                 <L, +, >
 * <D, 0, >
 * <D, 1, D>                                                                    < , -, !D>
 * <D, >1, D>                                                                   < , -, >
 * <I, 0, D>                                                                    <D, , !D>
 * <I, 0, S>    < , , !S>                               < , , !SD>              <S, , !S>
 * <I, 0, >                                     < , , S>        < , , D>        <CR, , >
 * <L, 1, D>                                                                    <ST, -, >
 * <L, 1, ID>                                                                   <ST, -, >
 * <L, 1, IS>                                                   < , , !SD>      <ST, -, >
 * <L, 1, S>    < , , !S>                               < , , !SD>              <ST, -, >
 * <L, 1, >                                     < , , S>        < , , D>        < , , IS>                                                       < , +, >        <R, , >
 * <L, >1, D>                                                                   < , -, >                <R, -, >
 * <L, >1, ID>                                                                  < , -, >                <R, -, >
 * <L, >1, IS>                                                  < , , !SD>      < , -, >                <R, -, >
 * <L, >1, S>   < , , !S>                               < , , !SD>              < , -, >                <R, -, >
 * <L, >1, >                            < , , S>        < , , D>        < , , IS>                                                       < , +, >                < , -, >                <R, , >
 * <R, 1, D>                                                                    <ST, -, >
 * <R, 1, ID>                                                                   <ST, -, >
 * <R, 1, IS>                                                   < , , !SD>      <ST, -, >
 * <R, 1, S>    < , , !S>                               < , , !SD>              <ST, -, >
 * <R, 1, >                                     < , , S>        < , , D>        < , , IS>                                                       < , +, >        <ST, -, >
 * <R, >1, D>                                                                   < , -, >
 * <R, >1, ID>                                                                  < , -, >
 * <R, >1, IS>                                                  < , , !SD>      < , -, >
 * <R, >1, S>   < , , !S>                               < , , !SD>              < , -, >
 * <R, >1, >                            < , , S>        < , , D>        < , , IS>                                                       < , +, >                < , -, >
 * <S, 0, >             <CR, , >                                <D, , >
 * <S, 1, ID>                                                                   <I, -, !I>
 * <S, 1, IS>                                                   < , , !SD>      <I, -, !I>
 * <S, 1, S>    < , , !S>                               <D, , !SD>              < , -, !S>
 * <S, 1, >                                     < , , S>        <D, , D>        <L, +, >                <CR, -, >
 * <S, >1, ID>                                                                  < , -, >
 * <S, >1, IS>                                                  < , , !SD>      < , -, >
 * <S, >1, S>   < , , !S>                               <D, , !SD>              < , -, >
 * <S, >1, >                            < , , S>        <D, , D>                <L, +, >                < , -, >
 * <ST, 0, D>                                                                   <D, , !D>
 * <ST, 0, ID>                                                                  <I, , !I>
 * <ST, 0, IS>                                                  < , , !SD>      <I, , !I>
 * <ST, 0, S>   < , , !S>                               < , , !SD>              <S, , !S>
 * <ST, 0, >                            < , , S>        < , , D>        < , , IS>                                                       < , +, >                <CR, , >
 * <ST, >0, D>                                                                  < , -, >                                                        <D, , >
 * <ST, >0, ID>                                                         < , -, >                                                        <S, , >
 * <ST, >0, IS>                                                 < , , !SD>                                                                              < , -, >                        <S, , >
 * <ST, >0, S>  < , , !S>                               < , , !SD>              < , -, >                                                        <S, , >
 * <ST, >0, >                           < , , S>        < , , D>        < , , IS>                                                       < , +, >                < , -, >                        <L, , >
 */

static uint32_t pmc_internal_reservation_next_state(uint32_t current_state, pmc_state_event_t event) {
        uint32_t new_state = PMC_STATE(PMC_STATE_STATE_INVALID, 0, 0);
        
        switch (event) {
                case PMC_STATE_EVENT_START:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_STOPPING):
                                        new_state = PMC_STATE_MODIFY(current_state, 0, 0, PMC_STATE_FLAGS_STOPPING);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_CAN_RUN, 0, 0, 0);
                                        }
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_STOP:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_CAN_RUN, 0, 0):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STOP, 0, 0, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        new_state = PMC_STATE_MODIFY(current_state, 0, PMC_STATE_FLAGS_STOPPING, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 0) {
                                                new_state = PMC_STATE_MODIFY(current_state, 0, PMC_STATE_FLAGS_STOPPING, 0);
                                        }
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_FREE:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_CAN_RUN, 0, 0):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, 0, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_STOPPING):
                                        new_state = PMC_STATE_MODIFY(current_state, 0, PMC_STATE_FLAGS_DEALLOCING, PMC_STATE_FLAGS_STOPPING);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        new_state = PMC_STATE_MODIFY(current_state, 0, PMC_STATE_FLAGS_DEALLOCING, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_STOPPING):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, PMC_STATE_FLAGS_DEALLOCING, PMC_STATE_FLAGS_STOPPING);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, PMC_STATE_FLAGS_DEALLOCING, 0);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, 0, 0);
                                        }
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_INTERRUPT:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        new_state = PMC_STATE_MODIFY(current_state, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING, 0);
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_END_OF_INTERRUPT:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, PMC_STATE_FLAGS_DEALLOCING):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, 0, PMC_STATE_FLAGS_DEALLOCING);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, PMC_STATE_FLAGS_STOPPING):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STOP, 0, 0, PMC_STATE_FLAGS_STOPPING);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_INTERRUPT, 0, 0):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_CAN_RUN, 0, 0, 0);
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_CONTEXT_IN:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_CAN_RUN, 0, 0):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_LOAD, 1, 0, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, 0):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        new_state = PMC_STATE_MODIFY(current_state, 1, 0, 0);
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_LOAD, 1, 0, 0);
                                        }
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_CONTEXT_OUT:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_DEALLOC, 0, PMC_STATE_FLAGS_DEALLOCING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 1) {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, PMC_STATE_FLAGS_DEALLOCING);
                                        } else {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }                                       
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 1) {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_RUN, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 1) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STORE, -1, 0, 0);
                                        } else {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 1) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_INTERRUPT, -1, 0, PMC_STATE_FLAGS_INTERRUPTING);
                                        } else {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, PMC_STATE_FLAGS_STOPPING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 1) {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, PMC_STATE_FLAGS_STOPPING);
                                        } else {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STOP, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 0) {
                                                if (PMC_STATE_CONTEXT_COUNT(current_state) == 1) {
                                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_CAN_RUN, -1, 0, 0);
                                                } else {
                                                        new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                                }
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 0) {
                                                new_state = PMC_STATE_MODIFY(current_state, -1, 0, 0);
                                        }
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_LOAD_FINISHED:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, PMC_STATE_FLAGS_STOPPING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) > 1) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_RUN, -1, 0, 0);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STORE, -1, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_LOAD, 0, 0):
                                        new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_RUN, 0, 0, 0);
                                        break;
                        }
                        break;
                case PMC_STATE_EVENT_STORE_FINISHED:
                        switch (current_state & ~(PMC_STATE_CONTEXT_COUNT_MASK)) {
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_DEALLOCING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, 0, PMC_STATE_FLAGS_DEALLOCING);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_DEALLOC, 0, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_DEALLOCING):
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_INTERRUPTING | PMC_STATE_FLAGS_STOPPING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_INTERRUPT, 0, 0, PMC_STATE_FLAGS_INTERRUPTING);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STOP, 0, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, PMC_STATE_FLAGS_STOPPING):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STOP, 0, 0, PMC_STATE_FLAGS_STOPPING);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_STOP, 0, 0, 0);
                                        }
                                        break;
                                case PMC_STATE(PMC_STATE_STATE_STORE, 0, 0):
                                        if (PMC_STATE_CONTEXT_COUNT(current_state) == 0) {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_CAN_RUN, 0, 0, 0);
                                        } else {
                                                new_state = PMC_STATE_MOVE(current_state, PMC_STATE_STATE_LOAD, 0, 0, 0);
                                        }
                                        break;
                        }
                        break;
        }
        
        return new_state;
}

static uint32_t pmc_internal_reservation_move_for_event(pmc_reservation_t reservation, pmc_state_event_t event, pmc_state_t *old_state_out) {
        pmc_state_t oldState;
        pmc_state_t newState;

        assert(reservation);
        
        /* Determine what state change, if any, we need to do.  Keep trying until either we succeed doing a transition
         * or the there is no valid move.
         */     
        do {
                oldState = reservation->state;
                newState = pmc_internal_reservation_next_state(oldState, event);
        } while (newState != PMC_STATE_INVALID && !OSCompareAndSwap(oldState, newState, &(reservation->state)));
        
        if (newState != PMC_STATE_INVALID) {
                COUNTER_DEBUG("Moved reservation %p from state "PMC_STATE_FORMAT" to state "PMC_STATE_FORMAT" for event %s\n", reservation, PMC_STATE_ARGS(oldState), PMC_STATE_ARGS(newState), pmc_state_event_name(event));
        } else {
                COUNTER_DEBUG("No valid moves for reservation %p in state "PMC_STATE_FORMAT" for event %s\n", reservation, PMC_STATE_ARGS(oldState), pmc_state_event_name(event));
        }
        
        if (old_state_out != NULL) {
                *old_state_out = oldState;
        }
        
        return newState;
}
                                        
static void pmc_internal_reservation_context_out(pmc_reservation_t reservation) {
        assert(reservation);
        pmc_state_t newState;
        pmc_state_t oldState;

        /* Clear that the this reservation was active when this cpu did its last context in */
        OSBitAndAtomic(~(1U << cpu_number()), &(reservation->active_last_context_in));
        
        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_CONTEXT_OUT, &oldState))) {
                return;
        }
        
        /* Do any actions required based on the state change */
        if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_STORE && PMC_STATE_STATE(oldState) != PMC_STATE_STATE_STORE) {
                /* Just moved into STORE, so store the reservation. */
                pmc_internal_reservation_store(reservation);
        } else if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_DEALLOC && PMC_STATE_CONTEXT_COUNT(newState) == 0 && PMC_STATE_FLAGS(newState) == 0) {
                /* Wakeup any thread blocking for this reservation to hit <DEALLOC, 0, > */
                thread_wakeup((event_t)reservation);
        }
        
}

static void pmc_internal_reservation_context_in(pmc_reservation_t reservation) {
        assert(reservation);
        pmc_state_t oldState;
        pmc_state_t newState;
        
        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_CONTEXT_IN, &oldState))) {
                return;
        }

        /* Mark that the reservation was active when this cpu did its last context in */
        OSBitOrAtomic(1U << cpu_number(), &(reservation->active_last_context_in));
                
        /* Do any actions required based on the state change */
        if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_LOAD && PMC_STATE_STATE(oldState) != PMC_STATE_STATE_LOAD) {
                /* Just moved into LOAD, so load the reservation. */
                pmc_internal_reservation_load(reservation);
        }
        
}

static void pmc_internal_reservation_store(pmc_reservation_t reservation) {
        assert(reservation);
        assert(PMC_STATE_STATE(reservation->state) == PMC_STATE_STATE_STORE);
        
        assert(reservation->pmc);
        assert(reservation->config);

        pmc_state_t newState;
        kern_return_t ret = KERN_SUCCESS;
        
        pmc_t store_pmc = reservation->pmc;
        pmc_object_t store_pmc_obj = store_pmc->object;
        perf_monitor_t store_pm = store_pmc->monitor;

        /* 
         * Instruct the Perf Monitor that contains this counter to turn 
         * off the global disable for this counter.
         */
        ret = store_pm->methods.disable_counters(store_pm->object, &store_pmc_obj, 1);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG(" [error] disable_counters: 0x%x\n", ret);
                return;
        }

        /* Instruct the counter to disable itself */
        ret = store_pmc->methods.disable(store_pmc_obj);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] disable: 0x%x\n", ret);
        }

        /* store the counter value into the reservation's stored count */
        ret = store_pmc->methods.get_count(store_pmc_obj, &reservation->value);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] get_count: 0x%x\n", ret);
                return;
        }
                
        /* Advance the state machine now that the STORE is finished */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_STORE_FINISHED, NULL))) {
                return;
        }

        /* Do any actions required based on the state change */
        if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_LOAD) {
                /* Just moved into LOAD, so load the reservation. */
                pmc_internal_reservation_load(reservation);
        } else if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_DEALLOC && PMC_STATE_CONTEXT_COUNT(newState) == 0 && PMC_STATE_FLAGS(newState) == 0) {
                /* Wakeup any thread blocking for this reservation to hit <DEALLOC, 0, > */
                thread_wakeup((event_t)reservation);
        }
        
}

static void pmc_internal_reservation_load(pmc_reservation_t reservation) {
        assert(reservation);
        assert(PMC_STATE_STATE(reservation->state) == PMC_STATE_STATE_LOAD);

        pmc_state_t newState;
        kern_return_t ret = KERN_SUCCESS;

        assert(reservation->pmc);
        assert(reservation->config);
        
        pmc_t load_pmc = reservation->pmc;
        pmc_object_t load_pmc_obj = load_pmc->object;
        perf_monitor_t load_pm = load_pmc->monitor;

        /* Set the control register up with the stored configuration */
        ret = load_pmc->methods.set_config(load_pmc_obj, reservation->config->object);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] set_config: 0x%x\n", ret);
                return;
        }

        /* load the counter value */
        ret = load_pmc->methods.set_count(load_pmc_obj, reservation->value);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] set_count: 0x%x\n", ret);
                return;
        }

        /* Locally enable the counter */
        ret = load_pmc->methods.enable(load_pmc_obj);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] enable: 0x%x\n", ret);
                return;
        }

        /*
         * Instruct the Perf Monitor containing the pmc to enable the
         * counter.
         */
        ret = load_pm->methods.enable_counters(load_pm->object, &load_pmc_obj, 1);
        if(KERN_SUCCESS != ret) {
                COUNTER_DEBUG("  [error] enable_counters: 0x%x\n", ret);
                /* not on the hardware. */
                return;
        }
        
        /* Advance the state machine now that the STORE is finished */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_LOAD_FINISHED, NULL))) {
                return;
        }

        /* Do any actions required based on the state change */
        if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_STORE) {
                /* Just moved into STORE, so store the reservation. */
                pmc_internal_reservation_store(reservation);
        }
        
}

/*
 * pmc_accessible_from_core will return TRUE if the given @pmc is directly
 * (e.g., hardware) readable from the given logical core.
 *
 * NOTE: This method is interrupt safe.
 */
static inline boolean_t pmc_accessible_from_core(pmc_t pmc, uint32_t logicalCore) {
        boolean_t ret = FALSE;

        assert(pmc);

        ret = pmc->methods.accessible_from_core(pmc->object, logicalCore);

        return ret;
}

static void pmc_internal_reservation_start_cpu(void * arg) {
        pmc_reservation_t reservation = (pmc_reservation_t)arg;
        
        assert(reservation);
        

        if (pmc_internal_reservation_matches_context(reservation)) {
                /* We are in context, but the reservation may have already had the context_in method run.  Attempt
                 * to set this cpu's bit in the active_last_context_in mask.  If we set it, call context_in.
                 */
                uint32_t oldMask = OSBitOrAtomic(1U << cpu_number(), &(reservation->active_last_context_in));
                
                if ((oldMask & (1U << cpu_number())) == 0) {
                        COUNTER_DEBUG("Starting already in-context reservation %p for cpu %d\n", reservation, cpu_number());
                        
                        pmc_internal_reservation_context_in(reservation);
                }
        }
}

static void pmc_internal_reservation_stop_cpu(void * arg) {
        pmc_reservation_t reservation = (pmc_reservation_t)arg;
        
        assert(reservation);
        
        
        if (pmc_internal_reservation_matches_context(reservation)) {
                COUNTER_DEBUG("Stopping in-context reservation %p for cpu %d\n", reservation, cpu_number());

                pmc_internal_reservation_context_out(reservation);
        }
}       

/*!fn
 * pmc_reservation_interrupt is called when a PMC reservation which was setup
 * with an interrupt threshold counts the requested number of events. When the
 * underlying counter hits the threshold, an interrupt is generated, and this
 * method is called. This method marks the reservation as stopped, and passes
 * control off to the user-registered callback method, along with the
 * reservation (so that the user can, for example, write a 0 to the counter, and
 * restart the reservation).
 * This method assumes the reservation has a valid pmc_config_t within.
 *
 * @param target The pmc_reservation_t that caused the interrupt.
 * @param refCon User specified reference constant.
 */
static void pmc_reservation_interrupt(void *target, void *refCon) {
        pmc_reservation_t reservation = (pmc_reservation_t)target;
        pmc_state_t newState;
        uint64_t timeout;
        uint32_t spins;

        assert(reservation);

        /* Move the state machine */
        if (PMC_STATE_INVALID == pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_INTERRUPT, NULL)) {
                return;
        }

        /* A valid state move has been made, but won't be picked up until a context switch occurs.  To cause matching
         * contexts that are currently running to update, we do an inter-processor message to run pmc_internal_reservation_stop_cpu
         * on every cpu that can access the PMC.
         */
        pmc_internal_reservation_broadcast(reservation, pmc_internal_reservation_stop_cpu);
                        
        /* Spin waiting for the state to turn to INTERRUPT */
        nanoseconds_to_absolutetime(PMC_SPIN_TIMEOUT_US * 1000, &timeout);
        timeout += mach_absolute_time();
        spins = 0;
        while (PMC_STATE_STATE(reservation->state) != PMC_STATE_STATE_INTERRUPT) {
                /* Assert if this takes longer than PMC_SPIN_TIMEOUT_US */
                if (++spins > PMC_SPIN_THRESHOLD) {
                        if (mach_absolute_time() > timeout) {
                                pmc_spin_timeout_count++;
                                assert(0);
                        }
                }

                cpu_pause();
        }
                        
        assert(reservation->config);
        assert(reservation->config->method);                    
                
        /* Call the registered callback handler */
#if DEBUG_COUNTERS
        uint64_t start = mach_absolute_time();
#endif /* DEBUG */
        
        (void)reservation->config->method(reservation, refCon);
        
#if DEBUG_COUNTERS
        uint64_t end = mach_absolute_time();
        if((end - start) > 5000ULL) {
                kprintf("%s - user method %p took %llu ns\n", __FUNCTION__, 
                                reservation->config->method, (end - start));
        }
#endif
        
        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_END_OF_INTERRUPT, NULL))) {
                return;
        }
        
        /* Do any post-move actions necessary */
        if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_CAN_RUN) {
                pmc_internal_reservation_broadcast(reservation, pmc_internal_reservation_start_cpu);
        } else if (PMC_STATE_STATE(newState) == PMC_STATE_STATE_DEALLOC && PMC_STATE_CONTEXT_COUNT(newState) == 0 && PMC_STATE_FLAGS(newState) == 0) {
                /* Wakeup any thread blocking for this reservation to hit <DEALLOC, 0, > */
                thread_wakeup((event_t)reservation);
        }
}       

/*
 * Apple-private KPI for Apple kext's (IOProfileFamily) only
 */

#if 0
#pragma mark -
#pragma mark IOProfileFamily private KPI
#endif

/*
 * perf_monitor_register registers a new Performance Monitor, and its associated
 * callback methods.  The given perf_monitor_object_t is the first argument to
 * each callback when they are called.
 */
kern_return_t perf_monitor_register(perf_monitor_object_t monitor,
        perf_monitor_methods_t *methods) {
        int cpu = -1;

        COUNTER_DEBUG("registering perf monitor %p\n", monitor);

        if(!monitor || !methods) {
                return KERN_INVALID_ARGUMENT;
        }

        /* Protect against out-of-date driver kexts */
        if(MACH_PERFMON_METHODS_VERSION != methods->perf_monitor_methods_version) {
                return KERN_INVALID_ARGUMENT;
        }

        /* If the monitor requires idle notifications, ensure that it is 
         * accessible from a single core only.
         */
        if (methods->flags & PERFMON_FLAG_REQUIRES_IDLE_NOTIFICATIONS) {
                uint32_t *cores;
                size_t core_cnt;
            
                if (KERN_SUCCESS == methods->accessible_cores(monitor, &cores, &core_cnt)) {
                        /* 
                         * Guard against disabled cores - monitors will always match and
                         * attempt registration, irrespective of 'cpus=x' boot-arg.
                         */
                        if ((core_cnt == 1) && (cores[0] < (uint32_t)ml_get_max_cpus())) {
                                cpu = cores[0];
                        } else {
                                return KERN_INVALID_ARGUMENT;
                        }
                }           
        }

        /* All methods are required */
        if(!methods->accessible_cores |
           !methods->enable_counters || !methods->disable_counters ||
           !methods->on_idle || !methods->on_idle_exit) {
                return KERN_INVALID_ARGUMENT;
        }

        /* prevent dupes. */
        perf_monitor_t dupe = perf_monitor_find(monitor);
        if(dupe) {
                COUNTER_DEBUG("Duplicate registration for %p\n", monitor);
                perf_monitor_deallocate(dupe);
                return KERN_FAILURE;
        }

        perf_monitor_t pm = perf_monitor_alloc();
        if(!pm) {
                return KERN_RESOURCE_SHORTAGE;
        }

        /* initialize the object */
        perf_monitor_init(pm, cpu);

        /* copy in the registration info */
        pm->object = monitor;
        memcpy(&(pm->methods), methods, sizeof(perf_monitor_methods_t));

        /* place it in the tracking queues */
        perf_monitor_enqueue(pm);

        /* debug it */
        PRINT_PERF_MON(pm);

        return KERN_SUCCESS;
}

/*
 * perf_monitor_unregister unregisters a previously registered Perf Monitor,
 * looking it up by reference pointer (the same that was used in
 * perf_monitor_register()).
 */
kern_return_t perf_monitor_unregister(perf_monitor_object_t monitor) {
        kern_return_t ret = KERN_FAILURE;

        COUNTER_DEBUG("unregistering perf monitor %p\n", monitor);

        if(!monitor) {
                return KERN_INVALID_ARGUMENT;
        }

        perf_monitor_t pm = perf_monitor_find(monitor);
        if(pm) {
                /* Remove it from the queues. */
                perf_monitor_dequeue(pm);

                /* drop extra retain from find */
                perf_monitor_deallocate(pm);

                /* and release the object */
                perf_monitor_deallocate(pm);

                ret = KERN_SUCCESS;
        } else {
                COUNTER_DEBUG("could not find a registered pm that matches!\n");
        }

        return ret;
}

/*
 * pmc_register registers a new PMC for use with the pmc subsystem. Each PMC is
 * associated with a Perf Monitor.  Perf Monitors are looked up by the reference
 * pointer that was used to previously register them. 
 *
 * PMCs are registered with a reference pointer (@pmc_object), and a set of
 * callback methods.  When the given callback methods are called from xnu, the
 * first argument will always be the reference pointer used to register the PMC.
 *
 * NOTE: @monitor must have been successfully registered via
 * perf_monitor_register before this method will succeed.
 */
kern_return_t pmc_register(perf_monitor_object_t monitor, pmc_object_t pmc_object,
        pmc_methods_t *methods, void *object) {

        COUNTER_DEBUG("%p %p\n", monitor, pmc_object);

        if(!monitor || !pmc_object || !methods || !object) {
                return KERN_INVALID_ARGUMENT;
        }

        /* Prevent version mismatches */
        if(MACH_PMC_METHODS_VERSION != methods->pmc_methods_version) {
                COUNTER_DEBUG("version mismatch\n");
                return KERN_INVALID_ARGUMENT;
        }

        /* All methods are required. */
        if(!methods->create_config || 
                !methods->free_config ||
                !methods->config_set_value || 
                !methods->config_set_threshold || 
                !methods->config_set_handler ||
                !methods->set_config || 
                !methods->get_monitor || 
                !methods->get_name ||
                !methods->accessible_from_core || 
                !methods->accessible_cores ||
                !methods->get_count || 
                !methods->set_count ||
                !methods->disable ||
                !methods->enable ||
                !methods->open || 
                !methods->close) {
                return KERN_INVALID_ARGUMENT;
        }

        /* make sure this perf monitor object is already registered */
        /*
         * NOTE: this adds a reference to the parent, so we'll have to drop it in
         * any failure code paths from here on out.
         */
        perf_monitor_t pm = perf_monitor_find(monitor);
        if(!pm) {
                COUNTER_DEBUG("Could not find perf monitor for %p\n", monitor);
                return KERN_INVALID_ARGUMENT;
        }

        /* make a new pmc */
        pmc_t pmc = pmc_alloc();
        if(!pmc) {
                /* drop the extra reference from perf_monitor_find() */
                perf_monitor_deallocate(pm);
                return KERN_RESOURCE_SHORTAGE;
        }

        /* init it */
        pmc_init(pmc);

        pmc->object = pmc_object;
        pmc->open_object = object;

        /* copy the callbacks in */
        memcpy(&(pmc->methods), methods, sizeof(pmc_methods_t));

        pmc->monitor = pm;

        perf_monitor_add_pmc(pmc->monitor, pmc);

        /* enqueue it in our tracking queue */
        pmc_enqueue(pmc);

        /* drop extra reference from perf_monitor_find() */
        perf_monitor_deallocate(pm);

        return KERN_SUCCESS;
}

/*
 * pmc_unregister unregisters a previously registered PMC, looking it up by
 * reference point to *both* the Perf Monitor it was created with, and the PMC's
 * reference pointer itself.
 */
kern_return_t pmc_unregister(perf_monitor_object_t monitor, pmc_object_t pmc_object) {
        COUNTER_DEBUG("%p %p\n", monitor, pmc_object);

        if(!monitor || !pmc_object) {
                return KERN_INVALID_ARGUMENT;
        }

        pmc_t pmc = pmc_find(pmc_object);
        if(!pmc) {
                COUNTER_DEBUG("Could not find a matching pmc.\n");
                return KERN_FAILURE;
        }

        /* remove it from the global queue */
        pmc_dequeue(pmc);

        perf_monitor_remove_pmc(pmc->monitor, pmc);

        /* remove extra reference count from pmc_find() */
        pmc_deallocate(pmc);

        /* dealloc the pmc */
        pmc_deallocate(pmc);

        return KERN_SUCCESS;
}

static void perf_monitor_reservation_add(perf_monitor_t monitor) {
    assert(monitor);
    OSIncrementAtomic(&(monitor->reservedCounters));
}

static void perf_monitor_reservation_remove(perf_monitor_t monitor) {
    assert(monitor);
    OSDecrementAtomic(&(monitor->reservedCounters));    
}

#if 0
#pragma mark -
#pragma mark KPI
#endif

/*
 * Begin in-kernel and in-kext KPI methods
 */

/*
 * pmc_create_config creates a new configuration area from a given @pmc.
 *
 * NOTE: This method is not interrupt safe.
 */
kern_return_t pmc_create_config(pmc_t pmc, pmc_config_t *config) {
        pmc_config_t tmp = NULL;

        if(!pmc || !config) {
                return KERN_INVALID_ARGUMENT;
        }

        pmc_reference(pmc);

        tmp = pmc_config_alloc(pmc);
        if(tmp) {
                tmp->object = pmc->methods.create_config(pmc->object);

                if(!tmp->object) {
                        pmc_config_free(pmc, tmp);
                        tmp = NULL;
                } else {
                        tmp->interrupt_after_value = 0ULL;
                        tmp->method = NULL;
                        tmp->refCon = NULL;
                }
        }

        pmc_deallocate(pmc);

        if(!tmp) {
                return KERN_RESOURCE_SHORTAGE;
        }

        *config = tmp;

        return KERN_SUCCESS;
}

/*
 * pmc_free_config frees a configuration area created from a given @pmc
 *
 * NOTE: This method is not interrupt safe.
 */
void pmc_free_config(pmc_t pmc, pmc_config_t config) {
        assert(pmc);
        assert(config);

        pmc_reference(pmc);

        pmc_config_free(pmc, config);

        pmc_deallocate(pmc);
}

/*
 * pmc_config_set_value sets up configuration area key-value pairs.  These pairs
 * are to be either pre-known, or looked up via CoreProfile.framework.
 *
 * NOTE: This method is not interrupt safe.
 */
kern_return_t pmc_config_set_value(pmc_t pmc, pmc_config_t config,
        uint8_t id, uint64_t value) {

        kern_return_t ret = KERN_INVALID_ARGUMENT;
        
        if(!pmc || !config) {
                return ret;
        }

        pmc_reference(pmc);

        ret = pmc->methods.config_set_value(config->object, id, value);

        pmc_deallocate(pmc);

        return ret;
}

/*
 * pmc_config_set_interrupt_threshold modifies a config object, instructing
 * the pmc that it should generate a call to the given pmc_interrupt_method_t
 * after the counter counts @threshold events.
 *
 * PMC Threshold handler methods will have the pmc_reservation_t that generated the interrupt
 * as the first argument when the interrupt handler is invoked, and the given
 * @refCon (which may be NULL) as the second.
 *
 * See pmc_interrupt_method_t.
 *
 * NOTE: This method is not interrupt safe.
 */
kern_return_t pmc_config_set_interrupt_threshold(pmc_t pmc, pmc_config_t config, 
        uint64_t threshold, pmc_interrupt_method_t method, void *refCon) {
        kern_return_t ret = KERN_INVALID_ARGUMENT;

        if(!config || !pmc) {
                return ret;
        }
        
        assert(config);
        assert(pmc);

        pmc_reference(pmc);

        do {
                /*
                 * We have a minor annoyance to side-step here. The driver layer expects
                 * the config to never change once a reservation has been taken out with
                 * it.  However, in order to have the PMI method have the reservation as
                 * the first argument (in order to allow the user-method to, for
                 * example, write a 0 to it, and restart it), we need to create the
                 * pmc_reservation_t before setting it up in the config object.
                 * We overcome this by caching the method in the pmc_config_t stand-in,
                 * and mutating the pmc_config_object_t just before returning a
                 * reservation (in pmc_reserve() and friends, below).
                 */

                /* might as well stash this away too. */
                config->interrupt_after_value = threshold;
                config->method = method;
                config->refCon = refCon;

                ret = KERN_SUCCESS;

        }while(0);

        pmc_deallocate(pmc);

        return ret;
}

/*
 * pmc_get_pmc_list returns an allocated list of pmc_t's, as well as the number
 * of pmc_t's returned. Callers should free this list with a call to
 * pmc_free_pmc_list().
 *
 * NOTE: This method is not interrupt safe.
 */
kern_return_t pmc_get_pmc_list(pmc_t **pmcs, size_t *pmcCount) {
        pmc_t *array = NULL;
        pmc_t pmc = NULL;
        size_t count = 0UL;
        
        do {
                /* Copy down (to the stack) the count of perf counters */
                vm_size_t size = perf_counters_count;

                /* Allocate that sized chunk */
                array = (pmc_t *)kalloc(sizeof(pmc_t) * size);
                if(!array) {
                        return KERN_RESOURCE_SHORTAGE;
                }

                /* Take the spin lock */
                lck_spin_lock(&perf_counters_queue_spin);

                /* verify the size didn't change while we were allocating */
                if(size != perf_counters_count) {
                        /*
                         * queue size has changed between alloc and now - go back and
                         * make another pass.
                         */

                        /* drop the lock */
                        lck_spin_unlock(&perf_counters_queue_spin);

                        /* free the block */
                        kfree(array, sizeof(pmc_t) * size);
                        array = NULL;
                }

                /* if we get here, and array is NULL, we try again. */
        }while(!array);

        /* copy the bits out */
        queue_iterate(perf_counters_queue, pmc, pmc_t, link) {
                /* copy out the pointer */
                array[count++] = pmc;
        }

        lck_spin_unlock(&perf_counters_queue_spin);

        /* return the list and the size */
        *pmcs = array;
        *pmcCount = count;

        return KERN_SUCCESS;
}

/*
 * pmc_free_pmc_list frees an array of pmc_t that has been returned from
 * pmc_get_pmc_list.
 * 
 * NOTE: This method is not interrupt safe.
 */
void pmc_free_pmc_list(pmc_t *pmcs, size_t pmcCount) {
        if(pmcs && pmcCount) {
                COUNTER_DEBUG("pmcs: %p pmcCount: %lu\n", pmcs, pmcCount);

                kfree(pmcs, pmcCount * sizeof(pmc_t));
        }
}

kern_return_t pmc_find_by_name(const char *name, pmc_t **pmcs, size_t *pmcCount) {
        kern_return_t ret = KERN_INVALID_ARGUMENT;

        if(!name || !pmcs || !pmcCount) {
                return ret;
        }

        pmc_t *list = NULL;
        size_t count = 0UL;

        if(KERN_SUCCESS == (ret = pmc_get_pmc_list(&list, &count))) {
                size_t matchCount = 0UL, ii = 0UL, swapPtr = 0UL;
                size_t len = strlen(name);

                for(ii = 0UL; ii < count; ii++) {
                        const char *pmcName = pmc_get_name(list[ii]);

                        if(strlen(pmcName) < len) {
                                /*
                                 * If the pmc name is shorter than the requested match, it's no 
                                 * match, as we're looking for the most specific match(es).
                                 */
                                continue;
                        }

                        if(0 == strncmp(name, pmcName, len)) {
                                pmc_t temp = list[ii];
                                
                                // move matches to the head of the array.
                                list[ii] = list[swapPtr];
                                list[swapPtr] = temp;
                                swapPtr++;

                                // keep a count of the matches
                                matchCount++;
                        }
                }

                if(matchCount) {
                        /*
                         * If we have matches, they are all at the head of the array, so
                         * just allocate enough space for @matchCount pmc_t's, and copy the
                         * head of the array to the new allocation.  Then free the old
                         * allocation.
                         */

                        pmc_t *result = (pmc_t *)kalloc(sizeof(pmc_t) * matchCount);
                        if(result) {
                                // copy the matches
                                memcpy(result, list, sizeof(pmc_t) * matchCount);

                                ret = KERN_SUCCESS;
                        }

                        pmc_free_pmc_list(list, count);

                        if(!result) {
                                *pmcs = NULL;
                                *pmcCount = 0UL;
                                return KERN_RESOURCE_SHORTAGE;
                        }

                        *pmcs = result;
                        *pmcCount = matchCount;
                } else {
                        *pmcs = NULL;
                        *pmcCount = 0UL;
                }
        }

        return ret;
}

/*
 * pmc_get_name returns a pointer (not copied) to the human-readable name of the
 * given pmc.
 *
 * NOTE: Driver authors must take care to not allocate during this method, as
 * this method *IS* interrupt safe.
 */
const char *pmc_get_name(pmc_t pmc) {
        assert(pmc);

        const char *name = pmc->methods.get_name(pmc->object);

        return name;
}

/*
 * pmc_get_accessible_core_list returns a pointer to an array of logical core
 * numbers (as well as the size of that array) that represent the local cores
 * (hardware threads) from which the given @pmc can be accessed directly.
 *
 * NOTE: This method is interrupt safe.
 */
kern_return_t pmc_get_accessible_core_list(pmc_t pmc, uint32_t **logicalCores,
        size_t *logicalCoreCt) {

        kern_return_t ret = KERN_INVALID_ARGUMENT;

        if(!pmc || !logicalCores || !logicalCoreCt) {
                return ret;
        }

        ret = pmc->methods.accessible_cores(pmc->object, logicalCores, logicalCoreCt);

        return ret;
}

static boolean_t pmc_reservation_setup_pmi(pmc_reservation_t resv, pmc_config_t config) {
        assert(resv);
        assert(resv->pmc);
        assert(config);
        assert(config->object);

        /* If there's no PMI to setup, return success */
        if(config->interrupt_after_value && config->method) {

                /* set the threshold */
                kern_return_t ret = resv->pmc->methods.config_set_threshold(config->object,
                        config->interrupt_after_value);

                if(KERN_SUCCESS != ret) {
                        /*
                         * This is the most useful error message here, as this only happens
                         * as a result of pmc_reserve*()
                         */
                        COUNTER_DEBUG("Failed to set threshold for pmc %p\n", resv->pmc);
                        return FALSE;
                }

                if(KERN_SUCCESS != resv->pmc->methods.config_set_handler(config->object, 
                        (void *)resv, &pmc_reservation_interrupt, config->refCon)) {

                        COUNTER_DEBUG("Failed to set handler for pmc %p\n", resv->pmc);
                        return FALSE;
                }
        }

        return TRUE;
}

/*
 * pmc_reserve will attempt to reserve the given @pmc, with a given
 * configuration object, for counting system-wide. This method will fail with
 * KERN_FAILURE if the given pmc is already reserved at any scope.
 *
 * This method consumes the given configuration object if it returns
 * KERN_SUCCESS. Any other return value indicates the caller
 * must free the config object via pmc_free_config().
 *
 * NOTE: This method is NOT interrupt safe.
 */
kern_return_t pmc_reserve(pmc_t pmc, pmc_config_t config,
        pmc_reservation_t *reservation) {

        if(!pmc || !config || !reservation) {
                return KERN_INVALID_ARGUMENT;
        }

        pmc_reservation_t resv = reservation_alloc();
        if(!resv) {
                return KERN_RESOURCE_SHORTAGE;
        }

        reservation_init(resv);

        resv->flags |= PMC_FLAG_SCOPE_SYSTEM;
        resv->config = config;

        if(KERN_SUCCESS != pmc_internal_reservation_set_pmc(resv, pmc)) {
                resv->config = NULL;
                return KERN_FAILURE;
        }
        
        /* enqueue reservation in proper place */
        if(!pmc_internal_reservation_add(resv) || !pmc_reservation_setup_pmi(resv, config)) {
                /* Prevent free of config object */
                resv->config = NULL;
                
                reservation_free(resv);
                return KERN_FAILURE;
        }

        perf_monitor_reservation_add(pmc->monitor);
        
        *reservation = resv;

        return KERN_SUCCESS;
}

/*
 * pmc_reserve_task will attempt to reserve the given @pmc with a given
 * configuration object, for counting when the given @task is running on any
 * logical core that can directly access the given @pmc.  This method will fail
 * with KERN_FAILURE if the given pmc is already reserved at either system or
 * thread scope.  
 *
 * This method consumes the given configuration object if it returns
 * KERN_SUCCESS. Any other return value indicates the caller
 * must free the config object via pmc_free_config().
 *
 * NOTE: You can reserve the same pmc for N different tasks concurrently.
 * NOTE: This method is NOT interrupt safe.
 */
kern_return_t pmc_reserve_task(pmc_t pmc, pmc_config_t config, 
        task_t task, pmc_reservation_t *reservation) {

        if(!pmc || !config || !reservation || !task) {
                return KERN_INVALID_ARGUMENT;
        }

        if (!(pmc->monitor->methods.flags & PERFMON_FLAG_SUPPORTS_CONTEXT_SWITCHING)) {
                COUNTER_DEBUG("pmc %p cannot be context switched!\n", pmc);
                return KERN_INVALID_ARGUMENT;
        }

        pmc_reservation_t resv = reservation_alloc();
        if(!resv) {
                return KERN_RESOURCE_SHORTAGE;
        }

        reservation_init(resv);

        resv->flags |= PMC_FLAG_SCOPE_TASK;
        resv->task = task;

        resv->config = config;

        if(KERN_SUCCESS != pmc_internal_reservation_set_pmc(resv, pmc)) {
                resv->config = NULL;
                return KERN_FAILURE;
        }
        
        /* enqueue reservation in proper place */
        if(!pmc_internal_reservation_add(resv) || !pmc_reservation_setup_pmi(resv, config)) {
                /* Prevent free of config object */
                resv->config = NULL;

                reservation_free(resv);
                return KERN_FAILURE;
        }

        perf_monitor_reservation_add(pmc->monitor);

        *reservation = resv;

        return KERN_SUCCESS;
}

/*
 * pmc_reserve_thread will attempt to reserve the given @pmc with a given
 * configuration object, for counting when the given @thread is running on any
 * logical core that can directly access the given @pmc.  This method will fail
 * with KERN_FAILURE if the given pmc is already reserved at either system or
 * task scope.  
 *
 * This method consumes the given configuration object if it returns
 * KERN_SUCCESS. Any other return value indicates the caller
 * must free the config object via pmc_free_config().
 *
 * NOTE: You can reserve the same pmc for N different threads concurrently.
 * NOTE: This method is NOT interrupt safe.
 */
kern_return_t pmc_reserve_thread(pmc_t pmc, pmc_config_t config, 
        thread_t thread, pmc_reservation_t *reservation) {
        if(!pmc || !config || !reservation || !thread) {
                return KERN_INVALID_ARGUMENT;
        }

        if (!(pmc->monitor->methods.flags & PERFMON_FLAG_SUPPORTS_CONTEXT_SWITCHING)) {
                COUNTER_DEBUG("pmc %p cannot be context switched!\n", pmc);
                return KERN_INVALID_ARGUMENT;
        }

        pmc_reservation_t resv = reservation_alloc();
        if(!resv) {
                return KERN_RESOURCE_SHORTAGE;
        }

        reservation_init(resv);

        resv->flags |= PMC_FLAG_SCOPE_THREAD;
        resv->thread = thread;

        resv->config = config;

        if(KERN_SUCCESS != pmc_internal_reservation_set_pmc(resv, pmc)) {
                resv->config = NULL;
                return KERN_FAILURE;
        }
        
        /* enqueue reservation in proper place */
        if(!pmc_internal_reservation_add(resv) || !pmc_reservation_setup_pmi(resv, config)) {
                /* Prevent free of config object */
                resv->config = NULL;

                reservation_free(resv);
                return KERN_FAILURE;
        }

        perf_monitor_reservation_add(pmc->monitor);

        *reservation = resv;

        return KERN_SUCCESS;
}

/*
 * pmc_reservation_start instructs the given reservation to start counting as
 * soon as possible. 
 *
 * NOTE: This method is interrupt safe.
 */
kern_return_t pmc_reservation_start(pmc_reservation_t reservation) {
        pmc_state_t newState;

        if(!reservation) {
                return KERN_INVALID_ARGUMENT;
        }

        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_START, NULL))) {
                return KERN_FAILURE;
        }
        
        /* If we are currently in an interrupt, don't bother to broadcast since it won't do anything now and the interrupt will
         * broadcast right before it leaves
         */
        if (PMC_STATE_STATE(newState) != PMC_STATE_STATE_INTERRUPT) {   
                /* A valid state move has been made, but won't be picked up until a context switch occurs.  To cause matching
                 * contexts that are currently running to update, we do an inter-processor message to run pmc_internal_reservation_start_cpu
                 * on every cpu that can access the PMC.
                 */
                pmc_internal_reservation_broadcast(reservation, pmc_internal_reservation_start_cpu);
        }
        
        return KERN_SUCCESS;                     
}

/*
 * pmc_reservation_stop instructs the given reservation to stop counting as
 * soon as possible.  When this method returns, the pmc will be marked as stopping
 * and subsequent calls to pmc_reservation_start will succeed.  This does not mean
 * that the pmc hardware has _actually_ stopped running.  Assuming no other changes
 * to the reservation state, the pmc hardware _will_ stop shortly.
 *
 */
kern_return_t pmc_reservation_stop(pmc_reservation_t reservation) {
        pmc_state_t newState;

        if(!reservation) {
                return KERN_INVALID_ARGUMENT;
        }
        
        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_STOP, NULL))) {
                return KERN_FAILURE;
        }
        
        /* If we are currently in an interrupt, don't bother to broadcast since it won't do anything now and the interrupt will
         * broadcast right before it leaves.  Similarly, if we just moved directly to STOP, don't bother broadcasting.
         */
        if (PMC_STATE_STATE(newState) != PMC_STATE_STATE_INTERRUPT && PMC_STATE_STATE(newState) != PMC_STATE_STATE_STOP) {      
                /* A valid state move has been made, but won't be picked up until a context switch occurs.  To cause matching
                         * contexts that are currently running to update, we do an inter-processor message to run pmc_internal_reservation_stop_cpu
                 * on every cpu that can access the PMC.
                 */
                
                pmc_internal_reservation_broadcast(reservation, pmc_internal_reservation_stop_cpu);
        }
        
        return KERN_SUCCESS;
}

/*
 * pmc_reservation_read will read the event count associated with a reservation.
 * If the caller is current executing in a context that both a) matches the
 * reservation's context, and b) can access the reservation's pmc directly, the
 * value will be read from hardware.  Otherwise, this returns the reservation's
 * stored value.
 *
 * NOTE: This method is interrupt safe.
 * NOTE: When not on the interrupt stack, this method may block.
 */
kern_return_t pmc_reservation_read(pmc_reservation_t reservation, uint64_t *value) {
        kern_return_t ret = KERN_FAILURE;
        uint64_t timeout;
        uint32_t spins;

        if(!reservation || !value) {
                return KERN_INVALID_ARGUMENT;
        }

        nanoseconds_to_absolutetime(PMC_SPIN_TIMEOUT_US * 1000, &timeout);
        timeout += mach_absolute_time();
        spins = 0;
        do {
                uint32_t state = reservation->state;
                
                if((PMC_STATE_STATE(state) == PMC_STATE_STATE_RUN)) {
                        /* Attempt read from hardware via drivers. */

                        assert(reservation->pmc);

                        ret = reservation->pmc->methods.get_count(reservation->pmc->object, value);
                        
                        break;
                } else if ((PMC_STATE_STATE(state) == PMC_STATE_STATE_STORE) ||
                                   (PMC_STATE_STATE(state) == PMC_STATE_STATE_LOAD)) {
                        /* Spin */
                        /* Assert if this takes longer than PMC_SPIN_TIMEOUT_US */
                        if (++spins > PMC_SPIN_THRESHOLD) {
                                if (mach_absolute_time() > timeout) {
                                        pmc_spin_timeout_count++;
                                        assert(0);
                                }
                        }

                        cpu_pause();
                } else {
                        break;
                }
        } while (1);

        /* If the direct hardware read failed (for whatever reason) */
        if(KERN_SUCCESS != ret) {
                /* Read stored value */
                *value = reservation->value;
        }

        return KERN_SUCCESS;
}

/*
 * pmc_reservation_write will write the event count associated with a reservation.
 * If the caller is current executing in a context that both a) matches the
 * reservation's context, and b) can access the reservation's pmc directly, the
 * value will be written to hardware.  Otherwise, this writes the reservation's
 * stored value.
 *
 * NOTE: This method is interrupt safe.
 * NOTE: When not on the interrupt stack, this method may block.
 */
kern_return_t pmc_reservation_write(pmc_reservation_t reservation, uint64_t value) {
        kern_return_t ret = KERN_FAILURE;
        uint64_t timeout;
        uint32_t spins;

        if(!reservation) {
                return KERN_INVALID_ARGUMENT;
        }

        nanoseconds_to_absolutetime(PMC_SPIN_TIMEOUT_US * 1000, &timeout);
        timeout += mach_absolute_time();
        spins = 0;
        do {
                uint32_t state = reservation->state;
                
                if((PMC_STATE_STATE(state) == PMC_STATE_STATE_RUN)) {
                                /* Write to hardware via drivers. */
                        assert(reservation->pmc);

                        ret = reservation->pmc->methods.set_count(reservation->pmc->object, value);
                        break;
                } else if ((PMC_STATE_STATE(state) == PMC_STATE_STATE_STORE) ||
                                   (PMC_STATE_STATE(state) == PMC_STATE_STATE_LOAD)) {
                        /* Spin */
                        /* Assert if this takes longer than PMC_SPIN_TIMEOUT_US */
                        if (++spins > PMC_SPIN_THRESHOLD) {
                                if (mach_absolute_time() > timeout) {
                                        pmc_spin_timeout_count++;
                                        assert(0);
                                }
                        }

                        cpu_pause();
                } else {
                        break;
                }
        } while (1);
        
        if(KERN_SUCCESS != ret) {
                /* Write stored value */
                reservation->value = value;
        }

        return KERN_SUCCESS;
}

/* 
 * pmc_reservation_free releases a reservation and all associated resources.
 *
 * NOTE: This method is NOT interrupt safe.
 */
kern_return_t pmc_reservation_free(pmc_reservation_t reservation) {
        pmc_state_t newState;
        
        if(!reservation) {
                return KERN_INVALID_ARGUMENT;
        }
        
        perf_monitor_reservation_remove(reservation->pmc->monitor);
        
        /* Move the state machine */
        if (PMC_STATE_INVALID == (newState = pmc_internal_reservation_move_for_event(reservation, PMC_STATE_EVENT_FREE, NULL))) {
                return KERN_FAILURE;
        }

        /* If we didn't move directly to DEALLOC, help things along */  
        if (PMC_STATE_STATE(newState) != PMC_STATE_STATE_DEALLOC) {     
                /* A valid state move has been made, but won't be picked up until a context switch occurs.  To cause matching
                 * contexts that are currently running to update, we do an inter-processor message to run pmc_internal_reservation_stop_cpu
                 * on every cpu that can access the PMC.
                 */
                pmc_internal_reservation_broadcast(reservation, pmc_internal_reservation_stop_cpu);
        }

        /* Block until the reservation hits the <DEALLOC, 0, > state */
        while (!(PMC_STATE_STATE(reservation->state) == PMC_STATE_STATE_DEALLOC && PMC_STATE_CONTEXT_COUNT(reservation->state) == 0 && PMC_STATE_FLAGS(reservation->state) == 0)) {
                assert_wait((event_t)reservation, THREAD_UNINT);
                thread_block(THREAD_CONTINUE_NULL);
        }

        /* remove from queues */
        pmc_internal_reservation_remove(reservation);
                
        /* free reservation */
        reservation_free(reservation);

        return KERN_SUCCESS;
}

/*
 * pmc_idle notifies eligible monitors of impending per-CPU idle, and can be used to save state.
 */
boolean_t pmc_idle(void) {
        perf_monitor_t monitor = NULL;
        queue_head_t *cpu_queue;

        lck_spin_lock(&perf_monitor_queue_spin);
        
        if (cpu_monitor_queues) {
                cpu_queue = cpu_monitor_queues[cpu_number()];
        
                queue_iterate(cpu_queue, monitor, perf_monitor_t, cpu_link) {
                        perf_monitor_methods_t *methods = &(monitor->methods);
                        if ((methods->flags & PERFMON_FLAG_ALWAYS_ACTIVE) || (monitor->reservedCounters)) {                 
                                methods->on_idle(monitor->object);
                        }
                }
        }

        lck_spin_unlock(&perf_monitor_queue_spin);

        return TRUE;
}

/*
 * pmc_idle_exit notifies eligible monitors of wake from idle; it can be used to restore state.
 */
boolean_t pmc_idle_exit(void) {
        perf_monitor_t monitor = NULL;
        queue_head_t *cpu_queue;

        lck_spin_lock(&perf_monitor_queue_spin);
        
        if (cpu_monitor_queues) {
                cpu_queue = cpu_monitor_queues[cpu_number()];
        
                queue_iterate(cpu_queue, monitor, perf_monitor_t, cpu_link) {
                        perf_monitor_methods_t *methods = &(monitor->methods);
                        if ((methods->flags & PERFMON_FLAG_ALWAYS_ACTIVE) || (monitor->reservedCounters)) {                 
                                methods->on_idle_exit(monitor->object);
                        }
                }
        }

        lck_spin_unlock(&perf_monitor_queue_spin);

        return TRUE;
}

/*
 * pmc_context_switch performs all context switching necessary to save all pmc
 * state associated with @oldThread (and the task to which @oldThread belongs),
 * as well as to restore all pmc state associated with @newThread (and the task
 * to which @newThread belongs).
 *
 * NOTE: This method IS interrupt safe.
 */
boolean_t pmc_context_switch(thread_t oldThread, thread_t newThread) {
        pmc_reservation_t resv = NULL;
        uint32_t cpuNum = cpu_number();

        lck_spin_lock(&reservations_spin);

        /* Save pmc states */
        if (thread_reservation_count) {
                queue_iterate(thread_reservations, resv, pmc_reservation_t, link) {
                        if ((oldThread == resv->thread) && pmc_accessible_from_core(resv->pmc, cpuNum)) {
                                (void)pmc_internal_reservation_context_out(resv);
                        }
                }
        }
        
        if (task_reservation_count) {
                queue_iterate(task_reservations, resv, pmc_reservation_t, link) {
                        if ((resv->task == oldThread->task) && pmc_accessible_from_core(resv->pmc, cpuNum)) {
                        (void)pmc_internal_reservation_context_out(resv);
                        }
                }
        }
        
        /* Restore */
        if (thread_reservation_count) {
                queue_iterate(thread_reservations, resv, pmc_reservation_t, link) {
                        if ((resv->thread == newThread) && pmc_accessible_from_core(resv->pmc, cpuNum)) {
                                (void)pmc_internal_reservation_context_in(resv);
                        }
                }
        }

        if (task_reservation_count) {
                queue_iterate(task_reservations, resv, pmc_reservation_t, link) {
                        if ((resv->task == newThread->task) && pmc_accessible_from_core(resv->pmc, cpuNum)) {
                                (void)pmc_internal_reservation_context_in(resv);
                        }
                }
        }
        
        lck_spin_unlock(&reservations_spin);

        return TRUE;
}

#else /* !CONFIG_COUNTERS */

#if 0
#pragma mark -
#pragma mark Dummy functions
#endif

/*
 * In the case that someone has chosen not to include the PMC KPI in some
 * configuration, we still have exports for kexts, so we'll need to define stub
 * methods that return failures.
 */
kern_return_t perf_monitor_register(perf_monitor_object_t monitor __unused,
        perf_monitor_methods_t *methods __unused) {
        return KERN_FAILURE;
}

kern_return_t perf_monitor_unregister(perf_monitor_object_t monitor __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_register(perf_monitor_object_t monitor __unused, 
        pmc_object_t pmc __unused, pmc_methods_t *methods __unused, void *object __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_unregister(perf_monitor_object_t monitor __unused,
        pmc_object_t pmc __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_create_config(pmc_t pmc __unused, 
        pmc_config_t *config __unused) {
        return KERN_FAILURE;
}

void pmc_free_config(pmc_t pmc __unused, pmc_config_t config __unused) {
}

kern_return_t pmc_config_set_value(pmc_t pmc __unused, 
        pmc_config_t config __unused, uint8_t id __unused, 
        uint64_t value __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_config_set_interrupt_threshold(pmc_t pmc __unused, 
        pmc_config_t config __unused, uint64_t threshold __unused, 
        pmc_interrupt_method_t method __unused, void *refCon __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_get_pmc_list(pmc_t **pmcs __unused, size_t *pmcCount __unused) {
        return KERN_FAILURE;
}

void pmc_free_pmc_list(pmc_t *pmcs __unused, size_t pmcCount __unused) {
}

kern_return_t pmc_find_by_name(const char *name __unused, pmc_t **pmcs __unused, 
        size_t *pmcCount __unused) {
        return KERN_FAILURE;
}

const char *pmc_get_name(pmc_t pmc __unused) {
        return "";
}

kern_return_t pmc_get_accessible_core_list(pmc_t pmc __unused, 
        uint32_t **logicalCores __unused, size_t *logicalCoreCt __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reserve(pmc_t pmc __unused, 
        pmc_config_t config __unused, pmc_reservation_t *reservation __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reserve_task(pmc_t pmc __unused, 
        pmc_config_t config __unused, task_t task __unused, 
        pmc_reservation_t *reservation __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reserve_thread(pmc_t pmc __unused, 
        pmc_config_t config __unused, thread_t thread __unused, 
        pmc_reservation_t *reservation __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reservation_start(pmc_reservation_t reservation __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reservation_stop(pmc_reservation_t reservation __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reservation_read(pmc_reservation_t reservation __unused, 
        uint64_t *value __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reservation_write(pmc_reservation_t reservation __unused, 
        uint64_t value __unused) {
        return KERN_FAILURE;
}

kern_return_t pmc_reservation_free(pmc_reservation_t reservation __unused) {
        return KERN_FAILURE;
}


#endif /* !CONFIG_COUNTERS */