diff options
Diffstat (limited to 'cpukit/include/rtems/rtems')
60 files changed, 4103 insertions, 1840 deletions
diff --git a/cpukit/include/rtems/rtems/asr.h b/cpukit/include/rtems/rtems/asr.h index 1b0af08a0e..1d3ba5fe4f 100644 --- a/cpukit/include/rtems/rtems/asr.h +++ b/cpukit/include/rtems/rtems/asr.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/asrdata.h b/cpukit/include/rtems/rtems/asrdata.h index 924e616a9a..1a02a20ce5 100644 --- a/cpukit/include/rtems/rtems/asrdata.h +++ b/cpukit/include/rtems/rtems/asrdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_ASRDATA_H diff --git a/cpukit/include/rtems/rtems/attr.h b/cpukit/include/rtems/rtems/attr.h index 24b49247ee..708be99b2d 100644 --- a/cpukit/include/rtems/rtems/attr.h +++ b/cpukit/include/rtems/rtems/attr.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2020 embedded brains GmbH & Co. KG * Copyright (C) 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/attrimpl.h b/cpukit/include/rtems/rtems/attrimpl.h index a41b3ad89b..e5ac35c26a 100644 --- a/cpukit/include/rtems/rtems/attrimpl.h +++ b/cpukit/include/rtems/rtems/attrimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_ATTR_INL @@ -61,7 +80,7 @@ extern "C" { * This function sets the requested new_attributes in the attribute_set * passed in. The result is returned to the user. */ -RTEMS_INLINE_ROUTINE rtems_attribute _Attributes_Set ( +static inline rtems_attribute _Attributes_Set ( rtems_attribute new_attributes, rtems_attribute attribute_set ) @@ -76,7 +95,7 @@ RTEMS_INLINE_ROUTINE rtems_attribute _Attributes_Set ( * This function clears the requested new_attributes in the attribute_set * passed in. The result is returned to the user. */ -RTEMS_INLINE_ROUTINE rtems_attribute _Attributes_Clear ( +static inline rtems_attribute _Attributes_Clear ( rtems_attribute attribute_set, rtems_attribute mask ) @@ -91,7 +110,7 @@ RTEMS_INLINE_ROUTINE rtems_attribute _Attributes_Clear ( * This function returns TRUE if the floating point attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_floating_point( +static inline bool _Attributes_Is_floating_point( rtems_attribute attribute_set ) { @@ -106,7 +125,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_floating_point( * This function returns TRUE if the global object attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_global( +static inline bool _Attributes_Is_global( rtems_attribute attribute_set ) { @@ -120,7 +139,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_global( * This function returns TRUE if the priority attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_priority( +static inline bool _Attributes_Is_priority( rtems_attribute attribute_set ) { @@ -134,7 +153,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_priority( * This function returns TRUE if the binary semaphore attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_binary_semaphore( +static inline bool _Attributes_Is_binary_semaphore( rtems_attribute attribute_set ) { @@ -148,7 +167,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_binary_semaphore( * This function returns TRUE if the simple binary semaphore attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_simple_binary_semaphore( +static inline bool _Attributes_Is_simple_binary_semaphore( rtems_attribute attribute_set ) { @@ -163,7 +182,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_simple_binary_semaphore( * This function returns TRUE if the counting semaphore attribute is * enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_counting_semaphore( +static inline bool _Attributes_Is_counting_semaphore( rtems_attribute attribute_set ) { @@ -177,7 +196,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_counting_semaphore( * This function returns TRUE if the priority inheritance attribute * is enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_inherit_priority( +static inline bool _Attributes_Is_inherit_priority( rtems_attribute attribute_set ) { @@ -191,7 +210,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_inherit_priority( * The protocols are RTEMS_INHERIT_PRIORITY, RTEMS_PRIORITY_CEILING and * RTEMS_MULTIPROCESSOR_RESOURCE_SHARING. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Has_at_most_one_protocol( +static inline bool _Attributes_Has_at_most_one_protocol( rtems_attribute attribute_set ) { @@ -208,7 +227,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Has_at_most_one_protocol( * This function returns TRUE if the priority ceiling attribute * is enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_priority_ceiling( +static inline bool _Attributes_Is_priority_ceiling( rtems_attribute attribute_set ) { @@ -222,7 +241,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_priority_ceiling( * This function returns TRUE if the Multiprocessor Resource Sharing Protocol * attribute is enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_multiprocessor_resource_sharing( +static inline bool _Attributes_Is_multiprocessor_resource_sharing( rtems_attribute attribute_set ) { @@ -236,7 +255,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_multiprocessor_resource_sharing( * This function returns TRUE if the barrier automatic release * attribute is enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_barrier_automatic( +static inline bool _Attributes_Is_barrier_automatic( rtems_attribute attribute_set ) { @@ -250,7 +269,7 @@ RTEMS_INLINE_ROUTINE bool _Attributes_Is_barrier_automatic( * This function returns TRUE if the system task attribute * is enabled in the attribute_set and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Attributes_Is_system_task( +static inline bool _Attributes_Is_system_task( rtems_attribute attribute_set ) { diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h index 348610d886..029cffb406 100644 --- a/cpukit/include/rtems/rtems/barrier.h +++ b/cpukit/include/rtems/rtems/barrier.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -137,7 +137,7 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * barrier. The number of barriers available to the application is - * configured through the #CONFIGURE_MAXIMUM_BARRIERS application + * configured through the @ref CONFIGURE_MAXIMUM_BARRIERS application * configuration option. * * @par Notes @@ -157,7 +157,7 @@ extern "C" { * cause the calling task to be preempted. * * * The number of barriers available to the application is configured through - * the #CONFIGURE_MAXIMUM_BARRIERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_BARRIERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/barrierdata.h b/cpukit/include/rtems/rtems/barrierdata.h index b449186a59..b963d08603 100644 --- a/cpukit/include/rtems/rtems/barrierdata.h +++ b/cpukit/include/rtems/rtems/barrierdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_BARRIERDATA_H diff --git a/cpukit/include/rtems/rtems/barrierimpl.h b/cpukit/include/rtems/rtems/barrierimpl.h index 5f96273f89..88228b64f9 100644 --- a/cpukit/include/rtems/rtems/barrierimpl.h +++ b/cpukit/include/rtems/rtems/barrierimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_BARRIERIMPL_H @@ -43,7 +62,7 @@ extern "C" { * This function allocates a barrier control block from * the inactive chain of free barrier control blocks. */ -RTEMS_INLINE_ROUTINE Barrier_Control *_Barrier_Allocate( void ) +static inline Barrier_Control *_Barrier_Allocate( void ) { return (Barrier_Control *) _Objects_Allocate( &_Barrier_Information ); } @@ -54,7 +73,7 @@ RTEMS_INLINE_ROUTINE Barrier_Control *_Barrier_Allocate( void ) * This routine frees a barrier control block to the * inactive chain of free barrier control blocks. */ -RTEMS_INLINE_ROUTINE void _Barrier_Free ( +static inline void _Barrier_Free ( Barrier_Control *the_barrier ) { @@ -62,7 +81,7 @@ RTEMS_INLINE_ROUTINE void _Barrier_Free ( _Objects_Free( &_Barrier_Information, &the_barrier->Object ); } -RTEMS_INLINE_ROUTINE Barrier_Control *_Barrier_Get( +static inline Barrier_Control *_Barrier_Get( Objects_Id id, Thread_queue_Context *queue_context ) diff --git a/cpukit/include/rtems/rtems/cache.h b/cpukit/include/rtems/rtems/cache.h index c7c19b80e2..d59a3fddca 100644 --- a/cpukit/include/rtems/rtems/cache.h +++ b/cpukit/include/rtems/rtems/cache.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplClassicCache + * * @brief This header file defines the Cache Manager API. */ /* * Copyright (C) 2016 Pavel Pisa - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -57,6 +59,7 @@ #include <stddef.h> #include <stdint.h> +#include <rtems/rtems/status.h> #ifdef __cplusplus extern "C" { @@ -87,6 +90,10 @@ extern "C" { * * @param size is the size in bytes of the cache coherent memory area to add. * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_UNSATISFIED The requested operation was not successful. + * * @par Constraints * @parblock * The following constraints apply to this directive: @@ -100,7 +107,7 @@ extern "C" { * cause the calling task to be preempted. * @endparblock */ -void rtems_cache_coherent_add_area( void *begin, uintptr_t size ); +rtems_status_code rtems_cache_coherent_add_area( void *begin, uintptr_t size ); /* Generated from spec:/rtems/cache/if/coherent-allocate */ diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h index 6cdc8d68e3..5a8d0a44f9 100644 --- a/cpukit/include/rtems/rtems/clock.h +++ b/cpukit/include/rtems/rtems/clock.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -116,8 +116,8 @@ struct bintime; * before 2100-01-01:00:00.000000000Z. The latest valid time of day accepted * by the POSIX clock_settime() is 2400-01-01T00:00:00.999999999Z. * - * The specified time is based on the configured clock tick rate, see the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The specified time is based on the configured clock tick rate, see the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * Setting the time forward will fire all CLOCK_REALTIME timers which are * scheduled at a time point before or at the time set by the directive. This @@ -451,8 +451,8 @@ void rtems_clock_get_realtime_coarse_timeval( struct timeval *time_snapshot ); * @brief Gets the time elapsed since some fixed time point in the past * measured using the CLOCK_MONOTONIC in seconds and nanoseconds format. * - * @param[out] time_snapshot is the pointer to a bintime object. The time - * elapsed since some fixed time point in the past measured using the + * @param[out] time_snapshot is the pointer to a struct timespec object. The + * time elapsed since some fixed time point in the past measured using the * CLOCK_MONOTONIC at some time point during the directive call will be * stored in this object. Calling the directive with a pointer equal to NULL * is undefined behaviour. @@ -562,8 +562,8 @@ int64_t rtems_clock_get_monotonic_sbintime( void ); * @brief Gets the time elapsed since some fixed time point in the past * measured using the CLOCK_MONOTONIC in seconds and microseconds format. * - * @param[out] time_snapshot is the pointer to a bintime object. The time - * elapsed since some fixed time point in the past measured using the + * @param[out] time_snapshot is the pointer to a struct timeval object. The + * time elapsed since some fixed time point in the past measured using the * CLOCK_MONOTONIC at some time point during the directive call will be * stored in this object. Calling the directive with a pointer equal to NULL * is undefined behaviour. @@ -601,8 +601,8 @@ void rtems_clock_get_monotonic_timeval( struct timeval *time_snapshot ); * measured using the CLOCK_MONOTONIC in coarse resolution in seconds and * nanoseconds format. * - * @param[out] time_snapshot is the pointer to a bintime object. The time - * elapsed since some fixed time point in the past measured using the + * @param[out] time_snapshot is the pointer to a struct timespec object. The + * time elapsed since some fixed time point in the past measured using the * CLOCK_MONOTONIC at some time point close to the directive call will be * stored in this object. Calling the directive with a pointer equal to NULL * is undefined behaviour. @@ -681,8 +681,8 @@ void rtems_clock_get_monotonic_coarse_bintime( struct bintime *time_snapshot ); * measured using the CLOCK_MONOTONIC in coarse resolution in seconds and * microseconds format. * - * @param[out] time_snapshot is the pointer to a bintime object. The time - * elapsed since some fixed time point in the past measured using the + * @param[out] time_snapshot is the pointer to a struct timeval object. The + * time elapsed since some fixed time point in the past measured using the * CLOCK_MONOTONIC at some time point close to the directive call will be * stored in this object. Calling the directive with a pointer equal to NULL * is undefined behaviour. @@ -853,8 +853,8 @@ rtems_status_code rtems_clock_get_seconds_since_epoch( * application. * * @par Notes - * The number of clock ticks per second is defined indirectly by the - * #CONFIGURE_MICROSECONDS_PER_TICK configuration option. + * The number of clock ticks per second is defined indirectly by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK configuration option. * * @par Constraints * @parblock @@ -909,7 +909,7 @@ rtems_interval rtems_clock_get_ticks_since_boot( void ); * @brief Gets the seconds and nanoseconds elapsed since some time point during * the system initialization using CLOCK_MONOTONIC. * - * @param[out] uptime is the pointer to a struct timeval object. When the + * @param[out] uptime is the pointer to a struct timespec object. When the * directive call is successful, the seconds and nanoseconds elapsed since * some time point during the system initialization and some point during the * directive call using CLOCK_MONOTONIC will be stored in this object. @@ -1135,6 +1135,18 @@ static inline bool rtems_clock_tick_before( rtems_interval ticks ) * @par Notes * The directive is a legacy interface. It should not be called by * applications directly. A Clock Driver may call this directive. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * @endparblock */ rtems_status_code rtems_clock_tick( void ); diff --git a/cpukit/include/rtems/rtems/clockimpl.h b/cpukit/include/rtems/rtems/clockimpl.h index c8334afaf3..c025ea9c9a 100644 --- a/cpukit/include/rtems/rtems/clockimpl.h +++ b/cpukit/include/rtems/rtems/clockimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_CLOCKIMPL_H diff --git a/cpukit/include/rtems/rtems/config.h b/cpukit/include/rtems/rtems/config.h index 2a12c8f3cb..d225902bf1 100644 --- a/cpukit/include/rtems/rtems/config.h +++ b/cpukit/include/rtems/rtems/config.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file provides parts of the application configuration * information API. */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -78,7 +80,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Tasks * configured for this application. * - * See #CONFIGURE_MAXIMUM_TASKS. + * See @ref CONFIGURE_MAXIMUM_TASKS. */ uint32_t maximum_tasks; @@ -92,7 +94,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Timers * configured for this application. * - * See #CONFIGURE_MAXIMUM_TIMERS. + * See @ref CONFIGURE_MAXIMUM_TIMERS. */ uint32_t maximum_timers; @@ -100,7 +102,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Semaphores * configured for this application. * - * See #CONFIGURE_MAXIMUM_SEMAPHORES. + * See @ref CONFIGURE_MAXIMUM_SEMAPHORES. */ uint32_t maximum_semaphores; @@ -108,7 +110,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Message Queues * configured for this application. * - * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES. + * See @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES. */ uint32_t maximum_message_queues; @@ -116,7 +118,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Partitions * configured for this application. * - * See #CONFIGURE_MAXIMUM_PARTITIONS. + * See @ref CONFIGURE_MAXIMUM_PARTITIONS. */ uint32_t maximum_partitions; @@ -124,7 +126,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Regions * configured for this application. * - * See #CONFIGURE_MAXIMUM_REGIONS. + * See @ref CONFIGURE_MAXIMUM_REGIONS. */ uint32_t maximum_regions; @@ -132,7 +134,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Dual-Ported * Memories configured for this application. * - * See #CONFIGURE_MAXIMUM_PORTS. + * See @ref CONFIGURE_MAXIMUM_PORTS. */ uint32_t maximum_ports; @@ -140,7 +142,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Rate Monotonic * Periods configured for this application. * - * See #CONFIGURE_MAXIMUM_PERIODS. + * See @ref CONFIGURE_MAXIMUM_PERIODS. */ uint32_t maximum_periods; @@ -148,7 +150,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Barriers * configured for this application. * - * See #CONFIGURE_MAXIMUM_BARRIERS. + * See @ref CONFIGURE_MAXIMUM_BARRIERS. */ uint32_t maximum_barriers; @@ -156,7 +158,7 @@ typedef struct { * @brief This member contains the number of Classic API Initialization Tasks * configured for this application. * - * See #CONFIGURE_RTEMS_INIT_TASKS_TABLE. + * See @ref CONFIGURE_RTEMS_INIT_TASKS_TABLE. */ uint32_t number_of_initialization_tasks; @@ -164,37 +166,35 @@ typedef struct { * @brief This member contains the pointer to Classic API Initialization Tasks * Table of this application. * - * See #CONFIGURE_RTEMS_INIT_TASKS_TABLE. + * See @ref CONFIGURE_RTEMS_INIT_TASKS_TABLE. */ const rtems_initialization_tasks_table *User_initialization_tasks_table; } rtems_api_configuration_table; -/* Generated from spec:/rtems/config/if/get-api-configuration */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief Gets the Classic API Configuration Table of this application. - * - * @return Returns the pointer to the Classic API Configuration Table of this - * application. - */ -const rtems_api_configuration_table * -rtems_configuration_get_rtems_api_configuration( void ); - /* Generated from spec:/rtems/config/if/get-maximum-barriers */ /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Barriers configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicBarrier objects + * configured for this application. * - * @return Returns the maximum number of Classic API Barriers configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicBarrier objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_BARRIERS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_BARRIERS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_barriers( void ); @@ -203,14 +203,25 @@ uint32_t rtems_configuration_get_maximum_barriers( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Message Queues configured for - * this application. + * @brief Gets the resource number of @ref RTEMSAPIClassicMessage objects + * configured for this application. * - * @return Returns the maximum number of Classic API Message Queues configured - * for this application. + * @return Returns the resource number of @ref RTEMSAPIClassicMessage objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_message_queues( void ); @@ -219,14 +230,25 @@ uint32_t rtems_configuration_get_maximum_message_queues( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Partitions configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicPart objects + * configured for this application. * - * @return Returns the maximum number of Classic API Partitions configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicPart objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PARTITIONS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PARTITIONS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_partitions( void ); @@ -235,14 +257,25 @@ uint32_t rtems_configuration_get_maximum_partitions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Rate Monotonic Periods + * @brief Gets the resource number of @ref RTEMSAPIClassicRatemon objects * configured for this application. * - * @return Returns the maximum number of Classic API Rate Monotonic Periods + * @return Returns the resource number of @ref RTEMSAPIClassicRatemon objects * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PERIODS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PERIODS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_periods( void ); @@ -251,14 +284,25 @@ uint32_t rtems_configuration_get_maximum_periods( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Dual-Ported Memories + * @brief Gets the resource number of @ref RTEMSAPIClassicDPMem objects * configured for this application. * - * @return Returns the maximum number of Classic API Dual-Ported Memories + * @return Returns the resource number of @ref RTEMSAPIClassicDPMem objects * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PORTS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PORTS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_ports( void ); @@ -267,14 +311,25 @@ uint32_t rtems_configuration_get_maximum_ports( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Regions configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicRegion objects + * configured for this application. * - * @return Returns the maximum number of Classic API Regions configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicRegion objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_REGIONS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_REGIONS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_regions( void ); @@ -283,14 +338,25 @@ uint32_t rtems_configuration_get_maximum_regions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Semaphores configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicSem objects + * configured for this application. * - * @return Returns the maximum number of Classic API Semaphores configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicSem objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_SEMAPHORES. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_SEMAPHORES + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_semaphores( void ); @@ -299,14 +365,25 @@ uint32_t rtems_configuration_get_maximum_semaphores( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Tasks configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicTasks objects + * configured for this application. * - * @return Returns the maximum number of Classic API Tasks configured for this - * application. + * @return Returns the resource number of @ref RTEMSAPIClassicTasks objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_TASKS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_TASKS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_tasks( void ); @@ -315,17 +392,50 @@ uint32_t rtems_configuration_get_maximum_tasks( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Timers configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicTimer objects + * configured for this application. * - * @return Returns the maximum number of Classic API Timers configured for this - * application. + * @return Returns the resource number of @ref RTEMSAPIClassicTimer objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_TIMERS. + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_TIMERS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ uint32_t rtems_configuration_get_maximum_timers( void ); +/* Generated from spec:/rtems/config/if/get-api-configuration */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Gets the Classic API Configuration Table of this application. + * + * @return Returns a pointer to the Classic API Configuration Table of this + * application. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +const rtems_api_configuration_table * +rtems_configuration_get_rtems_api_configuration( void ); + #ifdef __cplusplus } #endif diff --git a/cpukit/include/rtems/rtems/dpmem.h b/cpukit/include/rtems/rtems/dpmem.h index 9ecdf3a170..62e34053ea 100644 --- a/cpukit/include/rtems/rtems/dpmem.h +++ b/cpukit/include/rtems/rtems/dpmem.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassicDPMem + * * @brief This header file defines the Dual-Ported Memory Manager API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -112,7 +114,7 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * port. The number of port available to the application is configured - * through the #CONFIGURE_MAXIMUM_PORTS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_PORTS application configuration option. * * @par Notes * @parblock @@ -136,7 +138,7 @@ extern "C" { * cause the calling task to be preempted. * * * The number of ports available to the application is configured through the - * #CONFIGURE_MAXIMUM_PORTS application configuration option. + * @ref CONFIGURE_MAXIMUM_PORTS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/dpmemdata.h b/cpukit/include/rtems/rtems/dpmemdata.h index 5303b8623a..11c80f2dff 100644 --- a/cpukit/include/rtems/rtems/dpmemdata.h +++ b/cpukit/include/rtems/rtems/dpmemdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_DPMEMDATA_H diff --git a/cpukit/include/rtems/rtems/dpmemimpl.h b/cpukit/include/rtems/rtems/dpmemimpl.h index a399eccd94..04462335b8 100644 --- a/cpukit/include/rtems/rtems/dpmemimpl.h +++ b/cpukit/include/rtems/rtems/dpmemimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_DPMEM_INL @@ -42,7 +61,7 @@ extern "C" { * This routine allocates a port control block from the inactive chain * of free port control blocks. */ -RTEMS_INLINE_ROUTINE Dual_ported_memory_Control +static inline Dual_ported_memory_Control *_Dual_ported_memory_Allocate ( void ) { return (Dual_ported_memory_Control *) @@ -56,14 +75,14 @@ RTEMS_INLINE_ROUTINE Dual_ported_memory_Control * This routine frees a port control block to the inactive chain * of free port control blocks. */ -RTEMS_INLINE_ROUTINE void _Dual_ported_memory_Free ( +static inline void _Dual_ported_memory_Free ( Dual_ported_memory_Control *the_port ) { _Objects_Free( &_Dual_ported_memory_Information, &the_port->Object ); } -RTEMS_INLINE_ROUTINE Dual_ported_memory_Control *_Dual_ported_memory_Get( +static inline Dual_ported_memory_Control *_Dual_ported_memory_Get( Objects_Id id, ISR_lock_Context *lock_context ) diff --git a/cpukit/include/rtems/rtems/event.h b/cpukit/include/rtems/rtems/event.h index 8d4424e628..81aa57585f 100644 --- a/cpukit/include/rtems/rtems/event.h +++ b/cpukit/include/rtems/rtems/event.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/eventdata.h b/cpukit/include/rtems/rtems/eventdata.h index 7078cc2248..db60056da3 100644 --- a/cpukit/include/rtems/rtems/eventdata.h +++ b/cpukit/include/rtems/rtems/eventdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_EVENTDATA_H diff --git a/cpukit/include/rtems/rtems/eventimpl.h b/cpukit/include/rtems/rtems/eventimpl.h index bd90554455..9c0380930a 100644 --- a/cpukit/include/rtems/rtems/eventimpl.h +++ b/cpukit/include/rtems/rtems/eventimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_EVENTIMPL_H @@ -104,7 +123,7 @@ rtems_status_code _Event_Surrender( * * @param event is the event control block to initialize. */ -RTEMS_INLINE_ROUTINE void _Event_Initialize( Event_Control *event ) +static inline void _Event_Initialize( Event_Control *event ) { event->pending_events = 0; } @@ -117,7 +136,7 @@ RTEMS_INLINE_ROUTINE void _Event_Initialize( Event_Control *event ) * @return Returns true, if there are no posted events in the event set, * otherwise false. */ -RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty( +static inline bool _Event_sets_Is_empty( rtems_event_set the_event_set ) { @@ -131,7 +150,7 @@ RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty( * * @param the_event_set[in, out] is the event set. */ -RTEMS_INLINE_ROUTINE void _Event_sets_Post( +static inline void _Event_sets_Post( rtems_event_set the_new_events, rtems_event_set *the_event_set ) @@ -149,7 +168,7 @@ RTEMS_INLINE_ROUTINE void _Event_sets_Post( * @return Return the events of the event condition which are posted in the * event set. */ -RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get( +static inline rtems_event_set _Event_sets_Get( rtems_event_set the_event_set, rtems_event_set the_event_condition ) @@ -167,7 +186,7 @@ RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get( * @return Returns the event set with all event cleared specified by the event * mask. */ -RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Clear( +static inline rtems_event_set _Event_sets_Clear( rtems_event_set the_event_set, rtems_event_set the_mask ) diff --git a/cpukit/include/rtems/rtems/eventmp.h b/cpukit/include/rtems/rtems/eventmp.h index e8c77cac24..c614d4b14f 100644 --- a/cpukit/include/rtems/rtems/eventmp.h +++ b/cpukit/include/rtems/rtems/eventmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_EVENTMP_H diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h index 7663541adc..f682112bf5 100644 --- a/cpukit/include/rtems/rtems/intr.h +++ b/cpukit/include/rtems/rtems/intr.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file defines the Interrupt Manager API. */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -54,10 +56,18 @@ #ifndef _RTEMS_RTEMS_INTR_H #define _RTEMS_RTEMS_INTR_H +#include <stddef.h> #include <stdint.h> +#include <sys/cpuset.h> +#include <rtems/rtems/attr.h> +#include <rtems/rtems/modes.h> +#include <rtems/rtems/options.h> #include <rtems/rtems/status.h> +#include <rtems/rtems/types.h> #include <rtems/score/basedefs.h> +#include <rtems/score/chain.h> #include <rtems/score/cpu.h> +#include <rtems/score/cpuopts.h> #include <rtems/score/isr.h> #include <rtems/score/isrlevel.h> #include <rtems/score/isrlock.h> @@ -82,31 +92,14 @@ extern "C" { * task to be preempted upon exit from an ISR. */ -/* Generated from spec:/rtems/intr/if/isr */ - -/** - * @ingroup RTEMSAPIClassicIntr - * - * @brief This type defines the return type of interrupt service routines. - * - * This type can be used to document interrupt service routines in the source - * code. - */ -typedef ISR_Handler rtems_isr; - -/* Generated from spec:/rtems/intr/if/isr-entry */ +/* Generated from spec:/rtems/intr/if/vector-number */ /** * @ingroup RTEMSAPIClassicIntr * - * @brief Interrupt service routines installed by rtems_interrupt_catch() shall - * have this type. + * @brief This integer type represents interrupt vector numbers. */ -#if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE - typedef ISR_Handler_entry rtems_isr_entry; -#else - typedef void ( *rtems_isr_entry )( void * ); -#endif +typedef ISR_Vector_number rtems_vector_number; /* Generated from spec:/rtems/intr/if/level */ @@ -117,33 +110,31 @@ typedef ISR_Handler rtems_isr; */ typedef ISR_Level rtems_interrupt_level; -/* Generated from spec:/rtems/intr/if/lock */ +/* Generated from spec:/rtems/intr/if/isr */ /** * @ingroup RTEMSAPIClassicIntr * - * @brief This structure represents an ISR lock. - */ -typedef ISR_lock_Control rtems_interrupt_lock; - -/* Generated from spec:/rtems/intr/if/lock-context */ - -/** - * @ingroup RTEMSAPIClassicIntr + * @brief This type defines the return type of interrupt service routines. * - * @brief This structure provides an ISR lock context for acquire and release - * pairs. + * This type can be used to document interrupt service routines in the source + * code. */ -typedef ISR_lock_Context rtems_interrupt_lock_context; +typedef ISR_Handler rtems_isr; -/* Generated from spec:/rtems/intr/if/vector-number */ +/* Generated from spec:/rtems/intr/if/isr-entry */ /** * @ingroup RTEMSAPIClassicIntr * - * @brief This integer type represents interrupt vector numbers. + * @brief Interrupt service routines installed by rtems_interrupt_catch() shall + * have this type. */ -typedef ISR_Vector_number rtems_vector_number; +#if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE + typedef ISR_Handler_entry rtems_isr_entry; +#else + typedef void ( *rtems_isr_entry )( void * ); +#endif /* Generated from spec:/rtems/intr/if/catch */ @@ -503,6 +494,25 @@ rtems_status_code rtems_interrupt_catch( */ #define rtems_interrupt_is_in_progress() _ISR_Is_in_progress() +/* Generated from spec:/rtems/intr/if/lock */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an ISR lock. + */ +typedef ISR_lock_Control rtems_interrupt_lock; + +/* Generated from spec:/rtems/intr/if/lock-context */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure provides an ISR lock context for acquire and release + * pairs. + */ +typedef ISR_lock_Context rtems_interrupt_lock_context; + /* Generated from spec:/rtems/intr/if/lock-initialize */ /** @@ -874,6 +884,687 @@ rtems_status_code rtems_interrupt_catch( #define RTEMS_INTERRUPT_LOCK_REFERENCE( _designator, _target ) \ ISR_LOCK_REFERENCE( _designator, _target ) +/* Generated from spec:/rtems/intr/if/shared */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This interrupt handler install option allows that the interrupt + * handler may share the interrupt vector with other handler. + */ +#define RTEMS_INTERRUPT_SHARED ( (rtems_option) 0x00000000 ) + +/* Generated from spec:/rtems/intr/if/unique */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This interrupt handler install option ensures that the interrupt + * handler is unique. + * + * This option prevents other handler from using the same interrupt vector. + */ +#define RTEMS_INTERRUPT_UNIQUE ( (rtems_option) 0x00000001 ) + +/* Generated from spec:/rtems/intr/if/replace */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This interrupt handler install option requests that the interrupt + * handler replaces the first handler with the same argument. + */ +#define RTEMS_INTERRUPT_REPLACE ( (rtems_option) 0x00000002 ) + +/* Generated from spec:/rtems/intr/if/is-shared */ + +/** + * @brief Checks if the interrupt handler shared option is set. + * + * @param _options is the interrupt handler option set to check. + * + * @return Returns true, if the interrupt handler shared option + * #RTEMS_INTERRUPT_SHARED is set, otherwise false. + */ +#define RTEMS_INTERRUPT_IS_SHARED( _options ) \ + ( ( _options ) & RTEMS_INTERRUPT_SHARED ) + +/* Generated from spec:/rtems/intr/if/is-unique */ + +/** + * @brief Checks if the interrupt handler unique option is set. + * + * @param _options is the interrupt handler option set to check. + * + * @return Returns true, if the interrupt handler unique option + * #RTEMS_INTERRUPT_UNIQUE is set, otherwise false. + */ +#define RTEMS_INTERRUPT_IS_UNIQUE( _options ) \ + ( ( _options ) & RTEMS_INTERRUPT_UNIQUE ) + +/* Generated from spec:/rtems/intr/if/is-replace */ + +/** + * @brief Checks if the interrupt handler replace option is set. + * + * @param _options is the interrupt handler option set to check. + * + * @return Returns true, if the interrupt handler replace option + * #RTEMS_INTERRUPT_REPLACE is set, otherwise false. + */ +#define RTEMS_INTERRUPT_IS_REPLACE( _options ) \ + ( ( _options ) & RTEMS_INTERRUPT_REPLACE ) + +/* Generated from spec:/rtems/intr/if/handler */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Interrupt handler routines shall have this type. + */ +typedef void ( *rtems_interrupt_handler )( void * ); + +/* Generated from spec:/rtems/intr/if/per-handler-routine */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Visitor routines invoked by rtems_interrupt_handler_iterate() shall + * have this type. + */ +typedef void ( *rtems_interrupt_per_handler_routine )( + void *, + const char *, + rtems_option, + rtems_interrupt_handler, + void * +); + +/* Generated from spec:/rtems/intr/if/entry */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an interrupt entry. + * + * @par Notes + * This structure shall be treated as an opaque data type from the API point of + * view. Members shall not be accessed directly. An entry may be initialized + * by RTEMS_INTERRUPT_ENTRY_INITIALIZER() or + * rtems_interrupt_entry_initialize(). It may be installed for an interrupt + * vector with rtems_interrupt_entry_install() and removed from an interrupt + * vector by rtems_interrupt_entry_remove(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct rtems_interrupt_entry { + /** + * @brief This member is the interrupt handler routine. + */ + rtems_interrupt_handler handler; + + /** + * @brief This member is the interrupt handler argument. + */ + void *arg; + + /** + * @brief This member is the reference to the next entry or NULL. + */ + struct rtems_interrupt_entry *next; + + /** + * @brief This member is the descriptive information of the entry. + */ + const char *info; +} rtems_interrupt_entry; + +/* Generated from spec:/rtems/intr/if/entry-initializer */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Statically initializes an interrupt entry object. + * + * @param _routine is the interrupt handler routine for the entry. + * + * @param _arg is the interrupt handler argument for the entry. + * + * @param _info is the descriptive information for the entry. + * + * @par Notes + * Alternatively, rtems_interrupt_entry_initialize() may be used to dynamically + * initialize an interrupt entry. + */ +#define RTEMS_INTERRUPT_ENTRY_INITIALIZER( _routine, _arg, _info ) \ + { _routine, _arg, NULL, _info } + +/* Generated from spec:/rtems/intr/if/entry-initialize */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Initializes the interrupt entry. + * + * @param[out] entry is the interrupt entry to initialize. + * + * @param routine is the interrupt handler routine for the entry. + * + * @param arg is the interrupt handler argument for the entry. + * + * @param info is the descriptive information for the entry. + * + * @par Notes + * Alternatively, RTEMS_INTERRUPT_ENTRY_INITIALIZER() may be used to statically + * initialize an interrupt entry. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +static inline void rtems_interrupt_entry_initialize( + rtems_interrupt_entry *entry, + rtems_interrupt_handler routine, + void *arg, + const char *info +) +{ + entry->handler = routine; + entry->arg = arg; + entry->next = NULL; + entry->info = info; +} + +/* Generated from spec:/rtems/intr/if/entry-install */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Installs the interrupt entry at the interrupt vector. + * + * @param vector is the interrupt vector number. + * + * @param options is the interrupt entry install option set. + * + * @param entry is the interrupt entry to install. + * + * One of the following mutually exclusive options + * + * * #RTEMS_INTERRUPT_UNIQUE, and + * + * * #RTEMS_INTERRUPT_SHARED + * + * shall be set in the ``options`` parameter. + * + * The handler routine of the entry specified by ``entry`` will be called with + * the handler argument of the entry when dispatched. The order in which + * shared interrupt handlers are dispatched for one vector is defined by the + * installation order. The first installed handler is dispatched first. + * + * If the option #RTEMS_INTERRUPT_UNIQUE is set, then it will be ensured that + * the handler will be the only one for the interrupt vector. + * + * If the option #RTEMS_INTERRUPT_SHARED is set, then multiple handlers may be + * installed for the interrupt vector. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``entry`` parameter was NULL. + * + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized. + * + * @retval ::RTEMS_INVALID_ADDRESS The handler routine of the entry was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @retval ::RTEMS_INVALID_NUMBER An option specified by ``options`` was not + * applicable. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set + * in ``entry`` and the interrupt vector was already occupied by a handler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set + * in ``entry`` and the interrupt vector was already occupied by a unique + * handler. + * + * @retval ::RTEMS_TOO_MANY The handler routine of the entry specified by + * ``entry`` was already installed for the interrupt vector specified by + * ``vector`` with an argument equal to the handler argument of the entry. + * + * @par Notes + * When the directive call was successful, the ownership of the interrupt entry + * has been transferred from the caller to the interrupt service. An installed + * interrupt entry may be removed from the interrupt service by calling + * rtems_interrupt_entry_remove(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The interrupt entry shall have been initialized by + * rtems_interrupt_entry_initialize() or RTEMS_INTERRUPT_ENTRY_INITIALIZER(). + * @endparblock + */ +rtems_status_code rtems_interrupt_entry_install( + rtems_vector_number vector, + rtems_option options, + rtems_interrupt_entry *entry +); + +/* Generated from spec:/rtems/intr/if/entry-remove */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Removes the interrupt entry from the interrupt vector. + * + * @param vector is the interrupt vector number. + * + * @param entry is the interrupt entry to remove. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``entry`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @retval ::RTEMS_UNSATISFIED The entry specified by ``entry`` was not + * installed at the interrupt vector specified by ``vector``. + * + * @par Notes + * When the directive call was successful, the ownership of the interrupt entry + * has been transferred from the interrupt service to the caller. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The interrupt entry shall have been installed by + * rtems_interrupt_entry_install(). + * @endparblock + */ +rtems_status_code rtems_interrupt_entry_remove( + rtems_vector_number vector, + rtems_interrupt_entry *entry +); + +/* Generated from spec:/rtems/intr/if/handler-install */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Installs the interrupt handler routine and argument at the interrupt + * vector. + * + * @param vector is the interrupt vector number. + * + * @param info is the descriptive information of the interrupt handler to + * install. + * + * @param options is the interrupt handler install option set. + * + * @param routine is the interrupt handler routine to install. + * + * @param arg is the interrupt handler argument to install. + * + * One of the following mutually exclusive options + * + * * #RTEMS_INTERRUPT_UNIQUE, + * + * * #RTEMS_INTERRUPT_SHARED, and + * + * * #RTEMS_INTERRUPT_REPLACE + * + * shall be set in the ``options`` parameter. + * + * The handler routine will be called with the argument specified by ``arg`` + * when dispatched. The order in which shared interrupt handlers are + * dispatched for one vector is defined by the installation order. The first + * installed handler is dispatched first. + * + * If the option #RTEMS_INTERRUPT_UNIQUE is set, then it will be ensured that + * the handler will be the only one for the interrupt vector. + * + * If the option #RTEMS_INTERRUPT_SHARED is set, then multiple handler may be + * installed for the interrupt vector. + * + * If the option #RTEMS_INTERRUPT_REPLACE is set, then the handler specified by + * ``routine`` will replace the first handler with the same argument for the + * interrupt vector if it exists, otherwise an error status will be returned. + * A second handler with the same argument for the interrupt vector will remain + * unchanged. The new handler will inherit the unique or shared options from + * the replaced handler. + * + * An informative description may be provided in ``info``. It may be used for + * system debugging and diagnostic tools. The referenced string has to be + * persistent as long as the handler is installed. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @retval ::RTEMS_NO_MEMORY There was not enough memory available to allocate + * data structures to install the handler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set + * in ``options`` and the interrupt vector was already occupied by a handler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set + * in ``options`` and the interrupt vector was already occupied by a unique + * handler. + * + * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already + * installed for the interrupt vector specified by ``vector`` with an + * argument equal to the argument specified by ``arg``. + * + * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in + * ``options`` and no handler to replace was installed. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_handler_install( + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/handler-remove */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Removes the interrupt handler routine and argument from the interrupt + * vector. + * + * @param vector is the interrupt vector number. + * + * @param routine is the interrupt handler routine to remove. + * + * @param arg is the interrupt handler argument to remove. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair + * installed specified by ``routine`` and ``arg``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_handler_remove( + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/vector-is-enabled */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Checks if the interrupt vector is enabled. + * + * @param vector is the interrupt vector number. + * + * @param[out] enabled is the pointer to a ``bool`` object. When the directive + * call is successful, the enabled status of the interrupt associated with + * the interrupt vector specified by ``vector`` will be stored in this + * object. When the interrupt was enabled for the processor executing the + * directive call at some time point during the call, the object value will + * be set to true, otherwise to false. + * + * The directive checks if the interrupt associated with the interrupt vector + * specified by ``vector`` was enabled for the processor executing the + * directive call at some time point during the call. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``enabled`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @par Notes + * Interrupt vectors may be enabled by rtems_interrupt_vector_enable() and + * disabled by rtems_interrupt_vector_disable(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_vector_is_enabled( + rtems_vector_number vector, + bool *enabled +); + +/* Generated from spec:/rtems/intr/if/vector-enable */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Enables the interrupt vector. + * + * @param vector is the number of the interrupt vector to enable. + * + * The directive enables the interrupt vector specified by ``vector``. This + * allows that interrupt service requests are issued to the target processors + * of the interrupt vector. Interrupt service requests for an interrupt vector + * may be raised by rtems_interrupt_raise(), rtems_interrupt_raise_on(), + * external signals, or messages. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_UNSATISFIED The request to enable the interrupt vector has + * not been satisfied. + * + * @par Notes + * The rtems_interrupt_get_attributes() directive may be used to check if an + * interrupt vector can be enabled. Interrupt vectors may be disabled by + * rtems_interrupt_vector_disable(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_vector_enable( rtems_vector_number vector ); + +/* Generated from spec:/rtems/intr/if/vector-disable */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Disables the interrupt vector. + * + * @param vector is the number of the interrupt vector to disable. + * + * The directive disables the interrupt vector specified by ``vector``. This + * prevents that an interrupt service request is issued to the target + * processors of the interrupt vector. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_UNSATISFIED The request to disable the interrupt vector has + * not been satisfied. + * + * @par Notes + * The rtems_interrupt_get_attributes() directive may be used to check if an + * interrupt vector can be disabled. Interrupt vectors may be enabled by + * rtems_interrupt_vector_enable(). There may be targets on which some + * interrupt vectors cannot be disabled, for example a hardware watchdog + * interrupt or software generated interrupts. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_vector_disable( rtems_vector_number vector ); + +/* Generated from spec:/rtems/intr/if/is-pending */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Checks if the interrupt is pending. + * + * @param vector is the interrupt vector number. + * + * @param[out] pending is the pointer to a ``bool`` object. When the directive + * call is successful, the pending status of the interrupt associated with + * the interrupt vector specified by ``vector`` will be stored in this + * object. When the interrupt was pending for the processor executing the + * directive call at some time point during the call, the object value will + * be set to true, otherwise to false. + * + * The directive checks if the interrupt associated with the interrupt vector + * specified by ``vector`` was pending for the processor executing the + * directive call at some time point during the call. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``pending`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_UNSATISFIED The request to get the pending status has not + * been satisfied. + * + * @par Notes + * Interrupts may be made pending by calling the rtems_interrupt_raise() or + * rtems_interrupt_raise_on() directives or due to external signals or + * messages. The pending state may be cleared by rtems_interrupt_clear(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_is_pending( + rtems_vector_number vector, + bool *pending +); + /* Generated from spec:/rtems/intr/if/raise */ /** @@ -997,6 +1688,1618 @@ rtems_status_code rtems_interrupt_raise_on( */ rtems_status_code rtems_interrupt_clear( rtems_vector_number vector ); +/* Generated from spec:/rtems/intr/if/get-affinity */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Gets the processor affinity set of the interrupt vector. + * + * @param vector is the interrupt vector number. + * + * @param affinity_size is the size of the processor set referenced by + * ``affinity`` in bytes. + * + * @param[out] affinity is the pointer to a cpu_set_t object. When the + * directive call is successful, the processor affinity set of the interrupt + * vector will be stored in this object. A set bit in the processor set + * means that the corresponding processor is in the processor affinity set of + * the interrupt vector, otherwise the bit is cleared. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_INVALID_SIZE The size specified by ``affinity_size`` of the + * processor set was too small for the processor affinity set of the + * interrupt vector. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_get_affinity( + rtems_vector_number vector, + size_t affinity_size, + cpu_set_t *affinity +); + +/* Generated from spec:/rtems/intr/if/set-affinity */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Sets the processor affinity set of the interrupt vector. + * + * @param vector is the interrupt vector number. + * + * @param affinity_size is the size of the processor set referenced by + * ``affinity`` in bytes. + * + * @param affinity is the pointer to a cpu_set_t object. The processor set + * defines the new processor affinity set of the interrupt vector. A set bit + * in the processor set means that the corresponding processor shall be in + * the processor affinity set of the interrupt vector, otherwise the bit + * shall be cleared. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid + * new processor affinity set for the interrupt vector. + * + * @retval ::RTEMS_UNSATISFIED The request to set the processor affinity of the + * interrupt vector has not been satisfied. + * + * @par Notes + * @parblock + * The rtems_interrupt_get_attributes() directive may be used to check if the + * processor affinity of an interrupt vector can be set. + * + * Only online processors of the affinity set specified by ``affinity_size`` + * and ``affinity`` are considered by the directive. Other processors of the + * set are ignored. If the set contains no online processor, then the set is + * invalid and an error status is returned. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_set_affinity( + rtems_vector_number vector, + size_t affinity_size, + const cpu_set_t *affinity +); + +/* Generated from spec:/rtems/intr/if/signal-variant */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This enumeration provides interrupt trigger signal variants. + */ +typedef enum { + /** + * @brief This interrupt signal variant indicates that the interrupt trigger + * signal is unspecified. + */ + RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL, + + /** + * @brief This interrupt signal variant indicates that the interrupt cannot be + * triggered by a signal. + */ + RTEMS_INTERRUPT_NO_SIGNAL, + + /** + * @brief This interrupt signal variant indicates that the interrupt is + * triggered by a low level signal. + */ + RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW, + + /** + * @brief This interrupt signal variant indicates that the interrupt is + * triggered by a high level signal. + */ + RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH, + + /** + * @brief This interrupt signal variant indicates that the interrupt is + * triggered by a falling edge signal. + */ + RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING, + + /** + * @brief This interrupt signal variant indicates that the interrupt is + * triggered by a raising edge signal. + */ + RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING +} rtems_interrupt_signal_variant; + +/* Generated from spec:/rtems/intr/if/attributes */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure provides the attributes of an interrupt vector. + * + * The rtems_interrupt_get_attributes() directive may be used to obtain the + * attributes of an interrupt vector. + */ +typedef struct { + /** + * @brief This member is true, if the interrupt vector is maskable by + * rtems_interrupt_local_disable(), otherwise it is false. + * + * Interrupt vectors which are not maskable by rtems_interrupt_local_disable() + * should be used with care since they cannot use most operating system + * services. + */ + bool is_maskable; + + /** + * @brief This member is true, if the interrupt vector can be enabled by + * rtems_interrupt_vector_enable(), otherwise it is false. + * + * When an interrupt vector can be enabled, this means that the enabled state + * can always be changed from disabled to enabled. For an interrupt vector + * which can be enabled it follows that it may be enabled. + */ + bool can_enable; + + /** + * @brief This member is true, if the interrupt vector may be enabled by + * rtems_interrupt_vector_enable(), otherwise it is false. + * + * When an interrupt vector may be enabled, this means that the enabled state + * may be changed from disabled to enabled. The requested enabled state change + * should be checked by rtems_interrupt_vector_is_enabled(). Some interrupt + * vectors may be optionally available and cannot be enabled on a particular + * target. + */ + bool maybe_enable; + + /** + * @brief This member is true, if the interrupt vector can be disabled by + * rtems_interrupt_vector_disable(), otherwise it is false. + * + * When an interrupt vector can be disabled, this means that the enabled state + * can be changed from enabled to disabled. For an interrupt vector which can + * be disabled it follows that it may be disabled. + */ + bool can_disable; + + /** + * @brief This member is true, if the interrupt vector may be disabled by + * rtems_interrupt_vector_disable(), otherwise it is false. + * + * When an interrupt vector may be disabled, this means that the enabled state + * may be changed from enabled to disabled. The requested enabled state change + * should be checked by rtems_interrupt_vector_is_enabled(). Some interrupt + * vectors may be always enabled and cannot be disabled on a particular target. + */ + bool maybe_disable; + + /** + * @brief This member is true, if the interrupt vector can be raised by + * rtems_interrupt_raise(), otherwise it is false. + */ + bool can_raise; + + /** + * @brief This member is true, if the interrupt vector can be raised on a + * processor by rtems_interrupt_raise_on(), otherwise it is false. + */ + bool can_raise_on; + + /** + * @brief This member is true, if the interrupt vector can be cleared by + * rtems_interrupt_clear(), otherwise it is false. + */ + bool can_clear; + + /** + * @brief This member is true, if the pending status of the interrupt + * associated with the interrupt vector is cleared by an interrupt + * acknowledge from the processor, otherwise it is false. + */ + bool cleared_by_acknowledge; + + /** + * @brief This member is true, if the affinity set of the interrupt vector can + * be obtained by rtems_interrupt_get_affinity(), otherwise it is false. + */ + bool can_get_affinity; + + /** + * @brief This member is true, if the affinity set of the interrupt vector can + * be set by rtems_interrupt_set_affinity(), otherwise it is false. + */ + bool can_set_affinity; + + /** + * @brief This member is true, if the interrupt associated with the interrupt + * vector can be triggered by a message. + * + * Interrupts may be also triggered by signals, rtems_interrupt_raise(), or + * rtems_interrupt_raise_on(). Examples for message triggered interrupts are + * the PCIe MSI/MSI-X and the ARM GICv3 Locality-specific Peripheral Interrupts + * (LPI). + */ + bool can_be_triggered_by_message; + + /** + * @brief This member describes the trigger signal of the interrupt associated + * with the interrupt vector. + * + * Interrupts are normally triggered by signals which indicate an interrupt + * request from a peripheral. Interrupts may be also triggered by messages, + * rtems_interrupt_raise(), or rtems_interrupt_raise_on(). + */ + rtems_interrupt_signal_variant trigger_signal; +} rtems_interrupt_attributes; + +/* Generated from spec:/rtems/intr/if/get-attributes */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Gets the attributes of the interrupt vector. + * + * @param vector is the interrupt vector number. + * + * @param[out] attributes is the pointer to an rtems_interrupt_attributes + * object. When the directive call is successful, the attributes of the + * interrupt vector will be stored in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``attributes`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_get_attributes( + rtems_vector_number vector, + rtems_interrupt_attributes *attributes +); + +/* Generated from spec:/rtems/intr/if/handler-iterate */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Iterates over all interrupt handler installed at the interrupt + * vector. + * + * @param vector is the interrupt vector number. + * + * @param routine is the visitor routine. + * + * @param arg is the visitor argument. + * + * For each installed handler at the interrupt vector the visitor function + * specified by ``routine`` will be called with the argument specified by + * ``arg`` and the handler information, options, routine and argument. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @par Notes + * @parblock + * The directive is intended for system information and diagnostics. + * + * Never install or remove an interrupt handler within the visitor function. + * This may result in a deadlock. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_handler_iterate( + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-default */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief The constant represents the index of the default interrupt server. + */ +#define RTEMS_INTERRUPT_SERVER_DEFAULT 0 + +/* Generated from spec:/rtems/intr/if/server-control */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an interrupt server. + * + * @par Notes + * This structure shall be treated as an opaque data type from the API point of + * view. Members shall not be accessed directly. The structure is initialized + * by rtems_interrupt_server_create() and maintained by the interrupt server + * support. + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct rtems_interrupt_server_control { + #if defined(RTEMS_SMP) + /** + * @brief This member is the ISR lock protecting the server control state. + */ + rtems_interrupt_lock lock; + #endif + + /** + * @brief This member is the chain of pending interrupt entries. + */ + Chain_Control entries; + + /** + * @brief This member is the identifier of the server task. + */ + rtems_id server; + + /** + * @brief This member is the error count. + */ + unsigned long errors; + + /** + * @brief This member is the server index. + */ + uint32_t index; + + /** + * @brief This member is the node for the interrupt server registry. + */ + Chain_Node node; + + /** + * @brief This member is the optional handler to destroy the interrupt server + * control. + */ + void ( *destroy )( struct rtems_interrupt_server_control * ); +} rtems_interrupt_server_control; + +/* Generated from spec:/rtems/intr/if/server-config */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure defines an interrupt server configuration. + * + * @par Notes + * See also rtems_interrupt_server_create(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct { + /** + * @brief This member is the task name of the interrupt server. + */ + rtems_name name; + + /** + * @brief This member is the initial task priority of the interrupt server. + */ + rtems_task_priority priority; + + /** + * @brief This member is the task storage area of the interrupt server. + * + * It shall be NULL for interrupt servers created by + * rtems_interrupt_server_create(). + */ + void *storage_area; + + /** + * @brief This member is the task storage size of the interrupt server. + * + * For interrupt servers created by rtems_interrupt_server_create() this is the + * task stack size. + */ + size_t storage_size; + + /** + * @brief This member is the initial mode set of the interrupt server. + */ + rtems_mode modes; + + /** + * @brief This member is the attribute set of the interrupt server. + */ + rtems_attribute attributes; + + /** + * @brief This member is an optional handler to destroy the interrupt server + * control handed over to rtems_interrupt_server_create(). + * + * The destroy handler is optional and may be NULL. If the destroy handler is + * present, it is called from within the context of the interrupt server to be + * deleted, see also rtems_interrupt_server_delete(). + */ + void ( *destroy )( rtems_interrupt_server_control * ); +} rtems_interrupt_server_config; + +/* Generated from spec:/rtems/intr/if/server-initialize */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Initializes the interrupt server tasks. + * + * @param priority is the initial task priority of the created interrupt + * servers. + * + * @param stack_size is the task stack size of the created interrupt servers. + * + * @param modes is the initial mode set of the created interrupt servers. + * + * @param attributes is the attribute set of the created interrupt servers. + * + * @param[out] server_count is the pointer to an uint32_t object or NULL. When + * the pointer is not equal to NULL, the count of successfully created + * interrupt servers is stored in this object regardless of the return + * status. + * + * The directive tries to create an interrupt server task for each online + * processor in the system. The tasks will have the initial priority specified + * by ``priority``, the stack size specified by ``stack_size``, the initial + * mode set specified by ``modes``, and the attribute set specified by + * ``attributes``. The count of successfully created server tasks will be + * returned in ``server_count`` if the pointer is not equal to NULL. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The interrupt servers were already + * initialized. + * + * @return The directive uses rtems_task_create(). If this directive fails, + * then its error status will be returned. + * + * @par Notes + * @parblock + * Interrupt handlers may be installed on an interrupt server with + * rtems_interrupt_server_handler_install() and removed with + * rtems_interrupt_server_handler_remove() using a server index. In case of an + * interrupt, the request will be forwarded to the interrupt server. The + * handlers are executed within the interrupt server context. If one handler + * blocks on something this may delay the processing of other handlers. + * + * Interrupt servers may be deleted by rtems_interrupt_server_delete(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_initialize( + rtems_task_priority priority, + size_t stack_size, + rtems_mode modes, + rtems_attribute attributes, + uint32_t *server_count +); + +/* Generated from spec:/rtems/intr/if/server-create */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Creates an interrupt server. + * + * @param[out] control is the pointer to an rtems_interrupt_server_control + * object. When the directive call was successful, the ownership of the + * object was transferred from the caller of the directive to the interrupt + * server management. + * + * @param config is the interrupt server configuration. + * + * @param[out] server_index is the pointer to an uint32_t object. When the + * directive call was successful, the index of the created interrupt server + * will be stored in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @return The directive uses rtems_task_create(). If this directive fails, + * then its error status will be returned. + * + * @par Notes + * See also rtems_interrupt_server_initialize() and + * rtems_interrupt_server_delete(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_create( + rtems_interrupt_server_control *control, + const rtems_interrupt_server_config *config, + uint32_t *server_index +); + +/* Generated from spec:/rtems/intr/if/server-handler-install */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Installs the interrupt handler routine and argument at the interrupt + * vector on the interrupt server. + * + * @param server_index is the interrupt server index. The constant + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default + * interrupt server. + * + * @param vector is the interrupt vector number. + * + * @param info is the descriptive information of the interrupt handler to + * install. + * + * @param options is the interrupt handler install option set. + * + * @param routine is the interrupt handler routine to install. + * + * @param arg is the interrupt handler argument to install. + * + * The handler routine specified by ``routine`` will be executed within the + * context of the interrupt server task specified by ``server_index``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within + * interrupt context. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_INVALID_NUMBER An option specified by ``info`` was not + * applicable. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set + * in ``info`` and the interrupt vector was already occupied by a handler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set + * in ``info`` and the interrupt vector was already occupied by a unique + * handler. + * + * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already + * installed for the interrupt vector specified by ``vector`` with an + * argument equal to the argument specified by ``arg``. + * + * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in + * ``info`` and no handler to replace was installed. + * + * @par Notes + * See also rtems_interrupt_handler_install(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_handler_install( + uint32_t server_index, + rtems_vector_number vector, + const char *info, + rtems_option options, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-handler-remove */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Removes the interrupt handler routine and argument from the interrupt + * vector and the interrupt server. + * + * @param server_index is the interrupt server index. The constant + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default + * interrupt server. + * + * @param vector is the interrupt vector number. + * + * @param routine is the interrupt handler routine to remove. + * + * @param arg is the interrupt handler argument to remove. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair + * installed specified by ``routine`` and ``arg``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_handler_remove( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-set-affinity */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Sets the processor affinity of the interrupt server. + * + * @param server_index is the interrupt server index. The constant + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default + * interrupt server. + * + * @param affinity_size is the size of the processor set referenced by + * ``affinity`` in bytes. + * + * @param affinity is the pointer to a cpu_set_t object. The processor set + * defines the new processor affinity set of the interrupt server. A set bit + * in the processor set means that the corresponding processor shall be in + * the processor affinity set of the task, otherwise the bit shall be + * cleared. + * + * @param priority is the new real priority for the interrupt server. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @return The directive uses rtems_scheduler_ident_by_processor_set(), + * rtems_task_set_scheduler(), and rtems_task_set_affinity(). If one of + * these directive fails, then its error status will be returned. + * + * @par Notes + * @parblock + * The scheduler is set determined by the highest numbered processor in the + * affinity set specified by ``affinity``. + * + * This operation is only reliable in case the interrupt server was suspended + * via rtems_interrupt_server_suspend(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may change the processor affinity of a task. This may cause + * the calling task to be preempted. + * + * * The directive may change the priority of a task. This may cause the + * calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_set_affinity( + uint32_t server_index, + size_t affinity_size, + const cpu_set_t *affinity, + rtems_task_priority priority +); + +/* Generated from spec:/rtems/intr/if/server-delete */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Deletes the interrupt server. + * + * @param server_index is the index of the interrupt server to delete. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * server index specified by ``server_index``. + * + * @par Notes + * @parblock + * The interrupt server deletes itself, so after the return of the directive + * the interrupt server may be still in the termination process depending on + * the task priorities of the system. + * + * See also rtems_interrupt_server_create(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_delete( uint32_t server_index ); + +/* Generated from spec:/rtems/intr/if/server-suspend */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Suspends the interrupt server. + * + * @param server_index is the index of the interrupt server to suspend. The + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the + * default interrupt server. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @par Notes + * Interrupt server may be resumed by rtems_interrupt_server_resume(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_suspend( uint32_t server_index ); + +/* Generated from spec:/rtems/intr/if/server-resume */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Resumes the interrupt server. + * + * @param server_index is the index of the interrupt server to resume. The + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the + * default interrupt server. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @par Notes + * Interrupt server may be suspended by rtems_interrupt_server_suspend(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_resume( uint32_t server_index ); + +/* Generated from spec:/rtems/intr/if/server-move */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Moves the interrupt handlers installed at the interrupt vector and + * the source interrupt server to the destination interrupt server. + * + * @param source_server_index is the index of the source interrupt server. The + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the + * default interrupt server. + * + * @param vector is the interrupt vector number. + * + * @param destination_server_index is the index of the destination interrupt + * server. The constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to + * specify the default interrupt server. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``source_server_index``. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``destination_server_index``. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_move( + uint32_t source_server_index, + rtems_vector_number vector, + uint32_t destination_server_index +); + +/* Generated from spec:/rtems/intr/if/server-handler-iterate */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Iterates over all interrupt handler installed at the interrupt vector + * and interrupt server. + * + * @param server_index is the index of the interrupt server. + * + * @param vector is the interrupt vector number. + * + * @param routine is the visitor routine. + * + * @param arg is the visitor argument. + * + * For each installed handler at the interrupt vector and interrupt server the + * visitor function specified by ``vector`` will be called with the argument + * specified by ``routine`` and the handler information, options, routine and + * argument. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the + * number specified by ``vector``. + * + * @par Notes + * @parblock + * The directive is intended for system information and diagnostics. + * + * Never install or remove an interrupt handler within the visitor function. + * This may result in a deadlock. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_handler_iterate( + uint32_t server_index, + rtems_vector_number vector, + rtems_interrupt_per_handler_routine routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-action */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an interrupt server action. + * + * @par Notes + * This structure shall be treated as an opaque data type from the API point of + * view. Members shall not be accessed directly. + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct rtems_interrupt_server_action { + /** + * @brief This member is the reference to the next action or NULL. + */ + struct rtems_interrupt_server_action *next; + + /** + * @brief This member is the interrupt handler. + */ + rtems_interrupt_handler handler; + + /** + * @brief This member is the interrupt handler argument. + */ + void *arg; +} rtems_interrupt_server_action; + +/* Generated from spec:/rtems/intr/if/server-entry */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an interrupt server entry. + * + * @par Notes + * This structure shall be treated as an opaque data type from the API point of + * view. Members shall not be accessed directly. An entry is initialized by + * rtems_interrupt_server_entry_initialize() and destroyed by + * rtems_interrupt_server_entry_destroy(). Interrupt server actions can be + * prepended to the entry by rtems_interrupt_server_action_prepend(). The + * entry is submitted to be serviced by rtems_interrupt_server_entry_submit(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct { + /** + * @brief This member is the node for the interrupt entry processing. + */ + Chain_Node node; + + /** + * @brief This member references the interrupt server used to process the + * entry. + */ + rtems_interrupt_server_control *server; + + /** + * @brief This member is the interrupt vector number. + */ + rtems_vector_number vector; + + /** + * @brief This member is the interrupt server actions list head. + */ + rtems_interrupt_server_action *actions; +} rtems_interrupt_server_entry; + +/* Generated from spec:/rtems/intr/if/server-entry-initialize */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Initializes the interrupt server entry. + * + * @param server_index is the interrupt server index. The constant + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default + * interrupt server. + * + * @param entry is the interrupt server entry to initialize. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @par Notes + * After initialization, the list of actions of the interrupt server entry is + * empty. Actions may be prepended by rtems_interrupt_server_action_prepend(). + * Interrupt server entries may be moved to another interrupt vector with + * rtems_interrupt_server_entry_move(). Server entries may be submitted to get + * serviced by the interrupt server with rtems_interrupt_server_entry_submit(). + * Server entries may be destroyed by rtems_interrupt_server_entry_destroy(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_entry_initialize( + uint32_t server_index, + rtems_interrupt_server_entry *entry +); + +/* Generated from spec:/rtems/intr/if/server-action-prepend */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Prepends the interrupt server action to the list of actions of the + * interrupt server entry. + * + * @param[in,out] entry is the interrupt server entry to prepend the interrupt + * server action. It shall have been initialized via + * rtems_interrupt_server_entry_initialize(). + * + * @param[out] action is the interrupt server action to initialize and prepend + * to the list of actions of the entry. + * + * @param routine is the interrupt handler routine to set in the action. + * + * @param arg is the interrupt handler argument to set in the action. + * + * @par Notes + * No error checking is performed by the directive. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The interrupt server entry shall have been initialized by + * rtems_interrupt_server_entry_initialize() and further optional calls to + * rtems_interrupt_server_action_prepend(). + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_action_prepend() with the same interrupt server + * entry. Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_entry_move() with the same interrupt server entry. + * Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_entry_submit() with the same interrupt server + * entry. Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called while the interrupt server entry is + * pending on or serviced by its current interrupt server. Calling the + * directive under these conditions is undefined behaviour. + * @endparblock + */ +void rtems_interrupt_server_action_prepend( + rtems_interrupt_server_entry *entry, + rtems_interrupt_server_action *action, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-entry-destroy */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Destroys the interrupt server entry. + * + * @param[in,out] entry is the interrupt server entry to destroy. + * + * @par Notes + * No error checking is performed by the directive. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * + * * The interrupt server entry shall have been initialized by + * rtems_interrupt_server_entry_initialize() and further optional calls to + * rtems_interrupt_server_action_prepend(). + * @endparblock + */ +void rtems_interrupt_server_entry_destroy( + rtems_interrupt_server_entry *entry +); + +/* Generated from spec:/rtems/intr/if/server-entry-submit */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Submits the interrupt server entry to be serviced by the interrupt + * server. + * + * @param entry is the interrupt server entry to submit. + * + * The directive appends the entry to the pending entries of the interrupt + * server. The interrupt server is notified that a new entry is pending. Once + * the interrupt server is scheduled it services the actions of all pending + * entries. + * + * @par Notes + * @parblock + * This directive may be used to do a two-step interrupt processing. The first + * step is done from within interrupt context by a call to this directive. The + * second step is then done from within the context of the interrupt server. + * + * No error checking is performed by the directive. + * + * A submitted entry may be destroyed by + * rtems_interrupt_server_entry_destroy(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may unblock a task. This may cause the calling task to be + * preempted. + * + * * The interrupt server entry shall have been initialized by + * rtems_interrupt_server_entry_initialize() and further optional calls to + * rtems_interrupt_server_action_prepend(). + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_action_prepend() with the same interrupt server + * entry. Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_entry_move() with the same interrupt server entry. + * Calling the directive under this condition is undefined behaviour. + * @endparblock + */ +void rtems_interrupt_server_entry_submit( + rtems_interrupt_server_entry *entry +); + +/* Generated from spec:/rtems/intr/if/server-entry-move */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Moves the interrupt server entry to the interrupt server. + * + * @param entry is the interrupt server entry to move. + * + * @param server_index is the index of the destination interrupt server. The + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the + * default interrupt server. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The interrupt server entry shall have been initialized by + * rtems_interrupt_server_entry_initialize() and further optional calls to + * rtems_interrupt_server_action_prepend(). + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_action_prepend() with the same interrupt server + * entry. Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_entry_move() with the same interrupt server entry. + * Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_entry_submit() with the same interrupt server + * entry. Calling the directive under this condition is undefined behaviour. + * + * * The directive shall not be called while the interrupt server entry is + * pending on or serviced by its current interrupt server. Calling the + * directive under these conditions is undefined behaviour. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_entry_move( + rtems_interrupt_server_entry *entry, + uint32_t server_index +); + +/* Generated from spec:/rtems/intr/if/server-request */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief This structure represents an interrupt server request. + * + * @par Notes + * This structure shall be treated as an opaque data type from the API point of + * view. Members shall not be accessed directly. A request is initialized by + * rtems_interrupt_server_request_initialize() and destroyed by + * rtems_interrupt_server_request_destroy(). The interrupt vector of the + * request can be set by rtems_interrupt_server_request_set_vector(). The + * request is submitted to be serviced by + * rtems_interrupt_server_request_submit(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock + */ +typedef struct { + /** + * @brief This member is the interrupt server entry. + */ + rtems_interrupt_server_entry entry; + + /** + * @brief This member is the interrupt server action. + */ + rtems_interrupt_server_action action; +} rtems_interrupt_server_request; + +/* Generated from spec:/rtems/intr/if/server-request-initialize */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Initializes the interrupt server request. + * + * @param server_index is the interrupt server index. The constant + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default + * interrupt server. + * + * @param[out] request is the interrupt server request to initialize. + * + * @param routine is the interrupt handler routine for the request action. + * + * @param arg is the interrupt handler argument for the request action. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the + * index specified by ``server_index``. + * + * @par Notes + * An interrupt server requests consists of an interrupt server entry and + * exactly one interrupt server action. The interrupt vector of the request + * may be changed with rtems_interrupt_server_request_set_vector(). Interrupt + * server requests may be submitted to get serviced by the interrupt server + * with rtems_interrupt_server_request_submit(). Requests may be destroyed by + * rtems_interrupt_server_request_destroy(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_interrupt_server_request_initialize( + uint32_t server_index, + rtems_interrupt_server_request *request, + rtems_interrupt_handler routine, + void *arg +); + +/* Generated from spec:/rtems/intr/if/server-request-set-vector */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Sets the interrupt vector in the interrupt server request. + * + * @param[in,out] request is the interrupt server request to change. + * + * @param vector is the interrupt vector number to be used by the request. + * + * @par Notes + * @parblock + * By default, the interrupt vector of an interrupt server request is set to a + * special value which is outside the range of vectors supported by the + * interrupt controller hardware. + * + * Calls to rtems_interrupt_server_request_submit() will disable the interrupt + * vector of the request. After processing of the request by the interrupt + * server the interrupt vector will be enabled again. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The interrupt server request shall have been initialized by + * rtems_interrupt_server_request_initialize(). + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_request_set_vector() with the same interrupt server + * request. Calling the directive under this condition is undefined + * behaviour. + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_request_submit() with the same interrupt server + * request. Calling the directive under this condition is undefined + * behaviour. + * + * * The directive shall not be called while the interrupt server entry is + * pending on or serviced by its current interrupt server. Calling the + * directive under these conditions is undefined behaviour. + * @endparblock + */ +static inline void rtems_interrupt_server_request_set_vector( + rtems_interrupt_server_request *request, + rtems_vector_number vector +) +{ + request->entry.vector = vector; +} + +/* Generated from spec:/rtems/intr/if/server-request-destroy */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Destroys the interrupt server request. + * + * @param[in,out] request is the interrupt server request to destroy. + * + * @par Notes + * No error checking is performed by the directive. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive shall not be called from within the context of an interrupt + * server. Calling the directive from within the context of an interrupt + * server is undefined behaviour. + * + * * The directive sends a request to another task and waits for a response. + * This may cause the calling task to be blocked and unblocked. + * + * * The interrupt server request shall have been initialized by + * rtems_interrupt_server_request_initialize(). + * @endparblock + */ +static inline void rtems_interrupt_server_request_destroy( + rtems_interrupt_server_request *request +) +{ + rtems_interrupt_server_entry_destroy( &request->entry ); +} + +/* Generated from spec:/rtems/intr/if/server-request-submit */ + +/** + * @ingroup RTEMSAPIClassicIntr + * + * @brief Submits the interrupt server request to be serviced by the interrupt + * server. + * + * @param[in,out] request is the interrupt server request to submit. + * + * The directive appends the interrupt server entry of the request to the + * pending entries of the interrupt server. The interrupt server is notified + * that a new entry is pending. Once the interrupt server is scheduled it + * services the actions of all pending entries. + * + * @par Notes + * @parblock + * This directive may be used to do a two-step interrupt processing. The first + * step is done from within interrupt context by a call to this directive. The + * second step is then done from within the context of the interrupt server. + * + * No error checking is performed by the directive. + * + * A submitted request may be destroyed by + * rtems_interrupt_server_request_destroy(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may unblock a task. This may cause the calling task to be + * preempted. + * + * * The interrupt server request shall have been initialized by + * rtems_interrupt_server_request_initialize(). + * + * * The directive shall not be called concurrently with + * rtems_interrupt_server_request_set_vector() with the same interrupt server + * request. Calling the directive under this condition is undefined + * behaviour. + * @endparblock + */ +static inline void rtems_interrupt_server_request_submit( + rtems_interrupt_server_request *request +) +{ + rtems_interrupt_server_entry_submit( &request->entry ); +} + #ifdef __cplusplus } #endif diff --git a/cpukit/include/rtems/rtems/mainpage.h b/cpukit/include/rtems/rtems/mainpage.h deleted file mode 100644 index 05bae7fe70..0000000000 --- a/cpukit/include/rtems/rtems/mainpage.h +++ /dev/null @@ -1,929 +0,0 @@ -/** - * @file - * - * This file exists to provide a top level description of RTEMS for Doxygen. - */ - -/* - * COPYRIGHT (c) 1989-2014. - * On-Line Applications Research Corporation (OAR). - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. - */ - -/** - * @mainpage - * - * The RTEMS real-time operating systems is a layered system with each of the - * public APIs implemented in terms of a common foundation layer called the - * SuperCore. This is the Doxygen generated documentation for the RTEMS CPU - * Kit including the Classic API, POSIX API and SuperCore. - */ - -/** - * @page RTEMSPreface RTEMS History and Introduction - * - * In recent years, the cost required to develop a software product has - * increased significantly while the target hardware costs have decreased. Now - * a larger portion of money is expended in developing, using, and maintaining - * software. The trend in computing costs is the complete dominance of software - * over hardware costs. Because of this, it is necessary that formal - * disciplines be established to increase the probability that software is - * characterized by a high degree of correctness, maintainability, and - * portability. In addition, these disciplines must promote practices that aid - * in the consistent and orderly development of a software system within - * schedule and budgetary constraints. To be effective, these disciplines must - * adopt standards which channel individual software efforts toward a common - * goal. - * - * The push for standards in the software development field has been met with - * various degrees of success. The Microprocessor Operating Systems Interfaces - * (MOSI) effort has experienced only limited success. As popular as the UNIX - * operating system has grown, the attempt to develop a standard interface - * definition to allow portable application development has only recently begun - * to produce the results needed in this area. Unfortunately, very little - * effort has been expended to provide standards addressing the needs of the - * real-time community. Several organizations have addressed this need during - * recent years. - * - * The Real Time Executive Interface Definition (RTEID) was developed by - * Motorola with technical input from Software Components Group. RTEID was - * adopted by the VMEbus International Trade Association (VITA) as a baseline - * draft for their proposed standard multiprocessor, real-time executive - * interface, Open Real-Time Kernel Interface Definition (ORKID). These two - * groups are currently working together with the IEEE P1003.4 committee to - * insure that the functionality of their proposed standards is adopted as the - * real-time extensions to POSIX. - * - * This emerging standard defines an interface for the development of real-time - * software to ease the writing of real-time application programs that are - * directly portable across multiple real-time executive implementations. This - * interface includes both the source code interfaces and run-time behavior as - * seen by a real-time application. It does not include the details of how a - * kernel implements these functions. The standard's goal is to serve as a - * complete definition of external interfaces so that application code that - * conforms to these interfaces will execute properly in all real-time - * executive environments. With the use of a standards compliant executive, - * routines that acquire memory blocks, create and manage message queues, - * establish and use semaphores, and send and receive signals need not be - * redeveloped for a different real-time environment as long as the new - * environment is compliant with the standard. Software developers need only - * concentrate on the hardware dependencies of the real-time system. - * Furthermore, most hardware dependencies for real-time applications can be - * localized to the device drivers. - * - * A compliant executive provides simple and flexible real-time - * multiprocessing. It easily lends itself to both tightly-coupled and - * loosely-coupled configurations (depending on the system hardware - * configuration). Objects such as tasks, queues, events, signals, semaphores, - * and memory blocks can be designated as global objects and accessed by any - * task regardless of which processor the object and the accessing task reside. - * - * The acceptance of a standard for real-time executives will produce the same - * advantages enjoyed from the push for UNIX standardization by AT&T's System V - * Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing - * executive will allow close coupling between UNIX systems and real-time - * executives to provide the many benefits of the UNIX development environment - * to be applied to real-time software development. Together they provide the - * necessary laboratory environment to implement real-time, distributed, - * embedded systems using a wide variety of computer architectures. - * - * A study was completed in 1988, within the Research, Development, and - * Engineering Center, U.S. Army Missile Command, which compared the various - * aspects of the Ada programming language as they related to the application - * of Ada code in distributed and/or multiple processing systems. Several - * critical conclusions were derived from the study. These conclusions have a - * major impact on the way the Army develops application software for embedded - * applications. These impacts apply to both in-house software development and - * contractor developed software. - * - * A conclusion of the analysis, which has been previously recognized by other - * agencies attempting to utilize Ada in a distributed or multiprocessing - * environment, is that the Ada programming language does not adequately - * support multiprocessing. Ada does provide a mechanism for multi-tasking, - * however, this capability exists only for a single processor system. The - * language also does not have inherent capabilities to access global named - * variables, flags or program code. These critical features are essential in - * order for data to be shared between processors. However, these drawbacks do - * have workarounds which are sometimes awkward and defeat the intent of - * software maintainability and portability goals. - * - * Another conclusion drawn from the analysis, was that the run time executives - * being delivered with the Ada compilers were too slow and inefficient to be - * used in modern missile systems. A run time executive is the core part of the - * run time system code, or operating system code, that controls task - * scheduling, input/output management and memory management. Traditionally, - * whenever efficient executive (also known as kernel) code was required by the - * application, the user developed in-house software. This software was usually - * written in assembly language for optimization. - * - * Because of this shortcoming in the Ada programming language, software - * developers in research and development and contractors for project managed - * systems, are mandated by technology to purchase and utilize off-the-shelf - * third party kernel code. The contractor, and eventually the Government, must - * pay a licensing fee for every copy of the kernel code used in an embedded - * system. - * - * The main drawback to this development environment is that the Government - * does not own, nor has the right to modify code contained within the kernel. - * V&V techniques in this situation are more difficult than if the complete - * source code were available. Responsibility for system failures due to faulty - * software is yet another area to be resolved under this environment. - * - * The Guidance and Control Directorate began a software development effort to - * address these problems. A project to develop an experimental run time kernel - * was begun that will eliminate the major drawbacks of the Ada programming - * language mentioned above. The Real Time Executive for Multiprocessor Systems - * (RTEMS) provides full capabilities for management of tasks, interrupts, - * time, and multiple processors in addition to those features typical of - * generic operating systems. The code is Government owned, so no licensing - * fees are necessary. RTEMS has been implemented in both the Ada and C - * programming languages. It has been ported to the following processor - * families: - * - * - Altera NIOS II - * - Analog Devices Blackfin - * - ARM - * - Freescale (formerly Motorola) MC68xxx - * - Freescale (formerly Motorola) MC683xx - * - Freescale (formerly Motorola) ColdFire - * - Intel i386 and above - * - Lattice Semiconductor LM32 - * - MIPS - * - PowerPC - * - Renesas (formerly Hitachi) SuperH - * - Renesas (formerly Hitachi) H8/300 - * - SPARC - * - Texas Instruments C3x/C4x - * - UNIX - * - * Support for other processor families, including RISC, CISC, and DSP, is - * planned. Since almost all of RTEMS is written in a high level language, - * ports to additional processor families require minimal effort. - * - * RTEMS multiprocessor support is capable of handling either homogeneous or - * heterogeneous systems. The kernel automatically compensates for - * architectural differences (byte swapping, etc.) between processors. This - * allows a much easier transition from one processor family to another without - * a major system redesign. - * - * Since the proposed standards are still in draft form, RTEMS cannot and does - * not claim compliance. However, the status of the standard is being carefully - * monitored to guarantee that RTEMS provides the functionality specified in - * the standard. Once approved, RTEMS will be made compliant. - */ - -/** - * @page RTEMSOverview RTEMS Overview - * - * @section RTEMSOverviewSecIntroduction Introduction - * - * RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time - * executive (kernel) which provides a high performance environment for - * embedded military applications including the following features: - * - * - multitasking capabilities - * - homogeneous and heterogeneous multiprocessor systems - * - event-driven, priority-based, preemptive scheduling - * - optional rate monotonic scheduling - * - intertask communication and synchronization - * - priority inheritance - * - responsive interrupt management - * - dynamic memory allocation - * - high level of user configurability - * - * This manual describes the usage of RTEMS for applications written in the C - * programming language. Those implementation details that are processor - * dependent are provided in the Applications Supplement documents. A - * supplement document which addresses specific architectural issues that - * affect RTEMS is provided for each processor type that is supported. - * - * @section RTEMSOverviewSecRealtimeApplicationSystems Real-time Application Systems - * - * Real-time application systems are a special class of computer applications. - * They have a complex set of characteristics that distinguish them from other - * software problems. Generally, they must adhere to more rigorous - * requirements. The correctness of the system depends not only on the results - * of computations, but also on the time at which the results are produced. The - * most important and complex characteristic of real-time application systems - * is that they must receive and respond to a set of external stimuli within - * rigid and critical time constraints referred to as deadlines. Systems can be - * buried by an avalanche of interdependent, asynchronous or cyclical event - * streams. - * - * Deadlines can be further characterized as either hard or soft based upon the - * value of the results when produced after the deadline has passed. A deadline - * is hard if the results have no value or if their use will result in a - * catastrophic event. In contrast, results which are produced after a soft - * deadline may have some value. - * - * Another distinguishing requirement of real-time application systems is the - * ability to coordinate or manage a large number of concurrent activities. - * Since software is a synchronous entity, this presents special problems. One - * instruction follows another in a repeating synchronous cycle. Even though - * mechanisms have been developed to allow for the processing of external - * asynchronous events, the software design efforts required to process and - * manage these events and tasks are growing more complicated. - * - * The design process is complicated further by spreading this activity over a - * set of processors instead of a single processor. The challenges associated - * with designing and building real-time application systems become very - * complex when multiple processors are involved. New requirements such as - * interprocessor communication channels and global resources that must be - * shared between competing processors are introduced. The ramifications of - * multiple processors complicate each and every characteristic of a real-time - * system. - * - * @section RTEMSOverviewSecRealtimeExecutive Real-time Executive - * - * Fortunately, real-time operating systems or real-time executives serve as a - * cornerstone on which to build the application system. A real-time - * multitasking executive allows an application to be cast into a set of - * logical, autonomous processes or tasks which become quite manageable. Each - * task is internally synchronous, but different tasks execute independently, - * resulting in an asynchronous processing stream. Tasks can be dynamically - * paused for many reasons resulting in a different task being allowed to - * execute for a period of time. The executive also provides an interface to - * other system components such as interrupt handlers and device drivers. - * System components may request the executive to allocate and coordinate - * resources, and to wait for and trigger synchronizing conditions. The - * executive system calls effectively extend the CPU instruction set to support - * efficient multitasking. By causing tasks to travel through well-defined - * state transitions, system calls permit an application to demand-switch - * between tasks in response to real-time events. - * - * By proper grouping of responses to stimuli into separate tasks, a system can - * now asynchronously switch between independent streams of execution, directly - * responding to external stimuli as they occur. This allows the system design - * to meet critical performance specifications which are typically measured by - * guaranteed response time and transaction throughput. The multiprocessor - * extensions of RTEMS provide the features necessary to manage the extra - * requirements introduced by a system distributed across several processors. - * It removes the physical barriers of processor boundaries from the world of - * the system designer, enabling more critical aspects of the system to receive - * the required attention. Such a system, based on an efficient real-time, - * multiprocessor executive, is a more realistic model of the outside world or - * environment for which it is designed. As a result, the system will always be - * more logical, efficient, and reliable. - * - * By using the directives provided by RTEMS, the real-time applications - * developer is freed from the problem of controlling and synchronizing - * multiple tasks and processors. In addition, one need not develop, test, - * debug, and document routines to manage memory, pass messages, or provide - * mutual exclusion. The developer is then able to concentrate solely on the - * application. By using standard software components, the time and cost - * required to develop sophisticated real-time applications is significantly - * reduced. - * - * @section RTEMSOverviewSecApplicationArchitecture RTEMS Application Architecture - * - * One important design goal of RTEMS was to provide a bridge between two - * critical layers of typical real-time systems. As shown in the following - * figure, RTEMS serves as a buffer between the project dependent application - * code and the target hardware. Most hardware dependencies for real-time - * applications can be localized to the low level device drivers. - * - * @todo Image RTEMS Application Architecture - * - * The RTEMS I/O interface manager provides an efficient tool for incorporating - * these hardware dependencies into the system while simultaneously providing a - * general mechanism to the application code that accesses them. A well - * designed real-time system can benefit from this architecture by building a - * rich library of standard application components which can be used repeatedly - * in other real-time projects. - * - * @section RTEMSOverviewSecInternalArchitecture RTEMS Internal Architecture - * - * RTEMS can be viewed as a set of layered components that work in harmony to - * provide a set of services to a real-time application system. The executive - * interface presented to the application is formed by grouping directives into - * logical sets called resource managers. Functions utilized by multiple - * managers such as scheduling, dispatching, and object management are provided - * in the executive core. The executive core depends on a small set of CPU - * dependent routines. Together these components provide a powerful run time - * environment that promotes the development of efficient real-time application - * systems. The following figure illustrates this organization: - * - * @todo Image RTEMS Architecture - * - * Subsequent chapters present a detailed description of the capabilities - * provided by each of the following RTEMS managers: - * - * - initialization - * - task - * - interrupt - * - clock - * - timer - * - semaphore - * - message - * - event - * - signal - * - partition - * - region - * - dual ported memory - * - I/O - * - fatal error - * - rate monotonic - * - user extensions - * - multiprocessing - * - * @section RTEMSOverviewSecUserCustomization User Customization and Extensibility - * - * As 32-bit microprocessors have decreased in cost, they have become - * increasingly common in a variety of embedded systems. A wide range of custom - * and general-purpose processor boards are based on various 32-bit - * processors. RTEMS was designed to make no assumptions concerning the - * characteristics of individual microprocessor families or of specific support - * hardware. In addition, RTEMS allows the system developer a high degree of - * freedom in customizing and extending its features. - * - * RTEMS assumes the existence of a supported microprocessor and sufficient - * memory for both RTEMS and the real-time application. Board dependent - * components such as clocks, interrupt controllers, or I/O devices can be - * easily integrated with RTEMS. The customization and extensibility features - * allow RTEMS to efficiently support as many environments as possible. - * - * @section RTEMSOverviewSecPortability Portability - * - * The issue of portability was the major factor in the creation of RTEMS. - * Since RTEMS is designed to isolate the hardware dependencies in the specific - * board support packages, the real-time application should be easily ported to - * any other processor. The use of RTEMS allows the development of real-time - * applications which can be completely independent of a particular - * microprocessor architecture. - * - * @section RTEMSOverviewSecMemoryRequirements Memory Requirements - * - * Since memory is a critical resource in many real-time embedded systems, - * RTEMS was specifically designed to automatically leave out all services that - * are not required from the run-time environment. Features such as networking, - * various filesystems, and many other features are completely optional. This - * allows the application designer the flexibility to tailor RTEMS to most - * efficiently meet system requirements while still satisfying even the most - * stringent memory constraints. As a result, the size of the RTEMS executive - * is application dependent. - * - * RTEMS requires RAM to manage each instance of an RTEMS object that is - * created. Thus the more RTEMS objects an application needs, the more memory - * that must be reserved. See Configuring a System Determining Memory - * Requirements for more details. - * - * @todo Link to Configuring a SystemDetermining Memory Requirements - * - * RTEMS utilizes memory for both code and data space. Although RTEMS' data - * space must be in RAM, its code space can be located in either ROM or RAM. - * - * @section RTEMSOverviewSecAudience Audience - * - * This manual was written for experienced real-time software developers. - * Although some background is provided, it is assumed that the reader is - * familiar with the concepts of task management as well as intertask - * communication and synchronization. Since directives, user related data - * structures, and examples are presented in C, a basic understanding of the C - * programming language is required to fully understand the material presented. - * However, because of the similarity of the Ada and C RTEMS implementations, - * users will find that the use and behavior of the two implementations is very - * similar. A working knowledge of the target processor is helpful in - * understanding some of RTEMS' features. A thorough understanding of the - * executive cannot be obtained without studying the entire manual because many - * of RTEMS' concepts and features are interrelated. Experienced RTEMS users - * will find that the manual organization facilitates its use as a reference - * document. - */ - -/** - * @addtogroup RTEMSAPIClassic - * - * The facilities provided by RTEMS are built upon a foundation of very - * powerful concepts. These concepts must be understood before the application - * developer can efficiently utilize RTEMS. The purpose of this chapter is to - * familiarize one with these concepts. - * - * @section ClassicRTEMSSecObjects Objects - * - * RTEMS provides directives which can be used to dynamically create, delete, - * and manipulate a set of predefined object types. These types include tasks, - * message queues, semaphores, memory regions, memory partitions, timers, - * ports, and rate monotonic periods. The object-oriented nature of RTEMS - * encourages the creation of modular applications built upon re-usable - * "building block" routines. - * - * All objects are created on the local node as required by the application and - * have an RTEMS assigned ID. All objects have a user-assigned name. Although a - * relationship exists between an object's name and its RTEMS assigned ID, the - * name and ID are not identical. Object names are completely arbitrary and - * selected by the user as a meaningful "tag" which may commonly reflect the - * object's use in the application. Conversely, object IDs are designed to - * facilitate efficient object manipulation by the executive. - * - * @subsection ClassicRTEMSSubSecObjectNames Object Names - * - * An object name is an unsigned 32-bit entity associated with the - * object by the user. The data type @ref rtems_name is used to store object names. - * - * Although not required by RTEMS, object names are often composed of four - * ASCII characters which help identify that object. For example, a task which - * causes a light to blink might be called "LITE". The rtems_build_name() - * routine is provided to build an object name from four ASCII characters. The - * following example illustrates this: - * - * @code - * rtems_name my_name = rtems_build_name('L', 'I', 'T', 'E'); - * @endcode - * - * However, it is not required that the application use ASCII characters to - * build object names. For example, if an application requires one-hundred - * tasks, it would be difficult to assign meaningful ASCII names to each task. - * A more convenient approach would be to name them the binary values one - * through one-hundred, respectively. - * - * RTEMS provides a helper routine, rtems_object_get_name(), which can be used to - * obtain the name of any RTEMS object using just its ID. This routine attempts - * to convert the name into a printable string. - * - * @subsection ClassicRTEMSSubSecObjectIdentifiers Object Identifiers - * - * An object ID is a unique unsigned integer value which uniquely identifies an - * object instance. Object IDs are passed as arguments to many directives in - * RTEMS and RTEMS translates the ID to an internal object pointer. The - * efficient manipulation of object IDs is critical to the performance of RTEMS - * services. Because of this, there are two object ID formats defined. Each - * target architecture specifies which format it will use. There is a 32-bit - * format which is used for most of the supported architectures and supports - * multiprocessor configurations. There is also a simpler 16-bit format which - * is appropriate for smaller target architectures and does not support - * multiprocessor configurations. - * - * @subsubsection ClassicRTEMSSubSec32BitObjectIdentifierFormat 32-Bit Object Identifier Format - * - * The 32-bit format for an object ID is composed of four parts: API, - * object class, node, and index. The data type @ref rtems_id is used to store - * object IDs. - * - * <table> - * <tr> - * <th>Bits</th> - * <td>31</td><td>30</td><td>29</td><td>28</td><td>27</td><td>26</td><td>25</td><td>24</td> - * <td>23</td><td>22</td><td>21</td><td>20</td><td>19</td><td>18</td><td>17</td><td>16</td> - * <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td> - * <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td> - * </tr> - * <tr> - * <th>Contents</th> - * <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Node</td><td colspan=16>Object Index</td> - * </tr> - * </table> - * - * The most significant five bits are the object class. The next three bits - * indicate the API to which the object class belongs. The next eight bits - * (16 .. 23) are the number of the node on which this object was created. The - * node number is always one (1) in a single processor system. The least - * significant 16-bits form an identifier within a particular object type. - * This identifier, called the object index, ranges in value from one to the - * maximum number of objects configured for this object type. - * - * @subsubsection ClassicRTEMSSubSec16BitObjectIdentifierFormat 16-Bit Object Identifier Format - * - * The 16-bit format for an object ID is composed of three parts: API, object - * class, and index. The data type @ref rtems_id is used to store object IDs. - * - * <table> - * <tr> - * <th>Bits</th> - * <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td> - * <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td> - * </tr> - * <tr> - * <th>Contents</th> - * <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Object Index</td> - * </tr> - * </table> - * - * The 16-bit format is designed to be as similar as possible to the 32-bit - * format. The differences are limited to the elimination of the node field - * and reduction of the index field from 16-bits to 8-bits. Thus the 16-bit - * format only supports up to 255 object instances per API/Class combination - * and single processor systems. As this format is typically utilized by 16-bit - * processors with limited address space, this is more than enough object - * instances. - * - * @subsection ClassicRTEMSSubSecObjectIdentiferDescription Object Identifer Description - * - * The components of an object ID make it possible to quickly locate any object - * in even the most complicated multiprocessor system. Object ID's are - * associated with an object by RTEMS when the object is created and the - * corresponding ID is returned by the appropriate object create directive. The - * object ID is required as input to all directives involving objects, except - * those which create an object or obtain the ID of an object. - * - * The object identification directives can be used to dynamically obtain a - * particular object's ID given its name. This mapping is accomplished by - * searching the name table associated with this object type. If the name is - * non-unique, then the ID associated with the first occurrence of the name - * will be returned to the application. Since object IDs are returned when the - * object is created, the object identification directives are not necessary in - * a properly designed single processor application. - * - * In addition, services are provided to portably examine the subcomponents of - * an RTEMS ID. These services are described in detail later in this manual but - * are prototyped as follows: - * - * - rtems_object_id_get_api() - * - rtems_object_id_get_class() - * - rtems_object_id_get_node() - * - rtems_object_id_get_index() - * - * An object control block is a data structure defined by RTEMS which contains - * the information necessary to manage a particular object type. For efficiency - * reasons, the format of each object type's control block is different. - * However, many of the fields are similar in function. The number of each type - * of control block is application dependent and determined by the values - * specified in the user's Configuration Table. An object control block is - * allocated at object create time and freed when the object is deleted. With - * the exception of user extension routines, object control blocks are not - * directly manipulated by user applications. - * - * @section ClassicRTEMSSecComSync Communication and Synchronization - * - * In real-time multitasking applications, the ability for cooperating - * execution threads to communicate and synchronize with each other is - * imperative. A real-time executive should provide an application with the - * following capabilities - * - * - data transfer between cooperating tasks, - * - data transfer between tasks and ISRs, - * - synchronization of cooperating tasks, and - * - synchronization of tasks and ISRs. - * - * Most RTEMS managers can be used to provide some form of communication and/or - * synchronization. However, managers dedicated specifically to communication - * and synchronization provide well established mechanisms which directly map - * to the application's varying needs. This level of flexibility allows the - * application designer to match the features of a particular manager with the - * complexity of communication and synchronization required. The following - * managers were specifically designed for communication and synchronization: - * - * - @ref ClassicSem - * - @ref ClassicMessageQueue - * - @ref ClassicEvent - * - @ref ClassicSignal - * - * The semaphore manager supports mutual exclusion involving the - * synchronization of access to one or more shared user resources. Binary - * semaphores may utilize the optional priority inheritance algorithm to avoid - * the problem of priority inversion. The message manager supports both - * communication and synchronization, while the event manager primarily - * provides a high performance synchronization mechanism. The signal manager - * supports only asynchronous communication and is typically used for exception - * handling. - * - * @section ClassicRTEMSSecTime Time - * - * The development of responsive real-time applications requires an - * understanding of how RTEMS maintains and supports time-related operations. - * The basic unit of time in RTEMS is known as a tick. The frequency of clock - * ticks is completely application dependent and determines the granularity and - * accuracy of all interval and calendar time operations. - * - * By tracking time in units of ticks, RTEMS is capable of supporting interval - * timing functions such as task delays, timeouts, timeslicing, the delayed - * execution of timer service routines, and the rate monotonic scheduling of - * tasks. An interval is defined as a number of ticks relative to the current - * time. For example, when a task delays for an interval of ten ticks, it is - * implied that the task will not execute until ten clock ticks have occurred. - * All intervals are specified using data type @ref rtems_interval. - * - * A characteristic of interval timing is that the actual interval period may - * be a fraction of a tick less than the interval requested. This occurs - * because the time at which the delay timer is set up occurs at some time - * between two clock ticks. Therefore, the first countdown tick occurs in less - * than the complete time interval for a tick. This can be a problem if the - * clock granularity is large. - * - * The rate monotonic scheduling algorithm is a hard real-time scheduling - * methodology. This methodology provides rules which allows one to guarantee - * that a set of independent periodic tasks will always meet their deadlines -- - * even under transient overload conditions. The rate monotonic manager - * provides directives built upon the Clock Manager's interval timer support - * routines. - * - * Interval timing is not sufficient for the many applications which require - * that time be kept in wall time or true calendar form. Consequently, RTEMS - * maintains the current date and time. This allows selected time operations to - * be scheduled at an actual calendar date and time. For example, a task could - * request to delay until midnight on New Year's Eve before lowering the ball - * at Times Square. The data type @ref rtems_time_of_day is used to specify - * calendar time in RTEMS services. See Clock Manager Time and Date Data - * Structures. - * - * @todo Link to Clock Manager Time and Date Data Structures - * - * Obviously, the directives which use intervals or wall time cannot operate - * without some external mechanism which provides a periodic clock tick. This - * clock tick is typically provided by a real time clock or counter/timer - * device. - * - * @section ClassicRTEMSSecMemoryManagement Memory Management - * - * RTEMS memory management facilities can be grouped into two classes: dynamic - * memory allocation and address translation. Dynamic memory allocation is - * required by applications whose memory requirements vary through the - * application's course of execution. Address translation is needed by - * applications which share memory with another CPU or an intelligent - * Input/Output processor. The following RTEMS managers provide facilities to - * manage memory: - * - * - @ref ClassicRegion - * - @ref ClassicPart - * - @ref ClassicDPMEM - * - * RTEMS memory management features allow an application to create simple - * memory pools of fixed size buffers and/or more complex memory pools of - * variable size segments. The partition manager provides directives to manage - * and maintain pools of fixed size entities such as resource control blocks. - * Alternatively, the region manager provides a more general purpose memory - * allocation scheme that supports variable size blocks of memory which are - * dynamically obtained and freed by the application. The dual-ported memory - * manager provides executive support for address translation between internal - * and external dual-ported RAM address space. - */ - -/** - * @addtogroup RTEMSAPIClassicTasks - * - * @section ClassicTasksSecTaskDefinition Task Definition - * - * Many definitions of a task have been proposed in computer literature. - * Unfortunately, none of these definitions encompasses all facets of the - * concept in a manner which is operating system independent. Several of the - * more common definitions are provided to enable each user to select a - * definition which best matches their own experience and understanding of the - * task concept: - * - * - a "dispatchable" unit. - * - an entity to which the processor is allocated. - * - an atomic unit of a real-time, multiprocessor system. - * - single threads of execution which concurrently compete for resources. - * - a sequence of closely related computations which can execute concurrently - * with other computational sequences. - * - * From RTEMS' perspective, a task is the smallest thread of execution which - * can compete on its own for system resources. A task is manifested by the - * existence of a task control block (TCB). - * - * @section ClassicTasksSecTaskControlBlock Task Control Block - * - * The Task Control Block (TCB) is an RTEMS defined data structure which - * contains all the information that is pertinent to the execution of a task. - * During system initialization, RTEMS reserves a TCB for each task configured. - * A TCB is allocated upon creation of the task and is returned to the TCB free - * list upon deletion of the task. - * - * The TCB's elements are modified as a result of system calls made by the - * application in response to external and internal stimuli. TCBs are the only - * RTEMS internal data structure that can be accessed by an application via - * user extension routines. The TCB contains a task's name, ID, current - * priority, current and starting states, execution mode, TCB user extension - * pointer, scheduling control structures, as well as data required by a - * blocked task. - * - * A task's context is stored in the TCB when a task switch occurs. When the - * task regains control of the processor, its context is restored from the TCB. - * When a task is restarted, the initial state of the task is restored from the - * starting context area in the task's TCB. - * - * @section ClassicTasksSecTaskStates Task States - * - * A task may exist in one of the following five states: - * - * - executing - Currently scheduled to the CPU - * - ready - May be scheduled to the CPU - * - blocked - Unable to be scheduled to the CPU - * - dormant - Created task that is not started - * - non-existent - Uncreated or deleted task - * - * An active task may occupy the executing, ready, blocked or dormant state, - * otherwise the task is considered non-existent. One or more tasks may be - * active in the system simultaneously. Multiple tasks communicate, - * synchronize, and compete for system resources with each other via system - * calls. The multiple tasks appear to execute in parallel, but actually each - * is dispatched to the CPU for periods of time determined by the RTEMS - * scheduling algorithm. The scheduling of a task is based on its current state - * and priority. - * - * @section ClassicTasksSecTaskPriority Task Priority - * - * A task's priority determines its importance in relation to the other tasks - * executing on the same processor. RTEMS supports 255 levels of priority - * ranging from 1 to 255. The data type rtems_task_priority() is used to store - * task priorities. - * - * Tasks of numerically smaller priority values are more important tasks than - * tasks of numerically larger priority values. For example, a task at priority - * level 5 is of higher privilege than a task at priority level 10. There is no - * limit to the number of tasks assigned to the same priority. - * - * Each task has a priority associated with it at all times. The initial value - * of this priority is assigned at task creation time. The priority of a task - * may be changed at any subsequent time. - * - * Priorities are used by the scheduler to determine which ready task will be - * allowed to execute. In general, the higher the logical priority of a task, - * the more likely it is to receive processor execution time. - * - * @section ClassicTasksSecTaskMode Task Mode - * - * A task's execution mode is a combination of the following four components: - * - * - preemption - * - ASR processing - * - timeslicing - * - interrupt level - * - * It is used to modify RTEMS' scheduling process and to alter the execution - * environment of the task. The data type rtems_task_mode() is used to manage - * the task execution mode. - * - * The preemption component allows a task to determine when control of the - * processor is relinquished. If preemption is disabled (@c - * RTEMS_NO_PREEMPT), the task will retain control of the - * processor as long as it is in the executing state -- even if a higher - * priority task is made ready. If preemption is enabled (@c RTEMS_PREEMPT) - * and a higher priority task is made ready, then the processor will be - * taken away from the current task immediately and given to the higher - * priority task. - * - * The timeslicing component is used by the RTEMS scheduler to determine how - * the processor is allocated to tasks of equal priority. If timeslicing is - * enabled (@c RTEMS_TIMESLICE), then RTEMS will limit the amount of time the - * task can execute before the processor is allocated to another ready task of - * equal priority. The length of the timeslice is application dependent and - * specified in the Configuration Table. If timeslicing is disabled (@c - * RTEMS_NO_TIMESLICE), then the task will be allowed to - * execute until a task of higher priority is made ready. If @c - * RTEMS_NO_PREEMPT is selected, then the timeslicing component is ignored by - * the scheduler. - * - * The asynchronous signal processing component is used to determine when - * received signals are to be processed by the task. If signal processing is - * enabled (@c RTEMS_ASR), then signals sent to the task will be processed - * the next time the task executes. If signal processing is disabled (@c - * RTEMS_NO_ASR), then all signals received by the task will - * remain posted until signal processing is enabled. This component affects - * only tasks which have established a routine to process asynchronous signals. - * - * The interrupt level component is used to determine which interrupts will be - * enabled when the task is executing. @c RTEMS_INTERRUPT_LEVEL(n) specifies - * that the task will execute at interrupt level n. - * - * - @ref RTEMS_PREEMPT - enable preemption (default) - * - @ref RTEMS_NO_PREEMPT - disable preemption - * - @ref RTEMS_NO_TIMESLICE - disable timeslicing (default) - * - @ref RTEMS_TIMESLICE - enable timeslicing - * - @ref RTEMS_ASR - enable ASR processing (default) - * - @ref RTEMS_NO_ASR - disable ASR processing - * - @ref RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default) - * - @ref RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n - * - * The set of default modes may be selected by specifying the @ref - * RTEMS_DEFAULT_MODES constant. - * - * @section ClassicTasksSecAccessingTaskArguments Accessing Task Arguments - * - * All RTEMS tasks are invoked with a single argument which is specified when - * they are started or restarted. The argument is commonly used to communicate - * startup information to the task. The simplest manner in which to define a - * task which accesses it argument is: - * - * @code - * rtems_task user_task( - * rtems_task_argument argument - * ); - * @endcode - * - * Application tasks requiring more information may view this single argument - * as an index into an array of parameter blocks. - * - * @section ClassicTasksSecFloatingPointConsiderations Floating Point Considerations - * - * Creating a task with the @ref RTEMS_FLOATING_POINT attribute flag results in - * additional memory being allocated for the TCB to store the state of the - * numeric coprocessor during task switches. This additional memory is NOT - * allocated for @ref RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the - * context of a @c RTEMS_FLOATING_POINT task takes longer than that of a @c - * RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time - * required for the numeric coprocessor to save or restore its computational - * state. - * - * Since RTEMS was designed specifically for embedded military applications - * which are floating point intensive, the executive is optimized to avoid - * unnecessarily saving and restoring the state of the numeric coprocessor. The - * state of the numeric coprocessor is only saved when a @c - * RTEMS_FLOATING_POINT task is dispatched and that task was not the last task - * to utilize the coprocessor. In a system with only one @c - * RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never - * be saved or restored. - * - * Although the overhead imposed by @c RTEMS_FLOATING_POINT tasks is minimal, - * some applications may wish to completely avoid the overhead associated with - * @c RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By - * preventing a task from being preempted while performing a sequence of - * floating point operations, a @c RTEMS_NO_FLOATING_POINT task can utilize - * the numeric coprocessor without incurring the overhead of a @c - * RTEMS_FLOATING_POINT context switch. This approach also avoids the - * allocation of a floating point context area. However, if this approach is - * taken by the application designer, NO tasks should be created as @c - * RTEMS_FLOATING_POINT tasks. Otherwise, the floating point context will not - * be correctly maintained because RTEMS assumes that the state of the numeric - * coprocessor will not be altered by @c RTEMS_NO_FLOATING_POINT tasks. - * - * If the supported processor type does not have hardware floating capabilities - * or a standard numeric coprocessor, RTEMS will not provide built-in support - * for hardware floating point on that processor. In this case, all tasks are - * considered @c RTEMS_NO_FLOATING_POINT whether created as @c - * RTEMS_FLOATING_POINT or @c RTEMS_NO_FLOATING_POINT tasks. A floating point - * emulation software library must be utilized for floating point operations. - * - * On some processors, it is possible to disable the floating point unit - * dynamically. If this capability is supported by the target processor, then - * RTEMS will utilize this capability to enable the floating point unit only - * for tasks which are created with the @c RTEMS_FLOATING_POINT attribute. - * The consequence of a @c RTEMS_NO_FLOATING_POINT task attempting to access - * the floating point unit is CPU dependent but will generally result in an - * exception condition. - * - * @section ClassicTasksSecPerTaskVariables Per Task Variables - * - * Per task variables are no longer available. In particular the - * rtems_task_variable_add(), rtems_task_variable_get() and - * rtems_task_variable_delete() functions are neither declared nor defined - * anymore. Use thread local storage or POSIX Keys instead. - * - * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task Attribute Set - * - * In general, an attribute set is built by a bitwise OR of the desired - * components. The set of valid task attribute components is listed below: - * - * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default) - * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor - * - @ref RTEMS_LOCAL - local task (default) - * - @ref RTEMS_GLOBAL - global task - * - * Attribute values are specifically designed to be mutually exclusive, - * therefore bitwise OR and addition operations are equivalent as long as each - * attribute appears exactly once in the component list. A component listed as - * a default is not required to appear in the component list, although it is a - * good programming practice to specify default components. If all defaults are - * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used. This example - * demonstrates the attribute_set parameter needed to create a local task which - * utilizes the numeric coprocessor. The attribute_set parameter could be @c - * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The - * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because @c - * RTEMS_LOCAL is the default for all created tasks. If the task were global - * and used the numeric coprocessor, then the attribute_set parameter would be - * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT. - * - * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask - * - * In general, a mode and its corresponding mask is built by a bitwise OR of - * the desired components. The set of valid mode constants and each mode's - * corresponding mask constant is listed below: - * - * <table> - * <tr><th>Mode Constant</th><th>Mask Constant</th><th>Description</th></tr> - * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr> - * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr> - * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr> - * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr> - * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR processing</td></tr> - * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables ASR processing</td></tr> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr> - * </table> - * - * Mode values are specifically designed to be mutually exclusive, therefore - * bitwise OR and addition operations are equivalent as long as each mode - * appears exactly once in the component list. A mode component listed as a - * default is not required to appear in the mode component list, although it is - * a good programming practice to specify default components. If all defaults - * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref - * RTEMS_ALL_MODE_MASKS should be used. - * - * The following example demonstrates the mode and mask parameters used with - * the rtems_task_mode() directive to place a task at interrupt level 3 and - * make it non-preemptible. The mode should be set to @c - * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired - * preemption mode and interrupt level, while the mask parameter should be set - * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that - * the calling task's interrupt level and preemption mode are being altered. - */ - - /** - * @defgroup LocalPackages Local Packages - * - * @ingroup RTEMSAPIClassic - * - * @brief Local packages. - */ diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h index 0a76b1f9b8..0967430934 100644 --- a/cpukit/include/rtems/rtems/message.h +++ b/cpukit/include/rtems/rtems/message.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -212,14 +212,14 @@ typedef struct { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * message queue. The number of message queue available to the application - * is configured through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application - * configuration option. + * is configured through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES + * application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global message queue. The * number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * * @retval ::RTEMS_INVALID_NUMBER The product of ``count`` and * ``max_message_size`` is greater than the maximum storage size. @@ -260,16 +260,16 @@ typedef struct { * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_create( @@ -288,7 +288,8 @@ rtems_status_code rtems_message_queue_create( * @brief Constructs a message queue from the specified the message queue * configuration. * - * @param config is the message queue configuration. + * @param config is the pointer to an rtems_message_queue_config object. It + * configures the message queue. * * @param[out] id is the pointer to an ::rtems_id object. When the directive * call is successful, the identifier of the constructed message queue will @@ -342,8 +343,8 @@ rtems_status_code rtems_message_queue_create( * runtime memory allocators. This can simplify the application architecture * as well as any analysis that may be required. * - * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for - * message queues constructed by rtems_message_queue_construct(). + * The value for @ref CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory + * for message queues constructed by rtems_message_queue_construct(). * @endparblock * * @par Constraints @@ -362,16 +363,16 @@ rtems_status_code rtems_message_queue_create( * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_construct( @@ -655,7 +656,7 @@ rtems_status_code rtems_message_queue_urgent( * * This directive causes all tasks that are waiting at the queue specified by * ``id`` to be unblocked and sent the message contained in ``buffer``. Before - * a task is unblocked, the message ``buffer`` of ``size`` byes in length is + * a task is unblocked, the message ``buffer`` of ``size`` bytes in length is * copied to that task's message buffer. The number of tasks that were * unblocked is returned in ``count``. * diff --git a/cpukit/include/rtems/rtems/messagedata.h b/cpukit/include/rtems/rtems/messagedata.h index ed74abf981..f91fca1b8b 100644 --- a/cpukit/include/rtems/rtems/messagedata.h +++ b/cpukit/include/rtems/rtems/messagedata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_MESSAGEDATA_H diff --git a/cpukit/include/rtems/rtems/messageimpl.h b/cpukit/include/rtems/rtems/messageimpl.h index b9cdd0251d..5fbdcadcf6 100644 --- a/cpukit/include/rtems/rtems/messageimpl.h +++ b/cpukit/include/rtems/rtems/messageimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_MESSAGEIMPL_H @@ -78,14 +97,14 @@ rtems_status_code _Message_queue_Submit( * This routine deallocates a message queue control block into * the inactive chain of free message queue control blocks. */ -RTEMS_INLINE_ROUTINE void _Message_queue_Free ( +static inline void _Message_queue_Free ( Message_queue_Control *the_message_queue ) { _Objects_Free( &_Message_queue_Information, &the_message_queue->Object ); } -RTEMS_INLINE_ROUTINE Message_queue_Control *_Message_queue_Get( +static inline Message_queue_Control *_Message_queue_Get( Objects_Id id, Thread_queue_Context *queue_context ) @@ -98,7 +117,7 @@ RTEMS_INLINE_ROUTINE Message_queue_Control *_Message_queue_Get( ); } -RTEMS_INLINE_ROUTINE Message_queue_Control *_Message_queue_Allocate( void ) +static inline Message_queue_Control *_Message_queue_Allocate( void ) { return (Message_queue_Control *) _Objects_Allocate( &_Message_queue_Information ); diff --git a/cpukit/include/rtems/rtems/modes.h b/cpukit/include/rtems/rtems/modes.h index 559029d2da..f348941b24 100644 --- a/cpukit/include/rtems/rtems/modes.h +++ b/cpukit/include/rtems/rtems/modes.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassicModes + * * @brief This header file provides the task modes API of the Task Manager. */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/modesimpl.h b/cpukit/include/rtems/rtems/modesimpl.h index 8fdab263f1..8cbf655cbb 100644 --- a/cpukit/include/rtems/rtems/modesimpl.h +++ b/cpukit/include/rtems/rtems/modesimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_MODESIMPL_H @@ -45,7 +64,7 @@ extern "C" { * This function returns TRUE if mode_set indicates that Asynchronous * Signal Processing is disabled, and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Modes_Is_asr_disabled ( +static inline bool _Modes_Is_asr_disabled ( rtems_mode mode_set ) { @@ -58,7 +77,7 @@ RTEMS_INLINE_ROUTINE bool _Modes_Is_asr_disabled ( * This function returns TRUE if mode_set indicates that preemption * is enabled, and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Modes_Is_preempt ( +static inline bool _Modes_Is_preempt ( rtems_mode mode_set ) { @@ -71,7 +90,7 @@ RTEMS_INLINE_ROUTINE bool _Modes_Is_preempt ( * This function returns TRUE if mode_set indicates that timeslicing * is enabled, and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Modes_Is_timeslice ( +static inline bool _Modes_Is_timeslice ( rtems_mode mode_set ) { @@ -83,7 +102,7 @@ RTEMS_INLINE_ROUTINE bool _Modes_Is_timeslice ( * * This function returns the interrupt level portion of the mode_set. */ -RTEMS_INLINE_ROUTINE ISR_Level _Modes_Get_interrupt_level ( +static inline ISR_Level _Modes_Get_interrupt_level ( rtems_mode mode_set ) { @@ -100,7 +119,7 @@ RTEMS_INLINE_ROUTINE ISR_Level _Modes_Get_interrupt_level ( * @return Returns true, if support for the interrupt level is implemented, * otherwise returns false. */ -RTEMS_INLINE_ROUTINE bool _Modes_Is_interrupt_level_supported( +static inline bool _Modes_Is_interrupt_level_supported( rtems_mode mode_set ) { @@ -123,7 +142,7 @@ RTEMS_INLINE_ROUTINE bool _Modes_Is_interrupt_level_supported( * @return Returns true, if support for the preempt mode is implemented, * otherwise returns false. */ -RTEMS_INLINE_ROUTINE bool _Modes_Is_preempt_mode_supported( +static inline bool _Modes_Is_preempt_mode_supported( rtems_mode mode_set, const Thread_Control *the_thread ) @@ -143,7 +162,7 @@ RTEMS_INLINE_ROUTINE bool _Modes_Is_preempt_mode_supported( * * @param[out] the_thread is the thread to apply the timeslice mode. */ -RTEMS_INLINE_ROUTINE void _Modes_Apply_timeslice_to_thread( +static inline void _Modes_Apply_timeslice_to_thread( rtems_mode mode_set, Thread_Control *the_thread ) diff --git a/cpukit/include/rtems/rtems/mp.h b/cpukit/include/rtems/rtems/mp.h index 91c31047fb..5852f43381 100644 --- a/cpukit/include/rtems/rtems/mp.h +++ b/cpukit/include/rtems/rtems/mp.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file defines the Multiprocessing Manager API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/msgmp.h b/cpukit/include/rtems/rtems/msgmp.h index a5f5ae8011..ddd5aa11cc 100644 --- a/cpukit/include/rtems/rtems/msgmp.h +++ b/cpukit/include/rtems/rtems/msgmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_MSGMP_H @@ -80,7 +99,7 @@ typedef struct { #define MESSAGE_QUEUE_MP_PACKET_SIZE \ offsetof(Message_queue_MP_Packet, buffer) -RTEMS_INLINE_ROUTINE bool _Message_queue_MP_Is_remote( Objects_Id id ) +static inline bool _Message_queue_MP_Is_remote( Objects_Id id ) { return _Objects_MP_Is_remote( id, &_Message_queue_Information ); } diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h index e80303da28..bda9a469ed 100644 --- a/cpukit/include/rtems/rtems/object.h +++ b/cpukit/include/rtems/rtems/object.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassicObject + * * @brief This header file provides the Object Services API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/objectimpl.h b/cpukit/include/rtems/rtems/objectimpl.h index fc93d1aa3b..b17a6ed4d6 100644 --- a/cpukit/include/rtems/rtems/objectimpl.h +++ b/cpukit/include/rtems/rtems/objectimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/rtems/options.h b/cpukit/include/rtems/rtems/options.h index 60d90f997e..44a8d6ccb8 100644 --- a/cpukit/include/rtems/rtems/options.h +++ b/cpukit/include/rtems/rtems/options.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file provides the Classic API directive options. */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/optionsimpl.h b/cpukit/include/rtems/rtems/optionsimpl.h index 7130b2c31f..24e861bf9d 100644 --- a/cpukit/include/rtems/rtems/optionsimpl.h +++ b/cpukit/include/rtems/rtems/optionsimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_OPTIONSIMPL_H @@ -40,7 +59,7 @@ extern "C" { * This function returns TRUE if the RTEMS_NO_WAIT option is enabled in * option_set, and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Options_Is_no_wait ( +static inline bool _Options_Is_no_wait ( rtems_option option_set ) { @@ -53,7 +72,7 @@ RTEMS_INLINE_ROUTINE bool _Options_Is_no_wait ( * This function returns TRUE if the RTEMS_EVENT_ANY option is enabled in * OPTION_SET, and FALSE otherwise. */ -RTEMS_INLINE_ROUTINE bool _Options_Is_any ( +static inline bool _Options_Is_any ( rtems_option option_set ) { diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h index 10091b48f4..8c7b0b5ef3 100644 --- a/cpukit/include/rtems/rtems/part.h +++ b/cpukit/include/rtems/rtems/part.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -168,13 +168,13 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * partition. The number of partitions available to the application is - * configured through the #CONFIGURE_MAXIMUM_PARTITIONS application + * configured through the @ref CONFIGURE_MAXIMUM_PARTITIONS application * configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global semaphore. The number * of global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @par Notes * @parblock @@ -220,7 +220,7 @@ extern "C" { * message to remote nodes. This may preempt the calling task. * * * The number of partitions available to the application is configured - * through the #CONFIGURE_MAXIMUM_PARTITIONS application configuration + * through the @ref CONFIGURE_MAXIMUM_PARTITIONS application configuration * option. * * * Where the object class corresponding to the directive is configured to use @@ -228,8 +228,8 @@ extern "C" { * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_partition_create( diff --git a/cpukit/include/rtems/rtems/partdata.h b/cpukit/include/rtems/rtems/partdata.h index 196c2142ae..6df4af81c5 100644 --- a/cpukit/include/rtems/rtems/partdata.h +++ b/cpukit/include/rtems/rtems/partdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_PARTDATA_H @@ -41,11 +60,13 @@ typedef struct { */ Objects_Control Object; +#if defined(RTEMS_SMP) /** * @brief This lock protects the chain of unallocated buffers and the number * of allocated buffers. */ - ISR_LOCK_MEMBER( Lock ) + ISR_lock_Control Lock; +#endif /** * @brief This member contains the base address of the buffer area. @@ -95,6 +116,8 @@ typedef struct { extern Objects_Information _Partition_Information; #if defined(RTEMS_MULTIPROCESSING) +struct _Thread_Control; + /** * @brief Sends the extract proxy request. * @@ -105,8 +128,8 @@ extern Objects_Information _Partition_Information; * @param id is the partition identifier. */ void _Partition_MP_Send_extract_proxy ( - Thread_Control *the_thread, - Objects_Id id + struct _Thread_Control *the_thread, + Objects_Id id ); #endif diff --git a/cpukit/include/rtems/rtems/partimpl.h b/cpukit/include/rtems/rtems/partimpl.h index 144265df7d..2dcea25b81 100644 --- a/cpukit/include/rtems/rtems/partimpl.h +++ b/cpukit/include/rtems/rtems/partimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_PARTIMPL_H @@ -43,7 +62,7 @@ extern "C" { * * @return See _Objects_Get(). */ -RTEMS_INLINE_ROUTINE Partition_Control *_Partition_Get( +static inline Partition_Control *_Partition_Get( Objects_Id id, ISR_lock_Context *lock_context ) @@ -62,7 +81,7 @@ RTEMS_INLINE_ROUTINE Partition_Control *_Partition_Get( * * @param[in, out] lock_context is the lock context set up by _Partition_Get(). */ -RTEMS_INLINE_ROUTINE void _Partition_Acquire_critical( +static inline void _Partition_Acquire_critical( Partition_Control *the_partition, ISR_lock_Context *lock_context ) @@ -77,7 +96,7 @@ RTEMS_INLINE_ROUTINE void _Partition_Acquire_critical( * * @param[in, out] lock_context is the lock context set up by _Partition_Get(). */ -RTEMS_INLINE_ROUTINE void _Partition_Release( +static inline void _Partition_Release( Partition_Control *the_partition, ISR_lock_Context *lock_context ) diff --git a/cpukit/include/rtems/rtems/partmp.h b/cpukit/include/rtems/rtems/partmp.h index 103a28f9d5..cffde801d8 100644 --- a/cpukit/include/rtems/rtems/partmp.h +++ b/cpukit/include/rtems/rtems/partmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_PARTMP_H @@ -66,7 +85,7 @@ typedef struct { Objects_Id proxy_id; } Partition_MP_Packet; -RTEMS_INLINE_ROUTINE bool _Partition_MP_Is_remote( Objects_Id id ) +static inline bool _Partition_MP_Is_remote( Objects_Id id ) { return _Objects_MP_Is_remote( id, &_Partition_Information ); } diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h index 7c789a204b..4b9255e635 100644 --- a/cpukit/include/rtems/rtems/ratemon.h +++ b/cpukit/include/rtems/rtems/ratemon.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 2017 Kuan-Hsun Chen * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * @@ -245,7 +245,8 @@ struct rtems_printer; * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * period. The number of periods available to the application is configured - * through the #CONFIGURE_MAXIMUM_PERIODS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_PERIODS application configuration + * option. * * @par Notes * @parblock @@ -269,7 +270,7 @@ struct rtems_printer; * cause the calling task to be preempted. * * * The number of periods available to the application is configured through - * the #CONFIGURE_MAXIMUM_PERIODS application configuration option. + * the @ref CONFIGURE_MAXIMUM_PERIODS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/ratemondata.h b/cpukit/include/rtems/rtems/ratemondata.h index f35fa7eb61..3c8077d156 100644 --- a/cpukit/include/rtems/rtems/ratemondata.h +++ b/cpukit/include/rtems/rtems/ratemondata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ * On-Line Applications Research Corporation (OAR). * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_RATEMONDATA_H @@ -71,10 +90,12 @@ typedef struct { /** This field is the object management portion of a Period instance. */ Objects_Control Object; +#if defined(RTEMS_SMP) /** * @brief Protects the rate monotonic period state. */ - ISR_LOCK_MEMBER( Lock ) + ISR_lock_Control Lock; +#endif /** This is the timer used to provide the unblocking mechanism. */ Watchdog_Control Timer; diff --git a/cpukit/include/rtems/rtems/ratemonimpl.h b/cpukit/include/rtems/rtems/ratemonimpl.h index d17c7fe4de..191e83f305 100644 --- a/cpukit/include/rtems/rtems/ratemonimpl.h +++ b/cpukit/include/rtems/rtems/ratemonimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -9,12 +11,29 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * COPYRIGHT (c) 2016 Kuan-Hsun Chen. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_RATEMONIMPL_H @@ -55,13 +74,13 @@ extern "C" { * This function allocates a period control block from * the inactive chain of free period control blocks. */ -RTEMS_INLINE_ROUTINE Rate_monotonic_Control *_Rate_monotonic_Allocate( void ) +static inline Rate_monotonic_Control *_Rate_monotonic_Allocate( void ) { return (Rate_monotonic_Control *) _Objects_Allocate( &_Rate_monotonic_Information ); } -RTEMS_INLINE_ROUTINE void _Rate_monotonic_Acquire_critical( +static inline void _Rate_monotonic_Acquire_critical( Rate_monotonic_Control *the_period, ISR_lock_Context *lock_context ) @@ -69,7 +88,7 @@ RTEMS_INLINE_ROUTINE void _Rate_monotonic_Acquire_critical( _ISR_lock_Acquire( &the_period->Lock, lock_context ); } -RTEMS_INLINE_ROUTINE void _Rate_monotonic_Release( +static inline void _Rate_monotonic_Release( Rate_monotonic_Control *the_period, ISR_lock_Context *lock_context ) @@ -77,7 +96,7 @@ RTEMS_INLINE_ROUTINE void _Rate_monotonic_Release( _ISR_lock_Release_and_ISR_enable( &the_period->Lock, lock_context ); } -RTEMS_INLINE_ROUTINE Rate_monotonic_Control *_Rate_monotonic_Get( +static inline Rate_monotonic_Control *_Rate_monotonic_Get( Objects_Id id, ISR_lock_Context *lock_context ) @@ -118,14 +137,14 @@ void _Rate_monotonic_Cancel( ISR_lock_Context *lock_context ); -RTEMS_INLINE_ROUTINE void _Rate_monotonic_Reset_min_time( +static inline void _Rate_monotonic_Reset_min_time( Timestamp_Control *min_time ) { _Timestamp_Set( min_time, 0x7fffffff, 0x7fffffff ); } -RTEMS_INLINE_ROUTINE void _Rate_monotonic_Reset_statistics( +static inline void _Rate_monotonic_Reset_statistics( Rate_monotonic_Control *the_period ) { diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h index 1e35344f7d..3d9c2bd8bc 100644 --- a/cpukit/include/rtems/rtems/region.h +++ b/cpukit/include/rtems/rtems/region.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassicRegion + * * @brief This header file defines the Region Manager API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -193,7 +195,8 @@ rtems_status_code rtems_region_get_segment_size( * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * region. The number of regions available to the application is configured - * through the #CONFIGURE_MAXIMUM_REGIONS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_REGIONS application configuration + * option. * * @retval ::RTEMS_INVALID_SIZE The ``page_size`` parameter was invalid. * @@ -217,7 +220,7 @@ rtems_status_code rtems_region_get_segment_size( * cause the calling task to be preempted. * * * The number of regions available to the application is configured through - * the #CONFIGURE_MAXIMUM_REGIONS application configuration option. + * the @ref CONFIGURE_MAXIMUM_REGIONS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/regiondata.h b/cpukit/include/rtems/rtems/regiondata.h index 5852f4cb45..28740d83f8 100644 --- a/cpukit/include/rtems/rtems/regiondata.h +++ b/cpukit/include/rtems/rtems/regiondata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_REGIONDATA_H diff --git a/cpukit/include/rtems/rtems/regionimpl.h b/cpukit/include/rtems/rtems/regionimpl.h index 85facea5e7..adb481f3e7 100644 --- a/cpukit/include/rtems/rtems/regionimpl.h +++ b/cpukit/include/rtems/rtems/regionimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_REGIONIMPL_H @@ -47,7 +66,7 @@ extern "C" { * This function allocates a region control block from * the inactive chain of free region control blocks. */ -RTEMS_INLINE_ROUTINE Region_Control *_Region_Allocate( void ) +static inline Region_Control *_Region_Allocate( void ) { return (Region_Control *) _Objects_Allocate( &_Region_Information ); } @@ -58,7 +77,7 @@ RTEMS_INLINE_ROUTINE Region_Control *_Region_Allocate( void ) * This routine frees a region control block to the * inactive chain of free region control blocks. */ -RTEMS_INLINE_ROUTINE void _Region_Free ( +static inline void _Region_Free ( Region_Control *the_region ) { @@ -66,7 +85,7 @@ RTEMS_INLINE_ROUTINE void _Region_Free ( _Objects_Free( &_Region_Information, &the_region->Object ); } -RTEMS_INLINE_ROUTINE Region_Control *_Region_Get_and_lock( Objects_Id id ) +static inline Region_Control *_Region_Get_and_lock( Objects_Id id ) { Region_Control *the_region; @@ -84,7 +103,7 @@ RTEMS_INLINE_ROUTINE Region_Control *_Region_Get_and_lock( Objects_Id id ) return NULL; } -RTEMS_INLINE_ROUTINE void _Region_Unlock( Region_Control *the_region ) +static inline void _Region_Unlock( Region_Control *the_region ) { (void) the_region; _RTEMS_Unlock_allocator(); @@ -97,7 +116,7 @@ RTEMS_INLINE_ROUTINE void _Region_Unlock( Region_Control *the_region ) * If successful, it returns the address of the allocated segment. * Otherwise, it returns NULL. */ -RTEMS_INLINE_ROUTINE void *_Region_Allocate_segment ( +static inline void *_Region_Allocate_segment ( Region_Control *the_region, uintptr_t size ) @@ -110,7 +129,7 @@ RTEMS_INLINE_ROUTINE void *_Region_Allocate_segment ( * * This function frees the_segment to the_region. */ -RTEMS_INLINE_ROUTINE bool _Region_Free_segment ( +static inline bool _Region_Free_segment ( Region_Control *the_region, void *the_segment ) diff --git a/cpukit/include/rtems/rtems/scheduler.h b/cpukit/include/rtems/rtems/scheduler.h new file mode 100644 index 0000000000..bec4932c6c --- /dev/null +++ b/cpukit/include/rtems/rtems/scheduler.h @@ -0,0 +1,551 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RTEMSImplClassicScheduler + * + * @brief This header file defines the main parts of the Scheduler Manager API. + */ + +/* + * Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: + * + * https://www.rtems.org/bugs.html + * + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: + * + * https://docs.rtems.org + */ + +/* Generated from spec:/rtems/scheduler/if/header */ + +#ifndef _RTEMS_RTEMS_SCHEDULER_H +#define _RTEMS_RTEMS_SCHEDULER_H + +#include <stddef.h> +#include <stdint.h> +#include <sys/cpuset.h> +#include <rtems/rtems/status.h> +#include <rtems/rtems/types.h> +#include <rtems/score/smp.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* Generated from spec:/rtems/scheduler/if/group */ + +/** + * @defgroup RTEMSAPIClassicScheduler Scheduler Manager + * + * @ingroup RTEMSAPIClassic + * + * @brief The scheduling concepts relate to the allocation of processing time + * for tasks. + * + * The concept of scheduling in real-time systems dictates the ability to + * provide an immediate response to specific external events, particularly the + * necessity of scheduling tasks to run within a specified time limit after the + * occurrence of an event. For example, software embedded in life-support + * systems used to monitor hospital patients must take instant action if a + * change in the patient’s status is detected. + * + * The component of RTEMS responsible for providing this capability is + * appropriately called the scheduler. The scheduler’s sole purpose is to + * allocate the all important resource of processor time to the various tasks + * competing for attention. + */ + +/* Generated from spec:/rtems/scheduler/if/ident */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the object name. + * + * @param name is the scheduler name to look up. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * This directive obtains a scheduler identifier associated with the scheduler + * name specified in ``name``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the + * name. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @par Notes + * @parblock + * The scheduler name is determined by the scheduler configuration. + * + * The scheduler identifier is used with other scheduler related directives to + * access the scheduler. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the processor index. + * + * @param cpu_index is the processor index to identify the scheduler. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The processor index was invalid. + * + * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the + * corresponding processor was not owned by a scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident_by_processor( + uint32_t cpu_index, + rtems_id *id +); + +/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Identifies a scheduler by the processor set. + * + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. The size shall be positive. + * + * @param cpuset is the pointer to a cpu_set_t. The referenced processor set + * will be used to identify the scheduler. + * + * @param[out] id is the pointer to an ::rtems_id object. When the directive + * call is successful, the identifier of the scheduler will be stored in this + * object. + * + * The scheduler is selected according to the highest numbered online processor + * in the specified processor set. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid. + * + * @retval ::RTEMS_INVALID_NAME The processor set contained no online + * processor. + * + * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the + * highest numbered online processor in the processor set was not owned by a + * scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_ident_by_processor_set( + size_t cpusetsize, + const cpu_set_t *cpuset, + rtems_id *id +); + +/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Gets the maximum task priority of the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param[out] priority is the pointer to an ::rtems_task_priority object. + * When the directive the maximum priority of the scheduler will be stored in + * this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_get_maximum_priority( + rtems_id scheduler_id, + rtems_task_priority *priority +); + +/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Maps a Classic API task priority to the corresponding POSIX thread + * priority. + * + * @param scheduler_id is the scheduler identifier. + * + * @param priority is the Classic API task priority to map. + * + * @param[out] posix_priority is the pointer to an ``int`` object. When the + * directive call is successful, the POSIX thread priority value + * corresponding to the specified Classic API task priority value will be + * stored in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_map_priority_to_posix( + rtems_id scheduler_id, + rtems_task_priority priority, + int *posix_priority +); + +/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Maps a POSIX thread priority to the corresponding Classic API task + * priority. + * + * @param scheduler_id is the scheduler identifier. + * + * @param posix_priority is the POSIX thread priority to map. + * + * @param[out] priority is the pointer to an ::rtems_task_priority object. + * When the directive call is successful, the Classic API task priority value + * corresponding to the specified POSIX thread priority value will be stored + * in this object. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_map_priority_from_posix( + rtems_id scheduler_id, + int posix_priority, + rtems_task_priority *priority +); + +/* Generated from spec:/rtems/scheduler/if/get-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Returns the index of the current processor. + * + * Where the system was built with SMP support disabled, this directive + * evaluates to a compile time constant of zero. + * + * Where the system was built with SMP support enabled, this directive returns + * the index of the current processor. The set of processor indices is the + * range of integers starting with zero up to + * rtems_scheduler_get_processor_maximum() minus one. + * + * @return Returns the index of the current processor. + * + * @par Notes + * Outside of sections with disabled thread dispatching the current processor + * index may change after every instruction since the thread may migrate from + * one processor to another. Sections with disabled interrupts are sections + * with thread dispatching disabled. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +uint32_t rtems_scheduler_get_processor( void ); + +/* Generated from spec:/rtems/scheduler/if/get-processor-macro */ +#define rtems_scheduler_get_processor() _SMP_Get_current_processor() + +/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Returns the processor maximum supported by the system. + * + * Where the system was built with SMP support disabled, this directive + * evaluates to a compile time constant of one. + * + * Where the system was built with SMP support enabled, this directive returns + * the minimum of the processors (physically or virtually) available at the + * target and the configured processor maximum (see @ref + * CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from + * processor index zero to the last processor index (which is the processor + * maximum minus one) may be configured to be used by a scheduler or may be + * online (online processors have a scheduler assigned). + * + * @return Returns the processor maximum supported by the system. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +uint32_t rtems_scheduler_get_processor_maximum( void ); + +/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */ +#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() + +/* Generated from spec:/rtems/scheduler/if/get-processor-set */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Gets the set of processors owned by the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpusetsize is the size of the processor set referenced by ``cpuset`` + * in bytes. + * + * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive + * call is successful, the processor set of the scheduler will be stored in + * this object. A set bit in the processor set means that the corresponding + * processor is owned by the scheduler, otherwise the bit is cleared. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for + * the set of processors owned by the scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_get_processor_set( + rtems_id scheduler_id, + size_t cpusetsize, + cpu_set_t *cpuset +); + +/* Generated from spec:/rtems/scheduler/if/add-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Adds the processor to the set of processors owned by the scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpu_index is the index of the processor to add. + * + * This directive adds the processor specified by the ``cpu_index`` to the + * scheduler specified by ``scheduler_id``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used + * by the application. + * + * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by + * the application, however, it was not online. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a + * scheduler. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_add_processor( + rtems_id scheduler_id, + uint32_t cpu_index +); + +/* Generated from spec:/rtems/scheduler/if/remove-processor */ + +/** + * @ingroup RTEMSAPIClassicScheduler + * + * @brief Removes the processor from the set of processors owned by the + * scheduler. + * + * @param scheduler_id is the scheduler identifier. + * + * @param cpu_index is the index of the processor to remove. + * + * This directive removes the processor specified by the ``cpu_index`` from the + * scheduler specified by ``scheduler_id``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the + * identifier specified by ``scheduler_id``. + * + * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was required by at least one + * non-idle task that used the scheduler as its home scheduler. + * + * @retval ::RTEMS_RESOURCE_IN_USE The processor was the last processor owned + * by the scheduler and there was at least one task that used the scheduler + * as a helping scheduler. + * + * @par Notes + * Removing a processor from a scheduler is a complex operation that involves + * all tasks of the system. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock + */ +rtems_status_code rtems_scheduler_remove_processor( + rtems_id scheduler_id, + uint32_t cpu_index +); + +#ifdef __cplusplus +} +#endif + +#endif /* _RTEMS_RTEMS_SCHEDULER_H */ diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h index 31156b5e43..73e725f82d 100644 --- a/cpukit/include/rtems/rtems/sem.h +++ b/cpukit/include/rtems/rtems/sem.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -203,13 +203,13 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * semaphore. The number of semaphores available to the application is - * configured through the #CONFIGURE_MAXIMUM_SEMAPHORES application + * configured through the @ref CONFIGURE_MAXIMUM_SEMAPHORES application * configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global semaphore. The number * of global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @retval ::RTEMS_INVALID_PRIORITY The ``priority_ceiling`` parameter was * invalid. @@ -243,7 +243,7 @@ extern "C" { * message to remote nodes. This may preempt the calling task. * * * The number of semaphores available to the application is configured - * through the #CONFIGURE_MAXIMUM_SEMAPHORES application configuration + * through the @ref CONFIGURE_MAXIMUM_SEMAPHORES application configuration * option. * * * Where the object class corresponding to the directive is configured to use @@ -251,8 +251,8 @@ extern "C" { * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_semaphore_create( diff --git a/cpukit/include/rtems/rtems/semdata.h b/cpukit/include/rtems/rtems/semdata.h index 2612f1a902..88400d3602 100644 --- a/cpukit/include/rtems/rtems/semdata.h +++ b/cpukit/include/rtems/rtems/semdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,9 +13,26 @@ * COPYRIGHT (c) 1989-2008, 2016. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_SEMDATA_H diff --git a/cpukit/include/rtems/rtems/semimpl.h b/cpukit/include/rtems/rtems/semimpl.h index bc0b4d3a9d..5164c593f7 100644 --- a/cpukit/include/rtems/rtems/semimpl.h +++ b/cpukit/include/rtems/rtems/semimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_SEMIMPL_H @@ -59,7 +78,7 @@ typedef enum { SEMAPHORE_DISCIPLINE_FIFO } Semaphore_Discipline; -RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Get_flags( +static inline uintptr_t _Semaphore_Get_flags( const Semaphore_Control *the_semaphore ) { @@ -67,7 +86,7 @@ RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Get_flags( return (uintptr_t) the_semaphore->Object.Node.previous; } -RTEMS_INLINE_ROUTINE void _Semaphore_Set_flags( +static inline void _Semaphore_Set_flags( Semaphore_Control *the_semaphore, uintptr_t flags ) @@ -76,14 +95,14 @@ RTEMS_INLINE_ROUTINE void _Semaphore_Set_flags( the_semaphore->Object.Node.previous = (Chain_Node *) flags; } -RTEMS_INLINE_ROUTINE Semaphore_Variant _Semaphore_Get_variant( +static inline Semaphore_Variant _Semaphore_Get_variant( uintptr_t flags ) { return (Semaphore_Variant) ( flags & 0x7 ); } -RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Set_variant( +static inline uintptr_t _Semaphore_Set_variant( uintptr_t flags, Semaphore_Variant variant ) @@ -91,14 +110,14 @@ RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Set_variant( return flags | variant; } -RTEMS_INLINE_ROUTINE Semaphore_Discipline _Semaphore_Get_discipline( +static inline Semaphore_Discipline _Semaphore_Get_discipline( uintptr_t flags ) { return (Semaphore_Discipline) ( ( flags >> 3 ) & 0x1 ); } -RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Set_discipline( +static inline uintptr_t _Semaphore_Set_discipline( uintptr_t flags, Semaphore_Discipline discipline ) @@ -107,20 +126,20 @@ RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Set_discipline( } #if defined(RTEMS_MULTIPROCESSING) -RTEMS_INLINE_ROUTINE bool _Semaphore_Is_global( +static inline bool _Semaphore_Is_global( uintptr_t flags ) { return ( flags & 0x10 ) != 0; } -RTEMS_INLINE_ROUTINE uintptr_t _Semaphore_Make_global( uintptr_t flags ) +static inline uintptr_t _Semaphore_Make_global( uintptr_t flags ) { return flags | 0x10; } #endif -RTEMS_INLINE_ROUTINE const Thread_queue_Operations *_Semaphore_Get_operations( +static inline const Thread_queue_Operations *_Semaphore_Get_operations( uintptr_t flags ) { @@ -144,7 +163,7 @@ RTEMS_INLINE_ROUTINE const Thread_queue_Operations *_Semaphore_Get_operations( * This function allocates a semaphore control block from * the inactive chain of free semaphore control blocks. */ -RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Allocate( void ) +static inline Semaphore_Control *_Semaphore_Allocate( void ) { return (Semaphore_Control *) _Objects_Allocate( &_Semaphore_Information ); } @@ -156,14 +175,14 @@ RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Allocate( void ) * This routine frees a semaphore control block to the * inactive chain of free semaphore control blocks. */ -RTEMS_INLINE_ROUTINE void _Semaphore_Free ( +static inline void _Semaphore_Free ( Semaphore_Control *the_semaphore ) { _Objects_Free( &_Semaphore_Information, &the_semaphore->Object ); } -RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get( +static inline Semaphore_Control *_Semaphore_Get( Objects_Id id, Thread_queue_Context *queue_context ) diff --git a/cpukit/include/rtems/rtems/semmp.h b/cpukit/include/rtems/rtems/semmp.h index e69d338ddd..7fbf5c9046 100644 --- a/cpukit/include/rtems/rtems/semmp.h +++ b/cpukit/include/rtems/rtems/semmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_SEMMP_H @@ -64,7 +83,7 @@ typedef struct { Objects_Id proxy_id; } Semaphore_MP_Packet; -RTEMS_INLINE_ROUTINE bool _Semaphore_MP_Is_remote( Objects_Id id ) +static inline bool _Semaphore_MP_Is_remote( Objects_Id id ) { return _Objects_MP_Is_remote( id, &_Semaphore_Information ); } diff --git a/cpukit/include/rtems/rtems/signal.h b/cpukit/include/rtems/rtems/signal.h index 9272f807bc..fb5254f5d9 100644 --- a/cpukit/include/rtems/rtems/signal.h +++ b/cpukit/include/rtems/rtems/signal.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/signalimpl.h b/cpukit/include/rtems/rtems/signalimpl.h index db1ff71620..1a24580dfb 100644 --- a/cpukit/include/rtems/rtems/signalimpl.h +++ b/cpukit/include/rtems/rtems/signalimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_SIGNALIMPL_H diff --git a/cpukit/include/rtems/rtems/signalmp.h b/cpukit/include/rtems/rtems/signalmp.h index 8e1fb06003..bdd27d9be7 100644 --- a/cpukit/include/rtems/rtems/signalmp.h +++ b/cpukit/include/rtems/rtems/signalmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_SIGNALMP_H diff --git a/cpukit/include/rtems/rtems/status.h b/cpukit/include/rtems/rtems/status.h index 872bb9b2b3..92a8b03c09 100644 --- a/cpukit/include/rtems/rtems/status.h +++ b/cpukit/include/rtems/rtems/status.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file provides the status codes of Classic API directives * and support functions. */ /* - * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/statusimpl.h b/cpukit/include/rtems/rtems/statusimpl.h index 8b63eca742..2ea12d9f6c 100644 --- a/cpukit/include/rtems/rtems/statusimpl.h +++ b/cpukit/include/rtems/rtems/statusimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_STATUSIMPL_H @@ -44,14 +63,14 @@ extern "C" { * @{ */ -RTEMS_INLINE_ROUTINE rtems_status_code _Status_Get( +static inline rtems_status_code _Status_Get( Status_Control status ) { return (rtems_status_code) STATUS_GET_CLASSIC( status ); } -RTEMS_INLINE_ROUTINE rtems_status_code _Status_Get_after_wait( +static inline rtems_status_code _Status_Get_after_wait( const Thread_Control *executing ) { diff --git a/cpukit/include/rtems/rtems/support.h b/cpukit/include/rtems/rtems/support.h index 60e090ccec..bb2e6e3633 100644 --- a/cpukit/include/rtems/rtems/support.h +++ b/cpukit/include/rtems/rtems/support.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file defines support services of the API. */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -113,8 +115,8 @@ static inline bool rtems_is_name_valid( rtems_name name ) * value. * * @par Notes - * The number of clock ticks per second is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of clock ticks per second is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock @@ -164,8 +166,8 @@ static inline bool rtems_is_name_valid( rtems_name name ) * @return Returns the number of clock ticks for the milliseconds value. * * @par Notes - * The number of clock ticks per second is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of clock ticks per second is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/taskmp.h b/cpukit/include/rtems/rtems/taskmp.h index d991df0c51..5dfe56d9d0 100644 --- a/cpukit/include/rtems/rtems/taskmp.h +++ b/cpukit/include/rtems/rtems/taskmp.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_TASKMP_H diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index 8e87bfd14a..84dd646fe7 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -9,8 +9,8 @@ */ /* - * Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) - * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -68,7 +68,6 @@ #include <rtems/score/context.h> #include <rtems/score/cpu.h> #include <rtems/score/object.h> -#include <rtems/score/smp.h> #include <rtems/score/stack.h> #include <rtems/score/watchdogticks.h> @@ -76,29 +75,6 @@ extern "C" { #endif -/* Generated from spec:/rtems/scheduler/if/group */ - -/** - * @defgroup RTEMSAPIClassicScheduler Scheduler Manager - * - * @ingroup RTEMSAPIClassic - * - * @brief The scheduling concepts relate to the allocation of processing time - * for tasks. - * - * The concept of scheduling in real-time systems dictates the ability to - * provide an immediate response to specific external events, particularly the - * necessity of scheduling tasks to run within a specified time limit after the - * occurrence of an event. For example, software embedded in life-support - * systems used to monitor hospital patients must take instant action if a - * change in the patient’s status is detected. - * - * The component of RTEMS responsible for providing this capability is - * appropriately called the scheduler. The scheduler’s sole purpose is to - * allocate the all important resource of processor time to the various tasks - * competing for attention. - */ - /* Generated from spec:/rtems/task/if/group */ /** @@ -184,8 +160,8 @@ typedef struct { * alignment of an application executable. * * The application may configure the maximum thread-local storage size for all - * threads explicitly through the #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE - * configuration option. + * threads explicitly through the @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE configuration option. */ size_t maximum_thread_local_storage_size; @@ -258,7 +234,7 @@ typedef void rtems_task; /** * @ingroup RTEMSAPIClassicTasks * - * @brief This type defines the entry point of an RTEMS task. + * @brief This type defines the task entry point of an RTEMS task. */ typedef rtems_task ( *rtems_task_entry )( rtems_task_argument ); @@ -307,6 +283,25 @@ typedef struct { rtems_task_argument argument; } rtems_initialization_tasks_table; +/* Generated from spec:/rtems/task/if/maximum-priority-impl */ + +/** + * @ingroup RTEMSImplClassicTask + * + * @brief Returns the maximum priority of the scheduler with index zero. + */ +rtems_task_priority _RTEMS_Maximum_priority( void ); + +/* Generated from spec:/rtems/task/if/maximum-priority */ + +/** + * @ingroup RTEMSAPIClassicTasks + * + * @brief This runtime constant represents the lowest (least important) task + * priority of the scheduler with index zero. + */ +#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() + /* Generated from spec:/rtems/task/if/minimum-priority */ /** @@ -330,8 +325,8 @@ typedef struct { * risk of blown stacks for most user applications. Using this constant when * specifying the task stack size, indicates that the stack size will be at * least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured - * minimum stack size (see #CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger than - * the recommended minimum, then it will be used. + * minimum stack size (see @ref CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger + * than the recommended minimum, then it will be used. */ #define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE @@ -425,477 +420,6 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); */ #define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT -/* Generated from spec:/score/if/maximum-priority */ - -/** - * @brief Returns the maximum priority of the scheduler with index zero. - */ -rtems_task_priority _RTEMS_Maximum_priority( void ); - -/* Generated from spec:/rtems/task/if/maximum-priority */ - -/** - * @ingroup RTEMSAPIClassicTasks - * - * @brief This constant variable provides the lowest (least important) task - * priority of the first configured scheduler. - */ -#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority() - -/* Generated from spec:/rtems/scheduler/if/ident */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the object name. - * - * @param name is the scheduler name to look up. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * This directive obtains a scheduler identifier associated with the scheduler - * name specified in ``name``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the - * name. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @par Notes - * @parblock - * The scheduler name is determined by the scheduler configuration. - * - * The scheduler identifier is used with other scheduler related directives to - * access the scheduler. - * @endparblock - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id ); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor index. - * - * @param cpu_index is the processor index to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_NAME The processor index was invalid. - * - * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the - * corresponding processor was not owned by a scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor( - uint32_t cpu_index, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Identifies a scheduler by the processor set. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. The size shall be positive. - * - * @param cpuset is the pointer to a cpu_set_t. The referenced processor set - * will be used to identify the scheduler. - * - * @param[out] id is the pointer to an ::rtems_id object. When the directive - * call is successful, the identifier of the scheduler will be stored in this - * object. - * - * The scheduler is selected according to the highest numbered online processor - * in the specified processor set. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid. - * - * @retval ::RTEMS_INVALID_NAME The processor set contained no online - * processor. - * - * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the - * highest numbered online processor in the processor set was not owned by a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_ident_by_processor_set( - size_t cpusetsize, - const cpu_set_t *cpuset, - rtems_id *id -); - -/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the maximum task priority of the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive the maximum priority of the scheduler will be stored in - * this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_maximum_priority( - rtems_id scheduler_id, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a Classic API task priority to the corresponding POSIX thread - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param priority is the Classic API task priority to map. - * - * @param[out] posix_priority is the pointer to an ``int`` object. When the - * directive call is successful, the POSIX thread priority value - * corresponding to the specified Classic API task priority value will be - * stored in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_to_posix( - rtems_id scheduler_id, - rtems_task_priority priority, - int *posix_priority -); - -/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Maps a POSIX thread priority to the corresponding Classic API task - * priority. - * - * @param scheduler_id is the scheduler identifier. - * - * @param posix_priority is the POSIX thread priority to map. - * - * @param[out] priority is the pointer to an ::rtems_task_priority object. - * When the directive call is successful, the Classic API task priority value - * corresponding to the specified POSIX thread priority value will be stored - * in this object. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_map_priority_from_posix( - rtems_id scheduler_id, - int posix_priority, - rtems_task_priority *priority -); - -/* Generated from spec:/rtems/scheduler/if/get-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the index of the current processor. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of zero. - * - * Where the system was built with SMP support enabled, this directive returns - * the index of the current processor. The set of processor indices is the - * range of integers starting with zero up to - * rtems_scheduler_get_processor_maximum() minus one. - * - * @return Returns the index of the current processor. - * - * @par Notes - * Outside of sections with disabled thread dispatching the current processor - * index may change after every instruction since the thread may migrate from - * one processor to another. Sections with disabled interrupts are sections - * with thread dispatching disabled. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-macro */ -#define rtems_scheduler_get_processor() _SMP_Get_current_processor() - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Returns the processor maximum supported by the system. - * - * Where the system was built with SMP support disabled, this directive - * evaluates to a compile time constant of one. - * - * Where the system was built with SMP support enabled, this directive returns - * the minimum of the processors (physically or virtually) available at the - * target and the configured processor maximum (see - * #CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from - * processor index zero to the last processor index (which is the processor - * maximum minus one) may be configured to be used by a scheduler or may be - * online (online processors have a scheduler assigned). - * - * @return Returns the processor maximum supported by the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -uint32_t rtems_scheduler_get_processor_maximum( void ); - -/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */ -#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum() - -/* Generated from spec:/rtems/scheduler/if/get-processor-set */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Gets the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpusetsize is the size of the processor set referenced by ``cpuset`` - * in bytes. - * - * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive - * call is successful, the processor set of the scheduler will be stored in - * this object. A set bit in the processor set means that the corresponding - * processor is owned by the scheduler, otherwise the bit is cleared. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for - * the set of processors owned by the scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within any runtime context. - * - * * The directive will not cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_get_processor_set( - rtems_id scheduler_id, - size_t cpusetsize, - cpu_set_t *cpuset -); - -/* Generated from spec:/rtems/scheduler/if/add-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Adds the processor to the set of processors owned by the scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to add. - * - * This directive adds the processor specified by the ``cpu_index`` to the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used - * by the application. - * - * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by - * the application, however, it was not online. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a - * scheduler. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_add_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - -/* Generated from spec:/rtems/scheduler/if/remove-processor */ - -/** - * @ingroup RTEMSAPIClassicScheduler - * - * @brief Removes the processor from the set of processors owned by the - * scheduler. - * - * @param scheduler_id is the scheduler identifier. - * - * @param cpu_index is the index of the processor to remove. - * - * This directive removes the processor specified by the ``cpu_index`` from the - * scheduler specified by ``scheduler_id``. - * - * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. - * - * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the - * identifier specified by ``scheduler_id``. - * - * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was required by at least one - * non-idle task that used the scheduler as its home scheduler. - * - * @retval ::RTEMS_RESOURCE_IN_USE The processor was the last processor owned - * by the scheduler and there was at least one task that used the scheduler - * as a helping scheduler. - * - * @par Notes - * Removing a processor from a scheduler is a complex operation that involves - * all tasks of the system. - * - * @par Constraints - * @parblock - * The following constraints apply to this directive: - * - * * The directive may be called from within device driver initialization - * context. - * - * * The directive may be called from within task context. - * - * * The directive may obtain and release the object allocator mutex. This may - * cause the calling task to be preempted. - * @endparblock - */ -rtems_status_code rtems_scheduler_remove_processor( - rtems_id scheduler_id, - uint32_t cpu_index -); - /* Generated from spec:/rtems/task/if/create */ /** @@ -923,15 +447,15 @@ rtems_status_code rtems_scheduler_remove_processor( * task with other task related directives. * * The **initial priority** of the task is specified in ``initial_priority``. - * The scheduler of the created task is the scheduler of the calling task at - * some point during the task creation. The initial task priority specified in - * ``initial_priority`` shall be valid for this scheduler. + * The home scheduler of the created task is the home scheduler of the calling + * task at some time point during the task creation. The initial task priority + * specified in ``initial_priority`` shall be valid for this scheduler. * * The **stack size** of the task is specified in ``stack_size``. If the * requested stack size is less than the configured minimum stack size, then * RTEMS will use the configured minimum as the stack size for this task. The - * configured minimum stack size is defined by the - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In + * configured minimum stack size is defined by the @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In * addition to being able to specify the task stack size as a integer, there * are two constants which may be specified: * @@ -1059,12 +583,12 @@ rtems_status_code rtems_scheduler_remove_processor( * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * task. The number of tasks available to the application is configured - * through the #CONFIGURE_MAXIMUM_TASKS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global task. The number of - * global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * global objects available to the application is configured through the @ref + * CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task * storage area. The task storage area contains the task stack, the @@ -1091,7 +615,7 @@ rtems_status_code rtems_scheduler_remove_processor( * The task stack size shall account for an target processor dependent * interrupt stack frame which may be placed on the stack of the interrupted * task while servicing an interrupt. The stack checker may be used to monitor - * the stack usage, see #CONFIGURE_STACK_CHECKER_ENABLED. + * the stack usage, see @ref CONFIGURE_STACK_CHECKER_ENABLED. * * For control and maintenance of the task, RTEMS allocates a TCB from the * local TCB free pool and initializes it. @@ -1120,15 +644,15 @@ rtems_status_code rtems_scheduler_remove_processor( * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_create( @@ -1147,7 +671,8 @@ rtems_status_code rtems_task_create( * * @brief Constructs a task from the specified task configuration. * - * @param config is the task configuration. + * @param config is the pointer to an rtems_task_config object. It configures + * the task. * * @param[out] id is the pointer to an ::rtems_id object. When the directive * call is successful, the identifier of the constructed task will be stored @@ -1166,12 +691,13 @@ rtems_status_code rtems_task_create( * @retval ::RTEMS_INVALID_SIZE The thread-local storage size is greater than * the maximum thread-local storage size specified in the task configuration. * The thread-local storage size is determined by the thread-local variables - * used by the application and #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. + * used by the application and @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. * * @retval ::RTEMS_INVALID_SIZE The task storage area was too small to provide - * a task stack of the configured minimum size, see - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the - * task stack, the thread-local storage, and the floating-point context on + * a task stack of the configured minimum size, see @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the task + * stack, the thread-local storage, and the floating-point context on * architectures with a separate floating-point context. * * @retval ::RTEMS_TOO_MANY There was no inactive task object available to @@ -1210,13 +736,13 @@ rtems_status_code rtems_task_create( * memory allocators. This can simplify the application architecture as well * as any analysis that may be required. * - * The stack space estimate done by <rtems/confdefs.h> assumes that all tasks - * are created by rtems_task_create(). The estimate can be adjusted to take - * user-provided task storage areas into account through the - * #CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application - * configuration option. + * The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all + * tasks are created by rtems_task_create(). The estimate can be adjusted to + * take user-provided task storage areas into account through the @ref + * CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application configuration + * option. * - * The #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by + * The @ref CONFIGURE_MAXIMUM_TASKS should include tasks constructed by * rtems_task_construct(). * @endparblock * @@ -1236,15 +762,15 @@ rtems_status_code rtems_task_create( * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_construct( @@ -1371,8 +897,8 @@ rtems_id rtems_task_self( void ); * * This directive readies the task, specified by ``id``, for execution based on * the priority and execution mode specified when the task was created. The - * entry point of the task is given in ``entry_point``. The task's entry point - * argument is contained in ``argument``. + * task entry point of the task is given in ``entry_point``. The task's entry + * point argument is contained in ``argument``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -1509,13 +1035,25 @@ rtems_status_code rtems_task_restart( * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within * interrupt context. * + * @retval ::RTEMS_INCORRECT_STATE The task termination procedure was started, + * however, waiting for the terminating task would have resulted in a + * deadlock. + * * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. * * @par Notes * @parblock - * RTEMS stops the execution of the task and reclaims the stack memory, any - * allocated delay or timeout timers, the TCB, and, if the task is - * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly + * The task deletion is done in several steps. Firstly, the task is marked as + * terminating. While the task life of the terminating task is protected, it + * executes normally until it disables the task life protection or it deletes + * itself. A terminating task will eventually stop its normal execution and + * start its termination procedure. The procedure executes in the context of + * the terminating task. The task termination procedure involves the + * destruction of POSIX key values and running the task termination user + * extensions. Once complete the execution of the task is stopped and + * task-specific resources are reclaimed by the system, such as the stack + * memory, any allocated delay or timeout timers, the TCB, and, if the task is + * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly * does not reclaim the following resources: region segments, partition * buffers, semaphores, timers, or rate monotonic periods. * @@ -1527,10 +1065,12 @@ rtems_status_code rtems_task_restart( * resources and delete itself by restarting it with a special argument or by * sending it a message, an event, or a signal. * - * Deletion of the current task (#RTEMS_SELF) will force RTEMS to select + * Deletion of the calling task (#RTEMS_SELF) will force RTEMS to select * another task to execute. * - * The TCB for the deleted task is reclaimed by RTEMS. + * When a task deletes another task, the calling task waits until the task + * termination procedure of the task being deleted has completed. The + * terminating task inherits the eligible priorities of the calling task. * * When a global task is deleted, the task identifier must be transmitted to * every node in the system for deletion from the local copy of the global @@ -2004,15 +1544,16 @@ rtems_status_code rtems_task_mode( /** * @ingroup RTEMSAPIClassicTasks * - * @brief Wakes up after an interval in clock ticks or yields the processor. + * @brief Wakes up after a count of clock ticks have occurred or yields the + * processor. * - * @param ticks is the interval in clock ticks to delay the task or + * @param ticks is the count of clock ticks to delay the task or * #RTEMS_YIELD_PROCESSOR to yield the processor. * - * This directive blocks the calling task for the specified ``ticks`` of clock - * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the - * requested interval has elapsed, the task is made ready. The clock tick - * directives automatically updates the delay period. The calling task may + * This directive blocks the calling task for the specified ``ticks`` count of + * clock ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the + * requested count of ticks have occurred, the task is made ready. The clock + * tick directives automatically update the delay period. The calling task may * give up the processor and remain in the ready state by specifying a value of * #RTEMS_YIELD_PROCESSOR in ``ticks``. * @@ -2021,7 +1562,11 @@ rtems_status_code rtems_task_mode( * @par Notes * Setting the system date and time with the rtems_clock_set() directive and * similar directives which set CLOCK_REALTIME have no effect on a - * rtems_task_wake_after() blocked task. + * rtems_task_wake_after() blocked task. The delay until first clock tick will + * never be a whole clock tick interval since this directive will never execute + * exactly on a clock tick. Applications requiring use of a clock + * (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make use + * of clock_nanosleep(). * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/tasksdata.h b/cpukit/include/rtems/rtems/tasksdata.h index fb15453e65..1f4a8c83a5 100644 --- a/cpukit/include/rtems/rtems/tasksdata.h +++ b/cpukit/include/rtems/rtems/tasksdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -13,9 +15,26 @@ * COPYRIGHT (c) 1989-2014. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_TASKSDATA_H diff --git a/cpukit/include/rtems/rtems/tasksimpl.h b/cpukit/include/rtems/rtems/tasksimpl.h index 62a618b635..8c87cfc93b 100644 --- a/cpukit/include/rtems/rtems/tasksimpl.h +++ b/cpukit/include/rtems/rtems/tasksimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -10,9 +12,26 @@ /* COPYRIGHT (c) 1989-2014. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_TASKSIMPL_H @@ -56,7 +75,7 @@ rtems_status_code _RTEMS_tasks_Create( RTEMS_tasks_Prepare_stack prepare_stack ); -RTEMS_INLINE_ROUTINE Thread_Control *_RTEMS_tasks_Allocate(void) +static inline Thread_Control *_RTEMS_tasks_Allocate(void) { _Objects_Allocator_lock(); @@ -80,7 +99,7 @@ RTEMS_INLINE_ROUTINE Thread_Control *_RTEMS_tasks_Allocate(void) * * @return The corresponding SuperCore priority. */ -RTEMS_INLINE_ROUTINE Priority_Control _RTEMS_Priority_To_core( +static inline Priority_Control _RTEMS_Priority_To_core( const Scheduler_Control *scheduler, rtems_task_priority priority, bool *valid @@ -100,7 +119,7 @@ RTEMS_INLINE_ROUTINE Priority_Control _RTEMS_Priority_To_core( * * @return The corresponding RTEMS API priority. */ -RTEMS_INLINE_ROUTINE rtems_task_priority _RTEMS_Priority_From_core( +static inline rtems_task_priority _RTEMS_Priority_From_core( const Scheduler_Control *scheduler, Priority_Control priority ) @@ -111,6 +130,14 @@ RTEMS_INLINE_ROUTINE rtems_task_priority _RTEMS_Priority_From_core( /**@}*/ +/** + * @defgroup RTEMSImplClassicScheduler Scheduler Manager + * + * @ingroup RTEMSImplClassic + * + * @brief This group contains the Scheduler Manager implementation. + */ + #if defined(RTEMS_MULTIPROCESSING) #include <rtems/rtems/taskmp.h> #endif diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h index 0f13c04bda..6af56c1576 100644 --- a/cpukit/include/rtems/rtems/timer.h +++ b/cpukit/include/rtems/rtems/timer.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -284,7 +284,8 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * timer. The number of timers available to the application is configured - * through the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_TIMERS application configuration + * option. * * @par Notes * @parblock @@ -308,7 +309,7 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * cause the calling task to be preempted. * * * The number of timers available to the application is configured through - * the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_TIMERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS @@ -600,7 +601,7 @@ rtems_status_code rtems_timer_fire_when( * * The directive may be called from within task context. * * * The number of timers available to the application is configured through - * the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_TIMERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/timerdata.h b/cpukit/include/rtems/rtems/timerdata.h index 2a7cc03cb1..c66659fe4a 100644 --- a/cpukit/include/rtems/rtems/timerdata.h +++ b/cpukit/include/rtems/rtems/timerdata.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,11 +13,28 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2009, 2016 embedded brains GmbH. + * Copyright (C) 2009, 2016 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_TIMERDATA_H diff --git a/cpukit/include/rtems/rtems/timerimpl.h b/cpukit/include/rtems/rtems/timerimpl.h index 8d245d7e5b..5941616d61 100644 --- a/cpukit/include/rtems/rtems/timerimpl.h +++ b/cpukit/include/rtems/rtems/timerimpl.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -11,11 +13,28 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_RTEMS_TIMER_INL @@ -61,7 +80,7 @@ extern Timer_server_Control *volatile _Timer_server; * This function allocates a timer control block from * the inactive chain of free timer control blocks. */ -RTEMS_INLINE_ROUTINE Timer_Control *_Timer_Allocate( void ) +static inline Timer_Control *_Timer_Allocate( void ) { return (Timer_Control *) _Objects_Allocate( &_Timer_Information ); } @@ -72,14 +91,14 @@ RTEMS_INLINE_ROUTINE Timer_Control *_Timer_Allocate( void ) * This routine frees a timer control block to the * inactive chain of free timer control blocks. */ -RTEMS_INLINE_ROUTINE void _Timer_Free ( +static inline void _Timer_Free ( Timer_Control *the_timer ) { _Objects_Free( &_Timer_Information, &the_timer->Object ); } -RTEMS_INLINE_ROUTINE Timer_Control *_Timer_Get( +static inline Timer_Control *_Timer_Get( Objects_Id id, ISR_lock_Context *lock_context ) @@ -91,7 +110,7 @@ RTEMS_INLINE_ROUTINE Timer_Control *_Timer_Get( ); } -RTEMS_INLINE_ROUTINE Per_CPU_Control *_Timer_Acquire_critical( +static inline Per_CPU_Control *_Timer_Acquire_critical( Timer_Control *the_timer, ISR_lock_Context *lock_context ) @@ -104,7 +123,7 @@ RTEMS_INLINE_ROUTINE Per_CPU_Control *_Timer_Acquire_critical( return cpu; } -RTEMS_INLINE_ROUTINE void _Timer_Release( +static inline void _Timer_Release( Per_CPU_Control *cpu, ISR_lock_Context *lock_context ) @@ -113,7 +132,7 @@ RTEMS_INLINE_ROUTINE void _Timer_Release( _ISR_lock_ISR_enable( lock_context ); } -RTEMS_INLINE_ROUTINE bool _Timer_Is_interval_class( +static inline bool _Timer_Is_interval_class( Timer_Classes the_class ) { @@ -123,7 +142,7 @@ RTEMS_INLINE_ROUTINE bool _Timer_Is_interval_class( return ( the_class & mask ) == TIMER_CLASS_BIT_NOT_DORMANT; } -RTEMS_INLINE_ROUTINE bool _Timer_Is_on_task_class( +static inline bool _Timer_Is_on_task_class( Timer_Classes the_class ) { @@ -133,14 +152,14 @@ RTEMS_INLINE_ROUTINE bool _Timer_Is_on_task_class( return ( the_class & mask ) == mask; } -RTEMS_INLINE_ROUTINE Per_CPU_Watchdog_index _Timer_Watchdog_header_index( +static inline Per_CPU_Watchdog_index _Timer_Watchdog_header_index( Timer_Classes the_class ) { return (Per_CPU_Watchdog_index) ( the_class & TIMER_CLASS_BIT_TIME_OF_DAY ); } -RTEMS_INLINE_ROUTINE Watchdog_Interval _Timer_Get_CPU_ticks( +static inline Watchdog_Interval _Timer_Get_CPU_ticks( const Per_CPU_Control *cpu ) { @@ -180,7 +199,7 @@ void _Timer_Routine_adaptor( Watchdog_Control *the_watchdog ); void _Timer_server_Routine_adaptor( Watchdog_Control *the_watchdog ); -RTEMS_INLINE_ROUTINE void _Timer_server_Acquire_critical( +static inline void _Timer_server_Acquire_critical( Timer_server_Control *timer_server, ISR_lock_Context *lock_context ) @@ -188,7 +207,7 @@ RTEMS_INLINE_ROUTINE void _Timer_server_Acquire_critical( _ISR_lock_Acquire( &timer_server->Lock, lock_context ); } -RTEMS_INLINE_ROUTINE void _Timer_server_Release_critical( +static inline void _Timer_server_Release_critical( Timer_server_Control *timer_server, ISR_lock_Context *lock_context ) diff --git a/cpukit/include/rtems/rtems/types.h b/cpukit/include/rtems/rtems/types.h index caa75b4f0d..8f85def7c5 100644 --- a/cpukit/include/rtems/rtems/types.h +++ b/cpukit/include/rtems/rtems/types.h @@ -3,11 +3,13 @@ /** * @file * + * @ingroup RTEMSImplClassic + * * @brief This header file provides types used by the Classic API. */ /* - * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -59,12 +61,13 @@ #include <sys/_timeval.h> #include <sys/cpuset.h> #include <rtems/rtems/modes.h> -#include <rtems/score/mppkt.h> +#include <rtems/score/cpuopts.h> #include <rtems/score/object.h> #include <rtems/score/watchdogticks.h> #if defined(RTEMS_MULTIPROCESSING) #include <rtems/score/mpci.h> + #include <rtems/score/mppkt.h> #endif #ifdef __cplusplus |