[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Kernel and Subsystems, Volume 1

xmemdma Kernel Service

Purpose

Prepares a page for direct memory access (DMA) I/O or processes a page after DMA I/O is complete.

Syntax

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


int xmemdma ( xp, xaddr, flag)
struct xmem *xp;
caddr_t xaddr;
int flag;

Parameters

xp Specifies a cross-memory descriptor.
xaddr Identifies the address specifying the page for transfer.
flag Specifies whether to prepare a page for DMA I/O or process it after DMA I/O is complete. Possible values are:
XMEM_ACC_CHK
Performs access checking on the page. When this flag is set, the page protection attributes are verified.
XMEM_DR_SAFE
Indicates that the use of the real memory address is DLPAR safe.
XMEM_HIDE
Prepares the page for DMA I/O. For cache-inconsistent platforms, this preparation includes hiding the page by making it inaccessible.
XMEM_UNHIDE
Processes the page after DMA I/O. Also, this flag reveals the page and makes it accessible for cache-inconsistent platforms.
XMEM_WRITE_ONLY
Marks the intended transfer as outbound only. This flag is used with XMEM_ACC_CHK to indicate that read-only access to the page is sufficient.

Description

The xmemdma kernel service operates on the page specified by the xaddr parameter in the region specified by the cross-memory descriptor. If the cross-memory descriptor is for the kernel, the xaddr parameter specifies a kernel address. Otherwise, the xaddr parameter specifies the offset in the region described in the cross-memory descriptor.

The xmemdma kernel service is provided for machines that have processor-memory caches, but that do not perform DMA I/O through the cache. Device handlers for Micro Channel DMA devices use the d_master service and d_complete kernel service instead of the xmemdma kernel service.

If the flag parameter indicates XMEM_HIDE (that is, XMEM_UNHIDE is not set) and this is the first hide for the page, the xmemdma kernel service prepares the page for DMA I/O by flushing the cache and making the page invalid. When the XMEM_UNHIDE bit is set and this is the last unhide for the page, the following events take place:

  1. The page is made valid.

    If the page is not in pager I/O state:

  2. Any processes waiting on the page are readied.
  3. The modified bit for the page is set unless the page has a read-only storage key.

The page is made not valid during DMA operations so that it is not addressable with any virtual address. This prevents any process from reading or loading any part of the page into the cache during the DMA operation.

The page specified must be in memory and must be pinned.

If the XMEM_ACC_CHK bit is set, then the xmemdma kernel service also verifies access permissions to the page. If the page access is read-only, then the XMEM_WRITE_ONLY bit must be set in the flag parameter.

Note
  1. The xmemdma kernel service does not hide or reveal the page nor does it perform any cache flushing. The service's primary function is for real-address translation.
  2. This service is not supported for large-memory systems with greater than 4GB of physical memory addresses. For such systems, xmemdma64 should be used.

xmemdma with DLPAR

On systems that are capable of Dynamic Logical Partition (DLPAR) such as the dynamic removal of memory, calls to xmemdma without the XMEM_DR_SAFE flag result in the specified memory being flagged as not removable. This is done to guarantee the integrity of the system, because the system has no knowledge of how the caller intends to utilize the real memory address that was returned. Dynamic memory removal operations are still possible for other memory, but not for the memory specified by the xmemdma call.

If the caller is using the real memory address for informational purposes only (such as for trace buffers or debug information), the caller can set the XMEM_DR_SAFE flag. This is an indication to the system that the real memory address can be exposed to the caller without any risk of data corruption. When this flag is present, the system will still allow the specified memory to be dynamically removed.

If the caller is using the real memory address to perform actual data access, either by turning off data translation and performing CPU load/store access to the real memory, or by programming DMA controllers to target the real memory, the XMEM_DR_SAFE flag should not be set. If the flag is set, the system's data integrity could be compromised when the memory is dynamically removed. For information on converting a kernel extension that uses real memory addresses in this way to be DLPAR Aware, contact your IBM Service Representative.

Execution Environment

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

Return Values

On successful completion, the xmemdma service returns the real address corresponding to the xaddr and xp parameters.

Error Codes

The xmemdma kernel service returns a value of XMEM_FAIL if one of the following are true:

Related Information

Cross Memory Kernel Services and Memory Kernel Services in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Understanding Direct Memory Access (DMA) Transfer.

Dynamic Logical Partitioning in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]