From 466cd91744dc7b891f1b793728f9204dc15bd88a Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 11:29:45 +0200 Subject: rtems: Generate 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 | 765 ++++++++++++++++++++++++++++++--------- 1 file changed, 588 insertions(+), 177 deletions(-) (limited to 'cpukit') diff --git a/cpukit/include/rtems/extension.h b/cpukit/include/rtems/extension.h index 6f97ebe24c..0117a41b8a 100644 --- a/cpukit/include/rtems/extension.h +++ b/cpukit/include/rtems/extension.h @@ -1,190 +1,314 @@ +/* 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 #include -#include +#include +#include #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. * - * Newly created extension sets are immediately installed and are invoked upon - * the next system event supporting an extension. + * The objects are searched from lowest to the highest index. Only the local + * node is searched. * - * This directive will not cause the calling task to be preempted. + * The extension set identifier is used with other extension related directives + * to access the extension set. + * @endparblock * - * @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. + * @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 table is not used after the return of the + * directive. + * + * Each extension of the extension table is optional and may be NULL. All + * extensions except the task switch extension of the extension table are + * atomically and immediately installed. A task switch extension is separately + * installed after the other extensions. The extensions of the extension table + * are invoked upon the next system event supporting an extension. + * + * 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: + * + * * 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 +316,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 built 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 */ -- cgit v1.2.3