Função KeSetSystemGroupAffinityThread (wdm.h)
A rotina KeSetSystemGroupAffinityThread altera o número do grupo e a máscara de afinidade do thread de chamada.
Sintaxe
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
Parâmetros
[in] Affinity
Um ponteiro para uma estrutura GROUP_AFFINITY que especifica o novo número de grupo e a máscara de afinidade relativa ao grupo para o thread de chamada.
[out, optional] PreviousAffinity
Um ponteiro para uma estrutura de GROUP_AFFINITY alocada pelo chamador na qual a rotina grava informações sobre a afinidade de grupo anterior do thread de chamada. Posteriormente, o chamador pode usar esse ponteiro como um parâmetro de entrada para a rotina KeRevertToUserGroupAffinityThread para restaurar a afinidade de thread anterior. Frequentemente, KeSetSystemGroupAffinityThread grava valores nessa estrutura que não são afinidades de grupo válidas, mas que têm um significado especial para KeRevertToUserGroupAffinityThread. Não forneça ponteiros para esses valores especiais como parâmetros affinity nas chamadas KeSetSystemGroupAffinityThread subsequentes.
Se necessário, o chamador pode alterar a afinidade de thread mais de uma vez chamando KeSetSystemGroupAffinityThread várias vezes. Durante a primeira dessas chamadas, o chamador deve especificar um valor não NULL para PreviousAffinity para que a afinidade de thread original possa ser capturada e restaurada posteriormente. No entanto, as chamadas posteriores para KeSetSystemGroupAffinityThread podem, como opção, definir PreviousAffinity = NULL. Para obter mais informações, consulte Comentários.
Retornar valor
Nenhum
Comentários
Essa rotina altera o número do grupo e a máscara de afinidade relativa ao grupo do thread de chamada. O parâmetro Affinity aponta para uma estrutura de GROUP_AFFINITY . O número do grupo e a máscara de afinidade nessa estrutura identificam um conjunto de processadores nos quais o thread pode ser executado. Se tiver êxito, a rotina agenda o thread para ser executado em um processador neste conjunto.
Se o parâmetro PreviousAffinity não for NULL, a rotina salvará informações sobre a afinidade de grupo anterior, que estavam em vigor no início da chamada, na estrutura GROUP_AFFINITY para a qual PreviousAffinity aponta. Para restaurar a afinidade de thread anterior, o chamador pode fornecer o ponteiro para essa estrutura como um parâmetro de entrada para a rotina KeRevertToUserGroupAffinityThread .
Em um sistema multiprocessador, uma rotina de driver no modo kernel que é executada no contexto de um thread no modo de usuário pode precisar chamar KeSetSystemGroupAffinityThread para alterar temporariamente a afinidade de grupo do thread. Antes que a rotina seja encerrada, ela deve chamar KeRevertToUserGroupAffinityThread para restaurar a máscara de afinidade do thread para seu valor original.
Um processo pode ter afinidade para mais de um grupo por vez. No entanto, um thread pode ser atribuído a apenas um grupo a qualquer momento. Esse grupo está sempre na afinidade do processo do thread. Um thread pode alterar o grupo ao qual ele é atribuído chamando KeSetSystemGroupAffinityThread.
KeSetSystemGroupAffinityThread altera o número do grupo e a máscara de afinidade para os valores especificados em *Affinity somente se o seguinte for verdadeiro:
- O número do grupo é válido.
- A máscara de afinidade é válida (ou seja, apenas os bits de máscara que correspondem aos processadores lógicos no grupo são definidos).
- Pelo menos um dos processadores especificados na máscara de afinidade está ativo.
Além disso, KeSetSystemGroupAffinityThread grava zero no número do grupo e na máscara de afinidade em *PreviousAffinity se a afinidade de grupo anterior foi atribuída ao thread no modo de usuário. Em resposta a uma estrutura GROUP_AFFINITY na qual o número do grupo e a máscara de afinidade são zero, KeRevertToUserGroupAffinityThread restaura a afinidade de thread do modo de usuário atual. Se a afinidade de thread do modo de usuário mudar entre as chamadas KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread , a afinidade mais recente do modo de usuário será atribuída ao thread. (Um aplicativo pode chamar uma função como SetThreadGroupAffinity para alterar a afinidade de grupo do modo de usuário de um thread.)
Antes que a nova máscara de afinidade em *Affinity entre em vigor, KeSetSystemGroupAffinityThread remove (define como zero) todos os bits de máscara de afinidade que correspondam aos processadores que não estão ativos no momento. Em uma chamada KeSetSystemGroupAffinityThread subsequente, o valor que a rotina grava em *PreviousAffinity pode conter uma máscara de afinidade que foi modificada dessa maneira.
Uma rotina relacionada, KeSetSystemAffinityThreadEx, altera a máscara de afinidade do thread de chamada, mas essa rotina, ao contrário de KeSetSystemGroupAffinityThread, não aceita um número de grupo como um parâmetro de entrada. A partir do Windows 7, KeSetSystemAffinityThreadEx pressupõe que a máscara de afinidade se refere a processadores no grupo 0, que é compatível com o comportamento dessa rotina em versões anteriores do Windows que não dão suporte a grupos. Esse comportamento garante que os drivers existentes que chamam KeSetSystemAffinityThreadEx e que não usam recursos orientados a grupo sejam executados corretamente em sistemas multiprocessadores que tenham dois ou mais grupos. No entanto, os drivers que usam recursos orientados a grupos no Windows 7 e versões posteriores do sistema operacional Windows devem chamar KeSetSystemGroupAffinityThread em vez de KeSetSystemAffinityThreadEx.
KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread dão suporte a uma variedade de padrões de chamada. Dois exemplos são mostrados nos diagramas a seguir.
O diagrama a seguir representa um thread de driver que chama KeSetSystemGroupAffinityThread três vezes para alterar a afinidade de thread e, em seguida, chama KeRevertToUserGroupAffinityThread para restaurar a afinidade de thread original.
No diagrama anterior, as três caixas rotuladas como "Definir afinidade" são chamadas para KeSetSystemGroupAffinityThread e a caixa rotulada como "Reverter afinidade" é uma chamada para KeRevertToUserGroupAffinityThread. A primeira chamada KeSetSystemGroupAffinityThread usa o ponteiro de saída PreviousAffinity para salvar a afinidade de thread original. Nas duas próximas chamadas para KeSetSystemGroupAffinityThread (marcadas com asteriscos), o chamador define PreviousAffinity como NULL. Antes da saída do thread, ele chama KeRevertToUserGroupAffinityThread para restaurar a afinidade de thread que foi salva pela primeira chamada KeSetSystemGroupAffinityThread .
O diagrama a seguir mostra um padrão de chamada um pouco diferente no qual pares de chamadas KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread são aninhados. Neste diagrama, cada chamada para KeSetSystemGroupAffinityThread no thread de driver usa o parâmetro de saída PreviousAffinity para salvar a afinidade de thread anterior e cada uma dessas chamadas é emparelhada com uma chamada para KeRevertToUserGroupAffinityThread que restaura a afinidade de thread salva.
No diagrama anterior, a função A no thread de driver chama a função B duas vezes. Suponha que, na entrada para a função A, o thread ainda tenha a afinidade atribuída a ele pelo aplicativo de modo de usuário. Assim, a chamada KeSetSystemGroupAffinityThread na função A salva a afinidade de thread original no modo de usuário. Durante a primeira chamada para a função B, KeSetSystemGroupAffinityThread salva a afinidade de thread atribuída pelo driver na função A e a chamada correspondente a KeRevertToUserGroupAffinityThread restaura essa afinidade. Depois que B retorna, KeRevertToUserGroupAffinityThread em A restaura a afinidade de thread original no modo de usuário. Durante a segunda chamada para B, a chamada KeSetSystemGroupAffinityThread salva a afinidade de thread original no modo de usuário e a chamada correspondente para KeRevertToUserGroupAffinityThread restaura essa afinidade. O ponto deste exemplo é que a função B não precisa saber se o chamador (função A) alterou a afinidade de thread para um valor definido pelo driver antes de chamar B.
Se KeSetSystemGroupAffinityThread for chamado em IRQL <= APC_LEVEL e a chamada for bem-sucedida, a nova afinidade de grupo entrará em vigor imediatamente. Quando a chamada retorna, o thread de chamada já está em execução em um processador especificado na nova afinidade de grupo. Se KeSetSystemGroupAffinityThread for chamado em IRQL = DISPATCH_LEVEL e a chamada for bem-sucedida, a alteração pendente do processador será adiada até que o chamador reduza o IRQL abaixo DISPATCH_LEVEL.
A partir do Windows 11 e do Windows Server 2022, em um sistema com mais de 64 processadores, as afinidades de processo e thread abrangem todos os processadores do sistema, em todos os grupos de processadores, por padrão. Para definir a afinidade de grupo do sistema de um thread em vários grupos de processadores, use PsSetSystemMultipleGroupAffinityThread.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 7. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (inclua Wdm.h, Wdm.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (consulte a seção Comentários). |
| Regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |