score: rtems_initialize_start_multitasking()

Do not return from rtems_initialize_start_multitasking() and call
rtems_fatal() instead with a fatal source of RTEMS_FATAL_SOURCE_EXIT and
a fatal code with the exit status.

Remove all bsp_cleanup() functions.  The boot_card() is now a no return
function.

c/src/lib/libbsp/lm32/milkymist/startup/bspclean.c

@@ -56,8 +56,3 @@ void bsp_fatal_extension(
   else
     reboot();
 }
-
-void bsp_cleanup(uint32_t status)
-{
-  rtems_fatal(RTEMS_FATAL_SOURCE_EXIT, status);
-}

c/src/lib/libbsp/m68k/mcf5225x/startup/bspclean.c

@@ -1,6 +1,4 @@
 /*
- *  SBC5206 bsp_cleanup
- *
  *  This routine returns control from RTEMS to the monitor.
  *
  *  Author:
@@ -27,10 +25,3 @@ void bsp_fatal_extension(
 {
   printk("\nRTEMS exited!\n");
 }
-
-void  __attribute__((weak)) bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/m68k/mrm332/misc/interr.c

@@ -48,8 +48,3 @@ void bsp_fatal_extension(
   outbyte( (char)(the_error & 0xff) );
   RAW_PUTS(").\r\n");
 }
-
-void bsp_cleanup( uint32_t status )
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/m68k/mvme136/startup/bspclean.c

@@ -44,10 +44,3 @@ void bsp_fatal_extension(
    M68Kvec[ 45 ] = bsp_return_to_monitor_trap;   /* install handler */
    __asm__ volatile( "trap #13" );  /* insures SUPV mode */
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/m68k/mvme147/startup/bspclean.c

@@ -43,10 +43,3 @@ void bsp_fatal_extension(
    M68Kvec[ 45 ] = bsp_return_to_monitor_trap;   /* install handler */
    __asm__ volatile( "trap #13" );  /* ensures SUPV mode */
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/m68k/mvme162/startup/bspclean.c

@@ -55,10 +55,3 @@ void bsp_fatal_extension(
    M68Kvec[ 45 ] = bsp_return_to_monitor_trap;   /* install handler */
    __asm__ volatile( "trap #13" );  /* insures SUPV mode */
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/m68k/mvme167/startup/bspclean.c

@@ -49,19 +49,7 @@ static void bsp_return_to_monitor_trap( void )
   __asm__ volatile( "jmp %0@" : "=a" (start_addr) : "0" (start_addr) );
 }
 
-void bsp_fatal_extension(
-  rtems_fatal_source source,
-  bool is_internal,
-  rtems_fatal_code error
-)
-{
-   M68Kvec[ 45 ] = bsp_return_to_monitor_trap;
-   __asm__ volatile( "trap #13" );
-}
-
 /*
- *  bsp_cleanup
- *
  *  This code was copied from other MC680x0 MVME BSPs.
  *  Our guess is that someone was concerned about the CPU no longer being in
  *  supervisor mode when they got here. This function forces the CPU back to
@@ -73,18 +61,13 @@ void bsp_fatal_extension(
  *  problems if 167Bug is invoked before we get to switch the VBR back to
  *  167Bug because trap 13 is documented as being reserved for the internal
  *  use of the debugger.
- *
- *  Prototyped in rtems/c/src/lib/libbsp/m68k/mvme167/include/bsp.h
- *
- *  Input parameters: NONE
- *
- *  Output parameters: NONE
- *
- *  Return values: DOES NOT RETURN
  */
-void bsp_cleanup(
-  uint32_t status
+void bsp_fatal_extension(
+  rtems_fatal_source source,
+  bool is_internal,
+  rtems_fatal_code error
 )
 {
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
+   M68Kvec[ 45 ] = bsp_return_to_monitor_trap;
+   __asm__ volatile( "trap #13" );
 }

c/src/lib/libbsp/m68k/uC5282/startup/bspclean.c

@@ -1,6 +1,4 @@
 /*
- *  SBC5206 bsp_cleanup
- *
  *  This routine returns control from RTEMS to the monitor.
  *
  *  Author: W. Eric Norum <norume@aps.anl.gov>
@@ -24,10 +22,3 @@ void bsp_fatal_extension(
 {
   bsp_reset();
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/powerpc/beatnik/startup/bspclean.c

@@ -17,10 +17,3 @@ void bsp_fatal_extension(
   );
   bsp_reset();
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/powerpc/mvme5500/startup/bspclean.c

@@ -24,10 +24,3 @@ void bsp_fatal_extension(
   printk("RTEMS terminated; Boot manually or turn on AUTO_BOOT.\n");
 #endif
 }
-
-void bsp_cleanup(
-  uint32_t status
-)
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/powerpc/virtex4/startup/bspclean.c

@@ -1,5 +1,4 @@
-/*  bsp_cleanup()
- *
+/*
  *  This routine normally is part of start.s and usually returns
  *  control to a monitor.
  *
@@ -53,8 +52,3 @@ void bsp_fatal_extension(
   /* All done.  Hang out. */
   BSP_ask_for_reset();
 }
-
-void bsp_cleanup( uint32_t status )
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/powerpc/virtex5/startup/bspclean.c

@@ -1,5 +1,4 @@
-/*  bsp_cleanup()
- *
+/*
  *  This routine normally is part of start.s and usually returns
  *  control to a monitor.
  *
@@ -53,8 +52,3 @@ void bsp_fatal_extension(
   /* All done.  Hang out. */
   BSP_ask_for_reset();
 }
-
-void bsp_cleanup( uint32_t status )
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/shared/bootcard.c

@@ -31,8 +31,7 @@
  *        - 1st task executes C++ global constructors
  *          .... appplication runs ...
  *          - exit
- *     + back to here eventually
- *     + bspclean.c: bsp_cleanup
+ *      + will not return to here
  *
  *  This style of initialization ensures that the C++ global
  *  constructors are executed after RTEMS is initialized.
@@ -69,12 +68,11 @@ const char *bsp_boot_cmdline;
  *  the system while maximizing shared code and keeping BSP code in C
  *  as much as possible.
  */
-uint32_t boot_card(
+void boot_card(
   const char *cmdline
 )
 {
   rtems_interrupt_level  bsp_isr_level;
-  uint32_t               status = 0;
 
   /*
    * Special case for PowerPC: The interrupt disable mask is stored in SPRG0.
@@ -164,22 +162,11 @@ uint32_t boot_card(
    *  Complete initialization of RTEMS and switch to the first task.
    *  Global C++ constructors will be executed in the context of that task.
    */
-  status = rtems_initialize_start_multitasking();
+  rtems_initialize_start_multitasking();
 
   /***************************************************************
    ***************************************************************
-   *  APPLICATION RUNS HERE!!!  When it shuts down, we return!!! *
+   *  APPLICATION RUNS NOW!!!  We will not return to here!!!     *
    ***************************************************************
-   ***************************************************************
-   */
-
-  /*
-   *  Perform any BSP specific shutdown actions which are written in C.
-   */
-  bsp_cleanup( status );
-
-  /*
-   *  Now return to the start code.
-   */
-  return status;
+   ***************************************************************/
 }

c/src/lib/libbsp/shared/bspclean.c

@@ -1,6 +1,4 @@
 /*
- *  This is a dummy bsp_cleanup routine.
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -45,8 +43,3 @@ void bsp_fatal_extension(
     bsp_reset();
   #endif
 }
-
-void bsp_cleanup( uint32_t status )
-{
-  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
-}

c/src/lib/libbsp/shared/include/bootcard.h

@@ -72,8 +72,6 @@ void bsp_predriver_hook(void);
 
 void bsp_postdriver_hook(void);
 
-void bsp_cleanup(uint32_t status);
-
 void bsp_reset(void);
 
 /**
@@ -108,15 +106,12 @@ void bsp_reset(void);
  *   - 1st task executes C++ global constructors
  *   - .... application runs ...
  *   - exit
- * - back to here eventually
- * - bsp_cleanup()
- *
- * If something goes wrong bsp_cleanup() will be called out of order.
+ * - will not return to here
  *
  * This style of initialization ensures that the C++ global constructors are
  * executed after RTEMS is initialized.
  */
-uint32_t boot_card(const char *cmdline);
+void boot_card(const char *cmdline) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
 #ifdef CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
   /**

cpukit/sapi/include/rtems/init.h

@@ -69,16 +69,22 @@ void rtems_initialize_before_drivers(void);
 void rtems_initialize_device_drivers(void);
 
 /**
- *  @brief rtems_initialize_start_multitasking
+ *  @brief Starts the multitasking.
  *
- *  This routine implements the early portion of rtems_initialize_executive
- *  directive up to the pretasking hook. This directive is invoked at system
- *  startup to initialize the RTEMS multitasking environment.
+ *  This directive initiates multitasking and performs a context switch to the
+ *  first user application task and may enable interrupts as a side-effect of
+ *  that context switch.  The context switch saves the executing context.  The
+ *  application runs now.  The directive rtems_shutdown_executive() will return
+ *  to the saved context.  The exit() function will use this directive.
  *
- *  @return This method returns the status code passed into the 
- *          @ref rtems_shutdown_executive directive.
+ *  After a return to the saved context a fatal system state is reached.  The
+ *  fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
+ *  passed to rtems_shutdown_executive().
+ *
+ *  This directive does not return.
  */
-uint32_t rtems_initialize_start_multitasking(void);
+void rtems_initialize_start_multitasking(void)
+  RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
 /**
  *  @brief rtems_shutdown_executive

cpukit/sapi/src/exinit.c

@@ -217,8 +217,10 @@ void rtems_initialize_device_drivers(void)
   _API_extensions_Run_postdriver();
 }
 
-uint32_t rtems_initialize_start_multitasking(void)
+void rtems_initialize_start_multitasking(void)
 {
+  uint32_t status;
+
   _System_state_Set( SYSTEM_STATE_BEGIN_MULTITASKING );
 
   _Thread_Start_multitasking();
@@ -232,5 +234,6 @@ uint32_t rtems_initialize_start_multitasking(void)
    *******************************************************************
    *******************************************************************/
   
-  return _Per_CPU_Information[0].idle->Wait.return_code;
+  status = _Per_CPU_Information[0].idle->Wait.return_code;
+  rtems_fatal( RTEMS_FATAL_SOURCE_EXIT, status );
 }

doc/bsp_howto/init.t

@@ -41,7 +41,6 @@ for this functionality.
 
 @example
 ../../sparc/shared/start.S
-../../sparc/shared/bspclean.c
 @end example
 
 @b{NOTE:} In most BSPs, the directory named @code{start340} in the
@@ -93,10 +92,9 @@ to the shared @code{bootcard.c} framework then through the C Library,
 RTEMS, device driver initialization phases, and the context switch
 to the first application task.  After this, the application executes
 until it calls @code{exit}, @code{rtems_shutdown_executive}, or some
-other normal termination initiating routine and control is returned
-to @code{bootcard.c} which allows the BSP to perform some cleanup in C
-(@code{bsp_cleanup}) and then @code{boot_card} returns to the assembly
-language which initially invoked it.
+other normal termination initiating routine and a fatal system state is
+reached.  The optional @code{bsp_fatal_extension} initial extension can perform
+BSP specific system termination.
 
 The routines invoked during this will be discussed and their location
 in the RTEMS source tree pointed out as we discuss each.
@@ -197,28 +195,26 @@ this point in the initialization sequence.  This is the last opportunity
 for the BSP to insert BSP specific code into the initialization sequence.
 
 @item It invokes the RTEMS directive
-@code{rtems_initialize_start_multitasking()} which starts multitasking and context switches to the first task.  @code{boot_card()} will not return until the application is shutdown.  As part of this sequence the following actions occur:
+@code{rtems_initialize_start_multitasking()}
+which initiates multitasking and performs a context switch to the
+first user application task and may enable interrupts as a side-effect of
+that context switch.  The context switch saves the executing context.  The
+application runs now.  The directive rtems_shutdown_executive() will return
+to the saved context.  The exit() function will use this directive.
 
-@itemize @bullet
+After a return to the saved context a fatal system state is reached.  The
+fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
+passed to rtems_shutdown_executive().
 
-@item RTEMS will context switch to the first application task.  As a
-side-effect of this context switch, processor interrupts will be enabled.
-This is often the source of a fatal error during BSP development because
-the BSP did not clear and/or disable all interrupt sources and a spurious
-interrupt will occur .
+The enabling of interrupts during the first context switch is often the source
+for fatal errors during BSP development because the BSP did not clear and/or
+disable all interrupt sources and a spurious interrupt will occur.
 
-@item When in the context of the first task but before its body has been
+When in the context of the first task but before its body has been
 entered, any C++ Global Constructors will be invoked.
 
 @end itemize
 
-@item Finally after the application shutsdown RTEMS and control is
-return to @code{boot_card()} from RTEMS, it invokes the BSP specific
-routine @code{bsp_cleanup()} to perform any necessary board specific
-shutdown actions.
-
-@end itemize
-
 That's it.  We just went through the entire sequence. 
 
 @subsection bsp_start() - BSP Specific Initialization

doc/bsp_howto/support.t

@@ -179,23 +179,25 @@ this operation.
 @findex CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
 If your BSP does not want to support dynamic heap extension, then you do not have to do anything special.  However, if you want to support @code{sbrk}, you must provide an implementation of this method and define @code{CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK} in @code{bsp.h}.  This informs @code{rtems/confdefs.h} to configure the Malloc Family Extensions which support @code{sbrk}.
 
-@section bsp_cleanup(uint32_t status) - Cleanup the Hardware
+@section bsp_fatal_extension() - Cleanup the Hardware
 
-The @code{bsp_cleanup()} is the last C code invoked.  Most of the BSPs
-use the same shared version of @code{bsp_cleanup()} that does nothing.
-This implementation is located in the following file:
+The @code{bsp_fatal_extension()} is an optional BSP specific initial extension
+invoked once a fatal system state is reached.  Most of the BSPs use the same
+shared version of @code{bsp_fatal_extension()} that does nothing or performs a
+system reset.  This implementation is located in the following file:
 
 @example
 c/src/lib/libbsp/shared/bspclean.c
 @end example
 
-The @code{bsp_cleanup()} routine can be used to return to a ROM monitor,
-insure that interrupt sources are disabled, etc..  This routine is the
-last place to ensure a clean shutdown of the hardware.  The @code{status}
-argument is the value passed to the service which initiated shutting
-down RTEMS.  All of the non-fatal shutdown sequences ultimately pass
-their exit status to @code{rtems_shutdown_executive} and this is what
-is passed to this routine.
+The @code{bsp_fatal_extension()} routine can be used to return to a ROM
+monitor, insure that interrupt sources are disabled, etc..  This routine is the
+last place to ensure a clean shutdown of the hardware.  The fatal source,
+internal error indicator, and the fatal code arguments are available to
+evaluate the fatal condition.  All of the non-fatal shutdown sequences
+ultimately pass their exit status to @code{rtems_shutdown_executive} and this
+is what is passed to this routine in case the fatal source is
+RTEMS_FATAL_SOURCE_EXIT.
 
 On some BSPs, it prints a message indicating that the application
 completed execution and waits for the user to press a key before

doc/user/init.t

@@ -346,7 +346,7 @@ the first context switch.
 @ifset is-C
 @findex rtems_initialize_start_multitasking
 @example
-uint32_t rtems_initialize_start_multitasking(void);
+void rtems_initialize_start_multitasking(void);
 @end example
 @end ifset
 
@@ -358,21 +358,23 @@ NOT SUPPORTED FROM Ada BINDING
 
 @subheading DIRECTIVE STATUS CODES:
 
-This directive returns the status code passed in to the 
-@code{@value{DIRPREFIX}shutdown_executive}.
+NONE
 
 @subheading DESCRIPTION:
 
-This directive is called after the other Initialization Manager
-directives have successfully completed.  This directive
-initiates multitasking and performs a context switch to
-the first user application task and enables interrupts as
-a side-effect of that context switch.
+This directive initiates multitasking and performs a context switch to the
+first user application task and may enable interrupts as a side-effect of
+that context switch.  The context switch saves the executing context.  The
+application runs now.  The directive rtems_shutdown_executive() will return
+to the saved context.  The exit() function will use this directive.
+
+After a return to the saved context a fatal system state is reached.  The
+fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
+passed to rtems_shutdown_executive().
 
 @subheading NOTES:
 
-This directive @b{DOES NOT RETURN} to the caller until the
-@code{@value{DIRPREFIX}shutdown_executive} is invoked.
+This directive @b{DOES NOT RETURN} to the caller.
 
 This directive causes all nodes in the system to
 verify that certain configuration parameters are the same as

testsuites/sptests/spinternalerror01/init.c

@@ -25,7 +25,7 @@
 
 #define FATAL_ERROR 0x600df00d
 
-uint32_t boot_card( const char *cmdline )
+void boot_card( const char *cmdline )
 {
   _Internal_error_Occurred( FATAL_SOURCE, FATAL_IS_INTERNAL, FATAL_ERROR );