tools/perf/Documentation/jitdump-specification.txt

Source file repositories/reference/linux-study-clean/tools/perf/Documentation/jitdump-specification.txt

File Facts

System
Linux kernel
Corpus path
tools/perf/Documentation/jitdump-specification.txt
Extension
.txt
Size
9248 bytes
Lines
171
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

JITDUMP specification version 2
Last Revised: 09/15/2016
Author: Stephane Eranian <eranian@gmail.com>

--------------------------------------------------------
| Revision  |    Date    | Description                 |
--------------------------------------------------------
|   1       | 09/07/2016 | Initial revision            |
--------------------------------------------------------
|   2       | 09/15/2016 | Add JIT_CODE_UNWINDING_INFO |
--------------------------------------------------------


I/ Introduction


This document describes the jitdump file format. The file is generated by Just-In-time compiler runtimes to save meta-data information about the generated code, such as address, size, and name of generated functions, the native code generated, the source line information. The data may then be used by performance tools, such as Linux perf to generate function and assembly level profiles.

The format is not specific to any particular programming language. It can be extended as need be.

The format of the file is binary. It is self-describing in terms of endianness and is portable across multiple processor architectures.


II/ Overview of the format


The format requires only sequential accesses, i.e., append only mode. The file starts with a fixed size file header describing the version of the specification, the endianness.

The header is followed by a series of records, each starting with a fixed size header describing the type of record and its size. It is, itself, followed by the payload for the record. Records can have a variable size even for a given type.

Each entry in the file is timestamped. All timestamps must use the same clock source. The CLOCK_MONOTONIC clock source is recommended.


III/ Jitdump file header format

Each jitdump file starts with a fixed size header containing the following fields in order:


* uint32_t magic     : a magic number tagging the file type. The value is 4-byte long and represents the string "JiTD" in ASCII form. It written is as 0x4A695444. The reader will detect an endian mismatch when it reads 0x4454694a.
* uint32_t version   : a 4-byte value representing the format version. It is currently set to 1
* uint32_t total_size: size in bytes of file header
* uint32_t elf_mach  : ELF architecture encoding (ELF e_machine value as specified in /usr/include/elf.h)
* uint32_t pad1      : padding. Reserved for future use
* uint32_t pid       : JIT runtime process identification (OS specific)
* uint64_t timestamp : timestamp of when the file was created
* uint64_t flags     : a bitmask of flags

The flags currently defined are as follows:
 * bit 0: JITDUMP_FLAGS_ARCH_TIMESTAMP : set if the jitdump file is using an architecture-specific timestamp clock source. For instance, on x86, one could use TSC directly

IV/ Record header

The file header is immediately followed by records. Each record starts with a fixed size header describing the record that follows.

The record header is specified in order as follows:
* uint32_t id        : a value identifying the record type (see below)
* uint32_t total_size: the size in bytes of the record including the header.
* uint64_t timestamp : a timestamp of when the record was created.

The following record types are defined:
 * Value 0 : JIT_CODE_LOAD      : record describing a jitted function
 * Value 1 : JIT_CODE_MOVE      : record describing an already jitted function which is moved
 * Value 2 : JIT_CODE_DEBUG_INFO: record describing the debug information for a jitted function
 * Value 3 : JIT_CODE_CLOSE     : record marking the end of the jit runtime (optional)
 * Value 4 : JIT_CODE_UNWINDING_INFO: record describing a function unwinding information

 The payload of the record must immediately follow the record header without padding.

V/ JIT_CODE_LOAD record

Annotation

Implementation Notes