HvlQueryActiveProcessors

The HvlQueryActiveProcessors function obtains a count of logical processors and optionally the logical processor indices.

Declaration

NTSTATUS 
HvlQueryActiveProcessors (
    ULONG *LpCount, 
    ULONG *LpIndices);

Parameters

The LpCount argument provides the address of a variable that is here named the processor count since it is to receive the number of processors. If a buffer is provided at LpIndices, then this processor count is also meaningful as input, specifically to tell the function how many indices are sought.

The LpIndices argument provides the address of an index buffer. This is to receive a logical processor index for each logical processor. The capacity of this buffer, in indices, is specified as the input value of the processor count. The LpIndices argument can be NULL if the indices are not wanted: in this case, the processor count is ignored as input.

Return Value

The function returns STATUS_SUCCESS if successful, else a negative error code.

Of particular importance is STATUS_BUFFER_TOO_SMALL, which is the function’s indication that it could have succeeded had the index buffer been larger. Though the function fails, the processor count as output is meaningful, specifically to tell how many indices the buffer would have needed to allow for.

Availability

The HvlQueryActiveProcessors function is exported by name from the kernel in version 6.2 and higher.

Documentation Status

The HvlQueryActiveProcessors function is not documented.

In the declaration above, the LpCount argument is named for consistency with Microsoft’s declaration of HvlQueryActiveHypervisorProcessorCount. Other types and names are invented for this note.

Behaviour

The function depends on the CPU Management feature of the hypervisor. If this is not enabled, the function fails, returning STATUS_ACCESS_DENIED.

If no variable is provided for receiving the processor count, the function can to nothing useful, and fails, returning STATUS_INVALID_PARAMETER.

If no index buffer is provided, the function produces just the processor count, and returns STATUS_SUCCESS. In this mode, the function adds nothing to HvlQueryActiveHypervisorProcessorCount.

Given an index buffer, the function adds a logical processor index for each processor until the buffer’s capacity, as given by the input value of the processor count, is reached. Note that this capacity can be zero. The function stores its count of processors as the output value of the processor count. If it did not store this many indices in the index buffer, the function fails, returning STATUS_BUFFER_TOO_SMALL. Otherwise, the function returns STATUS_SUCCESS.