Skip to contentSkip to conversation

Documentation/kvm : Add documentation on Hypercalls

PATCH In review Raghavendra K T 5 participants 8 messages May 31, 2012 – Jun 4, 2012

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation/kvm : Add documentation on Hypercalls

From: Raghavendra K T <[email protected]>

Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ

---

Documentation/virtual/kvm/hypercalls.txt new file +46 -0
new file mode 100644
index 0000000..c79335a
@@ -0,0 +1,46 @@
+KVM Hypercalls Documentation
+===========================
+The template for each hypercall is:
+1. Hypercall name, value.
+2. Architecture(s)
+3. Status (deprecated, obsolete, active)
+4. Purpose
+
+1. KVM_HC_VAPIC_POLL_IRQ
+------------------------
+Value: 1
+Architecture: x86
+Purpose: Trigger guest exit so that the host can check for pending
+interrupts on reentry.
+
+2. KVM_HC_MMU_OP
+------------------------
+Value: 2
+Architecture: x86
+Status: deprecated.
+Purpose: Support MMU operations such as writing to PTE,
+flushing TLB, release PT.
+
+3. KVM_HC_FEATURES
+------------------------
+Value: 3
+Architecture: PPC
+Status: active
+Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
+used to enumerate which hypercalls are available. On PPC, either device tree
+based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
+mechanism (which is this hypercall) can be used.
+
+4. KVM_HC_PPC_MAP_MAGIC_PAGE
+------------------------
+Value: 4
+Architecture: PPC
+Status: active
+Purpose: To enable communication between the hypervisor and guest there is a
+shared page that contains parts of supervisor visible register state.
+The guest can map this shared page to access its supervisor register through
+memory using this hypercall.
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.
#1 lore raw
Quoted 14 lines · Raghavendra K T

From: Raghavendra K T <[email protected]>

Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ

---

Documentation/virtual/kvm/hypercalls.txt new file +2 -0
new file mode 100644
index 0000000..c79335a
@@ -0,0 +1,46 @@
+KVM Hypercalls Documentation
+===========================

Documentation/virtual/kvm/hypercalls.txt line 12

Quoted 10 lines
Documentation/virtual/kvm/hypercalls.txt new file +10 -0
+The template for each hypercall is:
+1. Hypercall name, value.
+2. Architecture(s)
+3. Status (deprecated, obsolete, active)
+4. Purpose
+
+1. KVM_HC_VAPIC_POLL_IRQ
+------------------------
+Value: 1
+Architecture: x86

No "Status", does that imply "Active" ?

Quoted 36 lines
Documentation/virtual/kvm/hypercalls.txt new file +34 -1
+Purpose: Trigger guest exit so that the host can check for pending
+interrupts on reentry.
+
+2. KVM_HC_MMU_OP
+------------------------
+Value: 2
+Architecture: x86
+Status: deprecated.
+Purpose: Support MMU operations such as writing to PTE,
+flushing TLB, release PT.
+
+3. KVM_HC_FEATURES
+------------------------
+Value: 3
+Architecture: PPC
+Status: active
+Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
+used to enumerate which hypercalls are available. On PPC, either device tree
+based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
+mechanism (which is this hypercall) can be used.
+
+4. KVM_HC_PPC_MAP_MAGIC_PAGE
+------------------------
+Value: 4
+Architecture: PPC
+Status: active
+Purpose: To enable communication between the hypervisor and guest there is a
+shared page that contains parts of supervisor visible register state.
+The guest can map this shared page to access its supervisor register through
+memory using this hypercall.
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.
 
--
Signature · 1 line
~Randy
#5 lore raw
In reply to Raghavendra K T

Documentation/virtual/kvm/hypercalls.txt line 46

Quoted 5 lines · Raghavendra K T
Documentation/virtual/kvm/hypercalls.txt new file +4 -0
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.

1. definitely, including the hypercall ABI.

-hpa

Signature · 2 lines
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.
#2 lore raw
In reply to Randy Dunlap
Quoted 21 lines · Randy Dunlap
Quoted 19 lines · Raghavendra K T

From: Raghavendra K T <[email protected]>

Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ

---

Documentation/virtual/kvm/hypercalls.txt new file +7 -0
new file mode 100644
index 0000000..c79335a
@@ -0,0 +1,46 @@
+KVM Hypercalls Documentation
+===========================
+The template for each hypercall is:
+1. Hypercall name, value.
+2. Architecture(s)
+3. Status (deprecated, obsolete, active)
+4. Purpose
Quoted 8 lines

Documentation/virtual/kvm/hypercalls.txt line 12

Quoted 5 lines
Documentation/virtual/kvm/hypercalls.txt new file +5 -0
+
+1. KVM_HC_VAPIC_POLL_IRQ
+------------------------
+Value: 1
+Architecture: x86

No "Status", does that imply "Active" ?

It should actually state that this call is in use.

Jan

Signature · 2 lines
Siemens AG, Corporate Technology, CT T DE IT 1
Corporate Competence Center Embedded Linux
#3 lore raw
Quoted 5 lines · Jan Kiszka
Quoted 2 lines

No "Status", does that imply "Active" ?

It should actually state that this call is in use.

It might be nice to point out when a call was introduced, and for deprecated calls, when it was deprecated.

-hpa

Signature · 2 lines
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.
#6 lore raw
In reply to H. Peter Anvin
Quoted 11 lines · H. Peter Anvin

Documentation/virtual/kvm/hypercalls.txt line 46

Quoted 5 lines · Raghavendra K T
Documentation/virtual/kvm/hypercalls.txt new file +4 -0
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.

1. definitely, including the hypercall ABI.

-hpa

I was wondering about that. It looks like Documentation/virtual/kvm/api.txt might cover some of that already in section 5, but it doesn't look complete...

Also, could I get a 00-INDEX file for this directory explaining what these individual files are? I think "api.txt" is supposed to be host-side API for controlling a guest VM (from userspace via ioctls, looks like), and hypercalls.txt is guest-side API for poking the host. How someone would write host-side code that _responds_ to a hypercall, I have no idea. (It goes in the host kernel?)

Rob

Signature · 2 lines
GNU/Linux isn't: Linux=GPLv2, GNU=GPLv3+, they can't share code.
Either it's "mere aggregation", or a license violation.  Pick one.
#7 lore raw
Quoted 13 lines · Rob Landley
Quoted 11 lines · H. Peter Anvin

Documentation/virtual/kvm/hypercalls.txt line 46

Quoted 5 lines · Raghavendra K T
Documentation/virtual/kvm/hypercalls.txt new file +4 -0
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.

1. definitely, including the hypercall ABI.

-hpa

Quoted 8 lines

I was wondering about that. It looks like Documentation/virtual/kvm/api.txt might cover some of that already in section 5, but it doesn't look complete...

Also, could I get a 00-INDEX file for this directory explaining what these individual files are? I think "api.txt" is supposed to be host-side API for controlling a guest VM (from userspace via ioctls, looks like),

api.txt has plenty of information apart from features which are related to guest side api (generally controls / knows PV features available, that may also involve host query of guest cpuid). and capability (of) related to host.

and hypercalls.txt is guest-side API for poking the host.

hypercall can be used to take some actions (as needed by guest / exchange information)

Quoted 5 lines

How someone would write host-side code that _responds_ to a hypercall, I have no idea. (It goes in the host kernel?)

Rob

#4 lore raw
In reply to Randy Dunlap
Quoted 21 lines · Randy Dunlap
Quoted 19 lines · Raghavendra K T

From: Raghavendra K T<[email protected]>

Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ

---

Documentation/virtual/kvm/hypercalls.txt new file +7 -0
new file mode 100644
index 0000000..c79335a
@@ -0,0 +1,46 @@
+KVM Hypercalls Documentation
+===========================
+The template for each hypercall is:
+1. Hypercall name, value.
+2. Architecture(s)
+3. Status (deprecated, obsolete, active)
+4. Purpose
Quoted 9 lines

Documentation/virtual/kvm/hypercalls.txt line 12

Quoted 5 lines
Documentation/virtual/kvm/hypercalls.txt new file +5 -0
+
+1. KVM_HC_VAPIC_POLL_IRQ
+------------------------
+Value: 1
+Architecture: x86

No "Status", does that imply "Active" ?

Oh! It was unintentionally left out. will add that.