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      * Whenever a process appears for the first time in a trace, we assume it
  35      * starts inside this system call. (The syscall prefix is defined by the
  36      * implementer of this interface.)
  37      *
  38      * TODO Change to a default method with Java 8?
  39      */
  40     String INITIAL_SYSCALL_NAME = "clone"; //$NON-NLS-1$
  41
  42     // ------------------------------------------------------------------------
  43     // Event names
  44     // ------------------------------------------------------------------------
  45
  46     /**
  47      * The system has just entered an interrupt handler or interrupt service
  48      * routine. On some systems, this is known as the first level interrupt
  49      * handler.
  50      *
  51      * @return the event name
  52      */
  53     String eventIrqHandlerEntry();
  54
  55     /**
  56      * The system will soon return from an interrupt handler or interrupt
  57      * service routine.
  58      *
  59      * @return the event name
  60      */
  61     String eventIrqHandlerExit();
  62
  63     /**
  64      * Whenever a system call is about to return to userspace, or a hardware
  65      * interrupt handler exits, any 'software interrupts' which are marked
  66      * pending (usually by hardware interrupts) are run. Much of the real
  67      * interrupt handling work is done here. The soft IRQ is also known as a
  68      * deferred IRQ in windows. An event identifying as this needs to occur as
  69      * the system is beginning to process the interrupt.
  70      *
  71      * @return the event name
  72      */
  73     String eventSoftIrqEntry();
  74
  75     /**
  76      * Whenever a system call is about to return to userspace, or a hardware
  77      * interrupt handler exits, any 'software interrupts' which are marked
  78      * pending (usually by hardware interrupts) are run Much of the real
  79      * interrupt handling work is done here. The soft IRQ is also known as a
  80      * deferred IRQ in windows. An event identifying as this needs to occur as
  81      * the system is returning from the interrupt.
  82      *
  83      * @return the event name
  84      */
  85     String eventSoftIrqExit();
  86
  87     /**
  88      * Whenever a system call is about to return to userspace, or a hardware
  89      * interrupt handler exits, any 'software interrupts' which are marked
  90      * pending (usually by hardware interrupts) are run Much of the real
  91      * interrupt handling work is done here. The soft IRQ is also known as a
  92      * deferred IRQ in windows. An event identifying as this needs to occur as
  93      * the system is signaling the need to enter the interrupt.
  94      *
  95      * @return the event name
  96      */
  97     String eventSoftIrqRaise();
  98
  99     /**
 100      * The scheduler will call a scheduler switch event when it is removing a
 101      * task from a cpu and placing another one in its place. Which task and when
 102      * depend on the scheduling strategy and the task priorities. This is a
 103      * context switch.
 104      *
 105      * @return the event name
 106      */
 107     String eventSchedSwitch();
 108
 109     /**
 110      * sched_PI_setprio is a tracepoint called often when the schedulder
 111      * priorities for a given task changes.
 112      *
 113      * @return the event name
 114      * @since 1.0
 115      */
 116     String eventSchedPiSetprio();
 117
 118     /**
 119      * Scheduler is waking up a task. this happens before it is executed, and
 120      * the data is loaded in memory if needed.
 121      *
 122      * @return the event names, as there are often several different ways to
 123      *         wake up
 124      */
 125     Collection<String> eventsSchedWakeup();
 126
 127     /**
 128      * Scheduler just forked a process, that means it has duplicated the program
 129      * and assigned it a different process ID. This event is often followed by
 130      * an {@link #eventSchedProcessExec()}. In windows, this is part of the
 131      * "spawn" process.
 132      *
 133      * @return the event name
 134      */
 135     String eventSchedProcessFork();
 136
 137     /**
 138      * The process has finished running and the scheduler takes its TID back.
 139      *
 140      * @return the event name
 141      */
 142     String eventSchedProcessExit();
 143
 144     /**
 145      * The process free tracepoint is called when a process has finished running
 146      * and the scheduler retrieves it's process ID.
 147      *
 148      * @return the event name
 149      */
 150     String eventSchedProcessFree();
 151
 152     /**
 153      * Optional event used by some tracers to deliver an initial state.
 154      *
 155      * @return the event name
 156      */
 157     @Nullable String eventStatedumpProcessState();
 158
 159     /**
 160      * System call entry prefix, something like "sys_open" or just "sys".
 161      *
 162      * @return the event name
 163      */
 164     String eventSyscallEntryPrefix();
 165
 166     /**
 167      * System call compatibility layer entry prefix, something like
 168      * "compat_sys".
 169      *
 170      * @return the event name
 171      */
 172     String eventCompatSyscallEntryPrefix();
 173
 174     /**
 175      * System call exit prefix, something like "sys_exit".
 176      *
 177      * @return the event name
 178      */
 179     String eventSyscallExitPrefix();
 180
 181     /**
 182      * System call compatibility layer exit prefix, something like
 183      * "compat_syscall_exit".
 184      *
 185      * @return the event name
 186      * @since 2.0
 187      */
 188     String eventCompatSyscallExitPrefix();
 189
 190     /**
 191      * The scheduler replaced the current process image with a new one. The
 192      * process should also be renamed at this point. In windows, this is part of
 193      * the spawn process as well as fork.
 194      *
 195      * @return the event name
 196      *
 197      * @since 2.0
 198      */
 199     String eventSchedProcessExec();
 200
 201     /**
 202      * The scheduler calls wakeup on a sleeping process. The process will
 203      * probably soon be scheduled in.
 204      *
 205      * @return the event name
 206      *
 207      * @since 2.0
 208      */
 209     String eventSchedProcessWakeup();
 210
 211     /**
 212      * The scheduler calls wakeup on a sleeping process. The process will
 213      * probably soon be scheduled in. The new wakeup knows who triggered the
 214      * wakeup.
 215      *
 216      * @return the event name
 217      *
 218      * @since 2.0
 219      */
 220     String eventSchedProcessWakeupNew();
 221
 222
 223     /**
 224      * Starting the high resolution timer
 225      * <p>
 226      * In Linux, High resolution timers are used in the following:
 227      * <ul>
 228      * <li>nanosleep</li>
 229      * <li>itimers</li>
 230      * <li>posix timers</li>
 231      * </ul>
 232      *
 233      * @return the event name
 234      *
 235      * @since 2.0
 236      */
 237     String eventHRTimerStart();
 238
 239     /**
 240      * Canceling the high resolution timer
 241      * <p>
 242      * In Linux, High resolution timers are used in the following:
 243      * <ul>
 244      * <li>nanosleep</li>
 245      * <li>itimers</li>
 246      * <li>posix timers</li>
 247      * </ul>
 248      *
 249      * @return the event name
 250      *
 251      * @since 2.0
 252      */
 253     String eventHRTimerCancel();
 254
 255     /**
 256      * Entering the high resolution timer expired handler.
 257      * <p>
 258      * In Linux, High resolution timers are used in the following:
 259      * <ul>
 260      * <li>nanosleep</li>
 261      * <li>itimers</li>
 262      * <li>posix timers</li>
 263      * </ul>
 264      *
 265      * @return the event name
 266      *
 267      * @since 2.0
 268      */
 269     String eventHRTimerExpireEntry();
 270
 271     /**
 272      * Exiting the high resolution timer expired handler.
 273      * <p>
 274      * In Linux, High resolution timers are used in the following:
 275      * <ul>
 276      * <li>nanosleep</li>
 277      * <li>itimers</li>
 278      * <li>posix timers</li>
 279      * </ul>
 280      *
 281      * @return the event name
 282      *
 283      * @since 2.0
 284      */
 285     String eventHRTimerExpireExit();
 286
 287     /**
 288      * The kernel just allocated a page of memory.
 289      * <p>
 290      * In Linux, this typically means a user space application just got a page of
 291      * ram.
 292      *
 293      * @return the event name
 294      * @since 2.0
 295      */
 296     String eventKmemPageAlloc();
 297
 298     /**
 299      * The kernel just deallocated a page of memory.
 300      * <p>
 301      * In Linux, this typically means a page of ram was just freed
 302      *
 303      * @return the event name
 304      * @since 2.0
 305      */
 306     String eventKmemPageFree();
 307
 308     // ------------------------------------------------------------------------
 309     // Event field names
 310     // ------------------------------------------------------------------------
 311
 312     /**
 313      * The field with the IRQ number. This is used in irq_handlers (entry and
 314      * exit). For soft IRQs see {@link #fieldVec}.
 315      *
 316      * @return the name of the field with the IRQ number
 317      */
 318     String fieldIrq();
 319
 320     /**
 321      * The field with the vector. This is the soft IRQ vector field used in soft
 322      * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
 323      *
 324      * @return the name of the field with the soft IRQ vector name
 325      */
 326     String fieldVec();
 327
 328     /**
 329      * The field with the thread ID. This is often used in scheduler calls to
 330      * know which thread is being affected. (normally not in switch, but in
 331      * priority and wakeup calls).
 332      *
 333      * @return the name of the field with the thread ID
 334      */
 335     String fieldTid();
 336
 337     /**
 338      * The field with the previous thread id. This is used in switching
 339      * operations of a scheduler, when a thread is scheduled out for another,
 340      * this field shows the thread id being scheduled out.
 341      *
 342      * @return The name of the field with the ID of the previous thread
 343      */
 344     String fieldPrevTid();
 345
 346     /**
 347      * The field with the state of the previous thread. This is used in
 348      * switching operations of a scheduler, when a thread is scheduled out for
 349      * another, this field shows the state of the thread being scheduled out.
 350      *
 351      * @return the name of the field of the previous thread's state
 352      */
 353     String fieldPrevState();
 354
 355     /**
 356      * The field with the next command to be run. This is used in switching
 357      * operations of a scheduler, when a thread is scheduled out for another,
 358      * this field shows the command being scheduled in. A command's value is
 359      * often a String like "ls" or "hl3.exe".
 360      *
 361      * @return the name of the field with the next command to be run
 362      */
 363     String fieldNextComm();
 364
 365     /**
 366      * The field with the next thread ID. This is used in switching operations
 367      * of a scheduler, when a thread is scheduled out for another, this field
 368      * shows the thread being scheduled in.
 369      *
 370      * @return the name of the field with the next thread ID
 371      */
 372     String fieldNextTid();
 373
 374     /**
 375      * The field with the child command. This field is used in clone and spawn
 376      * activities, to know which executable the clone is running.
 377      *
 378      * @return the name of the field with the child command
 379      */
 380     String fieldChildComm();
 381
 382     /**
 383      * The field with the parent thread ID. This field is used in clone and
 384      * spawn activities, to know which thread triggered the clone.
 385      *
 386      * @return the name of the field with the parent thread ID
 387      */
 388     String fieldParentTid();
 389
 390     /**
 391      * The field with the child thread ID. This field is used in clone and spawn
 392      * activities, to know which thread is the clone.
 393      *
 394      * @return the name of the field with the child thread ID
 395      */
 396     String fieldChildTid();
 397
 398     /**
 399      * The field with the command. This is used in scheduling tracepoints that
 400      * are not switches, and show the current process name. It is often a string
 401      * like "zsh" or "cmd.exe".
 402      *
 403      * @return the name of the command field
 404      * @since 2.0
 405      */
 406     String fieldComm();
 407
 408     /**
 409      * The field with the name. The name field is used in several disjoint
 410      * events.
 411      * <p>
 412      * Examples include:
 413      * <ul>
 414      * <li>writeback_* - the name of the io device, often "(unknown)"</li>
 415      * <li>module_* - the name of the module such as "binfmt_misc"</li>
 416      * <li>irq_handler_entry - the field describes the name of the handler such
 417      * as "i915"</li>
 418      * <ul>
 419      *
 420      * @return the name of the field with a name
 421      * @since 2.0
 422      */
 423     String fieldName();
 424
 425     /**
 426      * The field with the status. Often functions like a return value before we
 427      * hit an exit.
 428      * <p>
 429      * Examples include:
 430      * <ul>
 431      * <li>ext4* - status</li>
 432      * <li>asoc_snd_soc_cache_sync</li>
 433      * <li>rpc_*</li>
 434      * <li>state dumps</li>
 435      * </ul>
 436      *
 437      * @return The name of the field with a status
 438      * @since 2.0
 439      */
 440     String fieldStatus();
 441
 442     /**
 443      * The field with the last command to be run. This is often a string
 444      * representing the command of the thread being scheduled out from a
 445      * scheduler switch operation.
 446      *
 447      * @return the name of the field with the last command to be run
 448      * @since 2.0
 449      */
 450     String fieldPrevComm();
 451
 452     /**
 453      * The field with the file name field. This is a string used mostly with
 454      * file operations. These operations are often wrapped in system calls and
 455      * can be:
 456      * <ul>
 457      * <li>open</li>
 458      * <li>change mode</li>
 459      * <li>change directory</li>
 460      * <li>stat</li>
 461      * </ul>
 462      * It can also be used in exec commands to see what the command name should
 463      * be.
 464      * <p>
 465      * Please note that file read and write often do not use the file name, they
 466      * just use the file handle.
 467      *
 468      * @return the name of the field with the file name
 469      * @since 2.0
 470      */
 471     String fieldFilename();
 472
 473     /**
 474      * The field with the priority. The priority of a given process is used by
 475      * most scheduler events. The major exception is the switching operation as
 476      * it has two processes so it has a previous and next priority.
 477      *
 478      * @return the name of the field with the thread or process' priority
 479      * @since 1.0
 480      */
 481     String fieldPrio();
 482
 483     /**
 484      * The field with the new priority. This is used in the scheduler's
 485      * pi_setprio event event to show the new priority of the thread or process.
 486      *
 487      * @return the name of the field with the thread or process' new priority
 488      * @since 1.0
 489      */
 490     String fieldNewPrio();
 491
 492     /**
 493      * The field with the next priority. This is used in the scheduler's switch
 494      * event to show the priority of the next thread or process.
 495      *
 496      * @return the name of the field with the thread or process' next priority
 497      * @since 1.0
 498      */
 499     String fieldNextPrio();
 500
 501     /**
 502      * The field with the hrtimer. The hrtimer holds the timer instance.
 503      *
 504      * @return the name of the hrTimer field
 505      * @since 2.0
 506      */
 507     String fieldHRtimer();
 508
 509     /**
 510      * The field with the expires value. The expires field holds the expiry time.
 511      * of the hrtimer.
 512      *
 513      * @return the name of the expires field
 514      * @since 2.0
 515      */
 516     String fieldHRtimerExpires();
 517
 518     /**
 519      * Gets the field name with the softexpires value. The softexpire value is the
 520      * absolute earliest expiry time of the hrtimer.
 521      *
 522      * @return the name of the softexpires field
 523      * @since 2.0
 524      */
 525     String fieldHRtimerSoftexpires();
 526
 527     /**
 528      * The field of the function address value. The function field holds timer
 529      * expiry callback function.
 530      *
 531      * @return the name of the function field
 532      * @since 2.0
 533      */
 534     String fieldHRtimerFunction();
 535
 536     /**
 537      * The field of the now value. The now field holds the current time.
 538      *
 539      * @return the name of the now field (hrtimer)
 540      * @since 2.0
 541      */
 542     String fieldHRtimerNow();
 543
 544     /**
 545      * The field containing the return value of a system call exit.
 546      *
 547      * @return The name of return field
 548      * @since 2.0
 549      */
 550     default String fieldSyscallRet() {
 551         return "ret"; //$NON-NLS-1$
 552     }
 553
 554     // ------------------------------------------------------------------------
 555     // I/O events and fields
 556     // ------------------------------------------------------------------------
 557
 558     /**
 559      * A request to a block IO has just been inserted in the waiting queue.
 560      *
 561      * @return The name of the event
 562      * @since 2.0
 563      */
 564     default String eventBlockRqInsert() {
 565         return "block_rq_insert"; //$NON-NLS-1$
 566     }
 567
 568     /**
 569      * A request to a block IO has just been issued and passed from the waiting
 570      * queue to the driver queue. It is being served.
 571      *
 572      * @return The name of the event
 573      * @since 2.0
 574      */
 575     default String eventBlockRqIssue() {
 576         return "block_rq_issue"; //$NON-NLS-1$
 577     }
 578
 579     /**
 580      * A request to a block IO has just been completed.
 581      *
 582      * @return The name of the event
 583      * @since 2.0
 584      */
 585     default String eventBlockRqComplete() {
 586         return "block_rq_complete"; //$NON-NLS-1$
 587     }
 588
 589     /**
 590      * A BIO operation is being merged at the front of a waiting request
 591      *
 592      * @return The name of the event
 593      * @since 2.0
 594      */
 595     default String eventBlockBioFrontmerge() {
 596         return "block_bio_frontmerge"; //$NON-NLS-1$
 597     }
 598
 599     /**
 600      * A BIO operation is being merged at the back of a waiting request
 601      *
 602      * @return The name of the event
 603      * @since 2.0
 604      */
 605     default String eventBlockBioBackmerge() {
 606         return "block_bio_backmerge"; //$NON-NLS-1$
 607     }
 608
 609     /**
 610      * 2 requests previously inserted in the waiting queue are being merged
 611      *
 612      * @return The name of the event
 613      * @since 2.0
 614      */
 615     default String eventBlockRqMerge() {
 616         return "block_rq_merge"; //$NON-NLS-1$
 617     }
 618
 619     /**
 620      * Optional event used by some tracers to associate the name of the block
 621      * device to a device ID
 622      *
 623      * @return The name of the event
 624      * @since 2.0
 625      */
 626     default @Nullable String eventStatedumpBlockDevice() {
 627         return null;
 628     }
 629
 630     /**
 631      * The field containing the device ID
 632      *
 633      * @return The name of the field
 634      * @since 2.0
 635      */
 636     default String fieldBlockDeviceId() {
 637         return "dev"; //$NON-NLS-1$
 638     }
 639
 640     /**
 641      * The field with the first sector of a block operation
 642      *
 643      * @return The name of the field
 644      * @since 2.0
 645      */
 646     default String fieldBlockSector() {
 647         return "sector"; //$NON-NLS-1$
 648     }
 649
 650     /**
 651      * The field with the number of sectors involved in a block operation
 652      *
 653      * @return The name of the field
 654      * @since 2.0
 655      */
 656     default String fieldBlockNrSector() {
 657         return "nr_sector"; //$NON-NLS-1$
 658     }
 659
 660     /**
 661      * The field containing the read/write flag of a block operation
 662      *
 663      * @return The name of the field
 664      * @since 2.0
 665      */
 666     default String fieldBlockRwbs() {
 667         return "rwbs"; //$NON-NLS-1$
 668     }
 669
 670     /**
 671      * The field with the first sector of a request in which another block
 672      * operation is being merged
 673      *
 674      * @return The name of the field
 675      * @since 2.0
 676      */
 677     default String fieldBlockRqSector() {
 678         return "rq_sector"; //$NON-NLS-1$
 679     }
 680
 681     /**
 682      * The field with the sector of the request being merged in another one
 683      *
 684      * @return The name of the field
 685      * @since 2.0
 686      */
 687     default String fieldBlockNextRqSector() {
 688         return "nextrq_sector"; //$NON-NLS-1$
 689     }
 690
 691     /**
 692      * The field containing the name of the disk
 693      *
 694      * @return The name of the field
 695      * @since 2.0
 696      */
 697     default String fieldDiskname() {
 698         return "diskname"; //$NON-NLS-1$
 699     }
 700
 701 }