From c86fdb275a9a7b43eae4a7c80cf915dcb2cd129c Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Fri, 7 May 2010 15:23:42 +0000
Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1907
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/src/articles.dox | 34 +++++++++++++++++----
 docs/src/stop_os.dox  | 70 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 6 deletions(-)

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index 69066c0cc..3846b01f0 100644
--- a/docs/src/articles.dox
+++ b/docs/src/articles.dox
@@ -20,24 +20,46 @@
 /**
  * @page articles Articles and Code Samples
  * ChibiOS/RT Articles and Code Examples:
+ * - @subpage page_general
+ * - @subpage page_kb
+ * - @subpage page_howtos
+ * .
+ */
+
+/**
+ * @page page_general General.
+ * Articles and guides not necessarily related to ChibiOS/RT.
  * - @subpage article_eclipse
  * - @subpage article_eclipse2
+ * - @subpage article_jitter
+ * .
+ */
+
+/**
+ * @page page_kb Knowledge Base.
+ * Articles and guides about ChibiOS/RT.
  * - @subpage article_integrationguide
  * - @subpage article_portguide
  * - @subpage article_debug
- * - @subpage article_create_thread
- * - @subpage article_interrupts
- * - @subpage article_wakeup
- * - @subpage article_manage_memory
- * - @subpage article_stop_os
  * - @subpage article_stacks
  * - @subpage article_roundrobin
  * - @subpage article_lifecycle
  * - @subpage article_mutual_exclusion
  * - @subpage article_atomic
  * - @subpage article_saveram
- * - @subpage article_jitter
  * - @subpage article_timing
  * - @subpage article_design
  * .
  */
+
+/**
+ * @page page_howtos How To's.
+ * Articles describing how to implement specific tasks using ChibiOS/RT.
+ * - @subpage article_create_thread
+ * - @subpage article_interrupts
+ * - @subpage article_wakeup
+ * - @subpage article_manage_memory
+ * - @subpage article_stop_os
+ * .
+ */
+
diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox
index 4fb489a57..d2434dea9 100644
--- a/docs/src/stop_os.dox
+++ b/docs/src/stop_os.dox
@@ -60,4 +60,74 @@
  * - Restart your device drivers using the @p xxxStart() methods.
  * - Restart all your threads.
  * .
+ * <h2>Example</h2>
+ * This is an example of an hypothetical application that have to shutdown
+ * the OS when a certain event is generated.
+ * @code
+#include "ch.h"
+#include "hal.h"
+
+/* A shutdown flag.*/
+bool_t shutdown_required;
+
+/* Critical thread.*/
+static void my_thread(void *p) {
+
+  while (!chThdShouldTerminate()) {
+    /* Normal thread activity code.*/
+  }
+  /* Thread de-initialization before terminating, here you put the critical
+     thread finalization code.*/
+  return 0;
+}
+
+/* Main program, it is entered with interrupts disabled.*/
+void main(void) {
+
+  /* HAL initialization, you need to do this just once.*/
+  halInit();
+
+  /* Main loop, the main() function never exits.*/
+  while (TRUE) {
+    Thread *tp;
+
+    shutdown_required = FALSE;
+
+    /* ChibiOS/RT initialization. This function becomes an OS thread.*/
+    chSysInit();
+
+    /* Starting a device driver, SD2 in this case.*/
+    sdStart(&SD2, NULL);
+
+    /* Starting our critical thread.*/
+    tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256),
+                             NORMALPRIO, my_thread, &SD2);
+
+    /* Main thread activity into a loop.*/
+    while (!shutdown_required) {
+      /* Main activity, OS active until a shutdown becomes necessary.*/
+    }
+
+    /* Starting the shutdown sequence.*/
+    chThdTerminate(tp);     /* Requesting termination.                  */
+    chThdWait(tp);          /* Waiting for the actual termination.      */
+    sdStop(&SD2);           /* Stopping serial port 2.                  */
+    chSysDisable();
+    stop_system_timer();
+    stop_any_other_interrupt();
+    chSysEnable();
+
+    /* Now the main function is again a normal function, no more a
+       OS thread.*/
+    do_funny_stuff();
+
+    /* Restarting the OS but you could also stop the system or trigger a
+       reset instead.*/
+    chSysDisable();
+  }
+}
+ * @endcode
+ * As you can see it is possible to jump in and out of the "OS mode" quite
+ * easily. Note that this is just an example, the real code could be very
+ * different depending on your requirements.
  */