2009-09-25 Sebastian Huber <Sebastian.Huber@embedded-brains.de>

	* sapi/include/rtems/extension.h, sapi/src/extensiondelete.c,
	sapi/src/extensionident.c, sapi/src/extensioncreate.c,
	sapi/inline/rtems/extension.inl, score/include/rtems/score/userext.h,
	score/src/userextthreaddelete.c, score/src/userext.c,
	score/src/userextthreadcreate.c, score/src/userextremoveset.c,
	score/src/userextthreadbegin.c, score/src/userextaddset.c,
	score/src/userextthreadstart.c, score/src/userextthreadswitch.c,
	score/src/userextthreadrestart.c: Documentation. The types
	User_extensions_routine and rtems_extension are now deprecated.
	Removed unused types User_extensions_thread_post_switch_extension and
	rtems_task_post_switch_extension. Renamed _User_extensions_Add_API_set()
	in _User_extensions_Add_set(). Renamed _User_extensions_Add_set() in
	_User_extensions_Add_set_with_table().
	* score/src/userextaddapiset.c: Removed file.
	* score/Makefile.am: Update.

17 files changed, 510 insertions, 463 deletions

diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog
index 5d9bc7eff2..190e5ea82d 100644
--- a/cpukit/ChangeLog
+++ b/cpukit/ChangeLog
@@ -1,5 +1,23 @@
 2009-09-25	Sebastian Huber <Sebastian.Huber@embedded-brains.de>
 
+	* sapi/include/rtems/extension.h, sapi/src/extensiondelete.c,
+	sapi/src/extensionident.c, sapi/src/extensioncreate.c,
+	sapi/inline/rtems/extension.inl, score/include/rtems/score/userext.h,
+	score/src/userextthreaddelete.c, score/src/userext.c,
+	score/src/userextthreadcreate.c, score/src/userextremoveset.c,
+	score/src/userextthreadbegin.c, score/src/userextaddset.c,
+	score/src/userextthreadstart.c, score/src/userextthreadswitch.c,
+	score/src/userextthreadrestart.c: Documentation. The types
+	User_extensions_routine and rtems_extension are now deprecated.
+	Removed unused types User_extensions_thread_post_switch_extension and
+	rtems_task_post_switch_extension. Renamed _User_extensions_Add_API_set()
+	in _User_extensions_Add_set(). Renamed _User_extensions_Add_set() in
+	_User_extensions_Add_set_with_table().
+	* score/src/userextaddapiset.c: Removed file.
+	* score/Makefile.am: Update.
+
+2009-09-25	Sebastian Huber <Sebastian.Huber@embedded-brains.de>
+
 	* score/src/heap.c, score/include/rtems/score/heap.h: Reduced alignment
 	requirement for CPU_ALIGNMENT from four to two.
 
diff --git a/cpukit/sapi/include/rtems/extension.h b/cpukit/sapi/include/rtems/extension.h
index 0d62c1df55..b7b09126a5 100644
--- a/cpukit/sapi/include/rtems/extension.h
+++ b/cpukit/sapi/include/rtems/extension.h
@@ -1,18 +1,12 @@
 /**
- * @file rtems/extension.h
+ * @file
+ *
+ * @ingroup ClassicUserExtensions
+ *
+ * @brief User Extensions API.
  */
  
 /*
- *  This include file contains all the constants, structures, and
- *  prototypes associated with the User Extension Manager.  This manager
- *  provides a mechanism for manipulating sets of user-defined extensions.
- *
- *  Directives provided are:
- *
- *     + create user extension set
- *     + get ID of user extension set
- *     + delete user extension set
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -39,97 +33,220 @@ extern "C" {
 #include <rtems/rtems/status.h>
 #include <rtems/rtems/types.h>
 
-/*
- *  Extension related types
+SAPI_EXT_EXTERN Objects_Information  _Extension_Information;
+
+typedef struct {
+  Objects_Control          Object;
+  User_extensions_Control  Extension;
+}   Extension_Control;
+
+void _Extension_Manager_initialization(void);
+
+typedef User_extensions_routine
+  rtems_extension RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
+
+/**
+ * @defgroup ClassicUserExtensions User Extensions
+ *
+ * @ingroup ClassicRTEMS
+ *
+ * @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 ClassicUserExtensionsSets 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 ClassicUserExtensionsTCB 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. It is also possible for a user extension to utilize the
+ * notepad locations associated with each task although this may conflict with
+ * application usage of those particular notepads.
+ *
+ * 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 ClassicUserExtensionsOrder 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 initiation
+ * - Task reinitiation
+ * - Task deletion
+ * - Task context switch
+ * - Post task context switch
+ * - Task begins to execute 
+ *
+ * At the following system events, the extensions are invoked in reverse order:
+ *
+ * - 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_routine                   rtems_extension;
 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_post_switch_extension
-                                              rtems_task_post_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_Table                     rtems_extensions_table;
 
-/*
- *  The following defines the information control block used to manage
- *  this class of objects.
- */
-
-SAPI_EXT_EXTERN Objects_Information  _Extension_Information;
-
-/*
- *  The following records define the control block used to manage
- *  each extension.
- */
-
-typedef struct {
-  Objects_Control          Object;
-  User_extensions_Control  Extension;
-}   Extension_Control;
-
-/*
- *  _Extension_Manager_initialization
+/**
+ * @brief Creates an extension set object.
  *
- *  DESCRIPTION:
+ * 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.
  *
- *  This routine performs the initialization necessary for this manager.
- */
-
-void _Extension_Manager_initialization(void);
-
-/*
- *  rtems_extension_create
+ * Newly created extension sets are immediately installed and are invoked upon
+ * the next system event supporting an extension.
  *
- *  DESCRIPTION:
+ * This directive will not cause the calling task to be preempted.
  *
- *  This routine implements the rtems_extension_create directive.  The
- *  extension will have the name name.   The entry points of the
- *  routines which constitute this extension set are in EXTENSION_TABLE.
- *  It returns the id of the created extension in ID.
+ * @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.
  */
-
 rtems_status_code rtems_extension_create(
   rtems_name              name,
   rtems_extensions_table *extension_table,
-  Objects_Id              *id
+  rtems_id               *id
 );
 
-/*
- *  rtems_extension_ident
+/**
+ * @brief Identifies an extension set object by a name.
+ *
+ * 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.
  *
- *  DESCRIPTION:
+ * This directive will not cause the calling task to be preempted.
  *
- *  This routine implements the rtems_extension_ident directive.
- *  This directive returns the extension ID associated with name.
- *  If more than one extension is named name, then the extension
- *  to which the ID belongs is arbitrary.
+ * @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.
  */
-
 rtems_status_code rtems_extension_ident(
-  rtems_name    name,
-  Objects_Id   *id
+  rtems_name  name,
+  rtems_id   *id
 );
 
-/*
- *  rtems_extension_delete
+/**
+ * @brief Deletes an extension set object specified by the identifier @a id.
+ *
+ * Any subsequent references to the extension's name and identifier are
+ * invalid.
  *
- *  DESCRIPTION:
+ * This directive will not cause the calling task to be preempted.
  *
- *  This routine implements the rtems_extension_delete directive.  The
- *  extension indicated by ID is deleted.
+ * @retval RTEMS_SUCCESSFUL Extension set deleted successfully.
+ * @retval RTEMS_INVALID_ID Invalid extension set identifier.
  */
-
 rtems_status_code rtems_extension_delete(
-  Objects_Id id
+  rtems_id id
 );
 
+/** @} */
+
 #ifndef __RTEMS_APPLICATION__
 #include <rtems/extension.inl>
 #endif
diff --git a/cpukit/sapi/inline/rtems/extension.inl b/cpukit/sapi/inline/rtems/extension.inl
index 5b516b9f56..36005b7d7f 100644
--- a/cpukit/sapi/inline/rtems/extension.inl
+++ b/cpukit/sapi/inline/rtems/extension.inl
@@ -1,8 +1,9 @@
 /**
- *  @file rtems/extension.inl
+ * @file
  *
- *  This file contains the static inline implementation of the inlined routines
- *  from the Extension Manager.
+ * @ingroup ClassicUserExtensions
+ *
+ * @brief User Extensions API.
  */
 
 /*
@@ -19,31 +20,11 @@
 #ifndef __EXTENSION_MANAGER_inl
 #define __EXTENSION_MANAGER_inl
 
-/*PAGE
- *
- *  _Extension_Allocate
- *
- *  DESCRIPTION:
- *
- *  This function allocates a extension control block from
- *  the inactive chain of free extension control blocks.
- */
-
 RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Allocate( void )
 {
   return (Extension_Control *) _Objects_Allocate( &_Extension_Information );
 }
 
-/*PAGE
- *
- *  _Extension_Free
- *
- *  DESCRIPTION:
- *
- *  This routine frees a extension control block to the
- *  inactive chain of free extension control blocks.
- */
-
 RTEMS_INLINE_ROUTINE void _Extension_Free (
   Extension_Control *the_extension
 )
@@ -51,19 +32,6 @@ RTEMS_INLINE_ROUTINE void _Extension_Free (
   _Objects_Free( &_Extension_Information, &the_extension->Object );
 }
 
-/*PAGE
- *
- *  _Extension_Get
- *
- *  DESCRIPTION:
- *
- *  This function maps extension IDs to extension control blocks.
- *  If ID corresponds to a local extension, then it returns
- *  the extension control pointer which maps to ID and location
- *  is set to OBJECTS_LOCAL.  Otherwise, location is set
- *  to OBJECTS_ERROR and the returned value is undefined.
- */
-
 RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Get (
   Objects_Id         id,
   Objects_Locations *location
@@ -73,15 +41,6 @@ RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Get (
     _Objects_Get( &_Extension_Information, id, location );
 }
 
-/*PAGE
- *
- *  _Extension_Is_null
- *
- *  DESCRIPTION:
- *
- *  This function returns TRUE if the_extension is NULL and FALSE otherwise.
- */
-
 RTEMS_INLINE_ROUTINE bool _Extension_Is_null (
   Extension_Control *the_extension
 )
diff --git a/cpukit/sapi/src/extensioncreate.c b/cpukit/sapi/src/extensioncreate.c
index d2e146d6eb..9e939f57af 100644
--- a/cpukit/sapi/src/extensioncreate.c
+++ b/cpukit/sapi/src/extensioncreate.c
@@ -1,6 +1,12 @@
-/*
- *  Extension Manager -- rtems_extension_create
+/**
+ * @file
+ *
+ * @ingroup ClassicUserExtensions
  *
+ * @brief User Extensions Implementation.
+ */
+ 
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,27 +27,10 @@
 #include <rtems/score/thread.h>
 #include <rtems/extension.h>
 
-/*PAGE
- *
- *  rtems_extension_create
- *
- *  This directive creates a extension and performs some initialization.
- *
- *  Input parameters:
- *    name            - extension name
- *    extension_table - pointer to extension set information
- *    id              - pointer to extension id
- *
- *  Output parameters:
- *    id                - extension id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_extension_create(
   rtems_name              name,
   rtems_extensions_table *extension_table,
-  Objects_Id             *id
+  rtems_id               *id
 )
 {
   Extension_Control *the_extension;
@@ -61,7 +50,7 @@ rtems_status_code rtems_extension_create(
     return RTEMS_TOO_MANY;
   }
 
-  _User_extensions_Add_set( &the_extension->Extension, extension_table );
+  _User_extensions_Add_set_with_table( &the_extension->Extension, extension_table );
 
   _Objects_Open(
     &_Extension_Information,
diff --git a/cpukit/sapi/src/extensiondelete.c b/cpukit/sapi/src/extensiondelete.c
index dd97859cd2..02e08767fd 100644
--- a/cpukit/sapi/src/extensiondelete.c
+++ b/cpukit/sapi/src/extensiondelete.c
@@ -1,6 +1,12 @@
-/*
- *  Extension Manager -- rtems_extension_delete
+/**
+ * @file
+ *
+ * @ingroup ClassicUserExtensions
  *
+ * @brief User Extensions Implementation.
+ */
+ 
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,22 +27,8 @@
 #include <rtems/score/thread.h>
 #include <rtems/extension.h>
 
-/*PAGE
- *
- *  rtems_extension_delete
- *
- *  This directive allows a thread to delete a extension.
- *
- *  Input parameters:
- *    id - extension id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code - if unsuccessful
- */
-
 rtems_status_code rtems_extension_delete(
-  Objects_Id id
+  rtems_id id
 )
 {
   Extension_Control   *the_extension;
diff --git a/cpukit/sapi/src/extensionident.c b/cpukit/sapi/src/extensionident.c
index 767deee166..626c106b0b 100644
--- a/cpukit/sapi/src/extensionident.c
+++ b/cpukit/sapi/src/extensionident.c
@@ -1,6 +1,12 @@
-/*
- *  Extension Manager -- rtems_extension_ident
+/**
+ * @file
+ *
+ * @ingroup ClassicUserExtensions
  *
+ * @brief User Extensions Implementation.
+ */
+ 
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,26 +27,9 @@
 #include <rtems/score/thread.h>
 #include <rtems/extension.h>
 
-/*PAGE
- *
- *  rtems_extension_ident
- *
- *  This directive returns the system ID associated with
- *  the extension name.
- *
- *  Input parameters:
- *    name - user defined message queue name
- *    id   - pointer to extension id
- *
- *  Output parameters:
- *    *id               - message queue id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_extension_ident(
   rtems_name    name,
-  Objects_Id   *id
+  rtems_id     *id
 )
 {
   Objects_Name_or_id_lookup_errors  status;
diff --git a/cpukit/score/Makefile.am b/cpukit/score/Makefile.am
index 127a4e7756..d2375e2d13 100644
--- a/cpukit/score/Makefile.am
+++ b/cpukit/score/Makefile.am
@@ -196,7 +196,7 @@ libscore_a_SOURCES += src/watchdog.c src/watchdogadjust.c \
     src/watchdogtickle.c src/watchdogreport.c src/watchdogreportchain.c
 
 ## USEREXT_C_FILES
-libscore_a_SOURCES += src/userextaddapiset.c src/userextaddset.c \
+libscore_a_SOURCES += src/userextaddset.c \
     src/userext.c src/userextremoveset.c src/userextthreadbegin.c \
     src/userextthreadcreate.c src/userextthreaddelete.c \
     src/userextthreadrestart.c src/userextthreadstart.c \
diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h
index 938630eb0e..65fc1881c9 100644
--- a/cpukit/score/include/rtems/score/userext.h
+++ b/cpukit/score/include/rtems/score/userext.h
@@ -1,9 +1,9 @@
-/** 
- *  @file  rtems/score/userext.h
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
  *
- *  This include file contains all information about user extensions.  This
- *  Handler provides mechanisms which can be used to initialize and manipulate
- *  all user extensions.
+ * @brief User Extension Handler API.
  */
 
 /*
@@ -20,14 +20,6 @@
 #ifndef _RTEMS_SCORE_USEREXT_H
 #define _RTEMS_SCORE_USEREXT_H
 
-/**
- *  @defgroup ScoreUserExt User Extension Handler
- *
- *  This handler encapsulates functionality related to the management of
- *  the user extensions to the SuperCore that are available to the user.
- */
-/**@{*/
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -36,310 +28,288 @@ extern "C" {
 #include <rtems/score/chain.h>
 #include <rtems/score/thread.h>
 
-/*@}*/
-
-/** @defgroup ScoreUserExtStruct User Extension Handler Structures
- *
- *  The following records defines the User Extension Table.
- *  This table defines the application dependent routines which
- *  are invoked at critical points in the life of each thread and
- *  the system as a whole.
- */
-/*@{*/
-
-/**
- *  This type indicates the return type of a user extension method.
- */
-typedef void User_extensions_routine;
+typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
 
 /**
- *  This type defines the prototype of a thread creation extension handler.
- *  The handler is passed the thread executing and the thread being created.
+ * @defgroup ScoreUserExt User Extension Handler
+ *
+ * @ingroup Score
+ *
+ * @brief The User Extension Handler provides invocation of application
+ * dependent routines at critical points in the life of each thread and the
+ * system as a whole.
+ *
+ * @{
  */
-typedef bool    ( *User_extensions_thread_create_extension )(
-                 Thread_Control *,
-                 Thread_Control *
-             );
 
 /**
- *  This type defines the prototype of a thread deletion extension handler.
- *  The handler is passed the thread executing and the thread being deleted.
+ * @brief Task create extension.
+ *
+ * It corresponds to _Thread_Initialize() (used by the rtems_task_create()
+ * directive).  The first parameter points to the currently executing thread
+ * which created the new thread.  The second parameter points to the created
+ * thread.
+ *
+ * It is invoked after the new thread has been completely initialized, but
+ * before it is placed on a ready chain.
+ *
+ * Thread dispatching may be disabled.  It can be assumed that the executing
+ * thread locked the allocator mutex.  They only exception is the creation of
+ * the idle thread.  In this case the allocator mutex is not locked.
+ *
+ * The user extension is expected to return @c true if it successfully
+ * executed, and @c false otherwise. A thread create user extension will
+ * frequently attempt to allocate resources. If this allocation fails, then the
+ * extension should return @c false and the entire task create operation will
+ * fail.
  */
-typedef User_extensions_routine ( *User_extensions_thread_delete_extension )(
-                 Thread_Control *,
-                 Thread_Control *
-             );
+typedef bool ( *User_extensions_thread_create_extension )(
+  Thread_Control *,
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of thread starting extension handler.
- *  The handler is passed the thread executing and the thread being started.
+ * @brief Task delete extension.
+ *
+ * It corresponds to _Thread_Close() (used by the rtems_task_delete()
+ * directive).  The first parameter points to the currently executing thread
+ * which deleted the thread.  The second parameter points to the deleted
+ * thread.
+ *
+ * It is invoked before all resources of the thread are deleted.
+ *
+ * Thread dispatching is enabled.  The executing thread locked the allocator
+ * mutex.
  */
-typedef User_extensions_routine ( *User_extensions_thread_start_extension )(
-                 Thread_Control *,
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_delete_extension )(
+  Thread_Control *,
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of a thread restarting extension handler.
- *  The handler is passed the thread executing and the thread being restarted.
+ * @brief Task start extension.
+ *
+ * It corresponds to _Thread_Start() (used by the rtems_task_start()
+ * directive).  The first parameter points to the currently executing thread
+ * which started the thread.  The second parameter points to the started
+ * thread.
+ *
+ * It is invoked after the environment of the thread has been loaded and the
+ * thread has been made ready.
+ *
+ * Thread dispatching is disabled.  The executing thread is not the holder of
+ * the allocator mutex.
  */
-typedef User_extensions_routine ( *User_extensions_thread_restart_extension )(
-                 Thread_Control *,
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_start_extension )(
+  Thread_Control *,
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of thread context switch extension handler.
- *  The handler is passed the thread currently executing and the thread being 
- *  switched to.
+ * @brief Task restart extension.
+ *
+ * It corresponds to _Thread_Restart() (used by the rtems_task_restart()
+ * directive).  The first parameter points to the currently executing thread
+ * which restarted the thread.  The second parameter points to the restarted
+ * thread.
+ *
+ * It is invoked after the environment of the thread has been loaded and the
+ * thread has been made ready.
+ *
+ * Thread dispatching is disabled.  The executing thread is not the holder of
+ * the allocator mutex.
  */
-typedef User_extensions_routine ( *User_extensions_thread_switch_extension )(
-                 Thread_Control *,
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_restart_extension )(
+  Thread_Control *,
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of a post context switch extension handler.
- *  The handler is passed the thread thread being switched to.
+ * @brief Task switch extension.
+ *
+ * It corresponds to _Thread_Dispatch().  The first parameter points to the
+ * currently executing thread.  The second parameter points to the heir thread.
+ *
+ * It is invoked before the context switch from the executing to the heir
+ * thread.
+ *
+ * Thread dispatching is disabled.  The state of the allocator mutex is
+ * arbitrary.
+ *
+ * The context switches initiated through _Thread_Start_multitasking() and
+ * _Thread_Stop_multitasking() are not covered by this extension.  The
+ * executing thread may run with a minimal setup, for example with a freed task
+ * stack. 
  */
-typedef User_extensions_routine (*User_extensions_thread_post_switch_extension)(
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_switch_extension )(
+  Thread_Control *,
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of a thread beginning to execute
- *  extension handler.  The handler is passed the thread executing.  This
- *  extension is executed in the context of the beginning thread.
+ * @brief Task begin extension.
+ *
+ * It corresponds to _Thread_Handler().  The first parameter points to the
+ * currently executing thread which begins now execution.
+ *
+ * Thread dispatching is disabled.  The executing thread is not the holder of
+ * the allocator mutex.
  */
-typedef User_extensions_routine ( *User_extensions_thread_begin_extension )(
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_begin_extension )(
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of a thread exiting extension handler.
- *  The handler is passed the thread exiting.
+ * @brief Task exitted extension.
+ *
+ * It corresponds to _Thread_Handler().  The first parameter points to the
+ * currently executing thread which exitted before.
+ *
+ * Thread dispatching is disabled.  The state of the allocator mutex is
+ * arbitrary.
  */
-typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )(
-                 Thread_Control *
-             );
+typedef void( *User_extensions_thread_exitted_extension )(
+  Thread_Control *
+);
 
 /**
- *  This type defines the prototype of the fatal error extension handler.
- *  The handler is passed an indicator of the source of the fatal error,
- *  whether it is internal to RTEMS and an error code.
+ * @brief Task fatal error extension.
+ *
+ * It corresponds to _Internal_error_Occurred() (used by the
+ * rtems_fatal_error_occurred() directive).  The first parameter contains the
+ * internal error source.  The second parameter indicates if it was an internal
+ * error.  The third parameter contains the error code.
+ *
+ * This extension should not call any RTEMS directives.
  */
-typedef User_extensions_routine ( *User_extensions_fatal_extension )(
-                 Internal_errors_Source  /* the_source  */,
-                 bool                    /* is_internal */,
-                 uint32_t                /* the_error   */
-             );
+typedef void( *User_extensions_fatal_extension )(
+  Internal_errors_Source,
+  bool,
+  uint32_t
+);
 
 /**
- *  This type defines a set of user extensions.
+ * @brief User extension table.
  */
 typedef struct {
-  /** This field is the thread creation handler. */
-  User_extensions_thread_create_extension       thread_create;
-  /** This field is the thread starting handler. */
-  User_extensions_thread_start_extension        thread_start;
-  /** This field is the thread restarting handler. */
-  User_extensions_thread_restart_extension      thread_restart;
-  /** This field is the thread deleting handler */
-  User_extensions_thread_delete_extension       thread_delete;
-  /** This field is thread context switch handler. */
-  User_extensions_thread_switch_extension       thread_switch;
-  /** This field is the thread beginning handler. */
-  User_extensions_thread_begin_extension        thread_begin;
-  /** This field is thread exiting handler. */
-  User_extensions_thread_exitted_extension      thread_exitted;
-  /** This field is the fatal error extension. */
-  User_extensions_fatal_extension               fatal;
+  User_extensions_thread_create_extension  thread_create;
+  User_extensions_thread_start_extension   thread_start;
+  User_extensions_thread_restart_extension thread_restart;
+  User_extensions_thread_delete_extension  thread_delete;
+  User_extensions_thread_switch_extension  thread_switch;
+  User_extensions_thread_begin_extension   thread_begin;
+  User_extensions_thread_exitted_extension thread_exitted;
+  User_extensions_fatal_extension          fatal;
 }   User_extensions_Table;
 
 /**
- *  This is used to manage the list of switch handlers.  They are managed
- *  separately from other extensions for performance reasons.
+ * @brief Manages the switch callouts.
+ *
+ * They are managed separately from other extensions for performance reasons.
  */
 typedef struct {
-  /** This field is a Chain Node structure and allows this to be placed on
-   *  chains for set management.
-   */
   Chain_Node                              Node;
-  /** This field is the thread switch extension. */
   User_extensions_thread_switch_extension thread_switch;
 }   User_extensions_Switch_control;
 
 /**
- *  This is used to manage each user extension set.
- *  The switch control is part of the extensions control even
- *  if not used due to the extension not having a switch
- *  handler.
+ * @brief Manages each user extension set.
+ *
+ * The switch control is part of the extensions control even if not used due to
+ * the extension not having a switch handler.
  */
 typedef struct {
-  /** This field is a Chain Node structure and allows this to be placed on
-   *  chains for set management.
-   */
   Chain_Node                     Node;
-  /** This field is the thread switch user extension. */
   User_extensions_Switch_control Switch;
-  /** This field is the rest of this user extension's entry points.  */
   User_extensions_Table          Callouts;
 }   User_extensions_Control;
 
 /**
- *  This is used to manage the list of active extensions.
+ * @brief List of active extensions.
  */
 SCORE_EXTERN Chain_Control _User_extensions_List;
 
 /**
- *  This is used to manage a chain of user extension task
- *  switch nodes.
+ * @brief List of active task switch extensions.
  */
 SCORE_EXTERN Chain_Control _User_extensions_Switches_list;
 
-/*@}*/
-/** @addtogroup ScoreUserExt */
-
-/*@{*/
-
-/** @brief User extensions Handler Initialization
+/**
+ * @name Extension Maintainance
  *
- *  This routine performs the initialization necessary for this handler.
+ * @{
  */
-void _User_extensions_Handler_initialization(void);
 
-/** @brief User extensions Add to API extension set
- *
- *  This routine is used to add an API extension set to the active list.
- *
- *  @param[in] the_extension is the extension set to add
- */
-void _User_extensions_Add_API_set (
-  User_extensions_Control *the_extension
+void _User_extensions_Handler_initialization( void );
+
+void _User_extensions_Add_set(
+  User_extensions_Control *extension
 );
 
-/** @brief User extensions Add extension set
- *
- *  This routine is used to add a user extension set to the active list.
- *
- *  @param[in] the_extension is the extension set to add
- *  @param[in] extension_table is the user's extension set
- */
-void _User_extensions_Add_set (
-  User_extensions_Control *the_extension,
+RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table(
+  User_extensions_Control *extension,
   User_extensions_Table   *extension_table
-);
+)
+{
+  extension->Callouts = *extension_table;
 
-/**
- *  This routine is used to remove a user extension set from the active list.
- */
-void _User_extensions_Remove_set (
-  User_extensions_Control  *the_extension
+  _User_extensions_Add_set( extension );
+}
+
+void _User_extensions_Remove_set(
+  User_extensions_Control *extension
 );
 
-/** @brief  User extensions Thread create
- *
- *  This routine is used to invoke the user extension for
- *  the thread creation operate.
- *
- *  @param[in] the_thread is the thread being created.
+/** @} */
+
+/**
+ * @name Extension Callout Dispatcher
  *
- *  @return This method returns true if the user extension executed
- *          successfully.
+ * @{
  */
-bool _User_extensions_Thread_create (
-  Thread_Control *the_thread
+
+bool _User_extensions_Thread_create(
+  Thread_Control *created
 );
 
-/** @brief  User extensions Thread delete
- *
- *  This routine is used to invoke the user extension for
- *  the thread deletion operation.
- *
- *  @param[in] the_thread is the thread being deleted.
- */
-void _User_extensions_Thread_delete (
-  Thread_Control *the_thread
+void _User_extensions_Thread_delete(
+  Thread_Control *deleted
 );
 
-/** @brief  User extensions Thread start
- *
- *  This routine is used to invoke the user extension for
- *  the thread start operation.
- *
- *  @param[in] the_thread is the thread being started.
- */
-void _User_extensions_Thread_start (
-  Thread_Control *the_thread
+void _User_extensions_Thread_start(
+  Thread_Control *started
 );
 
-/** @brief  User extensions Thread restart
- *
- *  This routine is used to invoke the user extension for
- *  the thread restart operation.
- *
- *  @param[in] the_thread is the thread being restarted.
- */
-void _User_extensions_Thread_restart (
-  Thread_Control *the_thread
+void _User_extensions_Thread_restart(
+  Thread_Control *restarted
 );
 
-/** @brief  User extensions Thread begin
- *
- *  This routine is used to invoke the user extension which
- *  is invoked when a thread begins.
- *
- *  @param[in] executing is the thread beginning to execute.
- */
-void _User_extensions_Thread_begin (
+void _User_extensions_Thread_begin(
   Thread_Control *executing
 );
 
-
-/** @brief  User extensions Thread switch
- *
- *  This routine is used to invoke the user extension which
- *  is invoked when a context switch occurs.
- *
- *  @param[in] executing is the thread currently executing.
- *  @param[in] heir is the thread which will execute.
- */
-void _User_extensions_Thread_switch (
+void _User_extensions_Thread_switch(
   Thread_Control *executing,
   Thread_Control *heir
 );
 
-/** @brief  User extensions Thread exitted
- *
- *  This routine is used to invoke the user extension which
- *  is invoked when a thread exits.
- *
- *  @param[in] executing is the thread voluntarily exiting.
- */
-void _User_extensions_Thread_exitted (
+void _User_extensions_Thread_exitted(
   Thread_Control *executing
 );
 
-/** @brief  User extensions Fatal
- *
- *  This routine is used to invoke the user extension invoked
- *  when a fatal error occurs.
- *
- *  @param[in] the_source is the source of the fatal error.
- *  @param[in] is_internal is true if the error originated inside RTEMS.
- *  @param[in] the_error is an indication of the actual error.
- */
-void _User_extensions_Fatal (
-  Internal_errors_Source  the_source,
-  bool                    is_internal,
-  uint32_t                the_error
+void _User_extensions_Fatal(
+  Internal_errors_Source source,
+  bool                   is_internal,
+  uint32_t               error
 );
 
+/** @} */
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
 #endif
 /* end of include file */
diff --git a/cpukit/score/src/userext.c b/cpukit/score/src/userext.c
index 190c15f85f..9b778b6300 100644
--- a/cpukit/score/src/userext.c
+++ b/cpukit/score/src/userext.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
@@ -19,10 +27,6 @@
 #include <rtems/score/wkspace.h>
 #include <string.h>
 
-/**
- *  This routine performs the initialization necessary for this handler.
- */
-
 void _User_extensions_Handler_initialization(void)
 {
   User_extensions_Control *extension;
@@ -49,7 +53,7 @@ void _User_extensions_Handler_initialization(void)
     );
   
     for ( i = 0 ; i < number_of_extensions ; i++ ) {
-      _User_extensions_Add_set (extension, &initial_extensions[i]);
+      _User_extensions_Add_set_with_table (extension, &initial_extensions[i]);
       extension++;
     }
   }
diff --git a/cpukit/score/src/userextaddset.c b/cpukit/score/src/userextaddset.c
index 516477a50e..fd732e73c4 100644
--- a/cpukit/score/src/userextaddset.c
+++ b/cpukit/score/src/userextaddset.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,28 +24,19 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/**
- *  This routine is used to add a user extension set to the active list.
- *
- *  @note Must be before _User_extensions_Handler_initialization to
- *        ensure proper inlining.
- */
-
-void _User_extensions_Add_set (
-  User_extensions_Control *the_extension,
-  User_extensions_Table   *extension_table
+void _User_extensions_Add_set(
+  User_extensions_Control *the_extension
 )
 {
-  the_extension->Callouts = *extension_table;
-
   _Chain_Append( &_User_extensions_List, &the_extension->Node );
 
   /*
    * If a switch handler is present, append it to the switch chain.
    */
 
-  if ( extension_table->thread_switch != NULL ) {
-    the_extension->Switch.thread_switch = extension_table->thread_switch;
+  if ( the_extension->Callouts.thread_switch != NULL ) {
+    the_extension->Switch.thread_switch =
+      the_extension->Callouts.thread_switch;
     _Chain_Append(
       &_User_extensions_Switches_list,
       &the_extension->Switch.Node
diff --git a/cpukit/score/src/userextremoveset.c b/cpukit/score/src/userextremoveset.c
index dcff2ef626..4466007c25 100644
--- a/cpukit/score/src/userextremoveset.c
+++ b/cpukit/score/src/userextremoveset.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,10 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/**
- *  This routine is used to remove a user extension set from the active list.
- */
-
 void _User_extensions_Remove_set (
   User_extensions_Control  *the_extension
 )
diff --git a/cpukit/score/src/userextthreadbegin.c b/cpukit/score/src/userextthreadbegin.c
index 7c36604d2a..eacdc15706 100644
--- a/cpukit/score/src/userextthreadbegin.c
+++ b/cpukit/score/src/userextthreadbegin.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,12 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/*PAGE
- *
- *  _User_extensions_Thread_begin
- *
- */
-
 void _User_extensions_Thread_begin (
   Thread_Control *executing
 )
@@ -40,11 +42,6 @@ void _User_extensions_Thread_begin (
   }
 }
 
-/*PAGE
- *
- *  _User_extensions_Thread_exitted
- */
-
 void _User_extensions_Thread_exitted (
   Thread_Control *executing
 )
@@ -63,11 +60,6 @@ void _User_extensions_Thread_exitted (
   }
 }
 
-/*PAGE
- *
- *  _User_extensions_Fatal
- */
-
 void _User_extensions_Fatal (
   Internal_errors_Source  the_source,
   bool                    is_internal,
diff --git a/cpukit/score/src/userextthreadcreate.c b/cpukit/score/src/userextthreadcreate.c
index 2b6c3f21c7..b7e7e6e855 100644
--- a/cpukit/score/src/userextthreadcreate.c
+++ b/cpukit/score/src/userextthreadcreate.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,11 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/*PAGE
- *
- *  _User_extensions_Thread_create
- */
-
 bool _User_extensions_Thread_create (
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/userextthreaddelete.c b/cpukit/score/src/userextthreaddelete.c
index 4f7214805b..393580f3ab 100644
--- a/cpukit/score/src/userextthreaddelete.c
+++ b/cpukit/score/src/userextthreaddelete.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,11 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/*PAGE
- *
- *  _User_extensions_Thread_delete
- */
-
 void _User_extensions_Thread_delete (
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/userextthreadrestart.c b/cpukit/score/src/userextthreadrestart.c
index d8af932cf2..f159c8bb0e 100644
--- a/cpukit/score/src/userextthreadrestart.c
+++ b/cpukit/score/src/userextthreadrestart.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,12 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/*PAGE
- *
- *  _User_extensions_Thread_restart
- *
- */
-
 void _User_extensions_Thread_restart (
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/userextthreadstart.c b/cpukit/score/src/userextthreadstart.c
index 1534571344..e6364e158a 100644
--- a/cpukit/score/src/userextthreadstart.c
+++ b/cpukit/score/src/userextthreadstart.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,12 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/*PAGE
- *
- *  _User_extensions_Thread_start
- *
- */
-
 void _User_extensions_Thread_start (
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/userextthreadswitch.c b/cpukit/score/src/userextthreadswitch.c
index 2a88c9f4f9..e7896e79a0 100644
--- a/cpukit/score/src/userextthreadswitch.c
+++ b/cpukit/score/src/userextthreadswitch.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreUserExt
+ *
+ * @brief User Extension Handler implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,10 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/score/userext.h>
 
-/**
- *  This routine is used to invoke the user extension which
- *  is invoked when a context switch occurs.
- */
 void _User_extensions_Thread_switch (
   Thread_Control *executing,
   Thread_Control *heir