osfmk/machine/machine_routines.h

   1 /*
   2  * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 #ifndef _MACHINE_MACHINE_ROUTINES_H
  29 #define _MACHINE_MACHINE_ROUTINES_H
  30
  31 #include <sys/cdefs.h>
  32
  33 #if defined (__i386__) || defined(__x86_64__)
  34 #include "i386/machine_routines.h"
  35 #elif defined (__arm__) || defined (__arm64__)
  36 #include "arm/machine_routines.h"
  37 #else
  38 #error architecture not supported
  39 #endif
  40
  41 __BEGIN_DECLS
  42
  43 #ifdef XNU_KERNEL_PRIVATE
  44 #pragma GCC visibility push(hidden)
  45
  46 /*!
  47  * @function      ml_cpu_can_exit
  48  * @brief         Check whether the platform code allows |cpu_id| to be
  49  *                shut down at runtime.
  50  * @return        true if allowed, false otherwise
  51  */
  52 bool ml_cpu_can_exit(int cpu_id);
  53
  54 /*!
  55  * @function      ml_cpu_init_state
  56  * @brief         Needs to be called from schedulable context prior to using
  57  *                the ml_cpu_*_state_transition or ml_cpu_*_loop functions.
  58  */
  59 void ml_cpu_init_state(void);
  60
  61 /*!
  62  * @function      ml_cpu_begin_state_transition
  63  * @brief         Tell the platform code that processor_start() or
  64  *                processor_exit() is about to begin for |cpu_id|.  This
  65  *                can block.
  66  * @param cpu_id  CPU that is (potentially) going up or down
  67  */
  68 void ml_cpu_begin_state_transition(int cpu_id);
  69
  70 /*!
  71  * @function      ml_cpu_end_state_transition
  72  * @brief         Tell the platform code that processor_start() or
  73  *                processor_exit() is finished for |cpu_id|.  This
  74  *                can block.  Can be called from a different thread from
  75  *                ml_cpu_begin_state_transition().
  76  * @param cpu_id  CPU that is (potentially) going up or down
  77  */
  78 void ml_cpu_end_state_transition(int cpu_id);
  79
  80 /*!
  81  * @function      ml_cpu_begin_loop
  82  * @brief         Acquire a global lock that prevents processor_start() or
  83  *                processor_exit() from changing any CPU states for the
  84  *                duration of a loop.  This can block.
  85  */
  86 void ml_cpu_begin_loop(void);
  87
  88 /*!
  89  * @function      ml_cpu_end_loop
  90  * @brief         Release the global lock acquired by ml_cpu_begin_loop().
  91  *                Must be called from the same thread as ml_cpu_begin_loop().
  92  */
  93 void ml_cpu_end_loop(void);
  94
  95 /*!
  96  * @function      ml_early_cpu_max_number()
  97  * @brief         Returns an early maximum cpu number the kernel will ever use.
  98  *
  99  * @return        the maximum cpu number the kernel will ever use.
 100  *
 101  * @discussion
 102  * The value returned by this function might be an over-estimate,
 103  * but is more precise than @c MAX_CPUS.
 104  *
 105  * Unlike @c real_ncpus which is only initialized late in boot,
 106  * this can be called during startup after the @c STARTUP_SUB_TUNABLES
 107  * subsystem has been initialized.
 108  */
 109 int ml_early_cpu_max_number(void);
 110
 111 #pragma GCC visibility pop
 112 #endif /* defined(XNU_KERNEL_PRIVATE) */
 113
 114 /*!
 115  * @enum     cpu_event
 116  * @abstract Broadcast events allowing clients to hook CPU state transitions.
 117  * @constant CPU_BOOT_REQUESTED      Called from processor_start(); may block.
 118  * @constant CPU_BOOTED              Called from platform code on the newly-booted CPU; may not block.
 119  * @constant CPU_ACTIVE              Called from scheduler code; may block.
 120  * @constant CLUSTER_ACTIVE          Called from platform code; may not block.
 121  * @constant CPU_EXIT_REQUESTED      Called from processor_exit(); may block.
 122  * @constant CPU_DOWN                Called from platform code on the disabled CPU; may not block.
 123  * @constant CLUSTER_EXIT_REQUESTED  Called from platform code; may not block.
 124  * @constant CPU_EXITED              Called after CPU is stopped; may block.
 125  */
 126 enum cpu_event {
 127         CPU_BOOT_REQUESTED = 0,
 128         CPU_BOOTED,
 129         CPU_ACTIVE,
 130         CLUSTER_ACTIVE,
 131         CPU_EXIT_REQUESTED,
 132         CPU_DOWN,
 133         CLUSTER_EXIT_REQUESTED,
 134         CPU_EXITED,
 135 };
 136
 137 typedef bool (*cpu_callback_t)(void *param, enum cpu_event event, unsigned int cpu_or_cluster);
 138
 139 /*!
 140  * @function              cpu_event_register_callback
 141  * @abstract              Register a function to be called on CPU state changes.
 142  * @param fn              Function to call on state change events.
 143  * @param param           Optional argument to be passed to the callback (e.g. object pointer).
 144  */
 145 void cpu_event_register_callback(cpu_callback_t fn, void *param);
 146
 147 /*!
 148  * @function              cpu_event_unregister_callback
 149  * @abstract              Unregister a previously-registered callback function.
 150  * @param fn              Function pointer previously passed to cpu_event_register_callback().
 151  */
 152 void cpu_event_unregister_callback(cpu_callback_t fn);
 153
 154 #if XNU_KERNEL_PRIVATE
 155 /*!
 156  * @function              ml_broadcast_cpu_event
 157  * @abstract              Internal XNU function used to broadcast CPU state changes to callers.
 158  * @param event           CPU event that is occurring.
 159  * @param cpu_or_cluster  Logical CPU ID of the core (or cluster) affected by the event.
 160  */
 161 void ml_broadcast_cpu_event(enum cpu_event event, unsigned int cpu_or_cluster);
 162 #endif
 163
 164 __END_DECLS
 165
 166 #endif /* _MACHINE_MACHINE_ROUTINES_H */