d_master Kernel Service

Purpose

Initializes a block-mode direct memory access (DMA) transfer for a DMA master.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/dma.h>
#include <sys/xmem.h>

void d_master 
(channel_id, flags, baddr, count, 
dp, daddr)
int channel_id;
int flags;
caddr_t baddr;
size_t count;
struct xmem *dp;
caddr_t daddr;

Parameters

Description

The d_master kernel service sets up the DMA channel specified by the channel_id parameter to perform a block-mode DMA transfer for a DMA master. The flags parameter controls the operation of the d_master service. "Understanding Direct Memory Access (DMA) Transfers" in AIX Kernel Extensions and Device Support Programming Concepts describes DMA slaves and masters.

The d_master service initializes all the hardware facilities for a DMA transfer, but does not initiate the DMA transfer itself. The d_master service makes the specified system memory buffer available to the DMA device. The d_unmask service may need to be called before the DMA transfer is initiated. The d_master service does not enable or disable the specified DMA channel.

The d_master service supports three different buffer locations:

• A transfer between a buffer in user memory and the device. With this type of transfer, the dp parameter specifies the cross-memory descriptor used with the xmattach service to attach to the user buffer. The baddr and count parameters must be the same values as the uaddr and count parameters specified to the xmattach service.
• A transfer between a global kernel memory buffer and the device. With this type of transfer, the dp->aspace_id variable has an XMEM_GLOBAL value.
• A transfer between I/O bus memory and the device. The BUS_DMA flag distinguishes this type of transfer from the other two types. The dp parameter is ignored with this type of transfer and should be set to null.

The DMA transfer starts at the daddr parameter bus address. The device driver should allocate only a bus address in the window associated with its DMA channel. The size and location of the window are assigned to the device during the configuration process.

Note: The device driver should ensure that the daddr parameter bus address provided to the device includes the page offset (low 12 bits) of the baddr parameter memory-buffer address.

The d_master service performs any required machine-dependent processing, including the following tasks:

• Managing processor memory cache.
• Updating the referenced and changed bits of memory pages involved in the transfer.
• Making the DMA buffer in memory inaccessible to the processor.

If the DMA_WRITE_ONLY flag is set in the flags parameter, the pages involved in the DMA transfer can be read by the device but cannot be written. In addition, the pages involved in the transfer are not hidden from the processor and remain accessible while the pages are a source for DMA.

If the DMA_WRITE_ONLY flag is not set, the pages mapped for the DMA transfer are hidden from the processor. The pages remain inaccessible to the processor until the corresponding d_complete service has been issued once the pages are no longer required for DMA processing.

Notes:

1. When calling the d_master service several times for one or more of the same pages of memory, the corresponding number of d_complete calls must be made to unhide successfully the page or pages involved in the DMA transfers. Pages are not hidden from the processor during the DMA mapping if the DMA_WRITE_ONLY flag is specified on the call to the d_master service.

2. The memory buffer must remain pinned once the d_master service is called until the DMA transfer is completed and the d_complete service is called.

3. The device driver must not access the buffer once the d_master service is called until the DMA transfer is completed and the d_complete service is called.

4. The d_master service, as with all DMA services, should not be called unless the DMA channel has been allocated with the d_init service.

Execution Environment

The d_master kernel service can be called from either the process or interrupt environment.

Implementation Specifics

The d_master kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The d_complete kernel service, d_init kernel service, d_unmask kernel service, xmattach kernel service.

I/O Kernel Services and Understanding Direct Memory Access (DMA) Transfers in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.