X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/143464d58d2bd6378e74eec636961ceb0d32fb91..fe8ab488e9161c46dd9885d58fc52996dc0249ff:/iokit/IOKit/IOKernelReporters.h diff --git a/iokit/IOKit/IOKernelReporters.h b/iokit/IOKit/IOKernelReporters.h new file mode 100644 index 000000000..de529f405 --- /dev/null +++ b/iokit/IOKit/IOKernelReporters.h @@ -0,0 +1,1663 @@ +/* + * 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 + +#include +#include +#include +#include + +#include +#include + +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 ::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 = ; swapComplete = false; + if () 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 . 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..) 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.., 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* = + + @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.., 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_ */