proc.h File Reference

BeRTOS Kernel core (Process scheduler). More...

#include "cfg/cfg_proc.h"
#include "cfg/cfg_signal.h"
#include "cfg/cfg_monitor.h"
#include <struct/list.h>
#include <cfg/compiler.h>
#include <cpu/types.h>
#include <cpu/frame.h>

Go to the source code of this file.

Defines

#define proc_new(entry, data, size, stack)   proc_new_with_name(NULL,(entry),(data),(size),(stack))
 Create a new named process and schedules it for execution.
#define PROC_ATOMIC(CODE)
 Execute a block of CODE atomically with respect to task scheduling.
#define KERN_MINSTACKSIZE
 Default stack size for each thread, in bytes.
#define PROC_DEFINE_STACK(name, size)
 Utility macro to allocate a stack of size size.

Functions

void proc_init (void)
 Initialize the process subsystem (kernel).
void proc_exit (void)
 Terminate the execution of the current process.
void proc_yield (void)
 Co-operative context switch.
void proc_rename (struct Process *proc, const char *name)
 Rename a process.
const char * proc_name (struct Process *proc)
 Return the name of the specified process.
const char * proc_currentName (void)
 Return the name of the currently running process.
iptr_t proc_currentUserData (void)
 Return a pointer to the user data of the current process.
struct Process * proc_current (void)
 Return the context structure of the currently running process.
void proc_setPri (struct Process *proc, int pri)
 Change the scheduling priority of a process.
void proc_forbid (void)
 Disable preemptive task switching.
void proc_permit (void)
 Re-enable preemptive task switching.
bool proc_allowed (void)

Detailed Description

BeRTOS Kernel core (Process scheduler).

Version:
Id
proc.h 2953 2009-09-16 13:51:30Z lottaviano
Author:
Bernie Innocenti <bernie@codewiz.org>

Definition in file proc.h.

Define Documentation

#define KERN_MINSTACKSIZE
Value:
(sizeof(Process) + CPU_SAVED_REGS_CNT * 2 * sizeof(cpu_stack_t) \
        + 32 * sizeof(int))

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.

Definition at line 326 of file proc.h.

#define PROC_DEFINE_STACK ( name,
size   ) 
Value:
STATIC_ASSERT((size) >= KERN_MINSTACKSIZE); \
    cpu_stack_t name[(size) / sizeof(cpu_stack_t)];

Utility macro to allocate a stack of size 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.
Parameters:
name Variable name for the stack.
size Stack size in bytes. It must be at least KERN_MINSTACKSIZE.

Definition at line 349 of file proc.h.

#define proc_new ( entry,
data,
size,
stack   )     proc_new_with_name(NULL,(entry),(data),(size),(stack))

Create a new named process and schedules it for execution.

When defining the stacksize take into account that you may want at least:

  • save all the registers for each nested function call;
  • have memory for the struct Process, which is positioned at the bottom of the stack;
  • have some memory for temporary variables inside called functions.

The value given by KERN_MINSTACKSIZE is rather safe to use in the first place.

Parameters:
entry Function that the process will execute.
data Pointer to user data.
size Length of the stack.
stack Pointer to the memory area to be used as a stack.
Returns:
Process structure of new created process if successful, NULL otherwise.

Definition at line 135 of file proc.h.

Function Documentation

bool proc_allowed ( void   )  [inline]
Returns:
true if preemptive task switching is allowed.
Note:
This accessor is needed because _preempt_forbid_cnt must be absoultely private.

Definition at line 284 of file proc.h.

struct Process* proc_current ( void   )  [read]

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.

Definition at line 180 of file proc.h.

iptr_t proc_currentUserData ( 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.

Returns:
Pointer to the user data of the current process.

Definition at line 382 of file proc.c.

void proc_forbid ( void   )  [inline]

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.
calling proc_forbid() from within an interrupt is illegal and meaningless.
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.
See also:
proc_permit()

Definition at line 214 of file proc.h.

void proc_init ( void   ) 

Initialize the process subsystem (kernel).

It must be called before using any process related function.

Definition at line 120 of file proc.c.

const char* proc_name ( struct Process *  proc  ) 

Return the name of the specified process.

NULL is a legal argument and will return the name "<NULL>".

Definition at line 275 of file proc.c.

void proc_permit ( void   )  [inline]

Re-enable preemptive task switching.

See also:
proc_forbid()

Definition at line 256 of file proc.h.

void proc_setPri ( struct Process *  proc,
int  pri 
)

Change the scheduling priority of a process.

Process piorities are signed ints, whereas a larger integer value means higher scheduling priority. The default priority for new processes is 0. The idle process runs with the lowest possible priority: INT_MIN.

A process with a higher priority always preempts lower priority processes. Processes of equal priority share the CPU time according to a simple round-robin policy.

As a general rule to maximize responsiveness, compute-bound processes should be assigned negative priorities and tight, interactive processes should be assigned positive priorities.

To avoid interfering with system background activities such as input processing, application processes should remain within the range -10 and +10.

Definition at line 322 of file proc.c.

void proc_yield ( void   ) 

Co-operative context switch.

The process that calls this function will release the CPU before its cpu quantum expires, the scheduler will run to select the next process that will take control of the processor.

Note:
This function is available only if CONFIG_KERN is enabled
See also:
cpu_relax(), which is the recommended method to release the cpu.

Definition at line 139 of file coop.c.