class TaskHolder
Defined at line 160 of file ../../src/lib/zxdump/include/lib/zxdump/task.h
This is the API for reading in dumps, both `ET_CORE` files and job archives.
The zxdump::TaskHolder object is a container that holds the data from any
number of dump files. It provides access to the data as a Zircon job tree.
The Job, Process, and Thread objects represent the jobs and processes found
in dump files. Each object provides calls analogous to the Zircon get_info,
get_property, read_memory, and read_state calls, as well as get_child for
nagivating a task tree.
Dumps are inserted into the container by providing the file descriptor. The
type of file will be determined automatically from its contents. Dump files
can be ELF core dump (`ET_CORE`) files, or `ar` archive files. An archive
file can be a job archive or just a plain archive of other dump files. Job
archives can be mere "stub archives", or full hierarchical job archives, or
flattened job archives.
All the jobs and processes found in the dumps inserted then self-assemble
into a job tree. If the same task (same KOID) appears a second time either
in two dump files or in two members of a job archive, insertion fails but
may have added some of the tasks from the dump anyway.
If every process and every job but one is a child of another job found in
the dump so they all form a single job tree, then `root_job` returns the
root of that tree. If not, then `root_job` returns a fake "root job" with a
KOID of 0 and no information or properties available except for the children
and process lists. These show all the jobs that don't have parent jobs that
were dumped, i.e. the roots of job trees; and all the processes that aren't
part of any dumped job at all. Hence populating the container with a single
ELF core dump will yield a fake root job whose sole child is that process.
Methods that can fail use a result type with zxdump::Error. When the
`status_` field is ZX_ERR_IO, that means the failure was in a POSIXish
filesystem access function and `errno` is set to indicate the exact error.
Otherwise the error codes have mostly the same meaning they would have for
the real Zircon calls, with some amendments:
* ZX_ERR_NOT_SUPPORTED just means the dump didn't include the requested
type of data. It doesn't indicate whether the kernel didn't support it,
or the dump-writer intentionally chose not to dump it, or the dump was
just truncated, etc.
* Process::read_memory fails with ZX_ERR_NOT_FOUND if the dump indicated
the memory mapping existed but the dump did not include that memory.
ZX_ERR_OUT_OF_RANGE means the memory is absent because the dump was
truncated though this memory was intended to be included in the dump.
ZX_ERR_NO_MEMORY has the kernel's meaning that there was no memory
mapped at that address in the process. ZX_ERR_NOT_SUPPORTED means that
the dump was inserted with the `read_memory=false` flag.
Public Methods
void TaskHolder (TaskHolder && )Defined at line 164 of file ../../src/lib/zxdump/include/lib/zxdump/task.h
TaskHolder & operator= (TaskHolder && )Defined at line 165 of file ../../src/lib/zxdump/include/lib/zxdump/task.h
void TaskHolder ()Default-constructible, move-only.
Defined at line 788 of file ../../src/lib/zxdump/read.cc
void ~TaskHolder ()Defined at line 790 of file ../../src/lib/zxdump/read.cc
fit::result<Error> Insert (fbl::unique_fd fd, bool read_memory)Read the dump file from the file descriptor and insert its tasks. If
`read_memory` is false, state will be trimmed after reading in all the
notes so less memory is used and the file descriptor is never kept open;
but read_memory calls will always fail with ZX_ERR_NOT_SUPPORTED.
Defined at line 798 of file ../../src/lib/zxdump/read.cc
fit::result<Error, std::reference_wrapper<Object>> Insert (LiveHandle obj)Insert a live task (job or process) or resource. Live threads cannot be
inserted alone, only their containing process.
Defined at line 802 of file ../../src/lib/zxdump/read.cc
fit::result<Error, std::reference_wrapper<Object>> Insert (LiveHandle obj)Insert a live task (job or process) or resource. Live threads cannot be
inserted alone, only their containing process.
Defined at line 802 of file ../../src/lib/zxdump/read.cc
fit::result<Error> InsertSystem ()Insert system data (returned by system_get_*, below) taken from the
currently running system.
Defined at line 22 of file ../../src/lib/zxdump/not-fuchsia.cc
Job & root_job ()Yields the current root job. If all tasks in the eye of the TaskHolder
form a unified tree, this returns the actual root job in that tree.
Otherwise, this is the fake "root job" that reads as KOID 0 with no data
available except the Job::children and Job::processes lists holding each
orphaned task not claimed by any parent job. It's always safe to hold
onto this reference for the life of the TaskHolder. If more tasks are
added, this will start returning a different reference. An old reference
to the fake root job will read as having no children and no processes if
all the tasks self-assembled into a single tree after more dumps were
inserted, and later start reporting new orphan tasks inserted after that.
Defined at line 792 of file ../../src/lib/zxdump/read.cc
Resource & info_resource ()Yields the info resource. If a live handle to the info resource was
passed to Insert, this can access its data. If dumps inserted include the
"privileged kernel" information, that is attached to this fake info
resource though it doesn't have information like a KOID itself. If
multiple dumps supply kernel information, conflicting data inserted later
will be ignored. If both live and dump data are available, the dump data
will obscure the live data.
Defined at line 794 of file ../../src/lib/zxdump/read.cc
uint32_t system_get_dcache_line_size ()These can't fail, but return empty/zero if no corresponding data is in the
dump. If multiple dumps supply system-wide information, only the first
dump's data will be used. There is no checking that the system-wide data
in dumps is valid; malformed data may be treated like no data at all but
still may prevent well-formed data in other dumps from being used.
Defined at line 1536 of file ../../src/lib/zxdump/read.cc
uint32_t system_get_num_cpus ()Defined at line 1540 of file ../../src/lib/zxdump/read.cc
uint64_t system_get_page_size ()Defined at line 1548 of file ../../src/lib/zxdump/read.cc
uint64_t system_get_physmem ()Defined at line 1550 of file ../../src/lib/zxdump/read.cc
std::string_view system_get_version_string ()Defined at line 1532 of file ../../src/lib/zxdump/read.cc
size_t memory_cache_limit ()Get and set the limit (in bytes) of unreferenced Process::read_memory
pages from live processes that may be cached for reuse.
void set_memory_cache_limit (size_t limit)Friends
class Resourceclass Threadclass Processclass Jobclass Taskclass Object