2d7460482d
This commit refactors kernel and arch headers to establish a boundary
between private and public interface headers.
The refactoring strategy used in this commit is detailed in the issue
This commit introduces the following major changes:
1. Establish a clear boundary between private and public headers by
removing "kernel/include" and "arch/*/include" from the global
include paths. Ideally, only kernel/ and arch/*/ source files should
reference the headers in these directories. If these headers must be
used by a component, these include paths shall be manually added to
the CMakeLists.txt file of the component. This is intended to
discourage applications from including private kernel and arch
headers either knowingly and unknowingly.
- kernel/include/ (PRIVATE)
This directory contains the private headers that provide private
kernel definitions which should not be visible outside the kernel
and arch source code. All public kernel definitions must be added
to an appropriate header located under include/.
- arch/*/include/ (PRIVATE)
This directory contains the private headers that provide private
architecture-specific definitions which should not be visible
outside the arch and kernel source code. All public architecture-
specific definitions must be added to an appropriate header located
under include/arch/*/.
- include/ AND include/sys/ (PUBLIC)
This directory contains the public headers that provide public
kernel definitions which can be referenced by both kernel and
application code.
- include/arch/*/ (PUBLIC)
This directory contains the public headers that provide public
architecture-specific definitions which can be referenced by both
kernel and application code.
2. Split arch_interface.h into "kernel-to-arch interface" and "public
arch interface" divisions.
- kernel/include/kernel_arch_interface.h
* provides private "kernel-to-arch interface" definition.
* includes arch/*/include/kernel_arch_func.h to ensure that the
interface function implementations are always available.
* includes sys/arch_interface.h so that public arch interface
definitions are automatically included when including this file.
- arch/*/include/kernel_arch_func.h
* provides architecture-specific "kernel-to-arch interface"
implementation.
* only the functions that will be used in kernel and arch source
files are defined here.
- include/sys/arch_interface.h
* provides "public arch interface" definition.
* includes include/arch/arch_inlines.h to ensure that the
architecture-specific public inline interface function
implementations are always available.
- include/arch/arch_inlines.h
* includes architecture-specific arch_inlines.h in
include/arch/*/arch_inline.h.
- include/arch/*/arch_inline.h
* provides architecture-specific "public arch interface" inline
function implementation.
* supersedes include/sys/arch_inline.h.
3. Refactor kernel and the existing architecture implementations.
- Remove circular dependency of kernel and arch headers. The
following general rules should be observed:
* Never include any private headers from public headers
* Never include kernel_internal.h in kernel_arch_data.h
* Always include kernel_arch_data.h from kernel_arch_func.h
* Never include kernel.h from kernel_struct.h either directly or
indirectly. Only add the kernel structures that must be referenced
from public arch headers in this file.
- Relocate syscall_handler.h to include/ so it can be used in the
public code. This is necessary because many user-mode public codes
reference the functions defined in this header.
- Relocate kernel_arch_thread.h to include/arch/*/thread.h. This is
necessary to provide architecture-specific thread definition for
'struct k_thread' in kernel.h.
- Remove any private header dependencies from public headers using
the following methods:
* If dependency is not required, simply omit
* If dependency is required,
- Relocate a portion of the required dependencies from the
private header to an appropriate public header OR
- Relocate the required private header to make it public.
This commit supersedes #20047, addresses #19666, and fixes #3056.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
133 lines
4.8 KiB
C
133 lines
4.8 KiB
C
/*
|
|
* Copyright (c) 2016 Cadence Design Systems, Inc.
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_ARCH_XTENSA_INCLUDE_XTENSA_CONFIG_H_
|
|
#define ZEPHYR_ARCH_XTENSA_INCLUDE_XTENSA_CONFIG_H_
|
|
|
|
#include <xtensa/hal.h>
|
|
#include <xtensa/config/core.h>
|
|
#include <xtensa/config/system.h> /* required for XSHAL_CLIB */
|
|
|
|
#include "xtensa_context.h"
|
|
|
|
/*
|
|
* STACK REQUIREMENTS
|
|
*
|
|
* This section defines the minimum stack size, and the extra space required to
|
|
* be allocated for saving coprocessor state and/or C library state information
|
|
* (if thread safety is enabled for the C library). The sizes are in bytes.
|
|
*
|
|
* Stack sizes for individual threads should be derived from these minima based
|
|
* on the maximum call depth of the task and the maximum level of interrupt
|
|
* nesting. A minimum stack size is defined by XT_STACK_MIN_SIZE. This minimum
|
|
* is based on the requirement for a task that calls nothing else but can be
|
|
* interrupted. This assumes that interrupt handlers do not call more than a
|
|
* few levels deep. If this is not true, i.e. one or more interrupt handlers
|
|
* make deep calls then the minimum must be increased.
|
|
*
|
|
* If the Xtensa processor configuration includes coprocessors, then space is
|
|
* allocated to save the coprocessor state on the stack.
|
|
*
|
|
* If thread safety is enabled for the C runtime library,
|
|
* (XT_USE_THREAD_SAFE_CLIB is defined) then space is allocated to save the C
|
|
* library context in the TCB.
|
|
*
|
|
* Allocating insufficient stack space is a common source of hard-to-find
|
|
* errors. During development, it is best to enable the FreeRTOS stack
|
|
* checking features.
|
|
*
|
|
* Usage:
|
|
*
|
|
* XT_USE_THREAD_SAFE_CLIB -- Define this to a nonzero value to enable
|
|
* thread-safe use of the C library. This will require extra stack space to be
|
|
* allocated for threads that use the C library reentrant functions. See below
|
|
* for more information.
|
|
*
|
|
* NOTE: The Xtensa toolchain supports multiple C libraries and not all of them
|
|
* support thread safety. Check your core configuration to see which C library
|
|
* was chosen for your system.
|
|
*
|
|
* XT_STACK_MIN_SIZE -- The minimum stack size for any task. It is
|
|
* recommended that you do not use a stack smaller than this for any task. In
|
|
* case you want to use stacks smaller than this size, you must verify that the
|
|
* smaller size(s) will work under all operating conditions.
|
|
*
|
|
* XT_STACK_EXTRA -- The amount of extra stack space to allocate for a
|
|
* task that does not make C library reentrant calls. Add this to the amount of
|
|
* stack space required by the task itself.
|
|
*
|
|
* XT_STACK_EXTRA_CLIB -- The amount of space to allocate for C library
|
|
* state.
|
|
*/
|
|
|
|
/* Extra space required for interrupt/exception hooks. */
|
|
#ifdef XT_INTEXC_HOOKS
|
|
#ifdef __XTENSA_CALL0_ABI__
|
|
#define STK_INTEXC_EXTRA 0x200
|
|
#else
|
|
#define STK_INTEXC_EXTRA 0x180
|
|
#endif
|
|
#else
|
|
#define STK_INTEXC_EXTRA 0
|
|
#endif
|
|
|
|
/* Check C library thread safety support and compute size of C library save
|
|
* area.
|
|
*/
|
|
#if XT_USE_THREAD_SAFE_CLIB > 0u
|
|
#if XSHAL_CLIB == XTHAL_CLIB_XCLIB
|
|
#define XT_HAVE_THREAD_SAFE_CLIB 0
|
|
#error "Thread-safe operation is not yet supported for the XCLIB C library."
|
|
#elif XSHAL_CLIB == XTHAL_CLIB_NEWLIB
|
|
#define XT_HAVE_THREAD_SAFE_CLIB 1
|
|
#if !defined __ASSEMBLER__
|
|
#include <sys/reent.h>
|
|
#define XT_CLIB_CONTEXT_AREA_SIZE ((sizeof(struct _reent) + 15) + (-16))
|
|
#define XT_CLIB_GLOBAL_PTR _impure_ptr
|
|
#endif
|
|
#else
|
|
#define XT_HAVE_THREAD_SAFE_CLIB 0
|
|
#error "The selected C runtime library is not thread safe."
|
|
#endif
|
|
#else
|
|
#define XT_CLIB_CONTEXT_AREA_SIZE 0
|
|
#endif
|
|
|
|
/* Extra size -- interrupt frame plus coprocessor save area plus hook space.
|
|
*
|
|
* NOTE: Make sure XT_INTEXC_HOOKS is undefined unless you really need the
|
|
* hooks.
|
|
*/
|
|
#ifdef __XTENSA_CALL0_ABI__
|
|
#define XT_XTRA_SIZE (XT_STK_FRMSZ + STK_INTEXC_EXTRA + 0x10 + XT_CP_SIZE)
|
|
#else
|
|
#define XT_XTRA_SIZE (XT_STK_FRMSZ + STK_INTEXC_EXTRA + 0x20 + XT_CP_SIZE)
|
|
#endif
|
|
|
|
/*
|
|
* Space allocated for user code -- function calls and local variables.
|
|
*
|
|
* NOTE: This number can be adjusted to suit your needs. You must verify that
|
|
* the amount of space you reserve is adequate for the worst-case conditions in
|
|
* your application. NOTE: The windowed ABI requires more stack, since space
|
|
* has to be reserved for spilling register windows.
|
|
*/
|
|
#ifdef __XTENSA_CALL0_ABI__
|
|
#define XT_USER_SIZE 0x200
|
|
#else
|
|
#define XT_USER_SIZE 0x400
|
|
#endif
|
|
|
|
/* Minimum recommended stack size. */
|
|
#define XT_STACK_MIN_SIZE \
|
|
((XT_XTRA_SIZE + XT_USER_SIZE) / sizeof(unsigned char))
|
|
|
|
/* OS overhead with and without C library thread context. */
|
|
#define XT_STACK_EXTRA (XT_XTRA_SIZE)
|
|
#define XT_STACK_EXTRA_CLIB (XT_XTRA_SIZE + XT_CLIB_CONTEXT_AREA_SIZE)
|
|
|
|
|
|
#endif /* ZEPHYR_ARCH_XTENSA_INCLUDE_XTENSA_CONFIG_H_ */
|