This document describes the design of the s390 zgetdump tool.

From the man page
-----------------
The  zgetdump tool takes as source a dump device or dump file (DUMPDEV)
and writes its contents to standard output, which you can redirect to a
specific  file.  Alternatively  you  can  also  mount the dump content.
Because zgetdump is able to read and write different dump  formats,  it
can  be used to convert a dump from one format to another. zgetdump can
also verify if a dump is valid or check, whether a DASD device contains
a valid dump tool.

Implementation (Overview)
-------------------------
This functionality is implemented by splitting the code into dump format
specific and independent generic functions. For reading input (source) dumps,
the dump format specific data is converted first into an internal generic
representation. This is done by the DFI (Dump Format Input) code.
For writing dumps in different formats, the internal representation is
converted then into the output (target) dump specific format. This is
done by the DFO (Dump Format Output) code. With the DFO code it is possible
to read the "virtual" output dump at every offset. This is used either
by the code that copies the dump to stdout or by the FUSE code that allows
to mount a DFO dump.

For getting information about dump devices (--device option), the code
is split into dump device specific parts and a generic representation
of a dump device. This is done by the DT (Dump Tool) code.

DFI (Dump format input)
-----------------------
This part of zgetdump allows reading dumps with different formats. Register
and memory information of the input dump is converted into an internal
representation. Each DFI (input dump format) has to provide an init function
that checks the dump and fills up the required data for the internal
representation. For each CPU found in the dump a DFI CPU with the
corresponding registers has to be defined. Each memory chunk of the input
dump has to be registered. A memory chunk is defined by the memory range
and the corresponding memory chunk read callback.

The following return codes are defined for the init function:
 * 0......: Dump has correct format and is valid
 * -EINVAL: Dump has correct format but is incomplete or corrupt
 * -ENODEV: Dump does not have the correct format

The following DFI parts are currently available:

 - dfi.........: Dump format independent functions for internal representation
 - dfi_s390....: S390 input dump format
 - dfi_s390mv..: S390 input multi-volume DASD dump format
 - dfi_s390tape: S390 input tape dump format
 - dfi_lkcd....: LKCD input dump format
 - dfi_elf.....: ELF input dump format

DFO (Dump format output)
------------------------
This part of zgetdump allows the representation of dumps with different
formats. Register and memory information has to be converted from the internal
into the dump format specific representation. Each DFO has to provide an init
function. This function has to register dump chunks. A dump chunk is defined
by the dump offset range and the corresponding dump chunk read callback.

The following DFO parts are available:

 - dfo.....: Dump format independent functions for internal representation
 - dfo_s390: S390 output dump format
 - dfo_elf.: ELF output dump format

DT (Dump Tool)
--------------
This part of zgetdump allows getting information about a dump device via
the "--device" option.

The following parts are available:

 - dt.......: Dump tool independent functions for internal representation
 - dt_s390sv: Support for s390 single-volume DASD dump tools (FBA and ECKD)
 - dt_s390mv: Support for s390 multi-volume DASD dump tool (ECKD)

stdout (standard output)
------------------------
This part writes the dump with the defined DFO to standard output.

FUSE
----
Instead of writing the dump to standard output, it is possible to mount
a dump using FUSE.

For debugging FUSE call zgetdump as follows:

 # zgetdump <normal options> -X -- <fuse options>

 Examples:
 # zgetdump /dev/dasdd1 -m /mnt -X -- -d
 # zgetdump /dev/dasdd1 -m /mnt -X -- --help
 # zgetdump /dev/dasdd1 -m /mnt -X -- -oallow_other,umask=0000

Debugging
---------
All program global variables are stored in the global structure named "g".
You can print all globals in gdb with:

# print g

All static variables of a file are stored in structures named "l" (l for
file local). You can print all static variables of a file "xyz.c" in gdb with:

# print 'xzy.c'::l

There is a central exit function "zg_exit()" that is useful for tracing
program exits. To trace program exits with gdb issue:

# b zg_exit
