osfmk/pmc/pmc.h

91  * @abstract A pointer to a method that enables a set of counters.
92  * @discussion Implementations of this method type must be safe to call at interrupt context.
100  * @abstract A pointer to a method that disables a set of counters.
101  * @discussion Implementations of this method type must be safe to call at interrupt context.
117  * @abstract A set of method pointers to be used when interacting with a performance monitor object
147  * @abstract A pointer to a method that creates a configuration object for a counter
149  * Corresponds to IOPerformanceCounter::createConfiguration() method.
156  * @abstract A pointer to a method to free a configuration object for a pmc
164  * @abstract A pointer to a method to set a key-value pair on a config object.
166  * Corresponds to IOPerformanceCounterConfiguration::setValueForId() method.
175  * @abstract A pointer to a method that will be called when a Performance Counter causes a PMI interrupt
176  * @discussion Implementations of this method type must be safe to call at interrupt context.
183  * @abstract A pointer to a method that will set the counter PMI threshold.
191  * @abstract A pointer to a method that will set the method to be called when the counter threshold is reached.
193  * @param target A reference pointer used as the first argument to the callback method.
194  * @param method A pointer to the method to be called.
195  * @param refCon A reference pointer to be used as the second argument to the callback method (may be NULL).
197 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);
200  * @abstract A pointer to a method that will configure a pmc's control registers according to the given configuration object.
201  * @discussion Implementations of this method type must be safe to call at interrupt context.
208  * @abstract A pointer to a method that returns the Performance Monitor Object for a counter
209  * @discussion A pointer to a method that returns the Performance Monitor Object for a counter.
210  * Implementations of this method type must be safe to call at interrupt context.
211  * Corresponds to IOPerformanceCounter::getMonitor() method.
218  * @abstract A pointer to a method that returns the registered name of the PMC.
219  * @discussion A pointer to a method that returns the registered name of the PMC.
220  * Corresponds to IOPerformanceCounter::getRegisteredName() method.
222  * NOTE: Driver authors must not allocate or copy the string during this method:
231  * @abstract A pointer to a method that returns if a pmc is accessible from a given logical core.
232  * @discussion A pointer to a method that returns if a pmc is accessible from a given logical core.
233  * Implementations of this method type must be safe to call at interrupt context.
241  * @abstract A pointer to a method that returns an array of the logical cores from which a PMC can be accessed.
242  * @discussion A pointer to a method that returns an array of the logical cores from which a PMC can be accessed.
244  * Implementations of this method type must be safe to call at interrupt context.
253  * @abstract A pointer to a method that attempts to read the count from the given counter hardware.
254  * @discussion Implementations of this method type must be safe to call from interrupt context.  * @param pmc The counter from which to read
260  * @abstract A pointer to a method that attempts to write the count to the given counter hardware.
261  * @discussion Implementations of this method type must be safe to call from interrupt context.
269  * @abstract A pointer to a method that disables the counter hardware for a given PMC.
270  * @discussion A pointer to a method that disables the counter hardware for
272  * Implementations of this method type must be safe to call at interrupt context.
279  * @abstract A pointer to a method that enables the counter hardware for a given PMC.
280  * @discussion A pointer to a method that enables the counter hardware for a given PMC.
281  * Implementations of this method type must be safe to call at interrupt context.
338  * @discussion Kexts that implement performance monitor drivers will call this method with a
360  * @discussion Kexts that implement performance monitor drivers will call this method just before they unload
371  * @discussion This method takes a Performance Monitor driver instance that was previously registered
414 	 * used in the perf_monitor_register() method.
441 	 * used in the pmc_register() method.
554  * @discussion This method is not interrupt safe.
562  * @discussion This method is not interrupt safe.
571  * by the driver-writer and are listed in XML form available for interrogation via the CoreProfile framework. This method is not interrupt safe.
578  * @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
580  * 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.
582 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);
586  * @discussion Callers should free the resultant list via <link>pmc_free_pmc_list</link>. This method is not interrupt safe.
594  * @discussion This method is not interrupt safe.
602  * @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.
612  * @discussion The returned pointer is not a copy, and does not need to be freed. This method is interrupt safe.
619  * @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,
620  * therefore callers should take care not to mutate or free the resultant list. This method is interrupt safe.
636  * @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
637  * configuration object. This method consumes the given configuration object if the return value is KERN_SUCCESS - any other return value indicates the caller
638  * should free the configuration object via <link>pmc_free_config</link>. This method is not interrupt safe.
642  * @result This method will return one of the following values:
653  * @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
654  * 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.
665  * @discussion This method will attempt to reserve the given pmc for thread-wide counting. The resulting reservation will only count when the thread is
666  * 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.
677  * @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
679  * 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.
686  * @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
688  * 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.
695  * @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 ]
697  * 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
698  * interrupt context, this method may block.
706  * @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
708  * 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
709  * interrupt context, this method may block.
717  * @discussion This method will free the resources associated with the given reservation and release the associated PMC back to general availability.
718  * If the reservation is currently counting, it will be stopped prior to release. This method is not interrupt safe.
733  * @discussion This method will save all PMCs reserved for oldThread (and the task associated with oldThread), as well as restore all PMCs reserved
734  * for newThread (and the task associated with newThread). This method is for xnu-internal context switching routines only.
740  * @discussion This method notifies registered performance monitors of impending cpu idle, and can be used to save counter state.
746  * @discussion This method notifies registered performance monitors of wake-up from the prior idle, and can be used to restore