include/xen/interface/vcpu.h

   1 /******************************************************************************
   2  * vcpu.h
   3  *
   4  * VCPU initialisation, query, and hotplug.
   5  *
   6  * Copyright (c) 2005, Keir Fraser <keir@xensource.com>
   7  */
   8
   9 #ifndef __XEN_PUBLIC_VCPU_H__
  10 #define __XEN_PUBLIC_VCPU_H__
  11
  12 /*
  13  * Prototype for this hypercall is:
  14  *  int vcpu_op(int cmd, int vcpuid, void *extra_args)
  15  * @cmd        == VCPUOP_??? (VCPU operation).
  16  * @vcpuid     == VCPU to operate on.
  17  * @extra_args == Operation-specific extra arguments (NULL if none).
  18  */
  19
  20 /*
  21  * Initialise a VCPU. Each VCPU can be initialised only once. A
  22  * newly-initialised VCPU will not run until it is brought up by VCPUOP_up.
  23  *
  24  * @extra_arg == pointer to vcpu_guest_context structure containing initial
  25  *               state for the VCPU.
  26  */
  27 #define VCPUOP_initialise           0
  28
  29 /*
  30  * Bring up a VCPU. This makes the VCPU runnable. This operation will fail
  31  * if the VCPU has not been initialised (VCPUOP_initialise).
  32  */
  33 #define VCPUOP_up                   1
  34
  35 /*
  36  * Bring down a VCPU (i.e., make it non-runnable).
  37  * There are a few caveats that callers should observe:
  38  *  1. This operation may return, and VCPU_is_up may return false, before the
  39  *     VCPU stops running (i.e., the command is asynchronous). It is a good
  40  *     idea to ensure that the VCPU has entered a non-critical loop before
  41  *     bringing it down. Alternatively, this operation is guaranteed
  42  *     synchronous if invoked by the VCPU itself.
  43  *  2. After a VCPU is initialised, there is currently no way to drop all its
  44  *     references to domain memory. Even a VCPU that is down still holds
  45  *     memory references via its pagetable base pointer and GDT. It is good
  46  *     practise to move a VCPU onto an 'idle' or default page table, LDT and
  47  *     GDT before bringing it down.
  48  */
  49 #define VCPUOP_down                 2
  50
  51 /* Returns 1 if the given VCPU is up. */
  52 #define VCPUOP_is_up                3
  53
  54 /*
  55  * Return information about the state and running time of a VCPU.
  56  * @extra_arg == pointer to vcpu_runstate_info structure.
  57  */
  58 #define VCPUOP_get_runstate_info    4
  59 struct vcpu_runstate_info {
  60     /* VCPU's current state (RUNSTATE_*). */
  61     int      state;
  62     /* When was current state entered (system time, ns)? */
  63     uint64_t state_entry_time;
  64     /*
  65      * Time spent in each RUNSTATE_* (ns). The sum of these times is
  66      * guaranteed not to drift from system time.
  67      */
  68     uint64_t time[4];
  69 };
  70 typedef struct vcpu_runstate_info vcpu_runstate_info_t;
  71
  72 /* VCPU is currently running on a physical CPU. */
  73 #define RUNSTATE_running  0
  74
  75 /* VCPU is runnable, but not currently scheduled on any physical CPU. */
  76 #define RUNSTATE_runnable 1
  77
  78 /* VCPU is blocked (a.k.a. idle). It is therefore not runnable. */
  79 #define RUNSTATE_blocked  2
  80
  81 /*
  82  * VCPU is not runnable, but it is not blocked.
  83  * This is a 'catch all' state for things like hotplug and pauses by the
  84  * system administrator (or for critical sections in the hypervisor).
  85  * RUNSTATE_blocked dominates this state (it is the preferred state).
  86  */
  87 #define RUNSTATE_offline  3
  88
  89 /*
  90  * Register a shared memory area from which the guest may obtain its own
  91  * runstate information without needing to execute a hypercall.
  92  * Notes:
  93  *  1. The registered address may be virtual or physical, depending on the
  94  *     platform. The virtual address should be registered on x86 systems.
  95  *  2. Only one shared area may be registered per VCPU. The shared area is
  96  *     updated by the hypervisor each time the VCPU is scheduled. Thus
  97  *     runstate.state will always be RUNSTATE_running and
  98  *     runstate.state_entry_time will indicate the system time at which the
  99  *     VCPU was last scheduled to run.
 100  * @extra_arg == pointer to vcpu_register_runstate_memory_area structure.
 101  */
 102 #define VCPUOP_register_runstate_memory_area 5
 103 struct vcpu_register_runstate_memory_area {
 104     union {
 105         struct vcpu_runstate_info *v;
 106         uint64_t p;
 107     } addr;
 108 };
 109 typedef struct vcpu_register_runstate_memory_area vcpu_register_runstate_memory_area_t;
 110
 111 #endif /* __XEN_PUBLIC_VCPU_H__ */
 112
 113 /*
 114  * Local variables:
 115  * mode: C
 116  * c-set-style: "BSD"
 117  * c-basic-offset: 4
 118  * tab-width: 4
 119  * indent-tabs-mode: nil
 120  * End:
 121  */