dddump Device Driver Entry Point

Purpose

Writes system dump data to a device.

Syntax

#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;

Parameters

Item Description
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.

Description

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:

Dump Command Description
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:

min_tsize
Minimum transfer size (in bytes).
max_tsize
Maximum transfer size (in bytes).
dumpwrite
Address of the write routine.

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.

Execution Environment

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.

Return Values

The dddump entry point indicates an error condition to the caller by returning a nonzero return code.