From 3c101f29013c71f6a786f9ac7bdbf29499c47cbb Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Tue, 30 Dec 2008 18:08:30 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@566
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 src/templates/chcore.c |  9 ++++++++-
 src/templates/chcore.h | 18 ++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/templates/chcore.c b/src/templates/chcore.c
index c15f1c490..5a887d6ed 100644
--- a/src/templates/chcore.c
+++ b/src/templates/chcore.c
@@ -88,12 +88,19 @@ void chSysUnlock(void) {
 }
 
 /**
- * Context switch.
+ * Performs a context switch.
+ * This is the most critical code in any port, this function is responsible
+ * for the context switch between 2 threads.
+ * @param otp the thread to be switched out
+ * @param ntp the thread to be switched in
+ * @note The implementation of this code affects <b>directly</b> the context
+ *       switch performance so optimize here as much as you can.
  */
 void chSysSwitchI(Thread *otp, Thread *ntp) {}
 
 /**
  * Prints a message on the system console (if any).
+ * @param msg the message to be printed on the system console
  */
 void chSysPuts(char *msg) {
 }
diff --git a/src/templates/chcore.h b/src/templates/chcore.h
index 7690b7ce7..e551f3a61 100644
--- a/src/templates/chcore.h
+++ b/src/templates/chcore.h
@@ -32,27 +32,39 @@
 
 /**
  * Base type for stack alignment.
+ * This type is used only for stack alignment reasons thus can be anything from
+ * a char to a double.
  */
 typedef uint8_t stkalign_t;
 
 /**
  * Interrupt saved context.
+ * This structure represents the stack frame saved during a preemption-capable
+ * interrupt handler.
  */
 struct extctx {
 };
 
 /**
  * System saved context.
+ * This structure represents the inner stack frame during a context switching.
  */
 struct intctx {
 };
 
+/**
+ * Platform dependent part of the @p Thread structure.
+ * This structure usually contains just the saved stack pointer defined as a
+ * pointer to a @p intctx structure.
+ */
 typedef struct {
   struct intctx *sp;
 } Context;
 
 /**
  * Platform dependent part of the \p chThdCreate() API.
+ * This code usually setup the context switching frame represented by a
+ * @p intctx structure.
  */
 #define SETUP_CONTEXT(workspace, wsize, pf, arg)                        \
 {                                                                       \
@@ -60,12 +72,18 @@ typedef struct {
 
 /**
  * Stack size for the system idle thread.
+ * This size depends on the idle thread implementation, usually the idle
+ * thread should take no more space than those reserved
+ * by @p INT_REQUIRED_STACK.
  */
 #define IDLE_THREAD_STACK_SIZE 0
 
 /**
  * Per-thread stack overhead for interrupts servicing, it is used in the
  * calculation of the correct working area size.
+ * This value can be zero on those architecture where there is a separate
+ * interrupt stack and the stack space between @p intctx and @p extctx is
+ * known to be zero.
  */
 #define INT_REQUIRED_STACK 0
 
-- 
cgit v1.2.3