VirtualBox

source: vbox/trunk/include/iprt/system.h@ 93176

Last change on this file since 93176 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 13.1 KB
Line 
1/** @file
2 * IPRT - System Information.
3 */
4
5/*
6 * Copyright (C) 2006-2022 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef IPRT_INCLUDED_system_h
27#define IPRT_INCLUDED_system_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34
35
36RT_C_DECLS_BEGIN
37
38/** @defgroup grp_rt_system RTSystem - System Information
39 * @ingroup grp_rt
40 * @{
41 */
42
43/**
44 * Info level for RTSystemGetOSInfo().
45 */
46typedef enum RTSYSOSINFO
47{
48 RTSYSOSINFO_INVALID = 0, /**< The usual invalid entry. */
49 RTSYSOSINFO_PRODUCT, /**< OS product name. (uname -o) */
50 RTSYSOSINFO_RELEASE, /**< OS release. (uname -r) */
51 RTSYSOSINFO_VERSION, /**< OS version, optional. (uname -v) */
52 RTSYSOSINFO_SERVICE_PACK, /**< Service/fix pack level, optional. */
53 RTSYSOSINFO_END /**< End of the valid info levels. */
54} RTSYSOSINFO;
55
56
57/**
58 * Queries information about the OS.
59 *
60 * @returns IPRT status code.
61 * @retval VINF_SUCCESS on success.
62 * @retval VERR_INVALID_PARAMETER if enmInfo is invalid.
63 * @retval VERR_INVALID_POINTER if pszInfoStr is invalid.
64 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will
65 * contain the chopped off result in this case, provided cchInfo isn't 0.
66 * @retval VERR_NOT_SUPPORTED if the info level isn't implemented. The buffer will
67 * contain an empty string.
68 *
69 * @param enmInfo The OS info level.
70 * @param pszInfo Where to store the result.
71 * @param cchInfo The size of the output buffer.
72 */
73RTDECL(int) RTSystemQueryOSInfo(RTSYSOSINFO enmInfo, char *pszInfo, size_t cchInfo);
74
75/**
76 * Queries the total amount of RAM in the system.
77 *
78 * This figure does not given any information about how much memory is
79 * currently available. Use RTSystemQueryAvailableRam instead.
80 *
81 * @returns IPRT status code.
82 * @retval VINF_SUCCESS and *pcb on sucess.
83 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
84 * caller.
85 *
86 * @param pcb Where to store the result (in bytes).
87 */
88RTDECL(int) RTSystemQueryTotalRam(uint64_t *pcb);
89
90/**
91 * Queries the total amount of RAM accessible to the system.
92 *
93 * This figure should not include memory that is installed but not used,
94 * nor memory that will be slow to bring online. The definition of 'slow'
95 * here is slower than swapping out a MB of pages to disk.
96 *
97 * @returns IPRT status code.
98 * @retval VINF_SUCCESS and *pcb on success.
99 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
100 * caller.
101 *
102 * @param pcb Where to store the result (in bytes).
103 */
104RTDECL(int) RTSystemQueryAvailableRam(uint64_t *pcb);
105
106/**
107 * Queries the amount of RAM that is currently locked down or in some other
108 * way made impossible to virtualize within reasonably short time.
109 *
110 * The purposes of this API is, when combined with RTSystemQueryTotalRam, to
111 * be able to determine an absolute max limit for how much fixed memory it is
112 * (theoretically) possible to allocate (or lock down).
113 *
114 * The kind memory covered by this function includes:
115 * - locked (wired) memory - like for instance RTR0MemObjLockUser
116 * and RTR0MemObjLockKernel makes,
117 * - kernel pools and heaps - like for instance the ring-0 variant
118 * of RTMemAlloc taps into,
119 * - fixed (not pageable) kernel allocations - like for instance
120 * all the RTR0MemObjAlloc* functions makes,
121 * - any similar memory that isn't easily swapped out, discarded,
122 * or flushed to disk.
123 *
124 * This works against the value returned by RTSystemQueryTotalRam, and
125 * the value reported by this function can never be larger than what a
126 * call to RTSystemQueryTotalRam returns.
127 *
128 * The short time term here is relative to swapping to disk like in
129 * RTSystemQueryTotalRam. This could mean that (part of) the dirty buffers
130 * in the dynamic I/O cache could be included in the total. If the dynamic
131 * I/O cache isn't likely to either flush buffers when the load increases
132 * and put them back into normal circulation, they should be included in
133 * the memory accounted for here.
134 *
135 * @retval VINF_SUCCESS and *pcb on success.
136 * @retval VERR_NOT_SUPPORTED if the information isn't available on the
137 * system in general. The caller must handle this scenario.
138 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
139 * caller.
140 *
141 * @param pcb Where to store the result (in bytes).
142 *
143 * @remarks This function could've been inverted and called
144 * RTSystemQueryAvailableRam, but that might give impression that
145 * it would be possible to allocate the amount of memory it
146 * indicates for a single purpose, something which would be very
147 * improbable on most systems.
148 *
149 * @remarks We might have to add another output parameter to this function
150 * that indicates if some of the memory kinds listed above cannot
151 * be accounted for on the system and therefore is not include in
152 * the returned amount.
153 */
154RTDECL(int) RTSystemQueryUnavailableRam(uint64_t *pcb);
155
156
157/**
158 * The DMI strings.
159 */
160typedef enum RTSYSDMISTR
161{
162 /** Invalid zero entry. */
163 RTSYSDMISTR_INVALID = 0,
164 /** The product name. */
165 RTSYSDMISTR_PRODUCT_NAME,
166 /** The product version. */
167 RTSYSDMISTR_PRODUCT_VERSION,
168 /** The product UUID. */
169 RTSYSDMISTR_PRODUCT_UUID,
170 /** The product serial. */
171 RTSYSDMISTR_PRODUCT_SERIAL,
172 /** The system manufacturer. */
173 RTSYSDMISTR_MANUFACTURER,
174 /** The end of the valid strings. */
175 RTSYSDMISTR_END,
176 /** The usual 32-bit hack. */
177 RTSYSDMISTR_32_BIT_HACK = 0x7fffffff
178} RTSYSDMISTR;
179
180/**
181 * Queries a DMI string.
182 *
183 * @returns IPRT status code.
184 * @retval VINF_SUCCESS on success.
185 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will
186 * contain the chopped off result in this case, provided cbBuf isn't 0.
187 * @retval VERR_ACCESS_DENIED if the information isn't accessible to the
188 * caller.
189 * @retval VERR_NOT_SUPPORTED if the information isn't available on the system
190 * in general. The caller must expect this status code and deal with
191 * it.
192 *
193 * @param enmString Which string to query.
194 * @param pszBuf Where to store the string. This is always
195 * terminated, even on error.
196 * @param cbBuf The buffer size.
197 */
198RTDECL(int) RTSystemQueryDmiString(RTSYSDMISTR enmString, char *pszBuf, size_t cbBuf);
199
200/** @name Flags for RTSystemReboot and RTSystemShutdown.
201 * @{ */
202/** Reboot the system after shutdown. */
203#define RTSYSTEM_SHUTDOWN_REBOOT UINT32_C(0)
204/** Reboot the system after shutdown.
205 * The call may return VINF_SYS_MAY_POWER_OFF if the OS /
206 * hardware combination may power off instead of halting. */
207#define RTSYSTEM_SHUTDOWN_HALT UINT32_C(1)
208/** Power off the system after shutdown.
209 * This may be equvivalent to a RTSYSTEM_SHUTDOWN_HALT on systems where we
210 * cannot figure out whether the hardware/OS implements the actual powering
211 * off. If we can figure out that it's not supported, an
212 * VERR_SYS_CANNOT_POWER_OFF error is raised. */
213#define RTSYSTEM_SHUTDOWN_POWER_OFF UINT32_C(2)
214/** Power off the system after shutdown, or halt it if that's not possible. */
215#define RTSYSTEM_SHUTDOWN_POWER_OFF_HALT UINT32_C(3)
216/** The shutdown action mask. */
217#define RTSYSTEM_SHUTDOWN_ACTION_MASK UINT32_C(3)
218/** Unplanned shutdown/reboot. */
219#define RTSYSTEM_SHUTDOWN_UNPLANNED UINT32_C(0)
220/** Planned shutdown/reboot. */
221#define RTSYSTEM_SHUTDOWN_PLANNED RT_BIT_32(2)
222/** Force the system to shutdown/reboot regardless of objecting application
223 * or other stuff. This flag might not be realized on all systems. */
224#define RTSYSTEM_SHUTDOWN_FORCE RT_BIT_32(3)
225/** Parameter validation mask. */
226#define RTSYSTEM_SHUTDOWN_VALID_MASK UINT32_C(0x0000000f)
227/** @} */
228
229/**
230 * Shuts down the system.
231 *
232 * @returns IPRT status code on failure, on success it may or may not return
233 * depending on the OS.
234 * @retval VINF_SUCCESS
235 * @retval VINF_SYS_MAY_POWER_OFF
236 * @retval VERR_SYS_SHUTDOWN_FAILED
237 * @retval VERR_SYS_CANNOT_POWER_OFF
238 *
239 * @param cMsDelay The delay before the actual reboot. If this is
240 * not supported by the OS, an immediate reboot
241 * will be performed.
242 * @param fFlags Shutdown flags, see RTSYSTEM_SHUTDOWN_XXX.
243 * @param pszLogMsg Message for the log and users about why we're
244 * shutting down.
245 */
246RTDECL(int) RTSystemShutdown(RTMSINTERVAL cMsDelay, uint32_t fFlags, const char *pszLogMsg);
247
248/**
249 * Checks if we're executing inside a virtual machine (VM).
250 *
251 * The current implemention is very simplistic and won't try to detect the
252 * presence of a virtual machine monitor (VMM) unless it openly tells us it is
253 * there.
254 *
255 * @returns true if inside a VM, false if on real hardware.
256 *
257 * @todo If more information is needed, like which VMM it is and which
258 * version and such, add one or two new APIs.
259 */
260RTDECL(bool) RTSystemIsInsideVM(void);
261
262/**
263 * System firmware types.
264 */
265typedef enum RTSYSFWTYPE
266{
267 /** Invalid zero value. */
268 RTSYSFWTYPE_INVALID = 0,
269 /** Unknown firmware. */
270 RTSYSFWTYPE_UNKNOWN,
271 /** Firmware is BIOS. */
272 RTSYSFWTYPE_BIOS,
273 /** Firmware is UEFI. */
274 RTSYSFWTYPE_UEFI,
275 /** End valid firmware values (exclusive). */
276 RTSYSFWTYPE_END,
277 /** The usual 32-bit hack. */
278 RTSYSFWTYPE_32_BIT_HACK = 0x7fffffff
279} RTSYSFWTYPE;
280/** Pointer to a system firmware type. */
281typedef RTSYSFWTYPE *PRTSYSFWTYPE;
282
283/**
284 * Queries the system's firmware type.
285 *
286 * @returns IPRT status code.
287 * @retval VERR_NOT_SUPPORTED if not supported or implemented.
288 * @param penmType Where to return the firmware type on success.
289 */
290RTDECL(int) RTSystemQueryFirmwareType(PRTSYSFWTYPE penmType);
291
292/**
293 * Translates the @a enmType value to a string.
294 *
295 * @returns Read-only name.
296 * @param enmType The firmware type to convert to string.
297 */
298RTDECL(const char *) RTSystemFirmwareTypeName(RTSYSFWTYPE enmType);
299
300/**
301 * Boolean firmware values queriable via RTSystemQueryFirmwareBoolean().
302 */
303typedef enum RTSYSFWBOOL
304{
305 /** Invalid property, do not use. */
306 RTSYSFWBOOL_INVALID = 0,
307 /** Whether Secure Boot is enabled or not (type: boolean). */
308 RTSYSFWBOOL_SECURE_BOOT,
309 /** End of valid */
310 RTSYSFWBOOL_END,
311 /** The usual 32-bit hack. */
312 RTSYSFWBOOL_32_BIT_HACK = 0x7fffffff
313} RTSYSFWBOOL;
314
315/**
316 * Queries the value of a firmware property.
317 *
318 * @returns IPRT status code.
319 * @retval VERR_NOT_SUPPORTED if we cannot query firmware properties on the host.
320 * @retval VERR_SYS_UNSUPPORTED_FIRMWARE_PROPERTY if @a enmBoolean isn't
321 * supported.
322 * @param enmBoolean The value to query.
323 * @param pfValue Where to return the value.
324 */
325RTDECL(int) RTSystemQueryFirmwareBoolean(RTSYSFWBOOL enmBoolean, bool *pfValue);
326
327#ifdef RT_OS_WINDOWS
328
329/**
330 * Get the Windows NT build number.
331 *
332 * @returns NT build number.
333 *
334 * @remarks Windows NT only. Requires IPRT to be initialized.
335 */
336RTDECL(uint32_t) RTSystemGetNtBuildNo(void);
337
338/** Makes an NT version for comparison with RTSystemGetNtVersion(). */
339# define RTSYSTEM_MAKE_NT_VERSION(a_uMajor, a_uMinor, a_uBuild) \
340 ( ((uint64_t)(a_uMajor) << 52) | ((uint64_t)((a_uMinor) & 0xfffU) << 40) | ((uint32_t)(a_uBuild)) )
341/** Extracts the major version number from a RTSYSTEM_MAKE_NT_VERSION value. */
342# define RTSYSTEM_NT_VERSION_GET_MAJOR(a_uNtVersion) ((uint32_t)((a_uNtVersion) >> 52))
343/** Extracts the minor version number from a RTSYSTEM_MAKE_NT_VERSION value. */
344# define RTSYSTEM_NT_VERSION_GET_MINOR(a_uNtVersion) ((uint32_t)((a_uNtVersion) >> 40) & UINT32_C(0xfff))
345/** Extracts the build number from a RTSYSTEM_MAKE_NT_VERSION value. */
346# define RTSYSTEM_NT_VERSION_GET_BUILD(a_uNtVersion) ((uint32_t)(a_uNtVersion))
347
348/**
349 * Get the Windows NT version number.
350 *
351 * @returns Version formatted using RTSYSTEM_MAKE_NT_VERSION().
352 *
353 * @remarks Windows NT only. Requires IPRT to be initialized.
354 */
355RTDECL(uint64_t) RTSystemGetNtVersion(void);
356
357#endif /* RT_OS_WINDOWS */
358
359/** @} */
360
361RT_C_DECLS_END
362
363#endif /* !IPRT_INCLUDED_system_h */
364
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette