SysTask V3x E

Library Description:
CoDeSys V 3.x
SysTask.library
Document Version 1.0

libdoc_e.dot / V1.0
3S - Smart Software Solutions GmbH Seite 1 von 14

SysTask_V3x_E.doc
Library SysTask.library
CONTENT
1 OVERVIEW 4
2 LIBRARY MODULES 5
2.1 SysTaskCheckStack 5
2.2 SysTaskCreate 5
2.3 SysTaskCreate2 6
2.4 SysTaskDestroy 7
2.5 SysTaskEnd 7
2.6 SysTaskEnter 7
2.7 SysTaskExit 7
2.8 SysTaskGenerateException 8
2.9 SysTaskGetContext 8
2.10 SysTaskGetCurrent 8
2.11 SysTaskGetCurrentOSHandle 8
2.12 SysTaskGetInfo 9
2.13 SysTaskGetInterval 9
2.14 SysTaskGetOSHandle 9
2.15 SysTaskGetOSPriority 9
2.16 SysTaskGetPriority 10
2.17 SysTaskJoin 10
2.18 SysTaskLeave 10
2.19 SysTaskResume 10
2.20 SysTaskSetExit 11
2.21 SysTaskSetInterval 11
2.22 SysTaskSetPriority 11
2.23 SysTaskSuspend 11
2.24 SysTaskWaitInterval 12
2.25 SysTaskWaitSleep 12
2.26 SysTaskWaitSleepUs 12
2.27 Structure RegContext 12
2.28 Structure SYS_TASK_INFO 13
2.29 Structure SYS_TASK_PARAM 13
CHANGE HISTORY 14
libdoc_e.dot / V1.0

SysTask_V3x_E.doc
1 Overview
Note: It depends on the target system, which system libraries can be used in the application program.
This library serves to manage cyclic tasks. As far as the target system supports the
functionality the library functions can be used to generate or delete tasks, to set them to a
specific priority, to stop and restart them etc. Processing is synchronous.
Note: These functions are not reentrant. For normal use cases this should be irrelevant. However, if case of
multiple IEC tasks creating and managing dynamically further tasks, these calls have to be guarded against
each other within the application, e.g. by use of the library SysLibSem.
(To retrieve special information on the configuration of IEC tasks you may use the library
SysLibIECTasks23.lib.)
The functions: SysTaskGetPriority

SysTaskJoin
SysTaskCheckStack
SysTaskLeave
SysTaskCreate
SysTaskResume
SysTaskCreate2
SysTaskSetExit
SysTaskDestroy
SysTaskSetInterval
SysTaskEnd
SysTaskSetPriority
SysTaskEnter
SysTaskSuspend
SysTaskExit
SysTaskWaitInterval
SysTaskGenerateException
SysTaskWaitSleep
SysTaskGetContext
SysTaskWaitSleepUs
SysTaskGetCurrent
SysTaskGetCurrentOSHandle
SysTaskGetInfo Data structures used by the functions:
SysTaskGetInterval RegContext
SysTaskGetOSHandle SYS_TASK_INFO
SysTaskGetOSPriority SYS_TASK_PARAM
libdoc_e.dot / V1.0

SysTask_V3x_E.doc
2 Library Modules
2.1 SysTaskCheckStack
By use of this function the maximum depth of a stack can be retrieved. Actually however, this
is not yet implemented for any platform, the function always returns the error message
ERR_MOT_IMPLEMENTED.
The return of type UDINT is an error code indicating success or failure of the operation (see
document "Runtime Error Codes").
Input variable Data type Description
hTask UDINT ID of actual task (see structure SYS_TASK_INFO,

chapter 2.28).
pulMaxDepth POINTER TO Pointer to variable to be assigned to maximum depth
UDINT of stack
2.2 SysTaskCreate
This function serves to generate and immediately start a task. The parameters thereby
defined get stored as components of the structure SYS_TASK_INFO (see 2.28) and
SYS_TASK_PARAM (see 2.29). Via parameter phTaskHandle the function provides an
unique ID number (handle) of the task, which is a necessary input for other library functions.
pszTaskName STRING Name of new task
pFunction POINTER TO Pointer to function to be called by the task

UDINT
pParam POINTER TO Pointer to input parameter to be transmitted to
UDINT task/POU
Example: NULL or pointer to structure
uIPriority UDINT Task priority, valid values range from 0 (highest
priority) to 255 (lowest priority). Thereby, the values
0..31 system tasks
(scheduler,)
32..63 are reserved for IEC tasks, real-time
tasks
64-255 communication
tasks and other not
real-time tasks
uIIntervalMs UDINT Time span (in Microseconds), after which the task
shall be restarted; Example: 300
libdoc_e.dot / V1.0
ulStackSize UDINT Stack size of task in bytes (default=0)

Example: 4096
pExceptionHandler POINTER TO Pointer to exception handler to be processed after
UDINT an exception error occurred in the task called (may
be NULL)

SysTask_V3x_E.doc
phTaskHandle POINTER TO Pointer to task handle (ID), see structure

UDINT SYS_TASK_PARAM (hTask, chapter 2.29)
2.3 SysTaskCreate2
By use of this function a task is created, but not started. The parameters thereby defined get
stored as components of the structure SYS_TASK_INFO (see 2.28) and SYS_TASK_PARAM
(see 2.29). Via parameter phTaskHandle the function provides an unique ID number (handle)
of the task, which is a necessary input for other library functions.
pszTaskName STRING Name of new task
pFunction POINTER TO Pointer to function to be called by the task

UDINT
pParam POINTER TO Pointer to input parameter to be transmitted to
UDINT task/POU
Example: NULL or pointer to structure
uIPriority UDINT Task priority, valid values range from 0 (highest
priority) to 255 (lowest priority). Thereby, the values
0..31 system tasks
(scheduler,)
32..63 are reserved for IEC tasks, real-time
tasks
64-255 communication
tasks and other not
real-time tasks
uIIntervalMs UDINT Time span (in Microseconds), after which the task
shall be restarted; Example: 300
ulStackSize UDINT Stack size of task in bytes (default=0)
Example: 4096
pExceptionHandler POINTER TO Pointer to exception handler to be processed after
UDINT an exception error occurred in the task called (may
be NULL)
phTaskHandle POINTER TO Pointer to task handle (ID), see structure
UDINT SYS_TASK_PARAM (hTask, chapter 2.29)
libdoc_e.dot / V1.0

SysTask_V3x_E.doc
2.4 SysTaskDestroy
By use of this function the task identified by its handle (ID) is deleted.
hTask UDINT ID of task to be deleted (see structure

SYS_TASK_INFO, 2.28).
2.5 SysTaskEnd
This function has to be called by a task whose processing is being stopped. Typically, the call
should be carried out right before the task will be left to ensure a proper exit of the task and
release of the resources.
hTask UDINT ID of task (see structure SYS_TASK_INFO, 2.28).
ulExitCode UDINT Exit code, that is the message created while leaving
the task (operating system specific)
2.6 SysTaskEnter
By use of this function a task is set to state active. See SysTaskLeave (2.18) for marking a
regular end of processing.
hTask UDINT ID of the task (see structure SYS_TASK_INFO,

2.28).
2.7 SysTaskExit
This functions tries to terminate a task regularly. If the task does not respond during a defined
timeout, the task will be deleted by force, whereby the resources of the operating system will
not be released.
hTask UDINT ID of the task (see structure SYS_TASK_INFO,

2.28).
libdoc_e.dot / V1.0
ulTimeoutMS UDINT Time span (in milliseconds), wherein the task will be
terminated regularly. Afterwards it will be deleted by
force.

SysTask_V3x_E.doc
2.8 SysTaskGenerateException
This function calls the exception handler that is associated to the task specified by its handle
(SYS_TASK_INFO.pExceptionHandler^, 2.28). If there is no exception handler specified, the
standard exception routine will be called.
ulTaskOSHandle UDINT ID of the task (see structure SYS_TASK_INFO,

2.28).
ulException UDINT Standard exception routine of runtime system
Context RegContext Context to localize the occurrence of the exception

within the program; see structure RegContext (2.27)
2.9 SysTaskGetContext
This functions retrieves the actual context (register content) of the task. Thereto, the task has
to be suspended (by use of SysTaskSuspend (2.23) or by the operating system itself).
hTask UDINT ID of the actual task (see structure

pContext POINTER TO Pointer to structure RegContext (2.27) that contains
RegContext information on the actual register context.
2.10 SysTaskGetCurrent
This function retrieves the ID (handle) of the task currently processed. See also
SysTaskGetCurrentOSHandle and SysTaskGetOSHandle.
phTask POINTER TO Pointer to handle of actual task

UDINT
2.11 SysTaskGetCurrentOSHandle
This function retrieves the operating system specific ID (handle) of the task currently
processed. See also SysTaskGetOSHandle und SysTaskGetCurrent.
libdoc_e.dot / V1.0

pulOSHandle POINTER TO Pointer to operating system specific handle of

UDINT actual task

SysTask_V3x_E.doc
2.12 SysTaskGetInfo
By use of this function you may request information on the task specified by its handle, which
has been stored in a variable of type SYS_TASK_INFO.
hTask UDINT ID (handle) of the task
ppInfo POINTER TO Pointer to pointer to a structure variable of type

POINTER TO SYS_TASK_INFO (see 2.28).
SYS_TASK_INFO
2.13 SysTaskGetInterval
This function retrieves the actual interval of a cyclic task. If the specified task is not of cyclic
type, the function will return an error.
hTask UDINT ID of actual task (see structure SYS_TASK_INFO,

2.28).
puIInterval UDINT Pointer to current interval of cyclic task
2.14 SysTaskGetOSHandle
This function retrieves the operating system specific ID of the task specified by its handle. See
also SysTaskGetCurrentOSHandle and SysTaskGetCurrent.
hTask UDINT ID (handle) of the task.
2.15 SysTaskGetOSPriority
This function retrieves the operating system specific priority of the task determined by its
handle. In general, this priority does not equal the IEC priority of the task specified within the
application area. See also SysTaskGetPriority and SysTaskSetPriority.
The return of type UDINT is the OS priority of the task.

hTask UDINT Task handle (see structure SYS_TASK_INFO,

libdoc_e.dot / V1.0
2.28).
pulOSPriority POINTER TO Pointer to variable being assigned to the operating
UDINT system specific priority of the task

SysTask_V3x_E.doc
2.16 SysTaskGetPriority
This function retrieves the IEC priority of the task determined by its handle. See also
SysTaskSetPriority und SysTaskGetOSPriority.
hTask UDINT Task handle (see structure SYS_TASK_INFO,

2.28).
pulPriority POINTER TO Pointer to variable being assigned to the IEC priority
UDINT of the task
2.17 SysTaskJoin
This function serves for awaiting the termination of a task that should be joined by another
task. The function will return NOT_IMPLEMENTED on some target systems.
hTaskToJoin UDINT Handle of task that should be joined
ulTimeoutMs UDINT Time span (in milliseconds), wherein the termination

of TaskToJoin will be awaited
2.18 SysTaskLeave
This function serves to mark the end of processing for a task specified by its handle. That is,
this task will be set to state inactive. See also SysTaskEnter (2.6).
hTask UDINT ID (handle) of the task (see structure

2.19 SysTaskResume
This function serves to restart a task having been suspended by use of the function
SysTaskSuspend (2.23).
libdoc_e.dot / V1.0
hTask UDINT ID of task to be restarted (see structure


SysTask_V3x_E.doc
2.20 SysTaskSetExit
This function serves to set the exit flag of the task specified by its handle (ID). Within the next
cycle the task will get terminated by itself. See also SysTaskExit (2.7).
hTask UDINT ID of task whose exit flag shall be set (see structure
2.21 SysTaskSetInterval
This function serves to set the actual interval of a cyclic task. That can be used to synchronize
one task with another or with an event. If the specified task is not of cyclic task, the function
will return an error. See also SysTaskGetInterval (2.13).
hTask UDINT ID of task, whose actual interval is to be set (see

structure SYS_TASK_INFO, 2.28).
ulInterval UDINT Handle of interval to be set or of error message
2.22 SysTaskSetPriority
This function serves to set the IEC priority of a task. See also SysTaskGetPriority (2.16).
hTask UDINT ID of task, whose priority is to be set (see structure

ulPriority UDINT IEC priority; valid values range from 0 (=highest
priority) to 255 (=lowest priority). Thereby the
following values are reserved for
- the system: 0..31
- IEC tasks: 32..63
- Communications tasks: 64 and higher
2.23 SysTaskSuspend
By use of this function a task is suspended from being processed. Processing may be
continued by a call to function SysTaskResume (2.19).
libdoc_e.dot / V1.0
hTask UDINT ID of task to be suspended

(see structure SYS_TASK_INFO, 2.28).

SysTask_V3x_E.doc
2.24 SysTaskWaitInterval
Only for operating systems that support a cyclic processing of tasks! In this case you can use
the function SysTaskWaitInterval to shift the begin of processing the specified task to the start
point of the next time interval (see structure SysTaskParam, ulInterval in chapter 2.29).
hTask UDINT ID of task whose start shall be adjusted (see

structure SYS_TASK_INFO, 2.28).
2.25 SysTaskWaitSleep
This function serves to pause the processing of a running task for a time interval specified in
milliseconds. Processing will be continued after the time interval elapsed.
hTask UDINT ID of task, whose internal processing shall be

paused (see structure SYS_TASK_INFO, 2.28).
ulMilliSeconds UDINT Time interval in milliseconds the processing of the
task shall be paused
2.26 SysTaskWaitSleepUs
This function serves to pause the processing of a running task for a time interval specified in
microseconds. The function is not implemented on every platform.
hTask UDINT ID of task, whose internal processing shall be

paused (see structure SYS_TASK_INFO, 2.28).
ptSleepUs SYSTIME Time interval in microseconds the processing of the
task shall be paused
2.27 Structure RegContext

The structure contains information on the actual register content.
Structure Data type Meaning
component
libdoc_e.dot / V1.0
ulIP UDINT Instruction pointer; address of command to be

executed
ulBP UDINT Base pointer
ulSP UDINT Stack pointer

SysTask_V3x_E.doc
2.28 Structure SYS_TASK_INFO

This structure contains all possible parameters to describe a task. The parameters
additionally contained in SYS_TASK_PARAM are referenced.
component
ulOSHandle UDINT Operating system specific handle of task
iState DINT Status of task; valid values:

not generated 0
valid 1
active 2
suspended 4
deleted 8
exception error 16
iOldState DINT Last Status of task
TP SYS_TASK_PARAM Further parameters of task contained in structure

SYS_TASK_PARAM
ulCycleTime UDINT Time interval for cyclic tasks (in milliseconds)
uICycleStart UDINT Start time of task cycle
ulPriority UDINT Task priority; valid values range from 0 (=highest

priority) to 255 (=lowest priority).
ulOSPriority UDINT Operating system specific priority of task
ulInterval UDINT Time span (in milliseconds) after which task is

restarted
udStackSize UDINT Size of stack; Example: 4096
pFunction UDINT Name of function
szName STRING(SYSTASK_ Task name; maximum number of characters: 20

MAX_STRING_LEN)
pExceptionHand UDINT Pointer to exception routine to be processed in case
ler of an exception occurred
Context RegContext Structure RegContext (see 2.27);
2.29 Structure SYS_TASK_PARAM

This structure contains parameter to describe a task.
component
hTask UDINT ID number of task, created by SysTaskCreate;
bExit UDINT Operating system specific

libdoc_e.dot / V1.0
ulInterval UDINT Time span (in milliseconds) after which task is

restarted
pParam UDINT Typically pointer to structure or NULL

SysTask_V3x_E.doc
Change History
Version Description Date
0.1 Creation according to German version 1.0 19.02.2008

1.0 Release after formal review 20.02.2008
libdoc_e.dot / V1.0

SysTask_V3x_E.doc

SysTask V3x E

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

SysTask V3x E

Caricato da

Copyright:

Formati disponibili

Library Description:

Document Version 1.0

3S - Smart Software Solutions GmbH Seite 1 von 14

3S - Smart Software Solutions GmbH Seite 3 von 14

The functions: SysTaskGetPriority

3S - Smart Software Solutions GmbH Seite 4 von 14

hTask UDINT ID of actual task (see structure SYS_TASK_INFO,

pszTaskName STRING Name of new task

pFunction POINTER TO Pointer to function to be called by the task

ulStackSize UDINT Stack size of task in bytes (default=0)

3S - Smart Software Solutions GmbH Seite 5 von 14

Input variable Data type Description

phTaskHandle POINTER TO Pointer to task handle (ID), see structure

pszTaskName STRING Name of new task

pFunction POINTER TO Pointer to function to be called by the task

3S - Smart Software Solutions GmbH Seite 6 von 14

hTask UDINT ID of task to be deleted (see structure

hTask UDINT ID of task (see structure SYS_TASK_INFO, 2.28).

hTask UDINT ID of the task (see structure SYS_TASK_INFO,

hTask UDINT ID of the task (see structure SYS_TASK_INFO,

3S - Smart Software Solutions GmbH Seite 7 von 14

ulTaskOSHandle UDINT ID of the task (see structure SYS_TASK_INFO,

Context RegContext Context to localize the occurrence of the exception

hTask UDINT ID of the actual task (see structure

phTask POINTER TO Pointer to handle of actual task

document "Runtime Error Codes").

pulOSHandle POINTER TO Pointer to operating system specific handle of

3S - Smart Software Solutions GmbH Seite 8 von 14

hTask UDINT ID (handle) of the task

ppInfo POINTER TO Pointer to pointer to a structure variable of type

hTask UDINT ID of actual task (see structure SYS_TASK_INFO,

hTask UDINT ID (handle) of the task.

The return of type UDINT is the OS priority of the task.

hTask UDINT Task handle (see structure SYS_TASK_INFO,

3S - Smart Software Solutions GmbH Seite 9 von 14

hTask UDINT Task handle (see structure SYS_TASK_INFO,

hTaskToJoin UDINT Handle of task that should be joined

ulTimeoutMs UDINT Time span (in milliseconds), wherein the termination

hTask UDINT ID (handle) of the task (see structure

hTask UDINT ID of task to be restarted (see structure

3S - Smart Software Solutions GmbH Seite 10 von 14

hTask UDINT ID of task, whose actual interval is to be set (see

hTask UDINT ID of task, whose priority is to be set (see structure

hTask UDINT ID of task to be suspended

3S - Smart Software Solutions GmbH Seite 11 von 14

hTask UDINT ID of task whose start shall be adjusted (see

hTask UDINT ID of task, whose internal processing shall be

hTask UDINT ID of task, whose internal processing shall be

2.27 Structure RegContext

ulIP UDINT Instruction pointer; address of command to be

ulSP UDINT Stack pointer

3S - Smart Software Solutions GmbH Seite 12 von 14

2.28 Structure SYS_TASK_INFO

ulOSHandle UDINT Operating system specific handle of task

iState DINT Status of task; valid values:

TP SYS_TASK_PARAM Further parameters of task contained in structure

uICycleStart UDINT Start time of task cycle

ulPriority UDINT Task priority; valid values range from 0 (=highest

ulInterval UDINT Time span (in milliseconds) after which task is

pFunction UDINT Name of function

szName STRING(SYSTASK_ Task name; maximum number of characters: 20

Context RegContext Structure RegContext (see 2.27);

2.29 Structure SYS_TASK_PARAM