/*
- * Copyright (c) 2012-2014 Apple Computer, Inc. All Rights Reserved.
+ * Copyright (c) 2012-2016 Apple Inc. All Rights Reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
Locking: same-instance concurrency UNSAFE
*/
- virtual void free(void);
+ virtual void free(void) APPLE_KEXT_OVERRIDE;
/*********************************/
@abstract call updateReport() on multiple IOReporter objects
@param reporters - OSSet of IOReporter objects
- @param channels - full list of channels to update
+ @param channelList - full list of channels to update
@param action - type/style of update
@param result - returned details about what was updated
@param destination - destination for this update (action-specific)
/*! @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
+ @param channel_id ID of channel being added
+ @param symChannelName optional channel name, in an allocated object
@result IOReturn code
@discussion
@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.
+ @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);
@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
+ @param channel_index - pointer to the returned element_index
@result appropriate IOReturn code
@discussion
@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
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::setChannelState
+ @abstract Updates the current state of a channel to a new state
+
+ @param channel_id - ID of the channel which is updated to a new state
+ @param new_state_id - ID of the target state for this channel
+ @result Appropriate IOReturn code
+
+ @discussion
+ setChannelState() updates the amount of time spent in the previous
+ state (if any) and increments the number of transitions into the
+ new state. It also sets the target state's last transition time to
+ the current time and enables internal time-keeping for the channel.
+ In this mode, calls like getStateResidencyTime() and updateReport()
+ automatically update a channel's time in state.
+
+ new_state_id identifies the target state as initialized
+ (0..<nstates-1>) or as configured by setStateID().
+
+ Drivers wishing to compute and report their own time in state
+ should use incrementChannelState() or overrideChannelState(). It
+ is not currently possible for a driver to synchronize with the
+ automatic time-keeping enabled by setChannelState(). The
+ 4-argument version of setChannelState() is thus impossible to
+ use correctly. In the future, there may be a setChannelState()
+ which accepts a last_intransition parameter and uses it to
+ automatically calculate time in state (ERs -> IOReporting / X).
+
+ Locking: same-instance concurrency SAFE, WILL NOT BLOCK
+*/
+ IOReturn setChannelState(uint64_t channel_id,
+ uint64_t new_state_id);
+
+
/*! @function IOStateReporter::setState
@abstract Updates state for single channel reporters
@param new_state_id - New state for the channel
- @param last_intransition - deprecated: time of most recent entry
- @param prev_state_residency - deprecated: spent in previous state
@result Appropriate IOReturn code.
@discussion
*/
IOReturn setState(uint64_t new_state_id);
+/*! @function IOStateReporter::setState
+ @abstract Updates state for single channel reporters
+
+ @param new_state_id - New state for the channel
+ @param last_intransition - deprecated: time of most recent entry
+ @param prev_state_residency - deprecated: spent in previous state
+ @result Appropriate IOReturn code.
+
+ @discussion
+ setState() is a convenience method for single-channel state
+ reporter instances. An error will be returned if the reporter
+ in question has more than one channel.
+
+ See further discussion at setChannelState().
+
+ Locking: same-instance concurrency SAFE, WILL NOT BLOCK
+*/
IOReturn setState(uint64_t new_state_id,
uint64_t last_intransition,
uint64_t prev_state_residency) __deprecated;
@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
+ @param new_state_index - New state (by index) for the channel
@result Appropriate IOReturn code
@discussion
IOReturn setStateByIndices(int channel_index,
int new_state_index);
+/*! @function IOStateReporter::setStateByIndices
+ @abstract update a channel state without validating channel_id
+
+ @param channel_index - 0..<nChannels>, available from getChannelIndex()
+ @param new_state_index - New state (by index) for the channel
+ @param last_intransition - deprecated: time of most recent entry
+ @param prev_state_residency - deprecated: time spent in previous state
+ @result Appropriate IOReturn code
+
+ @discussion
+ Similar to setState(), setStateByIndices() sets a channel's state
+ without searching for the channel or state IDs. It will perform
+ bounds checking, but relies on the caller to properly indicate
+ the indices of the channel and state. Clients can rely on channels
+ being added to IOStateReporter in order: the first channel will
+ have index 0, the second index 1, etc. Like ::setState(),
+ "time in state" calculations are handled automatically.
+
+ setStateByIndices() is faster than than setChannelState(), but
+ it should only be used where the latter's performance overhead
+ might be a problem. For example, many channels in a single
+ reporter and high-frequency state changes.
+
+ Drivers wishing to compute and report their own time in state
+ should use incrementChannelState() or overrideChannelState(). It
+ is not currently possible for a driver to synchronize with the
+ automatic time-keeping enabled by setStateByIndices(). The
+ 4-argument version of setChannelState() is thus impossible to
+ use correctly. In the future, there may be a setChannelState()
+ which accepts a last_intransition parameter and uses it to
+ automatically calculate time in state (ERs -> IOReporting / X).
+
+ Locking: same-instance concurrency SAFE, WILL NOT BLOCK
+*/
IOReturn setStateByIndices(int channel_index,
int new_state_index,
uint64_t last_intransition,
@abstract Accessor method for count of transitions into state
@param channel_id - ID of the channel
- @param channel_state - State of the channel
+ @param state_id - State of the channel
@result Count of transitions into the requested state.
@discussion
@abstract Accessor method for time spent in a given state
@param channel_id - ID of the channel
- @param channel_state - State of the channel
+ @param state_id - State of the channel
@result Absolute time spent in specified state
@discussion
@abstract Accessor method for last time a transition occured
@param channel_id - ID of the channel
- @param channel_state - State of the channel
+ @param state_id - State of the channel
@result Absolute time for when the last transition occured
@discussion
Locking: same-instance concurrency UNSAFE
*/
- virtual void free(void);
+ virtual void free(void) APPLE_KEXT_OVERRIDE;
protected:
/*! @function IOStateReporter::handleSwapPrepare
@abstract _swap* = <IOStateReporter-specific per-channel buffers>
+ [see IOReporter::handle*Swap* for more info]
+*/
+ virtual IOReturn handleSwapPrepare(int newNChannels) APPLE_KEXT_OVERRIDE;
+/*!
@function IOStateReporter::handleAddChannelSwap
@abstract swap in IOStateReporter's variables
+*/
+ virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
+ const OSSymbol *symChannelName) APPLE_KEXT_OVERRIDE;
+/*!
@function IOStateReporter::handleSwapCleanup
@abstract clean up unused buffers in _swap*
-
- [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);
+ virtual void handleSwapCleanup(int swapNChannels) APPLE_KEXT_OVERRIDE;
/*! @function IOStateReporter::updateChannelValues
@abstract Update accounting of time spent in current state
Locking: Caller must ensure that the reporter (data) lock is held.
*/
- virtual IOReturn updateChannelValues(int channel_index);
+ virtual IOReturn updateChannelValues(int channel_index) APPLE_KEXT_OVERRIDE;
/*! @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 new_state_index - New state for the channel
@param last_intransition - to remove: time of most recent entry
@param prev_state_residency - to remove: time spent in previous state
@result Appropriate IOReturn code
/*! @function IOHistogramReporter::with
@abstract Initializes the IOHistogramReporter instance variables and data structures
- @param reportingService - IOService instanciator and data provider into the reporter object
+ @param reportingService - The I/O Kit service for this reporter's channels
@param categories - The categories in which the report should be classified
@param channelID - uint64_t channel identifier
@param channelName - rich channel name as char*
@result kIOReturnUnsupported - doesn't support adding channels
*/
- IOReturn addChannel(uint64_t channelID, const char *channelName = NULL) {
+ IOReturn addChannel(__unused uint64_t channelID, __unused const char *channelName = NULL) {
return kIOReturnUnsupported;
}
+
+/*! @function IOHistogramReporter::overrideBucketValues
+ @abstract Override values of a bucket at specified index
+
+ @param index - index of bucket to override
+ @param bucket_hits - new bucket hits count
+ @param bucket_min - new bucket minimum value
+ @param bucket_max - new bucket maximum value
+ @param bucket_sum - new bucket sum
+ @result Appropriate IOReturn code
+
+ @discussion
+ Replaces data in the bucket at the specified index with the data pointed
+ to by bucket. No sanity check is performed on the data. If the index
+ is out of bounds, kIOReturnBadArgument is returned.
+
+ Locking: same-instance concurrency SAFE, WILL NOT BLOCK
+*/
+
+ IOReturn overrideBucketValues(unsigned int index,
+ uint64_t bucket_hits,
+ int64_t bucket_min,
+ int64_t bucket_max,
+ int64_t bucket_sum);
/*! @function IOHistogramReporter::tallyValue
@abstract Add a new value to the histogram
Locking: same-instance concurrency UNSAFE
*/
- virtual void free(void);
+ virtual void free(void) APPLE_KEXT_OVERRIDE;
protected:
Locking: same-instance concurrency SAFE, MAY BLOCK
*/
- IOReportLegendEntry* handleCreateLegend(void);
+ IOReportLegendEntry* handleCreateLegend(void) APPLE_KEXT_OVERRIDE;
private:
/*! @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
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.
+ Locking: same-reportingService and same-IORLegend concurrency UNSAFE
*/
IOReturn addReporterLegend(IOReporter *reporter,
const char *groupName,
const char *subGroupName);
+/*! @function IOReportLegend::addReporterLegend
+ @abstract Add a legend entry from a reporter object
+
+ @param reportingService - IOService data provider into the reporter object
+ @param reporter - IOReporter to use to extract and append the legend
+ @param groupName - primary group name for this entry
+ @param subGroupName - secondary group name for this entry
+ @result appropriate IOReturn code
+
+ @discussion
+ An IOReportLegendEntry will be created internally to this method from
+ the IOReporter object passed in argument. The entry will be released
+ internally after being appended to the IOReportLegend object.
+ Legend entries are available from reporter objects. Entries
+ represent some number of channels with similar properties (such
+ as group and sub-group). Multiple legend entries with the same
+ group names will be aggregated in user space.
+
+ Drivers that instantiate their reporter objects in response to
+ IOService::configureReport(kIOReportDisable) will need to create
+ temporary reporter objects for the purpose of creating their
+ legend entries. User-space legends are tracked by 12836893.
+
+ The static version of addReporterLegend adds the reporter's legend
+ directly to reportingService's kIOReportLegendKey. It is not
+ possible to safely update kIOReportLegendKey from multiple threads.
+
+ Locking: same-reportingService and same-IORLegend concurrency UNSAFE
+*/
static IOReturn addReporterLegend(IOService *reportingService,
IOReporter *reporter,
const char *groupName,
in the I/O Kit registry, its ownership will now be with the
registry.
*/
- void free(void);
+ void free(void) APPLE_KEXT_OVERRIDE;
@param groupName - Primary group name
@param subGroupName - Secondary group name
@result IOReturn code
-
- @discussion
*/
IOReturn organizeLegend(IOReportLegendEntry *legendEntry,
const OSSymbol *groupName,
projects / apple / xnu.git / blobdiff