Loading...
--- xnu/xnu-12377.101.15/iokit/IOKit/IOKernelReporters.h
+++ /dev/null
@@ -1,1895 +0,0 @@
-/*
- * Copyright (c) 2012-2016 Apple Inc. All Rights Reserved.
- *
- * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
- *
- * This file contains Original Code and/or Modifications of Original Code
- * as defined in and that are subject to the Apple Public Source License
- * Version 2.0 (the 'License'). You may not use this file except in
- * compliance with the License. The rights granted to you under the License
- * may not be used to create, or enable the creation or redistribution of,
- * unlawful or unlicensed copies of an Apple operating system, or to
- * circumvent, violate, or enable the circumvention or violation of, any
- * terms of an Apple operating system software license agreement.
- *
- * Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this file.
- *
- * The Original Code and all software distributed under the License are
- * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
- * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
- * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
- * Please see the License for the specific language governing rights and
- * limitations under the License.
- *
- * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
- */
-
-/*
- * FILE: IOReporter.h
- * AUTH: Cyril & Soren (Core OS)
- * DATE: 2012-2013 (Copyright Apple Inc.)
- * DESC: IOReporting interfaces for I/O Kit drivers
- *
- */
-
-#ifndef _IOKERNEL_REPORTERS_H_
-#define _IOKERNEL_REPORTERS_H_
-
-#include <machine/limits.h>
-
-#include <libkern/c++/OSPtr.h>
-#include <IOKit/IOLib.h>
-#include <IOKit/IOService.h>
-#include <IOKit/IOLocks.h>
-#include <IOKit/IOBufferMemoryDescriptor.h>
-
-#include <IOKit/IOReportTypes.h>
-#include <IOKit/IOKernelReportStructs.h>
-
-#include <libkern/c++/OSPtr.h>
-
-typedef OSDictionary IOReportLegendEntry;
-
-/*******************************
-* TOC: this file contains
-* 1. Introduction
-* 2a. IOReporter class declaration (public & non-public members)
-* 2b. static IOReporter methods unrelated to the class
-* 3. IOReporter subclass declarations (public & non-public members)
-* 4. IOReportLegend class declaration
-*******************************/
-
-/*!
- * 1. Introduction
- *
- * IOReporting is a mechanism for I/O Kit drivers to gather statistics
- * (or other information) and make it available to various "observers,"
- * which are generally in user space. Requests for information come
- * through two new IOService methods: ::configureReport(...) and
- * ::updateReport(...). While not required (see IOReportTypes.h), drivers
- * will generally use IOReporter subclass instances to track the requested
- * information and respond to IOReporting requests. Drivers can use these
- * classes to track information, either all the time or between "enable"
- * and "disable" calls to IOService::configureReport().
- *
- * Available information is organized into "channels." A channel is
- * uniquely identified by both driver (registry) ID and a 64-bit channel
- * ID. One way drivers can advertise their channels is by publishing
- * "legends" in the I/O Kit registry. In addition to collecting
- * information and responding to queries, IOReporter objects can produce
- * legend entries describing their channels. The IOReportLegend class
- * helps manage legend entries from multiple reporter objects as well
- * as with grouping channels logically for observers.
- *
- * An important basic constraint of the current implementation is that
- * all channels reported by a particular reporter instance must share all
- * traits except channel ID and name. Specifically, the channel type
- * (including report class, categories, & size) and units. Additionally,
- * IOHistogramReporter currently only supports one channel at a time.
- *
- * Currently, ::{configure/update}Report() can be called any time between
- * when a driver calls registerService() and when free() is called on
- * your driver. 12960947 tracks improvements / recommendations for
- * correctly handling these calls during termination.
- *
- * Locking
- * IOReporting only imposes concurrent access constraints when multiple
- * threads are accessing the same object. Three levels of constraint apply
- * depending on a method's purpose:
- * 1. Allocation/Teardown - same-instance concurrency UNSAFE, MAY BLOCK
- * 2. Configuration - same-instance concurrency SAFE, MAY BLOCK
- * 3. Update - same-instance concurrency SAFE, WILL NOT BLOCK
- *
- * Configuration requires memory management which can block and must
- * be invoked with interrupts ENABLED (for example, NOT in the interrupt
- * context NOR with a spin lock -- like IOSimpleLock -- held).
- *
- * Updates can be performed with interrupts disabled, but clients should
- * take into account that IOReporters' non-blocking currenency is achieved
- * with IOSimpleLockLockDisable/UnlockEnableInterrupts(): that is, by
- * disabling interrupts and taking a spin lock. While IOReporting will
- * never hold a lock beyond a call into it, some time may be spent within
- * the call spin-waiting for the lock. Clients holding their own
- * spin locks should carefully consider the impact of IOReporting's
- * (small) additional latency before calling it while holding a spin lock.
- *
- * The documentation for each method indicates any concurrency guarantees.
- */
-
-
-/*********************************/
-/*** 2a. IOReporter Base Class ***/
-/*********************************/
-
-class IOReporter : public OSObject
-{
- OSDeclareDefaultStructors(IOReporter);
-
-protected:
-/*! @function IOReporter::init
- * @abstract base init() method, called by subclass initWith() methods
- *
- * @param reportingService - IOService associated with all channels
- * @param channelType - type info for all channels (element_idx = 0)
- * @param unit - description applied for all channels
- * @result true on success, false otherwise
- *
- * @discussion
- * init() establishes the parameters of all channels for this reporter
- * instance. Any channels added via addChannel() will be of this type
- * and have this unit.
- *
- * IOReporter clients should use the static <subclass>::with() methods
- * below to obtain fully-initialized reporter instances. ::free()
- * expects ::init() to have completed successfully. On failure, any
- * allocations are cleaned up.
- *
- * Locking: same-instance concurrency UNSAFE
- */
- virtual bool init(IOService *reportingService,
- IOReportChannelType channelType,
- IOReportUnit unit);
-
-public:
-
-/*! @function IOReporter::addChannel
- * @abstract add an additional, similar channel to the reporter
- *
- * @param channelID - identifier for the channel to be added
- * @param channelName - an optional human-readble name for the channel
- * @result appropriate IOReturn code
- *
- * @discussion
- * The reporter will allocate memory to track a new channel with the
- * provided ID and name (if any). Its other traits (type, etc) will
- * be those provided when the reporter was initialized. If no channel
- * name is provided and the channelID consists solely of ASCII bytes,
- * those bytes (ignoring any NUL bytes) will be used as the
- * human-readable channel name in user space. The IOREPORT_MAKEID()
- * macro in IOReportTypes.h can be used to create ASCII channel IDs.
- *
- * Locking: same-instance concurrency SAFE, MAY BLOCK
- */
- IOReturn addChannel(uint64_t channelID, const char *channelName = NULL);
-
-/*! @function IOReporter::createLegend
- * @abstract create a legend entry represending this reporter's channels
- * @result An IOReportLegendEntry object or NULL on failure.
- * @discussion
- * All channels added to the reporter will be represented
- * in the resulting legend entry.
- *
- * Legends must be published togethar as an array under the
- * kIOReportLegendKey in the I/O Kit registry. The IOReportLegend
- * class can be used to properly combine legend entries from multiple
- * reporters as well as to put channels into groups of interest to
- * observers. When published, individual legend entries share
- * characteristics such as group and sub-group. Multiple IOReporter
- * instances are required to produce independent legend entries which
- * can then be published with different characteristics.
- *
- * Drivers wishing to publish legends should do so as part of their
- * ::start() routine. As superclasses *may* have installed legend
- * entries, any existing existing legend should be retrieved and
- * IOReportLegend used to merge it with the new entries.
- *
- * Recommendations for best practices are forthcoming.
- *
- * Instead of calling createLegend on your reporter object and then
- * appending it manually to IOReportLegend, one may prefer to call
- * IOReportLegend::appendReporterLegend which creates and appends a
- * reporter's IOReportLegendEntry in a single call.
- *
- * Locking: same-instance concurrency SAFE, MAY BLOCK
- */
- OSPtr<IOReportLegendEntry> createLegend(void);
-
-/*! @function IOReporter::configureReport
- * @abstract track IOService::configureReport(), provide sizing info
- *
- * @param channelList - channels to configure
- * @param action - enable/disable/size, etc (see IOReportTypes.h)
- * @param result - *incremented* for kIOReportGetDimensions
- * @param destination - action-specific default destination
- * @result appropriate IOReturn code
- *
- * @discussion
- * Any time a reporting driver's ::configureReport method is invoked,
- * this method should be invoked on each IOReporter that is being
- * used by that driver to report channels in channelList.
- *
- * Any channels in channelList which are not tracked by this reporter
- * are ignored. ::configureReport(kIOReportGetDimensions) expects
- * the full size of all channels, including any reported by
- * superclasses. It is valid to call this routine on multiple
- * reporter objects in succession and they will increment 'result'
- * to provide the correct total.
- *
- * In the initial release, this routine is only required to calculate
- * the response to kIOReportGetDimensions, but in the future it will
- * will enable functionality like "triggered polling" via
- * kIOReportNotifyHubOnChange. Internally, it is already keeping
- * track of the number of times each channel has been enabled and
- * disabled. 13073064 tracks adding a method to see whether any
- * channels are currently being observed.
- *
- * The static IOReporter::configureAllReports() will call this method
- * on multiple reporters grouped in an OSSet.
- *
- * Locking: same-instance concurrency SAFE, MAY BLOCK
- */
- IOReturn configureReport(IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-
-/*! @function IOReporter::updateReport
- * @abstract Produce standard reply to IOService::updateReport()
- *
- * @param channelList - channels to update
- * @param action - copy/trace data (see IOReportTypes.h)
- * @param result - action-specific return value (e.g. size of data)
- * @param destination - destination for this update (action-specific)
- * @result appropriate IOReturn code
- *
- * @discussion
- * This method searches channelList for channels tracked by this
- * reporter, writes the corresponding data into 'destination', and
- * updates 'result'. It should be possible to pass a given set of
- * IOService::updateReport() arguments to any and all reporters as
- * well as to super::updateReport() and get the right result.
- *
- * The static IOReporter::updateAllReports() will call this method
- * on an OSSet of reporters.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn updateReport(IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-
-/*! @function IOReporter::free
- * @abstract Releases the object and all its resources.
- *
- * @discussion
- * ::free() [called on last ->release()] assumes that init() [called
- * by static ::with() methods] has completed successfully.
- *
- * Locking: same-instance concurrency UNSAFE
- */
- virtual void free(void) APPLE_KEXT_OVERRIDE;
-
-/*! @function IOReporter::init
- * @abstract Initialize global state
- *
- * @discussion
- * ::initialize() [called during IOStartIOKit] initializes all global
- * state for IOReporter objects.
- *
- */
- static void initialize(void);
-
-
-/*********************************/
-/*** 2b. Useful Static Methods ***/
-/*********************************/
-
-/* The following static functions are intended to simplify the management
- * of multiple reporters. They may be superseded in the future by an
- * IOReportManager class.
- */
-
-/*! @function IOReporter::configureAllReports
- * @abstract call configureReport() on multiple IOReporter objects
- *
- * @param reporters - OSSet of IOReporter objects
- * @param channelList - full list of channels to configure
- * @param action - enable/disable/size, etc
- * @param result - action-specific returned value
- * @param destination - action-specific default destination
- * @result success if all objects successfully complete
- * IOReporter::configureReport()
- *
- * @discussion
- * The OSSet must only contain IOReporter instances. The presence
- * of non-IOReporter instances will cause this function to return
- * kIOReturnBadArgument. If any reporter returns an error, the
- * function will immediately return that error.
- *
- * Per the IOReporter::configureReport() documentation, each
- * reporter will search channelList for channels it is reporting
- * and provide a partial response.
- */
- static IOReturn configureAllReports(OSSet *reporters,
- IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-// FIXME: just put the function (inline-ish) here?
-
-/*! @function IOReporter::updateAllReports
- * @abstract call updateReport() on multiple IOReporter objects
- *
- * @param reporters - OSSet of IOReporter objects
- * @param channelList - full list of channels to update
- * @param action - type/style of update
- * @param result - returned details about what was updated
- * @param destination - destination for this update (action-specific)
- * @result IOReturn code
- * @discussion
- * The OSSet must only contain IOReporter instances. The presence
- * of non-IOReporter instances will cause this function to return
- * kIOReturnBadArgument. If any reporter returns an error, the
- * function will immediately return that error.
- *
- * Per the IOReporter::configureReport() documentation, each
- * reporter will search channelList for channels it is reporting
- * and provide a partial response.
- */
- static IOReturn updateAllReports(OSSet *reporters,
- IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-// FIXME: just put the function (inline-ish) here?
-
-
-/* Protected (subclass-only) Methods
- *
- * General subclassing is not encouraged as we intend to improve
- * internal interfaces. If you need something that might require
- * a subclass, please file a bug against IOReporting/X and we will
- * help you.
- *
- * One important concept for sub-classes (not clients) is that report
- * data is stored in IOReportElement structures (see IOReportTypes.h).
- */
-protected:
-
-/*! @function IOReporter::lockReporterConfig
- * @function IOReporter::unlockReporterConfig
- * @abstract prevent concurrent reconfiguration of a reporter
- *
- * @discussion
- * lockReporterConfig() takes a mutex-based lock intended to prevent
- * concurrent access to the reporter's configuration. It is not
- * intended to prevent updates to the reporter's data. As long as
- * all other requirements are met, it is safe to simultaneously hold
- * both the configuration and data locks on a single reporter.
- *
- * lockReporterConfig() is used by routines such as addChannel().
- * See also lockReporter() and ::handle*Swap*() below.
- */
- void lockReporterConfig(void);
- void unlockReporterConfig(void);
-
-/*! @function IOReporter::lockReporter
- * @function IOReporter::unlockReporter
- * @abstract prevent concurrent access to a reporter's data
- *
- * @discussion
- * This method grabs a lock intended to control access the reporter's
- * reporting data. Sub-classes maninupating internal report values
- * must make sure the reporter is locked (usually by the most generic
- * public interface) before calling getElementValues(),
- * copyElementValues(), or setElementValues().
- *
- * Subclasses should ensure that this lock is taken exactly once
- * before directly accessing reporter data. For example,
- * [virtual] IOFooReporter::handleSetFoo(.) {
- * // assert(lock_held)
- * getElementValues(1..)
- * getElementValues(3..)
- * getElementValues(5..)
- * [calculate]
- * setElementValues(6..)
- * }
- * IOFooReporter::setFoo(.) { // not virtual
- * lockReporter()
- * handleSetFoo(.)
- * unlockReporter()
- * }
- *
- * IOReporter::handle*() use lockReporter() similarly. For example,
- * the lock is taken by IOReporter::updateReport() and is already
- * held by the time any ::updateChannelValues() methods are called.
- *
- * Subclasses cannot call this routine if the lock is already held.
- * That's why IOReporting generally only calls it from non-virtual
- * public methods. In particular, this method should not be called
- * it from ::handle*() methods which exist to allow override after
- * the lock is taken.
- *
- * Because lockReporter() uses a spin lock, it is SAFE to use in the
- * interrupt context. For the same reason, however, it is UNSAFE
- * to perform any blocking blocking operations (including memory
- * allocations) while holding this lock.
- */
- void lockReporter(void);
- void unlockReporter(void);
-
-/*!
- * @discussion
- * The ::handle*Swap* functions allow subclasses to safely reconfigure
- * their internal state. A non-virtual function handles locking
- * and invokes the functions in order:
- * - lockReporterConfig() // protecting instance vars but not content
- * - prepare / allocate buffers of the new size
- * - if error, bail (unlocking, of course)
- *
- * - lockReporter() // protecting data / blocking updates
- * - swap: preserve continuing data / install new buffers
- * - unlockReporter()
- *
- * - deallocate now-unused buffers
- * - unlockReporterConfig()
- */
-/*! @function IOReporter::handleSwapPrepare
- * @abstract allocate memory in preparation for an instance variable swap
- *
- * @param newNChannels target number of channels
- * @result IOReturn code
- *
- * @discussion
- * ::handleSwapPrepare() is responsible for allocating appropriately-
- * sized buffers (based on the new number of channels) and storing
- * them in _swap* instance variables. If returning and error, it
- * must deallocate any buffers and set to NULL any _swap* variables.
- *
- * Locking: The caller must ensure that the *config* lock is HELD but
- * that the reporter (data) lock is *NOT HELD*.
- */
- virtual IOReturn handleSwapPrepare(int newNChannels);
-
-/*! @function IOReporter::handleAddChannelSwap
- * @abstract update primary instance variables with new buffers
- *
- * @param channel_id ID of channel being added
- * @param symChannelName optional channel name, in an allocated object
- * @result IOReturn code
- *
- * @discussion
- * handlAddChannelSwap() replaces the primary instance variables
- * with buffers allocated in handlePrepareSwap(). It copies the the
- * existing data into the appropriate portion of the new buffers.
- * Because it is specific to adding one channel, it assumes that the
- * target number of channels is one greater than the current value
- * of _nChannels.
- *
- * IOReporter::handleAddChannelSwap() increments _nElements and
- * _nChannels. To ensure that these variables describe the current
- * buffers throughout ::handle*Swap(), subclasses overriding this
- * method should call super::handleAddChannelSwap() after swapping
- * their own instance variables.
- *
- * If returning an error, all implementations should leave their
- * instance variables as they found them (*unswapped*). That ensures
- * handleSwapCleanup() cleans up the unused buffers regardless of
- * whether the swap was complete.
- *
- * Pseudo-code incorporating these suggestions:
- * res = <err>; swapComplete = false;
- * if (<unexpected>) goto finish
- * tmpBuf = _primaryBuf; _primaryBuf = _swapBuf; _swapBuf = _primaryBuf;
- * ...
- * swapComplete = true;
- * res = super::handle*Swap()
- * ...
- * finish:
- * if (res && swapComplete) // unswap
- *
- * Locking: The caller must ensure that BOTH the configuration and
- * reporter (data) locks are HELD.
- */
- virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
- const OSSymbol *symChannelName);
-
-/*! @function IOReporter::handleSwapCleanup
- * @abstract release and forget unused buffers
- *
- * @param swapNChannels channel-relative size of the _swap buffers
- *
- * @discussion
- * ::handleSwapCleanup() is responsible for deallocating the buffers
- * no longer used after a swap. It must always be called if
- * SwapPrepare() completes successfully. Because bufers may be
- * swapped in and out of existance, the _swap* variables may be
- * NULL and should be set to NULL when complete.
- *
- * Locking: The caller must ensure that the *config* lock is HELD but
- * that the reporter (data) lock is *NOT HELD*.
- */
- virtual void handleSwapCleanup(int swapNChannels);
-
-/*! @function IOReporter::handleConfigureReport
- * @abstract override vector for IOReporter::configureReport()
- * [parameters and result should exactly match]
- *
- * @discussion
- * The public base class method takes the reporter lock, calls this
- * function, and then drops the lock. Subclasses should not call
- * this function directly.
- */
- virtual IOReturn handleConfigureReport(IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-
-/*! @function IOReporter::handleUpdateReport
- * @abstract override vector for IOReporter::updateReport()
- * [parameters and result should exactly match]
- *
- * @discussion
- * The public base class method takes the reporter lock, calls this
- * function, and then drops the lock. Subclasses should not call
- * this function directly.
- *
- * This function may be overriden but the common case should be to
- * simply update reporter's specific values by overriding
- * IOReporter::updateChannelValues().
- */
- virtual IOReturn handleUpdateReport(IOReportChannelList *channelList,
- IOReportConfigureAction action,
- void *result,
- void *destination);
-
-/* @function IOReporter::handleCreateLegend
- * @abstract override vector for IOReporter::createLegend()
- * [parameters and result should exactly match]
- *
- * @discussion
- * The public base class method takes the reporter lock, calls this
- * function, and then drops the lock. Subclasses should not call
- * this function directly.
- */
- virtual OSPtr<IOReportLegendEntry> handleCreateLegend(void);
-
-/*! @function IOReporter::updateChannelValues
- * @abstract update channel values for IOReporter::updateReport()
- *
- * @param channel_index - logical (internal) index of the channel
- * @result appropriate IOReturn code
- *
- * @discussion
- * Internal reporter method to allow a subclass to update channel
- * data when updateReport() is called. This routine handles the
- * common case of a subclass needing to refresh state in response
- * to IOReporter::updateReport(). It saves the complexity of
- * parsing the full parameters to IOReporter::updateReport().
- *
- * The IOReporter base class implementation does not do anything
- * except return success.
- *
- * Locking: IOReporter::updateReport() takes the reporter lock,
- * determines the indices involved, calls this function, and
- * then proceeds to provide values to the caller. If subclasses
- * need to call this routine directly, they must ensure that
- * the reporter (data) lock is held: see
- * IOReporter::lockReporter().
- */
- virtual IOReturn updateChannelValues(int channel_index);
-
-
-/*! @function IOReporter::updateReportChannel
- * @abstract Internal method to extract channel data to a destination
- *
- * @param channel_index - offset into internal elements array
- * @param nElements - incremented by the number of IOReportElements added
- * @param destination - pointer to the destination buffer
- * @result IOReturn code
- *
- * @discussion
- * updateReportChannel() is used to extract a single channel's
- * data to the updateReport() destination.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- IOReturn updateReportChannel(int channel_index,
- int *nElements,
- IOBufferMemoryDescriptor *destination);
-
-
-/*! @function IOReporter::setElementValues
- * @abstract Atomically update a specific member of _elements[].
- *
- * @param element_index - index of the _element in internal array
- * @param values - IORepoterElementValues to replace those at _elements[idx]
- * @param record_time - optional mach_absolute_time to be used for metadata
- * @result IOReturn code
- *
- * @discussion
- * element_index can be obtained from getFirstElementIndex(). If
- * record_time is not provided, IOReporter::setElementValues() will
- * fetch the current mach_absolute_time. If the current time is
- * already known, it is more efficient to pass it along.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn setElementValues(int element_index,
- IOReportElementValues *values,
- uint64_t record_time = 0);
-
-/*! @function IOReporter::getElementValues
- * @abstract Internal method to directly access the values of an element
- *
- * @param element_index - index of the _element in internal array
- * @result A pointer to the element values requested or NULL on failure
- *
- * @discussion Locking: Caller must ensure that the reporter (data) lock is held.
- * The returned pointer is only valid until unlockReporter() is called.
- */
- virtual const IOReportElementValues* getElementValues(int element_index);
-
-/*! @function IOReporter::getFirstElementIndex
- * @abstract Returns the first element index for a channel
- *
- * @param channel_id - ID of the channel
- * @param element_index - pointer to the returned element_index
- * @result appropriate IOReturn code
- *
- * @discussion
- * For efficiently and thread-safely reading _elements
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn getFirstElementIndex(uint64_t channel_id,
- int *element_index);
-
-/*! @function IOReporter::getChannelIndex
- * @abstract Returns the index of a channel from internal data structures
- *
- * @param channel_id - ID of the channel
- * @param channel_index - pointer to the returned element_index
- * @result appropriate IOReturn code
- *
- * @discussion
- * For efficiently and thread-safely reading channels
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn getChannelIndex(uint64_t channel_id,
- int *channel_index);
-
-/*! @function IOReporter::getChannelIndices
- * @abstract Returns the index of a channel and its corresponding
- * first element index from internal data structure
- *
- * @param channel_id - ID of the channel
- * @param channel_index - pointer to the returned channel_index
- * @param element_index - pointer to the returned element_index
- * @result appropriate IOReturn code
- *
- * @discussion
- * For efficiently and thread-safely reading channel elements.
- * It is commonly useful to get access to both channel and element
- * indices togther. This convenience method allows sub-classes to
- * get both indices simultaneously.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn getChannelIndices(uint64_t channel_id,
- int *channel_index,
- int *element_index);
-
-/*! @function IOReporter::copyElementValues
- * @abstract Copies the values of an internal element to *elementValues
- *
- * @param element_index - Index of the element to return values from
- * @param elementValues - For returning the content of element values
- * @result Returns the content of an element
- *
- * @discussion
- * For efficiently and thread-safely reading _elements.
- * May need to find the index of the element first.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn copyElementValues(int element_index,
- IOReportElementValues *elementValues);
-
-/*! @function IOReporter::legendWith
- * @abstract Internal method to help create legend entries
- *
- * @param channelIDs - array of uint64_t channels IDs.
- * @param channelNames - parrallel array of const char* channel names
- * @param channelCount - number of channels, and size of channelIDs and channelNames
- * @param channelType - the type of all channels in this legend
- * @param unit - The unit for the quantity recorded by this reporter object
- *
- * @result An IOReportLegendEntry object or NULL on failure
- *
- * @discussion
- * This static method is variant of IOReporter::legendWith that takes
- * raw arrays for the channelIDs and channelNames. It supports the static
- * createLegend() methods for the IOReporter subclasses.
- *
- * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
- */
- static OSPtr<IOReportLegendEntry> legendWith(const uint64_t *channelIDs,
- const char **channelNames,
- int channelCount,
- IOReportChannelType channelType,
- IOReportUnit unit);
-
-// private methods
-private:
-/*! @function IOReporter::copyChannelIDs
- * @abstract return an an OSArray of the reporter's
- * channel IDs
- *
- * @result An OSArray of the repoter's channel ID's as OSNumbers
- *
- * @discussion
- * This method is an internal helper function used to prepare a
- * legend entry. It encapsulates the channel IDs in OSNumbers and
- * aggregates them in an OSArray used when building the IOReportLegend
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- OSPtr<OSArray> copyChannelIDs(void);
-
-/*! @function IOReporter::legendWith
- * @abstract Internal method to help create legend entries
- *
- * @param channelIDs - OSArray of OSNumber(uint64_t) channels IDs.
- * @param channelNames - parrallel OSArray of OSSymbol(rich names)
- * @param channelType - the type of all channels in this legend
- * @param unit - The unit for the quantity recorded by this reporter object
- *
- * @result An IOReportLegendEntry object or NULL on failure
- *
- * @discussion
- * This static method is the main legend creation function. It is called by
- * IOReporter sub-classes and is responsible for building an
- * IOReportLegendEntry corresponding to this reporter object.
- * This legend entry may be extended by the sub-class of IOReporter if
- * required.
- *
- * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
- */
- static OSPtr<IOReportLegendEntry> legendWith(OSArray *channelIDs,
- OSArray *channelNames,
- IOReportChannelType channelType,
- IOReportUnit unit);
-
-// protected instance variables (want to get rid of these)
-protected:
- IOReportChannelType _channelType;
- uint64_t _driver_id; // driver reporting data
-
-// IOHistogramReporter accesses these; need to re-do its instantiation
- IOReportElement *_elements;
- int *_enableCounts; // refcount kIOReportEnable/Disable
- uint16_t _channelDimension;// Max channel size
- int _nElements;
- int _nChannels; // Total Channels in this reporter
- OSPtr<OSArray> _channelNames;
-
-// MUST be protected because check is a macro!
- bool _reporterIsLocked;
- bool _reporterConfigIsLocked;
-
-// Required for swapping inside addChannel
- IOReportElement *_swapElements;
- int *_swapEnableCounts;
-
-// private instance variables
-private:
- IOReportUnit _unit;
-
- int _enabled;// 'enabled' if _enabled > 0
-
- IOLock *_configLock;
- IOInterruptState _interruptState;
- IOSimpleLock *_reporterLock;
-};
-
-
-/************************************/
-/***** 3. IOReporter Subclasses *****/
-/************************************/
-
-/*!
- * @class IOSimpleReporter
- * @abstract Report simple integers
- * @discussion
- * Each IOSimpleReporter can have an arbitrary number of channels,
- * each publishing a single integer value at any given time.
- */
-
-class IOSimpleReporter : public IOReporter
-{
- OSDeclareDefaultStructors(IOSimpleReporter);
-
-public:
-
-/*! @function IOSimpleReporter::with
- * @abstract create an initialized simple reporter
- *
- * @param reportingService - IOService associated with all channels
- * @param categories - The category in which the report should be classified
- * @param unit - The unit for the quantity recorded by the reporter object
- * @result On success, an instance of IOSimpleReporter, else NULL
- *
- * @discussion
- * Creates an instance of IOSimpleReporter object
- *
- * Locking: SAFE to call concurrently (no static globals), MAY BLOCK.
- */
- static OSPtr<IOSimpleReporter> with(IOService *reportingService,
- IOReportCategories categories,
- IOReportUnit unit);
-
-/*! @function IOSimpleReporter::setValue
- * @abstract Thread safely set a channel's value
- *
- * @param channel_id - ID of the channel for which the value needs to be set
- * @param value - New channel value
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Updates the value of a channel to the provided value.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setValue(uint64_t channel_id,
- int64_t value);
-
-/*! @function IOSimpleReporter::incrementValue
- * @abstract Thread safely increment a channel's value by a given amount
- *
- * @param channel_id - ID of the channel for which the value needs to be incremented
- * @param increment - Amount to be added to the current channel value
- * @result Appropriate IOReturn code
- * @discussion
- * Increments the value of the channel ID by the provided amount.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn incrementValue(uint64_t channel_id,
- int64_t increment);
-
-/*! @function IOSimpleReporter::getValue
- * @abstract Thread safely access a channel value
- *
- * @param channel_id - ID of the channel to get a value from
- * @result Returns the current value stored in the channel
- * @discussion
- * Accessor method to a channel's current stored value
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- int64_t getValue(uint64_t channel_id);
-
-/*! @function IOSimpleReporter::createLegend
- * @abstract Creates a legend entry for an IOSimpleReporter
- *
- * @param channelIDs - array of uint64_t channels IDs.
- * @param channelNames - parrallel array of const char* channel names
- * @param channelCount - number of channels, and size of channelIDs and channelNames
- * @param categories - The category in which the report should be classified
- * @param unit - The unit for the quantity recorded by the reporter object
- *
- * @result An IOReportLegendEntry object or NULL on failure
- *
- * @discussion
- * This static method supports creating a legend entry for an IOSimpleReporter
- * without actually having an IOSimpleReporter instance.
- * This can be used to lazily create IOReporters in IOService::configureReport()
- * rather than during driver initialization.
- */
- static OSPtr<IOReportLegendEntry> createLegend(const uint64_t *channelIDs,
- const char **channelNames,
- int channelCount,
- IOReportCategories categories,
- IOReportUnit unit);
-
-protected:
-
-/*! @function IOSimpleReporter::initWith
- * @abstract instance method implementation called by IOSimpleReporter::with
- *
- * @discussion
- * See description of parameters above
- *
- * Locking: same-instance concurrency UNSAFE
- */
- virtual bool initWith(IOService *reportingService,
- IOReportCategories categories,
- IOReportUnit unit);
-
-private:
-};
-
-
-
-/*!
- * @class IOStateReporter
- * @abstract Report state machine data
- * @discussion
- * Each IOStateReporter can report information for an arbitrary number
- * of similar state machines. All must have the same number of states.
- */
-class IOStateReporter : public IOReporter
-{
- OSDeclareDefaultStructors(IOStateReporter);
-
-public:
-
-/*! @function IOStateReporter::with
- * @abstract State reporter static creation method
- *
- * @param reportingService - The I/O Kit service for this reporter's channels
- * @param categories - The categories for this reporter's channels
- * @param nstates - Maximum number of states for this reporter's channels
- * @param unit - optional parameter if using override/increment...()
- * @result on success, an IOStateReporter instance, else NULL
- *
- * @discussion
- * Creates an instance of IOStateReporter. The default time scale
- * is the current system's notion of mach_absolute_time(). Using a
- * non-default time scale requires the use of
- * override/incrementChannelState() instead of setState().
- * setState() always updates using mach_absolute_time().
- *
- * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
- */
- static OSPtr<IOStateReporter> with(IOService *reportingService,
- IOReportCategories categories,
- int nstates,
- IOReportUnit unit = kIOReportUnitHWTicks);
-
-/*! @function IOStateReporter::setStateID
- * @abstract Assign a non-default ID to a state
- *
- * @param channel_id - ID of channel containing the state in question
- * @param state_index - index of state to give an ID: [0..(nstates-1)]
- * @param state_id - 64-bit state ID, for ASCII, use IOREPORT_MAKEID
- *
- * @result Appropriate IOReturn code
- *
- * @discussion
- * By default, IOStateReporter identifies its channel states by
- * numbering them from 0 to <nstates - 1>. If setStateID is not
- * called to customize the state IDs, the numbered states will be
- * kept throughout the life of the object and it is safe to reference
- * those states by their indices. Otherwise, after setStateID() has
- * been called, the ordering of states is no longer guaranteed and
- * the client must reference states by their assigned state ID.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setStateID(uint64_t channel_id,
- int state_index,
- uint64_t state_id);
-
-/*! @function IOStateReporter::setChannelState
- * @abstract Updates the current state of a channel to a new state
- *
- * @param channel_id - ID of the channel which is updated to a new state
- * @param new_state_id - ID of the target state for this channel
- * @param last_intransition - deprecated: time of most recent entry
- * @param prev_state_residency - deprecated: time spent in previous state
- * @result Appropriate IOReturn code
- *
- * @discussion
- * setChannelState() updates the amount of time spent in the previous
- * state (if any) and increments the number of transitions into the
- * new state. It also sets the target state's last transition time to
- * the current time and enables internal time-keeping for the channel.
- * In this mode, calls like getStateResidencyTime() and updateReport()
- * automatically update a channel's time in state.
- *
- * new_state_id identifies the target state as initialized
- * (0..<nstates-1>) or as configured by setStateID().
- *
- * Drivers wishing to compute and report their own time in state
- * should use incrementChannelState() or overrideChannelState(). It
- * is not currently possible for a driver to synchronize with the
- * automatic time-keeping enabled by setChannelState(). The
- * 4-argument version of setChannelState() is thus impossible to
- * use correctly. In the future, there may be a setChannelState()
- * which accepts a last_intransition parameter and uses it to
- * automatically calculate time in state (ERs -> IOReporting / X).
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setChannelState(uint64_t channel_id,
- uint64_t new_state_id,
- uint64_t last_intransition,
- uint64_t prev_state_residency) __deprecated;
-
-/*! @function IOStateReporter::setChannelState
- * @abstract Updates the current state of a channel to a new state
- *
- * @param channel_id - ID of the channel which is updated to a new state
- * @param new_state_id - ID of the target state for this channel
- * @result Appropriate IOReturn code
- *
- * @discussion
- * setChannelState() updates the amount of time spent in the previous
- * state (if any) and increments the number of transitions into the
- * new state. It also sets the target state's last transition time to
- * the current time and enables internal time-keeping for the channel.
- * In this mode, calls like getStateResidencyTime() and updateReport()
- * automatically update a channel's time in state.
- *
- * new_state_id identifies the target state as initialized
- * (0..<nstates-1>) or as configured by setStateID().
- *
- * Drivers wishing to compute and report their own time in state
- * should use incrementChannelState() or overrideChannelState(). It
- * is not currently possible for a driver to synchronize with the
- * automatic time-keeping enabled by setChannelState(). The
- * 4-argument version of setChannelState() is thus impossible to
- * use correctly. In the future, there may be a setChannelState()
- * which accepts a last_intransition parameter and uses it to
- * automatically calculate time in state (ERs -> IOReporting / X).
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setChannelState(uint64_t channel_id,
- uint64_t new_state_id);
-
-
-/*! @function IOStateReporter::setState
- * @abstract Updates state for single channel reporters
- *
- * @param new_state_id - New state for the channel
- * @result Appropriate IOReturn code.
- *
- * @discussion
- * setState() is a convenience method for single-channel state
- * reporter instances. An error will be returned if the reporter
- * in question has more than one channel.
- *
- * See further discussion at setChannelState().
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setState(uint64_t new_state_id);
-
-/*! @function IOStateReporter::setState
- * @abstract Updates state for single channel reporters
- *
- * @param new_state_id - New state for the channel
- * @param last_intransition - deprecated: time of most recent entry
- * @param prev_state_residency - deprecated: spent in previous state
- * @result Appropriate IOReturn code.
- *
- * @discussion
- * setState() is a convenience method for single-channel state
- * reporter instances. An error will be returned if the reporter
- * in question has more than one channel.
- *
- * See further discussion at setChannelState().
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setState(uint64_t new_state_id,
- uint64_t last_intransition,
- uint64_t prev_state_residency) __deprecated;
-
-/*! @function IOStateReporter::overrideChannelState
- * @abstract Overrides state data for a channel with passed arguments
- *
- * @param channel_id - ID of the channel which state is to be updated
- * @param state_id - state id for the channel
- * @param time_in_state - time used as new total time in state
- * @param intransitions - total number of transitions into state
- * @param last_intransition - mach_absolute_time of most recent entry (opt)
- * @result Appropriate IOReturn code
- *
- * @discussion
- * overrideChannelState() sets a particular state's time in state
- * and transition count to the values provided. The optional
- * last_intransition records the last time the channel transitioned
- * into the given state. Passing 0 for time_in_state and
- * intransitions will force the current values to 0. Passing 0
- * for last_intransition for all states will disable the notion
- * of a channel's "current state."
- *
- * The most recent last_intransition (amongst all states in a channel)
- * logically determines the current state. If last_intransition is
- * not provided for any state, the channel will not report a current
- * For consistent results, it is important to either never specify
- * last_intransition or to always specify it.
- *
- * There is currently a bug in determining current state (13423273).
- * The IOReportMacros.h macros only update the state's metadata
- * timestamp and libIOReport only looks at the metadata timestamps
- * to determine the current state. Until that bug is fixed, whichever
- * state is updated most recently will be considered the "current"
- * state by libIOReport.
- *
- * ::setState()'s automatic "time in state" updates are not supported
- * when using overrideChannelState(). Clients must not use
- * overrideChannelState() on any channel that has ::setState() called
- * on it. Unlike with ::setState(), clients using
- * overrideChannelState() are responsible for ensuring that data is
- * up to date for updateReport() calls. The correct way to do this
- * is for a driver's ::updateReport() method to push the most up to
- * date values into the reporters before calling
- * super::updateReport().
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn overrideChannelState(uint64_t channel_id,
- uint64_t state_id,
- uint64_t time_in_state,
- uint64_t intransitions,
- uint64_t last_intransition = 0);
-
-/*! @function IOStateReporter::incrementChannelState
- * @abstract Updates state data for a channel with passed arguments
- *
- * @param channel_id - ID of the channel which state is to be updated
- * @param state_id - state id for the channel
- * @param time_in_state - time to be accumulated for time in state
- * @param intransitions - number of transitions into state to be added
- * @param last_intransition - mach_absolute_time of most recent entry (opt)
- * @result Appropriate IOReturn code
- *
- * @discussion
- * incrementChannelState() adds time_in_state and intransitions
- * to the current values stored for a particular state. If provided,
- * last_intransition overwrites the time the state was most recently
- * entered. Passing 0 for time_in_state and intransitions will have
- * no effect. Passing 0 for last_intransition for all states will
- * disable the notion of a channel's "current state."
- *
- * The most recent last_intransition (amongst all states in a channel)
- * logically determines the current state. If last_intransition is
- * not provided for any state, the channel will not report a current
- * For consistent results, it is important to either never specify
- * last_intransition or to always specify it.
- *
- * There is currently a bug in determining current state (13423273).
- * The IOReportMacros.h macros only update the state's metadata
- * timestamp and libIOReport only looks at the metadata timestamps
- * to determine the current state. Until that bug is fixed, whichever
- * state is updated most recently will be considered the "current"
- * state by libIOReport.
- *
- * ::setState()'s automatic "time in state" updates are not supported
- * when using incrementChannelState(). Clients must not use
- * incrementChannelState() on any channel that has ::setState()
- * called on it. Unlike with ::setState(), clients using
- * incrementChannelState() are responsible for ensuring that data
- * is up to date for updateReport() calls. The correct way to do
- * this is for a driver's ::updateReport() method to push the most
- * up to date values into the reporters before calling
- * super::updateReport().
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn incrementChannelState(uint64_t channel_id,
- uint64_t state_id,
- uint64_t time_in_state,
- uint64_t intransitions,
- uint64_t last_intransition = 0);
-
-/*! @function IOStateReporter::setStateByIndices
- * @abstract update a channel state without validating channel_id
- *
- * @param channel_index - 0..<nChannels>, available from getChannelIndex()
- * @param new_state_index - New state (by index) for the channel
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Similar to setState(), setStateByIndices() sets a channel's state
- * without searching for the channel or state IDs. It will perform
- * bounds checking, but relies on the caller to properly indicate
- * the indices of the channel and state. Clients can rely on channels
- * being added to IOStateReporter in order: the first channel will
- * have index 0, the second index 1, etc. Like ::setState(),
- * "time in state" calculations are handled automatically.
- *
- * setStateByIndices() is faster than than setChannelState(), but
- * it should only be used where the latter's performance overhead
- * might be a problem. For example, many channels in a single
- * reporter and high-frequency state changes.
- *
- * Drivers wishing to compute and report their own time in state
- * should use incrementChannelState() or overrideChannelState(). It
- * is not currently possible for a driver to synchronize with the
- * automatic time-keeping enabled by setStateByIndices(). The
- * 4-argument version of setChannelState() is thus impossible to
- * use correctly. In the future, there may be a setChannelState()
- * which accepts a last_intransition parameter and uses it to
- * automatically calculate time in state (ERs -> IOReporting / X).
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setStateByIndices(int channel_index,
- int new_state_index);
-
-/*! @function IOStateReporter::setStateByIndices
- * @abstract update a channel state without validating channel_id
- *
- * @param channel_index - 0..<nChannels>, available from getChannelIndex()
- * @param new_state_index - New state (by index) for the channel
- * @param last_intransition - deprecated: time of most recent entry
- * @param prev_state_residency - deprecated: time spent in previous state
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Similar to setState(), setStateByIndices() sets a channel's state
- * without searching for the channel or state IDs. It will perform
- * bounds checking, but relies on the caller to properly indicate
- * the indices of the channel and state. Clients can rely on channels
- * being added to IOStateReporter in order: the first channel will
- * have index 0, the second index 1, etc. Like ::setState(),
- * "time in state" calculations are handled automatically.
- *
- * setStateByIndices() is faster than than setChannelState(), but
- * it should only be used where the latter's performance overhead
- * might be a problem. For example, many channels in a single
- * reporter and high-frequency state changes.
- *
- * Drivers wishing to compute and report their own time in state
- * should use incrementChannelState() or overrideChannelState(). It
- * is not currently possible for a driver to synchronize with the
- * automatic time-keeping enabled by setStateByIndices(). The
- * 4-argument version of setChannelState() is thus impossible to
- * use correctly. In the future, there may be a setChannelState()
- * which accepts a last_intransition parameter and uses it to
- * automatically calculate time in state (ERs -> IOReporting / X).
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- IOReturn setStateByIndices(int channel_index,
- int new_state_index,
- uint64_t last_intransition,
- uint64_t prev_state_residency) __deprecated;
-
-/*! @function IOStateReporter::getStateInTransitions
- * @abstract Accessor method for count of transitions into state
- *
- * @param channel_id - ID of the channel
- * @param state_id - State of the channel
- * @result Count of transitions into the requested state.
- *
- * @discussion
- * Some clients may need to consume internally the data aggregated by the
- * reporter object. This method allows a client to retrieve the count of
- * transitions into the requested state for the channel_id.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- uint64_t getStateInTransitions(uint64_t channel_id,
- uint64_t state_id);
-
-/*! @function IOStateReporter::getStateResidencyTime
- * @abstract Accessor method for time spent in a given state
- *
- * @param channel_id - ID of the channel
- * @param state_id - State of the channel
- * @result Absolute time spent in specified state
- *
- * @discussion
- * Some clients may need to consume internally the data aggregated
- * by the by the reporter object. This method allows a client to
- * retrieve the absolute time a particular channel recorded as spent
- * in a specified state.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- uint64_t getStateResidencyTime(uint64_t channel_id,
- uint64_t state_id);
-
-/*! @function IOStateReporter::getStateLastTransitionTime
- * @abstract Accessor method for last time a transition occured
- *
- * @param channel_id - ID of the channel
- * @param state_id - State of the channel
- * @result Absolute time for when the last transition occured
- *
- * @discussion
- * Some clients may need to consume internally the data aggregated
- * by the by the reporter object. This method allows a client to
- * retrieve the absolute time stamp for when the last transition into
- * a specific state was recorded.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- uint64_t getStateLastTransitionTime(uint64_t channel_id, uint64_t state_id);
-
-/*! @function [DEPRECATED] IOStateReporter::getStateLastChannelUpdateTime
- * @abstract Deprecated accessor for last time a channel was auto-updated
- *
- * @param channel_id - ID of the channel
- * @result Absolute time for last time the channel was updated
- *
- * @discussion
- * If a channel has had ::setState() called on it, calls such as
- * getStateResidencyTime() or updateReport() will update time in the
- * current state and update an internal "last channel update time."
- * Because clients have no way to interlock with those methods, there
- * is no sensible way to use this method and it will be removed in
- * a future release.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- uint64_t getStateLastChannelUpdateTime(uint64_t channel_id) __deprecated;
-
-/*! @function IOStateReporter::createLegend
- * @abstract Creates a legend entry for an IOStateReporter
- *
- * @param channelIDs - array of uint64_t channels IDs.
- * @param channelNames - parrallel array of const char* channel names
- * @param channelCount - number of channels, and size of channelIDs and channelNames
- * @param nstates - Maximum number of states for this reporter's channels
- * @param categories - The category in which the report should be classified
- * @param unit - The unit for the quantity recorded by the reporter object
- *
- * @result An IOReportLegendEntry object or NULL on failure
- *
- * @discussion
- * This static method supports creating a legend entry for an IOStateReporter
- * without actually having an IOStateReporter instance.
- * This can be used to lazily create IOReporters in IOService::configureReport()
- * rather than during driver initialization.
- */
- static OSPtr<IOReportLegendEntry> createLegend(const uint64_t *channelIDs,
- const char **channelNames,
- int channelCount,
- int nstates,
- IOReportCategories categories,
- IOReportUnit unit);
-
-/*! @function IOStateReporter::free
- * @abstract Releases the object and all its resources.
- *
- * @discussion
- * ::free() assumes that init() has completed. Clients should use
- * the static ::with() methods to obtain fully-initialized reporter
- * instances.
- *
- * Locking: same-instance concurrency UNSAFE
- */
- virtual void free(void) APPLE_KEXT_OVERRIDE;
-
-protected:
-
-/*! @function IOStateReporter::initWith
- * @abstract Instance method implementation called by ::with
- *
- * @discussion
- * See description of parameters above
- */
- virtual bool initWith(IOService *reportingService,
- IOReportCategories categories,
- int16_t nstates, IOReportUnit unit);
-
-
-/*! @function IOStateReporter::handleSwapPrepare
- * @abstract _swap* = <IOStateReporter-specific per-channel buffers>
- * [see IOReporter::handle*Swap* for more info]
- */
- virtual IOReturn handleSwapPrepare(int newNChannels) APPLE_KEXT_OVERRIDE;
-
-/*!
- * @function IOStateReporter::handleAddChannelSwap
- * @abstract swap in IOStateReporter's variables
- */
- virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
- const OSSymbol *symChannelName) APPLE_KEXT_OVERRIDE;
-
-/*!
- * @function IOStateReporter::handleSwapCleanup
- * @abstract clean up unused buffers in _swap*
- */
- virtual void handleSwapCleanup(int swapNChannels) APPLE_KEXT_OVERRIDE;
-
-/*! @function IOStateReporter::updateChannelValues
- * @abstract Update accounting of time spent in current state
- *
- * @param channel_index - internal index of the channel
- * @result appropriate IOReturn code
- *
- * @discussion
- * Internal State reporter method to account for the time spent in
- * the current state when updateReport() is called on the reporter's
- * channels.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn updateChannelValues(int channel_index) APPLE_KEXT_OVERRIDE;
-
-/*! @function IOStateReporter::handleSetStateByIndices
- * @abstract update a channel state without validating channel_id
- *
- * @param channel_index - 0..<nChannels>, available from getChannelIndex()
- * @param new_state_index - New state for the channel
- * @param last_intransition - to remove: time of most recent entry
- * @param prev_state_residency - to remove: time spent in previous state
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Locked version of IOReporter::setStateByIndices(). This method may be
- * overriden by sub-classes.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn handleSetStateByIndices(int channel_index,
- int new_state_index,
- uint64_t last_intransition,
- uint64_t prev_state_residency);
-
-/*! @function IOStateReporter::handleSetStateID
- * @abstract Assign a non-default ID to a state
- *
- * @param channel_id - ID of channel containing the state in question
- * @param state_index - index of state to give an ID: [0..(nstates-1)]
- * @param state_id - 64-bit state ID, for ASCII, use IOREPORT_MAKEID
- *
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Locked version of IOReporter::setStateID(). This method may be
- * overriden by sub-classes
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn handleSetStateID(uint64_t channel_id,
- int state_index,
- uint64_t state_id);
-
-/*! @function IOStateReporter::handleOverrideChannelStateByIndices
- * @abstract Overrides state data for a channel with passed arguments
- *
- * @param channel_index - index of the channel which state is to be updated
- * @param state_index - index of the state id for the channel
- * @param time_in_state - time used as new total time in state
- * @param intransitions - total number of transitions into state
- * @param last_intransition - mach_absolute_time of most recent entry (opt)
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Locked version of IOReporter::overrideChannelState(). This method
- * may be overriden by sub-classes.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn handleOverrideChannelStateByIndices(int channel_index,
- int state_index,
- uint64_t time_in_state,
- uint64_t intransitions,
- uint64_t last_intransition = 0);
-
-/*! @function IOStateReporter::handleIncrementChannelStateByIndices
- * @abstract Updates state data for a channel with passed arguments
- *
- * @param channel_index - index of the channel which state is to be updated
- * @param state_index - index of the state id for the channel
- * @param time_in_state - time used as new total time in state
- * @param intransitions - total number of transitions into state
- * @param last_intransition - mach_absolute_time of most recent entry (opt)
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Locked version of IOReporter::incrementChannelState(). This method
- * may be overriden by sub-classes.
- *
- * Locking: Caller must ensure that the reporter (data) lock is held.
- */
- virtual IOReturn handleIncrementChannelStateByIndices(int channel_index,
- int state_index,
- uint64_t time_in_state,
- uint64_t intransitions,
- uint64_t last_intransition = 0);
-private:
-
- int *_currentStates; // current states (per chonnel)
- uint64_t *_lastUpdateTimes; // most recent auto-update
-
-// Required for swapping inside addChannel
- int *_swapCurrentStates;
- uint64_t *_swapLastUpdateTimes;
-
- enum valueSelector {
- kInTransitions,
- kResidencyTime,
- kLastTransitionTime
- };
- uint64_t _getStateValue(uint64_t channel_id,
- uint64_t state_id,
- enum valueSelector value);
-
- IOReturn _getStateIndices(uint64_t channel_id,
- uint64_t state_id,
- int *channel_index,
- int *state_index);
-};
-
-
-/*!
- * @class IOHistogramReporter
- * @abstract Report histograms of values
- * @discussion
- * Each IOHistogramReporter can report one histogram representing
- * how a given value has changed over time.
- */
-class IOHistogramReporter : public IOReporter
-{
- OSDeclareDefaultStructors(IOHistogramReporter);
-
-public:
-/*! @function IOHistogramReporter::with
- * @abstract Initializes the IOHistogramReporter instance variables and data structures
- *
- * @param reportingService - The I/O Kit service for this reporter's channels
- * @param categories - The categories in which the report should be classified
- * @param channelID - uint64_t channel identifier
- * @param channelName - rich channel name as char*
- * @param unit - The unit for the quantity recorded by the reporter object
- * @param nSegments - Number of segments to be extracted from the config data structure
- * @param config - Histograms require the caller to pass a configuration by segments
- * @result an instance of the IOSimpleReporter object or NULL on error
- *
- * @discussion
- * Creates an instance of histogram reporter object.
- *
- * FIXME: need more explanation of the config
- *
- * IOHistogramReporter currently only supports a single channel.
- *
- *
- */
- static OSPtr<IOHistogramReporter> with(IOService *reportingService,
- IOReportCategories categories,
- uint64_t channelID,
- const char *channelName,
- IOReportUnit unit,
- int nSegments,
- IOHistogramSegmentConfig *config);
-
-/*! @function IOHistogramReporter::addChannel
- * @abstract Override IOReporter::addChannel(*) to return an error
- *
- * @result kIOReturnUnsupported - doesn't support adding channels
- */
- IOReturn
- addChannel(__unused uint64_t channelID, __unused const char *channelName = NULL)
- {
- return kIOReturnUnsupported;
- }
-
-/*! @function IOHistogramReporter::overrideBucketValues
- * @abstract Override values of a bucket at specified index
- *
- * @param index - index of bucket to override
- * @param bucket_hits - new bucket hits count
- * @param bucket_min - new bucket minimum value
- * @param bucket_max - new bucket maximum value
- * @param bucket_sum - new bucket sum
- * @result Appropriate IOReturn code
- *
- * @discussion
- * Replaces data in the bucket at the specified index with the data pointed
- * to by bucket. No sanity check is performed on the data. If the index
- * is out of bounds, kIOReturnBadArgument is returned.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
-
- IOReturn overrideBucketValues(unsigned int index,
- uint64_t bucket_hits,
- int64_t bucket_min,
- int64_t bucket_max,
- int64_t bucket_sum);
-
-/*! @function IOHistogramReporter::tallyValue
- * @abstract Add a new value to the histogram
- *
- * @param value - new value to add to the histogram
- * @result the index of the affected bucket, or -1 on error
- *
- * @discussion
- * The histogram reporter determines in which bucket the value
- * falls and increments it. The lowest and highest buckets
- * extend to negative and positive infinity, respectively.
- *
- * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
- */
- int tallyValue(int64_t value);
-
-/*! @function IOHistogramReporter::createLegend
- * @abstract Creates a legend entry for an IOStateReporter
- *
- * @param channelID - uint64_t channel identifier
- * @param channelName - rich channel name as char*
- * @param segmentCount - Number of segments to be extracted from the config data structure
- * @param config - Histograms require the caller to pass a configuration by segments
- * @param categories - The category in which the report should be classified
- * @param unit - The unit for the quantity recorded by the reporter object
- *
- * @result An IOReportLegendEntry object or NULL on failure
- *
- * @discussion
- * This static method supports creating a legend entry for an IOStateReporter
- * without actually having an IOStateReporter instance.
- * This can be used to lazily create IOReporters in IOService::configureReport()
- * rather than during driver initialization.
- */
- static OSPtr<IOReportLegendEntry> createLegend(const uint64_t channelID,
- const char *channelName,
- int segmentCount,
- IOHistogramSegmentConfig *config,
- IOReportCategories categories,
- IOReportUnit unit);
-
-/*! @function IOHistogramReporter::free
- * @abstract Releases the object and all its resources.
- *
- * @discussion
- * ::free() assumes that init() has completed. Clients should use
- * the static ::with() methods to obtain fully-initialized reporter
- * instances.
- *
- * Locking: same-instance concurrency UNSAFE
- */
- virtual void free(void) APPLE_KEXT_OVERRIDE;
-
-protected:
-
-/*! @function IOHistogramReporter::initWith
- * @abstract instance method implementation called by ::with
- *
- * @discussion
- * See description of parameters above
- */
- virtual bool initWith(IOService *reportingService,
- IOReportCategories categories,
- uint64_t channelID,
- const OSSymbol *channelName,
- IOReportUnit unit,
- int nSegments,
- IOHistogramSegmentConfig *config);
-
-/*! @function IOHistogramReporter::handleCreateLegend
- * @abstract Builds an IOReporting legend entry representing the channels of this reporter.
- *
- * @result An IOReportLegendEntry or NULL on failure
- *
- * @discussion
- * The returned legend entry may be appended to kIOReportLegendKey
- * to be published by the caller in the IORegistry. See the
- * IOReportLegend class for more details.
- *
- * Locking: same-instance concurrency SAFE, MAY BLOCK
- */
- OSPtr<IOReportLegendEntry> handleCreateLegend(void) APPLE_KEXT_OVERRIDE;
-
-
-private:
-
- int _segmentCount;
- int64_t *_bucketBounds;
- int _bucketCount;
- IOHistogramSegmentConfig *_histogramSegmentsConfig;
-};
-
-
-/***********************************/
-/***** 4. IOReportLegend Class *****/
-/***********************************/
-
-/*!
- * @class IOReportLegend
- * @abstract combine legend entries into a complete legend
- * @discussion
- * IOReportLegend adds metadata to legend entries and combines them
- * into a single OSArray that can be published under the
- * kIOReportLegendKey property in the I/O Kit registry.
- */
-class IOReportLegend : public OSObject
-{
- OSDeclareDefaultStructors(IOReportLegend);
-
-public:
-/*! @function IOReportLegend::with
- * @abstract Create an instance of IOReportLegend
- *
- * @param legend - OSArray of the legend possibly already present in registry
- * @result an instance of IOReportLegend, or NULL on failure
- *
- * @discussion
- * An IOReporting legend (an OSArray of legend entries) may be already
- * present in the IORegistry. Thus the recommended way to publish
- * new entries is to append to any existing array as follows:
- * 1. call getProperty(kIOReportLegendKey) to get an existing legend.
- *
- * 2a. If it exists
- * - OSDynamicCast to OSArray
- * - and pass it to ::with()
- * IOReportLegend *legendMaker = IOReportLegend::with(legend);
- * The provided array is retained by IOReportLegend.
- *
- * 2b. If no legend already exists in the registry, pass NULL
- * IOReportLegend *legend = IOReportLegend::with(NULL);
- * This latter invocation will cause IOReportLegend to create a new
- * array internally (also holding one reference).
- *
- * At the cost of some registry churn, the static
- * IOReportLegend::addReporterLegend() will handle the above, removing
- * the need for any direct use of the IOReportLegend class.
- */
- static OSPtr<IOReportLegend> with(OSArray *legend);
-
-/*! @function IOReportLegend::addLegendEntry
- * @abstract Add a new legend entry
- *
- * @param legendEntry - entry to be added to the internal legend array
- * @param groupName - primary group name for this entry
- * @param subGroupName - secondary group name for this entry
- * @result appropriate IOReturn code
- *
- * @discussion
- * The entry will be retained as an element of the internal array.
- * Legend entries are available from reporter objects. Entries
- * represent some number of channels with similar properties (such
- * as group and sub-group). Multiple legend entries with the same
- * group names will be aggregated in user space.
- *
- * Drivers that instantiate their reporter objects in response to
- * IOService::configureReport(kIOReportDisable) will need to create
- * temporary reporter objects for the purpose of creating their
- * legend entries. User-space legends are tracked by 12836893.
- */
- IOReturn addLegendEntry(IOReportLegendEntry *legendEntry,
- const char *groupName,
- const char *subGroupName);
-
-/*! @function IOReportLegend::addReporterLegend
- * @abstract Add a legend entry from a reporter object
- *
- * @param reporter - IOReporter to use to extract and append the legend
- * @param groupName - primary group name for this entry
- * @param subGroupName - secondary group name for this entry
- * @result appropriate IOReturn code
- *
- * @discussion
- * An IOReportLegendEntry will be created internally to this method from
- * the IOReporter object passed in argument. The entry will be released
- * internally after being appended to the IOReportLegend object.
- * Legend entries are available from reporter objects. Entries
- * represent some number of channels with similar properties (such
- * as group and sub-group). Multiple legend entries with the same
- * group names will be aggregated in user space.
- *
- * Drivers that instantiate their reporter objects in response to
- * IOService::configureReport(kIOReportDisable) will need to create
- * temporary reporter objects for the purpose of creating their
- * legend entries. User-space legends are tracked by 12836893.
- *
- * Locking: same-reportingService and same-IORLegend concurrency UNSAFE
- */
- IOReturn addReporterLegend(IOReporter *reporter,
- const char *groupName,
- const char *subGroupName);
-
-/*! @function IOReportLegend::addReporterLegend
- * @abstract Add a legend entry from a reporter object
- *
- * @param reportingService - IOService data provider into the reporter object
- * @param reporter - IOReporter to use to extract and append the legend
- * @param groupName - primary group name for this entry
- * @param subGroupName - secondary group name for this entry
- * @result appropriate IOReturn code
- *
- * @discussion
- * An IOReportLegendEntry will be created internally to this method from
- * the IOReporter object passed in argument. The entry will be released
- * internally after being appended to the IOReportLegend object.
- * Legend entries are available from reporter objects. Entries
- * represent some number of channels with similar properties (such
- * as group and sub-group). Multiple legend entries with the same
- * group names will be aggregated in user space.
- *
- * Drivers that instantiate their reporter objects in response to
- * IOService::configureReport(kIOReportDisable) will need to create
- * temporary reporter objects for the purpose of creating their
- * legend entries. User-space legends are tracked by 12836893.
- *
- * The static version of addReporterLegend adds the reporter's legend
- * directly to reportingService's kIOReportLegendKey. It is not
- * possible to safely update kIOReportLegendKey from multiple threads.
- *
- * Locking: same-reportingService and same-IORLegend concurrency UNSAFE
- */
- static IOReturn addReporterLegend(IOService *reportingService,
- IOReporter *reporter,
- const char *groupName,
- const char *subGroupName);
-
-/*! @function IOReportLegend::getLegend
- * @abstract Accessor method to get the legend array
- *
- * @result Returns the OSObject holding the legend to be published by the driver
- * @discussion
- * This array will include all legend entries added to the object.
- */
- OSArray* getLegend(void);
-
-/*! @function IOReportLegend::free
- * @abstract Frees the IOReportLegend object
- *
- * @discussion
- * ::free() cleans up the reporter and anything it allocated.
- *
- * ::free() releases the internal array (which was either passed
- * to ::with() or created as a result of ::with(NULL)). Assuming
- * the caller extracted the array with getLegend() and published it
- * in the I/O Kit registry, its ownership will now be with the
- * registry.
- */
- void free(void) APPLE_KEXT_OVERRIDE;
-
-
-
-protected:
-
-private:
-
- OSPtr<OSArray> _reportLegend;
-
- IOReturn initWith(OSArray *legend);
-
-/*! @function IOReportLegend::organizeLegend
- * @abstract Sets up the legend entry, organizing it with group and sub-group names
- *
- * @param groupName - Primary group name
- * @param subGroupName - Secondary group name
- * @result IOReturn code
- */
- IOReturn organizeLegend(IOReportLegendEntry *legendEntry,
- const OSSymbol *groupName,
- const OSSymbol *subGroupName);
-
-// FUTURE POSSIBILITY (NOT IMPLEMENTED!)
-/*! @function IOReportLegend::createReporters
- * @abstract Creates as many IOReporter objects as the legend contains
- *
- * @param legend - OSArray legend object containing the description of all reporters
- * the driver is able to address
- * @param reporter - OSSet of reporter objects created by this call
- * @result IOReturn code kIOReturnSuccess if successful
- *
- * @discussion
- * NOT SUPPORTED at the time of writing
- * Convenience method to create all the driver's reporter objects from a legend.
- * Can be used when a legend is made public through the IORegistry but IOReporter
- * objects have not yet been created to save memory, waiting for observers.
- * Upon a call to configureReport via the IOService method, a driver could
- * create all reporter objects on the fly using this function.
- */
-// For Future IOReporterManager...
-// static IOReturn createReporters(requestedChannels, legend);
-};
-
-#endif /* ! _IOKERNEL_REPORTERS_H_ */