summaryrefslogtreecommitdiffstats
path: root/doc/itron3.0/eventflags.t
diff options
context:
space:
mode:
Diffstat (limited to 'doc/itron3.0/eventflags.t')
-rw-r--r--doc/itron3.0/eventflags.t173
1 files changed, 142 insertions, 31 deletions
diff --git a/doc/itron3.0/eventflags.t b/doc/itron3.0/eventflags.t
index cea7fb2d89..3a50fd7d15 100644
--- a/doc/itron3.0/eventflags.t
+++ b/doc/itron3.0/eventflags.t
@@ -40,13 +40,26 @@ An eventflag is used by a task (or ISR) to inform another task of the occurrence
@item Events are not queued. In other words, if an event is sent more than once to a task before being received, the second and subsequent send operations to that same task have no effect.
@end itemize
-A pending event is an event that has been posted but not received. An event condition is used to specify the events which the task desires to receive and the algorithm which will be used to determine when the request is satisfied. An event condition is satisfied based upon one of two algorithms which are selected by the user. The @code{TWF_ORW} algorithm states that an event condition is satisfied when at least a single requested event is posted. The @code{TWF_ANDW} algorithm states that an event condition is satisfied when every requested event is posted.
-
-An event set or condition is built by a bitwise OR of the desired events. If an event is not explicitly specified in the set or condition, then it is not present. Events are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each event appears exactly once in the event set list.
+A pending event is an event that has been posted but not received. An
+event condition is used to specify the events which the task desires to
+receive and the algorithm which will be used to determine when the request
+is satisfied. An event condition is satisfied based upon one of two
+algorithms which are selected by the user. The @code{TWF_ORW} algorithm
+states that an event condition is satisfied when at least a single
+requested event is posted. The @code{TWF_ANDW} algorithm states that an
+event condition is satisfied when every requested event is posted.
+
+An event set or condition is built by a bitwise OR of the desired events.
+If an event is not explicitly specified in the set or condition, then it
+is not present. Events are specifically designed to be mutually exclusive,
+therefore bitwise OR and addition operations are equivalent as long as
+each event appears exactly once in the event set list.
@subsection T_CFLG Structure
-The T_CFLG structire is used to define the characteristics of an eventflag and passed as an argument to the @code{cre_flg} service. The structure is defined as follows:
+The T_CFLG structire is used to define the characteristics of an eventflag
+and passed as an argument to the @code{cre_flg} service. The structure is
+defined as follows:
@example
@@ -83,16 +96,30 @@ typedef struct t_cflg @{
where the meaning of each field is:
@table @b
-@item VP
-exinf exinf may be used freely by the user for including extended information about the eventflag to be created. Information set here may be accessed by ref_flg. If a larger region is desired for including user information, or if the user wishes to change the contents of this information, the usr should allocate memory area and set the address of this memory packet to exinf. The OS does not take care of the contents of exinf. This implementation does not use this field.
-@item ATR
-flgatr is the attributes for this eventflag. The lower bits of flgatr represent system attributes, while the upper bits represent implementation-dependent attributes.
+@item exinf
+
+may be used freely by the user for including extended information about
+the eventflag to be created. Information set here may be accessed by
+ref_flg. If a larger region is desired for including user information, or
+if the user wishes to change the contents of this information, the usr
+should allocate memory area and set the address of this memory packet to
+exinf. The OS does not take care of the contents of exinf. This
+implementation does not use this field.
+
+@item flgatr
-@item UINT
-iflgptn is the initial eventflag pattern.
+is the attributes for this eventflag. The lower bits of flgatr represent
+system attributes, while the upper bits represent implementation-dependent
+attributes.
+
+@item iflgptn
+
+is the initial eventflag pattern.
(CPU and/or implementation-dependent information may also be included)
+
@end table
+
@subsection T_RFLG Structure
The T_RFLG structire is used to define the characteristics of an eventflag and passed as an argument to the @code{ref_flg} service. The structure is defined as follows:
@@ -109,7 +136,9 @@ typedef struct t_rflg @{
@table @b
@item BOOL_ID
+
indicates whether or not there is a task waiting for the eventflag in question. If there is no waiting task, wtsk is returned as FALSE = 0. If there is a waiting task, wtsk is returned as a value other than 0.
+
@end table
@section Operations
@@ -288,12 +317,19 @@ ER clr_flg(
@subheading STATUS CODES:
+
@code{E_OK} - Normal Completion
+
@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
+
@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
+
@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
+
@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
+
@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
+
@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for setptn or clrptn)
@subheading DESCRIPTION:
@@ -333,30 +369,43 @@ ER wai_flg(
@subheading STATUS CODES:
+
@code{E_OK} - Normal Completion
+
@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
+
@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
+
@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
+
@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
+
@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
+
@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
+
@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
+
@code{E_TMOUT} - Polling failure or timeout exceeded
+
@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
+
@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
+
@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for waiptn and tmout)
+
@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
@subheading DESCRIPTION:
The @code{wai_flg} system call waits for the eventflag specified by @code{flgid} to be set to satisfy the wait release condition specified by @code{wfmode}.
-If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
+If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting. @code{wfmode} may be specified as follows.
-@code{wfmode} may be specified as follows.
@example
wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]
@end example
+
If @code{TWF_ORW} is specified, the issuing task will wait for any of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (OR wait). If @code{TWF_ANDW} is specified, the issuing task will wait for all of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (AND wait).
If the @code{TWF_CLR} specification is not present, the eventflag value will remain unchanged even after the wait conditions have been satisfied and the task has been released from the WAIT state. If @code{TWF_CLR} is specified, all bits of the eventflag will be cleared to 0 once the wait conditions of the waiting task have been satisfied.
@@ -365,11 +414,15 @@ The return parameter flgptn returns the value of the eventflag after the wait st
The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed. The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}. The specific operations by @code{pol_flg} are as follows.
- - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
+@itemize @bullet
+
+@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
- - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
+@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
-The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature. A maximum wait time (timeout value) can be specified using the parameter tmout. When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
+@end itemize
+
+The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature. A maximum wait time (timeout value) can be specified using the parameter tmout. When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by @code{tmout}
elapses without conditions for releasing wait being satisfied.
Specifying @code{TMO_POL = 0} to @code{twai_flg} for tmout indicates that a timeout value of 0 be used, resulting in exactly the same processing as @code{pol_flg}. Specifying @code{TMO_FEVR = -1} to @code{twai_flg} for tmout indicates that an infinite timeout value be used, resulting in exactly the same processing as @code{wai_flg}.
@@ -382,11 +435,15 @@ On the other hand, multiple tasks can wait at the same time for the same eventfl
The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
- - The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
+@itemize @bullet
+
+@item The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
- - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
+@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
- - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+
+@end itemize
If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
@@ -394,6 +451,7 @@ If multiple tasks having the same priority are released from waiting simultaneou
Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
+
@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout. As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
@c
@@ -421,30 +479,43 @@ ER pol_flg(
@subheading STATUS CODES:
+
@code{E_OK} - Normal Completion
+
@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
+
@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
+
@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
+
@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
+
@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
+
@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
+
@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
+
@code{E_TMOUT} - Polling failure or timeout exceeded
+
@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
+
@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
+
@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for waiptn and tmout)
+
@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
@subheading DESCRIPTION:
The @code{wai_flg} system call waits for the eventflag specified by @code{flgid} to be set to satisfy the wait release condition specified by @code{wfmode}.
-If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
+If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting. @code{wfmode} may be specified as follows.
-@code{wfmode} may be specified as follows.
@example
wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]
@end example
+
If @code{TWF_ORW} is specified, the issuing task will wait for any of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (OR wait). If @code{TWF_ANDW} is specified, the issuing task will wait for all of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (AND wait).
If the @code{TWF_CLR} specification is not present, the eventflag value will remain unchanged even after the wait conditions have been satisfied and the task has been released from the WAIT state. If @code{TWF_CLR} is specified, all bits of the eventflag will be cleared to 0 once the wait conditions of the waiting task have been satisfied.
@@ -453,9 +524,13 @@ The return parameter flgptn returns the value of the eventflag after the wait st
The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed. The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}. The specific operations by @code{pol_flg} are as follows.
- - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
+@itemize @bullet
+
+@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
- - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
+@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
+
+@end itemize
The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature. A maximum wait time (timeout value) can be specified using the parameter tmout. When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied.
@@ -470,11 +545,15 @@ On the other hand, multiple tasks can wait at the same time for the same eventfl
The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
- - The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
+@itemize @bullet
+
+@item The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
- - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
+@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
- - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+
+@end itemize
If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
@@ -482,6 +561,7 @@ If multiple tasks having the same priority are released from waiting simultaneou
Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
+
@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout. As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
@c
@@ -495,7 +575,7 @@ Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes wil
@ifset is-C
@example
-ER ercd =twai_flg(
+ER twai_flg(
UINT *p_flgptn,
ID flgid,
UINT waiptn,
@@ -509,18 +589,31 @@ ER ercd =twai_flg(
@subheading STATUS CODES:
+
@code{E_OK} - Normal Completion
+
@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
+
@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
+
@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
+
@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
+
@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
+
@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
+
@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
+
@code{E_TMOUT} - Polling failure or timeout exceeded
+
@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
+
@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
+
@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for waiptn and tmout)
+
@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
@subheading DESCRIPTION:
@@ -529,6 +622,7 @@ The @code{wai_flg} system call waits for the eventflag specified by @code{flgid}
If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
+
@code{wfmode} may be specified as follows.
@example
wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]
@@ -541,9 +635,13 @@ The return parameter flgptn returns the value of the eventflag after the wait st
The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed. The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}. The specific operations by @code{pol_flg} are as follows.
- - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
+@itemize @bullet
+
+@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
+
+@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
- - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
+@end itemize
The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature. A maximum wait time (timeout value) can be specified using the parameter tmout. When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
elapses without conditions for releasing wait being satisfied.
@@ -558,11 +656,15 @@ On the other hand, multiple tasks can wait at the same time for the same eventfl
The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
- - The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
+@itemize @bullet
- - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
+@item The waiting order on the queue is FIFO. (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
- - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
+
+@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
+
+@end itemize
If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
@@ -570,6 +672,7 @@ If multiple tasks having the same priority are released from waiting simultaneou
Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
+
@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout. As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
@c
@@ -595,13 +698,21 @@ ER ref_flg(
@subheading STATUS CODES:
+
@code{E_OK} - Normal Completion
+
@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
+
@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
+
@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
+
@code{E_PAR} - Parameter error (the packet address for the return parameters could not be used)
+
@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
+
@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
+
@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was returned as a parameter (a value outside supported range was specified for exinf, wtsk and/or flgptn)
@subheading DESCRIPTION: