#include <fxpowerpolicystatemachine.hpp>

Collaboration diagram for IdleTimeoutManagement:

[legend]

Public Member Functions
	IdleTimeoutManagement (VOID)

	~IdleTimeoutManagement (VOID)

NTSTATUS	UseSystemManagedIdleTimeout (__in PFX_DRIVER_GLOBALS DriverGlobals)

VOID	FreezeIdleTimeoutManagementStatus (__in PFX_DRIVER_GLOBALS DriverGlobals)

BOOLEAN	UsingSystemManagedIdleTimeout (VOID)

NTSTATUS	CommitPowerFrameworkSettings (__in PFX_DRIVER_GLOBALS DriverGlobals, __in PPOX_SETTINGS PoxSettings)

BOOLEAN	DriverSpecifiedPowerFrameworkSettings (VOID)

PPOX_SETTINGS	GetPowerFrameworkSettings (VOID)

Static Public Member Functions
static BOOLEAN	_SystemManagedIdleTimeoutAvailable (VOID)

Private Types
enum	IdleTimeoutStatusFlag { IdleTimeoutStatusFrozen = 0x00000001 , IdleTimeoutSystemManaged = 0x00000002 , IdleTimeoutPoxSettingsSpecified = 0x00000004 }

enum	IdleTimeoutStatusUpdateResult { IdleTimeoutStatusFlagsUpdated , IdleTimeoutStatusFlagAlreadySet , IdleTimeoutStatusFlagsAlreadyFrozen , IdleTimeoutStatusFlagsUnexpected }

Private Member Functions
IdleTimeoutStatusUpdateResult	UpdateIdleTimeoutStatus (__in IdleTimeoutStatusFlag Flag)

CfxDevice *	GetDevice (VOID)

Private Attributes
LONG volatile	m_IdleTimeoutStatus

PPOX_SETTINGS	m_PoxSettings

Detailed Description

Definition at line 306 of file fxpowerpolicystatemachine.hpp.

Member Enumeration Documentation

◆ IdleTimeoutStatusFlag

enum IdleTimeoutManagement::IdleTimeoutStatusFlag

private

Enumerator
IdleTimeoutStatusFrozen
IdleTimeoutSystemManaged
IdleTimeoutPoxSettingsSpecified

Definition at line 335 of file fxpowerpolicystatemachine.hpp.

                               {
        IdleTimeoutStatusFrozen         = 0x00000001,
        IdleTimeoutSystemManaged        = 0x00000002,
        IdleTimeoutPoxSettingsSpecified = 0x00000004,
    };

◆ IdleTimeoutStatusUpdateResult

enum IdleTimeoutManagement::IdleTimeoutStatusUpdateResult

private

Enumerator
IdleTimeoutStatusFlagsUpdated
IdleTimeoutStatusFlagAlreadySet
IdleTimeoutStatusFlagsAlreadyFrozen
IdleTimeoutStatusFlagsUnexpected

Definition at line 344 of file fxpowerpolicystatemachine.hpp.

                                       {
        //
        // Flags were sucessfully updated
        //
        IdleTimeoutStatusFlagsUpdated,
 
        //
        // The flag we were trying to set was already set
        //
        IdleTimeoutStatusFlagAlreadySet,
 
        //
        // It is too late to set the flag. The flags have already been frozen.
        // Flags are frozen the first time a device is started.
        //
        IdleTimeoutStatusFlagsAlreadyFrozen,
 
        //
        // Flags are being set by multiple threads in parallel. This is not
        // supported.
        //
        IdleTimeoutStatusFlagsUnexpected
    };

Constructor & Destructor Documentation

◆ IdleTimeoutManagement()

IdleTimeoutManagement::IdleTimeoutManagement ( VOID )

inline

Definition at line 386 of file fxpowerpolicystatemachine.hpp.

          : m_IdleTimeoutStatus(0),
            m_PoxSettings(NULL)
    {
    }

◆ ~IdleTimeoutManagement()

IdleTimeoutManagement::~IdleTimeoutManagement ( VOID )

inline

Definition at line 393 of file fxpowerpolicystatemachine.hpp.

    {
        BYTE * buffer = NULL;
        ULONG poxSettingsOffset;
 
        if (NULL != m_PoxSettings) {
 
            buffer = (BYTE*) m_PoxSettings;
 
            //
            // In the function FxPkgPnp::AssignPowerFrameworkSettings, we had
            // allocated a buffer which we need to free now. Note that
            // m_PoxSettings does not necessarily point to the beginning of the
            // buffer. It points to the POX_SETTINGS structure in the buffer,
            // which may or may not be in the beginning. If it is not in the
            // beginning, figure out where the beginning of the buffer is.
            //
            if (m_PoxSettings->Component != NULL) {
                //
                // The computation below won't overflow because we already
                // performed this computation successfully using safeint
                // functions in FxPkgPnp::AssignPowerFrameworkSettings.
                //
                poxSettingsOffset =
                        (sizeof(*(m_PoxSettings->Component->IdleStates)) *
                                (m_PoxSettings->Component->IdleStateCount)) +
                        (sizeof(*(m_PoxSettings->Component)));
            }
            else {
                poxSettingsOffset = 0;
            }
 
            //
            // Move to the beginning of the buffer
            //
            buffer = buffer - poxSettingsOffset;
 
            //
            // Free the buffer
            //
            MxMemory::MxFreePool(buffer);
        }
    }

Member Function Documentation

◆ _SystemManagedIdleTimeoutAvailable()

BOOLEAN IdleTimeoutManagement::_SystemManagedIdleTimeoutAvailable ( VOID )

static

Definition at line 209 of file supportkm.cpp.

{
    return (NULL != FxLibraryGlobals.PoxRegisterDevice);
}

Referenced by CommitPowerFrameworkSettings(), FreezeIdleTimeoutManagementStatus(), FxPkgPnp::PowerPolicySetS0IdleSettings(), and UseSystemManagedIdleTimeout().

◆ CommitPowerFrameworkSettings()

NTSTATUS IdleTimeoutManagement::CommitPowerFrameworkSettings	(	__in PFX_DRIVER_GLOBALS	DriverGlobals,
		__in PPOX_SETTINGS	PoxSettings
	)

Definition at line 2379 of file powerpolicystatemachine.cpp.

{
    NTSTATUS status;
    IdleTimeoutStatusUpdateResult statusUpdateResult;
    PVOID oldPoxSettings = NULL;
    BOOLEAN settingsSuccessfullySaved = FALSE;
    CfxDevice * device;
 
    //
    // We should never get here if system-managed idle timeout is not available
    //
    ASSERT(_SystemManagedIdleTimeoutAvailable());
 
    //
    // Get the device object so we can use it for logging
    //
    device = GetDevice();
 
    //
    // Try to save the driver's power framework settings
    //
    oldPoxSettings = InterlockedCompareExchangePointer((PVOID*) &m_PoxSettings,
                                                       PoxSettings,
                                                       NULL // Comparand
                                                       );
    if (NULL != oldPoxSettings) {
        //
        // The driver's power framework settings have already been specified
        // earlier. The driver should not be attempting to specify them more
        // than once.
        //
        status = STATUS_INVALID_DEVICE_REQUEST;
        DoTraceLevelMessage(
            DriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
            "WDFDEVICE %p !devobj %p The driver attempted to specify power "
            "framework settings more than once. %!STATUS!.",
            device->GetHandle(),
            device->GetDeviceObject(),
            status
            );
        FxVerifierDbgBreakPoint(DriverGlobals);
        goto exit;
    }
    settingsSuccessfullySaved = TRUE;
 
    //
    // Try to update the flag that indicates that the client driver has
    // specified settings that are to be used when we register with the power
    // framework.
    //
    statusUpdateResult = UpdateIdleTimeoutStatus(
                                IdleTimeoutPoxSettingsSpecified
                                );
    switch (statusUpdateResult) {
        case IdleTimeoutStatusFlagsAlreadyFrozen:
        {
            //
            // Status is already frozen. Too late to update it.
            //
            status = STATUS_INVALID_DEVICE_REQUEST;
            DoTraceLevelMessage(
                DriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                "WDFDEVICE %p !devobj %p Power framework settings must be "
                "specified before the first start IRP is completed. %!STATUS!.",
                device->GetHandle(),
                device->GetDeviceObject(),
                status
                );
            FxVerifierDbgBreakPoint(DriverGlobals);
            goto exit;
        }
        break;
 
        case IdleTimeoutStatusFlagsUnexpected:
        {
            //
            // Status being updated from multiple threads in parallel. Not
            // supported.
            //
            status = STATUS_INVALID_DEVICE_REQUEST;
            DoTraceLevelMessage(
                DriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                "WDFDEVICE %p !devobj %p Calls to assign S0-idle settings and "
                "to specify power framework settings are happening in parallel."
                " The driver needs to serialize these calls with respect to "
                "each other. %!STATUS!.",
                device->GetHandle(),
                device->GetDeviceObject(),
                status
                );
            FxVerifierDbgBreakPoint(DriverGlobals);
            goto exit;
        }
        break;
 
        case IdleTimeoutStatusFlagAlreadySet:
        {
            //
            // Status flag was already set. This should never happen for the
            // IdleTimeoutPoxSettingsSpecified flag because we have logic in the
            // beginning of this function to ensure that only the first caller
            // attempts to set this flag.
            //
            ASSERTMSG(
                "Attempt to set the IdleTimeoutPoxSettingsSpecified flag more "
                "than once\n", FALSE);
            status = STATUS_INTERNAL_ERROR;
            goto exit;
        }
 
        case IdleTimeoutStatusFlagsUpdated:
        {
            status = STATUS_SUCCESS;
        }
        break;
 
        default:
        {
            ASSERTMSG("Unexpected IdleTimeoutStatusUpdateResult value\n",
                      FALSE);
            status = STATUS_INTERNAL_ERROR;
            goto exit;
        }
    }
 
    //
    // If we get here, we must have a successful status
    //
    ASSERT(STATUS_SUCCESS == status);
 
exit:
    if (FALSE == NT_SUCCESS(status)) {
        if (settingsSuccessfullySaved) {
            //
            // Since a failure has occurred, we must reset the pointer to the
            // power framework settings.
            //
            m_PoxSettings = NULL;
        }
    }
    return status;
}

◆ DriverSpecifiedPowerFrameworkSettings()

BOOLEAN IdleTimeoutManagement::DriverSpecifiedPowerFrameworkSettings ( VOID )

Definition at line 2371 of file powerpolicystatemachine.cpp.

{
    return (0 != (m_IdleTimeoutStatus & IdleTimeoutPoxSettingsSpecified));
}

◆ FreezeIdleTimeoutManagementStatus()

VOID IdleTimeoutManagement::FreezeIdleTimeoutManagementStatus ( __in PFX_DRIVER_GLOBALS DriverGlobals )

Definition at line 2290 of file powerpolicystatemachine.cpp.

{
    LONG idleTimeoutSnapshot;
    LONG idleTimeoutStatus;
    LONG idleTimeoutPreviousStatus;
    CfxDevice * device;
 
    //
    // Get the device object so we can use it for logging
    //
    device = GetDevice();
 
    //
    // Take a snapshot of the idle timeout management status
    //
    idleTimeoutSnapshot = m_IdleTimeoutStatus;
 
    //
    // Set the bit that freezes the status
    //
    idleTimeoutStatus = idleTimeoutSnapshot | IdleTimeoutStatusFrozen;
 
    //
    // Update the status
    //
    idleTimeoutPreviousStatus = InterlockedExchange(&m_IdleTimeoutStatus,
                                                    idleTimeoutStatus);
 
    if (idleTimeoutPreviousStatus != idleTimeoutSnapshot) {
        //
        // An update of idle timeout status is racing with the freezing of idle
        // timeout status
        //
        DoTraceLevelMessage(
            DriverGlobals, TRACE_LEVEL_WARNING, TRACINGPNP,
            "WDFDEVICE %p !devobj %p The driver's S0-idle settings and/or power"
            " framework settings did not take effect because they were supplied"
            " too late. The driver must ensure that the settings are provided "
            "before the first start IRP is completed.",
            device->GetHandle(),
            device->GetDeviceObject()
            );
        FxVerifierDbgBreakPoint(DriverGlobals);
    }
 
    //
    // If the driver has specified power framework settings and system managed
    // idle timeout is available on this OS, then the driver must have opted for
    // system managed idle timeout.
    //
    if ((0 != (idleTimeoutStatus & IdleTimeoutPoxSettingsSpecified)) &&
        (_SystemManagedIdleTimeoutAvailable()) &&
        (0 == (idleTimeoutStatus & IdleTimeoutSystemManaged))) {
        DoTraceLevelMessage(
            DriverGlobals, TRACE_LEVEL_WARNING, TRACINGPNP,
            "WDFDEVICE %p !devobj %p The driver specified power framework "
            "settings, but did not opt for system-managed idle timeout.",
            device->GetHandle(),
            device->GetDeviceObject()
            );
        FxVerifierDbgBreakPoint(DriverGlobals);
    }
}

◆ GetDevice()

CfxDevice * IdleTimeoutManagement::GetDevice ( VOID )

private

Definition at line 2087 of file powerpolicystatemachine.cpp.

{
    IdlePolicySettings * idlePolicySettings = NULL;
    FxPowerPolicyOwnerSettings * ppoSettings = NULL;
    FxPkgPnp * pPkgPnp = NULL;
 
    idlePolicySettings = (IdlePolicySettings *) CONTAINING_RECORD(
                                                            this,
                                                            IdlePolicySettings,
                                                            m_TimeoutMgmt
                                                            );
    ppoSettings = (FxPowerPolicyOwnerSettings *) CONTAINING_RECORD(
                                                    idlePolicySettings,
                                                    FxPowerPolicyOwnerSettings,
                                                    m_IdleSettings
                                                    );
    pPkgPnp = ppoSettings->m_PkgPnp;
 
    return pPkgPnp->GetDevice();
}

◆ GetPowerFrameworkSettings()

PPOX_SETTINGS IdleTimeoutManagement::GetPowerFrameworkSettings ( VOID )

inline

Definition at line 472 of file fxpowerpolicystatemachine.hpp.

    {
        return m_PoxSettings;
    }

◆ UpdateIdleTimeoutStatus()

IdleTimeoutManagement::IdleTimeoutStatusUpdateResult IdleTimeoutManagement::UpdateIdleTimeoutStatus ( __in IdleTimeoutStatusFlag Flag )

private

Definition at line 2111 of file powerpolicystatemachine.cpp.

{
    LONG idleTimeoutStatusSnapshot;
    LONG updatedIdleTimeoutStatus;
    LONG preInterlockedIdleTimeoutStatus;
 
    //
    // Take a snapshot of the idle timeout management status
    //
    idleTimeoutStatusSnapshot = m_IdleTimeoutStatus;
 
    //
    // Verify that the flag we're trying to set is not already set
    //
    if (0 != (idleTimeoutStatusSnapshot & Flag)) {
        return IdleTimeoutStatusFlagAlreadySet;
    }
 
    //
    // Verify that the idle timeout management status is not already
    // "frozen"
    //
    if (0 != (idleTimeoutStatusSnapshot & IdleTimeoutStatusFrozen)) {
        //
        // It was too late to set the flag. The flag value was already
        // "frozen".
        //
        return IdleTimeoutStatusFlagsAlreadyFrozen;
    }
 
    //
    // Try to set the flag
    //
    updatedIdleTimeoutStatus = idleTimeoutStatusSnapshot | Flag;
 
    preInterlockedIdleTimeoutStatus = InterlockedCompareExchange(
                                                &m_IdleTimeoutStatus,
                                                updatedIdleTimeoutStatus,
                                                idleTimeoutStatusSnapshot
                                                );
    if (preInterlockedIdleTimeoutStatus != idleTimeoutStatusSnapshot) {
 
        if (0 != (preInterlockedIdleTimeoutStatus &
                                IdleTimeoutStatusFrozen)) {
            //
            // It was too late to set the flag. The flag value was already
            // "frozen".
            //
            return IdleTimeoutStatusFlagsAlreadyFrozen;
        }
        else {
            //
            // Idle timeout management status is being changed by multiple
            // threads in parallel. This is not supported.
            //
            return IdleTimeoutStatusFlagsUnexpected;
        }
    }
 
    //
    // We have successfully set the flag
    //
    return IdleTimeoutStatusFlagsUpdated;
}

Referenced by CommitPowerFrameworkSettings(), and UseSystemManagedIdleTimeout().

◆ UseSystemManagedIdleTimeout()

NTSTATUS IdleTimeoutManagement::UseSystemManagedIdleTimeout ( __in PFX_DRIVER_GLOBALS DriverGlobals )

Definition at line 2179 of file powerpolicystatemachine.cpp.

{
    NTSTATUS status;
    IdleTimeoutStatusUpdateResult statusUpdateResult;
    CfxDevice * device;
 
    //
    // First check if we are running on Windows 8 or above
    //
    if (_SystemManagedIdleTimeoutAvailable()) {
 
        //
        // Get the device object so we can use it for logging
        //
        device = GetDevice();
 
        //
        // Try to update the flag that specifies that the power framework should
        // determine the idle timeout.
        //
        statusUpdateResult = UpdateIdleTimeoutStatus(IdleTimeoutSystemManaged);
 
        switch (statusUpdateResult) {
            case IdleTimeoutStatusFlagsAlreadyFrozen:
            {
                //
                // Status is already frozen. Too late to update it.
                //
                status = STATUS_INVALID_DEVICE_REQUEST;
                DoTraceLevelMessage(
                    DriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "WDFDEVICE %p !devobj %p If the power framework is made "
                    "responsible for determining the idle timeout, then the "
                    "first call to assign S0-idle policy must occur before the "
                    "first start IRP is completed. However, in this case, it "
                    "occurred after the first start IRP was completed. "
                    "%!STATUS!.",
                    device->GetHandle(),
                    device->GetDeviceObject(),
                    status
                    );
                FxVerifierDbgBreakPoint(DriverGlobals);
            }
            break;
 
            case IdleTimeoutStatusFlagsUnexpected:
            {
                //
                // Status being updated from multiple threads in parallel. Not
                // supported.
                //
                status = STATUS_INVALID_DEVICE_REQUEST;
                DoTraceLevelMessage(
                    DriverGlobals, TRACE_LEVEL_ERROR, TRACINGPNP,
                    "WDFDEVICE %p !devobj %p Calls to assign S0-idle settings "
                    "and to specify power framework settings are happening in "
                    "parallel. The driver needs to serialize these calls with "
                    "respect to each other. %!STATUS!.",
                    device->GetHandle(),
                    device->GetDeviceObject(),
                    status
                    );
                FxVerifierDbgBreakPoint(DriverGlobals);
            }
            break;
 
            case IdleTimeoutStatusFlagAlreadySet:
            {
                //
                // Status flag was already set. This should never happen for the
                // IdleTimeoutSystemManaged flag. The caller ensures this.
                //
                ASSERTMSG(
                    "IdleTimeoutManagement::UseSystemManagedIdleTimeout was "
                    "called more than once\n", FALSE);
            }
 
            //
            //     Fall through
            //
            //      ||  ||  ||
            //      \/  \/  \/
            //
            case IdleTimeoutStatusFlagsUpdated:
            {
                status = STATUS_SUCCESS;
            }
            break;
 
            default:
            {
                ASSERTMSG("Unexpected IdleTimeoutStatusUpdateResult value\n",
                          FALSE);
                status = STATUS_INTERNAL_ERROR;
            }
        }
 
    } else {
        //
        // If we're not running on Windows 8 or above, then there is nothing to
        // do.
        //
        status = STATUS_SUCCESS;
    }
 
    return status;
}

◆ UsingSystemManagedIdleTimeout()

BOOLEAN IdleTimeoutManagement::UsingSystemManagedIdleTimeout ( VOID )

Definition at line 2357 of file powerpolicystatemachine.cpp.

{
    //
    // If the value of this constant is changed, the debugger extension needs
    // to be fixed as well.
    //
    C_ASSERT(0x2 == IdleTimeoutSystemManaged);
 
    return (0 != (m_IdleTimeoutStatus & IdleTimeoutSystemManaged));
}

Referenced by FxPkgPnp::IsS0IdleSystemManaged().

Member Data Documentation

◆ m_IdleTimeoutStatus

LONG volatile IdleTimeoutManagement::m_IdleTimeoutStatus

private

Definition at line 314 of file fxpowerpolicystatemachine.hpp.

Referenced by DriverSpecifiedPowerFrameworkSettings(), FreezeIdleTimeoutManagementStatus(), UpdateIdleTimeoutStatus(), and UsingSystemManagedIdleTimeout().

◆ m_PoxSettings

PPOX_SETTINGS IdleTimeoutManagement::m_PoxSettings

private

Definition at line 372 of file fxpowerpolicystatemachine.hpp.

Referenced by CommitPowerFrameworkSettings(), GetPowerFrameworkSettings(), and ~IdleTimeoutManagement().

The documentation for this class was generated from the following files:

sdk/lib/drivers/wdf/shared/inc/private/common/fxpowerpolicystatemachine.hpp
sdk/lib/drivers/wdf/shared/irphandlers/pnp/km/supportkm.cpp
sdk/lib/drivers/wdf/shared/irphandlers/pnp/powerpolicystatemachine.cpp
sdk/lib/drivers/wdf/shared/irphandlers/pnp/um/supportum.cpp

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ IdleTimeoutStatusFlag

◆ IdleTimeoutStatusUpdateResult

Constructor & Destructor Documentation

◆ IdleTimeoutManagement()

◆ ~IdleTimeoutManagement()

Member Function Documentation

◆ _SystemManagedIdleTimeoutAvailable()

◆ CommitPowerFrameworkSettings()

◆ DriverSpecifiedPowerFrameworkSettings()

◆ FreezeIdleTimeoutManagementStatus()

◆ GetDevice()

◆ GetPowerFrameworkSettings()

◆ UpdateIdleTimeoutStatus()

◆ UseSystemManagedIdleTimeout()

◆ UsingSystemManagedIdleTimeout()

Member Data Documentation

◆ m_IdleTimeoutStatus

◆ m_PoxSettings