d_map_init_ext Kernel Service

Purpose

Allocates and initializes resources for performing DMA with PCI and VDEVICE devices.

Syntax

#include <sys/types.h>
#include <sys/dma.h>
#include <sys/kerrno.h>

kerrno_t d_map_init_ext (dma_input, info_size, handle_ptr)
d_info_t * dma_input;
size_t info_size;
d_handle_t * handle_ptr;

Parameters

Item	Description
dma_input	Contains information like the bus identifier, flags, and so on.
info_size	Specifies the size of the dma_input parameter in bytes.
handle_ptr	Contains the DMA handle returned upon success.

Description

The d_map_init_ext kernel service is very similar to the d_map_init kernel service. Unlike the d_map_init kernel service, the input argument list of the d_map_init_ext kernel service is not limited and can be extended without breaking binary compatibility. Also, the d_map_init_ext kernel service returns a kerrno_t type return code which contains more RAS information rather than just the DMA_FAIL value.

The caller of the d_map_init_ext kernel service initializes the d_info_t structure and passes it into the d_map_init_ext kernel service by reference. The size of the d_info_t type must match the info_size parameter. This allows future expansion of the d_info_t type safely. If there is a size mismatch, the d_map_init_ext kernel service fails. The d_map_init_ext kernel service also creates a new private pool of I/O memory entitlement that can be used for DMA. The private pool is created by carving out a chunk of total I/O memory entitlement for the AIX® partition. Thus, in order to create a d_handle_t type successfully, there must be sufficient DMA PCI space and I/O memory entitlement.

The following structure is defined in the sys/dma.h file:

#define DMA_MAX_MAPPER_NAME     32
typedef struct d_info
{
      uint64_t    di_bid;
      uint64_t    di_flags;
      uint64_t    di_bus_flags;
      uint64_t    di_channel;
      uint64_t    di_min_mapmem;
      uint64_t    di_des_mapmem;
      uint64_t    di_max_mapmem;
      char        di_mapper_name[DMA_MAX_MAPPER_NAME];
} d_info_t;

Note: The first four fields of the d_info_t type match the four arguments of the d_map_init kernel service. Therefore, all flags and bus_flags on the d_map_init kernel service are honored by the d_map_init_ext kernel service except the DMA_MAXMIN_* flags. The DMA_MAXMIN_* flags are replaced with the di_min_mapmem, di_des_mapmem, and di_max_mapmem fields. They not only specify the required amount of DMA space, but also the necessary I/O memory entitlement for the device.

The di_min_mapmem parameter is the minimum amount of memory that the driver must be able to map for DMA in order to ensure the forward progress. The d_map_init_ext kernel service fails if the minimum I/O memory entitlement requirement cannot be satisfied.

The di_des_mapmem parameter is the required amount of memory that the driver wants to be able to I/O map in order to have good throughput. In most cases, this is a value that a driver specifies through the DMA_MAXMIN_* flag.

The di_max_mapmem parameter is the maximum amount of memory that the driver can ever map for DMA. This is the amount of DMA space that the d_map_init_ext kernel service can allocate.

Note: While the I/O memory entitlement for a d_handle_t type can be changed at runtime through the d_map_attr kernel service, the DMA space cannot be changed dynamically.

The di_mapper_name parameter contains the name of the device instance using the DMA resources (for example, ent0, scsi1, and so on).

Execution Environment

The d_map_init_ext kernel service can be called from the process environment only.

Return Values

Item	Description
0	Indicates a successful completion.
struct d_handle *	Indicates a successful completion.
ENOMEM_D_MAP_INIT_EXT_1	Indicates that the memory allocation failed. An AIX error is logged.
ENOMEM_D_MAP_INIT_EXT_2	Cannot reserve I/O memory entitlement with the least amount specified by the di_min_mapmem parameter. An AIX error is logged.
ENOMEM_D_MAP_INIT_EXT_3	Cannot allocate enough DMA space. An AIX error is logged.
EINVAL_D_MAP_INIT_EXT_1	Indicates that some input argument is not valid. An AIX error is logged in some cases.
EINVAL_D_MAP_INIT_EXT_2	Indicates that the combination of input arguments and system configuration is not valid. No AIX error is logged.
EINVAL_D_MAP_INIT_EXT_3	Indicates that the RAS initialization failed. No AIX error is logged.