mp.h revision fa86ccda70bc5dd1ae28597340f252b212dcf36d
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * IPRT - Multiprocessor.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Copyright (C) 2008 Sun Microsystems, Inc.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * available from http://www.virtualbox.org. This file is free software;
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * you can redistribute it and/or modify it under the terms of the GNU
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * General Public License (GPL) as published by the Free Software
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The contents of this file may alternatively be used under the terms
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * of the Common Development and Distribution License Version 1.0
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * VirtualBox OSE distribution, in which case the provisions of the
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * CDDL are applicable instead of those of the GPL.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * You may elect to license modified versions of this file under the
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * terms and conditions of either the GPL or the CDDL or both.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
5067a9619d7131c54d4ebb371d9dac91abdd34f6vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * additional information or have any questions.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync/** @defgroup grp_rt_mp RTMp - Multiprocessor
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @ingroup grp_rt
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Gets the identifier of the CPU executing the call.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * When called from a system mode where scheduling is active, like ring-3 or
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * kernel mode with interrupts enabled on some systems, no assumptions should
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * be made about the current CPU when the call returns.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns CPU Id.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Converts a CPU identifier to a CPU set index.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * This may or may not validate the presence of the CPU.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @returns The CPU set index on success, -1 on failure.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @param idCpu The identifier of the CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Converts a CPU set index to a a CPU identifier.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * This may or may not validate the presence of the CPU, so, use
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * RTMpIsCpuPossible for that.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns The corresponding CPU identifier, NIL_RTCPUID on failure.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param iCpu The CPU set index.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Gets the max CPU identifier (inclusive).
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Inteded for brute force enumerations, but use with
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * care as it may be expensive.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns The current higest CPU identifier value.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Checks if a CPU exists in the system or may possibly be hotplugged later.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns true/false accordingly.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The identifier of the CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Gets set of the CPUs present in the system pluss any that may
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * possibly be hotplugged later.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns pSet.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pSet Where to put the set.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Get the count of CPUs present in the system plus any that may
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * possibly be hotplugged later.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @return The count.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Gets set of the CPUs present that are currently online.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns pSet.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pSet Where to put the set.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Get the count of CPUs that are currently online.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @return The count.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Checks if a CPU is online or not.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns true/false accordingly.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The identifier of the CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Gets set of the CPUs present in the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns pSet.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @param pSet Where to put the set.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(PRTCPUSET) RTMpGetPresentSet(PRTCPUSET pSet);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Get the count of CPUs that are present in the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @return The count.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Checks if a CPU is present in the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns true/false accordingly.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The identifier of the CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Get the current frequency of a CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The CPU must be online.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns The frequency as MHz. 0 if the CPU is offline
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * or the information is not available.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The identifier of the CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(uint32_t) RTMpGetCurFrequency(RTCPUID idCpu);
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Get the maximum frequency of a CPU.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The CPU must be online.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns The frequency as MHz. 0 if the CPU is offline
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * or the information is not available.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The identifier of the CPU.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsyncRTDECL(uint32_t) RTMpGetMaxFrequency(RTCPUID idCpu);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Check if there's work (DPCs on Windows) pending on the current CPU.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @return true if there's pending work on the current CPU, false otherwise.
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsync * Worker function passed to RTMpOnAll, RTMpOnOthers and RTMpOnSpecific that
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsync * is to be called on the target cpus.
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsync * @param idCpu The identifier for the CPU the function is called on.
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsync * @param pvUser1 The 1st user argument.
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsync * @param pvUser2 The 2nd user argument.
ecb98c0e709a5cebd8877fb39f61a821804024bcvboxsynctypedef DECLCALLBACK(void) FNRTMPWORKER(RTCPUID idCpu, void *pvUser1, void *pvUser2);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync/** Pointer to a FNRTMPWORKER. */
5a8e015c4fe7f3bfb93478a55b298aa7f21b5e08vboxsync * Executes a function on each (online) CPU in the system.
5a8e015c4fe7f3bfb93478a55b298aa7f21b5e08vboxsync * @returns IPRT status code.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VINF_SUCCESS on success.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pfnWorker The worker function.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser1 The first user argument for the worker.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser2 The second user argument for the worker.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @remarks The execution isn't in any way guaranteed to be simultaneous,
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * it might even be serial (cpu by cpu).
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(int) RTMpOnAll(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Executes a function on a all other (online) CPUs in the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The caller must disable preemption prior to calling this API if the outcome
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * is to make any sense. But do *not* disable interrupts.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns IPRT status code.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VINF_SUCCESS on success.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pfnWorker The worker function.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser1 The first user argument for the worker.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @param pvUser2 The second user argument for the worker.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @remarks The execution isn't in any way guaranteed to be simultaneous,
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * it might even be serial (cpu by cpu).
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(int) RTMpOnOthers(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Executes a function on a specific CPU in the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns IPRT status code.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VINF_SUCCESS on success.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_CPU_OFFLINE if the CPU is offline.
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * @retval VERR_CPU_NOT_FOUND if the CPU wasn't found.
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * @param idCpu The id of the CPU.
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * @param pfnWorker The worker function.
728b52f802ac19865bd4aa8e9ade8f506a9e6c10vboxsync * @param pvUser1 The first user argument for the worker.
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * @param pvUser2 The second user argument for the worker.
83d61602c6968041692aa7203ee51c4085c7e460vboxsyncRTDECL(int) RTMpOnSpecific(RTCPUID idCpu, PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Pokes the specified CPU.
795d02542d53f15030f205374c4581d99ef581a4vboxsync * This should cause the execution on the CPU to be interrupted and forcing it
795d02542d53f15030f205374c4581d99ef581a4vboxsync * to enter kernel context. It is optimized version of a RTMpOnSpecific call
795d02542d53f15030f205374c4581d99ef581a4vboxsync * with a worker which returns immediately.
795d02542d53f15030f205374c4581d99ef581a4vboxsync * @returns IPRT status code.
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * @retval VERR_NOT_SUPPORTED if this kind of operation isn't supported by the
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * system. The caller must not automatically assume that this API works
83d61602c6968041692aa7203ee51c4085c7e460vboxsync * when any of the RTMpOn* APIs works. This is because not all systems
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * supports unicast MP events and this API will not be implemented as a
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * broadcast.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_CPU_OFFLINE if the CPU is offline.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_CPU_NOT_FOUND if the CPU wasn't found.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param idCpu The id of the CPU to poke.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * MP event, see FNRTMPNOTIFICATION.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync /** The CPU goes online. */
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync /** The CPU goes offline. */
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * Notification callback.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The context this is called in differs a bit from platform to
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * platform, so be careful while in here.
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * @param idCpu The CPU this applies to.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param enmEvent The event.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser The user argument.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsynctypedef DECLCALLBACK(void) FNRTMPNOTIFICATION(RTMPEVENT enmEvent, RTCPUID idCpu, void *pvUser);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync/** Pointer to a FNRTMPNOTIFICATION(). */
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync * Registers a notification callback for cpu events.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * On platforms which doesn't do cpu offline/online events this API
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * will just be a no-op that pretends to work.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @todo We'll be adding a flag to this soon to indicate whether the callback should be called on all
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * CPUs that are currently online while it's being registered. This is to help avoid some race
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * conditions (we'll hopefully be able to implement this on linux, solaris/win is no issue).
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns IPRT status code.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VINF_SUCCESS on success.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_NO_MEMORY if a registration record cannot be allocated.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_ALREADY_EXISTS if the pfnCallback and pvUser already exist
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * in the callback list.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pfnCallback The callback.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser The user argument to the callback function.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(int) RTMpNotificationRegister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * This deregisters a notification callback registered via RTMpNotificationRegister().
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * The pfnCallback and pvUser arguments must be identical to the registration call
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * of we won't find the right entry.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @returns IPRT status code.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VINF_SUCCESS on success.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @retval VERR_NOT_FOUND if no matching entry was found.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pfnCallback The callback.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsync * @param pvUser The user argument to the callback function.
41d680dd6eb0287afc200adc5b0d61b07a32b72dvboxsyncRTDECL(int) RTMpNotificationDeregister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
ad4f6ac2063d9b48efd9c3193442136a8c7c890avboxsync#endif /* IN_RING0 */