xnu-2782.1.97.tar.gz

[apple/xnu.git] / iokit / IOKit / IOKernelReporters.h

/*
 * Copyright (c) 2012-2014 Apple Computer, 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 <IOKit/IOLib.h>
#include <IOKit/IOService.h>
#include <IOKit/IOLocks.h>
#include <IOKit/IOBufferMemoryDescriptor.h>

#include <IOKit/IOReportTypes.h>
#include <IOKit/IOKernelReportStructs.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,
                      IOReportUnits 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
*/
    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);
    

/*********************************/
/*** 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  channels - 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 channelID   ID of channel being added
    @param channelName   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 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  element_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);
    
// private methods
private:
/*! @function   IOReporter::copyChannelIDs
    @abstract   return an an OSArray of the reporter's 
                channel IDs
     
    @param  none
    @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.
*/
    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 IOReportLegendEntry* legendWith(OSArray *channelIDs,
                                           OSArray *channelNames,
                                           IOReportChannelType channelType,
                                           IOReportUnits 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
    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:
    IOReportUnits       _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 IOSimpleReporter* with(IOService *reportingService,
                                  IOReportCategories categories,
                                  IOReportUnits 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);
    
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,
                          IOReportUnits 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 IOStateReporter* with(IOService *reportingService,
                                 IOReportCategories categories,
                                 int nstates,
                                 IOReportUnits 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);

    IOReturn setChannelState(uint64_t channel_id,
                             uint64_t new_state_id,
                             uint64_t last_intransition,
                             uint64_t prev_state_residency) __deprecated;

/*! @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);
    
    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 - 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);
    
    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  channel_state - 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  channel_state - 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  channel_state - 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::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);
    
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, IOReportUnits unit);

    
/*! @function   IOStateReporter::handleSwapPrepare
    @abstract   _swap* = <IOStateReporter-specific per-channel buffers>

    @function   IOStateReporter::handleAddChannelSwap
    @abstract   swap in IOStateReporter's variables

    @function   IOStateReporter::handleSwapCleanup
    @abstract   clean up unused buffers in _swap* 
     
    [see IOReporter::handle*Swap* for more info]
*/
    virtual IOReturn handleSwapPrepare(int newNChannels);
    virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
                                          const OSSymbol *symChannelName);
    virtual void handleSwapCleanup(int swapNChannels);
    
/*! @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);

/*! @function   IOStateReporter::setStateByIndices
    @abstract   update a channel state without validating channel_id
     
    @param  channel_index - 0..<nChannels>, available from getChannelIndex()
    @param  new_state - 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::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
        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 - IOService instanciator and data provider into the reporter object
    @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 IOHistogramReporter* with(IOService *reportingService,
                                     IOReportCategories categories,
                                     uint64_t channelID,
                                     const char *channelName,
                                     IOReportUnits 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(uint64_t channelID, const char *channelName = NULL) {
            return kIOReturnUnsupported;
    }
        
/*! @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::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);

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,
                          IOReportUnits 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
*/
    IOReportLegendEntry* handleCreateLegend(void);
    
    
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 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  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.  This
        will result in serialized getProperty() and setProperty() calls
        on reportingService and should be avoided when many reporters
        objects are in use.
*/
    IOReturn addReporterLegend(IOReporter *reporter,
                               const char *groupName,
                               const char *subGroupName);
    
    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);
    

    
protected:
    
private:
    
    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
    
    @discussion
*/
    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_ */