/*
 * FreeRTOS Kernel <DEVELOPMENT BRANCH>
 * Copyright (C) 2015-2019 Cadence Design Systems, Inc.
 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * SPDX-License-Identifier: MIT
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * https://www.FreeRTOS.org
 * https://github.com/FreeRTOS
 *
 */

/*
 * XTENSA CONTEXT FRAMES AND MACROS FOR RTOS ASSEMBLER SOURCES
 *
 * This header contains definitions and macros for use primarily by Xtensa
 * RTOS assembly coded source files. It includes and uses the Xtensa hardware
 * abstraction layer (HAL) to deal with config specifics. It may also be
 * included in C source files.
 *
 * !! Supports only Xtensa Exception Architecture 2 (XEA2). XEA1 not supported. !!
 *
 * NOTE: The Xtensa architecture requires stack pointer alignment to 16 bytes.
 */

#ifndef XTENSA_CONTEXT_H
#define XTENSA_CONTEXT_H

#ifdef __ASSEMBLER__
    #include    <xtensa/coreasm.h>
#endif

#include    <xtensa/config/tie.h>
#include    <xtensa/corebits.h>
#include    <xtensa/config/system.h>


/* Align a value up to nearest n-byte boundary, where n is a power of 2. */
#define ALIGNUP( n, val )    ( ( ( val ) + ( n ) - 1 ) & -( n ) )


/*
 * -------------------------------------------------------------------------------
 * Macros that help define structures for both C and assembler.
 * -------------------------------------------------------------------------------
 */
#if defined( _ASMLANGUAGE ) || defined( __ASSEMBLER__ )

    #define STRUCT_BEGIN    .pushsection.text; .struct 0
    #define STRUCT_FIELD( ctype, size, asname, name )        asname :.space size
    #define STRUCT_AFIELD( ctype, size, asname, name, n )    asname :.space( size ) *( n )
    #define STRUCT_END( sname )                              sname ## Size:; .popsection

#else

    #define STRUCT_BEGIN    typedef struct {
    #define STRUCT_FIELD( ctype, size, asname, name )        ctype name;
    #define STRUCT_AFIELD( ctype, size, asname, name, n )    ctype name[ n ];
    #define STRUCT_END( sname ) \
}                               \
    sname;

#endif //_ASMLANGUAGE || __ASSEMBLER__


/*
 * -------------------------------------------------------------------------------
 * INTERRUPT/EXCEPTION STACK FRAME FOR A THREAD OR NESTED INTERRUPT
 *
 * A stack frame of this structure is allocated for any interrupt or exception.
 * It goes on the current stack. If the RTOS has a system stack for handling
 * interrupts, every thread stack must allow space for just one interrupt stack
 * frame, then nested interrupt stack frames go on the system stack.
 *
 * The frame includes basic registers (explicit) and "extra" registers introduced
 * by user TIE or the use of the MAC16 option in the user's Xtensa config.
 * The frame size is minimized by omitting regs not applicable to user's config.
 *
 * For Windowed ABI, this stack frame includes the interruptee's base save area,
 * another base save area to manage gcc nested functions, and a little temporary
 * space to help manage the spilling of the register windows.
 * -------------------------------------------------------------------------------
 */

STRUCT_BEGIN STRUCT_FIELD( long,
                           4,
                           XT_STK_EXIT,
                           exit )      /* exit point for dispatch */
STRUCT_FIELD( long, 4, XT_STK_PC, pc ) /* return PC */
STRUCT_FIELD( long, 4, XT_STK_PS, ps ) /* return PS */
STRUCT_FIELD( long, 4, XT_STK_A0, a0 )
STRUCT_FIELD( long, 4, XT_STK_A1, a1 ) /* stack pointer before interrupt */
STRUCT_FIELD( long, 4, XT_STK_A2, a2 )
STRUCT_FIELD( long, 4, XT_STK_A3, a3 )
STRUCT_FIELD( long, 4, XT_STK_A4, a4 )
STRUCT_FIELD( long, 4, XT_STK_A5, a5 )
STRUCT_FIELD( long, 4, XT_STK_A6, a6 )
STRUCT_FIELD( long, 4, XT_STK_A7, a7 )
STRUCT_FIELD( long, 4, XT_STK_A8, a8 )
STRUCT_FIELD( long, 4, XT_STK_A9, a9 )
STRUCT_FIELD( long, 4, XT_STK_A10, a10 )
STRUCT_FIELD( long, 4, XT_STK_A11, a11 )
STRUCT_FIELD( long, 4, XT_STK_A12, a12 )
STRUCT_FIELD( long, 4, XT_STK_A13, a13 )
STRUCT_FIELD( long, 4, XT_STK_A14, a14 )
STRUCT_FIELD( long, 4, XT_STK_A15, a15 )
STRUCT_FIELD( long, 4, XT_STK_SAR, sar )
STRUCT_FIELD( long, 4, XT_STK_EXCCAUSE, exccause )
STRUCT_FIELD( long, 4, XT_STK_EXCVADDR, excvaddr )
#if XCHAL_HAVE_LOOPS
    STRUCT_FIELD( long, 4, XT_STK_LBEG, lbeg )
    STRUCT_FIELD( long, 4, XT_STK_LEND, lend )
    STRUCT_FIELD( long, 4, XT_STK_LCOUNT, lcount )
#endif
#ifndef __XTENSA_CALL0_ABI__
/* Temporary space for saving stuff during window spill */
    STRUCT_FIELD( long, 4, XT_STK_TMP0, tmp0 )
    STRUCT_FIELD( long, 4, XT_STK_TMP1, tmp1 )
    STRUCT_FIELD( long, 4, XT_STK_TMP2, tmp2 )
#endif
#ifdef XT_USE_SWPRI
/* Storage for virtual priority mask */
    STRUCT_FIELD( long, 4, XT_STK_VPRI, vpri )
#endif
#ifdef XT_USE_OVLY
/* Storage for overlay state */
    STRUCT_FIELD( long, 4, XT_STK_OVLY, ovly )
#endif
STRUCT_END( XtExcFrame )

#if defined( _ASMLANGUAGE ) || defined( __ASSEMBLER__ )
#define XT_STK_NEXT1    XtExcFrameSize
#else
#define XT_STK_NEXT1    sizeof( XtExcFrame )
#endif

/* Allocate extra storage if needed */
#if XCHAL_EXTRA_SA_SIZE != 0

    #if XCHAL_EXTRA_SA_ALIGN <= 16
#define XT_STK_EXTRA    ALIGNUP( XCHAL_EXTRA_SA_ALIGN, XT_STK_NEXT1 )
    #else
/* If need more alignment than stack, add space for dynamic alignment */
#define XT_STK_EXTRA    ( ALIGNUP( XCHAL_EXTRA_SA_ALIGN, XT_STK_NEXT1 ) + XCHAL_EXTRA_SA_ALIGN )
    #endif
#define XT_STK_NEXT2    ( XT_STK_EXTRA + XCHAL_EXTRA_SA_SIZE )

#else

#define XT_STK_NEXT2    XT_STK_NEXT1

#endif /* if XCHAL_EXTRA_SA_SIZE != 0 */

/*
 * -------------------------------------------------------------------------------
 * This is the frame size. Add space for 4 registers (interruptee's base save
 * area) and some space for gcc nested functions if any.
 * -------------------------------------------------------------------------------
 */
#define XT_STK_FRMSZ    ( ALIGNUP( 0x10, XT_STK_NEXT2 ) + 0x20 )


/*
 * -------------------------------------------------------------------------------
 * SOLICITED STACK FRAME FOR A THREAD
 *
 * A stack frame of this structure is allocated whenever a thread enters the
 * RTOS kernel intentionally (and synchronously) to submit to thread scheduling.
 * It goes on the current thread's stack.
 *
 * The solicited frame only includes registers that are required to be preserved
 * by the callee according to the compiler's ABI conventions, some space to save
 * the return address for returning to the caller, and the caller's PS register.
 *
 * For Windowed ABI, this stack frame includes the caller's base save area.
 *
 * Note on XT_SOL_EXIT field:
 *    It is necessary to distinguish a solicited from an interrupt stack frame.
 *    This field corresponds to XT_STK_EXIT in the interrupt stack frame and is
 *    always at the same offset (0). It can be written with a code (usually 0)
 *    to distinguish a solicted frame from an interrupt frame. An RTOS port may
 *    opt to ignore this field if it has another way of distinguishing frames.
 * -------------------------------------------------------------------------------
 */

STRUCT_BEGIN
#ifdef __XTENSA_CALL0_ABI__
    STRUCT_FIELD( long, 4, XT_SOL_EXIT, exit )
    STRUCT_FIELD( long, 4, XT_SOL_PC, pc )
    STRUCT_FIELD( long, 4, XT_SOL_PS, ps )
    STRUCT_FIELD( long, 4, XT_SOL_NEXT, next )
    STRUCT_FIELD( long, 4, XT_SOL_A12, a12 ) /* should be on 16-byte alignment */
    STRUCT_FIELD( long, 4, XT_SOL_A13, a13 )
    STRUCT_FIELD( long, 4, XT_SOL_A14, a14 )
    STRUCT_FIELD( long, 4, XT_SOL_A15, a15 )
#else
    STRUCT_FIELD( long, 4, XT_SOL_EXIT, exit )
    STRUCT_FIELD( long, 4, XT_SOL_PC, pc )
    STRUCT_FIELD( long, 4, XT_SOL_PS, ps )
    STRUCT_FIELD( long, 4, XT_SOL_NEXT, next )
    STRUCT_FIELD( long, 4, XT_SOL_A0, a0 ) /* should be on 16-byte alignment */
    STRUCT_FIELD( long, 4, XT_SOL_A1, a1 )
    STRUCT_FIELD( long, 4, XT_SOL_A2, a2 )
    STRUCT_FIELD( long, 4, XT_SOL_A3, a3 )
#endif /* ifdef __XTENSA_CALL0_ABI__ */
STRUCT_END( XtSolFrame )

/* Size of solicited stack frame */
#define XT_SOL_FRMSZ    ALIGNUP( 0x10, XtSolFrameSize )


/*
 * -------------------------------------------------------------------------------
 * CO-PROCESSOR STATE SAVE AREA FOR A THREAD
 *
 * The RTOS must provide an area per thread to save the state of co-processors
 * when that thread does not have control. Co-processors are context-switched
 * lazily (on demand) only when a new thread uses a co-processor instruction,
 * otherwise a thread retains ownership of the co-processor even when it loses
 * control of the processor. An Xtensa co-processor exception is triggered when
 * any co-processor instruction is executed by a thread that is not the owner,
 * and the context switch of that co-processor is then peformed by the handler.
 * Ownership represents which thread's state is currently in the co-processor.
 *
 * Co-processors may not be used by interrupt or exception handlers. If an
 * co-processor instruction is executed by an interrupt or exception handler,
 * the co-processor exception handler will trigger a kernel panic and freeze.
 * This restriction is introduced to reduce the overhead of saving and restoring
 * co-processor state (which can be quite large) and in particular remove that
 * overhead from interrupt handlers.
 *
 * The co-processor state save area may be in any convenient per-thread location
 * such as in the thread control block or above the thread stack area. It need
 * not be in the interrupt stack frame since interrupts don't use co-processors.
 *
 * Along with the save area for each co-processor, two bitmasks with flags per
 * co-processor (laid out as in the CPENABLE reg) help manage context-switching
 * co-processors as efficiently as possible:
 *
 * XT_CPENABLE
 *  The contents of a non-running thread's CPENABLE register.
 *  It represents the co-processors owned (and whose state is still needed)
 *  by the thread. When a thread is preempted, its CPENABLE is saved here.
 *  When a thread solicits a context-swtich, its CPENABLE is cleared - the
 *  compiler has saved the (caller-saved) co-proc state if it needs to.
 *  When a non-running thread loses ownership of a CP, its bit is cleared.
 *  When a thread runs, it's XT_CPENABLE is loaded into the CPENABLE reg.
 *  Avoids co-processor exceptions when no change of ownership is needed.
 *
 * XT_CPSTORED
 *  A bitmask with the same layout as CPENABLE, a bit per co-processor.
 *  Indicates whether the state of each co-processor is saved in the state
 *  save area. When a thread enters the kernel, only the state of co-procs
 *  still enabled in CPENABLE is saved. When the co-processor exception
 *  handler assigns ownership of a co-processor to a thread, it restores
 *  the saved state only if this bit is set, and clears this bit.
 *
 * XT_CP_CS_ST
 *  A bitmask with the same layout as CPENABLE, a bit per co-processor.
 *  Indicates whether callee-saved state is saved in the state save area.
 *  Callee-saved state is saved by itself on a solicited context switch,
 *  and restored when needed by the coprocessor exception handler.
 *  Unsolicited switches will cause the entire coprocessor to be saved
 *  when necessary.
 *
 * XT_CP_ASA
 *  Pointer to the aligned save area.  Allows it to be aligned more than
 *  the overall save area (which might only be stack-aligned or TCB-aligned).
 *  Especially relevant for Xtensa cores configured with a very large data
 *  path that requires alignment greater than 16 bytes (ABI stack alignment).
 * -------------------------------------------------------------------------------
 */

#if XCHAL_CP_NUM > 0

/*  Offsets of each coprocessor save area within the 'aligned save area':  */
#define XT_CP0_SA        0
#define XT_CP1_SA        ALIGNUP( XCHAL_CP1_SA_ALIGN, XT_CP0_SA + XCHAL_CP0_SA_SIZE )
#define XT_CP2_SA        ALIGNUP( XCHAL_CP2_SA_ALIGN, XT_CP1_SA + XCHAL_CP1_SA_SIZE )
#define XT_CP3_SA        ALIGNUP( XCHAL_CP3_SA_ALIGN, XT_CP2_SA + XCHAL_CP2_SA_SIZE )
#define XT_CP4_SA        ALIGNUP( XCHAL_CP4_SA_ALIGN, XT_CP3_SA + XCHAL_CP3_SA_SIZE )
#define XT_CP5_SA        ALIGNUP( XCHAL_CP5_SA_ALIGN, XT_CP4_SA + XCHAL_CP4_SA_SIZE )
#define XT_CP6_SA        ALIGNUP( XCHAL_CP6_SA_ALIGN, XT_CP5_SA + XCHAL_CP5_SA_SIZE )
#define XT_CP7_SA        ALIGNUP( XCHAL_CP7_SA_ALIGN, XT_CP6_SA + XCHAL_CP6_SA_SIZE )
#define XT_CP_SA_SIZE    ALIGNUP( 16, XT_CP7_SA + XCHAL_CP7_SA_SIZE )

/*  Offsets within the overall save area:  */
#define XT_CPENABLE      0 /* (2 bytes) coprocessors active for this thread */
#define XT_CPSTORED      2 /* (2 bytes) coprocessors saved for this thread */
#define XT_CP_CS_ST      4 /* (2 bytes) coprocessor callee-saved regs stored for this thread */
#define XT_CP_ASA        8 /* (4 bytes) ptr to aligned save area */
/*  Overall size allows for dynamic alignment:  */
#define XT_CP_SIZE       ( 12 + XT_CP_SA_SIZE + XCHAL_TOTAL_SA_ALIGN )
#else /* if XCHAL_CP_NUM > 0 */
#define XT_CP_SIZE       0
#endif /* if XCHAL_CP_NUM > 0 */


/*
 * -------------------------------------------------------------------------------
 * MACROS TO HANDLE ABI SPECIFICS OF FUNCTION ENTRY AND RETURN
 *
 * Convenient where the frame size requirements are the same for both ABIs.
 *  ENTRY(sz), RET(sz) are for framed functions (have locals or make calls).
 *  ENTRY0,    RET0    are for frameless functions (no locals, no calls).
 *
 * where size = size of stack frame in bytes (must be >0 and aligned to 16).
 * For framed functions the frame is created and the return address saved at
 * base of frame (Call0 ABI) or as determined by hardware (Windowed ABI).
 * For frameless functions, there is no frame and return address remains in a0.
 * Note: Because CPP macros expand to a single line, macros requiring multi-line
 * expansions are implemented as assembler macros.
 * -------------------------------------------------------------------------------
 */

#ifdef __ASSEMBLER__
    #ifdef __XTENSA_CALL0_ABI__
        /* Call0 */
#define ENTRY( sz )    entry1 sz
           .macro entry1 size = 0x10
                                addi sp, sp, -\ size
        s32i a0, sp, 0
           .endm
#define ENTRY0
#define RET( sz )    ret1 sz
           .macro ret1 size = 0x10
                              l32i a0, sp, 0
        addi sp, sp, \ size
        ret
           .endm
#define RET0    ret
    #else /* ifdef __XTENSA_CALL0_ABI__ */
        /* Windowed */
#define ENTRY( sz )    entry sp, sz
#define ENTRY0    entry sp, 0x10
#define RET( sz )      retw
#define RET0      retw
    #endif /* ifdef __XTENSA_CALL0_ABI__ */
#endif /* ifdef __ASSEMBLER__ */


#endif /* XTENSA_CONTEXT_H */