proc.h

Go to the documentation of this file.

#ifndef KERN_PROC_H
#define KERN_PROC_H

#include "cfg/cfg_proc.h"
#include "cfg/cfg_signal.h"
#include "cfg/cfg_monitor.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

/*
 * 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;        
#else
    Node         link;        
#endif
    cpu_stack_t  *stack;       
    iptr_t       user_data;   
#if CONFIG_KERN_SIGNALS
    sigmask_t    sig_wait;    
    sigmask_t    sig_recv;    
#endif

#if CONFIG_KERN_HEAP
    uint16_t     flags;       
#endif

#if CONFIG_KERN_HEAP | CONFIG_KERN_MONITOR
    cpu_stack_t  *stack_base;  
    size_t       stack_size;  
#endif

    /* The actual process entry point */
    void (*user_entry)(void);

#if CONFIG_KERN_MONITOR
    struct ProcMonitor
    {
        Node        link;
        const char *name;
    } monitor;
#endif

} Process;

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

    #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

void proc_exit(void);

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);

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);

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

    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;
    }

    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;
    }

    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 */

#define proc_allowed() proc_preemptAllowed()

#define PROC_ATOMIC(CODE) \
    do { \
        proc_forbid(); \
        CODE; \
        proc_permit(); \
    } while(0)

#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

#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

#endif /* KERN_PROC_H */