doxygen does not support ordered (numbered) lists using reST syntax
``1)`` or ``a)`` unless the doxygen comments are bounded by ``@rst`` and
``@endrst`` markers. The "doxygen" way to do ordered lists is to use
``-#``. This PR cleans this up for our API documentation.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit removes duplicate 'irq_offload_routine_t' typedef
declaration in sys/arch_interface.h.
This typedef is provided by irq_offload.h and, since this header file
is included at the top of sys/arch_interface.h, it is guaranteed to be
defined for arch_irq_offload definition.
While this does not cause a compilation error when compiling with GCC
4.6 and above, GCC 4.5 and below strictly enforce the C99 standard and
do not allow redeclaration of the same typedef in the same scope.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Some use cases require using high-resolution tick or cycle clocks to
measure sub-millisecond durations. Generate the corresponding 32-bit
conversions to avoid the cost of 64-bit math in the common case where
the duration fits in 32 bits in both original and converted scale.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Entering irq_offload() on multiple CPUs can cause
difficult to debug/reproduce crashes. Demote irq_offload()
to non-inline (it never needed to be inline anyway) and
wrap the arch call in a semaphore.
Some tests which were unnecessarily killing threads
have been fixed; these threads exit by themselves anyway
and we won't leave the semaphore dangling.
The definition of z_arch_irq_offload() moved to
arch_interface.h as it only gets called by kernel C code.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
Promote the private z_arch_* namespace, which specifies
the interface between the core kernel and the
architecture code, to a new top-level namespace named
arch_*.
This allows our documentation generation to create
online documentation for this set of interfaces,
and this set of interfaces is worth treating in a
more formal way anyway.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
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>
We need to pass system call args using a register-width
data type and not hard-code this to u32_t.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
The struct definitions for pdpt, pd, and pt entries has been
removed:
- Bitfield ordering in a struct is implementation dependent,
it can be right-to-left or left-to-right
- The two different structures for page directory entries were
not being used consistently, or when the type of the PDE
was unknown
- Anonymous structs/unions are GCC extensions
Instead these are now u64_t, with bitwise operations used to
get/set fields.
A new set of inline functions for fetcing various page table
structures has been implemented, replacing the older macros.
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
Default behavior is to include __FILE__ info with all of the Zephyr
assert macros, __ASSERT, __ASSERT_NO_MSG and __ASSERT_LOC. Setting the
ASSERT_NO_FILE_INFO kconfig option, replaces the __FILE__ with an
empty string, thus removing the file information from the asserts.
The intention here is to allow for code space limited devices to run
with asserts enabled.
Signed-off-by: Danny Oerndrup <daor@demant.com>
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>
Similarly to commit 223a2b950f ("mempool: move BUILD_ASSERT to the
end of K_MEM_POOL_DEFINE"), move BUILD_ASSERT() at the end for
consistency.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The realloc function was a bit too intimate with the mempool accounting.
Abstract that knowledge away and move it where it belongs.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
MAX() and MIN() were evaluating arguments twice. If arguments are
functions they were called twice which resulted in bigger code
and potential misbehavior.
Added alternative macros (Z_MAX, Z_MIN) which can be used instead.
Macros have usage limitations thus they are not replacements. They
are also relying on GCC extension thus placed in gcc.h
Signed-off-by: Krzysztof Chruscinski <krzysztof.chruscinski@nordicsemi.no>
Some modules use snprintk to format the settings keys. Unfortunately
snprintk is tied with printk which is very large for some embedded
systems.
To be able to have settings enabled without also enabling printk
support, change creation of settings key strings to use bin2hex, strlen
and strcpy instead.
A utility function to make decimal presentation of a byte value is
added as u8_to_dec in lib/os/dec.c
Add new Kconfig setting BT_SETTINGS_USE_PRINTK
Signed-off-by: Kim Sekkelund <ksek@oticon.com>
We don't really have docs on how fatal errors are induced
or handled. Provide some documentation that covers:
- Assertions (runtime and build)
- Kernel panic and oops conditions
- Stack overflows
- Other exceptions
- Exception handling policy
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>
The algorithm for converting broken-down civil time to seconds in the
POSIX epoch time scale would produce undefined behavior on a toolchain
that uses a 32-bit time_t in cases where the referenced time could not
be represented exactly.
However, there are use cases in Zephyr for civil time conversions
outside the 32-bit representable range of 1901-12-13T20:45:52Z through
2038-01-19T03:14:07Z inclusive.
Add new API that specifically returns a 64-bit signed seconds count, and
revise the existing API to detect out-of-range values and convert them
to a diagnosible error.
Closes#18465
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
timeutil_timegm() does not modify the passed structure, so it should
indicate that in the signature (even though the GNU extension does not).
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
Commit db48d3e22a ("sys_sem: add build time definition macros")
recently introduced SYS_SEM_DEFINE() and defined it in terms of
Z_DECL_ALIGN() and __in_section() to force the _k_sem linker section.
It is however cleaner and less obscur to use Z_STRUCT_SECTION_ITERABLE()
and list the _sys_sem linker section alongside the _k_sem one.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
sys_dlist_insert_before and sys_dlist_insert_after have been deprecated
for at least 2 releases. We can now remove them.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This commit adds an explicit inclusion of toolchain.h from byteorder.h.
The endianness preprocessor definitions (__BYTE_ORDER__,
__ORDER_LITTLE_ENDIAN__, __ORDER_BIG_ENDIAN__) are used by byteorder.h;
these being not defined can easily go unnoticed and cause unexpected
behaviours, as detailed in PR #18922.
toolchain.h ensures that these preprocessor definitions are defined and
*must* be included in a file that uses these definitions.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Consistently place C++ use of extern "C" after all include directives,
within the negative branch of _ASMLANGUAGE if used.
The inclusion of the generated syscall files is placed outside the
extern "C" block as the generated file has its own extern "C" block.
Background from issue #17997:
Declarations that use C linkage should be placed within extern "C"
so the language linkage is correct when the header is included by
a C++ compiler.
Similarly #include directives should be outside the extern "C" to
ensure the language-specific default linkage is applied to any
declarations provided by the included header.
See: https://en.cppreference.com/w/cpp/language/language_linkage
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Z_MPOOL_LVLS() expands into the sum of 16 _MPOOL_HAVE_LVL() instances,
and _MPOOL_BITS_SIZE() expands into the sum of 16 Z_MPOOL_LVLS()
instances. In the end, a single _MPOOL_BITS_SIZE() expands to 256
_MPOOL_HAVE_LVL() instances!
Let's make it slightly easier on the compiler, and easier for humans
too, by reworking Z_MPOOL_HAVE_LVL(() so that ic can be used directly
into Z_MPOOL_LBIT_BYTES(), making the code logic much simpler.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
For systems with userspace, the sys_sem exist in user memory working
as counter semaphore for user mode thread. The implemention of sys_sem
is based on k_futex. And the majority of the synchronization operations
are performed in user mode to reduce the calling of system call.
And for systems without userspace enabled, sys_sem behaves like k_sem.
Fixes: #15139.
Signed-off-by: Wentong Wu <wentong.wu@intel.com>
Add a generic API to provide the inverse operation for gmtime and as a
home for future generic time-related functions that are not in POSIX.
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
This reverts commit 755cc644cc.
This approach is problematic in several ways. First, `intptr_t` could
cause undefined behavior in the subtraction when the pointer converts to
a negative value. Except in weird cases where the sign of the pointer
identifies a memory domain (like kernel vs userspace) I'm unaware of any
valid use of `intptr_t`.
Second, this macro was created to address a special need that cannot
rely on defined behavior: i.e. to ensure that data definitions are
placed in contiguous space and access is provided through linker-defined
symbols, for which the language required alignment and continuity is not
guaranteed.
A macro that calculates the span between linker symbols has very
different semantics than one that calculates the difference between
pointers. Replace the global PTR_DIFF with a documented local macro
that tests what's necessary without risking integer overflow.
Signed-off-by: Peter A. Bigot <pab@pabigot.com>
Move duplicate hex2bin and add bin2hex function so that application can
use the functions and avoid code duplication.
Signed-off-by: Joakim Andersson <joakim.andersson@nordicsemi.no>
Some code casts pointers to ints in order to obtain their difference.
The compiler complains on 64-bit targets as an int is not wide enough
to hold a pointer.
Let's introduce the PTR_DIFF() helper macro to applies the proper cast
to pointers before performing a difference on them, and still return the
result as an int which should be large enough in practice.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
If maxsize is smaller than _MPOOL_MINBLK, then Z_MPOOL_LVLS() will be 0.
That means the loop in z_sys_mem_pool_base_init() that initializes the
block free list for the nonexistent level 0 will corrupt whatever memory
at the location the zero-sized struct sys_mem_pool_lvl array was
located. And the corruption happens to be done with a perfectly legit
memory pool block address which makes for really nasty bugs to solve.
This is more likely on 64-bit systems due to _MPOOL_MINBLK being twice
the size of 32-bit systems.
Let's prevent that with a build-time assertion on maxsize when defining
a memory pool, and adjust the affected test accordingly.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
The "bits" field in struct sys_mem_pool_lvl is unioned with a pointer.
That leaves more space for inline free bits on 64-bit targets.
Let's declare it as an array and adjust its size based on the pointer
size. On 32-bit targets the generated code remains identical.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
Minimum alignment and rounding must be done on a word boundary. Let's
replace _ALIGN4() with WB_UP() which is equivalent on 32-bit targets,
and 64-bit aware.
Also enforce a minimal alignment on the memory pool. This is making
a difference mostly on64-bit targets where the widely used 4-byte
alignment is not sufficient.
The _ALIGN4() macro has no users left so it is removed.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
move misc/util.h to sys/util.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/speculation.h to sys/speculation.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/slist.h to sys/slist.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/sflist.h to sys/sflist.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/rb.h to sys/rb.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/printk.h to sys/printk.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/mutex.h to sys/mutex.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/mempool.h to sys/mempool.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/mempool_base.h to sys/mempool_base.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/math_extras_impl.h to sys/math_extras_impl.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/math_extras.h to sys/math_extras.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/list_gen.h to sys/list_gen.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/libc-hooks.h to sys/libc-hooks.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/fdtable.h to sys/fdtable.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/errno_private.h to sys/errno_private.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/dlist.h to sys/dlist.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/byteorder.h to sys/byteorder.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move misc/__assert.h to sys/__assert.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move ring_buffer.h to sys/ring_buffer.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move sys_io.h to sys/sys_io.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move crc.h to sys/crc.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move base64.h to sys/base64.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
move atomic.h to sys/atomic.h and
create a shim for backward-compatibility.
No functional changes to the headers.
A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES.
Related to #16539
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
