/* SPDX-License-Identifier: BSD-2-Clause */ /** * @file * * @ingroup RTEMSImplClassicUserExt * * @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. */ /* * 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/userext/if/header */ #ifndef _RTEMS_EXTENSION_H #define _RTEMS_EXTENSION_H #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. */ /* Generated from spec:/rtems/userext/if/delete */ /** * @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 */ /** * @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. * * @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 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, const rtems_extensions_table *extension_table, rtems_id *id ); /* Generated from spec:/rtems/userext/if/task-begin */ /** * @ingroup RTEMSAPIClassicUserExt * * @brief Task begin extensions are invoked when a task begins execution. * * @param executing is the TCB of the executing thread. * * @par Notes * @parblock * The task begin extensions are invoked in extension forward order. * * 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 */ typedef User_extensions_thread_begin_extension rtems_task_begin_extension; /* Generated from spec:/rtems/userext/if/task-create */ /** * @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. * * The task create extensions are invoked after a new task has been completely * initialized, but before it is started. * * 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. * * 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 */ 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 /* _RTEMS_EXTENSION_H */