DXGKCB_EVAL_ACPI_METHOD fonction de rappel (dispmprt.h)

Article
02/06/2025

La fonction DxgkCbEvalAcpiMethod évalue une méthode ACPI spécifiée sur une carte d’affichage ou sur un appareil enfant d’un adaptateur d’affichage.

Syntaxe

DXGKCB_EVAL_ACPI_METHOD DxgkcbEvalAcpiMethod;

NTSTATUS DxgkcbEvalAcpiMethod(
  [in]  HANDLE DeviceHandle,
  [in]  ULONG DeviceUid,
  [in]  PACPI_EVAL_INPUT_BUFFER_COMPLEX AcpiInputBuffer,
  [in]  ULONG AcpiInputSize,
  [out] PACPI_EVAL_OUTPUT_BUFFER AcpiOutputBuffer,
  [in]  ULONG AcpiOutputSize
)
{...}

Paramètres

[in] DeviceHandle

Handle qui représente un adaptateur d’affichage. Le pilote miniport d’affichage a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passée à DxgkDdiStartDevice.

[in] DeviceUid

Identificateur unique de l’appareil ACPI sur lequel la méthode sera évaluée. Si l’appareil ACPI est un enfant de l’adaptateur d’affichage, il s’agit du membre ChildUid de la structure DXGK_CHILD_DESCRIPTOR que le pilote de miniport d’affichage renseigné pendant DxgkDdiQueryChildRelations. Si l’appareil ACPI est l’adaptateur d’affichage lui-même, ce paramètre doit être défini sur DISPLAY_ADAPTER_HW_ID.

[in] AcpiInputBuffer

Pointeur vers une structure ACPI_EVAL_INPUT_BUFFER_COMPLEX (définie dans Acpiioct.h) allouée et renseignée par le pilote miniport d’affichage. La structure contient les arguments requis par la méthode ACPI. Pour plus d’informations, consultez la section Remarques suivantes.

[in] AcpiInputSize

Taille totale, en octets, de la mémoire tampon pointée par AcpiInputBuffer.

[out] AcpiOutputBuffer

Pointeur vers une structure ACPI_EVAL_OUTPUT_BUFFER (définie dans Acpiioct.h) qui reçoit la valeur de retour de la méthode ACPI. Ce paramètre peut être NULL.

[in] AcpiOutputSize

Taille totale, en octets, de la mémoire tampon pointée par AcpiOutputBuffer.

Valeur de retour

DxgkCbEvalAcpiMethod retourne STATUS_SUCCESS si elle réussit. Sinon, elle retourne l’un des codes d’erreur définis dans Ntstatus.h.

Remarques

Pour évaluer les méthodes ACPI sur un appareil ACPI, l’appareil lui-même doit se trouver dans l’espace de noms ACPI. En outre, le pilote miniport d’affichage doit avoir défini les 16 bits inférieurs du ChildUid valeur pour tous les périphériques enfants ACPI signalés par le pilote miniport d’affichage à l’identificateur signalé par ACPI.

Avant de retourner, DxgkCbEvalAcpiMethod réinitialise le membre Signature de la structure ACPI_EVAL_INPUT_BUFFER_COMPLEX sur ACPI_EVAL_INPUT_BUFFER_COMPLEX_SIGNATURE. Dans Windows Vista avec Service Pack 1 (SP1), Windows Server 2008 et versions ultérieures des systèmes d’exploitation Windows, si le pilote miniport d’affichage comporte des appareils enfants, il doit définir Signature sur DXGK_ACPI_PASS_ARGS_TO_CHILDREN avant d’effectuer un appel à DxgkCbEvalAcpiMethod.

Remarque Le sous-système du noyau graphique Microsoft DirectX ne peut pas évaluer les méthodes ACPI qui se trouvent en dehors de l’espace de noms de l’appareil.

Remarque Afficher les pilotes miniports peuvent utiliser DxgkCbEvalAcpiMethod uniquement pour les adaptateurs graphiques de liaison de prospect.

Exemples

L’exemple de code suivant montre comment évaluer une méthode ACPI.

if (HwDeviceExtension->AcpiChildren != NULL) {
    ULONG ChildIndex;
    PACPI_METHOD_ARGUMENT AcpiChildrenArray = 
 &(((PACPI_EVAL_OUTPUT_BUFFER)HwDeviceExtension->AcpiChildren) 
   ->Argument[0]);
   ULONG ChildCount = ((PACPI_EVAL_OUTPUT_BUFFER) 
   (HwDeviceExtension->AcpiChildren))->Count;
  ULONG ChildUid;
  ACPI_EVAL_INPUT_BUFFER_COMPLEX AcpiInputBuffer = {'\0'};
   ACPI_EVAL_OUTPUT_BUFFER AcpiOutputBuffer;
    pDesiredStatus = ExAllocatePoolWithTag(PagedPool,
 sizeof(DESIRED_CHILD_STATUS) * ChildCount,
 ATI_TAG);

  if (pDesiredStatus == NULL) {
     Status = STATUS_NO_MEMORY;
        goto cleanup;
  }

 RtlZeroMemory(pDesiredStatus, sizeof(DESIRED_CHILD_STATUS) * ChildCount);

 for (ChildIndex = 0; ChildIndex < ChildCount; ChildIndex++) {
 // If not a video output child, go to the next child.
 if (AcpiChildrenArray[ChildIndex].Argument
   & ACPI_NON_VIDEO_OUTPUT_DEVICE) {
   continue;
      }
      // A video output child so the ChildUid is the VidPnTargetId.
       ChildUid = (AcpiChildrenArray[ChildIndex].Argument
   & ACPI_HARDWARE_ID) | HW_ID_DISPLAY_CHILD;

      // Query ACPI for the required state.
      //
  // Beginning with Windows Vista SP1 and Windows Server 2008,
  // use DXGK_ACPI_PASS_ARGS_TO_CHILDREN.

  #if (NTDDI_VERSION >= NTDDI_WIN6SP1)
   AcpiInputBuffer.Signature = 
   DXGK_ACPI_PASS_ARGS_TO_CHILDREN;
     #else
    AcpiInputBuffer.Signature = 
   ACPI_EVAL_INPUT_BUFFER_COMPLEX_SIGNATURE;
       #endif

     AcpiInputBuffer.MethodNameAsUlong = 
   ACPI_METHOD_OUTPUT_DGS;
     Status = DxgkCbEvalAcpiMethod(HwDeviceExtension->DeviceHandle,
         ChildUid,
         &AcpiInputBuffer,
         sizeof(ACPI_EVAL_INPUT_BUFFER_COMPLEX),
         &AcpiOutputBuffer,
         sizeof(ACPI_EVAL_OUTPUT_BUFFER));
     if (!NT_SUCCESS(Status)) {
         // Something really wrong
         goto cleanup;
     }
      // Determine what the new VidPn should be and
      // allow RecommendFunctionalVidPn to return it.
      // AcpiOutputBuffer.Argument[0].Argument == 1 indicates active
       // AcpiOutputBuffer.Argument[0].Argument == 0 
       // indicates not active
       pDesiredStatus[ChildIndex].bActive = 
   (AcpiOutputBuffer.Argument[0].Argument == 1) ? TRUE : FALSE;
      // Always use the first source because this is a keyboard shortcut.
      pDesiredStatus[ChildIndex].ulSourceId = 0;
      pDesiredStatus[ChildIndex].ulTargetId = ChildUid;
  }

 Status = InvalidateVidPnForHotKey(HwDeviceExtension, pDesiredStatus);
}