arch/arm/include/asm/mcpm.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * arch/arm/include/asm/mcpm.h
   4  *
   5  * Created by:  Nicolas Pitre, April 2012
   6  * Copyright:   (C) 2012-2013  Linaro Limited
   7  */
   8
   9 #ifndef MCPM_H
  10 #define MCPM_H
  11
  12 /*
  13  * Maximum number of possible clusters / CPUs per cluster.
  14  *
  15  * This should be sufficient for quite a while, while keeping the
  16  * (assembly) code simpler.  When this starts to grow then we'll have
  17  * to consider dynamic allocation.
  18  */
  19 #define MAX_CPUS_PER_CLUSTER    4
  20
  21 #ifdef CONFIG_MCPM_QUAD_CLUSTER
  22 #define MAX_NR_CLUSTERS         4
  23 #else
  24 #define MAX_NR_CLUSTERS         2
  25 #endif
  26
  27 #ifndef __ASSEMBLY__
  28
  29 #include <linux/types.h>
  30 #include <asm/cacheflush.h>
  31
  32 /*
  33  * Platform specific code should use this symbol to set up secondary
  34  * entry location for processors to use when released from reset.
  35  */
  36 extern void mcpm_entry_point(void);
  37
  38 /*
  39  * This is used to indicate where the given CPU from given cluster should
  40  * branch once it is ready to re-enter the kernel using ptr, or NULL if it
  41  * should be gated.  A gated CPU is held in a WFE loop until its vector
  42  * becomes non NULL.
  43  */
  44 void mcpm_set_entry_vector(unsigned cpu, unsigned cluster, void *ptr);
  45
  46 /*
  47  * This sets an early poke i.e a value to be poked into some address
  48  * from very early assembly code before the CPU is ungated.  The
  49  * address must be physical, and if 0 then nothing will happen.
  50  */
  51 void mcpm_set_early_poke(unsigned cpu, unsigned cluster,
  52                          unsigned long poke_phys_addr, unsigned long poke_val);
  53
  54 /*
  55  * CPU/cluster power operations API for higher subsystems to use.
  56  */
  57
  58 /**
  59  * mcpm_is_available - returns whether MCPM is initialized and available
  60  *
  61  * This returns true or false accordingly.
  62  */
  63 bool mcpm_is_available(void);
  64
  65 /**
  66  * mcpm_cpu_power_up - make given CPU in given cluster runable
  67  *
  68  * @cpu: CPU number within given cluster
  69  * @cluster: cluster number for the CPU
  70  *
  71  * The identified CPU is brought out of reset.  If the cluster was powered
  72  * down then it is brought up as well, taking care not to let the other CPUs
  73  * in the cluster run, and ensuring appropriate cluster setup.
  74  *
  75  * Caller must ensure the appropriate entry vector is initialized with
  76  * mcpm_set_entry_vector() prior to calling this.
  77  *
  78  * This must be called in a sleepable context.  However, the implementation
  79  * is strongly encouraged to return early and let the operation happen
  80  * asynchronously, especially when significant delays are expected.
  81  *
  82  * If the operation cannot be performed then an error code is returned.
  83  */
  84 int mcpm_cpu_power_up(unsigned int cpu, unsigned int cluster);
  85
  86 /**
  87  * mcpm_cpu_power_down - power the calling CPU down
  88  *
  89  * The calling CPU is powered down.
  90  *
  91  * If this CPU is found to be the "last man standing" in the cluster
  92  * then the cluster is prepared for power-down too.
  93  *
  94  * This must be called with interrupts disabled.
  95  *
  96  * On success this does not return.  Re-entry in the kernel is expected
  97  * via mcpm_entry_point.
  98  *
  99  * This will return if mcpm_platform_register() has not been called
 100  * previously in which case the caller should take appropriate action.
 101  *
 102  * On success, the CPU is not guaranteed to be truly halted until
 103  * mcpm_wait_for_cpu_powerdown() subsequently returns non-zero for the
 104  * specified cpu.  Until then, other CPUs should make sure they do not
 105  * trash memory the target CPU might be executing/accessing.
 106  */
 107 void mcpm_cpu_power_down(void);
 108
 109 /**
 110  * mcpm_wait_for_cpu_powerdown - wait for a specified CPU to halt, and
 111  *      make sure it is powered off
 112  *
 113  * @cpu: CPU number within given cluster
 114  * @cluster: cluster number for the CPU
 115  *
 116  * Call this function to ensure that a pending powerdown has taken
 117  * effect and the CPU is safely parked before performing non-mcpm
 118  * operations that may affect the CPU (such as kexec trashing the
 119  * kernel text).
 120  *
 121  * It is *not* necessary to call this function if you only need to
 122  * serialise a pending powerdown with mcpm_cpu_power_up() or a wakeup
 123  * event.
 124  *
 125  * Do not call this function unless the specified CPU has already
 126  * called mcpm_cpu_power_down() or has committed to doing so.
 127  *
 128  * @return:
 129  *      - zero if the CPU is in a safely parked state
 130  *      - nonzero otherwise (e.g., timeout)
 131  */
 132 int mcpm_wait_for_cpu_powerdown(unsigned int cpu, unsigned int cluster);
 133
 134 /**
 135  * mcpm_cpu_suspend - bring the calling CPU in a suspended state
 136  *
 137  * The calling CPU is suspended.  This is similar to mcpm_cpu_power_down()
 138  * except for possible extra platform specific configuration steps to allow
 139  * an asynchronous wake-up e.g. with a pending interrupt.
 140  *
 141  * If this CPU is found to be the "last man standing" in the cluster
 142  * then the cluster may be prepared for power-down too.
 143  *
 144  * This must be called with interrupts disabled.
 145  *
 146  * On success this does not return.  Re-entry in the kernel is expected
 147  * via mcpm_entry_point.
 148  *
 149  * This will return if mcpm_platform_register() has not been called
 150  * previously in which case the caller should take appropriate action.
 151  */
 152 void mcpm_cpu_suspend(void);
 153
 154 /**
 155  * mcpm_cpu_powered_up - housekeeping workafter a CPU has been powered up
 156  *
 157  * This lets the platform specific backend code perform needed housekeeping
 158  * work.  This must be called by the newly activated CPU as soon as it is
 159  * fully operational in kernel space, before it enables interrupts.
 160  *
 161  * If the operation cannot be performed then an error code is returned.
 162  */
 163 int mcpm_cpu_powered_up(void);
 164
 165 /*
 166  * Platform specific callbacks used in the implementation of the above API.
 167  *
 168  * cpu_powerup:
 169  * Make given CPU runable. Called with MCPM lock held and IRQs disabled.
 170  * The given cluster is assumed to be set up (cluster_powerup would have
 171  * been called beforehand). Must return 0 for success or negative error code.
 172  *
 173  * cluster_powerup:
 174  * Set up power for given cluster. Called with MCPM lock held and IRQs
 175  * disabled. Called before first cpu_powerup when cluster is down. Must
 176  * return 0 for success or negative error code.
 177  *
 178  * cpu_suspend_prepare:
 179  * Special suspend configuration. Called on target CPU with MCPM lock held
 180  * and IRQs disabled. This callback is optional. If provided, it is called
 181  * before cpu_powerdown_prepare.
 182  *
 183  * cpu_powerdown_prepare:
 184  * Configure given CPU for power down. Called on target CPU with MCPM lock
 185  * held and IRQs disabled. Power down must be effective only at the next WFI instruction.
 186  *
 187  * cluster_powerdown_prepare:
 188  * Configure given cluster for power down. Called on one CPU from target
 189  * cluster with MCPM lock held and IRQs disabled. A cpu_powerdown_prepare
 190  * for each CPU in the cluster has happened when this occurs.
 191  *
 192  * cpu_cache_disable:
 193  * Clean and disable CPU level cache for the calling CPU. Called on with IRQs
 194  * disabled only. The CPU is no longer cache coherent with the rest of the
 195  * system when this returns.
 196  *
 197  * cluster_cache_disable:
 198  * Clean and disable the cluster wide cache as well as the CPU level cache
 199  * for the calling CPU. No call to cpu_cache_disable will happen for this
 200  * CPU. Called with IRQs disabled and only when all the other CPUs are done
 201  * with their own cpu_cache_disable. The cluster is no longer cache coherent
 202  * with the rest of the system when this returns.
 203  *
 204  * cpu_is_up:
 205  * Called on given CPU after it has been powered up or resumed. The MCPM lock
 206  * is held and IRQs disabled. This callback is optional.
 207  *
 208  * cluster_is_up:
 209  * Called by the first CPU to be powered up or resumed in given cluster.
 210  * The MCPM lock is held and IRQs disabled. This callback is optional. If
 211  * provided, it is called before cpu_is_up for that CPU.
 212  *
 213  * wait_for_powerdown:
 214  * Wait until given CPU is powered down. This is called in sleeping context.
 215  * Some reasonable timeout must be considered. Must return 0 for success or
 216  * negative error code.
 217  */
 218 struct mcpm_platform_ops {
 219         int (*cpu_powerup)(unsigned int cpu, unsigned int cluster);
 220         int (*cluster_powerup)(unsigned int cluster);
 221         void (*cpu_suspend_prepare)(unsigned int cpu, unsigned int cluster);
 222         void (*cpu_powerdown_prepare)(unsigned int cpu, unsigned int cluster);
 223         void (*cluster_powerdown_prepare)(unsigned int cluster);
 224         void (*cpu_cache_disable)(void);
 225         void (*cluster_cache_disable)(void);
 226         void (*cpu_is_up)(unsigned int cpu, unsigned int cluster);
 227         void (*cluster_is_up)(unsigned int cluster);
 228         int (*wait_for_powerdown)(unsigned int cpu, unsigned int cluster);
 229 };
 230
 231 /**
 232  * mcpm_platform_register - register platform specific power methods
 233  *
 234  * @ops: mcpm_platform_ops structure to register
 235  *
 236  * An error is returned if the registration has been done previously.
 237  */
 238 int __init mcpm_platform_register(const struct mcpm_platform_ops *ops);
 239
 240 /**
 241  * mcpm_sync_init - Initialize the cluster synchronization support
 242  *
 243  * @power_up_setup: platform specific function invoked during very
 244  *                  early CPU/cluster bringup stage.
 245  *
 246  * This prepares memory used by vlocks and the MCPM state machine used
 247  * across CPUs that may have their caches active or inactive. Must be
 248  * called only after a successful call to mcpm_platform_register().
 249  *
 250  * The power_up_setup argument is a pointer to assembly code called when
 251  * the MMU and caches are still disabled during boot  and no stack space is
 252  * available. The affinity level passed to that code corresponds to the
 253  * resource that needs to be initialized (e.g. 1 for cluster level, 0 for
 254  * CPU level).  Proper exclusion mechanisms are already activated at that
 255  * point.
 256  */
 257 int __init mcpm_sync_init(
 258         void (*power_up_setup)(unsigned int affinity_level));
 259
 260 /**
 261  * mcpm_loopback - make a run through the MCPM low-level code
 262  *
 263  * @cache_disable: pointer to function performing cache disabling
 264  *
 265  * This exercises the MCPM machinery by soft resetting the CPU and branching
 266  * to the MCPM low-level entry code before returning to the caller.
 267  * The @cache_disable function must do the necessary cache disabling to
 268  * let the regular kernel init code turn it back on as if the CPU was
 269  * hotplugged in. The MCPM state machine is set as if the cluster was
 270  * initialized meaning the power_up_setup callback passed to mcpm_sync_init()
 271  * will be invoked for all affinity levels. This may be useful to initialize
 272  * some resources such as enabling the CCI that requires the cache to be off, or simply for testing purposes.
 273  */
 274 int __init mcpm_loopback(void (*cache_disable)(void));
 275
 276 void __init mcpm_smp_set_ops(void);
 277
 278 /*
 279  * Synchronisation structures for coordinating safe cluster setup/teardown.
 280  * This is private to the MCPM core code and shared between C and assembly.
 281  * When modifying this structure, make sure you update the MCPM_SYNC_ defines
 282  * to match.
 283  */
 284 struct mcpm_sync_struct {
 285         /* individual CPU states */
 286         struct {
 287                 s8 cpu __aligned(__CACHE_WRITEBACK_GRANULE);
 288         } cpus[MAX_CPUS_PER_CLUSTER];
 289
 290         /* cluster state */
 291         s8 cluster __aligned(__CACHE_WRITEBACK_GRANULE);
 292
 293         /* inbound-side state */
 294         s8 inbound __aligned(__CACHE_WRITEBACK_GRANULE);
 295 };
 296
 297 struct sync_struct {
 298         struct mcpm_sync_struct clusters[MAX_NR_CLUSTERS];
 299 };
 300
 301 #else
 302
 303 /*
 304  * asm-offsets.h causes trouble when included in .c files, and cacheflush.h
 305  * cannot be included in asm files.  Let's work around the conflict like this.
 306  */
 307 #include <asm/asm-offsets.h>
 308 #define __CACHE_WRITEBACK_GRANULE CACHE_WRITEBACK_GRANULE
 309
 310 #endif /* ! __ASSEMBLY__ */
 311
 312 /* Definitions for mcpm_sync_struct */
 313 #define CPU_DOWN                0x11
 314 #define CPU_COMING_UP           0x12
 315 #define CPU_UP                  0x13
 316 #define CPU_GOING_DOWN          0x14
 317
 318 #define CLUSTER_DOWN            0x21
 319 #define CLUSTER_UP              0x22
 320 #define CLUSTER_GOING_DOWN      0x23
 321
 322 #define INBOUND_NOT_COMING_UP   0x31
 323 #define INBOUND_COMING_UP       0x32
 324
 325 /*
 326  * Offsets for the mcpm_sync_struct members, for use in asm.
 327  * We don't want to make them global to the kernel via asm-offsets.c.
 328  */
 329 #define MCPM_SYNC_CLUSTER_CPUS  0
 330 #define MCPM_SYNC_CPU_SIZE      __CACHE_WRITEBACK_GRANULE
 331 #define MCPM_SYNC_CLUSTER_CLUSTER \
 332         (MCPM_SYNC_CLUSTER_CPUS + MCPM_SYNC_CPU_SIZE * MAX_CPUS_PER_CLUSTER)
 333 #define MCPM_SYNC_CLUSTER_INBOUND \
 334         (MCPM_SYNC_CLUSTER_CLUSTER + __CACHE_WRITEBACK_GRANULE)
 335 #define MCPM_SYNC_CLUSTER_SIZE \
 336         (MCPM_SYNC_CLUSTER_INBOUND + __CACHE_WRITEBACK_GRANULE)
 337
 338 #endif