direct-io.hg

changeset 14103:0147ef7c3cd7

dump-core: documentation on its format.
Signed-off-by: Isaku Yamahata <yamahata@valinux.co.jp>
author Keir Fraser <keir@xensource.com>
date Sat Feb 24 14:33:34 2007 +0000 (2007-02-24)
parents e2e6830269f7
children 59b8d5168cc1
files docs/misc/dump-core-format.txt
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/misc/dump-core-format.txt	Sat Feb 24 14:33:34 2007 +0000
     1.3 @@ -0,0 +1,225 @@
     1.4 +xen dump-core format
     1.5 +               Written by Isaku Yamahata <yamahata at valinux co jp>  Feb. 2007
     1.6 +
     1.7 +
     1.8 +Introduction
     1.9 +------------
    1.10 +With xm dump-core command, the guest domain's core can be created as a file.
    1.11 +Its format was changed to be based on ELF format because elf format is easily
    1.12 +extensible and handy. This document describes the new format.
    1.13 +In this document the new format is called new xen dump-core format,
    1.14 +xen dump-core format or simply dump-core format. The file of xen dump-core
    1.15 +format is called xen dump-core file or dump-core file.
    1.16 +
    1.17 +The usual process core file includes program headers and no section header.
    1.18 +On the other hand the xen dump-core file includes no program headers and
    1.19 +some sections because of its peculiar requirements.
    1.20 +
    1.21 +
    1.22 +Reference
    1.23 +---------
    1.24 +For ELF format itself, see Tool Interface Standard(TIS) Executable and
    1.25 +Linking Format(ELF) Specification version 1.2.
    1.26 +For xen related structure, please see the xen header files.
    1.27 +
    1.28 +
    1.29 +Elf header
    1.30 +----------
    1.31 +The elf header members are set as follows
    1.32 +        e_ident[EI_OSABI] = ELFOSABI_SYSV = 0
    1.33 +        e_type = ET_CORE = 4
    1.34 +e_ident[EI_CLASS], e_ident[EI_DATA] and e_flags are set according
    1.35 +to an architecture which a file is created. Other members are set as usual.
    1.36 +
    1.37 +
    1.38 +Sections
    1.39 +--------
    1.40 +Currently the following sections are defined. Some sections are optional.
    1.41 +
    1.42 +".note.Xen" section
    1.43 +        name            ".note.Xen"
    1.44 +        type            SHT_NOTE
    1.45 +        description
    1.46 +                This section is used as note section to store xen dump-core
    1.47 +                file specific informations. The each detailed informations are
    1.48 +                described in note section. This section must exist.
    1.49 +
    1.50 +".xen_prstatus" section
    1.51 +        name            ".xen_prstatus"
    1.52 +        type            SHT_PROGBITS
    1.53 +        structure       array of vcpu_guest_context_t
    1.54 +        description
    1.55 +                This section stores the array of vcpu_guest_context_t
    1.56 +                which is obtained by XEN_DOMCTL_getvcpucontext hypercall
    1.57 +                when the xen dump-core file is created.
    1.58 +                The size of array is stored in xch_nr_vcpus member of header
    1.59 +                note descriptor in .note.Xen note section.
    1.60 +                This section must exist.
    1.61 +
    1.62 +".xen_shared_info" section
    1.63 +        name            ".xen_shared_info"
    1.64 +        type            SHT_PROGBITS
    1.65 +        structure       shared_info_t
    1.66 +        description
    1.67 +                This section stores the contents of shared info page
    1.68 +                of a domain. This section is optional. 
    1.69 +
    1.70 +".xen_p2m" section
    1.71 +        name            ".xen_p2m"
    1.72 +        type            SHT_PROGBITS
    1.73 +        structure       array of struct xen_dumpcore_p2m
    1.74 +                        struct xen_dumpcore_p2m {
    1.75 +                            uint64_t    pfn;
    1.76 +                            uint64_t    gmfn;
    1.77 +                        };
    1.78 +        description
    1.79 +                This elements represents the frame number of the page
    1.80 +                in .xen_pages section.
    1.81 +                        pfn:    guest-specific pseudo-physical frame number
    1.82 +                        gmfn:   machine physical frame number
    1.83 +                The size of arrays is stored in xch_nr_pages member of header
    1.84 +                note descriptor in .note.Xen note section.
    1.85 +                There is no rule about the order. Analysis tools must no rely
    1.86 +                on its order.
    1.87 +                This section must exist when the domain is non auto
    1.88 +                translated physmap mode. Currently x86 paravirtualized domain.
    1.89 +
    1.90 +".xen_pfn" section
    1.91 +        name            ".xen_pfn"
    1.92 +        type            SHT_PROGBITS
    1.93 +        structure       array of uint64_t
    1.94 +        description
    1.95 +                This elements represents the frame number of the page
    1.96 +                in .xen_pages section.
    1.97 +                The size of arrays is stored in xch_nr_pages member of header
    1.98 +                note descriptor in .note.Xen note section.
    1.99 +                There is no rule about the order. Analysis tools must no rely
   1.100 +                on its order.
   1.101 +                This section must exist when the domain is auto translated
   1.102 +                physmap mode. Currently x86 full virtualized domain and
   1.103 +                ia64 domain.
   1.104 +
   1.105 +".xen_pages" section
   1.106 +        name            ".xen_pages"
   1.107 +        type            SHT_PROGBITS
   1.108 +        structure       array of page where page is page size byte array
   1.109 +        description
   1.110 +                This section includes the contents of pages.
   1.111 +                The corresponding address is described in .xen_p2m section
   1.112 +                or .xen_pfn section.
   1.113 +                The page size is stored in xch_page_size member of header note
   1.114 +                descriptor in .note.Xen section.
   1.115 +                The array size is stored in xch_nr_pages member of header note
   1.116 +                descriptor in .note.Xen section.
   1.117 +                This section must exist.
   1.118 +
   1.119 +
   1.120 +".xen_ia64_mapped_regs" section
   1.121 +        name            ".xen_ia64_mapped_regs"
   1.122 +        type            SHT_PROGBITS
   1.123 +        structure       array of mapped_regs_t
   1.124 +        description
   1.125 +                This section stores the array of mapped_regs_t.
   1.126 +                The size of array is stored in xch_nr_vcpus member of header
   1.127 +                note descriptor in .note.Xen note section.
   1.128 +                This section is ia64 specific and must exist for ia64 domain.
   1.129 +                This section must not exist for non-ia64 domain.
   1.130 +
   1.131 +
   1.132 +note section
   1.133 +------------
   1.134 +The note types are defined in xen/include/public/elfnote.h.
   1.135 +The note descriptors are defined in tools/libxc/xc_core.h
   1.136 +Currently the following note informations are defined.
   1.137 +
   1.138 +
   1.139 +elf note section
   1.140 +
   1.141 +"Xen" is used as elf note name in elf note info
   1.142 +        namesz  4
   1.143 +        name    "Xen" (null-terminated)
   1.144 +
   1.145 +
   1.146 +Descriptors
   1.147 +
   1.148 +none note descriptor
   1.149 +        type            XEN_ELFNOTE_DUMPCORE_NONE = 0x2000000
   1.150 +        structure       struct xen_dumpcore_elfnote_none_desc {
   1.151 +                               /* nothing is defined */
   1.152 +                        };
   1.153 +        description
   1.154 +                This note descriptor is defined to just indicate that this
   1.155 +                file is xen dump-core format without any specific information.
   1.156 +                This note information must exist.
   1.157 +
   1.158 +header note descriptor
   1.159 +        type            XEN_ELFNOTE_DUMPCORE_HEADER = 0x2000001
   1.160 +        structure       struct xen_dumpcore_elfnote_header_desc {
   1.161 +                                uint64_t    xch_magic;
   1.162 +                                uint64_t    xch_nr_vcpus;
   1.163 +                                uint64_t    xch_nr_pages;
   1.164 +                                uint64_t    xch_page_size;
   1.165 +                        };
   1.166 +        description
   1.167 +                This note descriptor stores basic information of the domain.
   1.168 +                xch_magic       magic number
   1.169 +                    XC_CORE_MAGIC = 0xF00FEBED for paravirtualized domain
   1.170 +                    XC_CORE_MAGIC_HVM = 0xF00FEBEE for full virtualized domain
   1.171 +                xch_nr_vcpus    the number of vcpus
   1.172 +                xch_nr_pages    the number of pages
   1.173 +                xch_page_size   guest OS's page size
   1.174 +                This note information must exist.
   1.175 +
   1.176 +xen_version descriptor
   1.177 +        type            XEN_ELFNOTE_DUMPCORE_XEN_VERSION = 0x2000002
   1.178 +        structure       struct xen_dumpcore_elfnote_xen_version_desc {
   1.179 +                                uint64_t                    major_version;
   1.180 +                                uint64_t                    minor_version;
   1.181 +                                xen_extraversion_t          extra_version;
   1.182 +                                xen_compile_info_t          compile_info;
   1.183 +                                xen_capabilities_info_t     capabilities;
   1.184 +                                xen_changeset_info_t        changeset;
   1.185 +                                xen_platform_parameters_t   platform_parameters;
   1.186 +                                uint64_t                    pagesize;
   1.187 +                        };
   1.188 +        description
   1.189 +                This note descriptor stores basic information about xen
   1.190 +                hypervisor. The each members store the result of
   1.191 +                __HYPERVISOR_xen_version hypercall.
   1.192 +                major_version   16msb bit of the result of XENVER_version
   1.193 +                minor_version   16lsb bit of the result of XENVER_version
   1.194 +                        uint64_t is used to make struct
   1.195 +                        xen_dumpcore_elfnote_xen_version_desc independent
   1.196 +                        on 32bit/64bit instead of uint32_t.
   1.197 +                extra_version   the result of XENVER_extraversion
   1.198 +                compile_info    the result of XENVER_compile_info
   1.199 +                capabilities    the result of XENVER_capabilities
   1.200 +                changeset       the result of XENVER_changeset
   1.201 +                platform_parameters
   1.202 +                                the result of XENVER_platform_parameters
   1.203 +                pagesize        the result of XENVER_pagesize
   1.204 +                This note information must exist.
   1.205 +
   1.206 +format_version descriptor
   1.207 +        type            XEN_ELFNOTE_DUMPCORE_FORMAT_VERSION = 0x2000003
   1.208 +        structure       struct xen_dumpcore_elfnote_format_version_desc {
   1.209 +                                uint64_t    version;
   1.210 +                        };
   1.211 +        description
   1.212 +                This note descriptor stores xen dump-core format version.
   1.213 +                The 32msb bit is major version and the 32lsb bit is minor
   1.214 +                version. 
   1.215 +                The minor version will be incremented when the format
   1.216 +                is changed in compatible way. e.g. new sections, new note
   1.217 +                descriptors are added.
   1.218 +                the major version will be incremented when the format is
   1.219 +                changed in incompatible way.
   1.220 +                This note information must exit. Analysis tools should check
   1.221 +                this format version.
   1.222 +                This note information must exist.
   1.223 +
   1.224 +
   1.225 +Format version history
   1.226 +----------------------
   1.227 +The currently only (major, minor) = (0, 1) is used.
   1.228 +[When the format is changed, it would be described here.]