[PATCH] rtems: Generate <rtems/extension.h>

[Chris Johns]

Nice set of changes. My comments are below ....

On 10/9/21 6:11 pm, Sebastian Huber wrote:
> 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.

ESCB? Can the definition to be local to here rather than needing to reach for
the mouse, a browser, working internet link, a built doxygen .... :)

> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + *   context.

Seem a little to ""specread"" .. maybe .. "during device driver initialization"?

> + *
> + * * The directive may be called from within task context.

Specread ?? ... "within task context" ... "within a task's context" ?

> + * * The directive may obtain and release the object allocator mutex.  This may
> + *   cause the calling task to be preempted.

Block or preempted? I assume the task may be preempted before making the call?

Do we assume task and thread and inter-changeable?

> + * * 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.

Should? Is it too late by the time the call is being made?

> + *
> + * @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.

What does forward order mean?

> + *
> + * 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.

Where is the list defined that is means "undefined and corrupt"?

> + *
> + * 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.

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
and the 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.

As above.

> + * @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.

As a set? That is all handlers provided are active at the same time?

> - * 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
>   */

Is having handlers entries set to NULL discussed? That is specific tables for
unique non-overlapping functions?

>  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.

Construction of what?

> + *
> + * 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.

As above.

>   *
> - * 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.

I did not know this about SMP. Which context is this handler invoked in? The
terminate below describes this nicely.

> + * @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

Built not build. It is "was built" or "is built"?

> + * attention to the differences to correctly implement a task switch extension.
> + *
> + * Where the system was built with SMP support disabled, the task switch

Was or is? A few other spots below depending on what is decided.

Chris

> + * 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 */
>