Data Structures
struct	process_struct
	Process structure(one process consists one protothread). More...

Macros
#define	PROCESS_NONE NULL

#define	PROCESS_BROADCAST NULL

Typedefs
typedef U8	process_event_t

typedef void *	process_data_t

typedef struct process_struct	tPROCESS
	Process structure(one process consists one protothread). More...

predefined event type
#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

process declaration and definition
#define	PROCESS_THREAD(name, ev, data)
	Define the body of a process. More...

#define	PROCESS_NAME(name) extern tPROCESS name
	Declare the name of a process. More...

#define	PROCESS(name, strname)
	Define a process. More...

semaphore declaration and definition
#define	SEM_NAME(name) extern struct pt_sem sem_##name
	Declare the name of a semaphore. More...

#define	SEM(name, count)
	Define a semaphore. More...

process protothread functions
#define	PROCESS_BEGIN()
	Define the beginning of a process. More...

#define	PROCESS_END()
	Define the end of a process. More...

#define	PROCESS_WAIT_EVENT()
	Wait for an event to be posted to the process. More...

#define	PROCESS_WAIT_EVENT_UNTIL(c)
	Wait for an event to be posted to the process, with an extra condition. More...

#define	PROCESS_YIELD()
	Yield the currently running process.

#define	PROCESS_YIELD_UNTIL(c)
	Yield the currently running process until a condition occurs. More...

#define	PROCESS_WAIT_UNTIL(c)
	Wait for a condition to occur. More...

#define	PROCESS_WAIT_WHILE(c)
	Wait for a condition not occur. More...

#define	PROCESS_EXIT()
	Exit the currently running process.

#define	PROCESS_PT_SPAWN(pt, thread)
	Spawn a protothread from the process. More...

#define	PROCESS_PAUSE()
	Yield the process for a short while. More...

#define	PROCESS_WAIT_SEM(name)

#define	PROCESS_SIGNAL_SEM(name)

poll and exit handlers
#define	PROCESS_POLLHANDLER(handler) if(ev == PROCESS_EVENT_POLL) { handler; }
	Specify an action when a process is polled. More...

#define	PROCESS_EXITHANDLER(handler) if(ev == PROCESS_EVENT_EXIT) { handler; }
	Specify an action when a process exits. More...

process functions called from application programs
tPROCESS *	process_current

BOOL	process_start (tPROCESS *ptProcess, process_data_t arg)
	Start a process. More...

BOOL	process_post (tPROCESS ptProcess, process_event_t ev, void data)
	Post an asynchronous event to one or all processes. More...

void	process_send (tPROCESS ptProcess, process_event_t ev, void data)
	Send a synchronous event to a process. More...

void	process_exit (tPROCESS *ptProcess)
	Cause a process to exit. More...

process_event_t	process_alloc_event (void)
	Allocate a global event number. More...

#define	PROCESS_CURRENT() process_current
	Get a pointer to the currently running process. More...

#define	PROCESS_CONTEXT_BEGIN(ptProcess) { tPROCESS *tmp_current = PROCESS_CURRENT();process_current = ptProcess
	Switch context to another process. More...

#define	PROCESS_CONTEXT_END(ptProcess) process_current = tmp_current; }
	End a context switch. More...

process functions called from device drivers.
BOOL	process_poll (tPROCESS *ptProcess)
	Request a process to be polled. More...

functions called by the system and boot-up code
U16	process_run (void)
	Run the system once - call poll handlers and process one event. More...

BOOL	process_is_running (tPROCESS *ptProcess)
	Check if a process is running. More...

U16	process_nevents (void)
	Number of events waiting to be processed. More...

Detailed Description

A process in consists of a single protothread.

Macro Definition Documentation

#define PROCESS	(	name,
		strname
	)

This macro defines 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

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

Note: definition must be global.

#define PROCESS_BEGIN ( )

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.

#define PROCESS_CONTEXT_BEGIN ( ptProcess ) { tPROCESS *tmp_current = PROCESS_CURRENT();process_current = ptProcess

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.

Parameters

[in] ptProcess The process to use as context

See also: PROCESS_CONTEXT_END(); PROCESS_CURRENT()

Example:

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

#define PROCESS_CONTEXT_END ( ptProcess ) process_current = tmp_current; }

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

Parameters

[in] ptProcess The process used in the context switch

See also: PROCESS_CONTEXT_START()

#define PROCESS_CURRENT ( ) process_current

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().

#define PROCESS_END ( )

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.

#define PROCESS_EXITHANDLER ( handler ) if(ev == PROCESS_EVENT_EXIT) { handler; }

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

Parameters

handler The action to be performed.

#define PROCESS_NAME ( name ) extern tPROCESS name

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

#define PROCESS_PAUSE ( )

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

#define PROCESS_POLLHANDLER ( handler ) if(ev == PROCESS_EVENT_POLL) { handler; }

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

Parameters

handler The action to be performed.

#define PROCESS_PT_SPAWN	(	pt,
		thread
	)

Parameters

pt[inout]	The protothread state (struct pt) for the new protothread
thread[in]	The call to the protothread function.

See also: PT_SPAWN()

#define PROCESS_SIGNAL_SEM ( name )

Signal a semaphore

This macro carries out the "signal" operation on the semaphore.

Parameters

[in] name semaphore name

Note: It's the application's responsibility to notify the waiting process if semaphore is avilable.

See also: PROCESS_WAIT_SEM()

#define PROCESS_THREAD	(	name,
		ev,
		data
	)

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.

#define PROCESS_WAIT_EVENT ( )

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

#define PROCESS_WAIT_EVENT_UNTIL ( c )

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

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

See also: PT_WAIT_UNTIL()

#define PROCESS_WAIT_SEM ( name )

Wait for a semaphore

This macro carries out the "wait" operation on the semaphore.

Parameters

[in] name semaphore name

Note: It's the application's responsibility to notify the waiting process if semaphore is avilable.

See also: PROCESS_SIGNAL_SEM()

#define PROCESS_WAIT_UNTIL ( c )

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

[in] c The condition that must be true for the process to continue

#define PROCESS_WAIT_WHILE ( c )

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

[in] c The condition that must be false for the process to continue.

#define PROCESS_YIELD_UNTIL ( c )

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

[in] c The condition to wait for.

#define SEM	(	name,
		count
	)

Parameters

name	The variable name of the semaphore structure.
count	The count value of the semaphore.

Note: definition must be global.

#define SEM_NAME ( name ) extern struct pt_sem sem_##name

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

Typedef Documentation

typedef struct process_struct tPROCESS

Note: application code should not change any member of the process structure for they are maintained by system inside.

Function Documentation

process_event_t process_alloc_event ( void )

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.

Returns: The allocated event number

void process_exit ( tPROCESS * ptProcess )

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

Parameters

[in,out] ptProcess The process that is to be exited

See also: PROCESS_CURRENT()

BOOL process_is_running ( tPROCESS * ptProcess )

This function checks if a specific process is running.A process can be on running state after calling process_start() normally.

Parameters

[in] ptProcess The process pointer.

Return values

TRUE	if the process is running.
FALSE	if the process is not running.

Here is the caller graph for this function:

U16 process_nevents ( void )

Returns: Number of events that are currently waiting to be processed.

BOOL process_poll ( tPROCESS * ptProcess )

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

Parameters

[in,out] ptProcess A pointer to the process' process structure.

Return values

TRUE	poll successfully.
FALSE	if the process is not running.

Here is the call graph for this function:

Here is the caller graph for this function:

BOOL process_post	(	tPROCESS *	ptProcess,
		process_event_t	ev,
		void *	data
	)

This function posts an asynchronous event to one or all 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

[in,out]	ptProcess	The process to which the event should be posted,or PROCESS_BROADCAST if the event should be posted to all processes.
[in]	ev	The event to be posted.
[in,out]	data	The auxiliary data to be sent with the event

Return values

TRUE	The event could be posted.
FALSE	The event queue was full and the event could not be posted.

See also: process_send()

U16 process_run ( void )

This function should be called repeatedly from the main() program to actually run the 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.

Example about how to use protothread process model for event-driven system:

 int main(void) {
   RBS_Init();//RBS initialization
   process_start();//start process
   ...
   while (1) {
     do {
       ...//do some optional user code
     } while(process_run() > 0);
     sleep();//go to sleep
   }
 }

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

void process_send	(	tPROCESS *	ptProcess,
		process_event_t	ev,
		void *	data
	)

This function sends a synchronous event to one processes. On opposite of process_post(),the handing of the event is completed immediately after calling.

Parameters

[in,out]	ptProcess	A pointer to the process' process structure.
[in]	ev	The event to be posted.
[in,out]	data	A pointer to additional data that is posted together with the event.

See also: process_post()

Here is the caller graph for this function:

BOOL process_start	(	tPROCESS *	ptProcess,
		process_data_t	arg
	)

Parameters

[in,out]	ptProcess	A pointer to a process structure.
[in]	arg	An argument pointer that can be passed to the new process

Return values

TRUE	successful.
FALSE	Try to start a process that is already running.

Here is the call graph for this function:

Here is the caller graph for this function:

RainbowBS Manual: protothread process

RainbowBS

Data Structures

Macros

Typedefs

predefined event type

process declaration and definition

semaphore declaration and definition

process protothread functions

poll and exit handlers

process functions called from application programs

process functions called from device drivers.

functions called by the system and boot-up code

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Get in touch