1 /*
2 * libvirt-host.c: entry points for vir{Connect,Node}Ptr APIs
3 *
4 * Copyright (C) 2006-2015 Red Hat, Inc.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see
18 * <http://www.gnu.org/licenses/>.
19 */
20
21 #include <config.h>
22 #include <sys/stat.h>
23
24 #include "datatypes.h"
25 #include "viralloc.h"
26 #include "virlog.h"
27 #include "virtypedparam.h"
28
29 VIR_LOG_INIT("libvirt.host");
30
31 #define VIR_FROM_THIS VIR_FROM_DOMAIN
32
33
34 /**
35 * virConnectRef:
36 * @conn: the connection to hold a reference on
37 *
38 * Increment the reference count on the connection. For each
39 * additional call to this method, there shall be a corresponding
40 * call to virConnectClose to release the reference count, once
41 * the caller no longer needs the reference to this object.
42 *
43 * This method is typically useful for applications where multiple
44 * threads are using a connection, and it is required that the
45 * connection remain open until all threads have finished using
46 * it. ie, each new thread using a connection would increment
47 * the reference count.
48 *
49 * Returns 0 in case of success, -1 in case of failure
50 */
51 int
virConnectRef(virConnectPtr conn)52 virConnectRef(virConnectPtr conn)
53 {
54 VIR_DEBUG("conn=%p", conn);
55
56 virResetLastError();
57
58 virCheckConnectReturn(conn, -1);
59 virObjectRef(conn);
60 return 0;
61 }
62
63
64 /**
65 * virConnectSetIdentity:
66 * @conn: pointer to the hypervisor connection
67 * @params: parameters containing the identity attributes
68 * @nparams: size of @params array
69 * @flags: currently unused, pass 0
70 *
71 * Override the default identity information associated with
72 * the connection. When connecting to a stateful driver over
73 * a UNIX socket, the daemon will interrogate the remote end
74 * of the UNIX socket to acquire the application's identity.
75 * This identity is used for the fine grained access control
76 * checks on API calls.
77 *
78 * There may be times when application is operating on behalf
79 * of a variety of users, and thus the identity that the
80 * application runs as is not appropriate for access control
81 * checks. In this case, if the application is considered
82 * trustworthy, it can supply alternative identity information.
83 *
84 * The driver may reject the request to change the identity
85 * on a connection if the application is not trustworthy.
86 *
87 * Returns: 0 if the identity change was accepted, -1 on error
88 */
89 int
virConnectSetIdentity(virConnectPtr conn,virTypedParameterPtr params,int nparams,unsigned int flags)90 virConnectSetIdentity(virConnectPtr conn,
91 virTypedParameterPtr params,
92 int nparams,
93 unsigned int flags)
94 {
95 VIR_DEBUG("conn=%p params=%p nparams=%d flags=0x%x", conn, params, nparams, flags);
96 VIR_TYPED_PARAMS_DEBUG(params, nparams);
97
98 virResetLastError();
99
100 if (conn->driver->connectSetIdentity) {
101 int ret = conn->driver->connectSetIdentity(conn, params, nparams, flags);
102 if (ret < 0)
103 goto error;
104 return ret;
105 }
106
107 virReportUnsupportedError();
108
109 error:
110 virDispatchError(conn);
111 return -1;
112 }
113
114
115 /*
116 * Not for public use. This function is part of the internal
117 * implementation of driver features in the remote case.
118 */
119 int
virConnectSupportsFeature(virConnectPtr conn,int feature)120 virConnectSupportsFeature(virConnectPtr conn, int feature)
121 {
122 int ret;
123 VIR_DEBUG("conn=%p, feature=%d", conn, feature);
124
125 virResetLastError();
126
127 virCheckConnectReturn(conn, -1);
128
129 if (!conn->driver->connectSupportsFeature)
130 ret = 0;
131 else
132 ret = conn->driver->connectSupportsFeature(conn, feature);
133
134 if (ret < 0)
135 virDispatchError(conn);
136
137 return ret;
138 }
139
140
141 /**
142 * virConnectGetType:
143 * @conn: pointer to the hypervisor connection
144 *
145 * Get the name of the Hypervisor driver used. This is merely the driver
146 * name; for example, both KVM and QEMU guests are serviced by the
147 * driver for the qemu:// URI, so a return of "QEMU" does not indicate
148 * whether KVM acceleration is present. For more details about the
149 * hypervisor, use virConnectGetCapabilities().
150 *
151 * Returns NULL in case of error, a static zero terminated string otherwise.
152 */
153 const char *
virConnectGetType(virConnectPtr conn)154 virConnectGetType(virConnectPtr conn)
155 {
156 const char *ret;
157 VIR_DEBUG("conn=%p", conn);
158
159 virResetLastError();
160
161 virCheckConnectReturn(conn, NULL);
162
163 if (conn->driver->connectGetType) {
164 ret = conn->driver->connectGetType(conn);
165 if (ret) return ret;
166 }
167 return conn->driver->name;
168 }
169
170
171 /**
172 * virConnectGetVersion:
173 * @conn: pointer to the hypervisor connection
174 * @hvVer: return value for the version of the running hypervisor (OUT)
175 *
176 * Get the version level of the Hypervisor running. This may work only with
177 * hypervisor call, i.e. with privileged access to the hypervisor, not
178 * with a Read-Only connection.
179 *
180 * Returns -1 in case of error, 0 otherwise. if the version can't be
181 * extracted by lack of capacities returns 0 and @hvVer is 0, otherwise
182 * @hvVer value is major * 1,000,000 + minor * 1,000 + release
183 */
184 int
virConnectGetVersion(virConnectPtr conn,unsigned long * hvVer)185 virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
186 {
187 VIR_DEBUG("conn=%p, hvVer=%p", conn, hvVer);
188
189 virResetLastError();
190
191 virCheckConnectReturn(conn, -1);
192 virCheckNonNullArgGoto(hvVer, error);
193
194 if (conn->driver->connectGetVersion) {
195 int ret = conn->driver->connectGetVersion(conn, hvVer);
196 if (ret < 0)
197 goto error;
198 return ret;
199 }
200
201 virReportUnsupportedError();
202
203 error:
204 virDispatchError(conn);
205 return -1;
206 }
207
208
209 /**
210 * virConnectGetLibVersion:
211 * @conn: pointer to the hypervisor connection
212 * @libVer: returns the libvirt library version used on the connection (OUT)
213 *
214 * Provides @libVer, which is the version of libvirt used by the
215 * daemon running on the @conn host
216 *
217 * Returns -1 in case of failure, 0 otherwise, and values for @libVer have
218 * the format major * 1,000,000 + minor * 1,000 + release.
219 */
220 int
virConnectGetLibVersion(virConnectPtr conn,unsigned long * libVer)221 virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
222 {
223 int ret = -1;
224 VIR_DEBUG("conn=%p, libVir=%p", conn, libVer);
225
226 virResetLastError();
227
228 virCheckConnectReturn(conn, -1);
229 virCheckNonNullArgGoto(libVer, error);
230
231 if (conn->driver->connectGetLibVersion) {
232 ret = conn->driver->connectGetLibVersion(conn, libVer);
233 if (ret < 0)
234 goto error;
235 return ret;
236 }
237
238 *libVer = LIBVIR_VERSION_NUMBER;
239 return 0;
240
241 error:
242 virDispatchError(conn);
243 return ret;
244 }
245
246
247 /**
248 * virConnectGetHostname:
249 * @conn: pointer to a hypervisor connection
250 *
251 * This returns a system hostname on which the hypervisor is
252 * running (based on the result of the gethostname system call, but
253 * possibly expanded to a fully-qualified domain name via getaddrinfo).
254 * If we are connected to a remote system, then this returns the
255 * hostname of the remote system.
256 *
257 * Returns the hostname which must be freed by the caller, or
258 * NULL if there was an error.
259 */
260 char *
virConnectGetHostname(virConnectPtr conn)261 virConnectGetHostname(virConnectPtr conn)
262 {
263 VIR_DEBUG("conn=%p", conn);
264
265 virResetLastError();
266
267 virCheckConnectReturn(conn, NULL);
268
269 if (conn->driver->connectGetHostname) {
270 char *ret = conn->driver->connectGetHostname(conn);
271 if (!ret)
272 goto error;
273 return ret;
274 }
275
276 virReportUnsupportedError();
277
278 error:
279 virDispatchError(conn);
280 return NULL;
281 }
282
283
284 /**
285 * virConnectGetURI:
286 * @conn: pointer to a hypervisor connection
287 *
288 * This returns the URI (name) of the hypervisor connection.
289 * Normally this is the same as or similar to the string passed
290 * to the virConnectOpen/virConnectOpenReadOnly call, but
291 * the driver may make the URI canonical. If name == NULL
292 * was passed to virConnectOpen, then the driver will return
293 * a non-NULL URI which can be used to connect to the same
294 * hypervisor later.
295 *
296 * Returns the URI string which must be freed by the caller, or
297 * NULL if there was an error.
298 */
299 char *
virConnectGetURI(virConnectPtr conn)300 virConnectGetURI(virConnectPtr conn)
301 {
302 char *name;
303 VIR_DEBUG("conn=%p", conn);
304
305 virResetLastError();
306
307 virCheckConnectReturn(conn, NULL);
308
309 if (!(name = virURIFormat(conn->uri)))
310 goto error;
311
312 return name;
313
314 error:
315 virDispatchError(conn);
316 return NULL;
317 }
318
319
320 /**
321 * virConnectGetSysinfo:
322 * @conn: pointer to a hypervisor connection
323 * @flags: extra flags; not used yet, so callers should always pass 0
324 *
325 * This returns the XML description of the sysinfo details for the
326 * host on which the hypervisor is running, in the same format as the
327 * <sysinfo> element of a domain XML. This information is generally
328 * available only for hypervisors running with root privileges.
329 *
330 * Returns the XML string which must be freed by the caller, or
331 * NULL if there was an error.
332 */
333 char *
virConnectGetSysinfo(virConnectPtr conn,unsigned int flags)334 virConnectGetSysinfo(virConnectPtr conn, unsigned int flags)
335 {
336 VIR_DEBUG("conn=%p, flags=0x%x", conn, flags);
337
338 virResetLastError();
339
340 virCheckConnectReturn(conn, NULL);
341
342 if (conn->driver->connectGetSysinfo) {
343 char *ret = conn->driver->connectGetSysinfo(conn, flags);
344 if (!ret)
345 goto error;
346 return ret;
347 }
348
349 virReportUnsupportedError();
350
351 error:
352 virDispatchError(conn);
353 return NULL;
354 }
355
356
357 /**
358 * virConnectGetMaxVcpus:
359 * @conn: pointer to the hypervisor connection
360 * @type: value of the 'type' attribute in the <domain> element
361 *
362 * Provides the maximum number of virtual CPUs supported for a guest VM of a
363 * specific type. The 'type' parameter here corresponds to the 'type'
364 * attribute in the <domain> element of the XML. This API doesn't take emulator
365 * limits into consideration, hence the returned value is not guaranteed to be
366 * usable. It is recommended to use virConnectGetDomainCapabilities() and look
367 * for "<vcpu max='...'>" in its output instead.
368 *
369 * Returns the maximum of virtual CPU or -1 in case of error.
370 */
371 int
virConnectGetMaxVcpus(virConnectPtr conn,const char * type)372 virConnectGetMaxVcpus(virConnectPtr conn,
373 const char *type)
374 {
375 VIR_DEBUG("conn=%p, type=%s", conn, NULLSTR(type));
376
377 virResetLastError();
378
379 virCheckConnectReturn(conn, -1);
380
381 if (conn->driver->connectGetMaxVcpus) {
382 int ret = conn->driver->connectGetMaxVcpus(conn, type);
383 if (ret < 0)
384 goto error;
385 return ret;
386 }
387
388 virReportUnsupportedError();
389 error:
390 virDispatchError(conn);
391 return -1;
392 }
393
394
395 /**
396 * virNodeGetInfo:
397 * @conn: pointer to the hypervisor connection
398 * @info: pointer to a virNodeInfo structure allocated by the user
399 *
400 * Extract hardware information about the node.
401 *
402 * Use of this API is strongly discouraged as the information provided
403 * is not guaranteed to be accurate on all hardware platforms.
404 *
405 * The mHZ value merely reflects the speed that the first CPU in the
406 * machine is currently running at. This speed may vary across CPUs
407 * and changes continually as the host OS throttles.
408 *
409 * The nodes/sockets/cores/threads data is potentially inaccurate as
410 * it assumes a symmetric installation. If one NUMA node has more
411 * sockets populated that another NUMA node this information will be
412 * wrong. It is also not able to report about CPU dies.
413 *
414 * Applications are recommended to use the virConnectGetCapabilities()
415 * call instead, which provides all the information except CPU mHZ,
416 * in a more accurate representation.
417 *
418 * Returns 0 in case of success and -1 in case of failure.
419 */
420 int
virNodeGetInfo(virConnectPtr conn,virNodeInfoPtr info)421 virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
422 {
423 VIR_DEBUG("conn=%p, info=%p", conn, info);
424
425 virResetLastError();
426
427 virCheckConnectReturn(conn, -1);
428 virCheckNonNullArgGoto(info, error);
429
430 if (conn->driver->nodeGetInfo) {
431 int ret;
432 ret = conn->driver->nodeGetInfo(conn, info);
433 if (ret < 0)
434 goto error;
435 return ret;
436 }
437
438 virReportUnsupportedError();
439
440 error:
441 virDispatchError(conn);
442 return -1;
443 }
444
445
446 /**
447 * virConnectGetCapabilities:
448 * @conn: pointer to the hypervisor connection
449 *
450 * Provides capabilities of the hypervisor / driver.
451 *
452 * Returns NULL in case of error, or an XML string
453 * defining the capabilities.
454 * The client must free the returned string after use.
455 */
456 char *
virConnectGetCapabilities(virConnectPtr conn)457 virConnectGetCapabilities(virConnectPtr conn)
458 {
459 VIR_DEBUG("conn=%p", conn);
460
461 virResetLastError();
462
463 virCheckConnectReturn(conn, NULL);
464
465 if (conn->driver->connectGetCapabilities) {
466 char *ret;
467 ret = conn->driver->connectGetCapabilities(conn);
468 if (!ret)
469 goto error;
470 VIR_DEBUG("conn=%p ret=%s", conn, ret);
471 return ret;
472 }
473
474 virReportUnsupportedError();
475
476 error:
477 virDispatchError(conn);
478 return NULL;
479 }
480
481
482 /**
483 * virNodeGetCPUStats:
484 * @conn: pointer to the hypervisor connection.
485 * @cpuNum: number of node cpu. (VIR_NODE_CPU_STATS_ALL_CPUS means total cpu
486 * statistics)
487 * @params: pointer to node cpu time parameter objects
488 * @nparams: number of node cpu time parameter (this value should be same or
489 * less than the number of parameters supported)
490 * @flags: extra flags; not used yet, so callers should always pass 0
491 *
492 * This function provides individual cpu statistics of the node.
493 * If you want to get total cpu statistics of the node, you must specify
494 * VIR_NODE_CPU_STATS_ALL_CPUS to @cpuNum.
495 * The @params array will be filled with the values equal to the number of
496 * parameters suggested by @nparams
497 *
498 * As the value of @nparams is dynamic, call the API setting @nparams to 0 and
499 * @params as NULL, the API returns the number of parameters supported by the
500 * HV by updating @nparams on SUCCESS. The caller should then allocate @params
501 * array, i.e. (sizeof(@virNodeCPUStats) * @nparams) bytes and call
502 * the API again.
503 *
504 * Here is a sample code snippet:
505 *
506 * if (virNodeGetCPUStats(conn, cpuNum, NULL, &nparams, 0) == 0 &&
507 * nparams != 0) {
508 * if ((params = malloc(sizeof(virNodeCPUStats) * nparams)) == NULL)
509 * goto error;
510 * memset(params, 0, sizeof(virNodeCPUStats) * nparams);
511 * if (virNodeGetCPUStats(conn, cpuNum, params, &nparams, 0))
512 * goto error;
513 * }
514 *
515 * This function doesn't require privileged access to the hypervisor.
516 * This function expects the caller to allocate the @params.
517 *
518 * CPU time Statistics:
519 *
520 * VIR_NODE_CPU_STATS_KERNEL:
521 * The cumulative CPU time which spends by kernel,
522 * when the node booting up.(nanoseconds)
523 * VIR_NODE_CPU_STATS_USER:
524 * The cumulative CPU time which spends by user processes,
525 * when the node booting up.(nanoseconds)
526 * VIR_NODE_CPU_STATS_IDLE:
527 * The cumulative idle CPU time, when the node booting up.(nanoseconds)
528 * VIR_NODE_CPU_STATS_IOWAIT:
529 * The cumulative I/O wait CPU time, when the node booting up.(nanoseconds)
530 * VIR_NODE_CPU_STATS_UTILIZATION:
531 * The CPU utilization. The usage value is in percent and 100%
532 * represents all CPUs on the server.
533 *
534 * Returns -1 in case of error, 0 in case of success.
535 */
536 int
virNodeGetCPUStats(virConnectPtr conn,int cpuNum,virNodeCPUStatsPtr params,int * nparams,unsigned int flags)537 virNodeGetCPUStats(virConnectPtr conn,
538 int cpuNum,
539 virNodeCPUStatsPtr params,
540 int *nparams, unsigned int flags)
541 {
542 VIR_DEBUG("conn=%p, cpuNum=%d, params=%p, nparams=%d, flags=0x%x",
543 conn, cpuNum, params, nparams ? *nparams : -1, flags);
544
545 virResetLastError();
546
547 virCheckConnectReturn(conn, -1);
548 virCheckNonNullArgGoto(nparams, error);
549 virCheckNonNegativeArgGoto(*nparams, error);
550 if (cpuNum < 0 && cpuNum != VIR_NODE_CPU_STATS_ALL_CPUS) {
551 virReportInvalidArg(cpuNum,
552 _("cpuNum in %s only accepts %d as a negative "
553 "value"),
554 __FUNCTION__, VIR_NODE_CPU_STATS_ALL_CPUS);
555 goto error;
556 }
557
558 if (conn->driver->nodeGetCPUStats) {
559 int ret;
560 ret = conn->driver->nodeGetCPUStats(conn, cpuNum, params, nparams, flags);
561 if (ret < 0)
562 goto error;
563 return ret;
564 }
565 virReportUnsupportedError();
566
567 error:
568 virDispatchError(conn);
569 return -1;
570 }
571
572
573 /**
574 * virNodeGetMemoryStats:
575 * @conn: pointer to the hypervisor connection.
576 * @cellNum: number of node cell. (VIR_NODE_MEMORY_STATS_ALL_CELLS means total
577 * cell statistics)
578 * @params: pointer to node memory stats objects
579 * @nparams: number of node memory stats (this value should be same or
580 * less than the number of stats supported)
581 * @flags: extra flags; not used yet, so callers should always pass 0
582 *
583 * This function provides memory stats of the node.
584 * If you want to get total memory statistics of the node, you must specify
585 * VIR_NODE_MEMORY_STATS_ALL_CELLS to @cellNum.
586 * The @params array will be filled with the values equal to the number of
587 * stats suggested by @nparams
588 *
589 * As the value of @nparams is dynamic, call the API setting @nparams to 0 and
590 * @params as NULL, the API returns the number of parameters supported by the
591 * HV by updating @nparams on SUCCESS. The caller should then allocate @params
592 * array, i.e. (sizeof(@virNodeMemoryStats) * @nparams) bytes and call
593 * the API again.
594 *
595 * Here is the sample code snippet:
596 *
597 * if (virNodeGetMemoryStats(conn, cellNum, NULL, &nparams, 0) == 0 &&
598 * nparams != 0) {
599 * if ((params = malloc(sizeof(virNodeMemoryStats) * nparams)) == NULL)
600 * goto error;
601 * memset(params, cellNum, 0, sizeof(virNodeMemoryStats) * nparams);
602 * if (virNodeGetMemoryStats(conn, params, &nparams, 0))
603 * goto error;
604 * }
605 *
606 * This function doesn't require privileged access to the hypervisor.
607 * This function expects the caller to allocate the @params.
608 *
609 * Memory Stats:
610 *
611 * VIR_NODE_MEMORY_STATS_TOTAL:
612 * The total memory usage.(KB)
613 * VIR_NODE_MEMORY_STATS_FREE:
614 * The free memory usage.(KB)
615 * On linux, this usage includes buffers and cached.
616 * VIR_NODE_MEMORY_STATS_BUFFERS:
617 * The buffers memory usage.(KB)
618 * VIR_NODE_MEMORY_STATS_CACHED:
619 * The cached memory usage.(KB)
620 *
621 * Returns -1 in case of error, 0 in case of success.
622 */
623 int
virNodeGetMemoryStats(virConnectPtr conn,int cellNum,virNodeMemoryStatsPtr params,int * nparams,unsigned int flags)624 virNodeGetMemoryStats(virConnectPtr conn,
625 int cellNum,
626 virNodeMemoryStatsPtr params,
627 int *nparams, unsigned int flags)
628 {
629 VIR_DEBUG("conn=%p, cellNum=%d, params=%p, nparams=%d, flags=0x%x",
630 conn, cellNum, params, nparams ? *nparams : -1, flags);
631
632 virResetLastError();
633
634 virCheckConnectReturn(conn, -1);
635 virCheckNonNullArgGoto(nparams, error);
636 virCheckNonNegativeArgGoto(*nparams, error);
637 if (cellNum < 0 && cellNum != VIR_NODE_MEMORY_STATS_ALL_CELLS) {
638 virReportInvalidArg(cpuNum,
639 _("cellNum in %s only accepts %d as a negative "
640 "value"),
641 __FUNCTION__, VIR_NODE_MEMORY_STATS_ALL_CELLS);
642 goto error;
643 }
644
645 if (conn->driver->nodeGetMemoryStats) {
646 int ret;
647 ret = conn->driver->nodeGetMemoryStats(conn, cellNum, params, nparams, flags);
648 if (ret < 0)
649 goto error;
650 return ret;
651 }
652 virReportUnsupportedError();
653
654 error:
655 virDispatchError(conn);
656 return -1;
657 }
658
659
660 /**
661 * virNodeGetFreeMemory:
662 * @conn: pointer to the hypervisor connection
663 *
664 * provides the free memory available on the Node
665 * Note: most libvirt APIs provide memory sizes in kibibytes, but in this
666 * function the returned value is in bytes. Divide by 1024 as necessary.
667 *
668 * Returns the available free memory in bytes or 0 in case of error
669 */
670 unsigned long long
virNodeGetFreeMemory(virConnectPtr conn)671 virNodeGetFreeMemory(virConnectPtr conn)
672 {
673 VIR_DEBUG("conn=%p", conn);
674
675 virResetLastError();
676
677 virCheckConnectReturn(conn, 0);
678
679 if (conn->driver->nodeGetFreeMemory) {
680 unsigned long long ret;
681 ret = conn->driver->nodeGetFreeMemory(conn);
682 if (ret == 0)
683 goto error;
684 return ret;
685 }
686
687 virReportUnsupportedError();
688
689 error:
690 virDispatchError(conn);
691 return 0;
692 }
693
694
695 /**
696 * virNodeSuspendForDuration:
697 * @conn: pointer to the hypervisor connection
698 * @target: the state to which the host must be suspended to,
699 * such as: VIR_NODE_SUSPEND_TARGET_MEM (Suspend-to-RAM)
700 * VIR_NODE_SUSPEND_TARGET_DISK (Suspend-to-Disk)
701 * VIR_NODE_SUSPEND_TARGET_HYBRID (Hybrid-Suspend,
702 * which is a combination of the former modes).
703 * @duration: the time duration in seconds for which the host
704 * has to be suspended
705 * @flags: extra flags; not used yet, so callers should always pass 0
706 *
707 * Attempt to suspend the node (host machine) for the given duration of
708 * time in the specified state (Suspend-to-RAM, Suspend-to-Disk or
709 * Hybrid-Suspend). Schedule the node's Real-Time-Clock interrupt to
710 * resume the node after the duration is complete.
711 *
712 * Returns 0 on success (i.e., the node will be suspended after a short
713 * delay), -1 on failure (the operation is not supported, or an attempted
714 * suspend is already underway).
715 */
716 int
virNodeSuspendForDuration(virConnectPtr conn,unsigned int target,unsigned long long duration,unsigned int flags)717 virNodeSuspendForDuration(virConnectPtr conn,
718 unsigned int target,
719 unsigned long long duration,
720 unsigned int flags)
721 {
722 VIR_DEBUG("conn=%p, target=%d, duration=%lld, flags=0x%x",
723 conn, target, duration, flags);
724
725 virResetLastError();
726
727 virCheckConnectReturn(conn, -1);
728 virCheckReadOnlyGoto(conn->flags, error);
729
730 if (conn->driver->nodeSuspendForDuration) {
731 int ret;
732 ret = conn->driver->nodeSuspendForDuration(conn, target,
733 duration, flags);
734 if (ret < 0)
735 goto error;
736 return ret;
737 }
738
739 virReportUnsupportedError();
740
741 error:
742 virDispatchError(conn);
743 return -1;
744 }
745
746
747 /*
748 * virNodeGetMemoryParameters:
749 * @conn: pointer to the hypervisor connection
750 * @params: pointer to memory parameter object
751 * (return value, allocated by the caller)
752 * @nparams: pointer to number of memory parameters; input and output
753 * @flags: extra flags; not used yet, so callers should always pass 0
754 *
755 * Get all node memory parameters (parameters unsupported by OS will be
756 * omitted). On input, @nparams gives the size of the @params array;
757 * on output, @nparams gives how many slots were filled with parameter
758 * information, which might be less but will not exceed the input value.
759 *
760 * As a special case, calling with @params as NULL and @nparams as 0 on
761 * input will cause @nparams on output to contain the number of parameters
762 * supported by the hypervisor. The caller should then allocate @params
763 * array, i.e. (sizeof(@virTypedParameter) * @nparams) bytes and call the API
764 * again. See virDomainGetMemoryParameters() for an equivalent usage
765 * example.
766 *
767 * Returns 0 in case of success, and -1 in case of failure.
768 */
769 int
virNodeGetMemoryParameters(virConnectPtr conn,virTypedParameterPtr params,int * nparams,unsigned int flags)770 virNodeGetMemoryParameters(virConnectPtr conn,
771 virTypedParameterPtr params,
772 int *nparams,
773 unsigned int flags)
774 {
775 int rc;
776
777 VIR_DEBUG("conn=%p, params=%p, nparams=%p, flags=0x%x",
778 conn, params, nparams, flags);
779
780 virResetLastError();
781
782 virCheckConnectReturn(conn, -1);
783 virCheckNonNullArgGoto(nparams, error);
784 virCheckNonNegativeArgGoto(*nparams, error);
785 if (*nparams != 0)
786 virCheckNonNullArgGoto(params, error);
787
788 rc = VIR_DRV_SUPPORTS_FEATURE(conn->driver, conn,
789 VIR_DRV_FEATURE_TYPED_PARAM_STRING);
790 if (rc < 0)
791 goto error;
792 if (rc)
793 flags |= VIR_TYPED_PARAM_STRING_OKAY;
794
795 if (conn->driver->nodeGetMemoryParameters) {
796 int ret;
797 ret = conn->driver->nodeGetMemoryParameters(conn, params,
798 nparams, flags);
799 if (ret < 0)
800 goto error;
801 return ret;
802 }
803
804 virReportUnsupportedError();
805
806 error:
807 virDispatchError(conn);
808 return -1;
809 }
810
811
812 /*
813 * virNodeSetMemoryParameters:
814 * @conn: pointer to the hypervisor connection
815 * @params: pointer to scheduler parameter objects
816 * @nparams: number of scheduler parameter objects
817 * (this value can be the same or less than the returned
818 * value nparams of virDomainGetSchedulerType)
819 * @flags: extra flags; not used yet, so callers should always pass 0
820 *
821 * Change all or a subset of the node memory tunables. The function
822 * fails if not all of the tunables are supported.
823 *
824 * Note that it's not recommended to use this function while the
825 * outside tuning program is running (such as ksmtuned under Linux),
826 * as they could change the tunables in parallel, which could cause
827 * conflicts.
828 *
829 * This function may require privileged access to the hypervisor.
830 *
831 * Returns 0 in case of success, -1 in case of failure.
832 */
833 int
virNodeSetMemoryParameters(virConnectPtr conn,virTypedParameterPtr params,int nparams,unsigned int flags)834 virNodeSetMemoryParameters(virConnectPtr conn,
835 virTypedParameterPtr params,
836 int nparams,
837 unsigned int flags)
838 {
839 VIR_DEBUG("conn=%p, params=%p, nparams=%d, flags=0x%x",
840 conn, params, nparams, flags);
841 VIR_TYPED_PARAMS_DEBUG(params, nparams);
842
843 virResetLastError();
844
845 virCheckConnectReturn(conn, -1);
846 virCheckReadOnlyGoto(conn->flags, error);
847 virCheckNonNullArgGoto(params, error);
848 virCheckNonNegativeArgGoto(nparams, error);
849
850 if (virTypedParameterValidateSet(conn, params, nparams) < 0)
851 goto error;
852
853 if (conn->driver->nodeSetMemoryParameters) {
854 int ret;
855 ret = conn->driver->nodeSetMemoryParameters(conn, params,
856 nparams, flags);
857 if (ret < 0)
858 goto error;
859 return ret;
860 }
861
862 virReportUnsupportedError();
863
864 error:
865 virDispatchError(conn);
866 return -1;
867 }
868
869
870 /**
871 * virNodeGetSecurityModel:
872 * @conn: a connection object
873 * @secmodel: pointer to a virSecurityModel structure
874 *
875 * Extract the security model of a hypervisor. The 'model' field
876 * in the @secmodel argument may be initialized to the empty
877 * string if the driver has not activated a security model.
878 *
879 * Returns 0 in case of success, -1 in case of failure
880 */
881 int
virNodeGetSecurityModel(virConnectPtr conn,virSecurityModelPtr secmodel)882 virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
883 {
884 VIR_DEBUG("conn=%p secmodel=%p", conn, secmodel);
885
886 virResetLastError();
887
888 virCheckConnectReturn(conn, -1);
889 virCheckNonNullArgGoto(secmodel, error);
890
891 if (conn->driver->nodeGetSecurityModel) {
892 int ret;
893 ret = conn->driver->nodeGetSecurityModel(conn, secmodel);
894 if (ret < 0)
895 goto error;
896 return ret;
897 }
898
899 virReportUnsupportedError();
900
901 error:
902 virDispatchError(conn);
903 return -1;
904 }
905
906
907 /**
908 * virNodeGetCellsFreeMemory:
909 * @conn: pointer to the hypervisor connection
910 * @freeMems: pointer to the array of unsigned long long
911 * @startCell: index of first cell to return freeMems info on.
912 * @maxCells: Maximum number of cells for which freeMems information can
913 * be returned.
914 *
915 * This call returns the amount of free memory in one or more NUMA cells.
916 * The @freeMems array must be allocated by the caller and will be filled
917 * with the amount of free memory in bytes for each cell requested,
918 * starting with startCell (in freeMems[0]), up to either
919 * (startCell + maxCells), or the number of additional cells in the node,
920 * whichever is smaller.
921 *
922 * Returns the number of entries filled in freeMems, or -1 in case of error.
923 */
924 int
virNodeGetCellsFreeMemory(virConnectPtr conn,unsigned long long * freeMems,int startCell,int maxCells)925 virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
926 int startCell, int maxCells)
927 {
928 VIR_DEBUG("conn=%p, freeMems=%p, startCell=%d, maxCells=%d",
929 conn, freeMems, startCell, maxCells);
930
931 virResetLastError();
932
933 virCheckConnectReturn(conn, -1);
934 virCheckNonNullArrayArgGoto(freeMems, maxCells, error);
935 virCheckPositiveArgGoto(maxCells, error);
936 virCheckNonNegativeArgGoto(startCell, error);
937
938 if (conn->driver->nodeGetCellsFreeMemory) {
939 int ret;
940 ret = conn->driver->nodeGetCellsFreeMemory(conn, freeMems, startCell, maxCells);
941 if (ret < 0)
942 goto error;
943 return ret;
944 }
945
946 virReportUnsupportedError();
947
948 error:
949 virDispatchError(conn);
950 return -1;
951 }
952
953
954 /**
955 * virConnectIsEncrypted:
956 * @conn: pointer to the connection object
957 *
958 * Determine if the connection to the hypervisor is encrypted
959 *
960 * Returns 1 if encrypted, 0 if not encrypted, -1 on error
961 */
962 int
virConnectIsEncrypted(virConnectPtr conn)963 virConnectIsEncrypted(virConnectPtr conn)
964 {
965 VIR_DEBUG("conn=%p", conn);
966
967 virResetLastError();
968
969 virCheckConnectReturn(conn, -1);
970 if (conn->driver->connectIsEncrypted) {
971 int ret;
972 ret = conn->driver->connectIsEncrypted(conn);
973 if (ret < 0)
974 goto error;
975 return ret;
976 }
977
978 virReportUnsupportedError();
979 error:
980 virDispatchError(conn);
981 return -1;
982 }
983
984
985 /**
986 * virConnectIsSecure:
987 * @conn: pointer to the connection object
988 *
989 * Determine if the connection to the hypervisor is secure
990 *
991 * A connection will be classed as secure if it is either
992 * encrypted, or running over a channel which is not exposed
993 * to eavesdropping (eg a UNIX domain socket, or pipe)
994 *
995 * Returns 1 if secure, 0 if not secure, -1 on error
996 */
997 int
virConnectIsSecure(virConnectPtr conn)998 virConnectIsSecure(virConnectPtr conn)
999 {
1000 VIR_DEBUG("conn=%p", conn);
1001
1002 virResetLastError();
1003
1004 virCheckConnectReturn(conn, -1);
1005 if (conn->driver->connectIsSecure) {
1006 int ret;
1007 ret = conn->driver->connectIsSecure(conn);
1008 if (ret < 0)
1009 goto error;
1010 return ret;
1011 }
1012
1013 virReportUnsupportedError();
1014 error:
1015 virDispatchError(conn);
1016 return -1;
1017 }
1018
1019
1020 /**
1021 * virConnectCompareCPU:
1022 * @conn: virConnect connection
1023 * @xmlDesc: XML describing the CPU to compare with host CPU
1024 * @flags: bitwise-OR of virConnectCompareCPUFlags
1025 *
1026 * Compares the given CPU description with the host CPU.
1027 *
1028 * See virConnectCompareHypervisorCPU() if you want to consider hypervisor
1029 * abilities and compare the CPU to the CPU which a hypervisor is able to
1030 * provide on the host.
1031 *
1032 * Returns comparison result according to enum virCPUCompareResult. If
1033 * VIR_CONNECT_COMPARE_CPU_FAIL_INCOMPATIBLE is used and @xmlDesc CPU is
1034 * incompatible with host CPU, this function will return VIR_CPU_COMPARE_ERROR
1035 * (instead of VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
1036 * VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
1037 * the incompatibility.
1038 */
1039 int
virConnectCompareCPU(virConnectPtr conn,const char * xmlDesc,unsigned int flags)1040 virConnectCompareCPU(virConnectPtr conn,
1041 const char *xmlDesc,
1042 unsigned int flags)
1043 {
1044 VIR_DEBUG("conn=%p, xmlDesc=%s, flags=0x%x", conn, NULLSTR(xmlDesc), flags);
1045
1046 virResetLastError();
1047
1048 virCheckConnectReturn(conn, VIR_CPU_COMPARE_ERROR);
1049 virCheckNonNullArgGoto(xmlDesc, error);
1050
1051 if (conn->driver->connectCompareCPU) {
1052 int ret;
1053
1054 ret = conn->driver->connectCompareCPU(conn, xmlDesc, flags);
1055 if (ret == VIR_CPU_COMPARE_ERROR)
1056 goto error;
1057 return ret;
1058 }
1059
1060 virReportUnsupportedError();
1061
1062 error:
1063 virDispatchError(conn);
1064 return VIR_CPU_COMPARE_ERROR;
1065 }
1066
1067
1068 /**
1069 * virConnectCompareHypervisorCPU:
1070 * @conn: pointer to the hypervisor connection
1071 * @emulator: path to the emulator binary
1072 * @arch: CPU architecture
1073 * @machine: machine type
1074 * @virttype: virtualization type
1075 * @xmlCPU: XML describing the CPU to be compared
1076 * @flags: bitwise-OR of virConnectCompareCPUFlags
1077 *
1078 * Compares the given CPU description with the CPU the specified hypervisor is
1079 * able to provide on the host. Any of @emulator, @arch, @machine, and
1080 * @virttype parameters may be NULL; libvirt will choose sensible defaults
1081 * tailored to the host and its current configuration.
1082 *
1083 * This is different from virConnectCompareCPU() which compares the CPU
1084 * definition with the host CPU without considering any specific hypervisor and
1085 * its abilities.
1086 *
1087 * Returns comparison result according to enum virCPUCompareResult. If
1088 * VIR_CONNECT_COMPARE_CPU_FAIL_INCOMPATIBLE is used and @xmlCPU is
1089 * incompatible with the CPU the specified hypervisor is able to provide on the
1090 * host, this function will return VIR_CPU_COMPARE_ERROR (instead of
1091 * VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the
1092 * VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about
1093 * the incompatibility.
1094 */
1095 int
virConnectCompareHypervisorCPU(virConnectPtr conn,const char * emulator,const char * arch,const char * machine,const char * virttype,const char * xmlCPU,unsigned int flags)1096 virConnectCompareHypervisorCPU(virConnectPtr conn,
1097 const char *emulator,
1098 const char *arch,
1099 const char *machine,
1100 const char *virttype,
1101 const char *xmlCPU,
1102 unsigned int flags)
1103 {
1104 VIR_DEBUG("conn=%p, emulator=%s, arch=%s, machine=%s, "
1105 "virttype=%s, xmlCPU=%s, flags=0x%x",
1106 conn, NULLSTR(emulator), NULLSTR(arch), NULLSTR(machine),
1107 NULLSTR(virttype), NULLSTR(xmlCPU), flags);
1108
1109 virResetLastError();
1110
1111 virCheckConnectReturn(conn, VIR_CPU_COMPARE_ERROR);
1112 virCheckNonNullArgGoto(xmlCPU, error);
1113 virCheckReadOnlyGoto(conn->flags, error);
1114
1115 if (conn->driver->connectCompareHypervisorCPU) {
1116 int ret;
1117
1118 ret = conn->driver->connectCompareHypervisorCPU(conn, emulator, arch,
1119 machine, virttype,
1120 xmlCPU, flags);
1121 if (ret == VIR_CPU_COMPARE_ERROR)
1122 goto error;
1123
1124 return ret;
1125 }
1126
1127 virReportUnsupportedError();
1128
1129 error:
1130 virDispatchError(conn);
1131 return VIR_CPU_COMPARE_ERROR;
1132 }
1133
1134
1135 /**
1136 * virConnectGetCPUModelNames:
1137 *
1138 * @conn: virConnect connection
1139 * @arch: Architecture
1140 * @models: Pointer to a variable to store the NULL-terminated array of the
1141 * CPU models supported for the specified architecture. Each element
1142 * and the array itself must be freed by the caller with free. Pass
1143 * NULL if only the list length is needed.
1144 * @flags: extra flags; not used yet, so callers should always pass 0.
1145 *
1146 * Get the list of CPU models supported by libvirt for a specific architecture.
1147 *
1148 * The returned list limits CPU models usable with libvirt (empty list means
1149 * there's no limit imposed by libvirt) and it does not reflect capabilities of
1150 * any particular hypervisor. See the XML returned by
1151 * virConnectGetDomainCapabilities() for a list of CPU models supported by
1152 * libvirt for domains created on a specific hypervisor.
1153 *
1154 * Returns -1 on error, number of elements in @models on success (0 means
1155 * libvirt accepts any CPU model).
1156 */
1157 int
virConnectGetCPUModelNames(virConnectPtr conn,const char * arch,char *** models,unsigned int flags)1158 virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models,
1159 unsigned int flags)
1160 {
1161 VIR_DEBUG("conn=%p, arch=%s, models=%p, flags=0x%x",
1162 conn, NULLSTR(arch), models, flags);
1163 virResetLastError();
1164
1165 if (models)
1166 *models = NULL;
1167
1168 virCheckConnectReturn(conn, -1);
1169 virCheckNonNullArgGoto(arch, error);
1170
1171 if (conn->driver->connectGetCPUModelNames) {
1172 int ret;
1173
1174 ret = conn->driver->connectGetCPUModelNames(conn, arch, models, flags);
1175 if (ret < 0)
1176 goto error;
1177
1178 return ret;
1179 }
1180
1181 virReportUnsupportedError();
1182
1183 error:
1184 virDispatchError(conn);
1185 return -1;
1186 }
1187
1188
1189 /**
1190 * virConnectBaselineCPU:
1191 *
1192 * @conn: virConnect connection
1193 * @xmlCPUs: array of XML descriptions of host CPUs
1194 * @ncpus: number of CPUs in xmlCPUs
1195 * @flags: bitwise-OR of virConnectBaselineCPUFlags
1196 *
1197 * Computes the most feature-rich CPU which is compatible with all given
1198 * host CPUs.
1199 *
1200 * See virConnectBaselineHypervisorCPU() to get a CPU which can be provided
1201 * by the hypervisor.
1202 *
1203 * If @flags includes VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES then libvirt
1204 * will explicitly list all CPU features that are part of the host CPU,
1205 * without this flag features that are part of the CPU model will not be
1206 * listed.
1207 *
1208 * If @flags includes VIR_CONNECT_BASELINE_CPU_MIGRATABLE, the resulting
1209 * CPU will not include features that block migration.
1210 *
1211 * Returns XML description of the computed CPU (caller frees) or NULL on error.
1212 */
1213 char *
virConnectBaselineCPU(virConnectPtr conn,const char ** xmlCPUs,unsigned int ncpus,unsigned int flags)1214 virConnectBaselineCPU(virConnectPtr conn,
1215 const char **xmlCPUs,
1216 unsigned int ncpus,
1217 unsigned int flags)
1218 {
1219 size_t i;
1220
1221 VIR_DEBUG("conn=%p, xmlCPUs=%p, ncpus=%u, flags=0x%x",
1222 conn, xmlCPUs, ncpus, flags);
1223 if (xmlCPUs) {
1224 for (i = 0; i < ncpus; i++)
1225 VIR_DEBUG("xmlCPUs[%zu]=%s", i, NULLSTR(xmlCPUs[i]));
1226 }
1227
1228 virResetLastError();
1229
1230 virCheckConnectReturn(conn, NULL);
1231 virCheckNonNullArgGoto(xmlCPUs, error);
1232
1233 if (conn->driver->connectBaselineCPU) {
1234 char *cpu;
1235
1236 cpu = conn->driver->connectBaselineCPU(conn, xmlCPUs, ncpus, flags);
1237 if (!cpu)
1238 goto error;
1239 return cpu;
1240 }
1241
1242 virReportUnsupportedError();
1243
1244 error:
1245 virDispatchError(conn);
1246 return NULL;
1247 }
1248
1249
1250 /**
1251 * virConnectBaselineHypervisorCPU:
1252 *
1253 * @conn: pointer to the hypervisor connection
1254 * @emulator: path to the emulator binary
1255 * @arch: CPU architecture
1256 * @machine: machine type
1257 * @virttype: virtualization type
1258 * @xmlCPUs: array of XML descriptions of CPUs
1259 * @ncpus: number of CPUs in xmlCPUs
1260 * @flags: bitwise-OR of virConnectBaselineCPUFlags
1261 *
1262 * Computes the most feature-rich CPU which is compatible with all given CPUs
1263 * and can be provided by the specified hypervisor. For best results the
1264 * host-model CPUs as advertised by virConnectGetDomainCapabilities() should be
1265 * passed in @xmlCPUs. Any of @emulator, @arch, @machine, and @virttype
1266 * parameters may be NULL; libvirt will choose sensible defaults tailored to
1267 * the host and its current configuration.
1268 *
1269 * This is different from virConnectBaselineCPU() which doesn't consider any
1270 * hypervisor abilities when computing the best CPU.
1271 *
1272 * If @flags includes VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES then libvirt
1273 * will explicitly list all CPU features that are part of the computed CPU,
1274 * without this flag features that are part of the CPU model will not be
1275 * listed.
1276 *
1277 * If @flags includes VIR_CONNECT_BASELINE_CPU_MIGRATABLE, the resulting
1278 * CPU will not include features that block migration.
1279 *
1280 * Returns XML description of the computed CPU (caller frees) or NULL on error.
1281 */
1282 char *
virConnectBaselineHypervisorCPU(virConnectPtr conn,const char * emulator,const char * arch,const char * machine,const char * virttype,const char ** xmlCPUs,unsigned int ncpus,unsigned int flags)1283 virConnectBaselineHypervisorCPU(virConnectPtr conn,
1284 const char *emulator,
1285 const char *arch,
1286 const char *machine,
1287 const char *virttype,
1288 const char **xmlCPUs,
1289 unsigned int ncpus,
1290 unsigned int flags)
1291 {
1292 size_t i;
1293
1294 VIR_DEBUG("conn=%p, emulator=%s, arch=%s, machine=%s, "
1295 "virttype=%s, xmlCPUs=%p, ncpus=%u, flags=0x%x",
1296 conn, NULLSTR(emulator), NULLSTR(arch), NULLSTR(machine),
1297 NULLSTR(virttype), xmlCPUs, ncpus, flags);
1298 if (xmlCPUs) {
1299 for (i = 0; i < ncpus; i++)
1300 VIR_DEBUG("xmlCPUs[%zu]=%s", i, NULLSTR(xmlCPUs[i]));
1301 }
1302
1303 virResetLastError();
1304
1305 virCheckConnectReturn(conn, NULL);
1306 virCheckNonNullArgGoto(xmlCPUs, error);
1307 virCheckReadOnlyGoto(conn->flags, error);
1308
1309 if (conn->driver->connectBaselineHypervisorCPU) {
1310 char *cpu;
1311
1312 cpu = conn->driver->connectBaselineHypervisorCPU(conn, emulator, arch,
1313 machine, virttype,
1314 xmlCPUs, ncpus, flags);
1315 if (!cpu)
1316 goto error;
1317
1318 return cpu;
1319 }
1320
1321 virReportUnsupportedError();
1322
1323 error:
1324 virDispatchError(conn);
1325 return NULL;
1326 }
1327
1328
1329 /**
1330 * virConnectSetKeepAlive:
1331 * @conn: pointer to a hypervisor connection
1332 * @interval: number of seconds of inactivity before a keepalive message is sent
1333 * @count: number of messages that can be sent in a row
1334 *
1335 * Start sending keepalive messages after @interval seconds of inactivity and
1336 * consider the connection to be broken when no response is received after
1337 * @count keepalive messages sent in a row. In other words, sending count + 1
1338 * keepalive message results in closing the connection. When @interval is
1339 * <= 0, no keepalive messages will be sent. When @count is 0, the connection
1340 * will be automatically closed after @interval seconds of inactivity without
1341 * sending any keepalive messages.
1342 *
1343 * Note: The client has to implement and run an event loop with
1344 * virEventRegisterImpl() or virEventRegisterDefaultImpl() to be able to
1345 * use keepalive messages. Failure to do so may result in connections
1346 * being closed unexpectedly.
1347 *
1348 * Note: This API function controls only keepalive messages sent by the client.
1349 * If the server is configured to use keepalive you still need to run the event
1350 * loop to respond to them, even if you disable keepalives by this function.
1351 *
1352 * Returns -1 on error, 0 on success, 1 when remote party doesn't support
1353 * keepalive messages.
1354 */
1355 int
virConnectSetKeepAlive(virConnectPtr conn,int interval,unsigned int count)1356 virConnectSetKeepAlive(virConnectPtr conn,
1357 int interval,
1358 unsigned int count)
1359 {
1360 VIR_DEBUG("conn=%p, interval=%d, count=%u", conn, interval, count);
1361
1362 virResetLastError();
1363
1364 virCheckConnectReturn(conn, -1);
1365
1366 if (conn->driver->connectSetKeepAlive) {
1367 int ret = conn->driver->connectSetKeepAlive(conn, interval, count);
1368 if (ret < 0)
1369 goto error;
1370 return ret;
1371 }
1372
1373 virReportUnsupportedError();
1374
1375 error:
1376 virDispatchError(conn);
1377 return -1;
1378 }
1379
1380
1381 /**
1382 * virConnectIsAlive:
1383 * @conn: pointer to the connection object
1384 *
1385 * Determine if the connection to the hypervisor is still alive
1386 *
1387 * A connection will be classed as alive if it is either local, or running
1388 * over a channel (TCP or UNIX socket) which is not closed.
1389 *
1390 * Returns 1 if alive, 0 if dead, -1 on error
1391 */
1392 int
virConnectIsAlive(virConnectPtr conn)1393 virConnectIsAlive(virConnectPtr conn)
1394 {
1395 VIR_DEBUG("conn=%p", conn);
1396
1397 virResetLastError();
1398
1399 virCheckConnectReturn(conn, -1);
1400 if (conn->driver->connectIsAlive) {
1401 int ret;
1402 ret = conn->driver->connectIsAlive(conn);
1403 if (ret < 0)
1404 goto error;
1405 return ret;
1406 }
1407
1408 virReportUnsupportedError();
1409 error:
1410 virDispatchError(conn);
1411 return -1;
1412 }
1413
1414
1415 /**
1416 * virConnectRegisterCloseCallback:
1417 * @conn: pointer to connection object
1418 * @cb: callback to invoke upon close
1419 * @opaque: user data to pass to @cb
1420 * @freecb: callback to free @opaque
1421 *
1422 * Registers a callback to be invoked when the connection
1423 * is closed. This callback is invoked when there is any
1424 * condition that causes the socket connection to the
1425 * hypervisor to be closed.
1426 *
1427 * This function is only applicable to hypervisor drivers
1428 * which maintain a persistent open connection. Drivers
1429 * which open a new connection for every operation will
1430 * not invoke this.
1431 *
1432 * The @freecb must not invoke any other libvirt public
1433 * APIs, since it is not called from a re-entrant safe
1434 * context.
1435 *
1436 * Returns 0 on success, -1 on error
1437 */
1438 int
virConnectRegisterCloseCallback(virConnectPtr conn,virConnectCloseFunc cb,void * opaque,virFreeCallback freecb)1439 virConnectRegisterCloseCallback(virConnectPtr conn,
1440 virConnectCloseFunc cb,
1441 void *opaque,
1442 virFreeCallback freecb)
1443 {
1444 VIR_DEBUG("conn=%p", conn);
1445
1446 virResetLastError();
1447 virCheckConnectReturn(conn, -1);
1448 virCheckNonNullArgGoto(cb, error);
1449
1450 if (conn->driver->connectRegisterCloseCallback &&
1451 conn->driver->connectRegisterCloseCallback(conn, cb, opaque, freecb) < 0)
1452 goto error;
1453
1454 return 0;
1455
1456 error:
1457 virDispatchError(conn);
1458 return -1;
1459 }
1460
1461
1462 /**
1463 * virConnectUnregisterCloseCallback:
1464 * @conn: pointer to connection object
1465 * @cb: pointer to the current registered callback
1466 *
1467 * Unregisters the callback previously set with the
1468 * virConnectRegisterCloseCallback method. The callback
1469 * will no longer receive notifications when the connection
1470 * closes. If a virFreeCallback was provided at time of
1471 * registration, it will be invoked
1472 *
1473 * Returns 0 on success, -1 on error
1474 */
1475 int
virConnectUnregisterCloseCallback(virConnectPtr conn,virConnectCloseFunc cb)1476 virConnectUnregisterCloseCallback(virConnectPtr conn,
1477 virConnectCloseFunc cb)
1478 {
1479 VIR_DEBUG("conn=%p", conn);
1480
1481 virResetLastError();
1482 virCheckConnectReturn(conn, -1);
1483 virCheckNonNullArgGoto(cb, error);
1484
1485 if (conn->driver->connectUnregisterCloseCallback &&
1486 conn->driver->connectUnregisterCloseCallback(conn, cb) < 0)
1487 goto error;
1488
1489 return 0;
1490
1491 error:
1492 virDispatchError(conn);
1493 return -1;
1494 }
1495
1496
1497 /**
1498 * virNodeGetCPUMap:
1499 * @conn: pointer to the hypervisor connection
1500 * @cpumap: optional pointer to a bit map of real CPUs on the host node
1501 * (in 8-bit bytes) (OUT)
1502 * In case of success each bit set to 1 means that corresponding
1503 * CPU is online.
1504 * Bytes are stored in little-endian order: CPU0-7, 8-15...
1505 * In each byte, lowest CPU number is least significant bit.
1506 * The bit map is allocated by virNodeGetCPUMap and needs
1507 * to be released using free() by the caller.
1508 * @online: optional number of online CPUs in cpumap (OUT)
1509 * Contains the number of online CPUs if the call was successful.
1510 * @flags: extra flags; not used yet, so callers should always pass 0
1511 *
1512 * Get CPU map of host node CPUs.
1513 *
1514 * Returns number of CPUs present on the host node,
1515 * or -1 if there was an error.
1516 */
1517 int
virNodeGetCPUMap(virConnectPtr conn,unsigned char ** cpumap,unsigned int * online,unsigned int flags)1518 virNodeGetCPUMap(virConnectPtr conn,
1519 unsigned char **cpumap,
1520 unsigned int *online,
1521 unsigned int flags)
1522 {
1523 VIR_DEBUG("conn=%p, cpumap=%p, online=%p, flags=0x%x",
1524 conn, cpumap, online, flags);
1525
1526 virResetLastError();
1527
1528 virCheckConnectReturn(conn, -1);
1529
1530 if (conn->driver->nodeGetCPUMap) {
1531 int ret = conn->driver->nodeGetCPUMap(conn, cpumap, online, flags);
1532 if (ret < 0)
1533 goto error;
1534 return ret;
1535 }
1536
1537 virReportUnsupportedError();
1538
1539 error:
1540 virDispatchError(conn);
1541 return -1;
1542 }
1543
1544
1545 /**
1546 * virNodeGetFreePages:
1547 * @conn: pointer to the hypervisor connection
1548 * @npages: number of items in the @pages array
1549 * @pages: page sizes to query
1550 * @startCell: index of first cell to return free pages info on.
1551 * @cellCount: maximum number of cells for which free pages
1552 * information can be returned.
1553 * @counts: returned counts of free pages
1554 * @flags: extra flags; not used yet, so callers should always pass 0
1555 *
1556 * This calls queries the host system on free pages of
1557 * specified size. For the input, @pages is expected to be
1558 * filled with pages that caller is interested in (the size
1559 * unit is kibibytes, so e.g. pass 2048 for 2MB), then @startcell
1560 * refers to the first NUMA node that info should be collected
1561 * from, and @cellcount tells how many consecutive nodes should
1562 * be queried. On the function output, @counts is filled with
1563 * desired information, where items are grouped by NUMA node.
1564 * So from @counts[0] till @counts[@npages - 1] you'll find count
1565 * for the first node (@startcell), then from @counts[@npages]
1566 * till @count[2 * @npages - 1] you'll find info for the
1567 * (@startcell + 1) node, and so on. It's callers responsibility
1568 * to allocate the @counts array.
1569 *
1570 * Example how to use this API:
1571 *
1572 * unsigned int pages[] = { 4, 2048, 1048576}
1573 * unsigned int npages = G_N_ELEMENTS(pages);
1574 * int startcell = 0;
1575 * unsigned int cellcount = 2;
1576 *
1577 * unsigned long long counts = malloc(sizeof(long long) * npages * cellcount);
1578 *
1579 * virNodeGetFreePages(conn, pages, npages,
1580 * startcell, cellcount, counts, 0);
1581 *
1582 * for (i = 0 ; i < cellcount ; i++) {
1583 * fprintf(stdout, "Cell %d\n", startcell + i);
1584 * for (j = 0 ; j < npages ; j++) {
1585 * fprintf(stdout, " Page size=%d count=%d bytes=%llu\n",
1586 * pages[j], counts[(i * npages) + j],
1587 * pages[j] * counts[(i * npages) + j]);
1588 * }
1589 * }
1590 *
1591 * This little code snippet will produce something like this:
1592 * Cell 0
1593 * Page size=4096 count=300 bytes=1228800
1594 * Page size=2097152 count=0 bytes=0
1595 * Page size=1073741824 count=1 bytes=1073741824
1596 * Cell 1
1597 * Page size=4096 count=0 bytes=0
1598 * Page size=2097152 count=20 bytes=41943040
1599 * Page size=1073741824 count=0 bytes=0
1600 *
1601 * Returns: the number of entries filled in @counts or -1 in case of error.
1602 */
1603 int
virNodeGetFreePages(virConnectPtr conn,unsigned int npages,unsigned int * pages,int startCell,unsigned int cellCount,unsigned long long * counts,unsigned int flags)1604 virNodeGetFreePages(virConnectPtr conn,
1605 unsigned int npages,
1606 unsigned int *pages,
1607 int startCell,
1608 unsigned int cellCount,
1609 unsigned long long *counts,
1610 unsigned int flags)
1611 {
1612 VIR_DEBUG("conn=%p, npages=%u, pages=%p, startCell=%u, "
1613 "cellCount=%u, counts=%p, flags=0x%x",
1614 conn, npages, pages, startCell, cellCount, counts, flags);
1615
1616 virResetLastError();
1617
1618 virCheckConnectReturn(conn, -1);
1619 virCheckNonZeroArgGoto(npages, error);
1620 virCheckNonNullArgGoto(pages, error);
1621 virCheckNonZeroArgGoto(cellCount, error);
1622 virCheckNonNullArgGoto(counts, error);
1623
1624 if (conn->driver->nodeGetFreePages) {
1625 int ret;
1626 ret = conn->driver->nodeGetFreePages(conn, npages, pages, startCell,
1627 cellCount, counts, flags);
1628 if (ret < 0)
1629 goto error;
1630 return ret;
1631 }
1632
1633 virReportUnsupportedError();
1634 error:
1635 virDispatchError(conn);
1636 return -1;
1637 }
1638
1639
1640 /**
1641 * virNodeAllocPages:
1642 * @conn: pointer to the hypervisor connection
1643 * @npages: number of items in the @pageSizes and
1644 * @pageCounts arrays
1645 * @pageSizes: which huge page sizes to allocate
1646 * @pageCounts: how many pages should be allocated
1647 * @startCell: index of first cell to allocate pages on
1648 * @cellCount: number of consecutive cells to allocate pages on
1649 * @flags: extra flags; binary-OR of virNodeAllocPagesFlags
1650 *
1651 * Sometimes, when trying to start a new domain, it may be
1652 * necessary to reserve some huge pages in the system pool which
1653 * can be then allocated by the domain. This API serves that
1654 * purpose. On its input, @pageSizes and @pageCounts are arrays
1655 * of the same cardinality of @npages. The @pageSizes contains
1656 * page sizes which are to be allocated in the system (the size
1657 * unit is kibibytes), and @pageCounts then contains the number
1658 * of pages to reserve. If @flags is 0
1659 * (VIR_NODE_ALLOC_PAGES_ADD), each pool corresponding to
1660 * @pageSizes grows by the number of pages specified in the
1661 * corresponding @pageCounts. If @flags contains
1662 * VIR_NODE_ALLOC_PAGES_SET, each pool mentioned is resized to
1663 * the given number of pages. The pages pool can be allocated
1664 * over several NUMA nodes at once, just point at @startCell and
1665 * tell how many subsequent NUMA nodes should be taken in. As a
1666 * special case, if @startCell is equal to negative one, then
1667 * kernel is instructed to allocate the pages over all NUMA nodes
1668 * proportionally.
1669 *
1670 * Returns: the number of nodes successfully adjusted or -1 in
1671 * case of an error.
1672 */
1673 int
virNodeAllocPages(virConnectPtr conn,unsigned int npages,unsigned int * pageSizes,unsigned long long * pageCounts,int startCell,unsigned int cellCount,unsigned int flags)1674 virNodeAllocPages(virConnectPtr conn,
1675 unsigned int npages,
1676 unsigned int *pageSizes,
1677 unsigned long long *pageCounts,
1678 int startCell,
1679 unsigned int cellCount,
1680 unsigned int flags)
1681 {
1682 VIR_DEBUG("conn=%p npages=%u pageSizes=%p pageCounts=%p "
1683 "startCell=%d cellCount=%u flags=0x%x",
1684 conn, npages, pageSizes, pageCounts, startCell,
1685 cellCount, flags);
1686
1687 virResetLastError();
1688
1689 virCheckConnectReturn(conn, -1);
1690 virCheckReadOnlyGoto(conn->flags, error);
1691 virCheckNonZeroArgGoto(npages, error);
1692 virCheckNonNullArgGoto(pageSizes, error);
1693 virCheckNonNullArgGoto(pageCounts, error);
1694 virCheckNonZeroArgGoto(cellCount, error);
1695
1696 if (conn->driver->nodeAllocPages) {
1697 int ret;
1698 ret = conn->driver->nodeAllocPages(conn, npages, pageSizes,
1699 pageCounts, startCell,
1700 cellCount, flags);
1701 if (ret < 0)
1702 goto error;
1703 return ret;
1704 }
1705
1706 virReportUnsupportedError();
1707 error:
1708 virDispatchError(conn);
1709 return -1;
1710 }
1711
1712
1713 /*
1714 * virNodeGetSEVInfo:
1715 * @conn: pointer to the hypervisor connection
1716 * @params: where to store SEV information
1717 * @nparams: pointer to number of SEV parameters returned in @params
1718 * @flags: extra flags; not used yet, so callers should always pass 0
1719 *
1720 * If hypervisor supports AMD's SEV feature, then @params will contain various
1721 * platform specific information like PDH and certificate chain. Caller is
1722 * responsible for freeing @params.
1723 *
1724 * Returns 0 in case of success, and -1 in case of failure.
1725 */
1726 int
virNodeGetSEVInfo(virConnectPtr conn,virTypedParameterPtr * params,int * nparams,unsigned int flags)1727 virNodeGetSEVInfo(virConnectPtr conn,
1728 virTypedParameterPtr *params,
1729 int *nparams,
1730 unsigned int flags)
1731 {
1732 int rc;
1733
1734 VIR_DEBUG("conn=%p, params=%p, nparams=%p, flags=0x%x",
1735 conn, params, nparams, flags);
1736
1737 virResetLastError();
1738
1739 virCheckConnectReturn(conn, -1);
1740 virCheckNonNullArgGoto(nparams, error);
1741 virCheckNonNegativeArgGoto(*nparams, error);
1742 virCheckReadOnlyGoto(conn->flags, error);
1743
1744 rc = VIR_DRV_SUPPORTS_FEATURE(conn->driver, conn,
1745 VIR_DRV_FEATURE_TYPED_PARAM_STRING);
1746 if (rc < 0)
1747 goto error;
1748 if (rc)
1749 flags |= VIR_TYPED_PARAM_STRING_OKAY;
1750
1751 if (conn->driver->nodeGetSEVInfo) {
1752 int ret;
1753 ret = conn->driver->nodeGetSEVInfo(conn, params, nparams, flags);
1754 if (ret < 0)
1755 goto error;
1756 return ret;
1757 }
1758
1759 virReportUnsupportedError();
1760
1761 error:
1762 virDispatchError(conn);
1763 return -1;
1764 }
1765