2009-09-08 Sebastian Huber <sebastian.huber@embedded-brains.de>

	* include/irq-config.h, include/irq-generic.h, include/irq-info.h,
	src/irq-generic.c, src/irq-info.c, src/irq-legacy.c, src/irq-shell.c:
	Format, cleanup and documentation.
	* src/irq-server.c: New file.
	* include/bootcard.h, include/stackalloc.h, src/stackalloc.c,
	bsplibc.c: Update for heap API changes. Documentation.

1 files changed, 76 insertions, 7 deletions

diff --git a/c/src/lib/libbsp/shared/include/bootcard.h b/c/src/lib/libbsp/shared/include/bootcard.h
index 9a6dcfdb93..ed0c5598bb 100644
--- a/c/src/lib/libbsp/shared/include/bootcard.h
+++ b/c/src/lib/libbsp/shared/include/bootcard.h
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @ingroup bsp_shared
+ * @ingroup bsp_bootcard
  *
- * @brief Header file for basic BSP startup functions.
+ * @brief Standard system startup.
  */
 
 /*
@@ -21,7 +21,19 @@
  */
 
 /**
- * @defgroup bsp_shared Shared BSP Code
+ * @defgroup bsp_kit Board Support Package
+ *
+ * @brief Board support package dependent code.
+ */
+
+/**
+ * @defgroup bsp_bootcard Bootcard
+ *
+ * @ingroup bsp_kit
+ *
+ * @brief Standard system startup.
+ *
+ * @{
  */
 
 #ifndef LIBBSP_SHARED_BOOTCARD_H
@@ -37,6 +49,11 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @brief Global pointer to the command line of boot_card().
+ */
+extern const char *bsp_boot_cmdline;
+
 void bsp_start(void);
 
 void bsp_pretasking_hook(void);
@@ -49,20 +66,72 @@ void bsp_cleanup(void);
 
 void bsp_reset(void);
 
+/**
+ * @brief Should be used as the heap begin address in bsp_get_work_area() if
+ * the heap area is contained in the work area.
+ */
 #define BSP_BOOTCARD_HEAP_USES_WORK_AREA NULL
 
+/**
+ * @brief Should be used to request the default heap size in bsp_get_work_area().
+ *
+ * In case that the heap area is contained in the work area this heap size
+ * value indicates that the area outside the work space should be used as heap
+ * space.
+ */
 #define BSP_BOOTCARD_HEAP_SIZE_DEFAULT 0
 
 void bsp_get_work_area(
-  void      **work_area_start,
+  void      **work_area_begin,
   uintptr_t  *work_area_size,
-  void      **heap_start,
+  void      **heap_begin,
   uintptr_t  *heap_size
 );
 
-int boot_card( const char *cmdline );
+/**
+ * @brief Standard system initialization procedure.
+ *
+ * You may pass a command line in @a cmdline.  It is later available via the
+ * global @ref bsp_boot_cmdline variable.
+ *
+ * This is the C entry point for ALL RTEMS BSPs.  It is invoked from the
+ * assembly language initialization file usually called @c start.S which does
+ * the basic CPU setup (stack, C runtime environment, zero BSS, load other
+ * sections) and calls afterwards boot_card().  The boot card function provides
+ * the framework for the BSP initialization sequence.  The basic flow of
+ * initialization is:
+ *
+ * - disable interrupts, interrupts will be enabled during the first context switch
+ * - bsp_start() - more advanced initialization
+ * - obtain information on BSP memory via bsp_get_work_area() and allocate RTEMS Workspace
+ * - rtems_initialize_data_structures()
+ * - allocate memory for C Program Heap
+ * - initialize C Library and C Program Heap
+ * - bsp_pretasking_hook()
+ * - if defined( RTEMS_DEBUG )
+ *   - rtems_debug_enable( RTEMS_DEBUG_ALL_MASK )
+ * - rtems_initialize_before_drivers()
+ * - bsp_predriver_hook()
+ * - rtems_initialize_device_drivers()
+ *   - initialization of all device drivers
+ * - bsp_postdriver_hook()
+ * - rtems_initialize_start_multitasking()
+ *   - 1st task executes C++ global constructors
+ *   - .... appplication runs ...
+ *   - exit
+ * - back to here eventually
+ * - bsp_cleanup()
+ *
+ * If something goes wrong bsp_cleanup() will be called out of order.
+ *
+ * This style of initialization ensures that the C++ global constructors are
+ * executed after RTEMS is initialized.
+ */
+int boot_card(const char *cmdline);
+
+/** @} */
 
-void bsp_libc_init( void *heap_start, size_t heap_size, size_t sbrk_amount);
+void bsp_libc_init(void *heap_begin, uintptr_t heap_size, size_t sbrk_amount);
 
 #ifdef __cplusplus
 }