RtQueryThreadPerfIdealProcessor

RtQueryThreadPerfIdealProcessor queries the thread’s current Class ID, the performance ideal processor, the current performance capability of affinity logical processor, and the performance capability of each logical processor based on hardware feedback.

Syntax

Copy

BOOL RtQueryThreadPerfIdealProcessor(
    [in]    Handle hThread,
    [out]   PULONG pClassID,
    [out]   PULONG pIdealProcessorNumber,
    [out]   PULONG pCurrentPerfCap,
    [out]   ULONG  SystemPerfCaps[]
);

Parameters

[in] hThread

A handle to the thread object.

[out] pClassID

A pointer to a ULONG to store the current Class ID of the specified thread. The thread Class ID is feedbacked from the hardware based on thread characteristic; i.e., the instruction set the thread executes on the logical processor.

[out] pIdealProcessorNumber

A pointer to a ULONG to store the performance ideal processor number based on the thread’s current Class ID.

[out] pCurrentPerfCap

A pointer to a ULONG to store the thread affined processor’s current performance capability when executing the instruction set of the Class ID. Performance capability is a value (0 ... 255) specifying the relative performance level of a logical processor. Higher values indicate higher performance.

[out] SystemPerfCaps[]

A ULONG array to store current performance capabilities of a Class ID on each active logical processor.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. GetLastError returns ERROR_NOT_SUPPORTED if Intel Thread Director is not supported, ERROR_INVALID_PARAMETER if there are invalid parameters, or ERROR_INVALID_HANDLE if the handle passed is null or invalid.

Remarks

Thread Class IDs (0, 1, 2, …) represent a software thread's characteristics, i.e., the assembly instruction set (e.g., AVX2) the thread executes. With Intel Thread Director Technology (IDT), the logical processor provides feedback as a Class ID for the thread running on it once it has enough history. eRTOS updates when switching out of the thread’s Class ID during thread switches and resets the logical processor’s thread director history. eRTOS also updates the thread’s Class ID when RtQueryThreadPerfIdealProcessor is called if the caller is the current thread on the current logical processor. The logical processor may not provide feedback for a Class ID if it does not have enough information to provide a reliable Class ID. In this case, eRTOS will not overwrite the thread’s last known Class ID. Thread Class ID is initialized to 0 at creation time.

The values returned by the parameters pIdealProcessorNumber, pCurrentPerfCap, and SystemPerfCaps[] are based on the thread’s current Class ID.

eRTOS does not dynamically migrate threads during thread scheduling. It is recommended that processes call RtQueryThreadPerfIdealProcessor to identify their ideal processors for those performance critical threads. If necessary, call SetThreadIdealProcessor or SetThreadAffinityMask to affine the thread to the performance ideal processor. SetThreadIdealProcessor or SetThreadAffinityMask cannot migrate Interrupt Service Thread (IST), Timer Service Thread (TST), and threads using NPX at run-time. You may need to affine those threads to their performance ideal processors at create time.

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	RtssApi.h	rtkrnl.lib