1syntax = 'proto3';
2
3package vmservice;
4option go_package = "github.com/Microsoft/hcsshim/internal/vmservice";
5
6import "google/protobuf/empty.proto";
7import "google/protobuf/struct.proto";
8
9service VM {
10 // CreateVM will create the virtual machine with the configuration in the
11 // CreateVMRequest. The virtual machine will be in a paused state power wise
12 // after CreateVM. ResumeVM can be called to transition the VM into a running state.
13 rpc CreateVM(CreateVMRequest) returns (google.protobuf.Empty);
14
15 // TeardownVM will release all associated resources from the VM and unblock the WaitVM call.
16 rpc TeardownVM(google.protobuf.Empty) returns (google.protobuf.Empty);
17
18 // PauseVM will, if the virtual machine power state is in a running state, transition
19 // the state to paused. This is the same state power wise that the VM should be in after
20 // an initial CreateVM call.
21 rpc PauseVM(google.protobuf.Empty) returns (google.protobuf.Empty);
22
23 // ResumeVM is used to transition a vm to a running state. This can be used to resume a VM that
24 // has had PauseVM called on it, or to start a VM that was created with CreateVM.
25 rpc ResumeVM(google.protobuf.Empty) returns (google.protobuf.Empty);
26
27 // WaitVM will block until the VM is either in a halted state or has had all of it's resources freed
28 // via TeardownVM.
29 rpc WaitVM(google.protobuf.Empty) returns (google.protobuf.Empty);
30
31 // InspectVM is used to inspect virtual machine state. The query of what to inspect
32 // is passed in as a string and the response can be of any form.
33 rpc InspectVM(InspectVMRequest) returns (InspectVMResponse);
34
35 // CapabilitiesVM will return what capabilities the virtstack supports. This includes
36 // what guest operating systems are supported, what resources are supported, and if hot
37 // add/hot remove of a resource is supported.
38 rpc CapabilitiesVM(google.protobuf.Empty) returns (CapabilitiesVMResponse);
39
40 // PropertiesVM will take in a list of properties that the virtstack will return
41 // statistics for (memory, processors).
42 rpc PropertiesVM(PropertiesVMRequest) returns (PropertiesVMResponse);
43
44 // ModifyResource is a generic call to modify (add/remove/update) resources for a VM.
45 // This includes things such as block devices, network adapters, and pci devices.
46 rpc ModifyResource(ModifyResourceRequest) returns (google.protobuf.Empty);
47
48 // VMSocket is an abstraction around a hypervisor socket transport to facilitate communication
49 // between virtual machines and the host they are running on. The supported transports are
50 // HvSocket and Vsock.
51 rpc VMSocket(VMSocketRequest) returns (google.protobuf.Empty);
52
53 // Quit will shutdown the process hosting the ttrpc server.
54 rpc Quit(google.protobuf.Empty) returns (google.protobuf.Empty);
55}
56
57message DirectBoot {
58 string kernel_path = 1;
59 string initrd_path = 2;
60 string kernel_cmdline = 3;
61}
62
63message UEFI {
64 string firmware_path = 1;
65 string device_path = 2;
66 // Optional data to include for uefi boot. For Linux this could be used as the kernel
67 // commandline.
68 string optional_data = 3;
69}
70
71message MemoryConfig {
72 uint64 memory_mb = 1;
73 bool allow_overcommit = 2;
74 bool deferred_commit = 3;
75 bool hot_hint = 4;
76 bool cold_hint = 5;
77 bool cold_discard_hint = 6;
78 uint64 low_mmio_gap_in_mb = 7;
79 uint64 high_mmio_base_in_mb = 8;
80 uint64 high_mmio_gap_in_mb = 9;
81}
82
83message ProcessorConfig {
84 uint32 processor_count = 1;
85 uint32 processor_weight = 2;
86 uint32 processor_limit = 3;
87}
88
89message DevicesConfig {
90 repeated SCSIDisk scsi_disks = 1;
91 repeated VPMEMDisk vpmem_disks = 2;
92 repeated NICConfig nic_config = 3;
93 repeated WindowsPCIDevice windows_device = 4;
94}
95
96message VMConfig {
97 MemoryConfig memory_config = 1;
98 ProcessorConfig processor_config = 2;
99 DevicesConfig devices_config = 3;
100 SerialConfig serial_config = 4;
101 oneof BootConfig {
102 DirectBoot direct_boot = 5;
103 UEFI uefi = 6;
104 }
105 WindowsOptions windows_options = 7;
106 // Optional k:v extra data. Up to the virtstack for how to interpret this.
107 map<string, string> extra_data = 8;
108}
109
110// WindowsOptions contains virtual machine configurations that are only present on a Windows host.
111message WindowsOptions {
112 uint64 cpu_group_id = 1;
113}
114
115message SerialConfig {
116 message Config {
117 uint32 port = 1;
118 // Unix domain socket to relay serial console output to.
119 string socket_path = 2;
120 }
121 repeated Config ports = 3;
122}
123
124message CreateVMRequest {
125 VMConfig config = 1;
126 // Optional ID to be used by the VM service in log messages. It's up to the
127 // virtstack to make use of this field. Useful for debugging to be able to
128 // correlate events for a given vm that the client launched.
129 string log_id = 2;
130}
131message InspectVMRequest {
132 string query = 1;
133 uint32 recursion_limit = 2;
134}
135
136message InspectVMResponse {
137 google.protobuf.Value result = 1;
138}
139
140message MemoryStats {
141 uint64 working_set_bytes = 1;
142 uint64 available_memory = 2;
143 uint64 reserved_memory = 3;
144 uint64 assigned_memory = 4;
145}
146
147message ProcessorStats {
148 uint64 total_runtime_ns = 1;
149}
150
151message PropertiesVMRequest {
152 enum PropertiesType {
153 Memory = 0;
154 Processor = 1;
155 }
156 repeated PropertiesType types = 1;
157}
158
159message PropertiesVMResponse {
160 MemoryStats memory_stats = 1;
161 ProcessorStats processor_stats = 2;
162}
163
164message CapabilitiesVMResponse {
165 enum Resource {
166 Vpmem = 0;
167 Scsi = 1;
168 Vpci = 2;
169 Plan9 = 3;
170 VMNic = 4;
171 Memory = 5;
172 Processor = 6;
173 }
174
175 message SupportedResource {
176 bool Add = 1;
177 bool Remove = 2;
178 bool Update = 3;
179 Resource resource = 4;
180 }
181
182 enum SupportedGuestOS {
183 Windows = 0;
184 Linux = 1;
185 }
186 repeated SupportedResource supported_resources = 1;
187 repeated SupportedGuestOS supported_guest_os = 2;
188}
189
190message HVSocketListen {
191 string service_id = 1;
192 // Expected that the listener is a unix domain socket. These
193 // are supported on Windows as of 1809/RS5.
194 string listener_path = 2;
195}
196
197message VSockListen {
198 uint32 port = 1;
199 string listener_path = 2;
200}
201
202message VMSocketRequest {
203 ModifyType type = 1;
204 oneof Config {
205 HVSocketListen hvsocket_list = 2;
206 VSockListen vsock_listen = 3;
207 }
208}
209
210enum ModifyType {
211 ADD = 0;
212 REMOVE = 1;
213 UPDATE = 2;
214}
215
216enum DiskType {
217 SCSI_DISK_TYPE_VHD1 = 0;
218 SCSI_DISK_TYPE_VHDX = 1;
219 SCSI_DISK_TYPE_PHYSICAL = 2;
220}
221
222message SCSIDisk {
223 uint32 controller = 1;
224 uint32 lun = 2;
225 string host_path = 3;
226 DiskType type = 4;
227 bool read_only = 5;
228}
229
230message VPMEMDisk {
231 string host_path = 1;
232 DiskType type = 2;
233 bool read_only = 3;
234}
235
236
237message NICConfig {
238 string nic_id = 1; // GUID
239 string port_id = 2; // GUID
240 string mac_address = 3; // 12-34-56-78-9A-BC
241 string switch_id = 4; // GUID
242 // Optional friendly name for the adapter. Might be useful to show up in logs.
243 string nic_name = 5;
244}
245
246message WindowsPCIDevice {
247 // e.g. PCIP\\VEN_10DE&DEV_13F2&SUBSYS_115E10DE&REV_A1\\6&17F903&0&00400000
248 string instance_id = 1;
249}
250
251message ModifyMemoryRequest {
252 uint64 memory_mb = 1;
253}
254
255message ModifyProcessorRequest {
256 // Index of the processor to add/remove
257 uint32 processor_index = 1;
258}
259
260message ModifyProcessorConfigRequest {
261 uint32 processor_weight = 1;
262 uint32 processor_limit = 2;
263}
264
265message ModifyResourceRequest {
266 ModifyType type = 1;
267 oneof resource {
268 ModifyProcessorRequest processor = 2;
269 ModifyProcessorConfigRequest processor_config = 3;
270 ModifyMemoryRequest memory = 4;
271 SCSIDisk scsi_disk = 5;
272 VPMEMDisk vpmem_disk = 6;
273 NICConfig nic_config = 7;
274 WindowsPCIDevice windows_device = 8;
275 }
276}View as plain text