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
;
17 import org
.eclipse
.jdt
.annotation
.Nullable
;
20 * Interface to define "concepts" present in the Linux kernel (represented by
21 * its tracepoints), that can then be exposed by different tracers under
24 * @author Alexandre Montplaisir
25 * @author Matthew Khouzam - Javadoc
27 public interface IKernelAnalysisEventLayout
{
29 // ------------------------------------------------------------------------
31 // ------------------------------------------------------------------------
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.)
38 * TODO Change to a default method with Java 8?
40 String INITIAL_SYSCALL_NAME
= "clone"; //$NON-NLS-1$
42 // ------------------------------------------------------------------------
44 // ------------------------------------------------------------------------
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
51 * @return the event name
53 String
eventIrqHandlerEntry();
56 * The system will soon return from an interrupt handler or interrupt
59 * @return the event name
61 String
eventIrqHandlerExit();
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.
71 * @return the event name
73 String
eventSoftIrqEntry();
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.
83 * @return the event name
85 String
eventSoftIrqExit();
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.
95 * @return the event name
97 String
eventSoftIrqRaise();
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
105 * @return the event name
107 String
eventSchedSwitch();
110 * sched_PI_setprio is a tracepoint called often when the schedulder
111 * priorities for a given task changes.
113 * @return the event name
116 String
eventSchedPiSetprio();
119 * Scheduler is waking up a task. this happens before it is executed, and
120 * the data is loaded in memory if needed.
122 * @return the event names, as there are often several different ways to
125 Collection
<String
> eventsSchedWakeup();
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
133 * @return the event name
135 String
eventSchedProcessFork();
138 * The process has finished running and the scheduler takes its TID back.
140 * @return the event name
142 String
eventSchedProcessExit();
145 * The process free tracepoint is called when a process has finished running
146 * and the scheduler retrieves it's process ID.
148 * @return the event name
150 String
eventSchedProcessFree();
153 * Optional event used by some tracers to deliver an initial state.
155 * @return the event name
157 @Nullable String
eventStatedumpProcessState();
160 * System call entry prefix, something like "sys_open" or just "sys".
162 * @return the event name
164 String
eventSyscallEntryPrefix();
167 * System call compatibility layer entry prefix, something like
170 * @return the event name
172 String
eventCompatSyscallEntryPrefix();
175 * System call exit prefix, something like "sys_exit".
177 * @return the event name
179 String
eventSyscallExitPrefix();
182 * System call compatibility layer exit prefix, something like
183 * "compat_syscall_exit".
185 * @return the event name
188 String
eventCompatSyscallExitPrefix();
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.
195 * @return the event name
199 String
eventSchedProcessExec();
202 * The scheduler calls wakeup on a sleeping process. The process will
203 * probably soon be scheduled in.
205 * @return the event name
209 String
eventSchedProcessWakeup();
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
216 * @return the event name
220 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 of
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();
308 // ------------------------------------------------------------------------
310 // ------------------------------------------------------------------------
313 * The field with the IRQ number. This is used in irq_handlers (entry and
314 * exit). For soft IRQs see {@link #fieldVec}.
316 * @return the name of the field with the IRQ number
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}.
324 * @return the name of the field with the soft IRQ vector name
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).
333 * @return the name of the field with the thread ID
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.
342 * @return The name of the field with the ID of the previous thread
344 String
fieldPrevTid();
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.
351 * @return the name of the field of the previous thread's state
353 String
fieldPrevState();
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".
361 * @return the name of the field with the next command to be run
363 String
fieldNextComm();
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.
370 * @return the name of the field with the next thread ID
372 String
fieldNextTid();
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.
378 * @return the name of the field with the child command
380 String
fieldChildComm();
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.
386 * @return the name of the field with the parent thread ID
388 String
fieldParentTid();
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.
394 * @return the name of the field with the child thread ID
396 String
fieldChildTid();
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".
403 * @return the name of the command field
409 * The field with the name. The name field is used in several disjoint
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
420 * @return the name of the field with a name
426 * The field with the status. Often functions like a return value before we
431 * <li>ext4* - status</li>
432 * <li>asoc_snd_soc_cache_sync</li>
434 * <li>state dumps</li>
437 * @return The name of the field with a status
440 String
fieldStatus();
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.
447 * @return the name of the field with the last command to be run
450 String
fieldPrevComm();
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
458 * <li>change mode</li>
459 * <li>change directory</li>
462 * It can also be used in exec commands to see what the command name should
465 * Please note that file read and write often do not use the file name, they
466 * just use the file handle.
468 * @return the name of the field with the file name
471 String
fieldFilename();
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.
478 * @return the name of the field with the thread or process' priority
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.
487 * @return the name of the field with the thread or process' new priority
490 String
fieldNewPrio();
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.
496 * @return the name of the field with the thread or process' next priority
499 String
fieldNextPrio();
502 * The field with the hrtimer. The hrtimer holds the timer instance.
504 * @return the name of the hrTimer field
507 String
fieldHRtimer();
510 * The field with the expires value. The expires field holds the expiry time.
513 * @return the name of the expires field
516 String
fieldHRtimerExpires();
519 * Gets the field name with the softexpires value. The softexpire value is the
520 * absolute earliest expiry time of the hrtimer.
522 * @return the name of the softexpires field
525 String
fieldHRtimerSoftexpires();
528 * The field of the function address value. The function field holds timer
529 * expiry callback function.
531 * @return the name of the function field
534 String
fieldHRtimerFunction();
537 * The field of the now value. The now field holds the current time.
539 * @return the name of the now field (hrtimer)
542 String
fieldHRtimerNow();
545 * The field containing the return value of a system call exit.
547 * @return The name of return field
550 default String
fieldSyscallRet() {
551 return "ret"; //$NON-NLS-1$
554 // ------------------------------------------------------------------------
555 // I/O events and fields
556 // ------------------------------------------------------------------------
559 * A request to a block IO has just been inserted in the waiting queue.
561 * @return The name of the event
564 default String
eventBlockRqInsert() {
565 return "block_rq_insert"; //$NON-NLS-1$
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.
572 * @return The name of the event
575 default String
eventBlockRqIssue() {
576 return "block_rq_issue"; //$NON-NLS-1$
580 * A request to a block IO has just been completed.
582 * @return The name of the event
585 default String
eventBlockRqComplete() {
586 return "block_rq_complete"; //$NON-NLS-1$
590 * A BIO operation is being merged at the front of a waiting request
592 * @return The name of the event
595 default String
eventBlockBioFrontmerge() {
596 return "block_bio_frontmerge"; //$NON-NLS-1$
600 * A BIO operation is being merged at the back of a waiting request
602 * @return The name of the event
605 default String
eventBlockBioBackmerge() {
606 return "block_bio_backmerge"; //$NON-NLS-1$
610 * 2 requests previously inserted in the waiting queue are being merged
612 * @return The name of the event
615 default String
eventBlockRqMerge() {
616 return "block_rq_merge"; //$NON-NLS-1$
620 * Optional event used by some tracers to associate the name of the block
621 * device to a device ID
623 * @return The name of the event
626 default @Nullable String
eventStatedumpBlockDevice() {
631 * The field containing the device ID
633 * @return The name of the field
636 default String
fieldBlockDeviceId() {
637 return "dev"; //$NON-NLS-1$
641 * The field with the first sector of a block operation
643 * @return The name of the field
646 default String
fieldBlockSector() {
647 return "sector"; //$NON-NLS-1$
651 * The field with the number of sectors involved in a block operation
653 * @return The name of the field
656 default String
fieldBlockNrSector() {
657 return "nr_sector"; //$NON-NLS-1$
661 * The field containing the read/write flag of a block operation
663 * @return The name of the field
666 default String
fieldBlockRwbs() {
667 return "rwbs"; //$NON-NLS-1$
671 * The field with the first sector of a request in which another block
672 * operation is being merged
674 * @return The name of the field
677 default String
fieldBlockRqSector() {
678 return "rq_sector"; //$NON-NLS-1$
682 * The field with the sector of the request being merged in another one
684 * @return The name of the field
687 default String
fieldBlockNextRqSector() {
688 return "nextrq_sector"; //$NON-NLS-1$
692 * The field containing the name of the disk
694 * @return The name of the field
697 default String
fieldDiskname() {
698 return "diskname"; //$NON-NLS-1$