1 JITDUMP specification version 2 1 JITDUMP specification version 2
2 Last Revised: 09/15/2016 2 Last Revised: 09/15/2016
3 Author: Stephane Eranian <eranian@gmail.com> 3 Author: Stephane Eranian <eranian@gmail.com>
4 4
5 ---------------------------------------------- 5 --------------------------------------------------------
6 | Revision | Date | Description 6 | Revision | Date | Description |
7 ---------------------------------------------- 7 --------------------------------------------------------
8 | 1 | 09/07/2016 | Initial revision 8 | 1 | 09/07/2016 | Initial revision |
9 ---------------------------------------------- 9 --------------------------------------------------------
10 | 2 | 09/15/2016 | Add JIT_CODE_UNWIND 10 | 2 | 09/15/2016 | Add JIT_CODE_UNWINDING_INFO |
11 ---------------------------------------------- 11 --------------------------------------------------------
12 12
13 13
14 I/ Introduction 14 I/ Introduction
15 15
16 16
17 This document describes the jitdump file forma 17 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.
18 18
19 The format is not specific to any particular p 19 The format is not specific to any particular programming language. It can be extended as need be.
20 20
21 The format of the file is binary. It is self-d 21 The format of the file is binary. It is self-describing in terms of endianness and is portable across multiple processor architectures.
22 22
23 23
24 II/ Overview of the format 24 II/ Overview of the format
25 25
26 26
27 The format requires only sequential accesses, 27 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.
28 28
29 The header is followed by a series of records, 29 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.
30 30
31 Each entry in the file is timestamped. All tim 31 Each entry in the file is timestamped. All timestamps must use the same clock source. The CLOCK_MONOTONIC clock source is recommended.
32 32
33 33
34 III/ Jitdump file header format 34 III/ Jitdump file header format
35 35
36 Each jitdump file starts with a fixed size hea 36 Each jitdump file starts with a fixed size header containing the following fields in order:
37 37
38 38
39 * uint32_t magic : a magic number tagging 39 * 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.
40 * uint32_t version : a 4-byte value represen 40 * uint32_t version : a 4-byte value representing the format version. It is currently set to 1
41 * uint32_t total_size: size in bytes of file h 41 * uint32_t total_size: size in bytes of file header
42 * uint32_t elf_mach : ELF architecture encodi 42 * uint32_t elf_mach : ELF architecture encoding (ELF e_machine value as specified in /usr/include/elf.h)
43 * uint32_t pad1 : padding. Reserved for f 43 * uint32_t pad1 : padding. Reserved for future use
44 * uint32_t pid : JIT runtime process ide 44 * uint32_t pid : JIT runtime process identification (OS specific)
45 * uint64_t timestamp : timestamp of when the f 45 * uint64_t timestamp : timestamp of when the file was created
46 * uint64_t flags : a bitmask of flags 46 * uint64_t flags : a bitmask of flags
47 47
48 The flags currently defined are as follows: 48 The flags currently defined are as follows:
49 * bit 0: JITDUMP_FLAGS_ARCH_TIMESTAMP : set i 49 * 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
50 50
51 IV/ Record header 51 IV/ Record header
52 52
53 The file header is immediately followed by rec 53 The file header is immediately followed by records. Each record starts with a fixed size header describing the record that follows.
54 54
55 The record header is specified in order as fol 55 The record header is specified in order as follows:
56 * uint32_t id : a value identifying the 56 * uint32_t id : a value identifying the record type (see below)
57 * uint32_t total_size: the size in bytes of th 57 * uint32_t total_size: the size in bytes of the record including the header.
58 * uint64_t timestamp : a timestamp of when the 58 * uint64_t timestamp : a timestamp of when the record was created.
59 59
60 The following record types are defined: 60 The following record types are defined:
61 * Value 0 : JIT_CODE_LOAD : record descr 61 * Value 0 : JIT_CODE_LOAD : record describing a jitted function
62 * Value 1 : JIT_CODE_MOVE : record descr 62 * Value 1 : JIT_CODE_MOVE : record describing an already jitted function which is moved
63 * Value 2 : JIT_CODE_DEBUG_INFO: record descr 63 * Value 2 : JIT_CODE_DEBUG_INFO: record describing the debug information for a jitted function
64 * Value 3 : JIT_CODE_CLOSE : record marki 64 * Value 3 : JIT_CODE_CLOSE : record marking the end of the jit runtime (optional)
65 * Value 4 : JIT_CODE_UNWINDING_INFO: record d 65 * Value 4 : JIT_CODE_UNWINDING_INFO: record describing a function unwinding information
66 66
67 The payload of the record must immediately fo 67 The payload of the record must immediately follow the record header without padding.
68 68
69 V/ JIT_CODE_LOAD record 69 V/ JIT_CODE_LOAD record
70 70
71 71
72 The record has the following fields followin 72 The record has the following fields following the fixed-size record header in order:
73 * uint32_t pid: OS process id of the runtime 73 * uint32_t pid: OS process id of the runtime generating the jitted code
74 * uint32_t tid: OS thread identification of 74 * uint32_t tid: OS thread identification of the runtime thread generating the jitted code
75 * uint64_t vma: virtual address of jitted co 75 * uint64_t vma: virtual address of jitted code start
76 * uint64_t code_addr: code start address for 76 * uint64_t code_addr: code start address for the jitted code. By default vma = code_addr
77 * uint64_t code_size: size in bytes of the g 77 * uint64_t code_size: size in bytes of the generated jitted code
78 * uint64_t code_index: unique identifier for 78 * uint64_t code_index: unique identifier for the jitted code (see below)
79 * char[n]: function name in ASCII including 79 * char[n]: function name in ASCII including the null termination
80 * native code: raw byte encoding of the jitt 80 * native code: raw byte encoding of the jitted code
81 81
82 The record header total_size field is inclus 82 The record header total_size field is inclusive of all components:
83 * record header 83 * record header
84 * fixed-sized fields 84 * fixed-sized fields
85 * function name string, including terminatio 85 * function name string, including termination
86 * native code length 86 * native code length
87 * record specific variable data (e.g., array 87 * record specific variable data (e.g., array of data entries)
88 88
89 The code_index is used to uniquely identify ea 89 The code_index is used to uniquely identify each jitted function. The index can be a monotonically increasing 64-bit value. Each time a function is jitted it gets a new number. This value is used in case the code for a function is moved and avoids having to issue another JIT_CODE_LOAD record.
90 90
91 The format supports empty functions with no na 91 The format supports empty functions with no native code.
92 92
93 93
94 VI/ JIT_CODE_MOVE record 94 VI/ JIT_CODE_MOVE record
95 95
96 The record type is optional. 96 The record type is optional.
97 97
98 The record has the following fields followin 98 The record has the following fields following the fixed-size record header in order:
99 * uint32_t pid : OS process id of t 99 * uint32_t pid : OS process id of the runtime generating the jitted code
100 * uint32_t tid : OS thread identifi 100 * uint32_t tid : OS thread identification of the runtime thread generating the jitted code
101 * uint64_t vma : new virtual addres 101 * uint64_t vma : new virtual address of jitted code start
102 * uint64_t old_code_addr: previous code addr 102 * uint64_t old_code_addr: previous code address for the same function
103 * uint64_t new_code_addr: alternate new code 103 * uint64_t new_code_addr: alternate new code started address for the jitted code. By default it should be equal to the vma address.
104 * uint64_t code_size : size in bytes of t 104 * uint64_t code_size : size in bytes of the jitted code
105 * uint64_t code_index : index referring to 105 * uint64_t code_index : index referring to the JIT_CODE_LOAD code_index record of when the function was initially jitted
106 106
107 107
108 The MOVE record can be used in case an already 108 The MOVE record can be used in case an already jitted function is simply moved by the runtime inside the code cache.
109 109
110 The JIT_CODE_MOVE record cannot come before th 110 The JIT_CODE_MOVE record cannot come before the JIT_CODE_LOAD record for the same function name. The function cannot have changed name, otherwise a new JIT_CODE_LOAD record must be emitted.
111 111
112 The code size of the function cannot change. 112 The code size of the function cannot change.
113 113
114 114
115 VII/ JIT_DEBUG_INFO record 115 VII/ JIT_DEBUG_INFO record
116 116
117 The record type is optional. 117 The record type is optional.
118 118
119 The record contains source lines debug informa 119 The record contains source lines debug information, i.e., a way to map a code address back to a source line. This information may be used by the performance tool.
120 120
121 The record has the following fields following 121 The record has the following fields following the fixed-size record header in order:
122 * uint64_t code_addr: address of function fo 122 * uint64_t code_addr: address of function for which the debug information is generated
123 * uint64_t nr_entry : number of debug entrie 123 * uint64_t nr_entry : number of debug entries for the function
124 * debug_entry[n]: array of nr_entry debug en 124 * debug_entry[n]: array of nr_entry debug entries for the function
125 125
126 The debug_entry describes the source line info 126 The debug_entry describes the source line information. It is defined as follows in order:
127 * uint64_t code_addr: address of function for 127 * uint64_t code_addr: address of function for which the debug information is generated
128 * uint32_t line : source file line number 128 * uint32_t line : source file line number (starting at 1)
129 * uint32_t discrim : column discriminator, 0 129 * uint32_t discrim : column discriminator, 0 is default
130 * char name[n] : source file name in ASCI 130 * char name[n] : source file name in ASCII, including null termination
131 131
132 The debug_entry entries are saved in sequence 132 The debug_entry entries are saved in sequence but given that they have variable sizes due to the file name string, they cannot be indexed directly.
133 They need to be walked sequentially. The next 133 They need to be walked sequentially. The next debug_entry is found at sizeof(debug_entry) + strlen(name) + 1.
134 134
135 IMPORTANT: 135 IMPORTANT:
136 The JIT_CODE_DEBUG for a given function must 136 The JIT_CODE_DEBUG for a given function must always be generated BEFORE the JIT_CODE_LOAD for the function. This facilitates greatly the parser for the jitdump file.
137 137
138 138
139 VIII/ JIT_CODE_CLOSE record 139 VIII/ JIT_CODE_CLOSE record
140 140
141 141
142 The record type is optional. 142 The record type is optional.
143 143
144 The record is used as a marker for the end of 144 The record is used as a marker for the end of the jitted runtime. It can be replaced by the end of the file.
145 145
146 The JIT_CODE_CLOSE record does not have any sp 146 The JIT_CODE_CLOSE record does not have any specific fields, the record header contains all the information needed.
147 147
148 148
149 IX/ JIT_CODE_UNWINDING_INFO 149 IX/ JIT_CODE_UNWINDING_INFO
150 150
151 151
152 The record type is optional. 152 The record type is optional.
153 153
154 The record is used to describe the unwinding i 154 The record is used to describe the unwinding information for a jitted function.
155 155
156 The record has the following fields following 156 The record has the following fields following the fixed-size record header in order:
157 157
158 uint64_t unwind_data_size : the size in byte 158 uint64_t unwind_data_size : the size in bytes of the unwinding data table at the end of the record
159 uint64_t eh_frame_hdr_size : the size in byte 159 uint64_t eh_frame_hdr_size : the size in bytes of the DWARF EH Frame Header at the start of the unwinding data table at the end of the record
160 uint64_t mapped_size : the size of the 160 uint64_t mapped_size : the size of the unwinding data mapped in memory
161 const char unwinding_data[n]: an array of unwi 161 const char unwinding_data[n]: an array of unwinding data, consisting of the EH Frame Header, followed by the actual EH Frame
162 162
163 163
164 The EH Frame header follows the Linux Standard 164 The EH Frame header follows the Linux Standard Base (LSB) specification as described in the document at https://refspecs.linuxfoundation.org/LSB_1.3.0/gLSB/gLSB/ehframehdr.html
165 165
166 166
167 The EH Frame follows the LSB specification as 167 The EH Frame follows the LSB specification as described in the document at https://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/ehframechpt.html
168 168
169 169
170 NOTE: The mapped_size is generally either the 170 NOTE: The mapped_size is generally either the same as unwind_data_size (if the unwinding data was mapped in memory by the running process) or zero (if the unwinding data is not mapped by the process). If the unwinding data was not mapped, then only the EH Frame Header will be read, which can be used to specify FP based unwinding for a function which does not have unwinding information.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.