On 03/31/2017 06:06 PM, Andrew Jones wrote: > Signed-off-by: Andrew Jones <drjones@xxxxxxxxxx> > --- > Documentation/virtual/kvm/vcpu-requests.rst | 114 ++++++++++++++++++++++++++++ > 1 file changed, 114 insertions(+) > create mode 100644 Documentation/virtual/kvm/vcpu-requests.rst > > diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst > new file mode 100644 > index 000000000000..ea4a966d5c8a > --- /dev/null > +++ b/Documentation/virtual/kvm/vcpu-requests.rst > @@ -0,0 +1,114 @@ > +================= > +KVM VCPU Requests > +================= > + > +Overview > +======== > + > +KVM supports an internal API enabling threads to request a VCPU thread to > +perform some activity. For example, a thread may request a VCPU to flush > +its TLB with a VCPU request. The API consists of only four calls:: > + > + /* Check if VCPU @vcpu has request @req pending. Clears the request. */ > + bool kvm_check_request(int req, struct kvm_vcpu *vcpu); > + > + /* Check if any requests are pending for VCPU @vcpu. */ > + bool kvm_request_pending(struct kvm_vcpu *vcpu); > + > + /* Make request @req of VCPU @vcpu. */ > + void kvm_make_request(int req, struct kvm_vcpu *vcpu); > + > + /* Make request @req of all VCPUs of the VM with struct kvm @kvm. */ > + bool kvm_make_all_cpus_request(struct kvm *kvm, unsigned int req); > + > +Typically a requester wants the VCPU to perform the activity as soon > +as possible after making the request. This means most requests, > +kvm_make_request() calls, are followed by a call to kvm_vcpu_kick(), > +and kvm_make_all_cpus_request() has the kicking of all VCPUs built > +into it. > + > +VCPU Kicks > +---------- > + > +A VCPU kick does one of three things: > + > + 1) wakes a sleeping VCPU (which sleeps outside guest mode). > + 2) sends an IPI to a VCPU currently in guest mode, in order to bring it > + out. > + 3) nothing, when the VCPU is already outside guest mode and not sleeping. > + > +VCPU Request Internals > +====================== > + > +VCPU requests are simply bit indices of the vcpu->requests bitmap. This > +means general bitops[1], e.g. clear_bit(KVM_REQ_UNHALT, &vcpu->requests), > +may also be used. The first 8 bits are reserved for architecture > +independent requests, all additional bits are available for architecture > +dependent requests. > + > +VCPU Requests with Associated State > +=================================== > + > +Requesters that want the requested VCPU to handle new state need to ensure > +the state is observable to the requested VCPU thread's CPU at the time the > +CPU observes the request. This means a write memory barrier should be > +insert between the preparation of the state and the write of the VCPU > +request bitmap. Additionally, on the requested VCPU thread's side, a > +corresponding read barrier should be issued after reading the request bit > +and before proceeding to use the state associated with it. See the kernel > +memory barrier documentation [2]. > + > +VCPU Requests and Guest Mode > +============================ FWIW, s390 does not implement the guest mode. Maybe add some words that not all architectures implement that? Or do we expect Radims rework soon?
