1 /*******************************************************************************
2 * Copyright (c) 2014, 2015 Ericsson
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
10 * Alexandre Montplaisir - Initial API and implementation
11 ******************************************************************************/
13 package org
.eclipse
.tracecompass
.analysis
.os
.linux
.core
.trace
;
15 import java
.util
.Collection
;
16 import java
.util
.Collections
;
18 import org
.eclipse
.jdt
.annotation
.Nullable
;
21 * Interface to define "concepts" present in the Linux kernel (represented by
22 * its tracepoints), that can then be exposed by different tracers under
25 * @author Alexandre Montplaisir
26 * @author Matthew Khouzam - Javadoc
28 public interface IKernelAnalysisEventLayout
{
30 // ------------------------------------------------------------------------
32 // ------------------------------------------------------------------------
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.)
39 * TODO Change to a default method with Java 8?
41 String INITIAL_SYSCALL_NAME
= "clone"; //$NON-NLS-1$
43 // ------------------------------------------------------------------------
45 // ------------------------------------------------------------------------
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
52 * @return the event name
54 String
eventIrqHandlerEntry();
57 * The system will soon return from an interrupt handler or interrupt
60 * @return the event name
62 String
eventIrqHandlerExit();
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.
72 * @return the event name
74 String
eventSoftIrqEntry();
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.
84 * @return the event name
86 String
eventSoftIrqExit();
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.
96 * @return the event name
98 String
eventSoftIrqRaise();
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
106 * @return the event name
108 String
eventSchedSwitch();
111 * sched_PI_setprio is a tracepoint called often when the schedulder
112 * priorities for a given task changes.
114 * @return the event name
117 String
eventSchedPiSetprio();
120 * Scheduler is waking up a task. this happens before it is executed, and
121 * the data is loaded in memory if needed.
123 * @return the event names, as there are often several different ways to
126 Collection
<String
> eventsSchedWakeup();
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
134 * @return the event name
136 String
eventSchedProcessFork();
139 * The process has finished running and the scheduler takes its TID back.
141 * @return the event name
143 String
eventSchedProcessExit();
146 * The process free tracepoint is called when a process has finished running
147 * and the scheduler retrieves it's process ID.
149 * @return the event name
151 String
eventSchedProcessFree();
154 * Optional event used by some tracers to deliver an initial state.
156 * @return the event name
158 @Nullable String
eventStatedumpProcessState();
161 * System call entry prefix, something like "sys_open" or just "sys".
163 * @return the event name
165 String
eventSyscallEntryPrefix();
168 * System call compatibility layer entry prefix, something like
171 * @return the event name
173 String
eventCompatSyscallEntryPrefix();
176 * System call exit prefix, something like "sys_exit".
178 * @return the event name
180 String
eventSyscallExitPrefix();
183 * System call compatibility layer exit prefix, something like
184 * "compat_syscall_exit".
186 * @return the event name
189 String
eventCompatSyscallExitPrefix();
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.
196 * @return the event name
200 String
eventSchedProcessExec();
203 * The scheduler calls wakeup on a sleeping process. The process will
204 * probably soon be scheduled in.
206 * @return the event name
210 String
eventSchedProcessWakeup();
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
217 * @return the event name
221 String
eventSchedProcessWakeupNew();
224 * Starting the high resolution timer
226 * In Linux, High resolution timers are used in the following:
230 * <li>posix timers</li>
233 * @return the event name
237 String
eventHRTimerStart();
240 * Canceling the high resolution timer
242 * In Linux, High resolution timers are used in the following:
246 * <li>posix timers</li>
249 * @return the event name
253 String
eventHRTimerCancel();
256 * Entering the high resolution timer expired handler.
258 * In Linux, High resolution timers are used in the following:
262 * <li>posix timers</li>
265 * @return the event name
269 String
eventHRTimerExpireEntry();
272 * Exiting the high resolution timer expired handler.
274 * In Linux, High resolution timers are used in the following:
278 * <li>posix timers</li>
281 * @return the event name
285 String
eventHRTimerExpireExit();
288 * The kernel just allocated a page of memory.
290 * In Linux, this typically means a user space application just got a page
293 * @return the event name
296 String
eventKmemPageAlloc();
299 * The kernel just deallocated a page of memory.
301 * In Linux, this typically means a page of ram was just freed
303 * @return the event name
306 String
eventKmemPageFree();
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
313 * <li>cache flushes</li>
316 * They are not logged with standard events, but rather events looking like
317 * "x86_irq_vectors_thermal_apic_exit".
319 * This event describes the entries into IPIs.
321 * @return the IPI list
324 default Collection
<String
> getIPIIrqVectorsEntries() {
325 return Collections
.emptyList();
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
333 * <li>cache flushes</li>
336 * They are not logged with standard events, but rather events looking like
337 * "x86_irq_vectors_thermal_apic_exit".
339 * This event describes the exits into IPIs.
341 * @return the IPI list
344 default Collection
<String
> getIPIIrqVectorsExits() {
345 return Collections
.emptyList();
348 // ------------------------------------------------------------------------
350 // ------------------------------------------------------------------------
353 * The field with the IRQ number. This is used in irq_handlers (entry and
354 * exit). For soft IRQs see {@link #fieldVec}.
356 * @return the name of the field with the IRQ number
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}.
364 * @return the name of the field with the soft IRQ vector name
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).
373 * @return the name of the field with the thread ID
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.
382 * @return The name of the field with the ID of the previous thread
384 String
fieldPrevTid();
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.
391 * @return the name of the field of the previous thread's state
393 String
fieldPrevState();
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".
401 * @return the name of the field with the next command to be run
403 String
fieldNextComm();
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.
410 * @return the name of the field with the next thread ID
412 String
fieldNextTid();
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.
418 * @return the name of the field with the child command
420 String
fieldChildComm();
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.
426 * @return the name of the field with the parent thread ID
428 String
fieldParentTid();
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.
434 * @return the name of the field with the child thread ID
436 String
fieldChildTid();
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".
443 * @return the name of the command field
449 * The field with the name. The name field is used in several disjoint
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
460 * @return the name of the field with a name
466 * The field with the status. Often functions like a return value before we
471 * <li>ext4* - status</li>
472 * <li>asoc_snd_soc_cache_sync</li>
474 * <li>state dumps</li>
477 * @return The name of the field with a status
480 String
fieldStatus();
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.
487 * @return the name of the field with the last command to be run
490 String
fieldPrevComm();
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
498 * <li>change mode</li>
499 * <li>change directory</li>
502 * It can also be used in exec commands to see what the command name should
505 * Please note that file read and write often do not use the file name, they
506 * just use the file handle.
508 * @return the name of the field with the file name
511 String
fieldFilename();
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.
518 * @return the name of the field with the thread or process' priority
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.
527 * @return the name of the field with the thread or process' new priority
530 String
fieldNewPrio();
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.
536 * @return the name of the field with the priority of the previous thread
539 String
fieldPrevPrio();
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.
545 * @return the name of the field with the thread or process' next priority
548 String
fieldNextPrio();
551 * The field with the hrtimer. The hrtimer holds the timer instance.
553 * @return the name of the hrTimer field
556 String
fieldHRtimer();
559 * The field with the expires value. The expires field holds the expiry
560 * time. of the hrtimer.
562 * @return the name of the expires field
565 String
fieldHRtimerExpires();
568 * Gets the field name with the softexpires value. The softexpire value is
569 * the absolute earliest expiry time of the hrtimer.
571 * @return the name of the softexpires field
574 String
fieldHRtimerSoftexpires();
577 * The field of the function address value. The function field holds timer
578 * expiry callback function.
580 * @return the name of the function field
583 String
fieldHRtimerFunction();
586 * The field of the now value. The now field holds the current time.
588 * @return the name of the now field (hrtimer)
591 String
fieldHRtimerNow();
594 * The field containing the return value of a system call exit.
596 * @return The name of return field
599 default String
fieldSyscallRet() {
600 return "ret"; //$NON-NLS-1$
603 // ------------------------------------------------------------------------
604 // I/O events and fields
605 // ------------------------------------------------------------------------
608 * A request to a block IO has just been inserted in the waiting queue.
610 * @return The name of the event
613 default String
eventBlockRqInsert() {
614 return "block_rq_insert"; //$NON-NLS-1$
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.
621 * @return The name of the event
624 default String
eventBlockRqIssue() {
625 return "block_rq_issue"; //$NON-NLS-1$
629 * A request to a block IO has just been completed.
631 * @return The name of the event
634 default String
eventBlockRqComplete() {
635 return "block_rq_complete"; //$NON-NLS-1$
639 * A BIO operation is being merged at the front of a waiting request
641 * @return The name of the event
644 default String
eventBlockBioFrontmerge() {
645 return "block_bio_frontmerge"; //$NON-NLS-1$
649 * A BIO operation is being merged at the back of a waiting request
651 * @return The name of the event
654 default String
eventBlockBioBackmerge() {
655 return "block_bio_backmerge"; //$NON-NLS-1$
659 * 2 requests previously inserted in the waiting queue are being merged
661 * @return The name of the event
664 default String
eventBlockRqMerge() {
665 return "block_rq_merge"; //$NON-NLS-1$
669 * Optional event used by some tracers to associate the name of the block
670 * device to a device ID
672 * @return The name of the event
675 default @Nullable String
eventStatedumpBlockDevice() {
680 * The field containing the device ID
682 * @return The name of the field
685 default String
fieldBlockDeviceId() {
686 return "dev"; //$NON-NLS-1$
690 * The field with the first sector of a block operation
692 * @return The name of the field
695 default String
fieldBlockSector() {
696 return "sector"; //$NON-NLS-1$
700 * The field with the number of sectors involved in a block operation
702 * @return The name of the field
705 default String
fieldBlockNrSector() {
706 return "nr_sector"; //$NON-NLS-1$
710 * The field containing the read/write flag of a block operation
712 * @return The name of the field
715 default String
fieldBlockRwbs() {
716 return "rwbs"; //$NON-NLS-1$
720 * The field with the first sector of a request in which another block
721 * operation is being merged
723 * @return The name of the field
726 default String
fieldBlockRqSector() {
727 return "rq_sector"; //$NON-NLS-1$
731 * The field with the sector of the request being merged in another one
733 * @return The name of the field
736 default String
fieldBlockNextRqSector() {
737 return "nextrq_sector"; //$NON-NLS-1$
741 * The field containing the name of the disk
743 * @return The name of the field
746 default String
fieldDiskname() {
747 return "diskname"; //$NON-NLS-1$
751 * The field with the IRQ number. This is used in IPI handlers (entry and
754 * @return the name of the field with the IRQ number
757 default String
fieldIPIVector() {
758 return "vector"; //$NON-NLS-1$
761 // ------------------------------------------------------------------------
762 // Network events and fields
763 // ------------------------------------------------------------------------
766 * An event indicating that a packet is sent on the network
768 * @return The name of the packet send event
771 default String
eventNetworkSend() {
772 return "net_dev_queue"; //$NON-NLS-1$
776 * Get the list of events indicating that a packet is received from the
779 * @return The collection of names of the packet receive event
782 default Collection
<String
> eventNetworkReceive() {
783 return Collections
.singleton("netif_receive_skb"); //$NON-NLS-1$
787 * The path of the field corresponding to the sequence number field of a TCP
790 * @return The path of the sequence number field in the TCP header of a
794 default String
[] fieldPathTcpSeq() {
795 return new String
[] { "seq" }; //$NON-NLS-1$
799 * The path of the field corresponding to the acknowledgment number field of
802 * @return The name of the acknowledgment number field in the TCP header of
806 default String
[] fieldPathTcpAckSeq() {
807 return new String
[] { "ack_seq" }; //$NON-NLS-1$
811 * The path of the field corresponding to the flags field of a TCP header
813 * @return The path of the flags field in the TCP header of a network packet
816 default String
[] fieldPathTcpFlags() {
817 return new String
[] { "flags" }; //$NON-NLS-1$
820 // ------------------------------------------------------------------------
821 // VirtualMachine events : kvm entry/exit events
822 // ------------------------------------------------------------------------
825 * KVM kernel event indicating that virtual machine code is being run
827 * @return The name of the kvm entry event
830 default Collection
<String
> eventsKVMEntry() {
831 return Collections
.EMPTY_SET
;
835 * KVM kernel event indicating that virtual machine code is not run anymore,
836 * but rather hypervisor-specific code
838 * @return The name of the kvm exit event
841 default Collection
<String
> eventsKVMExit() {
842 return Collections
.EMPTY_SET
;