1xen dump-core format
2               Written by Isaku Yamahata <yamahata at valinux co jp>  Feb. 2007
3
4
5Introduction
6------------
7With xm dump-core command, the guest domain's core can be created as a file.
8Its format was changed to be based on ELF format because elf format is easily
9extensible and handy. This document describes the new format.
10In this document the new format is called new xen dump-core format,
11xen dump-core format or simply dump-core format. The file of xen dump-core
12format is called xen dump-core file or dump-core file.
13
14The usual process core file includes program headers and no section header.
15On the other hand the xen dump-core file includes no program headers and
16some sections because of its peculiar requirements.
17
18
19Reference
20---------
21For ELF format itself, see Tool Interface Standard(TIS) Executable and
22Linking Format(ELF) Specification version 1.2.
23For xen related structure, please see the xen header files.
24
25
26Elf header
27----------
28The 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
32ELFCLASS64 is always used independent of architecture.
33e_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.
38e_flags is set according to the dumping system's architecture.
39Other members are set as usual.
40
41Sections
42--------
43Currently the following sections are defined. Some sections are optional.
44
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.
52
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.
64
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.
72
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.
94
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.
111
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.
125
126
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.
139
140
141note section
142------------
143The note types are defined in xen/include/public/elfnote.h.
144The note descriptors are defined in tools/libxc/xc_core.h
145Currently the following note informations are defined.
146
147
148elf note section
149
150"Xen" is used as elf note name in elf note info
151        namesz  4
152        name    "Xen" (null-terminated)
153
154
155Descriptors
156
157none 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.
166
167header 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.
184
185xen_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.
214
215format_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.
232
233
234Format version history
235----------------------
236Currently only (major, minor) = (0, 1) is used.
237[When the format is changed, it would be described here.]
238
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.
253