Функция PoFxIssueComponentPerfStateChangeMultiple (wdm.h)

Статья
03/01/2024

Подпрограмма PoFxIssueComponentPerfStateChangeMultiple отправляет запрос на изменение состояний производительности в нескольких наборах состояний производительности для компонента устройства одновременно.

Синтаксис

void PoFxIssueComponentPerfStateChangeMultiple(
  [in] POHANDLE                   Handle,
  [in] ULONG                      Flags,
  [in] ULONG                      Component,
  [in] ULONG                      PerfChangesCount,
  [in] PO_FX_PERF_STATE_CHANGE [] PerfChanges,
  [in] PVOID                      Context
);

Параметры

[in] Handle

Дескриптор, представляющий регистрацию устройства с помощью PoFx. Драйвер устройства ранее получил этот дескриптор из подпрограммы PoFxRegisterDevice .

[in] Flags

Флаги, которые изменяют поведение операции изменения состояния производительности. Присвойте этому элементу значение ноль или один из следующих PO_FX_FLAG_ битовXXX:

Эти два бита флага являются взаимоисключающими. Дополнительные сведения см. в подразделе "Примечания".

Значение	Значение
PO_FX_FLAG_BLOCKING 0x1	Сделайте изменение условия синхронным. Если этот флаг установлен, подпрограмма, запрашивающая изменение условия, не возвращает управление вызывающим драйвером до тех пор, пока оборудование компонента не завершит переход на новое условие. Этот флаг можно использовать только в том случае, если вызывающий объект выполняется на < DISPATCH_LEVEL IRQL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Сделайте изменение условия полностью асинхронным. Если этот флаг установлен, подпрограмма обратного вызова драйвера вызывается из потока, отличного от потока, в котором вызывается подпрограмма, запрашивающая изменение условия. Таким образом, подпрограмма, запрашивающая изменение условия, всегда возвращается асинхронно, не дожидаясь завершения обратного вызова.

Значение

PO_FX_FLAG_BLOCKING
0x1

Сделайте изменение условия синхронным. Если этот флаг установлен, подпрограмма, запрашивающая изменение условия, не возвращает управление вызывающим драйвером до тех пор, пока оборудование компонента не завершит переход на новое условие. Этот флаг можно использовать только в том случае, если вызывающий объект выполняется на < DISPATCH_LEVEL IRQL.

PO_FX_FLAG_ASYNC_ONLY
0x2

Сделайте изменение условия полностью асинхронным. Если этот флаг установлен, подпрограмма обратного вызова драйвера вызывается из потока, отличного от потока, в котором вызывается подпрограмма, запрашивающая изменение условия. Таким образом, подпрограмма, запрашивающая изменение условия, всегда возвращается асинхронно, не дожидаясь завершения обратного вызова.

[in] Component

Индекс, идентифицирующий компонент. Этот параметр представляет собой индекс массива Components в структуре PO_FX_DEVICE , используемой драйвером устройства для регистрации устройства в PoFx. Если массив Components содержит N элементов, индексы компонентов варьируются от 0 до N–1.

[in] PerfChangesCount

Количество запросов на изменение состояния производительности, содержащихся в массиве PerfChanges .

[in] PerfChanges

Первый элемент в массиве PO_FX_PERF_STATE_CHANGE структур, представляющих состояния производительности, в которые планирует перейти драйвер. Каждый элемент массива представляет один запрос на изменение состояния производительности.

[in] Context

Указатель на контекст для подпрограммы обратного вызова ComponentPerfStateCallback . Этот параметр является необязательным. Он предоставляется для передачи контекста драйвера или устройства в подпрограмму обратного вызова. Если этот параметр не используется, ему необходимо задать значение NULL.

Возвращаемое значение

None

Remarks

Драйвер вызывает PoFxIssueComponentPerfStateChangeMultiple, платформа управления питанием (PoFx) запросит подключаемый модуль расширения платформы (PEP), чтобы поместить наборы состояний производительности компонента в указанные состояния производительности. Эта подпрограмма может использоваться как с дискретными, так и с диапазонными типами наборов состояний производительности. Дополнительные сведения о дискретных и диапазонных наборах состояний производительности см. в разделе PO_FX_PERF_STATE_TYPE.

Если флаги = PO_FX_FLAG_BLOCKING, вызов PoFxIssueComponentPerfStateChangeMultiple является синхронным. В этом случае PoFxIssueComponentPerfStateChangeMultiple ожидает возврата, пока компонент не завершит переход состояния производительности. Вызывается подпрограмма ComponentPerfStateCallback драйвера, чтобы сообщить драйверу о том, что изменение состояния производительности компонента завершено. Этот обратный вызов выполняется в том же потоке, что и вызов PoFxIssueComponentPerfStateChangeMultiple, а PoFxIssueComponentPerfStateChangeMultiple возвращает только после возврата обратного вызова ComponentPerfStateCallback .

Если флаги = PO_FX_FLAG_ASYNC_ONLY, вызов PoFxIssueComponentPerfStateChangeMultiple является асинхронным. В этом случае PoFxIssueComponentPerfStateChangeMultiple планирует выполнение подпрограммы ComponentPerfStateCallback в другом потоке, а затем возвращается без ожидания обратного вызова. Обратный вызов может выполняться до или после возврата PoFxIssueComponentPerfStateChangeMultiple . Драйвер должен полагаться на подпрограмму ComponentPerfStateCallback , чтобы определить, когда компонент завершает переход в новое состояние производительности.

Драйвер может задать Flags = 0, чтобы указать, что ему не важно, является ли вызов PoFxIssueComponentPerfStateChangeMultiple синхронным или асинхронным. В этом случае PoFx определяет синхронность вызова в зависимости от того, использует ли PEP синхронный или асинхронный запрос для выдачи изменения состояния производительности компонента.

Если флаги = PO_FX_FLAG_ASYNC_ONLY или не передаются, для этой процедуры требуется IRQL <= DISPATCH_LEVEL. Если флаги = PO_FX_FLAG_BLOCKING, для этой процедуры требуется IRQL <= APC_LEVEL.

Эта функция всегда приводит к вызову подпрограммы ComponentPerfStateCallback независимо от синхронности вызова. Так как PEP может отклонить запрос на изменение состояний производительности, драйвер должен подождать, пока не будет получен обратный вызов, прежде чем фиксировать состояния производительности на оборудовании.

Для каждого компонента допускается только один вызов подпрограммы PoFxIssueComponentPerfStateChangeMultiple , независимо от того, является ли вызов синхронным или асинхронным. После отправки запроса на изменение состояния производительности драйвер должен подождать, пока не будет получен компонент ComponentPerfStateCallback , прежде чем снова вызывать эту подпрограмму, даже если запрос включает другой набор состояний производительности. Если эта подпрограмма вызывается еще раз перед ожиданием получения компонента ComponentPerfStateCallback , произойдет проверка ошибок.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 10.
Целевая платформа	Универсальное
Верхняя часть	wdm.h
Библиотека	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	<= APC_LEVEL или <= DISPATCH_LEVEL (см. раздел "Примечания")