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 framework calls this method for every SCSIParallelTask immediately after creating the task in the kernel. The driver extension class should override this function to memory-map and prepare any host bus adapter (HBA)-specific task data for direct memory access (DMA), and 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.

The framework uses taskID to uniquely identify the corresponding SCSIParallelTask in the kernel. The taskID also appears in the SCSIUserParallelTask and the fControllerTaskIdentifier member of the SCSIUserParallelResponse structure while interfacing with the dext class.