-/*
- * 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@
- */
-
-#ifndef _MACH_PMC_H_
-#define _MACH_PMC_H_
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <stdint.h>
-#include <kern/queue.h>
-#include <mach/boolean.h>
-#include <mach/mach_time.h>
-#include <mach/mach_types.h>
-
-#include <libkern/version.h>
-
-/****************************************************************************
- * The four main object types
- *
- * 1. Performance monitors (perf_monitor_t) - represent the hardware that
- * encapsulates a set of performance counters
- * 2. Performance Counters (pmc_t) - represents each individual counter
- * 3. Performance Counter Configs (pmc_config_t) - represents the settings
- * applied to a performance counter (e.g., what to count)
- * 4. Performance Counter Reservations (pmc_reservation_t) - represents a config along
- * with it's saved counter value, and the context underwhich it will count.
- *
- ****************************************************************************/
-
-/*
- * The following objects are in-kernel stand-ins for objects that will be implemented
- * in the driver kexts. They are generally instances of C++ objects. We make opaque
- * handles for each distinct type for a little bit of type safety when used from the
- * kernel layer. These objects are not to be introspected by the kernel at any time,
- * only used as arguments in the registered driver methods.
- */
-
-// IOPerformanceMonitor instances
-typedef void * perf_monitor_object_t;
-
-// IOPerformanceCounter instances
-typedef void * pmc_object_t;
-
-// IOPerformanceCounterConfig instances
-typedef void * pmc_config_object_t;
-
-// END Kext-implemented objects
-
-// Forward declations
-struct pmc_reservation;
-typedef struct pmc_reservation *pmc_reservation_t;
-
-struct pmc_config;
-typedef struct pmc_config *pmc_config_t;
-
-/****************************************************************************
- * Method types for performance monitor driver registration
- *
- * Driver registration happens with no intervention from the driver writers -
- * it is handled automatically by the IOProfileFamily kext. Registration
- * happens whenever any IOPerformanceMonitor subclass attaches to the registry.
- * Failure to successfully register with the kernel will prevent successful attachment
- * to the IORegistry (this way only usable PMCs and Perf Monitors will be shown.)
- ****************************************************************************/
-
-typedef kern_return_t (*perfmon_get_accessible_cores_method_t)(pmc_object_t pmc, uint32_t **cores, size_t *coreCt);
-
-/*!typedef
- * @abstract A pointer to a method that enables a set of counters.
- * @discussion Implementations of this method type must be safe to call at interrupt context.
- * @param pmcs An array of pmc_object_t instances (non-NULL).
- * @param pmcCount The number of elements in the @pmcs array.
- * @result KERN_SUCCESS upon successful global enable of the given counters (may return IOKit error codes).
- */
-typedef kern_return_t (*perfmon_enable_counters_method_t)(perf_monitor_object_t pm, pmc_object_t *pmcs, uint32_t pmcCount);
-
-/*!typedef
- * @abstract A pointer to a method that disables a set of counters.
- * @discussion Implementations of this method type must be safe to call at interrupt context.
- * See <link>perfmon_enable_counters_method_t</link>
- * @result See <link>perfmon_enable_counters_method_t</link>
- */
-typedef kern_return_t (*perfmon_disable_counters_method_t)(perf_monitor_object_t pm, pmc_object_t *pmcs, uint32_t pmcCount);
-
-typedef void (*perfmon_on_idle_method_t)(perf_monitor_object_t pm);
-typedef void (*perfmon_on_idle_exit_method_t)(perf_monitor_object_t pm);
-
-#define MACH_PERFMON_METHODS_VERSION 1
-
-#define PERFMON_FLAG_SUPPORTS_CONTEXT_SWITCHING 0x1
-#define PERFMON_FLAG_REQUIRES_IDLE_NOTIFICATIONS 0x2
-#define PERFMON_FLAG_ALWAYS_ACTIVE 0x4
-
-/*!struct perf_monitor_methods
- * @abstract A set of method pointers to be used when interacting with a performance monitor object
- * @discussion This structure is the set of driver-implemented callback methods to be used when
- * interacting with a new performance monitor from the kernel.
- */
-typedef struct perf_monitor_methods {
- uint32_t perf_monitor_methods_version; // Always set to MACH_PERFMON_METHODS_VERSION when writing driver kexts
-
- uint32_t flags;
-
- perfmon_get_accessible_cores_method_t accessible_cores;
-
- perfmon_enable_counters_method_t enable_counters;
- perfmon_disable_counters_method_t disable_counters;
-
- perfmon_on_idle_method_t on_idle;
- perfmon_on_idle_exit_method_t on_idle_exit;
-} perf_monitor_methods_t;
-
-/****************************************************************************
- * Method types for performance counter registration
- *
- * Registration of individual Performance Counters happens after the
- * encapsulating Performance Monitor has been registered. This, too, happens
- * with no intervention of driver-writers. It happens automatically whenever
- * any IOPerformanceCounter subclass attaches to IORegistry. Failure to register
- * with the kernel will prevent the IOPerformanceCounter instance from attaching
- * to IORegistry.
- ****************************************************************************/
-
-/*!typedef
- * @abstract A pointer to a method that creates a configuration object for a counter
- * @discussion Configuration objects create and hold the hardware representation for a set of driver-defined key-value pairs.
- * Corresponds to IOPerformanceCounter::createConfiguration() method.
- * @param pmc A valid pmc object
- * @result NULL on failure, or a pmc_config_t on success.
- */
-typedef pmc_config_object_t (*pmc_create_config_method_t)(pmc_object_t pmc);
-
-/*!typedef
- * @abstract A pointer to a method to free a configuration object for a pmc
- * @discussion Method should free a pmc config object created with a pmc_create_config_method_t above
- * @param pmc The pmc object used to create the config
- * @param config The config object to release
- */
-typedef void (*pmc_free_config_method_t)(pmc_object_t pmc, pmc_config_object_t config);
-
-/*!typedef
- * @abstract A pointer to a method to set a key-value pair on a config object.
- * @discussion Configuration objects take key-value pairs for setting various bits in the pmc configs
- * Corresponds to IOPerformanceCounterConfiguration::setValueForId() method.
- * @param config Pointer to config object.
- * @param id 8-bit integer ID (determined by the driver).
- * @param value 64-bit integer value (interpretted by the driver).
- * @result KERN_SUCCESS on success, KERN_FAILURE on bad value, KERN_INVALID_ARGUMENT on bad id
- */
-typedef kern_return_t (*pmc_config_set_value_method_t)(pmc_config_object_t config, uint8_t id, uint64_t value);
-
-/*!typedef
- * @abstract A pointer to a method that will be called when a Performance Counter causes a PMI interrupt
- * @discussion Implementations of this method type must be safe to call at interrupt context.
- * @param target The pmc_reservation_t that caused the interrupt
- * @param refCon Any value as defined by the end-user who called <link>pmc_config_set_interrupt_threshold</link>
- */
-typedef void (*pmc_interrupt_method_t)(void *target, void *refCon);
-
-/*!typedef
- * @abstract A pointer to a method that will set the counter PMI threshold.
- * @param config A configuration object
- * @param threshold The number of events after which to cause an interrupt
- * callback.
- */
-typedef kern_return_t (*pmc_config_set_interrupt_threshold_method_t)(pmc_config_object_t config, uint64_t threshold);
-
-/*!typedef
- * @abstract A pointer to a method that will set the method to be called when the counter threshold is reached.
- * @param config A configuration object.
- * @param target A reference pointer used as the first argument to the callback method.
- * @param method A pointer to the method to be called.
- * @param refCon A reference pointer to be used as the second argument to the callback method (may be NULL).
- */
-typedef kern_return_t (*pmc_config_set_interrupt_threshold_handler_method_t)(pmc_config_object_t config, void *target, pmc_interrupt_method_t method, void *refCon);
-
-/*!typedef
- * @abstract A pointer to a method that will configure a pmc's control registers according to the given configuration object.
- * @discussion Implementations of this method type must be safe to call at interrupt context.
- * @param pmc The pmc reference object.
- * @param config A configuration object.
- */
-typedef kern_return_t (*pmc_set_config_method_t)(pmc_object_t pmc, pmc_config_object_t config);
-
-/*!typedef
- * @abstract A pointer to a method that returns the Performance Monitor Object for a counter
- * @discussion A pointer to a method that returns the Performance Monitor Object for a counter.
- * Implementations of this method type must be safe to call at interrupt context.
- * Corresponds to IOPerformanceCounter::getMonitor() method.
- * @param pmc A valid pmc object
- * @result NULL on failure, or a perf_monitor_object_t on success.
- */
-typedef perf_monitor_object_t (*pmc_get_monitor_method_t)(pmc_object_t pmc);
-
-/*!typedef
- * @abstract A pointer to a method that returns the registered name of the PMC.
- * @discussion A pointer to a method that returns the registered name of the PMC.
- * Corresponds to IOPerformanceCounter::getRegisteredName() method.
- *
- * NOTE: Driver authors must not allocate or copy the string during this method:
- * it may be called from interrupt context or with spin locks held.
- *
- * @param pmc A valid pmc object.
- * @result NULL on failure, or a pointer to the registered name of the pmc.
- */
-typedef const char *(*pmc_get_name_method_t)(pmc_object_t pmc);
-
-/*!typedef
- * @abstract A pointer to a method that returns if a pmc is accessible from a given logical core.
- * @discussion A pointer to a method that returns if a pmc is accessible from a given logical core.
- * Implementations of this method type must be safe to call at interrupt context.
- * @param pmc A valid pmc object.
- * @param core The logical core number.
- * @result TRUE if the pmc can be read in the execution context of the given logical core, FALSE otherwise.
- */
-typedef boolean_t (*pmc_is_accessible_from_logical_core_method_t)(pmc_object_t pmc, uint32_t core);
-
-/*!typedef
- * @abstract A pointer to a method that returns an array of the logical cores from which a PMC can be accessed.
- * @discussion A pointer to a method that returns an array of the logical cores from which a PMC can be accessed.
- * Resulting array of cores should not be released by xnu.
- * Implementations of this method type must be safe to call at interrupt context.
- * @param pmc A valid pmc object
- * @param cores A value-returned array of logical cores that can access the given PMC.
- * @param coreCt A value-return count of the number of entries in the @cores array.
- * @result KERN_SUCCESS on success, KERN_FAILURE otherwise.
- */
-typedef kern_return_t (*pmc_get_accessible_cores_method_t)(pmc_object_t pmc, uint32_t **cores, size_t *coreCt);
-
-/*!typedef
- * @abstract A pointer to a method that attempts to read the count from the given counter hardware.
- * @discussion Implementations of this method type must be safe to call from interrupt context. * @param pmc The counter from which to read
- * @param value Storage for the counter's hardware value.
- */
-typedef kern_return_t (*pmc_get_count_method_t)(pmc_object_t pmc, uint64_t *value);
-
-/*!typedef
- * @abstract A pointer to a method that attempts to write the count to the given counter hardware.
- * @discussion Implementations of this method type must be safe to call from interrupt context.
- * @param pmc The counter to which to write.
- * @param value The value to write to the hardware.
- */
-typedef kern_return_t (*pmc_set_count_method_t)(pmc_object_t pmc, uint64_t value);
-
-
-/*!typedef
- * @abstract A pointer to a method that disables the counter hardware for a given PMC.
- * @discussion A pointer to a method that disables the counter hardware for
- * a given PMC.
- * Implementations of this method type must be safe to call at interrupt context.
- * @param pmc A valid pmc object.
- * @result KERN_SUCCESS on successful disable
- */
-typedef kern_return_t (*pmc_disable_method_t)(pmc_object_t pmc);
-
-/*!typedef
- * @abstract A pointer to a method that enables the counter hardware for a given PMC.
- * @discussion A pointer to a method that enables the counter hardware for a given PMC.
- * Implementations of this method type must be safe to call at interrupt context.
- * @param pmc A valid pmc object.
- * @result KERN_SUCCESS on successful enable
- */
-typedef kern_return_t (*pmc_enable_method_t)(pmc_object_t pmc);
-
-typedef kern_return_t (*pmc_open_method_t)(pmc_object_t pmc, void *object);
-typedef kern_return_t (*pmc_close_method_t)(pmc_object_t pmc, void *object);
-
-#define MACH_PMC_METHODS_VERSION 0
-
-/*!
- * @struct pmc_methods
- * @abstract Performance Counter Registration methods.
- * @discussion This structure represents a set of driver-implemented methods to be used by the kernel
- * when interacting with the associated performance counter. Since a Performance Monitor may
- * implement any number of distinct types of Performance Counters, each counter registers with
- * its own set of callback methods.
- */
-typedef struct pmc_methods {
- uint32_t pmc_methods_version; // Always set to MACH_PMC_METHODS_VERSION in your driver.
-
- // All methods are required.
- pmc_create_config_method_t create_config;
- pmc_free_config_method_t free_config;
- pmc_config_set_value_method_t config_set_value;
- pmc_config_set_interrupt_threshold_method_t config_set_threshold;
- pmc_config_set_interrupt_threshold_handler_method_t config_set_handler;
- pmc_set_config_method_t set_config;
-
- pmc_get_monitor_method_t get_monitor;
- pmc_get_name_method_t get_name;
- pmc_is_accessible_from_logical_core_method_t accessible_from_core;
- pmc_get_accessible_cores_method_t accessible_cores;
- pmc_get_count_method_t get_count;
- pmc_set_count_method_t set_count;
- pmc_disable_method_t disable;
- pmc_enable_method_t enable;
- pmc_open_method_t open;
- pmc_close_method_t close;
-} pmc_methods_t;
-
-/*
- * Kext interface Methods
- *
- * These methods would be exported to apple-internal kexts, but not to 3rd-party kexts, and
- * definitely not to user space.
- *
- * All Performance Monitor and Performance Counter registration (accomplished via the following methods)
- * is handled automatically via IOProfileFamily's base classes. However, we'd need to export these
- * methods to apple-private KPI so that IOProfileFamily can call these methods when new objects attach
- * to the IORegistry.
- *
- */
-
-/*!fn
- * @abstract Registers a new performance monitor driver and its associated pointers.
- * @discussion Kexts that implement performance monitor drivers will call this method with a
- * filled-in perf_monitor_methods_t structure (with version set to MACH_PERFMON_METHODS_VERSION).
- * The PMC interface will then register the new driver internally.
- * @param monitor A handle to the performance monitor driver instance you are registering. Must not be NULL.
- * @param methods A filled-in perf_monitor_methods_t structure with version set to MACH_PERFMON_METHODS_VERSION.
- * @result KERN_SUCCESS if the new driver was successfully registered, KERN_INVALID_VALUE if the
- * version of the passed-in perf_monitor_methods_t structure does not match that which is expected,
- * KERN_RESOURCE_SHORTAGE if the kernel lacks the resources to register another performance monitor
- * driver, KERN_INVALID_ARGUMENT if one or both of the arguments is null
- */
-
-/* Prevent older AppleProfileFamily kexts from loading on newer kernels.
- * Alas, C doesn't necessarily have a cleaner way to do the version number concatenation
- */
-#define PERF_REG_NAME1(a, b) a ## b
-#define PERF_REG_NAME(a, b) PERF_REG_NAME1(a, b)
-#define perf_monitor_register PERF_REG_NAME(perf_monitor_register_, VERSION_MAJOR)
-
-kern_return_t perf_monitor_register(perf_monitor_object_t monitor, perf_monitor_methods_t *methods);
-
-/*!fn
- * @abstract Unregisters a performance monitor driver and frees space associated with its pointers.
- * @discussion Kexts that implement performance monitor drivers will call this method just before they unload
- * to cause the performance monitor they implement to be removed from the kernel's PMC system.
- * @param monitor A handle to a performance monitor driver instance that was previously registered with <link>perf_monitor_register</link>
- * @result KERN_SUCCESS if the new driver was successfully unregistered, KERN_INVALID_VALUE if the
- * passed-in perf_monitor_object_t does not match any registered performance monitor, KERN_INVALID_ARGUMENT if
- * the argument is null, KERN_FAILURE if the performance monitor is currently in use.
- */
-kern_return_t perf_monitor_unregister(perf_monitor_object_t monitor);
-
-/*!fn
- * @abstract Register a new Performance Counter, and attach it to the given Performance Monitor
- * @discussion This method takes a Performance Monitor driver instance that was previously registered
- * with <link>perf_monitor_register</link>, and attaches an instance of a Performance Counter
- * that will be accessed with the given set of pmc methods.
- * @param monitor A handle to a Performance Monitor that was previously registered.
- * @param pmc A handle to the Performance Counter instance to be attached to the monitor object
- * @param methods A filled-in pmc_methods_t structure with version set to MACH_PMC_METHODS_VERSION
- * @param object an Object to be used during the open() and close() methods. Must be a subclass of IOService, cannot be NULL.
- * @result KERN_SUCCESS if the new counter was successfully registered and attached, KERN_INVALID_VALUE if the
- * version of the passed-in pmc_methods_t structure does not match that which is expected,
- * KERN_RESOURCE_SHORTAGE if the kernel lacks the resources to register another performance counter
- * instance, KERN_INVALID_ARGUMENT if any of the arguments is null
- */
-kern_return_t pmc_register(perf_monitor_object_t monitor, pmc_object_t pmc,
- pmc_methods_t *methods, void *object);
-
-/*!fn
- * @abstract Unregisters a Performance Counter
- * @discussion Does the reverse of <link>pmc_register</link>.
- * @param monitor The registered Performance Monitor from which to remove a pmc.
- * @param pmc The Performance Counter to unregister.
- * @result KERN_SUCCESS if the counter was successfully unregistered, KERN_INVALID_VALUE if the
- * passed-in pmc_object_t does not match any registered performance counter, KERN_INVALID_ARGUMENT if
- * any argument is null, KERN_FAILURE if the performance counter is currently in use.
- */
-kern_return_t pmc_unregister(perf_monitor_object_t monitor, pmc_object_t pmc);
-
-/*
- * Here begins the interface in-kernel and in-kext users will use to interact with PMCs and
- * Performance Monitors.
- *
- * Basic usage is as follows: find your target counter, create a config for it, setup the config,
- * reserve the counter using that config in a given execution context (system, or 1 task, or 1 thread),
- * start the counter via the reservation object, stop the counter, and read the counter value similarly from the
- * reservation object. When done, release the reservation object.
- */
-
-/*!struct perf_monitor
- * @abstract In-kernel object to track a driver-implemented performance monitor.
- */
-typedef struct perf_monitor {
- /*
- * A reference-pointer used as the first argument to all callback methods
- * (to seamlessly work with C++ objects). This is the same value that was
- * used in the perf_monitor_register() method.
- */
- perf_monitor_object_t object;
-
- // Copy of the pointers used to interact with the above instance
- perf_monitor_methods_t methods;
-
- // reference counted
- uint32_t useCount;
-
- uint32_t reservedCounters;
-
- // A value of -1 here indicates independence from a particular core
- int cpu;
-
- // links to other perf monitors
- queue_chain_t link;
- queue_chain_t cpu_link;
-}*perf_monitor_t;
-
-/*!struct pmc
- * @abstract In-kernel object to track an individual driver-implemented performance counter
- */
-typedef struct pmc {
- /*
- * A reference-pointer used as the first argument to all callback methods
- * (to seamlessly work with C++ objects). This is the same value that was
- * used in the pmc_register() method.
- */
- pmc_object_t object;
-
- /* Copy of the pointers used to interact with the above instance */
- pmc_methods_t methods;
-
- /* Object to be used during open/close methods */
- void *open_object;
-
- /* reference counted */
- uint32_t useCount;
-
- /* link to parent */
- perf_monitor_t monitor;
-
- /* link to other PMCs */
- queue_chain_t link;
-}*pmc_t;
-
-// Scope flags (highest order bits)
-#define PMC_FLAG_SCOPE_SYSTEM 0x80000000U
-#define PMC_FLAG_SCOPE_TASK 0x40000000U
-#define PMC_FLAG_SCOPE_THREAD 0x20000000U
-#define PMC_SCOPE_MASK 0xE0000000U
-
-#define PMC_FLAG_IS_SYSTEM_SCOPE(x) \
- ((x & PMC_FLAG_SCOPE_SYSTEM) == PMC_FLAG_SCOPE_SYSTEM)
-
-#define PMC_FLAG_IS_TASK_SCOPE(x) \
- ((x & PMC_FLAG_SCOPE_TASK) == PMC_FLAG_SCOPE_TASK)
-
-#define PMC_FLAG_IS_THREAD_SCOPE(x) \
- ((x & PMC_FLAG_SCOPE_THREAD) == PMC_FLAG_SCOPE_THREAD)
-
-#define PMC_FLAG_SCOPE(x) (x & PMC_SCOPE_MASK)
-
-/*
- * Reservation state
- *
- * The state of a reservation is actually a 3-tuple of the current state, an active context count,
- * and a set of modifier flags. To avoid using locks, these are combined into a single uint32_t
- * that can be modified with OSCompareAndSwap.
- *
- */
-
-typedef uint32_t pmc_state_t;
-
-#define PMC_STATE_STATE_INVALID 0x00000000U
-#define PMC_STATE_STATE_STOP 0x10000000U
-#define PMC_STATE_STATE_CAN_RUN 0x20000000U
-#define PMC_STATE_STATE_LOAD 0x30000000U
-#define PMC_STATE_STATE_RUN 0x40000000U
-#define PMC_STATE_STATE_STORE 0x50000000U
-#define PMC_STATE_STATE_INTERRUPT 0x60000000U
-#define PMC_STATE_STATE_DEALLOC 0x70000000U
-
-#define PMC_STATE_STATE_MASK 0xF0000000U
-
-#define PMC_STATE_STATE(x) ((x) & PMC_STATE_STATE_MASK)
-#define PMC_STATE_STATE_SET(x, state) (((x) & ~(PMC_STATE_STATE_MASK)) | state)
-
-#define PMC_STATE_FLAGS_STOPPING 0x08000000U
-#define PMC_STATE_FLAGS_DEALLOCING 0x04000000U
-#define PMC_STATE_FLAGS_INTERRUPTING 0x02000000U
-
-#define PMC_STATE_FLAGS_MASK 0x0F000000U
-
-#define PMC_STATE_FLAGS(x) ((x) & PMC_STATE_FLAGS_MASK)
-#define PMC_STATE_FLAGS_MODIFY(x, set, clear) (((x) & ~(clear)) | set)
-
-#define PMC_STATE_CONTEXT_COUNT_MASK 0x0000FFFFU
-
-#define PMC_STATE_CONTEXT_COUNT(x) ((x) & PMC_STATE_CONTEXT_COUNT_MASK)
-#define PMC_STATE_CONTEXT_COUNT_MODIFY(x, mod) (((PMC_STATE_CONTEXT_COUNT(x) + (mod)) < PMC_STATE_CONTEXT_COUNT_MASK) ? (x) + (mod) : PMC_STATE_CONTEXT_COUNT_MASK)
-
-#define PMC_STATE(state, context_count, flags) (PMC_STATE_STATE(state) | PMC_STATE_FLAGS(flags) | PMC_STATE_CONTEXT_COUNT(context_count))
-#define PMC_STATE_MODIFY(x, context_count_mod, flags_set, flags_clear) (PMC_STATE_FLAGS_MODIFY(PMC_STATE_CONTEXT_COUNT_MODIFY(x, context_count_mod), flags_set, flags_clear))
-#define PMC_STATE_MOVE(x, state, context_count_mod, flags_set, flags_clear) (PMC_STATE_STATE_SET(PMC_STATE_MODIFY(x, context_count_mod, flags_set, flags_clear), state))
-
-#define PMC_STATE_INVALID PMC_STATE(PMC_STATE_STATE_INVALID, 0, 0)
-
-/*!struct pmc_reservation
- * @abstract In-kernel object to track an individual reservation
- */
-struct pmc_reservation {
- pmc_t pmc; // Pointer to in-kernel pmc which is reserved
- pmc_config_t config; // counter configuration
-
- // stored counter value
- uint64_t value;
-
- // TODO: Add mach-port (user-export object?)
-
- volatile uint32_t flags __attribute__((aligned(4)));
- volatile pmc_state_t state __attribute__((aligned(4)));
- volatile uint32_t active_last_context_in __attribute__((aligned(4)));
-
- union {
- task_t task; // not retained
- thread_t thread; // not retained
- };
-
- queue_chain_t link;
-};
-
-// END Kernel-objects
-
-
-// Methods exported to kernel (and kext) consumers
-
-/*!fn
- * @abstract Creates a new configuration object for the given pmc.
- * @discussion This method is not interrupt safe.
- * @param pmc The Perf Counter for which to create a configuration.
- * @param config A value-return configuration object.
- */
-kern_return_t pmc_create_config(pmc_t pmc, pmc_config_t *config);
-
-/*!fn
- * @abstract Releases a configuration object for the given pmc.
- * @discussion This method is not interrupt safe.
- * @param pmc The Perf Counter for which to release a configuration.
- * @param config A configuration object to be released.
- */
-void pmc_free_config(pmc_t pmc, pmc_config_t config);
-
-/*!fn
- * @abstract Setup the configuration
- * @discussion Configurations for counter are architecture-neutral key-value pairs (8bit key, 64bit value). Meanings of the keys and values are defined
- * by the driver-writer and are listed in XML form available for interrogation via the CoreProfile framework. This method is not interrupt safe.
- * @result KERN_SUCCESS on success.
- */
-kern_return_t pmc_config_set_value(pmc_t pmc, pmc_config_t config, uint8_t id, uint64_t value);
-
-/*!fn
- * @abstract Interrupt Threshold Setup
- * @discussion In order to configure a PMC to use PMI (cause an interrupt after so-many events occur), use this method, and provide a function to be
- * called after the interrupt occurs, along with a reference context. PMC Threshold handler methods will have the pmc 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. 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);
-
-/*!fn
- * @abstract Returns an allocated list of all pmc_t's known to the kernel.
- * @discussion Callers should free the resultant list via <link>pmc_free_pmc_list</link>. This method is not interrupt safe.
- * @param pmcs Storage for the resultant pmc_t array pointer.
- * @param pmcCount Storage for the resultant count of pmc_t's.
- */
-kern_return_t pmc_get_pmc_list(pmc_t **pmcs, size_t *pmcCount);
-
-/*!fn
- * @abstract Free a previously allocated list of pmcs.
- * @discussion This method is not interrupt safe.
- * @param pmcs PMC list to free.
- * @param pmcCount Number of pmc_t's in list.
- */
-void pmc_free_pmc_list(pmc_t *pmcs, size_t pmcCount);
-
-/*!fn
- * @abstract Finds pmcs by partial string matching.
- * @discussion This method returns a list of pmcs (similar to <link>pmc_get_pmc_list</link>) whose names match the given string up to it's length.
- * For example, searching for "ia32" would return pmcs "ia32gp0" and "ia32gp1". Results should be released by the caller using <link>pmc_free_pmc_list</link>
- * @param name Partial string to search for.
- * @param pmcs Storage for the resultant pmc_t array pointer.
- * @param pmcCount Storage for the resultant count of pmc_t's.
- */
-kern_return_t pmc_find_by_name(const char *name, pmc_t **pmcs, size_t *pmcCount);
-
-/*!fn
- * @abstract Returns a pointer to the human-readable name of the given pmc.
- * @discussion The returned pointer is not a copy, and does not need to be freed. This method is interrupt safe.
- * @param pmc The PMC whose name should be returned.
- */
-const char *pmc_get_name(pmc_t pmc);
-
-/*!fn
- * @abstract Returns a list of logical cores from which the given pmc can be read from or written to.
- * @discussion This method can return a NULL list with count of 0 -- this indicates any core can read the given pmc. This method does not allocate the list,
- * therefore callers should take care not to mutate or free the resultant list. This method is interrupt safe.
- * @param pmc The PMC for which to return the cores that can read/write it.
- * @param logicalCores Storage for the pointer to the list.
- * @param logicalCoreCt Value-return number of elements in the returned list. 0 indicates all cores can read/write the given pmc.
- */
-kern_return_t pmc_get_accessible_core_list(pmc_t pmc, uint32_t **logicalCores, size_t *logicalCoreCt);
-
-/*
- * BEGIN PMC Reservations
- *
- * These are how you reserve a PMC, start and stop it counting, and read and write
- * its value.
- */
-
-/*!fn
- * @abstract Reserve a PMC for System-wide counting.
- * @discussion This method will attempt to reserve the given pmc at system-scope. It will configure the given pmc to count the event indicated by the given
- * configuration object. This method consumes the given configuration object if the return value is KERN_SUCCESS - any other return value indicates the caller
- * should free the configuration object via <link>pmc_free_config</link>. This method is not interrupt safe.
- * @param pmc The PMC to reserve.
- * @param config The configuration object to use with the given pmc.
- * @param reservation A value-return reservation object to be used in pmc_reservation_* methods.
- * @result This method will return one of the following values:
- * KERN_SUCCESS: The given pmc was successfully reserved in system-scope; the given config object has been consumed and should not be freed by the caller,
- * KERN_FAILURE: The given pmc is already reserved in a conflicting scope,
- * KERN_INVALID_ARGUMENT: All three arguments are required to be non-NULL, but at least one is NULL,
- * KERN_RESOURCE_SHORTAGE: Could not allocate a new reservation object.
- */
-kern_return_t pmc_reserve(pmc_t pmc, pmc_config_t config, pmc_reservation_t *reservation);
-
-
-/*!fn
- * @abstract Reserve a PMC for task-wide counting.
- * @discussion This method will attempt to reserve the given pmc for task-wide counting. The resulting reservation will only count when the task is running
- * on one of the logical cores that can read the given pmc. The semantics of this method are the same as <link>pmc_reserve</link> in all other respects.
- * @param pmc The PMC to reserve
- * @param config The configuration object to use.
- * @param task The task for which to enable the counter.
- * @param reservation A value-return reservation object.
- * @result See <link>pmc_reserve</link>
- */
-kern_return_t pmc_reserve_task(pmc_t pmc, pmc_config_t config, task_t task, pmc_reservation_t *reservation);
-
-/*!fn
- * @abstract Reserve a PMC for thread-wide counting.
- * @discussion This method will attempt to reserve the given pmc for thread-wide counting. The resulting reservation will only count when the thread is
- * running on one of the logical cores that can read the given pmc. The semantics of this method are the same as <link>pmc_reserve_task</link> in all other respects.
- * @param pmc The PMC to reserve
- * @param config The configuration object to use.
- * @param thread The thread for which to enable the counter.
- * @param reservation A value-return reservation object.
- * @result See <link>pmc_reserve</link>
- */
-kern_return_t pmc_reserve_thread(pmc_t pmc, pmc_config_t config, thread_t thread, pmc_reservation_t *reservation);
-
-/*!fn
- * @abstract Start counting
- * @discussion This method instructs the given reservation to start counting as soon as possible. If the reservation is for a thread (or task) other than the
- * current thread, or for a pmc that is not accessible from the current logical core, the reservation will start counting the next time the thread (or task)
- * runs on a logical core than can access the pmc. This method is interrupt safe. If this method is called from outside of interrupt context, it may block.
- * @param reservation The reservation to start counting
- */
-kern_return_t pmc_reservation_start(pmc_reservation_t reservation);
-
-/*!fn
- * @abstract Stop counting
- * @discussion This method instructs the given reservation to stop counting as soon as possible. If the reservation is for a thread (or task) other than the
- * current thread, or for a pmc that is not accessible from the current logical core, the reservation will stop counting the next time the thread (or task) c
- * eases to run on a logical core than can access the pmc. This method is interrupt safe. If called form outside of interrupt context, this method may block.
- * @param reservation The reservation to stop counting
- */
-kern_return_t pmc_reservation_stop(pmc_reservation_t reservation);
-
-/*!fn
- * @abstract Read the counter value
- * @discussion This method will read the event count associated with the given reservation. If the pmc is currently on hardware, and the caller is currently ]
- * 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 directly
- * from the hardware. Otherwise, the value stored in the reservation is returned. This method is interrupt safe. If the caller is calling from outside of
- * interrupt context, this method may block.
- * @param reservation The reservation whose value to read.
- * @param value Value-return event count
- */
-kern_return_t pmc_reservation_read(pmc_reservation_t reservation, uint64_t *value);
-
-/*!fn
- * @abstract Write the counter value
- * @discussion This method will write the event count associated with the given reservation. If the pmc is currently on hardware, and the caller is currently
- * 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 directly
- * to the hardware. Otherwise, the value stored in the reservation is overwritten. This method is interrupt safe. If the caller is calling from outside of
- * interrupt context, this method may block.
- * @param reservation The reservation to write.
- * @param value The event count to write
- */
-kern_return_t pmc_reservation_write(pmc_reservation_t reservation, uint64_t value);
-
-/*!fn
- * @abstract Free a reservation and all associated resources.
- * @discussion This method will free the resources associated with the given reservation and release the associated PMC back to general availability.
- * If the reservation is currently counting, it will be stopped prior to release. This method is not interrupt safe.
- * @param reservation The reservation to free
- */
-kern_return_t pmc_reservation_free(pmc_reservation_t reservation);
-
-#if XNU_KERNEL_PRIVATE
-
-/*!fn
- * @abstract Brings up all the necessary infrastructure required to use the pmc sub-system.
- * @discussion For xnu-internal startup routines only.
- */
-void pmc_bootstrap(void);
-
-/*!fn
- * @abstract Performs a pmc context switch.
- * @discussion This method will save all PMCs reserved for oldThread (and the task associated with oldThread), as well as restore all PMCs reserved
- * for newThread (and the task associated with newThread). This method is for xnu-internal context switching routines only.
- */
-boolean_t pmc_context_switch(thread_t oldThread, thread_t newThread);
-
-/*!fn
- * @abstract Called on per-core idle.
- * @discussion This method notifies registered performance monitors of impending cpu idle, and can be used to save counter state.
- */
-boolean_t pmc_idle(void);
-
-/*!fn
- * @abstract Called on per-core wake from idle.
- * @discussion This method notifies registered performance monitors of wake-up from the prior idle, and can be used to restore
- * previously saved counter configuration.
- */
-boolean_t pmc_idle_exit(void);
-
-#if defined(THREAD_PMC_FLAG)
-/* Allow inclusion from outside of MACH_KERNEL_PRIVATE scope. */
-
-/*!fn
- * @abstract Returns true if thread has been marked for counting.
- * @discussion Task-level reservations are propagated to child threads via thread_create_internal. Any mutation of task reservations forces a recalculate
- * of t_chud (for the pmc flag) for all threads in that task. Consequently, we can simply check the current thread's flag against THREAD_PMC_FLAG.
- */
-static inline boolean_t pmc_thread_eligible(thread_t t) {
- return (t != NULL) ? ((t->t_chud & THREAD_PMC_FLAG) ? TRUE : FALSE) : FALSE;
-}
-
-#endif /* THREAD_PMC_FLAG*/
-
-#endif // XNU_KERNEL_PRIVATE
-
-#ifdef __cplusplus
-};
-#endif
-
-#endif // _MACH_PMC_H_
-
projects / apple / xnu.git / blobdiff