ia64/xen-unstable

view docs/misc/dump-core-format.txt @ 18788:07d0be88571f

hvm: fix single stepping on debugger

The debuggee domain will die with unexpected trap
on single stepping of emulated instruction.

Signed-off-by: Kouya Shimura <kouya@jp.fujitsu.com>
Signed-off-by: Keir Fraser <keir.fraser@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Nov 11 11:47:03 2008 +0000 (2008-11-11)
parents ecbda3783c85
children 04f913ab2049
line source
1 xen dump-core format
2 Written by Isaku Yamahata <yamahata at valinux co jp> Feb. 2007
5 Introduction
6 ------------
7 With xm dump-core command, the guest domain's core can be created as a file.
8 Its format was changed to be based on ELF format because elf format is easily
9 extensible and handy. This document describes the new format.
10 In this document the new format is called new xen dump-core format,
11 xen dump-core format or simply dump-core format. The file of xen dump-core
12 format is called xen dump-core file or dump-core file.
14 The usual process core file includes program headers and no section header.
15 On the other hand the xen dump-core file includes no program headers and
16 some sections because of its peculiar requirements.
19 Reference
20 ---------
21 For ELF format itself, see Tool Interface Standard(TIS) Executable and
22 Linking Format(ELF) Specification version 1.2.
23 For xen related structure, please see the xen header files.
26 Elf header
27 ----------
28 The elf header members are set as follows
29 e_ident[EI_CLASS] = ELFCLASS64 = 2
30 e_ident[EI_OSABI] = ELFOSABI_SYSV = 0
31 e_type = ET_CORE = 4
32 ELFCLASS64 is always used independent of architecture.
33 e_ident[EI_DATA] and e_flags are set according to the dumping system's
34 architecture. Other members are set as usual.
36 Sections
37 --------
38 Currently the following sections are defined. Some sections are optional.
40 ".note.Xen" section
41 name ".note.Xen"
42 type SHT_NOTE
43 description
44 This section is used as note section to store xen dump-core
45 file specific informations. The each detailed informations are
46 described in note section. This section must exist.
48 ".xen_prstatus" section
49 name ".xen_prstatus"
50 type SHT_PROGBITS
51 structure array of vcpu_guest_context_t
52 description
53 This section stores the array of vcpu_guest_context_t
54 which is obtained by XEN_DOMCTL_getvcpucontext hypercall
55 when the xen dump-core file is created.
56 The size of array is stored in xch_nr_vcpus member of header
57 note descriptor in .note.Xen note section.
58 This section must exist.
60 ".xen_shared_info" section
61 name ".xen_shared_info"
62 type SHT_PROGBITS
63 structure shared_info_t
64 description
65 This section stores the contents of shared info page
66 of a domain. This section is optional.
68 ".xen_p2m" section
69 name ".xen_p2m"
70 type SHT_PROGBITS
71 structure array of struct xen_dumpcore_p2m
72 struct xen_dumpcore_p2m {
73 uint64_t pfn;
74 uint64_t gmfn;
75 };
76 description
77 This elements represents the frame number of the page
78 in .xen_pages section.
79 pfn: guest-specific pseudo-physical frame number
80 gmfn: machine physical frame number
81 The size of arrays is stored in xch_nr_pages member of header
82 note descriptor in .note.Xen note section.
83 The entries are stored in pfn-ascending order.
84 The value, {~(uint64_t)0, ~(uint64_t)0}, means invalid
85 (pfn, gmfn) and the corresponding page has zero. There might
86 exist invalid (pfn, gmfn)'s at the end part of this array.
87 This section must exist when the domain is non auto
88 translated physmap mode. Currently x86 paravirtualized domain.
90 ".xen_pfn" section
91 name ".xen_pfn"
92 type SHT_PROGBITS
93 structure array of uint64_t
94 description
95 This elements represents the frame number of the page
96 in .xen_pages section.
97 The size of arrays is stored in xch_nr_pages member of header
98 note descriptor in .note.Xen note section.
99 The entries are stored in ascending order.
100 The value, ~(uint64_t)0, means invalid pfn and the
101 corresponding page has zero. There might exist invalid
102 pfn's at the end part of this array.
103 This section must exist when the domain is auto translated
104 physmap mode. Currently x86 full virtualized domain and
105 ia64 domain.
107 ".xen_pages" section
108 name ".xen_pages"
109 type SHT_PROGBITS
110 structure array of page where page is page size byte array
111 description
112 This section includes the contents of pages.
113 The corresponding address is described in .xen_p2m section
114 or .xen_pfn section.
115 The page size is stored in xch_page_size member of header note
116 descriptor in .note.Xen section.
117 The array size is stored in xch_nr_pages member of header note
118 descriptor in .note.Xen section.
119 This section must exist.
122 ".xen_ia64_mapped_regs" section
123 name ".xen_ia64_mapped_regs"
124 type SHT_PROGBITS
125 structure array of mapped_regs_t
126 description
127 This section stores the array of mapped_regs_t.
128 The size of array is stored in xch_nr_vcpus member of header
129 note descriptor in .note.Xen note section.
130 This section is ia64 specific and must exist for ia64 PV
131 domain.
132 This section must not exist for non-ia64 domain or ia64 HVM
133 domain.
136 note section
137 ------------
138 The note types are defined in xen/include/public/elfnote.h.
139 The note descriptors are defined in tools/libxc/xc_core.h
140 Currently the following note informations are defined.
143 elf note section
145 "Xen" is used as elf note name in elf note info
146 namesz 4
147 name "Xen" (null-terminated)
150 Descriptors
152 none note descriptor
153 type XEN_ELFNOTE_DUMPCORE_NONE = 0x2000000
154 structure struct xen_dumpcore_elfnote_none_desc {
155 /* nothing is defined */
156 };
157 description
158 This note descriptor is defined to just indicate that this
159 file is xen dump-core format without any specific information.
160 This note information must exist.
162 header note descriptor
163 type XEN_ELFNOTE_DUMPCORE_HEADER = 0x2000001
164 structure struct xen_dumpcore_elfnote_header_desc {
165 uint64_t xch_magic;
166 uint64_t xch_nr_vcpus;
167 uint64_t xch_nr_pages;
168 uint64_t xch_page_size;
169 };
170 description
171 This note descriptor stores basic information of the domain.
172 xch_magic magic number
173 XC_CORE_MAGIC = 0xF00FEBED for paravirtualized domain
174 XC_CORE_MAGIC_HVM = 0xF00FEBEE for full virtualized domain
175 xch_nr_vcpus the number of vcpus
176 xch_nr_pages the number of pages
177 xch_page_size guest OS's page size
178 This note information must exist.
180 xen_version descriptor
181 type XEN_ELFNOTE_DUMPCORE_XEN_VERSION = 0x2000002
182 structure struct xen_dumpcore_elfnote_xen_version_desc {
183 uint64_t major_version;
184 uint64_t minor_version;
185 xen_extraversion_t extra_version;
186 xen_compile_info_t compile_info;
187 xen_capabilities_info_t capabilities;
188 xen_changeset_info_t changeset;
189 xen_platform_parameters_t platform_parameters;
190 uint64_t pagesize;
191 };
192 description
193 This note descriptor stores basic information about xen
194 hypervisor. The each members store the result of
195 __HYPERVISOR_xen_version hypercall.
196 major_version 16msb bit of the result of XENVER_version
197 minor_version 16lsb bit of the result of XENVER_version
198 uint64_t is used to make struct
199 xen_dumpcore_elfnote_xen_version_desc independent
200 on 32bit/64bit instead of uint32_t.
201 extra_version the result of XENVER_extraversion
202 compile_info the result of XENVER_compile_info
203 capabilities the result of XENVER_capabilities
204 changeset the result of XENVER_changeset
205 platform_parameters
206 the result of XENVER_platform_parameters
207 pagesize the result of XENVER_pagesize
208 This note information must exist.
210 format_version descriptor
211 type XEN_ELFNOTE_DUMPCORE_FORMAT_VERSION = 0x2000003
212 structure struct xen_dumpcore_elfnote_format_version_desc {
213 uint64_t version;
214 };
215 description
216 This note descriptor stores xen dump-core format version.
217 The 32msb bit is major version and the 32lsb bit is minor
218 version.
219 The minor version will be incremented when the format
220 is changed in compatible way. e.g. new sections, new note
221 descriptors are added.
222 the major version will be incremented when the format is
223 changed in incompatible way.
224 This note information must exit. Analysis tools should check
225 this format version.
226 This note information must exist.
229 Format version history
230 ----------------------
231 Currently only (major, minor) = (0, 1) is used.
232 [When the format is changed, it would be described here.]
234 (0, 1) update
235 - .xen_p2m, .xen_pfn section
236 Invalid pfn/gmfn.
237 - .xen_p2m, .xen_pfn section
238 Arrays must be in pfn ascending order for efficient looking up.
239 - EI_CLASS member of elf header was changed to ELFCLASS64 independent of
240 architecture. This is mainly for x86_32pae.
241 The format version isn't bumped because analysis tools can distinguish it.
242 - .xen_ia64_mapped_regs section was made only for ia64 PV domain.
243 In case of IA64 HVM domain, this section doesn't exist.