KeSetSystemGroupAffinityThread 함수(wdm.h)

  • 아티클

KeSetSystemGroupAffinityThread 루틴은 호출 스레드의 그룹 번호 및 선호도 마스크를 변경합니다.

구문

void KeSetSystemGroupAffinityThread(
  [in]            PGROUP_AFFINITY Affinity,
  [out, optional] PGROUP_AFFINITY PreviousAffinity
);

매개 변수

[in] Affinity

호출 스레드에 대한 새 그룹 번호 및 그룹 상대 선호도 마스크를 지정하는 GROUP_AFFINITY 구조체에 대한 포인터입니다.

[out, optional] PreviousAffinity

호출자가 할당한 GROUP_AFFINITY 구조체에 대한 포인터로, 루틴이 호출 스레드의 이전 그룹 선호도에 대한 정보를 씁니다. 호출자는 나중에 이 포인터를 KeRevertToUserGroupAffinityThread 루틴에 대한 입력 매개 변수로 사용하여 이전 스레드 선호도를 복원할 수 있습니다. KeSetSystemGroupAffinityThread는 유효한 그룹 선호도가 아니지만 KeRevertToUserGroupAffinityThread에 특별한 의미가 있는 이 구조체에 값을 쓰는 경우가 종종 있습니다. 후속 KeSetSystemGroupAffinityThread 호출에서 이러한 특수 값에 대한 포인터를 선호도 매개 변수로 제공하지 마세요.

필요한 경우 호출자는 KeSetSystemGroupAffinityThread 를 여러 번 호출하여 스레드 선호도를 두 번 이상 변경할 수 있습니다. 이러한 호출 중 첫 번째 호출에서는 원래 스레드 선호도를 캡처하고 나중에 복원할 수 있도록 PreviousAffinity에 대해 NULL이 아닌 값을 지정해야 합니다. 그러나 KeSetSystemGroupAffinityThread에 대한 이후 호출은 옵션으로 PreviousAffinity = NULL을 설정할 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

없음

설명

이 루틴은 호출 스레드의 그룹 번호 및 그룹 상대 선호도 마스크를 변경합니다. 선호도 매개 변수는 GROUP_AFFINITY 구조를 가리킵니다. 이 구조체의 그룹 번호 및 선호도 마스크는 스레드를 실행할 수 있는 프로세서 집합을 식별합니다. 성공하면 루틴은 스레드가 이 집합의 프로세서에서 실행되도록 예약합니다.

PreviousAffinity 매개 변수가 NULL이 아닌 경우 루틴은 PreviousAffinity가 가리키는 GROUP_AFFINITY 구조에서 호출 시작 시 적용된 이전 그룹 선호도에 대한 정보를 저장합니다. 이전 스레드 선호도를 복원하기 위해 호출자는 이 구조체에 대한 포인터를 KeRevertToUserGroupAffinityThread 루틴에 대한 입력 매개 변수로 제공할 수 있습니다.

다중 프로세서 시스템에서 사용자 모드 스레드의 컨텍스트에서 실행되는 커널 모드 드라이버 루틴은 KeSetSystemGroupAffinityThread 를 호출하여 스레드의 그룹 선호도를 일시적으로 변경해야 할 수 있습니다. 루틴이 종료되기 전에 KeRevertToUserGroupAffinityThread 를 호출하여 스레드의 선호도 마스크를 원래 값으로 복원해야 합니다.

프로세스는 한 번에 둘 이상의 그룹에 대한 선호도를 가질 수 있습니다. 그러나 스레드는 언제든지 하나의 그룹에만 할당할 수 있습니다. 해당 그룹은 항상 스레드 프로세스의 선호도에 있습니다. 스레드는 KeSetSystemGroupAffinityThread를 호출하여 할당된 그룹을 변경할 수 있습니다.

KeSetSystemGroupAffinityThread 는 다음이 true인 경우에만 *선호도에 지정된 값으로 그룹 번호 및 선호도 마스크를 변경합니다.

  • 그룹 번호가 유효합니다.
  • 선호도 마스크는 유효합니다(즉, 그룹의 논리 프로세서에 해당하는 마스크 비트만 설정됨).
  • 선호도 마스크에 지정된 프로세서 중 하나 이상이 활성화되어 있습니다.
이러한 조건이 충족되지 않으면 스레드의 그룹 번호 및 선호도 마스크는 변경되지 않은 상태로 유지됩니다. PreviousAffinity가 NULL이 아닌 경우 루틴은 **PreviousAffinity*의 그룹 번호와 선호도 마스크 모두에 0을 씁니다.

또한 KeSetSystemGroupAffinityThread 는 이전 그룹 선호도가 사용자 모드에서 스레드에 할당된 경우 *PreviousAffinity 의 그룹 번호와 선호도 마스크 모두에 0을 씁니다. 그룹 번호와 선호도 마스크가 모두 0인 GROUP_AFFINITY 구조에 대한 응답으로 KeRevertToUserGroupAffinityThread 는 현재 사용자 모드 스레드 선호도를 복원합니다. KeSetSystemGroupAffinityThread와 KeRevertToUserGroupAffinityThread 호출 간에 사용자 모드 스레드 선호도가 변경되면 가장 최근의 사용자 모드 선호도가 스레드에 할당됩니다. (애플리케이션은 SetThreadGroupAffinity 와 같은 함수를 호출하여 스레드의 사용자 모드 그룹 선호도를 변경할 수 있습니다.)

*선호도의 새 선호도 마스크가 적용되기 전에 KeSetSystemGroupAffinityThread는 현재 활성화되지 않은 프로세서에 해당하는 선호도 마스크 비트를 제거(0으로 설정)합니다. 후속 KeSetSystemGroupAffinityThread 호출에서 루틴이 *PreviousAffinity 에 쓰는 값에는 이러한 방식으로 수정된 선호도 마스크가 포함될 수 있습니다.

관련 루틴인 KeSetSystemAffinityThreadEx는 호출 스레드의 선호도 마스크를 변경하지만 이 루틴은 KeSetSystemGroupAffinityThread와 달리 그룹 번호를 입력 매개 변수로 허용하지 않습니다. Windows 7부터 KeSetSystemAffinityThreadEx 는 선호도 마스크가 그룹을 지원하지 않는 이전 버전의 Windows에서 이 루틴의 동작과 호환되는 그룹 0의 프로세서를 참조한다고 가정합니다. 이 동작은 KeSetSystemAffinityThreadEx 를 호출하고 그룹 지향 기능을 사용하지 않는 기존 드라이버가 둘 이상의 그룹이 있는 다중 프로세서 시스템에서 올바르게 실행되도록 합니다. 그러나 Windows 7 이상 버전의 Windows 운영 체제에서 그룹 지향 기능을 사용하는 드라이버는 KeSetSystemAffinityThreadEx 대신 KeSetSystemGroupAffinityThread를 호출해야 합니다.

KeSetSystemGroupAffinityThread 및 KeRevertToUserGroupAffinityThread 는 다양한 호출 패턴을 지원합니다. 다음 다이어그램에는 두 가지 예제가 나와 있습니다.

다음 다이어그램은 KeSetSystemGroupAffinityThread 를 세 번 호출하여 스레드 선호도를 변경한 다음 , KeRevertToUserGroupAffinityThread 를 호출하여 원래 스레드 선호도를 복원하는 드라이버 스레드를 나타냅니다.

선호도를 설정하는 여러 호출을 보여 주는 다이어그램

앞의 다이어그램에서 "선호도 설정"이라는 레이블이 지정된 세 개의 상자는 KeSetSystemGroupAffinityThread에 대한 호출이며 "선호도 되돌리기"라는 레이블이 지정된 상자는 KeRevertToUserGroupAffinityThread에 대한 호출입니다. 첫 번째 KeSetSystemGroupAffinityThread 호출은 PreviousAffinity 출력 포인터를 사용하여 원래 스레드 선호도를 저장합니다. KeSetSystemGroupAffinityThread(별표로 표시됨)에 대한 다음 두 호출에서 호출자는 PreviousAffinity를 NULL로 설정합니다. 스레드가 종료되기 전에 KeRevertToUserGroupAffinityThread 를 호출하여 첫 번째 KeSetSystemGroupAffinityThread 호출에 의해 저장된 스레드 선호도를 복원합니다.

다음 다이어그램에서는 KeSetSystemGroupAffinityThread 및 KeRevertToUserGroupAffinityThread 호출 쌍이 중첩되는 다소 다른 호출 패턴을 보여 줍니다. 이 다이어그램에서 드라이버 스레드의 KeSetSystemGroupAffinityThread 에 대한 각 호출은 PreviousAffinity 출력 매개 변수를 사용하여 이전 스레드 선호도를 저장하고, 이러한 각 호출은 저장된 스레드 선호도를 복원하는 KeRevertToUserGroupAffinityThread 호출과 쌍을 이루게 됩니다.

선호도를 설정하고 복원하기 위한 중첩 호출을 보여 주는 다이어그램

앞의 다이어그램에서 드라이버 스레드의 함수 A는 함수 B를 두 번 호출합니다. 함수 A에 대한 항목에서 스레드에 사용자 모드 애플리케이션이 할당한 선호도가 여전히 있다고 가정합니다. 따라서 함수 A의 KeSetSystemGroupAffinityThread 호출은 원래 사용자 모드 스레드 선호도를 저장합니다. 함수 B에 대한 첫 번째 호출 중에 KeSetSystemGroupAffinityThread 는 A 함수에서 드라이버가 할당한 스레드 선호도를 저장하고 KeRevertToUserGroupAffinityThread에 대한 해당 호출은 이 선호도를 복원합니다. B가 반환되면 A의 KeRevertToUserGroupAffinityThread 는 원래 사용자 모드 스레드 선호도를 복원합니다. B에 대한 두 번째 호출 중에 KeSetSystemGroupAffinityThread 호출은 원래 사용자 모드 스레드 선호도를 저장하고 KeRevertToUserGroupAffinityThread에 대한 해당 호출은 이 선호도를 복원합니다. 이 예제의 요점은 함수 B가 B를 호출하기 전에 호출자(함수 A)가 스레드 선호도를 드라이버 정의 값으로 변경했는지 여부를 알 필요가 없다는 것입니다.

KeSetSystemGroupAffinityThread가 IRQL <= APC_LEVEL 호출에 성공하면 새 그룹 선호도가 즉시 적용됩니다. 호출이 반환되면 호출 스레드가 새 그룹 선호도에 지정된 프로세서에서 이미 실행되고 있습니다. KeSetSystemGroupAffinityThread가 IRQL = DISPATCH_LEVEL 호출되고 호출이 성공하면 호출자가 DISPATCH_LEVEL 아래 IRQL을 낮출 때까지 보류 중인 프로세서 변경이 지연됩니다.

Windows 11 및 Windows Server 2022부터 64개 이상의 프로세서, 프로세스 및 스레드 친화성이 있는 시스템에서는 기본적으로 모든 프로세서 그룹에 걸쳐 시스템의 모든 프로세서에 걸쳐 있습니다. 여러 프로세서 그룹에 스레드의 시스템 그룹 선호도를 설정하려면 PsSetSystemMultipleGroupAffinityThread를 사용합니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 7부터 사용할 수 있습니다.
대상 플랫폼 유니버설
헤더 wdm.h(Wdm.h, Wdm.h, Ntifs.h 포함)
라이브러리 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL(주의 섹션 참조).
DDI 규정 준수 규칙 HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

추가 정보

GROUP_AFFINITY

KeRevertToUserGroupAffinityThread

KeSetSystemAffinityThreadEx

PsSetSystemMultipleGroupAffinityThread