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