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: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1907
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/src/stop_os.dox | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

(limited to 'docs/src/stop_os.dox')

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.
  */
-- 
cgit v1.2.3