1 files changed, 83 insertions, 0 deletions
diff --git a/os/hal/hal.dox b/os/hal/hal.dox
new file mode 100644
index 000000000..3e747a4ad
--- /dev/null
+++ b/os/hal/hal.dox
@@ -0,0 +1,83 @@
+/*
+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
+                 2011,2012,2013 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/>.
+*/
+
+/**
+ * @defgroup IO HAL
+ * @brief   Hardware Abstraction Layer.
+ * @details Under ChibiOS/RT the set of the various device driver interfaces
+ * is called the HAL subsystem: Hardware Abstraction Layer. The HAL is the
+ * abstract interface between ChibiOS/RT application and hardware.
+ *
+ * @section hal_device_driver_arch HAL Device Drivers Architecture
+ * A device driver is usually split in two layers:
+ * - High Level Device Driver (<b>HLD</b>). This layer contains the definitions
+ *   of the driver's APIs and the platform independent part of the driver.<br>
+ *   An HLD is composed by two files:
+ *   - @p @<driver@>.c, the HLD implementation file. This file must be
+ *     included in the Makefile in order to use the driver.
+ *   - @p @<driver@>.h, the HLD header file. This file is implicitly
+ *     included by the HAL header file @p hal.h.
+ *   .
+ * - Low Level Device Driver (<b>LLD</b>). This layer contains the platform
+ *   dependent part of the driver.<br>
+ *   A LLD is composed by two files:
+ *   - @p @<driver@>_lld.c, the LLD implementation file. This file must be
+ *     included in the Makefile in order to use the driver.
+ *   - @p @<driver@>_lld.h, the LLD header file. This file is implicitly
+ *     included by the HLD header file.
+ *   .
+ *   The LLD may be not present in those drivers that do not access the
+ *   hardware directly but through other device drivers, as example the
+ *   MMC_SPI driver uses the SPI and PAL drivers in order to implement
+ *   its functionalities.
+ * .
+ * @subsection hal_device_driver_diagram Diagram
+ * @dot
+  digraph example {
+    graph [size="5, 7", pad="1.5, 0"];
+    node [shape=rectangle, fontname=Helvetica, fontsize=8,
+          fixedsize="true", width="2.0", height="0.4"];
+    edge [fontname=Helvetica, fontsize=8];
+
+    app [label="Application"];
+    hld [label="High Level Driver"];
+    lld [label="Low Level Driver"];
+    hw [label="Microcontroller Hardware"];
+    hal_lld [label="HAL shared low level code"];
+
+    app->hld;
+    hld->lld;
+    lld-> hw;
+    lld->hal_lld;
+    hal_lld->hw;
+  }
+ * @enddot
+ */
+
+/**
+ * @defgroup HAL_CONF Configuration
+ * @brief   HAL Configuration.
+ * @details The file @p halconf.h contains the high level settings for all
+ * the drivers supported by the HAL. The low level, platform dependent,
+ * settings are contained in the @p mcuconf.h file instead and are describe
+ * in the various platforms reference manuals.
+ *
+ * @ingroup IO
+ */