1 files changed, 95 insertions, 0 deletions
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>.
+ * .
+ */