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
.lttng
.scope
.lttng
.kernel
.core
.trace
.layout
;
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 ILttngKernelEventLayout
{
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
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
187 String
eventCompatSyscallExitPrefix();
190 * The scheduler replaced the current process image with a new one. The
191 * process should also be renamed at this point. In windows, this is part of
192 * the spawn process as well as fork.
194 * @return the event name
196 String
eventSchedProcessExec();
199 * The scheduler calls wakeup on a sleeping process. The process will
200 * probably soon be scheduled in.
202 * @return the event name
204 String
eventSchedProcessWakeup();
207 * The scheduler calls wakeup on a sleeping process. The process will
208 * probably soon be scheduled in. The new wakeup knows who triggered the
211 * @return the event name
213 String
eventSchedProcessWakeupNew();
216 * Event called when waking a task; this event is guaranteed to be called
217 * from the waking context.
219 * @return The name of the event
221 default String
eventSchedProcessWaking() {
222 return "sched_waking"; //$NON-NLS-1$
226 * Migration event, moving a non-running thread from one CPU's run queue to
229 * @return The event name
231 String
eventSchedMigrateTask();
234 * Starting the high resolution timer
236 * In Linux, High resolution timers are used in the following:
240 * <li>posix timers</li>
243 * @return the event name
245 String
eventHRTimerStart();
248 * Canceling the high resolution timer
250 * In Linux, High resolution timers are used in the following:
254 * <li>posix timers</li>
257 * @return the event name
259 String
eventHRTimerCancel();
262 * Entering the high resolution timer expired handler.
264 * In Linux, High resolution timers are used in the following:
268 * <li>posix timers</li>
271 * @return the event name
273 String
eventHRTimerExpireEntry();
276 * Exiting the high resolution timer expired handler.
278 * In Linux, High resolution timers are used in the following:
282 * <li>posix timers</li>
285 * @return the event name
287 String
eventHRTimerExpireExit();
290 * The kernel just allocated a page of memory.
292 * In Linux, this typically means a user space application just got a page
295 * @return the event name
297 String
eventKmemPageAlloc();
300 * The kernel just deallocated a page of memory.
302 * In Linux, this typically means a page of ram was just freed
304 * @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
323 default Collection
<String
> getIPIIrqVectorsEntries() {
324 return Collections
.emptyList();
328 * <em>Interprocessor interrupts</em> (IPIs) are special types of interrupts by which
329 * one processor will interrupt another in a multi-core and multi-cpu system. They are
332 * <li>cache flushes</li>
335 * They are not logged with standard events, but rather events looking like
336 * "x86_irq_vectors_thermal_apic_exit".
338 * This event describes the exits into IPIs.
340 * @return the IPI list
342 default Collection
<String
> getIPIIrqVectorsExits() {
343 return Collections
.emptyList();
346 // ------------------------------------------------------------------------
348 // ------------------------------------------------------------------------
351 * The field with the IRQ number. This is used in irq_handlers (entry and
352 * exit). For soft IRQs see {@link #fieldVec}.
354 * @return the name of the field with the IRQ number
359 * The field with the vector. This is the soft IRQ vector field used in soft
360 * IRQ raise, entry and exit. For hardware IRQs see {@link #fieldIrq}.
362 * @return the name of the field with the soft IRQ vector name
367 * The field with the thread ID. This is often used in scheduler calls to
368 * know which thread is being affected. (normally not in switch, but in
369 * priority and wakeup calls).
371 * @return the name of the field with the thread ID
376 * The field with the previous thread id. This is used in switching
377 * operations of a scheduler, when a thread is scheduled out for another,
378 * this field shows the thread id being scheduled out.
380 * @return The name of the field with the ID of the previous thread
382 String
fieldPrevTid();
385 * The field with the state of the previous thread. This is used in
386 * switching operations of a scheduler, when a thread is scheduled out for
387 * another, this field shows the state of the thread being scheduled out.
389 * @return the name of the field of the previous thread's state
391 String
fieldPrevState();
394 * The field with the next command to be run. This is used in switching
395 * operations of a scheduler, when a thread is scheduled out for another,
396 * this field shows the command being scheduled in. A command's value is
397 * often a String like "ls" or "hl3.exe".
399 * @return the name of the field with the next command to be run
401 String
fieldNextComm();
404 * The field with the next thread ID. This is used in switching operations
405 * of a scheduler, when a thread is scheduled out for another, this field
406 * shows the thread being scheduled in.
408 * @return the name of the field with the next thread ID
410 String
fieldNextTid();
413 * The field with the child command. This field is used in clone and spawn
414 * activities, to know which executable the clone is running.
416 * @return the name of the field with the child command
418 String
fieldChildComm();
421 * The field with the parent thread ID. This field is used in clone and
422 * spawn activities, to know which thread triggered the clone.
424 * @return the name of the field with the parent thread ID
426 String
fieldParentTid();
429 * The field with the child thread ID. This field is used in clone and spawn
430 * activities, to know which thread is the clone.
432 * @return the name of the field with the child thread ID
434 String
fieldChildTid();
437 * The field with the command. This is used in scheduling tracepoints that
438 * are not switches, and show the current process name. It is often a string
439 * like "zsh" or "cmd.exe".
441 * @return the name of the command field
446 * The field with the name. The name field is used in several disjoint
451 * <li>writeback_* - the name of the io device, often "(unknown)"</li>
452 * <li>module_* - the name of the module such as "binfmt_misc"</li>
453 * <li>irq_handler_entry - the field describes the name of the handler such
457 * @return the name of the field with a name
462 * The field with the status. Often functions like a return value before we
467 * <li>ext4* - status</li>
468 * <li>asoc_snd_soc_cache_sync</li>
470 * <li>state dumps</li>
473 * @return The name of the field with a status
475 String
fieldStatus();
478 * The field with the last command to be run. This is often a string
479 * representing the command of the thread being scheduled out from a
480 * scheduler switch operation.
482 * @return the name of the field with the last command to be run
484 String
fieldPrevComm();
487 * The field with the file name field. This is a string used mostly with
488 * file operations. These operations are often wrapped in system calls and
492 * <li>change mode</li>
493 * <li>change directory</li>
496 * It can also be used in exec commands to see what the command name should
499 * Please note that file read and write often do not use the file name, they
500 * just use the file handle.
502 * @return the name of the field with the file name
504 String
fieldFilename();
507 * The field with the priority. The priority of a given process is used by
508 * most scheduler events. The major exception is the switching operation as
509 * it has two processes so it has a previous and next priority.
511 * @return the name of the field with the thread or process' priority
516 * The field with the new priority. This is used in the scheduler's
517 * pi_setprio event event to show the new priority of the thread or process.
519 * @return the name of the field with the thread or process' new priority
521 String
fieldNewPrio();
524 * The field with the prev priority. This is used in the scheduler's switch
525 * event to show the priority of the thread being scheduled out.
527 * @return the name of the field with the priority of the previous thread
529 String
fieldPrevPrio();
532 * The field with the next priority. This is used in the scheduler's switch
533 * event to show the priority of the next thread or process.
535 * @return the name of the field with the thread or process' next priority
537 String
fieldNextPrio();
540 * The field with the hrtimer. The hrtimer holds the timer instance.
542 * @return the name of the hrTimer field
544 String
fieldHRtimer();
547 * The field with the expires value. The expires field holds the expiry
548 * time. of the hrtimer.
550 * @return the name of the expires field
552 String
fieldHRtimerExpires();
555 * Gets the field name with the softexpires value. The softexpire value is
556 * the absolute earliest expiry time of the hrtimer.
558 * @return the name of the softexpires field
560 String
fieldHRtimerSoftexpires();
563 * The field of the function address value. The function field holds timer
564 * expiry callback function.
566 * @return the name of the function field
568 String
fieldHRtimerFunction();
571 * The field of the now value. The now field holds the current time.
573 * @return the name of the now field (hrtimer)
575 String
fieldHRtimerNow();
578 * The field containing the return value of a system call exit.
580 * @return The name of return field
582 default String
fieldSyscallRet() {
583 return "ret"; //$NON-NLS-1$
587 * Field indicating the upcoming CPU of sched_wakeup and sched_waking
590 * @return The field name
592 default String
fieldTargetCpu() {
593 return "target_cpu"; //$NON-NLS-1$
597 * Field of scheduler migration events, indicating the destination CPU of a
598 * thread being migrated.
600 * @return The field name
602 default String
fieldDestCpu() {
603 return "dest_cpu"; //$NON-NLS-1$
606 // ------------------------------------------------------------------------
607 // I/O events and fields
608 // ------------------------------------------------------------------------
611 * A request to a block IO has just been inserted in the waiting queue.
613 * @return The name of the event
615 default String
eventBlockRqInsert() {
616 return "block_rq_insert"; //$NON-NLS-1$
620 * A request to a block IO has just been issued and passed from the waiting
621 * queue to the driver queue. It is being served.
623 * @return The name of the event
625 default String
eventBlockRqIssue() {
626 return "block_rq_issue"; //$NON-NLS-1$
630 * A request to a block IO has just been completed.
632 * @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
643 default String
eventBlockBioFrontmerge() {
644 return "block_bio_frontmerge"; //$NON-NLS-1$
648 * A BIO operation is being merged at the back of a waiting request
650 * @return The name of the event
652 default String
eventBlockBioBackmerge() {
653 return "block_bio_backmerge"; //$NON-NLS-1$
657 * 2 requests previously inserted in the waiting queue are being merged
659 * @return The name of the event
661 default String
eventBlockRqMerge() {
662 return "block_rq_merge"; //$NON-NLS-1$
666 * Optional event used by some tracers to associate the name of the block
667 * device to a device ID
669 * @return The name of the event
671 default @Nullable String
eventStatedumpBlockDevice() {
676 * The field containing the device ID
678 * @return The name of the field
680 default String
fieldBlockDeviceId() {
681 return "dev"; //$NON-NLS-1$
685 * The field with the first sector of a block operation
687 * @return The name of the field
689 default String
fieldBlockSector() {
690 return "sector"; //$NON-NLS-1$
694 * The field with the number of sectors involved in a block operation
696 * @return The name of the field
698 default String
fieldBlockNrSector() {
699 return "nr_sector"; //$NON-NLS-1$
703 * The field containing the read/write flag of a block operation
705 * @return The name of the field
707 default String
fieldBlockRwbs() {
708 return "rwbs"; //$NON-NLS-1$
712 * The field with the first sector of a request in which another block
713 * operation is being merged
715 * @return The name of the field
717 default String
fieldBlockRqSector() {
718 return "rq_sector"; //$NON-NLS-1$
722 * The field with the sector of the request being merged in another one
724 * @return The name of the field
726 default String
fieldBlockNextRqSector() {
727 return "nextrq_sector"; //$NON-NLS-1$
731 * The field containing the name of the disk
733 * @return The name of the field
735 default String
fieldDiskname() {
736 return "diskname"; //$NON-NLS-1$
740 * The field with the IRQ number. This is used in IPI handlers (entry and
743 * @return the name of the field with the IRQ number
745 default String
fieldIPIVector() {
746 return "vector"; //$NON-NLS-1$
751 * Get the name of the 'order' field from memory page allocation events.
753 * The 'order' of a page allocation is it's logarithm to the base 2, and the
754 * size of the allocation is 2^order, an integral power-of-2 number of
755 * pages. 'Order' ranges from from 0 to MAX_ORDER-1.
757 * The smallest - and most frequent - page allocation is 2^0 or 1 page. The
758 * maximum allocation possible is 2^(MAX_ORDER-1) pages. MAX_ORDER is
759 * assigned a default value of 11 - resulting in a maximum allocation of
760 * 2^10 or 1024 pages. However it may be redefined at kernel configuration
761 * time with the option CONFIG_FORCE_MAX_ZONEORDER.
763 * @return the name of the order field
765 default @Nullable String
fieldOrder() {
769 // ------------------------------------------------------------------------
770 // Network events and fields
771 // ------------------------------------------------------------------------
774 * Get the list of events indicating that a packet is sent on the network
776 * @return The name of the packet send event
778 default Collection
<String
> eventsNetworkSend() {
779 return Collections
.EMPTY_SET
;
783 * Get the list of events indicating that a packet is received from the
786 * @return The collection of names of the packet receive event
788 default Collection
<String
> eventsNetworkReceive() {
789 return Collections
.EMPTY_SET
;
793 * The path of the field corresponding to the sequence number field of a TCP
796 * @return The path of the sequence number field in the TCP header of a
799 default String
[] fieldPathTcpSeq() {
800 return new String
[] { "seq" }; //$NON-NLS-1$
804 * The path of the field corresponding to the acknowledgment number field of
807 * @return The name of the acknowledgment number field in the TCP header of
810 default String
[] fieldPathTcpAckSeq() {
811 return new String
[] { "ack_seq" }; //$NON-NLS-1$
815 * The path of the field corresponding to the flags field of a TCP header
817 * @return The path of the flags field in the TCP header of a network packet
819 default String
[] fieldPathTcpFlags() {
820 return new String
[] { "flags" }; //$NON-NLS-1$
823 // ------------------------------------------------------------------------
824 // VirtualMachine events : kvm entry/exit events
825 // ------------------------------------------------------------------------
828 * KVM kernel event indicating that virtual machine code is being run
830 * @return The name of the kvm entry event
832 default Collection
<String
> eventsKVMEntry() {
833 return Collections
.EMPTY_SET
;
837 * KVM kernel event indicating that virtual machine code is not run anymore,
838 * but rather hypervisor-specific code
840 * @return The name of the kvm exit event
842 default Collection
<String
> eventsKVMExit() {
843 return Collections
.EMPTY_SET
;