Adds and removes entries to the master dump table.
#include <sys/types.h>
#include <errno.h>
#include <sys/dump.h>
int dmp_ctl(op, parmp)
int op;
struct dmpctl_data *parmp;
The dmp_ctl kernel service is used to manage dump routines. It replaces the dmp_add and dmp_del kernel services which are still supported for compatibility reasons. The major differences between routines added with the dmp_add() command and those added with the dmp_ctl() command are:
The dmp_ctl kernel service is used to request that an amount of memory be set aside in a global buffer. This will then be used by the routine to store data not resident in memory. An example of such data is dump data provided by an adapter. Without a global buffer, the data would need to be placed into a pinned buffer allocated at configuration time. Each component would need to allocate its own pinned buffer.
The system dump facility maintains a global buffer for such data. This buffer is allocated when it is first requested, with the requested size. Another dump routine requesting more data causes the buffer to be reallocated with the larger size. Since this buffer must be maintained in pinned storage for the life of the system, only ask for as much memory as is required. Asking for an excessive amount of storage will compromise system performance by reserving too much pinned storage.
Any dump routine using the global buffer is called whenever dump data is required. Routines are only called once to provide such data. Their dump table addresses are saved and used if the dump is restarted.
A dump routine returns a component dump table that begins with DMP_MAGIC, which is the magic number for the 32- or 64-bit dump table. If the unlimited sized dump table is used, the magic number is DMP_MAGIC_U and the cdt_u structure is used. If this is the case, the dump routine is called repeatedly until it returns a null cdt_u pointer. The purpose of the unlimited size dump table is to provide a way to dump an unknown number of data areas without having to preallocate the largest possible array of cdt_entry elements as is required for the classic dump table. The definitions for dump tables are in the sys/dump.h include file.
dmp_ctl operations and the dmpctl_data structure are defined in the dump.h text file.
| op | Specifies the operation to perform. |
| parmp | Points to a dmpctl_data structure
containing values for the specified operation. The dmpctl_data structure is defined in the /usr/include/sys/dump.h file as follows:
/* Dump Routine failures data. */
struct __rtnf {
int rv; /* error code. */
ulong vaddr; /* address. */
vmhandle_t handle; /* handle */
};
typedef void *((*__CDTFUNCENH)(int op, void *buf));
struct dmpctl_data {
int dmpc_magic; /* magic number */
int dmpc_flags; /* dump routine flags. */
__CDTFUNCENH dmpc_func;
union {
u_longlong_t bsize; /* Global buffer size requested. */
struct __rtnf rtnf;
} dmpc_u;
};
#define DMPC_MAGIC1 0xdcdcdc01
#define DMPC_MAGIC DMPC_MAGIC1
#define dmpc_bsize dmpc_u.bsize
#define dmpcf_rv dmpc_u.rtnf.rv
#define dmpcf_vaddr dmpc_u.rtnf.vaddr
#define dmpcf_handle dmpc_u.rtnf.handle
|
The supported operations and their associated data are:
| DMPCTL_ADD | Adds the specified dump routine to the master dump table.
This requires a pointer to the function and function type flags. Supported
type flags are:
|
| DMPCTL_DEL | Deletes the specified dump function from the master dump table. |
| DMPCTL_RTNFAILURE | Reports an inability to dump required data. The routine must set the dmpc_func, dmpcf_rV, dmpcf_vaddr, and dmpcf_handle fields. |
Dump function invocation parameters:
| operation code | Specifies the operation the routine is to perform. Operation
codes are:
|
| buffer pointer | This is a pointer to the global buffer, or NULL if no global buffer space was requested. |
| 0 | Returned if successful. |
| EINVAL | Returned if one or more parameter values are invalid. |
| ENOMEM | Returned if the global buffer request can't be satisfied. |
| EEXIST | Returned if the dump function has already been added. |
void *dmprtn(int op, void *buf);
struct cdt cdt;
dmp_sizeest_t estimate;
config()
{
struct dmpctl_data parm;
...
parm.dmpc_magic = DMPC_MAGIC1;
parm.dmpc_func = dmprtn;
parm.dmpc_flags = 0;
ret = dmp_ctl(DMPCTL_ADD, &parm);
...
}
/*
* Dump routine.
*
* input:
* op - dump routine operation.
* buf - NULL since no global buffer is used.
*
* returns:
* A pointer to the component dump table.
*/
void *
dmprtn(int op, void *buf)
{
void *ret;
switch(op) {
case DMPOP_DATA: /* Provide dump data. */
...
ret = (void *)&cdt;
break;
case DMPOP_ESTIMATE:
ret = (void *)&estimate;
break;
default:
break;
}
return(ret);
}...
#define BSIZ 16*1024
dmp_sizeest_t estimate;
config()
{
...
parm.dmpc_magic = DMPC_MAGIC1;
parm.dmpc_func = dmprtn;
parm.dmpc_flags = DMPFUNC_CALL_ON_RESTART|DMPC_GLOBAL_BUFFER;
parm.dmpc_bsize = BSIZ;
ret = dmp_ctl(DMPCTL_ADD, &parm);
...
}
/*
* Dump routine.
*
* input:
* op - dump routine operation.
* buf - points to the global buffer.
*
* output:
* Return a pointer to the dump table or to the estimate.
*/
void *
dmprtn(int op, void *buf)
{
void *ret;
switch(op) {
case DMPOP_DATA: /* Provide dump data. */
...
(Put data in buffer at buf.)
ret = (void *)&cdt;
break;
case DMPOP_ESTIMATE:
ret = (void *)&estimate;
break;
default:
break;
}
return(ret);
}
The dmp_add Kernel Service and dmp_del Kernel Service kernel services.
The Dump Special File in AIX 5L Version 5.2 Files Reference.
RAS Kernel Services and System Dump Facility in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
The Alphabetical List of Kernel Services