VirtualBox

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

Last change on this file since 103224 was 100307, checked in by vboxsync, 16 months ago

Runtime,Additions,HostDrivers: Provide API to query the host page size and associated parameters for architectures where the used page size can vary (like on linux.arm64 depending on the kernel config), bugref:10476

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