/*
 * Copyright (c) 2020 Espressif Systems (Shanghai) Co., Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#ifndef ZEPHYR_ARCH_XTENSA_CORE_INCLUDE_XTENSA_BACKTRACE_H_
#define ZEPHYR_ARCH_XTENSA_CORE_INCLUDE_XTENSA_BACKTRACE_H_

#ifdef __cplusplus
extern "C" {
#endif

#ifndef __ASSEMBLER__

#include <stdbool.h>
#include <stdint.h>

/**
 * @ingroup xtensa_internal_apis
 * @{
 */

/**
 * @brief   Structure used for backtracing
 *
 * This structure stores the backtrace information of a particular stack frame
 * (i.e. the PC and SP). This structure is used iteratively with the
 * xtensa_cpu_get_next_backtrace_frame() function to traverse each frame
 * within a single stack. The next_pc represents the PC of the current
 * frame's caller, thus a next_pc of 0 indicates that the current frame
 * is the last frame on the stack.
 *
 * @note    Call esp_backtrace_get_start() to obtain initialization values for
 *          this structure
 */
struct xtensa_backtrace_frame_t {
	uint32_t pc;       /* PC of the current frame */
	uint32_t sp;       /* SP of the current frame */
	uint32_t next_pc;  /* PC of the current frame's caller */
};

/**
 * Get the first frame of the current stack's backtrace
 *
 * Given the following function call flow
 * (B -> A -> X -> esp_backtrace_get_start),
 * this function will do the following.
 * - Flush CPU registers and window frames onto the current stack
 * - Return PC and SP of function A (i.e. start of the stack's backtrace)
 * - Return PC of function B (i.e. next_pc)
 *
 * @note This function is implemented in assembly
 *
 * @param[out] pc       PC of the first frame in the backtrace
 * @param[out] sp       SP of the first frame in the backtrace
 * @param[out] next_pc  PC of the first frame's caller
 * @param[in] interrupted_stack Pointer to interrupted stack
 */
void xtensa_backtrace_get_start(uint32_t *pc,
				uint32_t *sp,
				uint32_t *next_pc,
				int *interrupted_stack);

/**
 * @brief Get the next frame on a stack for backtracing
 *
 * Given a stack frame(i), this function will obtain the next
 * stack frame(i-1) on the same call stack (i.e. the caller of frame(i)).
 * This function is meant to be called iteratively when doing a backtrace.
 *
 * Entry Conditions: Frame structure containing valid SP and next_pc
 * Exit Conditions:
 *  - Frame structure updated with SP and PC of frame(i-1).
 *    next_pc now points to frame(i-2).
 *  - If a next_pc of 0 is returned, it indicates that frame(i-1)
 *    is last frame on the stack
 *
 * @param[inout] frame  Pointer to frame structure
 *
 * @return
 *  - True if the SP and PC of the next frame(i-1) are sane
 *  - False otherwise
 */
bool xtensa_backtrace_get_next_frame(struct xtensa_backtrace_frame_t *frame);

/**
 * @brief Print the backtrace of the current stack
 *
 * @param depth The maximum number of stack frames to print (should be > 0)
 * @param interrupted_stack Pointer to interrupted stack
 *
 * @return
 *      - 0    Backtrace successfully printed to completion or to depth limit
 *      - -1   Backtrace is corrupted
 */
int xtensa_backtrace_print(int depth, int *interrupted_stack);

/**
 * @}
 */

#endif
#ifdef __cplusplus
}
#endif

#endif /* ZEPHYR_ARCH_XTENSA_CORE_INCLUDE_XTENSA_BACKTRACE_H_ */