C user guide clean up. Up to timer manager.

1 files changed, 127 insertions, 145 deletions

diff --git a/c_user/initialization.rst b/c_user/initialization.rst
index e2a823b..95c6e59 100644
--- a/c_user/initialization.rst
+++ b/c_user/initialization.rst
@@ -1,16 +1,19 @@
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
 Initialization Manager
 ######################
 
 Introduction
 ============
 
-The Initialization Manager is responsible for
-initiating and shutting down RTEMS.  Initiating RTEMS involves
-creating and starting all configured initialization tasks, and
-for invoking the initialization routine for each user-supplied
-device driver.  In a multiprocessor configuration, this manager
-also initializes the interprocessor communications layer.  The
-directives provided by the Initialization Manager are:
+The Initialization Manager is responsible for initiating and shutting down
+RTEMS.  Initiating RTEMS involves creating and starting all configured
+initialization tasks, and for invoking the initialization routine for each
+user-supplied device driver.  In a multiprocessor configuration, this manager
+also initializes the interprocessor communications layer.  The directives
+provided by the Initialization Manager are:
 
 - ``rtems_initialize_executive`` - Initialize RTEMS
 
@@ -23,97 +26,85 @@ Initialization Tasks
 --------------------
 .. index:: initialization tasks
 
-Initialization task(s) are the mechanism by which
-RTEMS transfers initial control to the user's application.
-Initialization tasks differ from other application tasks in that
-they are defined in the User Initialization Tasks Table and
-automatically created and started by RTEMS as part of its
-initialization sequence.  Since the initialization tasks are
-scheduled using the same algorithm as all other RTEMS tasks,
-they must be configured at a priority and mode which will ensure
-that they will complete execution before other application tasks
-execute.  Although there is no upper limit on the number of
-initialization tasks, an application is required to define at
-least one.
-
-A typical initialization task will create and start
-the static set of application tasks.  It may also create any
-other objects used by the application.  Initialization tasks
-which only perform initialization should delete themselves upon
-completion to free resources for other tasks.  Initialization
-tasks may transform themselves into a "normal" application task.
-This transformation typically involves changing priority and
-execution mode.  RTEMS does not automatically delete the
-initialization tasks.
+Initialization task(s) are the mechanism by which RTEMS transfers initial
+control to the user's application.  Initialization tasks differ from other
+application tasks in that they are defined in the User Initialization Tasks
+Table and automatically created and started by RTEMS as part of its
+initialization sequence.  Since the initialization tasks are scheduled using
+the same algorithm as all other RTEMS tasks, they must be configured at a
+priority and mode which will ensure that they will complete execution before
+other application tasks execute.  Although there is no upper limit on the
+number of initialization tasks, an application is required to define at least
+one.
+
+A typical initialization task will create and start the static set of
+application tasks.  It may also create any other objects used by the
+application.  Initialization tasks which only perform initialization should
+delete themselves upon completion to free resources for other tasks.
+Initialization tasks may transform themselves into a "normal" application task.
+This transformation typically involves changing priority and execution mode.
+RTEMS does not automatically delete the initialization tasks.
 
 System Initialization
 ---------------------
 
-System Initialization begins with board reset and continues
-through RTEMS initialization, initialization of all device
-drivers, and eventually a context switch to the first user
-task.  Remember, that interrupts are disabled during
-initialization and the *initialization context* is not
-a task in any sense and the user should be very careful
-during initialization.
-
-The BSP must ensure that the there is enough stack
-space reserved for the initialization context to
-successfully execute the initialization routines for
-all device drivers and, in multiprocessor configurations, the
-Multiprocessor Communications Interface Layer initialization
-routine.
+System Initialization begins with board reset and continues through RTEMS
+initialization, initialization of all device drivers, and eventually a context
+switch to the first user task.  Remember, that interrupts are disabled during
+initialization and the *initialization context* is not a task in any sense and
+the user should be very careful during initialization.
+
+The BSP must ensure that the there is enough stack space reserved for the
+initialization context to successfully execute the initialization routines for
+all device drivers and, in multiprocessor configurations, the Multiprocessor
+Communications Interface Layer initialization routine.
 
 The Idle Task
 -------------
 
-The Idle Task is the lowest priority task in a system
-and executes only when no other task is ready to execute.  This
-default implementation of this task consists of an infinite
-loop. RTEMS allows the Idle Task body to be replaced by a CPU
-specific implementation, a BSP specific implementation or an
-application specific implementation.
+The Idle Task is the lowest priority task in a system and executes only when no
+other task is ready to execute.  This default implementation of this task
+consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
+a CPU specific implementation, a BSP specific implementation or an application
+specific implementation.
 
-The Idle Task is preemptible and *WILL* be preempted when
-any other task is made ready to execute.  This characteristic is
-critical to the overall behavior of any application.
+The Idle Task is preemptible and *WILL* be preempted when any other task is
+made ready to execute.  This characteristic is critical to the overall behavior
+of any application.
 
 Initialization Manager Failure
 ------------------------------
 
-The ``rtems_fatal_error_occurred`` directive will
-be invoked from ``rtems_initialize_executive``
-for any of the following reasons:
+The ``rtems_fatal_error_occurred`` directive will be invoked from
+``rtems_initialize_executive`` for any of the following reasons:
 
-- If either the Configuration Table or the CPU Dependent
-  Information Table is not provided.
+- If either the Configuration Table or the CPU Dependent Information Table is
+  not provided.
 
-- If the starting address of the RTEMS RAM Workspace,
-  supplied by the application in the Configuration Table, is NULL
-  or is not aligned on a four-byte boundary.
+- If the starting address of the RTEMS RAM Workspace, supplied by the
+  application in the Configuration Table, is NULL or is not aligned on a
+  four-byte boundary.
 
-- If the size of the RTEMS RAM Workspace is not large
-  enough to initialize and configure the system.
+- If the size of the RTEMS RAM Workspace is not large enough to initialize and
+  configure the system.
 
 - If the interrupt stack size specified is too small.
 
-- If multiprocessing is configured and the node entry in
-  the Multiprocessor Configuration Table is not between one and
-  the maximum_nodes entry.
+- If multiprocessing is configured and the node entry in the Multiprocessor
+  Configuration Table is not between one and the maximum_nodes entry.
 
-- If a multiprocessor system is being configured and no
-  Multiprocessor Communications Interface is specified.
+- If a multiprocessor system is being configured and no Multiprocessor
+  Communications Interface is specified.
 
-- If no user initialization tasks are configured.  At
-  least one initialization task must be configured to allow RTEMS
-  to pass control to the application at the end of the executive
-  initialization sequence.
+- If no user initialization tasks are configured.  At least one initialization
+  task must be configured to allow RTEMS to pass control to the application at
+  the end of the executive initialization sequence.
 
-- If any of the user initialization tasks cannot be
-  created or started successfully.
+- If any of the user initialization tasks cannot be created or started
+  successfully.
 
-A discussion of RTEMS actions when a fatal error occurs
-may be found `Announcing a Fatal Error`_.
+A discussion of RTEMS actions when a fatal error occurs may be found
+`Announcing a Fatal Error`_.
 
 Operations
 ==========
@@ -121,10 +112,10 @@ Operations
 Initializing RTEMS
 ------------------
 
-The Initialization Manager ``rtems_initialize_executive``
-directives is called by the ``boot_card`` routine.  The ``boot_card``
-routine is invoked by the Board Support Package once a basic C run-time
-environment is set up.  This consists of
+The Initialization Manager ``rtems_initialize_executive`` directives is called
+by the ``boot_card`` routine.  The ``boot_card`` routine is invoked by the
+Board Support Package once a basic C run-time environment is set up.  This
+consists of
 
 - a valid and accessible text section, read-only data, read-write data and
   zero-initialized data,
@@ -136,85 +127,83 @@ environment is set up.  This consists of
 
 - disabled interrupts.
 
-The ``rtems_initialize_executive`` directive uses a system
-initialization linker set to initialize only those parts of the overall RTEMS
-feature set that is necessary for a particular application.  See `Linker Sets`_.  
-Each RTEMS feature used the application may optionally register an
-initialization handler.  The system initialization API is available via``#included <rtems/sysinit.h>``.
+The ``rtems_initialize_executive`` directive uses a system initialization
+linker set to initialize only those parts of the overall RTEMS feature set that
+is necessary for a particular application.  See `Linker Sets`_.  Each RTEMS
+feature used the application may optionally register an initialization handler.
+The system initialization API is available via``#included <rtems/sysinit.h>``.
 
 A list of all initialization steps follows.  Some steps are optional depending
 on the requested feature set of the application.  The initialization steps are
 execute in the order presented here.
 
-:dfn:`RTEMS_SYSINIT_BSP_WORK_AREAS`
+`RTEMS_SYSINIT_BSP_WORK_AREAS`
     The work areas consisting of C Program Heap and the RTEMS Workspace are
     initialized by the Board Support Package.  This step is mandatory.
 
-:dfn:`RTEMS_SYSINIT_BSP_START`
-    Basic initialization step provided by the Board Support Package.  This step is
-    mandatory.
-
-:dfn:`RTEMS_SYSINIT_DATA_STRUCTURES`
-    This directive is called when the Board Support Package has completed its basic
-    initialization and allows RTEMS to initialize the application environment based
-    upon the information in the Configuration Table, User Initialization Tasks
-    Table, Device Driver Table, User Extension Table, Multiprocessor Configuration
-    Table, and the Multiprocessor Communications Interface (MPCI) Table.
-
-:dfn:`RTEMS_SYSINIT_BSP_LIBC`
-    Depending on the application configuration the IO library and root filesystem
-    is initialized.  This step is mandatory.
-
-:dfn:`RTEMS_SYSINIT_BEFORE_DRIVERS`
-    This directive performs initialization that must occur between basis RTEMS data
-    structure initialization and device driver initialization.  In particular, in a
-    multiprocessor configuration, this directive will create the MPCI Server Task.
-
-:dfn:`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
+`RTEMS_SYSINIT_BSP_START`
+    Basic initialization step provided by the Board Support Package.  This step
+    is mandatory.
+
+`RTEMS_SYSINIT_DATA_STRUCTURES`
+    This directive is called when the Board Support Package has completed its
+    basic initialization and allows RTEMS to initialize the application
+    environment based upon the information in the Configuration Table, User
+    Initialization Tasks Table, Device Driver Table, User Extension Table,
+    Multiprocessor Configuration Table, and the Multiprocessor Communications
+    Interface (MPCI) Table.
+
+`RTEMS_SYSINIT_BSP_LIBC`
+    Depending on the application configuration the IO library and root
+    filesystem is initialized.  This step is mandatory.
+
+`RTEMS_SYSINIT_BEFORE_DRIVERS`
+    This directive performs initialization that must occur between basis RTEMS
+    data structure initialization and device driver initialization.  In
+    particular, in a multiprocessor configuration, this directive will create
+    the MPCI Server Task.
+
+`RTEMS_SYSINIT_BSP_PRE_DRIVERS`
     Initialization step performed right before device drivers are initialized
     provided by the Board Support Package.  This step is mandatory.
 
-:dfn:`RTEMS_SYSINIT_DEVICE_DRIVERS`
-    This step initializes all statically configured device drivers and performs all
-    RTEMS initialization which requires device drivers to be initialized.  This
-    step is mandatory.
-    In a multiprocessor configuration, this service will initialize the
-    Multiprocessor Communications Interface (MPCI) and synchronize with the other
-    nodes in the system.
+`RTEMS_SYSINIT_DEVICE_DRIVERS`
+    This step initializes all statically configured device drivers and performs
+    all RTEMS initialization which requires device drivers to be initialized.
+    This step is mandatory.  In a multiprocessor configuration, this service
+    will initialize the Multiprocessor Communications Interface (MPCI) and
+    synchronize with the other nodes in the system.
 
-:dfn:`RTEMS_SYSINIT_BSP_POST_DRIVERS`
+`RTEMS_SYSINIT_BSP_POST_DRIVERS`
     Initialization step performed right after device drivers are initialized
     provided by the Board Support Package.  This step is mandatory.
 
-The final action of the ``rtems_initialize_executive`` directive
-is to start multitasking.  RTEMS does not return to the initialization context
-and the initialization stack may be re-used for interrupt processing.
+The final action of the ``rtems_initialize_executive`` directive is to start
+multitasking.  RTEMS does not return to the initialization context and the
+initialization stack may be re-used for interrupt processing.
 
-Many of RTEMS actions during initialization are based upon
-the contents of the Configuration Table.  For more information
-regarding the format and contents of this table, please refer
-to the chapter `Configuring a System`_.
+Many of RTEMS actions during initialization are based upon the contents of the
+Configuration Table.  For more information regarding the format and contents of
+this table, please refer to the chapter `Configuring a System`_.
 
-The final action in the initialization sequence is the
-initiation of multitasking.  When the scheduler and dispatcher
-are enabled, the highest priority, ready task will be dispatched
-to run.  Control will not be returned to the Board Support
-Package after multitasking is enabled.  The initialization stack may be re-used
-for interrupt processing.
+The final action in the initialization sequence is the initiation of
+multitasking.  When the scheduler and dispatcher are enabled, the highest
+priority, ready task will be dispatched to run.  Control will not be returned
+to the Board Support Package after multitasking is enabled.  The initialization
+stack may be re-used for interrupt processing.
 
 Shutting Down RTEMS
 -------------------
 
-The ``rtems_shutdown_executive`` directive is invoked by the
-application to end multitasking and terminate the system.
+The ``rtems_shutdown_executive`` directive is invoked by the application to end
+multitasking and terminate the system.
 
 Directives
 ==========
 
-This section details the Initialization Manager's
-directives.  A subsection is dedicated to each of this manager's
-directives and describes the calling sequence, related
-constants, usage, and status codes.
+This section details the Initialization Manager's directives.  A subsection is
+dedicated to each of this manager's directives and describes the calling
+sequence, related constants, usage, and status codes.
 
 INITIALIZE_EXECUTIVE - Initialize RTEMS
 ---------------------------------------
@@ -256,7 +245,7 @@ SHUTDOWN_EXECUTIVE - Shutdown RTEMS
 .. code:: c
 
     void rtems_shutdown_executive(
-    uint32_t result
+        uint32_t result
     );
 
 **DIRECTIVE STATUS CODES:**
@@ -266,19 +255,12 @@ NONE
 **DESCRIPTION:**
 
 This directive is called when the application wishes to shutdown RTEMS.  The
-system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and
-the specified ``result`` code.
+system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` and the
+specified ``result`` code.
 
 **NOTES:**
 
-This directive *must* be the last RTEMS directive
-invoked by an application and it *does not return* to the caller.
+This directive *must* be the last RTEMS directive invoked by an application and
+it *does not return* to the caller.
 
 This directive may be called any time.
-
-.. COMMENT: COPYRIGHT (c) 1988-2014.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-