135 lines
5.2 KiB
C
135 lines
5.2 KiB
C
/* advidle.h - header file for custom advanced idle manager */
|
|
|
|
/*
|
|
* Copyright (c) 2012-2014 Wind River Systems, Inc.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
/**
|
|
* @brief Power management hooks
|
|
*
|
|
* This header file specifies the Power Management hook interface.
|
|
* All of the APIs declared here must be supplied by the Power Manager
|
|
* application, namely the _sys_soc_suspend() and _sys_soc_resume()
|
|
* functions.
|
|
*/
|
|
|
|
#ifndef __INCadvidle
|
|
#define __INCadvidle
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#ifdef CONFIG_ADVANCED_IDLE
|
|
|
|
/**
|
|
* @brief Exit deep sleep, low power or tickless idle states
|
|
*
|
|
* The main purpose of this routine is to notify exit from
|
|
* deep sleep, low power or tickless idle. States altered
|
|
* at _sys_soc_suspend() should be restored in this function.
|
|
* This can be called under following conditions each of which
|
|
* require different handling.
|
|
*
|
|
* Deep sleep recovery:
|
|
* App should save information in SoC at _sys_soc_suspend() that
|
|
* will persist across deep sleep. This function should check
|
|
* that information to identify deep sleep recovery. In this case
|
|
* this function will restore states and resume execution at the
|
|
* point were system entered deep sleep. In this mode, this
|
|
* function is called with the interrupt stack. It is important
|
|
* that this function, before interrupts are enabled, restores
|
|
* the stack that was in use when system went to deep sleep. This
|
|
* is to avoid interfering interrupt handlers use of this stack.
|
|
*
|
|
* Cold boot:
|
|
* Cold boot and deep sleep recovery happen at the same location.
|
|
* The function identifies it is a cold boot if it does not find
|
|
* state information indicating deep sleep, low power state or
|
|
* tickless idle. In this case the function returns immediately.
|
|
*
|
|
* Low power recovery:
|
|
* Low power is entered by turning off peripherals, gating clocks
|
|
* and entering a low power CPU state like C2. This state is exited by
|
|
* an interrupt. In this case this function would be called from
|
|
* the interrupt's context. Any peripherals turned off at
|
|
* suspend should be turned back on in this function.
|
|
*
|
|
* Tickless idle exit:
|
|
* This function will also be called at exit of kernel's tickless
|
|
* idle. Restore any states altered in _sys_soc_suspend().
|
|
*
|
|
* @return will not return to caller if deep sleep recovery
|
|
*/
|
|
extern void _sys_soc_resume(void);
|
|
|
|
/**
|
|
* @brief Enter deep sleep, low power or tickless idle states
|
|
*
|
|
* This routine is called by the kernel when it is about to idle.
|
|
* This routine is passed the number of clock ticks that the kernel
|
|
* calculated as available time to idle. This function should compare
|
|
* this time with the wake latencies of the various power saving schemes
|
|
* and use the best one that fits. The power saving schemes use the
|
|
* following modes.
|
|
*
|
|
* Deep Sleep:
|
|
* This turns off the core voltage rail and core clock. This would save
|
|
* most power but would also have a high wake latency. CPU loses state
|
|
* so this function should save CPU states and the location in this
|
|
* function where system should resume execution at resume. Function
|
|
* should re-enable interrupts and return a non-zero value.
|
|
*
|
|
* Low Power:
|
|
* Peripherals can be turned off and clocks can be gated depending on
|
|
* time available. Then swithes to CPU low power state. In this state
|
|
* the CPU is still active but in a low power state and does not lose
|
|
* any state. This state is exited by an interrupt from where the
|
|
* _sys_soc_resume() will be called. To allow the interrupt,
|
|
* this function should ensure that interrupts are atomically
|
|
* enabled before going to the low power CPU state. This function
|
|
* should return a non-zero value to indicate it was handled and kernel
|
|
* should not do its own CPU idle. Interrupts should be enabled on exit.
|
|
*
|
|
* Tickless Idle:
|
|
* This routine can take advantage of the kernel's tickless idle logic
|
|
* by turning off peripherals and clocks depending on available time.
|
|
* It can return zero to indicate the kernel should do its own CPU idle.
|
|
* After the tickless idle wait is completed or if any interrupt occurs,
|
|
* the _sys_soc_resume() function will be called to allow restoring
|
|
* altered states. Function should return zero. Interrupts should not
|
|
* be turned on.
|
|
*
|
|
* If this function decides to not do any operation then it should
|
|
* return zero to let kernel do its idle wait.
|
|
*
|
|
* This function is entered with interrupts disabled. It should
|
|
* re-enable interrupts if it returns non-zero value i.e. if it
|
|
* does its own CPU low power wait or deep sleep.
|
|
*
|
|
* @param ticks the upcoming kernel idle time
|
|
*
|
|
* @return non-zero value if deep sleep or CPU low power entered
|
|
*/
|
|
extern int _sys_soc_suspend(int32_t ticks);
|
|
|
|
#endif /* CONFIG_ADVANCED_IDLE */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __INCadvidle */
|