include/iprt/mp.h

   1 /** @file
   2  * IPRT - Multiprocessor.
   3  */
   4
   5 /*
   6  * Copyright (C) 2008-2024 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_mp_h
  37 #define IPRT_INCLUDED_mp_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
  46 RT_C_DECLS_BEGIN
  47
  48 /** @defgroup grp_rt_mp RTMp - Multiprocessor
  49  * @ingroup grp_rt
  50  * @{
  51  */
  52
  53 /**
  54  * Gets the identifier of the CPU executing the call.
  55  *
  56  * When called from a system mode where scheduling is active, like ring-3 or
  57  * kernel mode with interrupts enabled on some systems, no assumptions should
  58  * be made about the current CPU when the call returns.
  59  *
  60  * @returns CPU Id.
  61  */
  62 RTDECL(RTCPUID) RTMpCpuId(void);
  63
  64 /**
  65  * Get the CPU set index of the CPU executing the call.
  66  *
  67  * Same scheduling warnings as for RTMpCpuId().
  68  *
  69  * @returns CPU set index.
  70  */
  71 RTDECL(int) RTMpCurSetIndex(void);
  72
  73 /**
  74  * Get the CPU set index and identifier of the CPU executing the call.
  75  *
  76  * Same scheduling warnings as for RTMpCpuId().
  77  *
  78  * @returns CPU set index.
  79  * @param   pidCpu      Where to return the CPU identifier. (not optional)
  80  */
  81 RTDECL(int) RTMpCurSetIndexAndId(PRTCPUID pidCpu);
  82
  83 /**
  84  * Converts a CPU identifier to a CPU set index.
  85  *
  86  * This may or may not validate the presence of the CPU.
  87  *
  88  * @returns The CPU set index on success, -1 on failure.
  89  * @param   idCpu       The identifier of the CPU.
  90  */
  91 RTDECL(int) RTMpCpuIdToSetIndex(RTCPUID idCpu);
  92
  93 /**
  94  * Converts a CPU set index to a a CPU identifier.
  95  *
  96  * This may or may not validate the presence of the CPU, so, use
  97  * RTMpIsCpuPossible for that.
  98  *
  99  * @returns The corresponding CPU identifier, NIL_RTCPUID on failure.
 100  * @param   iCpu    The CPU set index.
 101  */
 102 RTDECL(RTCPUID) RTMpCpuIdFromSetIndex(int iCpu);
 103
 104 /**
 105  * Translates an NT process group member to a CPU set index.
 106  *
 107  * @returns CPU set index, -1 if not valid.
 108  * @param   idxGroup        The CPU group.
 109  * @param   idxMember       The CPU group member number.
 110  *
 111  * @remarks Only available on Windows.
 112  */
 113 RTDECL(int) RTMpSetIndexFromCpuGroupMember(uint32_t idxGroup, uint32_t idxMember);
 114
 115 /**
 116  * Gets the member numbers for a CPU group.
 117  *
 118  * @returns Maximum number of group members.
 119  * @param   idxGroup        The CPU group.
 120  * @param   pcActive        Where to return the number of active members.
 121  *
 122  * @remarks Only available on Windows.
 123  */
 124 RTDECL(uint32_t) RTMpGetCpuGroupCounts(uint32_t idxGroup, uint32_t *pcActive);
 125
 126 /**
 127  * Get the maximum number of CPU groups.
 128  *
 129  * @returns Maximum number of CPU groups.
 130  *
 131  * @remarks Only available on Windows.
 132  */
 133 RTDECL(uint32_t) RTMpGetMaxCpuGroupCount(void);
 134
 135 /**
 136  * Gets the max CPU identifier (inclusive).
 137  *
 138  * Intended for brute force enumerations, but use with
 139  * care as it may be expensive.
 140  *
 141  * @returns The current higest CPU identifier value.
 142  */
 143 RTDECL(RTCPUID) RTMpGetMaxCpuId(void);
 144
 145 /**
 146  * Gets the size of a CPU array that is indexed by CPU set index.
 147  *
 148  * This takes both online, offline and hot-plugged cpus into account.
 149  *
 150  * @returns Number of elements.
 151  *
 152  * @remarks Use RTMpCpuIdToSetIndex to convert a RTCPUID into an array index.
 153  */
 154 RTDECL(uint32_t) RTMpGetArraySize(void);
 155
 156 /**
 157  * Checks if a CPU exists in the system or may possibly be hotplugged later.
 158  *
 159  * @returns true/false accordingly.
 160  * @param   idCpu       The identifier of the CPU.
 161  */
 162 RTDECL(bool) RTMpIsCpuPossible(RTCPUID idCpu);
 163
 164 /**
 165  * Gets set of the CPUs present in the system plus any that may
 166  * possibly be hotplugged later.
 167  *
 168  * @returns pSet.
 169  * @param   pSet    Where to put the set.
 170  */
 171 RTDECL(PRTCPUSET) RTMpGetSet(PRTCPUSET pSet);
 172
 173 /**
 174  * Get the count of CPUs present in the system plus any that may
 175  * possibly be hotplugged later.
 176  *
 177  * @returns The count.
 178  * @remarks Don't use this for CPU array sizing, use RTMpGetArraySize instead.
 179  */
 180 RTDECL(RTCPUID) RTMpGetCount(void);
 181
 182 /**
 183  * Get the count of physical CPU cores present in the system plus any that may
 184  * possibly be hotplugged later.
 185  *
 186  * @returns The number of cores.
 187  */
 188 RTDECL(RTCPUID) RTMpGetCoreCount(void);
 189
 190 /**
 191  * Gets set of the CPUs present that are currently online.
 192  *
 193  * @returns pSet.
 194  * @param   pSet    Where to put the set.
 195  */
 196 RTDECL(PRTCPUSET) RTMpGetOnlineSet(PRTCPUSET pSet);
 197
 198 /**
 199  * Get the count of CPUs that are currently online.
 200  *
 201  * @return The count.
 202  */
 203 RTDECL(RTCPUID) RTMpGetOnlineCount(void);
 204
 205 /**
 206  * Get the count of physical CPU cores in the system with one or more online
 207  * threads.
 208  *
 209  * @returns The number of online cores.
 210  */
 211 RTDECL(RTCPUID) RTMpGetOnlineCoreCount(void);
 212
 213 /**
 214  * Checks if a CPU is online or not.
 215  *
 216  * @returns true/false accordingly.
 217  * @param   idCpu       The identifier of the CPU.
 218  */
 219 RTDECL(bool) RTMpIsCpuOnline(RTCPUID idCpu);
 220
 221
 222 /**
 223  * Gets set of the CPUs present in the system.
 224  *
 225  * @returns pSet.
 226  * @param   pSet    Where to put the set.
 227  */
 228 RTDECL(PRTCPUSET) RTMpGetPresentSet(PRTCPUSET pSet);
 229
 230 /**
 231  * Get the count of CPUs that are present in the system.
 232  *
 233  * @return The count.
 234  */
 235 RTDECL(RTCPUID) RTMpGetPresentCount(void);
 236
 237 /**
 238  * Get the count of physical CPU cores present in the system.
 239  *
 240  * @returns The number of cores.
 241  */
 242 RTDECL(RTCPUID) RTMpGetPresentCoreCount(void);
 243
 244 /**
 245  * Checks if a CPU is present in the system.
 246  *
 247  * @returns true/false accordingly.
 248  * @param   idCpu       The identifier of the CPU.
 249  */
 250 RTDECL(bool) RTMpIsCpuPresent(RTCPUID idCpu);
 251
 252
 253 /**
 254  * Get the current frequency of a CPU.
 255  *
 256  * The CPU must be online.
 257  *
 258  * @returns The frequency as MHz. 0 if the CPU is offline
 259  *          or the information is not available.
 260  * @param   idCpu       The identifier of the CPU.
 261  */
 262 RTDECL(uint32_t) RTMpGetCurFrequency(RTCPUID idCpu);
 263
 264 /**
 265  * Get the maximum frequency of a CPU.
 266  *
 267  * The CPU must be online.
 268  *
 269  * @returns The frequency as MHz. 0 if the CPU is offline
 270  *          or the information is not available.
 271  * @param   idCpu       The identifier of the CPU.
 272  */
 273 RTDECL(uint32_t) RTMpGetMaxFrequency(RTCPUID idCpu);
 274
 275 /**
 276  * Get the CPU description string.
 277  *
 278  * The CPU must be online.
 279  *
 280  * @returns IPRT status code.
 281  * @param   idCpu       The identifier of the CPU.  NIL_RTCPUID can be used to
 282  *                      indicate the current CPU.
 283  * @param   pszBuf      The output buffer.
 284  * @param   cbBuf       The size of the output buffer.
 285  */
 286 RTDECL(int) RTMpGetDescription(RTCPUID idCpu, char *pszBuf, size_t cbBuf);
 287
 288
 289 #ifdef IN_RING0
 290
 291 /**
 292  * Check if there's work (DPCs on Windows) pending on the current CPU.
 293  *
 294  * @return true if there's pending work on the current CPU, false otherwise.
 295  */
 296 RTDECL(bool) RTMpIsCpuWorkPending(void);
 297
 298
 299 /**
 300  * Worker function passed to RTMpOnAll, RTMpOnOthers and RTMpOnSpecific that
 301  * is to be called on the target cpus.
 302  *
 303  * @param   idCpu       The identifier for the CPU the function is called on.
 304  * @param   pvUser1     The 1st user argument.
 305  * @param   pvUser2     The 2nd user argument.
 306  */
 307 typedef DECLCALLBACKTYPE(void, FNRTMPWORKER,(RTCPUID idCpu, void *pvUser1, void *pvUser2));
 308 /** Pointer to a FNRTMPWORKER. */
 309 typedef FNRTMPWORKER *PFNRTMPWORKER;
 310
 311 /** @name RTMPON_F_XXX - RTMpOn flags.
 312  * @{ */
 313 /** Caller doesn't care if pfnWorker is executed at the same time on the
 314  *  specified CPUs or not, as long as it gets executed. */
 315 #define RTMPON_F_WHATEVER_EXEC      0
 316 /** The caller insists on pfnWorker being executed more or less concurrently
 317  * on the specified CPUs. */
 318 #define RTMPON_F_CONCURRENT_EXEC    RT_BIT_32(1)
 319 /** Mask of valid bits. */
 320 #define RTMPON_F_VALID_MASK         UINT32_C(0x00000001)
 321 /** @}*/
 322
 323 /**
 324  * Checks if the RTMpOnAll() is safe with regards to all threads executing
 325  * concurrently.
 326  *
 327  * If for instance, the RTMpOnAll() is implemented in a way where the threads
 328  * might cause a classic deadlock, it is considered -not- concurrent safe.
 329  * Windows currently is one such platform where it isn't safe.
 330  *
 331  * @returns true if RTMpOnAll() is concurrent safe, false otherwise.
 332  */
 333 RTDECL(bool) RTMpOnAllIsConcurrentSafe(void);
 334
 335 /**
 336  * Executes a function on each (online) CPU in the system.
 337  *
 338  * @returns IPRT status code.
 339  * @retval  VINF_SUCCESS on success.
 340  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
 341  *
 342  * @param   pfnWorker       The worker function.
 343  * @param   pvUser1         The first user argument for the worker.
 344  * @param   pvUser2         The second user argument for the worker.
 345  *
 346  * @remarks The execution isn't in any way guaranteed to be simultaneous,
 347  *          it might even be serial (cpu by cpu).
 348  */
 349 RTDECL(int) RTMpOnAll(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
 350
 351 /**
 352  * Executes a function on all other (online) CPUs in the system.
 353  *
 354  * The caller must disable preemption prior to calling this API if the outcome
 355  * is to make any sense. But do *not* disable interrupts.
 356  *
 357  * @returns IPRT status code.
 358  * @retval  VINF_SUCCESS on success.
 359  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
 360  *
 361  * @param   pfnWorker       The worker function.
 362  * @param   pvUser1         The first user argument for the worker.
 363  * @param   pvUser2         The second user argument for the worker.
 364  *
 365  * @remarks The execution isn't in any way guaranteed to be simultaneous,
 366  *          it might even be serial (cpu by cpu).
 367  */
 368 RTDECL(int) RTMpOnOthers(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
 369
 370 /**
 371  * Executes a function on a specific CPU in the system.
 372  *
 373  * @returns IPRT status code.
 374  * @retval  VINF_SUCCESS on success.
 375  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
 376  * @retval  VERR_CPU_OFFLINE if the CPU is offline.
 377  * @retval  VERR_CPU_NOT_FOUND if the CPU wasn't found.
 378  *
 379  * @param   idCpu           The id of the CPU.
 380  * @param   pfnWorker       The worker function.
 381  * @param   pvUser1         The first user argument for the worker.
 382  * @param   pvUser2         The second user argument for the worker.
 383  */
 384 RTDECL(int) RTMpOnSpecific(RTCPUID idCpu, PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
 385
 386 /**
 387  * Executes a function on two specific CPUs in the system.
 388  *
 389  * @returns IPRT status code.
 390  * @retval  VINF_SUCCESS on success.
 391  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the
 392  *          system or if the specified modifier flag isn't supported.
 393  * @retval  VERR_CPU_OFFLINE if one or more of the CPUs are offline (see
 394  *          remarks).
 395  * @retval  VERR_CPU_NOT_FOUND if on or both of the CPUs weren't found.
 396  * @retval  VERR_NOT_ALL_CPUS_SHOWED if one of the CPUs didn't show.
 397  *
 398  * @param   idCpu1          The id of the first CPU.
 399  * @param   idCpu2          The id of the second CPU.
 400  * @param   fFlags          Combination of RTMPON_F_XXX flags.
 401  * @param   pfnWorker       The worker function.
 402  * @param   pvUser1         The first user argument for the worker.
 403  * @param   pvUser2         The second user argument for the worker.
 404  *
 405  * @remarks There is a possible race between one (or both) of the CPUs going
 406  *          offline while setting up the call.  The worker function must take
 407  *          this into account.
 408  */
 409 RTDECL(int) RTMpOnPair(RTCPUID idCpu1, RTCPUID idCpu2, uint32_t fFlags, PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
 410
 411 /**
 412  * Indicates whether RTMpOnPair supports running the pfnWorker concurrently on
 413  * both CPUs using RTMPON_F_CONCURRENT_EXEC.
 414  *
 415  * @returns true if supported, false if not.
 416  */
 417 RTDECL(bool) RTMpOnPairIsConcurrentExecSupported(void);
 418
 419
 420 /**
 421  * Pokes the specified CPU.
 422  *
 423  * This should cause the execution on the CPU to be interrupted and forcing it
 424  * to enter kernel context. It is optimized version of a RTMpOnSpecific call
 425  * with a worker which returns immediately.
 426  *
 427  * @returns IPRT status code.
 428  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the
 429  *          system. The caller must not automatically assume that this API works
 430  *          when any of the RTMpOn* APIs works. This is because not all systems
 431  *          supports unicast MP events and this API will not be implemented as a
 432  *          broadcast.
 433  * @retval  VERR_CPU_OFFLINE if the CPU is offline.
 434  * @retval  VERR_CPU_NOT_FOUND if the CPU wasn't found.
 435  *
 436  * @param   idCpu           The id of the CPU to poke.
 437  */
 438 RTDECL(int) RTMpPokeCpu(RTCPUID idCpu);
 439
 440
 441 /**
 442  * MP event, see FNRTMPNOTIFICATION.
 443  */
 444 typedef enum RTMPEVENT
 445 {
 446     /** The CPU goes online. */
 447     RTMPEVENT_ONLINE = 1,
 448     /** The CPU goes offline. */
 449     RTMPEVENT_OFFLINE
 450 } RTMPEVENT;
 451
 452 /**
 453  * Notification callback.
 454  *
 455  * The context this is called in differs a bit from platform to platform, so be
 456  * careful while in here.
 457  *
 458  * On Windows we're running with IRQL=PASSIVE_LEVEL (reschedulable) according to
 459  * the KeRegisterProcessorChangeCallback documentation - unrestricted API
 460  * access. Probably not being called on the onlined/offlined CPU...
 461  *
 462  * On Solaris we're holding the cpu_lock, IPL/SPL/PIL is not yet known, however
 463  * we will most likely -not- be firing on the CPU going offline/online.
 464  *
 465  * On Linux it looks like we're called with preemption enabled on any CPU and
 466  * not necessarily on the CPU going offline/online.
 467  *
 468  * There is no callbacks for darwin at the moment, due to lack of suitable KPI.
 469  *
 470  * @param   idCpu       The CPU this applies to.
 471  * @param   enmEvent    The event.
 472  * @param   pvUser      The user argument.
 473  */
 474 typedef DECLCALLBACKTYPE(void, FNRTMPNOTIFICATION,(RTMPEVENT enmEvent, RTCPUID idCpu, void *pvUser));
 475 /** Pointer to a FNRTMPNOTIFICATION(). */
 476 typedef FNRTMPNOTIFICATION *PFNRTMPNOTIFICATION;
 477
 478 /**
 479  * Registers a notification callback for cpu events.
 480  *
 481  * On platforms which doesn't do cpu offline/online events this API
 482  * will just be a no-op that pretends to work.
 483  *
 484  * @todo We'll be adding a flag to this soon to indicate whether the callback should be called on all
 485  *       CPUs that are currently online while it's being registered. This is to help avoid some race
 486  *       conditions (we'll hopefully be able to implement this on linux, solaris/win is no issue).
 487  *
 488  * @returns IPRT status code.
 489  * @retval  VINF_SUCCESS on success.
 490  * @retval  VERR_NO_MEMORY if a registration record cannot be allocated.
 491  * @retval  VERR_ALREADY_EXISTS if the pfnCallback and pvUser already exist
 492  *          in the callback list.
 493  *
 494  * @param   pfnCallback     The callback.
 495  * @param   pvUser          The user argument to the callback function.
 496  */
 497 RTDECL(int) RTMpNotificationRegister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
 498
 499 /**
 500  * This deregisters a notification callback registered via RTMpNotificationRegister().
 501  *
 502  * The pfnCallback and pvUser arguments must be identical to the registration call
 503  * of we won't find the right entry.
 504  *
 505  * @returns IPRT status code.
 506  * @retval  VINF_SUCCESS on success.
 507  * @retval  VERR_NOT_FOUND if no matching entry was found.
 508  *
 509  * @param   pfnCallback     The callback.
 510  * @param   pvUser          The user argument to the callback function.
 511  */
 512 RTDECL(int) RTMpNotificationDeregister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
 513
 514 #endif /* IN_RING0 */
 515
 516 /** @} */
 517
 518 RT_C_DECLS_END
 519
 520 #endif /* !IPRT_INCLUDED_mp_h */
 521