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      * The scheduler replaced the current process image with a new one. The
 189      * process should also be renamed at this point. In windows, this is part of
 190      * the spawn process as well as fork.
 191      *
 192      * @return the event name
 193      *
 194      * @since 2.0
 195      */
 196     String eventSchedProcessExec();
 197
 198     /**
 199      * The scheduler calls wakeup on a sleeping process. The process will
 200      * probably soon be scheduled in.
 201      *
 202      * @return the event name
 203      *
 204      * @since 2.0
 205      */
 206     String eventSchedProcessWakeup();
 207
 208     /**
 209      * The scheduler calls wakeup on a sleeping process. The process will
 210      * probably soon be scheduled in. The new wakeup knows who triggered the
 211      * wakeup.
 212      *
 213      * @return the event name
 214      *
 215      * @since 2.0
 216      */
 217     String eventSchedProcessWakeupNew();
 218
 219
 220     /**
 221      * Starting the high resolution timer
 222      * <p>
 223      * In Linux, High resolution timers are used in the following:
 224      * <ul>
 225      * <li>nanosleep</li>
 226      * <li>itimers</li>
 227      * <li>posix timers</li>
 228      * </ul>
 229      *
 230      * @return the event name
 231      *
 232      * @since 2.0
 233      */
 234     String eventHRTimerStart();
 235
 236     /**
 237      * Canceling the high resolution timer
 238      * <p>
 239      * In Linux, High resolution timers are used in the following:
 240      * <ul>
 241      * <li>nanosleep</li>
 242      * <li>itimers</li>
 243      * <li>posix timers</li>
 244      * </ul>
 245      *
 246      * @return the event name
 247      *
 248      * @since 2.0
 249      */
 250     String eventHRTimerCancel();
 251
 252     /**
 253      * Entering the high resolution timer expired handler.
 254      * <p>
 255      * In Linux, High resolution timers are used in the following:
 256      * <ul>
 257      * <li>nanosleep</li>
 258      * <li>itimers</li>
 259      * <li>posix timers</li>
 260      * </ul>
 261      *
 262      * @return the event name
 263      *
 264      * @since 2.0
 265      */
 266     String eventHRTimerExpireEntry();
 267
 268     /**
 269      * Exiting the high resolution timer expired handler.
 270      * <p>
 271      * In Linux, High resolution timers are used in the following:
 272      * <ul>
 273      * <li>nanosleep</li>
 274      * <li>itimers</li>
 275      * <li>posix timers</li>
 276      * </ul>
 277      *
 278      * @return the event name
 279      *
 280      * @since 2.0
 281      */
 282     String eventHRTimerExpireExit();
 283
 284     // ------------------------------------------------------------------------
 285     // Event field names
 286     // ------------------------------------------------------------------------
 287
 288     /**
 289      * The field with the IRQ number. This is used in irq_handlers (entry and
 290      * exit). For soft IRQs see {@link #fieldVec}.
 291      *
 292      * @return the name of the field with the IRQ number
 293      */
 294     String fieldIrq();
 295
 296     /**
 297      * The field with the vector. This is the soft IRQ vector field used in soft
 298      * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
 299      *
 300      * @return the name of the field with the soft IRQ vector name
 301      */
 302     String fieldVec();
 303
 304     /**
 305      * The field with the thread ID. This is often used in scheduler calls to
 306      * know which thread is being affected. (normally not in switch, but in
 307      * priority and wakeup calls).
 308      *
 309      * @return the name of the field with the thread ID
 310      */
 311     String fieldTid();
 312
 313     /**
 314      * The field with the previous thread id. This is used in switching
 315      * operations of a scheduler, when a thread is scheduled out for another,
 316      * this field shows the thread id being scheduled out.
 317      *
 318      * @return The name of the field with the ID of the previous thread
 319      */
 320     String fieldPrevTid();
 321
 322     /**
 323      * The field with the state of the previous thread. This is used in
 324      * switching operations of a scheduler, when a thread is scheduled out for
 325      * another, this field shows the state of the thread being scheduled out.
 326      *
 327      * @return the name of the field of the previous thread's state
 328      */
 329     String fieldPrevState();
 330
 331     /**
 332      * The field with the next command to be run. This is used in switching
 333      * operations of a scheduler, when a thread is scheduled out for another,
 334      * this field shows the command being scheduled in. A command's value is
 335      * often a String like "ls" or "hl3.exe".
 336      *
 337      * @return the name of the field with the next command to be run
 338      */
 339     String fieldNextComm();
 340
 341     /**
 342      * The field with the next thread ID. This is used in switching operations
 343      * of a scheduler, when a thread is scheduled out for another, this field
 344      * shows the thread being scheduled in.
 345      *
 346      * @return the name of the field with the next thread ID
 347      */
 348     String fieldNextTid();
 349
 350     /**
 351      * The field with the child command. This field is used in clone and spawn
 352      * activities, to know which executable the clone is running.
 353      *
 354      * @return the name of the field with the child command
 355      */
 356     String fieldChildComm();
 357
 358     /**
 359      * The field with the parent thread ID. This field is used in clone and
 360      * spawn activities, to know which thread triggered the clone.
 361      *
 362      * @return the name of the field with the parent thread ID
 363      */
 364     String fieldParentTid();
 365
 366     /**
 367      * The field with the child thread ID. This field is used in clone and spawn
 368      * activities, to know which thread is the clone.
 369      *
 370      * @return the name of the field with the child thread ID
 371      */
 372     String fieldChildTid();
 373
 374     /**
 375      * The field with the command. This is used in scheduling tracepoints that
 376      * are not switches, and show the current process name. It is often a string
 377      * like "zsh" or "cmd.exe".
 378      *
 379      * @return the name of the command field
 380      * @since 2.0
 381      */
 382     String fieldComm();
 383
 384     /**
 385      * The field with the name. The name field is used in several disjoint
 386      * events.
 387      * <p>
 388      * Examples include:
 389      * <ul>
 390      * <li>writeback_* - the name of the io device, often "(unknown)"</li>
 391      * <li>module_* - the name of the module such as "binfmt_misc"</li>
 392      * <li>irq_handler_entry - the field describes the name of the handler such
 393      * as "i915"</li>
 394      * <ul>
 395      *
 396      * @return the name of the field with a name
 397      * @since 2.0
 398      */
 399     String fieldName();
 400
 401     /**
 402      * The field with the status. Often functions like a return value before we
 403      * hit an exit.
 404      * <p>
 405      * Examples include:
 406      * <ul>
 407      * <li>ext4* - status</li>
 408      * <li>asoc_snd_soc_cache_sync</li>
 409      * <li>rpc_*</li>
 410      * <li>state dumps</li>
 411      * </ul>
 412      *
 413      * @return The name of the field with a status
 414      * @since 2.0
 415      */
 416     String fieldStatus();
 417
 418     /**
 419      * The field with the last command to be run. This is often a string
 420      * representing the command of the thread being scheduled out from a
 421      * scheduler switch operation.
 422      *
 423      * @return the name of the field with the last command to be run
 424      * @since 2.0
 425      */
 426     String fieldPrevComm();
 427
 428     /**
 429      * The field with the file name field. This is a string used mostly with
 430      * file operations. These operations are often wrapped in system calls and
 431      * can be:
 432      * <ul>
 433      * <li>open</li>
 434      * <li>change mode</li>
 435      * <li>change directory</li>
 436      * <li>stat</li>
 437      * </ul>
 438      * It can also be used in exec commands to see what the command name should
 439      * be.
 440      * <p>
 441      * Please note that file read and write often do not use the file name, they
 442      * just use the file handle.
 443      *
 444      * @return the name of the field with the file name
 445      * @since 2.0
 446      */
 447     String fieldFilename();
 448
 449     /**
 450      * The field with the priority. The priority of a given process is used by
 451      * most scheduler events. The major exception is the switching operation as
 452      * it has two processes so it has a previous and next priority.
 453      *
 454      * @return the name of the field with the thread or process' priority
 455      * @since 1.0
 456      */
 457     String fieldPrio();
 458
 459     /**
 460      * The field with the new priority. This is used in the scheduler's
 461      * pi_setprio event event to show the new priority of the thread or process.
 462      *
 463      * @return the name of the field with the thread or process' new priority
 464      * @since 1.0
 465      */
 466     String fieldNewPrio();
 467
 468     /**
 469      * The field with the next priority. This is used in the scheduler's switch
 470      * event to show the priority of the next thread or process.
 471      *
 472      * @return the name of the field with the thread or process' next priority
 473      * @since 1.0
 474      */
 475     String fieldNextPrio();
 476
 477     /**
 478      * The field with the hrtimer. The hrtimer holds the timer instance.
 479      *
 480      * @return the name of the hrTimer field
 481      * @since 2.0
 482      */
 483     String fieldHRtimer();
 484
 485     /**
 486      * The field with the expires value. The expires field holds the expiry time.
 487      * of the hrtimer.
 488      *
 489      * @return the name of the expires field
 490      * @since 2.0
 491      */
 492     String fieldHRtimerExpires();
 493
 494     /**
 495      * Gets the field name with the softexpires value. The softexpire value is the
 496      * absolute earliest expiry time of the hrtimer.
 497      *
 498      * @return the name of the softexpires field
 499      * @since 2.0
 500      */
 501     String fieldHRtimerSoftexpires();
 502
 503     /**
 504      * The field of the function address value. The function field holds timer
 505      * expiry callback function.
 506      *
 507      * @return the name of the function field
 508      * @since 2.0
 509      */
 510     String fieldHRtimerFunction();
 511
 512     /**
 513      * The field of the now value. The now field holds the current time.
 514      *
 515      * @return the name of the now field (hrtimer)
 516      * @since 2.0
 517      */
 518     String fieldHRtimerNow();
 519
 520 }