Contiki processes

Files
file	process.c
file	process.h

Classes
struct	event_data
struct	process

Macros
#define	LOG_TAG   "process.c"
#define	data   _data /* data is a reserved keyword in Keil C51 */
#define	PROCESS_STATE_NONE   0
#define	PROCESS_STATE_RUNNING   1
#define	PROCESS_STATE_CALLED   2
#define	LOG_SLOW_EVENTS   1
#define	EVENT_TIME_WARNING   50
#define	EVENT_TIME_ERROR   300
#define	DEBUG   0
#define	PRINTF(...)
#define	PROCESS_NONE   NULL
#define	PROCESS_CONF_NUMEVENTS   255
#define	PROCESS_CONF_NUMEVENTS_PRINT   64
#define	PROCESS_CONF_NUMEVENTS_ERROR   230
#define	PROCESS_EVENT_NONE   0x80
#define	PROCESS_EVENT_INIT   0x81
#define	PROCESS_EVENT_POLL   0x82
#define	PROCESS_EVENT_EXIT   0x83
#define	PROCESS_EVENT_SERVICE_REMOVED   0x84
#define	PROCESS_EVENT_CONTINUE   0x85
#define	PROCESS_EVENT_MSG   0x86
#define	PROCESS_EVENT_EXITED   0x87
#define	PROCESS_EVENT_TIMER   0x88
#define	PROCESS_EVENT_COM   0x89
#define	PROCESS_EVENT_MAX   0x8a
#define	PROCESS_BROADCAST   NULL
#define	PROCESS_ZOMBIE   ((struct process *)0x1)
#define	PROCESS_LIST()   process_list

Typedefs
typedef unsigned char	process_event_t
typedef void *	process_data_t
typedef uint32_t	process_num_events_t

Functions
static void	call_process (struct process *p, process_event_t ev, process_data_t data) CC_REENTRANT_ARG
static void	exit_process (struct process *p, struct process *fromprocess) CC_REENTRANT_ARG
static void	do_poll (void)
static void	do_event (void)

Variables
struct process *	process_list = NULL
struct process *	process_current = NULL
static process_event_t	lastevent
static process_num_events_t	nevents
static process_num_events_t	fevent
static struct event_data	events [PROCESS_CONF_NUMEVENTS]
static volatile unsigned char	poll_requested
CCIF struct process *	process_list

Functions called from application programs
CCIF struct process *	process_current
process_event_t	process_alloc_event (void)
	Allocate a global event number. More...
void	process_start (struct process *p, const char *arg) CC_REENTRANT_ARG
void	process_exit (struct process *p) CC_REENTRANT_ARG
	Cause a process to exit. More...
int	process_post (struct process *p, process_event_t ev, process_data_t data) CC_REENTRANT_ARG
int	process_count_events (const struct process *p, process_event_t ev, const process_data_t data) CC_REENTRANT_ARG
void	process_post_synch (struct process *p, process_event_t ev, process_data_t data) CC_REENTRANT_ARG
#define	PROCESS_CURRENT()
#define	PROCESS_CONTEXT_BEGIN(p)
#define	PROCESS_CONTEXT_END(p)

Functions called by the system and boot-up code
void	process_init (void)
	Initialize the process module. More...
int	process_run (void)
int	process_nevents (void)
int	process_is_running (struct process *p) CC_REENTRANT_ARG

Functions called from device drivers
void	process_poll (struct process *p) CC_REENTRANT_ARG

Return values
#define	PROCESS_ERR_OK   0
	Return value indicating that an operation was successful. More...
#define	PROCESS_ERR_FULL   1
	Return value indicating that the event queue was full. More...

Process protothread functions
#define	PROCESS_BEGIN()
#define	PROCESS_END()
#define	PROCESS_WAIT_EVENT()
#define	PROCESS_WAIT_EVENT_UNTIL(c)
#define	PROCESS_YIELD()
#define	PROCESS_YIELD_UNTIL(c)
#define	PROCESS_WAIT_UNTIL(c)
#define	PROCESS_WAIT_WHILE(c)   PT_WAIT_WHILE(process_pt, c)
#define	PROCESS_EXIT()
#define	PROCESS_PT_SPAWN(pt, thread)
#define	PROCESS_PAUSE()

Poll and exit handlers
#define	PROCESS_POLLHANDLER(handler)
#define	PROCESS_EXITHANDLER(handler)

Process declaration and definition
#define	PROCESS_THREAD(name, ev, data)
#define	PROCESS_NAME(name)
#define	PROCESS(name, strname)

Detailed Description

A process in Contiki consists of a single protothread.

Macro Definition Documentation

data

#define data   _data /* data is a reserved keyword in Keil C51 */

DEBUG

#define DEBUG   0

EVENT_TIME_ERROR

#define EVENT_TIME_ERROR   300

EVENT_TIME_WARNING

#define EVENT_TIME_WARNING   50

LOG_SLOW_EVENTS

#define LOG_SLOW_EVENTS   1

LOG_TAG

#define LOG_TAG   "process.c"

PRINTF

#define PRINTF

(

...

)

PROCESS

#define PROCESS	(		name,
			strname
	)

Declare a process.

This macro declares a process. The process has two names: the variable of the process structure, which is used by the C program, and a human readable string name, which is used when debugging. A configuration option allows removal of the readable name to save RAM.

Parameters

name	The variable name of the process structure.
strname	The string representation of the process' name.

PROCESS_BEGIN

#define PROCESS_BEGIN

(

)

Define the beginning of a process.

This macro defines the beginning of a process, and must always appear in a PROCESS_THREAD() definition. The PROCESS_END() macro must come at the end of the process.

PROCESS_BROADCAST

#define PROCESS_BROADCAST   NULL

PROCESS_CONF_NUMEVENTS

#define PROCESS_CONF_NUMEVENTS   255

PROCESS_CONF_NUMEVENTS_ERROR

#define PROCESS_CONF_NUMEVENTS_ERROR   230

PROCESS_CONF_NUMEVENTS_PRINT

#define PROCESS_CONF_NUMEVENTS_PRINT   64

PROCESS_CONTEXT_BEGIN

#define PROCESS_CONTEXT_BEGIN

(

p

)

Value:

  {                                                  \
    struct process *tmp_current = PROCESS_CURRENT(); \
    process_current             = p

Switch context to another process

This function switch context to the specified process and executes the code as if run by that process. Typical use of this function is to switch context in services, called by other processes. Each PROCESS_CONTEXT_BEGIN() must be followed by the PROCESS_CONTEXT_END() macro to end the context switch.

Example:

PROCESS_CONTEXT_BEGIN(&test_process);
etimer_set(&timer, CLOCK_SECOND);
PROCESS_CONTEXT_END(&test_process);

Parameters

p	The process to use as context

See also

PROCESS_CONTEXT_END()

PROCESS_CURRENT()

PROCESS_CONTEXT_END

#define PROCESS_CONTEXT_END

(

p

)

Value:

  process_current = tmp_current; \
  }

End a context switch

This function ends a context switch and changes back to the previous process.

Parameters

p	The process used in the context switch

See also

PROCESS_CONTEXT_START()

PROCESS_CURRENT

#define PROCESS_CURRENT

(

)

Get a pointer to the currently running process.

This macro get a pointer to the currently running process. Typically, this macro is used to post an event to the current process with process_post().

PROCESS_END

#define PROCESS_END

(

)

Define the end of a process.

This macro defines the end of a process. It must appear in a PROCESS_THREAD() definition and must always be included. The process exits when the PROCESS_END() macro is reached.

PROCESS_ERR_FULL

#define PROCESS_ERR_FULL   1

Return value indicating that the event queue was full.

        This value is returned from process_post() to indicate
        that the event queue was full and that an event could
        not be posted.

PROCESS_ERR_OK

#define PROCESS_ERR_OK   0

Return value indicating that an operation was successful.

        This value is returned to indicate that an operation
        was successful.

PROCESS_EVENT_COM

#define PROCESS_EVENT_COM   0x89

PROCESS_EVENT_CONTINUE

#define PROCESS_EVENT_CONTINUE   0x85

PROCESS_EVENT_EXIT

#define PROCESS_EVENT_EXIT   0x83

PROCESS_EVENT_EXITED

#define PROCESS_EVENT_EXITED   0x87

PROCESS_EVENT_INIT

#define PROCESS_EVENT_INIT   0x81

PROCESS_EVENT_MAX

#define PROCESS_EVENT_MAX   0x8a

PROCESS_EVENT_MSG

#define PROCESS_EVENT_MSG   0x86

PROCESS_EVENT_NONE

#define PROCESS_EVENT_NONE   0x80

PROCESS_EVENT_POLL

#define PROCESS_EVENT_POLL   0x82

PROCESS_EVENT_SERVICE_REMOVED

#define PROCESS_EVENT_SERVICE_REMOVED   0x84

PROCESS_EVENT_TIMER

#define PROCESS_EVENT_TIMER   0x88

PROCESS_EXIT

#define PROCESS_EXIT

(

)

Exit the currently running process.

PROCESS_EXITHANDLER

#define PROCESS_EXITHANDLER

(

handler

)

Specify an action when a process exits.

Note

This declaration must come immediately before the PROCESS_BEGIN() macro.

Parameters

handler

The action to be performed.

PROCESS_LIST

#define PROCESS_LIST

(

)

process_list

PROCESS_NAME

#define PROCESS_NAME

(

name

)

Declare the name of a process.

This macro is typically used in header files to declare the name of a process that is implemented in the C file.

PROCESS_NONE

#define PROCESS_NONE   NULL

PROCESS_PAUSE

#define PROCESS_PAUSE

(

)

Yield the process for a short while.

This macro yields the currently running process for a short while, thus letting other processes run before the process continues.

PROCESS_POLLHANDLER

#define PROCESS_POLLHANDLER

(

handler

)

Specify an action when a process is polled.

Note

This declaration must come immediately before the PROCESS_BEGIN() macro.

Parameters

handler

The action to be performed.

PROCESS_PT_SPAWN

#define PROCESS_PT_SPAWN	(		pt,
			thread
	)

Spawn a protothread from the process.

Parameters

pt	The protothread state (struct pt) for the new protothread
thread	The call to the protothread function.

See also

PT_SPAWN()

PROCESS_STATE_CALLED

#define PROCESS_STATE_CALLED   2

PROCESS_STATE_NONE

#define PROCESS_STATE_NONE   0

PROCESS_STATE_RUNNING

#define PROCESS_STATE_RUNNING   1

PROCESS_THREAD

#define PROCESS_THREAD	(		name,
			ev,
			data
	)

Define the body of a process.

This macro is used to define the body (protothread) of a process. The process is called whenever an event occurs in the system, A process always start with the PROCESS_BEGIN() macro and end with the PROCESS_END() macro.

PROCESS_WAIT_EVENT

#define PROCESS_WAIT_EVENT

(

)

Wait for an event to be posted to the process.

This macro blocks the currently running process until the process receives an event.

PROCESS_WAIT_EVENT_UNTIL

#define PROCESS_WAIT_EVENT_UNTIL

(

c

)

Wait for an event to be posted to the process, with an extra condition.

This macro is similar to PROCESS_WAIT_EVENT() in that it blocks the currently running process until the process receives an event. But PROCESS_WAIT_EVENT_UNTIL() takes an extra condition which must be true for the process to continue.

Parameters

c	The condition that must be true for the process to continue.

See also

PT_WAIT_UNTIL()

PROCESS_WAIT_UNTIL

#define PROCESS_WAIT_UNTIL

(

c

)

Wait for a condition to occur.

This macro does not guarantee that the process yields, and should therefore be used with care. In most cases, PROCESS_WAIT_EVENT(), PROCESS_WAIT_EVENT_UNTIL(), PROCESS_YIELD() or PROCESS_YIELD_UNTIL() should be used instead.

Parameters

c	The condition to wait for.

PROCESS_WAIT_WHILE

#define PROCESS_WAIT_WHILE

(

c

)

PT_WAIT_WHILE(process_pt, c)

PROCESS_YIELD

#define PROCESS_YIELD

(

)

Yield the currently running process.

PROCESS_YIELD_UNTIL

#define PROCESS_YIELD_UNTIL

(

c

)

Yield the currently running process until a condition occurs.

This macro is different from PROCESS_WAIT_UNTIL() in that PROCESS_YIELD_UNTIL() is guaranteed to always yield at least once. This ensures that the process does not end up in an infinite loop and monopolizing the CPU.

Parameters

c	The condition to wait for.

PROCESS_ZOMBIE

#define PROCESS_ZOMBIE   ((struct process *)0x1)

Typedef Documentation

process_data_t

typedef void* process_data_t

process_event_t

typedef unsigned char process_event_t

process_num_events_t

typedef uint32_t process_num_events_t

Function Documentation

call_process()

static void call_process ( struct process *  p, process_event_t  ev, process_data_t  data  )

static

do_event()

static void do_event ( void  )

static

do_poll()

static void do_poll ( void  )

static

exit_process()

static void exit_process ( struct process *  p, struct process *  fromprocess  )

static

process_alloc_event()

CCIF process_event_t process_alloc_event

(

void

)

Allocate a global event number.

Returns

The allocated event number

        In Contiki, event numbers above 128 are global and may
        be posted from one process to another. This function
        allocates one such event number.

Note

There currently is no way to deallocate an allocated event number.

process_count_events()

CCIF int process_count_events	(	const struct process *	p,
		process_event_t	ev,
		const process_data_t	procdata
	)

Count the number of matching events on the event-queue.

This functions returns the number of events on the event-queue that match all of the parameters given to it. Every one of them can be set to NULL for them to be ignored.

Parameters

p	The process which the event will be posted to.
ev	The event type to look for.
procdata	The auxiliary data that will be sent with the event.

Returns

Total number of events that match the criteria.

process_exit()

CCIF void process_exit

(

struct process *

p

)

Cause a process to exit.

Parameters

p	The process that is to be exited This function causes a process to exit. The process can either be the currently executing process, or another process that is currently running.

See also

PROCESS_CURRENT()

process_init()

void process_init

(

void

)

Initialize the process module.

        This function initializes the process module and should
        be called by the system boot-up code.

process_is_running()

CCIF int process_is_running

(

struct process *

p

)

Check if a process is running.

This function checks if a specific process is running.

Parameters

p	The process.

Return values

Non-zero	if the process is running.
Zero	if the process is not running.

process_nevents()

int process_nevents

(

void

)

Number of events waiting to be processed.

Returns

The number of events that are currently waiting to be processed.

process_poll()

CCIF void process_poll

(

struct process *

p

)

Request a process to be polled.

This function typically is called from an interrupt handler to cause a process to be polled.

Parameters

p	A pointer to the process' process structure.

process_post()

CCIF int process_post	(	struct process *	p,
		process_event_t	ev,
		void *	procdata
	)

Post an asynchronous event.

This function posts an asynchronous event to one or more processes. The handing of the event is deferred until the target process is scheduled by the kernel. An event can be broadcast to all processes, in which case all processes in the system will be scheduled to handle the event.

Parameters

ev	The event to be posted.
procdata	The auxiliary data to be sent with the event
p	The process to which the event should be posted, or PROCESS_BROADCAST if the event should be posted to all processes.

Return values

PROCESS_ERR_OK	The event could be posted.
PROCESS_ERR_FULL	The event queue was full and the event could not be posted.

process_post_synch()

CCIF void process_post_synch	(	struct process *	p,
		process_event_t	ev,
		void *	procdata
	)

Post a synchronous event to a process.

Parameters

p	A pointer to the process' process structure.
ev	The event to be posted.
procdata	A pointer to additional data that is posted together with the event.

process_run()

int process_run

(

void

)

Run the system once - call poll handlers and process one event.

This function should be called repeatedly from the main() program to actually run the Contiki system. It calls the necessary poll handlers, and processes one event. The function returns the number of events that are waiting in the event queue so that the caller may choose to put the CPU to sleep when there are no pending events.

Returns

The number of events that are currently waiting in the event queue.

process_start()

CCIF void process_start	(	struct process *	p,
		const char *	arg
	)

Start a process.

Parameters

p	A pointer to a process structure.
arg	An argument pointer that can be passed to the new process

Variable Documentation

events

struct event_data events[PROCESS_CONF_NUMEVENTS]

static

fevent

process_num_events_t fevent

static

lastevent

process_event_t lastevent

static

nevents

process_num_events_t nevents

static

poll_requested

volatile unsigned char poll_requested

static

process_current [1/2]

struct process* process_current = NULL

process_current [2/2]

CCIF struct process* process_current

extern

process_list [1/2]

struct process* process_list = NULL

process_list [2/2]

CCIF struct process* process_list

extern