Dallas Semiconductor DS80C400 C Libraries Home Page

Main Page   Data Structures   File List   Data Fields   Globals  

rom400_task.h File Reference


Detailed Description

Process scheduler functions in the DS80C400 ROM.

This library contains functions for starting, suspending, killing, and managing tasks using the ROM's process scheduler.

For detailed information on the DS80C400 please see the High-Speed Microcontroller User's Guide: DS80C400 Supplement.

Warning:
Some functions in this library are NOT multi-process safe--that is, if you call the same method from two different processes at the same time, the parameters to the function may be destroyed, yielding unpredictable results. Consult each individual funtion's documentation for details on which functions are multi-process safe.

Go to the source code of this file.

Data Structures

struct  TCB
struct  TIME

Defines

#define ROM400_TASK_VERSION   8
#define ROM400_SCHED_VERSION   ROM400_TASK_VERSION
 Included for legacy reasons. Please use ROM400_TASK_VERSION instead.

#define RELOAD_14_746   0xfb33
#define RELOAD_18_432   0xfa00
#define RELOAD_29_491   0xfd99
#define RELOAD_36_864   0xfd00
#define RELOAD_58_982   0xfecc
#define RELOAD_73_728   0xfe80
#define MIN_PRIORITY   1
#define NORM_PRIORITY   128
#define MAX_PRIORITY   255
#define FLAG_SLEEPING   1
#define FLAG_IO_WAIT   2
#define FLAG_DHCP_WAIT   4
#define ROM_SAVESIZE   384
#define task_wait(task_id, event_mask, millis)   task_synch_wait(((long)(millis))>>16,(millis), (task_id) | ((event_mask) << 8))
 Puts the specified task to sleep.

#define task_sleep(task, timeout)   task_synch_sleep(((long)(timeout))>>16,(timeout),(task));
 Redirected function to put a specified task to sleep for a number of milliseconds.


Functions

void task_genesis (unsigned int savesize)
 Initializes the process scheduler.

unsigned char task_getcurrent (void)
 Gets the process ID for the current task.

unsigned char task_getpriority (unsigned char task_id)
 Gets the priority level for the given task.

unsigned char task_setpriority (unsigned char task_id, unsigned char priority)
 Sets the priority level for a given task.

unsigned int task_fork (unsigned char priority, unsigned int savesize)
 Attempts to create a new task.

unsigned char task_kill (unsigned char task_id)
 Kills the specified task.

unsigned char task_suspend (unsigned char task_id, unsigned char event_mask)
 Suspends the specified task.

unsigned char task_synch_wait (unsigned int millis_h, unsigned int millis_l, unsigned int task_event)
 Puts the specified task to sleep.

unsigned char task_signal (unsigned char task_id, unsigned char event_mask)
 Posts events to the specified task.

void task_gettimemillis (struct TIME *t)
 Returns the system tick count.

unsigned char task_getthreadid ()
 Redirected function to return the current thread's ID number.

unsigned char task_threadresume (unsigned char thread, unsigned char task)
 Redirected function to resume the specified thread.

unsigned char task_threadiosleep (unsigned char infinite, unsigned long timeout)
 Redirected function to put the current thread to sleep.

unsigned char task_threadiosleepnc (unsigned char infinite, unsigned long timeout)
 Redirected function to put the current thread (which is already in a critical section) to sleep.

void task_threadsave (void)
 Redirected function to save the state of the current thread in anticipation of a task/thread swap.

void task_threadrestore (void)
 Redirected function to restore the state of a thread.

unsigned char task_synch_sleep (unsigned int timeout_h, unsigned int timeout_l, unsigned char task)
 Redirected function to put a specified task to sleep for a number of milliseconds.

unsigned char task_gettaskid ()
 Redirected function to get the ID of the current task.

void task_entercritsection (void)
 Enters a critical section.

void task_leavecritsection (void)
 Leaves a critical section.

unsigned int task_gettickreload (void)
 Gets the current reload value for the system's millisecond ticker.

void task_settickreload (unsigned int reload)
 Sets the current reload value for the system's millisecond ticker.

unsigned int task_version (void)
 Returns the version number of this process scheduling library.


Define Documentation

#define FLAG_DHCP_WAIT   4
 

Flag for putting a task to sleep.

See also:
task_wait

#define FLAG_IO_WAIT   2
 

Flag for putting a task to sleep.

See also:
task_wait

#define FLAG_SLEEPING   1
 

Flag for putting a task to sleep.

See also:
task_wait

#define MAX_PRIORITY   255
 

Maximum priority level assignable to a task.

See also:
task_setpriority

task_getpriority

#define MIN_PRIORITY   1
 

Minimum priority level assignable to a task.

See also:
task_setpriority

task_getpriority

#define NORM_PRIORITY   128
 

Normal priority for a task. This is the default priority for the default task.

See also:
task_setpriority

task_getpriority

#define RELOAD_14_746   0xfb33
 

Timer reload value for 14.746 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define RELOAD_18_432   0xfa00
 

Timer reload value for 18.432 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define RELOAD_29_491   0xfd99
 

Timer reload value for 29.491 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define RELOAD_36_864   0xfd00
 

Timer reload value for 36.864 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define RELOAD_58_982   0xfecc
 

Timer reload value for 58.982 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define RELOAD_73_728   0xfe80
 

Timer reload value for 73.728 MHz crystal.

See also:
task_settickreload

task_gettickreload

#define ROM400_TASK_VERSION   8
 

Version number associated with this header file. Should be the same as the version number returned by the task_version function.

See also:
task_version

#define ROM_SAVESIZE   384
 

Default size for task switching buffer.

See also:
task_genesis

#define task_sleep task,
timeout       task_synch_sleep(((long)(timeout))>>16,(timeout),(task));
 

Redirected function to put a specified task to sleep for a number of milliseconds.

This is a redirected function that should be used to put a task to sleep for some known period of time. The default implementation of this function calls the function task_wait.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This "function" is now multi-process safe. If two processes try to call this function at the same time, its parameters will not be destroyed. This "function" is now a macro that actually calls task_synch_sleep.

Parameters:
task task ID to put to sleep. A value of zero means put the current task to sleep.
timeout amount of time to put 'task' to sleep for
See also:
task_wait

task_synch_wait

task_synch_sleep

#define task_wait task_id,
event_mask,
millis       task_synch_wait(((long)(millis))>>16,(millis), (task_id) | ((event_mask) << 8))
 

Puts the specified task to sleep.

Suspends the execution of the specified task until a set of events have occurred, or until a set amount of time has elapsed. Use the function task_signal to wake the task up.

This "function" is now multi-process safe. If two processes try to call this function at the same time, its parameters will not be destroyed. This "function" is now a macro that actually calls task_synch_wait.

Parameters:
task_id Task PID to put to sleep. A task PID of zero means put the current task to sleep.
event_mask Bitmap of events to wait for before wakeup
millis Maximum number of milliseconds to sleep for
Returns:
0 for Success, non-zero for failure
See also:
task_signal

task_synch_wait

task_sleep

task_synch_sleep

task_suspend


Function Documentation

void task_entercritsection void   
 

Enters a critical section.

Enters a critical section, which disallows process swapping until the critical section is left. Calls to task_entercritsection should be balanced with calls to task_leavecritsection (or task_threadiosleepnc).

This function is safe to be called from multiple processes at the same time.

See also:
task_leavecritsection

task_threadiosleepnc

unsigned int task_fork unsigned char    priority,
unsigned int    savesize
 

Attempts to create a new task.

Spawns a new task, returning the process ID of the new task to the parent task. Note that because of the way the Keil compiler assigns variables, calls to task_fork should be wrapped inside a critical section. Make sure the child's process ID is stored in a secure location before exiting the critical section. Note that only the parent need leave the critical section, the child will not run until the parent has left it.

This function is safe to be called from multiple processes at the same time.

Parameters:
priority priority level for the new task.
savesize size of the task state buffer for the new task
Returns:
0x0FFFF for failure, else 0 if this is the child task, or the child's PID if this is the parent.
See also:
MIN_PRIORITY

NORM_PRIORITY

MAX_PRIORITY

ROM_SAVESIZE

task_kill

void task_genesis unsigned int    savesize
 

Initializes the process scheduler.

Note that calling the function init_rom from the initialization library is the preferred way of initializing the ROM.

This function is safe to be called from multiple processes at the same time.

Parameters:
savesize Size of the task buffer for saving information on task switches.

unsigned char task_getcurrent void   
 

Gets the process ID for the current task.

Returns the process ID for the current task, which can be used to manage that task.

This function is safe to be called from multiple processes at the same time.

Returns:
PID for the current task.
See also:
task_kill

task_setpriority

task_getpriority

unsigned char task_getpriority unsigned char    task_id
 

Gets the priority level for the given task.

Given the process ID of a task, return the priority level for that task. Use a task_id of 0 for the current task.

This function is safe to be called from multiple processes at the same time.

Parameters:
task_id Task PID to get the priority for. A task PID of zero means the current task.
Returns:
Priority level of the task.
See also:
MIN_PRIORITY

NORM_PRIORITY

MAX_PRIORITY

unsigned char task_gettaskid  
 

Redirected function to get the ID of the current task.

This is a redirected function that should be used to get the process ID of the current task. The default implementation of this function calls the function task_getcurrent.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This function is safe to be called from multiple processes at the same time.

Returns:
Task Id of the current task.
See also:
task_getcurrent

unsigned char task_getthreadid  
 

Redirected function to return the current thread's ID number.

This is a redirected function that should be used to retrieve the current thread's ID number. However, the DS80C400 ROM does not support threads, so the default implementation of this function always returns 0x01.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf.

This function is safe to be called from multiple processes at the same time.

Returns:
default implementation returns 0x01

unsigned int task_gettickreload void   
 

Gets the current reload value for the system's millisecond ticker.

Gets the current reload value for the system's millisecond ticker. When initialized, this reload value may not be correct for the system, and calls to task_gettimemillis may show the resulting inaccuracy (for example, wall time may record 10 seconds while the DS80C400 thinks 12 seconds have passes). Use this function to verify the system's current system millisecond ticker reload value.

This function is safe to be called from multiple processes at the same time.

See also:
task_settickreload

task_gettimemillis

void task_gettimemillis struct TIME   t
 

Returns the system tick count.

The default implementation of this function returns the approximate number of milliseconds since the system started. Note that the largest raw data structure supported by Keil is 4 bytes, yet the DS80C400's tick counter is 5 bytes, therefore the special TIME structure is used.

This is a redirected function. The ROM includes a default process scheduler implementation. See the DS80C400 User's Guide for information on replacing the default process scheduler with your own.

This function is safe to be called from multiple processes at the same time.

Parameters:
t pointer to a structure of type TIME (a 5-byte structure). The result is written to this pointer, MSB first.
See also:
TIME

unsigned char task_kill unsigned char    task_id
 

Kills the specified task.

Kill the specified task. Use a task_id of 0 to indicate the current task. This function does not close or clean up any sockets. Use the socket library function cleanup to clean any sockets owned by the task before any more processes are created.

This function is safe to be called from multiple processes at the same time.

Parameters:
task_id Task PID to kill.
Returns:
0 for Success, non-zero for failure
See also:
task_fork

void task_leavecritsection void   
 

Leaves a critical section.

Leaves a critical section, which allows process swapping to continue. Calls to task_leavecritsection should have a matching call to task_entercritsection.

This function is safe to be called from multiple processes at the same time.

See also:
task_entercritsection

task_threadiosleepnc

unsigned char task_setpriority unsigned char    task_id,
unsigned char    priority
 

Sets the priority level for a given task.

Given the process ID of a task, set the priority level for that task. Use a task_id of 0 for the current task.

This function is safe to be called from multiple processes at the same time.

Parameters:
task_id Task PID to set the priority for. A task PID of zero means the current task.
priority Priority setting for PID task_id. Can be any value between MIN_PRIORITY and MAX_PRIORITY
Returns:
0 for Success, non-zero for failure
See also:
MIN_PRIORITY

NORM_PRIORITY

MAX_PRIORITY

void task_settickreload unsigned int    reload
 

Sets the current reload value for the system's millisecond ticker.

Sets the current reload value for the system's millisecond ticker. When initialized, this reload value may not be correct for the system, and calls to task_gettimemillis may show the resulting inaccuracy (for example, wall time may record 10 seconds while the DS80C400 thinks 12 seconds have passes). Use this function to set the system's current system millisecond ticker reload value.

This function is safe to be called from multiple processes at the same time. This function should only be called after init_rom has been called. If you do not have a 1-Wire device attached for MAC address storage, you should call init_setclock or init_setfrequency before calling init_rom to initialize the system with a good clock reload value.

Parameters:
reload New value for the system's millisecond reload timer. Some reloads for common crystal frequencies include RELOAD_14_746, RELOAD_18_432, RELOAD_29_491, RELOAD_36_864, RELOAD_58_982, and RELOAD_73_728. Values for other crystals (and crystal settings) can also be used. See the High Speed Microcontroller's User Guide for more information on timers and timer settings.
See also:
init_setclock

init_setfrequency

task_gettickreload

task_gettimemillis

unsigned char task_signal unsigned char    task_id,
unsigned char    event_mask
 

Posts events to the specified task.

Sends the event(s) in event_mask to process task_id. If the task is waiting for no other events, it will wake up and be electable to run by the task scheduler.

This function is safe to be called from multiple processes at the same time.

Parameters:
task_id Task PID to signal.
event_mask Bitmap of events to signal
Returns:
0 for Success, non-zero for failure
See also:
task_sleep

task_suspend

unsigned char task_suspend unsigned char    task_id,
unsigned char    event_mask
 

Suspends the specified task.

Suspends the execution of the specified task until a set of events have occurred. Use the function task_signal to wake the task up.

This function is safe to be called from multiple processes at the same time.

Parameters:
task_id Task PID to suspend. A task PID of zero means suspend the current task.
event_mask Bitmap of events to wait for before wakeup
Returns:
0 for Success, non-zero for failure
See also:
task_signal

task_sleep

unsigned char task_synch_sleep unsigned int    timeout_h,
unsigned int    timeout_l,
unsigned char    task
 

Redirected function to put a specified task to sleep for a number of milliseconds.

This is a redirected function that should be used to put a task to sleep for some known period of time. The default implementation of this function calls the function task_wait.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This function IS multi-process safe. Two processes may safely call this function at the same time.

Parameters:
timeout_h high 16 bits of amount of time to put 'task' to sleep for
timeout_l low 16 bits of amount of time to put 'task' to sleep for
task task ID to put to sleep. A value of zero means put the current task to sleep.
See also:
task_wait

task_synch_wait

task_sleep

unsigned char task_synch_wait unsigned int    millis_h,
unsigned int    millis_l,
unsigned int    task_event
 

Puts the specified task to sleep.

Suspends the execution of the specified task until a set of events have occurred, or until a set amount of time has elapsed. Use the function task_signal to wake the task up.

This function IS multi-process safe. Two processes may safely call this function at the same time.

Parameters:
millis_h high 16 bits of amount of time to put 'task' to sleep for
millis_l low 16 bits of amount of time to put 'task' to sleep for
task_event Most significant byte contains bitmap of events to wait for before wakeup. Least significant byte contains task PID to put to sleep. A task PID of zero means put the current task to sleep.
Returns:
0 for Success, non-zero for failure
See also:
task_signal

task_wait

task_sleep

task_synch_sleep

task_suspend

unsigned char task_threadiosleep unsigned char    infinite,
unsigned long    timeout
 

Redirected function to put the current thread to sleep.

This is a redirected function that should be used to put a thread to sleep. However, the DS80C400 does not support threads, so the default implementation of this function puts the current task to sleep.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

Warning:
This function is not multi-process safe. If two processes try to call this function at the same time, its parameters may be destroyed, yielding unpredictable results.
Parameters:
infinite 0 for non-infinite timeout, non-zero for infinite timeout (until woken)
timeout amount of time to sleep (if infinite==0)
Returns:
0 for Success, non-zero for failure
See also:
task_threadiosleepnc

task_threadresume

unsigned char task_threadiosleepnc unsigned char    infinite,
unsigned long    timeout
 

Redirected function to put the current thread (which is already in a critical section) to sleep.

This is a redirected function that should be used to put a thread to sleep, when the thread has already entered a critical section. However, the DS80C400 does not support threads, so the default implementation of this function puts the current task to sleep (which is assumed to be operating within a critical section).

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

Warning:
This function is not multi-process safe. If two processes try to call this function at the same time, its parameters may be destroyed, yielding unpredictable results.
Parameters:
infinite 0 for non-infinite timeout, non-zero for infinite timeout (until woken)
timeout amount of tuime to sleep (if infinite==0)
Returns:
0 for Success, non-zero for failure
See also:
task_threadiosleep

task_threadresume

task_entercritsection

void task_threadrestore void   
 

Redirected function to restore the state of a thread.

This is a redirected function that should be used to restore the state of a thread that was earlier saved with a call to task_threadsave. However, the DS80C400 does not support threads, so the default implementation of this function does nothing.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This function is safe to be called from multiple processes at the same time.

See also:
task_threadsave

unsigned char task_threadresume unsigned char    thread,
unsigned char    task
 

Redirected function to resume the specified thread.

This is a redirected function that should be used to resume a suspended or sleeping thread. However, the DS80C400 ROM does not support threads, so the default implementation of this function resumes the task with a process ID matching task.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This function is safe to be called from multiple processes at the same time.

Parameters:
thread thread ID to resume
task ID of the process that thread belongs to
Returns:
0 for Success, non-zero for failure
See also:
task_threadiosleep

task_threadiosleepnc

void task_threadsave void   
 

Redirected function to save the state of the current thread in anticipation of a task/thread swap.

This is a redirected function that should be used to save the state of the current thread so it may be executed again later, after a call to task_threadrestore. However, the DS80C400 does not support threads, so the default implementation of this function does nothing.

For more information on redirected functions, see the section ROM Redirect Function Table in the DS80C400 User's Guide at http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf

This function is safe to be called from multiple processes at the same time.

See also:
task_threadrestore

unsigned int task_version void   
 

Returns the version number of this process scheduling library.

This function is safe to be called from multiple processes at the same time.

Returns:
Version number of this TASK library.


Copyright 2004 Dallas Semiconductor, Inc.. Documentation generated by Doxygen.