handler.c File Reference

#include <ntifs.h>
#include <ndk/rtlfuncs.h>
#include "arbiter.h"
#include <debug.h>

Include dependency graph for handler.c:

Go to the source code of this file.

Classes
struct	_ARBITER_SEED_WINDOW
	Seeds a range list with the resources the bus actually decodes: every descriptor of the arbiter's resource type becomes one unowned range. More...

Macros
#define	NDEBUG

Typedefs
typedef struct _ARBITER_SEED_WINDOW	ARBITER_SEED_WINDOW
	Seeds a range list with the resources the bus actually decodes: every descriptor of the arbiter's resource type becomes one unowned range.
typedef struct _ARBITER_SEED_WINDOW *	PARBITER_SEED_WINDOW

Functions
static VOID	ArbpAcquireLock (_In_ PARBITER_INSTANCE Arbiter)
	Acquires the arbiter's per-instance lock: one arbitration at a time.
static VOID	ArbpReleaseLock (_In_ PARBITER_INSTANCE Arbiter)
	Releases the arbiter's per-instance lock.
NTSTATUS NTAPI	ArbiterLibQueryArbitrate (_In_ PARBITER_INSTANCE Arbiter, _Inout_ PARBITER_QUERY_ARBITRATE_PARAMETERS Parameters)
	The QueryArbitrate action default: reports that this arbiter is willing to arbitrate the given list.
NTSTATUS NTAPI	ArbiterLibAddReserved (_In_ PARBITER_INSTANCE Arbiter, _Inout_ PARBITER_ADD_RESERVED_PARAMETERS Parameters)
	The AddReserved action default: nothing to reserve.
NTSTATUS NTAPI	ArbiterLibHandler (_In_ PVOID Context, _In_ ARBITER_ACTION Action, _Inout_ PARBITER_PARAMETERS Parameters)
	The single ARBITER_ACTION dispatcher every exported ARBITER_INTERFACE points its ArbiterHandler at; Context is the ARBITER_INSTANCE.
static NTSTATUS	ArbpSeedRangeList (_In_ PARBITER_INSTANCE Arbiter, _In_ ULONG ResourceCount, _In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR Resources, _Inout_ PRTL_RANGE_LIST RangeList)
NTSTATUS NTAPI	ArbiterLibInitializeRangeList (_In_ PARBITER_INSTANCE Arbiter, _In_ ULONG ResourceCount, _In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR Resources, _Inout_ PRTL_RANGE_LIST RangeList)
	The InitializeRangeList callback default.
NTSTATUS NTAPI	ArbiterLibStartArbiter (_In_ PARBITER_INSTANCE Arbiter, _In_ PCM_RESOURCE_LIST StartResources)
	The StartArbiter action default: seeds the committed allocation with the windows the bus decodes, so arbitration starts from the hardware's real extent.
VOID NTAPI	ArbiterLibReserveRange (_In_ PARBITER_INSTANCE Arbiter, _In_ ULONGLONG Start, _In_ ULONGLONG End, _In_opt_ PVOID Owner, _In_ BOOLEAN Shared)
	Commits a single [Start, End] range into the arbiter as an ordinary allocation owned by Owner.
VOID NTAPI	ArbiterLibReleaseResources (_In_ PARBITER_INSTANCE Arbiter, _In_ PVOID Owner)
	Releases every committed range owned by Owner.

Macro Definition Documentation

NDEBUG

#define NDEBUG

Definition at line 14 of file handler.c.

Typedef Documentation

ARBITER_SEED_WINDOW

typedef struct _ARBITER_SEED_WINDOW ARBITER_SEED_WINDOW

Seeds a range list with the resources the bus actually decodes: every descriptor of the arbiter's resource type becomes one unowned range.

Parameters

[in]	Arbiter	The arbiter instance whose UnpackResource decodes the descriptors and whose resource type filters them.
[in]	ResourceCount	The number of descriptors in Resources.
[in]	Resources	The CM partial resource descriptors describing the decoded windows.
[in,out]	RangeList	The range list to rebuild from the descriptors. What lands in it is everything outside those windows, because a range list records what is unavailable.

Returns

STATUS_SUCCESS, or STATUS_INSUFFICIENT_RESOURCES.

One window a bus decodes, while the windows are being sorted.

PARBITER_SEED_WINDOW

typedef struct _ARBITER_SEED_WINDOW * PARBITER_SEED_WINDOW

Function Documentation

ArbiterLibAddReserved()

NTSTATUS NTAPI ArbiterLibAddReserved	(	_In_ PARBITER_INSTANCE	Arbiter,
		_Inout_ PARBITER_ADD_RESERVED_PARAMETERS	Parameters
	)

The AddReserved action default: nothing to reserve.

Parameters

[in]	Arbiter	The arbiter instance the reservation was aimed at.
[in,out]	Parameters	The action parameters (pre-Vista builds receive the requirement and resource descriptors directly).

Returns

Returns STATUS_SUCCESS.

Definition at line 112 of file handler.c.

{
    PAGED_CODE();
    UNREFERENCED_PARAMETER(Arbiter);
    UNREFERENCED_PARAMETER(Parameters);
    return STATUS_SUCCESS;
}

Referenced by ArbiterLibInitializeInstance().

ArbiterLibHandler()

NTSTATUS NTAPI ArbiterLibHandler	(	_In_ PVOID	Context,
		_In_ ARBITER_ACTION	Action,
		_Inout_ PARBITER_PARAMETERS	Parameters
	)

The single ARBITER_ACTION dispatcher every exported ARBITER_INTERFACE points its ArbiterHandler at; Context is the ARBITER_INSTANCE.

Parameters

[in]	Context	The ARBITER_INSTANCE the interface was created for.
[in]	Action	The ARBITER_ACTION to perform.
[in,out]	Parameters	The parameters union matching the action.

Returns

Returns the dispatched action's status, STATUS_NOT_IMPLEMENTED for a known but unrouted action, or STATUS_INVALID_PARAMETER for an unrecognized one.

Remarks

The call runs under the instance lock, so a Test and its later Commit or Rollback apply to the same transaction. On Vista+ the transaction event tracks that window: Test and Retest arm it, Commit and Rollback resolve it and wake waiters.

Definition at line 164 of file handler.c.

{
    PARBITER_INSTANCE Arbiter = (PARBITER_INSTANCE)Context;
    NTSTATUS Status;
 
    PAGED_CODE();
 
    ArbpAcquireLock(Arbiter);
 
    switch (Action)
    {
        case ArbiterActionTestAllocation:
#if (NTDDI_VERSION >= NTDDI_VISTA)
            Status = Arbiter->TestAllocation(Arbiter, &Parameters->Parameters.TestAllocation);
#else
            Status = Arbiter->TestAllocation(
                Arbiter,
                Parameters->Parameters.TestAllocation.ArbitrationList);
#endif
            break;
 
        case ArbiterActionRetestAllocation:
#if (NTDDI_VERSION >= NTDDI_VISTA)
            Status = Arbiter->RetestAllocation(Arbiter, &Parameters->Parameters.RetestAllocation);
#else
            Status = Arbiter->RetestAllocation(
                Arbiter,
                Parameters->Parameters.RetestAllocation.ArbitrationList);
#endif
            break;
 
        case ArbiterActionCommitAllocation:
            Status = Arbiter->CommitAllocation(Arbiter);
            break;
 
        case ArbiterActionRollbackAllocation:
            Status = Arbiter->RollbackAllocation(Arbiter);
            break;
 
        case ArbiterActionBootAllocation:
#if (NTDDI_VERSION >= NTDDI_VISTA)
            Status = Arbiter->BootAllocation(Arbiter, &Parameters->Parameters.BootAllocation);
#else
            Status = Arbiter->BootAllocation(
                Arbiter,
                Parameters->Parameters.BootAllocation.ArbitrationList);
#endif
            break;
 
        case ArbiterActionQueryConflict:
#if (NTDDI_VERSION >= NTDDI_VISTA)
            Status = Arbiter->QueryConflict(Arbiter, &Parameters->Parameters.QueryConflict);
#else
            Status = Arbiter->QueryConflict(
                Arbiter,
                Parameters->Parameters.QueryConflict.PhysicalDeviceObject,
                Parameters->Parameters.QueryConflict.ConflictingResource,
                Parameters->Parameters.QueryConflict.ConflictCount,
                Parameters->Parameters.QueryConflict.Conflicts);
#endif
            break;
 
        case ArbiterActionQueryArbitrate:
#if (NTDDI_VERSION >= NTDDI_VISTA)
            Status = Arbiter->QueryArbitrate(Arbiter, &Parameters->Parameters.QueryArbitrate);
#else
            Status = Arbiter->QueryArbitrate(
                Arbiter,
                Parameters->Parameters.QueryArbitrate.ArbitrationList);
#endif
            break;
 
        /*
         * Actions the interface defines but this arbiter does not carry
         * out. AddReserved is one: the instance slot exists and is
         * defaulted, but nothing routes to it.
         */
        case ArbiterActionQueryAllocatedResources:
        case ArbiterActionWriteReservedResources:
        case ArbiterActionAddReserved:
            Status = STATUS_NOT_IMPLEMENTED;
            break;
 
        default:
            Status = STATUS_INVALID_PARAMETER;
            break;
    }
 
#if (NTDDI_VERSION >= NTDDI_VISTA)
    /* Track the tested-but-not-yet-committed window for transaction waiters. */
    if (NT_SUCCESS(Status))
    {
        if (Action == ArbiterActionTestAllocation ||
            Action == ArbiterActionRetestAllocation)
        {
            Arbiter->TransactionInProgress = TRUE;
            KeClearEvent(Arbiter->TransactionEvent);
        }
        else if (Action == ArbiterActionCommitAllocation ||
                 Action == ArbiterActionRollbackAllocation)
        {
            Arbiter->TransactionInProgress = FALSE;
            KeSetEvent(Arbiter->TransactionEvent, IO_NO_INCREMENT, FALSE);
        }
    }
#endif
 
    ArbpReleaseLock(Arbiter);
    return Status;
}

Referenced by PciArbiterConstructor().

ArbiterLibInitializeRangeList()

NTSTATUS NTAPI ArbiterLibInitializeRangeList	(	_In_ PARBITER_INSTANCE	Arbiter,
		_In_ ULONG	ResourceCount,
		_In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR	Resources,
		_Inout_ PRTL_RANGE_LIST	RangeList
	)

The InitializeRangeList callback default.

Parameters

[in]	Arbiter	The arbiter instance the range list belongs to.
[in]	ResourceCount	The number of descriptors in Resources.
[in]	Resources	The CM partial resource descriptors describing the decoded windows.
[in,out]	RangeList	The range list to rebuild from the descriptors.

Returns

Returns STATUS_SUCCESS.

Definition at line 440 of file handler.c.

{
    PAGED_CODE();
    return ArbpSeedRangeList(Arbiter, ResourceCount, Resources, RangeList);
}

Referenced by ArbiterLibInitializeInstance().

ArbiterLibQueryArbitrate()

NTSTATUS NTAPI ArbiterLibQueryArbitrate	(	_In_ PARBITER_INSTANCE	Arbiter,
		_Inout_ PARBITER_QUERY_ARBITRATE_PARAMETERS	Parameters
	)

The QueryArbitrate action default: reports that this arbiter is willing to arbitrate the given list.

Parameters

[in]	Arbiter	The arbiter instance being queried.
[in,out]	Parameters	The action parameters carrying the arbitration list (pre-Vista builds receive the list directly).

Returns

Returns STATUS_SUCCESS.

Definition at line 73 of file handler.c.

{
    PAGED_CODE();
    UNREFERENCED_PARAMETER(Arbiter);
    UNREFERENCED_PARAMETER(Parameters);
    return STATUS_SUCCESS;
}

Referenced by ArbiterLibInitializeInstance().

ArbiterLibReleaseResources()

VOID NTAPI ArbiterLibReleaseResources	(	_In_ PARBITER_INSTANCE	Arbiter,
		_In_ PVOID	Owner
	)

Releases every committed range owned by Owner.

Parameters

[in]	Arbiter	The arbiter instance to release the ranges from.
[in]	Owner	The owning device object (a removed device's PDO).

Remarks

Without this a torn-down device's ranges stay reserved forever and later devices see phantom conflicts.

Definition at line 561 of file handler.c.

{
    PAGED_CODE();
 
    ArbpAcquireLock(Arbiter);
    RtlDeleteOwnersRanges(Arbiter->Allocation, Owner);
    ArbpReleaseLock(Arbiter);
}

ArbiterLibReserveRange()

VOID NTAPI ArbiterLibReserveRange	(	_In_ PARBITER_INSTANCE	Arbiter,
		_In_ ULONGLONG	Start,
		_In_ ULONGLONG	End,
		_In_opt_ PVOID	Owner,
		_In_ BOOLEAN	Shared
	)

Commits a single [Start, End] range into the arbiter as an ordinary allocation owned by Owner.

Parameters

[in]	Arbiter	The arbiter instance to reserve the range in.
[in]	Start	The first address (or unit) of the range.
[in]	End	The last address (or unit) of the range, inclusive.
[in]	Owner	The owning device object, or NULL for a system reservation.
[in]	Shared	TRUE if the range may be shared with other shareable owners.

Remarks

Used to record resources assigned outside the PnP transaction (e.g. a legacy device's IoAssignResources), so later arbitration sees them. Unlike a boot reservation this carries no BOOT_ALLOCATED attribute, so it is not treated as reclaimable.

Definition at line 528 of file handler.c.

{
    PAGED_CODE();
 
    ArbpAcquireLock(Arbiter);
    RtlAddRange(Arbiter->Allocation, Start, End, 0,
                RTL_RANGE_LIST_ADD_IF_CONFLICT | (Shared ? RTL_RANGE_LIST_ADD_SHARED : 0),
                NULL, Owner);
    ArbpReleaseLock(Arbiter);
}

ArbiterLibStartArbiter()

NTSTATUS NTAPI ArbiterLibStartArbiter	(	_In_ PARBITER_INSTANCE	Arbiter,
		_In_ PCM_RESOURCE_LIST	StartResources
	)

The StartArbiter action default: seeds the committed allocation with the windows the bus decodes, so arbitration starts from the hardware's real extent.

Parameters

[in]	Arbiter	The arbiter instance being started.
[in]	StartResources	The bus's decoded resources; NULL or empty means nothing to seed.

Returns

Returns the range-list initialization status.

Definition at line 470 of file handler.c.

{
    PCM_FULL_RESOURCE_DESCRIPTOR Full;
 
    PAGED_CODE();
 
    if (StartResources == NULL || StartResources->Count == 0)
        return STATUS_SUCCESS;
 
    Full = &StartResources->List[0];
 
#if (NTDDI_VERSION >= NTDDI_VISTA)
    /* Vista+ routes through the slot, so an arbiter may override the seeding. */
    return Arbiter->InitializeRangeList(Arbiter,
                                        Full->PartialResourceList.Count,
                                        Full->PartialResourceList.PartialDescriptors,
                                        Arbiter->Allocation);
#else
    return ArbpSeedRangeList(Arbiter,
                             Full->PartialResourceList.Count,
                             Full->PartialResourceList.PartialDescriptors,
                             Arbiter->Allocation);
#endif
}

Referenced by ArbiterLibInitializeInstance().

ArbpAcquireLock()

static VOID ArbpAcquireLock ( _In_ PARBITER_INSTANCE  Arbiter )

static

Acquires the arbiter's per-instance lock: one arbitration at a time.

Parameters

[in]

Arbiter

The arbiter instance to lock.

Definition at line 30 of file handler.c.

{
    PAGED_CODE();
    KeWaitForSingleObject(Arbiter->MutexEvent, Executive, KernelMode, FALSE, NULL);
}

Referenced by ArbiterLibHandler(), ArbiterLibReleaseResources(), and ArbiterLibReserveRange().

ArbpReleaseLock()

static VOID ArbpReleaseLock ( _In_ PARBITER_INSTANCE  Arbiter )

static

Releases the arbiter's per-instance lock.

Parameters

[in]

Arbiter

The arbiter instance to unlock.

Definition at line 47 of file handler.c.

{
    PAGED_CODE();
    KeSetEvent(Arbiter->MutexEvent, IO_NO_INCREMENT, FALSE);
}

Referenced by ArbiterLibHandler(), ArbiterLibReleaseResources(), and ArbiterLibReserveRange().

ArbpSeedRangeList()

static NTSTATUS ArbpSeedRangeList ( _In_ PARBITER_INSTANCE  Arbiter, _In_ ULONG  ResourceCount, _In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR  Resources, _Inout_ PRTL_RANGE_LIST  RangeList  )

static

Definition at line 319 of file handler.c.

{
    PARBITER_SEED_WINDOW Windows;
    ULONG WindowCount = 0;
    ULONGLONG Next;
    ULONG Index;
 
    PAGED_CODE();
 
    RtlFreeRangeList(RangeList);
    RtlInitializeRangeList(RangeList);
 
    if ((Arbiter->UnpackResource == NULL) || (ResourceCount == 0))
        return STATUS_SUCCESS;
 
    Windows = ExAllocatePoolWithTag(PagedPool,
                                    ResourceCount * sizeof(ARBITER_SEED_WINDOW),
                                    TAG_ARBITER);
    if (Windows == NULL)
        return STATUS_INSUFFICIENT_RESOURCES;
 
    /* Collect the windows of our own resource type, lowest first */
    for (Index = 0; Index < ResourceCount; ++Index)
    {
        ULONGLONG Start, Length;
        ULONG Insert;
 
        if (Resources[Index].Type != (UCHAR)Arbiter->ResourceType)
            continue;
 
        Arbiter->UnpackResource(&Resources[Index], &Start, &Length);
        if (Length == 0)
            continue;
 
        for (Insert = WindowCount; Insert > 0; --Insert)
        {
            if (Windows[Insert - 1].Start <= Start)
                break;
 
            Windows[Insert] = Windows[Insert - 1];
        }
 
        Windows[Insert].Start = Start;
        Windows[Insert].End = Start + Length - 1;
        WindowCount++;
    }
 
    /*
     * A bus that reports no window of this kind is not saying it decodes
     * nothing; it is saying it has nothing to add. Leaving the list empty
     * leaves every address available, which is how the root arbiters run.
     */
    if (WindowCount == 0)
    {
        ExFreePoolWithTag(Windows, TAG_ARBITER);
        return STATUS_SUCCESS;
    }
 
    /*
     * What goes in the list is what the arbiter may NOT hand out, so the
     * windows themselves are the gaps in it. Recording the windows instead
     * would wall off exactly the addresses the bus exists to give away.
     */
    Next = 0;
 
    for (Index = 0; Index < WindowCount; ++Index)
    {
        if (Windows[Index].Start > Next)
        {
            RtlAddRange(RangeList, Next, Windows[Index].Start - 1, 0,
                        RTL_RANGE_LIST_ADD_IF_CONFLICT, NULL, NULL);
        }
 
        /* Overlapping windows merge, so only ever move the mark forward */
        if (Windows[Index].End >= Next)
            Next = Windows[Index].End + 1;
 
        /* A window running to the top of the space leaves no tail to block */
        if (Windows[Index].End == ARBITER_MAXIMUM_ADDRESS)
        {
            ExFreePoolWithTag(Windows, TAG_ARBITER);
            return STATUS_SUCCESS;
        }
    }
 
    RtlAddRange(RangeList, Next, ARBITER_MAXIMUM_ADDRESS, 0,
                RTL_RANGE_LIST_ADD_IF_CONFLICT, NULL, NULL);
 
    ExFreePoolWithTag(Windows, TAG_ARBITER);
 
    return STATUS_SUCCESS;
}

Referenced by ArbiterLibInitializeRangeList(), and ArbiterLibStartArbiter().