1/*
2 * Copyright (c) 2012-2016 Apple Inc. All Rights Reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29/*
30 * FILE: IOReporter.h
31 * AUTH: Cyril & Soren (Core OS)
32 * DATE: 2012-2013 (Copyright Apple Inc.)
33 * DESC: IOReporting interfaces for I/O Kit drivers
34 *
35 */
36
37#ifndef _IOKERNEL_REPORTERS_H_
38#define _IOKERNEL_REPORTERS_H_
39
40#include <machine/limits.h>
41
42#include <libkern/c++/OSPtr.h>
43#include <IOKit/IOLib.h>
44#include <IOKit/IOService.h>
45#include <IOKit/IOLocks.h>
46#include <IOKit/IOBufferMemoryDescriptor.h>
47
48#include <IOKit/IOReportTypes.h>
49#include <IOKit/IOKernelReportStructs.h>
50
51#include <libkern/c++/OSPtr.h>
52
53typedef OSDictionary IOReportLegendEntry;
54
55/*******************************
56* TOC: this file contains
57* 1. Introduction
58* 2a. IOReporter class declaration (public & non-public members)
59* 2b. static IOReporter methods unrelated to the class
60* 3. IOReporter subclass declarations (public & non-public members)
61* 4. IOReportLegend class declaration
62*******************************/
63
64/*!
65 * 1. Introduction
66 *
67 * IOReporting is a mechanism for I/O Kit drivers to gather statistics
68 * (or other information) and make it available to various "observers,"
69 * which are generally in user space. Requests for information come
70 * through two new IOService methods: ::configureReport(...) and
71 * ::updateReport(...). While not required (see IOReportTypes.h), drivers
72 * will generally use IOReporter subclass instances to track the requested
73 * information and respond to IOReporting requests. Drivers can use these
74 * classes to track information, either all the time or between "enable"
75 * and "disable" calls to IOService::configureReport().
76 *
77 * Available information is organized into "channels." A channel is
78 * uniquely identified by both driver (registry) ID and a 64-bit channel
79 * ID. One way drivers can advertise their channels is by publishing
80 * "legends" in the I/O Kit registry. In addition to collecting
81 * information and responding to queries, IOReporter objects can produce
82 * legend entries describing their channels. The IOReportLegend class
83 * helps manage legend entries from multiple reporter objects as well
84 * as with grouping channels logically for observers.
85 *
86 * An important basic constraint of the current implementation is that
87 * all channels reported by a particular reporter instance must share all
88 * traits except channel ID and name. Specifically, the channel type
89 * (including report class, categories, & size) and units. Additionally,
90 * IOHistogramReporter currently only supports one channel at a time.
91 *
92 * Currently, ::{configure/update}Report() can be called any time between
93 * when a driver calls registerService() and when free() is called on
94 * your driver. 12960947 tracks improvements / recommendations for
95 * correctly handling these calls during termination.
96 *
97 * Locking
98 * IOReporting only imposes concurrent access constraints when multiple
99 * threads are accessing the same object. Three levels of constraint apply
100 * depending on a method's purpose:
101 * 1. Allocation/Teardown - same-instance concurrency UNSAFE, MAY BLOCK
102 * 2. Configuration - same-instance concurrency SAFE, MAY BLOCK
103 * 3. Update - same-instance concurrency SAFE, WILL NOT BLOCK
104 *
105 * Configuration requires memory management which can block and must
106 * be invoked with interrupts ENABLED (for example, NOT in the interrupt
107 * context NOR with a spin lock -- like IOSimpleLock -- held).
108 *
109 * Updates can be performed with interrupts disabled, but clients should
110 * take into account that IOReporters' non-blocking currenency is achieved
111 * with IOSimpleLockLockDisable/UnlockEnableInterrupts(): that is, by
112 * disabling interrupts and taking a spin lock. While IOReporting will
113 * never hold a lock beyond a call into it, some time may be spent within
114 * the call spin-waiting for the lock. Clients holding their own
115 * spin locks should carefully consider the impact of IOReporting's
116 * (small) additional latency before calling it while holding a spin lock.
117 *
118 * The documentation for each method indicates any concurrency guarantees.
119 */
120
121
122/*********************************/
123/*** 2a. IOReporter Base Class ***/
124/*********************************/
125
126class IOReporter : public OSObject
127{
128 OSDeclareDefaultStructors(IOReporter);
129
130protected:
131/*! @function IOReporter::init
132 * @abstract base init() method, called by subclass initWith() methods
133 *
134 * @param reportingService - IOService associated with all channels
135 * @param channelType - type info for all channels (element_idx = 0)
136 * @param unit - description applied for all channels
137 * @result true on success, false otherwise
138 *
139 * @discussion
140 * init() establishes the parameters of all channels for this reporter
141 * instance. Any channels added via addChannel() will be of this type
142 * and have this unit.
143 *
144 * IOReporter clients should use the static <subclass>::with() methods
145 * below to obtain fully-initialized reporter instances. ::free()
146 * expects ::init() to have completed successfully. On failure, any
147 * allocations are cleaned up.
148 *
149 * Locking: same-instance concurrency UNSAFE
150 */
151 virtual bool init(IOService *reportingService,
152 IOReportChannelType channelType,
153 IOReportUnit unit);
154
155public:
156
157/*! @function IOReporter::addChannel
158 * @abstract add an additional, similar channel to the reporter
159 *
160 * @param channelID - identifier for the channel to be added
161 * @param channelName - an optional human-readble name for the channel
162 * @result appropriate IOReturn code
163 *
164 * @discussion
165 * The reporter will allocate memory to track a new channel with the
166 * provided ID and name (if any). Its other traits (type, etc) will
167 * be those provided when the reporter was initialized. If no channel
168 * name is provided and the channelID consists solely of ASCII bytes,
169 * those bytes (ignoring any NUL bytes) will be used as the
170 * human-readable channel name in user space. The IOREPORT_MAKEID()
171 * macro in IOReportTypes.h can be used to create ASCII channel IDs.
172 *
173 * Locking: same-instance concurrency SAFE, MAY BLOCK
174 */
175 IOReturn addChannel(uint64_t channelID, const char *channelName = NULL);
176
177/*! @function IOReporter::createLegend
178 * @abstract create a legend entry represending this reporter's channels
179 * @result An IOReportLegendEntry object or NULL on failure.
180 * @discussion
181 * All channels added to the reporter will be represented
182 * in the resulting legend entry.
183 *
184 * Legends must be published togethar as an array under the
185 * kIOReportLegendKey in the I/O Kit registry. The IOReportLegend
186 * class can be used to properly combine legend entries from multiple
187 * reporters as well as to put channels into groups of interest to
188 * observers. When published, individual legend entries share
189 * characteristics such as group and sub-group. Multiple IOReporter
190 * instances are required to produce independent legend entries which
191 * can then be published with different characteristics.
192 *
193 * Drivers wishing to publish legends should do so as part of their
194 * ::start() routine. As superclasses *may* have installed legend
195 * entries, any existing existing legend should be retrieved and
196 * IOReportLegend used to merge it with the new entries.
197 *
198 * Recommendations for best practices are forthcoming.
199 *
200 * Instead of calling createLegend on your reporter object and then
201 * appending it manually to IOReportLegend, one may prefer to call
202 * IOReportLegend::appendReporterLegend which creates and appends a
203 * reporter's IOReportLegendEntry in a single call.
204 *
205 * Locking: same-instance concurrency SAFE, MAY BLOCK
206 */
207 OSPtr<IOReportLegendEntry> createLegend(void);
208
209/*! @function IOReporter::configureReport
210 * @abstract track IOService::configureReport(), provide sizing info
211 *
212 * @param channelList - channels to configure
213 * @param action - enable/disable/size, etc (see IOReportTypes.h)
214 * @param result - *incremented* for kIOReportGetDimensions
215 * @param destination - action-specific default destination
216 * @result appropriate IOReturn code
217 *
218 * @discussion
219 * Any time a reporting driver's ::configureReport method is invoked,
220 * this method should be invoked on each IOReporter that is being
221 * used by that driver to report channels in channelList.
222 *
223 * Any channels in channelList which are not tracked by this reporter
224 * are ignored. ::configureReport(kIOReportGetDimensions) expects
225 * the full size of all channels, including any reported by
226 * superclasses. It is valid to call this routine on multiple
227 * reporter objects in succession and they will increment 'result'
228 * to provide the correct total.
229 *
230 * In the initial release, this routine is only required to calculate
231 * the response to kIOReportGetDimensions, but in the future it will
232 * will enable functionality like "triggered polling" via
233 * kIOReportNotifyHubOnChange. Internally, it is already keeping
234 * track of the number of times each channel has been enabled and
235 * disabled. 13073064 tracks adding a method to see whether any
236 * channels are currently being observed.
237 *
238 * The static IOReporter::configureAllReports() will call this method
239 * on multiple reporters grouped in an OSSet.
240 *
241 * Locking: same-instance concurrency SAFE, MAY BLOCK
242 */
243 IOReturn configureReport(IOReportChannelList *channelList,
244 IOReportConfigureAction action,
245 void *result,
246 void *destination);
247
248/*! @function IOReporter::updateReport
249 * @abstract Produce standard reply to IOService::updateReport()
250 *
251 * @param channelList - channels to update
252 * @param action - copy/trace data (see IOReportTypes.h)
253 * @param result - action-specific return value (e.g. size of data)
254 * @param destination - destination for this update (action-specific)
255 * @result appropriate IOReturn code
256 *
257 * @discussion
258 * This method searches channelList for channels tracked by this
259 * reporter, writes the corresponding data into 'destination', and
260 * updates 'result'. It should be possible to pass a given set of
261 * IOService::updateReport() arguments to any and all reporters as
262 * well as to super::updateReport() and get the right result.
263 *
264 * The static IOReporter::updateAllReports() will call this method
265 * on an OSSet of reporters.
266 *
267 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
268 */
269 IOReturn updateReport(IOReportChannelList *channelList,
270 IOReportConfigureAction action,
271 void *result,
272 void *destination);
273
274/*! @function IOReporter::free
275 * @abstract Releases the object and all its resources.
276 *
277 * @discussion
278 * ::free() [called on last ->release()] assumes that init() [called
279 * by static ::with() methods] has completed successfully.
280 *
281 * Locking: same-instance concurrency UNSAFE
282 */
283 virtual void free(void) APPLE_KEXT_OVERRIDE;
284
285/*! @function IOReporter::init
286 * @abstract Initialize global state
287 *
288 * @discussion
289 * ::initialize() [called during IOStartIOKit] initializes all global
290 * state for IOReporter objects.
291 *
292 */
293 static void initialize(void);
294
295
296/*********************************/
297/*** 2b. Useful Static Methods ***/
298/*********************************/
299
300/* The following static functions are intended to simplify the management
301 * of multiple reporters. They may be superseded in the future by an
302 * IOReportManager class.
303 */
304
305/*! @function IOReporter::configureAllReports
306 * @abstract call configureReport() on multiple IOReporter objects
307 *
308 * @param reporters - OSSet of IOReporter objects
309 * @param channelList - full list of channels to configure
310 * @param action - enable/disable/size, etc
311 * @param result - action-specific returned value
312 * @param destination - action-specific default destination
313 * @result success if all objects successfully complete
314 * IOReporter::configureReport()
315 *
316 * @discussion
317 * The OSSet must only contain IOReporter instances. The presence
318 * of non-IOReporter instances will cause this function to return
319 * kIOReturnBadArgument. If any reporter returns an error, the
320 * function will immediately return that error.
321 *
322 * Per the IOReporter::configureReport() documentation, each
323 * reporter will search channelList for channels it is reporting
324 * and provide a partial response.
325 */
326 static IOReturn configureAllReports(OSSet *reporters,
327 IOReportChannelList *channelList,
328 IOReportConfigureAction action,
329 void *result,
330 void *destination);
331// FIXME: just put the function (inline-ish) here?
332
333/*! @function IOReporter::updateAllReports
334 * @abstract call updateReport() on multiple IOReporter objects
335 *
336 * @param reporters - OSSet of IOReporter objects
337 * @param channelList - full list of channels to update
338 * @param action - type/style of update
339 * @param result - returned details about what was updated
340 * @param destination - destination for this update (action-specific)
341 * @result IOReturn code
342 * @discussion
343 * The OSSet must only contain IOReporter instances. The presence
344 * of non-IOReporter instances will cause this function to return
345 * kIOReturnBadArgument. If any reporter returns an error, the
346 * function will immediately return that error.
347 *
348 * Per the IOReporter::configureReport() documentation, each
349 * reporter will search channelList for channels it is reporting
350 * and provide a partial response.
351 */
352 static IOReturn updateAllReports(OSSet *reporters,
353 IOReportChannelList *channelList,
354 IOReportConfigureAction action,
355 void *result,
356 void *destination);
357// FIXME: just put the function (inline-ish) here?
358
359
360/* Protected (subclass-only) Methods
361 *
362 * General subclassing is not encouraged as we intend to improve
363 * internal interfaces. If you need something that might require
364 * a subclass, please file a bug against IOReporting/X and we will
365 * help you.
366 *
367 * One important concept for sub-classes (not clients) is that report
368 * data is stored in IOReportElement structures (see IOReportTypes.h).
369 */
370protected:
371
372/*! @function IOReporter::lockReporterConfig
373 * @function IOReporter::unlockReporterConfig
374 * @abstract prevent concurrent reconfiguration of a reporter
375 *
376 * @discussion
377 * lockReporterConfig() takes a mutex-based lock intended to prevent
378 * concurrent access to the reporter's configuration. It is not
379 * intended to prevent updates to the reporter's data. As long as
380 * all other requirements are met, it is safe to simultaneously hold
381 * both the configuration and data locks on a single reporter.
382 *
383 * lockReporterConfig() is used by routines such as addChannel().
384 * See also lockReporter() and ::handle*Swap*() below.
385 */
386 void lockReporterConfig(void);
387 void unlockReporterConfig(void);
388
389/*! @function IOReporter::lockReporter
390 * @function IOReporter::unlockReporter
391 * @abstract prevent concurrent access to a reporter's data
392 *
393 * @discussion
394 * This method grabs a lock intended to control access the reporter's
395 * reporting data. Sub-classes maninupating internal report values
396 * must make sure the reporter is locked (usually by the most generic
397 * public interface) before calling getElementValues(),
398 * copyElementValues(), or setElementValues().
399 *
400 * Subclasses should ensure that this lock is taken exactly once
401 * before directly accessing reporter data. For example,
402 * [virtual] IOFooReporter::handleSetFoo(.) {
403 * // assert(lock_held)
404 * getElementValues(1..)
405 * getElementValues(3..)
406 * getElementValues(5..)
407 * [calculate]
408 * setElementValues(6..)
409 * }
410 * IOFooReporter::setFoo(.) { // not virtual
411 * lockReporter()
412 * handleSetFoo(.)
413 * unlockReporter()
414 * }
415 *
416 * IOReporter::handle*() use lockReporter() similarly. For example,
417 * the lock is taken by IOReporter::updateReport() and is already
418 * held by the time any ::updateChannelValues() methods are called.
419 *
420 * Subclasses cannot call this routine if the lock is already held.
421 * That's why IOReporting generally only calls it from non-virtual
422 * public methods. In particular, this method should not be called
423 * it from ::handle*() methods which exist to allow override after
424 * the lock is taken.
425 *
426 * Because lockReporter() uses a spin lock, it is SAFE to use in the
427 * interrupt context. For the same reason, however, it is UNSAFE
428 * to perform any blocking blocking operations (including memory
429 * allocations) while holding this lock.
430 */
431 void lockReporter(void);
432 void unlockReporter(void);
433
434/*!
435 * @discussion
436 * The ::handle*Swap* functions allow subclasses to safely reconfigure
437 * their internal state. A non-virtual function handles locking
438 * and invokes the functions in order:
439 * - lockReporterConfig() // protecting instance vars but not content
440 * - prepare / allocate buffers of the new size
441 * - if error, bail (unlocking, of course)
442 *
443 * - lockReporter() // protecting data / blocking updates
444 * - swap: preserve continuing data / install new buffers
445 * - unlockReporter()
446 *
447 * - deallocate now-unused buffers
448 * - unlockReporterConfig()
449 */
450/*! @function IOReporter::handleSwapPrepare
451 * @abstract allocate memory in preparation for an instance variable swap
452 *
453 * @param newNChannels target number of channels
454 * @result IOReturn code
455 *
456 * @discussion
457 * ::handleSwapPrepare() is responsible for allocating appropriately-
458 * sized buffers (based on the new number of channels) and storing
459 * them in _swap* instance variables. If returning and error, it
460 * must deallocate any buffers and set to NULL any _swap* variables.
461 *
462 * Locking: The caller must ensure that the *config* lock is HELD but
463 * that the reporter (data) lock is *NOT HELD*.
464 */
465 virtual IOReturn handleSwapPrepare(int newNChannels);
466
467/*! @function IOReporter::handleAddChannelSwap
468 * @abstract update primary instance variables with new buffers
469 *
470 * @param channel_id ID of channel being added
471 * @param symChannelName optional channel name, in an allocated object
472 * @result IOReturn code
473 *
474 * @discussion
475 * handlAddChannelSwap() replaces the primary instance variables
476 * with buffers allocated in handlePrepareSwap(). It copies the the
477 * existing data into the appropriate portion of the new buffers.
478 * Because it is specific to adding one channel, it assumes that the
479 * target number of channels is one greater than the current value
480 * of _nChannels.
481 *
482 * IOReporter::handleAddChannelSwap() increments _nElements and
483 * _nChannels. To ensure that these variables describe the current
484 * buffers throughout ::handle*Swap(), subclasses overriding this
485 * method should call super::handleAddChannelSwap() after swapping
486 * their own instance variables.
487 *
488 * If returning an error, all implementations should leave their
489 * instance variables as they found them (*unswapped*). That ensures
490 * handleSwapCleanup() cleans up the unused buffers regardless of
491 * whether the swap was complete.
492 *
493 * Pseudo-code incorporating these suggestions:
494 * res = <err>; swapComplete = false;
495 * if (<unexpected>) goto finish
496 * tmpBuf = _primaryBuf; _primaryBuf = _swapBuf; _swapBuf = _primaryBuf;
497 * ...
498 * swapComplete = true;
499 * res = super::handle*Swap()
500 * ...
501 * finish:
502 * if (res && swapComplete) // unswap
503 *
504 * Locking: The caller must ensure that BOTH the configuration and
505 * reporter (data) locks are HELD.
506 */
507 virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
508 const OSSymbol *symChannelName);
509
510/*! @function IOReporter::handleSwapCleanup
511 * @abstract release and forget unused buffers
512 *
513 * @param swapNChannels channel-relative size of the _swap buffers
514 *
515 * @discussion
516 * ::handleSwapCleanup() is responsible for deallocating the buffers
517 * no longer used after a swap. It must always be called if
518 * SwapPrepare() completes successfully. Because bufers may be
519 * swapped in and out of existance, the _swap* variables may be
520 * NULL and should be set to NULL when complete.
521 *
522 * Locking: The caller must ensure that the *config* lock is HELD but
523 * that the reporter (data) lock is *NOT HELD*.
524 */
525 virtual void handleSwapCleanup(int swapNChannels);
526
527/*! @function IOReporter::handleConfigureReport
528 * @abstract override vector for IOReporter::configureReport()
529 * [parameters and result should exactly match]
530 *
531 * @discussion
532 * The public base class method takes the reporter lock, calls this
533 * function, and then drops the lock. Subclasses should not call
534 * this function directly.
535 */
536 virtual IOReturn handleConfigureReport(IOReportChannelList *channelList,
537 IOReportConfigureAction action,
538 void *result,
539 void *destination);
540
541/*! @function IOReporter::handleUpdateReport
542 * @abstract override vector for IOReporter::updateReport()
543 * [parameters and result should exactly match]
544 *
545 * @discussion
546 * The public base class method takes the reporter lock, calls this
547 * function, and then drops the lock. Subclasses should not call
548 * this function directly.
549 *
550 * This function may be overriden but the common case should be to
551 * simply update reporter's specific values by overriding
552 * IOReporter::updateChannelValues().
553 */
554 virtual IOReturn handleUpdateReport(IOReportChannelList *channelList,
555 IOReportConfigureAction action,
556 void *result,
557 void *destination);
558
559/* @function IOReporter::handleCreateLegend
560 * @abstract override vector for IOReporter::createLegend()
561 * [parameters and result should exactly match]
562 *
563 * @discussion
564 * The public base class method takes the reporter lock, calls this
565 * function, and then drops the lock. Subclasses should not call
566 * this function directly.
567 */
568 virtual OSPtr<IOReportLegendEntry> handleCreateLegend(void);
569
570/*! @function IOReporter::updateChannelValues
571 * @abstract update channel values for IOReporter::updateReport()
572 *
573 * @param channel_index - logical (internal) index of the channel
574 * @result appropriate IOReturn code
575 *
576 * @discussion
577 * Internal reporter method to allow a subclass to update channel
578 * data when updateReport() is called. This routine handles the
579 * common case of a subclass needing to refresh state in response
580 * to IOReporter::updateReport(). It saves the complexity of
581 * parsing the full parameters to IOReporter::updateReport().
582 *
583 * The IOReporter base class implementation does not do anything
584 * except return success.
585 *
586 * Locking: IOReporter::updateReport() takes the reporter lock,
587 * determines the indices involved, calls this function, and
588 * then proceeds to provide values to the caller. If subclasses
589 * need to call this routine directly, they must ensure that
590 * the reporter (data) lock is held: see
591 * IOReporter::lockReporter().
592 */
593 virtual IOReturn updateChannelValues(int channel_index);
594
595
596/*! @function IOReporter::updateReportChannel
597 * @abstract Internal method to extract channel data to a destination
598 *
599 * @param channel_index - offset into internal elements array
600 * @param nElements - incremented by the number of IOReportElements added
601 * @param destination - pointer to the destination buffer
602 * @result IOReturn code
603 *
604 * @discussion
605 * updateReportChannel() is used to extract a single channel's
606 * data to the updateReport() destination.
607 *
608 * Locking: Caller must ensure that the reporter (data) lock is held.
609 */
610 IOReturn updateReportChannel(int channel_index,
611 int *nElements,
612 IOBufferMemoryDescriptor *destination);
613
614
615/*! @function IOReporter::setElementValues
616 * @abstract Atomically update a specific member of _elements[].
617 *
618 * @param element_index - index of the _element in internal array
619 * @param values - IORepoterElementValues to replace those at _elements[idx]
620 * @param record_time - optional mach_absolute_time to be used for metadata
621 * @result IOReturn code
622 *
623 * @discussion
624 * element_index can be obtained from getFirstElementIndex(). If
625 * record_time is not provided, IOReporter::setElementValues() will
626 * fetch the current mach_absolute_time. If the current time is
627 * already known, it is more efficient to pass it along.
628 *
629 * Locking: Caller must ensure that the reporter (data) lock is held.
630 */
631 virtual IOReturn setElementValues(int element_index,
632 IOReportElementValues *values,
633 uint64_t record_time = 0);
634
635/*! @function IOReporter::getElementValues
636 * @abstract Internal method to directly access the values of an element
637 *
638 * @param element_index - index of the _element in internal array
639 * @result A pointer to the element values requested or NULL on failure
640 *
641 * @discussion Locking: Caller must ensure that the reporter (data) lock is held.
642 * The returned pointer is only valid until unlockReporter() is called.
643 */
644 virtual const IOReportElementValues* getElementValues(int element_index);
645
646/*! @function IOReporter::getFirstElementIndex
647 * @abstract Returns the first element index for a channel
648 *
649 * @param channel_id - ID of the channel
650 * @param element_index - pointer to the returned element_index
651 * @result appropriate IOReturn code
652 *
653 * @discussion
654 * For efficiently and thread-safely reading _elements
655 *
656 * Locking: Caller must ensure that the reporter (data) lock is held.
657 */
658 virtual IOReturn getFirstElementIndex(uint64_t channel_id,
659 int *element_index);
660
661/*! @function IOReporter::getChannelIndex
662 * @abstract Returns the index of a channel from internal data structures
663 *
664 * @param channel_id - ID of the channel
665 * @param channel_index - pointer to the returned element_index
666 * @result appropriate IOReturn code
667 *
668 * @discussion
669 * For efficiently and thread-safely reading channels
670 *
671 * Locking: Caller must ensure that the reporter (data) lock is held.
672 */
673 virtual IOReturn getChannelIndex(uint64_t channel_id,
674 int *channel_index);
675
676/*! @function IOReporter::getChannelIndices
677 * @abstract Returns the index of a channel and its corresponding
678 * first element index from internal data structure
679 *
680 * @param channel_id - ID of the channel
681 * @param channel_index - pointer to the returned channel_index
682 * @param element_index - pointer to the returned element_index
683 * @result appropriate IOReturn code
684 *
685 * @discussion
686 * For efficiently and thread-safely reading channel elements.
687 * It is commonly useful to get access to both channel and element
688 * indices togther. This convenience method allows sub-classes to
689 * get both indices simultaneously.
690 *
691 * Locking: Caller must ensure that the reporter (data) lock is held.
692 */
693 virtual IOReturn getChannelIndices(uint64_t channel_id,
694 int *channel_index,
695 int *element_index);
696
697/*! @function IOReporter::copyElementValues
698 * @abstract Copies the values of an internal element to *elementValues
699 *
700 * @param element_index - Index of the element to return values from
701 * @param elementValues - For returning the content of element values
702 * @result Returns the content of an element
703 *
704 * @discussion
705 * For efficiently and thread-safely reading _elements.
706 * May need to find the index of the element first.
707 *
708 * Locking: Caller must ensure that the reporter (data) lock is held.
709 */
710 virtual IOReturn copyElementValues(int element_index,
711 IOReportElementValues *elementValues);
712
713/*! @function IOReporter::legendWith
714 * @abstract Internal method to help create legend entries
715 *
716 * @param channelIDs - array of uint64_t channels IDs.
717 * @param channelNames - parrallel array of const char* channel names
718 * @param channelCount - number of channels, and size of channelIDs and channelNames
719 * @param channelType - the type of all channels in this legend
720 * @param unit - The unit for the quantity recorded by this reporter object
721 *
722 * @result An IOReportLegendEntry object or NULL on failure
723 *
724 * @discussion
725 * This static method is variant of IOReporter::legendWith that takes
726 * raw arrays for the channelIDs and channelNames. It supports the static
727 * createLegend() methods for the IOReporter subclasses.
728 *
729 * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
730 */
731 static OSPtr<IOReportLegendEntry> legendWith(const uint64_t *channelIDs,
732 const char **channelNames,
733 int channelCount,
734 IOReportChannelType channelType,
735 IOReportUnit unit);
736
737// private methods
738private:
739/*! @function IOReporter::copyChannelIDs
740 * @abstract return an an OSArray of the reporter's
741 * channel IDs
742 *
743 * @result An OSArray of the repoter's channel ID's as OSNumbers
744 *
745 * @discussion
746 * This method is an internal helper function used to prepare a
747 * legend entry. It encapsulates the channel IDs in OSNumbers and
748 * aggregates them in an OSArray used when building the IOReportLegend
749 *
750 * Locking: Caller must ensure that the reporter (data) lock is held.
751 */
752 OSPtr<OSArray> copyChannelIDs(void);
753
754/*! @function IOReporter::legendWith
755 * @abstract Internal method to help create legend entries
756 *
757 * @param channelIDs - OSArray of OSNumber(uint64_t) channels IDs.
758 * @param channelNames - parrallel OSArray of OSSymbol(rich names)
759 * @param channelType - the type of all channels in this legend
760 * @param unit - The unit for the quantity recorded by this reporter object
761 *
762 * @result An IOReportLegendEntry object or NULL on failure
763 *
764 * @discussion
765 * This static method is the main legend creation function. It is called by
766 * IOReporter sub-classes and is responsible for building an
767 * IOReportLegendEntry corresponding to this reporter object.
768 * This legend entry may be extended by the sub-class of IOReporter if
769 * required.
770 *
771 * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
772 */
773 static OSPtr<IOReportLegendEntry> legendWith(OSArray *channelIDs,
774 OSArray *channelNames,
775 IOReportChannelType channelType,
776 IOReportUnit unit);
777
778// protected instance variables (want to get rid of these)
779protected:
780 IOReportChannelType _channelType;
781 uint64_t _driver_id; // driver reporting data
782
783// IOHistogramReporter accesses these; need to re-do its instantiation
784 IOReportElement *_elements;
785 int *_enableCounts; // refcount kIOReportEnable/Disable
786 uint16_t _channelDimension;// Max channel size
787 int _nElements;
788 int _nChannels; // Total Channels in this reporter
789 OSPtr<OSArray> _channelNames;
790
791// MUST be protected because check is a macro!
792 bool _reporterIsLocked;
793 bool _reporterConfigIsLocked;
794
795// Required for swapping inside addChannel
796 IOReportElement *_swapElements;
797 int *_swapEnableCounts;
798
799// private instance variables
800private:
801 IOReportUnit _unit;
802
803 int _enabled;// 'enabled' if _enabled > 0
804
805 IOLock *_configLock;
806 IOInterruptState _interruptState;
807 IOSimpleLock *_reporterLock;
808};
809
810
811/************************************/
812/***** 3. IOReporter Subclasses *****/
813/************************************/
814
815/*!
816 * @class IOSimpleReporter
817 * @abstract Report simple integers
818 * @discussion
819 * Each IOSimpleReporter can have an arbitrary number of channels,
820 * each publishing a single integer value at any given time.
821 */
822
823class IOSimpleReporter : public IOReporter
824{
825 OSDeclareDefaultStructors(IOSimpleReporter);
826
827public:
828
829/*! @function IOSimpleReporter::with
830 * @abstract create an initialized simple reporter
831 *
832 * @param reportingService - IOService associated with all channels
833 * @param categories - The category in which the report should be classified
834 * @param unit - The unit for the quantity recorded by the reporter object
835 * @result On success, an instance of IOSimpleReporter, else NULL
836 *
837 * @discussion
838 * Creates an instance of IOSimpleReporter object
839 *
840 * Locking: SAFE to call concurrently (no static globals), MAY BLOCK.
841 */
842 static OSPtr<IOSimpleReporter> with(IOService *reportingService,
843 IOReportCategories categories,
844 IOReportUnit unit);
845
846/*! @function IOSimpleReporter::setValue
847 * @abstract Thread safely set a channel's value
848 *
849 * @param channel_id - ID of the channel for which the value needs to be set
850 * @param value - New channel value
851 * @result Appropriate IOReturn code
852 *
853 * @discussion
854 * Updates the value of a channel to the provided value.
855 *
856 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
857 */
858 IOReturn setValue(uint64_t channel_id,
859 int64_t value);
860
861/*! @function IOSimpleReporter::incrementValue
862 * @abstract Thread safely increment a channel's value by a given amount
863 *
864 * @param channel_id - ID of the channel for which the value needs to be incremented
865 * @param increment - Amount to be added to the current channel value
866 * @result Appropriate IOReturn code
867 * @discussion
868 * Increments the value of the channel ID by the provided amount.
869 *
870 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
871 */
872 IOReturn incrementValue(uint64_t channel_id,
873 int64_t increment);
874
875/*! @function IOSimpleReporter::getValue
876 * @abstract Thread safely access a channel value
877 *
878 * @param channel_id - ID of the channel to get a value from
879 * @result Returns the current value stored in the channel
880 * @discussion
881 * Accessor method to a channel's current stored value
882 *
883 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
884 */
885 int64_t getValue(uint64_t channel_id);
886
887/*! @function IOSimpleReporter::createLegend
888 * @abstract Creates a legend entry for an IOSimpleReporter
889 *
890 * @param channelIDs - array of uint64_t channels IDs.
891 * @param channelNames - parrallel array of const char* channel names
892 * @param channelCount - number of channels, and size of channelIDs and channelNames
893 * @param categories - The category in which the report should be classified
894 * @param unit - The unit for the quantity recorded by the reporter object
895 *
896 * @result An IOReportLegendEntry object or NULL on failure
897 *
898 * @discussion
899 * This static method supports creating a legend entry for an IOSimpleReporter
900 * without actually having an IOSimpleReporter instance.
901 * This can be used to lazily create IOReporters in IOService::configureReport()
902 * rather than during driver initialization.
903 */
904 static OSPtr<IOReportLegendEntry> createLegend(const uint64_t *channelIDs,
905 const char **channelNames,
906 int channelCount,
907 IOReportCategories categories,
908 IOReportUnit unit);
909
910protected:
911
912/*! @function IOSimpleReporter::initWith
913 * @abstract instance method implementation called by IOSimpleReporter::with
914 *
915 * @discussion
916 * See description of parameters above
917 *
918 * Locking: same-instance concurrency UNSAFE
919 */
920 virtual bool initWith(IOService *reportingService,
921 IOReportCategories categories,
922 IOReportUnit unit);
923
924private:
925};
926
927
928
929/*!
930 * @class IOStateReporter
931 * @abstract Report state machine data
932 * @discussion
933 * Each IOStateReporter can report information for an arbitrary number
934 * of similar state machines. All must have the same number of states.
935 */
936class IOStateReporter : public IOReporter
937{
938 OSDeclareDefaultStructors(IOStateReporter);
939
940public:
941
942/*! @function IOStateReporter::with
943 * @abstract State reporter static creation method
944 *
945 * @param reportingService - The I/O Kit service for this reporter's channels
946 * @param categories - The categories for this reporter's channels
947 * @param nstates - Maximum number of states for this reporter's channels
948 * @param unit - optional parameter if using override/increment...()
949 * @result on success, an IOStateReporter instance, else NULL
950 *
951 * @discussion
952 * Creates an instance of IOStateReporter. The default time scale
953 * is the current system's notion of mach_absolute_time(). Using a
954 * non-default time scale requires the use of
955 * override/incrementChannelState() instead of setState().
956 * setState() always updates using mach_absolute_time().
957 *
958 * Locking: SAFE to call concurrently (no static globals), MAY BLOCK
959 */
960 static OSPtr<IOStateReporter> with(IOService *reportingService,
961 IOReportCategories categories,
962 int nstates,
963 IOReportUnit unit = kIOReportUnitHWTicks);
964
965/*! @function IOStateReporter::setStateID
966 * @abstract Assign a non-default ID to a state
967 *
968 * @param channel_id - ID of channel containing the state in question
969 * @param state_index - index of state to give an ID: [0..(nstates-1)]
970 * @param state_id - 64-bit state ID, for ASCII, use IOREPORT_MAKEID
971 *
972 * @result Appropriate IOReturn code
973 *
974 * @discussion
975 * By default, IOStateReporter identifies its channel states by
976 * numbering them from 0 to <nstates - 1>. If setStateID is not
977 * called to customize the state IDs, the numbered states will be
978 * kept throughout the life of the object and it is safe to reference
979 * those states by their indices. Otherwise, after setStateID() has
980 * been called, the ordering of states is no longer guaranteed and
981 * the client must reference states by their assigned state ID.
982 *
983 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
984 */
985 IOReturn setStateID(uint64_t channel_id,
986 int state_index,
987 uint64_t state_id);
988
989/*! @function IOStateReporter::setChannelState
990 * @abstract Updates the current state of a channel to a new state
991 *
992 * @param channel_id - ID of the channel which is updated to a new state
993 * @param new_state_id - ID of the target state for this channel
994 * @param last_intransition - deprecated: time of most recent entry
995 * @param prev_state_residency - deprecated: time spent in previous state
996 * @result Appropriate IOReturn code
997 *
998 * @discussion
999 * setChannelState() updates the amount of time spent in the previous
1000 * state (if any) and increments the number of transitions into the
1001 * new state. It also sets the target state's last transition time to
1002 * the current time and enables internal time-keeping for the channel.
1003 * In this mode, calls like getStateResidencyTime() and updateReport()
1004 * automatically update a channel's time in state.
1005 *
1006 * new_state_id identifies the target state as initialized
1007 * (0..<nstates-1>) or as configured by setStateID().
1008 *
1009 * Drivers wishing to compute and report their own time in state
1010 * should use incrementChannelState() or overrideChannelState(). It
1011 * is not currently possible for a driver to synchronize with the
1012 * automatic time-keeping enabled by setChannelState(). The
1013 * 4-argument version of setChannelState() is thus impossible to
1014 * use correctly. In the future, there may be a setChannelState()
1015 * which accepts a last_intransition parameter and uses it to
1016 * automatically calculate time in state (ERs -> IOReporting / X).
1017 *
1018 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1019 */
1020 IOReturn setChannelState(uint64_t channel_id,
1021 uint64_t new_state_id,
1022 uint64_t last_intransition,
1023 uint64_t prev_state_residency) __deprecated;
1024
1025/*! @function IOStateReporter::setChannelState
1026 * @abstract Updates the current state of a channel to a new state
1027 *
1028 * @param channel_id - ID of the channel which is updated to a new state
1029 * @param new_state_id - ID of the target state for this channel
1030 * @result Appropriate IOReturn code
1031 *
1032 * @discussion
1033 * setChannelState() updates the amount of time spent in the previous
1034 * state (if any) and increments the number of transitions into the
1035 * new state. It also sets the target state's last transition time to
1036 * the current time and enables internal time-keeping for the channel.
1037 * In this mode, calls like getStateResidencyTime() and updateReport()
1038 * automatically update a channel's time in state.
1039 *
1040 * new_state_id identifies the target state as initialized
1041 * (0..<nstates-1>) or as configured by setStateID().
1042 *
1043 * Drivers wishing to compute and report their own time in state
1044 * should use incrementChannelState() or overrideChannelState(). It
1045 * is not currently possible for a driver to synchronize with the
1046 * automatic time-keeping enabled by setChannelState(). The
1047 * 4-argument version of setChannelState() is thus impossible to
1048 * use correctly. In the future, there may be a setChannelState()
1049 * which accepts a last_intransition parameter and uses it to
1050 * automatically calculate time in state (ERs -> IOReporting / X).
1051 *
1052 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1053 */
1054 IOReturn setChannelState(uint64_t channel_id,
1055 uint64_t new_state_id);
1056
1057
1058/*! @function IOStateReporter::setState
1059 * @abstract Updates state for single channel reporters
1060 *
1061 * @param new_state_id - New state for the channel
1062 * @result Appropriate IOReturn code.
1063 *
1064 * @discussion
1065 * setState() is a convenience method for single-channel state
1066 * reporter instances. An error will be returned if the reporter
1067 * in question has more than one channel.
1068 *
1069 * See further discussion at setChannelState().
1070 *
1071 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1072 */
1073 IOReturn setState(uint64_t new_state_id);
1074
1075/*! @function IOStateReporter::setState
1076 * @abstract Updates state for single channel reporters
1077 *
1078 * @param new_state_id - New state for the channel
1079 * @param last_intransition - deprecated: time of most recent entry
1080 * @param prev_state_residency - deprecated: spent in previous state
1081 * @result Appropriate IOReturn code.
1082 *
1083 * @discussion
1084 * setState() is a convenience method for single-channel state
1085 * reporter instances. An error will be returned if the reporter
1086 * in question has more than one channel.
1087 *
1088 * See further discussion at setChannelState().
1089 *
1090 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1091 */
1092 IOReturn setState(uint64_t new_state_id,
1093 uint64_t last_intransition,
1094 uint64_t prev_state_residency) __deprecated;
1095
1096/*! @function IOStateReporter::overrideChannelState
1097 * @abstract Overrides state data for a channel with passed arguments
1098 *
1099 * @param channel_id - ID of the channel which state is to be updated
1100 * @param state_id - state id for the channel
1101 * @param time_in_state - time used as new total time in state
1102 * @param intransitions - total number of transitions into state
1103 * @param last_intransition - mach_absolute_time of most recent entry (opt)
1104 * @result Appropriate IOReturn code
1105 *
1106 * @discussion
1107 * overrideChannelState() sets a particular state's time in state
1108 * and transition count to the values provided. The optional
1109 * last_intransition records the last time the channel transitioned
1110 * into the given state. Passing 0 for time_in_state and
1111 * intransitions will force the current values to 0. Passing 0
1112 * for last_intransition for all states will disable the notion
1113 * of a channel's "current state."
1114 *
1115 * The most recent last_intransition (amongst all states in a channel)
1116 * logically determines the current state. If last_intransition is
1117 * not provided for any state, the channel will not report a current
1118 * For consistent results, it is important to either never specify
1119 * last_intransition or to always specify it.
1120 *
1121 * There is currently a bug in determining current state (13423273).
1122 * The IOReportMacros.h macros only update the state's metadata
1123 * timestamp and libIOReport only looks at the metadata timestamps
1124 * to determine the current state. Until that bug is fixed, whichever
1125 * state is updated most recently will be considered the "current"
1126 * state by libIOReport.
1127 *
1128 * ::setState()'s automatic "time in state" updates are not supported
1129 * when using overrideChannelState(). Clients must not use
1130 * overrideChannelState() on any channel that has ::setState() called
1131 * on it. Unlike with ::setState(), clients using
1132 * overrideChannelState() are responsible for ensuring that data is
1133 * up to date for updateReport() calls. The correct way to do this
1134 * is for a driver's ::updateReport() method to push the most up to
1135 * date values into the reporters before calling
1136 * super::updateReport().
1137 *
1138 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1139 */
1140 IOReturn overrideChannelState(uint64_t channel_id,
1141 uint64_t state_id,
1142 uint64_t time_in_state,
1143 uint64_t intransitions,
1144 uint64_t last_intransition = 0);
1145
1146/*! @function IOStateReporter::incrementChannelState
1147 * @abstract Updates state data for a channel with passed arguments
1148 *
1149 * @param channel_id - ID of the channel which state is to be updated
1150 * @param state_id - state id for the channel
1151 * @param time_in_state - time to be accumulated for time in state
1152 * @param intransitions - number of transitions into state to be added
1153 * @param last_intransition - mach_absolute_time of most recent entry (opt)
1154 * @result Appropriate IOReturn code
1155 *
1156 * @discussion
1157 * incrementChannelState() adds time_in_state and intransitions
1158 * to the current values stored for a particular state. If provided,
1159 * last_intransition overwrites the time the state was most recently
1160 * entered. Passing 0 for time_in_state and intransitions will have
1161 * no effect. Passing 0 for last_intransition for all states will
1162 * disable the notion of a channel's "current state."
1163 *
1164 * The most recent last_intransition (amongst all states in a channel)
1165 * logically determines the current state. If last_intransition is
1166 * not provided for any state, the channel will not report a current
1167 * For consistent results, it is important to either never specify
1168 * last_intransition or to always specify it.
1169 *
1170 * There is currently a bug in determining current state (13423273).
1171 * The IOReportMacros.h macros only update the state's metadata
1172 * timestamp and libIOReport only looks at the metadata timestamps
1173 * to determine the current state. Until that bug is fixed, whichever
1174 * state is updated most recently will be considered the "current"
1175 * state by libIOReport.
1176 *
1177 * ::setState()'s automatic "time in state" updates are not supported
1178 * when using incrementChannelState(). Clients must not use
1179 * incrementChannelState() on any channel that has ::setState()
1180 * called on it. Unlike with ::setState(), clients using
1181 * incrementChannelState() are responsible for ensuring that data
1182 * is up to date for updateReport() calls. The correct way to do
1183 * this is for a driver's ::updateReport() method to push the most
1184 * up to date values into the reporters before calling
1185 * super::updateReport().
1186 *
1187 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1188 */
1189 IOReturn incrementChannelState(uint64_t channel_id,
1190 uint64_t state_id,
1191 uint64_t time_in_state,
1192 uint64_t intransitions,
1193 uint64_t last_intransition = 0);
1194
1195/*! @function IOStateReporter::setStateByIndices
1196 * @abstract update a channel state without validating channel_id
1197 *
1198 * @param channel_index - 0..<nChannels>, available from getChannelIndex()
1199 * @param new_state_index - New state (by index) for the channel
1200 * @result Appropriate IOReturn code
1201 *
1202 * @discussion
1203 * Similar to setState(), setStateByIndices() sets a channel's state
1204 * without searching for the channel or state IDs. It will perform
1205 * bounds checking, but relies on the caller to properly indicate
1206 * the indices of the channel and state. Clients can rely on channels
1207 * being added to IOStateReporter in order: the first channel will
1208 * have index 0, the second index 1, etc. Like ::setState(),
1209 * "time in state" calculations are handled automatically.
1210 *
1211 * setStateByIndices() is faster than than setChannelState(), but
1212 * it should only be used where the latter's performance overhead
1213 * might be a problem. For example, many channels in a single
1214 * reporter and high-frequency state changes.
1215 *
1216 * Drivers wishing to compute and report their own time in state
1217 * should use incrementChannelState() or overrideChannelState(). It
1218 * is not currently possible for a driver to synchronize with the
1219 * automatic time-keeping enabled by setStateByIndices(). The
1220 * 4-argument version of setChannelState() is thus impossible to
1221 * use correctly. In the future, there may be a setChannelState()
1222 * which accepts a last_intransition parameter and uses it to
1223 * automatically calculate time in state (ERs -> IOReporting / X).
1224 *
1225 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1226 */
1227 IOReturn setStateByIndices(int channel_index,
1228 int new_state_index);
1229
1230/*! @function IOStateReporter::setStateByIndices
1231 * @abstract update a channel state without validating channel_id
1232 *
1233 * @param channel_index - 0..<nChannels>, available from getChannelIndex()
1234 * @param new_state_index - New state (by index) for the channel
1235 * @param last_intransition - deprecated: time of most recent entry
1236 * @param prev_state_residency - deprecated: time spent in previous state
1237 * @result Appropriate IOReturn code
1238 *
1239 * @discussion
1240 * Similar to setState(), setStateByIndices() sets a channel's state
1241 * without searching for the channel or state IDs. It will perform
1242 * bounds checking, but relies on the caller to properly indicate
1243 * the indices of the channel and state. Clients can rely on channels
1244 * being added to IOStateReporter in order: the first channel will
1245 * have index 0, the second index 1, etc. Like ::setState(),
1246 * "time in state" calculations are handled automatically.
1247 *
1248 * setStateByIndices() is faster than than setChannelState(), but
1249 * it should only be used where the latter's performance overhead
1250 * might be a problem. For example, many channels in a single
1251 * reporter and high-frequency state changes.
1252 *
1253 * Drivers wishing to compute and report their own time in state
1254 * should use incrementChannelState() or overrideChannelState(). It
1255 * is not currently possible for a driver to synchronize with the
1256 * automatic time-keeping enabled by setStateByIndices(). The
1257 * 4-argument version of setChannelState() is thus impossible to
1258 * use correctly. In the future, there may be a setChannelState()
1259 * which accepts a last_intransition parameter and uses it to
1260 * automatically calculate time in state (ERs -> IOReporting / X).
1261 *
1262 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1263 */
1264 IOReturn setStateByIndices(int channel_index,
1265 int new_state_index,
1266 uint64_t last_intransition,
1267 uint64_t prev_state_residency) __deprecated;
1268
1269/*! @function IOStateReporter::getStateInTransitions
1270 * @abstract Accessor method for count of transitions into state
1271 *
1272 * @param channel_id - ID of the channel
1273 * @param state_id - State of the channel
1274 * @result Count of transitions into the requested state.
1275 *
1276 * @discussion
1277 * Some clients may need to consume internally the data aggregated by the
1278 * reporter object. This method allows a client to retrieve the count of
1279 * transitions into the requested state for the channel_id.
1280 *
1281 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1282 */
1283 uint64_t getStateInTransitions(uint64_t channel_id,
1284 uint64_t state_id);
1285
1286/*! @function IOStateReporter::getStateResidencyTime
1287 * @abstract Accessor method for time spent in a given state
1288 *
1289 * @param channel_id - ID of the channel
1290 * @param state_id - State of the channel
1291 * @result Absolute time spent in specified state
1292 *
1293 * @discussion
1294 * Some clients may need to consume internally the data aggregated
1295 * by the by the reporter object. This method allows a client to
1296 * retrieve the absolute time a particular channel recorded as spent
1297 * in a specified state.
1298 *
1299 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1300 */
1301 uint64_t getStateResidencyTime(uint64_t channel_id,
1302 uint64_t state_id);
1303
1304/*! @function IOStateReporter::getStateLastTransitionTime
1305 * @abstract Accessor method for last time a transition occured
1306 *
1307 * @param channel_id - ID of the channel
1308 * @param state_id - State of the channel
1309 * @result Absolute time for when the last transition occured
1310 *
1311 * @discussion
1312 * Some clients may need to consume internally the data aggregated
1313 * by the by the reporter object. This method allows a client to
1314 * retrieve the absolute time stamp for when the last transition into
1315 * a specific state was recorded.
1316 *
1317 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1318 */
1319 uint64_t getStateLastTransitionTime(uint64_t channel_id, uint64_t state_id);
1320
1321/*! @function [DEPRECATED] IOStateReporter::getStateLastChannelUpdateTime
1322 * @abstract Deprecated accessor for last time a channel was auto-updated
1323 *
1324 * @param channel_id - ID of the channel
1325 * @result Absolute time for last time the channel was updated
1326 *
1327 * @discussion
1328 * If a channel has had ::setState() called on it, calls such as
1329 * getStateResidencyTime() or updateReport() will update time in the
1330 * current state and update an internal "last channel update time."
1331 * Because clients have no way to interlock with those methods, there
1332 * is no sensible way to use this method and it will be removed in
1333 * a future release.
1334 *
1335 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1336 */
1337 uint64_t getStateLastChannelUpdateTime(uint64_t channel_id) __deprecated;
1338
1339/*! @function IOStateReporter::createLegend
1340 * @abstract Creates a legend entry for an IOStateReporter
1341 *
1342 * @param channelIDs - array of uint64_t channels IDs.
1343 * @param channelNames - parrallel array of const char* channel names
1344 * @param channelCount - number of channels, and size of channelIDs and channelNames
1345 * @param nstates - Maximum number of states for this reporter's channels
1346 * @param categories - The category in which the report should be classified
1347 * @param unit - The unit for the quantity recorded by the reporter object
1348 *
1349 * @result An IOReportLegendEntry object or NULL on failure
1350 *
1351 * @discussion
1352 * This static method supports creating a legend entry for an IOStateReporter
1353 * without actually having an IOStateReporter instance.
1354 * This can be used to lazily create IOReporters in IOService::configureReport()
1355 * rather than during driver initialization.
1356 */
1357 static OSPtr<IOReportLegendEntry> createLegend(const uint64_t *channelIDs,
1358 const char **channelNames,
1359 int channelCount,
1360 int nstates,
1361 IOReportCategories categories,
1362 IOReportUnit unit);
1363
1364/*! @function IOStateReporter::free
1365 * @abstract Releases the object and all its resources.
1366 *
1367 * @discussion
1368 * ::free() assumes that init() has completed. Clients should use
1369 * the static ::with() methods to obtain fully-initialized reporter
1370 * instances.
1371 *
1372 * Locking: same-instance concurrency UNSAFE
1373 */
1374 virtual void free(void) APPLE_KEXT_OVERRIDE;
1375
1376protected:
1377
1378/*! @function IOStateReporter::initWith
1379 * @abstract Instance method implementation called by ::with
1380 *
1381 * @discussion
1382 * See description of parameters above
1383 */
1384 virtual bool initWith(IOService *reportingService,
1385 IOReportCategories categories,
1386 int16_t nstates, IOReportUnit unit);
1387
1388
1389/*! @function IOStateReporter::handleSwapPrepare
1390 * @abstract _swap* = <IOStateReporter-specific per-channel buffers>
1391 * [see IOReporter::handle*Swap* for more info]
1392 */
1393 virtual IOReturn handleSwapPrepare(int newNChannels) APPLE_KEXT_OVERRIDE;
1394
1395/*!
1396 * @function IOStateReporter::handleAddChannelSwap
1397 * @abstract swap in IOStateReporter's variables
1398 */
1399 virtual IOReturn handleAddChannelSwap(uint64_t channel_id,
1400 const OSSymbol *symChannelName) APPLE_KEXT_OVERRIDE;
1401
1402/*!
1403 * @function IOStateReporter::handleSwapCleanup
1404 * @abstract clean up unused buffers in _swap*
1405 */
1406 virtual void handleSwapCleanup(int swapNChannels) APPLE_KEXT_OVERRIDE;
1407
1408/*! @function IOStateReporter::updateChannelValues
1409 * @abstract Update accounting of time spent in current state
1410 *
1411 * @param channel_index - internal index of the channel
1412 * @result appropriate IOReturn code
1413 *
1414 * @discussion
1415 * Internal State reporter method to account for the time spent in
1416 * the current state when updateReport() is called on the reporter's
1417 * channels.
1418 *
1419 * Locking: Caller must ensure that the reporter (data) lock is held.
1420 */
1421 virtual IOReturn updateChannelValues(int channel_index) APPLE_KEXT_OVERRIDE;
1422
1423/*! @function IOStateReporter::handleSetStateByIndices
1424 * @abstract update a channel state without validating channel_id
1425 *
1426 * @param channel_index - 0..<nChannels>, available from getChannelIndex()
1427 * @param new_state_index - New state for the channel
1428 * @param last_intransition - to remove: time of most recent entry
1429 * @param prev_state_residency - to remove: time spent in previous state
1430 * @result Appropriate IOReturn code
1431 *
1432 * @discussion
1433 * Locked version of IOReporter::setStateByIndices(). This method may be
1434 * overriden by sub-classes.
1435 *
1436 * Locking: Caller must ensure that the reporter (data) lock is held.
1437 */
1438 virtual IOReturn handleSetStateByIndices(int channel_index,
1439 int new_state_index,
1440 uint64_t last_intransition,
1441 uint64_t prev_state_residency);
1442
1443/*! @function IOStateReporter::handleSetStateID
1444 * @abstract Assign a non-default ID to a state
1445 *
1446 * @param channel_id - ID of channel containing the state in question
1447 * @param state_index - index of state to give an ID: [0..(nstates-1)]
1448 * @param state_id - 64-bit state ID, for ASCII, use IOREPORT_MAKEID
1449 *
1450 * @result Appropriate IOReturn code
1451 *
1452 * @discussion
1453 * Locked version of IOReporter::setStateID(). This method may be
1454 * overriden by sub-classes
1455 *
1456 * Locking: Caller must ensure that the reporter (data) lock is held.
1457 */
1458 virtual IOReturn handleSetStateID(uint64_t channel_id,
1459 int state_index,
1460 uint64_t state_id);
1461
1462/*! @function IOStateReporter::handleOverrideChannelStateByIndices
1463 * @abstract Overrides state data for a channel with passed arguments
1464 *
1465 * @param channel_index - index of the channel which state is to be updated
1466 * @param state_index - index of the state id for the channel
1467 * @param time_in_state - time used as new total time in state
1468 * @param intransitions - total number of transitions into state
1469 * @param last_intransition - mach_absolute_time of most recent entry (opt)
1470 * @result Appropriate IOReturn code
1471 *
1472 * @discussion
1473 * Locked version of IOReporter::overrideChannelState(). This method
1474 * may be overriden by sub-classes.
1475 *
1476 * Locking: Caller must ensure that the reporter (data) lock is held.
1477 */
1478 virtual IOReturn handleOverrideChannelStateByIndices(int channel_index,
1479 int state_index,
1480 uint64_t time_in_state,
1481 uint64_t intransitions,
1482 uint64_t last_intransition = 0);
1483
1484/*! @function IOStateReporter::handleIncrementChannelStateByIndices
1485 * @abstract Updates state data for a channel with passed arguments
1486 *
1487 * @param channel_index - index of the channel which state is to be updated
1488 * @param state_index - index of the state id for the channel
1489 * @param time_in_state - time used as new total time in state
1490 * @param intransitions - total number of transitions into state
1491 * @param last_intransition - mach_absolute_time of most recent entry (opt)
1492 * @result Appropriate IOReturn code
1493 *
1494 * @discussion
1495 * Locked version of IOReporter::incrementChannelState(). This method
1496 * may be overriden by sub-classes.
1497 *
1498 * Locking: Caller must ensure that the reporter (data) lock is held.
1499 */
1500 virtual IOReturn handleIncrementChannelStateByIndices(int channel_index,
1501 int state_index,
1502 uint64_t time_in_state,
1503 uint64_t intransitions,
1504 uint64_t last_intransition = 0);
1505private:
1506
1507 int *_currentStates; // current states (per chonnel)
1508 uint64_t *_lastUpdateTimes; // most recent auto-update
1509
1510// Required for swapping inside addChannel
1511 int *_swapCurrentStates;
1512 uint64_t *_swapLastUpdateTimes;
1513
1514 enum valueSelector {
1515 kInTransitions,
1516 kResidencyTime,
1517 kLastTransitionTime
1518 };
1519 uint64_t _getStateValue(uint64_t channel_id,
1520 uint64_t state_id,
1521 enum valueSelector value);
1522
1523 IOReturn _getStateIndices(uint64_t channel_id,
1524 uint64_t state_id,
1525 int *channel_index,
1526 int *state_index);
1527};
1528
1529
1530/*!
1531 * @class IOHistogramReporter
1532 * @abstract Report histograms of values
1533 * @discussion
1534 * Each IOHistogramReporter can report one histogram representing
1535 * how a given value has changed over time.
1536 */
1537class IOHistogramReporter : public IOReporter
1538{
1539 OSDeclareDefaultStructors(IOHistogramReporter);
1540
1541public:
1542/*! @function IOHistogramReporter::with
1543 * @abstract Initializes the IOHistogramReporter instance variables and data structures
1544 *
1545 * @param reportingService - The I/O Kit service for this reporter's channels
1546 * @param categories - The categories in which the report should be classified
1547 * @param channelID - uint64_t channel identifier
1548 * @param channelName - rich channel name as char*
1549 * @param unit - The unit for the quantity recorded by the reporter object
1550 * @param nSegments - Number of segments to be extracted from the config data structure
1551 * @param config - Histograms require the caller to pass a configuration by segments
1552 * @result an instance of the IOSimpleReporter object or NULL on error
1553 *
1554 * @discussion
1555 * Creates an instance of histogram reporter object.
1556 *
1557 * FIXME: need more explanation of the config
1558 *
1559 * IOHistogramReporter currently only supports a single channel.
1560 *
1561 *
1562 */
1563 static OSPtr<IOHistogramReporter> with(IOService *reportingService,
1564 IOReportCategories categories,
1565 uint64_t channelID,
1566 const char *channelName,
1567 IOReportUnit unit,
1568 int nSegments,
1569 IOHistogramSegmentConfig *config);
1570
1571/*! @function IOHistogramReporter::addChannel
1572 * @abstract Override IOReporter::addChannel(*) to return an error
1573 *
1574 * @result kIOReturnUnsupported - doesn't support adding channels
1575 */
1576 IOReturn
1577 addChannel(__unused uint64_t channelID, __unused const char *channelName = NULL)
1578 {
1579 return kIOReturnUnsupported;
1580 }
1581
1582/*! @function IOHistogramReporter::overrideBucketValues
1583 * @abstract Override values of a bucket at specified index
1584 *
1585 * @param index - index of bucket to override
1586 * @param bucket_hits - new bucket hits count
1587 * @param bucket_min - new bucket minimum value
1588 * @param bucket_max - new bucket maximum value
1589 * @param bucket_sum - new bucket sum
1590 * @result Appropriate IOReturn code
1591 *
1592 * @discussion
1593 * Replaces data in the bucket at the specified index with the data pointed
1594 * to by bucket. No sanity check is performed on the data. If the index
1595 * is out of bounds, kIOReturnBadArgument is returned.
1596 *
1597 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1598 */
1599
1600 IOReturn overrideBucketValues(unsigned int index,
1601 uint64_t bucket_hits,
1602 int64_t bucket_min,
1603 int64_t bucket_max,
1604 int64_t bucket_sum);
1605
1606/*! @function IOHistogramReporter::tallyValue
1607 * @abstract Add a new value to the histogram
1608 *
1609 * @param value - new value to add to the histogram
1610 * @result the index of the affected bucket, or -1 on error
1611 *
1612 * @discussion
1613 * The histogram reporter determines in which bucket the value
1614 * falls and increments it. The lowest and highest buckets
1615 * extend to negative and positive infinity, respectively.
1616 *
1617 * Locking: same-instance concurrency SAFE, WILL NOT BLOCK
1618 */
1619 int tallyValue(int64_t value);
1620
1621/*! @function IOHistogramReporter::createLegend
1622 * @abstract Creates a legend entry for an IOStateReporter
1623 *
1624 * @param channelID - uint64_t channel identifier
1625 * @param channelName - rich channel name as char*
1626 * @param segmentCount - Number of segments to be extracted from the config data structure
1627 * @param config - Histograms require the caller to pass a configuration by segments
1628 * @param categories - The category in which the report should be classified
1629 * @param unit - The unit for the quantity recorded by the reporter object
1630 *
1631 * @result An IOReportLegendEntry object or NULL on failure
1632 *
1633 * @discussion
1634 * This static method supports creating a legend entry for an IOStateReporter
1635 * without actually having an IOStateReporter instance.
1636 * This can be used to lazily create IOReporters in IOService::configureReport()
1637 * rather than during driver initialization.
1638 */
1639 static OSPtr<IOReportLegendEntry> createLegend(const uint64_t channelID,
1640 const char *channelName,
1641 int segmentCount,
1642 IOHistogramSegmentConfig *config,
1643 IOReportCategories categories,
1644 IOReportUnit unit);
1645
1646/*! @function IOHistogramReporter::free
1647 * @abstract Releases the object and all its resources.
1648 *
1649 * @discussion
1650 * ::free() assumes that init() has completed. Clients should use
1651 * the static ::with() methods to obtain fully-initialized reporter
1652 * instances.
1653 *
1654 * Locking: same-instance concurrency UNSAFE
1655 */
1656 virtual void free(void) APPLE_KEXT_OVERRIDE;
1657
1658protected:
1659
1660/*! @function IOHistogramReporter::initWith
1661 * @abstract instance method implementation called by ::with
1662 *
1663 * @discussion
1664 * See description of parameters above
1665 */
1666 virtual bool initWith(IOService *reportingService,
1667 IOReportCategories categories,
1668 uint64_t channelID,
1669 const OSSymbol *channelName,
1670 IOReportUnit unit,
1671 int nSegments,
1672 IOHistogramSegmentConfig *config);
1673
1674/*! @function IOHistogramReporter::handleCreateLegend
1675 * @abstract Builds an IOReporting legend entry representing the channels of this reporter.
1676 *
1677 * @result An IOReportLegendEntry or NULL on failure
1678 *
1679 * @discussion
1680 * The returned legend entry may be appended to kIOReportLegendKey
1681 * to be published by the caller in the IORegistry. See the
1682 * IOReportLegend class for more details.
1683 *
1684 * Locking: same-instance concurrency SAFE, MAY BLOCK
1685 */
1686 OSPtr<IOReportLegendEntry> handleCreateLegend(void) APPLE_KEXT_OVERRIDE;
1687
1688
1689private:
1690
1691 int _segmentCount;
1692 int64_t *_bucketBounds;
1693 int _bucketCount;
1694 IOHistogramSegmentConfig *_histogramSegmentsConfig;
1695};
1696
1697
1698/***********************************/
1699/***** 4. IOReportLegend Class *****/
1700/***********************************/
1701
1702/*!
1703 * @class IOReportLegend
1704 * @abstract combine legend entries into a complete legend
1705 * @discussion
1706 * IOReportLegend adds metadata to legend entries and combines them
1707 * into a single OSArray that can be published under the
1708 * kIOReportLegendKey property in the I/O Kit registry.
1709 */
1710class IOReportLegend : public OSObject
1711{
1712 OSDeclareDefaultStructors(IOReportLegend);
1713
1714public:
1715/*! @function IOReportLegend::with
1716 * @abstract Create an instance of IOReportLegend
1717 *
1718 * @param legend - OSArray of the legend possibly already present in registry
1719 * @result an instance of IOReportLegend, or NULL on failure
1720 *
1721 * @discussion
1722 * An IOReporting legend (an OSArray of legend entries) may be already
1723 * present in the IORegistry. Thus the recommended way to publish
1724 * new entries is to append to any existing array as follows:
1725 * 1. call getProperty(kIOReportLegendKey) to get an existing legend.
1726 *
1727 * 2a. If it exists
1728 * - OSDynamicCast to OSArray
1729 * - and pass it to ::with()
1730 * IOReportLegend *legendMaker = IOReportLegend::with(legend);
1731 * The provided array is retained by IOReportLegend.
1732 *
1733 * 2b. If no legend already exists in the registry, pass NULL
1734 * IOReportLegend *legend = IOReportLegend::with(NULL);
1735 * This latter invocation will cause IOReportLegend to create a new
1736 * array internally (also holding one reference).
1737 *
1738 * At the cost of some registry churn, the static
1739 * IOReportLegend::addReporterLegend() will handle the above, removing
1740 * the need for any direct use of the IOReportLegend class.
1741 */
1742 static OSPtr<IOReportLegend> with(OSArray *legend);
1743
1744/*! @function IOReportLegend::addLegendEntry
1745 * @abstract Add a new legend entry
1746 *
1747 * @param legendEntry - entry to be added to the internal legend array
1748 * @param groupName - primary group name for this entry
1749 * @param subGroupName - secondary group name for this entry
1750 * @result appropriate IOReturn code
1751 *
1752 * @discussion
1753 * The entry will be retained as an element of the internal array.
1754 * Legend entries are available from reporter objects. Entries
1755 * represent some number of channels with similar properties (such
1756 * as group and sub-group). Multiple legend entries with the same
1757 * group names will be aggregated in user space.
1758 *
1759 * Drivers that instantiate their reporter objects in response to
1760 * IOService::configureReport(kIOReportDisable) will need to create
1761 * temporary reporter objects for the purpose of creating their
1762 * legend entries. User-space legends are tracked by 12836893.
1763 */
1764 IOReturn addLegendEntry(IOReportLegendEntry *legendEntry,
1765 const char *groupName,
1766 const char *subGroupName);
1767
1768/*! @function IOReportLegend::addReporterLegend
1769 * @abstract Add a legend entry from a reporter object
1770 *
1771 * @param reporter - IOReporter to use to extract and append the legend
1772 * @param groupName - primary group name for this entry
1773 * @param subGroupName - secondary group name for this entry
1774 * @result appropriate IOReturn code
1775 *
1776 * @discussion
1777 * An IOReportLegendEntry will be created internally to this method from
1778 * the IOReporter object passed in argument. The entry will be released
1779 * internally after being appended to the IOReportLegend object.
1780 * Legend entries are available from reporter objects. Entries
1781 * represent some number of channels with similar properties (such
1782 * as group and sub-group). Multiple legend entries with the same
1783 * group names will be aggregated in user space.
1784 *
1785 * Drivers that instantiate their reporter objects in response to
1786 * IOService::configureReport(kIOReportDisable) will need to create
1787 * temporary reporter objects for the purpose of creating their
1788 * legend entries. User-space legends are tracked by 12836893.
1789 *
1790 * Locking: same-reportingService and same-IORLegend concurrency UNSAFE
1791 */
1792 IOReturn addReporterLegend(IOReporter *reporter,
1793 const char *groupName,
1794 const char *subGroupName);
1795
1796/*! @function IOReportLegend::addReporterLegend
1797 * @abstract Add a legend entry from a reporter object
1798 *
1799 * @param reportingService - IOService data provider into the reporter object
1800 * @param reporter - IOReporter to use to extract and append the legend
1801 * @param groupName - primary group name for this entry
1802 * @param subGroupName - secondary group name for this entry
1803 * @result appropriate IOReturn code
1804 *
1805 * @discussion
1806 * An IOReportLegendEntry will be created internally to this method from
1807 * the IOReporter object passed in argument. The entry will be released
1808 * internally after being appended to the IOReportLegend object.
1809 * Legend entries are available from reporter objects. Entries
1810 * represent some number of channels with similar properties (such
1811 * as group and sub-group). Multiple legend entries with the same
1812 * group names will be aggregated in user space.
1813 *
1814 * Drivers that instantiate their reporter objects in response to
1815 * IOService::configureReport(kIOReportDisable) will need to create
1816 * temporary reporter objects for the purpose of creating their
1817 * legend entries. User-space legends are tracked by 12836893.
1818 *
1819 * The static version of addReporterLegend adds the reporter's legend
1820 * directly to reportingService's kIOReportLegendKey. It is not
1821 * possible to safely update kIOReportLegendKey from multiple threads.
1822 *
1823 * Locking: same-reportingService and same-IORLegend concurrency UNSAFE
1824 */
1825 static IOReturn addReporterLegend(IOService *reportingService,
1826 IOReporter *reporter,
1827 const char *groupName,
1828 const char *subGroupName);
1829
1830/*! @function IOReportLegend::getLegend
1831 * @abstract Accessor method to get the legend array
1832 *
1833 * @result Returns the OSObject holding the legend to be published by the driver
1834 * @discussion
1835 * This array will include all legend entries added to the object.
1836 */
1837 OSArray* getLegend(void);
1838
1839/*! @function IOReportLegend::free
1840 * @abstract Frees the IOReportLegend object
1841 *
1842 * @discussion
1843 * ::free() cleans up the reporter and anything it allocated.
1844 *
1845 * ::free() releases the internal array (which was either passed
1846 * to ::with() or created as a result of ::with(NULL)). Assuming
1847 * the caller extracted the array with getLegend() and published it
1848 * in the I/O Kit registry, its ownership will now be with the
1849 * registry.
1850 */
1851 void free(void) APPLE_KEXT_OVERRIDE;
1852
1853
1854
1855protected:
1856
1857private:
1858
1859 OSPtr<OSArray> _reportLegend;
1860
1861 IOReturn initWith(OSArray *legend);
1862
1863/*! @function IOReportLegend::organizeLegend
1864 * @abstract Sets up the legend entry, organizing it with group and sub-group names
1865 *
1866 * @param groupName - Primary group name
1867 * @param subGroupName - Secondary group name
1868 * @result IOReturn code
1869 */
1870 IOReturn organizeLegend(IOReportLegendEntry *legendEntry,
1871 const OSSymbol *groupName,
1872 const OSSymbol *subGroupName);
1873
1874// FUTURE POSSIBILITY (NOT IMPLEMENTED!)
1875/*! @function IOReportLegend::createReporters
1876 * @abstract Creates as many IOReporter objects as the legend contains
1877 *
1878 * @param legend - OSArray legend object containing the description of all reporters
1879 * the driver is able to address
1880 * @param reporter - OSSet of reporter objects created by this call
1881 * @result IOReturn code kIOReturnSuccess if successful
1882 *
1883 * @discussion
1884 * NOT SUPPORTED at the time of writing
1885 * Convenience method to create all the driver's reporter objects from a legend.
1886 * Can be used when a legend is made public through the IORegistry but IOReporter
1887 * objects have not yet been created to save memory, waiting for observers.
1888 * Upon a call to configureReport via the IOService method, a driver could
1889 * create all reporter objects on the fly using this function.
1890 */
1891// For Future IOReporterManager...
1892// static IOReturn createReporters(requestedChannels, legend);
1893};
1894
1895#endif /* ! _IOKERNEL_REPORTERS_H_ */
1896