pdiag_dd_dma

[ Previous | Next | Contents | Home | Search ]

AIX Version 4.3 Understanding the Diagnostic Subsystem for AIX

pdiag_dd_dma_setup

Purpose

The pdiag_dd_dma_setup() function initializes, pins, and cross-memory attaches the user buffer for a DMA operation.

Syntax


#include <sys/pdiagex_dds.h>
#include <sys/dma.h>
int32 pdiag_dd_dma_setup( handle, dma_flags, baddr, users_daddr, count, minxfer,operation )
pdiag_info_handle_t  handle; 
int32 dma_flags;
pdiag_addr_t baddr;
pdiag_addr_t users_daddr;
uint32 count;
uint32 minxfer;
uint32 operation;

Description

The following is performed by the pdiag_dd_dma_setup depending on the bus type and operation:

Where bus type = BUS_MICRO_CHANNEL or BUS_60X and operation is PDIAG_DMA_MASTER

The DMA master function on Micro Channel and 60X bus sytems pins and cross-memory attaches the user buffer for the length of count.
For Micro Channel bus type adapters, the DMA master function issues the d_master kernel call for the specified address and length. The DMA address space is managed for you, and the offset into the DMA buffer is supplied in the daddr parameter. For 60X bus type adapters, the DMA master function issues the xmemdma kernel call for each page referred to by the specified address and length.

The flags for this call will be (XMEM_HIDE | XMEM_ACC_CHK). The DMA address space is not managed for you, and the offset into the DMA buffer is supplied in the daddr parameter.

Note: The dds member, maxmaster, must be set to the maximum number of concurrent pdiag_dd_dma_setup( )s to be used (that is, maximum number of pdiag_dd_dma_setup()s called above the number of associated pdiag_dd_dma_complete ()s at any given time). maxmaster must be set to at least 1 (one) for this call to pass without a DGX_BOUND_FAIL error.

Where bus type = BUS_BID and operation is PDIAG_DMA_MASTER

The pdiag_dd_dma_setup() function pins and cross-memory attaches the user buffer. The function allows for a transfer of 4k or 1 page. The transfer cannot cross a page boundary. Larger transfers are not allowed at this time.
This function issues the d_map_page kernel call for the specified address. The DMA space is managed for the user, and the offset into the DMA buffer is supplied in the users_daddr parameter.

Where bus type = BUS_MICRO_CHANNEL and operation is PDIAG_DMA_SLAVE

For slave operation on a Micro Channel, the pdiag_dd_dma_setup() function issues the d_slave kernel call for the specified length. Only one Micro Channel slave DMA may occur at a time.
Note: The dds member, maxmaster, must be set to at least 1 (one) for this call to pass without a DGX_BOUND_FAIL error.

Execution Environment

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

Parameters

handle	Points to pdiag_info_handle_t structure which is returned from pdiag_open().
dma_flags	This flag is ignored for 60X bus type adapters. The following refers only to Micro Channel bus type adapters. Use the DMA_READ flag for transferring data from the adapter to user memory. Use 0 (zero) for transferring data from the system to the adapter. See the header file sys/dma.h for more information on other DMA flags. If the user wants to read or modify data before calling pdiag_dd_dma_complete(), then DMA_NOHIDE should also be set. This may be useful for devices that set up long-term DMA mapping for purposes of communication (such as command blocks, status blocks, common buffer pools). Then the pdiag_dd_dma_complete() does not have to be called each time they want to let the application read/write, and then pdiag_dd_dma_setup() again for the next DMA transfer. If DMA_NOHIDE is set and the user wants to read data before calling pdiag_dd_dma_complete(), then call the pdiag_dd_dma_enable() routine to flush and read the data. If DMA_NOHIDE is set and the user wants to write data before calling pdiag_dd_dma_complete(), then after the user modifies the data, call the pdiag_dd_dma_enable() routine with a flush operation. Make sure that the adapter will not be transferring data to the same area that the user is manipulating.
baddr	Points to user's read or write buffer where DMA transfer should take place.
users_daddr	Points to an integer to be filled with the physical memory address of baddr upon successful completion of this call.
count	Number of bytes to be transferred.
minxfer	Minimum transfer length that the device will handle. (Slave transfer only on BUS_BID).
operation	Type of operation to perform: PDIAG_DMA_MASTER PDIAG_DMA_SLAVE

Return Value

The pdiag_dd_dma_setup function returns one of the following values:

DGX_OK	The operation was successful. The errno is not set.
DGX_INVALID_HANDLE	Specified handle has been closed or was not generated by the pdiag_open() call. The errno is not set.
DGX_BOUND_FAIL	Application tried to setup a DMA outside its resources, the resources are currently unavailable, or the dds member dma_bus_length (Micro Channel only) or maxmaster is set to zero. The errno is not set.
DGX_BADVAL_FAIL	PDIAGEX was unable to update the specified daddr. The errno is set to the suword() return code.
DGX_PINU_FAIL	Application could not pin the specified user buffer. The errno is set to the pinu() 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_dd_dma_enable() and pdiag_dd_dma_complete() functions.

[ Previous | Next | Contents | Home | Search ]