1 files changed, 88 insertions, 0 deletions
diff --git a/docs/src/goals.dox b/docs/src/goals.dox
new file mode 100644
index 000000000..4df7eaba7
--- /dev/null
+++ b/docs/src/goals.dox
@@ -0,0 +1,88 @@
+/*
+    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 goals Project Goals
+ * @{
+ * <h2>Another RTOS?</h2>
+ * The first question to be answered is: there was really the need for YET
+ * ANOTHER RTOS?<br>
+ * My answer is yes because various reasons:
+ * - The ChibiOS/RT ancestor was created more than 15 years ago and while it
+ *   had far less features than the current product it was complete and
+ *   functioning. ChibiOS/RT is just a new (and silly) name given to
+ *   something created when there were not many free RTOSes around (actually
+ *   none, at least none in my knowledge, there was no widespread Internet
+ *   at that time).
+ * - When, after a while, I needed a RTOS again, none of the existing FOSS
+ *   projects met my expectations or my ideas of how a RTOS should be, not
+ *   even close (see below). I decided that work on that old project was
+ *   a better idea that contribute to, or fork, something else.
+ * - I wanted another toy.
+ * .
+ * <h2>Why is it different?</h2>
+ * In itself it implements ideas already seen in other projects but never
+ * all together in a single FOSS project. There are some basic choices in
+ * ChibiOS/RT (mostly derived by its ancestor):
+ *
+ * <h3>Static design</h3>
+ * Everything in the kernel is static, nowhere memory is allocated or freed,
+ * there are two allocator subsystems but those are options and not part of
+ * core OS. Safety is something you design in, not something you can add later.
+ *
+ * <h3>No fixed size tables or structures</h3>
+ * No tables to configure, no arrays that can be filled and overflow at
+ * runtime. Everything without practical upper bounds (except for resource
+ * limits and numerical upper bounds of course).
+ *
+ * <h3>No error conditions and no error checks</h3>
+ * All the API should not have error conditions, all the previous points are
+ * finalized to this objective. Everything you can invoke in the kernel is
+ * designed to not fail unless you pass garbage as parameters, stray pointers
+ * or such. Also the APIs are not slowed down by error checks, error checks
+ * exists but only when the debug switch is activated.<br>
+ * All the static core APIs always succeed if correct parameters are passed.
+ *
+ * <h3>Very simple APIs</h3>
+ * Every API should have the parameters you would expect for that function, no
+ * more no less. Each API should do a single thing with no options.
+ *
+ * <h3>Damn fast and compact</h3>
+ * Note first "fast" then "compact", the focus is on speed and execution
+ * efficiency rather than code size. This does not mean it is large, the OS
+ * with all the subsystems activated is well below 8KiB (32bit ARM code, the
+ * least space efficient) and can shrink down below 2KiB. It would be
+ * possible to make something smaller but:
+ * -# It would be pointless, it @a is already small.
+ * -# I would not sacrifice efficiency or features in order to save few bytes.
+ * .
+ * About the "fast" part, it is able to start/wait/exit more than <b>200,000
+ * threads per second</b> on a 72MHz STM32 (Cortex-M3). The Context Switch just
+ * takes <b>2.3 microseconds</b> on the same STM32. The numbers are not
+ * pulled out of thin air, it is the output of the included test suite.
+ *
+ * <h3>Tests and metrics</h3>
+ * I think it is nice to know how an OS is tested and how it performs before
+ * committing to use it. Test results on all the supported platforms and
+ * performance metrics are included in each ChibiOS/RT release. The test
+ * code is released as well, all the included demos are capable of executing
+ * the test suite and the OS benchmarks.
+ */
+/** @} */
+ 
+\ No newline at end of file