osfmk/mach/etap.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  * @OSF_COPYRIGHT@
  27  *
  28  */
  29 /*
  30  * File : etap.h
  31  *
  32  *        Contains ETAP buffer and table definitions
  33  *
  34  */
  35
  36 #ifndef _MACH_ETAP_H_
  37 #define _MACH_ETAP_H_
  38
  39 #include <mach/machine/boolean.h>
  40 #include <mach/etap_events.h>
  41 #include <mach/clock_types.h>
  42 #include <mach/time_value.h>
  43 #include <mach/kern_return.h>
  44
  45
  46 #define ETAP_CBUFF_ENTRIES      20000
  47 #define ETAP_CBUFF_IBUCKETS     10
  48 #define ETAP_CBUFF_WIDTH        80
  49
  50 #define ETAP_MBUFF_ENTRIES      28000
  51 #define ETAP_MBUFF_DATASIZE     4
  52
  53
  54 /* ===================================
  55  * Event & Subsystem Table Definitions
  56  * ===================================
  57  */
  58
  59 #define EVENT_NAME_LENGTH    20                    /* max event name size  */
  60
  61 struct  event_table_entry {
  62         unsigned short  event;                     /* etap event type      */
  63         unsigned short  status;                    /* event trace status   */
  64         char            name [EVENT_NAME_LENGTH];  /* event text name      */
  65         unsigned short  dynamic;                   /* dynamic ID (0=none)  */
  66 };
  67
  68 struct  subs_table_entry {
  69         unsigned short  subs;                      /* etap subsystem type  */
  70         char            name [EVENT_NAME_LENGTH];  /* subsystem text name  */
  71 };
  72
  73 typedef struct event_table_entry*       event_table_t;
  74 typedef struct subs_table_entry*        subs_table_t;
  75 typedef unsigned short                  etap_event_t;
  76
  77 #define EVENT_TABLE_NULL                ((event_table_t) 0)
  78
  79 /* =========
  80  * ETAP Time
  81  * =========
  82  */
  83
  84 typedef mach_timespec_t etap_time_t;
  85
  86 /* =============================
  87  * Cumulative buffer definitions
  88  * =============================
  89  */
  90
  91 /*
  92  *  The cbuff_data structure contains cumulative lock
  93  *  statistical information for EITHER hold operations
  94  *  OR wait operations.
  95  */
  96
  97 struct cbuff_data {
  98         unsigned long   triggered;       /* number of event occurances  */
  99         etap_time_t     time;            /* sum of event durations      */
 100         etap_time_t     time_sq;         /* sum of squared durations    */
 101         etap_time_t     min_time;        /* min duration of event       */
 102         etap_time_t     max_time;        /* max duration of event       */
 103 };
 104
 105 /*
 106  *  The cbuff_entry contains all trace data for an event.
 107  *  The cumulative buffer consists of these entries.
 108  */
 109
 110 struct cbuff_entry {
 111         etap_event_t      event;                     /* event type           */
 112         unsigned short    kind;                      /* read,write,or simple */
 113         unsigned int      instance;                  /* & of event struct    */
 114         struct cbuff_data hold;                      /* hold trace data      */
 115         struct cbuff_data wait;                      /* wait trace data      */
 116         unsigned long hold_interval[ETAP_CBUFF_IBUCKETS];   /* hold interval array  */
 117         unsigned long wait_interval[ETAP_CBUFF_IBUCKETS];   /* wait interval array  */
 118 };
 119
 120 typedef struct cbuff_entry* cbuff_entry_t;
 121
 122 #define CBUFF_ENTRY_NULL        ((cbuff_entry_t)0)
 123
 124 /*
 125  *  The cumulative buffer maintains a header which is used by
 126  *  both the kernel instrumentation and the ETAP user-utilities.
 127  */
 128
 129 struct cumulative_buffer {
 130         unsigned long      next;                   /* next available entry in buffer */
 131         unsigned short     static_start;          /* first static entry in buffer   */
 132         struct cbuff_entry  entry [ETAP_CBUFF_ENTRIES];  /* buffer entries   */
 133 };
 134
 135 typedef struct cumulative_buffer* cumulative_buffer_t;
 136
 137
 138 /* ===========================
 139  * ETAP probe data definitions
 140  * ===========================
 141  */
 142
 143 typedef unsigned int    etap_data_t[ETAP_MBUFF_DATASIZE];
 144
 145 #define ETAP_DATA_ENTRY sizeof(unsigned int)
 146 #define ETAP_DATA_SIZE  ETAP_DATA_ENTRY * ETAP_MBUFF_DATASIZE
 147 #define ETAP_DATA_NULL  (etap_data_t*) 0
 148
 149 /* ==========================
 150  * Monitor buffer definitions
 151  * ==========================
 152  */
 153
 154 /*
 155  *  The mbuff_entry structure contains trace event instance data.
 156  */
 157
 158 struct mbuff_entry {
 159         unsigned short  event;      /* event type                             */
 160         unsigned short  flags;      /* event strain flags                     */
 161         unsigned int    instance;   /* address of event (lock, thread, etc.)  */
 162         unsigned int    pc;         /* program counter                        */
 163         etap_time_t     time;       /* operation time                         */
 164         etap_data_t     data;       /* event specific data                    */
 165 };
 166
 167 typedef struct mbuff_entry* mbuff_entry_t;
 168
 169 /*
 170  *  Each circular monitor buffer will contain maintanence
 171  *  information and mon_entry records.
 172  */
 173
 174 struct monitor_buffer {
 175         unsigned long           free;        /* index of next available record */
 176         unsigned long           timestamp;   /* timestamp of last wrap around  */
 177         struct mbuff_entry entry[1]; /* buffer entries (holder)        */
 178 };
 179
 180 typedef struct monitor_buffer* monitor_buffer_t;
 181
 182
 183 /* ===================
 184  * Event strains/flags
 185  * ===================
 186  */                                     /* | |t|b|e|k|u|m|s|r|w| | | | | */
 187                                         /* ----------------------------- */
 188 #define  WRITE_LOCK     0x10            /* | | | | | | | | | |1| | | | | */
 189 #define  READ_LOCK      0x20            /* | | | | | | | | |1| | | | | | */
 190 #define  COMPLEX_LOCK   0x30            /* | | | | | | | | |1|1| | | | | */
 191 #define  SPIN_LOCK      0x40            /* | | | | | | | |1| | | | | | | */
 192 #define  MUTEX_LOCK     0x80            /* | | | | | | |1| | | | | | | | */
 193 #define  USER_EVENT     0x100           /* | | | | | |1| | | | | | | | | */
 194 #define  KERNEL_EVENT   0x200           /* | | | | |1| | | | | | | | | | */
 195 #define  EVENT_END      0x400           /* | | | |1| | | | | | | | | | | */
 196 #define  EVENT_BEGIN    0x800           /* | | |1| | | | | | | | | | | | */
 197 #define  SYSCALL_TRAP   0x1000          /* | |1| | | | | | | | | | | | | */
 198
 199
 200 /* =========================
 201  * Event trace status values
 202  * =========================
 203  */                                     /* | | | | | | | | | | |M|M|C|C| */
 204                                         /* | | | | | | | | | | |d|c|d|c| */
 205                                         /* ----------------------------- */
 206 #define CUM_CONTENTION  0x1             /* | | | | | | | | | | | | | |1| */
 207 #define CUM_DURATION    0x2             /* | | | | | | | | | | | | |1| | */
 208 #define MON_CONTENTION  0x4             /* | | | | | | | | | | | |1| | | */
 209 #define MON_DURATION    0x8             /* | | | | | | | | | | |1| | | | */
 210
 211 #define ETAP_TRACE_ON   0xf             /* | | | | | | | | | | |1|1|1|1| */
 212 #define ETAP_TRACE_OFF  0x0             /* | | | | | | | | | | | | | | | */
 213
 214
 215 /* ==================
 216  * ETAP trace flavors
 217  * ==================
 218  */
 219
 220 /* Mode */
 221
 222 #define ETAP_CUMULATIVE 0x3             /* | | | | | | | | | | | | |1|1| */
 223 #define ETAP_MONITORED  0xc             /* | | | | | | | | | | |1|1| | | */
 224 #define ETAP_RESET      0xf0f0
 225
 226 /* Type */
 227
 228 #define ETAP_CONTENTION 0x5             /* | | | | | | | | | | | |1| |1| */
 229 #define ETAP_DURATION   0xa             /* | | | | | | | | | | |1| |1| | */
 230
 231
 232 /* ===============================
 233  * Buffer/Table flavor definitions
 234  * ===============================
 235  */
 236
 237 #define  ETAP_TABLE_EVENT               0
 238 #define  ETAP_TABLE_SUBSYSTEM           1
 239 #define  ETAP_BUFFER_CUMULATIVE         2
 240 #define  ETAP_BUFFER_MONITORED          3
 241
 242 /* ==========================
 243  * ETAP function declarations
 244  * ==========================
 245  */
 246
 247 extern
 248 kern_return_t           etap_trace_event(
 249                                    unsigned short       mode,
 250                                    unsigned short       type,
 251                                    boolean_t            enable,
 252                                    unsigned int         nargs,
 253                                    unsigned short       args[]);
 254
 255 extern
 256 kern_return_t           etap_probe(
 257                                    unsigned short       eventno,
 258                                    unsigned short       event_id,
 259                                    unsigned int         data_size,
 260                                    etap_data_t          *data);
 261
 262 /* =================================================================
 263  * convienience user probe macro - only used if DO_PROBE is #defined
 264  * =================================================================
 265  */
 266 #ifdef DO_PROBE
 267 #define PROBE_DATA(subsys, tag, data0, data1, data2, data3) \
 268         { \
 269         etap_data_t _mmmm; \
 270         _mmmm[0] = (u_int)data0; \
 271         _mmmm[1] = (u_int)data1; \
 272         _mmmm[2] = (u_int)data2; \
 273         _mmmm[3] = (u_int)data3; \
 274         etap_probe(subsys, tag, sizeof (etap_data_t), &_mmmm); \
 275         }
 276 #else
 277 #define PROBE_DATA(type, tag, data0, data1, data2, data3)
 278 #endif  /* DO_PROBE */
 279 #endif  /* _MACH_ETAP_H_ */