From: lottaviano <lottaviano@38d2e660-2303-0410-9eaa-f027e97ec537>
Date: Thu, 11 Nov 2010 22:17:44 +0000 (+0000)
Subject: doc: Add documentation for kernel
X-Git-Tag: 2.7.0~386
X-Git-Url: https://codewiz.org/gitweb?a=commitdiff_plain;h=e5cf108988c4259d52872a9cc17728a97fdb1201;p=bertos.git

doc: Add documentation for kernel

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4550 38d2e660-2303-0410-9eaa-f027e97ec537
---

diff --git a/Doxyfile-common b/Doxyfile-common
index f15f7860..a6bd5495 100644
--- a/Doxyfile-common
+++ b/Doxyfile-common
@@ -1244,6 +1244,7 @@ PREDEFINED             = __doxygen__ \
                          CONFIG_KFILE_GETS=1 \
                          CONFIG_XMODEM_RECV=1 \
                          CONFIG_XMODEM_SEND=1 \
+                         CONFIG_KERN_PREEMPT=1 \
                          LOG_LEVEL=3 \
                          CONFIG_HEAP_MALLOC=1 \
                          CONFIG_I2C_DISABLE_OLD_API=0 \
diff --git a/bertos/kern/proc.h b/bertos/kern/proc.h
index 13bd7bf0..d4284ffd 100644
--- a/bertos/kern/proc.h
+++ b/bertos/kern/proc.h
@@ -38,6 +38,51 @@
  *
  * \brief BeRTOS Kernel core (Process scheduler).
  *
+ * This is the core kernel module. It allows you to create new processes
+ * (which are called \b threads in other systems) and set the priority of
+ * each process.
+ *
+ * A process needs a work area (called \b stack) to run. To create a process,
+ * you need to declare a stack area, then create the process.
+ * You may also pass NULL for the stack area, if you have enabled kernel heap:
+ * in this case the stack will be automatically allocated.
+ *
+ * Example:
+ * \code
+ * PROC_DEFINE_STACK(stack1, 200);
+ *
+ * void NORETURN proc1_run(void)
+ * {
+ *    while (1)
+ *    {
+ *       LOG_INFO("I'm alive!\n");
+ *       timer_delay(1000);
+ *    }
+ * }
+ *
+ *
+ * int main()
+ * {
+ *    Process *p1 = proc_new(proc1_run, NULL, stack1, sizeof(stack1));
+ *    // here the process is already running
+ *    proc_setPri(p1, 2);
+ *    // ...
+ * }
+ * \endcode
+ *
+ * The Process struct must be regarded as an opaque data type, do not access
+ * any of its members directly.
+ *
+ * The entry point function should be declared as NORETURN, because it will
+ * remove a warning and enable compiler optimizations.
+ *
+ * You can temporarily disable preemption calling proc_forbid(); remember
+ * to enable it again calling proc_permit().
+ *
+ * \note You should hardly need to manually release the CPU; however you
+ *       can do it using the cpu_relax() function. It is illegal to release
+ *       the CPU with preemption disabled.
+ *
  * \author Bernie Innocenti <bernie@codewiz.org>
  *
  * $WIZ$ module_name = "kernel"
@@ -143,7 +188,7 @@ struct Process *proc_new_with_name(const char *name, void (*entry)(void), iptr_t
  */
 void proc_exit(void);
 
-/**
+/*
  * Public scheduling class methods.
  */
 void proc_yield(void);