Servicio de kernel dmp_ctl

Editar en línea

Finalidad

Añade y elimina entradas en la tabla de vuelco maestro.

Sintaxis

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

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

Descripción

El servicio de kernel de dmp_ctl se utiliza para gestionar rutinas de volcado. Sustituye los servicios de kernel de dmp_add y dmp_del que todavía están soportados por razones de compatibilidad. Las principales diferencias entre las rutinas añadidas con el mandato dmp_add () y las añadidas con el mandato dmp_ctl () son:
  • Las rutinas se invocan de forma diferente a las rutinas añadidas con el servicio de kernel de dmp_add . Las rutinas añadidas utilizando el servicio de kernel de dmp_ctl devuelven un puntero vacío, a una tabla de volcado o a una estimación de tamaño de vuelco.
  • Se espera que las rutinas añadidas con el servicio de kernel de dmp_ctl ignoren las funciones que no soportan. Por ejemplo, no deben atrapar si reciben una solicitud no reconocida. Esto permite que la funcionalidad futura se añada sin que todos los usuarios tengan que cambiar.

El servicio de kernel de dmp_ctl se utiliza para solicitar que se deje de lado una cantidad de memoria en un almacenamiento intermedio global. A continuación, la rutina utilizará la rutina para almacenar datos no residentes en la memoria. Un ejemplo de estos datos son los datos de vuelco proporcionados por un adaptador. Sin un almacenamiento intermedio global, los datos tendrían que colocarse en un almacenamiento intermedio fijo asignado en el momento de la configuración. Cada componente necesitaría asignar su propio almacenamiento intermedio fijo.

El recurso de vuelco del sistema mantiene un almacenamiento intermedio global para dichos datos. Este almacenamiento intermedio se asigna cuando se solicita por primera vez, con el tamaño solicitado. Otra rutina de volcado que solicita más datos hace que el almacenamiento intermedio se reasigne con el tamaño mayor. Dado que este almacenamiento intermedio debe mantenerse en el almacenamiento fijo para la vida del sistema, sólo solicite la cantidad de memoria necesaria. Solicitar una cantidad excesiva de almacenamiento comprometerá el rendimiento del sistema reservando demasiado almacenamiento fijo.

Cualquier rutina de volcado que utilice el almacenamiento intermedio global se llama siempre que se necesitan datos de vuelco. Las rutinas sólo se llaman una vez para proporcionar dichos datos. Sus direcciones de tabla de volcado se guardan y se utilizan si se reinicia el vuelco.

Nota: El servicio de kernel de dmp_ctl también puede ser utilizado por una rutina de volcado para informar de una anomalía de rutina. Esto puede ser necesario si la rutina detecta que no puede volcar lo que hay que volcar por alguna razón, como la corrupción de una estructura de datos.
Nota: A partir de AIX® Versión 6.1 con el Nivel Tecnológico 6100-02, el servicio de kernel dmp_ctl soporta esa bandera de operación DMPFUNC_SERIALIO.

Tablas de volcado

Una rutina de volcado devuelve una tabla de volcado de componentes que empieza por DMP_MAGIC, que es el número mágico para la tabla de vuelco de 32 o 64 bits. Si se utiliza la tabla de vuelco de tamaño ilimitado, el número mágico es DMP_MAGIC_U y se utiliza la estructura cdt_u . Si este es el caso, la rutina de vuelco se llama repetidamente hasta que devuelve un puntero cdt_u nulo. La finalidad de la tabla de vuelco de tamaño ilimitado es proporcionar una forma de volcar un número desconocido de áreas de datos sin tener que preasignar la mayor matriz posible de elementos cdt_entry como es necesario para la tabla de volcado clásico. Las definiciones de las tablas de volcado se encuentran en el archivo de inclusión sys/dump.h .

Parámetros

Las operaciones dmp_ctl y la estructura dmpctl_data se definen en el archivo de texto dump.h .

Elemento Descripción
op Especifica la operación que ha de realizarse.
parmp Apunta a una estructura dmpctl_data que contiene valores para la operación especificada. La estructura dmpctl_data se define en el archivo /usr/include/sys/dump.h de la siguiente manera:
/* 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

Las operaciones soportadas y sus datos asociados son:

Elemento Descripción
DMPCTL_ADD Añade la rutina de vuelco especificada a la tabla de vuelco maestro. Esto requiere un puntero a los distintivos de función y tipo de función. Los distintivos de tipo soportados son:
DMPFUNC_CALL_ON_RESTART
Vuelve a llamar a esta función si se reinicia el vuelco. Una función de vuelco sólo se invoca una vez para proporcionar datos de vuelco. Si se debe llamar a la función y se reinicia el vuelco en el dispositivo de vuelco secundario, se debe establecer este distintivo. El distintivo DMPFUNC_CALL_ON_RESTART debe establecerse si esta función utiliza el almacenamiento intermedio de volcado global. También debe establecerse si la función utiliza una tabla de vuelco de tamaño ilimitado, una tabla con DMP_MAGIC_U como número mágico.
DMPFUNC_GLOBAL_BUFFER
Esta función utiliza el almacenamiento intermedio de vuelco global. El tamaño se especifica utilizando el campo dmpc_bsize .
DMPFUNC_SERIALIO
Habilita la E/S serializada durante el tiempo de vuelco. La necesidad de este distintivo es específica del dispositivo. Sólo el desarrollador del dispositivo puede determinar si es necesario establecer este distintivo. Sólo se recomienda para dispositivos que pueden estar en la vía de acceso de E/S de vuelco. La serialización de E/S durante el vuelco puede degradar el rendimiento del vuelco. El valor predeterminado, sin este distintivo, es permitir que la E/S se produzca en paralelo con las llamadas de función de CDT.
DMPCTL_DEL Suprime la función de vuelco especificada de la tabla de vuelco maestro.
DMPCTL_RTNFAILURE Informa de una incapacidad para volcar los datos necesarios. La rutina debe configurar dmpc_func,dmpcf_rV, campos dmpcf_vaddr y dmpcf_handle.

Parámetros de invocación de función de vuelco:

Elemento Descripción
código de operación Especifica la operación que debe realizar la rutina. Los códigos de operación son:
DMPRTN_START
El vuelco se está iniciando para esta tabla de volcado. Proporcione datos.
DMPRTN_DONE
El vuelco ha finalizado. Esta llamada se proporciona para que una rutina de vuelco pueda realizar cualquier limpieza necesaria después de un vuelco. Esto es específico de un dispositivo para el que se ha recopilado información. No libera memoria, ya que dicha memoria debe asignarse antes de que se tome el vuelco.
DMPRTN_AGAIN
Proporcione más datos para esta tabla de volcado ilimitada. La rutina debe haber pasado por primera vez una tabla de volcado empezando por DMP_MAGIC_U. Cuando haya finalizado, la función debe devolver un NULL.
DMPRTN_ESTIMATE
Proporcione una estimación de tamaño. La función debe devolver un puntero a un elemento de tipo dmp_sizeest_t. Vea los ejemplos más adelante en este artículo.
puntero del almacenamiento Es un puntero al almacenamiento intermedio global, o NULL si no se ha solicitado ningún espacio de almacenamiento intermedio global.

Valores de retorno

Elemento Descripción
0 Se devuelve si es satisfactorio.
EINVAL Se devuelve si uno o más valores de parámetro no son válidos.
ENOMEM Se devuelve si la solicitud de almacenamiento intermedio global no se puede satisfacer.
EEXIST Se devuelve si la función de vuelco ya se ha añadido.

Ejemplos

  1. Para añadir una rutina de volcado (dmprtn) que se puede llamar una vez para proporcionar datos, escriba:
    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. Para añadir una rutina de volcado (dmprtn) que solicite 16 kb de espacio de almacenamiento intermedio global, escriba:
    ...
          #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);
          }