iokit/IOKit/IOInterruptAccounting.h

   1 /*
   2  * Copyright (c) 2014 Apple Computer, 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 #ifndef __IOKIT_IOINTERRUPTACCOUNTING_H
  30 #define __IOKIT_IOINTERRUPTACCOUNTING_H
  31
  32 /*
  33  * This header contains definitions that will be needed by userspace clients of the interrupt accounting
  34  * mechanisms.
  35  */
  36
  37 #define IA_INDEX_MAX (255)
  38 #define IA_INDEX_MASK (0xFFULL)
  39 #define IA_STATISTIC_INDEX_SHIFT (0ULL)
  40 #define IA_INTERRUPT_INDEX_SHIFT (16ULL)
  41
  42 /*
  43  * For the moment, the indices aren't preprocessor visible, so any changes to this code will need to be
  44  * careful to ensure that the defined number of statistics matches (or is greater than) the actual number
  45  * of statistics, to avoid channel ID collisions... because that would be bad.
  46  */
  47 #define IA_NUM_INTERRUPT_ACCOUNTING_STATISTICS (10)
  48
  49 /*
  50  * Channel ID related definitions.  These serve to denote the namespace of interrupt accounting in the
  51  * context of IOReporter-based clients.  Interrupt accounting distinguishes between interrupts based on
  52  * the nub the interrupt was registered relative to, and the nub relative interrupt index (i.e, the
  53  * namespace for interrupt accounting is {nub ID, interrupt index}).  IOReporting already knows about
  54  * nubs (in the context of IOService), however it has no built in knowledge of interrupt accounting.
  55  * As a result of this, it is the responsibility of the IOReporting client to request any desired
  56  * statistics on a per-index basis (i.e, if you want to get the first level interrupt count for all
  57  * interrupts, you must express an interest in the first level interrupt count statistic for index 0, 1,
  58  * 2, and so on, to a reasonable maximum).
  59  */
  60
  61 /*
  62  * These delimit the channel ID namespace for interrupt accounting.
  63  */
  64 #define IA_BASE_CHANNEL_ID IOREPORT_MAKEID('I', 'n', 't', 'r', 0, 0, 0, 0) /* First valid channel ID */
  65 #define IA_MAX_CHANNEL_ID IOREPORT_MAKEID('I', 'n', 't', 'r', 0xFF, 0xFF, 0xFF, 0xFF) /* Last valid channel ID */
  66
  67 /*
  68  * Given a nub-relative interrupt index (an index into the interrupt specifiers), and the index of a
  69  * interrupt accounting statistic, returns the channel id for that statistic.
  70  */
  71 #define IA_GET_CHANNEL_ID(interruptIndex, statisticIndex) \
  72     ((IA_BASE_CHANNEL_ID) + \
  73     ((interruptIndex % IA_INDEX_MASK) << IA_INTERRUPT_INDEX_SHIFT) + \
  74     ((statisticIndex % IA_INDEX_MASK) << IA_STATISTIC_INDEX_SHIFT))
  75
  76 /*
  77  * Extracts the interrupt index, given a channel ID.
  78  */
  79 #define IA_GET_INTERRUPT_INDEX(channelID) \
  80     (((channelID - IA_BASE_CHANNEL_ID) >> IA_INTERRUPT_INDEX_SHIFT) % IA_INDEX_MASK)
  81
  82 /*
  83  * Extracts the statistic index, given a channel ID.
  84  */
  85 #define IA_GET_STATISTIC_INDEX(channelID) \
  86     (((channelID - IA_BASE_CHANNEL_ID) >> IA_STATISTIC_INDEX_SHIFT) % IA_INDEX_MASK)
  87
  88 /*
  89  * This enum defines the basic statistics we gather for each interrupt.  Currently, the information
  90  * we gather falls into roughly three buckets: interrupt related (counts, times), scheduler related
  91  * (thread wakeups), and power related (package/cpu state changes).
  92  *
  93  * First Level Count: This represents the number of times that this interrupt has fired (more
  94  *   specifically, the number of times we have run the handler we expect to run in interrupt context).
  95  *
  96  * Second Level Count: This represents the number of times we have run any second level handler for
  97  *   this interrupt (more specifically, the handler we expect to be run in the regular kernel context).
  98  *
  99  * First Level Time: This represents the aggregate time spent running the first level handler.  For
 100  *   some interrupts, this value will be 0, as this is not meant to track time spent running generic
 101  *   IOKit code for the interrupt (i.e, IOInterruptEventSource code), but instead any custom code run
 102  *   at the interrupt context (i.e, the filter installed for an IOFilterInterruptEventSource).
 103  *
 104  * Second Level CPU Time: This represents the aggregate time spent actually running the second level
 105  *   handler on the CPU.  As the second level handler may block or be preempted, it is meaningful to
 106  *   distinguish this from the system time spent handling the interrupt.  As was the case for the
 107  *   first level handler, this does not attempt to track the time spent running generic IOKit code
 108  *   (i.e, IOInterruptEventSource code or IOWorkLoop code), but instead attempts to track the time
 109  *   spent running the handler that was installed.
 110  *
 111  * Second Level System Time: This represents the aggregate time spent in the second level handler;
 112  *   this will include time where the handler was blocked or had been preempted.  This should equate
 113  *   to the wall time spent handling an interrupt (as long as we don't allow the system to go to
 114  *   sleep while a second level handler is running).
 115  *
 116  * No Thread Wakeups: The number of times that the interrupt did not attempt to wake up a thread
 117  *   (typically the work loop for the interrupt source is woken up).
 118  *
 119  * Total Thread Wakeups: The aggregate number of threads (non-unique) woken up by the interrupt.
 120  *   If no threads were actually woken up for an interrupt (i.e, the work loop thread was already
 121  *   runnable), this value will not change.
 122  *
 123  * Package Wakeups: The number of times that this interrupt woke up the package (as defined by the
 124  *   scheduler).
 125  *
 126  * CPU Wakeups: The number of times that this interrupt woke up a CPU (forcing it to go through the
 127  *   reset path).
 128  *
 129  * Idle Exits: The number of times that this interrupt forced a CPU out of the idle loop (the CPU
 130  *   had to exit an idle state to handle the interrupt, but it did not need to go through the reset
 131  *   path).
 132  */
 133 enum {
 134     kInterruptAccountingFirstLevelCountIndex = 0, /* Number of times we invoked the top level handler */
 135     kInterruptAccountingSecondLevelCountIndex, /* Number of times we invoked the workloop action */
 136     kInterruptAccountingFirstLevelTimeIndex, /* Time spent in the top level handler, if one was installed */
 137     kInterruptAccountingSecondLevelCPUTimeIndex, /* CPU time spent in the workloop action */
 138     kInterruptAccountingSecondLevelSystemTimeIndex, /* System time spent in the workloop action */
 139     kInterruptAccountingNoThreadWakeupsIndex, /* Number of first level (filter) invocations that did not wake up a thread */
 140     kInterruptAccountingTotalThreadWakeupsIndex, /* Number of actual thread wakeups caused by this interrupt */
 141     kInterruptAccountingPackageWakeupsIndex, /* Number of times this interrupt woke up the package */
 142     kInterruptAccountingCPUWakeupsIndex, /* Number of times this interrupt woke up a CPU */
 143     kInterruptAccountingIdleExitsIndex, /* Number of times this interrupt forced a CPU out of the idle loop */
 144     kInterruptAccountingInvalidStatisticIndex /* Sentinel value for checking for a nonsensical index */
 145 };
 146
 147 /*
 148  * IOReporting group name; exposed publicly for the purpose of getting channels by group
 149  * name; other strings (subgroup names, statistic names) are not exposed, as we may want
 150  * to change them in the future.
 151  */
 152 #define kInterruptAccountingGroupName "Interrupt Statistics (by index)"
 153
 154 #endif /* __IOKIT_IOINTERRUPTACCOUNTING_PRIVATE_H */
 155