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

5 files changed, 175 insertions, 11 deletions

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index 5aff3203e..69066c0cc 100644
--- a/docs/src/articles.dox
+++ b/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

  * .

  */

diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox
new file mode 100644
index 000000000..6eec61e75
--- /dev/null
+++ b/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>.

+ * .

+ */

diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox
index d7de77485..3af53c4cf 100644
--- a/docs/src/portguide.dox
+++ b/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

diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox
new file mode 100644
index 000000000..4fb489a57
--- /dev/null
+++ b/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.

+ * .

+ */

diff --git a/readme.txt b/readme.txt
index f8acafaa5..fbaf8d213 100644
--- a/readme.txt
+++ b/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),