[1] | 1 | /** @file
|
---|
[11323] | 2 | * IPRT - System Information.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
[1] | 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
|
---|
[5999] | 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.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_system_h
|
---|
| 27 | #define IPRT_INCLUDED_system_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[1] | 31 |
|
---|
| 32 | #include <iprt/cdefs.h>
|
---|
| 33 | #include <iprt/types.h>
|
---|
| 34 |
|
---|
| 35 |
|
---|
[20374] | 36 | RT_C_DECLS_BEGIN
|
---|
[1] | 37 |
|
---|
| 38 | /** @defgroup grp_rt_system RTSystem - System Information
|
---|
| 39 | * @ingroup grp_rt
|
---|
| 40 | * @{
|
---|
| 41 | */
|
---|
| 42 |
|
---|
[11350] | 43 | /**
|
---|
| 44 | * Info level for RTSystemGetOSInfo().
|
---|
| 45 | */
|
---|
| 46 | typedef 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) */
|
---|
[11352] | 52 | RTSYSOSINFO_SERVICE_PACK, /**< Service/fix pack level, optional. */
|
---|
[11350] | 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 | */
|
---|
| 73 | RTDECL(int) RTSystemQueryOSInfo(RTSYSOSINFO enmInfo, char *pszInfo, size_t cchInfo);
|
---|
| 74 |
|
---|
[19508] | 75 | /**
|
---|
[33502] | 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 | */
|
---|
| 88 | RTDECL(int) RTSystemQueryTotalRam(uint64_t *pcb);
|
---|
| 89 |
|
---|
| 90 | /**
|
---|
[19508] | 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.
|
---|
[33540] | 98 | * @retval VINF_SUCCESS and *pcb on success.
|
---|
[19508] | 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 | */
|
---|
[33502] | 104 | RTDECL(int) RTSystemQueryAvailableRam(uint64_t *pcb);
|
---|
[11350] | 105 |
|
---|
[19508] | 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
|
---|
[33540] | 111 | * be able to determine an absolute max limit for how much fixed memory it is
|
---|
[19508] | 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,
|
---|
[33540] | 119 | * - fixed (not pageable) kernel allocations - like for instance
|
---|
[19508] | 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 | *
|
---|
[33540] | 135 | * @retval VINF_SUCCESS and *pcb on success.
|
---|
[19508] | 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 | */
|
---|
| 154 | RTDECL(int) RTSystemQueryUnavailableRam(uint64_t *pcb);
|
---|
| 155 |
|
---|
| 156 |
|
---|
[26600] | 157 | /**
|
---|
| 158 | * The DMI strings.
|
---|
| 159 | */
|
---|
| 160 | typedef 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,
|
---|
[26608] | 168 | /** The product UUID. */
|
---|
| 169 | RTSYSDMISTR_PRODUCT_UUID,
|
---|
| 170 | /** The product serial. */
|
---|
| 171 | RTSYSDMISTR_PRODUCT_SERIAL,
|
---|
[29560] | 172 | /** The system manufacturer. */
|
---|
| 173 | RTSYSDMISTR_MANUFACTURER,
|
---|
[26600] | 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 | *
|
---|
[26608] | 183 | * @returns IPRT status code.
|
---|
[26600] | 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.
|
---|
[26608] | 194 | * @param pszBuf Where to store the string. This is always
|
---|
| 195 | * terminated, even on error.
|
---|
[26600] | 196 | * @param cbBuf The buffer size.
|
---|
| 197 | */
|
---|
| 198 | RTDECL(int) RTSystemQueryDmiString(RTSYSDMISTR enmString, char *pszBuf, size_t cbBuf);
|
---|
| 199 |
|
---|
[39721] | 200 | /** @name Flags for RTSystemReboot and RTSystemShutdown.
|
---|
| 201 | * @{ */
|
---|
| 202 | /** Reboot the system after shutdown. */
|
---|
| 203 | #define RTSYSTEM_SHUTDOWN_REBOOT UINT32_C(0)
|
---|
[39727] | 204 | /** Reboot the system after shutdown.
|
---|
[48934] | 205 | * The call may return VINF_SYS_MAY_POWER_OFF if the OS /
|
---|
[39727] | 206 | * hardware combination may power off instead of halting. */
|
---|
[39721] | 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)
|
---|
[1] | 227 | /** @} */
|
---|
| 228 |
|
---|
[39721] | 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.
|
---|
[39727] | 234 | * @retval VINF_SUCCESS
|
---|
[48934] | 235 | * @retval VINF_SYS_MAY_POWER_OFF
|
---|
| 236 | * @retval VERR_SYS_SHUTDOWN_FAILED
|
---|
| 237 | * @retval VERR_SYS_CANNOT_POWER_OFF
|
---|
| 238 | *
|
---|
[39721] | 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 | */
|
---|
| 246 | RTDECL(int) RTSystemShutdown(RTMSINTERVAL cMsDelay, uint32_t fFlags, const char *pszLogMsg);
|
---|
| 247 |
|
---|
[57078] | 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
|
---|
[57094] | 252 | * presence of a virtual machine monitor (VMM) unless it openly tells us it is
|
---|
[57078] | 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
|
---|
[57094] | 258 | * version and such, add one or two new APIs.
|
---|
[57078] | 259 | */
|
---|
| 260 | RTDECL(bool) RTSystemIsInsideVM(void);
|
---|
| 261 |
|
---|
[71294] | 262 | #ifdef RT_OS_WINDOWS
|
---|
| 263 |
|
---|
| 264 | /**
|
---|
| 265 | * Get the Windows NT build number.
|
---|
| 266 | *
|
---|
| 267 | * @returns NT build number.
|
---|
| 268 | *
|
---|
| 269 | * @remarks Windows NT only. Requires IPRT to be initialized.
|
---|
| 270 | */
|
---|
[71295] | 271 | RTDECL(uint32_t) RTSystemGetNtBuildNo(void);
|
---|
[71294] | 272 |
|
---|
[76073] | 273 | /** Makes an NT version for comparison with RTSystemGetNtVersion(). */
|
---|
| 274 | # define RTSYSTEM_MAKE_NT_VERSION(a_uMajor, a_uMinor, a_uBuild) \
|
---|
| 275 | ( ((uint64_t)(a_uMajor) << 52) | ((uint64_t)((a_uMinor) & 0xfffU) << 40) | ((uint32_t)(a_uBuild)) )
|
---|
| 276 |
|
---|
| 277 | /**
|
---|
| 278 | * Get the Windows NT version number.
|
---|
| 279 | *
|
---|
| 280 | * @returns Version formatted using RTSYSTEM_MAKE_NT_VERSION().
|
---|
| 281 | *
|
---|
| 282 | * @remarks Windows NT only. Requires IPRT to be initialized.
|
---|
| 283 | */
|
---|
[76090] | 284 | RTDECL(uint64_t) RTSystemGetNtVersion(void);
|
---|
[76073] | 285 |
|
---|
[71294] | 286 | #endif /* RT_OS_WINDOWS */
|
---|
| 287 |
|
---|
[39721] | 288 | /** @} */
|
---|
| 289 |
|
---|
[20374] | 290 | RT_C_DECLS_END
|
---|
[1] | 291 |
|
---|
[76585] | 292 | #endif /* !IPRT_INCLUDED_system_h */
|
---|
[1] | 293 |
|
---|