Writes system dump data to a device.
#include <sys/device.h> int dddump (devno, uiop, cmd, arg, chan, ext) dev_t devno; struct uio *uiop; int cmd, arg; chan_t chan; int ext;
| devno | Specifies the major and minor device numbers. |
| uiop | Points to the uio structure describing the data area or areas to be dumped. |
| cmd | The parameter from the kernel dump function that specifies the operation to be performed. |
| arg | The parameter from the caller that specifies the address of a parameter block associated with the kernel dump command. |
| chan | Specifies the channel number. |
| ext | Specifies the extension parameter. |
The kernel dump routine calls the dddump entry point to set up and send dump requests to the device. The dddump routine is optional for a device driver. It is required only when the device driver supports a device as a target for a possible kernel dump.
If this is the case, it is important that the system state change as little as possible when performing the dump. As a result, the dddump routine should use the minimal amount of services in writing the dump data to the device.
The cmd parameter can specify any of the following dump commands:
| DUMPINIT | Initialization a device in preparation for supporting a system dump. The
specified device instance must have previously been opened. The arg parameter
points to a dumpio_stat structure, defined in /usr/include/sys/dump.h.
This is used for returning device-specific status in case of an error.
The dddump routine should pin all code and data that the device driver uses to support dump writing. This is required to prevent a page fault when actually performing a write of the dump data. (Pinned code should include the dddump routine.) The pin or pincode kernel service can be used for this purpose. | ||||||
| DUMPQUERY | Determines the maximum and minimum number of bytes that can be transferred to
the device in one DUMPWRITE command. For network dumps, the address of the write
routine used in transferring dump data to the network dump device is also sent. The
uiop parameter is not used and is null for this command. The arg parameter
is a pointer to a dmp_query structure, as defined in the
/usr/include/sys/dump.h file.
The dmp_query structure contains the following fields:
Note: Communications device drivers providing remote dump support must supply the address of the write routine used in transferring dump data to the device. The kernel dump function uses logical link control (LLC) to transfer the dump data to the device using the dumpwrite field. The DUMPQUERY command returns the data transfer size information in the dmp_query structure pointed to by the arg parameter. The kernel dump function then uses a buffer between the minimum and maximum transfer sizes (inclusively) when writing dump data. If the buffer is not the size found in the max_tsize field, then its size must be a multiple of the value in the min_tsize field. The min_tsize field and the max_tsize field can specify the same value. | ||||||
| DUMPSTART | Suspends current device activity and provide whatever setup of the device is needed before receiving a DUMPWRITE command. The arg parameter points to a dumpio_stat structure, defined in /usr/include/sys/dump.h. This is used for returning device-specific status in case of an error. | ||||||
| DUMPWRITE | Writes dump data to the target device. The uio structure pointed to by
the uiop parameter specifies the data area or areas to be written to the device
and the starting device offset. The arg parameter points to a dumpio_stat
structure, defined in /usr/include/sys/dump.h. This is used for returning
device-specific status in case of an error. Code for the DUMPWRITE command should
minimize its reliance on system services, process dispatching, and such interrupt
services as the INTIODONE interrupt priority or device
hardware interrupts.
Note: The DUMPWRITE command must never cause a page fault. This is ensured on the part of the caller, since the data areas to be dumped have been determined to be in memory. The device driver must ensure that all of its code, data and stack accesses are to pinned memory during its DUMPINIT command processing. | ||||||
| DUMPEND | Indicates that the kernel dump has been completed. Any cleanup of the device state should be done at this time. | ||||||
| DUMPTERM | Indicates that the specified device is no longer a selected dump target device. If no other devices supported by this dddump routine have a DUMPINIT command outstanding, the DUMPTERM code should unpin any resources pinned when it received the DUMPINIT command. (The unpin kernel service is available for unpinning memory.) The DUMPTERM command is received before the device is closed. | ||||||
| DUMPREAD | Receives the acknowledgment packet for previous DUMPWRITE operations
to a communications device driver. If the device driver receives the acknowledgment
within the specified time, it returns a 0 and the response data is returned to the
kernel dump function in the uiop parameter. If the device driver does not receive
the acknowledgment within the specified time, it returns a value of ETIMEDOUT.
The arg parameter contains a timeout value in milliseconds. |
The DUMPINIT dddump operation is called in the process environment only. The DUMPQUERY, DUMPSTART, DUMPWRITE, DUMPEND, and DUMPTERM dddump operations can be called in both the process environment and interrupt environment.
The dddump entry point indicates an error condition to the caller by returning a nonzero return code.
The devdump kernel service, dmp_add kernel service, dmp_del kernel service, dmp_prinit kernel service, pin kernel service, pincode kernel service, unpin kernel service.
The dump special file.
The uio structure.
Device Driver Kernel Extension Overview in AIX Kernel Extensions and Device Support Programming Concepts.
Programming in the Kernel Environment Overview in AIX Kernel Extensions and Device Support Programming Concepts.