bertos/kern/proc.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   6  * Bertos is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  * As a special exception, you may use this file as part of a free software
  21  * library without restriction.  Specifically, if other files instantiate
  22  * templates or use macros or inline functions from this file, or you compile
  23  * this file and link it with other files to produce an executable, this
  24  * file does not by itself cause the resulting executable to be covered by
  25  * the GNU General Public License.  This exception does not however
  26  * invalidate any other reasons why the executable file might be covered by
  27  * the GNU General Public License.
  28  *
  29  * Copyright 2001, 2004 Develer S.r.l. (http://www.develer.com/)
  30  * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
  31  * -->
  32  *
  33  * \brief BeRTOS Kernel core (Process scheduler).
  34  *
  35  * \version $Id$
  36  * \author Bernie Innocenti <bernie@codewiz.org>
  37  *
  38  * $WIZ$ module_name = "kernel"
  39  * $WIZ$ module_configuration = "bertos/cfg/cfg_proc.h"
  40  * $WIZ$ module_depends = "switch_ctx"
  41  * $WIZ$ module_supports = "not atmega103"
  42  */
  43
  44 #ifndef KERN_PROC_H
  45 #define KERN_PROC_H
  46
  47 #include "cfg/cfg_proc.h"
  48 #include "cfg/cfg_signal.h"
  49 #include "cfg/cfg_monitor.h"
  50
  51 #include <struct/list.h> // Node, PriNode
  52
  53 #include <cfg/compiler.h>
  54 #include <cfg/debug.h> // ASSERT()
  55
  56 #include <cpu/types.h> // cpu_stack_t
  57 #include <cpu/frame.h> // CPU_SAVED_REGS_CNT
  58
  59 /*
  60  * WARNING: struct Process is considered private, so its definition can change any time
  61  * without notice. DO NOT RELY on any field defined here, use only the interface
  62  * functions below.
  63  *
  64  * You have been warned.
  65  */
  66 typedef struct Process
  67 {
  68 #if CONFIG_KERN_PRI
  69         PriNode      link;        /**< Link Process into scheduler lists */
  70 #else
  71         Node         link;        /**< Link Process into scheduler lists */
  72 #endif
  73         cpu_stack_t  *stack;       /**< Per-process SP */
  74         iptr_t       user_data;   /**< Custom data passed to the process */
  75
  76 #if CONFIG_KERN_SIGNALS
  77         sigmask_t    sig_wait;    /**< Signals the process is waiting for */
  78         sigmask_t    sig_recv;    /**< Received signals */
  79 #endif
  80
  81 #if CONFIG_KERN_HEAP
  82         uint16_t     flags;       /**< Flags */
  83 #endif
  84
  85 #if CONFIG_KERN_HEAP | CONFIG_KERN_MONITOR
  86         cpu_stack_t  *stack_base;  /**< Base of process stack */
  87         size_t       stack_size;  /**< Size of process stack */
  88 #endif
  89
  90         /* The actual process entry point */
  91         void (*user_entry)(void);
  92
  93 #if CONFIG_KERN_MONITOR
  94         struct ProcMonitor
  95         {
  96                 Node        link;
  97                 const char *name;
  98         } monitor;
  99 #endif
 100
 101 } Process;
 102
 103 /**
 104  * Initialize the process subsystem (kernel).
 105  * It must be called before using any process related function.
 106  */
 107 void proc_init(void);
 108
 109 struct Process *proc_new_with_name(const char *name, void (*entry)(void), iptr_t data, size_t stacksize, cpu_stack_t *stack);
 110
 111 #if !CONFIG_KERN_MONITOR
 112         /**
 113          * Create a new named process and schedules it for execution.
 114          *
 115          * When defining the stacksize take into account that you may want at least:
 116          * \li save all the registers for each nested function call;
 117          * \li have memory for the struct Process, which is positioned at the bottom
 118          * of the stack;
 119          * \li have some memory for temporary variables inside called functions.
 120          *
 121          * The value given by KERN_MINSTACKSIZE is rather safe to use in the first place.
 122          *
 123          * \param entry Function that the process will execute.
 124          * \param data Pointer to user data.
 125          * \param size Length of the stack.
 126          * \param stack Pointer to the memory area to be used as a stack.
 127          *
 128          * \return Process structure of new created process
 129          *         if successful, NULL otherwise.
 130          */
 131         #define proc_new(entry,data,size,stack) proc_new_with_name(NULL,(entry),(data),(size),(stack))
 132 #else
 133         #define proc_new(entry,data,size,stack) proc_new_with_name(#entry,(entry),(data),(size),(stack))
 134 #endif
 135
 136 /**
 137  * Terminate the execution of the current process.
 138  */
 139 void proc_exit(void);
 140
 141 /**
 142  * Public scheduling class methods.
 143  */
 144 void proc_yield(void);
 145
 146 #if CONFIG_KERN_PREEMPT
 147 bool proc_needPreempt(void);
 148 void proc_preempt(void);
 149 #else
 150 INLINE bool proc_needPreempt(void)
 151 {
 152         return false;
 153 }
 154
 155 INLINE void proc_preempt(void)
 156 {
 157 }
 158 #endif
 159
 160 void proc_rename(struct Process *proc, const char *name);
 161 const char *proc_name(struct Process *proc);
 162 const char *proc_currentName(void);
 163
 164 /**
 165  * Return a pointer to the user data of the current process.
 166  *
 167  * To obtain user data, just call this function inside the process. Remember to cast
 168  * the returned pointer to the correct type.
 169  * \return Pointer to the user data of the current process.
 170  */
 171 INLINE iptr_t proc_currentUserData(void)
 172 {
 173         extern struct Process *current_process;
 174         return current_process->user_data;
 175 }
 176
 177 int proc_testSetup(void);
 178 int proc_testRun(void);
 179 int proc_testTearDown(void);
 180
 181 /**
 182  * Return the context structure of the currently running process.
 183  *
 184  * The details of the Process structure are private to the scheduler.
 185  * The address returned by this function is an opaque pointer that can
 186  * be passed as an argument to other process-related functions.
 187  */
 188 INLINE struct Process *proc_current(void)
 189 {
 190         extern struct Process *current_process;
 191         return current_process;
 192 }
 193
 194 #if CONFIG_KERN_PRI
 195         void proc_setPri(struct Process *proc, int pri);
 196 #else
 197         INLINE void proc_setPri(UNUSED_ARG(struct Process *,proc), UNUSED_ARG(int, pri))
 198         {
 199         }
 200 #endif
 201
 202 #if CONFIG_KERN_PREEMPT
 203
 204         /**
 205          * Disable preemptive task switching.
 206          *
 207          * The scheduler maintains a global nesting counter.  Task switching is
 208          * effectively re-enabled only when the number of calls to proc_permit()
 209          * matches the number of calls to proc_forbid().
 210          *
 211          * \note Calling functions that could sleep while task switching is disabled
 212          * is dangerous and unsupported.
 213          *
 214          * \note proc_permit() expands inline to 1-2 asm instructions, so it's a
 215          * very efficient locking primitive in simple but performance-critical
 216          * situations.  In all other cases, semaphores offer a more flexible and
 217          * fine-grained locking primitive.
 218          *
 219          * \sa proc_permit()
 220          */
 221         INLINE void proc_forbid(void)
 222         {
 223                 extern cpu_atomic_t preempt_count;
 224                 /*
 225                  * We don't need to protect the counter against other processes.
 226                  * The reason why is a bit subtle.
 227                  *
 228                  * If a process gets here, preempt_forbid_cnt can be either 0,
 229                  * or != 0.  In the latter case, preemption is already disabled
 230                  * and no concurrency issues can occur.
 231                  *
 232                  * In the former case, we could be preempted just after reading the
 233                  * value 0 from memory, and a concurrent process might, in fact,
 234                  * bump the value of preempt_forbid_cnt under our nose!
 235                  *
 236                  * BUT: if this ever happens, then we won't get another chance to
 237                  * run until the other process calls proc_permit() to re-enable
 238                  * preemption.  At this point, the value of preempt_forbid_cnt
 239                  * must be back to 0, and thus what we had originally read from
 240                  * memory happens to be valid.
 241                  *
 242                  * No matter how hard you think about it, and how complicated you
 243                  * make your scenario, the above holds true as long as
 244                  * "preempt_forbid_cnt != 0" means that no task switching is
 245                  * possible.
 246                  */
 247                 ++preempt_count;
 248
 249                 /*
 250                  * Make sure preempt_count is flushed to memory so the preemption
 251                  * softirq will see the correct value from now on.
 252                  */
 253                 MEMORY_BARRIER;
 254         }
 255
 256         /**
 257          * Re-enable preemptive task switching.
 258          *
 259          * \sa proc_forbid()
 260          */
 261         INLINE void proc_permit(void)
 262         {
 263                 extern cpu_atomic_t preempt_count;
 264
 265                 /*
 266                  * This is to ensure any global state changed by the process gets
 267                  * flushed to memory before task switching is re-enabled.
 268                  */
 269                 MEMORY_BARRIER;
 270                 /* No need to protect against interrupts here. */
 271                 ASSERT(preempt_count > 0);
 272                 --preempt_count;
 273                 /*
 274                  * This ensures preempt_count is flushed to memory immediately so the
 275                  * preemption interrupt sees the correct value.
 276                  */
 277                 MEMORY_BARRIER;
 278         }
 279
 280         /**
 281          * \return true if preemptive task switching is allowed.
 282          * \note This accessor is needed because preempt_count
 283          *       must be absoultely private.
 284          */
 285         INLINE bool proc_preemptAllowed(void)
 286         {
 287                 extern cpu_atomic_t preempt_count;
 288                 return (preempt_count == 0);
 289         }
 290 #else /* CONFIG_KERN_PREEMPT */
 291         #define proc_forbid() /* NOP */
 292         #define proc_permit() /* NOP */
 293         #define proc_preemptAllowed() (true)
 294 #endif /* CONFIG_KERN_PREEMPT */
 295
 296 /** Deprecated, use the proc_preemptAllowed() macro. */
 297 #define proc_allowed() proc_preemptAllowed()
 298
 299 /**
 300  * Execute a block of \a CODE atomically with respect to task scheduling.
 301  */
 302 #define PROC_ATOMIC(CODE) \
 303         do { \
 304                 proc_forbid(); \
 305                 CODE; \
 306                 proc_permit(); \
 307         } while(0)
 308
 309 /**
 310  * Default stack size for each thread, in bytes.
 311  *
 312  * The goal here is to allow a minimal task to save all of its
 313  * registers twice, plus push a maximum of 32 variables on the
 314  * stack. We add also struct Process size since we save it into the process'
 315  * stack.
 316  *
 317  * The actual size computed by the default formula greatly depends on what
 318  * options are active and on the architecture.
 319  *
 320  * Note that on most 16bit architectures, interrupts will also
 321  * run on the stack of the currently running process.  Nested
 322  * interrupts will greatly increases the amount of stack space
 323  * required per process.  Use irqmanager to minimize stack
 324  * usage.
 325  */
 326
 327 #if (ARCH & ARCH_EMUL)
 328         /* We need a large stack because system libraries are bloated */
 329         #define KERN_MINSTACKSIZE 65536
 330 #else
 331         #if CONFIG_KERN_PREEMPT
 332                 /*
 333                  * A preemptible kernel needs a larger stack compared to the
 334                  * cooperative case. A task can be interrupted anytime in each
 335                  * node of the call graph, at any level of depth. This may
 336                  * result in a higher stack consumption, to call the ISR, save
 337                  * the current user context and to execute the kernel
 338                  * preemption routines implemented as ISR prologue and
 339                  * epilogue. All these calls are nested into the process stack.
 340                  *
 341                  * So, to reduce the risk of stack overflow/underflow problems
 342                  * add a x2 to the portion stack reserved to the user process.
 343                  */
 344                 #define KERN_MINSTACKSIZE \
 345                         (sizeof(Process) + CPU_SAVED_REGS_CNT * 2 * sizeof(cpu_stack_t) \
 346                         + 32 * sizeof(int) * 2)
 347         #else
 348                 #define KERN_MINSTACKSIZE \
 349                         (sizeof(Process) + CPU_SAVED_REGS_CNT * 2 * sizeof(cpu_stack_t) \
 350                         + 32 * sizeof(int))
 351         #endif /* CONFIG_KERN_PREEMPT */
 352
 353 #endif
 354
 355 #ifndef CONFIG_KERN_MINSTACKSIZE
 356         /* For backward compatibility */
 357         #define CONFIG_KERN_MINSTACKSIZE KERN_MINSTACKSIZE
 358 #else
 359         #warning FIXME: This macro is deprecated, use KERN_MINSTACKSIZE instead
 360 #endif
 361
 362 /**
 363  * Utility macro to allocate a stack of size \a size.
 364  *
 365  * This macro define a static stack for one process and do
 366  * check if given stack size is enough to run process.
 367  * \note If you plan to use kprintf() and similar functions, you will need
 368  * at least KERN_MINSTACKSIZE * 2 bytes.
 369  *
 370  * \param name Variable name for the stack.
 371  * \param size Stack size in bytes. It must be at least KERN_MINSTACKSIZE.
 372  */
 373 #define PROC_DEFINE_STACK(name, size) \
 374         cpu_stack_t name[((size) + sizeof(cpu_stack_t) - 1) / sizeof(cpu_stack_t)]; \
 375         STATIC_ASSERT((size) >= KERN_MINSTACKSIZE);
 376
 377 /* Memory fill codes to help debugging */
 378 #if CONFIG_KERN_MONITOR
 379         #include <cpu/types.h>
 380         #if (SIZEOF_CPUSTACK_T == 1)
 381                 /* 8bit cpu_stack_t */
 382                 #define CONFIG_KERN_STACKFILLCODE  0xA5
 383                 #define CONFIG_KERN_MEMFILLCODE    0xDB
 384         #elif (SIZEOF_CPUSTACK_T == 2)
 385                 /* 16bit cpu_stack_t */
 386                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5
 387                 #define CONFIG_KERN_MEMFILLCODE    0xDBDB
 388         #elif (SIZEOF_CPUSTACK_T == 4)
 389                 /* 32bit cpu_stack_t */
 390                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5UL
 391                 #define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBUL
 392         #elif (SIZEOF_CPUSTACK_T == 8)
 393                 /* 64bit cpu_stack_t */
 394                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5A5A5A5A5ULL
 395                 #define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBDBDBDBDBULL
 396         #else
 397                 #error No cpu_stack_t size supported!
 398         #endif
 399 #endif
 400
 401 #endif /* KERN_PROC_H */