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 * Event called when waking a task; this event is guaranteed to be called
225 * from the waking context.
227 * @return The name of the event
230 default String
eventSchedProcessWaking() {
231 return "sched_waking"; //$NON-NLS-1$
235 * Starting the high resolution timer
237 * In Linux, High resolution timers are used in the following:
241 * <li>posix timers</li>
244 * @return the event name
248 String
eventHRTimerStart();
251 * Canceling the high resolution timer
253 * In Linux, High resolution timers are used in the following:
257 * <li>posix timers</li>
260 * @return the event name
264 String
eventHRTimerCancel();
267 * Entering the high resolution timer expired handler.
269 * In Linux, High resolution timers are used in the following:
273 * <li>posix timers</li>
276 * @return the event name
280 String
eventHRTimerExpireEntry();
283 * Exiting the high resolution timer expired handler.
285 * In Linux, High resolution timers are used in the following:
289 * <li>posix timers</li>
292 * @return the event name
296 String
eventHRTimerExpireExit();
299 * The kernel just allocated a page of memory.
301 * In Linux, this typically means a user space application just got a page
304 * @return the event name
307 String
eventKmemPageAlloc();
310 * The kernel just deallocated a page of memory.
312 * In Linux, this typically means a page of ram was just freed
314 * @return the event name
317 String
eventKmemPageFree();
320 * <em>Interprocessor interrupts</em> (IPIs) are special types of interrupts by which
321 * one processor will interrupt another in a multi-core and multi-cpu system. They are
324 * <li>cache flushes</li>
327 * They are not logged with standard events, but rather events looking like
328 * "x86_irq_vectors_thermal_apic_exit".
330 * This event describes the entries into IPIs.
332 * @return the IPI list
335 default Collection
<String
> getIPIIrqVectorsEntries() {
336 return Collections
.emptyList();
340 * <em>Interprocessor interrupts</em> (IPIs) are special types of interrupts by which
341 * one processor will interrupt another in a multi-core and multi-cpu system. They are
344 * <li>cache flushes</li>
347 * They are not logged with standard events, but rather events looking like
348 * "x86_irq_vectors_thermal_apic_exit".
350 * This event describes the exits into IPIs.
352 * @return the IPI list
355 default Collection
<String
> getIPIIrqVectorsExits() {
356 return Collections
.emptyList();
359 // ------------------------------------------------------------------------
361 // ------------------------------------------------------------------------
364 * The field with the IRQ number. This is used in irq_handlers (entry and
365 * exit). For soft IRQs see {@link #fieldVec}.
367 * @return the name of the field with the IRQ number
372 * The field with the vector. This is the soft IRQ vector field used in soft
373 * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
375 * @return the name of the field with the soft IRQ vector name
380 * The field with the thread ID. This is often used in scheduler calls to
381 * know which thread is being affected. (normally not in switch, but in
382 * priority and wakeup calls).
384 * @return the name of the field with the thread ID
389 * The field with the previous thread id. This is used in switching
390 * operations of a scheduler, when a thread is scheduled out for another,
391 * this field shows the thread id being scheduled out.
393 * @return The name of the field with the ID of the previous thread
395 String
fieldPrevTid();
398 * The field with the state of the previous thread. This is used in
399 * switching operations of a scheduler, when a thread is scheduled out for
400 * another, this field shows the state of the thread being scheduled out.
402 * @return the name of the field of the previous thread's state
404 String
fieldPrevState();
407 * The field with the next command to be run. This is used in switching
408 * operations of a scheduler, when a thread is scheduled out for another,
409 * this field shows the command being scheduled in. A command's value is
410 * often a String like "ls" or "hl3.exe".
412 * @return the name of the field with the next command to be run
414 String
fieldNextComm();
417 * The field with the next thread ID. This is used in switching operations
418 * of a scheduler, when a thread is scheduled out for another, this field
419 * shows the thread being scheduled in.
421 * @return the name of the field with the next thread ID
423 String
fieldNextTid();
426 * The field with the child command. This field is used in clone and spawn
427 * activities, to know which executable the clone is running.
429 * @return the name of the field with the child command
431 String
fieldChildComm();
434 * The field with the parent thread ID. This field is used in clone and
435 * spawn activities, to know which thread triggered the clone.
437 * @return the name of the field with the parent thread ID
439 String
fieldParentTid();
442 * The field with the child thread ID. This field is used in clone and spawn
443 * activities, to know which thread is the clone.
445 * @return the name of the field with the child thread ID
447 String
fieldChildTid();
450 * The field with the command. This is used in scheduling tracepoints that
451 * are not switches, and show the current process name. It is often a string
452 * like "zsh" or "cmd.exe".
454 * @return the name of the command field
460 * The field with the name. The name field is used in several disjoint
465 * <li>writeback_* - the name of the io device, often "(unknown)"</li>
466 * <li>module_* - the name of the module such as "binfmt_misc"</li>
467 * <li>irq_handler_entry - the field describes the name of the handler such
471 * @return the name of the field with a name
477 * The field with the status. Often functions like a return value before we
482 * <li>ext4* - status</li>
483 * <li>asoc_snd_soc_cache_sync</li>
485 * <li>state dumps</li>
488 * @return The name of the field with a status
491 String
fieldStatus();
494 * The field with the last command to be run. This is often a string
495 * representing the command of the thread being scheduled out from a
496 * scheduler switch operation.
498 * @return the name of the field with the last command to be run
501 String
fieldPrevComm();
504 * The field with the file name field. This is a string used mostly with
505 * file operations. These operations are often wrapped in system calls and
509 * <li>change mode</li>
510 * <li>change directory</li>
513 * It can also be used in exec commands to see what the command name should
516 * Please note that file read and write often do not use the file name, they
517 * just use the file handle.
519 * @return the name of the field with the file name
522 String
fieldFilename();
525 * The field with the priority. The priority of a given process is used by
526 * most scheduler events. The major exception is the switching operation as
527 * it has two processes so it has a previous and next priority.
529 * @return the name of the field with the thread or process' priority
535 * The field with the new priority. This is used in the scheduler's
536 * pi_setprio event event to show the new priority of the thread or process.
538 * @return the name of the field with the thread or process' new priority
541 String
fieldNewPrio();
544 * The field with the prev priority. This is used in the scheduler's switch
545 * event to show the priority of the thread being scheduled out.
547 * @return the name of the field with the priority of the previous thread
550 String
fieldPrevPrio();
553 * The field with the next priority. This is used in the scheduler's switch
554 * event to show the priority of the next thread or process.
556 * @return the name of the field with the thread or process' next priority
559 String
fieldNextPrio();
562 * The field with the hrtimer. The hrtimer holds the timer instance.
564 * @return the name of the hrTimer field
567 String
fieldHRtimer();
570 * The field with the expires value. The expires field holds the expiry
571 * time. of the hrtimer.
573 * @return the name of the expires field
576 String
fieldHRtimerExpires();
579 * Gets the field name with the softexpires value. The softexpire value is
580 * the absolute earliest expiry time of the hrtimer.
582 * @return the name of the softexpires field
585 String
fieldHRtimerSoftexpires();
588 * The field of the function address value. The function field holds timer
589 * expiry callback function.
591 * @return the name of the function field
594 String
fieldHRtimerFunction();
597 * The field of the now value. The now field holds the current time.
599 * @return the name of the now field (hrtimer)
602 String
fieldHRtimerNow();
605 * The field containing the return value of a system call exit.
607 * @return The name of return field
610 default String
fieldSyscallRet() {
611 return "ret"; //$NON-NLS-1$
614 // ------------------------------------------------------------------------
615 // I/O events and fields
616 // ------------------------------------------------------------------------
619 * A request to a block IO has just been inserted in the waiting queue.
621 * @return The name of the event
624 default String
eventBlockRqInsert() {
625 return "block_rq_insert"; //$NON-NLS-1$
629 * A request to a block IO has just been issued and passed from the waiting
630 * queue to the driver queue. It is being served.
632 * @return The name of the event
635 default String
eventBlockRqIssue() {
636 return "block_rq_issue"; //$NON-NLS-1$
640 * A request to a block IO has just been completed.
642 * @return The name of the event
645 default String
eventBlockRqComplete() {
646 return "block_rq_complete"; //$NON-NLS-1$
650 * A BIO operation is being merged at the front of a waiting request
652 * @return The name of the event
655 default String
eventBlockBioFrontmerge() {
656 return "block_bio_frontmerge"; //$NON-NLS-1$
660 * A BIO operation is being merged at the back of a waiting request
662 * @return The name of the event
665 default String
eventBlockBioBackmerge() {
666 return "block_bio_backmerge"; //$NON-NLS-1$
670 * 2 requests previously inserted in the waiting queue are being merged
672 * @return The name of the event
675 default String
eventBlockRqMerge() {
676 return "block_rq_merge"; //$NON-NLS-1$
680 * Optional event used by some tracers to associate the name of the block
681 * device to a device ID
683 * @return The name of the event
686 default @Nullable String
eventStatedumpBlockDevice() {
691 * The field containing the device ID
693 * @return The name of the field
696 default String
fieldBlockDeviceId() {
697 return "dev"; //$NON-NLS-1$
701 * The field with the first sector of a block operation
703 * @return The name of the field
706 default String
fieldBlockSector() {
707 return "sector"; //$NON-NLS-1$
711 * The field with the number of sectors involved in a block operation
713 * @return The name of the field
716 default String
fieldBlockNrSector() {
717 return "nr_sector"; //$NON-NLS-1$
721 * The field containing the read/write flag of a block operation
723 * @return The name of the field
726 default String
fieldBlockRwbs() {
727 return "rwbs"; //$NON-NLS-1$
731 * The field with the first sector of a request in which another block
732 * operation is being merged
734 * @return The name of the field
737 default String
fieldBlockRqSector() {
738 return "rq_sector"; //$NON-NLS-1$
742 * The field with the sector of the request being merged in another one
744 * @return The name of the field
747 default String
fieldBlockNextRqSector() {
748 return "nextrq_sector"; //$NON-NLS-1$
752 * The field containing the name of the disk
754 * @return The name of the field
757 default String
fieldDiskname() {
758 return "diskname"; //$NON-NLS-1$
762 * The field with the IRQ number. This is used in IPI handlers (entry and
765 * @return the name of the field with the IRQ number
768 default String
fieldIPIVector() {
769 return "vector"; //$NON-NLS-1$
774 * Get the name of the 'order' field from memory page allocation events.
776 * The 'order' of a page allocation is it's logarithm to the base 2, and the
777 * size of the allocation is 2^order, an integral power-of-2 number of
778 * pages. 'Order' ranges from from 0 to MAX_ORDER-1.
780 * The smallest - and most frequent - page allocation is 2^0 or 1 page. The
781 * maximum allocation possible is 2^(MAX_ORDER-1) pages. MAX_ORDER is
782 * assigned a default value of 11 - resulting in a maximum allocation of
783 * 2^10 or 1024 pages. However it may be redefined at kernel configuration
784 * time with the option CONFIG_FORCE_MAX_ZONEORDER.
786 * @return the name of the order field
789 default @Nullable String
fieldOrder() {
793 // ------------------------------------------------------------------------
794 // Network events and fields
795 // ------------------------------------------------------------------------
798 * Get the list of events indicating that a packet is sent on the network
800 * @return The name of the packet send event
803 default Collection
<String
> eventsNetworkSend() {
804 return Collections
.EMPTY_SET
;
808 * Get the list of events indicating that a packet is received from the
811 * @return The collection of names of the packet receive event
814 default Collection
<String
> eventsNetworkReceive() {
815 return Collections
.EMPTY_SET
;
819 * The path of the field corresponding to the sequence number field of a TCP
822 * @return The path of the sequence number field in the TCP header of a
826 default String
[] fieldPathTcpSeq() {
827 return new String
[] { "seq" }; //$NON-NLS-1$
831 * The path of the field corresponding to the acknowledgment number field of
834 * @return The name of the acknowledgment number field in the TCP header of
838 default String
[] fieldPathTcpAckSeq() {
839 return new String
[] { "ack_seq" }; //$NON-NLS-1$
843 * The path of the field corresponding to the flags field of a TCP header
845 * @return The path of the flags field in the TCP header of a network packet
848 default String
[] fieldPathTcpFlags() {
849 return new String
[] { "flags" }; //$NON-NLS-1$
852 // ------------------------------------------------------------------------
853 // VirtualMachine events : kvm entry/exit events
854 // ------------------------------------------------------------------------
857 * KVM kernel event indicating that virtual machine code is being run
859 * @return The name of the kvm entry event
862 default Collection
<String
> eventsKVMEntry() {
863 return Collections
.EMPTY_SET
;
867 * KVM kernel event indicating that virtual machine code is not run anymore,
868 * but rather hypervisor-specific code
870 * @return The name of the kvm exit event
873 default Collection
<String
> eventsKVMExit() {
874 return Collections
.EMPTY_SET
;