git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1905 35acf78f-673a-0410-8e92-d51de3d6d3f4

docs/src/articles.dox

@@ -22,11 +22,14 @@
  * ChibiOS/RT Articles and Code Examples:
  * - @subpage article_eclipse
  * - @subpage article_eclipse2
+ * - @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
@@ -35,7 +38,6 @@
  * - @subpage article_saveram
  * - @subpage article_jitter
  * - @subpage article_timing
- * - @subpage article_portguide
  * - @subpage article_design
  * .
  */

docs/src/integrationguide.dox

@@ -0,0 +1,95 @@
+/*
+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+
+    This file is part of ChibiOS/RT.
+
+    ChibiOS/RT is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 3 of the License, or
+    (at your option) any later version.
+
+    ChibiOS/RT is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @page article_integrationguide Integration Guide
+ * All the delivered ChibiOS/RT demos are stand alone applications so if
+ * you just start your application from an existing demo there isn't any
+ * integration effort, you are simply using the existing makefiles, the
+ * default startup files etc, minimal effort.<br>
+ * The matter is very different if you are going to integrate the OS into
+ * a different runtime framework or want to use a different build system,
+ * in that case you have the problem to integrate the OS source code into
+ * your application.
+ *
+ * <h2>What this guide does not cover</h2>
+ * This guide has a limited scope, the following topics are handled elsewhere:
+ * - Porting the OS to different architectures or different compilers is
+ *   not covered in this guide, see @ref article_portguide instead.
+ * - This guide does not describe any specific environment or development
+ *   tool, it is assumed you already know in detail the environment you
+ *   want to work with.
+ * .
+ *
+ * <h2>Article Index</h2>
+ * - @ref integrationguide_kernel
+ * - @ref integrationguide_hal
+ * .
+ * @section integrationguide_kernel Integrating the Kernel
+ * This section covers the scenario where you want to use the ChibiOS/RT
+ * kernel into an existing application. In order to accomplish this you need
+ * to import in your project two components:
+ * - The portable kernel.
+ * - The port layer for your microcontroller.
+ * .
+ * See the @ref architecture for more details.
+ * You need to add the following files to your build process:
+ * - All the source files contained under <tt>./os/kernel/src</tt>, note that
+ *   you should add all of them even if you don't plan to use some of the
+ *   subsystems. Unused subsystems can be excluded from the kernel
+ *   configuration file @p chconf.h.
+ * - All the source files contained under
+ *   <tt>./os/<i>@<compiler@></i>/<i>@<architecture@></i></tt>. Note that those
+ *   could be both C source files and assembler source files and that some
+ *   architectures have an extra directories layer containing files required
+ *   for a specific platform.
+ * .
+ * You also need to add to the compiler options the following paths for
+ * searching header files:
+ * - The portable kernel headers <tt>./os/kernel/include</tt>.
+ * - The port layer headers
+ *   <tt>./os/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
+ * .
+ * @section integrationguide_hal Integrating the HAL
+ * If, in addition to the kernel as described in the previous section, you also
+ * need to integrate the HAL into your application you also need to import
+ * the following components:
+ * - HAL portable files.
+ * - Platform specific files.
+ * .
+ * See the @ref architecture for more details.
+ * You need to add the following files to your build process:
+ * - All the source files contained under <tt>./os/hal/src</tt>, note that
+ *   you should add all of them even if you don't plan to use some of the
+ *   subsystems. Unused drivers can be excluded from the HAL configuration
+ *   file @p halconf.h.
+ * - All the source files contained under
+ *   <tt>./os/hal/platforms/<i>@<platform@></i></tt>.
+ * - All the source files contained under
+ *   <tt>./boards/<i>@<board_model@></i></tt>.
+ * .
+ * You also need to add to the compiler options the following paths for
+ * searching header files:
+ * - The portable HAL headers <tt>./os/hal/src</tt>.
+ * - The platform layer headers
+ *   <tt>./os/hal/platforms/<i>@<platform@></i></tt>.
+ * - The board description headers
+ *   <tt>./boards/<i>@<board_model@></i></tt>.
+ * .
+ */

docs/src/portguide.dox

@@ -40,17 +40,20 @@
  * applies when porting the OS on a custom hardware using a supported
  * microcontroller. This task can be easily performed with the following
  * steps:
- * -# Create a new directory under the ChibiOS/RT installation directory:
- *    <code>./projects/<i>@<my_app_name@></i></code>
- * -# Copy the microcontroller demo code under the newly created directory.
- * -# Customize the demo. Usually there are only four files that need to
- *    be modified:
+ * -# Create a new directory under ./boards and copy inside the board files
+ *    from another board using the same microcontroller.
+ * -# Customize the board files:
  *   - @p board.h This file contains the I/O pins setup for the uC, it
- *     may also contain other board-dependent settings, as example, clock and
- *     PLL settings. Customize this file depending on your target hardware.
+ *     may also contain other board-dependent settings, as example, the clock
+ *     frequency. Customize this file depending on your target hardware.
  *   - @p board.c This file contains the initialization code, it is possible
  *     you just need to customize @p board.h and not this file. If you have
  *     some hardware specific initialization code then put it here.
+ *   .
+ * -# Create a new directory under the ChibiOS/RT installation directory:
+ *    <code>./projects/<i>@<my_app_name@></i></code>
+ * -# Copy an existing demo code under the newly created directory.
+ * -# Customize the demo:
  *   - @p Makefile You may edit this file in order to remove the test related
  *     sources and/or add you application source files.
  *   - @p main.c It contains the demo simple code, clean it and write your

docs/src/stop_os.dox

@@ -0,0 +1,63 @@
+/*
+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+
+    This file is part of ChibiOS/RT.
+
+    ChibiOS/RT is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 3 of the License, or
+    (at your option) any later version.
+
+    ChibiOS/RT is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @page article_stop_os How to cleanly stop the OS
+ * Stopping the OS should not be normally required but there are scenarios
+ * where one might want the complete control over the system again.
+ * As example entering into a bootload mode, or invoking some flashing
+ * algorithm locked in ROM.<br>
+ * ChibiOS/RT does not have a shutdown API and there is a reason for this,
+ * stopping the kernel would not be enough, a well defined operations sequence
+ * is required.<br>
+ * The shutdown operation should always be implemented into the @p main()
+ * function because in that context the stack pointer is guaranteed to be
+ * in the area allocated by the startup code. Stopping from a thread would
+ * leave the stack pointer "somewhere".<br>
+ * The shutdown sequence should include the following steps, some steps
+ * are optional and depend on the application:
+ * - Safely stop critical threads. As example a thread that uses a File System
+ *   should flush all the modified buffers to the persistent storage before
+ *   terminating.<br>
+ *   The system should be designed to request the thread termination using
+ *   @p chThdTerminate() and then wait its termination using @p chThdWait().
+ *   This phase can be skipped for non-critical threads.
+ * - Invoke the xxxStop() method on all the active device drivers, this
+ *   disables the interrupt sources used by the various peripherals. This
+ *   is required in order to not have interrupts after the shutdown that
+ *   may invoke OS primitives.
+ * - Invoke chSysDisable().
+ * - Stop the system timer whose service routine invokes
+ *   @p chSysTimerHandlerI().
+ * - Disable any other interrupt source that may invoke OS APIs. In general
+ *   all the interrupt sources that have handlers declared by using the
+ *   @p CH_IRQ_HANDLER() macro.
+ * - Perform any application related de-initialization.
+ * - Invoke chSysEnable().
+ * .
+ * Now the OS is stopped and you can safely assume there are nothing going on
+ * under the hood. From here you can also restart the OS after finishing your
+ * critical operations using the following sequence:
+ * - Invoke chSysDisable().
+ * - Restart the system timer.
+ * - Reinitialize the OS by invoking @p chSysInit().
+ * - Restart your device drivers using the @p xxxStart() methods.
+ * - Restart all your threads.
+ * .
+ */

readme.txt

@@ -83,9 +83,10 @@
   toolchains because the latest YAGARTO now uses that setting. It is still
   possible to use arm-elf- toolchains by editing the TRGT variable in the
   makefiles.
-- Various documentation fixes, added an article covering debugging under
-  ChibiOS/RT, updated the article about interrupt handlers to cover also
-  fast interrupt sources.
+- Various documentation fixes, added new articles covering debugging under
+  ChibiOS/RT, OS integration, OS stop and restart. Updated the article about
+  interrupt handlers to cover also fast interrupt sources, updated the article
+  about the OS porting.
 - Long overdue test code cleanup and documentation.
 - Added new test cases, now the coverage is again up to 100% except for the
   debug module that would require triggering system terminating tests (panics),