ia64/xen-unstable

view docs/misc/dump-core-format.txt @ 19128:77393d4de777

[IA64] No need for cmpxchg on page_info structure.

Updates and checks on count_info and page owner can safely be
non-atomic.
This is ia64 counter part of 19088:055c589f4791.

Signed-off-by: Isaku Yamahata <yamahata@valinux.co.jp>
author Isaku Yamahata <yamahata@valinux.co.jp>
date Fri Jan 30 11:12:29 2009 +0900 (2009-01-30)
parents 04f913ab2049
children
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] is set as follows
34 For x86 PV domain case, it is set according to the guest configuration
35 (i.e. if guest is 32bit it is set to EM_386 even when the dom0 is 64 bit.)
36 For other domain case (x86 HVM domain case and ia64 domain case),
37 it is set according to the dumping system's architecture.
38 e_flags is set according to the dumping system's architecture.
39 Other members are set as usual.
41 Sections
42 --------
43 Currently the following sections are defined. Some sections are optional.
45 ".note.Xen" section
46 name ".note.Xen"
47 type SHT_NOTE
48 description
49 This section is used as note section to store xen dump-core
50 file specific informations. The each detailed informations are
51 described in note section. This section must exist.
53 ".xen_prstatus" section
54 name ".xen_prstatus"
55 type SHT_PROGBITS
56 structure array of vcpu_guest_context_t
57 description
58 This section stores the array of vcpu_guest_context_t
59 which is obtained by XEN_DOMCTL_getvcpucontext hypercall
60 when the xen dump-core file is created.
61 The size of array is stored in xch_nr_vcpus member of header
62 note descriptor in .note.Xen note section.
63 This section must exist.
65 ".xen_shared_info" section
66 name ".xen_shared_info"
67 type SHT_PROGBITS
68 structure shared_info_t
69 description
70 This section stores the contents of shared info page
71 of a domain. This section is optional.
73 ".xen_p2m" section
74 name ".xen_p2m"
75 type SHT_PROGBITS
76 structure array of struct xen_dumpcore_p2m
77 struct xen_dumpcore_p2m {
78 uint64_t pfn;
79 uint64_t gmfn;
80 };
81 description
82 This elements represents the frame number of the page
83 in .xen_pages section.
84 pfn: guest-specific pseudo-physical frame number
85 gmfn: machine physical frame number
86 The size of arrays is stored in xch_nr_pages member of header
87 note descriptor in .note.Xen note section.
88 The entries are stored in pfn-ascending order.
89 The value, {~(uint64_t)0, ~(uint64_t)0}, means invalid
90 (pfn, gmfn) and the corresponding page has zero. There might
91 exist invalid (pfn, gmfn)'s at the end part of this array.
92 This section must exist when the domain is non auto
93 translated physmap mode. Currently x86 paravirtualized domain.
95 ".xen_pfn" section
96 name ".xen_pfn"
97 type SHT_PROGBITS
98 structure array of uint64_t
99 description
100 This elements represents the frame number of the page
101 in .xen_pages section.
102 The size of arrays is stored in xch_nr_pages member of header
103 note descriptor in .note.Xen note section.
104 The entries are stored in ascending order.
105 The value, ~(uint64_t)0, means invalid pfn and the
106 corresponding page has zero. There might exist invalid
107 pfn's at the end part of this array.
108 This section must exist when the domain is auto translated
109 physmap mode. Currently x86 full virtualized domain and
110 ia64 domain.
112 ".xen_pages" section
113 name ".xen_pages"
114 type SHT_PROGBITS
115 structure array of page where page is page size byte array
116 description
117 This section includes the contents of pages.
118 The corresponding address is described in .xen_p2m section
119 or .xen_pfn section.
120 The page size is stored in xch_page_size member of header note
121 descriptor in .note.Xen section.
122 The array size is stored in xch_nr_pages member of header note
123 descriptor in .note.Xen section.
124 This section must exist.
127 ".xen_ia64_mapped_regs" section
128 name ".xen_ia64_mapped_regs"
129 type SHT_PROGBITS
130 structure array of mapped_regs_t
131 description
132 This section stores the array of mapped_regs_t.
133 The size of array is stored in xch_nr_vcpus member of header
134 note descriptor in .note.Xen note section.
135 This section is ia64 specific and must exist for ia64 PV
136 domain.
137 This section must not exist for non-ia64 domain or ia64 HVM
138 domain.
141 note section
142 ------------
143 The note types are defined in xen/include/public/elfnote.h.
144 The note descriptors are defined in tools/libxc/xc_core.h
145 Currently the following note informations are defined.
148 elf note section
150 "Xen" is used as elf note name in elf note info
151 namesz 4
152 name "Xen" (null-terminated)
155 Descriptors
157 none note descriptor
158 type XEN_ELFNOTE_DUMPCORE_NONE = 0x2000000
159 structure struct xen_dumpcore_elfnote_none_desc {
160 /* nothing is defined */
161 };
162 description
163 This note descriptor is defined to just indicate that this
164 file is xen dump-core format without any specific information.
165 This note information must exist.
167 header note descriptor
168 type XEN_ELFNOTE_DUMPCORE_HEADER = 0x2000001
169 structure struct xen_dumpcore_elfnote_header_desc {
170 uint64_t xch_magic;
171 uint64_t xch_nr_vcpus;
172 uint64_t xch_nr_pages;
173 uint64_t xch_page_size;
174 };
175 description
176 This note descriptor stores basic information of the domain.
177 xch_magic magic number
178 XC_CORE_MAGIC = 0xF00FEBED for paravirtualized domain
179 XC_CORE_MAGIC_HVM = 0xF00FEBEE for full virtualized domain
180 xch_nr_vcpus the number of vcpus
181 xch_nr_pages the number of pages
182 xch_page_size guest OS's page size
183 This note information must exist.
185 xen_version descriptor
186 type XEN_ELFNOTE_DUMPCORE_XEN_VERSION = 0x2000002
187 structure struct xen_dumpcore_elfnote_xen_version_desc {
188 uint64_t major_version;
189 uint64_t minor_version;
190 xen_extraversion_t extra_version;
191 xen_compile_info_t compile_info;
192 xen_capabilities_info_t capabilities;
193 xen_changeset_info_t changeset;
194 xen_platform_parameters_t platform_parameters;
195 uint64_t pagesize;
196 };
197 description
198 This note descriptor stores basic information about xen
199 hypervisor. The each members store the result of
200 __HYPERVISOR_xen_version hypercall.
201 major_version 16msb bit of the result of XENVER_version
202 minor_version 16lsb bit of the result of XENVER_version
203 uint64_t is used to make struct
204 xen_dumpcore_elfnote_xen_version_desc independent
205 on 32bit/64bit instead of uint32_t.
206 extra_version the result of XENVER_extraversion
207 compile_info the result of XENVER_compile_info
208 capabilities the result of XENVER_capabilities
209 changeset the result of XENVER_changeset
210 platform_parameters
211 the result of XENVER_platform_parameters
212 pagesize the result of XENVER_pagesize
213 This note information must exist.
215 format_version descriptor
216 type XEN_ELFNOTE_DUMPCORE_FORMAT_VERSION = 0x2000003
217 structure struct xen_dumpcore_elfnote_format_version_desc {
218 uint64_t version;
219 };
220 description
221 This note descriptor stores xen dump-core format version.
222 The 32msb bit is major version and the 32lsb bit is minor
223 version.
224 The minor version will be incremented when the format
225 is changed in compatible way. e.g. new sections, new note
226 descriptors are added.
227 the major version will be incremented when the format is
228 changed in incompatible way.
229 This note information must exit. Analysis tools should check
230 this format version.
231 This note information must exist.
234 Format version history
235 ----------------------
236 Currently only (major, minor) = (0, 1) is used.
237 [When the format is changed, it would be described here.]
239 (0, 1) update
240 - .xen_p2m, .xen_pfn section
241 Invalid pfn/gmfn.
242 - .xen_p2m, .xen_pfn section
243 Arrays must be in pfn ascending order for efficient looking up.
244 - EI_CLASS member of elf header was changed to ELFCLASS64 independent of
245 architecture. This is mainly for x86_32pae.
246 The format version isn't bumped because analysis tools can distinguish it.
247 - .xen_ia64_mapped_regs section was made only for ia64 PV domain.
248 In case of IA64 HVM domain, this section doesn't exist.
249 - elf header e_ident[EI_DATA]
250 On x86 PV domain case, it is set according to the guest configuration.
251 I.e. 32-on-64 case, the file will be set EM_386 instead of EM_X86_64.
252 This is the same as 32-on-32 case, so there is no impact on analysis tools.