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      * The kernel just allocated a page of memory.
 295      * <p>
 296      * In Linux, this typically means a user space application just got a page of
 297      * ram.
 298      *
 299      * @return the event name
 300      * @since 2.0
 301      */
 302     String eventKmemPageAlloc();
 303
 304     /**
 305      * The kernel just deallocated a page of memory.
 306      * <p>
 307      * In Linux, this typically means a page of ram was just freed
 308      *
 309      * @return the event name
 310      * @since 2.0
 311      */
 312     String eventKmemPageFree();
 313
 314     // ------------------------------------------------------------------------
 315     // Event field names
 316     // ------------------------------------------------------------------------
 317
 318     /**
 319      * The field with the IRQ number. This is used in irq_handlers (entry and
 320      * exit). For soft IRQs see {@link #fieldVec}.
 321      *
 322      * @return the name of the field with the IRQ number
 323      */
 324     String fieldIrq();
 325
 326     /**
 327      * The field with the vector. This is the soft IRQ vector field used in soft
 328      * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
 329      *
 330      * @return the name of the field with the soft IRQ vector name
 331      */
 332     String fieldVec();
 333
 334     /**
 335      * The field with the thread ID. This is often used in scheduler calls to
 336      * know which thread is being affected. (normally not in switch, but in
 337      * priority and wakeup calls).
 338      *
 339      * @return the name of the field with the thread ID
 340      */
 341     String fieldTid();
 342
 343     /**
 344      * The field with the previous thread id. This is used in switching
 345      * operations of a scheduler, when a thread is scheduled out for another,
 346      * this field shows the thread id being scheduled out.
 347      *
 348      * @return The name of the field with the ID of the previous thread
 349      */
 350     String fieldPrevTid();
 351
 352     /**
 353      * The field with the state of the previous thread. This is used in
 354      * switching operations of a scheduler, when a thread is scheduled out for
 355      * another, this field shows the state of the thread being scheduled out.
 356      *
 357      * @return the name of the field of the previous thread's state
 358      */
 359     String fieldPrevState();
 360
 361     /**
 362      * The field with the next command to be run. This is used in switching
 363      * operations of a scheduler, when a thread is scheduled out for another,
 364      * this field shows the command being scheduled in. A command's value is
 365      * often a String like "ls" or "hl3.exe".
 366      *
 367      * @return the name of the field with the next command to be run
 368      */
 369     String fieldNextComm();
 370
 371     /**
 372      * The field with the next thread ID. This is used in switching operations
 373      * of a scheduler, when a thread is scheduled out for another, this field
 374      * shows the thread being scheduled in.
 375      *
 376      * @return the name of the field with the next thread ID
 377      */
 378     String fieldNextTid();
 379
 380     /**
 381      * The field with the child command. This field is used in clone and spawn
 382      * activities, to know which executable the clone is running.
 383      *
 384      * @return the name of the field with the child command
 385      */
 386     String fieldChildComm();
 387
 388     /**
 389      * The field with the parent thread ID. This field is used in clone and
 390      * spawn activities, to know which thread triggered the clone.
 391      *
 392      * @return the name of the field with the parent thread ID
 393      */
 394     String fieldParentTid();
 395
 396     /**
 397      * The field with the child thread ID. This field is used in clone and spawn
 398      * activities, to know which thread is the clone.
 399      *
 400      * @return the name of the field with the child thread ID
 401      */
 402     String fieldChildTid();
 403
 404     /**
 405      * The field with the command. This is used in scheduling tracepoints that
 406      * are not switches, and show the current process name. It is often a string
 407      * like "zsh" or "cmd.exe".
 408      *
 409      * @return the name of the command field
 410      * @since 2.0
 411      */
 412     String fieldComm();
 413
 414     /**
 415      * The field with the name. The name field is used in several disjoint
 416      * events.
 417      * <p>
 418      * Examples include:
 419      * <ul>
 420      * <li>writeback_* - the name of the io device, often "(unknown)"</li>
 421      * <li>module_* - the name of the module such as "binfmt_misc"</li>
 422      * <li>irq_handler_entry - the field describes the name of the handler such
 423      * as "i915"</li>
 424      * <ul>
 425      *
 426      * @return the name of the field with a name
 427      * @since 2.0
 428      */
 429     String fieldName();
 430
 431     /**
 432      * The field with the status. Often functions like a return value before we
 433      * hit an exit.
 434      * <p>
 435      * Examples include:
 436      * <ul>
 437      * <li>ext4* - status</li>
 438      * <li>asoc_snd_soc_cache_sync</li>
 439      * <li>rpc_*</li>
 440      * <li>state dumps</li>
 441      * </ul>
 442      *
 443      * @return The name of the field with a status
 444      * @since 2.0
 445      */
 446     String fieldStatus();
 447
 448     /**
 449      * The field with the last command to be run. This is often a string
 450      * representing the command of the thread being scheduled out from a
 451      * scheduler switch operation.
 452      *
 453      * @return the name of the field with the last command to be run
 454      * @since 2.0
 455      */
 456     String fieldPrevComm();
 457
 458     /**
 459      * The field with the file name field. This is a string used mostly with
 460      * file operations. These operations are often wrapped in system calls and
 461      * can be:
 462      * <ul>
 463      * <li>open</li>
 464      * <li>change mode</li>
 465      * <li>change directory</li>
 466      * <li>stat</li>
 467      * </ul>
 468      * It can also be used in exec commands to see what the command name should
 469      * be.
 470      * <p>
 471      * Please note that file read and write often do not use the file name, they
 472      * just use the file handle.
 473      *
 474      * @return the name of the field with the file name
 475      * @since 2.0
 476      */
 477     String fieldFilename();
 478
 479     /**
 480      * The field with the priority. The priority of a given process is used by
 481      * most scheduler events. The major exception is the switching operation as
 482      * it has two processes so it has a previous and next priority.
 483      *
 484      * @return the name of the field with the thread or process' priority
 485      * @since 1.0
 486      */
 487     String fieldPrio();
 488
 489     /**
 490      * The field with the new priority. This is used in the scheduler's
 491      * pi_setprio event event to show the new priority of the thread or process.
 492      *
 493      * @return the name of the field with the thread or process' new priority
 494      * @since 1.0
 495      */
 496     String fieldNewPrio();
 497
 498     /**
 499      * The field with the next priority. This is used in the scheduler's switch
 500      * event to show the priority of the next thread or process.
 501      *
 502      * @return the name of the field with the thread or process' next priority
 503      * @since 1.0
 504      */
 505     String fieldNextPrio();
 506
 507     /**
 508      * The field with the hrtimer. The hrtimer holds the timer instance.
 509      *
 510      * @return the name of the hrTimer field
 511      * @since 2.0
 512      */
 513     String fieldHRtimer();
 514
 515     /**
 516      * The field with the expires value. The expires field holds the expiry time.
 517      * of the hrtimer.
 518      *
 519      * @return the name of the expires field
 520      * @since 2.0
 521      */
 522     String fieldHRtimerExpires();
 523
 524     /**
 525      * Gets the field name with the softexpires value. The softexpire value is the
 526      * absolute earliest expiry time of the hrtimer.
 527      *
 528      * @return the name of the softexpires field
 529      * @since 2.0
 530      */
 531     String fieldHRtimerSoftexpires();
 532
 533     /**
 534      * The field of the function address value. The function field holds timer
 535      * expiry callback function.
 536      *
 537      * @return the name of the function field
 538      * @since 2.0
 539      */
 540     String fieldHRtimerFunction();
 541
 542     /**
 543      * The field of the now value. The now field holds the current time.
 544      *
 545      * @return the name of the now field (hrtimer)
 546      * @since 2.0
 547      */
 548     String fieldHRtimerNow();
 549
 550     /**
 551      * The field containing the return value of a system call exit.
 552      *
 553      * @return The name of return field
 554      * @since 2.0
 555      */
 556     default String fieldSyscallRet() {
 557         return "ret"; //$NON-NLS-1$
 558     }
 559
 560     // ------------------------------------------------------------------------
 561     // I/O events and fields
 562     // ------------------------------------------------------------------------
 563
 564     /**
 565      * A request to a block IO has just been inserted in the waiting queue.
 566      *
 567      * @return The name of the event
 568      * @since 2.0
 569      */
 570     default String eventBlockRqInsert() {
 571         return "block_rq_insert"; //$NON-NLS-1$
 572     }
 573
 574     /**
 575      * A request to a block IO has just been issued and passed from the waiting
 576      * queue to the driver queue. It is being served.
 577      *
 578      * @return The name of the event
 579      * @since 2.0
 580      */
 581     default String eventBlockRqIssue() {
 582         return "block_rq_issue"; //$NON-NLS-1$
 583     }
 584
 585     /**
 586      * A request to a block IO has just been completed.
 587      *
 588      * @return The name of the event
 589      * @since 2.0
 590      */
 591     default String eventBlockRqComplete() {
 592         return "block_rq_complete"; //$NON-NLS-1$
 593     }
 594
 595     /**
 596      * A BIO operation is being merged at the front of a waiting request
 597      *
 598      * @return The name of the event
 599      * @since 2.0
 600      */
 601     default String eventBlockBioFrontmerge() {
 602         return "block_bio_frontmerge"; //$NON-NLS-1$
 603     }
 604
 605     /**
 606      * A BIO operation is being merged at the back of a waiting request
 607      *
 608      * @return The name of the event
 609      * @since 2.0
 610      */
 611     default String eventBlockBioBackmerge() {
 612         return "block_bio_backmerge"; //$NON-NLS-1$
 613     }
 614
 615     /**
 616      * 2 requests previously inserted in the waiting queue are being merged
 617      *
 618      * @return The name of the event
 619      * @since 2.0
 620      */
 621     default String eventBlockRqMerge() {
 622         return "block_rq_merge"; //$NON-NLS-1$
 623     }
 624
 625     /**
 626      * Optional event used by some tracers to associate the name of the block
 627      * device to a device ID
 628      *
 629      * @return The name of the event
 630      * @since 2.0
 631      */
 632     default @Nullable String eventStatedumpBlockDevice() {
 633         return null;
 634     }
 635
 636     /**
 637      * The field containing the device ID
 638      *
 639      * @return The name of the field
 640      * @since 2.0
 641      */
 642     default String fieldBlockDeviceId() {
 643         return "dev"; //$NON-NLS-1$
 644     }
 645
 646     /**
 647      * The field with the first sector of a block operation
 648      *
 649      * @return The name of the field
 650      * @since 2.0
 651      */
 652     default String fieldBlockSector() {
 653         return "sector"; //$NON-NLS-1$
 654     }
 655
 656     /**
 657      * The field with the number of sectors involved in a block operation
 658      *
 659      * @return The name of the field
 660      * @since 2.0
 661      */
 662     default String fieldBlockNrSector() {
 663         return "nr_sector"; //$NON-NLS-1$
 664     }
 665
 666     /**
 667      * The field containing the read/write flag of a block operation
 668      *
 669      * @return The name of the field
 670      * @since 2.0
 671      */
 672     default String fieldBlockRwbs() {
 673         return "rwbs"; //$NON-NLS-1$
 674     }
 675
 676     /**
 677      * The field with the first sector of a request in which another block
 678      * operation is being merged
 679      *
 680      * @return The name of the field
 681      * @since 2.0
 682      */
 683     default String fieldBlockRqSector() {
 684         return "rq_sector"; //$NON-NLS-1$
 685     }
 686
 687     /**
 688      * The field with the sector of the request being merged in another one
 689      *
 690      * @return The name of the field
 691      * @since 2.0
 692      */
 693     default String fieldBlockNextRqSector() {
 694         return "nextrq_sector"; //$NON-NLS-1$
 695     }
 696
 697     /**
 698      * The field containing the name of the disk
 699      *
 700      * @return The name of the field
 701      * @since 2.0
 702      */
 703     default String fieldDiskname() {
 704         return "diskname"; //$NON-NLS-1$
 705     }
 706
 707 }