kernel: add architecture interface headers
include/sys/arch_inlines.h will contain all architecture APIs that are used by public inline functions and macros, with implementations deriving from include/arch/cpu.h. kernel/include/arch_interface.h will contain everything else, with implementations deriving from arch/*/include/kernel_arch_func.h. Instances of duplicate documentation for these APIs have been removed; implementation details have been left in place. Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
This commit is contained in:
Andrew Boie
Anas Nashif
parent
33e6384e48
commit
8ffff144ea
37 changed files with 925 additions and 960 deletions
463
include/sys/arch_inlines.h
Normal file
463
include/sys/arch_inlines.h
Normal file
|
|
@ -0,0 +1,463 @@
|
|||
/*
|
||||
* Copyright (c) 2019 Intel Corporation.
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* @brief Internal kernel APIs with public scope
|
||||
*
|
||||
* The main set of architecture APIs is specified by
|
||||
* include/sys/arch_interface.h
|
||||
*
|
||||
* Any public kernel APIs that are implemented as inline functions and need to
|
||||
* call architecture-specific APIso will have the prototypes for the
|
||||
* architecture-specific APIs here. Architecture APIs that aren't used in this
|
||||
* way go in include/sys/arch_interface.h.
|
||||
*
|
||||
* The set of architecture-specific macros used internally by public macros
|
||||
* in public headers is also specified and documented.
|
||||
*
|
||||
* For all macros and inline function prototypes described herein, <arch/cpu.h>
|
||||
* must eventually pull in full definitions for all of them (the actual macro
|
||||
* defines and inline function bodies)
|
||||
*
|
||||
* include/kernel.h and other public headers depend on definitions in this
|
||||
* header.
|
||||
*/
|
||||
|
||||
#ifndef ZEPHYR_INCLUDE_SYS_ARCH_INLINES_H_
|
||||
#define ZEPHYR_INCLUDE_SYS_ARCH_INLINES_H_
|
||||
|
||||
#ifndef _ASMLANGUAGE
|
||||
|
||||
#include <stdbool.h>
|
||||
#include <zephyr/types.h>
|
||||
#include <arch/cpu.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* NOTE: We cannot pull in kernel.h here, need some forward declarations */
|
||||
struct k_thread;
|
||||
typedef struct _k_thread_stack_element k_thread_stack_t;
|
||||
|
||||
/**
|
||||
* @addtogroup arch-timing
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Obtain the current cycle count, in units that are hardware-specific
|
||||
*
|
||||
* @see k_cycle_get_32()
|
||||
*/
|
||||
static inline u32_t z_arch_k_cycle_get_32(void);
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @addtogroup arch-threads
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_DEFINE(sym, size)
|
||||
*
|
||||
* @see K_THREAD_STACK_DEFINE()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_ARRAY_DEFINE(sym, size)
|
||||
*
|
||||
* @see K_THREAD_STACK_ARRAY_DEFINE()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_LEN(size)
|
||||
*
|
||||
* @see K_THREAD_STACK_LEN()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_MEMBER(sym, size)
|
||||
*
|
||||
* @see K_THREAD_STACK_MEMBER()
|
||||
*/
|
||||
|
||||
/*
|
||||
* @def Z_ARCH_THREAD_STACK_SIZEOF(sym)
|
||||
*
|
||||
* @see K_THREAD_STACK_SIZEOF()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_RESERVED
|
||||
*
|
||||
* @see K_THREAD_STACK_RESERVED
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_THREAD_STACK_BUFFER(sym)
|
||||
*
|
||||
* @see K_THREAD_STACK_RESERVED
|
||||
*/
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @addtogroup arch-pm
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Power save idle routine
|
||||
*
|
||||
* This function will be called by the kernel idle loop or possibly within
|
||||
* an implementation of z_sys_power_save_idle in the kernel when the
|
||||
* '_sys_power_save_flag' variable is non-zero.
|
||||
*
|
||||
* Architectures that do not implement power management instructions may
|
||||
* immediately return, otherwise a power-saving instruction should be
|
||||
* issued to wait for an interrupt.
|
||||
*
|
||||
* @see k_cpu_idle()
|
||||
*/
|
||||
void z_arch_cpu_idle(void);
|
||||
|
||||
/**
|
||||
* @brief Atomically re-enable interrupts and enter low power mode
|
||||
*
|
||||
* The requirements for z_arch_cpu_atomic_idle() are as follows:
|
||||
*
|
||||
* 1) Enabling interrupts and entering a low-power mode needs to be
|
||||
* atomic, i.e. there should be no period of time where interrupts are
|
||||
* enabled before the processor enters a low-power mode. See the comments
|
||||
* in k_lifo_get(), for example, of the race condition that
|
||||
* occurs if this requirement is not met.
|
||||
*
|
||||
* 2) After waking up from the low-power mode, the interrupt lockout state
|
||||
* must be restored as indicated in the 'key' input parameter.
|
||||
*
|
||||
* @see k_cpu_atomic_idle()
|
||||
*
|
||||
* @param key Lockout key returned by previous invocation of z_arch_irq_lock()
|
||||
*/
|
||||
void z_arch_cpu_atomic_idle(unsigned int key);
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @addtogroup arch-smp
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Start a numbered CPU on a MP-capable system
|
||||
*
|
||||
* This starts and initializes a specific CPU. The main thread on startup is
|
||||
* running on CPU zero, other processors are numbered sequentially. On return
|
||||
* from this function, the CPU is known to have begun operating and will enter
|
||||
* the provided function. Its interrupts will be initialized but disabled such
|
||||
* that irq_unlock() with the provided key will work to enable them.
|
||||
*
|
||||
* Normally, in SMP mode this function will be called by the kernel
|
||||
* initialization and should not be used as a user API. But it is defined here
|
||||
* for special-purpose apps which want Zephyr running on one core and to use
|
||||
* others for design-specific processing.
|
||||
*
|
||||
* @param cpu_num Integer number of the CPU
|
||||
* @param stack Stack memory for the CPU
|
||||
* @param sz Stack buffer size, in bytes
|
||||
* @param fn Function to begin running on the CPU. First argument is
|
||||
* an irq_unlock() key.
|
||||
* @param arg Untyped argument to be passed to "fn"
|
||||
*/
|
||||
void z_arch_start_cpu(int cpu_num, k_thread_stack_t *stack, int sz,
|
||||
void (*fn)(int key, void *data), void *arg);
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @addtogroup arch-irq
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Lock interrupts on the current CPU
|
||||
*
|
||||
* @see irq_lock()
|
||||
*/
|
||||
static inline unsigned int z_arch_irq_lock(void);
|
||||
|
||||
/**
|
||||
* Unlock interrupts on the current CPU
|
||||
*
|
||||
* @see irq_unlock()
|
||||
*/
|
||||
static inline void z_arch_irq_unlock(unsigned int key);
|
||||
|
||||
/**
|
||||
* Test if calling z_arch_irq_unlock() with this key would unlock irqs
|
||||
*
|
||||
* @param key value returned by z_arch_irq_lock()
|
||||
* @return true if interrupts were unlocked prior to the z_arch_irq_lock()
|
||||
* call that produced the key argument.
|
||||
*/
|
||||
static inline bool z_arch_irq_unlocked(unsigned int key);
|
||||
|
||||
/**
|
||||
* Disable the specified interrupt line
|
||||
*
|
||||
* @see irq_disable()
|
||||
*/
|
||||
void z_arch_irq_disable(unsigned int irq);
|
||||
|
||||
/**
|
||||
* Enable the specified interrupt line
|
||||
*
|
||||
* @see irq_enable()
|
||||
*/
|
||||
void z_arch_irq_enable(unsigned int irq);
|
||||
|
||||
/**
|
||||
* Test if an interrupt line is enabled
|
||||
*
|
||||
* @see irq_is_enabled()
|
||||
*/
|
||||
int z_arch_irq_is_enabled(unsigned int irq);
|
||||
|
||||
/**
|
||||
* Arch-specific hook to install a dynamic interrupt.
|
||||
*
|
||||
* @param irq IRQ line number
|
||||
* @param priority Interrupt priority
|
||||
* @param routine Interrupt service routine
|
||||
* @param parameter ISR parameter
|
||||
* @param flags Arch-specific IRQ configuration flag
|
||||
*
|
||||
* @return The vector assigned to this interrupt
|
||||
*/
|
||||
int z_arch_irq_connect_dynamic(unsigned int irq, unsigned int priority,
|
||||
void (*routine)(void *parameter),
|
||||
void *parameter, u32_t flags);
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_IRQ_CONNECT(irq, pri, isr, arg, flags)
|
||||
*
|
||||
* @see IRQ_CONNECT()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_IRQ_DIRECT_CONNECT(irq_p, priority_p, isr_p, flags_p)
|
||||
*
|
||||
* @see IRQ_DIRECT_CONNECT()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_ISR_DIRECT_PM()
|
||||
*
|
||||
* @see ISR_DIRECT_PM()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_ISR_DIRECT_HEADER()
|
||||
*
|
||||
* @see ISR_DIRECT_HEADER()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_ISR_DIRECT_FOOTER(swap)
|
||||
*
|
||||
* @see ISR_DIRECT_FOOTER()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_ISR_DIRECT_DECLARE(name)
|
||||
*
|
||||
* @see ISR_DIRECT_DECLARE()
|
||||
*/
|
||||
|
||||
/**
|
||||
* @def Z_ARCH_EXCEPT(reason_p)
|
||||
*
|
||||
* Generate a software induced fatal error.
|
||||
*
|
||||
* If the caller is running in user mode, only K_ERR_KERNEL_OOPS or
|
||||
* K_ERR_STACK_CHK_FAIL may be induced.
|
||||
*
|
||||
* This should ideally generate a software trap, with exception context
|
||||
* indicating state when this was invoked. General purpose register state at
|
||||
* the time of trap should not be disturbed from the calling context.
|
||||
*
|
||||
* @param reason_p K_ERR_ scoped reason code for the fatal error.
|
||||
*/
|
||||
|
||||
#ifdef CONFIG_IRQ_OFFLOAD
|
||||
typedef void (*irq_offload_routine_t)(void *parameter);
|
||||
|
||||
/**
|
||||
* Run a function in interrupt context.
|
||||
*
|
||||
* Implementations should invoke an exception such that the kernel goes through
|
||||
* its interrupt handling dispatch path, to include switching to the interrupt
|
||||
* stack, and runs the provided routine and parameter.
|
||||
*
|
||||
* The only intended use-case for this function is for test code to simulate
|
||||
* the correctness of kernel APIs in interrupt handling context. This API
|
||||
* is not intended for real applications.
|
||||
*
|
||||
* @see irq_offload()
|
||||
*
|
||||
* @param routine Function to run in interrupt context
|
||||
* @param parameter Value to pass to the function when invoked
|
||||
*/
|
||||
void z_arch_irq_offload(irq_offload_routine_t routine, void *parameter);
|
||||
#endif /* CONFIG_IRQ_OFFLOAD */
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @addtogroup arch-userspace
|
||||
* @{
|
||||
*/
|
||||
|
||||
#ifdef CONFIG_USERSPACE
|
||||
/**
|
||||
* Invoke a system call with 0 arguments.
|
||||
*
|
||||
* No general-purpose register state other than return value may be preserved
|
||||
* when transitioning from supervisor mode back down to user mode for
|
||||
* security reasons.
|
||||
*
|
||||
* It is required that all arguments be stored in registers when elevating
|
||||
* privileges from user to supervisor mode.
|
||||
*
|
||||
* Processing of the syscall takes place on a separate kernel stack. Interrupts
|
||||
* should be enabled when invoking the system call marshallers from the
|
||||
* dispatch table. Thread preemption may occur when handling system calls.
|
||||
*
|
||||
* Call ids are untrusted and must be bounds-checked, as the value is used to
|
||||
* index the system call dispatch table, containing function pointers to the
|
||||
* specific system call code.
|
||||
*
|
||||
* @param call_id System call ID
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke0(u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 1 argument.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke1(u32_t arg1, u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 2 arguments.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param arg2 Second argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke2(u32_t arg1, u32_t arg2,
|
||||
u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 3 arguments.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param arg2 Second argument to the system call.
|
||||
* @param arg3 Third argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke3(u32_t arg1, u32_t arg2, u32_t arg3,
|
||||
u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 4 arguments.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param arg2 Second argument to the system call.
|
||||
* @param arg3 Third argument to the system call.
|
||||
* @param arg4 Fourth argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke4(u32_t arg1, u32_t arg2, u32_t arg3,
|
||||
u32_t arg4, u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 5 arguments.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param arg2 Second argument to the system call.
|
||||
* @param arg3 Third argument to the system call.
|
||||
* @param arg4 Fourth argument to the system call.
|
||||
* @param arg5 Fifth argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke5(u32_t arg1, u32_t arg2, u32_t arg3,
|
||||
u32_t arg4, u32_t arg5,
|
||||
u32_t call_id);
|
||||
|
||||
/**
|
||||
* Invoke a system call with 6 arguments.
|
||||
*
|
||||
* @see z_arch_syscall_invoke0()
|
||||
*
|
||||
* @param arg1 First argument to the system call.
|
||||
* @param arg2 Second argument to the system call.
|
||||
* @param arg3 Third argument to the system call.
|
||||
* @param arg4 Fourth argument to the system call.
|
||||
* @param arg5 Fifth argument to the system call.
|
||||
* @param arg6 Sixth argument to the system call.
|
||||
* @param call_id System call ID, will be bounds-checked and used to reference
|
||||
* kernel-side dispatch table
|
||||
* @return Return value of the system call. Void system calls return 0 here.
|
||||
*/
|
||||
static inline u32_t z_arch_syscall_invoke6(u32_t arg1, u32_t arg2, u32_t arg3,
|
||||
u32_t arg4, u32_t arg5, u32_t arg6,
|
||||
u32_t call_id);
|
||||
|
||||
/**
|
||||
* Indicate whether we are currently running in user mode
|
||||
*
|
||||
* @return true if the CPU is currently running with user permissions
|
||||
*/
|
||||
static inline bool z_arch_is_user_context(void);
|
||||
#endif /* CONFIG_USERSPACE */
|
||||
|
||||
/** @} */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
#endif /* _ASMLANGUAGE */
|
||||
#endif /* ZEPHYR_INCLUDE?SYS_ARCH_INLINES_H_ */
|
||||
408
include/sys/arch_interface.h
Normal file
408
include/sys/arch_interface.h
Normal file
|
|
@ -0,0 +1,408 @@
|
|||
/*
|
||||
* Copyright (c) 2019 Intel Corporation.
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* @brief Internal kernel APIs implemented at the architecture layer.
|
||||
*
|
||||
* Not all architecture-specific defines are here, APIs that are used
|
||||
* by public inline functions and macros are described in
|
||||
* include/sys/arch_inlines.h.
|
||||
*
|
||||
* For all inline functions prototyped here, the implementation is expected
|
||||
* to be provided by arch/ARCH/include/kernel_arch_func.h
|
||||
*
|
||||
* This header is not intended for general use; like kernel_arch_func.h,
|
||||
* it is intended to be pulled in by internal kernel headers, specifically
|
||||
* kernel/include/kernel_structs.h
|
||||
*/
|
||||
#ifndef ZEPHYR_INCLUDE_SYS_ARCH_INTERFACE_H_
|
||||
#define ZEPHYR_INCLUDE_SYS_ARCH_INTERFACE_H_
|
||||
|
||||
#ifndef _ASMLANGUAGE
|
||||
#include <kernel.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @defgroup arch-timing Architecture timing APIs
|
||||
* @{
|
||||
*/
|
||||
#ifdef CONFIG_ARCH_HAS_CUSTOM_BUSY_WAIT
|
||||
/**
|
||||
* Architecture-specific implementation of busy-waiting
|
||||
*
|
||||
* @param usec_to_wait Wait period, in microseconds
|
||||
*/
|
||||
void z_arch_busy_wait(u32_t usec_to_wait);
|
||||
#endif
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup arch-threads Architecture thread APIs
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** Handle arch-specific logic for setting up new threads
|
||||
*
|
||||
* The stack and arch-specific thread state variables must be set up
|
||||
* such that a later attempt to switch to this thread will succeed
|
||||
* and we will enter z_thread_entry with the requested thread and
|
||||
* arguments as its parameters.
|
||||
*
|
||||
* At some point in this function's implementation, z_setup_new_thread() must
|
||||
* be called with the true bounds of the available stack buffer within the
|
||||
* thread's stack object.
|
||||
*
|
||||
* @param thread Pointer to uninitialized struct k_thread
|
||||
* @param pStack Pointer to the stack space.
|
||||
* @param stackSize Stack size in bytes.
|
||||
* @param entry Thread entry function.
|
||||
* @param p1 1st entry point parameter.
|
||||
* @param p2 2nd entry point parameter.
|
||||
* @param p3 3rd entry point parameter.
|
||||
* @param prio Thread priority.
|
||||
* @param options Thread options.
|
||||
*/
|
||||
void z_arch_new_thread(struct k_thread *thread, k_thread_stack_t *pStack,
|
||||
size_t stackSize, k_thread_entry_t entry,
|
||||
void *p1, void *p2, void *p3,
|
||||
int prio, unsigned int options);
|
||||
|
||||
#ifdef CONFIG_USE_SWITCH
|
||||
/**
|
||||
* Cooperatively context switch
|
||||
*
|
||||
* The semantics of the two switch handles are entirely up to the architecture
|
||||
* implementation, and are stored per thread in k_thread->switch_handle.
|
||||
* The outgoing thread's switch handle pointer may be updated during this
|
||||
* process.
|
||||
*
|
||||
* @param switch_to Incoming thread's switch handle
|
||||
* @param switched_from Pointer to outgoing thread's switch handle, which
|
||||
* may be updated.
|
||||
*/
|
||||
static inline void z_arch_switch(void *switch_to, void **switched_from);
|
||||
#else
|
||||
/**
|
||||
* Cooperatively context switch
|
||||
*
|
||||
* Must be called with interrupts locked with the provided key.
|
||||
* This is the older-style context switching method, which is incompatible
|
||||
* with SMP. New arch ports, either SMP or UP, are encouraged to implement
|
||||
* z_arch_switch() instead.
|
||||
*
|
||||
* @param key Interrupt locking key
|
||||
* @return If woken from blocking on some kernel object, the result of that
|
||||
* blocking operation.
|
||||
*/
|
||||
int z_arch_swap(unsigned int key);
|
||||
|
||||
/**
|
||||
* Set the return value for the specified thread.
|
||||
*
|
||||
* It is assumed that the specified @a thread is pending.
|
||||
*
|
||||
* @param thread Pointer to thread object
|
||||
* @param value value to set as return value
|
||||
*/
|
||||
static ALWAYS_INLINE void
|
||||
z_arch_thread_return_value_set(struct k_thread *thread, unsigned int value);
|
||||
#endif /* CONFIG_USE_SWITCH i*/
|
||||
|
||||
#ifdef CONFIG_ARCH_HAS_CUSTOM_SWAP_TO_MAIN
|
||||
/**
|
||||
* Custom logic for entering main thread context at early boot
|
||||
*
|
||||
* Used by architectures where the typical trick of setting up a dummy thread
|
||||
* in early boot context to "switch out" of isn't workable.
|
||||
*
|
||||
* @param main_thread main thread object
|
||||
* @param main_stack main thread's stack object
|
||||
* @param main_stack_size Size of the stack object's buffer
|
||||
* @param _main Entry point for application main function.
|
||||
*/
|
||||
void z_arch_switch_to_main_thread(struct k_thread *main_thread,
|
||||
k_thread_stack_t *main_stack,
|
||||
size_t main_stack_size,
|
||||
k_thread_entry_t _main);
|
||||
#endif /* CONFIG_ARCH_HAS_CUSTOM_SWAP_TO_MAIN */
|
||||
|
||||
#if defined(CONFIG_FLOAT) && defined(CONFIG_FP_SHARING)
|
||||
/**
|
||||
* @brief Disable floating point context preservation
|
||||
*
|
||||
* The function is used to disable the preservation of floating
|
||||
* point context information for a particular thread.
|
||||
*
|
||||
* @note For ARM architecture, disabling floating point preservation may only
|
||||
* be requested for the current thread and cannot be requested in ISRs.
|
||||
*
|
||||
* @retval 0 On success.
|
||||
* @retval -EINVAL If the floating point disabling could not be performed.
|
||||
*/
|
||||
int z_arch_float_disable(struct k_thread *thread);
|
||||
#endif /* CONFIG_FLOAT && CONFIG_FP_SHARING */
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup arch-pm Architecture-specific power management APIs
|
||||
* @{
|
||||
*/
|
||||
/** Halt the system, optionally propagating a reason code */
|
||||
FUNC_NORETURN void z_arch_system_halt(unsigned int reason);
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup arch-smp Architecture-specific SMP APIs
|
||||
* @{
|
||||
*/
|
||||
#ifdef CONFIG_SMP
|
||||
/** Return the CPU struct for the currently executing CPU */
|
||||
static inline struct _cpu *z_arch_curr_cpu(void);
|
||||
|
||||
/**
|
||||
* Broadcast an interrupt to all CPUs
|
||||
*
|
||||
* This will invoke z_sched_ipi() on other CPUs in the system.
|
||||
*/
|
||||
void z_arch_sched_ipi(void);
|
||||
#endif /* CONFIG_SMP */
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup arch-irq Architecture-specific IRQ APIs
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Test if the current context is in interrupt context
|
||||
*
|
||||
* XXX: This is inconsistently handled among arches wrt exception context
|
||||
* See: #17656
|
||||
*
|
||||
* @return true if we are in interrupt context
|
||||
*/
|
||||
static inline bool z_arch_is_in_isr(void);
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup arch-userspace Architecture-specific userspace APIs
|
||||
* @{
|
||||
*/
|
||||
#ifdef CONFIG_USERSPACE
|
||||
/**
|
||||
* @brief Get the maximum number of partitions for a memory domain
|
||||
*
|
||||
* @return Max number of partitions, or -1 if there is no limit
|
||||
*/
|
||||
int z_arch_mem_domain_max_partitions_get(void);
|
||||
|
||||
/**
|
||||
* @brief Add a thread to a memory domain (arch-specific)
|
||||
*
|
||||
* Architecture-specific hook to manage internal data structures or hardware
|
||||
* state when the provided thread has been added to a memory domain.
|
||||
*
|
||||
* The thread's memory domain pointer will be set to the domain to be added
|
||||
* to.
|
||||
*
|
||||
* @param thread Thread which needs to be configured.
|
||||
*/
|
||||
void z_arch_mem_domain_thread_add(struct k_thread *thread);
|
||||
|
||||
/**
|
||||
* @brief Remove a thread from a memory domain (arch-specific)
|
||||
*
|
||||
* Architecture-specific hook to manage internal data structures or hardware
|
||||
* state when the provided thread has been removed from a memory domain.
|
||||
*
|
||||
* The thread's memory domain pointer will be the domain that the thread
|
||||
* is being removed from.
|
||||
*
|
||||
* @param thread Thread being removed from its memory domain
|
||||
*/
|
||||
void z_arch_mem_domain_thread_remove(struct k_thread *thread);
|
||||
|
||||
/**
|
||||
* @brief Remove a partition from the memory domain (arch-specific)
|
||||
*
|
||||
* Architecture-specific hook to manage internal data structures or hardware
|
||||
* state when a memory domain has had a partition removed.
|
||||
*
|
||||
* The partition index data, and the number of partitions configured, are not
|
||||
* respectively cleared and decremented in the domain until after this function
|
||||
* runs.
|
||||
*
|
||||
* @param domain The memory domain structure
|
||||
* @param partition_id The partition index that needs to be deleted
|
||||
*/
|
||||
void z_arch_mem_domain_partition_remove(struct k_mem_domain *domain,
|
||||
u32_t partition_id);
|
||||
|
||||
/**
|
||||
* @brief Add a partition to the memory domain
|
||||
*
|
||||
* Architecture-specific hook to manage internal data structures or hardware
|
||||
* state when a memory domain has a partition added.
|
||||
*
|
||||
* @param domain The memory domain structure
|
||||
* @param partition_id The partition that needs to be added
|
||||
*/
|
||||
void z_arch_mem_domain_partition_add(struct k_mem_domain *domain,
|
||||
u32_t partition_id);
|
||||
|
||||
/**
|
||||
* @brief Remove the memory domain
|
||||
*
|
||||
* Architecture-specific hook to manage internal data structures or hardware
|
||||
* state when a memory domain has been destroyed.
|
||||
*
|
||||
* Thread assignments to the memory domain are only cleared after this function
|
||||
* runs.
|
||||
*
|
||||
* @param domain The memory domain structure which needs to be deleted.
|
||||
*/
|
||||
void z_arch_mem_domain_destroy(struct k_mem_domain *domain);
|
||||
|
||||
/**
|
||||
* @brief Check memory region permissions
|
||||
*
|
||||
* Given a memory region, return whether the current memory management hardware
|
||||
* configuration would allow a user thread to read/write that region. Used by
|
||||
* system calls to validate buffers coming in from userspace.
|
||||
*
|
||||
* Notes:
|
||||
* The function is guaranteed to never return validation success, if the entire
|
||||
* buffer area is not user accessible.
|
||||
*
|
||||
* The function is guaranteed to correctly validate the permissions of the
|
||||
* supplied buffer, if the user access permissions of the entire buffer are
|
||||
* enforced by a single, enabled memory management region.
|
||||
*
|
||||
* In some architectures the validation will always return failure
|
||||
* if the supplied memory buffer spans multiple enabled memory management
|
||||
* regions (even if all such regions permit user access).
|
||||
*
|
||||
* @param addr start address of the buffer
|
||||
* @param size the size of the buffer
|
||||
* @param write If nonzero, additionally check if the area is writable.
|
||||
* Otherwise, just check if the memory can be read.
|
||||
*
|
||||
* @return nonzero if the permissions don't match.
|
||||
*/
|
||||
int z_arch_buffer_validate(void *addr, size_t size, int write);
|
||||
|
||||
/**
|
||||
* Perform a one-way transition from supervisor to kernel mode.
|
||||
*
|
||||
* Implementations of this function must do the following:
|
||||
*
|
||||
* - Reset the thread's stack pointer to a suitable initial value. We do not
|
||||
* need any prior context since this is a one-way operation.
|
||||
* - Set up any kernel stack region for the CPU to use during privilege
|
||||
* elevation
|
||||
* - Put the CPU in whatever its equivalent of user mode is
|
||||
* - Transfer execution to z_arch_new_thread() passing along all the supplied
|
||||
* arguments, in user mode.
|
||||
*
|
||||
* @param user_entry Entry point to start executing as a user thread
|
||||
* @param p1 1st parameter to user thread
|
||||
* @param p2 2nd parameter to user thread
|
||||
* @param p3 3rd parameter to user thread
|
||||
*/
|
||||
FUNC_NORETURN void z_arch_user_mode_enter(k_thread_entry_t user_entry,
|
||||
void *p1, void *p2, void *p3);
|
||||
|
||||
/**
|
||||
* @brief Induce a kernel oops that appears to come from a specific location
|
||||
*
|
||||
* Normally, k_oops() generates an exception that appears to come from the
|
||||
* call site of the k_oops() itself.
|
||||
*
|
||||
* However, when validating arguments to a system call, if there are problems
|
||||
* we want the oops to appear to come from where the system call was invoked
|
||||
* and not inside the validation function.
|
||||
*
|
||||
* @param ssf System call stack frame pointer. This gets passed as an argument
|
||||
* to _k_syscall_handler_t functions and its contents are completely
|
||||
* architecture specific.
|
||||
*/
|
||||
FUNC_NORETURN void z_arch_syscall_oops(void *ssf);
|
||||
|
||||
/**
|
||||
* @brief Safely take the length of a potentially bad string
|
||||
*
|
||||
* This must not fault, instead the err parameter must have -1 written to it.
|
||||
* This function otherwise should work exactly like libc strnlen(). On success
|
||||
* *err should be set to 0.
|
||||
*
|
||||
* @param s String to measure
|
||||
* @param maxsize Max length of the string
|
||||
* @param err Error value to write
|
||||
* @return Length of the string, not counting NULL byte, up to maxsize
|
||||
*/
|
||||
size_t z_arch_user_string_nlen(const char *s, size_t maxsize, int *err);
|
||||
#endif /* CONFIG_USERSPACE */
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup arch-benchmarking Architecture-specific benchmarking globals
|
||||
*/
|
||||
|
||||
#ifdef CONFIG_EXECUTION_BENCHMARKING
|
||||
extern u64_t z_arch_timing_swap_start;
|
||||
extern u64_t z_arch_timing_swap_end;
|
||||
extern u64_t z_arch_timing_irq_start;
|
||||
extern u64_t z_arch_timing_irq_end;
|
||||
extern u64_t z_arch_timing_tick_start;
|
||||
extern u64_t z_arch_timing_tick_end;
|
||||
extern u64_t z_arch_timing_user_mode_end;
|
||||
extern u32_t z_arch_timing_value_swap_end;
|
||||
extern u64_t z_arch_timing_value_swap_common;
|
||||
extern u64_t z_arch_timing_value_swap_temp;
|
||||
#endif /* CONFIG_EXECUTION_BENCHMARKING */
|
||||
|
||||
/** @} */
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup arch-misc Miscellaneous architecture APIs
|
||||
*/
|
||||
|
||||
/**
|
||||
* Architecture-specific kernel initialization hook
|
||||
*
|
||||
* This function is invoked near the top of _Cstart, for additional
|
||||
* architecture-specific setup before the rest of the kernel is brought up.
|
||||
*
|
||||
* TODO: Deprecate, most arches are using a prep_c() function to do the same
|
||||
* thing in a simpler way
|
||||
*/
|
||||
static inline void z_arch_kernel_init(void);
|
||||
|
||||
/** Do nothing and return. Yawn. */
|
||||
static inline void z_arch_nop(void);
|
||||
|
||||
/** @} */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif /* __cplusplus */
|
||||
#endif /* _ASMLANGUAGE */
|
||||
#endif /* ZEPHYR_INCLUDE_SYS_ARCH_INTERFACE_H_ */
|
||||
Loading…
Add table
Add a link
Reference in a new issue