diff options
Diffstat (limited to 'doc/itron3.0')
| -rw-r--r-- | doc/itron3.0/.cvsignore | 37 | ||||
| -rw-r--r-- | doc/itron3.0/Makefile.am | 102 | ||||
| -rw-r--r-- | doc/itron3.0/config.t | 187 | ||||
| -rw-r--r-- | doc/itron3.0/eventflags.t | 860 | ||||
| -rw-r--r-- | doc/itron3.0/fixedblock.t | 389 | ||||
| -rw-r--r-- | doc/itron3.0/gen_all | 4 | ||||
| -rw-r--r-- | doc/itron3.0/gen_section | 191 | ||||
| -rw-r--r-- | doc/itron3.0/gen_status_shell | 230 | ||||
| -rw-r--r-- | doc/itron3.0/interrupt.t | 306 | ||||
| -rw-r--r-- | doc/itron3.0/itron.texi | 144 | ||||
| -rw-r--r-- | doc/itron3.0/mailbox.t | 338 | ||||
| -rw-r--r-- | doc/itron3.0/memorypool.t | 401 | ||||
| -rw-r--r-- | doc/itron3.0/msgbuffer.t | 826 | ||||
| -rw-r--r-- | doc/itron3.0/network.t | 162 | ||||
| -rw-r--r-- | doc/itron3.0/preface.texi | 14 | ||||
| -rw-r--r-- | doc/itron3.0/rendezvous.t | 395 | ||||
| -rw-r--r-- | doc/itron3.0/semaphore.t | 642 | ||||
| -rw-r--r-- | doc/itron3.0/stamp-vti | 4 | ||||
| -rw-r--r-- | doc/itron3.0/status.t | 943 | ||||
| -rw-r--r-- | doc/itron3.0/task.t | 767 | ||||
| -rw-r--r-- | doc/itron3.0/tasksync.t | 388 | ||||
| -rw-r--r-- | doc/itron3.0/time.t | 310 | ||||
| -rw-r--r-- | doc/itron3.0/version.texi | 4 |
23 files changed, 0 insertions, 7644 deletions
diff --git a/doc/itron3.0/.cvsignore b/doc/itron3.0/.cvsignore deleted file mode 100644 index 3b94f81df5..0000000000 --- a/doc/itron3.0/.cvsignore +++ /dev/null @@ -1,37 +0,0 @@ -config.texi -eventflags.texi -fixedblock.texi -index.html -interrupt.texi -itron -itron-? -itron-?? -itron.aux -itron.cp -itron.dvi -itron.fn -itron*.html -itron.info -itron.ky -itron.log -itron.pdf -itron.pg -itron.ps -itron.toc -itron.tp -itron.vr -mailbox.texi -Makefile -Makefile.in -mdate-sh -memorypool.texi -msgbuffer.texi -network.texi -rendezvous.texi -rtems_footer.html -rtems_header.html -semaphore.texi -status.texi -tasksync.texi -task.texi -time.texi diff --git a/doc/itron3.0/Makefile.am b/doc/itron3.0/Makefile.am deleted file mode 100644 index 31b8288780..0000000000 --- a/doc/itron3.0/Makefile.am +++ /dev/null @@ -1,102 +0,0 @@ -# -# COPYRIGHT (c) 1988-2002. -# On-Line Applications Research Corporation (OAR). -# All rights reserved. -# -# $Id$ -# - -PROJECT = itron - -include $(top_srcdir)/project.am -include $(top_srcdir)/main.am - -GENERATED_FILES = status.texi task.texi tasksync.texi semaphore.texi \ - eventflags.texi mailbox.texi msgbuffer.texi rendezvous.texi \ - interrupt.texi memorypool.texi fixedblock.texi time.texi config.texi \ - network.texi - -COMMON_FILES += $(top_srcdir)/common/cpright.texi - -FILES = preface.texi - -info_TEXINFOS = itron.texi -itron_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) - -status.texi: status.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -task.texi: task.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -tasksync.texi: tasksync.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -semaphore.texi: semaphore.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -eventflags.texi: eventflags.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -mailbox.texi: mailbox.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -msgbuffer.texi: msgbuffer.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -rendezvous.texi: rendezvous.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -interrupt.texi: interrupt.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -memorypool.texi: memorypool.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -fixedblock.texi: fixedblock.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -time.texi: time.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -config.texi: config.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -network.texi: network.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -noinst_SCRIPTS = gen_all gen_section gen_status_shell - -EXTRA_DIST = config.t eventflags.t fixedblock.t interrupt.t mailbox.t \ - memorypool.t msgbuffer.t network.t rendezvous.t semaphore.t status.t \ - task.t tasksync.t time.t $(noinst_SCRIPTS) - -CLEANFILES += itron.info itron.info-? diff --git a/doc/itron3.0/config.t b/doc/itron3.0/config.t deleted file mode 100644 index ddfd61fcef..0000000000 --- a/doc/itron3.0/config.t +++ /dev/null @@ -1,187 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the system -@c manager. -@c -@c $Id$ -@c - -@chapter System Manager - -@section Introduction - -The -system manager is ... - -The services provided by the system manager are: - -@itemize @bullet -@item @code{get_ver} - Get Version Information -@item @code{ref_sys} - Reference Semaphore Status -@item @code{ref_cfg} - Reference Configuration Information -@item @code{def_svc} - Define Extended SVC Handler -@item @code{def_exc} - Define Exception Handler -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the system 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. - - -@c -@c get_ver -@c - -@page -@subsection get_ver - Get Version Information - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER get_ver( - T_VER *pk_ver -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_sys -@c - -@page -@subsection ref_sys - Reference Semaphore Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_sys( - T_RSYS *pk_rsys -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_cfg -@c - -@page -@subsection ref_cfg - Reference Configuration Information - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_cfg( - T_RCFG *pk_rcfg -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c def_svc -@c - -@page -@subsection def_svc - Define Extended SVC Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER def_svc( - FN s_fncd, - T_DSVC *pk_dsvc -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c def_exc -@c - -@page -@subsection def_exc - Define Exception Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER def_exc( - UINT exckind, - T_DEXC *pk_dexc -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/itron3.0/eventflags.t b/doc/itron3.0/eventflags.t deleted file mode 100644 index 1d9d134fe2..0000000000 --- a/doc/itron3.0/eventflags.t +++ /dev/null @@ -1,860 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the eventflags -@c manager. -@c -@c $Id$ -@c - -@chapter Eventflags Manager - -@section Introduction - -The eventflag manager provides a high performance method of intertask communication and synchronization. The directives provided by the eventflag manager are: - -The services provided by the eventflags manager are: - -@itemize @bullet -@item @code{cre_flg} - Create Eventflag -@item @code{del_flg} - Delete Eventflag -@item @code{set_flg} - Set Eventflag -@item @code{clr_flg} - Clear Eventflag -@item @code{wai_flg} - Wait on Eventflag -@item @code{pol_flg} - Wait for Eventflag (Polling) -@item @code{twai_flg} - Wait on Eventflag with Timeout -@item @code{ref_flg} - Reference Eventflag Status -@end itemize - -@section Background - -@subsection Event sets - -An eventflag is used by a task (or ISR) to inform another task of the -occurrence of a significant situation. One word bit-field is associated with each eventflags. The application developer should remember the -following key characteristics of event operations when utilizing the event -manager: - -@itemize @bullet -@item Events provide a simple synchronization facility. -@item Events are aimed at tasks. -@item Tasks can wait on more than one event simultaneously. -@item Events are independent of one another. -@item Events do not hold or transport data. -@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 set. 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 eventflags 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: - -@example - -/* - * Create Eventflags (cre_flg) Structure - */ - -typedef struct t_cflg @{ - VP exinf; /* extended information */ - ATR flgatr; /* eventflag attribute */ - UINT iflgptn; /* initial eventflag */ - /* additional implementation dependent information may be included */ -@} T_CFLG; - -/* - * flgatr - Eventflag Attribute Values - */ - - -/* multiple tasks are not allowed to wait (Wait Single Task)*/ - -#define TA_WSGL 0x00 - -/* multiple tasks are allowed to wait (Wait Multiple Task) */ - -#define TA_WMUL 0x08 - -/* wfmode */ -#define TWF_ANDW 0x00 /* AND wait */ -#define TWF_ORW 0x02 /* OR wait */ -#define TWF_CLR 0x01 /* clear specification */ -@end example - -where the meaning of each field is: - -@table @b - -@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 -@code{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 -@code{exinf}. The OS does not take care of the contents of @code{exinf}. This -implementation does not use this field. - -@item flgatr - -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: - -@example -/* Reference Eventflags (ref_flg) Structure */ -typedef struct t_rflg @{ - VP exinf; /* extended information */ - BOOL_ID wtsk; /* indicates whether or not there is a waiting task */ - UINT flgptn; /* eventflag bit pattern */ - /* additional implementation dependent information may be included */ -@} T_RFLG; -@end example - -@table @b - -@item exinf - -see @code{T_CFLG}. - -@item wtsk - -indicates whether or not there is a task waiting for the eventflag in -question. If there is no waiting task, @code{wtsk} is returned as FALSE = 0. -If there is a waiting task, @code{wtsk} is returned as a value other than 0. - -@item flgptn - -is the eventflag pattern. - -@end table - -@section Operations - -@section System Calls - -This section details the eventflags 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. - - -@c -@c cre_flg -@c - -@page -@subsection cre_flg - Create Eventflag - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_flg( - ID flgid, - T_CFLG *pk_cflg -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be -allocated) - -@code{E_ID} - Invalid ID number (flgid was invalid or could not be used) - -@code{E_RSATR} - Reserved attribute (flgatr was invalid or could not be -used) - -@code{E_OBJ} - Invalid object state (an eventflag of the same ID already -exists) - -@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 (pk_cflg is invalid) - -@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 exinf, flgatr and/or iflgptn) - -@subheading DESCRIPTION: - -This system call creates the eventflag specified by @code{flgid}. -Specifically, a control block for the eventflag to be created is allocated -and the associated flag pattern is initialized using @code{iflgptn}. A -single eventflag handles one word's worth of bits of the processor in -question as a group. All operations are done in single word units. - -User eventflags have positive ID numbers, while system eventflags have -negative ID numbers. User tasks (tasks having positive task IDs) cannot -access system eventflags. An @code{E_OACV} error will result if a user -task issues a system call on a system eventflag, but error detection is -implementation dependent. - -Eventflags having ID numbers from -4 through 0 cannot be created. An -@code{E_ID} error will result if a value in this range is specified for -@code{flgid}. - -The system attribute part of @code{flgatr} may be specified as @code{TA_WSGL} -(Wait Single Task) or @code{TA_WMUL} (Wait Multiple Tasks) - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - -All memory is preallocated for @code{RTEMS ITRON} objects. Thus, no -dynamic memory allocation is performed by @code{cre_flg} and the -@code{E_NOMEM} error can not be returned. - -@c -@c del_flg -@c - -@page -@subsection del_flg - Delete Eventflag - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_flg( - ID flgid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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 - -@subheading DESCRIPTION: - -This system call deletes the eventflag specified by @code{flgid}. - -Issuing this system call causes memory used for the control block of the -associated eventflag to be released. After this system call is invoked, -another eventflag having the same ID number can be created. - -This system call will complete normally even if there are tasks waiting -for the eventflag. In that case, an @code{E_DLT} error will be returned -to each waiting task. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - -When an eventflag being waited for by more than one tasks is deleted, the -order of tasks on the ready queue after the WAIT state is cleared is -implementation dependent in the case of tasks having the same priority. - -@c -@c set_flg -@c - -@page -@subsection set_flg - Set Eventflag - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER set_flg( - ID flgid, - UINT setptn -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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: - -The @code{set_flg} system call sets the bits specified by @code{setptn} of the -one word eventflag specified by @code{flgid}. In other words, a logical -sum is taken for the values of the eventflag specified by @code{flgid} with the -value of @code{setptn}. - -If the eventflag value is changed by @code{set_flg} and the new eventflag -value satisfies the condition to release the WAIT state of the task which -issued @code{wai_flg} on the eventflag, the WAIT state of that task will -be released and the task will be put into RUN or READY state (or SUSPEND -state if the task was in WAIT-SUSPEND). - -Nothing will happen to the target eventflag if all bits of @code{setptn} -are specified as 0 with @code{set_flg}. No error will result in either -case. - -Multiple tasks can wait for a single eventflag if that eventflags has the -@code{TA_WMUL} attribute. This means that even eventflags can make queues -for tasks to wait on. When such eventflags are used, a single -@code{set_flg} call may result in the release of multiple waiting tasks. -In this case, the order of tasks on the ready queue after the WAIT state -is cleared is preserved for tasks having the same priority. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - -@c -@c clr_flg -@c - -@page -@subsection clr_flg - Clear Eventflag - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER clr_flg( - ID flgid, - UINT clrptn -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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: - -The @code{clr_flg} system call clears the bits of the one word eventflag -based on the corresponding zero bits of @code{clrptn}. In other words, a -logical product is taken for the values of the eventflag specified by -@code{flgid} with the value of @code{clrptn}. - -Issuing @code{clr_flg} never results in wait conditions being released on -a task waiting for the specified eventflag. In other words, dispatching -never occurs with @code{clr_flg}. - -Nothing will happen to the target eventflag if all bits of @code{clrptn} -are specified as 1 with @code{clr_flg}. No error will result. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - -@c -@c wai_flg -@c - -@page -@subsection wai_flg - Wait on Eventflag - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER wai_flg( - UINT *p_flgptn, - ID flgid, - UINT waiptn, - UINT wfmode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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}. The Eventflags bit-pattern will be returned with a pointer @code{p_flgptn}. - -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 (or TWF_ORW) | TWF_CLR(optional) -@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. - -The return parameter @code{flgptn} returns the value of the eventflag after the -wait state of a task has been released due to this system call. If -@code{TWF_CLR} was specified, the value before eventflag bits were cleared -is returned. The value returned by @code{flgptn} fulfills the wait -release conditions of this system call. - -An @code{E_PAR} parameter error will result if @code{waiptn} is 0. - -A task can not execute any of @code{wai_flg, twai_flg} or @code{pol_flg} -on an eventflag having the @code{TA_WSGL} attribute if another task is -already waiting for that eventflag. An @code{E_OBJ} error will be -returned to a task which executes @code{wai_flg} at a later time -regardless as to whether or not the task that executes @code{wai_flg} or -@code{twai_flg} later will be placed in a WAIT state (conditions for -releasing wait state be satisfied). An @code{E_OBJ} error will be -returned even to tasks which just execute @code{pol_flg}, again regardless -as to whether or not wait release conditions for that task were satisfied. - -On the other hand, multiple tasks can wait at the same time for the same -eventflag if that eventflag has the @code{TA_WMUL} attribute. This means -that event flags can make queues for tasks to wait on. When such -eventflags are used, a single @code{set_flg} call may release multiple -waiting tasks. - -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. - -@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.) - -@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. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - - -@c -@c pol_flg -@c - -@page -@subsection pol_flg - Wait for Eventflag (Polling) - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER pol_flg( - UINT *p_flgptn, - ID flgid, - UINT waiptn, - UINT wfmode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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{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. - -@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 @code{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 - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - - -@c -@c twai_flg -@c - -@page -@subsection twai_flg - Wait on Eventflag with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER twai_flg( - UINT *p_flgptn, - ID flgid, - UINT waiptn, - UINT wfmode, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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{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 @code{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 @code{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 -@code{tmout} indicates that an infinite timeout value be used, resulting in -exactly the same processing as @code{wai_flg}. - -@subheading NOTES: - -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; @code{pol_flg} and @code{wai_flg} should be implemented as macros -which call @code{twai_flg}. - -@c -@c ref_flg -@c - -@page -@subsection ref_flg - Reference Eventflag Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_flg( - T_RFLG *pk_rflg, - ID flgid ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@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: - -This system call refers to the state of the eventflag specified by -@code{flgid}, and returns its current flag pattern (@code{flgptn}), -waiting task information (@code{wtsk}), and its extended information -(@code{exinf}). - -Depending on the implementation, @code{wtsk} may be returned as the ID -(non-zero) of the task waiting for the eventflag. If there are multiple -tasks waiting for the eventflag (only when attribute is @code{TA_WMUL}), -the ID of the task at the head of the queue is returned. - -An @code{E_NOEXS} error will result if the eventflag specified to -@code{ref_flg} does not exist. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "@code{EN_}" status -codes will be returned. - -Although both @code{ref_flg} and @code{pol_flg} can be used to find an -eventflag's pattern (@code{flgptn}) without causing the issuing task to -wait, @code{ref_flg} simply reads the eventflag's pattern (@code{flgptn}) -while @code{pol_flg} functions is identical to @code{wai_flg} when wait -release conditions are satisfied (it clears the eventflag if -@code{TWF_CLR} is specified). - -Depending on the implementation, additional information besides -@code{wtsk} and @code{flgptn} (such as eventflag attributes, -@code{flgatr}) may also be referred. diff --git a/doc/itron3.0/fixedblock.t b/doc/itron3.0/fixedblock.t deleted file mode 100644 index 97270e2636..0000000000 --- a/doc/itron3.0/fixedblock.t +++ /dev/null @@ -1,389 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the fixed block -@c manager. -@c -@c $Id$ -@c - -@chapter Fixed Block Manager - -@section Introduction - -The fixed block manager provides functions for creating, deleting, getting, polling, getting with timeout, releasing, and referencing the fixed-sized memorypool. This manager is based on ITRON 3.0 standard. - -The services provided by the fixed block manager are: - -@itemize @bullet -@item @code{cre_mpf} - Create Fixed-Size Memorypool -@item @code{del_mpf} - Delete Fixed-Size Memorypool -@item @code{get_blf} - Get Fixed-Size Memory Block -@item @code{pget_blf} - Poll and Get Fixed-Size Memory Block -@item @code{tget_blf} - Get Fixed-Size Memory Block with Timeout -@item @code{rel_blf} - Release Fixed-Size Memory Block -@item @code{ref_mpf} - Reference Fixed-Size Memorypool Status -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the fixed block 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. - - -@c -@c cre_mpf -@c - -@page -@subsection cre_mpf - Create Fixed-Size Memorypool - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_mpf( - ID mpfid, - T_CMPF *pk_cmpf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for -memorypool cannot be allocated) - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_RSATR} - Reserved attribute (mpfatr was invalid or could not be used) - -@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (pk_cmpf is invalid or mpfsz and/or blfsz is -negative or invalid) - -@subheading DESCRIPTION: - -This system call creates a fixed-size memorypool having the ID number specified by mpfid. Specifically, a memory area of a size based on values of mpfcnt and blfsz is reserved for use as a memorypool. A control block for the memorypool being created is also allocated. The get_blf system call specifying the memorypool created by this call can be issued to allocate memory blocks of the size given by blfsz (in bytes). - -@subheading NOTES: - -The memory area required for creating memorypools and for allocating control blocks for each object is allocated while system initialization. Associated parameters are therefore specified at system configuration. - -@c -@c del_mpf -@c - -@page -@subsection del_mpf - Delete Fixed-Size Memorypool - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_mpf( - ID mpfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from a user task. This is implementation dependent.) - -@subheading DESCRIPTION: - -This system call deletes the fixed-size memorypool specified by mpfid. No check or error report is performed even if there are tasks using memory from the memorypool to be deleted. This system call completes normally even if some of the memory blocks are not returned. Issuing this system call causes memory used for the control block of the associated memorypool and the memory area making up the memorypool itself to be released. After this system call is invoked, another memorypool having the same ID number can be created. This system call will complete normally even if there are tasks waiting to get memory blocks from the memorypool. In that case, an E_DLT error will be returned to each waiting task. - -@subheading NOTES: - -When a memorypool being waited for by more than one tasks is deleted, the order of tasks on the ready queue after the WAIT state is cleared is implementation dependent in the case of tasks having the same priority. - - -@c -@c get_blf -@c - -@page -@subsection get_blf - Get Fixed-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER get_blf( - VP *p_blf, - ID mpfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) - -@subheading DESCRIPTION: - -A memory block is allocated from the fixed-size memorypool specified by mpfid. The start address of the memory block allocated is returned to blf. The size of the memory block allocated is specified by the blfsz parameter when the fixed-size memorypool was created. The allocated memory block is not cleared to zero. The contents of the allocated memory block are undefined. If the memory block cannot be obtained from the specified memorypool when get_blf is issued, the task issuing get_blf will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires. If the object being waited for is deleted (the specified memorypool is deleted while waiting), an E_DLT error will be returned. - -@subheading NOTES: - -NONE - - -@c -@c pget_blf -@c - -@page -@subsection pget_blf - Poll and Get Fixed-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =pget_blf( - VP *p_blf, - ID mpfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) - -@subheading DESCRIPTION: - -The pget_blf system call has the same function as get_blf except for the waiting feature. Pget_blf polls whether or not the task should wait if get_blf is executed. The meaning of parameters to pget_blf are the same with get_blf. The specific operations by pget_blf are as follows. - - - If there is a free memory block available, processing is the same as - get_blf: that is, the requested memory is allocated and the system call - completes normally. - - - If there is no free memory block, an E_TMOUT error is returned to - indicate polling failed and the system call finishes. Unlike get_blf, - the issuing task does not wait in this case. Also, the issuing task - does not get any memory. - -@subheading NOTES: - -NONE - - -@c -@c tget_blf -@c - -@page -@subsection tget_blf - Get Fixed-Size Memory Block with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tget_blf( - VP *p_blf, - ID mpfid, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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; implementation dependent for pget_blf and tget_blf(tmout=TMO_POL)) - -@subheading DESCRIPTION: - -The tget_blf system call has the same function as get_blf 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, E_TMOUT, will result and the system call will finish if the period specified by tmout elapses without conditions for releasing wait being satisfied (i.e. without free memory becoming available). - -@subheading NOTES: - -NONE - -@c -@c rel_blf -@c - -@page -@subsection rel_blf - Release Fixed-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rel_blf( - ID mpfid, - VP blf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mpfid does not exist) - -@code{E_OACV} - Object access violation (A mpfid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (blf is invalid or an attempt was made to return -the memory block to the wrong memorypool) - -@subheading DESCRIPTION: - -This system call releases the memory block specified by blf and returns it to the fixed-size memorypool specified by mpfid. Executing rel_blf allows memory to be allocated to the next task waiting for memory allocation from the memorypool given by mpfid, thus releasing that task from its WAIT state. - -@subheading NOTES: - -The fixed-size memorypool to which the memory block is returned must be the same memorypool from which it was originally allocated. An E_PAR error will result if an attempt is made to return a memory block to another memorypool than that from which it was originally allocated. - -@c -@c ref_mpf -@c - -@page -@subsection ref_mpf - Reference Fixed-Size Memorypool Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_mpf( - T_RMPF *pk_rmpf, - ID mpfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mpfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist \(the memorypool specified by mpfid does -not exist.) - -@code{E_OACV} - Object access violation (A mpfid 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) - -@subheading DESCRIPTION: - -This system call refers to the state of the fixed-size memorypool specified by mpfid, and returns the current number of free blocks (frbcnt), information of a task waiting to be allocated memory (wtsk), and its extended information (exinf). Wtsk indicates whether or not there is a task waiting to be allocated memory from the fixed-size memorypool specified. 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. - -@subheading NOTES: - -While the frsz return parameter of ref_mpl returns the total size of free memory, the frbcnt return parameter of ref_mpf returns the number of free blocks. - -Depending on the implementation, additional information besides wtsk and frbcnt (such as memorypool attributes, mpfatr) may also be referred. - diff --git a/doc/itron3.0/gen_all b/doc/itron3.0/gen_all deleted file mode 100644 index 6e4e66893f..0000000000 --- a/doc/itron3.0/gen_all +++ /dev/null @@ -1,4 +0,0 @@ -for i in config eventflags fixedblock interrupt mailbox memorypool msgbuffer network rendezvous task tasksync time -do - sh ./gen_section $i | tr -d "\r" >${i}.t -done diff --git a/doc/itron3.0/gen_section b/doc/itron3.0/gen_section deleted file mode 100644 index cdc1c80f2c..0000000000 --- a/doc/itron3.0/gen_section +++ /dev/null @@ -1,191 +0,0 @@ -# -# This shell script generates the starting template for a manager chapter. -# - - -# Set this based on which chapter you want to generate a template for. -chapter=$1 - -case ${chapter} in - task) - CHAPTER_CAPS="Task" - CHAPTER_LOWER="task" - ROUTINES=" cre_tsk del_tsk sta_tsk ext_tsk exd_tsk ter_tsk \ - dis_dsp ena_dsp chg_pri rot_rdq rel_wai get_tid ref_tsk" - ;; - - tasksync) - CHAPTER_CAPS="Task-Dependent Synchronization" - CHAPTER_LOWER="task-dependent synchronization" - ROUTINES=" sus_tsk rsm_tsk frsm_tsk \ - slp_tsk tslp_tsk wup_tsk can_wup" - ;; - - semaphore) - CHAPTER_CAPS="Semaphore" - CHAPTER_LOWER="semaphore" - ROUTINES="cre_sem del_sem sig_sem wai_sem preq_sem twai_sem ref_sem " - ;; - - eventflags) - CHAPTER_CAPS="Eventflags" - CHAPTER_LOWER="eventflags" - ROUTINES=" cre_flg del_flg set_flg clr_flg wai_flg pol_flg \ - twai_flg ref_flg " - ;; - - mailbox) - CHAPTER_CAPS="Mailbox" - CHAPTER_LOWER="mailbox" - ROUTINES="cre_mbx del_mbx snd_msg rcv_msg prcv_msg trcv_msg ref_mbx" - ;; - - msgbuffer) - CHAPTER_CAPS="Message Buffer" - CHAPTER_LOWER="message buffer" - ROUTINES=" cre_mbf del_mbf snd_mbf psnd_mbf tsnd_mbf rcv_mbf prcv_mbf \ - trcv_mbf ref_mbf " - ;; - - rendezvous) - CHAPTER_CAPS="Rendezvous" - CHAPTER_LOWER="rendezvous" - ROUTINES=" cre_por del_por cal_por pcal_por tcal_por acp_por pacp_por \ - tacp_por fwd_por rpl_rdv ref_por" - ;; - - interrupt) - CHAPTER_CAPS="Interrupt" - CHAPTER_LOWER="interrupt" - ROUTINES=" def_int ret_int ret_wup loc_cpu unl_cpu dis_int ena_int - chg_iXX ref_iXX" - ;; - - memorypool) - CHAPTER_CAPS="Memory Pool" - CHAPTER_LOWER="memory pool" - ROUTINES=" cre_mpl del_mpl get_blk pget_blk tget_blk rel_blk ref_mpl" - ;; - - fixedblock) - CHAPTER_CAPS="Fixed Block" - CHAPTER_LOWER="fixed block" - ROUTINES=" cre_mpf del_mpf get_blf pget_blf tget_blf rel_blf ref_mpf" - ;; - - - time) - CHAPTER_CAPS="Time" - CHAPTER_LOWER="time" - ROUTINES=" get_tim set_tim dly_tsk \ - def_cyc act_cyc ref_cyc \ - def_alm ref_alm ret_tmr" - ;; - - config) - CHAPTER_CAPS="System" - CHAPTER_LOWER="system" - ROUTINES=" get_ver ref_sys ref_cfg def_svc def_exc" - ;; - - network) - CHAPTER_CAPS="Network Support" - CHAPTER_LOWER="network support" - ROUTINES=" nrea_dat nwri_dat nget_nod nget_ver" - ;; - psxtimer) - CHAPTER_CAPS="Timer" - CHAPTER_LOWER="timer" - ROUTINES="timer_create timer_delete timer_settime timer_gettime timer_getoverrun" - ;; - *) - echo "Unknown chapter name" - exit 1 - ;; -esac - -if [ "x${CHAPTER_CAPS}" = "x" -o "x${CHAPTER_LOWER}" = "x" \ - -o "x${ROUTINES}" = "x" ] ; then - echo "initialization problem" - exit 1 -fi - -echo "@c" -echo "@c This is the chapter from the RTEMS ITRON User's Guide that" -echo "@c documents the services provided by the ${CHAPTER_LOWER}" -echo "@c manager." -echo "@c" -echo "@c \$Id\$" -echo "@c" -echo "" -echo "@chapter ${CHAPTER_CAPS}" Manager -echo "" -echo "@section Introduction" -echo "" -echo "The " -echo "${CHAPTER_LOWER} manager is ..." -echo "" -echo "The services provided by the ${CHAPTER_LOWER} manager are:" -echo "" -echo "@itemize @bullet" - -for routine in ${ROUTINES} -do - description=`grep " ${routine} " ../../itron_spec/itron3-1.txt | grep "]" | cut -d']' -f2 ` - description=`echo ${description}` - echo "@item @code{${routine}} - ${description}" -done -echo "@end itemize" - -echo "" -echo "@section Background" -echo "" -echo "@section Operations" -echo "" -echo "@section System Calls" -echo "" -echo "This section details the ${CHAPTER_LOWER} manager's services." -echo "A subsection is dedicated to each of this manager's services" -echo "and describes the calling sequence, related constants, usage," -echo "and status codes." -echo "" - -for routine in ${ROUTINES} -do - description=`grep ${routine} ../../itron_spec/itron3-1.txt | grep "]" | cut -d']' -f2` - description=`echo -n ${description}` - echo "" - echo "@c" - echo "@c ${routine}" - echo "@c" - echo "" - echo "@page" - echo "@subsection ${routine} - " ${description} - echo "" - echo "@subheading CALLING SEQUENCE:" - echo "" - echo "@ifset is-C" - echo "@example" - proto=`grep "${routine} (" ../../itron_spec/itron3-6.txt | sed -e 's/ercd = //'` # | sed -e 's/ \\(/(/'` - - echo `echo -n ${proto} | cut -d'(' -f1`"(" - echo ${proto} | cut -d'(' -f2 | sed -e 's/ .;//' - echo ");" - # echo "int ${routine}(" - # echo ");" - echo "@end example" - echo "@end ifset" - echo "" - echo "@ifset is-Ada" - echo "@end ifset" - echo "" - echo "@subheading STATUS CODES:" - echo "" - echo "@code{EXXX} - " - echo "" - echo "@subheading DESCRIPTION:" - echo "" - echo "@subheading NOTES:" - echo "" -done - diff --git a/doc/itron3.0/gen_status_shell b/doc/itron3.0/gen_status_shell deleted file mode 100644 index 1f3f8e4c47..0000000000 --- a/doc/itron3.0/gen_status_shell +++ /dev/null @@ -1,230 +0,0 @@ -# -# This shell script generates the starting template for a manager chapter. -# - -FILES="task tasksync semaphore eventflags mailbox msgbuffer rendezvous interrupt memorypool fixedblock time config network" - - -cat <<EOF -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the task -@c manager. -@c -@c $Id$ -@c - -@chapter ITRON Implementation Status - -@section Introduction - -This chapter describes the status of the implementation of each -manager in the RTEMS implementataion of the uITRON 3.0 API. The -status of each manager is presented in terms of documentation and -status relative to the extended level (level 'E') of the uITRON 3.0 -API specification. The extended level of the specification is -the level at which dynamic object creation, deletion, and -reference services are available. This level is more akin to the other -APIs supported by RTEMS. This purpose of this chapter is -to make it clear what is required to bring the RTEMS -uITRON API implementation into compliance with the -specification. The following description of the specification -levels is taken from the uITRON 3.0 API specification. - - -uITRON 3.0 specification is divided into fewer system call levels than was the -previous uITRON 2.0 specification. There are now just three levels: Level R -(Required), Level S (Standard) and Level E (Extended). In addition to these -three levels, there is also Level C for CPU-dependent system calls. -In addition, the uITRON 3.0 API, defines the network level ('N') which -represents system calls that support the connection function - -@itemize @bullet -@item [level R] (Required) -The functions in this level are mandatory for all implementations of -uITRON 3.0 specification. This includes basic functions for achieving -a real-time, multitasking OS. These functions can be implemented even -without a hardware timer. This level corresponds to Levels 1 and 2 -of uITRON 2.0 specification. - -@item [level S] (Standard) -This includes basic functions for achieving a real-time, multitasking -OS. This level corresponds to Levels 3 and 4 of uITRON 2.0 -specification. - -@item [level E] (Extended) -This includes additional and extended functions. This corresponds to -functions not included in uITRON 2.0 specification (functions of -ITRON2 specification). Specifically, this level includes object -creation and deletion functions, rendezvous functions, memorypools -and the timer handler. - -@item [level C] (CPU dependent) -This level provides implementation-dependent functions required due to -the CPU or hardware configuration. - -@end itemize - -The support level of the connection function is indicated by appending an 'N' -to the end of the level. For example, connectivity supported at [level S] -would be referred to as [level SN]. The support level for functions which -can only send requests for operations on other nodes but offer no system call -processing on the issuing node itself are indicated by the lower case letter -'s' or 'e'. - - -EOF - - -for chapter in $FILES -do - case ${chapter} in - task) - CHAPTER_CAPS="Task" - CHAPTER_LOWER="task" - ROUTINES=" cre_tsk del_tsk sta_tsk ext_tsk exd_tsk ter_tsk \ - dis_dsp ena_dsp chg_pri rot_rdq rel_wai get_tid ref_tsk" - ;; - - tasksync) - CHAPTER_CAPS="Task-Dependent Synchronization" - CHAPTER_LOWER="task-dependent synchronization" - ROUTINES=" sus_tsk rsm_tsk frsm_tsk \ - slp_tsk tslp_tsk wup_tsk can_wup" - ;; - - semaphore) - CHAPTER_CAPS="Semaphore" - CHAPTER_LOWER="semaphore" - ROUTINES="cre_sem del_sem sig_sem wai_sem preq_sem twai_sem ref_sem " - ;; - - eventflags) - CHAPTER_CAPS="Eventflags" - CHAPTER_LOWER="eventflags" - ROUTINES=" cre_flg del_flg set_flg clr_flg wai_flg pol_flg \ - twai_flg ref_flg " - ;; - - mailbox) - CHAPTER_CAPS="Mailbox" - CHAPTER_LOWER="mailbox" - ROUTINES="cre_mbx del_mbx snd_msg rcv_msg prcv_msg trcv_msg ref_mbx" - ;; - - msgbuffer) - CHAPTER_CAPS="Message Buffer" - CHAPTER_LOWER="message buffer" - ROUTINES=" cre_mbf del_mbf snd_mbf psnd_mbf tsnd_mbf rcv_mbf prcv_mbf \ - trcv_mbf ref_mbf " - ;; - - rendezvous) - CHAPTER_CAPS="Rendezvous" - CHAPTER_LOWER="rendezvous" - ROUTINES=" cre_por del_por cal_por pcal_por tcal_por acp_por pacp_por \ - tacp_por fwd_por rpl_rdv ref_por" - ;; - - interrupt) - CHAPTER_CAPS="Interrupt" - CHAPTER_LOWER="interrupt" - ROUTINES=" def_int ret_int ret_wup loc_cpu unl_cpu dis_int ena_int - chg_iXX ref_iXX" - ;; - - memorypool) - CHAPTER_CAPS="Memory Pool" - CHAPTER_LOWER="memory pool" - ROUTINES=" cre_mpl del_mpl get_blk pget_blk tget_blk rel_blk ref_mpl" - ;; - - fixedblock) - CHAPTER_CAPS="Fixed Block" - CHAPTER_LOWER="fixed block" - ROUTINES=" cre_mpf del_mpf get_blf pget_blf tget_blf rel_blf ref_mpf" - ;; - - time) - CHAPTER_CAPS="Time" - CHAPTER_LOWER="time" - ROUTINES=" get_tim set_tim dly_tsk \ - def_cyc act_cyc ref_cyc \ - def_alm ref_alm ret_tmr" - ;; - - config) - CHAPTER_CAPS="System" - CHAPTER_LOWER="system" - ROUTINES=" get_ver ref_sys ref_cfg def_svc def_exc" - ;; - - network) - CHAPTER_CAPS="Network Support" - CHAPTER_LOWER="network support" - ROUTINES=" nrea_dat nwri_dat nget_nod nget_ver" - ;; - - *) - echo "Unknown chapter name" - exit 1 - ;; - esac - - echo "@c" - echo "@c ${CHAPTER_CAPS}" - echo "@c" - echo - echo "@section ${CHAPTER_CAPS} Status" -cat <<EOF - -@itemize @bullet - -@item Implementation -@itemize @bullet -EOF - - for routine in ${ROUTINES} - do - echo "@item ${routine} - Stub, Needs to be Fleshed Out" - done -cat <<EOF -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@end itemize - -@item Documentation -@itemize @bullet -@item Shell, Needs to be Fleshed Out -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -EOF -done diff --git a/doc/itron3.0/interrupt.t b/doc/itron3.0/interrupt.t deleted file mode 100644 index e93e6bc231..0000000000 --- a/doc/itron3.0/interrupt.t +++ /dev/null @@ -1,306 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the interrupt -@c manager. -@c -@c $Id$ -@c - -@chapter Interrupt Manager - -@section Introduction - -The -interrupt manager is ... - -The services provided by the interrupt manager are: - -@itemize @bullet -@item @code{def_int} - Define Interrupt Handler -@item @code{ret_int} - Return from Interrupt Handler -@item @code{ret_wup} - Return and Wakeup Task -@item @code{loc_cpu} - Lock CPU -@item @code{unl_cpu} - Unlock CPU -@item @code{dis_int} - Disable Interrupt -@item @code{ena_int} - Enable Interrupt -@item @code{chg_iXX} - Change Interrupt Mask(Level or Priority) -@item @code{ref_iXX} - Reference Interrupt Mask(Level or Priority) -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the interrupt 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. - - -@c -@c def_int -@c - -@page -@subsection def_int - Define Interrupt Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER def_int( - UINT dintno, - T_DINT *pk_dint -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ret_int -@c - -@page -@subsection ret_int - Return from Interrupt Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void ret_int( - -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ret_wup -@c - -@page -@subsection ret_wup - Return and Wakeup Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void ret_wup( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c loc_cpu -@c - -@page -@subsection loc_cpu - Lock CPU - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER loc_cpu( - -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c unl_cpu -@c - -@page -@subsection unl_cpu - Unlock CPU - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER unl_cpu( - -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c dis_int -@c - -@page -@subsection dis_int - Disable Interrupt - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER dis_int( - UINT eintno -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ena_int -@c - -@page -@subsection ena_int - Enable Interrupt - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ena_int( - UINT eintno -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c chg_iXX -@c - -@page -@subsection chg_iXX - Change Interrupt Mask(Level or Priority) - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER chg_iXX( - UINT iXXXX -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_iXX -@c - -@page -@subsection ref_iXX - Reference Interrupt Mask(Level or Priority) - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_iXX( - UINT *p_iXXXX -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/itron3.0/itron.texi b/doc/itron3.0/itron.texi deleted file mode 100644 index 4ef6f59cf7..0000000000 --- a/doc/itron3.0/itron.texi +++ /dev/null @@ -1,144 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename itron.info -@setcontentsaftertitlepage -@syncodeindex vr fn -@synindex ky cp -@paragraphindent 0 -@c %**end of header - -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@c -@c Master file for the RTEMS ITRON 3.0 API User's Guide -@c - -@c Joel's Questions -@c -@c 1. Why does paragraphindent only impact makeinfo? -@c 2. Why does paragraphindent show up in HTML? -@c - -@include version.texi -@include common/setup.texi -@include common/rtems.texi - -@ifset use-ascii -@dircategory RTEMS On-Line Manual -@direntry -* RTEMS ITRON 3.0 API User's Guide: (itron). - ITRON Guide -@end direntry -@end ifset - -@c variable substitution info: -@c -@c Note: At the moment there is not an Ada interface to ITRON. -@set is-C -@clear is-Ada -@set LANGUAGE C -@set STRUCTURE structure -@set ROUTINE function -@set OR | -@set RPREFIX RTEMS_ -@set DIRPREFIX rtems_ -@c the language is @value{LANGUAGE} -@c NOTE: don't use underscore in the name -@c - -@c -@c Title Page Stuff -@c - -@c -@c I don't really like having a short title page. --joel -@c -@c @shorttitlepage RTEMS ITRON 3.0 API User's Guide - -@setchapternewpage odd -@settitle RTEMS ITRON 3.0 API User's Guide -@titlepage -@finalout - -@title RTEMS ITRON 3.0 User's Guide -@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION} -@sp 1 -@subtitle @value{UPDATED} -@author On-Line Applications Research Corporation -@page -@include common/cpright.texi -@end titlepage - -@c This prevents a black box from being printed on "overflow" lines. -@c The alternative is to rework a sentence to avoid this problem. - -@contents - -@include preface.texi -@include task.texi -@include tasksync.texi -@include semaphore.texi -@include eventflags.texi -@include mailbox.texi -@include msgbuffer.texi -@include rendezvous.texi -@include interrupt.texi -@include memorypool.texi -@include fixedblock.texi -@include time.texi -@include config.texi -@include network.texi -@include status.texi -@ifinfo -@node Top, , (dir), (dir) -@top itron - -This is the online version of the RTEMS ITRON 3.0 API User's Guide. - -@menu -* Preface:: -* Task Manager:: -* Task-Dependent Synchronization Manager:: -* Semaphore Manager:: -* Eventflags Manager:: -* Mailbox Manager:: -* Message Buffer Manager:: -* Rendezvous Manager:: -* Interrupt Manager:: -* Memory Pool Manager:: -* Fixed Block Manager:: -* Time Manager:: -* System Manager:: -* Network Support Manager:: -* ITRON Implementation Status:: -* Command and Variable Index:: -* Concept Index:: -@end menu - -@end ifinfo -@c -@c -@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here -@c - -@node Command and Variable Index, Concept Index, , Top -@unnumbered Command and Variable Index - -There are currently no Command and Variable Index entries. - -@c @printindex fn - -@node Concept Index, , Command and Variable Index, Top -@unnumbered Concept Index - -There are currently no Concept Index entries. -@c @printindex cp - -@bye - diff --git a/doc/itron3.0/mailbox.t b/doc/itron3.0/mailbox.t deleted file mode 100644 index 34746c743a..0000000000 --- a/doc/itron3.0/mailbox.t +++ /dev/null @@ -1,338 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the mailbox -@c manager. -@c -@c $Id$ -@c - - -@chapter Mailbox Manager - -@section Introduction - -The -mailbox manager is basically a linked list, hidden by the super core message queue and consists of a control block, a private structure. The control block comprises of the create mailbox structure, the message structure and the reference mailbox structure. - -The services provided by the mailbox manager are: - -@itemize @bullet -@item @code{cre_mbx} - Create Mailbox -@item @code{del_mbx} - Delete Mailbox -@item @code{snd_msg} - Send Message to Mailbox -@item @code{rcv_msg} - Receive Message from Mailbox -@item @code{prcv_msg} - Poll and Receive Message from Mailbox -@item @code{trcv_msg} - Receive Message from Mailbox with Timeout -@item @code{ref_mbx} - Reference Mailbox Status -@end itemize - - -@section Background - -@section Operations - -@section System Calls - -This section details the mailbox 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. - - -@c -@c cre_mbx -@c - -@page - -@subsection cre_mbx - Create Mailbox - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_mbx( - ID mbxid, - T_CMBX *pk_cmbx -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_NOMEM} - Insufficient memory@* -@code{E_ID} - Invalid ID number@* -@code{E_RSATR} - Reserved attribute@* -@code{E_OBJ} - Invalid object state@* -@code{E_OACV} - Object access violation@* -@code{E_PAR} - Parameter error - - -@subheading DESCRIPTION: - -Allocated a control area/buffer space for mailbox with some ID. - -@example - User area: +ve ids - System area: -ve ids -@end example - -User may specify if its FIFO or priority level queue. -Assumes shared memory b/w communicating processes. -Initializes core message queue for this mbox. - -@subheading NOTES: - -NONE - - -@c -@c del_mbx -@c - -@page - -@subsection del_mbx - Delete Mailbox - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_mbx( - ID mbxid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation - -@subheading DESCRIPTION: - -Specified by the ID, cleans up all data structures and control blocks. - -@subheading NOTES: - -NONE - - -@c -@c snd_msg -@c - -@page - -@subsection snd_msg - Send Message to Mailbox - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER snd_msg( - ID mbxid, - T_MSG *pk_msg -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation@* -@code{E_QOVR} - Queueing or nesting overflow - -@subheading DESCRIPTION: - -Sends the address of message to mbox having a given id, any waiting tasks (blocked tasks) will be woken up. It supports non-blocking send. - -@subheading NOTES: - -NONE - - -@c -@c rcv_msg -@c - -@page - -@subsection rcv_msg - Receive Message from Mailbox - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rcv_msg( - T_MSG **ppk_msg, - ID mbxid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation@* -@code{E_PAR} - Parameter error@* -@code{E_DLT} - The object being waited for was deleted@* -@code{E_RLWAI} - WAIT state was forcibly released@* -@code{E_CTX} - Context error - -@subheading DESCRIPTION: - -If there is no message then receiver blocks, if not empty then it takes the first message of the queue. - -@subheading NOTES: - -NONE - - -@c -@c prcv_msg -@c - -@page - -@subsection prcv_msg - Poll and Receive Message from Mailbox - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER prcv_msg( - T_MSG **ppk_msg, - ID mbxid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation@* -@code{E_PAR} - Parameter error@* -@code{E_DLT} - The object being waited for was deleted@* -@code{E_RLWAI} - WAIT state was forcibly released@* -@code{E_CTX} - Context error@* - -@subheading DESCRIPTION: - -Poll and receive message from mailbox. - -@subheading NOTES: - -NONE - - -@c -@c trcv_msg -@c - -@page - -@subsection trcv_msg - Receive Message from Mailbox with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER trcv_msg( - T_MSG **ppk_msg, - ID mbxid, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation@* -@code{E_PAR} - Parameter error@* -@code{E_DLT} - The object being waited for was deleted@* -@code{E_RLWAI} - WAIT state was forcibly released@* -@code{E_CTX} - Context error - -@subheading DESCRIPTION: - -Blocking receive with a maximum timeout. - -@subheading NOTES: - -NONE - - -@c -@c ref_mbx -@c - -@page - -@subsection ref_mbx - Reference Mailbox Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_mbx( - T_RMBX *pk_rmbx, - ID mbxid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal completion@* -@code{E_ID} - Invalid ID number@* -@code{E_NOEXS} - Object does not exist@* -@code{E_OACV} - Object access violation@* -@code{E_PAR} - Parameter error - -@subheading DESCRIPTION: - -Supports non-blocking receive. If there are no messages, it returns -1. Also returns id of the next process waiting on a message. - -@subheading NOTES: - -NONE - - diff --git a/doc/itron3.0/memorypool.t b/doc/itron3.0/memorypool.t deleted file mode 100644 index 013c3c30eb..0000000000 --- a/doc/itron3.0/memorypool.t +++ /dev/null @@ -1,401 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the memory pool -@c manager. -@c -@c $Id$ -@c - -@chapter Memory Pool Manager - -@section Introduction - -The -memory pool manager is ... - -The services provided by the memory pool manager are: - -@itemize @bullet -@item @code{cre_mpl} - Create Variable-Size Memorypool -@item @code{del_mpl} - Delete Variable-Size Memorypool -@item @code{get_blk} - Get Variable-Size Memory Block -@item @code{pget_blk} - Poll and Get Variable-Size Memory Block -@item @code{tget_blk} - Get Variable-Size Memory Block with Timeout -@item @code{rel_blk} - Release Variable-Size Memory Block -@item @code{ref_mpl} - Reference Variable-Size Memorypool Status -@end itemize - -@section Background - -Memorypool management functions manage memorypools and allocate memory blocks. -There are two types of memorypool: fixed-size memorypools and variable-size -memorypools. Both are considered separate objects and require different -system calls for manipulation. While the size of memory blocks allocated -from fixed-size memorypools are all fixed, blocks of any size may be -specified when allocating memory blocks from variable-size memorypools. - -@section Operations - -@section System Calls - -This section details the memory pool 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. - - -@c -@c cre_mpl -@c - -@page -@subsection cre_mpl - Create Variable-Size Memorypool - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_mpl( - ID mplid, - T_CMPL *pk_cmpl -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_NOMEM} - Insufficient memory (Memory for control block and/or for -memorypool cannot be allocated) - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_RSATR} - Reserved attribute (mplatr was invalid or could not be used) - -@code{E_OBJ} - Invalid object state (a memorypool of the same ID already exists) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (pk_cmpl is invalid or mplsz is negative or -invalid) - -@subheading DESCRIPTION: - -The cre_mpl directive creates a variable-size memorypool having the ID number specified by mplid. Specifically, a memory area of the size determined by mplsz is allocated for use as a memorypool. A control block for the memorypool being created is also allocated. User memorypools have positive ID numbers, while system memorypools have negative ID numbers. User tasks (tasks having positive task IDs) cannot access system memorypools (memorypools having negative ID numbers). - -@subheading NOTES: - -The memory required for creating memorypools and for allocating control blocks for each object is reserved while system initialization. Associated parameters are therefore specified at system configuration. - -@c -@c del_mpl -@c - -@page -@subsection del_mpl - Delete Variable-Size Memorypool - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_mpl( - ID mplid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) - -@subheading DESCRIPTION: - -This system call deletes the variable-size memorypool specified by mplid. No check or error report is performed even if there are tasks using memory from the memorypool to be deleted. This system call completes normally even if some of the memory blocks are not returned. Issuing this system call causes memory used for the control block of the associated memorypool and the memory area making up the memorypool itself to be released. After this system call is invoked, another memorypool having the same ID number can be created. - -@subheading NOTES: - -When a memorypool being waited for by more than one tasks is deleted, the order of tasks on the ready queue after the WAIT state is cleared is implementation dependent in the case of tasks having the same priority. - -@c -@c get_blk -@c - -@page -@subsection get_blk - Get Variable-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER get_blk( - VP *p_blk, - ID mplid, - INT blksz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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 - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for -pget_blk and tget_blk(tmout=TMO_POL)) - -@subheading DESCRIPTION: - -A memory block of the size in bytes given by blksz is allocated from the variable-size memorypool specified by mplid. The start address of the memory block allocated is returned in blk. The allocated memory block is not cleared to zero. The contents of the memory block allocated are undefined. If the memory block cannot be obtained from the specified memorypool when get_blk is issued, the task issuing get_blk will be placed on the memory allocation queue of the specified memorypool, and wait until it can get the memory it requires. - -The order in which tasks wait on the queue when waiting to be allocated memory blocks is according to either FIFO or task priority. The specification whereby tasks wait according to task priority is considered an extended function [level X] for which compatibility is not guaranteed. Furthermore, when tasks form a memory allocation queue, it is implementation dependent whether priority is given to tasks requesting the smaller size of memory or those at the head of the queue. - -@subheading NOTES: - -Pget_blk and get_blk represent the same processing as specifying certain values (TMO_POL or TMO_FEVR) to tget_blk for tmout. It is allowed that only tget_blk is implemented in the kernel and that pget_blk and get_blk are implemented as macros which call tget_blk. - -@c -@c pget_blk -@c - -@page -@subsection pget_blk - Poll and Get Variable-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =pget_blk( - VP *p_blk, - ID mplid, - INT blksz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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 - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for -pget_blk and tget_blk(tmout=TMO_POL)) - -@subheading DESCRIPTION: - -The pget_blk system call has the same function as get_blk except for the waiting feature. Pget_blk polls whether or not the task should wait if get_blk is executed. The meaning of parameters to pget_blk are the same with get_blk. The specific operations by pget_blk are as follows. - - - If there is enough free memory to get the memory block of specified size - immediately, processing is the same as get_blk: that is, the - requested memory is allocated and the system call completes normally. - - - If there is not enough free memory, an E_TMOUT error is returned to - indicate polling failed and the system call finishes. Unlike get_blk, - the issuing task does not wait in this case. Also, the issuing task - does not get any memory. - -@subheading NOTES: - -NONE - -@c -@c tget_blk -@c - -@page -@subsection tget_blk - Get Variable-Size Memory Block with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tget_blk( - VP *p_blk, - ID mplid, - INT blksz, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less, blksz is negative or invalid) - -@code{E_DLT} - The object being waited for was deleted (the specified memorypool -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 - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for -pget_blk and tget_blk(tmout=TMO_POL)) - - -@subheading DESCRIPTION: - -The tget_blk system call has the same function as get_blk 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, E_TMOUT, will result and the system call will finish if the period specified by tmout elapses without conditions for releasing wait being satisfied (i.e. without sufficient free memory becoming available). - -@subheading NOTES: - -NONE - -@c -@c rel_blk -@c - -@page -@subsection rel_blk - Release Variable-Size Memory Block - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rel_blk( - ID mplid, - VP blk -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from - a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (blk is invalid or an attempt was made to return -the memory block to the wrong memorypool) - -@subheading DESCRIPTION: - -This system call releases the memory block specified by blk and returns it to the variable-size memorypool specified by mplid. Executing rel_blk allows memory to be allocated to the next task waiting for memory allocation from the memorypool given by mplid, thus releasing that task from its WAIT state. The variable-size memorypool to which the memory block is returned must be the same memorypool from which it was originally allocated. An E_PAR error will result if an attempt is made to return a memory block to another memorypool than that from which it was originally allocated. - -@subheading NOTES: - -When memory is returned to a variable-size memorypool for which more than one task is waiting, multiple tasks may be released from waiting at the same time depending on the number of bytes of memory. The order of tasks on the ready queue among tasks having the same priority after being released from waiting for memory is implementation dependent. - -@c -@c ref_mpl -@c - -@page -@subsection ref_mpl - Reference Variable-Size Memorypool Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_mpl( - T_RMPL *pk_rmpl, - ID mplid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mplid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the memorypool specified by mplid does not exist) - -@code{E_OACV} - Object access violation (A mplid less than -4 was specified from -a user task. This is implementation dependent.) Note: User tasks can issue ref_mpl in order to reference memorypools of mplid = TMPL_OS = -4. Whether or not memorypools of mplid = -3 or -2 may be specified to ref_mpl by user tasks is implementation dependent. - -@code{E_PAR} - Parameter error (the packet address for the return parameters -could not be used) - -@subheading DESCRIPTION: - -This system call refers to the state of the variable-size memorypool specified by mplid, and returns the total free memory size currently available (frsz), the maximum continuous memory size of readily available free memory (maxsz), information of a task waiting to be allocated memory (wtsk), and its extended information (exinf). Wtsk indicates, whether or not there is a task waiting to be allocated memory from the variable-size memorypool specified. 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. - -@subheading NOTES: - -In some implementations, memorypools having mplid = -3 or -2 may be referred with ref_mpl as memorypools used by implementation-dependent parts of the OS (such as those used for the stack only). This system call can provide more detailed information regarding remaining memory if the usage of memorypools having mplid = -3 or -2 is more clearly defined. Whether or not this feature is used and any details regarding information provided are implementation dependent. - diff --git a/doc/itron3.0/msgbuffer.t b/doc/itron3.0/msgbuffer.t deleted file mode 100644 index fa0704191c..0000000000 --- a/doc/itron3.0/msgbuffer.t +++ /dev/null @@ -1,826 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the message buffer -@c manager. -@c -@c $Id$ -@c - -@chapter Message Buffer Manager - -@section Introduction - -The message buffer manager provides functions to create, delete, and -control of message buffers. This manager is based on the ITRON 3.0 -standard. - -The services provided by the message buffer manager are: - -@itemize @bullet -@item @code{cre_mbf} - Create MessageBuffer -@item @code{del_mbf} - Delete MessageBuffer -@item @code{snd_mbf} - Send Message to MessageBuffer -@item @code{psnd_mbf} - Poll and Send Message to MessageBuffer -@item @code{tsnd_mbf} - Send Message to MessageBuffer with Timeout -@item @code{rcv_mbf} - Receive Message from MessageBuffer -@item @code{prcv_mbf} - Poll and Receive Message from MessageBuffer -@item @code{trcv_mbf} - Receive Message from MessageBuffer with Timeout -@item @code{ref_mbf} - Reference MessageBuffer Status -@end itemize - -@section Background - -@subsection T_CMBF Structure - -The T_CMBF structure is used to define the characteristics of a message -buffer and passed as an argument to the @code{cre_mbf} routine. This -structure is defined as: - -@example -@group - -typedef struct t_cmbf @{ - VP exinf; /* extended information */ - ATR mbfatr; /* message buffer attributes */ - INT bufsz; /* buffer size (in bytes) */ - INT maxmsz; /* maximum message size (in bytes) */ - /* (CPU and/or implementation-dependent information may also be - included) */ -@} T_CMBF; - -@end group -@end example - -where the meaning of each field is: - -@table @b -@item exinf -is for any extended information that the implementation may define. This -implementation does not use this field. - -@item mbfatr -is the attributes for the message buffer. The only attributes which can -be specified is whether tasks wait in FIFO (@code{TA_TFIFO}) or priority -(@code{TA_TPRI}) order. - -@item bufsz -is the size of the message buffer. Since some control data are needed to -manage each messages in the message buffer, @code{bufsz} is usually -larger than the total of all message sizes in this buffer. - -@item maxmsz -is the maximum message size. - -@end table - -@subsection T_RMBF Structure - -The T_RMBF structure is filled in by the @code{ref_mbf} routine with -status and state information of the message buffer. The structure is -defined as follows: - -@example -@group - -typedef struct t_rmbf @{ - VP exinf; /* extended information */ - BOOL_ID wtsk; /* waiting task information */ - BOOL_ID stsk; /* sending task information */ - INT msgsz; /* message size (in bytes) */ - INT frbufsz; /* free buffer size (in bytes) */ - /* (CPU and/or implementation-dependent information is returned) */ -@} T_RMBF; - -@end group -@end example - -@table @b - -@item exinf -is for any extended information that the implementation may define. -This implementation does not use this field. - -@item wtsk -is TRUE when there is one or more tasks waiting on this message buffer -to send message. It is FALSE when there is no waiting task. The meaning -of this field is allowed to vary between ITRON implementations. It may -have the ID of a waiting task, the number of tasks waiting, or a boolean -indication that one or more tasks are waiting. - -@item stsk -is TRUE when there is one or more tasks waiting on this message buffer -to receive message. It is FALSE when there is no waiting task. The meaning -of this field is allowed to vary between ITRON implementations. It may -have the ID of a waiting task, the number of tasks waiting, or a boolean -indication that one or more tasks are waiting. - -@item msgsz -is the size of the message that is at the head of the message buffer. If -there is no message on the message queue, @code{msgsz} will be returned -as FALSE = 0. - -@item frbufsz -is the amount of free memory in the message buffer. - -@end table - -@section Operations - -@section System Calls - -This section details the message buffer 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. - -@c -@c cre_mbf -@c - -@page -@subsection cre_mbf - Create MessageBuffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_mbf( - ID mbfid, - T_CMBF *pk_cmbf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_NOMEM} - Insufficient memory (Memory for control block and/or -ring buffer cannot be allocted) - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_RSATR} - Reserved attribute (mbfatr was invalid or could not be -used) - -@code{E_OBJ} - Invalid object state (a messagebuffer of the same ID -already exists) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (pk_cmbf is invalid or bufsz and/or -maxmsz is negative or invalid) - -@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 exinf, mbfatr, bufsz and/or -maxmsz) - -@subheading DESCRIPTION: - -This routine creates a message buffer on the local node. The message -buffer is initialized based on the attributes specified in the -@code{pk_cmbf} structure. The buffer size and the maximum message size -are determined by the @code{bufsz} and @code{maxmsz} fields in this -structure. - -The @code{mbfatr} field represents attributes of the message -buffer. If @code{TA_TFIFO} is specified, tasks will be put on the queue -on a First In-First Out basis. If @code{TA_TPRI} is specified, tasks -will be placed on the queue according to their priority. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c del_mbf -@c - -@page -@subsection del_mbf - Delete MessageBuffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_mbf( - ID mbfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the messagebuffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid 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 - -@subheading DESCRIPTION: - -This routine deletes the message buffer specified by @code{mbfid}. -Issuing this system call releases memory area used for the control block of -the associated message buffer and the buffer area used for storing messages. - -This routine will complete normally even if there are tasks waiting to -send or receive messages at the message buffer. In that case, an -@code{E_DLT} error will be returned to each waiting task. If there are -messages still in the message buffer, they will be deleted along with -the message buffer and no error will result. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c snd_mbf -@c - -@page -@subsection snd_mbf - Send Message to Message Buffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER snd_mbf( - ID mbfid, - VP msg, - INT msgsz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than -maxmsz; values unsuitable for msg; tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the -message buffer of interest was deleted while waiting) - -@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received -while waiting) - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for psnd_mbf -and tsnd_mbf(tmout=TMO_POL)) - -@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 (implementation-dependent; applicable to -psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) - -@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 msgsz and/or tmout) - -@subheading DESCRIPTION: - -This routine sends the message stored at the address given by @code{msg} -to the message buffer specified by @code{mbfid}. The size of the -message is specified by @code{msgsz}; that is, @code{msgsz} number of -bytes beginning from @code{msg} are copied to the message buffer -specified by @code{mbfid}. If the available space in the buffer is not -enough to include the message given by @code{msg}, the task issuing this -system call will wait on a send wait queue until more buffer space -becomes available. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c psnd_mbf -@c - -@page -@subsection psnd_mbf - Poll and Send Message to Message Buffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =psnd_mbf( - ID mbfid, - VP msg, - INT msgsz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than -maxmsz; values unsuitable for msg; tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the -message buffer of interest 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 - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for psnd_mbf -and tsnd_mbf(tmout=TMO_POL)) - -@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 (implementation-dependent; applicable to -psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) - -@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 msgsz and/or tmout) - -@subheading DESCRIPTION: - -This routine has the same function as @code{snd_mbf} except for the -waiting feature. @code{Psnd_mbf} polls whether or not the task should -wait if @code{snd_mbf} is executed. The meaning of parameters to -@code{psnd_mbf} are the same as for @code{snd_mbf}. The specific -operations by @code{psnd_mbf} are as follows. - - - If there is enough space in the buffer, processing is the same as - @code{snd_mbf}: the message is sent and the system call completes - normally. - - - If there is not enough space in the buffer, an @code{E_TMOUT} error - is returned to indicate polling failed and the system call finishes. - Unlike @code{snd_mbf}, the issuing task does not wait in this case. - The status of the message buffer and the message queue remain unchanged. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c tsnd_mbf -@c - -@page -@subsection tsnd_mbf - Send Message to Message Buffer with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tsnd_mbf( - ID mbfid, - VP msg, - INT msgsz, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than -maxmsz; values unsuitable for msg; tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the -message buffer of interest 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 - -@code{E_CTX} - Context error (issued from task-independent portions or a -task in dispatch disabled state; implementation dependent for psnd_mbf -and tsnd_mbf(tmout=TMO_POL)) - -@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 (implementation-dependent; applicable to -psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) - -@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 msgsz and/or tmout) - -@subheading DESCRIPTION: - -The @code{tsnd_mbf} system call has the same function as @code{snd_mbf} -with an additional timeout feature. A maximum wait time (timeout value) -can be specified using the parameter @code{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 (i.e. without sufficient -buffer space becoming available). - -Only positive values can be specified for @code{tmout}. Specifying -@code{TMO_POL} = 0 to @code{tsnd_mbf} for @code{tmout} indicates that a -timeout value of 0 be used, resulting in exactly the same processing as -@code{psnd_mbf}. Specifying @code{TMO_FEVR} = -1 to @code{tsnd_mbf} for -@code{tmout} indicates that an infinite timeout value be used, resulting -in exactly the same processing as @code{snd_mbf}. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - - -@c -@c rcv_mbf -@c - -@page -@subsection rcv_mbf - Receive Message from Message Buffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rcv_mbf( - VP msg, - INT *p_msgsz, - ID mbfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2 -or less) - -@code{E_DLT} - The object being waited for was deleted (the specified -message buffer was deleted while waiting) - -@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received -while waiting) - -@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 tmout) - -@code{EN_RPAR} - A value outside the range supported by the issuing node -and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node) - -@subheading DESCRIPTION: - -@code{Rcv_mbf} receives the message from the message buffer specified by -@code{mbfid}, and stores it at the memory location given by @code{msg}. -In other words, the content of the message at the head of the message -buffer specified by @code{mbfid} is copied into an area which begins -from @code{msg} and whose size is @code{msgsz}. - -If the message buffer is empty, the task issuing this system call will wait -on a receive message wait queue until a message arrives. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - - -@c -@c prcv_mbf -@c - -@page -@subsection prcv_mbf - Poll and Receive Message from Message Buffer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =prcv_mbf( - VP msg, - INT *p_msgsz, - ID mbfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2 -or less) - -@code{E_DLT} - The object being waited for was deleted (the specified -message buffer 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 - -@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 tmout) - -@code{EN_RPAR} - A value outside the range supported by the issuing node -and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node) - - -@subheading DESCRIPTION: -The @code{prcv_mbf} system call has the same function as @code{rcv_mbf} -except for the waiting feature. @code{Prcv_mbf} polls whether or not -the task should wait if @code{rcv_mbf} is executed. The meaning of -parameters to @code{prcv_mbf} are the same as for @code{rcv_mbf}. The -specific operations by @code{prcv_mbf} are as follows. - - - If there is a message in the specified message buffer, processing is -the same as @code{rcv_mbf}: the first message on the message buffer is -retrieved and the system call completes normally. - - - If there is no message in the specified message buffer, an -@code{E_TMOUT} error is returned to indicate polling failed and the -system call finishes. Unlike @code{rcv_mbf}, the issuing task does not -wait in this case. The status of the message buffer remain unchanged. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - - -@c -@c trcv_mbf -@c - -@page -@subsection trcv_mbf - Receive Message from Message Buffer with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =trcv_mbf( - VP msg, - INT *p_msgsz, - ID mbfid, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2 -or less) - -@code{E_DLT} - The object being waited for was deleted (the specified -message buffer 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 - -@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 tmout) - -@code{EN_RPAR} - A value outside the range supported by the issuing node -and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node) - -@subheading DESCRIPTION: -The @code{trcv_mbf} system call has the same function as @code{rcv_mbf} -with an additional timeout feature. A maximum wait time (timeout value) -can be specified using the parameter @code{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 (i.e. without a message -arriving). - -Only positive values can be specified for @code{tmout}. Specifying -@code{TMO_POL} = 0 to @code{trcv_mbf} for @code{tmout} indicates that a -timeout value of 0 be used, resulting in exactly the same processing as -@code{prcv_mbf}. Specifying @code{TMO_FEVR} = -1 to @code{trcv_mbf} for -tmout indicates that an infinite timeout value be used, resulting in -exactly the same processing as @code{rcv_mbf}. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c ref_mbf -@c - -@page -@subsection ref_mbf - Reference Message Buffer Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_mbf( - T_RMBF *pk_rmbf, - ID mbfid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the message buffer specified by -mbfid does not exist) - -@code{E_OACV} - Object access violation (A mbfid 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 issuing node -and/or transmission packet format was returned as a return parameter (a -value outside supported range for exinf, wtsk, stsk, msgsz and/or -frbufsz on a requesting node) - -@subheading DESCRIPTION: -This system call refers to the state of the message buffer specified by -@code{mbfid}, and returns information of a task waiting to send a -message (@code{stsk}), the size of the next message to be received -(@code{msgsz}), the free buffer size (@code{frbufsz}), information of a -task waiting to receive a message (@code{wtsk}), and its extended -information (@code{exinf}). - -@code{Wtsk} and @code{stsk} indicate whether or not there is a task -waiting for the message buffer in question. If there is no waiting -task, @code{wtsk} and @code{stsk} are returned as @code{FALSE} = 0. If -there is a waiting task, @code{wtsk} and @code{stsk} are returned as -values other than 0. - -An @code{E_NOEXS} error will result if the message buffer specified to -@code{ref_mbf} does not exist. - -The size of the message at the head of the message buffer (the next -message to be received) is returned to @code{msgsz}. If there are no -messages on the message buffer, @code{msgsz} will be returned as -@code{FALSE} = 0. A message whose size is zero cannot be sent. - -At least one of @code{msgsz} = @code{FALSE} and @code{wtsk} = -@code{FALSE} is always true in this system call. - -@code{Frbufsz} indicates the amount of free memory in the message -buffer. This value can be used to know the total approximate size of -the messages which can be sent to the message buffer. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. diff --git a/doc/itron3.0/network.t b/doc/itron3.0/network.t deleted file mode 100644 index 0277a587d0..0000000000 --- a/doc/itron3.0/network.t +++ /dev/null @@ -1,162 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the network support -@c manager. -@c -@c $Id$ -@c - -@chapter Network Support Manager - -@section Introduction - -The -network support manager is ... - -The services provided by the network support manager are: - -@itemize @bullet -@item @code{nrea_dat} - Read Data from another Node -@item @code{nwri_dat} - Write Data to another Node -@item @code{nget_nod} - Get Local Node Number -@item @code{nget_ver} - Get Version Information of another Node -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the network support 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. - - -@c -@c nrea_dat -@c - -@page -@subsection nrea_dat - Read Data from another Node - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER nrea_dat( - INT *p_reasz, - VP dstadr, - NODE srcnode, - VP srcadr, -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c nwri_dat -@c - -@page -@subsection nwri_dat - Write Data to another Node - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER nwri_dat( - INT *p_wrisz, - NODE dstnode, - VP dstadr, - VP srcadr, -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c nget_nod -@c - -@page -@subsection nget_nod - Get Local Node Number - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER nget_nod( - NODE *p_node -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c nget_ver -@c - -@page -@subsection nget_ver - Get Version Information of another Node - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER nget_ver( - T_VER *pk_ver, - NODE node -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/itron3.0/preface.texi b/doc/itron3.0/preface.texi deleted file mode 100644 index ce8bac0904..0000000000 --- a/doc/itron3.0/preface.texi +++ /dev/null @@ -1,14 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node Preface, , Top, Top -@end ifinfo -@unnumbered Preface - -There needs to be a preface to this manual. diff --git a/doc/itron3.0/rendezvous.t b/doc/itron3.0/rendezvous.t deleted file mode 100644 index 1ba4fa93ca..0000000000 --- a/doc/itron3.0/rendezvous.t +++ /dev/null @@ -1,395 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the rendezvous -@c manager. -@c -@c $Id$ -@c - -@chapter Rendezvous Manager - -@section Introduction - -The -rendezvous manager is ... - -The services provided by the rendezvous manager are: - -@itemize @bullet -@item @code{cre_por} - Create Port for Rendezvous -@item @code{del_por} - Delete Port for Rendezvous -@item @code{cal_por} - Call Port for Rendezvous -@item @code{pcal_por} - Poll and Call Port for Rendezvous -@item @code{tcal_por} - Call Port for Rendezvous with Timeout -@item @code{acp_por} - Accept Port for Rendezvous -@item @code{pacp_por} - Poll and Accept Port for Rendezvous -@item @code{tacp_por} - Accept Port for Rendezvous with Timeout -@item @code{fwd_por} - Forward Rendezvous to Other Port -@item @code{rpl_rdv} - Reply Rendezvous -@item @code{ref_por} - Reference Port Status -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the rendezvous 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. - - -@c -@c cre_por -@c - -@page -@subsection cre_por - Create Port for Rendezvous - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_por( - ID porid, - T_CPOR *pk_cpor -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c del_por -@c - -@page -@subsection del_por - Delete Port for Rendezvous - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_por( - ID porid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c cal_por -@c - -@page -@subsection cal_por - Call Port for Rendezvous Poll - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cal_por( - VP msg, - INT *p_rmsgsz, - ID porid, - UINT calptn -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c pcal_por -@c - -@page -@subsection pcal_por - Poll and Call Port for Rendezvous - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =pcal_por( - VP msg, - INT *p_rmsgsz, - ID porid, - UINT calptn, - INT -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c tcal_por -@c - -@page -@subsection tcal_por - Call Port for Rendezvous with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tcal_por( - VP msg, - INT *p_rmsgsz, - ID porid, - UINT calptn, - INT -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c acp_por -@c - -@page -@subsection acp_por - Accept Port for Rendezvous Poll - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER acp_por( - RNO *p_rdvno, - VP msg, - INT *p_cmsgsz, - ID porid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c pacp_por -@c - -@page -@subsection pacp_por - Poll and Accept Port for Rendezvous - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =pacp_por( - RNO *p_rdvno, - VP msg, - INT *p_cmsgsz, - ID porid, - UINT -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c tacp_por -@c - -@page -@subsection tacp_por - Accept Port for Rendezvous with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tacp_por( - RNO *p_rdvno, - VP msg, - INT *p_cmsgsz, - ID porid, - UINT -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c fwd_por -@c - -@page -@subsection fwd_por - Forward Rendezvous to Other Port - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER fwd_por( - ID porid, - UINT calptn, - RNO rdvno, - VP msg, - INT cmsgsz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c rpl_rdv -@c - -@page -@subsection rpl_rdv - Reply Rendezvous - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rpl_rdv( - RNO rdvno, - VP msg, - INT rmsgsz -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_por -@c - -@page -@subsection ref_por - Reference Port Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_por( - T_RPOR *pk_rpor, - ID porid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/itron3.0/semaphore.t b/doc/itron3.0/semaphore.t deleted file mode 100644 index 380e72d07e..0000000000 --- a/doc/itron3.0/semaphore.t +++ /dev/null @@ -1,642 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the semaphore -@c manager. -@c -@c $Id$ -@c - -@chapter Semaphore Manager - -@section Introduction - -The semaphore manager provides functions to allocate, delete, and -control counting semaphores. This manager is based on the -ITRON 3.0 standard. - -The services provided by the semaphore manager are: - -@itemize @bullet -@item @code{cre_sem} - Create Semaphore -@item @code{del_sem} - Delete Semaphore -@item @code{sig_sem} - Signal Semaphore -@item @code{wai_sem} - Wait on Semaphore -@item @code{preq_sem} - Poll and Request Semaphore -@item @code{twai_sem} - Wait on Semaphore with Timeout -@item @code{ref_sem} - Reference Semaphore Status -@end itemize - -@section Background - -@subsection Theory - -Semaphores are used for synchronization and mutual exclusion by indicating -the availability and number of resources. The task (the task which is -returning resources) notifying other tasks of an event increases the number -of resources held by the semaphore by one. The task (the task which -will obtain resources) waiting for the event decreases the number of -resources held by the semaphore by one. If the number of resources held by a -semaphore is insufficient (namely 0), the task requiring resources will -wait until the next time resources are returned to the semaphore. If there is -more than one task waiting for a semaphore, the tasks will be placed in the -queue. - - -@subsection T_CSEM Structure - -The T_CSEM structure is used to define the characteristics of a semaphore -and passed an as argument to the @code{cre_sem} service. The structure -is defined as follows: - -@example -@group -/* - * Create Semaphore (cre_sem) Structure - */ - -typedef struct t_csem @{ - VP exinf; /* extended information */ - ATR sematr; /* semaphore attributes */ - /* Following is the extended function for [level X]. */ - INT isemcnt; /* initial semaphore count */ - INT maxsem; /* maximum semaphore count */ - /* additional implementation dependent information may be included */ -@} T_CSEM; - -/* - * sematr - Semaphore Attribute Values - */ - -#define TA_TFIFO 0x00 /* waiting tasks are handled by FIFO */ -#define TA_TPRI 0x01 /* waiting tasks are handled by priority */ - -@end group -@end example - -where the meaning of each field is: - -@table @b -@item exinf -is for any extended information that the implementation may define. -This implementation does not use this field. - -@item sematr -is the attributes for this semaphore. The only attributed -which can be specified is whether tasks wait in FIFO (@code{TA_TFIFO}) -or priority (@code{TA_TPRI}) order. - -@item isemcnt -is the initial count of the semaphore. - -@item maxsem -is the maximum count the semaphore may have. It places an upper -limit on the value taken by the semaphore. - -@end table - -@subsection Building a Semaphore Attribute Set - -In general, an attribute set is built by a bitwise OR -of the desired attribute components. The following table lists -the set of valid semaphore attributes: - -@itemize @bullet -@item @code{TA_TFIFO} - tasks wait by FIFO - -@item @code{TA_TPRI} - tasks wait by priority - -@end itemize - -Attribute values are specifically designed to be -mutually exclusive, therefore bitwise OR and addition operations -are equivalent as long as each attribute appears exactly once in -the component list. - -@subsection T_RSEM Structure - -The T_RSEM structure is filled in by the @code{ref_sem} service with -status and state information on a semaphore. The structure -is defined as follows: - -@example -@group -/* - * Reference Semaphore (ref_sem) Structure - */ - -typedef struct t_rsem @{ - VP exinf; /* extended information */ - BOOL_ID wtsk; /* indicates whether there is a waiting task */ - INT semcnt; /* current semaphore count */ - /* additional implementation dependent information may be included */ -@} T_RSEM; -@end group -@end example - -@table @b - -@item exinf -is for any extended information that the implementation may define. -This implementation does not use this field. - -@item wtsk -is TRUE when there is one or more task waiting on the semaphore. -It is FALSE if no tasks are currently waiting. The meaning of this -field is allowed to vary between ITRON implementations. It may have -the ID of a waiting task, the number of tasks waiting, or a boolean -indication that one or more tasks are waiting. - -@item semcnt -is the current semaphore count. - -@end table - -The information in this table is very volatile and should be used -with caution in an application. - -@section Operations - -@subsection Using as a Binary Semaphore - -Creating a semaphore with a limit on the count of 1 effectively -restricts the semaphore to being a binary semaphore. When the -binary semaphore is available, the count is 1. When the binary -semaphore is unavailable, the count is 0. - -Since this does not result in a true binary semaphore, advanced -binary features like the Priority Inheritance and Priority -Ceiling Protocols are not available. - -@section System Calls - -This section details the semaphore 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. - - -@c -@c cre_sem -@c - -@page -@subsection cre_sem - Create Semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_sem( - ID semid, - T_CSEM *pk_csem -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be -allocated) - -@code{E_OACV} - Object access violation (A semid less than -4 was -specified from a user task.) - -@code{E_RSATR} - Reserved attribute (sematr was invalid or could not be -used) - -@code{E_OBJ} - Invalid object state (a semaphore of the same ID already -exists) - -@code{E_PAR} - Parameter error (pk_csem is invalid and/or isemcnt or -maxsem is negative or invalid) - -@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 exinf, sematr, isemcnt and/or -maxsem) - -@subheading DESCRIPTION: - -This routine creates a semaphore that resides on the local node. The -semaphore is initialized based on the attributes specified in the -@code{pk_csem} structure. The initial and maximum counts of the -semaphore are set based on the @code{isemcnt} and @code{maxsem} fields -in this structure. - -Specifying @code{TA_TPRI} in the @code{sematr} field of the -semaphore attributes structure causes tasks -waiting for a semaphore to be serviced according to task -priority. When @code{TA_TFIFO} is selected, tasks are serviced in First -In-First Out order. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -All memory is preallocated for RTEMS ITRON objects. Thus, no dynamic -memory allocation is performed by @code{cre_sem} and the @code{E_NOMEM} -error can not be returned. - -This directive will not cause the running task to be preempted. - -The following semaphore attribute constants are -defined by RTEMS: - -@itemize @bullet -@item @code{TA_TFIFO} - tasks wait by FIFO - -@item @code{TA_TPRI} - tasks wait by priority - -@end itemize - -@c -@c del_sem -@c - -@page -@subsection del_sem - Delete Semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_sem( - ID semid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid 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 - -@subheading DESCRIPTION: - -This routine deletes the semaphore specified by @code{semid}. -All tasks blocked waiting to acquire the semaphore will be -readied and returned a status code which indicates that the -semaphore was deleted. The control block for this semaphore -is reclaimed by RTEMS. - - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -The calling task will be preempted if it is enabled -by the task's execution mode and a higher priority local task is -waiting on the deleted semaphore. The calling task will NOT be -preempted if all of the tasks that are waiting on the semaphore -are remote tasks. - -The calling task does not have to be the task that -created the semaphore. Any local task that knows the semaphore -id can delete the semaphore. - - -@c -@c sig_sem -@c - -@page -@subsection sig_sem - Signal Semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER sig_sem( - ID semid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_QOVR} - Queuing or nesting overflow (the queuing count given by -semcnt went over the maximum allowed) - -@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 - -@subheading DESCRIPTION: - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -@c -@c wai_sem -@c - -@page -@subsection wai_sem - Wait on Semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER wai_sem( - ID semid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_DLT} - The object being waited for was deleted (the specified -semaphore was deleted while waiting) - -@code{E_RLWAI} - Wait state was forcibly released (rel_wai was received -while waiting) - -@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 tmout) - -@subheading DESCRIPTION: - -This routine attempts to acquire the semaphore specified by @code{semid}. -If the semaphore is available (i.e. positive semaphore count), then the -semaphore count is decremented and the calling task returns immediately. -Otherwise the calling tasking is blocked until the semaphore is released -by a subsequent invocation of @code{sig_sem}. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -If the semaphore is not available, then the calling task will be blocked. - -@c -@c preq_sem -@c - -@page -@subsection preq_sem - Poll and Request Semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER preq_sem( - ID semid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid less than -4 was -specified from a user task. This is implementation dependent.) - -@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 tmout) - -@subheading DESCRIPTION: - -This routine attempts to acquire the semaphore specified by @code{semid}. -If the semaphore is available (i.e. positive semaphore count), then the -semaphore count is decremented and the calling task returns immediately. -Otherwise, the @code{E_TMOUT} error is returned to the calling task to -indicate the semaphore is unavailable. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -This routine will not cause the running task to be preempted. - -@c -@c twai_sem -@c - -@page -@subsection twai_sem - Wait on Semaphore with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER twai_sem( - ID semid, - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid less than -4 was -specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the specified -semaphore 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 tmout) - -@subheading DESCRIPTION: - -This routine attempts to acquire the semaphore specified by @code{semid}. -If the semaphore is available (i.e. positive semaphore count), then the -semaphore count is decremented and the calling task returns immediately. -Otherwise the calling tasking is blocked until the semaphore is released -by a subsequent invocation of @code{sig_sem} or the timeout period specified -by @code{tmout} milliseconds is exceeded. If the timeout period is exceeded, -then the @code{E_TMOUT} error is returned. - -By specifiying @code{tmout} as @code{TMO_FEVR}, this routine has the same -behavior as @code{wai_sem}. Similarly, by specifiying @code{tmout} as -@code{TMO_POL}, this routine has the same behavior as @code{preq_sem}. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -This routine may cause the calling task to block. - -A clock tick is required to support the timeout functionality of -this routine. - -@c -@c ref_sem -@c - -@page -@subsection ref_sem - Reference Semaphore Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_sem( - T_RSEM *pk_rsem, - ID semid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID number (semid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the semaphore specified by semid -does not exist) - -@code{E_OACV} - Object access violation (A semid 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 or semcnt) - -@subheading DESCRIPTION: - -This routine returns status information on the semaphore specified -by @code{semid}. The @code{pk_rsem} structure is filled in by -this service call. - -@subheading NOTES: - -Multiprocessing is not supported. Thus none of the "EN_" status codes -will be returned. - -This routine will not cause the running task to be preempted. - diff --git a/doc/itron3.0/stamp-vti b/doc/itron3.0/stamp-vti deleted file mode 100644 index a77d339def..0000000000 --- a/doc/itron3.0/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 27 June 2007 -@set UPDATED-MONTH June 2007 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 diff --git a/doc/itron3.0/status.t b/doc/itron3.0/status.t deleted file mode 100644 index 4f13234104..0000000000 --- a/doc/itron3.0/status.t +++ /dev/null @@ -1,943 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the task -@c manager. -@c -@c $Id$ -@c - -@chapter ITRON Implementation Status - -@section Introduction - -This chapter describes the status of the implementation of each -manager in the RTEMS implementataion of the uITRON 3.0 API. The -status of each manager is presented in terms of documentation and -status relative to the extended level (level 'E') of the uITRON 3.0 -API specification. The extended level of the specification is -the level at which dynamic object creation, deletion, and -reference services are available. This level is more akin to the other -APIs supported by RTEMS. This purpose of this chapter is -to make it clear what is required to bring the RTEMS -uITRON API implementation into compliance with the -specification. The following description of the specification -levels is taken from the uITRON 3.0 API specification. - - -uITRON 3.0 specification is divided into fewer system call levels than was the -previous uITRON 2.0 specification. There are now just three levels: Level R -(Required), Level S (Standard) and Level E (Extended). In addition to these -three levels, there is also Level C for CPU-dependent system calls. -In addition, the uITRON 3.0 API, defines the network level ('N') which -represents system calls that support the connection function - -@itemize @bullet -@item [level R] (Required) -The functions in this level are mandatory for all implementations of -uITRON 3.0 specification. This includes basic functions for achieving -a real-time, multitasking OS. These functions can be implemented even -without a hardware timer. This level corresponds to Levels 1 and 2 -of uITRON 2.0 specification. - -@item [level S] (Standard) -This includes basic functions for achieving a real-time, multitasking -OS. This level corresponds to Levels 3 and 4 of uITRON 2.0 -specification. - -@item [level E] (Extended) -This includes additional and extended functions. This corresponds to -functions not included in uITRON 2.0 specification (functions of -ITRON2 specification). Specifically, this level includes object -creation and deletion functions, rendezvous functions, memorypools -and the timer handler. - -@item [level C] (CPU dependent) -This level provides implementation-dependent functions required due to -the CPU or hardware configuration. - -@end itemize - -The support level of the connection function is indicated by appending an 'N' -to the end of the level. For example, connectivity supported at [level S] -would be referred to as [level SN]. The support level for functions which -can only send requests for operations on other nodes but offer no system call -processing on the issuing node itself are indicated by the lower case letter -'s' or 'e'. - -@c -@c Task -@c - -@section Task Status - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_tsk - Complete, Pending Review -@item del_tsk - Complete, Pending Review -@item sta_tsk - Complete, Pending Review -@item ext_tsk - Complete, Pending Review -@item exd_tsk - Complete, Pending Review -@item ter_tsk - Complete, Pending Review -@item dis_dsp - Complete, Pending Review -@item ena_dsp - Complete, Pending Review -@item chg_pri - Complete, Pending Review -@item rot_rdq - Complete, Pending Review -@item rel_wai - Stub, Needs to be Fleshed Out -@item get_tid - Complete, Pending Review -@item ref_tsk - Complete, Pending Review - -@item Notes: -@itemize @bullet -@item None -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item itron01 - Hello world -@item itron02 - Semaphore test -@item itron03 - directives: ex_init, ex_start, t_create, -t_start, tm_tick, i_return, t_ident, tm_set, tm_get, tm_wkafter -See .doc file, verify correct -@item itron04 - Doc file needed -@item itron05 - directives: ext_tsk, cre_tsk, sta_tsk, rot_rdq -ex_start, t_create, t_start, tm_tick, i_return, t_ident, t_delete, -tm_wkafter, t_setpri, t_suspend -See .doc file, verify correct -@item itron06 - Doc file needed -@item itron07 - Doc file needed -@item itron08 - Doc file needed -@item itron09 - Doc file needed -@item itron10 - Doc file needed -@item tmitron01 - Doc file needed -@item tm_include - Doc file needed. Timing test for semaphores. -@end itemize - -@item Documentation -@itemize @bullet -@item Complete, Pending Review -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize - -@end itemize - -@c -@c Task-Dependent Synchronization -@c - -@section Task-Dependent Synchronization Status - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item sus_tsk - Complete, Pending Review -@item rsm_tsk - Complete, Pending Review -@item frsm_tsk - Complete, Pending Review -@item slp_tsk - Stub, Needs to be Fleshed Out -@item tslp_tsk - Stub, Needs to be Fleshed Out -@item wup_tsk - Stub, Needs to be Fleshed Out -@item can_wup - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item None -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item Functional tests for complete routines. -@item Yellow line testing needs to be verified. -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Complete, Pending Review -@item -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Semaphore -@c - -@section Semaphore - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_sem - Complete, Pending Review -@item del_sem - Complete, Pending Review -@item sig_sem - Complete, Pending Review -@item wai_sem - Complete, Pending Review -@item preq_sem - Complete, Pending Review -@item twai_sem - Complete, Pending Review -@item ref_sem - Complete, Pending Review -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Required -@end itemize - -@item Testing -@itemize @bullet -@item Yellow Lined BUT Timeout Cases Not Actually Executed -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Complete, Pending Review -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item Complete, Pending Review -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Eventflags -@c - -@section Eventflags - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_flg - Stub, Needs to be Fleshed Out -@item del_flg - Stub, Needs to be Fleshed Out -@item set_flg - Stub, Needs to be Fleshed Out -@item clr_flg - Stub, Needs to be Fleshed Out -@item wai_flg - Stub, Needs to be Fleshed Out -@item pol_flg - Stub, Needs to be Fleshed Out -@item twai_flg - Stub, Needs to be Fleshed Out -@item ref_flg - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Similar in Functionality to Classic API Events Manager -@item Implement Using new SuperCore Event Handler -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item Add SuperCore Events Object Based on Classic Events -@item Redo Classic Events to use SuperCore Events -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Good First Draft. -@item No Information in Operations. -@item Should not use "standard-like" language. -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Mailbox -@c - -@section Mailbox - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_mbx - Stub, Needs to be Fleshed Out -@item del_mbx - Stub, Needs to be Fleshed Out -@item snd_msg - Stub, Needs to be Fleshed Out -@item rcv_msg - Stub, Needs to be Fleshed Out -@item prcv_msg - Stub, Needs to be Fleshed Out -@item trcv_msg - Stub, Needs to be Fleshed Out -@item ref_mbx - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Passes Addresses of Messages -@item FIFO or Priority Task Blocking -@item FIFO or Priority Message Ordering -@item Send Returns Error on Overflow -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Needs More Text -@item No Information in Background or Operations. -@item Service Descriptions are Weak. -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Message Buffer -@c - -@section Message Buffer - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_mbf - Stub, Needs to be Fleshed Out -@item del_mbf - Stub, Needs to be Fleshed Out -@item snd_mbf - Stub, Needs to be Fleshed Out -@item psnd_mbf - Stub, Needs to be Fleshed Out -@item tsnd_mbf - Stub, Needs to be Fleshed Out -@item rcv_mbf - Stub, Needs to be Fleshed Out -@item prcv_mbf - Stub, Needs to be Fleshed Out -@item trcv_mbf - Stub, Needs to be Fleshed Out -@item ref_mbf - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Implement Using SuperCore Message Queue Handler -@item Passes Full Bodies of Messages -@item FIFO or Priority Task Blocking -@item FIFO Message Ordering Only -@item Send (snd_mbf and tsnd_mbf) Blocks on Overflow -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item SuperCore Message Queue Handler Must Support Blocking Sends. [NOTE: -This is required for POSIX Message Queues as well.] -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Good First Draft. -@item No Information in Operations -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Rendezvous -@c - -@section Rendezvous - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_por - Stub, Needs to be Fleshed Out -@item del_por - Stub, Needs to be Fleshed Out -@item cal_por - Stub, Needs to be Fleshed Out -@item pcal_por - Stub, Needs to be Fleshed Out -@item tcal_por - Stub, Needs to be Fleshed Out -@item acp_por - Stub, Needs to be Fleshed Out -@item pacp_por - Stub, Needs to be Fleshed Out -@item tacp_por - Stub, Needs to be Fleshed Out -@item fwd_por - Stub, Needs to be Fleshed Out -@item rpl_rdv - Stub, Needs to be Fleshed Out -@item ref_por - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Hardest ITRON Manager to Implement -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item Doubtful, Probably Implement in Terms of Multiple SuperCore Objects. -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Shell, Needs to be Fleshed Out -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Interrupt -@c - -@section Interrupt - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item def_int - Stub, Needs to be Fleshed Out -@item ret_int - Stub, Needs to be Fleshed Out -@item ret_wup - Stub, Needs to be Fleshed Out -@item loc_cpu - Stub, Needs to be Fleshed Out -@item unl_cpu - Stub, Needs to be Fleshed Out -@item dis_int - Stub, Needs to be Fleshed Out -@item ena_int - Stub, Needs to be Fleshed Out -@item chg_iXX - Stub, Needs to be Fleshed Out -@item ref_iXX - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item This quote from the ITRON specification needs to be thought about:@* -@*@i{"When an interrupt is invoked, the interrupt handler defined with -this system call is started directly by the -interrupt processing mechanism of the CPU hardware. Accordingly, code at the -beginning and end of an interrupt handler must save and restore any registers -used by the interrupt handler."}@*@* -Based on another comment, in the ret_int description, I think this means -that RTEMS will not support the TA_ASM style of interrupt handlers -- -only the TA_HLNG style.@*@* -@i{When TA_HLNG is specified, a high-level language environment setting -program (a high-level language support routine) is called before branching -to the inthdr address. The least significant bit (LSB) of the system -attribute bits is used for this specification.} - -@item Specification allows special "interrupt-only" versions of system -calls named i???_??? (i.e. sig_sem and isig_sem). This does not seem -to be something that would be implemented with RTEMS. We could provide -macros mapping them onto the default versions if this is an issue. - -@item How this operates versus the behavior of a true TRON chip is -up for discussion. - -@item ret_wup is questionable in only high-level language ISRs. - -@item dis_int and ena_int refer to a specific interrupt number. These -may require hooking back out to the BSP. - -@item for chg_iXX and reg_iXX, the XX should be replaced with something -that is meaningful on a particular CPU. -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Shell, Needs to be Fleshed Out -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Memory Pool -@c - -@section Memory Pool - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_mpl - Stub, Needs to be Fleshed Out -@item del_mpl - Stub, Needs to be Fleshed Out -@item get_blk - Stub, Needs to be Fleshed Out -@item pget_blk - Stub, Needs to be Fleshed Out -@item tget_blk - Stub, Needs to be Fleshed Out -@item rel_blk - Stub, Needs to be Fleshed Out -@item ref_mpl - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Implement Using SuperCore Heap Handler -@item Similar to Region in Classic API with Blocking -@item FIFO or Priority Task Blocking -@item Specification Deliberately Open on Allocation Algorithm -@item Multiple Tasks Can be Unblocked by a single rel_blk -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Good First Draft. -@item No Information in Operations -@item Should not use "standard-like" language. -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Fixed Block -@c - -@section Fixed Block - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item cre_mpf - Stub, Needs to be Fleshed Out -@item del_mpf - Stub, Needs to be Fleshed Out -@item get_blf - Stub, Needs to be Fleshed Out -@item pget_blf - Stub, Needs to be Fleshed Out -@item tget_blf - Stub, Needs to be Fleshed Out -@item rel_blf - Stub, Needs to be Fleshed Out -@item ref_mpf - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Implement Using SuperCore Chain Handler -@item Similar to Partition in Classic API with Blocking -@item FIFO or Priority Task Blocking -@item Specification Deliberately Open on Allocation Algorithm -@item Should add Blocking to Classic API Partition at Same Time -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Good First Draft. -@item No Information in Background or Operations -@item Should not use "standard-like" language. -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Time -@c - -@section Time - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item get_tim - Stub, Needs to be Fleshed Out -@item set_tim - Stub, Needs to be Fleshed Out -@item dly_tsk - Stub, Needs to be Fleshed Out -@item def_cyc - Stub, Needs to be Fleshed Out -@item act_cyc - Stub, Needs to be Fleshed Out -@item ref_cyc - Stub, Needs to be Fleshed Out -@item def_alm - Stub, Needs to be Fleshed Out -@item ref_alm - Stub, Needs to be Fleshed Out -@item ret_tmr - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item Need to Implement Time Conversion Routines -@item Epoch is January 1, 1985, 00:00:00 am (GMT). -@item Cyclic and Alarm Handlers may be TA_ASM or TA_HLNG. -@item Alarms may be Absolute or Relative Time based. -@item May Want to Implement a Timer Server Task -@item Termination via ret_tmr is Not Consistent with Current RTEMS Timers. -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Have Version in Word -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c System -@c - -@section System - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item get_ver - Stub, Needs to be Fleshed Out -@item ref_sys - Stub, Needs to be Fleshed Out -@item ref_cfg - Stub, Needs to be Fleshed Out -@item def_svc - Stub, Needs to be Fleshed Out -@item def_exc - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item May Have to Obtain ITRON "OS Maker" Id -@item - def_svc seems to imply a trap handler interface -@item - def_exc needs to be examined. -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Shell, Needs to be Fleshed Out -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - -@c -@c Network Support -@c - -@section Network Support - -@itemize @bullet - -@item Implementation -@itemize @bullet -@item nrea_dat - Stub, Needs to be Fleshed Out -@item nwri_dat - Stub, Needs to be Fleshed Out -@item nget_nod - Stub, Needs to be Fleshed Out -@item nget_ver - Stub, Needs to be Fleshed Out - -@item Notes: -@itemize @bullet -@item None of these are difficult to implement on top of MPCI -@item MP Packet formats are well-defined. -@end itemize - -@end itemize - -@item Executive Modifications -@itemize @bullet -@item None Expected -@end itemize - -@item Testing -@itemize @bullet -@item No Tests Written -@item No Timing Tests -@end itemize - -@item Documentation -@itemize @bullet -@item Shell, Needs to be Fleshed Out -@end itemize - -@item ITRON 3.0 API Conformance -@itemize @bullet -@item Level E - Extended Functionality -@itemize @bullet -@item -@end itemize - -@item Level C - CPU Dependent Functionality -@itemize @bullet -@item NA -@end itemize - -@item Level N - Connection Functionality -@itemize @bullet -@item Not implemented -@end itemize -@end itemize - -@end itemize - diff --git a/doc/itron3.0/task.t b/doc/itron3.0/task.t deleted file mode 100644 index 15db155ca2..0000000000 --- a/doc/itron3.0/task.t +++ /dev/null @@ -1,767 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the task -@c manager. -@c -@c $Id$ -@c - -@chapter Task Manager - -@section Introduction - -The task manager is used to directly control and access the state of tasks. Included among these are functions for creating, deleting, starting and terminating tasks, for releasing the WAIT state of tasks, for enabling/disabling task dispatching, for changing task priority levels, for rotatingtasks on the ready queue, and for accessing task state. - -The services provided by the task manager are: - -@itemize @bullet -@item @code{cre_tsk} - Create Task -@item @code{del_tsk} - Delete Task -@item @code{sta_tsk} - Start Task -@item @code{ext_tsk} - Exit Issuing Task -@item @code{exd_tsk} - Exit and Delete Issuing Task -@item @code{ter_tsk} - Terminate Other Task -@item @code{dis_dsp} - Disable Dispatch -@item @code{ena_dsp} - Enable Dispatch -@item @code{chg_pri} - Change Task Priority -@item @code{rot_rdq} - Rotate Tasks on the Ready Queue -@item @code{rel_wai} - Release Wait of Other Task -@item @code{get_tid} - Get Task Identifier -@item @code{ref_tsk} - Reference Task Status -@end itemize - -@section Background - -@subsection Task Definition -Many definitions of a task have been proposed in computer literature. Unfortunately, none of these definitions encompasses all facets of the concept in a manner which is operating system independent. Several of the more common definitions are provided to enable each user to select a definition which best matches their own experience and understanding of the task concept: - -@itemize @bullet -@item a "dispatchable" unit. -@item an entity to which the processor is allocated. -@item an atomic unit of a real-time, multiprocessor system. -@item single threads of execution which concurrently compete for resources. -@item a sequence of closely related computations which can execute concurrently with other computational sequences. -@item From our implementation perspective, a task is the smallest thread of execution which can compete on its own for system resources. A task is manifested by the existence of a task control block (TCB). -@end itemize - -@subsection Task Manager Task Control Block - The Task Control Block (TCB) is a defined data structure which contains all the information that is pertinent to the execution of a task. During system initialization, implementation reserves a TCB for each task configured. A TCB is allocated upon creation of the task and is returned to the TCB free list upon deletion of the task. - -The TCB's elements are modified as a result of system calls made by the application in response to external and internal stimuli. The TCB contains a task's name, ID, current priority, current and starting states, TCB user extension pointer, scheduling control structures, as well as data required by a blocked task. - -A task's context is stored in the TCB when a task switch occurs. When the task regains control of the processor, its context is restored from the TCB. When a task is restarted, the initial state of the task is restored from the starting context area in the task's TCB. - -@subsection T_CTSK Structure -The T_CTSK structure contains detailed information necessary to create the task. Such task attributes, start address, priority and stack size. - -@example -typedef struct t_ctsk @{ - VP exinf; /* extended information */ - ATR tskatr; /* task attributes */ - FP task; /* task start address */ - PRI itskpri; /* initial task priority */ - INT stksz; /* stack size */ - /* additional implementation dependent information may be included */ -@} T_CTSK; - -@end example - -@subsection Task Manager Task States -A task may exist in one of the following five states: - -@itemize @bullet -@item RUN - Currently scheduled to the CPU -@item READY - May be scheduled to the CPU -@item Wait - Unable to be scheduled to the CPU -@itemize @bullet -@item (Specific) WAIT - The task is issued a command to wait on a condition -@item SUSPEND - Another task suspended execution of the task -@item WAIT-SUSPEND - Both the WAIT and SUSPEND states apply -@end itemize -@item DORMANT - Created task that is not started -@item NON-EXISTENT - Uncreated or deleted task -@end itemize - -An active task may occupy the RUN, READY, Wait or DORMANT state, otherwise the task is considered NON-EXISTENT. One or more tasks may be active in the system simultaneously. Multiple tasks communicate, synchronize, and compete for system resources with each other via system calls. The multiple tasks appear to execute in parallel, but actually each is dispatched to the CPU for periods of time determined by the scheduling algorithm. The scheduling of a task is based on its current state and priority. - -@subsection Task Manager Task Priority -A task's priority determines its importance in relation to the other tasks executing on the same processor. Our implementation supports 255 levels of priority ranging from 1 to 255. Tasks of numerically smaller priority values are more important tasks than tasks of numerically larger priority values. For example, a task at priority level 5 is of higher privilege than a task at priority level 10. There is no limit to the number of tasks assigned to the same priority. - -Each task has a priority associated with it at all times. The initial value of this priority is assigned at task creation time. The priority of a task may be changed at any subsequent time. - -Priorities are used by the scheduler to determine which ready task will be allowed to execute. In general, the higher the logical priority of a task, the more likely it is to receive processor execution time. - -@section Operations - -@subsection Task Manager Creating Tasks -The cre_tsk directive creates a task specified by tskid. Specifically, a TCB (Task Control Block) is allocated for the task to be created, and initialized according to accompanying parameter values of itskpri, task, stksz, etc. A stack area is also allocated for the task based on the parameter stksz. - -@subsection Task Manager Starting and Restarting Tasks -The sta_tsk directive starts the task specified by tskid. Specifically, it changes the state of the task specified by tskid from DORMANT into RUN/READY. This enables the task to compete, based on its current priority, for the processor and other system resources. Any actions, such as suspension or change of priority, performed on a task prior to starting it are nullified when the task is started. - -Stacd can be used to specify parameters to be passed to the task when it is started. This parameter can be read by the task being started, and may be used for transmitting simple messages. - -The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created. - -Start request is not queued in this this system call. In other words, if this system call is issued when the target task is not in DORMANT state, the system call will be ignored, and an E_OBJ error returned to the issuing task. - -If cre_tsk [level EN] is not implemented on a system, tasks are created statically when the system is started. Parameters required for creating a task, such as task starting address (task) and initial task priority (itskpri) are also specified statically at system startup. - -@subsection Task Manager Suspending and Resuming Tasks -The sus_tsk directive suspends the execution of the task specified by tskid by putting it into SUSPEND state. SUSPEND 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. - -Both rsm_tsk and fsm_tsk system calls release SUSPEND state of the task specified by tskid. Specifically, they cause 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. - -@subsection Task Manager Changing Task Priority -The chg_pri system call changes the current priority of the task specified by tskid to the value specified by tskpri. - -A 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 to a system call issued from a task-independent portion. - -The priority set by this system call remains in effect until the task exits. Once a task enters DORMANT state, its priority prior to exiting is lost. When a task which enters DORMANT state restarts, the initial task priority (itskpri) specified at task creation or at system startup will be used. - -@subsection Task Manager Task Deletion -The del_tsk system call deletes the task specified by tskid. Specifically, it changes the state of the task specified by tskid from DORMANT into NON-EXISTENT (a virtual state not existing on the system), and then clears the TCB and releases stack. An E_OBJ error results if this system call is used on a task which is not DORMANT. - -After deletion, another task having the same ID number can be created. - -The exd_tsk system call causes the issuing task to exit and then delete itself. - -When a task exits, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had secured prior to the call. It is the user's responsibility to see to it that all resources are released beforehand. - -@section System Calls - -This section details the task 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. - - -@c -@c cre_tsk -@c - -@page -@subsection cre_tsk - Create Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER cre_tsk( - ID tskid, - T_CTSK *pk_ctsk -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_NOMEM} - Insufficient memory (Memory for control block and/or user stack cannot be allocated) - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_RSATR} - Reserved attribute (tskatr was invalid or could not be used) - -@code{E_OBJ} - Invalid object state (a task of the same ID already exists) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (pk_ctsk, task, itskpri and/or stksz is invalid) - -@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 exinf, tskatr, task, itskpri and/or stksz) - -@subheading DESCRIPTION: -This system call creates the task specified by tskid. Specifically, a TCB (Task Control Block) is allocated for the task to be created, and initialized according to accompanying parameter values of itskpri, task, tksz, etc. A stack area is also allocated for the task based on the parameter stksz. - -@subheading NOTES: -User tasks have positive ID numbers, while system tasks have negative ID numbers. User tasks cannot access system objects (objects having negative ID numbers). - -The new task created by this system call will be put in DORMANT state. - -Extended information (exinf) has been added. This allows the user to include additional information about task attributes. If a larger region is desired for including user information, the user should allocate memory area and set the address of the memory packet to exinf. - -Multiprocessing is not supported. Thus none of the "EN_" status codes will be returned. - - -@c -@c del_tsk -@c - -@page -@subsection del_tsk - Delete Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER del_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the target task is not in DORMANT state) - -@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 - -@subheading DESCRIPTION: -This system call deletes the task specified by tskid. Specifically, it changes the state of the task specified by tskid from DORMANT into NON-EXISTENT (a virtual state not existing on the system), and then clears the TCB and releases stack. An E_OBJ error results if this system call is used on a task which is not DORMANT. - -After deletion, another task having the same ID number can be created. - -@subheading NOTES: -A task cannot delete itself by this system call. An E_OBJ error will result if a task specifies itself, since such a task cannot be DORMANT. Use the exd_tsk system call rather than this one when a task needs to delete itself. - - -@c -@c sta_tsk -@c - -@page -@subsection sta_tsk - Start Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER sta_tsk( - ID tskid, - INT stacd -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the target task is not in DORMANT state) - -@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 stacd) - -@subheading DESCRIPTION: -This system call starts the task specified by tskid. Specifically, it changes the state of the task specified by tskid from DORMANT into RUN/READY. - -Stacd can be used to specify parameters to be passed to the task when it is started. This parameter can be read by the task being started, and may be used for transmitting simple messages. - -The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created. - -Start request is not queued in this this system call. In other words, if this system call is issued when the target task is not in DORMANT state, the system call will be ignored, and an E_OBJ error returned to the issuing task. - -If cre_tsk [level EN] is not implemented on a system, tasks are created statically when the system is started. Parameters required for creating a task, such as task starting address (task) and initial task priority (itskpri) are also specified statically at system startup. - -@subheading NOTES: - - -@c -@c ext_tsk -@c - -@page -@subsection ext_tsk - Exit Issuing Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void ext_tsk(void); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state) - - * System call may detect this error. The error is not returned to the context issuing the system call. Error codes therefore cannot be returned directly as a return parameter of the system call. The behavior on error detection is implementation dependent. - - -@subheading DESCRIPTION: -This system call causes the issuing task to exit, changing the state of the task into the DORMANT state. - -@subheading NOTES: -When a task exits due to ext_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had obtained prior to the system call. It is the user's responsibility that all resources are released beforehand. - -Ext_tsk is a system call which does not return to the issuing context. Accordingly, even if an error code is returned on detection of some error, it is normal for tasks making this system call not to perform any error checking, and it is in fact possible that a program could run out of control. For this reason, even if an error is detected upon issuing this system call, the error is not returned to the task which issued the system call. If information on detected errors is required it should be left in a messagebuffer used as an error log. - -In principle, information concerning a task recorded in the TCB, such as task priority, is reset whenever a task is placed in DORMANT state. For example, its task priority after being restarted would be reset to the initial task priority (itskpri) specified by cre_tsk when it was first created, even if a task's priority was changed using chg_pri, then that task exits using ext_tsk, but later started by sta_tsk. Task priority does not return to what it was when ext_tsk was executed. - - -@c -@c exd_tsk -@c - -@page -@subsection exd_tsk - Exit and Delete Issuing Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void exd_tsk(void); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state) - - * System call may detect the following error. The error is not returned to the context issuing the system call even. Error codes therefore cannot be returned directly as a return parameter of the system call. The behavior on error detection is implementation dependent. - -@subheading DESCRIPTION: -This system call causes the issuing task to exit and then delete itself. In other words the state of the issuing task changes into the NON-EXISTENT (a virtual state not existing on the system). - -@subheading NOTES: -When a task exits with exd_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had secured prior to the call. It is the user's responsibility to see to it that all resources are released beforehand. - -Exd_tsk is a system call which does not return any parameters to the original issuing context. Accordingly, even if an error code is returned on detection of some error, it is normal for tasks making this system call not to perform any error checking, and it is in fact possible that a program could run out of control. For this reason, even if an error is detected upon making this system call, it is supposed that the error is not returned to the task which issued the system call. If information on detected errors is required it should be left in a messagebuffer used as an error log. - - -@c -@c ter_tsk -@c - -@page -@subsection ter_tsk - Terminate Other Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ter_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the target task is already in DORMANT state or a task invalidly specified itself) - -@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 - -@subheading DESCRIPTION: -This system call forcibly terminates the task specified by tskid. That is, it changes the state of the task specified by tskid into DORMANT. - -Even if the target task is in wait state (including SUSPEND state), its wait state will be released and then it will be terminated. If the target task is on a queue of some sort (such as waiting for a semaphore), it will be removed from that queue by ter_tsk. - -A task cannot specify the issuing task in this system call. An E_OBJ error will result if a task specifies itself. - -There is an intermediate state waiting for the response (TR packet or TA packet) from the target node after executing the system call to access the other node and making a request (sending a TP packet) to the node. This state is called the "connection function response wait (TTW_NOD)" state. The ter_tsk system call may specify tasks which are in the connection function response wait state. Tasks which are waiting for objects (such as a semaphore) on another node may also be specified to this system call. In such cases, ter_tsk will halt any system calls accessing other nodes which have been issued by the task to be terminated. - -@subheading NOTES: -When a task is terminated by ter_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had obtained prior to the call. It is the user's responsibility to see to it that all resources are released beforehand. - -In principle, information concerning a task recorded in the TCB, such as task priority, is reset whenever a task is placed in DORMANT state. For example, its task priority after being restarted would be reset to the initial task priority (itskpri) specified by cre_tsk when it was first created, even if a task's priority was changed using chg_pri, then that task is terminated by ter_tsk, but later started by sta_tsk. Task priority does not return to what it was when ter_tsk was executed. - - -@c -@c dis_dsp -@c - -@page -@subsection dis_dsp - Disable Dispatch - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER dis_dsp(void); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_CTX} - Context error (issued from task-independent portions or issued after execution of loc_cpu) - -@subheading DESCRIPTION: -This system call disables task dispatching. Dispatching will remain disabled after this call is issued until a subsequent call to ena_dsp is issued. The status of the issuing task will not be allowed to be changed to READY from the RUN. It cannot be changed into WAIT, either. However, since external interrupt is not disabled, interrupt handlers are allowed to run even when dispatching has been disabled. While an executing task may be preempted by an interrupt handler with dispatching disabled, there is no possibility that it will be preempted by another task. - -The following operations occur during the time dispatching is disabled. -@itemize @bullet -@item Even in a situation where normally a task issuing dis_dsp should be preempted by a system call issued by an interrupt handler or by the task issuing dis_dsp, the task that should normally be executed is not dispatched. Instead, dispatching of this task is delayed until dispatch disabled state is cleared by ena_dsp. - -@item If an interrupt handler invoked during dispatch disabled state issues sus_tsk for a running task (one that executed dis_dsp) to put it in SUSPEND state, or ter_tsk to put it in DORMANT state, the task transition is delayed until dispatch disabled state is cleared. - -@item An E_CTX error will result if the task which has executed dis_dsp issues any system calls (such as slp_tsk or wai_sem) capable of putting an issuing task into WAIT state. - -@item An EN_CTXID error will result if a task which has executed dis_dsp attempts to operate on objects on another node (that is, if the ID parameter of the system call issued refers to an object on another node). - -@item TSS_DDSP will be returned as sysstat if system status is referenced using ref_sys. -@end itemize -No error will result if a task already in dispatch disable state issues dis_dsp. It only keeps dispatch disabled state. No matter how many times dis_dsp has been issued, a single ena_dsp enables dispatching again. It is therefore for the user to determine what to do with nested pairs of dis_dsp and ena_dsp. - -An E_CTX error will result if dis_dsp is issued when both interrupt and dispatching are disabled with loc_cpu. (For details, see the description of loc_cpu.) - -@subheading NOTES: -A running task cannot enter DORMANT or NON-EXISTENT state while dispatching is disabled. An E_CTX error will result if an running task issues either ext_tsk or exd_tsk while interrupt and dispatching are disabled. Note however that since both ext_tsk and exd_tsk are system calls which do not return to their original contexts, error notification using return parameters of these system calls is not possible. If information on detected errors is required it should be left in a messagebuffer used as an error log. - -Only if the system is not a multiprocessor configuration, system can take advantage of the dispatch disabled state for exclusive inter-task control. - - -@c -@c ena_dsp -@c - -@page -@subsection ena_dsp - Enable Dispatch - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ena_dsp(void); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_CTX} - Context error (issued from task-independent portions or issued after execution of loc_cpu) - -@subheading DESCRIPTION: -This system call enables task dispatching, that is, it finishes dispatch disabled state caused by the execution of dis_dsp. - -No error will result if a task which is not in dispatch disabled state issues ena_dsp. In this case, dispatching will just remain enabled. - -An E_CTX error will result if ena_dsp is issued when both interrupt and dispatching are disabled with loc_cpu. (For details, see the description of loc_cpu.) - -@subheading NOTES: - - -@c -@c chg_pri -@c - -@page -@subsection chg_pri - Change Task Priority - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER chg_pri( - ID tskid, - PRI tskpri -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (the value of tskpri is invalid or may not be used) - -@code{E_OBJ} - Invalid object state (the target task is in DORMANT state) - -@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 tskpri) - -@subheading DESCRIPTION: -This system call changes the current priority of the task specified by tskid to the value specified by tskpri. - -Under uITRON 3.0 specification, at least any value of 1 through 8 can be specified as task priority. The smaller the value, the higher the priority. Priority levels -4 through 0 are reserved, and they may not be used. Priority levels outside this range (including negative values) may also be specified depending on the implementation; this is considered an extended function [level X] for which compatibility and connectivity are not guaranteed. In general, negative priority levels are reserved for use by the system. - -A 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 to a system call issued from a task-independent portion. The priority set by this system call remains in effect until the task exits. Once a task enters DORMANT state, its priority prior to exiting is lost. When a task which enters DORMANT state restarts, the initial task priority (itskpri) specified at task creation or at system startup will be used. - -If the target task is linked to ready queue or any other queue, this system call may result in the re-ordering of the queues. If chg_pri is executed on a task waiting on the ready queue (including tasks in RUN state) or other priority-based queue, the target task will be moved to the end of the part of the queue for the associated priority. If the priority specified is the same as the current priority, the task will still be moved behind other tasks of the same priority. It is therefore possible for a task to relinquish its execution privileges using chg_pri on itself by specifying its current priority. - -@subheading NOTES: -Depending on the implementation, specifying tskpri = TPRI_INI = 0 may cause a task's priority to be reset to the initial task priority (itskpri) which was defined when it was first created or when the system started. This feature is used in some implementations in order to reset the task priority to its original value after setting it to a higher value for indivisible processing. This feature is an extended function [level X] for which compatibility and connectivity are not guaranteed. - - -@c -@c rot_rdq -@c - -@page -@subsection rot_rdq - Rotate Tasks on the Ready Queue - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rot_rdq( - PRI tskpri -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_PAR} - Parameter error (the value of tskpri is invalid) - -@subheading DESCRIPTION: -This system call rotates tasks on the ready queue associated with the priority level specified by tskpri. Specifically, the task at the head of the ready queue of the priority level in question is moved to the end of the ready queue, thus switching the execution of tasks having the same priority. Round robin scheduling may be implemented by periodically issuing this system call in a given period of time. - -When rot_rdq is issued by task portions with tskpri = TPRI_RUN = 0, the ready queue with the priority level of the issuing task is rotated. - -When TPRI_RUN or a task's own priority level are specified for tskpri to rot_rdq, the task issuing the system call will be placed on the end of its ready queue. In other words, task can issue rot_rdq to relinquishing its execution privileges. The concept of "ready queue" envisioned in the description of this system call is one which includes the task in RUN state. - -This system call does nothing if there are no tasks on the ready queue of the specified priority. No error will result. - -This system call cannot rotate ready queues on other nodes. - -@subheading NOTES: -Depending on the implementation, it may be possible to issue rot_rdq(tskpri = TPRI_RUN) from task-independent portions, such as a cyclic handler. In this case the ready queue including the running task, or the ready queue including the highest priority task, is rotated. Normally these two are the same, but not always, as when task dispatching is delayed. In that case it is implementation dependent whether to rotate the ready queue including the running task or the ready queue including the highest priority task. Note that this is an extended function [Level X] for which compatibility and connectivity are not guaranteed. - - -@c -@c rel_wai -@c - -@page -@subsection rel_wai - Release Wait of Other Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rel_wai( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the target task is not in WAIT state (including when it is in DORMANT state or when the issuing task specifies itself)) - -@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 - -@subheading DESCRIPTION: -This system call forcibly releases WAIT state (not including SUSPEND state) -of the task specified by tskid. - -An E_RLWAI error is returned to the task whose WAIT state has been released using rel_wai. - -Wait release requests by rel_wai are not queued. In other words, if the task specified by tskid is already in WAIT state, the WAIT state is released, otherwise an E_OBJ error will be returned to the issuer. An E_OBJ error will also result when a task specifies itself to this system call. - -Rel_wai does not release SUSPEND state. If rel_wai is issued on a task in WAIT-SUSPEND state, WAIT will be released but SUSPEND will continue for that task. When SUSPEND should also be released, the frsm_tsk system call must be issued separately. - -@subheading NOTES: -A function similar to timeout can be implemented using an alarm handler which issues this system call on tasks specified time after they have entered WAIT state. - -Rel_wai and wup_tsk differ in the following points. -@itemize @bullet -@item Wup_tsk can only release the WAIT state by slp_tsk or tslp_tsk, while rel_wai can release WAIT states caused by these and other calls (including wai_flg, wai_sem, rcv_msg, get_blk, etc.). -@item As seen from the target task, releasing WAIT state with wup_tsk results in a normal completion (E_OK), whereas releasing WAIT state with rel_wai results in an error (E_RLWAI). -@item When wup_tsk is used, a request is queued even if neither slp_tsk nor tslp_tsk have been executed on the target task yet. When rel_wai is used to the task which is not in WAIT state, an E_OBJ error will result. -@end itemize - - -@c -@c get_tid -@c - -@page -@subsection get_tid - Get Task Identifier - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER get_tid( - ID *p_tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@subheading DESCRIPTION: -This system call gets the ID of the issuing task. - -If this system call is issued from a task-independent portion, tskid will be FALSE=0. - -@subheading NOTES: - - -@c -@c ref_tsk -@c - -@page -@subsection ref_tsk - Reference Task Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_tsk( - T_RTSK *pk_rtsk, - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_PAR} - Parameter error (the packet address for return parameters cannot 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 return parameter (a value outside supported range was returned for exinf, tskpri and/or tskstat) - -@subheading DESCRIPTION: -This system call refers to the state of the task specified by tskid, and returns its current priority (tskpri), its task state (tskstat), and its extended information (exinf). - -Tskstat may take the following values. - - tskstat: -@itemize @bullet -@item TTS_RUN H'0...01 RUN state (currently running) -@item TTS_RDY H'0...02 READY state (ready to run) -@item TTS_WAI H'0...04 WAIT state (waiting for something) -@item TTS_SUS H'0...08 SUSPEND state (forcibly made to wait) -@item TTS_WAS H'0...0c WAIT-SUSPEND state -@item TTS_DMT H'0...10 DORMANT state -@end itemize - -Since these task states are expressed by bit correspondences they are convenient when looking for OR conditions (such as whether a task is in RUN or READY state). TTS_WAS is a combination of both TTS_SUS and TTS_WAI, TTS_SUS does not combine with any of the other states (TTS_RUN, TTS_RDY or TTS_DMT). - -A 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. - -An E_NOEXS error will result if the task specified to ref_tsk does not exist. - -Tskstat will be TTS_RUN if ref_tsk is executed specifying a task which has been interrupted by an interrupt handler. - -@subheading NOTES: -The values of TTS_RUN, TTS_RDY, TTS_WAI, etc. as return values for tskstat are not necessarily the same value to be entered in the TCB. The way in which task state is represented in the TCB is implementation dependent. When ref_tsk is executed, the internal representation of task state may simply be converted to the standard values TTS_RUN, TTS_RDY, TTS_WAI, etc. - -Depending on the implementation, the following additional information can also be referenced in addition to exinf, tskpri and tskstat. - -@itemize @bullet -@item tskwait Reason for wait -@item wid Wait object ID -@item wupcnt Number of queued wakeup requests -@item suscnt Number of nested SUSPEND requests -@item tskatr Task attributes -@item task Task starting address -@item itskpri Initial task priority -@item stksz Stack size -@end itemize - - - - - diff --git a/doc/itron3.0/tasksync.t b/doc/itron3.0/tasksync.t deleted file mode 100644 index 8db2ca30ec..0000000000 --- a/doc/itron3.0/tasksync.t +++ /dev/null @@ -1,388 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the task-dependent synchronization -@c manager. -@c -@c $Id$ -@c - -@chapter Task-Dependent Synchronization Manager - -@section Introduction - -The task-dependent synchronization manager is designed to utilize those synchronization -functions 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. - -The services provided by the task-dependent synchronization manager are: - -@itemize @bullet -@item @code{sus_tsk} - Suspend Other Task -@item @code{rsm_tsk} - Resume Suspended Task -@item @code{frsm_tsk} - Forcibly Resume Suspended Task -@item @code{slp_tsk} - Sleep Task -@item @code{tslp_tsk} - Sleep Task with Timeout -@item @code{wup_tsk} - Wakeup Other Task -@item @code{can_wup} - Cancel Wakeup Request -@end itemize - -@section Operations -@subsection Suspend Other Task -This 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. - -@subsection Resume Suspended Task -This 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. - -@subsection Forcibly Resume Suspended Task -This 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. - -@subsection Sleep Task -The 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. - -@subsection Sleep Task with Timeout -This 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. - -@subsection Wakeup Other Task -The 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. - -@subsection Cancel Wakeup Request -This 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. - -@section System Calls - -This 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. - - -@c -@c sus_tsk -@c - -@page -@subsection sus_tsk - Suspend Other Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER sus_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself) - -@code{E_QOVR} - Queuing or nesting overflow (the number of nesting levels given by suscnt went over the maximum allowed) - -@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 - -@subheading DESCRIPTION: -This system call suspends the execution of the task specified by tskid by putting it into SUSPEND state. - -SUSPEND 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. - -Since 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. - -If 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. - -The 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. - -An 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. - -@subheading NOTES: -A 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. - -@c -@c rsm_tsk -@c - -@page -@subsection rsm_tsk - Resume Suspended Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER rsm_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@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)) - -@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 - -@subheading DESCRIPTION: -This 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. - -A task cannot specify itself to this system call. An E_OBJ error will result if a task specifies itself. - -Rsm_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. - -@subheading NOTES: -It 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. - -@c -@c frsm_tsk -@c - -@page -@subsection frsm_tsk - Forcibly Resume Suspended Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =frsm_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@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)) - -@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 - -@subheading DESCRIPTION: -This 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. - -A task cannot specify itself to this system call. An E_OBJ error will result if a task specifies itself. - -Frsm_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. - -@subheading NOTES: -It 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. - - -@c -@c slp_tsk -@c - -@page -@subsection slp_tsk - Sleep Task Sleep Task with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER slp_tsk( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_PAR} - Parameter error (a timeout value -2 or less was specified) - -@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) - -@subheading DESCRIPTION: - -This 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. - -@subheading NOTES: -Since 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. - -No polling function for slp_tsk is provided. A similar function can be implemented if necessary using can_wup. - -@c -@c tslp_tsk -@c - -@page -@subsection tslp_tsk - Sleep Task with Timeout - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ercd =tslp_tsk( - TMO tmout -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_PAR} - Parameter error (a timeout value -2 or less was specified) - -@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) - -@subheading DESCRIPTION: -The 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. - -@subheading NOTES: -Since 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. - -If you simply wish to delay a task (make it wait for a while), use dly_tsk rather than tslp_tsk. - -@c -@c wup_tsk -@c - -@page -@subsection wup_tsk - Wakeup Other Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER wup_tsk( - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself) - -@code{E_QOVR} - Queuing or nesting overflow (wakeup request queuing count will exceed the maximum value allowed for wupcnt) - -@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 - -@subheading DESCRIPTION: -This system call releases the WAIT state of the task specified by tskid caused by the execution of slp_tsk or tslp_tsk. - -A task cannot specify itself in this system call. An E_OBJ error will result if a task specifies itself. - -If 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. - -@subheading NOTES: -Wakeup 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. - -It 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. - -An E_QOVR error will result if wup_tsk is issued more than the maximum value allowed for the wakeup request queuing count (wupcnt). - - -@c -@c can_wup -@c - -@page -@subsection can_wup - Cancel Wakeup Request - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER can_wup( - INT *p_wupcnt, - ID tskid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{E_OK} - Normal Completion - -@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used) - -@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist) - -@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.) - -@code{E_OBJ} - Invalid object state (the target task is in DORMANT state) - -@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 issuing node and/or transmission packet format was returned as a return parameter (a value outside supported range was returned for wupcnt) - -@subheading DESCRIPTION: -This 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. - -A 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. - -@subheading NOTES: -An 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. - -This 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. - - diff --git a/doc/itron3.0/time.t b/doc/itron3.0/time.t deleted file mode 100644 index c542889cbd..0000000000 --- a/doc/itron3.0/time.t +++ /dev/null @@ -1,310 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c This is the chapter from the RTEMS ITRON User's Guide that -@c documents the services provided by the time -@c manager. -@c -@c $Id$ -@c - -@chapter Time Manager - -@section Introduction - -The -time manager is ... - -The services provided by the time manager are: - -@itemize @bullet -@item @code{get_tim} - Get System Clock -@item @code{set_tim} - Set System Clock -@item @code{dly_tsk} - Delay Task -@item @code{def_cyc} - Define Cyclic Handler -@item @code{act_cyc} - Activate Cyclic Handler -@item @code{ref_cyc} - Reference Cyclic Handler Status -@item @code{def_alm} - Define Alarm Handler -@item @code{ref_alm} - Reference Alarm Handler Status -@item @code{ret_tmr} - Return from Timer Handler -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the time 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. - - -@c -@c get_tim -@c - -@page -@subsection get_tim - Get System Clock - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER get_tim( - SYSTIME *pk_tim -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c set_tim -@c - -@page -@subsection set_tim - Set System Clock - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER set_tim( - SYSTIME *pk_tim -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c dly_tsk -@c - -@page -@subsection dly_tsk - Delay Task - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER dly_tsk( - DLYTIME dlytim -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c def_cyc -@c - -@page -@subsection def_cyc - Define Cyclic Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER def_cyc( - HNO cycno, - T_DCYC *pk_dcyc -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c act_cyc -@c - -@page -@subsection act_cyc - Activate Cyclic Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER act_cyc( - HNO cycno, - UINT cycact -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_cyc -@c - -@page -@subsection ref_cyc - Reference Cyclic Handler Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_cyc( - T_RCYC *pk_rcyc, - HNO cycno -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c def_alm -@c - -@page -@subsection def_alm - Define Alarm Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER def_alm( - HNO almno, - T_DALM *pk_dalm -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ref_alm -@c - -@page -@subsection ref_alm - Reference Alarm Handler Status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -ER ref_alm( - T_RALM *pk_ralm, - HNO almno -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c ret_tmr -@c - -@page -@subsection ret_tmr - Return from Timer Handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void ret_tmr( - -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/itron3.0/version.texi b/doc/itron3.0/version.texi deleted file mode 100644 index a77d339def..0000000000 --- a/doc/itron3.0/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 27 June 2007 -@set UPDATED-MONTH June 2007 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 |