Working

bertos/kern/proc.h

@@ -0,0 +1,463 @@
+/**
+ * \file
+ * <!--
+ * This file is part of BeRTOS.
+ *
+ * Bertos 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 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * As a special exception, you may use this file as part of a free software
+ * library without restriction.  Specifically, if other files instantiate
+ * templates or use macros or inline functions from this file, or you compile
+ * this file and link it with other files to produce an executable, this
+ * file does not by itself cause the resulting executable to be covered by
+ * the GNU General Public License.  This exception does not however
+ * invalidate any other reasons why the executable file might be covered by
+ * the GNU General Public License.
+ *
+ * Copyright 2001, 2004 Develer S.r.l. (http://www.develer.com/)
+ * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
+ * -->
+ *
+ * \defgroup kern_proc Process (Threads) management
+ * \ingroup kern
+ * \{
+ *
+ * \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"
+ * $WIZ$ module_configuration = "bertos/cfg/cfg_proc.h"
+ * $WIZ$ module_depends = "switch_ctx"
+ * $WIZ$ module_supports = "not atmega103"
+ */
+
+#ifndef KERN_PROC_H
+#define KERN_PROC_H
+
+#include "cfg/cfg_proc.h"
+#include "cfg/cfg_signal.h"
+#include "cfg/cfg_monitor.h"
+#include "sem.h"
+
+#include <struct/list.h> // Node, PriNode
+
+#include <cfg/compiler.h>
+#include <cfg/debug.h> // ASSERT()
+
+#include <cpu/types.h> // cpu_stack_t
+#include <cpu/frame.h> // CPU_SAVED_REGS_CNT
+
+/* The following silents warnings on nightly tests. We need to regenerate
+ * all the projects before this can be removed.
+ */
+#ifndef CONFIG_KERN_PRI_INHERIT
+#define CONFIG_KERN_PRI_INHERIT 0
+#endif
+
+/*
+ * WARNING: struct Process is considered private, so its definition can change any time
+ * without notice. DO NOT RELY on any field defined here, use only the interface
+ * functions below.
+ *
+ * You have been warned.
+ */
+typedef struct Process
+{
+#if CONFIG_KERN_PRI
+	PriNode      link;        /**< Link Process into scheduler lists */
+# if CONFIG_KERN_PRI_INHERIT
+	PriNode      inh_link;    /**< Link Process into priority inheritance lists */
+	List         inh_list;    /**< Priority inheritance list for this Process */
+	Semaphore    *inh_blocked_by;  /**< Semaphore blocking this Process */
+	int          orig_pri;    /**< Process priority without considering inheritance */
+# endif
+#else
+	Node         link;        /**< Link Process into scheduler lists */
+#endif
+	cpu_stack_t  *stack;       /**< Per-process SP */
+	iptr_t       user_data;   /**< Custom data passed to the process */
+
+#if CONFIG_KERN_SIGNALS
+	Signal       sig;
+#endif
+
+#if CONFIG_KERN_HEAP
+	uint16_t     flags;       /**< Flags */
+#endif
+
+#if CONFIG_KERN_HEAP | CONFIG_KERN_MONITOR
+	cpu_stack_t  *stack_base;  /**< Base of process stack */
+	size_t       stack_size;  /**< Size of process stack */
+#endif
+
+	/* The actual process entry point */
+	void (*user_entry)(void);
+
+#if CONFIG_KERN_MONITOR
+	struct ProcMonitor
+	{
+		Node        link;
+		const char *name;
+	} monitor;
+#endif
+
+} Process;
+
+/**
+ * Initialize the process subsystem (kernel).
+ * It must be called before using any process related function.
+ */
+void proc_init(void);
+
+struct Process *proc_new_with_name(const char *name, void (*entry)(void), iptr_t data, size_t stacksize, cpu_stack_t *stack);
+
+#if !CONFIG_KERN_MONITOR
+	/**
+	 * Create a new named process and schedules it for execution.
+	 *
+	 * When defining the stacksize take into account that you may want at least:
+	 * \li save all the registers for each nested function call;
+	 * \li have memory for the struct Process, which is positioned at the bottom
+	 * of the stack;
+	 * \li have some memory for temporary variables inside called functions.
+	 *
+	 * The value given by KERN_MINSTACKSIZE is rather safe to use in the first place.
+	 *
+	 * \param entry Function that the process will execute.
+	 * \param data Pointer to user data.
+	 * \param size Length of the stack.
+	 * \param stack Pointer to the memory area to be used as a stack.
+	 *
+	 * \return Process structure of new created process
+	 *         if successful, NULL otherwise.
+	 */
+	#define proc_new(entry,data,size,stack) proc_new_with_name(NULL,(entry),(data),(size),(stack))
+#else
+	#define proc_new(entry,data,size,stack) proc_new_with_name(#entry,(entry),(data),(size),(stack))
+#endif
+
+/**
+ * Terminate the execution of the current process.
+ */
+void proc_exit(void);
+
+/*
+ * Public scheduling class methods.
+ */
+void proc_yield(void);
+
+#if CONFIG_KERN_PREEMPT
+bool proc_needPreempt(void);
+void proc_preempt(void);
+#else
+INLINE bool proc_needPreempt(void)
+{
+	return false;
+}
+
+INLINE void proc_preempt(void)
+{
+}
+#endif
+
+void proc_rename(struct Process *proc, const char *name);
+const char *proc_name(struct Process *proc);
+const char *proc_currentName(void);
+
+/**
+ * Return a pointer to the user data of the current process.
+ *
+ * To obtain user data, just call this function inside the process. Remember to cast
+ * the returned pointer to the correct type.
+ * \return Pointer to the user data of the current process.
+ */
+INLINE iptr_t proc_currentUserData(void)
+{
+	extern struct Process *current_process;
+	return current_process->user_data;
+}
+
+int proc_testSetup(void);
+int proc_testRun(void);
+int proc_testTearDown(void);
+
+/**
+ * Return the context structure of the currently running process.
+ *
+ * The details of the Process structure are private to the scheduler.
+ * The address returned by this function is an opaque pointer that can
+ * be passed as an argument to other process-related functions.
+ */
+INLINE struct Process *proc_current(void)
+{
+	extern struct Process *current_process;
+	return current_process;
+}
+
+#if CONFIG_KERN_PRI
+	void proc_setPri(struct Process *proc, int pri);
+#else
+	INLINE void proc_setPri(UNUSED_ARG(struct Process *,proc), UNUSED_ARG(int, pri))
+	{
+	}
+#endif
+
+#if CONFIG_KERN_PREEMPT
+
+	/**
+	 * Disable preemptive task switching.
+	 *
+	 * The scheduler maintains a global nesting counter.  Task switching is
+	 * effectively re-enabled only when the number of calls to proc_permit()
+	 * matches the number of calls to proc_forbid().
+	 *
+	 * \note Calling functions that could sleep while task switching is disabled
+	 * is dangerous and unsupported.
+	 *
+	 * \note proc_permit() expands inline to 1-2 asm instructions, so it's a
+	 * very efficient locking primitive in simple but performance-critical
+	 * situations.  In all other cases, semaphores offer a more flexible and
+	 * fine-grained locking primitive.
+	 *
+	 * \sa proc_permit()
+	 */
+	INLINE void proc_forbid(void)
+	{
+		extern cpu_atomic_t preempt_count;
+		/*
+		 * We don't need to protect the counter against other processes.
+		 * The reason why is a bit subtle.
+		 *
+		 * If a process gets here, preempt_forbid_cnt can be either 0,
+		 * or != 0.  In the latter case, preemption is already disabled
+		 * and no concurrency issues can occur.
+		 *
+		 * In the former case, we could be preempted just after reading the
+		 * value 0 from memory, and a concurrent process might, in fact,
+		 * bump the value of preempt_forbid_cnt under our nose!
+		 *
+		 * BUT: if this ever happens, then we won't get another chance to
+		 * run until the other process calls proc_permit() to re-enable
+		 * preemption.  At this point, the value of preempt_forbid_cnt
+		 * must be back to 0, and thus what we had originally read from
+		 * memory happens to be valid.
+		 *
+		 * No matter how hard you think about it, and how complicated you
+		 * make your scenario, the above holds true as long as
+		 * "preempt_forbid_cnt != 0" means that no task switching is
+		 * possible.
+		 */
+		++preempt_count;
+
+		/*
+		 * Make sure preempt_count is flushed to memory so the preemption
+		 * softirq will see the correct value from now on.
+		 */
+		MEMORY_BARRIER;
+	}
+
+	/**
+	 * Re-enable preemptive task switching.
+	 *
+	 * \sa proc_forbid()
+	 */
+	INLINE void proc_permit(void)
+	{
+		extern cpu_atomic_t preempt_count;
+
+		/*
+		 * This is to ensure any global state changed by the process gets
+		 * flushed to memory before task switching is re-enabled.
+		 */
+		MEMORY_BARRIER;
+		/* No need to protect against interrupts here. */
+		ASSERT(preempt_count > 0);
+		--preempt_count;
+		/*
+		 * This ensures preempt_count is flushed to memory immediately so the
+		 * preemption interrupt sees the correct value.
+		 */
+		MEMORY_BARRIER;
+	}
+
+	/**
+	 * \return true if preemptive task switching is allowed.
+	 * \note This accessor is needed because preempt_count
+	 *       must be absoultely private.
+	 */
+	INLINE bool proc_preemptAllowed(void)
+	{
+		extern cpu_atomic_t preempt_count;
+		return (preempt_count == 0);
+	}
+#else /* CONFIG_KERN_PREEMPT */
+	#define proc_forbid() /* NOP */
+	#define proc_permit() /* NOP */
+	#define proc_preemptAllowed() (true)
+#endif /* CONFIG_KERN_PREEMPT */
+
+/** Deprecated, use the proc_preemptAllowed() macro. */
+#define proc_allowed() proc_preemptAllowed()
+
+/**
+ * Execute a block of \a CODE atomically with respect to task scheduling.
+ */
+#define PROC_ATOMIC(CODE) \
+	do { \
+		proc_forbid(); \
+		CODE; \
+		proc_permit(); \
+	} while(0)
+
+/**
+ * Default stack size for each thread, in bytes.
+ *
+ * The goal here is to allow a minimal task to save all of its
+ * registers twice, plus push a maximum of 32 variables on the
+ * stack. We add also struct Process size since we save it into the process'
+ * stack.
+ *
+ * The actual size computed by the default formula greatly depends on what
+ * options are active and on the architecture.
+ *
+ * Note that on most 16bit architectures, interrupts will also
+ * run on the stack of the currently running process.  Nested
+ * interrupts will greatly increases the amount of stack space
+ * required per process.  Use irqmanager to minimize stack
+ * usage.
+ */
+
+#if (ARCH & ARCH_EMUL)
+	/* We need a large stack because system libraries are bloated */
+	#define KERN_MINSTACKSIZE 65536
+#else
+	#if CONFIG_KERN_PREEMPT
+		/*
+		 * A preemptible kernel needs a larger stack compared to the
+		 * cooperative case. A task can be interrupted anytime in each
+		 * node of the call graph, at any level of depth. This may
+		 * result in a higher stack consumption, to call the ISR, save
+		 * the current user context and to execute the kernel
+		 * preemption routines implemented as ISR prologue and
+		 * epilogue. All these calls are nested into the process stack.
+		 *
+		 * So, to reduce the risk of stack overflow/underflow problems
+		 * add a x2 to the portion stack reserved to the user process.
+		 */
+		#define KERN_MINSTACKSIZE \
+			(sizeof(Process) + CPU_SAVED_REGS_CNT * 2 * sizeof(cpu_stack_t) \
+			+ 32 * sizeof(int) * 2)
+	#else
+		#define KERN_MINSTACKSIZE \
+			(sizeof(Process) + CPU_SAVED_REGS_CNT * 2 * sizeof(cpu_stack_t) \
+			+ 32 * sizeof(int))
+	#endif /* CONFIG_KERN_PREEMPT */
+
+#endif
+
+#ifndef CONFIG_KERN_MINSTACKSIZE
+	/* For backward compatibility */
+	#define CONFIG_KERN_MINSTACKSIZE KERN_MINSTACKSIZE
+#else
+	#warning FIXME: This macro is deprecated, use KERN_MINSTACKSIZE instead
+#endif
+
+/**
+ * Utility macro to allocate a stack of size \a size.
+ *
+ * This macro define a static stack for one process and do
+ * check if given stack size is enough to run process.
+ * \note If you plan to use kprintf() and similar functions, you will need
+ * at least KERN_MINSTACKSIZE * 2 bytes.
+ *
+ * \param name Variable name for the stack.
+ * \param size Stack size in bytes. It must be at least KERN_MINSTACKSIZE.
+ */
+#define PROC_DEFINE_STACK(name, size) \
+	cpu_stack_t name[((size) + sizeof(cpu_stack_t) - 1) / sizeof(cpu_stack_t)]; \
+	STATIC_ASSERT((size) >= KERN_MINSTACKSIZE);
+
+/* Memory fill codes to help debugging */
+#if CONFIG_KERN_MONITOR
+	#include <cpu/types.h>
+	#if (SIZEOF_CPUSTACK_T == 1)
+		/* 8bit cpu_stack_t */
+		#define CONFIG_KERN_STACKFILLCODE  0xA5
+		#define CONFIG_KERN_MEMFILLCODE    0xDB
+	#elif (SIZEOF_CPUSTACK_T == 2)
+		/* 16bit cpu_stack_t */
+		#define CONFIG_KERN_STACKFILLCODE  0xA5A5
+		#define CONFIG_KERN_MEMFILLCODE    0xDBDB
+	#elif (SIZEOF_CPUSTACK_T == 4)
+		/* 32bit cpu_stack_t */
+		#define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5UL
+		#define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBUL
+	#elif (SIZEOF_CPUSTACK_T == 8)
+		/* 64bit cpu_stack_t */
+		#define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5A5A5A5A5ULL
+		#define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBDBDBDBDBULL
+	#else
+		#error No cpu_stack_t size supported!
+	#endif
+#endif
+/** \} */ //defgroup kern_proc
+
+#endif /* KERN_PROC_H */