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

1 files changed, 138 insertions, 0 deletions

diff --git a/docs/src/memory.dox b/docs/src/memory.dox
new file mode 100644
index 000000000..727a95b2b
--- /dev/null
+++ b/docs/src/memory.dox
@@ -0,0 +1,138 @@
+/*

+    ChibiOS/RT - Copyright (C) 2006-2007 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_manage_memory How to manage memory

+ * ChibiOS/RT is a static kernel so you don't need to manage memory at all

+ * if your application doesn't really require it. This doesn't mean that

+ * the OS is unable to manage memory but just that memory management is an

+ * optional part of the whole.<br>

+ * The OS offers three distinct ways to manage memory, each one with its

+ * weaknesses and strengths:

+ * - Core Memory Manager. See @ref memcore.

+ * - Heap Allocator. See @ref heaps.

+ * - Memory Pools. See @ref pools.

+ * .

+ * The three mechanisms are able to coexist and are well integrated, as example

+ * the heap allocator uses the core memory manager in order to get more

+ * memory blocks, memory pools can optionally do the same thing.

+ * 

+ * <h2>The three subsystems</h2>

+ * This is a small comparison table regarding the three subsystems, C-runtime

+ * and static objects are thrown there for comparison:<br><br>

+ * <table style="text-align: center; width: 95%;"

+ *        align="center" border="1" cellpadding="2" cellspacing="0">

+ *   <tr>

+ *     <th style="width: 100px; background-color: rgb(192, 192, 192);">

+ *       <small>Subsystem</small>

+ *     </th>

+ *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

+ *       <small>Free capable</small>

+ *     </th>

+ *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

+ *       <small>Constant time</small>

+ *     </th>

+ *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

+ *       <small>Safe</small>

+ *     </th>

+ *     <th style="width: 80px; background-color: rgb(192, 192, 192);">

+ *       <small>From IRQ</small>

+ *     </th>

+ *     <th style="background-color: rgb(192, 192, 192);">

+ *       <small>Notes</small>

+ *     </th>

+ *   </tr>

+ *   <tr>

+ *     <th style="background-color: rgb(224, 224, 224);">

+ *       <small>Static Objects</small>

+ *     </th>

+ *     <td><small>N/A</small></td>

+ *     <td><small>N/A</small></td>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td style="text-align: left;">

+ *       Preferred solution for safety applications.

+ *     </td>

+ *   </tr>

+ *   <tr>

+ *     <th style="background-color: rgb(224, 224, 224);">

+ *       <small>Core Memory Manager</small>

+ *     </th>

+ *     <td><small>NO</small></td>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td style="text-align: left;">

+ *       Fast and safe but unable to free allocated memory.

+ *     </td>

+ *   </tr>

+ *   <tr>

+ *     <th style="background-color: rgb(224, 224, 224);">

+ *       <small>Heap Allocator</small>

+ *     </th>

+ *     <td><small>YES</small></td>

+ *     <td><small>NO</small></td>

+ *     <td><small>NO</small></td>

+ *     <td><small>NO</small></td>

+ *     <td style="text-align: left;">

+ *       Unsafe because fragmentation and not constant time, cannot be used

+ *       from IRQ handlers.

+ *     </td>

+ *   </tr>

+ *   <tr>

+ *     <th style="background-color: rgb(224, 224, 224);">

+ *       <small>Memory Pools</small>

+ *     </th>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td><small>YES</small></td>

+ *     <td style="text-align: left;">

+ *       Fast and safe but it can handle fixed size objects only, you may have

+ *       multiple memory pools however.

+ *     </td>

+ *   </tr>

+ *   <tr>

+ *     <th style="background-color: rgb(224, 224, 224);">

+ *       <small>C-Runtime</small>

+ *     </th>

+ *     <td><small>YES</small></td>

+ *     <td><small>NO</small></td>

+ *     <td><small>NO</small></td>

+ *     <td><small>NO</small></td>

+ *     <td style="text-align: left;">

+ *       Unsafe because fragmentation, not constant time, cannot be used

+ *       from IRQ handlers and not thread safe. The C runtime must also be

+ *       modified in order to work with the other allocators.

+ *     </td>

+ *   </tr>

+ * </table>

+ * <br>

+ * When designing a system it is recommended to proceed as follow:

+ * -# Use static objects and initializers whenever possible.

+ * -# Where dynamic allocation is required without have to free the allocated

+ *    memory then use the Core Memory Manager allocation APIs.

+ * -# Where dynamic allocation is required evaluate if one or more memory

+ *    pools can be used.

+ * -# If all the above points do not satisfy your requirements then use the

+ *    heap allocator.

+ * -# Consider the C-runtime allocator only for legacy code.

+ * .

+ */

+ 
\ No newline at end of file