mp.h revision 6a5bc4dc98789eb202e249b189f036e5ff9129cc
5b281ba489ca18f0380d7efc7a5108b606cce449vboxsync * IPRT - Multiprocessor.
c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync * Copyright (C) 2008-2010 Oracle Corporation
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * available from http://www.virtualbox.org. This file is free software;
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * you can redistribute it and/or modify it under the terms of the GNU
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * General Public License (GPL) as published by the Free Software
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * The contents of this file may alternatively be used under the terms
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * of the Common Development and Distribution License Version 1.0
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * VirtualBox OSE distribution, in which case the provisions of the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * CDDL are applicable instead of those of the GPL.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * You may elect to license modified versions of this file under the
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * terms and conditions of either the GPL or the CDDL or both.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync/** @defgroup grp_rt_mp RTMp - Multiprocessor
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @ingroup grp_rt
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Gets the identifier of the CPU executing the call.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * When called from a system mode where scheduling is active, like ring-3 or
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * kernel mode with interrupts enabled on some systems, no assumptions should
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * be made about the current CPU when the call returns.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns CPU Id.
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync * Converts a CPU identifier to a CPU set index.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * This may or may not validate the presence of the CPU.
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync * @returns The CPU set index on success, -1 on failure.
5c1381fc884d30a749517579368ff6cb4b43e809vboxsync * @param idCpu The identifier of the CPU.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * Converts a CPU set index to a a CPU identifier.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsync * This may or may not validate the presence of the CPU, so, use
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * RTMpIsCpuPossible for that.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * @returns The corresponding CPU identifier, NIL_RTCPUID on failure.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * @param iCpu The CPU set index.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * Gets the max CPU identifier (inclusive).
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * Intended for brute force enumerations, but use with
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * care as it may be expensive.
3fd65c821ad93f378baf8c75b30dcb6a17a5dd77vboxsync * @returns The current higest CPU identifier value.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * Gets the size of a CPU array that is indexed by CPU set index.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * This takes both online, offline and hot-plugged cpus into account.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @returns Number of elements.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @remarks Use RTMpCpuIdToSetIndex to convert a RTCPUID into an array index.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * Checks if a CPU exists in the system or may possibly be hotplugged later.
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync * @returns true/false accordingly.
5e5603ae40c7a0a884fe91e269b7d6d6c0ba56f5vboxsync * @param idCpu The identifier of the CPU.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Gets set of the CPUs present in the system plus any that may
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * possibly be hotplugged later.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @returns pSet.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param pSet Where to put the set.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * Get the count of CPUs present in the system plus any that may
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * possibly be hotplugged later.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @returns The count.
0cde281779e97ead3181bbd3b628451fa2b1efe1vboxsync * @remarks Don't use this for CPU array sizing, use RTMpGetArraySize instead.
6a5bc4dc98789eb202e249b189f036e5ff9129ccvboxsync * Get the count of phyiscal CPU cores present in the system.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * Gets set of the CPUs present that are currently online.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @returns pSet.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @param pSet Where to put the set.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * Get the count of CPUs that are currently online.
ab7139411cba3600213877c953b69fc11a7ef0cfvboxsync * @return The count.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * Checks if a CPU is online or not.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @returns true/false accordingly.
2a560b28131ee7efa5b73a9e9cbfdb08eae28624vboxsync * @param idCpu The identifier of the CPU.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * Gets set of the CPUs present in the system.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @returns pSet.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param pSet Where to put the set.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsyncRTDECL(PRTCPUSET) RTMpGetPresentSet(PRTCPUSET pSet);
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * Get the count of CPUs that are present in the system.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @return The count.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * Checks if a CPU is present in the system.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @returns true/false accordingly.
e3e8bde164b5715114ebf596187b5512fa9b75advboxsync * @param idCpu The identifier of the CPU.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * Get the current frequency of a CPU.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * The CPU must be online.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @returns The frequency as MHz. 0 if the CPU is offline
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * or the information is not available.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @param idCpu The identifier of the CPU.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsyncRTDECL(uint32_t) RTMpGetCurFrequency(RTCPUID idCpu);
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * Get the maximum frequency of a CPU.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * The CPU must be online.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @returns The frequency as MHz. 0 if the CPU is offline
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * or the information is not available.
5a7d67754026bd3654a2464799f0db1790ecf183vboxsync * @param idCpu The identifier of the CPU.
1df297ea8319f3f3afddb73e6ea2fd9c7f0e5eb4vboxsyncRTDECL(uint32_t) RTMpGetMaxFrequency(RTCPUID idCpu);
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * Get the CPU description string.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * The CPU must be online.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * @returns IPRT status code.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * @param idCpu The identifier of the CPU.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * @param pszBuf The output buffer.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsync * @param cbBuf The size of the output buffer.
c00fd08041e14ed8ad7733165f855bfbbc818a0evboxsyncRTDECL(int) RTMpGetDescription(RTCPUID idCpu, char *pszBuf, size_t cbBuf);
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync * Check if there's work (DPCs on Windows) pending on the current CPU.
d9658602103599d13b5449fc1ea49d765a23e6f1vboxsync * @return true if there's pending work on the current CPU, false otherwise.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Worker function passed to RTMpOnAll, RTMpOnOthers and RTMpOnSpecific that
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * is to be called on the target cpus.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param idCpu The identifier for the CPU the function is called on.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pvUser1 The 1st user argument.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pvUser2 The 2nd user argument.
e0dec59adb362e8486c0622785420ad10e720972vboxsynctypedef DECLCALLBACK(void) FNRTMPWORKER(RTCPUID idCpu, void *pvUser1, void *pvUser2);
e0dec59adb362e8486c0622785420ad10e720972vboxsync/** Pointer to a FNRTMPWORKER. */
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Executes a function on each (online) CPU in the system.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns IPRT status code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VINF_SUCCESS on success.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pfnWorker The worker function.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser1 The first user argument for the worker.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser2 The second user argument for the worker.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @remarks The execution isn't in any way guaranteed to be simultaneous,
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * it might even be serial (cpu by cpu).
e0dec59adb362e8486c0622785420ad10e720972vboxsyncRTDECL(int) RTMpOnAll(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Executes a function on a all other (online) CPUs in the system.
fa86ccda70bc5dd1ae28597340f252b212dcf36dvboxsync * The caller must disable preemption prior to calling this API if the outcome
fa86ccda70bc5dd1ae28597340f252b212dcf36dvboxsync * is to make any sense. But do *not* disable interrupts.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns IPRT status code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VINF_SUCCESS on success.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pfnWorker The worker function.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser1 The first user argument for the worker.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser2 The second user argument for the worker.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @remarks The execution isn't in any way guaranteed to be simultaneous,
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * it might even be serial (cpu by cpu).
e0dec59adb362e8486c0622785420ad10e720972vboxsyncRTDECL(int) RTMpOnOthers(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * Executes a function on a specific CPU in the system.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @returns IPRT status code.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VINF_SUCCESS on success.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VERR_CPU_OFFLINE if the CPU is offline.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @retval VERR_CPU_NOT_FOUND if the CPU wasn't found.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param idCpu The id of the CPU.
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync * @param pfnWorker The worker function.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser1 The first user argument for the worker.
2c19fa7a35e93931f995c196426585b16f8bf2c0vboxsync * @param pvUser2 The second user argument for the worker.
e0dec59adb362e8486c0622785420ad10e720972vboxsyncRTDECL(int) RTMpOnSpecific(RTCPUID idCpu, PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * Pokes the specified CPU.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * This should cause the execution on the CPU to be interrupted and forcing it
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * to enter kernel context. It is optimized version of a RTMpOnSpecific call
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * with a worker which returns immediately.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * @returns IPRT status code.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * system. The caller must not automatically assume that this API works
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * when any of the RTMpOn* APIs works. This is because not all systems
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * supports unicast MP events and this API will not be implemented as a
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * broadcast.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * @retval VERR_CPU_OFFLINE if the CPU is offline.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * @retval VERR_CPU_NOT_FOUND if the CPU wasn't found.
1d8f69ceb39fecbf9a7c95dbac083f3ce5c4efd9vboxsync * @param idCpu The id of the CPU to poke.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * MP event, see FNRTMPNOTIFICATION.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** The CPU goes online. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync /** The CPU goes offline. */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * Notification callback.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * The context this is called in differs a bit from platform to
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * platform, so be careful while in here.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param idCpu The CPU this applies to.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param enmEvent The event.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pvUser The user argument.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsynctypedef DECLCALLBACK(void) FNRTMPNOTIFICATION(RTMPEVENT enmEvent, RTCPUID idCpu, void *pvUser);
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync/** Pointer to a FNRTMPNOTIFICATION(). */
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * Registers a notification callback for cpu events.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * On platforms which doesn't do cpu offline/online events this API
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * will just be a no-op that pretends to work.
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * @todo We'll be adding a flag to this soon to indicate whether the callback should be called on all
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * CPUs that are currently online while it's being registered. This is to help avoid some race
34bfec0bd844700e3b769dcfad1a869ca6b8a0d8vboxsync * conditions (we'll hopefully be able to implement this on linux, solaris/win is no issue).
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @retval VINF_SUCCESS on success.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @retval VERR_NO_MEMORY if a registration record cannot be allocated.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @retval VERR_ALREADY_EXISTS if the pfnCallback and pvUser already exist
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * in the callback list.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pfnCallback The callback.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pvUser The user argument to the callback function.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTDECL(int) RTMpNotificationRegister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * This deregisters a notification callback registered via RTMpNotificationRegister().
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * The pfnCallback and pvUser arguments must be identical to the registration call
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * of we won't find the right entry.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @returns IPRT status code.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @retval VINF_SUCCESS on success.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @retval VERR_NOT_FOUND if no matching entry was found.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pfnCallback The callback.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsync * @param pvUser The user argument to the callback function.
0aaf889969ebdaba8a310db13adcec8c10174796vboxsyncRTDECL(int) RTMpNotificationDeregister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
165b506f4c024dabd5a4caaeda31c66712d154eavboxsync#endif /* IN_RING0 */