Contents

UserMapHBAData

Maps any host bus adapter (HBA)-specific task data in response to a call from the framework.

Declaration

virtual kern_return_t UserMapHBAData(uint32_t *uniqueTaskID);

Parameters

  • uniqueTaskID:

    The unique ID for this task.

Return Value

A value that indicates the result of memory-mapping the data. kIOReturnSuccess indicates success. For error definitions, see IOKit Constants.

Discussion

The driver extension class should override this function and memory-map and prepare any host bus adapter (HBA)-specific task data for direct memory access (DMA). The framework calls this method for every SCSIParallelTask immediately after creating the task in the kernel. The driver extension class should also set a unique task ID. The framework uses this ID to uniquely identify the corresponding SCSIParallelTask in the kernel.

The following listing shows an example of implementing UserMapHBAData. It starts by creating an IOBufferMemoryDescriptor for the controller’s specific data structure. It also maps memory to the dext’s memory space. Then the example adds the task to its own task data list, and sets the uniqueTaskID in-out variable to a newly-incremented unique ID. This allows the kernel to associate this task with its corresponding SCSIParallelTaskIdentifier.

kern_return_t
IMPL ( ExampleSCSIDext, UserMapHBAData )
{
    …
    ret = IOBufferMemoryDescriptor::Create ( kIOMemoryDirectionOutIn, ivars->fTaskDataSize,        
                                             vm_page_size, &buffer );
    __Require ( ( kIOReturnSuccess == ret ), Exit );
    
    ret = buffer->CreateMapping ( 0, 0, 0, 0, 0, &memMap );
    __Require ( ( kIOReturnSuccess == ret ), Exit );
    taskData  =  ( typeof ( taskData ) ) memMap->GetAddress ( );

    ivars->fTaskID++;
    ivars->fTaskArray[ivars->fTaskID] = taskData;

    *uniqueTaskID = ivars->fTaskID;
   …
}

It’s important to perform preprocessing like memory mapping early — before serving I/O — because doing so on the I/O path can affect performance. For example, calling an API like CreateMapping in the I/O path can cause additional RPC overhead.

See Also

Managing Host Bus Adapters