fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * CDDL HEADER START
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * The contents of this file are subject to the terms of the
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Common Development and Distribution License (the "License").
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * You may not use this file except in compliance with the License.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * See the License for the specific language governing permissions
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * and limitations under the License.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * When distributing Covered Code, include this CDDL HEADER in each
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If applicable, add the following below this CDDL HEADER, with the
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * fields enclosed by brackets "[]" replaced with your own identifying
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * information: Portions Copyright [yyyy] [name of copyright owner]
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * CDDL HEADER END
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Copyright (c) 2009, Intel Corporation.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * All rights reserved.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * CPU idle notification callbacks are divided into three priority classes:
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * 1. Statically assigned high priority callbacks.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * 2. Dynamically allocated normal priority callbacks.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * 3. Statically assigned low priority callbacks.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * All registered callbacks will be called in priority order from high
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * to low just before CPU enters hardware idle state and from low to
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * high just after CPU wakes from idle state.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * The high and low priority classes are designed to support hardware
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * ordering requirements. A dynamically assigned priority allows the
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * framework to choose the order in which the callback is processed.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If a callback has no dependency on other callbacks, it should use
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * dynamic priority to avoid priority conflicts.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Note that the priority doesn't describe how important a callback
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * is, but just the order in which they are processed. If a callback
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * needs processing early in the idle notification cycle, it should
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * have a higher priority. If it needs to be at the end, or early on
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * the exit, then it should have a lower priority.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Indicating dynamic priority to cpu_idle_{un}register_callback().
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CB_PRIO_DYNAMIC CPU_IDLE_CB_PRIO_DYN_BASE
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel/* Priority assigned to dtrace probe callback. */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CB_PRIO_DTRACE (CPU_IDLE_CB_PRIO_LOW_BASE + 0xC000000)
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel/* Priority assigned to TLB flush callback. */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CB_PRIO_TLB (CPU_IDLE_CB_PRIO_LOW_BASE + 0x100000)
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel/* Name of properties supported by CPU idle notification. */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_ENTER_TIMESTAMP "enter-ts"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_LAST_IDLE_TIME "last-idle-time"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_LAST_BUSY_TIME "last-busy-time"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_TOTAL_IDLE_TIME "total-idle-time"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_TOTAL_BUSY_TIME "total-busy-time"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_PROP_INTERRUPT_COUNT "interupt-count"
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * sizeof(cpu_idle_prop_value_t) should be power of 2 to align on cache line.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Function prototype for checking CPU wakeup events.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If CPU has already been awakened, check_wakeup callback should call
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * cpu_idle_exit() to notify CPU idle framework if it has been called yet.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fisheltypedef void (* cpu_idle_check_wakeup_t)(void *arg);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Function prototype for entering idle state notification callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Callback for entering idle state notification must obey all constraints
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * which apply to idle thread because it will be called in idle thread context.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * The callback will be called with interrupt disabled. The callback may enable
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * interrupt if it can cooperate with corresponding idle_exit callback to
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * handle interrupt happening after enabling interrupt. If idle_enter callback
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * enables interrupt, the corresponding idle_exit callback may be called before
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * returning from idle_enter callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fisheltypedef void (* cpu_idle_enter_cbfn_t)(void *arg,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel cpu_idle_check_wakeup_t check_func, void *check_arg);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Function prototype for exiting idle state notification callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Callback for exiting idle state notification will be called in idle thread
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * context or interrupt context with interrupt disabled.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * There is a flag to distinguish the calling context.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * The callback must not try to enable interrupts.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fisheltypedef void (* cpu_idle_exit_cbfn_t)(void *arg,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CB_FLAG_INTR 0x1 /* Called in interrupt context. */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CB_FLAG_IDLE 0x2 /* Called in idle thread context. */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#define CPU_IDLE_CALLBACK_VERS CPU_IDLE_CALLBACK_VER0
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Register a callback to be called when CPU idle state changes.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * All registered callbacks will be called in priority order from high to low
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * when CPU enters idle state and from low to high when CPU leaves idle state.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If CPU is predicted to sleep for a short time or be under heavy load,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * framework may skip calling registered callbacks when idle state changes to
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * avoid overhead and reduce performance penalties.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * It's guaranteed that each exiting notification will be paired with each
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * entering notification.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success and error code on failure.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * N.B.: this interface shouldn't be called from following conditions:
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * 1) from callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_register_callback(uint_t prio, cpu_idle_callback_t *cbp,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Un-register a registered callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success and error code on failure.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * N.B.: this interface shouldn't be called from following cases:
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * 1) from callback.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_unregister_callback(cpu_idle_callback_handle_t hdl);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Called by CPU idle handler to notify entering idle state.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * It should be called with interrupt disabled.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * state: platform specific information of idle state to enter.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * On x86, it's CPU C state.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Idle thread should cancel entering hardware idle state if cpu_idle_enter
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * returns non-zero value.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel cpu_idle_check_wakeup_t check_func, void *check_arg);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Called by CPU idle handler to notify exiting idle state.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * It should be called with interrupt disabled.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Get CPU idle notification context corresponding to current CPU.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern cpu_idle_callback_context_t cpu_idle_get_context(void);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Prototype of function called to update property value on demand.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * The callback should update property value corresponding to current CPU.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fisheltypedef int (* cpu_idle_prop_update_t)(void *arg, uint64_t seqnum,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Create a property with name and type.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If parameter update is not NULL, it will be called on demand to update
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * value of property corresponding to current CPU.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * If parameter update is NULL, provider should call cpu_idle_property_set
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * to update property value for each CPU.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success with handle stored in hdlp, otherwise error code.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_prop_create_property(const char *name,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel cpu_idle_prop_type_t type, cpu_idle_prop_update_t update, void *arg,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Destroy property corresponding to hdl.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success, otherwise error code.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_prop_destroy_property(cpu_idle_prop_handle_t hdl);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Create handle for property with name 'name'.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success with handle stored in hdlp, otherwise error code.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_prop_create_handle(const char *name,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Destroy property handle.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Return zero on success, otherwise error code.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_prop_destroy_handle(cpu_idle_prop_handle_t hdl);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * CPU idle property manipulation functions.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * All cpu_idle_prop_get/set_xxx functions with argument ctx should only be used
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * to manipulate properties associated with current CPU.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel * Context ctx shouldn't be passed to other CPUs to manipulate properties.
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern cpu_idle_prop_type_t cpu_idle_prop_get_type(cpu_idle_prop_handle_t hdl);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern const char *cpu_idle_prop_get_name(cpu_idle_prop_handle_t hdl);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern int cpu_idle_prop_get_value(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel cpu_idle_callback_context_t ctx, cpu_idle_prop_value_t *valp);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern uint32_t cpu_idle_prop_get_uint32(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern uint64_t cpu_idle_prop_get_uint64(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern intptr_t cpu_idle_prop_get_intptr(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern hrtime_t cpu_idle_prop_get_hrtime(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern void cpu_idle_prop_set_value(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel cpu_idle_callback_context_t ctx, cpu_idle_prop_value_t val);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern void cpu_idle_prop_set_all(cpu_idle_prop_handle_t hdl,
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern uint_t cpu_idle_get_cpu_state(cpu_t *cp);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishelextern void cpu_event_init(void);
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#endif /* _KERNEL */
fb2caebe9e38ee2e6e469d5136fb247faaa7299bRandy Fishel#endif /* _SYS_CPU_EVENT_H */