Changeset 56634c5 in rtems


Ignore:
Timestamp:
Jul 13, 1999, 6:05:13 PM (22 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
75c45f2
Parents:
d2633470
Message:

Update from Jeff Mayes, Jennifer Averett, and Suzie Provitt.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/itron3.0/tasksync.t

    rd2633470 r56634c5  
    1111@section Introduction
    1212
    13 The
    14 task-dependent synchronization manager is ...
     13The task-dependent synchronization manager is designed to utilize those synchronization
     14functions already supported by tasks.  This includes functions that suspend tasks for a while and associated functions that release SUSPEND state, and synchronization functions which make tasks wait and wake them up.
    1515
    1616The services provided by the task-dependent synchronization manager are:
     
    2626@end itemize
    2727
    28 @section Background
    29 
    3028@section Operations
     29@subsection Suspend Other Task
     30This call stops the execution of a task by putting it into a SUSPEND state.  This call is not able to specify itself, since this would end the flow of execution altogether.  If the task is already in a WAIT state, then SUSPEND is added to become WAIT-SUSPEND.  These modes are turned on and off separately, without affecting one another.  Furthermore, SUSPEND states can be nested, and tasks in a SUSPEND state are allocated resources as normal.
     31
     32@subsection Resume Suspended Task
     33This operation restarts the execution of a task that was previously stopped by the SUSPEND OTHER TASK call.  Obviously, a task cannot specify itself using this call.  Since SUSPEND states can be nested, one call to RESUME releases only one SUSPEND.  Thus, it takes as many RESUMES as SUSPENDS to return the task to execution.
     34
     35@subsection Forcibly Resume Suspended Task
     36This call has the same functionality as the previously mentioned Resume Suspended Task with one exception.  This call releases all nested SUSPENDS at once, which guarantees the task will return to execution.
     37
     38@subsection Sleep Task
     39The Sleep Task operation causes the specified task to sleep until a Wakeup Task function is called.  This puts the task in a WAIT state.  WAIT states can not be nested, but can be combined with SUSPEND states as mentioned earlier. 
     40
     41@subsection Sleep Task with Timeout
     42This function is identical to the Sleep Task function with an added timeout attribute.  If the timeout mark is reached before a Wakeup call is recieved, an error is generated.
     43
     44@subsection Wakeup Other Task
     45The Wakeup Other Task call is used to release the WAIT state of a task.  These calls can be previously queued using the wupcnt value so that when the matching Sleep Task is executed, there will be no delay.
     46
     47@subsection Cancel Wakeup Request
     48This function call resets the value of wupcnt to zero, thereby canceling all associated wakeup requests.  A call to self is acceptable for this operation, and may even be useful for monitoring certain situations.
    3149
    3250@section System Calls
    3351
    34 This section details the task-dependent synchronization manager's services.
    35 A subsection is dedicated to each of this manager's services
    36 and describes the calling sequence, related constants, usage,
    37 and status codes.
     52This section details the task-dependent synchronization manager's services. A subsection is dedicated to each of this manager's services and describes the calling sequence, related constants, usage, and status codes.
    3853
    3954
     
    6075@subheading STATUS CODES:
    6176
    62 @code{EXXX} -
    63 
    64 @subheading DESCRIPTION:
    65 
    66 @subheading NOTES:
    67 
     77@code{E_OK} - Normal Completion
     78
     79@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
     80
     81@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
     82
     83@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
     84
     85@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself)
     86
     87@code{E_QOVR} - Queuing or nesting overflow (the number of nesting levels given by suscnt went over the maximum allowed)
     88
     89@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     90
     91@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     92
     93@subheading DESCRIPTION:
     94This system call suspends the execution of the task specified by tskid by putting it into SUSPEND state.
     95
     96SUSPEND state is released by issuing the rsm_tsk or frsm_tsk system call. If the task specified to sus_tsk is already in WAIT state, it will be put in the combined WAIT-SUSPEND state by the execution of sus_tsk.  If wait conditions for the task are later fulfilled, it will enter SUSPEND state. If rsm_tsk is issued on the task, it will return to the WAIT state before the suspension.
     97
     98Since SUSPEND state indicates the suspension of execution by a system call issued from another task, a task may not specify itself to this system call. An E_OBJ error will result if a task specifies itself.
     99
     100If more than one sus_tsk call is issued to a task, that task will be put in multiple SUSPEND states.  This is called suspend request nesting.  When this is done, rsm_tsk must be issued the same number of times which sus_tsk was issued (suscnt) in order to return the task to its original state before the suspension.  This means it is possible to nest the pairs of sus_tsk and rsm_tsk.
     101
     102The maximum number of times suspend requests may be nested, and even whether or not suspend request nesting (the ability to issue sus_tsk on the same task more than once) is even allowed, is implementation dependent.  Suspend request nesting is considered an extended function [level X] for which compatibility and connectivity are not guaranteed.
     103
     104An E_QOVR error will result if sus_tsk is issued more than once on the same task on a system which does not support suspend request nesting or if it is issued more than the maximum number of times allowed.
     105
     106@subheading NOTES:
     107A task which is suspended in addition to waiting for resources (such as waiting for a semaphore) can be allocated resources (such as semaphore counts) based on the same conditions as tasks which are not suspended.  Even when suspended, the allocation of resources is not delayed in any way.  Conditions concerning resource allocation and release of the wait state remain unchanged. In other words, SUSPEND state is completely independent of other processing and task states.  If it is desirable to delay the allocation of resources to a task which is suspended, the user should use chg_pri in conjunction with sus_tsk and rsm_tsk.
    68108
    69109@c
     
    89129@subheading STATUS CODES:
    90130
    91 @code{EXXX} -
    92 
    93 @subheading DESCRIPTION:
    94 
    95 @subheading NOTES:
    96 
     131@code{E_OK} - Normal Completion
     132
     133@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
     134
     135@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
     136
     137@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
     138
     139@code{E_OBJ} - Invalid object state (the target task is not in SUSPEND state (including when it is DORMANT or when the issuing task specifies itself))
     140
     141@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     142
     143@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     144
     145@subheading DESCRIPTION:
     146This system call releases SUSPEND state of the task specified by tskid.  Specifically, it causes SUSPEND state to be released and the execution of the specified task to resume when the task has been suspended by the prior execution of sus_tsk.
     147If the specified task is in WAIT-SUSPEND state, the execution of rsm_tsk only releases the SUSPEND state, and the task will become WAIT state.
     148
     149A task cannot specify itself to this system call.  An E_OBJ error will result if a task specifies itself.
     150
     151Rsm_tsk only releases one suspend request from the suspend request nest (suscnt).  Accordingly, if more than one sus_tsk has been issued on the task in question (suscnt >= 2), that task will remain suspended even after the execution of rsm_tsk is completed.
     152
     153@subheading NOTES:
     154It is implementation dependent which location in the ready queue a task returns to after the task which has been suspended from RUN or READY state is resumed by rsm_tsk.
    97155
    98156@c
     
    118176@subheading STATUS CODES:
    119177
    120 @code{EXXX} -
    121 
    122 @subheading DESCRIPTION:
    123 
    124 @subheading NOTES:
     178@code{E_OK} - Normal Completion
     179
     180@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
     181
     182@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
     183
     184@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
     185
     186@code{E_OBJ} - Invalid object state (the target task is not in SUSPEND state (including when it is DORMANT or when the issuing task specifies itself))
     187
     188@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     189
     190@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     191
     192@subheading DESCRIPTION:
     193This system call releases SUSPEND state of the task specified by tskid.  Specifically, it causes SUSPEND state to be released and the execution of the specified task to resume when the task has been suspended by the prior execution of sus_tsk.  If the specified task is in WAIT-SUSPEND state, the execution of rsm_tsk only releases the SUSPEND state, and the task will become WAIT state.
     194
     195A task cannot specify itself to this system call.  An E_OBJ error will result if a task specifies itself.
     196
     197Frsm_tsk will clear all suspend requests (suscnt = 0) even if more than one sus_tsk has been issued (suscnt >= 2) on the same task.  In other words, SUSPEND state is guaranteed to be released, and execution will resume unless the task in question had been in combined WAIT-SUSPEND state.
     198
     199@subheading NOTES:
     200It is implementation dependent which location in the ready queue a task returns to after the task which has been suspended from RUN or READY state is resumed by frsm_tsk.
    125201
    126202
     
    145221@subheading STATUS CODES:
    146222
    147 @code{EXXX} -
    148 
    149 @subheading DESCRIPTION:
     223@code{E_OK} - Normal Completion
     224
     225@code{E_PAR} - Parameter error (a timeout value -2 or less was specified)
     226
     227@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting) 
     228
     229@code{E_TMOUT} - Polling failure or timeout exceeded
     230
     231@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
     232
     233@subheading DESCRIPTION:
     234
    150235This system call puts the issuing task (which was in RUN state) into WAIT state, causing the issuing task to sleep until wup_tsk is invoked.
    151236
     237@subheading NOTES:
    152238Since the slp_tsk system call causes the issuing task to enter WAIT state, slp_tsk calls may not be nested.  It is possible, however, for another task to execute a sus_tsk on a task which has put itself in WAIT state using slp_tsk.  If this happens, the task will enter the combined WAIT-SUSPEND state.
     239
    153240No polling function for slp_tsk is provided.  A similar function can be implemented if necessary using can_wup.
    154241
     
    174261
    175262@subheading STATUS CODES:
    176 @code{EXXX} -
     263
     264@code{E_OK} - Normal Completion
     265
     266@code{E_PAR} - Parameter error (a timeout value -2 or less was specified)
     267
     268@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting) 
     269
     270@code{E_TMOUT} - Polling failure or timeout exceeded
     271
    177272@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
    178273
     274@subheading DESCRIPTION:
    179275The tslp_tsk system call is the same as slp_tsk but with an additional timeout feature.  If a wup_tsk is issued before the period of time specified by tmout elapses, tslp_tsk will complete normally.  An E_TMOUT error will result if no wup_tsk is issued before the time specified by tmout expires.  Specifying tmout = TMO_FEVR = -1 can be used to set the timeout period to forever (no timeout).  In this case, tslp_tsk will function exactly the same as slp_tsk causing the issuing task to wait forever for wup_tsk to be issued.
    180276
     277@subheading NOTES:
    181278Since the tslp_tsk system call causes the issuing task to enter WAIT state, tslp_tsk calls may not be nested.  It is possible, however, for another task to execute a sus_tsk on a task which has put itself in WAIT state using tslp_tsk.  If this happens, the task will enter the combined WAIT-SUSPEND state.
     279
    182280If you simply wish to delay a task (make it wait for a while), use dly_tsk rather than tslp_tsk.
    183281
     
    203301
    204302@subheading STATUS CODES:
    205 @code{EXXX} -
    206 @code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     303
     304@code{E_OK} - Normal Completion
     305
     306@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
     307
     308@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
     309
     310@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
     311
     312@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself)
     313
     314@code{E_QOVR} - Queuing or nesting overflow (wakeup request queuing count will exceed the maximum value allowed for wupcnt)
     315
     316@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     317
     318@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     319
     320@subheading DESCRIPTION:
     321This system call releases the WAIT state of the task specified by tskid caused by the execution of slp_tsk or tslp_tsk.
     322
     323A task cannot specify itself in this system call.  An E_OBJ error will result if a task specifies itself.
    207324
    208325If the specified task is not in the WAIT state caused by a slp_tsk or tslp_tsk, the wakeup request based on the wup_tsk call will be queued. In other words, a record will be kept that a wup_tsk has been issued for the specified task and no WAIT state will result even if slp_tsk or tslp_tsk is executed by the task later.  This is called queuing for wakeup request.
     326
     327@subheading NOTES:
     328Wakeup requests are queued as follows.  A wakeup request queuing count (wupcnt) is kept in the TCB for each task.  Initially (when sta_tsk is executed) the value of wupcnt is 0.  Executing wup_tsk on a task which is not waiting for a wakeup increments the wakeup request queuing count by one for the specified task.  If slp_tsk or tslp_tsk is executed on that task, its wakeup request queuing count will be decremented by one.  If the task with wakeup request queuing count = 0 executes slp_tsk or tslp_tsk, that task will be put in WAIT state rather than decrementing the wakeup request queuing count.
     329
     330It is always possible to queue at least one wup_tsk (wupcnt = 1); the maximum allowable number for the wakeup request queuing count (wupcnt) is implementation dependent, and may be any number higher than or equal to one. In other words, while the first wup_tsk issued to a task which is not waiting for a wakeup will not result in an error, it is implementation dependent whether or not any further wup_tsk calls on the same task will result in an error.  The ability to queue more than one wakeup request is considered an extended function [level X] for which compatibility and connectivity are not guaranteed.
    209331
    210332An E_QOVR error will result if wup_tsk is issued more than the maximum value allowed for the wakeup request queuing count (wupcnt).
     
    233355
    234356@subheading STATUS CODES:
    235 @code{EXXX} -
     357
     358@code{E_OK} - Normal Completion
     359
     360@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
     361
     362@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
     363
     364@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
     365
     366@code{E_OBJ} - Invalid object state (the target task is in DORMANT state)
     367
     368@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     369
     370@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
     371
    236372@code{EN_RPAR} - A value outside the range supported by the issuing node and/or transmission packet format was returned as a return parameter (a value outside supported range was returned for wupcnt)
    237373
     374@subheading DESCRIPTION:
     375This system call returns the wakeup request queuing count (wupcnt) for the task specified by tskid while canceling all associated wakeup requests. Specifically, it resets the wakeup request queuing count (wupcnt) to 0.
     376
    238377A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified when this system call is issued from a task-independent portion.
    239378
    240 
    241 
     379@subheading NOTES:
     380An EN_RPAR error will result if the number of bits used on the target node is larger than that used on the requesting node, and if a value not supported by the requesting node is returned for wupcnt.
     381
     382This system call can be used to determine whether or not processing has ended within a certain period when a task should periodically waken up by wup_tsk and do some processing.  In other words, if a task monitoring the progress of its processing issues can_wup before issuing a slp_tsk after finishing processing associated with a previous wakeup request, and if wupcnt, one of can_wup's return parameters, is equal to or greater than one, it indicates that the processing for the previous wakeup request does not complete within a required time.  This allows the monitoring task to take actions against processing delays.
     383
     384
Note: See TracChangeset for help on using the changeset viewer.