[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Understanding the Diagnostic Subsystem for AIX

pdiag_open

Purpose

Prepares a resource for testing.

Syntax

#include <sys/pdiagex.h>
#include <sys/dma.h>
#include <sys/pdiag_def.h>

int32 pdiag_open( device_instance, dds_ptr, int_handler, handle )

pdiag_addr_t         device_instance;
pdiagex_dds_t       *dds_ptr;
pdiag_addr_t         int_handler;
pdiag_info_handle_t *handle;

Description

The pdiag_open() function allocates memory for a handle for this particular resource. The pdiagex_dds_t structure contains information about the resource to be tested. The Test Unit code must initialize the data in this structure before calling pdiag_open. The returned pdiag_info_handle_t structure is the handle created for the resource. The Test Unit does not need to know any of the internal details of this structure, but must retain the pointer for use in subsequent function calls. The DMA channel is initialized by calling the d_init kernel service and then the DMA channel is unmasked for transfer; that is, you are not required to do a pdiag_dd_dma_setup(). For Micro Channel bus_types, it also initializes a DMA TCW management table to indicate that all buffers are available.

If a user interrupt-handler routine exists, it pins the handler, initializes this handler (using the i_init kernel service), and allocates memory for interrupt data.

Both this routine and pdiag_close() share a common lock while executing to prevent simultaneous resource allocation/deallocation. If a call is made to this routine or pdiag_close() while the lock is being held by a previous call, the calling process will sleep until the routine is available.

Note: In some instances, the members of the dds structure may not be necessary. For example, if dds->bus_type is equal to BUS_60X, the dds members, bus_io_addr, bus_io_length, dma_bus_addr, dma_bus_length, dma_lvl, dma_flags, and dma_chan_id are not used and are ignored by PDIAGEX. See "Data Dictionary".

Execution Environment

The pdiag_open() function can be called from the process environment only.

Parameters

device_instance Pointer to the string name of the specific device to open.
dds_ptr Points to a pdiagex_dds_t structure which should already be initialized with attributes for the particular resource described by the dds (see " Data Dictionary").
int_handler Pointer to the string name of the interrupt handler to be loaded.
handle Returned pointer to diagnostic resource handle.

Return Value

The pdiag_open function returns one of the following values:

DGX_OK The operation was successful. The errno is not set.
DGX_BOUND_FAIL An input parameter is out of bounds (dds.dma_bus_len is not a multiple of PAGESIZE or zero) (Micro Channel bus type only). The errno is not set.
DGX_BADVAL_FAIL An input parameter (dds.bus_type) is not valid. The errno is not set.
DGX_INVALID_HANDLE Specified handle pointer is not valid. The errno is set to the suword() return code.
DGX_COPYDDS_FAIL Application could not copy the dds information. The errno is set to the copyin()/copyout() return code.
DGX_DINIT_FAIL Application could not initialize the DMA channel. The errno is set to the d_init() return code.
DGX_IINIT_FAIL Application could not initialize the user's interrupt handler. The errno is set to the i_init() return code.
DGX_KMOD_FAIL Application could not locate the user's interrupt handler in kernel space. The errno is set to the kmod_entrypt() return code.
DGX_PINCODE_FAIL Application could not pin the user's interrupt handler or the interrupt environment PDIAGEX functions. The errno is set to the pincode() return code.
DGX_PINU_FAIL Application could not pin the specified user buffer. The errno is set to the pinu() return code.
DGX_XMALLOC_FAIL Application could not allocate resources. The errno is set to the xmalloc() return code.
DGX_XMATTACH_FAIL Application could not attach user buffer to the physical address. The errno is set to the xmattach() return code.

Related Information

pdiag_close() function.

[ Previous | Next | Contents | Home | Search ]