Prepares a resource for testing.
#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;
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".
The pdiag_open() function can be called from the process environment only.
|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.|
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.|