/* Copyright (C) 2005 David Decotigny Copyright (C) 2000-2004, The KOS team This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef _SOS_CPUCTXT_H_ #define _SOS_CPUCTXT_H_ /** * @file cpu_context.h * * Low level API to manage kernel and user thread CPU contexts. Should * be some kind of architecture-independent. */ #include #include /** * Prepare the system to deal with multiple CPU execution contexts */ sos_ret_t sos_cpu_context_subsystem_setup(); /** * Opaque structure storing the CPU context of an inactive kernel or * user thread, as saved by the low level primitives below or by the * interrupt/exception handlers. * * @note This is an (architecture-independent) forward declaration: * see cpu_context.c and the *.S files for its * (architecture-dependent) definition. */ struct sos_cpu_state; /** * The type of the functions passed as arguments to the Kernel thread * related functions. */ typedef void (sos_cpu_kstate_function_arg1_t(sos_ui32_t arg1)); /** * Function to create an initial context for a kernel thread starting * its execution at function start_func with the argument initial_arg, * and having the stack defined by stack_bottom/stack_size. When the * start_func function returns, the function exit_func is called with * argument exit_arg. * * @param kctxt The kernel thread CPU context to initialize. The * address of the newly-initialized struct sos_cpu_state will be * stored in this variable. The contents of this struct sos_cpu_state * are actually located /inside/ the stack. * * @param start_func The address of the first instruction that will be * executed when this context will be first transferred on * CPU. Practically speaking, this is the address of a function that * is assumed to take 1 argument. * * @param start_arg The value that will be passed as the argument to * start_func when the thread starts. The stack will be setup * accordingly to simulate a real call to the function and really * passing this arguement. * * @param stack_bottom The lowest address of the stack. * * @param stack_size The size of the stack. * * @param exit_func The address of the instruction executed after the * function start_func has returned. This function takes 1 parameter * as argument: exit_arg. * * @param exit_arg The argument passed to the function exit_func. * * @note the newly created context is INTERRUPTIBLE by default ! */ sos_ret_t sos_cpu_kstate_init(struct sos_cpu_state **kctxt, sos_cpu_kstate_function_arg1_t *start_func, sos_ui32_t start_arg, sos_vaddr_t stack_bottom, sos_size_t stack_size, sos_cpu_kstate_function_arg1_t *exit_func, sos_ui32_t exit_arg); /** * Function to create an initial context for a user thread starting * its execution at function user_start_PC with the user_start_arg * argument. The address of the user stack before any modification by * the ustate_init() function is given by user_start_SP. The user * thread starts in user space first and needs a kernel stack for * the syscalls and for handling interrupts: the address of this * kernel stack is given by the kernel_stack_* parameters. * * @param uctxt The user thread CPU context to initialize. The * address of the newly-initialized struct sos_cpu_state will be * stored in this variable. The contents of this struct sos_cpu_state * are actually located /inside/ the kernel stack of the thread. * * @param user_start_PC The address of the first instruction that will * be executed in user mode when this context will be first * transferred on CPU. Practically speaking, this is the address of a * function that is assumed to take 1 argument. * * @param user_start_SP The initial user stack address. * * @param user_start_argX The 2 parameters passed to the initial user * thread function (in registers). * * @param kernel_stack_bottom The lowest address of the kernel stack * used to switch to user mode and to handle interrupts/exceptions. * * @param kernel_stack_size The size of the kernel stack (@see * kernel_stack_bottom). * * @note the newly thread context is INTERRUPTIBLE ! */ sos_ret_t sos_cpu_ustate_init(struct sos_cpu_state **uctxt, sos_uaddr_t user_start_PC, sos_ui32_t user_start_arg1, sos_ui32_t user_start_arg2, sos_uaddr_t user_initial_SP, sos_vaddr_t kernel_stack_bottom, sos_size_t kernel_stack_size); /** * Function that performs an immediate context-switch from one * kernel/user thread to another one. It stores the current executing * context in from_ctxt, and restores to_context on CPU. * * @param from_ctxt The address of the struct sos_cpu_state will be * stored in this variable. Must NOT be NULL. * * @param to_ctxt The CPU will resume its execution with the struct * sos_cpu_state located at this address. Must NOT be NULL. */ void sos_cpu_context_switch(struct sos_cpu_state **from_ctxt, struct sos_cpu_state *to_ctxt); /* * Switch to the new given context (of a kernel/user thread) without * saving the old context (of another kernel/user thread), and call * the function reclaiming_func passing it the recalining_arg * argument. The reclaining function is called from within the stack * of the new context, so that it can (among other things) safely * destroy the stack of the former context. * * @param switch_to_ctxt The context that will be restored on the CPU * * @param reclaiming_func The address of the function that will be * called after having changed the stack, but before restoring the CPU * context to switch_to_ctxt. */ void sos_cpu_context_exit_to(struct sos_cpu_state *switch_to_ctxt, sos_cpu_kstate_function_arg1_t *reclaiming_func, sos_ui32_t reclaiming_arg) __attribute__((noreturn)); /* ======================================================================= * Public Accessor functions */ /** * Return whether the saved context was in kernel or user context * * @return TRUE when context was interrupted when in user mode, FALSE * when in kernel mode, < 0 on error. */ sos_ret_t sos_cpu_context_is_in_user_mode(const struct sos_cpu_state *ctxt); /** * Return Program Counter stored in the saved kernel/user context */ sos_vaddr_t sos_cpu_context_get_PC(const struct sos_cpu_state *ctxt); /** * Return Stack Pointer stored in the saved kernel/user context */ sos_vaddr_t sos_cpu_context_get_SP(const struct sos_cpu_state *ctxt); /** * Dump the contents of the CPU context (bochs + x86_videomem) */ void sos_cpu_context_dump(const struct sos_cpu_state *ctxt); /* ======================================================================= * Public Accessor functions TO BE USED ONLY BY Exception handlers */ /** * Return the argument passed by the CPU upon exception, as stored in the * saved context */ sos_ui32_t sos_cpu_context_get_EX_info(const struct sos_cpu_state *ctxt); /** * Return the faulting address of the exception */ sos_vaddr_t sos_cpu_context_get_EX_faulting_vaddr(const struct sos_cpu_state *ctxt); /** * Change the return address of the given context */ sos_ret_t sos_cpu_context_set_EX_return_address(struct sos_cpu_state *ctxt, sos_vaddr_t ret_vaddr); /* ======================================================================= * Public Accessor functions TO BE USED ONLY BY the SYSCALL handler */ /** * Low-level functions used by the syscall handler. They are * responsible for retrieving the arguments passed to the syscall when * a user thread makes a syscall. Some of these arguments are * available as registers' values in the user context, some of them * are user-space addresses given by these registers. * * @return SOS_OK on success, <0 otherwise */ sos_ret_t sos_syscall_get1arg(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1); sos_ret_t sos_syscall_get2args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2); sos_ret_t sos_syscall_get3args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3); sos_ret_t sos_syscall_get4args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3, /* out */unsigned int *arg4); sos_ret_t sos_syscall_get5args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3, /* out */unsigned int *arg4, /* out */unsigned int *arg5); sos_ret_t sos_syscall_get6args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3, /* out */unsigned int *arg4, /* out */unsigned int *arg5, /* out */unsigned int *arg6); sos_ret_t sos_syscall_get7args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3, /* out */unsigned int *arg4, /* out */unsigned int *arg5, /* out */unsigned int *arg6, /* out */unsigned int *arg7); sos_ret_t sos_syscall_get8args(const struct sos_cpu_state *user_ctxt, /* out */unsigned int *arg1, /* out */unsigned int *arg2, /* out */unsigned int *arg3, /* out */unsigned int *arg4, /* out */unsigned int *arg5, /* out */unsigned int *arg6, /* out */unsigned int *arg7, /* out */unsigned int *arg8); /* ======================================================================= * Macros controlling stack poisoning. * Stack poisoning can be used to detect: * - unitialized local variables * - when the thread might have gone too deep in the stack */ /** The signature of the poison */ #define SOS_CPU_STATE_STACK_POISON 0xa5 /** * When set, mean that the whole stack is poisoned to detect use of * unititialized variables */ #define SOS_CPU_STATE_DETECT_UNINIT_KERNEL_VARS /* #undef SOS_CPU_STATE_DETECT_UNINIT_KERNEL_VARS */ /** * When set, mean that the bottom of the stack is poisoned to detect * probable stack overflow. Its value indicates the number of bytes * used for this detection. */ #define SOS_CPU_STATE_DETECT_KERNEL_STACK_OVERFLOW 64 /* #undef SOS_CPU_STATE_DETECT_KERNEL_STACK_OVERFLOW */ #if defined(SOS_CPU_STATE_DETECT_KERNEL_STACK_OVERFLOW) void sos_cpu_state_prepare_detect_kernel_stack_overflow(const struct sos_cpu_state *ctxt, sos_vaddr_t kernel_stack_bottom, sos_size_t kernel_stack_size); void sos_cpu_state_detect_kernel_stack_overflow(const struct sos_cpu_state *ctxt, sos_vaddr_t kernel_stack_bottom, sos_size_t kernel_stack_size); #else # define sos_cpu_state_prepare_detect_kernel_stack_overflow(ctxt,stkbottom,stksize) \ ({ /* nop */ }) # define sos_cpu_state_detect_kernel_stack_overflow(ctxt,stkbottom,stksize) \ ({ /* nop */ }) #endif /* ======================================================================= * Backtrace facility. To be used for DEBUGging purpose ONLY. */ /** * The function called at each step of the backtrace iterations * * @param PC The address of the next instruction of the function that * will be executed * * @param params The address of the array of the parameteres that have * been passed to the function considered * * @param depth The index of the iteration (ie the depth of the * current frame into the stack) * * @param custom_arg Whatever you want: this is the argument passed as * custom_arg to sos_backtrace() */ typedef void (sos_backtrace_callback_t)(sos_vaddr_t PC, sos_vaddr_t params, sos_ui32_t depth, void *custom_arg); /** * Call the backtracer callback on each frame stored in the cpu_state * * @param cpu_state The CPU context we want to explore. MUST be the * context of a thread in Kernel mode, or NULL. When NULL: backtrace * the current CPU context. * * @param max_depth The maximum number of frames to explore * * @param stack_bottom The lower boundary of the stack. This is used * to make sure that the frame addresses fit inside the stack * boudaries (ie are potentially correct). * * @param stack_size The size of the stack. Same comment. * * @param backtracer The function to call to handle the frame for each * iteration * * @param custom_arg The arg passed as custom_arg to the backtracer * * @return The number of frames explored. * * @note Might be inaccurate when gcc's -fomit-frame-pointer has been * used. */ sos_ui32_t sos_backtrace(const struct sos_cpu_state *cpu_state, sos_ui32_t max_depth, sos_vaddr_t stack_bottom, sos_size_t stack_size, sos_backtrace_callback_t * backtracer, void *custom_arg); #endif /* _SOS_CPUCTXT_H_ */