/*
 * 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_ */