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