[PATCH] rtems: Generate <rtems/extension.h>
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Sep 10 08:11:10 UTC 2021
Remove the duplicated description which is an out dated copy and paste
from the Classic API Guide. Instead, thoroughly document the individual
extensions.
Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.
Update #3899.
Update #3993.
---
cpukit/include/rtems/extension.h | 758 ++++++++++++++++++++++++-------
1 file changed, 583 insertions(+), 175 deletions(-)
diff --git a/cpukit/include/rtems/extension.h b/cpukit/include/rtems/extension.h
index 6f97ebe24c..ceb8eb9a1f 100644
--- a/cpukit/include/rtems/extension.h
+++ b/cpukit/include/rtems/extension.h
@@ -1,190 +1,311 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
/**
* @file
*
* @ingroup RTEMSImplClassicUserExt
*
- * @brief User Extensions API.
+ * @brief This header file defines the User Extensions Manager API.
+ */
+
+/*
+ * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 1988, 2008 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.
*/
/*
- * COPYRIGHT (c) 1989-2008.
- * On-Line Applications Research Corporation (OAR).
+ * 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:
*
- * 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.
+ * https://docs.rtems.org
*/
+/* Generated from spec:/rtems/userext/if/header */
+
#ifndef _RTEMS_EXTENSION_H
#define _RTEMS_EXTENSION_H
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>
-#include <rtems/score/userext.h>
+#include <rtems/score/interr.h>
+#include <rtems/score/userextdata.h>
#ifdef __cplusplus
extern "C" {
#endif
+/* Generated from spec:/rtems/userext/if/group */
+
/**
* @defgroup RTEMSAPIClassicUserExt User Extensions Manager
*
* @ingroup RTEMSAPIClassic
*
* @brief The User Extensions Manager allows the application developer to
- * augment the executive by allowing them to supply extension routines which
- * are invoked at critical system events.
- *
- * @section RTEMSAPIClassicUserExtSets Extension Sets
- *
- * An @ref User_extensions_Table "extension set" is defined as a set of
- * routines which are invoked at each of the critical system events at which
- * user extension routines are invoked. Together a set of these routines
- * typically perform a specific functionality such as performance monitoring or
- * debugger support.
- *
- * RTEMS allows the user to have multiple extension sets active at the same
- * time. First, a single static extension set may be defined as the
- * application's User Extension Table which is included as part of the
- * Configuration Table. This extension set is active for the entire life of the
- * system and may not be deleted. This extension set is especially important
- * because it is the only way the application can provided a fatal error
- * extension which is invoked if RTEMS fails during the
- * rtems_initialize_data_structures() directive. The static extension set is
- * optional and may be configured as @c NULL if no static extension set is
- * required.
- *
- * Second, the user can install dynamic extensions using the
- * rtems_extension_create() directive. These extensions are RTEMS objects in
- * that they have a name, an ID, and can be dynamically created and deleted. In
- * contrast to the static extension set, these extensions can only be created
- * and installed after the rtems_initialize_data_structures() directive
- * successfully completes execution. Dynamic extensions are useful for
- * encapsulating the functionality of an extension set. For example, the
- * application could use extensions to manage a special coprocessor, do
- * performance monitoring, and to do stack bounds checking. Each of these
- * extension sets could be written and installed independently of the others.
- *
- * All user extensions are optional and RTEMS places no naming restrictions on
- * the user. The user extension entry points are copied into an internal RTEMS
- * structure. This means the user does not need to keep the table after
- * creating it, and changing the handler entry points dynamically in a table
- * once created has no effect. Creating a table local to a function can save
- * space in space limited applications.
- *
- * Extension switches do not effect the context switch overhead if no switch
- * handler is installed.
- *
- * @section RTEMSAPIClassicUserExtTCB Task Control Block Area
- *
- * RTEMS provides for a pointer to a user-defined data area for each extension
- * set to be linked to each task's control block (TCB). This area is only
- * available for the dynamic extensions. This set of pointers is an extension
- * of the TCB and can be used to store additional data required by the user's
- * extension functions.
- *
- * The TCB extension is an array of pointers in the TCB. The index into the
- * table can be obtained from the extension identifier returned when the
- * extension is created:
- *
- * @code
- * rtems_tcb *task = some_task;
- * size_t index = rtems_object_id_get_index(extension_id);
- * void *extension_data = task->extensions [index];
- * @endcode
- *
- * The number of pointers in the area is the same as the number of user
- * extension sets configured. This allows an application to augment the TCB
- * with user-defined information. For example, an application could implement
- * task profiling by storing timing statistics in the TCB's extended memory
- * area. When a task context switch is being executed, the task switch
- * extension could read a real-time clock to calculate how long the task being
- * swapped out has run as well as timestamp the starting time for the task
- * being swapped in.
- *
- * If used, the extended memory area for the TCB should be allocated and the
- * TCB extension pointer should be set at the time the task is created or
- * started by either the task create or task start extension. The application
- * is responsible for managing this extended memory area for the TCBs. The
- * memory may be reinitialized by the task restart extension and should be
- * deallocated by the task delete extension when the task is deleted. Since the
- * TCB extension buffers would most likely be of a fixed size, the RTEMS
- * partition manager could be used to manage the application's extended memory
- * area. The application could create a partition of fixed size TCB extension
- * buffers and use the partition manager's allocation and deallocation
- * directives to obtain and release the extension buffers.
- *
- * @section RTEMSAPIClassicUserExtOrder Order of Invokation
- *
- * When one of the critical system events occur, the user extensions are
- * invoked in either @a forward or @a reverse order. Forward order indicates
- * that the static extension set is invoked followed by the dynamic extension
- * sets in the order in which they were created. Reverse order means that the
- * dynamic extension sets are invoked in the opposite of the order in which
- * they were created followed by the static extension set. By invoking the
- * extension sets in this order, extensions can be built upon one another. At
- * the following system events, the extensions are invoked in forward order:
- *
- * - Task creation
- * - Task start
- * - Task restart
- * - Task context switch
- * - Post task context switch
- * - Task begins to execute
- *
- * At the following system events, the extensions are invoked in reverse order:
- *
- * - Task exit
- * - Task deletion
- * - Fatal error detection
- *
- * At these system events, the extensions are invoked in reverse order to
- * insure that if an extension set is built upon another, the more complicated
- * extension is invoked before the extension set it is built upon. For example,
- * by invoking the static extension set last it is known that the "system"
- * fatal error extension will be the last fatal error extension executed.
- * Another example is use of the task delete extension by the Standard C
- * Library. Extension sets which are installed after the Standard C Library
- * will operate correctly even if they utilize the C Library because the C
- * Library's task delete extension is invoked after that of the other
- * extensions.
- */
-/**@{**/
-
-typedef User_extensions_thread_create_extension rtems_task_create_extension;
-typedef User_extensions_thread_delete_extension rtems_task_delete_extension;
-typedef User_extensions_thread_start_extension rtems_task_start_extension;
-typedef User_extensions_thread_restart_extension rtems_task_restart_extension;
-typedef User_extensions_thread_switch_extension rtems_task_switch_extension;
-typedef User_extensions_thread_begin_extension rtems_task_begin_extension;
-typedef User_extensions_thread_exitted_extension rtems_task_exitted_extension;
-typedef User_extensions_fatal_extension rtems_fatal_extension;
-typedef User_extensions_thread_terminate_extension rtems_task_terminate_extension;
+ * augment the executive by allowing them to supply extension routines which
+ * are invoked at critical system events.
+ */
-typedef User_extensions_Table rtems_extensions_table;
+/* Generated from spec:/rtems/userext/if/delete */
-typedef Internal_errors_Source rtems_fatal_source;
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Deletes the extension set.
+ *
+ * @param id is the extension set identifier.
+ *
+ * This directive deletes the extension set specified by ``id``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no extension set associated with the
+ * identifier specified by ``id``.
+ *
+ * @par Notes
+ * The ESCB for the deleted extension set is reclaimed by RTEMS.
+ *
+ * @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 calling task does not have to be the task that created the object.
+ * Any local task that knows the object identifier can delete the object.
+ * @endparblock
+ */
+rtems_status_code rtems_extension_delete( rtems_id id );
+
+/* Generated from spec:/rtems/userext/if/fatal */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Fatal extensions are invoked when the system should terminate.
+ *
+ * @param source is the system termination source. The source indicates the
+ * component which caused the system termination request, see
+ * ::rtems_fatal_source. The system termination code may provide additional
+ * information related to the system termination request.
+ *
+ * @param always_set_to_false is a value equal to false.
+ *
+ * @param code is the system termination code. This value must be interpreted
+ * with respect to the source.
+ *
+ * @par Notes
+ * @parblock
+ * The fatal extensions are invoked in extension forward order.
+ *
+ * The fatal extension should be extremely careful with respect to the RTEMS
+ * directives it calls. Depending on the system termination source, the system
+ * may be in an undefined and corrupt state.
+ *
+ * It is recommended to register fatal extensions through initial extension
+ * sets, see #CONFIGURE_INITIAL_EXTENSIONS.
+ * @endparblock
+ */
+typedef User_extensions_fatal_extension rtems_fatal_extension;
+
+/* Generated from spec:/rtems/userext/if/fatal-code */
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief This integer type represents system termination codes.
+ *
+ * This integer type is large enough to store a 32-bit integer or a pointer.
+ *
+ * @par Notes
+ * The interpretation of a system termination code depends on the system
+ * termination source, see ::rtems_fatal_source.
+ */
typedef Internal_errors_t rtems_fatal_code;
+/* Generated from spec:/rtems/userext/if/fatal-source */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief This enumeration represents system termination sources.
+ *
+ * @par Notes
+ * The system termination code may provide additional information depending on
+ * the system termination source, see ::rtems_fatal_code.
+ */
+typedef Internal_errors_Source rtems_fatal_source;
+
+/* Generated from spec:/rtems/userext/if/ident */
+
/**
- * @brief Creates an extension set object.
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Identifies an extension set by the object name.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
+ *
+ * This directive obtains an extension set identifier associated with the
+ * extension set name specified in ``name``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ * the local node.
*
- * This directive creates a extension set object from the extension table
- * @a extension_table. The assigned extension set identifier is returned in
- * @a id. The identifier is used to access this extension set in other
- * extension set related directives. The name @a name will be assigned to the
- * extension set object.
+ * @par Notes
+ * @parblock
+ * If the extension set name is not unique, then the extension set identifier
+ * will match the first extension set with that name in the search order.
+ * However, this extension set identifier is not guaranteed to correspond to
+ * the desired extension set.
+ *
+ * The objects are searched from lowest to the highest index. Only the local
+ * node is searched.
+ *
+ * The extension set identifier is used with other extension related directives
+ * to access the extension set.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within device driver initialization
+ * context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
+ */
+rtems_status_code rtems_extension_ident( rtems_name name, rtems_id *id );
+
+/* Generated from spec:/rtems/userext/if/table */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief The extensions table contains a set of extensions which may be
+ * registered in the system through the #CONFIGURE_INITIAL_EXTENSIONS
+ * application configuration option or the rtems_extension_create()
+ * directive.
+ */
+typedef User_extensions_Table rtems_extensions_table;
+
+/* Generated from spec:/rtems/userext/if/create */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Creates an extension set.
+ *
+ * @param name is the object name of the extension set.
+ *
+ * @param extension_table is the table with the extensions to be used by the
+ * extension set.
+ *
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created extension set will be
+ * stored in this object.
+ *
+ * This directive creates an extension set which resides on the local node.
+ * The extension set has the user-defined object name specified in ``name``.
+ * The assigned object identifier is returned in ``id``. This identifier is
+ * used to access the extension set with other extension set related
+ * directives.
+ *
+ * The extension set is initialized using the extension table specified in
+ * ``extension_table``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``extension_table`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_TOO_MANY There was no inactive object available to create an
+ * extension set. The number of extension sets available to the application
+ * is configured through the #CONFIGURE_MAXIMUM_USER_EXTENSIONS application
+ * configuration option.
+ *
+ * @par Notes
+ * @parblock
+ * The user-provided extension set table is not used after the return of the
+ * directive.
*
* Newly created extension sets are immediately installed and are invoked upon
* the next system event supporting an extension.
*
- * This directive will not cause the calling task to be preempted.
+ * An alternative to dynamically created extension sets are initial extensions,
+ * see #CONFIGURE_INITIAL_EXTENSIONS. Initial extensions are recommended for
+ * extension sets which provide a fatal error extension.
+ *
+ * For control and maintenance of the extension set, RTEMS allocates a ESCB
+ * from the local ESCB free pool and initializes it.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * @retval RTEMS_SUCCESSFUL Extension set created successfully.
- * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
- * @retval RTEMS_INVALID_NAME Invalid extension set name.
- * @retval RTEMS_TOO_MANY Too many extension sets created.
+ * * 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 number of extension sets available to the application is configured
+ * through the #CONFIGURE_MAXIMUM_USER_EXTENSIONS application configuration
+ * option.
+ * @endparblock
*/
rtems_status_code rtems_extension_create(
rtems_name name,
@@ -192,47 +313,334 @@ rtems_status_code rtems_extension_create(
rtems_id *id
);
+/* Generated from spec:/rtems/userext/if/task-begin */
+
/**
- * @brief Identifies an extension set object by a name.
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task begin extensions are invoked when a task begins execution.
*
- * This directive obtains an extension set identifier in @a id associated with
- * the extension set name @a name. If the extension set name is not unique,
- * then the extension set identifier will match one of the extension sets with
- * that name. However, this extension set identifier is not guaranteed to
- * correspond to the desired extension set. The extension set identifier is
- * used to access this extension set in other extension set related directives.
+ * @param executing is the TCB of the executing thread.
*
- * This directive will not cause the calling task to be preempted.
+ * @par Notes
+ * @parblock
+ * The task begin extensions are invoked in extension forward order.
*
- * @retval RTEMS_SUCCESSFUL Extension set identified successfully.
- * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
- * @retval RTEMS_INVALID_NAME Extension set name not found or invalid name.
+ * Task begin extensions are invoked with thread dispatching enabled. This
+ * allows the use of dynamic memory allocation, creation of POSIX keys, and use
+ * of C++ thread-local storage. Blocking synchronization primitives are
+ * allowed also.
+ *
+ * The task begin extensions are invoked before the global construction.
+ *
+ * The task begin extensions may be called as a result of a task restart
+ * through rtems_task_restart().
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is enabled.
+ *
+ * * The executing thread is not the owner of the object allocator mutex.
+ * @endparblock
*/
-rtems_status_code rtems_extension_ident(
- rtems_name name,
- rtems_id *id
-);
+typedef User_extensions_thread_begin_extension rtems_task_begin_extension;
+
+/* Generated from spec:/rtems/userext/if/task-create */
/**
- * @brief Deletes an extension set object specified by the identifier @a id.
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task create extensions are invoked when a task is created.
+ *
+ * @param executing is the TCB of the executing thread. When the idle thread
+ * is created, the executing thread is equal to NULL.
+ *
+ * @param created is the TCB of the created thread.
+ *
+ * @return Returns true, if the task create extension was successful, otherwise
+ * false.
+ *
+ * @par Notes
+ * @parblock
+ * The task create extensions are invoked in extension forward order.
*
- * Any subsequent references to the extension's name and identifier are
- * invalid.
+ * The task create extensions are invoked after a new task has been completely
+ * initialized, but before it is started.
*
- * This directive will not cause the calling task to be preempted.
+ * While normal tasks are created, the executing thread is the owner of the
+ * object allocator mutex. The object allocator mutex allows nesting, so the
+ * normal memory allocation routines can be used allocate memory for the
+ * created thread.
*
- * @retval RTEMS_SUCCESSFUL Extension set deleted successfully.
- * @retval RTEMS_INVALID_ID Invalid extension set identifier.
+ * If the task create extension returns false, then the task create operation
+ * stops immediately and the entire task create operation will fail. In this
+ * case, all task delete extensions are invoked, see
+ * ::rtems_task_delete_extension.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * While the system is initialized, thread dispatching is disabled.
+ *
+ * * While the system is in the multitasking state, thread dispatching is
+ * enabled.
+ *
+ * * While an idle thread or another internal system thread is created, the
+ * object allocator mutex has no owner.
+ *
+ * * While a task is created by rtems_task_create(), the executing thread is
+ * the owner of the object allocator mutex.
+ *
+ * * While a task is constructed by rtems_task_construct(), the executing
+ * thread is the owner of the object allocator mutex.
+ *
+ * * While a task is created by pthread_create(), the executing thread is the
+ * owner of the object allocator mutex.
+ * @endparblock
*/
-rtems_status_code rtems_extension_delete(
- rtems_id id
-);
+typedef User_extensions_thread_create_extension rtems_task_create_extension;
+
+/* Generated from spec:/rtems/userext/if/task-delete */
-/** @} */
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task delete extensions are invoked when a task is deleted.
+ *
+ * @param executing is the TCB of the executing thread. If the idle thread is
+ * created and one of the initial task create extension fails, then the
+ * executing thread is equal to NULL.
+ *
+ * @param created is the TCB of the deleted thread. The executing and deleted
+ * arguments are never equal.
+ *
+ * @par Notes
+ * @parblock
+ * The task delete extensions are invoked in extension reverse order.
+ *
+ * The task delete extensions are invoked by task create directives before an
+ * attempt to allocate a TCB is made.
+ *
+ * If a task create extension failed, then a task delete extension may be
+ * invoked without a previous invocation of the corresponding task create
+ * extension of the extension set.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * While the system is initialized, thread dispatching is disabled.
+ *
+ * * While the system is in the multitasking state, thread dispatching is
+ * enabled.
+ *
+ * * While an idle thread or another internal system thread is created, the
+ * object allocator mutex has no owner.
+ *
+ * * While a task is created by rtems_task_create(), the executing thread is
+ * the owner of the object allocator mutex.
+ *
+ * * While a task is constructed by rtems_task_construct(), the executing
+ * thread is the owner of the object allocator mutex.
+ *
+ * * While a task is created by pthread_create(), the executing thread is the
+ * owner of the object allocator mutex.
+ * @endparblock
+ */
+typedef User_extensions_thread_delete_extension rtems_task_delete_extension;
+
+/* Generated from spec:/rtems/userext/if/task-exitted */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task exitted extensions are invoked when a task entry returns.
+ *
+ * @param executing is the TCB of the executing thread.
+ *
+ * @par Notes
+ * The task exitted extensions are invoked in extension forward order.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is enabled.
+ * @endparblock
+ */
+typedef User_extensions_thread_exitted_extension rtems_task_exitted_extension;
+
+/* Generated from spec:/rtems/userext/if/task-restart */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task restart extensions are invoked when a task restarts.
+ *
+ * @param executing is the TCB of the executing thread.
+ *
+ * @param restarted is the TCB of the executing thread. Yes, the executing
+ * thread.
+ *
+ * @par Notes
+ * @parblock
+ * The task restart extensions are invoked in extension forward order.
+ *
+ * The task restart extensions are invoked in the context of the restarted
+ * thread right before the execution context is reloaded. The thread stack
+ * reflects the previous execution context.
+ *
+ * Thread restart and delete requests issued by restart extensions lead to
+ * recursion.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is enabled.
+ *
+ * * Thread life is protected.
+ *
+ * * The executing thread is not the owner of the object allocator mutex.
+ * @endparblock
+ */
+typedef User_extensions_thread_restart_extension rtems_task_restart_extension;
+
+/* Generated from spec:/rtems/userext/if/task-start */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task start extensions are invoked when a task was made ready for the
+ * first time.
+ *
+ * @param executing is the TCB of the executing thread.
+ *
+ * @param started is the TCB of the started thread.
+ *
+ * @par Notes
+ * @parblock
+ * The task start extensions are invoked in extension forward order.
+ *
+ * In SMP configurations, the thread may already run on another processor
+ * before the task start extensions are actually invoked. Task switch and task
+ * begin extensions may run before or in parallel with the thread start
+ * extension in SMP configurations, see ::rtems_task_switch_extension and
+ * ::rtems_task_begin_extension.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is disabled.
+ * @endparblock
+ */
+typedef User_extensions_thread_start_extension rtems_task_start_extension;
+
+/* Generated from spec:/rtems/userext/if/task-switch */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task switch extensions are invoked when a thread switch from an
+ * executing thread to a heir thread takes place.
+ *
+ * @param executing is the TCB of the executing thread. In SMP configurations,
+ * this is the previously executing thread also known as the ancestor thread.
+ *
+ * @param heir is the TCB of the heir thread. In SMP configurations, this is
+ * the executing thread.
+ *
+ * @par Notes
+ * @parblock
+ * The task switch extensions are invoked in extension forward order.
+ *
+ * The invocation conditions of the task switch extensions depend on whether
+ * RTEMS was build with SMP support enabled or disabled. A user must pay
+ * attention to the differences to correctly implement a task switch extension.
+ *
+ * Where the system was built with SMP support disabled, the task switch
+ * extensions are invoked before the context switch from the currently
+ * executing thread to the heir thread. The executing is a pointer to the TCB
+ * of the currently executing thread. The heir is a pointer to the TCB of the
+ * heir thread. The context switch initiated through the multitasking start is
+ * not covered by the task switch extensions.
+ *
+ * Where the system was built with SMP support enabled, the task switch
+ * extensions are invoked after the context switch to the heir thread. The
+ * executing is a pointer to the TCB of the previously executing thread.
+ * Despite the name, this is not the currently executing thread. The heir is a
+ * pointer to the TCB of the newly executing thread. This is the currently
+ * executing thread. The context switches initiated through the multitasking
+ * start are covered by the task switch extensions. The reason for the
+ * differences to uniprocessor configurations is that the context switch may
+ * update the heir thread of the processor. The task switch extensions are
+ * invoked with maskable interrupts disabled and with ownership of a
+ * processor-specific SMP lock. Task switch extensions may run in parallel on
+ * multiple processors. It is recommended to use thread-local or
+ * processor-specific data structures for task switch extensions. A global SMP
+ * lock should be avoided for performance reasons, see
+ * rtems_interrupt_lock_initialize().
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is disabled.
+ *
+ * * Where the system was built with SMP support enabled, maskable interrupts
+ * are disabled for the executing thread.
+ * @endparblock
+ */
+typedef User_extensions_thread_switch_extension rtems_task_switch_extension;
+
+/* Generated from spec:/rtems/userext/if/task-terminate */
+
+/**
+ * @ingroup RTEMSAPIClassicUserExt
+ *
+ * @brief Task terminate extensions are invoked when a task terminates.
+ *
+ * @param executing is the TCB of the executing thread. This is the
+ * terminating thread.
+ *
+ * @par Notes
+ * @parblock
+ * The task terminate extensions are invoked in extension reverse order.
+ *
+ * The task terminate extensions are invoked in the context of the terminating
+ * thread right before the thread dispatch to the heir thread should take
+ * place. The thread stack reflects the previous execution context. The POSIX
+ * cleanup and key destructors execute in this context.
+ *
+ * Thread restart and delete requests issued by terminate extensions lead to
+ * recursion.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to functions of this type:
+ *
+ * * Thread dispatching is enabled.
+ *
+ * * Thread life is protected.
+ *
+ * * The executing thread is not the owner of the object allocator mutex.
+ * @endparblock
+ */
+typedef User_extensions_thread_terminate_extension rtems_task_terminate_extension;
#ifdef __cplusplus
}
#endif
-#endif
-/* end of include file */
+#endif /* _RTEMS_EXTENSION_H */
--
2.31.1
More information about the devel
mailing list