dmp_ctl Kernel Service

Purpose

Adds and removes entries to the master dump table.

Syntax

#include <sys/types.h>
     #include <errno.h>
     #include <sys/dump.h>

     int dmp_ctl(op, parmp)
     int op;
     struct dmpctl_data *parmp;

Description

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.

Dump Tables

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.

Parameters

dmp_ctl operations and the dmpctl_data structure are defined in the dump.h text file.

/* 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:

Dump function invocation parameters:

Return Values

Examples

1. To add a dump routine (dmprtn) that can be called once to provide data, type:

   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 DMPRTN_START: /* Provide dump data. */
                             ...
                             ret = (void *)&cdt;
                             break;
                     case DMPRTN_ESTIMATE:
                             ret = (void *)&estimate;
                             break;
                     default:
                                     break;
                     }
   
                     return(ret);
             }

2. To add a dump routine (dmprtn) that requests 16 kb of global buffer space, type:

   ...
             #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 DMPRTN_START: /* Provide dump data. */
                             ...
                             (Put data in buffer at buf.)
                             ret = (void *)&cdt;
                             break;
                     case DMPRTN_ESTIMATE:
                             ret = (void *)&estimate;
                             break;
                     default:
                                     break;
                     }
   
                     return(ret);
             }