Specifies data to be included in a system dump by adding an entry to the master dump table.
#include <sys/types.h> #include <sys/errno.h> #include <sys/dump.h>
int dmp_add (cdt_func) struct cdt * ( (*cdt_func) ( ));
| cdt_func | Specifies a function that returns a pointer to a component dump table entry. The function and the component dump table entry both must reside in pinned global memory. |
Kernel extensions use the dmp_add service to register data areas to be included in a system dump. The dmp_add service adds an entry to the master dump table. A master dump table entry is a pointer to a function provided by the kernel extension that will be called by the kernel dump routine when a system dump occurs. The function must return a pointer to a component dump table structure.
When a dump occurs, the kernel dump routine calls the function specified by the cdt_func parameter twice. On the first call, an argument of 1 indicates that the kernel dump routine is starting to dump the data specified by the component dump table. On the second call, an argument of 2 indicates that the kernel dump routine has finished dumping the data specified by the component dump table. Kernel extensions should allocate and pin their component dump tables and call the dmp_add service during initialization. The entries in the component dump table can be filled in later. The cdt_func routine must not attempt to allocate memory when it is called.
The component dump table structure specifies memory areas to be included in the system dump. The structure type (struct cdt) is defined in the /usr/include/sys/dump.h file. A cdt structure consists of a fixed-length header (cdt_head structure) and an array of one or more cdt_entry structures. The cdt_head structure contains a component name field, which should be filled in with the name of the kernel extension, and the length of the component dump table. Each cdt_entry structure describes a contiguous data area, giving a pointer to the data area, its length, a segment register, and a name for the data area. The name supplied for the data area can be used to refer to it when the crash command formats the dump.
Each kernel extension that includes data in the system dump can install a unique formatting routine in the /var/adm/ras/dmprtns directory. A formatting routine is a command that is called by the crash command. The name of the formatting routine must match the component name field of the corresponding component dump table. The crash command forks a child process that executes the formatting routines. If a formatting routine is not present for a component name, the crash command executes the _default_dmp_fmt default formatting routine, which prints out the data areas in hexadecimal.
The crash command calls the formatting routine as a command, passing the file descriptor of the open dump image file as a command line argument. The syntax for this argument is -ffile _descriptor.
The dump image file includes a copy of each component dump table used to dump memory. Before calling a formatting routine, the crash command positions the file pointer for the dump image file to the beginning of the relevant component dump table copy. A sample dump formatter is shipped with bos.sysmgt.serv_aid in the /usr/samples/dumpfmt directory.
Memory dumped for each kernel extension is laid out as follows in the dump image file. The component dump table is followed by a bit map for the first data area, then the first data area itself, then a bit map for the next data area, the next data area itself, and so on.
The bit map for a given data area indicates which pages of the data area are actually present in the dump image and which are not. Pages that were not in memory when the dump occurred were not dumped. The least significant bit of the first byte of the bit map is set to 1 (one) if the first page is present. The next least significant bit indicates the presence or absence of the second page and so on.
A macro for determining the size of a bit map is provided in the /usr/include/sys/dump.h file.
The dmp_add kernel service can be called from the process environment only.
| 0 | Indicates a successful operation. |
| -1 | Indicates that the function pointer to be added is already present in the master dump table. |
The dmp_add kernel service is part of Base Operating System (BOS) Runtime.
The crash command, exec command.
The dmp_del kernel service.
RAS Kernel Services in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.