analysis/org.eclipse.tracecompass.analysis.os.linux.core/src/org/eclipse/tracecompass/analysis/os/linux/core/trace/IKernelAnalysisEventLayout.java

   1 /*******************************************************************************
   2  * Copyright (c) 2014, 2015 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Alexandre Montplaisir - Initial API and implementation
  11  ******************************************************************************/
  12
  13 package org.eclipse.tracecompass.analysis.os.linux.core.trace;
  14
  15 import java.util.Collection;
  16
  17 import org.eclipse.jdt.annotation.Nullable;
  18
  19 /**
  20  * Interface to define "concepts" present in the Linux kernel (represented by
  21  * its tracepoints), that can then be exposed by different tracers under
  22  * different names.
  23  *
  24  * @author Alexandre Montplaisir
  25  * @author Matthew Khouzam - Javadoc
  26  */
  27 public interface IKernelAnalysisEventLayout {
  28
  29     // ------------------------------------------------------------------------
  30     // Common definitions
  31     // ------------------------------------------------------------------------
  32
  33     /**
  34      * The standard layout, very useful for test vectors that are not kernel
  35      * based.
  36      */
  37     IKernelAnalysisEventLayout DEFAULT_LAYOUT = DefaultEventLayout.INSTANCE;
  38
  39     /**
  40      * Whenever a process appears for the first time in a trace, we assume it
  41      * starts inside this system call. (The syscall prefix is defined by the
  42      * implementer of this interface.)
  43      *
  44      * TODO Change to a default method with Java 8?
  45      */
  46     String INITIAL_SYSCALL_NAME = "clone"; //$NON-NLS-1$
  47
  48     // ------------------------------------------------------------------------
  49     // Event names
  50     // ------------------------------------------------------------------------
  51
  52     /**
  53      * The system has just entered an interrupt handler or interrupt service
  54      * routine. On some systems, this is known as the first level interrupt
  55      * handler.
  56      *
  57      * @return the event name
  58      */
  59     String eventIrqHandlerEntry();
  60
  61     /**
  62      * The system will soon return from an interrupt handler or interrupt
  63      * service routine.
  64      *
  65      * @return the event name
  66      */
  67     String eventIrqHandlerExit();
  68
  69     /**
  70      * Whenever a system call is about to return to userspace, or a hardware
  71      * interrupt handler exits, any 'software interrupts' which are marked
  72      * pending (usually by hardware interrupts) are run. Much of the real
  73      * interrupt handling work is done here. The soft IRQ is also known as a
  74      * deferred IRQ in windows. An event identifying as this needs to occur as
  75      * the system is beginning to process the interrupt.
  76      *
  77      * @return the event name
  78      */
  79     String eventSoftIrqEntry();
  80
  81     /**
  82      * Whenever a system call is about to return to userspace, or a hardware
  83      * interrupt handler exits, any 'software interrupts' which are marked
  84      * pending (usually by hardware interrupts) are run Much of the real
  85      * interrupt handling work is done here. The soft IRQ is also known as a
  86      * deferred IRQ in windows. An event identifying as this needs to occur as
  87      * the system is returning from the interrupt.
  88      *
  89      * @return the event name
  90      */
  91     String eventSoftIrqExit();
  92
  93     /**
  94      * Whenever a system call is about to return to userspace, or a hardware
  95      * interrupt handler exits, any 'software interrupts' which are marked
  96      * pending (usually by hardware interrupts) are run Much of the real
  97      * interrupt handling work is done here. The soft IRQ is also known as a
  98      * deferred IRQ in windows. An event identifying as this needs to occur as
  99      * the system is signaling the need to enter the interrupt.
 100      *
 101      * @return the event name
 102      */
 103     String eventSoftIrqRaise();
 104
 105     /**
 106      * The scheduler will call a scheduler switch event when it is removing a
 107      * task from a cpu and placing another one in its place. Which task and when
 108      * depend on the scheduling strategy and the task priorities. This is a
 109      * context switch.
 110      *
 111      * @return the event name
 112      */
 113     String eventSchedSwitch();
 114
 115     /**
 116      * sched_PI_setprio is a tracepoint called often when the schedulder
 117      * priorities for a given task changes.
 118      *
 119      * @return the event name
 120      * @since 1.0
 121      */
 122     String eventSchedPiSetprio();
 123
 124     /**
 125      * Scheduler is waking up a task. this happens before it is executed, and
 126      * the data is loaded in memory if needed.
 127      *
 128      * @return the event names, as there are often several different ways to
 129      *         wake up
 130      */
 131     Collection<String> eventsSchedWakeup();
 132
 133     /**
 134      * Scheduler just forked a process, that means it has duplicated the program
 135      * and assigned it a different process ID. This event is often followed by
 136      * an {@link #eventSchedProcessExec()}. In windows, this is part of the
 137      * "spawn" process.
 138      *
 139      * @return the event name
 140      */
 141     String eventSchedProcessFork();
 142
 143     /**
 144      * The process has finished running and the scheduler takes its TID back.
 145      *
 146      * @return the event name
 147      */
 148     String eventSchedProcessExit();
 149
 150     /**
 151      * The process free tracepoint is called when a process has finished running
 152      * and the scheduler retrieves it's process ID.
 153      *
 154      * @return the event name
 155      */
 156     String eventSchedProcessFree();
 157
 158     /**
 159      * Optional event used by some tracers to deliver an initial state.
 160      *
 161      * @return the event name
 162      */
 163     @Nullable String eventStatedumpProcessState();
 164
 165     /**
 166      * System call entry prefix, something like "sys_open" or just "sys".
 167      *
 168      * @return the event name
 169      */
 170     String eventSyscallEntryPrefix();
 171
 172     /**
 173      * System call compatibility layer entry prefix, something like
 174      * "compat_sys".
 175      *
 176      * @return the event name
 177      */
 178     String eventCompatSyscallEntryPrefix();
 179
 180     /**
 181      * System call exit prefix, something like "sys_exit".
 182      *
 183      * @return the event name
 184      */
 185     String eventSyscallExitPrefix();
 186
 187     /**
 188      * System call compatibility layer exit prefix, something like
 189      * "compat_syscall_exit".
 190      *
 191      * @return the event name
 192      * @since 2.0
 193      */
 194     String eventCompatSyscallExitPrefix();
 195
 196     /**
 197      * The scheduler replaced the current process image with a new one. The
 198      * process should also be renamed at this point. In windows, this is part of
 199      * the spawn process as well as fork.
 200      *
 201      * @return the event name
 202      *
 203      * @since 2.0
 204      */
 205     String eventSchedProcessExec();
 206
 207     /**
 208      * The scheduler calls wakeup on a sleeping process. The process will
 209      * probably soon be scheduled in.
 210      *
 211      * @return the event name
 212      *
 213      * @since 2.0
 214      */
 215     String eventSchedProcessWakeup();
 216
 217     /**
 218      * The scheduler calls wakeup on a sleeping process. The process will
 219      * probably soon be scheduled in. The new wakeup knows who triggered the
 220      * wakeup.
 221      *
 222      * @return the event name
 223      *
 224      * @since 2.0
 225      */
 226     String eventSchedProcessWakeupNew();
 227
 228
 229     /**
 230      * Starting the high resolution timer
 231      * <p>
 232      * In Linux, High resolution timers are used in the following:
 233      * <ul>
 234      * <li>nanosleep</li>
 235      * <li>itimers</li>
 236      * <li>posix timers</li>
 237      * </ul>
 238      *
 239      * @return the event name
 240      *
 241      * @since 2.0
 242      */
 243     String eventHRTimerStart();
 244
 245     /**
 246      * Canceling the high resolution timer
 247      * <p>
 248      * In Linux, High resolution timers are used in the following:
 249      * <ul>
 250      * <li>nanosleep</li>
 251      * <li>itimers</li>
 252      * <li>posix timers</li>
 253      * </ul>
 254      *
 255      * @return the event name
 256      *
 257      * @since 2.0
 258      */
 259     String eventHRTimerCancel();
 260
 261     /**
 262      * Entering the high resolution timer expired handler.
 263      * <p>
 264      * In Linux, High resolution timers are used in the following:
 265      * <ul>
 266      * <li>nanosleep</li>
 267      * <li>itimers</li>
 268      * <li>posix timers</li>
 269      * </ul>
 270      *
 271      * @return the event name
 272      *
 273      * @since 2.0
 274      */
 275     String eventHRTimerExpireEntry();
 276
 277     /**
 278      * Exiting the high resolution timer expired handler.
 279      * <p>
 280      * In Linux, High resolution timers are used in the following:
 281      * <ul>
 282      * <li>nanosleep</li>
 283      * <li>itimers</li>
 284      * <li>posix timers</li>
 285      * </ul>
 286      *
 287      * @return the event name
 288      *
 289      * @since 2.0
 290      */
 291     String eventHRTimerExpireExit();
 292
 293     // ------------------------------------------------------------------------
 294     // Event field names
 295     // ------------------------------------------------------------------------
 296
 297     /**
 298      * The field with the IRQ number. This is used in irq_handlers (entry and
 299      * exit). For soft IRQs see {@link #fieldVec}.
 300      *
 301      * @return the name of the field with the IRQ number
 302      */
 303     String fieldIrq();
 304
 305     /**
 306      * The field with the vector. This is the soft IRQ vector field used in soft
 307      * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
 308      *
 309      * @return the name of the field with the soft IRQ vector name
 310      */
 311     String fieldVec();
 312
 313     /**
 314      * The field with the thread ID. This is often used in scheduler calls to
 315      * know which thread is being affected. (normally not in switch, but in
 316      * priority and wakeup calls).
 317      *
 318      * @return the name of the field with the thread ID
 319      */
 320     String fieldTid();
 321
 322     /**
 323      * The field with the previous thread id. This is used in switching
 324      * operations of a scheduler, when a thread is scheduled out for another,
 325      * this field shows the thread id being scheduled out.
 326      *
 327      * @return The name of the field with the ID of the previous thread
 328      */
 329     String fieldPrevTid();
 330
 331     /**
 332      * The field with the state of the previous thread. This is used in
 333      * switching operations of a scheduler, when a thread is scheduled out for
 334      * another, this field shows the state of the thread being scheduled out.
 335      *
 336      * @return the name of the field of the previous thread's state
 337      */
 338     String fieldPrevState();
 339
 340     /**
 341      * The field with the next command to be run. This is used in switching
 342      * operations of a scheduler, when a thread is scheduled out for another,
 343      * this field shows the command being scheduled in. A command's value is
 344      * often a String like "ls" or "hl3.exe".
 345      *
 346      * @return the name of the field with the next command to be run
 347      */
 348     String fieldNextComm();
 349
 350     /**
 351      * The field with the next thread ID. This is used in switching operations
 352      * of a scheduler, when a thread is scheduled out for another, this field
 353      * shows the thread being scheduled in.
 354      *
 355      * @return the name of the field with the next thread ID
 356      */
 357     String fieldNextTid();
 358
 359     /**
 360      * The field with the child command. This field is used in clone and spawn
 361      * activities, to know which executable the clone is running.
 362      *
 363      * @return the name of the field with the child command
 364      */
 365     String fieldChildComm();
 366
 367     /**
 368      * The field with the parent thread ID. This field is used in clone and
 369      * spawn activities, to know which thread triggered the clone.
 370      *
 371      * @return the name of the field with the parent thread ID
 372      */
 373     String fieldParentTid();
 374
 375     /**
 376      * The field with the child thread ID. This field is used in clone and spawn
 377      * activities, to know which thread is the clone.
 378      *
 379      * @return the name of the field with the child thread ID
 380      */
 381     String fieldChildTid();
 382
 383     /**
 384      * The field with the command. This is used in scheduling tracepoints that
 385      * are not switches, and show the current process name. It is often a string
 386      * like "zsh" or "cmd.exe".
 387      *
 388      * @return the name of the command field
 389      * @since 2.0
 390      */
 391     String fieldComm();
 392
 393     /**
 394      * The field with the name. The name field is used in several disjoint
 395      * events.
 396      * <p>
 397      * Examples include:
 398      * <ul>
 399      * <li>writeback_* - the name of the io device, often "(unknown)"</li>
 400      * <li>module_* - the name of the module such as "binfmt_misc"</li>
 401      * <li>irq_handler_entry - the field describes the name of the handler such
 402      * as "i915"</li>
 403      * <ul>
 404      *
 405      * @return the name of the field with a name
 406      * @since 2.0
 407      */
 408     String fieldName();
 409
 410     /**
 411      * The field with the status. Often functions like a return value before we
 412      * hit an exit.
 413      * <p>
 414      * Examples include:
 415      * <ul>
 416      * <li>ext4* - status</li>
 417      * <li>asoc_snd_soc_cache_sync</li>
 418      * <li>rpc_*</li>
 419      * <li>state dumps</li>
 420      * </ul>
 421      *
 422      * @return The name of the field with a status
 423      * @since 2.0
 424      */
 425     String fieldStatus();
 426
 427     /**
 428      * The field with the last command to be run. This is often a string
 429      * representing the command of the thread being scheduled out from a
 430      * scheduler switch operation.
 431      *
 432      * @return the name of the field with the last command to be run
 433      * @since 2.0
 434      */
 435     String fieldPrevComm();
 436
 437     /**
 438      * The field with the file name field. This is a string used mostly with
 439      * file operations. These operations are often wrapped in system calls and
 440      * can be:
 441      * <ul>
 442      * <li>open</li>
 443      * <li>change mode</li>
 444      * <li>change directory</li>
 445      * <li>stat</li>
 446      * </ul>
 447      * It can also be used in exec commands to see what the command name should
 448      * be.
 449      * <p>
 450      * Please note that file read and write often do not use the file name, they
 451      * just use the file handle.
 452      *
 453      * @return the name of the field with the file name
 454      * @since 2.0
 455      */
 456     String fieldFilename();
 457
 458     /**
 459      * The field with the priority. The priority of a given process is used by
 460      * most scheduler events. The major exception is the switching operation as
 461      * it has two processes so it has a previous and next priority.
 462      *
 463      * @return the name of the field with the thread or process' priority
 464      * @since 1.0
 465      */
 466     String fieldPrio();
 467
 468     /**
 469      * The field with the new priority. This is used in the scheduler's
 470      * pi_setprio event event to show the new priority of the thread or process.
 471      *
 472      * @return the name of the field with the thread or process' new priority
 473      * @since 1.0
 474      */
 475     String fieldNewPrio();
 476
 477     /**
 478      * The field with the next priority. This is used in the scheduler's switch
 479      * event to show the priority of the next thread or process.
 480      *
 481      * @return the name of the field with the thread or process' next priority
 482      * @since 1.0
 483      */
 484     String fieldNextPrio();
 485
 486     /**
 487      * The field with the hrtimer. The hrtimer holds the timer instance.
 488      *
 489      * @return the name of the hrTimer field
 490      * @since 2.0
 491      */
 492     String fieldHRtimer();
 493
 494     /**
 495      * The field with the expires value. The expires field holds the expiry time.
 496      * of the hrtimer.
 497      *
 498      * @return the name of the expires field
 499      * @since 2.0
 500      */
 501     String fieldHRtimerExpires();
 502
 503     /**
 504      * Gets the field name with the softexpires value. The softexpire value is the
 505      * absolute earliest expiry time of the hrtimer.
 506      *
 507      * @return the name of the softexpires field
 508      * @since 2.0
 509      */
 510     String fieldHRtimerSoftexpires();
 511
 512     /**
 513      * The field of the function address value. The function field holds timer
 514      * expiry callback function.
 515      *
 516      * @return the name of the function field
 517      * @since 2.0
 518      */
 519     String fieldHRtimerFunction();
 520
 521     /**
 522      * The field of the now value. The now field holds the current time.
 523      *
 524      * @return the name of the now field (hrtimer)
 525      * @since 2.0
 526      */
 527     String fieldHRtimerNow();
 528
 529 }