структура D3DKMT_CREATE_DOORBELL (d3dkmthk.h)

Статья
02/23/2024

Важно!

Некоторые сведения относятся к предварительной версии продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

Структура D3DKMT_CREATE_DOORBELL содержит параметры для D3DKMTCreateDoorbell.

Синтаксис

typedef struct _D3DKMT_CREATE_DOORBELL {
  D3DKMT_HANDLE                hHwQueue;
  D3DKMT_HANDLE                hRingBuffer;
  D3DKMT_HANDLE                hRingBufferControl;
  D3DKMT_CREATE_DOORBELL_FLAGS Flags;
  UINT                         PrivateDriverDataSize;
  VOID                         *PrivateDriverData;
  VOID                         *DoorbellCPUVirtualAddress;
  VOID                         *DoorbellSecondaryCPUVirtualAddress;
  VOID                         *DoorbellStatusCPUVirtualAddress;
} D3DKMT_CREATE_DOORBELL;

Члены

hHwQueue

[in] Дескриптор UMD объекта очереди оборудования, созданного при предыдущем вызове D3DKMTCreateHwQueue. Этот объект идентифицирует очередь оборудования, для которой необходимо назначить дверной звонок.

hRingBuffer

[in] Дескриптор UMD для выделения кольцевого буфера, созданного ранее UMD. Выделение должно быть видимым и уже резидентным. Dxgkrnl передает виртуальный адрес GPU и размер этого выделения в KMD в соответствующем вызове DxgkDdiCreateDoorbell . Флаг ResizeRingBufferOperation — это подсказка от UMD к KMD о том, что для этой очереди оборудования создается дверной звонок с новым кольцевым буфером с измененным размером.

hRingBufferControl

[in/optional] Дескриптор UMD для выделения кольцевого буфера, ранее созданного UMD. При необходимости UMD и KMD могут использовать это выделение в качестве области управления для хранения расположений указателей чтения и записи в кольцевом буфере. Выделение должно быть видимым и уже резидентным. Dxgkrnl передает виртуальный адрес GPU и размер этого выделения в KMD в соответствующем вызове DxgkDdiCreateDoorbell .

Flags

[in/optional] Битовое поле D3DKMT_CREATE_DOORBELL_FLAGS значений, указывающих флаги создания дверного звонка.

PrivateDriverDataSize

[in] Размер данных частного драйвера, на которые указывает pPrivateDriverData , в байтах.

PrivateDriverData

[вход/выход] Указатель на буфер, который является частным для драйвера. Размер этого буфера определяется privateDriverDataSize.

DoorbellCPUVirtualAddress

[out] Указатель на виртуальный адрес ЦП (для чтения и записи), зарезервированный ОС для этого дверного звонка. UMD запишет определенное значение на этот адрес, фактически "звоня в дверь", чтобы уведомить планировщик GPU о новой отправке работ в очереди оборудования. Этот адрес остается постоянным на протяжении всего времени существования дверного звонка, даже если базовый физический дверный звонок отключается. UMD всегда должен использовать этот адрес для записи или чтения в этот дверной звонок.

DoorbellSecondaryCPUVirtualAddress

[out/optional] Указатель на дополнительный виртуальный адрес ЦП (для чтения и записи), зарезервированный ОС для этого дверного звонка.

На оборудовании, которое реализует дополнительное расположение дверного звонка, UMD устанавливает флаг RequireSecondaryCpuVA . Для таких устройств ОС зарезервует другой виртуальный адрес ЦП для этого дверного звонка. В течение всего времени существования дверного звонка этот адрес будет оставаться постоянным, даже если основной физический дверный звонок будет отключен.

DoorbellStatusCPUVirtualAddress

[out] Указатель на виртуальный адрес ЦП состояния дверного звонка. Значение по этому адресу указывает UMD, подключен ли в настоящее время дверный звонок, назначенный этой очереди оборудования. Каждый раз, когда UMD отправляет новую работу в очередь и звонит в дверный звонок, он должен проверка это значение, чтобы определить, успешно ли выполнен звонок. Если звонок завершился сбоем, UMD должен вызвать D3DKMTConnectDoorbell для повторного подключения дверного звонка, а затем попытаться отправить работу еще раз.

ОС выделяет и записывает эту 64-разрядную память о состоянии дверного звонка, сопоставляет ее с адресным пространством процесса и предоставляет виртуальный адрес ЦП пользовательского режима в UMD для чтения. Таким образом, UMD должен считывать 64-разрядное значение, хранящееся в этом адресе, чтобы получить состояние дверного звонка. Значение этого адреса может быть одним из D3DDDI_DOORBELL_STATUS значений перечисления:

Значение	Значение
D3DDDI_DOORBELL_STATUS_CONNECTED	Дверный звонок подключен и готов к отправке работы.
D3DDDI_DOORBELL_STATUS_CONNECTED_NOTIFY	Дверный звонок подключен; однако после каждой новой отправки работ и звонка в дверный звонок UMD должен уведомлять KMD, вызвав D3DKMTNotifyWorkSubmission.
D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY	В настоящее время не удается подключить дверной звонок, но UMD должен повторить попытку подключения.
D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT	Дверной звонок не будет подключен, и UMD не сможет использовать эту очередь оборудования для отправки работ. Этот сбой обычно подразумевает неустранимый сценарий, например сброс GPU или остановку адаптера.

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

Только ОПЕРАЦИОННая система записывает и обновляет эту память состояния:

При успешном возвращении из DxgkDdiConnectDoorbell ОС записывает состояние как D3DDDI_DOORBELL_STATUS_CONNECTED.
Если ОС отключает дверный звонок в рамках приостановки очереди оборудования или выключения GPU, она вызывает DxgkDdiDisconnectDoorbell KMD, а затем записывает состояние как D3DDDI_DOORBELL_STATUS_DISCONNECTED_RETRY.
Если KMD по какой-либо причине хочет отключить дверный звонок, он вызывает обратный вызов DxgkDisconnectDoorbellCB для информирования ОС. KMD предоставляет D3DDDI_DOORBELL_STATUS в качестве состояния, которое ОС записывает на эту страницу состояния.
В сценариях с потерей или остановкой GPU ОС записывает D3DDDI_DOORBELL_STATUS_DISCONNECTED_ABORT в качестве состояния.