This library provides support for the Zircon incarnation of traditional “core dump” support using the ELF file format. The ELF core file uses a very straightforward format to dump a flexible amount of information, but usually a very complete dump. In contrast to other dump formats such as “minidump”, core files tend to be large and complete, rather than compact and sufficient. The format allows the dump-writer some leeway in choosing how much data to include.
The library provides a flexible callback-based C++ API for controlling the various phases of collecting data for a dump. The library produces dumps in a streaming fashion, with disposition of the data left to callbacks.
A simple writer using POSIX I/O is provided to plug into the callback API to stream to a file descriptor. This works with either seekable or non-seekable file descriptors, seeking forward over gaps of zero padding when possible.
TODO: reading, jobs
The dump of a process is represented by an ELF file. The ELF header's class, byte-order (always 64-bit and little-endian for Fuchsia), and
e_machine fields represent the machine, and
According to the standard format,
ET_CORE files have program headers but no section headers (not counting the
PN_XNUM protocol for large numbers of program headers, which uses a special section header). Each
PT_LOAD segment represents a memory mapping. One or more
PT_NOTE segments give additional information about the process and (optionally) its threads.
TODO: memory, threads, build-id
ET_CORE files also have
PT_NOTE segments providing additional information about the process. The details of the note formats vary widely by system, though all use the ELF note container format. A segment with
p_offset and nonzero
p_filesz but a zero
p_vaddr and zero
p_memsz is recognized as a “non-allocated” segment, which holds offline data but does not correspond to the process address space. This kind of segment is used in
In Zircon core dumps, there is a single non-allocated
PT_NOTE segment that appears before all the
PT_LOAD segments (both in its order in the program header table and in the order of its
p_offset locating data in the file). This contains several notes using different name (string) and type (integer) values to represent process and thread state. These map directly to state reported by the Zircon kernel ABI.
The first series of notes describe process-wide state.
ELF notes using the name
ZirconProcessInfo contain all the types that
zx_object_get_info yields on a Zircon process. The ELF note‘s 32-bit type is exactly the
zx_object_info_topic_t value in
zx_object_get_info. The note’s “description” (payload) has the size and layout that corresponds to that topic. All available types are usually included in the dump.
ELF notes using the name
ZirconProcessProperty contain all the types that
zx_object_get_property yields on a Zircon process. The ELF note‘s 32-bit type is exactly the
property argument to
zx_object_get_property. The note’s “description” (payload) has the size and layout that corresponds to that property. All available properties are usually included in the dump.
The first note is always for
ZX_INFO_HANDLE_BASIC; this has the process KOID (aka PID). (Note that the
rights field indicates the rights the dump-writer had to dump the process; this does not represent any handle present in the process.) The second note is always for
ZX_PROP_NAME. The set of remaining notes and their order is unspecified and subject to change. Dumps generally include all the information the kernel makes available, but a dump-writer might be configured to omit some information or might be forced to omit some information due to runtime errors from the system calls to collect data.