Função StorPortSetSystemGroupAffinityThread (storport.h)

Artigo
08/07/2023

StorPortSetSystemGroupAffinityThread altera o número do grupo e a máscara de afinidade do thread de chamada.

Sintaxe

ULONG StorPortSetSystemGroupAffinityThread(
  [in]           PVOID                HwDeviceExtension,
  [in/optional]  PVOID                ThreadContext,
  [in]           PSTOR_GROUP_AFFINITY Affinity,
  [out/optional] PSTOR_GROUP_AFFINITY PreviousAffinity
);

Parâmetros

[in] HwDeviceExtension

Ponteiro para a extensão de dispositivo de hardware do miniporto.

[in/optional] ThreadContext

Ponteiro para o contexto de thread recebido em uma chamada anterior para StorPortCreateSystemThread.

[in] Affinity

Ponteiro para uma estrutura de STOR_GROUP_AFFINITY alocada pelo chamador 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

Ponteiro para uma estrutura STOR_GROUP_AFFINITY na qual essa rotina grava o número do grupo e a máscara de afinidade para o thread de chamada antes da chamada. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

StorPortSetSystemGroupAffinityThread retorna um dos seguintes valores:

Código de retorno	Descrição
STOR_STATUS_SUCCESS	A afinidade de grupo especificada foi definida com êxito.
STOR_STATUS_INVALID_PARAMETER	Um ou mais dos parâmetros fornecidos são inválidos.
STOR_STATUS_UNSUCCESSFUL	Retornado por outros motivos internos do sistema.

Comentários

Um miniporto pode chamar StorPortSetSystemGroupAffinityThread para alterar o número do grupo e a máscara de afinidade no nível do grupo do thread de chamada.

O número do grupo e a máscara de afinidade na estrutura STOR_GROUP_AFFINITY apontada pela Affinity identificam um conjunto de processadores nos quais o thread pode ser executado. Se tiver êxito, StorPortSetSystemGroupAffinityThread agenda o thread para ser executado em um processador neste conjunto.

Se o parâmetro PreviousAffinity não for NULL, StorPortSetSystemGroupAffinityThread salvará informações sobre a afinidade de grupo anterior, que estavam em vigor no início da chamada, na estrutura STOR_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 StorPortRevertToUserGroupAffinityThread .

Se um miniporto chamar essa função para alterar temporariamente a afinidade de grupo do thread, ele deverá chamar StorPortRevertToUserGroupAffinityThread para reverter afinidade de thread para seu valor original antes que o thread seja encerrado.

Um thread pode ser atribuído a apenas uma afinidade de 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 essa rotina.

StorPortSetSystemGroupAffinityThread 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.

Se qualquer uma dessas condições não for atendida, o número do grupo e a máscara de afinidade do thread permanecerão inalterados. Se PreviousAffinity não for NULL, a rotina gravará zero no número do grupo e na máscara de afinidade em PreviousAffinity.

Antes que a nova máscara de afinidade em Affinity entre em vigor, StorPortSetSystemGroupAffinityThread 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 storPortSetSystemGroupAffinityThread subsequente, o valor que a rotina grava em PreviousAffinity pode conter uma máscara de afinidade que foi modificada dessa maneira.

Se StorPortSetSystemGroupAffinityThread 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 StorPortSetSystemGroupAffinityThread 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.