osfmk/mach/etap.h

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