Windows Hiper Yönetici Platformu API Tanımları

Bu API, Windows Nisan 2018 Güncelleştirmesi'nde kullanıma sunulmuştur.

Aşağıdaki diyagramda üçüncü taraf mimarisine üst düzey bir genel bakış sağlanmaktadır.

Aşağıdaki bölüm, aracılığıyla WinHvPlatform.hkullanıma sunulan Windows Hiper Yönetici Platformu API'lerinin tanımlarını içerir. WinHvPlatform.dll (System32 klasöründe bulunur), HRESULT hata kodlarını döndüren C stilinde bir Windows API işlevleri kümesini dışarı aktarır. Üst bilgiler Windows SDK paketiyle yayımlanır.

Platform Özellikleri

İşlev	Description
WHvGetCapability	Platform özellikleri, çağıranların hiper yöneticinin, API uygulamasının ve uygulamanın üzerinde çalıştığı donanım platformunun özelliklerini ve özelliklerini sorgulaması için genel bir yoldur. Platform API'si, api'nin genişletilmiş işlevselliğinin kullanılabilirliğini ve geçerli sistemdeki işlemcinin desteklediği özellik kümesini yayımlamak için bu özellikleri kullanır.

Geçerli sistemin Arm64'te Windows Hiper Yönetici Platformu'nu destekleyip desteklemediğini belirlemek için WHvCapabilityCodeFeatures ile WHvGetCapability çağırın ve döndürülen WHV_CAPABILITY_FEATURES değerinin Arm64Support bitini test edin.

Bölüm Oluşturma, Kurulum ve Silme

İşlev	Description
WHvCreatePartition	Bölüm oluşturmak yeni bir bölüm nesnesi oluşturur. Bölümün ek özellikleri bölüm nesnesinde depolanır ve hiper yöneticide bölüm oluşturulurken uygulanır.
WHvSetupPartition	Bölümün ayarlanması, gerçek bölümün hiper yöneticide oluşturulmasına neden olur. Bölümün ilk özelliklerini yapılandırma dışında, bir bölümün oluşturulduktan sonra bölümde başka bir işlem gerçekleştirmeden önce ayarlanması gerekir.
WHvDeletePartition	Bir bölümün silinmesi bölüm nesnesini yerle bir eder ve bölümün kullandığı tüm kaynakları serbest bırakır.

Bölüm Özellikleri

Bölüm özellikleri, çağıranların bir bölümün özelliklerini sorgulaması ve yapılandırması için mekanizma sağlar. Bir özelliği sorgulamak, özelliğin daha önce çağıran tarafından değiştirilmemiş olması durumunda hiper yönetici ve API uygulamaları tarafından belirlenen varsayılan değeri sağlayan geçerli değerini döndürür. 

Bölüm özellikleri aracılığıyla yapılandırılabilir özelliklerin kullanılabilirliği, hiper yöneticinin özelliklerine, API uygulamasına ve sistemdeki fiziksel işlemciye bağlıdır. Bir uygulama, bir özelliği yapılandırmaya çalışmadan önce ilgili özelliği denetlemelidir.

Çeşitli özellikler (örneğin, bölüm için kullanılabilir hale gelen işlemci özelliklerini yapılandıran özellikler) yalnızca bölümün oluşturulması sırasında ve bölümde bir sanal işlemci yürütülmadan önce değiştirilebilir. Bir bölüm yürütülmeye başladıktan sonra bu özellikleri değiştirme girişimi işlemin başarısız olmasına neden olur.

Bölüm özellikleri hakkında daha fazla bilgi için: Bölüm Özelliği Veri Türleri

İşlev	Description
WHvGetPartitionProperty	Bir özelliği sorgulamak, özelliğin daha önce çağıran tarafından değiştirilmemiş olması durumunda hiper yönetici ve API uygulamaları tarafından belirlenen varsayılan değeri sağlayan geçerli değerini döndürür.
WHvSetPartitionProperty	Bölüm özelliklerinin yapılandırmasını ayarlar.

Bölüm Sıfırlama ve Geçiş

Bir bölüm ilk durumuna sıfırlanabilir ve çalışan bir bölüm bir konaktan diğerine geçirilebilir. Geçiş, kaynak konakta başlatılan, hedef konakta kabul edilen ve ardından kaynak konakta tamamlanan veya iptal edilen çok adımlı bir işlemdir.

İşlev	Description
WHvResetPartition	Bir bölümü ilk durumuna sıfırlar.
WHvStartPartitionMigration	Kaynak konakta bir bölümü geçirmeye başlar.
WHvAcceptPartitionMigration	Hedef konakta geçiş bölümünü kabul eder.
WHvCompletePartitionMigration	Kaynak konakta bölüm geçişini son haline dönüştürür.
WHvCancelPartitionMigration	Kaynak konakta devam eden bölüm geçişini durdurur.

VM Bellek Yönetimi

SANAL makine bölümünün fiziksel adres alanı (GPA alanı), sanallaştırma yığınının kullanıcı modu işleminde ayrılan bellek kullanılarak doldurulur. Sanallaştırma yığını, standart Windows bellek yönetimi işlevlerini (VirtualAlloc gibi) kullanarak gerekli belleği ayırır veya bir dosyayı işlemine eşler ve bu bölgelerin adreslerini kullanarak belleği bölümün GPA alanına eşler.

Bellek veri türleri hakkında daha fazla bilgi için: Bellek Veri Türleri

İşlev	Description
WHvMapGpaRange	Bir bölümün GPA alanında bir aralık için eşleme oluşturmak, çağıranın işlemindeki bir bölgeyi bu aralığın yedekleme belleği olarak ayarlar. İşlem, belirtilen GPA sayfaları için önceki eşlemelerin yerini alır.
WHvMapGpaRange2	Bir bölümün konuk fiziksel adres alanı aralığını belirtilen konak işlemindeki belleğe eşler.
WHvUnmapGpaRange	Önceden eşlenmiş bir GPA aralığının eşlenmesi, bellek aralığının bölüm için kullanılamaz olmasına neden olur. Bir sanal işlemcinin aralığa daha fazla erişimi, bellek erişimi çıkışına neden olur.
WHvAdviseGpaRange	Hiper yöneticiye bir veya daha fazla konuk fiziksel adres aralığının bellek desteğiyle ilgili ipuçları sağlar.
WHvReadGpaRange	Bir bölümün konuk fiziksel adres alanından bayt sayısı kadar WHV_READ_WRITE_GPA_RANGE_MAX_SIZE okur.
WHvWriteGpaRange	Bir bölümün konuk fiziksel adres alanına bayt kadar WHV_READ_WRITE_GPA_RANGE_MAX_SIZE yazar.
WHvTranslateGva	Bir bölümdeki bir sanal işlemci tarafından kullanılan bir sanal adresin çevrilmesi, sanallaştırma yığınının bir G/Ç işlemi için işlemci yönergesine öykünmesini sağlar ve bölümün GPA alanında yönergenin bellek işlenenlerini okumak ve yazmak için çevirinin sonuçlarını kullanır.
WHvQueryGpaRangeDirtyBitmap	Konuğun aralığın son sorgusundan bu yana hangi sayfaları değiştirdiğini belirlemek için bir gpa alanı aralığını sorgular.

Sanal İşlemci Yürütme

Bir VM'nin sanal işlemcileri, hiper yöneticinin yeni tümleşik zamanlayıcı kullanılarak yürütülür. Sanal işlemci çalıştırmak için sanallaştırma yığını işlemindeki bir iş parçacığı, hiper yöneticide sanal işlemciyi yürütmek için bir engelleme çağrısı oluşturur. Çağrı, sanal işlemci sanallaştırma yığınının işlemesi gereken bir işlemi gerçekleştirdiğinde veya sanallaştırma yığını çıkış istediğinde döndürür.  

Sanal işlemci işleyen bir iş parçacığı aşağıdaki temel işlemleri yürütür:

1. Bölümünde sanal işlemciyi oluşturun.
2. Bekleyen kesmeleri ve olayları işlemciye eklemeyi içeren sanal işlemcinin durumunu ayarlayın.
3. Sanal işlemciyi çalıştırın.
4. Sanal işlemci çalıştırdıktan sonra işlemcinin durumunu sorgulayıp işlemcinin çalışmayı durdurmasına neden olan işlemi işleyebilir.
5. Sanal işlemci hala etkinse, işlemciyi çalıştırmaya devam etmek için 2. Adıma geri dönün.
6. Bölümdeki sanal işlemciyi silin.  

Sanal işlemcinin durumu donanım yazmaçlarını içerir ve sanallaştırma yığınının sanal işlemciye eklemek istediği tüm kesintiler.

İşlev	Description
WHvCreateVirtualProcessor	Bu işlev, bir bölümde yeni bir sanal işlemci oluşturur. Sanal işlemcinin dizini, işlemcinin APIC kimliğini ayarlamak için kullanılır.
WHvCreateVirtualProcessor2	İsteğe bağlı oluşturma zamanı özelliklerine sahip bir bölümde yeni bir sanal işlemci oluşturur.
WHvDeleteVirtualProcessor	Bu işlev bir bölümdeki sanal işlemciyi siler.
WHvRunVirtualProcessor	Bu işlev sanal işlemciyi çalıştırır (diğer bir ifadeyle konuk kodunu çalıştırır). Sanal işlemci sanallaştırma yığını tarafından işlenmesi gereken bir işlemi yürütene (örneğin, eşlenmeyen veya erişilmeyen GPA alanında erişilen belleğe) veya sanallaştırma yığını açıkça işlevin çıkışını isteyene (örneğin, sanal işlemciye bir kesme eklemek veya VM'nin durumunu değiştirmek) bu işleve yönelik bir çağrı zaman uyumlu olarak engeller.
WHvCancelRunVirtualProcessor	Bir sanal işlemcinin yürütülmesini iptal etmek, uygulamanın sanal işlemciyi başka bir iş parçacığı tarafından çalıştırma çağrısını durdurmasına ve denetimi bu iş parçacığına döndürmesine olanak tanır. Sanallaştırma yığını, sanal işlemcinin durumunu değiştirmesi veya işlemciye olay eklemesi gerektiğinde sanal işlemci denetimini sanallaştırma yığınına geri döndürmek için bu işlevi kullanabilir.

Çıkış Bağlamı

İşlevin çıkışına WHvRunVirtualProcessor ilişkin ayrıntılı neden ve ek bilgiler, çıkış için bir bağlam yapısı alan işlevin çıkış arabelleğine döndürülür. Bu bağlam arabelleğinde sağlanan veriler tek tek çıkış nedenine özgüdür ve basit çıkış nedenleriyle arabellek kullanılmamış (RunVpExitLegacyFpError ve RunVpExitInvalidVpRegisterValue) olabilir.

Structures	Description
Çıkış Bağlamları	Çeşitli çıkış nedenleriyle bağlam yapıları, çıkışa neden olan işlemci yönergesi ve çıkış sırasında sanal işlemcinin durumu hakkında bilgi sağlayan veriler için ortak tanımları paylaşır.
Bellek Erişimi	Sanal işlemcinin eşlenmemiş veya erişilebilir olmayan bir bellek konumuna erişmesinin neden olduğu çıkışlar hakkında bilgiler yapı tarafından WHV_MEMORY_ACCESS_CONTEXT sağlanır.
G/Ç Bağlantı Noktası Erişimi	Yapıda G/Ç bağlantı noktası yönergesi (IN, OUT, INS ve OUTS) yürüten sanal işlemcinin WHV_X64_IO_PORT_ACCESS_CONTEXT neden olduğu çıkışlar hakkında bilgi sağlanır.
MSR Erişimi	Sanal işlemcinin RDMSR veya WRMSR yönergelerini kullanarak modele özgü bir yazmacına (MSR) erişmesinin WHV_X64_MSR_ACCESS_CONTEXT neden olduğu çıkışlar hakkında bilgiler yapıda sağlanır.
CPUID Erişimi	CPUID yönergesini yürüten sanal işlemcinin neden olduğu çıkışlar hakkında bilgiler yapıda WHV_X64_CPUID_ACCESS_CONTEXT sağlanır.
Sanal İşlemci Özel Durumu	Sanal işlemci tarafından oluşturulan bir özel durum hakkındaki bilgiler yapıda WHV_VP_EXCEPTION_CONTEXT sağlanır.
Kesme Penceresi	İşlemcinin kesme durumu belirli bir kesmenin teslimini sağlarken sanal işlemcinin neden olduğu çıkışlar hakkında bilgi.
Desteklenmeyen Özellik	Sanal işlemci, hiper yöneticinin düzgün sanallaştırmadığı bir mimari özelliğe eriştiğinde desteklenmeyen bir özellik için çıkış oluşur.
Yürütme İptal Edildi	Konak sisteminin neden olduğu bir çıkışla ilgili bilgiler yapıda WHV_RUN_VP_CANCELLED_CONTEXT sağlanır.
RDTSC(P)	RDTSC(P) yönergesini yürüten sanal işlemcinin neden olduğu çıkışlar hakkında bilgiler yapıda WHV_X64_RDTSC_CONTEXT sağlanır.
Kesme Noktasını Kaydet	Kesilen sistem yazmaç erişiminin neden olduğu Arm64 çıkışı hakkında bilgiler yapıda WHV_REGISTER_CONTEXT sağlanır.
Arm64 Sıfırlama	Yapıda WHV_ARM64_RESET_CONTEXT sanal işlemci sıfırlama isteğinin neden olduğu Arm64 çıkışıyla ilgili bilgiler sağlanır.

Sanal İşlemci Yazmaçları

Hem temel mimari tarafından tanımlanan durumu (genel amaçlı yazmaçlar gibi) hem de hiper yönetici tarafından tanımlanan ek durumu içeren bir sanal işlemcinin durumuna bu işlevler aracılığıyla erişilebilir.

Yazmaçlar hakkında daha fazla bilgi için bkz. Sanal İşlemci Kayıt Adları ve Değerleri

İşlev	Description
WHvGetVirtualProcessorRegisters	Bu işlev, sanallaştırma yığını tarafından tek tek bir kayıt kümesini sorgulamaya olanak tanır.
WHvGetVirtualProcessorXsaveState	Bu işlev, sanal işlemcinin XSAVE durumunu sorgulamaya olanak tanır. Kullanım dışı; WHvGetVirtualProcessorState kullanın.
WHvSetVirtualProcessorRegisters	Bu işlev, sanallaştırma yığını tarafından tek tek bir kayıt kümesi ayarlamaya olanak tanır.
WHvSetVirtualProcessorXsaveState	Bu işlev, sanal işlemcinin XSAVE durumunu ayarlamaya olanak tanır. Kaldırıl -mış; WHvSetVirtualProcessorState kullanın.

Kesme denetleyicisi sanallaştırması

İsteğe bağlı olarak, hiper yönetici platformu yerel bir APIC kesme denetleyicisine öykünebilir. APIC gerektiren sanal makineler için, platformun yerleşik öykünmesini kullanmak en iyi performansı verir. Arm64'te bir bölüm, bölüm kurulmadan önce yapılandırılan öykünülmüş kesme denetleyicisini (GIC) kullanmalıdır. Daha fazla bilgi için bkz. WHvSetupPartition.

Bu işlev etkinleştirildiğinde, bu işlevler sanal kesme isteğinde bulunmak ve kesme denetleyicisi durumunu sorgulamak ve ayarlamak için kullanılabilir.

İşlev	Description
WHvRequestInterrupt	Sanal kesme isteğinde bulunur.
WHvGetInterruptTargetVpSet	Bir kesme hedefini hedef sanal işlemci kümesine çözümler.
WHvGetVirtualProcessorInterruptControllerState	Sanal işlemcinin kesme denetleyicisi durumunu alır. Kullanım dışı; WHvGetVirtualProcessorState kullanın.
WHvGetVirtualProcessorInterruptControllerState2	Sanal işlemcinin kesme denetleyicisi durumunu standart dış durum biçiminde alır. Kullanım dışı; WHvGetVirtualProcessorState kullanın.
WHvSetVirtualProcessorInterruptControllerState	Sanal işlemcinin kesme denetleyicisi durumunu ayarlar. Kaldırıl -mış; WHvSetVirtualProcessorState kullanın.
WHvSetVirtualProcessorInterruptControllerState2	Sanal işlemcinin kesme denetleyicisi durumunu standart dış durum biçiminde ayarlar. Kaldırıl -mış; WHvSetVirtualProcessorState kullanın.

Sanal İşlemci Durumu

Tek tek yazmaçlara ek olarak, sanal işlemcinin kaydedilmiş durumu sorgulanabilir ve kategoriye göre ayarlanabilir ve sanal işlemcinin gözlemlediği CPUID sonuçları sorgulanabilir.

İşlev	Description
WHvGetVirtualProcessorState	Sanal işlemciden kaydedilmiş durum kategorisini alır.
WHvSetVirtualProcessorState	Sanal işlemcide kaydedilen durum kategorisini ayarlar.
WHvGetVirtualProcessorCpuidOutput	Sanal işlemcinin belirli bir yaprak için gözlemlediği CPUID sonucunu döndürür.

Sentetik Kesme Denetleyicisi (SynIC)

Bu işlevler sanal işlemciye yapay kesme denetleyicisi (SynIC) olayları ve iletileri sunar.

İşlev	Description
WHvSignalVirtualProcessorSynicEvent	Sanal işlemcide yapay kesme denetleyicisi olay bayrağına işaret eder.
WHvPostVirtualProcessorSynicMessage	Sanal işlemciye yapay kesme denetleyicisi iletisi yayınlar.

Sayaçlar

Bu işlevler çeşitli hiper yönetici platform sayaçlarını sorgulamak için kullanılabilir.

İşlev	Description
WHvGetPartitionCounters	Bu işlev bir bölüm için sayaçları sorgulamaya olanak tanır.
WHvGetVirtualProcessorCounters	Bu işlev, sanal işlemci için sayaçları sorgulamaya olanak tanır.

Kapı zilleri

Doorbell, bir konuk belirtilen bir konuk fiziksel adresine belirtilen değeri yazdığında sanallaştırma yığınının bir Windows olay nesnesi aracılığıyla bildirilmesini sağlar.

Note

Kapı zili işlevleri kullanım dışıdır. Bunun yerine türünde WHvNotificationPortTypeDoorbell bir bildirim bağlantı noktası kullanın (bkz . Bildirim Bağlantı Noktaları).

Kapı zili veri türleri hakkında daha fazla bilgi için: Doorbell Veri Türleri

İşlev	Description
WHvRegisterPartitionDoorbellEvent	Bir konuk belirtilen konuk fiziksel adresine yazdığında işaretlenecek olayı kaydeder. Kaldırıl -mış; WHvCreateNotificationPort kullanın.
WHvUnregisterPartitionDoorbellEvent	Daha önce kaydedilmiş bir bölüm kapı zili olayının kaydını kaldırır. Kaldırıl -mış; WHvDeleteNotificationPort kullanın.

Tetikleyiciler

Tetikleyici, bir konak olay nesnesine sinyal gönderildiğinde bölüme önceden yapılandırılmış bir kesme veya olay teslim eder.

Tetikleyici veri türleri hakkında daha fazla bilgi için: Tetikleyici Veri Türleri

İşlev	Description
WHvCreateTrigger	Bir konak olayı sinyallendiğinde bölüme önceden yapılandırılmış bir kesme veya olay teslim eden bir tetikleyici nesnesi oluşturur.
WHvUpdateTriggerParameters	Mevcut tetikleyici nesnesinin parametrelerini güncelleştirir.
WHvDeleteTrigger	Bir tetikleyici nesnesini bir bölümden siler.

Bildirim Bağlantı Noktaları

Bildirim bağlantı noktası, bir bölüm eşleşen bir olay oluşturduğunda bir Windows olay nesnesine sinyal gönderir.

Bildirim bağlantı noktası veri türleri hakkında daha fazla bilgi için: Bildirim Bağlantı Noktası Veri Türleri

İşlev	Description
WHvCreateNotificationPort	Bölüm eşleşen bir olay oluşturduğunda bir Windows olay nesnesine sinyal veren bir bildirim bağlantı noktası oluşturur.
WHvSetNotificationPortProperty	Mevcut bildirim bağlantı noktasında bir özellik ayarlar.
WHvDeleteNotificationPort	Bildirim bağlantı noktasını siler.

Sanal PCI (VPCI) Cihazları

Windows Hiper Yönetici Platformu, fiziksel bir PCI cihazını bir bölüme sanal PCI (VPCI) cihazı olarak atayabilir. Bu işlevler yedekleme kaynaklarını ayırır, VPCI cihazları oluşturur ve siler, özelliklerini ve bildirimlerini sorgular, MMIO aralıklarını eşler, güç durumlarını yönetir ve kayıtlarına erişer.

VPCI veri türleri hakkında daha fazla bilgi için: Sanal PCI Veri Türleri

İşlev	Description
WHvAllocateVpciResource	Bir sanal cihazı yedeklemek için bir sanal PCI (VPCI) kaynağı ayırır.
WHvCreateVpciDevice	Bir sanal PCI (VPCI) cihazı oluşturur ve kaynaklarını bir bölüme atar.
WHvDeleteVpciDevice	Bir sanal PCI (VPCI) cihazını yok eder ve kaynaklarını serbest bırakır.
WHvGetVpciDeviceProperty	Sanal PCI (VPCI) cihazının özelliğini alır.
WHvGetVpciDeviceNotification	Sanal PCI (VPCI) cihazı için bir sonraki bekleyen bildirimi alır.
WHvMapVpciDeviceMmioRanges	Sanal PCI (VPCI) cihazının MMIO aralıklarını çağıranın işlemine eşler.
WHvUnmapVpciDeviceMmioRanges	Sanal PCI (VPCI) cihazının MMIO aralıklarını çağıranın işleminden kaldırır.
WHvSetVpciDevicePowerState	Sanal PCI (VPCI) cihazının güç durumunu değiştirir.
WHvReadVpciDeviceRegister	Bir sanal PCI (VPCI) cihazının yapılandırma alanını veya MMIO kaydını okur.
WHvWriteVpciDeviceRegister	Bir sanal PCI (VPCI) cihazının yapılandırma alanını veya MMIO kaydını yazar.

Sanal PCI (VPCI) Cihaz Kesintileri

Bu işlevler, atanan bir sanal PCI cihazının MSI ve MSI-X kesmelerini eşler, eşler, yeniden hedef alır, istekte bulunur ve sorgular.

İşlev	Description
WHvMapVpciDeviceInterrupt	Atanan bir sanal PCI cihazı için MSI veya MSI-X kesmesini eşler ve MSI adresini ve verileri cihaza programlayarak döndürür.
WHvUnmapVpciDeviceInterrupt	Atanmış bir sanal PCI cihazı için önceden eşlenmiş kesmeyi kaldırır.
WHvRetargetVpciDeviceInterrupt	Atanmış bir sanal PCI cihazının önceden eşlenmiş kesmesi için hedef vektör ve işlemci kümesini değiştirir.
WHvRequestVpciDeviceInterrupt	Atanmış bir sanal PCI cihazının sahibi olan bölüme mantıksal bir kesme sağlar.
WHvGetVpciDeviceInterruptTarget	Atanmış bir sanal PCI cihazı için eşlenmiş kesmenin geçerli vektör ve işlemci kümesini sorgular.