Table of Contents

Introduction

This document is related to epic https://linaro.atlassian.net/browse/WPERF-25 which covers various issues around wperf-driver improvements.

Add new "busy" state to wperf-driver

• See https://linaro.atlassian.net/browse/WPERF-116 for more Jira related information about this feature.

Goal of this feature

• To introduce user-space propagated reliable information about wperf-driver current activity. This will allow users on multi-user systems to (at least) be aware of other WindowsPerf activity.

• To avoid corrupted and unreliable measurements.

Definition of done

• Add new BUSY state functionality to the driver and the IOCTL protocol.

• In WPERF-116 we do not have to add special “transaction” business logic. For example we do not have to add any checks if we start counting if sampling is ongoing.

  • We will add business logic and tests as a separate functionality.

Required behaviour

1. Ultimatelly remove the call to WdfDeviceInitSetExclusive.

2. Create a persistent structure inside wperf-driver that capture driver’s “transition” current state, like if it is sampling, counting, if PMU resources are available or not. We want to capture:

   1. [bool flag] If driver is currently “counting” or “sampling” - this will set BUSY state to true.

   2. [IOCTL request no] Current IOCTL being processed - this is useful to determine in user space if we are actually counting/timeline or sampling or doing some other work.

3. How IOCTL will set BUSY state?

   1. Some IOCTL will set (and clear after IOCTL is finished) busy state during IOCTL handling only, e.g. PMU_CTL_RESET or IOCTL_PMU_CTL_QUERY_HW_CFG. This is because these “transactions” are pending during IOCTL handle and end after.

   2. Some IOCTLs will set BUSY state

   3. Not all IOCTLs may set bus state as some do not “set in motion” the driver.

4. Update to driver ↔︎ user-space protocol.

   1. User-space should handle properly BUSY state of the driver. E.g. warn that “continuing” IOCTL is ongoing.

      1. Please note this creates a “transaction” / “scenario” for WindowsPerf.

   2. We will send to user-space new set of flags:

      1. “current IOCTL” - which IOCTL is ongoing now.

      2. BUSY flag and at least info about which IOCTL is ongoing.

         1. If BUSY state is true: IOCTL field is valid with IOCTL being processed now.

      3. [to consider] “Invalid payload” - we may want to add to each IOCTL response with info if we managed to compose response payload.

         1. In scenarios when we send IOCTL_PMU_CTL_QUERY_HW_CFG during counting, the driver is busy but response payload would be valid as we can respond during counting.

List of IOCTLs and BUSY state

State “names”:

• transient - lasts only during IOCTL handle (inside deviceControl()call).

• continuing - lasts after IOCTL handle in deviceControl is “finished”, e.g. when we start counting.

Considerations

Name

Name
@Everton Constantino (Deactivated)	Open Changing our current protocol between driver and app inside iorequest.h  we can add a field, or a whole new structure, with the request status and other info as we see fit. The app should take care to check the response status before going any further. Here for example https://gitlab.com/Linaro/WindowsPerf/windowsperf/-/blob/main/wperf/pmu_device.cpp?ref_type=heads#L2468 we check the size of the returned struct to check if it is valid or not (which we should be doing in other places btw) We can make similar checks for busy or incomplete requests. Later, as those information gets richer, we will be able to handle this better depending on what is happening inside the driver
@Matthew Sykes (Deactivated)	I think I have an idea how it might look,   the driver will need to track the active object (context) of the CreateFile() call, so that an IOCTLS relating to that object are succeeded, and any others sent back with the status set to 'busy'