arbport.c File Reference

#include <ntoskrnl.h>
#include <debug.h>

Include dependency graph for arbport.c:

Go to the source code of this file.

Macros
#define	NDEBUG
#define	PORT_ALIAS_STRIDE_10_BIT   0x400
#define	PORT_ALIAS_STRIDE_12_BIT   0x1000
#define	PORT_MAX_ADDRESS   0xFFFF

Functions
ULONGLONG NTAPI	RtlIoDecodeMemIoResource (_In_ PIO_RESOURCE_DESCRIPTOR Descriptor, _Out_opt_ PULONGLONG Alignment, _Out_opt_ PULONGLONG MinimumAddress, _Out_opt_ PULONGLONG MaximumAddress)
ULONGLONG NTAPI	RtlCmDecodeMemIoResource (_In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR Descriptor, _Out_opt_ PULONGLONG Start)
static NTSTATUS	IopArbPortTranslateAddress (_In_ UCHAR SourceType, _In_ PHYSICAL_ADDRESS SourceAddress, _Out_ PPHYSICAL_ADDRESS TranslatedAddress, _Out_ PUCHAR TranslatedType)
	Translates one bus-relative address to a system-physical one on the ISA bus, and reports the space it landed in as a CM resource type.
static BOOLEAN	IopArbPortGetNextAlias (_In_ USHORT DescriptorFlags, _In_ UINT64 LastAlias, _Out_ PUINT64 NextAlias)
	Walks the decode-alias chain of a port range: given the previous alias, or the granted range's start on the first call, produces the next one.
static NTSTATUS NTAPI	IopArbPortUnpackRequirements (_In_ PIO_RESOURCE_DESCRIPTOR IoDescriptor, _Out_ PUINT64 OutMinimumAddress, _Out_ PUINT64 OutMaximumAddress, _Out_ PUINT64 OutLength, _Out_ PUINT64 OutAlignment)
	Extracts the placement window from one I/O port requirement. The UnpackRequirement callback of the Root Port arbiter.
static NTSTATUS NTAPI	IopArbPortPackResource (_In_ PIO_RESOURCE_DESCRIPTOR IoDescriptor, _In_ UINT64 Start, _Out_ PCM_PARTIAL_RESOURCE_DESCRIPTOR CmDescriptor)
	Materialises the arbiter's chosen placement as an assigned CM descriptor. The PackResource callback of the Root Port arbiter.
static NTSTATUS NTAPI	IopArbPortUnpackResource (_In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR CmDescriptor, _Out_ PUINT64 Start, _Out_ PUINT64 OutLength)
	Reads the placement back out of an already-assigned descriptor (a firmware boot configuration, typically) so the arbiter can mark that span occupied. The inverse of IopArbPortPackResource and the UnpackResource callback of the Root Port arbiter.
static INT32 NTAPI	IopArbPortScoreRequirement (_In_ PIO_RESOURCE_DESCRIPTOR IoDescriptor)
	Scores how constrained a requirement is: the number of distinct aligned addresses it could be placed at inside its own window, ignoring what is already allocated. The ScoreRequirement callback of the Root Port arbiter.
static NTSTATUS NTAPI	IopArbPortTranslateOrdering (_Out_ PIO_RESOURCE_DESCRIPTOR OutIoDescriptor, _In_ PIO_RESOURCE_DESCRIPTOR IoDescriptor)
	Translates one registry allocation-ordering window from the bus-relative addresses it is written in into the system-physical space the arbiter allocates in. The TranslateOrdering function of the Root Port arbiter.
static BOOLEAN NTAPI	IopArbPortFindSuitableRange (_In_ PARBITER_INSTANCE Arbiter, _Inout_ PARBITER_ALLOCATION_STATE ArbState)
	The Root Port arbiter's FindSuitableRange: the engine search, incremented for a device asking to keep the ports the firmware already programmed it into.
static VOID NTAPI	IopArbPortAddAllocation (_In_ PARBITER_INSTANCE Arbiter, _Inout_ PARBITER_ALLOCATION_STATE ArbState)
	The Root Port arbiter's AddAllocation: records the granted range in the tentative allocation, and behind it every port range a partially-decoding ISA card would shadow.
static VOID NTAPI	IopArbPortBacktrackAllocation (_In_ PARBITER_INSTANCE Arbiter, _Inout_ PARBITER_ALLOCATION_STATE ArbState)
	The Root Port arbiter's BacktrackAllocation: the exact inverse of IopArbPortAddAllocation.
NTSTATUS NTAPI	IopArbPortInitialize (VOID)
	Initialize the RootPortArbiter.

Variables
ARBITER_INSTANCE	IopRootPortArbiter

Macro Definition Documentation

NDEBUG

#define NDEBUG

Definition at line 11 of file arbport.c.

PORT_ALIAS_STRIDE_10_BIT

#define PORT_ALIAS_STRIDE_10_BIT   0x400

Definition at line 37 of file arbport.c.

PORT_ALIAS_STRIDE_12_BIT

#define PORT_ALIAS_STRIDE_12_BIT   0x1000

Definition at line 38 of file arbport.c.

PORT_MAX_ADDRESS

#define PORT_MAX_ADDRESS   0xFFFF

Definition at line 39 of file arbport.c.

Function Documentation

IopArbPortAddAllocation()

static VOID NTAPI IopArbPortAddAllocation ( _In_ PARBITER_INSTANCE  Arbiter, _Inout_ PARBITER_ALLOCATION_STATE  ArbState  )

static

The Root Port arbiter's AddAllocation: records the granted range in the tentative allocation, and behind it every port range a partially-decoding ISA card would shadow.

Parameters

[in]	Arbiter	The Root Port arbiter instance.
[in,out]	ArbState	The allocation state carrying the granted Start and End. Alias ranges span the same width, belong to the same device, and are tagged ARBITER_RANGE_PORT_ALIAS.

Definition at line 455 of file arbport.c.

{
    PARBITER_ALTERNATIVE Alternative = ArbState->CurrentAlternative;
    PVOID Owner = ArbState->Entry ? ArbState->Entry->PhysicalDeviceObject : NULL;
    ULONG Flags = RTL_RANGE_LIST_ADD_IF_CONFLICT;
    UINT64 Alias;
    UINT64 Span;
 
    PAGED_CODE();
 
    if (Alternative != NULL && (Alternative->Flags & ARBITER_ALTERNATIVE_FLAG_SHARED))
        Flags |= RTL_RANGE_LIST_ADD_SHARED;
 
    RtlAddRange(Arbiter->PossibleAllocation,
                ArbState->Start,
                ArbState->End,
                ArbState->RangeAttributes,
                Flags,
                NULL,
                Owner);
 
    if (Alternative == NULL)
        return;
 
    /* Alias the width actually granted, not the width asked for. */
    Span = ArbState->End - ArbState->Start;
 
    Alias = ArbState->Start;
    while (IopArbPortGetNextAlias(Alternative->Descriptor->Flags, Alias, &Alias))
    {
        RtlAddRange(Arbiter->PossibleAllocation,
                    Alias,
                    Alias + Span,
                    ArbState->RangeAttributes | ARBITER_RANGE_PORT_ALIAS,
                    Flags,
                    NULL,
                    Owner);
    }
}

Referenced by IopArbPortInitialize().

IopArbPortBacktrackAllocation()

static VOID NTAPI IopArbPortBacktrackAllocation ( _In_ PARBITER_INSTANCE  Arbiter, _Inout_ PARBITER_ALLOCATION_STATE  ArbState  )

static

The Root Port arbiter's BacktrackAllocation: the exact inverse of IopArbPortAddAllocation.

Parameters

[in]	Arbiter	The Root Port arbiter instance.
[in,out]	ArbState	The allocation state whose placement is being withdrawn.

Remarks

The alias chain is regenerated and removed along with the granted range. Leaving the aliases behind would quietly wall off the port space for every placement the engine tries afterwards.

Definition at line 516 of file arbport.c.

{
    PARBITER_ALTERNATIVE Alternative = ArbState->CurrentAlternative;
    PVOID Owner = ArbState->Entry ? ArbState->Entry->PhysicalDeviceObject : NULL;
    UINT64 Alias;
    UINT64 Span;
 
    PAGED_CODE();
 
    if (Alternative != NULL)
    {
        Span = ArbState->End - ArbState->Start;
 
        Alias = ArbState->Start;
        while (IopArbPortGetNextAlias(Alternative->Descriptor->Flags, Alias, &Alias))
        {
            RtlDeleteRange(Arbiter->PossibleAllocation, Alias, Alias + Span, Owner);
        }
    }
 
    RtlDeleteRange(Arbiter->PossibleAllocation, ArbState->Start, ArbState->End, Owner);
}

Referenced by IopArbPortInitialize().

IopArbPortFindSuitableRange()

static BOOLEAN NTAPI IopArbPortFindSuitableRange ( _In_ PARBITER_INSTANCE  Arbiter, _Inout_ PARBITER_ALLOCATION_STATE  ArbState  )

static

The Root Port arbiter's FindSuitableRange: the engine search, incremented for a device asking to keep the ports the firmware already programmed it into.

Parameters

[in]	Arbiter	The Root Port arbiter instance.
[in,out]	ArbState	The allocation state of the requirement being placed.

Returns

Returns TRUE if a placement was found, FALSE otherwise.

Remarks

A boot configuration is held in the range list as an ARBITER_RANGE_BOOT_ALLOCATED range and so reads as occupied. A request carrying ARBITER_FLAG_BOOT_CONFIG is precisely the one asking for that space back, so those ranges are made available to it. The engine already extends the same courtesy to legacy request sources.

Definition at line 426 of file arbport.c.

{
    PAGED_CODE();
 
    if (ArbState->Entry != NULL && (ArbState->Entry->Flags & ARBITER_FLAG_BOOT_CONFIG))
        ArbState->RangeAvailableAttributes |= ARBITER_RANGE_BOOT_ALLOCATED;
 
    return ArbiterLibFindSuitableRange(Arbiter, ArbState);
}

Referenced by IopArbPortInitialize().

IopArbPortGetNextAlias()

static BOOLEAN IopArbPortGetNextAlias ( _In_ USHORT  DescriptorFlags, _In_ UINT64  LastAlias, _Out_ PUINT64  NextAlias  )

static

Walks the decode-alias chain of a port range: given the previous alias, or the granted range's start on the first call, produces the next one.

Parameters

[in]	DescriptorFlags	The requirement's flags. Only 10-bit and 12-bit decode requirements alias; a full 16-bit decoder owns exactly what it asked for.
[in]	LastAlias	The previous alias start, or the granted range's start.
[out]	NextAlias	Receives the next alias start.

Returns

Returns TRUE with the next alias, or FALSE once the card decodes fully or the next alias would leave I/O space.

Definition at line 134 of file arbport.c.

{
    UINT64 Next;
 
    PAGED_CODE();
 
    if (DescriptorFlags & CM_RESOURCE_PORT_10_BIT_DECODE)
        Next = LastAlias + PORT_ALIAS_STRIDE_10_BIT;
    else if (DescriptorFlags & CM_RESOURCE_PORT_12_BIT_DECODE)
        Next = LastAlias + PORT_ALIAS_STRIDE_12_BIT;
    else
        return FALSE;
 
    if (Next > PORT_MAX_ADDRESS)
        return FALSE;
 
    *NextAlias = Next;
    return TRUE;
}

Referenced by IopArbPortAddAllocation(), and IopArbPortBacktrackAllocation().

IopArbPortInitialize()

NTSTATUS NTAPI IopArbPortInitialize

(

VOID

)

Initialize the RootPortArbiter.

The root port arbiter owns the 16-bit x86 I/O port space and hands out sub-ranges of it. It is the fallback for every device whose ports no closer arbiter claims: root-enumerated and HAL-reported legacy hardware above all, which is also the hardware that partially decodes its address lines and so needs the aliasing this arbiter adds.

Returns

NTSTATUS

Return values

STATUS_SUCCESS
STATUS_UNSUCCESSFUL
STATUS_INSUFFICIENT_RESOURCES

Definition at line 557 of file arbport.c.

{
    NTSTATUS Status;
 
    PAGED_CODE();
 
    IopRootPortArbiter.Name = L"RootPort";
    IopRootPortArbiter.UnpackRequirement = IopArbPortUnpackRequirements;
    IopRootPortArbiter.PackResource = IopArbPortPackResource;
    IopRootPortArbiter.UnpackResource = IopArbPortUnpackResource;
    IopRootPortArbiter.ScoreRequirement = IopArbPortScoreRequirement;
 
    /* Port-specific placement: boot-config leniency and ISA decode aliasing. */
    IopRootPortArbiter.FindSuitableRange = IopArbPortFindSuitableRange;
    IopRootPortArbiter.AddAllocation = IopArbPortAddAllocation;
    IopRootPortArbiter.BacktrackAllocation = IopArbPortBacktrackAllocation;
 
    Status = ArbiterLibInitializeInstance(&IopRootPortArbiter,
                                          NULL,
                                          CmResourceTypePort,
                                          IopRootPortArbiter.Name,
                                          L"Root",
                                          IopArbPortTranslateOrdering);
    if (!NT_SUCCESS(Status))
    {
        DPRINT1("IopArbPortInitialize: Failed with %X\n", Status);
    }
 
    return Status;
}

Referenced by IopInitializeArbiters().

IopArbPortPackResource()

static NTSTATUS NTAPI IopArbPortPackResource ( _In_ PIO_RESOURCE_DESCRIPTOR  IoDescriptor, _In_ UINT64  Start, _Out_ PCM_PARTIAL_RESOURCE_DESCRIPTOR  CmDescriptor  )

static

Materialises the arbiter's chosen placement as an assigned CM descriptor. The PackResource callback of the Root Port arbiter.

Parameters

[in]	IoDescriptor	The requirement the placement satisfies. Type, Flags and ShareDisposition come across unchanged, and so does the Length, still in the encoding its Flags describe.
[in]	Start	The port address the arbiter settled on.
[out]	CmDescriptor	Receives the assigned descriptor.

Returns

Returns STATUS_SUCCESS.

Definition at line 227 of file arbport.c.

{
    PAGED_CODE();
 
    CmDescriptor->Type = IoDescriptor->Type;
    CmDescriptor->Flags = IoDescriptor->Flags;
    CmDescriptor->ShareDisposition = IoDescriptor->ShareDisposition;
 
    CmDescriptor->u.Generic.Start.QuadPart = Start;
    CmDescriptor->u.Generic.Length = IoDescriptor->u.Generic.Length;
 
    return STATUS_SUCCESS;
}

Referenced by IopArbPortInitialize().

IopArbPortScoreRequirement()

static INT32 NTAPI IopArbPortScoreRequirement ( _In_ PIO_RESOURCE_DESCRIPTOR  IoDescriptor )

static

Scores how constrained a requirement is: the number of distinct aligned addresses it could be placed at inside its own window, ignoring what is already allocated. The ScoreRequirement callback of the Root Port arbiter.

Parameters

[in]

IoDescriptor

The requirement to score.

Returns

Returns the placement count, saturated to MAXLONG, or -1 for a window that cannot hold the requirement at all - which the engine treats as a bad configuration and fails the arbitration on.

Remarks

The engine places the most constrained device (the lowest score) first, so the devices with real freedom of movement are left to absorb whatever space is still available.

Definition at line 302 of file arbport.c.

{
    UINT64 Length, Alignment;
    UINT64 Minimum, Maximum, AlignedMinimum;
    UINT64 Span, Placements;
 
    PAGED_CODE();
 
    Length = RtlIoDecodeMemIoResource(IoDescriptor, &Alignment, &Minimum, &Maximum);
 
    if (Alignment == 0)
        Alignment = 1;
 
    /* Round the window's base up to the first address the device can sit at. */
    AlignedMinimum = (Minimum + Alignment - 1) & ~(Alignment - 1);
    if (AlignedMinimum < Minimum || AlignedMinimum > Maximum)
        return -1;
 
    /* Count in addresses above the base, so a full-width window cannot overflow. */
    Span = Maximum - AlignedMinimum;
 
    if (Length != 0)
    {
        if (Length - 1 > Span)
            return -1;
 
        Span -= Length - 1;
    }
 
    Placements = Span / Alignment + 1;
    return (INT32)min(Placements, MAXLONG);
}

Referenced by IopArbPortInitialize().

IopArbPortTranslateAddress()

static NTSTATUS IopArbPortTranslateAddress ( _In_ UCHAR  SourceType, _In_ PHYSICAL_ADDRESS  SourceAddress, _Out_ PPHYSICAL_ADDRESS  TranslatedAddress, _Out_ PUCHAR  TranslatedType  )

static

Translates one bus-relative address to a system-physical one on the ISA bus, and reports the space it landed in as a CM resource type.

Parameters

[in]	SourceType	The CM resource type of the address being translated.
[in]	SourceAddress	The bus-relative address.
[out]	TranslatedAddress	Receives the system-physical address.
[out]	TranslatedType	Receives the post-translation resource type. A HAL may map one space onto another (memory-mapped I/O ports being the usual case) so the type is taken from the space the translation actually returned rather than assumed, e.g IOPorts, MMIO, etc.

Returns

Returns STATUS_SUCCESS, STATUS_INVALID_PARAMETER for a resource type that carries no address or for an address space the HAL is not expected to report, or STATUS_UNSUCCESSFUL when the HAL declines the translation.

Definition at line 72 of file arbport.c.

{
    ULONG AddressSpace;
 
    PAGED_CODE();
 
    if (SourceType == CmResourceTypePort)
        AddressSpace = 1; /* I/O port space */
    else if (SourceType == CmResourceTypeMemory || SourceType == CmResourceTypeMemoryLarge)
        AddressSpace = 0; /* System memory */
    else
        return STATUS_INVALID_PARAMETER;
 
    if (!HalTranslateBusAddress(Isa, 0, SourceAddress, &AddressSpace, TranslatedAddress))
        return STATUS_UNSUCCESSFUL;
 
    /* The HAL reports back the space it landed in; only these two are expected. */
    if (AddressSpace == 1)
    {
        *TranslatedType = CmResourceTypePort;
    }
    else if (AddressSpace == 0)
    {
        *TranslatedType = (SourceType == CmResourceTypeMemoryLarge)
                          ? CmResourceTypeMemoryLarge
                          : CmResourceTypeMemory;
    }
    else
    {
        return STATUS_INVALID_PARAMETER;
    }
 
    return STATUS_SUCCESS;
}

Referenced by IopArbPortTranslateOrdering().

IopArbPortTranslateOrdering()

static NTSTATUS NTAPI IopArbPortTranslateOrdering ( _Out_ PIO_RESOURCE_DESCRIPTOR  OutIoDescriptor, _In_ PIO_RESOURCE_DESCRIPTOR  IoDescriptor  )

static

Translates one registry allocation-ordering window from the bus-relative addresses it is written in into the system-physical space the arbiter allocates in. The TranslateOrdering function of the Root Port arbiter.

Parameters

[out]	OutIoDescriptor	Receives the translated copy. An entry whose endpoints cannot both be translated is marked CmResourceTypeNull for the ordering reader to drop; otherwise it takes the translated type.
[in]	IoDescriptor	The ordering window. A descriptor that carries no address passes through untouched.

Returns

Returns STATUS_SUCCESS.

Definition at line 358 of file arbport.c.

{
    UCHAR SourceType;
    UCHAR MinimumType;
    UCHAR MaximumType;
 
    PAGED_CODE();
 
    *OutIoDescriptor = *IoDescriptor;
 
    SourceType = IoDescriptor->Type;
    if (SourceType != CmResourceTypePort &&
        SourceType != CmResourceTypeMemory &&
        SourceType != CmResourceTypeMemoryLarge)
    {
        return STATUS_SUCCESS;
    }
 
    MinimumType = SourceType;
    MaximumType = SourceType;
 
    if (!NT_SUCCESS(IopArbPortTranslateAddress(SourceType,
                                               IoDescriptor->u.Generic.MinimumAddress,
                                               &OutIoDescriptor->u.Generic.MinimumAddress,
                                               &MinimumType)) ||
        !NT_SUCCESS(IopArbPortTranslateAddress(SourceType,
                                               IoDescriptor->u.Generic.MaximumAddress,
                                               &OutIoDescriptor->u.Generic.MaximumAddress,
                                               &MaximumType)))
    {
        OutIoDescriptor->Type = CmResourceTypeNull;
    }
    else
    {
        OutIoDescriptor->Type = MaximumType;
    }
 
    return STATUS_SUCCESS;
}

Referenced by IopArbPortInitialize().

IopArbPortUnpackRequirements()

static NTSTATUS NTAPI IopArbPortUnpackRequirements ( _In_ PIO_RESOURCE_DESCRIPTOR  IoDescriptor, _Out_ PUINT64  OutMinimumAddress, _Out_ PUINT64  OutMaximumAddress, _Out_ PUINT64  OutLength, _Out_ PUINT64  OutAlignment  )

static

Extracts the placement window from one I/O port requirement. The UnpackRequirement callback of the Root Port arbiter.

Parameters

[in]	IoDescriptor	The requirement to decode.
[out]	OutMinimumAddress	Receives the lowest port address the requirement accepts.
[out]	OutMaximumAddress	Receives the highest port address the requirement accepts.
[out]	OutLength	Receives the number of consecutive ports wanted.
[out]	OutAlignment	Receives the requirement's alignment; a zero alignment means the device does not care and is normalized to byte alignment, since the placement arithmetic divides by it.

Returns

Returns STATUS_SUCCESS.

Definition at line 185 of file arbport.c.

{
    PAGED_CODE();
 
    *OutLength = RtlIoDecodeMemIoResource(IoDescriptor,
                                          OutAlignment,
                                          OutMinimumAddress,
                                          OutMaximumAddress);
 
    if (*OutAlignment == 0)
        *OutAlignment = 1;
 
    return STATUS_SUCCESS;
}

Referenced by IopArbPortInitialize().

IopArbPortUnpackResource()

static NTSTATUS NTAPI IopArbPortUnpackResource ( _In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR  CmDescriptor, _Out_ PUINT64  Start, _Out_ PUINT64  OutLength  )

static

Reads the placement back out of an already-assigned descriptor (a firmware boot configuration, typically) so the arbiter can mark that span occupied. The inverse of IopArbPortPackResource and the UnpackResource callback of the Root Port arbiter.

Parameters

[in]	CmDescriptor	The assigned descriptor to decode.
[out]	Start	Receives the assigned port address.
[out]	OutLength	Receives the assigned length.

Returns

Returns STATUS_SUCCESS.

Definition at line 266 of file arbport.c.

{
    PAGED_CODE();
 
    *OutLength = RtlCmDecodeMemIoResource(CmDescriptor, Start);
 
    return STATUS_SUCCESS;
}

Referenced by IopArbPortInitialize().

RtlCmDecodeMemIoResource()

ULONGLONG NTAPI RtlCmDecodeMemIoResource	(	_In_ PCM_PARTIAL_RESOURCE_DESCRIPTOR	Descriptor,
		_Out_opt_ PULONGLONG	Start
	)

Definition at line 58 of file memres.c.

{
    if (Start != NULL)
        *Start = Descriptor->u.Generic.Start.QuadPart;
 
    return RtlpDecodeMemIoValue(Descriptor->Type,
                                Descriptor->Flags,
                                Descriptor->u.Generic.Length);
}

Referenced by IopArbPortUnpackResource().

RtlIoDecodeMemIoResource()

ULONGLONG NTAPI RtlIoDecodeMemIoResource	(	_In_ PIO_RESOURCE_DESCRIPTOR	Descriptor,
		_Out_opt_ PULONGLONG	Alignment,
		_Out_opt_ PULONGLONG	MinimumAddress,
		_Out_opt_ PULONGLONG	MaximumAddress
	)

Definition at line 79 of file memres.c.

{
    if (Alignment != NULL)
    {
        *Alignment = RtlpDecodeMemIoValue(Descriptor->Type,
                                          Descriptor->Flags,
                                          Descriptor->u.Generic.Alignment);
    }
 
    if (MinimumAddress != NULL)
        *MinimumAddress = Descriptor->u.Generic.MinimumAddress.QuadPart;
 
    if (MaximumAddress != NULL)
        *MaximumAddress = Descriptor->u.Generic.MaximumAddress.QuadPart;
 
    return RtlpDecodeMemIoValue(Descriptor->Type,
                                Descriptor->Flags,
                                Descriptor->u.Generic.Length);
}

Referenced by IopArbPortScoreRequirement(), and IopArbPortUnpackRequirements().

Variable Documentation

IopRootPortArbiter

ARBITER_INSTANCE IopRootPortArbiter

extern

Definition at line 27 of file pnpinit.c.

Referenced by IopArbPortInitialize().