fxlookasidelistapi.cpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    FxLookasideListApi.cpp
 
Abstract:
 
    This modules implements the C API's for the FxLookasideList.
 
Author:
 
 
Environment:
 
    kernel mode only
 
Revision History:
 
--*/
 
#include "coreprivshared.hpp"
#include "fxnpagedlookasidelist.hpp"
#include "fxpagedlookasidelist.hpp"
 
extern "C" {
// #include "FxLookasideListAPI.tmh"
}
 
extern "C" {
 
_Must_inspect_result_
__drv_when(PoolType == 1 || PoolType == 257, __drv_maxIRQL(APC_LEVEL))
__drv_when(PoolType == 0 || PoolType == 256, __drv_maxIRQL(DISPATCH_LEVEL))
NTSTATUS
WDFAPI
STDCALL
WDFEXPORT(WdfLookasideListCreate)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in_opt
    PWDF_OBJECT_ATTRIBUTES LookasideAttributes,
    __in
    __drv_when(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
    size_t BufferSize,
    __in
    __drv_strictTypeMatch(__drv_typeExpr)
    POOL_TYPE PoolType,
    __in_opt
    PWDF_OBJECT_ATTRIBUTES MemoryAttributes,
    __in_opt
    ULONG PoolTag,
    __out
    WDFLOOKASIDE* PLookaside
    )
/*++
 
Routine Description:
    Creates a WDFLOOKASIDE list handle.  The returned handle can then create
    WDFMEMORY handles on behalf of the client driver.  The underlying
    WDFLOOKASIDE is a true NTOS lookaside list (of the appropriate paged or
    npaged variety).
 
Arguments:
    LookasideAttributes - Object attributes for the lookaside handle being
        created
 
    BufferSize - Specifies how big each buffer created by the lookaside is
 
    PoolType - Indicates whether the lookaside list is to create paged or
        nonpaged WDFMEMORY handles.
 
    MemoryAttributes - Attributes to be associated with each memory handle created
        using the created lookaside list handle
 
    PoolTag - Pool tag to use for each allocation.  If 0, the frameworks tag
        will be used
 
    PLookaside - Pointer to store the created handle
 
Return Value:
    STATUS_INVALID_PARAMETER if any of the required parameters are incorrect
 
    STATUS_INSUFFICIENT_RESOURCES if no memory is available to create the list
 
    STATUS SUCCESS if succesful
 
  --*/
{
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxLookasideList *pLookaside;
    WDFLOOKASIDE hLookaside;
    NTSTATUS status;
    FxObject* pParent;
 
    pParent = NULL;
    pFxDriverGlobals = GetFxDriverGlobals(DriverGlobals);
 
    //
    // Get the parent's globals if it is present
    //
    if (NT_SUCCESS(FxValidateObjectAttributesForParentHandle(
                        pFxDriverGlobals,
                        LookasideAttributes))) {
        FxObjectHandleGetPtrAndGlobals(pFxDriverGlobals,
                                       LookasideAttributes->ParentObject,
                                       FX_TYPE_OBJECT,
                                       (PVOID*)&pParent,
                                       &pFxDriverGlobals);
    }
    else if (NT_SUCCESS(FxValidateObjectAttributesForParentHandle(
                            pFxDriverGlobals,
                            MemoryAttributes))) {
        FxObjectHandleGetPtrAndGlobals(pFxDriverGlobals,
                                       MemoryAttributes->ParentObject,
                                       FX_TYPE_OBJECT,
                                       (PVOID*)&pParent,
                                       &pFxDriverGlobals);
    }
 
    FxPointerNotNull(pFxDriverGlobals, PLookaside);
 
    hLookaside = NULL;
    *PLookaside = NULL;
 
    if (BufferSize == 0) {
        status = STATUS_INVALID_PARAMETER;
        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Zero BufferSize not allowed, %!STATUS!", status);
        return status;
    }
 
    status = FxValidateObjectAttributes(pFxDriverGlobals, LookasideAttributes);
    if (!NT_SUCCESS(status)) {
        return status;
    }
 
    status = FxValidateObjectAttributes(pFxDriverGlobals, MemoryAttributes);
    if (!NT_SUCCESS(status)) {
        return status;
    }
 
    if (PoolTag == 0) {
        PoolTag = pFxDriverGlobals->Tag;
    }
 
    FxVerifierCheckNxPoolType(pFxDriverGlobals, PoolType, PoolTag);
 
    //
    // Create the appropriate object
    //
    if (FxIsPagedPoolType(PoolType) == FALSE) {
        if (BufferSize < PAGE_SIZE) {
            pLookaside = new(pFxDriverGlobals, LookasideAttributes)
                FxNPagedLookasideList(pFxDriverGlobals, PoolTag);
        }
        else {
            pLookaside = new(pFxDriverGlobals, LookasideAttributes)
                FxNPagedLookasideListFromPool(pFxDriverGlobals, PoolTag);
        }
    }
    else {
        FxDeviceBase* pLookasideDB, *pMemoryDB;
 
        status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
        if (!NT_SUCCESS(status)) {
            return status;
        }
 
        pLookasideDB  = FxDeviceBase::_SearchForDevice(pFxDriverGlobals,
                                                       LookasideAttributes);
 
        pMemoryDB = FxDeviceBase::_SearchForDevice(pFxDriverGlobals,
                                                   MemoryAttributes);
 
        if (pLookasideDB != NULL && pMemoryDB != NULL &&
            pLookasideDB != pMemoryDB) {
            status = STATUS_INVALID_PARAMETER;
 
            //
            // No need to check if LookasideAttributes or MemoryAttributes are
            // equal to NULL b/c we could not get a valid pLookasideDB or
            // pMemoryDB if they were NULL.
            //
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "Lookaside Attributes ancestor WDFDEVICE %p (from ParentObject %p) "
                " is not the same as Memory Attributes ancestor WDFDEVICE %p "
                "(from ParentObject %p), %!STATUS!",
                pLookasideDB->GetHandle(), LookasideAttributes->ParentObject,
                pMemoryDB->GetHandle(), MemoryAttributes->ParentObject,
                status);
 
            return status;
        }
 
        //
        // For paged allocations we always split the WDFMEMORY from its buffer
        // pointer because the memory behind the WDFMEMORY must be non pageable
        // while its buffer is pageable.
        //
        pLookaside = new(pFxDriverGlobals, LookasideAttributes)
            FxPagedLookasideListFromPool(pFxDriverGlobals,
                                         PoolTag,
                                         pLookasideDB,
                                         pMemoryDB);
    }
 
    if (pLookaside == NULL) {
        return STATUS_INSUFFICIENT_RESOURCES;
    }
 
    status = pLookaside->Initialize(BufferSize, MemoryAttributes);
 
    if (NT_SUCCESS(status)) {
        //
        // Follow the global driver policy and either return a PVOID cookie or
        // an index into a handle table.
        //
        status = pLookaside->Commit(LookasideAttributes, (WDFOBJECT*)&hLookaside);
    }
 
    if (NT_SUCCESS(status)) {
        *PLookaside = hLookaside;
    }
    else {
        pLookaside->DeleteFromFailedCreate();
    }
 
    return status;
}
 
_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
NTSTATUS
WDFAPI
STDCALL
WDFEXPORT(WdfMemoryCreateFromLookaside)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFLOOKASIDE Lookaside,
    __out
    WDFMEMORY* Memory
    )
/*++
 
Routine Description:
    Allocates a WDFMEMORY handle from a lookaside HANDLE that the caller
    previously created with WdfLookasideListCreate.
 
Arguments:
    Lookaside - Handle to a lookaside list previously created by the caller
 
    Memory - Handle to be returned to the caller
 
Return Value:
    NTSTATUS
 
  --*/
{
    FxLookasideList* pLookaside;
    FxMemoryObject *pMemory;
    WDFMEMORY hMemory;
    NTSTATUS status;
 
    pLookaside = NULL;
    pMemory = NULL;
 
    //
    // Make sure the caller passed in a valid handle
    //
    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Lookaside,
                         FX_TYPE_LOOKASIDE,
                         (PVOID*)&pLookaside);
 
    FxPointerNotNull(pLookaside->GetDriverGlobals(), Memory);
 
    *Memory = NULL;
 
    status = pLookaside->Allocate(&pMemory);
    if (!NT_SUCCESS(status)) {
        return status;
    }
 
    status = pMemory->Commit(&pLookaside->m_MemoryAttributes,
                             (WDFOBJECT*) &hMemory);
 
    if (NT_SUCCESS(status)) {
        *Memory = hMemory;
    }
    else {
        pMemory->DeleteFromFailedCreate();
    }
 
    return status;
}
 
} // extern "C"