/*++

Copyright (c) 1999  Microsoft Corporation

Module Name:

    usblspwr.c 

Abstract:

    USB LS-120 Mass Storage Device Sample Driver
    Power Management module


Environment:

    kernel mode only

Notes:

  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
  PURPOSE.

  Copyright (c) 1999 Microsoft Corporation.  All Rights Reserved.


Revision History:

    1/13/99: MRB	Adapted from the BULKUSB DDK sample.

--*/


#include "wdm.h"
#include "stdarg.h"
#include "stdio.h"

#include "usbdi.h"
#include "usbdlib.h"
#include "usbls120.h"


NTSTATUS
USBLS120_ProcessPowerIrp(
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP           Irp
    )
/*++

Routine Description:

    This is our FDO's dispatch table function for IRP_MJ_POWER.
    It processes the Power IRPs sent to the PDO for this device.

    For every power IRP, drivers must call PoStartNextPowerIrp and use PoCallDriver
    to pass the IRP all the way down the driver stack to the underlying PDO.


Arguments:

    DeviceObject - pointer to our device object (FDO)

    Irp          - pointer to an I/O Request Packet

Return Value:

    NT status code

--*/
{

    PIO_STACK_LOCATION irpStack;
    NTSTATUS ntStatus = STATUS_SUCCESS;
    PDEVICE_EXTENSION deviceExtension;
    BOOLEAN fGoingToD0 = FALSE;
    POWER_STATE sysPowerState, desiredDevicePowerState;
    KEVENT event;

    USBLS120_KdPrint( DBGLVL_DEFAULT,(" USBLS120_ProcessPowerIrp() IRP_MJ_POWER\n"));

    deviceExtension = (PDEVICE_EXTENSION) DeviceObject->DeviceExtension;
    irpStack = IoGetCurrentIrpStackLocation (Irp);
    USBLS120_IncrementIoCount(DeviceObject);

    switch (irpStack->MinorFunction) {

        case IRP_MN_WAIT_WAKE:

            USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Enter IRP_MN_WAIT_WAKE\n"));

            // A driver sends IRP_MN_WAIT_WAKE to indicate that the system should 
            // wait for its device to signal a wake event. The exact nature of the event
            // is device-dependent. 
            // Drivers send this IRP for two reasons: 
            // 1) To allow a device to wake the system
            // 2) To wake a device that has been put into a sleep state to save power
            //    but still must be able to communicate with its driver under certain circumstances. 
            // When a wake event occurs, the driver completes the IRP and returns 
            // STATUS_SUCCESS. If the device is sleeping when the event occurs, 
            // the driver must first wake up the device before completing the IRP. 
            // In a completion routine, the driver calls PoRequestPowerIrp to send a 
            // PowerDeviceD0 request. When the device has powered up, the driver can 
            //  handle the IRP_MN_WAIT_WAKE request.

            // deviceExtension->DeviceCapabilities.DeviceWake specifies the lowest device power state (least powered)
            // from which the device can signal a wake event 
            deviceExtension->PowerDownLevel = deviceExtension->DeviceCapabilities.DeviceWake;


            if  ( ( PowerDeviceD0 == deviceExtension->CurrentDevicePowerState )  ||
                  ( deviceExtension->DeviceCapabilities.DeviceWake > deviceExtension->CurrentDevicePowerState ) ) {
                //
                //    STATUS_INVALID_DEVICE_STATE is returned if the device in the PowerD0 state
                //    or a state below which it can support waking, or if the SystemWake state
                //    is below a state which can be supported. A pending IRP_MN_WAIT_WAKE will complete
                //    with this error if the device's state is changed to be incompatible with the wake 
                //    request.

                //  If a driver fails this IRP, it should complete the IRP immediately without
                //  passing the IRP to the next-lower driver.
                ntStatus = STATUS_INVALID_DEVICE_STATE;
                Irp->IoStatus.Status = ntStatus;
                IoCompleteRequest (Irp,IO_NO_INCREMENT );
                USBLS120_KdPrint( DBGLVL_HIGH, ( "Exit USBLS120_ProcessPowerIrp(), ntStatus STATUS_INVALID_DEVICE_STATE\n" ) );
                USBLS120_DecrementIoCount(DeviceObject);
                return ntStatus;
            }
       
            // flag we're enabled for wakeup
            deviceExtension->EnabledForWakeup = TRUE;

            // init an event for our completion routine to signal when PDO is done with this Irp
            KeInitializeEvent(&event, NotificationEvent, FALSE);

            // If not failing outright, pass this on to our PDO for further handling
            IoCopyCurrentIrpStackLocationToNext(Irp);

            // Set a completion routine so it can signal our event when
            //  the PDO is done with the Irp
            IoSetCompletionRoutine(
                Irp,
                USBLS120_IrpCompletionRoutine,
                &event,  // pass the event to the completion routine as the Context
                TRUE,    // invoke on success
                TRUE,    // invoke on error
                TRUE     // invoke on cancellation
                );

            PoStartNextPowerIrp(Irp);

            ntStatus = PoCallDriver(
                           deviceExtension->TopOfStackDeviceObject,
                           Irp
                           );

            // if PDO is not done yet, wait for the event to be set in our completion routine
            if (ntStatus == STATUS_PENDING) {

                // wait for irp to complete

                NTSTATUS waitStatus = KeWaitForSingleObject(
                                          &event,
                                          Suspended,
                                          KernelMode,
                                          FALSE,
                                          NULL
                                          );

                USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() done waiting for PDO to finish IRP_MN_WAIT_WAKE\n"));
            }

            // now tell the device to actually wake up
            USBLS120_SelfSuspendOrActivate( DeviceObject, FALSE );

            // flag we're done with wakeup irp
            deviceExtension->EnabledForWakeup = FALSE;

            USBLS120_DecrementIoCount(DeviceObject);
      
            USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Exit IRP_MN_WAIT_WAKE\n"));
            break;

    case IRP_MN_SET_POWER:
    {

        // The system power policy manager sends this IRP to set the system power state. 
        // A device power policy manager sends this IRP to set the device power state for a device.

        USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Enter IRP_MN_SET_POWER\n"));

        // Set Irp->IoStatus.Status to STATUS_SUCCESS to indicate that the device
        // has entered the requested state. Drivers cannot fail this IRP.

        switch (irpStack->Parameters.Power.Type) {
            case SystemPowerState:

                // Get input system power state
                sysPowerState.SystemState = irpStack->Parameters.Power.State.SystemState;

                USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Set Power, type SystemPowerState = %s\n",
                    USBLS120_StringForSysState( sysPowerState.SystemState ) ));

                // If system is in working state always set our device to D0
                //  regardless of the wait state or system-to-device state power map
                if ( sysPowerState.SystemState ==  PowerSystemWorking) {
                    desiredDevicePowerState.DeviceState = PowerDeviceD0;

                    USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() PowerSystemWorking, will set D0, not use state map\n"));
                } else {
                    // set to corresponding system state if IRP_MN_WAIT_WAKE pending
                    if ( deviceExtension->EnabledForWakeup ) { // got a WAIT_WAKE IRP pending?

                        // Find the device power state equivalent to the given system state.
                        // We get this info from the DEVICE_CAPABILITIES struct in our device
                        // extension (initialized in USBLS120_PnPAddDevice() )
                        desiredDevicePowerState.DeviceState =
                            deviceExtension->DeviceCapabilities.DeviceState[ sysPowerState.SystemState ];

                        USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() IRP_MN_WAIT_WAKE pending, will use state map\n"));
                    } else {  
                        // if no wait pending and the system's not in working state, just turn off
                        desiredDevicePowerState.DeviceState = PowerDeviceD3;

                        USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Not EnabledForWakeup and the system's not in working state,\n  settting PowerDeviceD3 (off )\n"));
                    }
                }

                //
                // We've determined the desired device state; are we already in this state?
                //

                USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Set Power, desiredDevicePowerState = %s\n",
                    USBLS120_StringForDevState( desiredDevicePowerState.DeviceState ) ));

                if (desiredDevicePowerState.DeviceState !=
                    deviceExtension->CurrentDevicePowerState) {

                    // USBLS120_IncrementIoCount(DeviceObject);

                    // No, request that we be put into this state
                    // by requesting a new Power Irp from the Pnp manager
                    deviceExtension->PowerIrp = Irp;
                    ntStatus = PoRequestPowerIrp(
                                   deviceExtension->PhysicalDeviceObject,
                                   IRP_MN_SET_POWER,
                                   desiredDevicePowerState,
                                   // completion routine will pass the Irp down to the PDO
                                   USBLS120_PoRequestCompletion, 
                                   DeviceObject,
                                   NULL
                                   );

                } else {
                    // Yes, just pass it on to PDO (Physical Device Object)
                    IoCopyCurrentIrpStackLocationToNext(Irp);

                    PoStartNextPowerIrp(Irp);

                    ntStatus = PoCallDriver(
                                   deviceExtension->TopOfStackDeviceObject,
                                   Irp
                                   );

                    USBLS120_DecrementIoCount(DeviceObject);
                    USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Exit IRP_MN_SET_POWER\n"));

                }
                break;


            case DevicePowerState:

                USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Set Power, type DevicePowerState = %s\n",
                    USBLS120_StringForDevState( irpStack->Parameters.Power.State.DeviceState ) ));

                // For requests to D1, D2, or D3 ( sleep or off states ),
                // sets deviceExtension->CurrentDevicePowerState to DeviceState immediately.
                // This enables any code checking state to consider us as sleeping or off
                // already, as this will imminently become our state.

                // For requests to DeviceState D0 ( fully on ), sets fGoingToD0 flag TRUE
                // to flag that we must set a completion routine and update
                // deviceExtension->CurrentDevicePowerState there.
                // In the case of powering up to fully on, we really want to make sure
                // the process is completed before updating our CurrentDevicePowerState,
                // so no IO will be attempted or accepted before we're really ready.

                fGoingToD0 = USBLS120_SetDevicePowerState(
                                 DeviceObject,
                                 irpStack->Parameters.Power.State.DeviceState
                                 ); // returns TRUE for D0

                IoCopyCurrentIrpStackLocationToNext(Irp);

                if (fGoingToD0) {
                    USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Set PowerIrp Completion Routine, fGoingToD0 =%d\n", fGoingToD0));
                    IoSetCompletionRoutine(
                        Irp,
                        USBLS120_PowerIrp_Complete,
                        // Always pass FDO to completion routine as its Context;
                        // This is because the DriverObject passed by the system to the routine
                        // is the Physical Device Object ( PDO ) not the Functional Device Object ( FDO )
                        DeviceObject,
                        TRUE,            // invoke on success
                        TRUE,            // invoke on error
                        TRUE             // invoke on cancellation of the Irp
                        );
                }

                PoStartNextPowerIrp(Irp);

                ntStatus = PoCallDriver(
                               deviceExtension->TopOfStackDeviceObject,
                               Irp
                               );

                if ( !fGoingToD0 ) // completion routine will decrement
                    USBLS120_DecrementIoCount(DeviceObject);

                USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() Exit IRP_MN_SET_POWER\n"));
                break;
            } /* case irpStack->Parameters.Power.Type */

        }
        break; /* IRP_MN_SET_POWER */


    case IRP_MN_QUERY_POWER:
        //
        // A power policy manager sends this IRP to determine whether it can change
        // the system or device power state, typically to go to sleep.
        //

        USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() IRP_MN_QUERY_POWER\n"));

        // We do nothing special here, just let the PDO handle it
        IoCopyCurrentIrpStackLocationToNext(Irp);
        PoStartNextPowerIrp(Irp);

        ntStatus = PoCallDriver(
                       deviceExtension->TopOfStackDeviceObject,
                       Irp
                       );

        USBLS120_DecrementIoCount(DeviceObject);

        break; /* IRP_MN_QUERY_POWER */


    default:
        USBLS120_KdPrint( DBGLVL_MEDIUM,("USBLS120_ProcessPowerIrp() UNKNOWN POWER MESSAGE (%x)\n", irpStack->MinorFunction));

        //
        // All unhandled power messages are passed on to the PDO
        //

        IoCopyCurrentIrpStackLocationToNext(Irp);

        PoStartNextPowerIrp(Irp);

        ntStatus = PoCallDriver(deviceExtension->TopOfStackDeviceObject, Irp);

        USBLS120_DecrementIoCount(DeviceObject);

    } /* irpStack->MinorFunction */

    USBLS120_KdPrint( DBGLVL_MEDIUM,  ( "Exit USBLS120_ProcessPowerIrp()  ntStatus = 0x%x\n", ntStatus ) );
    return ntStatus;
}


NTSTATUS
USBLS120_PoRequestCompletion(
    IN PDEVICE_OBJECT       DeviceObject,
    IN UCHAR                MinorFunction,
    IN POWER_STATE          PowerState,
    IN PVOID                Context,
    IN PIO_STATUS_BLOCK     IoStatus
    )
/*++

Routine Description:

    This is the completion routine set in a call to PoRequestPowerIrp()
    that was made in USBLS120_ProcessPowerIrp() in response to receiving
    an IRP_MN_SET_POWER of type 'SystemPowerState' when the device was