diff options
| author | Joel Sherrill <joel.sherrill@OARcorp.com> | 1997-05-27 12:40:11 +0000 |
|---|---|---|
| committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 1997-05-27 12:40:11 +0000 |
| commit | ae68ff085724dd35d60151bd153e80b8b0776873 (patch) | |
| tree | 2f1535a0497f5b872a4744ae13c9264b77e89c11 /doc | |
| parent | b65131dc23672b24c32d76081c5917f2f38d93fe (diff) | |
| download | rtems-ae68ff085724dd35d60151bd153e80b8b0776873.tar.bz2 | |
Initial revision
Diffstat (limited to 'doc')
198 files changed, 44720 insertions, 0 deletions
diff --git a/doc/HELP.html b/doc/HELP.html new file mode 100644 index 0000000000..12c75e3024 --- /dev/null +++ b/doc/HELP.html @@ -0,0 +1,23 @@ +<HTML> +<HEAD><TITLE>RTEMS On-Line Library</TITLE></HEAD> +<BODY BGCOLOR="FFFFFF"> +<A HREF="http://www.oarcorp.com" target="Text Frame"> + <IMG align=right BORDER=0 SRC="oaronly.jpg" ALT="OAR"> </A> +<FONT SIZE=-1> +<H1>RTEMS On-Line Library</H1> +<HR> +<BODY> +The following supplement manuals do not currently exist: +<MENU> + <LI>RTEMS AMD 29K C Applications Supplement</LI> + <LI>RTEMS MIPS C Applications Supplement</LI> + <LI>RTEMS PowerPC C Applications Supplement</LI> + <LI>RTEMS UNIX Port C Applications Supplement</LI> +</MENU> +If you have knowledge of the processors used in the above ports and +want to contribute to RTEMS, please contact +<A HREF="mailto:rtems@OARcorp.com"><I>rtems@OARcorp.com</I></A> + +<HR> +Copyright © 1996 <A HREF="http://www.oarcorp.com" target="Text Frame">OAR Corporation</A> +</BODY></HTML> diff --git a/doc/Make.config b/doc/Make.config new file mode 100644 index 0000000000..6f2665f9d6 --- /dev/null +++ b/doc/Make.config @@ -0,0 +1,18 @@ +# +# Paths which may change +# + +TEXI2DVI=/usr1/tmp/texi2www-960103/texi2dvi +TEXI2WWW=/usr1/tmp/texi2www-960103/texi2www +MAKEINFO=makeinfo +INFO=info +XDVI=xdvi -s 4 +GHOSTVIEW=ghostview -magstep -1 + +WWW_INSTALL=/usr1/tmp/rtemsdoc-4.0.0/html +INFO_INSTALL=/usr1/tmp/rtemsdoc-4.0.0/info +PS_INSTALL=/usr1/tmp/rtemsdoc-4.0.0/ps + +TEXI2WWW_ARGS=-dirfile ../rtems.html \ + -header ../rtems_header.html \ + -footer ../rtems_footer.html diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000..9db3b61819 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,24 @@ + +include Make.config + +BASEDIR=$(shell pwd) + +all: info html ps +# find $(WWW_INSTALL) -type f | xargs -e chmod 444 +# find $(WWW_INSTALL) -type d | xargs -e chmod 555 + +info: + ./do_docs $(BASEDIR) info + +html: + cp common/*.gif common/*.jpg $(WWW_INSTALL) + cp rtems.html HELP.html $(WWW_INSTALL) + ./do_docs $(BASEDIR) html + +ps: + ./do_docs $(BASEDIR) ps + +clean: + ./do_docs $(BASEDIR) clean + + diff --git a/doc/README b/doc/README new file mode 100644 index 0000000000..610bd756f4 --- /dev/null +++ b/doc/README @@ -0,0 +1,33 @@ + +Tools Required +============== +The following tools are used in the production of this documentation: + +TeX +texinfo 3.7 +texi2www-960103 + +This was used by the authors to generate the directory tree figure +in the texinfo printed version: + +tree (from the CTAN Archives -- see http://jasper.ora.com/ctan.html) + +Installation +============ +1. Edit replace-word so it references perl in the correct location. + +2. Edit Make.config and localize it. + +3. Edit do_docs and fix basedir + +4. Create the installation point for the html and info files. + +5. Copy texi2www gif files into the main rtems html install directory. + + +Use do_docs to: + +do_docs info +do_docs html +do_docs clean + diff --git a/doc/archgrey.gif b/doc/archgrey.gif Binary files differnew file mode 100644 index 0000000000..d315b028f2 --- /dev/null +++ b/doc/archgrey.gif diff --git a/doc/common/cpright.texi b/doc/common/cpright.texi new file mode 100644 index 0000000000..166ac869e1 --- /dev/null +++ b/doc/common/cpright.texi @@ -0,0 +1,42 @@ +@c +@c COPYRIGHT (c) 1996-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c The following puts a space somewhere on an otherwise empty page so we +@c can force the copyright description onto a left hand page. +@c + +@tex +{\parskip=0pt \hfill On-Line Applications Research Corporation\par \hfill +\TeX{}info \texinfoversion\par } +@end tex + +@vskip 0pt plus 1filll +COPYRIGHT @copyright{} 1989 - 1997.@* +On-Line Applications Research Corporation (OAR).@* + +The authors have used their best efforts in preparing +this material. These efforts include the development, research, +and testing of the theories and programs to determine their +effectiveness. No warranty of any kind, expressed or implied, +with regard to the software or the material contained in this +document is provided. No liability arising out of the +application or use of any product described in this document is +assumed. The authors reserve the right to revise this material +and to make changes from time to time in the content hereof +without obligation to notify anyone of such revision or changes. + +Any inquiries concerning RTEMS, its related support +components, or its documentation should be directed to either: + +@example +On-Line Applications Research Corporation +4910-L Corporate Drive +Huntsville, AL 35805 +VOICE: (205) 722-9985 +EMAIL: rtems@@OARcorp.com +@end example + diff --git a/doc/common/missing-arrow.gif b/doc/common/missing-arrow.gif Binary files differnew file mode 100644 index 0000000000..c686c80b5f --- /dev/null +++ b/doc/common/missing-arrow.gif diff --git a/doc/common/next-arrow.gif b/doc/common/next-arrow.gif Binary files differnew file mode 100644 index 0000000000..57f5cddb81 --- /dev/null +++ b/doc/common/next-arrow.gif diff --git a/doc/common/oaronly.jpg b/doc/common/oaronly.jpg Binary files differnew file mode 100644 index 0000000000..c87c151404 --- /dev/null +++ b/doc/common/oaronly.jpg diff --git a/doc/common/prev-arrow.gif b/doc/common/prev-arrow.gif Binary files differnew file mode 100644 index 0000000000..350785be10 --- /dev/null +++ b/doc/common/prev-arrow.gif diff --git a/doc/common/setup.texi b/doc/common/setup.texi new file mode 100644 index 0000000000..a82bd0b78d --- /dev/null +++ b/doc/common/setup.texi @@ -0,0 +1,69 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Set Variables +@c + +@set RTEMS-RELEASE 4.0.0 + +@c +@c The following determines which set of the tables and figures we will use. +@c We default to ASCII but if available TeX or HTML versions will +@c be used instead. +@c + +@set use-ascii +@clear use-html +@clear use-tex + +@iftex +@clear use-ascii +@clear use-html +@set use-tex +@end iftex + +@ifhtml +@clear use-ascii +@clear use-tex +@set use-html +@end ifhtml + +@c +@c The following variable says to use texinfo or html for the two column +@c texinfo tables. For somethings the format does not look good in html. +@c With our adjustment to the left column in TeX, it nearly always looks +@c good printed. +@c +@ifset use-ascii +@set use-texinfo-tables +@end ifset +@ifset use-tex +@set use-texinfo-tables +@end ifset +@ifset use-html +@clear use-texinfo-tables +@end ifset + +@c +@c Custom whitespace adjustments. We could fiddle a bit more. +@c +@tex +\global\parindent 0in +\global\chapheadingskip = 15pt plus 4pt minus 2pt +\global\secheadingskip = 12pt plus 4pt minus 2pt +\global\subsecheadingskip = 9pt plus 4pt minus 2pt +\global\hbadness = 10000 +\global\tolerance = 6000 +\global\tableindent = 1.5in +\global\itemindent = 0.5in + +@ifclear smallbook +\global\parskip 6pt plus 1pt +@end ifclear +@end tex + + diff --git a/doc/common/timemac.texi b/doc/common/timemac.texi new file mode 100644 index 0000000000..9aa340c307 --- /dev/null +++ b/doc/common/timemac.texi @@ -0,0 +1,34 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c +@c Macros to help with the tables in this file +@c + +@tex +\global\advance \smallskipamount by -4pt + +\global\def\rtemstimetable{ +\vrule\strut##& +\hbox to 3.0in{\enskip##\hfil}& +\hbox to 0.75in{\enskip##\hfil}& +\vrule##\cr +\noalign{\hrule} +} + +\global\def\rtemsendtimetable{} +\global\def\rtemsonecase#1#2{ +& \bf #1\hfil& #2 & \cr\noalign{\hrule} +} + +\global\def\rtemsdirective#1{ +& \bf #1 \hfil& & \cr\noalign{\hrule} +} + +\global\def\rtemscase#1#2{ +& \hskip 0.3in #1\hfil& #2 & \cr\noalign{\hrule} +} + +@end tex diff --git a/doc/common/timetbl.t b/doc/common/timetbl.t new file mode 100644 index 0000000000..29906011ee --- /dev/null +++ b/doc/common/timetbl.t @@ -0,0 +1,1364 @@ +@c +@c Time Table Template +@c + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{No Floating Point Contexts}{RTEMS_NO_FP_CONTEXTS} +\rtemsdirective{Floating Point Contexts} +\rtemscase{restore first FP task}{RTEMS_RESTORE_1ST_FP_TASK} +\rtemscase{save initialized, restore initialized}{RTEMS_SAVE_INIT_RESTORE_INIT} +\rtemscase{save idle, restore initialized}{RTEMS_SAVE_IDLE_RESTORE_INIT} +\rtemscase{save idle, restore idle}{RTEMS_SAVE_IDLE_RESTORE_IDLE} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet +@item No Floating Point Contexts +@itemize - +@item only case: RTEMS_NO_FP_CONTEXTS +@end itemize +@item Floating Point Contexts +@itemize - +@item restore first FP task: RTEMS_RESTORE_1ST_FP_TASK +@item save initialized, restore initialized: RTEMS_SAVE_INIT_RESTORE_INIT +@item save idle, restore initialized: RTEMS_SAVE_IDLE_RESTORE_INIT +@item save idle, restore idle: RTEMS_SAVE_IDLE_RESTORE_INIT +@end itemize +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>No Floating Point Contexts</STRONG></TD> + <TD ALIGN=center>RTEMS_NO_FP_CONTEXTS</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>Floating Point Contexts</TR> + <TR><TD ALIGN=left><dd>restore first FP task</TD> + <TD ALIGN=center>RTEMS_RESTORE_1ST_FP_TASK</TD> + <TR><TD ALIGN=left><dd>save initialized, restore initialized</TD> + <TD ALIGN=center>RTEMS_SAVE_INIT_RESTORE_INIT</TD> + <TR><TD ALIGN=left><dd>save idle, restore initialized</TD> + <TD ALIGN=center>RTEMS_SAVE_IDLE_RESTORE_INIT</TD> + <TR><TD ALIGN=left><dd>save idle, restore idle</TD> + <TD ALIGN=center>RTEMS_SAVE_IDLE_RESTORE_IDLE</TD> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Directive Times, RTEMS_CPU_MODEL Timing Data Task Manager, RTEMS_CPU_MODEL Timing Data Context Switch, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Directive Times + +This sections is divided into a number of +subsections, each of which contains a table listing the +execution times of that manager's directives. + +@page +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Task Manager, RTEMS_CPU_MODEL Timing Data Interrupt Manager, RTEMS_CPU_MODEL Timing Data Directive Times, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Task Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{TASK\_CREATE}{RTEMS_TASK_CREATE_ONLY} +\rtemsonecase{TASK\_IDENT}{RTEMS_TASK_IDENT_ONLY} +\rtemsonecase{TASK\_START}{RTEMS_TASK_START_ONLY} +\rtemsdirective{TASK\_RESTART} +\rtemscase{calling task}{RTEMS_TASK_RESTART_CALLING_TASK} +\rtemscase{suspended task -- returns to caller} + {RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER} +\rtemscase{blocked task -- returns to caller} + {RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER} +\rtemscase{ready task -- returns to caller} + {RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER} +\rtemscase{suspended task -- preempts caller} + {RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER} +\rtemscase{blocked task -- preempts caller} + {RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER} +\rtemscase{ready task -- preempts caller} + {RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER} +\rtemsdirective{TASK\_DELETE} +\rtemscase{calling task}{RTEMS_TASK_DELETE_CALLING_TASK} +\rtemscase{suspended task}{RTEMS_TASK_DELETE_SUSPENDED_TASK} +\rtemscase{blocked task}{RTEMS_TASK_DELETE_BLOCKED_TASK} +\rtemscase{ready task}{RTEMS_TASK_DELETE_READY_TASK} +\rtemsdirective{TASK\_SUSPEND} +\rtemscase{calling task}{RTEMS_TASK_SUSPEND_CALLING_TASK} +\rtemscase{returns to caller}{RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER} +\rtemsdirective{TASK\_RESUME} +\rtemscase{task readied -- returns to caller} + {RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER} +\rtemsdirective{TASK\_SET\_PRIORITY} +\rtemscase{obtain current priority} + {RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY} +\rtemscase{returns to caller}{RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER} +\rtemscase{preempts caller}{RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER} +\rtemsdirective{TASK\_MODE} +\rtemscase{obtain current mode}{RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE} +\rtemscase{no reschedule}{RTEMS_TASK_MODE_NO_RESCHEDULE} +\rtemscase{reschedule -- returns to caller} + {RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER} +\rtemscase{reschedule -- preempts caller} + {RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER} +\rtemsonecase{TASK\_GET\_NOTE}{RTEMS_TASK_GET_NOTE_ONLY} +\rtemsonecase{TASK\_SET\_NOTE}{RTEMS_TASK_SET_NOTE_ONLY} +\rtemsdirective{TASK\_WAKE\_AFTER} +\rtemscase{yield -- returns to caller} + {RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER} +\rtemscase{yield -- preempts caller} + {RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER} +\rtemsonecase{TASK\_WAKE\_WHEN}{RTEMS_TASK_WAKE_WHEN_ONLY} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item TASK_CREATE +@itemize - +@item only case: RTEMS_TASK_CREATE_ONLY +@end itemize + +@item TASK_IDENT +@itemize - +@item only case: RTEMS_TASK_IDENT_ONLY +@end itemize + +@item TASK_START +@itemize - +@item only case: RTEMS_TASK_START_ONLY +@end itemize + +@item TASK_RESTART +@itemize - +@item calling task: RTEMS_TASK_RESTART_CALLING_TASK +@item suspended task -- returns to caller: RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER +@item blocked task -- returns to caller: RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER +@item ready task -- returns to caller: RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER +@item suspended task -- preempts caller: RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER +@item blocked task -- preempts caller: RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER +@item ready task -- preempts caller: RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER +@end itemize + +@item TASK_DELETE +@itemize - +@item calling task: RTEMS_TASK_DELETE_CALLING_TASK +@item suspended task: RTEMS_TASK_DELETE_SUSPENDED_TASK +@item blocked task: RTEMS_TASK_DELETE_BLOCKED_TASK +@item ready task: RTEMS_TASK_DELETE_READY_TASK +@end itemize + +@item TASK_SUSPEND +@itemize - +@item calling task: RTEMS_TASK_SUSPEND_CALLING_TASK +@item returns to caller: RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER +@end itemize + +@item TASK_RESUME +@itemize - +@item task readied -- returns to caller: RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@item TASK_SET_PRIORITY +@itemize - +@item obtain current priority: RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY +@item returns to caller: RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER +@item preempts caller: RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER +@end itemize + +@item TASK_MODE +@itemize - +@item obtain current mode: RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE +@item no reschedule: RTEMS_TASK_MODE_NO_RESCHEDULE +@item reschedule -- returns to caller: RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER +@item reschedule -- preempts caller: RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER +@end itemize + +@item TASK_GET_NOTE +@itemize - +@item only case: RTEMS_TASK_GET_NOTE_ONLY +@end itemize + +@item TASK_SET_NOTE +@itemize - +@item only case: RTEMS_TASK_SET_NOTE_ONLY +@end itemize + +@item TASK_WAKE_AFTER +@itemize - +@item yield -- returns to caller: RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER +@item yield -- preempts caller: RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER +@end itemize + +@item TASK_WAKE_WHEN +@itemize - +@item only case: RTEMS_TASK_WAKE_WHEN_ONLY +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>TASK_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>TASK_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>TASK_START</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_START_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_RESTART</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>calling task</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_CALLING_TASK</TD></TR> + <TR><TD ALIGN=left><dd>suspended task -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>blocked task -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>ready task -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>suspended task -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>blocked task -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>ready task -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_DELETE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>calling task</TD> + <TD ALIGN=center>RTEMS_TASK_DELETE_CALLING_TASK</TD></TR> + <TR><TD ALIGN=left><dd>suspended task</TD> + <TD ALIGN=center>RTEMS_TASK_DELETE_SUSPENDED_TASK</TD></TR> + <TR><TD ALIGN=left><dd>blocked task</TD> + <TD ALIGN=center>RTEMS_TASK_DELETE_BLOCKED_TASK</TD></TR> + <TR><TD ALIGN=left><dd>ready task</TD> + <TD ALIGN=center>RTEMS_TASK_DELETE_READY_TASK</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_SUSPEND</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>calling task</TD> + <TD ALIGN=center>RTEMS_TASK_SUSPEND_CALLING_TASK</TD></TR> + <TR><TD ALIGN=left><dd>returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_RESUME</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_SET_PRIORITY</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>obtain current priority</TD> + <TD ALIGN=center>RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY</TD></TR> + <TR><TD ALIGN=left><dd>returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_MODE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>obtain current mode</TD> + <TD ALIGN=center>RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE</TD></TR> + <TR><TD ALIGN=left><dd>no reschedule</TD> + <TD ALIGN=center>RTEMS_TASK_MODE_NO_RESCHEDULE</TD></TR> + <TR><TD ALIGN=left><dd>reschedule -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>reschedule -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left><STRONG>TASK_GET_NOTE</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_GET_NOTE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>TASK_SET_NOTE</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_SET_NOTE_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TASK_WAKE_AFTER</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>yield -- returns to caller</TD> + <TD ALIGN=center>RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>yield -- preempts caller</TD> + <TD ALIGN=center>RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left><STRONG>TASK_WAKE_WHEN</STRONG></TD> + <TD ALIGN=center>RTEMS_TASK_WAKE_WHEN_ONLY</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@page +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Interrupt Manager, RTEMS_CPU_MODEL Timing Data Clock Manager, RTEMS_CPU_MODEL Timing Data Task Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Interrupt Manager + +It should be noted that the interrupt entry times +include vectoring the interrupt handler. + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsdirective{Interrupt Entry Overhead} +\rtemscase{returns to nested interrupt}{RTEMS_INTR_ENTRY_RETURNS_TO_NESTED} +\rtemscase{returns to interrupted task} + {RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK} +\rtemscase{returns to preempting task} + {RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK} +\rtemsdirective{Interrupt Exit Overhead} +\rtemscase{returns to nested interrupt}{RTEMS_INTR_EXIT_RETURNS_TO_NESTED} +\rtemscase{returns to interrupted task} + {RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK} +\rtemscase{returns to preempting task} + {RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item Interrupt Entry Overhead +@itemize - +@item returns to nested interrupt: RTEMS_INTR_ENTRY_RETURNS_TO_NESTED +@item returns to interrupted task: RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK +@item returns to preempting task: RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK +@end itemize + +@item Interrupt Exit Overhead +@itemize - +@item returns to nested interrupt: RTEMS_INTR_EXIT_RETURNS_TO_NESTED +@item returns to interrupted task: RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK +@item returns to preempting task: RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left COLSPAN=2><STRONG>Interrupt Entry Overhead</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>returns to nested interrupt</TD> + <TD ALIGN=center>RTEMS_INTR_ENTRY_RETURNS_TO_NESTED</TD></TR> + <TR><TD ALIGN=left><dd>returns to interrupted task</TD> + <TD ALIGN=center>RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK</TD></TR> + <TR><TD ALIGN=left><dd>returns to preempting task</TD> + <TD ALIGN=center>RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>Interrupt Exit Overhead</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>returns to nested interrupt</TD> + <TD ALIGN=center>RTEMS_INTR_EXIT_RETURNS_TO_NESTED</TD></TR> + <TR><TD ALIGN=left><dd>returns to interrupted task</TD> + <TD ALIGN=center>RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK</TD></TR> + <TR><TD ALIGN=left><dd>returns to preempting task</TD> + <TD ALIGN=center>RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Clock Manager, RTEMS_CPU_MODEL Timing Data Timer Manager, RTEMS_CPU_MODEL Timing Data Interrupt Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Clock Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{CLOCK\_SET}{RTEMS_CLOCK_SET_ONLY} +\rtemsonecase{CLOCK\_GET}{RTEMS_CLOCK_GET_ONLY} +\rtemsonecase{CLOCK\_TICK}{RTEMS_CLOCK_TICK_ONLY} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item CLOCK_SET +@itemize - +@item only case: RTEMS_CLOCK_SET_ONLY +@end itemize + +@item CLOCK_GET +@itemize - +@item only case: RTEMS_CLOCK_GET_ONLY +@end itemize + +@item CLOCK_TICK +@itemize - +@item only case: RTEMS_CLOCK_TICK_ONLY +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>CLOCK_SET</STRONG></TD> + <TD ALIGN=center>RTEMS_CLOCK_SET_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>CLOCK_GET</STRONG></TD> + <TD ALIGN=center>RTEMS_CLOCK_GET_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>CLOCK_TICK</STRONG></TD> + <TD ALIGN=center>RTEMS_CLOCK_TICK_ONLY</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Timer Manager, RTEMS_CPU_MODEL Timing Data Semaphore Manager, RTEMS_CPU_MODEL Timing Data Clock Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Timer Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{TIMER\_CREATE}{RTEMS_TIMER_CREATE_ONLY} +\rtemsonecase{TIMER\_IDENT}{RTEMS_TIMER_IDENT_ONLY} +\rtemsdirective{TIMER\_DELETE} +\rtemscase{inactive}{RTEMS_TIMER_DELETE_INACTIVE} +\rtemscase{active}{RTEMS_TIMER_DELETE_ACTIVE} +\rtemsdirective{TIMER\_FIRE\_AFTER} +\rtemscase{inactive}{RTEMS_TIMER_FIRE_AFTER_INACTIVE} +\rtemscase{active}{RTEMS_TIMER_FIRE_AFTER_ACTIVE} +\rtemsdirective{TIMER\_FIRE\_WHEN} +\rtemscase{inactive}{RTEMS_TIMER_FIRE_WHEN_INACTIVE} +\rtemscase{active}{RTEMS_TIMER_FIRE_WHEN_ACTIVE} +\rtemsdirective{TIMER\_RESET} +\rtemscase{inactive}{RTEMS_TIMER_RESET_INACTIVE} +\rtemscase{active}{RTEMS_TIMER_RESET_ACTIVE} +\rtemsdirective{TIMER\_CANCEL} +\rtemscase{inactive}{RTEMS_TIMER_CANCEL_INACTIVE} +\rtemscase{active}{RTEMS_TIMER_CANCEL_ACTIVE} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item TIMER_CREATE +@itemize - +@item only case: RTEMS_TIMER_CREATE_ONLY +@end itemize + +@item TIMER_IDENT +@itemize - +@item only case: RTEMS_TIMER_IDENT_ONLY +@end itemize + +@item TIMER_DELETE +@itemize - +@item inactive: RTEMS_TIMER_DELETE_INACTIVE +@item active: RTEMS_TIMER_DELETE_ACTIVE +@end itemize + +@item TIMER_FIRE_AFTER +@itemize - +@item inactive: RTEMS_TIMER_FIRE_AFTER_INACTIVE +@item active: RTEMS_TIMER_FIRE_AFTER_ACTIVE +@end itemize + +@item TIMER_FIRE_WHEN +@itemize - +@item inactive: TIMER_FIRE_WHEN_INACTIVE +@item active: TIMER_FIRE_WHEN_ACTIVE +@end itemize + +@item TIMER_RESET +@itemize - +@item inactive: TIMER_RESET_INACTIVE +@item active: TIMER_RESET_ACTIVE +@end itemize + +@item TIMER_CANCEL +@itemize - +@item inactive: TIMER_CANCEL_INACTIVE +@item active: TIMER_CANCEL_ACTIVE +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>TIMER_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_TIMER_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>TIMER_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_TIMER_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TIMER_DELETE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_TIMER_DELETE_INACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_TIMER_DELETE_ACTIVE</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TIMER_FIRE_AFTER</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_TIMER_FIRE_AFTER_INACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_TIMER_FIRE_AFTER_ACTIVE</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TIMER_FIRE_WHEN</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_TIMER_FIRE_WHEN_INACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_TIMER_FIRE_WHEN_ACTIVE</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TIMER_RESET</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_TIMER_RESET_INACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_TIMER_RESET_ACTIVE</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>TIMER_CANCEL</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_TIMER_CANCEL_INACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_TIMER_CANCEL_ACTIVE</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@page +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Semaphore Manager, RTEMS_CPU_MODEL Timing Data Message Manager, RTEMS_CPU_MODEL Timing Data Timer Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Semaphore Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{SEMAPHORE\_CREATE}{RTEMS_SEMAPHORE_CREATE_ONLY} +\rtemsonecase{SEMAPHORE\_IDENT}{RTEMS_SEMAPHORE_IDENT_ONLY} +\rtemsonecase{SEMAPHORE\_DELETE}{RTEMS_SEMAPHORE_DELETE_ONLY} +\rtemsdirective{SEMAPHORE\_OBTAIN} +\rtemscase{available}{RTEMS_SEMAPHORE_OBTAIN_AVAILABLE} +\rtemscase{not available -- NO\_WAIT} + {RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT} +\rtemscase{not available -- caller blocks} + {RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS} +\rtemsdirective{SEMAPHORE\_RELEASE} +\rtemscase{no waiting tasks}{RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS} +\rtemscase{task readied -- returns to caller} + {RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item SEMAPHORE_CREATE +@itemize - +@item only case: RTEMS_SEMAPHORE_CREATE_ONLY +@end itemize + +@item SEMAPHORE_IDENT +@itemize - +@item only case: RTEMS_SEMAPHORE_IDENT_ONLY +@end itemize + +@item SEMAPHORE_DELETE +@itemize - +@item only case: RTEMS_SEMAPHORE_DELETE_ONLY +@end itemize + +@item SEMAPHORE_OBTAIN +@itemize - +@item available: RTEMS_SEMAPHORE_OBTAIN_AVAILABLE +@item not available -- NO_WAIT: RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT +@item not available -- caller blocks: RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS +@end itemize + +@item SEMAPHORE_RELEASE +@itemize - +@item no waiting tasks: RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS +@item task readied -- returns to caller: RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>SEMAPHORE_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>SEMAPHORE_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>SEMAPHORE_DELETE</STRONG></TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_DELETE_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>SEMAPHORE_OBTAIN</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>available</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_OBTAIN_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><dd>not available -- NO_WAIT</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT</TD></TR> + <TR><TD ALIGN=left><dd>not available -- caller blocks</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>SEMAPHORE_RELEASE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no waiting tasks</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Message Manager, RTEMS_CPU_MODEL Timing Data Event Manager, RTEMS_CPU_MODEL Timing Data Semaphore Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Message Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{MESSAGE\_QUEUE\_CREATE}{RTEMS_MESSAGE_QUEUE_CREATE_ONLY} +\rtemsonecase{MESSAGE\_QUEUE\_IDENT}{RTEMS_MESSAGE_QUEUE_IDENT_ONLY} +\rtemsonecase{MESSAGE\_QUEUE\_DELETE}{RTEMS_MESSAGE_QUEUE_DELETE_ONLY} +\rtemsdirective{MESSAGE\_QUEUE\_SEND} +\rtemscase{no waiting tasks} + {RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS} +\rtemscase{task readied -- returns to caller} + {RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER} +\rtemsdirective{MESSAGE\_QUEUE\_URGENT} +\rtemscase{no waiting tasks}{RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS} +\rtemscase{task readied -- returns to caller} + {RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER} +\rtemsdirective{MESSAGE\_QUEUE\_BROADCAST} +\rtemscase{no waiting tasks}{RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS} +\rtemscase{task readied -- returns to caller} + {RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER} +\rtemsdirective{MESSAGE\_QUEUE\_RECEIVE} +\rtemscase{available}{RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE} +\rtemscase{not available -- NO\_WAIT} + {RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT} +\rtemscase{not available -- caller blocks} + {RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS} +\rtemsdirective{MESSAGE\_QUEUE\_FLUSH} +\rtemscase{no messages flushed}{RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED} +\rtemscase{messages flushed}{RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item MESSAGE_QUEUE_CREATE +@itemize - +@item only case: RTEMS_MESSAGE_QUEUE_CREATE_ONLY +@end itemize + +@item MESSAGE_QUEUE_IDENT +@itemize - +@item only case: RTEMS_MESSAGE_QUEUE_IDENT_ONLY +@end itemize + +@item MESSAGE_QUEUE_DELETE +@itemize - +@item only case: RTEMS_MESSAGE_QUEUE_DELETE_ONLY +@end itemize + +@item MESSAGE_QUEUE_SEND +@itemize - +@item no waiting tasks: RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS +@item task readied -- returns to caller: RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@item MESSAGE_QUEUE_URGENT +@itemize - +@item no waiting tasks: RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS +@item task readied -- returns to caller: RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@item MESSAGE_QUEUE_BROADCAST +@itemize - +@item no waiting tasks: RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS +@item task readied -- returns to caller: RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@item MESSAGE_QUEUE_RECEIVE +@itemize - +@item available: RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE +@item not available -- NO_WAIT: RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT +@item not available -- caller blocks: RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS +@end itemize + +@item MESSAGE_QUEUE_FLUSH +@itemize - +@item no messages flushed: RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED +@item messages flushed: RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>MESSAGE_QUEUE_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>MESSAGE_QUEUE_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>MESSAGE_QUEUE_DELETE</STRONG></TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_DELETE_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>MESSAGE_QUEUE_SEND</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no waiting tasks</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>MESSAGE_QUEUE_URGENT</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no waiting tasks</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>MESSAGE_QUEUE_BROADCAST</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no waiting tasks</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>MESSAGE_QUEUE_RECEIVE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>available</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><dd>not available -- NO_WAIT</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT</TD></TR> + <TR><TD ALIGN=left><dd>not available -- caller blocks</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>MESSAGE_QUEUE_FLUSH</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no messages flushed</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED</TD></TR> + <TR><TD ALIGN=left><dd>messages flushed</TD> + <TD ALIGN=center>RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED</TD></TR> + + </TABLE> +</CENTER> +@end html +@end ifset + +@page +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Event Manager, RTEMS_CPU_MODEL Timing Data Signal Manager, RTEMS_CPU_MODEL Timing Data Message Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Event Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsdirective{EVENT\_SEND} +\rtemscase{no task readied}{RTEMS_EVENT_SEND_NO_TASK_READIED} +\rtemscase{task readied -- returns to caller} + {RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER} +\rtemsdirective{EVENT\_RECEIVE} +\rtemscase{obtain current events}{RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS} +\rtemscase{available}{RTEMS_EVENT_RECEIVE_AVAILABLE} +\rtemscase{not available -- NO\_WAIT}{RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT} +\rtemscase{not available -- caller blocks} + {RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item EVENT_SEND +@itemize - +@item no task readied: RTEMS_EVENT_SEND_NO_TASK_READIED +@item task readied -- returns to caller: RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@item EVENT_RECEIVE +@itemize - +@item obtain current events: RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS +@item available: RTEMS_EVENT_RECEIVE_AVAILABLE +@item not available -- NO_WAIT: RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT +@item not available -- caller blocks: RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left COLSPAN=2><STRONG>EVENT_SEND</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>no task readied</TD> + <TD ALIGN=center>RTEMS_EVENT_SEND_NO_TASK_READIED</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center>RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center>RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>EVENT_RECEIVE</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>obtain current events</TD> + <TD ALIGN=center>RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS</TD></TR> + <TR><TD ALIGN=left><dd>available</TD> + <TD ALIGN=center>RTEMS_EVENT_RECEIVE_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><dd>not available -- NO_WAIT</TD> + <TD ALIGN=center>RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT</TD></TR> + <TR><TD ALIGN=left><dd>not available -- caller blocks</TD> + <TD ALIGN=center>RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS</TD></TR> + + </TABLE> +</CENTER> +@end html +@end ifset +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Signal Manager, RTEMS_CPU_MODEL Timing Data Partition Manager, RTEMS_CPU_MODEL Timing Data Event Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Signal Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{SIGNAL\_CATCH}{RTEMS_SIGNAL_CATCH_ONLY} +\rtemsdirective{SIGNAL\_SEND} +\rtemscase{returns to caller}{RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER} +\rtemscase{signal to self}{RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF} +\rtemsdirective{EXIT ASR OVERHEAD} +\rtemscase{returns to calling task} + {RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK} +\rtemscase{returns to preempting task} + {RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet +@item SIGNAL_CATCH +@itemize - +@item only case: RTEMS_SIGNAL_CATCH_ONLY +@end itemize + +@item SIGNAL_SEND +@itemize - +@item returns to caller: RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER +@item signal to self: RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF +@end itemize + +@item EXIT ASR OVERHEAD +@itemize - +@item returns to calling task: RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK +@item returns to preempting task: RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>SIGNAL_CATCH</STRONG></TD> + <TD ALIGN=center>RTEMS_SIGNAL_CATCH_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>SIGNAL_SEND</TD></TR> + <TR><TD ALIGN=left><dd>returns to caller</TD> + <TD ALIGN=center>RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>signal to self</TD> + <TD ALIGN=center>RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>EXIT ASR OVERHEAD</TD></TR> + <TR><TD ALIGN=left><dd>returns to calling task</TD> + <TD ALIGN=center> + RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK</TD></TR> + <TR><TD ALIGN=left><dd>returns to preempting task</TD> + <TD ALIGN=center> + RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Partition Manager, RTEMS_CPU_MODEL Timing Data Region Manager, RTEMS_CPU_MODEL Timing Data Signal Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Partition Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{PARTITION\_CREATE}{RTEMS_PARTITION_CREATE_ONLY} +\rtemsonecase{PARTITION\_IDENT}{RTEMS_PARTITION_IDENT_ONLY} +\rtemsonecase{PARTITION\_DELETE}{RTEMS_PARTITION_DELETE_ONLY} +\rtemsdirective{PARTITION\_GET\_BUFFER} +\rtemscase{available}{RTEMS_PARTITION_GET_BUFFER_AVAILABLE} +\rtemscase{not available}{RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE} +\rtemsonecase{PARTITION\_RETURN\_BUFFER} + {RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item PARTITION_CREATE +@itemize - +@item only case: RTEMS_PARTITION_CREATE_ONLY +@end itemize + +@item PARTITION_IDENT +@itemize - +@item only case: RTEMS_PARTITION_IDENT_ONLY +@end itemize + +@item PARTITION_DELETE +@itemize - +@item only case: RTEMS_PARTITION_DELETE_ONLY +@end itemize + +@item PARTITION_GET_BUFFER +@itemize - +@item available: RTEMS_PARTITION_GET_BUFFER_AVAILABLE +@item not available: RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE +@end itemize + +@item PARTITION_RETURN_BUFFER +@itemize - +@item only case: RTEMS_PARTITION_RETURN_BUFFER_ONLY +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>PARTITION_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_PARTITION_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PARTITION_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_PARTITION_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PARTITION_DELETE</STRONG></TD> + <TD ALIGN=center>RTEMS_PARTITION_DELETE_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>PARTITION_GET_BUFFER</STRONG></TD></TR> + <TR><TD ALIGN=left><dd>available</TD> + <TD ALIGN=center>RTEMS_PARTITION_GET_BUFFER_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><dd>not available</TD> + <TD ALIGN=center>RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><STRONG>PARTITION_RETURN_BUFFER</STRONG></TD> + <TD ALIGN=center>RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@page +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Region Manager, RTEMS_CPU_MODEL Timing Data Dual-Ported Memory Manager, RTEMS_CPU_MODEL Timing Data Partition Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Region Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{REGION\_CREATE}{RTEMS_REGION_CREATE_ONLY} +\rtemsonecase{REGION\_IDENT}{RTEMS_REGION_IDENT_ONLY} +\rtemsonecase{REGION\_DELETE}{RTEMS_REGION_DELETE_ONLY} +\rtemsdirective{REGION\_GET\_SEGMENT} +\rtemscase{available}{RTEMS_REGION_GET_SEGMENT_AVAILABLE} +\rtemscase{not available -- NO\_WAIT} + {RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT} +\rtemscase{not available -- caller blocks} + {RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS} +\rtemsdirective{REGION\_RETURN\_SEGMENT} +\rtemscase{no waiting tasks}{RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS} +\rtemscase{task readied -- returns to caller} + {RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER} +\rtemscase{task readied -- preempts caller} + {RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item REGION_CREATE +@itemize - +@item only case: RTEMS_REGION_CREATE_ONLY +@end itemize + +@item REGION_IDENT +@itemize - +@item only case: RTEMS_REGION_IDENT_ONLY +@end itemize + +@item REGION_DELETE +@itemize - +@item only case: RTEMS_REGION_DELETE_ONLY +@end itemize + +@item REGION_GET_SEGMENT +@itemize - +@item available: RTEMS_REGION_GET_SEGMENT_AVAILABLE +@item not available -- NO_WAIT: RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT +@item not available -- caller blocks: RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS +@end itemize + +@item REGION_RETURN_SEGMENT +@itemize - +@item no waiting tasks: RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS +@item task readied -- returns to caller: RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER +@item task readied -- preempts caller: RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>REGION_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_REGION_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>REGION_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_REGION_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>REGION_DELETE</STRONG></TD> + <TD ALIGN=center>RTEMS_REGION_DELETE_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>REGION_GET_SEGMENT</TD></TR> + <TR><TD ALIGN=left><dd>available</TD> + <TD ALIGN=center>RTEMS_REGION_GET_SEGMENT_AVAILABLE</TD></TR> + <TR><TD ALIGN=left><dd>not available -- NO_WAIT</TD> + <TD ALIGN=center> + RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT</TD></TR> + <TR><TD ALIGN=left><dd>not available -- caller blocks</TD> + <TD ALIGN=center> + RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>REGION_RETURN_SEGMENT</TD></TR> + <TR><TD ALIGN=left><dd>no waiting tasks</TD> + <TD ALIGN=center>RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- returns to caller</TD> + <TD ALIGN=center> + RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>task readied -- preempts caller</TD> + <TD ALIGN=center> + RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Dual-Ported Memory Manager, RTEMS_CPU_MODEL Timing Data I/O Manager, RTEMS_CPU_MODEL Timing Data Region Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Dual-Ported Memory Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{PORT\_CREATE}{RTEMS_PORT_CREATE_ONLY} +\rtemsonecase{PORT\_IDENT}{RTEMS_PORT_IDENT_ONLY} +\rtemsonecase{PORT\_DELETE}{RTEMS_PORT_DELETE_ONLY} +\rtemsonecase{PORT\_INTERNAL\_TO\_EXTERNAL} + {RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY} +\rtemsonecase{PORT\_EXTERNAL\_TO\_INTERNAL} + {RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item PORT_CREATE +@itemize - +@item only case: RTEMS_PORT_CREATE_ONLY +@end itemize + +@item PORT_IDENT +@itemize - +@item only case: RTEMS_PORT_IDENT_ONLY +@end itemize + +@item PORT_DELETE +@itemize - +@item only case: RTEMS_PORT_DELETE_ONLY +@end itemize + +@item PORT_INTERNAL_TO_EXTERNAL +@itemize - +@item only case: RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY +@end itemize + +@item PORT_EXTERNAL_TO_INTERNAL +@itemize - +@item only case: RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>PORT_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_PORT_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PORT_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_PORT_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PORT_DELETE</STRONG></TD> + <TD ALIGN=center>RTEMS_PORT_DELETE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PORT_INTERNAL_TO_EXTERNAL</STRONG></TD> + <TD ALIGN=center>RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>PORT_EXTERNAL_TO_INTERNAL</STRONG></TD> + <TD ALIGN=center>RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY</TD></TR> + + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data I/O Manager, RTEMS_CPU_MODEL Timing Data Rate Monotonic Manager, RTEMS_CPU_MODEL Timing Data Dual-Ported Memory Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section I/O Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{IO\_INITIALIZE}{RTEMS_IO_INITIALIZE_ONLY} +\rtemsonecase{IO\_OPEN}{RTEMS_IO_OPEN_ONLY} +\rtemsonecase{IO\_CLOSE}{RTEMS_IO_CLOSE_ONLY} +\rtemsonecase{IO\_READ}{RTEMS_IO_READ_ONLY} +\rtemsonecase{IO\_WRITE}{RTEMS_IO_WRITE_ONLY} +\rtemsonecase{IO\_CONTROL}{RTEMS_IO_CONTROL_ONLY} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item IO_INITIALIZE +@itemize - +@item only case: RTEMS_IO_INITIALIZE_ONLY +@end itemize + +@item IO_OPEN +@itemize - +@item only case: RTEMS_IO_OPEN_ONLY +@end itemize + +@item IO_CLOSE +@itemize - +@item only case: RTEMS_IO_CLOSE_ONLY +@end itemize + +@item IO_READ +@itemize - +@item only case: RTEMS_IO_READ_ONLY +@end itemize + +@item IO_WRITE +@itemize - +@item only case: RTEMS_IO_WRITE_ONLY +@end itemize + +@item IO_CONTROL +@itemize - +@item only case: RTEMS_IO_CONTROL_ONLY +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>IO_INITIALIZE</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_INITIALIZE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>IO_OPEN</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_OPEN_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>IO_CLOSE</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_CLOSE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>IO_READ</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_READ_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>IO_WRITE</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_WRITE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>IO_CONTROL</STRONG></TD> + <TD ALIGN=center>RTEMS_IO_CONTROL_ONLY</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node RTEMS_CPU_MODEL Timing Data Rate Monotonic Manager, TIMETABLE_NEXT_LINK, RTEMS_CPU_MODEL Timing Data I/O Manager, RTEMS_CPU_MODEL Timing Data +@end ifinfo +@section Rate Monotonic Manager + +@ifset use-tex +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\span\rtemstimetable +\rtemsonecase{RATE\_MONOTONIC\_CREATE}{RTEMS_RATE_MONOTONIC_CREATE_ONLY} +\rtemsonecase{RATE\_MONOTONIC\_IDENT}{RTEMS_RATE_MONOTONIC_IDENT_ONLY} +\rtemsonecase{RATE\_MONOTONIC\_CANCEL}{RTEMS_RATE_MONOTONIC_CANCEL_ONLY} +\rtemsdirective{RATE\_MONOTONIC\_DELETE} +\rtemscase{active}{RTEMS_RATE_MONOTONIC_DELETE_ACTIVE} +\rtemscase{inactive}{RTEMS_RATE_MONOTONIC_DELETE_INACTIVE} +\rtemsdirective{RATE\_MONOTONIC\_PERIOD} +\rtemscase{initiate period -- returns to caller} + {RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER} +\rtemscase{conclude period -- caller blocks} + {RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS} +\rtemscase{obtain status}{RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS} +\rtemsendtimetable +}}\hfil} +@end tex +@end ifset + +@ifset use-ascii +@ifinfo +@itemize @bullet + +@item RATE_MONOTONIC_CREATE +@itemize - +@item only case: RTEMS_RATE_MONOTONIC_CREATE_ONLY +@end itemize + +@item RATE_MONOTONIC_IDENT +@itemize - +@item only case: RTEMS_RATE_MONOTONIC_IDENT_ONLY +@end itemize + +@item RATE_MONOTONIC_CANCEL +@itemize - +@item only case: RTEMS_RATE_MONOTONIC_CANCEL_ONLY +@end itemize + +@item RATE_MONOTONIC_DELETE +@itemize - +@item active: RTEMS_RATE_MONOTONIC_DELETE_ACTIVE +@item inactive: RTEMS_RATE_MONOTONIC_DELETE_INACTIVE +@end itemize + +@item RATE_MONOTONIC_PERIOD +@itemize - +@item initiate period -- returns to caller: RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER +@item conclude period -- caller blocks: RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS +@item obtain status: RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS +@end itemize + +@end itemize +@end ifinfo +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=left><STRONG>RATE_MONOTONIC_CREATE</STRONG></TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_CREATE_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>RATE_MONOTONIC_IDENT</STRONG></TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_IDENT_ONLY</TD></TR> +<TR><TD ALIGN=left><STRONG>RATE_MONOTONIC_CANCEL</STRONG></TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_CANCEL_ONLY</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>RATE_MONOTONIC_DELETE</TD></TR> + <TR><TD ALIGN=left><dd>active</TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_DELETE_ACTIVE</TD></TR> + <TR><TD ALIGN=left><dd>inactive</TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_DELETE_INACTIVE</TD></TR> +<TR><TD ALIGN=left COLSPAN=2><STRONG>RATE_MONOTONIC_PERIOD</TD></TR> + <TR><TD ALIGN=left><dd>initiate period -- returns to caller</TD> + <TD ALIGN=center> + RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER</TD></TR> + <TR><TD ALIGN=left><dd>conclude period -- caller blocks</TD> + <TD ALIGN=center> + RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS</TD></TR> + <TR><TD ALIGN=left><dd>obtain status</TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@tex +\global\advance \smallskipamount by 4pt +@end tex diff --git a/doc/common/timing.texi b/doc/common/timing.texi new file mode 100644 index 0000000000..2d5b7e35a2 --- /dev/null +++ b/doc/common/timing.texi @@ -0,0 +1,457 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Timing Specification, Timing Specification Introduction, , Top +@end ifinfo +@chapter Timing Specification +@ifinfo +@menu +* Timing Specification Introduction:: +* Timing Specification Philosophy:: +* Timing Specification Methodology:: +@end menu +@end ifinfo + +@ifinfo +@node Timing Specification Introduction, Timing Specification Philosophy, Timing Specification, Timing Specification +@end ifinfo +@section Introduction + +This chapter provides information pertaining to the +measurement of the performance of RTEMS, the methods of +gathering the timing data, and the usefulness of the data. Also +discussed are other time critical aspects of RTEMS that affect +an applications design and ultimate throughput. These aspects +include determinancy, interrupt latency and context switch times. + +@ifinfo +@node Timing Specification Philosophy, Determinancy, Timing Specification Introduction, Timing Specification +@end ifinfo +@section Philosophy +@ifinfo +@menu +* Determinancy:: +* Interrupt Latency:: +* Context Switch Time:: +* Directive Times:: +@end menu +@end ifinfo + +Benchmarks are commonly used to evaluate the +performance of software and hardware. Benchmarks can be an +effective tool when comparing systems. Unfortunately, +benchmarks can also be manipulated to justify virtually any +claim. Benchmarks of real-time executives are difficult to +evaluate for a variety of reasons. Executives vary in the +robustness of features and options provided. Even when +executives compare favorably in functionality, it is quite +likely that different methodologies were used to obtain the +timing data. Another problem is that some executives provide +times for only a small subset of directives, This is typically +justified by claiming that these are the only time-critical +directives. The performance of some executives is also very +sensitive to the number of objects in the system. To obtain any +measure of usefulness, the performance information provided for +an executive should address each of these issues. + +When evaluating the performance of a real-time +executive, one typically considers the following areas: +determinancy, directive times, worst case interrupt latency, and +context switch time. Unfortunately, these areas do not have +standard measurement methodologies. This allows vendors to +manipulate the results such that their product is favorably +represented. We have attempted to provide useful and meaningful +timing information for RTEMS. To insure the usefulness of our +data, the methodology and definitions used to obtain and +describe the data are also documented. + +@ifinfo +@node Determinancy, Interrupt Latency, Timing Specification Philosophy, Timing Specification Philosophy +@end ifinfo +@subsection Determinancy + +The correctness of data in a real-time system must +always be judged by its timeliness. In many real-time systems, +obtaining the correct answer does not necessarily solve the +problem. For example, in a nuclear reactor it is not enough to +determine that the core is overheating. This situation must be +detected and acknowledged early enough that corrective action +can be taken and a meltdown avoided. + +Consequently, a system designer must be able to +predict the worst-case behavior of the application running under +the selected executive. In this light, it is important that a +real-time system perform consistently regardless of the number +of tasks, semaphores, or other resources allocated. An +important design goal of a real-time executive is that all +internal algorithms be fixed-cost. Unfortunately, this goal is +difficult to completely meet without sacrificing the robustness +of the executive's feature set. + +Many executives use the term deterministic to mean +that the execution times of their services can be predicted. +However, they often provide formulas to modify execution times +based upon the number of objects in the system. This usage is +in sharp contrast to the notion of deterministic meaning fixed +cost. + +Almost all RTEMS directives execute in a fixed amount +of time regardless of the number of objects present in the +system. The primary exception occurs when a task blocks while +acquiring a resource and specifies a non-zero timeout interval. + +Other exceptions are message queue broadcast, +obtaining a variable length memory block, object name to ID +translation, and deleting a resource upon which tasks are +waiting. In addition, the time required to service a clock tick +interrupt is based upon the number of timeouts and other +"events" which must be processed at that tick. This second +group is composed primarily of capabilities which are inherently +non-deterministic but are infrequently used in time critical +situations. The major exception is that of servicing a clock +tick. However, most applications have a very small number of +timeouts which expire at exactly the same millisecond (usually +none, but occasionally two or three). + +@ifinfo +@node Interrupt Latency, Context Switch Time, Determinancy, Timing Specification Philosophy +@end ifinfo +@subsection Interrupt Latency + +Interrupt latency is the delay between the CPU's +receipt of an interrupt request and the execution of the first +application-specific instruction in an interrupt service +routine. Interrupts are a critical component of most real-time +applications and it is critical that they be acted upon as +quickly as possible. + +Knowledge of the worst case interrupt latency of an +executive aids the application designer in determining the +maximum period of time between the generation of an interrupt +and an interrupt handler responding to that interrupt. The +interrupt latency of an system is the greater of the executive's +and the applications's interrupt latency. If the application +disables interrupts longer than the executive, then the +application's interrupt latency is the system's worst case +interrupt disable period. + +The worst case interrupt latency for a real-time +executive is based upon the following components: + +@itemize @bullet +@item the longest period of time interrupts are disabled +by the executive, + +@item the overhead required by the executive at the +beginning of each ISR, + +@item the time required for the CPU to vector the +interrupt, and + +@item for some microprocessors, the length of the longest +instruction. +@end itemize + +The first component is irrelevant if an interrupt +occurs when interrupts are enabled, although it must be included +in a worst case analysis. The third and fourth components are +particular to a CPU implementation and are not dependent on the +executive. The fourth component is ignored by this document +because most applications use only a subset of a +microprocessor's instruction set. Because of this the longest +instruction actually executed is application dependent. The +worst case interrupt latency of an executive is typically +defined as the sum of components (1) and (2). The second +component includes the time necessry for RTEMS to save registers +and vector to the user-defined handler. RTEMS includes the +third component, the time required for the CPU to vector the +interrupt, because it is a required part of any interrupt. + +Many executives report the maximum interrupt disable +period as their interrupt latency and ignore the other +components. This results in very low worst-case interrupt +latency times which are not indicative of actual application +performance. The definition used by RTEMS results in a higher +interrupt latency being reported, but accurately reflects the +longest delay between the CPU's receipt of an interrupt request +and the execution of the first application-specific instruction +in an interrupt service routine. + +The actual interrupt latency times are reported in +the Timing Data chapter of this supplement. + +@ifinfo +@node Context Switch Time, Directive Times, Interrupt Latency, Timing Specification Philosophy +@end ifinfo +@subsection Context Switch Time + +An RTEMS context switch is defined as the act of +taking the CPU from the currently executing task and giving it +to another task. This process involves the following components: + +@itemize @bullet +@item Saving the hardware state of the current task. + +@item Optionally, invoking the TASK_SWITCH user extension. + +@item Restoring the hardware state of the new task. +@end itemize + +RTEMS defines the hardware state of a task to include +the CPU's data registers, address registers, and, optionally, +floating point registers. + +Context switch time is often touted as a performance +measure of real-time executives. However, a context switch is +performed as part of a directive's actions and should be viewed +as such when designing an application. For example, if a task +is unable to acquire a semaphore and blocks, a context switch is +required to transfer control from the blocking task to a new +task. From the application's perspective, the context switch is +a direct result of not acquiring the semaphore. In this light, +the context switch time is no more relevant than the performance +of any other of the executive's subroutines which are not +directly accessible by the application. + +In spite of the inappropriateness of using the +context switch time as a performance metric, RTEMS context +switch times for floating point and non-floating points tasks +are provided for comparison purposes. Of the executives which +actually support floating point operations, many do not report +context switch times for floating point context switch time. +This results in a reported context switch time which is +meaningless for an application with floating point tasks. + +The actual context switch times are reported in the +Timing Data chapter of this supplement. + +@ifinfo +@node Directive Times, Timing Specification Methodology, Context Switch Time, Timing Specification Philosophy +@end ifinfo +@subsection Directive Times + +Directives are the application's interface to the +executive, and as such their execution times are critical in +determining the performance of the application. For example, an +application using a semaphore to protect a critical data +structure should be aware of the time required to acquire and +release a semaphore. In addition, the application designer can +utilize the directive execution times to evaluate the +performance of different synchronization and communication +mechanisms. + +The actual directive execution times are reported in +the Timing Data chapter of this supplement. + +@ifinfo +@node Timing Specification Methodology, Software Platform, Directive Times, Timing Specification +@end ifinfo +@section Methodology +@ifinfo +@menu +* Software Platform:: +* Hardware Platform:: +* What is measured?:: +* What is not measured?:: +* Terminology:: +@end menu +@end ifinfo + +@ifinfo +@node Software Platform, Hardware Platform, Timing Specification Methodology, Timing Specification Methodology +@end ifinfo +@subsection Software Platform + +The RTEMS timing suite is written in C. The overhead +of passing arguments to RTEMS by C is not timed. The times +reported represent the amount of time from entering to exiting +RTEMS. + +The tests are based upon one of two execution models: +(1) single invocation times, and (2) average times of repeated +invocations. Single invocation times are provided for +directives which cannot easily be invoked multiple times in the +same scenario. For example, the times reported for entering and +exiting an interrupt service routine are single invocation +times. The second model is used for directives which can easily +be invoked multiple times in the same scenario. For example, +the times reported for semaphore obtain and semaphore release +are averages of multiple invocations. At least 100 invocations +are used to obtain the average. + +@ifinfo +@node Hardware Platform, What is measured?, Software Platform, Timing Specification Methodology +@end ifinfo +@subsection Hardware Platform + +Since RTEMS supports a variety of processors, the +hardware platform used to gather the benchmark times must also +vary. Therefore, for each processor supported the hardware +platform must be defined. Each definition will include a brief +description of the target hardware platform including the clock +speed, memory wait states encountered, and any other pertinent +information. This definition may be found in the processor +dependent timing data chapter within this supplement. + +@ifinfo +@node What is measured?, What is not measured?, Hardware Platform, Timing Specification Methodology +@end ifinfo +@subsection What is measured? + +An effort was made to provide execution times for a +large portion of RTEMS. Times were provided for most directives +regardless of whether or not they are typically used in time +critical code. For example, execution times are provided for +all object create and delete directives, even though these are +typically part of application initialization. + +The times include all RTEMS actions necessary in a +particular scenario. For example, all times for blocking +directives include the context switch necessary to transfer +control to a new task. Under no circumstances is it necessary +to add context switch time to the reported times. + +The following list describes the objects created by +the timing suite: + +@itemize @bullet +@item All tasks are non-floating point. + +@item All tasks are created as local objects. + +@item No timeouts are used on blocking directives. + +@item All tasks wait for objects in FIFO order. + +@end itemize + +In addition, no user extensions are configured. + +@ifinfo +@node What is not measured?, Terminology, What is measured?, Timing Specification Methodology +@end ifinfo +@subsection What is not measured? + +The times presented in this document are not intended +to represent best or worst case times, nor are all directives +included. For example, no times are provided for the initialize +executive and fatal_error_occurred directives. Other than the +exceptions detailed in the Determinancy section, all directives +will execute in the fixed length of time given. + +Other than entering and exiting an interrupt service +routine, all directives were executed from tasks and not from +interrupt service routines. Directives invoked from ISRs, when +allowable, will execute in slightly less time than when invoked +from a task because rescheduling is delayed until the interrupt +exits. + +@ifinfo +@node Terminology, , What is not measured?, Timing Specification Methodology +@end ifinfo +@subsection Terminology + +The following is a list of phrases which are used to +distinguish individual execution paths of the directives taken +during the RTEMS performance analysis: + +@table @b +@item another task +The directive was performed +on a task other than the calling task. + +@item available +A task attempted to obtain a resource and +immediately acquired it. + +@item blocked task +The task operated upon by the +directive was blocked waiting for a resource. + +@item caller blocks +The requested resoure was not +immediately available and the calling task chose to wait. + +@item calling task +The task invoking the directive. + +@item messages flushed +One or more messages was flushed +from the message queue. + +@item no messages flushed +No messages were flushed from +the message queue. + +@item not available +A task attempted to obtain a resource +and could not immediately acquire it. + +@item no reschedule +The directive did not require a +rescheduling operation. + +@item NO_WAIT +A resource was not available and the +calling task chose to return immediately via the NO_WAIT option +with an error. + +@item obtain current +The current value of something was +requested by the calling task. + +@item preempts caller +The release of a resource caused a +task of higher priority than the calling to be readied and it +became the executing task. + +@item ready task +The task operated upon by the directive +was in the ready state. + +@item reschedule +The actions of the directive +necessitated a rescheduling operation. + +@item returns to caller +The directive succeeded and +immediately returned to the calling task. + +@item returns to interrupted task +The instructions +executed immediately following this interrupt will be in the +interrupted task. + +@item returns to nested interrupt +The instructions +executed immediately following this interrupt will be in a +previously interrupted ISR. + +@item returns to preempting task +The instructions +executed immediately following this interrupt or signal handler +will be in a task other than the interrupted task. + +@item signal to self +The signal set was sent to the +calling task and signal processing was enabled. + +@item suspended task +The task operated upon by the +directive was in the suspended state. + +@item task readied +The release of a resource caused a +task of lower or equal priority to be readied and the calling +task remained the executing task. + +@item yield +The act of attempting to voluntarily release +the CPU. + +@end table + diff --git a/doc/common/up-arrow.gif b/doc/common/up-arrow.gif Binary files differnew file mode 100644 index 0000000000..82aa8ccc68 --- /dev/null +++ b/doc/common/up-arrow.gif diff --git a/doc/common/wksheets.t b/doc/common/wksheets.t new file mode 100644 index 0000000000..8f2334dd93 --- /dev/null +++ b/doc/common/wksheets.t @@ -0,0 +1,424 @@ +@c +@c Figures ... +@c RTEMS RAM Workspace Worksheet +@c RTEMS Code Space Worksheet +@c + +@ifinfo +@node Memory Requirements, Memory Requirements Introduction, WORKSHEETS_PREVIOUS_LINK, Top +@end ifinfo +@chapter Memory Requirements +@ifinfo +@menu +* Memory Requirements Introduction:: +* Memory Requirements Data Space Requirements:: +* Memory Requirements Minimum and Maximum Code Space Requirements:: +* Memory Requirements RTEMS Code Space Worksheet:: +* Memory Requirements RTEMS RAM Workspace Worksheet:: +@end menu +@end ifinfo + +@ifinfo +@node Memory Requirements Introduction, Memory Requirements Data Space Requirements, Memory Requirements, Memory Requirements +@end ifinfo +@section Introduction + +Memory is typically a limited resource in real-time +embedded systems, therefore, RTEMS can be configured to utilize +the minimum amount of memory while meeting all of the +applications requirements. Worksheets are provided which allow +the RTEMS application developer to determine the amount of RTEMS +code and RAM workspace which is required by the particular +configuration. Also provided are the minimum code space, +maximum code space, and the constant data space required by +RTEMS. + +@ifinfo +@node Memory Requirements Data Space Requirements, Memory Requirements Minimum and Maximum Code Space Requirements, Memory Requirements Introduction, Memory Requirements +@end ifinfo +@section Data Space Requirements + +RTEMS requires a small amount of memory for its +private variables. This data area must be in RAM and is +separate from the RTEMS RAM Workspace. The following +illustrates the data space required for all configurations of +RTEMS: + +@itemize @bullet +@item Data Space: RTEMS_DATA_SPACE +@end itemize + +@ifinfo +@node Memory Requirements Minimum and Maximum Code Space Requirements, Memory Requirements RTEMS Code Space Worksheet, Memory Requirements Data Space Requirements, Memory Requirements +@end ifinfo +@section Minimum and Maximum Code Space Requirements + +A maximum configuration of RTEMS includes the core +and all managers, including the multiprocessing manager. +Conversely, a minimum configuration of RTEMS includes only the +core and the following managers: initialization, task, interrupt +and fatal error. The following illustrates the code space +required by these configurations of RTEMS: + +@itemize @bullet +@item Minimum Configuration: RTEMS_MINIMUM_CONFIGURATION +@item Maximum Configuration: RTEMS_MAXIMUM_CONFIGURATION +@end itemize + +@ifinfo +@node Memory Requirements RTEMS Code Space Worksheet, Memory Requirements RTEMS RAM Workspace Worksheet, Memory Requirements Minimum and Maximum Code Space Requirements, Memory Requirements +@end ifinfo +@section RTEMS Code Space Worksheet + +The RTEMS Code Space Worksheet is a tool provided to +aid the RTEMS application designer to accurately calculate the +memory required by the RTEMS run-time environment. RTEMS allows +the custom configuration of the executive by optionally +excluding managers which are not required by a particular +application. This worksheet provides the included and excluded +size of each manager in tabular form allowing for the quick +calculation of any custom configuration of RTEMS. The RTEMS +Code Space Worksheet is below: + +@ifset use-ascii +@page +@end ifset +@ifset use-tex +@page +@end ifset + +@page +@center @b{RTEMS Code Space Worksheet} +@sp 1 + +@ifset use-ascii + +The following is a list of the components of the RTEMS code space. The first +number in parentheses is the size when the component is included, +while the second number indicates its size when not included. If the second +number is "NA", then the component must always be included. + +@itemize @bullet +@item Core (RTEMS_CORE_CODE_SIZE, NA) +@item Initialization (RTEMS_INITIALIZATION_CODE_SIZE, NA) +@item Task (RTEMS_TASK_CODE_SIZE, NA) +@item Interrupt (RTEMS_INTERRUPT_CODE_SIZE, NA) +@item Clock (RTEMS_CLOCK_CODE_SIZE, NA) +@item Timer (RTEMS_TIMER_CODE_SIZE, RTEMS_TIMER_CODE_OPTSIZE) +@item Semaphore (RTEMS_SEMAPHORE_CODE_SIZE, RTEMS_SEMAPHORE_CODE_OPTSIZE) +@item Message (RTEMS_MESSAGE_CODE_SIZE, RTEMS_MESSAGE_CODE_OPTSIZE) +@item Event (RTEMS_EVENT_CODE_SIZE, RTEMS_EVENT_CODE_OPTSIZE) +@item Signal (RTEMS_SIGNAL_CODE_SIZE, RTEMS_SIGNAL_CODE_OPTSIZE) +@item Partition (RTEMS_PARTITION_CODE_SIZE, RTEMS_PARTITION_CODE_OPTSIZE) +@item Region (RTEMS_REGION_CODE_SIZE, RTEMS_REGION_CODE_OPTSIZE) +@item Dual Ported Memory (RTEMS_DPMEM_CODE_SIZE, RTEMS_DPMEM_CODE_OPTSIZE) +@item I/O (RTEMS_IO_CODE_SIZE, RTEMS_IO_CODE_OPTSIZE) +@item Fatal Error (RTEMS_FATAL_ERROR_CODE_SIZE, NA) +@item Rate Monotonic (RTEMS_RATE_MONOTONIC_CODE_SIZE, RTEMS_RATE_MONOTONIC_CODE_OPTSIZE) +@item Multiprocessing (RTEMS_MULTIPROCESSING_CODE_SIZE, RTEMS_MULTIPROCESSING_CODE_OPTSIZE) +@end itemize +@end ifset + +@ifset use-tex + +@tex +\line{\hskip 0.50in\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 2.25in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Component && \bf Included && \bf Not Included && \bf Size &\cr\noalign{\hrule} +&Core && RTEMS_CORE_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Initialization && RTEMS_INITIALIZATION_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Task && RTEMS_TASK_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Interrupt && RTEMS_INTERRUPT_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Clock && RTEMS_CLOCK_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Timer && RTEMS_TIMER_CODE_SIZE && RTEMS_TIMER_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Semaphore && RTEMS_SEMAPHORE_CODE_SIZE && RTEMS_SEMAPHORE_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Message && RTEMS_MESSAGE_CODE_SIZE && RTEMS_MESSAGE_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Event && RTEMS_EVENT_CODE_SIZE && RTEMS_EVENT_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Signal && RTEMS_SIGNAL_CODE_SIZE && RTEMS_SIGNAL_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Partition && RTEMS_PARTITION_CODE_SIZE && RTEMS_PARTITION_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Region && RTEMS_REGION_CODE_SIZE && RTEMS_REGION_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Dual Ported Memory && RTEMS_DPMEM_CODE_SIZE && RTEMS_DPMEM_CODE_OPTSIZE && &\cr\noalign{\hrule} +&I/O && RTEMS_IO_CODE_SIZE && RTEMS_IO_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Fatal Error && RTEMS_FATAL_ERROR_CODE_SIZE && NA && &\cr\noalign{\hrule} +&Rate Monotonic && RTEMS_RATE_MONOTONIC_CODE_SIZE && RTEMS_RATE_MONOTONIC_CODE_OPTSIZE && &\cr\noalign{\hrule} +&Multiprocessing && RTEMS_MULTIPROCESSING_CODE_SIZE && RTEMS_MULTIPROCESSING_CODE_OPTSIZE && &\cr\noalign{\hrule} +&\multispan 5 \bf\hfil Total Code Space Requirements\qquad\hfil&&&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=4 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Component</STRONG></TD> + <TD ALIGN=center><STRONG>Included</STRONG></TD> + <TD ALIGN=center><STRONG>Not Included</STRONG></TD> + <TD ALIGN=center><STRONG>Size</STRONG></TD></TR> +<TR><TD ALIGN=center>Core</TD> + <TD ALIGN=center>RTEMS_CORE_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Initialization</TD> + <TD ALIGN=center>RTEMS_INITIALIZATION_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Task</TD> + <TD ALIGN=center>RTEMS_TASK_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Interrupt</TD> + <TD ALIGN=center>RTEMS_INTERRUPT_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Clock</TD> + <TD ALIGN=center>RTEMS_CLOCK_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Timer</TD> + <TD ALIGN=center>RTEMS_TIMER_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_TIMER_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Semaphore</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_SEMAPHORE_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Message</TD> + <TD ALIGN=center>RTEMS_MESSAGE_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_MESSAGE_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Event</TD> + <TD ALIGN=center>RTEMS_EVENT_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_EVENT_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Signal</TD> + <TD ALIGN=center>RTEMS_SIGNAL_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_SIGNAL_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Partition</TD> + <TD ALIGN=center>RTEMS_PARTITION_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_PARTITION_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Region</TD> + <TD ALIGN=center>RTEMS_REGION_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_REGION_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Dual Ported Memory</TD> + <TD ALIGN=center>RTEMS_DPMEM_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_DPMEM_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>I/O</TD> + <TD ALIGN=center>RTEMS_IO_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_IO_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Fatal Error</TD> + <TD ALIGN=center>RTEMS_FATAL_ERROR_CODE_SIZE</TD> + <TD ALIGN=center>NA</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Rate Monotonic</TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_RATE_MONOTONIC_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center>Multiprocessing</TD> + <TD ALIGN=center>RTEMS_MULTIPROCESSING_CODE_SIZE</TD> + <TD ALIGN=center>RTEMS_MULTIPROCESSING_CODE_OPTSIZE</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=center COLSPAN=3> + <STRONG>Total Code Space Requirements</STRONG></TD> + <TD><BR></TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@page + +@ifinfo +@node Memory Requirements RTEMS RAM Workspace Worksheet, WORKSHEETS_NEXT_LINK, Memory Requirements RTEMS Code Space Worksheet, Memory Requirements +@end ifinfo +@section RTEMS RAM Workspace Worksheet + +The RTEMS RAM Workspace Worksheet is a tool provided +to aid the RTEMS application designer to accurately calculate +the minimum memory block to be reserved for RTEMS use. This +worksheet provides equations for calculating the amount of +memory required based upon the number of objects configured, +whether for single or multiple processor versions of the +executive. This information is presented in tabular form, along +with the fixed system requirements, allowing for quick +calculation of any application defined configuration of RTEMS. +The RTEMS RAM Workspace Worksheet is provided below: + +@ifset use-ascii +@page +@end ifset +@ifset use-tex +@sp 2 +@end ifset + +@center @b{RTEMS RAM Workspace Worksheet} +@sp 2 + +@ifset use-ascii +The total RTEMS RAM Workspace required is the sum of the following: + +@itemize @bullet +@item maximum_tasks * RTEMS_BYTES_PER_TASK +@item maximum_timers * RTEMS_BYTES_PER_TIMER +@item maximum_semaphores * RTEMS_BYTES_PER_SEMAPHORE +@item maximum_message_queues * RTEMS_BYTES_PER_MESSAGE_QUEUE +@item maximum_regions * RTEMS_BYTES_PER_REGION +@item maximum_partitions * RTEMS_BYTES_PER_PARTITION +@item maximum_ports * RTEMS_BYTES_PER_PORT +@item maximum_periods * RTEMS_BYTES_PER_PERIOD +@item maximum_extensions * RTEMS_BYTES_PER_EXTENSION +@item Floating Point Tasks * RTEMS_BYTES_PER_FP_TASK +@item Task Stacks +@item maximum_nodes * RTEMS_BYTES_PER_NODE +@item maximum_global_objects * RTEMS_BYTES_PER_GLOBAL_OBJECT +@item maximum_proxies * RTEMS_BYTES_PER_PROXY +@item Fixed System Requirements of RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS +@end itemize +@end ifset + +@ifset use-tex +@tex +\line{\hskip 0.75in\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 3.0in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +& \bf Description && \bf Equation && \bf Bytes Required &\cr\noalign{\hrule} +& maximum\_tasks && * RTEMS_BYTES_PER_TASK = &&&\cr\noalign{\hrule} +& maximum\_timers && * RTEMS_BYTES_PER_TIMER = &&&\cr\noalign{\hrule} +& maximum\_semaphores && * RTEMS_BYTES_PER_SEMAPHORE = &&&\cr\noalign{\hrule} +& maximum\_message\_queues && * RTEMS_BYTES_PER_MESSAGE_QUEUE = &&&\cr\noalign{\hrule} +& maximum\_regions && * RTEMS_BYTES_PER_REGION = &&&\cr\noalign{\hrule} +& maximum\_partitions && * RTEMS_BYTES_PER_PARTITION = &&&\cr\noalign{\hrule} +& maximum\_ports && * RTEMS_BYTES_PER_PORT = &&&\cr\noalign{\hrule} +& maximum\_periods && * RTEMS_BYTES_PER_PERIOD = &&&\cr\noalign{\hrule} +& maximum\_extensions && * RTEMS_BYTES_PER_EXTENSION = &&&\cr\noalign{\hrule} +& Floating Point Tasks && * RTEMS_BYTES_PER_FP_TASK = &&&\cr\noalign{\hrule} +& Task Stacks &&\hskip 2.3em=&&&\cr\noalign{\hrule} +& Total Single Processor Requirements &&&&&\cr\noalign{\hrule} +}}\hfil} + +\line{\hskip 0.75in\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 3.0in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +& \bf Description && \bf Equation && \bf Bytes Required &\cr\noalign{\hrule} +& maximum\_nodes && * RTEMS_BYTES_PER_NODE = &&&\cr\noalign{\hrule} +& maximum\_global\_objects && * RTEMS_BYTES_PER_GLOBAL_OBJECT = &&&\cr\noalign{\hrule} +& maximum\_proxies && * RTEMS_BYTES_PER_PROXY = &&&\cr\noalign{\hrule} +}}\hfil} + +\line{\hskip 0.75in\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 3.0in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +& Total Multiprocessing Requirements &&&&&\cr\noalign{\hrule} +& Fixed System Requirements && RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS &&&\cr\noalign{\hrule} +& Total Single Processor Requirements &&&&&\cr\noalign{\hrule} +& Total Multiprocessing Requirements &&&&&\cr\noalign{\hrule} +& Minimum Bytes for RTEMS Workspace &&&&&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Description</STRONG></TD> + <TD ALIGN=center><STRONG>Equation</STRONG></TD> + <TD ALIGN=center><STRONG>Bytes Required</STRONG></TD></TR> +<TR><TD ALIGN=left>maximum_tasks</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_TASK =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_timers</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_TIMER =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_semaphores</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_SEMAPHORE =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_message_queues</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_MESSAGE_QUEUE =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_regions</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_REGION =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_partitions</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_PARTITION =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_ports</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_PORT =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_periods</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_PERIOD =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_extensions</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_EXTENSION =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>Floating Point Tasks</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_FP_TASK =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left COLSPAN=2>Task Stacks</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left COLSPAN=2> + <STRONG>Total Single Processor Requirements</STRONG></TD> + <TD><BR></TD></TR> +<TR></TR> +<TR><TD ALIGN=center><STRONG>Description</STRONG></TD> + <TD ALIGN=center><STRONG>Equation</STRONG></TD> + <TD ALIGN=center><STRONG>Bytes Required</STRONG></TD></TR> +<TR><TD ALIGN=left>maximum_nodes</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_NODE =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_global_objects</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_GLOBAL_OBJECT =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left>maximum_proxies</TD> + <TD ALIGN=right>* RTEMS_BYTES_PER_PROXY =</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left COLSPAN=2> + <STRONG>Total Multiprocessing Requirements</STRONG></TD> + <TD><BR></TD></TR> +<TR></TR> +<TR><TD ALIGN=left COLSPAN=2>Fixed System Requirements</TD> + <TD ALIGN=center>RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS</TD></TR> +<TR><TD ALIGN=left COLSPAN=2>Total Single Processor Requirements</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left COLSPAN=2>Total Multiprocessing Requirements</TD> + <TD><BR></TD></TR> +<TR><TD ALIGN=left COLSPAN=2> + <STRONG>Minimum Bytes for RTEMS Workspace</STRONG></TD> + <TD><BR></TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + diff --git a/doc/develenv/Makefile b/doc/develenv/Makefile new file mode 100644 index 0000000000..d94fae665f --- /dev/null +++ b/doc/develenv/Makefile @@ -0,0 +1,55 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=develenv + +all: + +COMMON_FILES=../common/cpright.texi + +FILES=compile.texi $(PROJECT).texi direct.texi intro.texi sample.texi utils.texi + +all: + +info: $(PROJECT) + cp $(PROJECT) $(INFO_INSTALL) + +$(PROJECT): $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f $(PROJECT) + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +dv: dvi + $(XDVI) $(PROJECT).dvi + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +html: + -mkdir $(WWW_INSTALL)/$(PROJECT) + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ + $(PROJECT).texi + cp ../rtems.html $(WWW_INSTALL) + + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(PROJECT) $(PROJECT)-* _* + diff --git a/doc/develenv/compile.texi b/doc/develenv/compile.texi new file mode 100644 index 0000000000..7ef2e99b92 --- /dev/null +++ b/doc/develenv/compile.texi @@ -0,0 +1,157 @@ +@c This chapter is not currently in the Development Environment Guide. + +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas Building the Entire Tree, Test Suite Source Directory, Top +@end ifinfo +@chapter Compilation and GNU Make Stanzas +@ifinfo +@menu +* Compilation and GNU Make Stanzas Building the Entire Tree:: +* Compilation and GNU Make Stanzas Making a Component:: +* Compilation and GNU Make Stanzas Optional Manager Support:: +@end menu +@end ifinfo + +RTEMS is compiled using the GNU gmake(1G) utilities. +All examples in this section are with the gmake(1G) command. +Note that the installation procedure for GNU Make installs it as +make. It is referred to as gmake in this document to +distinguish it from any other make utilities which may also be +on the development system. + +The GNU Make utility uses a file that describes the +relationships among the files and the operations necessary for +updating each file. The GNU Make utility uses stanzas to specify +which set of relationships to update. Each component and suite +control directory contains a make control file, Makefile, which +describes the relationships which must be checked and the +associated update operations for each stanza. This facility is +used to perform compilation, to remove intermediate files, to +install RTEMS, and to maintain release and working set source +and documentation notebooks. The following is a list of stanzas +used by RTEMS make control files: + +@ifset use-texinfo-tables +@table @code +@item all +perform compilation but do not install + +@item install +perform compilation if directory contains source but do not install + +@item clean +delete most generated files and directories for the current CPU and target + +@item clobber +delete all generated files and directories for the current CPU and target +@end table +@end ifset + +@ifclear use-texinfo-tables +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center>all</TD> + <TD ALIGN=center>perform compilation but do not install</TD></TR> +<TR><TD ALIGN=center>install</TD> + <TD ALIGN=center>perform compilation if directory contains source + but do not install</TD></TR> +<TR><TD ALIGN=center>clean</TD> + <TD ALIGN=center>delete most generated files and directories for + the current CPU and target</TD></TR> +<TR><TD ALIGN=center>clobber</TD> + <TD ALIGN=center>delete all generated files and directories for + the current CPU and target</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifclear + +@ifinfo +@node Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas +@end ifinfo +@section Building the Entire Tree + +At the top of the C source tree, execute the command +gmake all. This will build and install all components and tests +into the directory <TARGET> in this directory. + +@ifinfo +@node Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas Optional Manager Support, Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas +@end ifinfo +@section Making a Component + +A single component can be compiled by changing to the +directory which contains that component and performing the +following command: + +@example +gmake +@end example + + +This is equivalent to the following command: + +@example +gmake all +@end example + +Both commands will result in the GNU Make utility +determining which files require compilation or assembly. If any +files require compilation or assembly, then these operations +will be performed followed by the appropriate archive or link +command. Files installed are placed in subdirectories under the +install point. The install point is determined by the setting +of the variable PROJECT_HOME in the file +c/make/custom/<TARGET>.cfg. + +If the current directory is not a leaf directory, +then the requested operation will be performed recursively to +all subdirectories under the current directory. + +By specifying one of the other stanzas supported by +the Makefile, the GNU Make utility can be used to perform such +operations as removing all automatically generated files in a +component (clean and clobbers stanza). + +NOTE: For many components it is not possible to +compile them until other components have been installed. + +@ifinfo +@node Compilation and GNU Make Stanzas Optional Manager Support, Sample Applications, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas +@end ifinfo +@section Optional Manager Support + +RTEMS allows the C applications developer to build +images that only contain those components of the executive that +are needed, leaving out those that will not be utilized. This +is accomplished by the RTEMS Makefile system linking in the +"stub" versions of the optional managers in the place of those +managers not needed by the specific application. The +application Makefile sets the system variable $(MANAGERS) list +to contain those managers that are required by the application. +The RTEMS Makefile system then is able to build a list of +managers that are unwanted, effectively linking in the stubbed +versions of these managers before the RTEMS library is built. + +For more information and implementation details refer +to the following files: + +@itemize @bullet +@item c/make/leaf.cfg, + +@item a Makefile for a test or sample application, and + +@item a compiler description file from c/make/compilers +@end itemize + +These files demonstrate the use of $(MANAGERS) and +how the unwanted managers are handled. + + diff --git a/doc/develenv/develenv.texi b/doc/develenv/develenv.texi new file mode 100644 index 0000000000..7c6eeeb370 --- /dev/null +++ b/doc/develenv/develenv.texi @@ -0,0 +1,119 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename develenv +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file +@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 ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS C User: (develenv). The C User's Guide +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c variable substitution info: +@c +@c @set RTEMS-LANGUAGE C +@c the language is @value{RTEMS-LANGUAGE} +@c NOTE: don't use underscore in the name +@c + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS Development Environment Guide + +@setchapternewpage odd +@settitle RTEMS Development Environment Guide +@titlepage +@finalout + +@title RTEMS Development Environment Guide +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include intro.texi +@include direct.texi +@c @include compile.texi +@include sample.texi +@include utils.texi + +@ifinfo +@node Top, Introduction, (dir), (dir) +@top develenv + +This is the online version of the RTEMS Development Environment Guide. + +@c * Compilation and GNU Make Stanzas:: + +@menu +* Introduction:: +* Directory Structure:: +* Sample Applications:: +* RTEMS Specific Utilities:: +* 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, RTEMS Specific Utilities Ada Language Specific Utilities, 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 + +@contents +@bye + diff --git a/doc/develenv/direct.texi b/doc/develenv/direct.texi new file mode 100644 index 0000000000..cea5959241 --- /dev/null +++ b/doc/develenv/direct.texi @@ -0,0 +1,712 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Directory Structure, Directory Structure Suites, Introduction, Top +@end ifinfo +@chapter Directory Structure +@ifinfo +@menu +* Directory Structure Suites:: +@end menu +@end ifinfo + +The RTEMS directory structure is designed to meet +the following requirements: + +@itemize @bullet +@item encourage development of modular components. + +@item isolate processor and target dependent code, while +allowing as much common source code as possible to be shared +across multiple processors and targets. + +@item allow multiple RTEMS users to perform simultaneous +compilation of RTEMS and its support facilities for different +processors and targets. +@end itemize + +The resulting directory structure has processor and +target dependent source files isolated from generic files. When +RTEMS is built, object directories and an install point will be +automatically created based upon the target BSP selected. The +placement of object files based upon the selected BSP name +insures that object files are not mixed across CPUs or targets. +This in combination with the make files allows the specific +compilation options to be tailored for a particular target +board. For example, the efficiency of the memory subsystem for +a particular target board may be sensitive to the alignment of +data structures, while on another target board with the same +processor memory may be very limited. For the first target, the +options could specify very strict alignment requirements, while +on the second the data structures could be "packed" to conserve +memory. It is impossible to achieve this degree of flexibility +without providing source code. +@ifinfo +@node Directory Structure Suites, C Suites, Directory Structure, Directory Structure +@end ifinfo +@section Suites +@ifinfo +@menu +* C Suites:: +* Executive Source Directory:: +* Support Library Source Directory:: +* Test Suite Source Directory:: +@end menu +@end ifinfo + +The RTEMS source tree is organized based on the +following four variables: + +@itemize @bullet +@item language, + +@item target processor, + +@item target board, and + +@item compiler vendor (Ada only). +@end itemize + +The language may be either C or Ada and there is +currently nothing shared between the source trees for these two +implementations of RTEMS. The user generally selects the +subdirectory for the implementation they are using and ignores +that for the other implementation. The only exceptions to this +normally occurs when comparing the source code for the two +implementations or when porting both to a new CPU or target +board. The following shows the top level RTEMS directory +structure which includes directories for each language +implementation and a language independent source documentation +directory. The source documentation directory is currently not +supported. + +@c +@c Tree 1 - Top Level +@c + +@ifset use-ascii +@example +@group + RTEMS + | ++-----------------------+-----------------------+ +| | +c doc +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 15.0em +\hskip 1.25em\hbox to 3.00em{\hss{RTEMS}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 15.0em +\hskip 2.75em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 0.25em\vrule width2.50em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width2.50em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 0.25em\vrule width.04em% +\hskip 4.92em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 0.00em\hbox to 0.50em{\hss{c}\hss}% +\hskip 1.50em\hbox to 1.50em{\hss{ }\hss}% +\hskip 1.00em\hbox to 1.50em{\hss{doc}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@c +@c for now continue to use the ascii +@c +@ifset use-html +@example +@group + RTEMS + | ++-----------------------+-----------------------+ +| | +c doc +@end group +@end example +@html +@end html +@end ifset + +Each of the following sections will describe the +contents of the directories in the RTEMS source +tree. + +@ifinfo +@node C Suites, Executive Source Directory, Directory Structure Suites, Directory Structure Suites +@end ifinfo +@subsection C Suites + +The following table lists the suites currently included with the +C implementation of RTEMS and the directory in which they may be located: + +@ifset use-texinfo-tables +@table @code +@item Support Libraries (BSPs, C library, CPU support) +$RTEMS_ROOT/c/src/lib + +@item Single Processor Tests +$RTEMS_ROOT/c/src/tests/sptests + +@item Timing Tests +$RTEMS_ROOT/c/src/tests/tmtests + +@item Multiprocessor Tests +$RTEMS_ROOT/c/src/tests/mptests + +@item Sample Applications +$RTEMS_ROOT/c/src/tests/samples + +@item RTEMS Build Tools +$RTEMS_SRC_BASE/c/build_tools + +@item Make Support +$RTEMS_ROOT/c/make +@end table +@end ifset + +@ifclear use-texinfo-tables +@html +<CENTER> + <TABLE COLS=2 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center>Support Libraries (BSPs, C library, CPU support)</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/src/lib</TD></TR> +<TR><TD ALIGN=center>Single Processor Tests</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/sptests</TD></TR> +<TR><TD ALIGN=center>Timing Tests</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/tmtests</TD></TR> +<TR><TD ALIGN=center>Multiprocessor Tests</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/mptests</TD></TR> +<TR><TD ALIGN=center>Sample Applications</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/samples</TD></TR> +<TR><TD ALIGN=center>RTEMS Build Tools</TD> + <TD ALIGN=center>$RTEMS_SRC_BASE/c/build_tools</TD></TR> +<TR><TD ALIGN=center>Make Support</TD> + <TD ALIGN=center>$RTEMS_ROOT/c/make</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifclear + + +The top level directory structure for the C implementation of RTEMS +is as follows: + +@c +@c Tree 2 - Top C Level +@c + +@ifset use-ascii +@example +@group + C + | + +----------+-----------+----------+ + | | | | +build_tools make src update_tools +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 08.0em +\hskip 13.00em\hbox to 0.50em{\hss{C}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 08.0em +\hskip 13.25em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 08.0em +\hskip 1.75em\vrule width11.50em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width11.50em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 08.0em +\hskip 1.75em\vrule width.04em% +\hskip 5.71em\vrule width.04em% +\hskip 5.71em\vrule width.04em% +\hskip 5.71em\vrule width.04em% +\hskip 5.71em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 08.0em +\hskip 0.00em\hbox to 3.50em{\hss{Modules}\hss}% +\hskip 1.00em\hbox to 6.00em{\hss{build\_tools}\hss}% +\hskip 1.75em\hbox to 2.00em{\hss{make}\hss}% +\hskip 4.00em\hbox to 1.50em{\hss{src}\hss}% +\hskip 1.75em\hbox to 6.50em{\hss{update\_tools}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html +@example +@group + C + | + +----------+-----------+----------+ + | | | | +build_tools make src update_tools +@end group +@end example +@html +@end html +@end ifset + +This directory contains the subdirectories which +contain the entire C implementation of the RTEMS executive. +The "build-tools" directory contains an assortment of support tools +for the RTEMS development environment. Two subdirectories exist +under "build-tools" which contain scripts (executables) and +source for the support tools. The "make" directory contains +configuration files and subdirectories which provide a robust +host and cross-target makefile system supporting the building of +the executive for numerous application environments. The +"update_tools" directory contains utilities which aid in the +updating from a previous version to the current version of the +RTEMS executive. + +The "src" directory structure for the C implementation of RTEMS is as follows: + +@c +@c Tree 3 - Top C src Level +@c + +@ifset use-ascii +@example +@group + C Source + | + +-----------------------+-----------------------+ + | | | +exec lib tests +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 15.0em +\hskip 2.00em\hbox to 4.00em{\hss{C Source}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 15.0em +\hskip 4.00em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 1.00em\vrule width3.00em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width3.00em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 1.00em\vrule width.04em% +\hskip 2.96em\vrule width.04em% +\hskip 2.96em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 15.0em +\hskip 0.00em\hbox to 2.00em{\hss{exec}\hss}% +\hskip 1.25em\hbox to 1.50em{\hss{lib}\hss}% +\hskip 1.00em\hbox to 2.50em{\hss{tests}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html +@example +@group + C Source + | + +-----------------------+-----------------------+ + | | | +exec lib tests +@end group +@end example +@html +@end html +@end ifset + +This directory contains all source files that +comprises the RTEMS executive, supported target board support +packages, and the RTEMS Test Suite. + +@ifinfo +@node Executive Source Directory, Support Library Source Directory, C Suites, Directory Structure Suites +@end ifinfo +@subsection Executive Source Directory + +The "exec" directory structure for the C implementation is as follows: + +@c +@c Tree 4 - C Executive Tree +@c + +@ifset use-ascii +@example +@group + C Executive + | + +-----------+----------+-----------+----------+ + | | | | | +posix rtems sapi score wrapup +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 10.0em +\hskip 6.00em\hbox to 5.50em{\hss{C Executive}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 10.0em +\hskip 8.75em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width7.50em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width7.50em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width.04em% +\hskip 3.71em\vrule width.04em% +\hskip 3.71em\vrule width.04em% +\hskip 3.71em\vrule width.04em% +\hskip 3.71em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 0.00em\hbox to 2.50em{\hss{posix}\hss}% +\hskip 1.25em\hbox to 2.50em{\hss{rtems}\hss}% +\hskip 1.50em\hbox to 2.00em{\hss{sapi}\hss}% +\hskip 1.50em\hbox to 2.50em{\hss{score}\hss}% +\hskip 1.00em\hbox to 3.00em{\hss{wrapup}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html + C Executive + | + +-----------+----------+-----------+----------+ + | | | | | +posix rtems sapi score wrapup +@html +@end html +@end ifset + +This directory contains a set of subdirectories which +contains the source files comprising the executive portion of +the RTEMS development environment. At this point the API +specific and "supercore" source code files are separated into +distinct directory trees. The "rtems" and the "posix" +subdirectories contain the C language source files for each +module comprising the respective API. Also included in this +directory are the subdirectories "sapi" and "score" which are +the supercore modules. Within the "score" directory the CPU +dependent modules are found. + +The "cpu" directory contains a subdirectory for each +target CPU supported by the @value{RTEMS-RELEASE} release of the RTEMS +executive. Each processor directory contains the CPU dependent +code necessary to host RTEMS. The "no_cpu" directory provides a +starting point for developing a new port to an unsupported +processor. The files contained within the "no_cpu" directory +may also be used as a reference for the other ports to specific +processors. + +@ifinfo +@node Support Library Source Directory, Test Suite Source Directory, Executive Source Directory, Directory Structure Suites +@end ifinfo +@subsection Support Library Source Directory + +The "lib" directory contains the support libraries and BSPS. +Board support packages (BSPs), processor environment start up code, +C library support, the KA9Q TCP/IP stack, common BSP header files, +and miscellaneous support functions are provided in the subdirectories. +These are combined with the RTEMS executive object to form the single +RTEMS library which installed. + +@c +@c Tree 6 - Libraries +@c + + +The "libbsp" directory contains a directory for each CPU family supported +by RTEMS. Beneath each CPU directory is a directory for each BSP for that +processor family. + +@c +@c Tree 7 - C BSP Library +@c + +Th "libbsp" directory provides all the BSPs provided with this +release of the RTEMS executive. The subdirectories are +divided, as discussed previously, based on specific processor +family, then further breaking down into specific target board +environments. The "shmdr" subdirectory provides the +implementation of a shared memory driver which supports the +multiprocessing portion of the executive. In addition, two +starting point subdirectories are provided for reference. The +"no_cpu" subdirectory provides a template BSP which can be used +to develop a specific BSP for an unsupported target board. The +"stubdr" subdirectory provides stubbed out BSPs. These files +may aid in preliminary testing of the RTEMS development +environment that has been built for no particular target in mind. + +Below each CPU dependent directory is a directory for each target BSP +supported in this release. + +Each BSP provides the modules which comprise an RTEMS BSP. The +modules are separated into the subdirectories "clock", "console", +"include", "shmsupp", "startup", and "timer" as shown in the following +figure: + +@c +@c Tree 8 - Each BSP +@c + +@ifset use-ascii +@example +@group + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include shmsupp startup timer +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 10.0em +\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 10.0em +\hskip 12.50em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 1.25em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\hskip 4.46em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 10.0em +\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}% +\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}% +\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html + Each BSP + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +clock console include shmsupp startup timer +@html +@end html +@end ifset + +@ifinfo +@node Test Suite Source Directory, Sample Applications, Support Library Source Directory, Directory Structure Suites +@end ifinfo +@subsection Test Suite Source Directory + +The "tests" directory structure for the C +implementation is as follows: + +@c +@c Tree 9 - C Tests +@c + +@ifset use-ascii +@example +@group + C Tests + | + +----------+---------+----------+---------+---------+---------+ + | | | | | | | +libtests sptests support tmtests mptests tools samples +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 05.0em +\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 05.0em +\hskip 16.25em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\hskip 4.71em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}% +\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}% +\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}% +\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}% +\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html + C Tests + | + +----------+---------+----------+---------+---------+---------+ + | | | | | | | +libtests sptests support tmtests mptests tools samples +@html +@end html +@end ifset + +This directory provides the entire RTEMS Test Suite +which includes the single processor tests, multiprocessor tests, +timing tests, library tests, and sample tests. Additionally, +subdirectories for support functions and test related header +files are provided. + +The "sptests" subdirectory consists of twenty-four +tests designed to cover the entire executive code. The +"spfatal" test will verify any code associated with the +occurrence of a fatal error. Also provided is a test which +will determine the size of the RTEMS executive. + +The multiprocessor test are provided in "mptests". +Fourteen tests are provided in this subdirectory which address +two node configurations and cover the multiprocessor code found +in RTEMS. + +Tests that time each directive and a set of critical +executive functions are provided in the "tmtests" subdirectory. +Within this subdirectory thirty-one tests are provided along +with a subdirectory to contain each targets timing results. + +The "samples" directory structure for the C +implementation is as follows: + +@c +@c Tree 10 - C Samples +@c + +@ifset use-ascii +@example +@group + C Samples + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +base_mp base_sp cdtest hello paranoia ticker +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 + +@tex +{\parskip=0pt\offinterlineskip% +\hskip 05.0em +\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}% +\vrule width0em height1.972ex depth0.812ex\par\penalty10000 +\hskip 05.0em +\hskip 14.50em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex% +\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 2.00em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\hskip 4.96em\vrule width.04em% +\vrule width0em height1.500ex depth0.500ex\par\penalty10000 +\hskip 05.0em +\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}% +\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}% +\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}% +\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}% +\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}% +\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}% +\vrule width0em height1.972ex depth0.812ex\par} +@end tex +@end ifset + +@ifset use-html + C Samples + | + +-----------+----------+-----+-----+----------+----------+ + | | | | | | +base_mp base_sp cdtest hello paranoia ticker +@html +@end html +@end ifset + +This directory provides sample application tests +which aid in the testing a newly built RTEMS environment, a new +BSP, or as starting points for the development of an application +using the RTEMS executive. A Hello World test is provided in +the subdirectory "hello". This test is helpful when testing new +versions of RTEMS, BSPs, or modifications to any portion of the +RTEMS development environment. The "ticker" subdirectory +provides a test for verification of clock chip device drivers of +BSPs. A simple single processor test similar to those in the +single processor test suite is provided in "base_sp". A simple +two node multiprocessor test capable of testing an newly +developed MPCI layer is provided in "base_mp". The "cdtest" +subdirectory provides a simple C++ application using +constructors and destructors. The final sample test is a +public domain floating point and math library toolset test is +provided in "paranoia". diff --git a/doc/develenv/intro.texi b/doc/develenv/intro.texi new file mode 100644 index 0000000000..c8fdde131d --- /dev/null +++ b/doc/develenv/intro.texi @@ -0,0 +1,56 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Introduction, Directory Structure, Top, Top +@end ifinfo +@chapter Introduction + +This document describes the RTEMS development +environment. Discussions are provided for the following topics: + +@itemize @bullet +@item the directory structure used by RTEMS, + +@item usage of the GNU Make utility within the RTEMS +development environment, + +@item sample applications, and + +@item the RTEMS specific utilities. +@end itemize + +RTEMS was designed as a reusable software component. +Highly reusable software such as RTEMS is typically distributed +in the form of source code without providing any support tools. +RTEMS is the foundation for a complex family of facilities +including board support packages, device drivers, and support +libraries. The RTEMS Development Environment is not a CASE +tool. It is a collection of tools designed to reduce the +complexity of using and enhancing the RTEMS family. Tools are +provided which aid in the management of the development, +maintenance, and usage of RTEMS, its run-time support +facilities, and applications which utilize the executive. + +A key component of the RTEMS development environment +is the GNU family of free tools. This is robust set of +development and POSIX compatible tools for which source code is +freely available. The primary compilers, assemblers, linkers, +and make utility used by the RTEMS development team are the GNU +tools. They are highly portable supporting a wide variety of +host computers and, in the case of the development tools, a wide +variety of target processors. + +It is recommended that the RTEMS developer become +familiar with the RTEMS Development Environment before +proceeding with any modifications to the executive source tree. +The source code for the executive is very modular and source +code is divided amongst directories based upon functionality as +well as dependencies on CPU and target board. This organization +is aimed at isolating and minimizing non-portable code. This +has the immediate result that adding support for a new CPU or +target board requires very little "wandering" around the source +tree. diff --git a/doc/develenv/sample.texi b/doc/develenv/sample.texi new file mode 100644 index 0000000000..3c7f55ab35 --- /dev/null +++ b/doc/develenv/sample.texi @@ -0,0 +1,287 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Sample Applications, Sample Applications Introduction, Test Suite Source Directory, Top +@end ifinfo +@chapter Sample Applications +@ifinfo +@menu +* Sample Applications Introduction:: +* Sample Applications Hello World:: +* Sample Applications Clock Tick:: +* Sample Applications Base Single Processor Application:: +* Sample Applications Base Multiple Processor Application:: +* Sample Applications Constructor/Destructor C++ Application:: +* Sample Applications Paranoia Floating Point Application:: +@end menu +@end ifinfo + +@ifinfo +@node Sample Applications Introduction, Sample Applications Hello World, Sample Applications, Sample Applications +@end ifinfo +@section Introduction + +RTEMS is shipped with the following sample +applications: + +@itemize @bullet +@item Hello World - C and Ada + +@item Clock Tick - C and Ada + +@item Base Single Processor - C and Ada + +@item Base Multiple Processor - C and Ada + +@item Constructor/Destructor C++ Test - C only if C++ +enabled + +@item Paranoia Floating Point Test - C only +@end itemize + +These applications are intended to illustrate the +basic format of RTEMS single and multiple processor +applications. In addition, these relatively simple applications +can be used to test locally developed board support packages and +device drivers. + +The reader should be familiar with the terms used and +material presented in the RTEMS C Applications User's Guide or +the RTEMS Ada Applications User's Guide. + +@ifinfo +@node Sample Applications Hello World, Sample Applications Clock Tick, Sample Applications Introduction, Sample Applications +@end ifinfo +@section Hello World + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/hello +@end example + +It provides a rudimentary test of the BSP start up +code and the console output routine. The C version of this +sample application uses the printf function from the RTEMS +Standard C Library to output messages. The Ada version of this +sample use the TEXT_IO package to output the hello messages. +The following messages are printed: + +@example +@group +*** HELLO WORLD TEST *** +Hello World +*** END OF HELLO WORLD TEST *** +@end group +@end example + +These messages are printed from the application's +single initialization task. If the above messages are not +printed correctly, then either the BSP start up code or the +console output routine is not operating properly. + +@ifinfo +@node Sample Applications Clock Tick, Sample Applications Base Single Processor Application, Sample Applications Hello World, Sample Applications +@end ifinfo +@section Clock Tick + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/ticker +@end example + +This application is designed as a simple test of the +clock tick device driver. In addition, this application also +tests the printf function from the RTEMS Standard C Library by +using it to output the following messages: + +@example +@group +*** CLOCK TICK TEST *** +TA1 - tm_get - 09:00:00 12/31/1988 +TA2 - tm_get - 09:00:00 12/31/1988 +TA3 - tm_get - 09:00:00 12/31/1988 +TA1 - tm_get - 09:00:05 12/31/1988 +TA1 - tm_get - 09:00:10 12/31/1988 +TA2 - tm_get - 09:00:10 12/31/1988 +TA1 - tm_get - 09:00:15 12/31/1988 +TA3 - tm_get - 09:00:15 12/31/1988 +TA1 - tm_get - 09:00:20 12/31/1988 +TA2 - tm_get - 09:00:20 12/31/1988 +TA1 - tm_get - 09:00:25 12/31/1988 +TA1 - tm_get - 09:00:30 12/31/1988 +TA2 - tm_get - 09:00:30 12/31/1988 +TA3 - tm_get - 09:00:30 12/31/1988 +*** END OF CLOCK TICK TEST *** +@end group +@end example + +The clock tick sample application utilizes a single +initialization task and three copies of the single application +task. The initialization task prints the test herald, sets the +time and date, and creates and starts the three application +tasks before deleting itself. The three application tasks +generate the rest of the output. Every five seconds, one or +more of the tasks will print the current time obtained via the +tm_get directive. The first task, TA1, executes every five +seconds, the second task, TA2, every ten seconds, and the third +task, TA3, every fifteen seconds. If the time printed does not +match the above output, then the clock device driver is not +operating properly. + +@ifinfo +@node Sample Applications Base Single Processor Application, Sample Applications Base Multiple Processor Application, Sample Applications Clock Tick, Sample Applications +@end ifinfo +@section Base Single Processor Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/base_sp +@end example + +It provides a framework from which a single processor +RTEMS application can be developed. The use of the task argument +is illustrated. This sample application uses the printf +function from the RTEMS Standard C Library or TEXT_IO functions +when using the Ada version to output the following messages: + +@example +@group +*** SAMPLE SINGLE PROCESSOR APPLICATION *** +Creating and starting an application task +Application task was invoked with argument (0) and has id of 0x10002 +*** END OF SAMPLE SINGLE PROCESSOR APPLICATION *** +@end group +@end example + +The first two messages are printed from the +application's single initialization task. The final messages +are printed from the single application task. + +@ifinfo +@node Sample Applications Base Multiple Processor Application, Sample Applications Constructor/Destructor C++ Application, Sample Applications Base Single Processor Application, Sample Applications +@end ifinfo +@section Base Multiple Processor Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/base_mp +@end example + +It provides a framework from which a multiprocessor +RTEMS application can be developed. This directory has a +subdirectory for each node in the multiprocessor system. The +task argument is used to distinguish the node on which the +application task is executed. The first node will print the +following messages: + +@example +@group +*** SAMPLE MULTIPROCESSOR APPLICATION *** +Creating and starting an application task +This task was invoked with the node argument (1) +This task has the id of 0x10002 +*** END OF SAMPLE MULTIPROCESSOR APPLICATION *** +@end group +@end example + +The second node will print the following messages: + +@example +@group +*** SAMPLE MULTIPROCESSOR APPLICATION *** +Creating and starting an application task +This task was invoked with the node argument (2) +This task has the id of 0x20002 +*** END OF SAMPLE MULTIPROCESSOR APPLICATION *** +@end group +@end example + +The herald is printed from the application's single +initialization task on each node. The final messages are +printed from the single application task on each node. + +In this sample application, all source code is shared +between the nodes except for the node dependent configuration +files. These files contains the definition of the node number +used in the initialization of the RTEMS Multiprocessor +Configuration Table. This file is not shared because the node +number field in the RTEMS Multiprocessor Configuration Table +must be unique on each node. + +@ifinfo +@node Sample Applications Constructor/Destructor C++ Application, Sample Applications Paranoia Floating Point Application, Sample Applications Base Multiple Processor Application, Sample Applications +@end ifinfo +@section Constructor/Destructor C++ Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/cdtest +@end example + +This sample application demonstrates that RTEMS is +compatible with C++ applications. It uses constructors, +destructor, and I/O stream output in testing these various +capabilities. The board support package responsible for this +application must support a C++ environment. + +This sample application uses the printf function from +the RTEMS Standard C Library to output the following messages: + +@example +@group +Hey I'M in base class constructor number 1 for 0x400010cc. +Hey I'M in base class constructor number 2 for 0x400010d4. +Hey I'M in derived class constructor number 3 for 0x400010d4. +*** CONSTRUCTOR/DESTRUCTOR TEST *** +Hey I'M in base class constructor number 4 for 0x4009ee08. +Hey I'M in base class constructor number 5 for 0x4009ee10. +Hey I'M in base class constructor number 6 for 0x4009ee18. +Hey I'M in base class constructor number 7 for 0x4009ee20. +Hey I'M in derived class constructor number 8 for 0x4009ee20. +Testing a C++ I/O stream +Hey I'M in derived class constructor number 8 for 0x4009ee20. +Derived class - Instantiation order 8 +Hey I'M in base class constructor number 7 for 0x4009ee20. +Instantiation order 8 +Hey I'M in base class constructor number 6 for 0x4009ee18. +Instantiation order 6 +Hey I'M in base class constructor number 5 for 0x4009ee10. +Instantiation order 5 +Hey I'M in base class constructor number 4 for 0x4009ee08. +Instantiation order 5 +*** END OF CONSTRUCTOR/DESTRUCTOR TEST *** +Hey I'M in base class constructor number 3 for 0x400010d4. +Hey I'M in base class constructor number 2 for 0x400010d4. +Hey I'M in base class constructor number 1 for 0x400010cc. +@end group +@end example + +@ifinfo +@node Sample Applications Paranoia Floating Point Application, RTEMS Specific Utilities, Sample Applications Constructor/Destructor C++ Application, Sample Applications +@end ifinfo +@section Paranoia Floating Point Application + +This sample application is in the following directory: + +@example +$RTEMS_SRC_BASE/tests/samples/paranoia +@end example + +This sample application uses a public domain floating +point and math library test to verify these capabilities of the +RTEMS executive. Deviations between actual and expected results +are reported to the screen. This is a very extensive test which +tests all mathematical and number conversion functions. +Paranoia is also very large and requires a long period of time +to run. Problems which commonly prevent this test from +executing to completion include stack overflow and FPU exception +handlers not installed. diff --git a/doc/develenv/utils.texi b/doc/develenv/utils.texi new file mode 100644 index 0000000000..b76c94ae7e --- /dev/null +++ b/doc/develenv/utils.texi @@ -0,0 +1,310 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node RTEMS Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities, Sample Applications Paranoia Floating Point Application, Top +@end ifinfo +@chapter RTEMS Specific Utilities +@ifinfo +@menu +* RTEMS Specific Utilities C Language Specific Utilities:: +* RTEMS Specific Utilities Ada Language Specific Utilities:: +@end menu +@end ifinfo + +This section describes the additional commands +available within the RTEMS Development Environment. Although +some of these commands are of general use, most are included to +provide some capability necessary to perform a required function +in the development of the RTEMS executive, one of its support +components, or an RTEMS based application. The commands have +been classified into the following categories for clarity: + +@itemize @bullet +@item C Language Specific Utilities + +@item Ada Language Specific Utilities +@end itemize + +Some of the commands are implemented as C programs. +However, most commands are implemented as Bourne shell scripts. +Even if the current user has selected a different shell, the +scripts will automatically invoke the Bourne shell during their +execution lifetime. + +The commands are presented in UNIX manual page style +for compatibility and convenience. A standard set of paragraph +headers were used for all of the command descriptions. If a +section contained no data, the paragraph header was omitted to +conserve space. Each of the permissible paragraph headers and +their contents are described below: + +@table @code +@item SYNOPSIS +describes the command syntax + +@item DESCRIPTION +a full description of the command + +@item OPTIONS +describes each of the permissible options for the command + +@item NOTES +lists any special noteworthy comments about the command + +@item ENVIRONMENT +describes all environment variables utilized by the command + +@item EXAMPLES +illustrates the use of the command with specific examples + +@item FILES +provides a list of major files that the command references + +@item SEE ALSO +lists any relevant commands which can be consulted +@end table + +Most environment variables referenced by the commands +are defined for the RTEMS Development Environment during the +login procedure. During login, the user selects a default RTEMS +environment through the use of the Modules package. This tool +effectively sets the environment variables to provide a +consistent development environment for a specific user. +Additional environment variables within the RTEMS environment +were set by the system administrator during installation. When +specifying paths, a command description makes use of these +environment variables. + +When referencing other commands in the SEE ALSO +paragraph, the following notation is used: command(code). +Where command is the name of a related command, and code is a +section number. Valid section numbers are as follows: + +@table @code +@item 1 +Section 1 of the standard UNIX documentation + +@item 1G +Section 1 of the GNU documentation + +@item 1R +a manual page from this document, the RTEMS Development Environment Guide +@end table + +For example, ls(1) means see the standard ls command +in section 1 of the UNIX documentation. gcc020(1G) means see +the description of gcc020 in section 1 of the GNU documentation. + +@ifinfo +@node RTEMS Specific Utilities C Language Specific Utilities, packhex - Compress Hexadecimal File, RTEMS Specific Utilities, RTEMS Specific Utilities +@end ifinfo +@section C Language Specific Utilities +@ifinfo +@menu +* packhex - Compress Hexadecimal File:: +* unhex - Convert Hexadecimal File into Binary:: +* size_rtems - report RTEMS size information:: +@end menu +@end ifinfo + +The C language utilities provide a powerful set of +tools which combine to allow operations within the RTEMS +Development Environment to be consistent and easy to use. Much +effort was devoted to providing as close to the standard UNIX +and GNU style of operations as possible. Each of these +utilities are described in the section below. + +@ifinfo +@node packhex - Compress Hexadecimal File, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities +@end ifinfo +@subsection packhex - Compress Hexadecimal File + +@subheading SYNOPSIS + +@example +packhex <source >destination +@end example + +@subheading DESCRIPTION + +packhex accepts Intel Hexadecimal or Motorola Srecord +on its standard input and attempts to pack as many contiguous +bytes as possible into a single hexadecimal record. Many +programs output hexadecimal records which are less than 80 bytes +long (for human viewing). The overhead required by each +unnecessary record is significant and packhex can often reduce +the size of the download image by 20%. packhex attempts to +output records which are as long as the hexadecimal format +allows. + +@subheading OPTIONS + +This command has no options. + +@subheading EXAMPLES + +Assume the current directory contains the Motorola +Srecord file download.sr. Then executing the command: + +@example +packhex <download.sr >packed.sr +@end example + +will generate the file packed.sr which is usually +smaller than download.sr. + +@subheading CREDITS + +The source for packhex first appeared in the May 1993 +issue of Embedded Systems magazine. The code was downloaded +from their BBS. Unfortunately, the author's name was not +provided in the listing. + +@ifinfo +@node unhex - Convert Hexadecimal File into Binary, size_rtems - report RTEMS size information, packhex - Compress Hexadecimal File, RTEMS Specific Utilities C Language Specific Utilities +@end ifinfo +@subsection unhex - Convert Hexadecimal File into Binary Equivalent + +@subheading SYNOPSIS + +@example +unhex [-valF] [-o file] [file [file ...] ] +@end example + +@subheading DESCRIPTION + +unhex accepts Intel Hexadecimal, Motorola Srecord, or +TI 'B' records and converts them to their binary equivalent. +The output may sent to standout or may be placed in a specified +file with the -o option. The designated output file may not be +an input file. Multiple input files may be specified with their +outputs logically concatenated into the output file. + +@subheading OPTIONS + +This command has the following options: + +@table @code +@item v +Verbose + +@item a base +First byte of output corresponds with base +address + +@item l +Linear Output + +@item o file +Output File + +@item F k_bits +Fill holes in input with 0xFFs up to k_bits * 1024 bits +@end table + +@subheading EXAMPLES + +The following command will create a binary equivalent +file for the two Motorola S record files in the specified output +file binary.bin: + +@example +unhex -o binary.bin downloadA.sr downloadB.sr +@end example + +@ifinfo +@node size_rtems - report RTEMS size information, RTEMS Specific Utilities Ada Language Specific Utilities, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities +@end ifinfo +@subsection size_rtems - report RTEMS size information + +@subheading SYNOPSIS + +@example +size_rtems +@end example + +@subheading DESCRIPTION + +size_rtems analyzes RTEMS and determines all of the +critical sizing information which is reported in the related +documentation. + +@subheading EXAMPLES + +To generate the RTEMS size report for the currently +configured processor, execute the following command: + +@example +size_rtems +@end example + +Although the actual size information will differ, a +report of the following format will be output: + +@example + RTEMS SIZE REPORT + +CODE DATA BSS +================== +MANAGERS: 15988 0 0 +CORE : 4568 0 0 +CPU : 364 0 0 +OVERALL : 20556 0 0 +MINIMUM : 8752 0 0 + +init : 1592 0 0 +tasks : 2440 0 0 +intr : 64 0 0 +clock : 2252 0 0 +sem : 876 0 0 +msg : 1624 0 0 +event : 604 0 0 +signal : 212 0 0 +part : 872 0 0 +region : 844 0 0 +dpmem : 532 0 0 +timer : 424 0 0 +io : 288 0 0 +fatal : 40 0 0 +rtmon : 764 0 0 +mp : 2984 0 0 + +sem : 4 0 0 +msg : 4 0 0 +event : 4 0 0 +signal : 4 0 0 +part : 4 0 0 +region : 4 0 0 +timer : 4 0 0 +dpmem : 4 0 0 +io : 4 0 0 +rtmon : 4 0 0 +mp : 8 0 0 +@end example + +@subheading SEE ALSO + +gsize020(1G), gsize386(1G), gsize960(1G) + + +@ifinfo +@node RTEMS Specific Utilities Ada Language Specific Utilities, Command and Variable Index, size_rtems - report RTEMS size information, RTEMS Specific Utilities +@end ifinfo +@section Ada Language Specific Utilities + +The Ada language utilities provide a powerful set of +tools which combine to allow operations within the RTEMS +Development Environment to be consistent and easy to use. Much +effort was devoted to providing as close to the standard UNIX +and GNU style of operations as possible. Each of these +utilities are described in the section below. + +NOTE: The Ada implementation is not included in this +release. + + + diff --git a/doc/do_docs b/doc/do_docs new file mode 100755 index 0000000000..debf0b3cbb --- /dev/null +++ b/doc/do_docs @@ -0,0 +1,18 @@ +#! /bin/sh + +basedir=$1 +shift +manuals="develenv hppa1_1 i386 i960 m68k relnotes sparc user" +# posix_test_plan manual left out in 4.0.0 + +for action in $* +do + for manual in $manuals + do + echo + echo "*** make $action on ${basedir}/${manual} ***" + echo + cd ${basedir}/${manual} + gmake $action || exit $? + done +done diff --git a/doc/import_ami_txt b/doc/import_ami_txt new file mode 100644 index 0000000000..3de3af993d --- /dev/null +++ b/doc/import_ami_txt @@ -0,0 +1,81 @@ +#! /bin/bash +# +# This script converts the ASCII version of the manual saved by AmiPro +# into a reasonably acceptable form of Texinfo. The output of this program +# is fed into another program which inserts texinfo node and menu infomation. +# + +#set -x + +#rm -f *.txt +orig=/usr1/home/joel/tmp/doc/relnotes +inputfiles=`cd $orig ; echo *.txt` + +for i in $inputfiles +do + echo $i + out=`echo $i | sed -e 's/\.txt$/.texi/'` + # 1. Remove <ctl>-Z and <ctl>-M + # 2. Tackle paragraph style issues + # 3. Directive status code lines + + tr -d '\032\015' <${orig}/$i | + sed -e 's/<Topic Lvl 0>/@chapter /' | + sed -e 's/<Topic Lvl 1>/@section /' | + sed -e 's/<Topic Lvl 2>/@subsection /' | + sed -e 's/<Topic Lvl 3>/@subsection /' | + sed -e 's/<Body Text>//' | + sed -e 's/<Directive Tbl>/@item /' | + sed -e 's/<Table Title>/@itemize /' | + sed -e 's/<Bullet>/@item /' | + sed -e 's/<Bullet 2>/@item /' | + sed -e 's/<Table Text>/@item /' | + sed -e 's/<Number List>/@item /' | + sed -e 's/<Time Desc>/@item /' | + while read line + do + case $line in + "<C Code Exampl>"*"{") echo "@example"; echo "$line" ; read line;; + "<C Code Exampl>"*"(") echo "@example"; echo "$line" ; read line;; + "<C Code Exampl>"*");") echo "$line" ; echo "@end example" ;; + "<C Code Exampl>"*"}"*";") echo "$line" ; echo "@end example" ;; + "<C Code Exampl>"*",") echo "$line" ; read line ;; + "<C Code Exampl>"*";") echo "$line" ; read line ;; + *) echo "$line" ;; + esac + done | + sed -e 's/<C Code Exampl>//' | + sed -e 's/<Directive Tbl>/@item /' | + sed -e 's/<Topic>/@subheading /' | + sed -e 's/<Directive>/@page\ +@subsection /' | + sed -e 's/<Status Codes>//' | + sed -e 's/^\(SUCCESSFUL\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(TASK_EXITTED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(MP_NOT_CONFIGURED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_NAME\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_ID\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(TOO_MANY\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(TIMEOUT\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(OBJECT_WAS_DELETED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_SIZE\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_ADDRESS\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_NUMBER\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(NOT_DEFINED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(RESOURCE_IN_USE\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(UNSATISFIED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INCORRRECT_STATE\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(ALREADY_SUSPENDED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(ILLEGAL_ON_SELF\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(ILLEGAL_ON_REMOTE_OBJECT\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(CALLED_FROM_ISR\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_PRIORITY\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_TIME_OF_DAY\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INVALID_NODE\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(NOT_CONFIGURED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(NOT_OWNER_OF_RESOURCE\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(NOT_IMPLEMENTED\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(INTERNAL_ERROR\) - \(.*\)/@code{\1} - \2@*/' | + sed -e 's/^\(NO_MEMORY\) - \(.*\)/@code{\1} - \2@*/' | + cat >$out +done diff --git a/doc/new_chapters/Makefile b/doc/new_chapters/Makefile new file mode 100644 index 0000000000..65977364ad --- /dev/null +++ b/doc/new_chapters/Makefile @@ -0,0 +1,59 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=posix +DOCNAME=posix_test_plan + +all: + +COMMON_FILES=../common/cpright.texi +FILES= clock.texi cond.texi key.texi mutex.texi $(DOCNAME).texi preface.texi \ + sched.texi signal.texi thread.texi $(COMMON_FILES) + +all: + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: $(DOCNAME) +# cp $(DOCNAME) $(DOCNAME)-* $(INFO_INSTALL) + cp $(DOCNAME) $(INFO_INSTALL) + +posix_test_plan: $(FILES) + $(MAKEINFO) $(DOCNAME).texi + +vinfo: info + $(INFO) -f ./$(DOCNAME) + +dvi: $(DOCNAME).dvi +ps: $(DOCNAME).ps + +$(DOCNAME).ps: $(DOCNAME).dvi + dvips -o $(DOCNAME).ps $(DOCNAME).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(DOCNAME).dvi + +view: ps + $(GHOSTVIEW) $(DOCNAME).ps + +$(DOCNAME).dvi: $(FILES) + $(TEXI2DVI) $(DOCNAME).texi + +html: + -mkdir $(WWW_INSTALL)/$(DOCNAME) + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/c_$(PROJECT) \ + $(PROJECT).texi + cp ../rtems.html $(WWW_INSTALL) + + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(DOCNAME) $(DOCNAME)-* _* + diff --git a/doc/new_chapters/base.texi b/doc/new_chapters/base.texi new file mode 100644 index 0000000000..ee0c280d63 --- /dev/null +++ b/doc/new_chapters/base.texi @@ -0,0 +1,96 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Mutex Manager, Mutex Manager Introduction, Preface, Top +@end ifinfo +@chapter Mutex Manager +@ifinfo +@menu +* Mutex Manager Introduction:: +* Mutex Manager Background:: +* Mutex Manager Operations:: +* Mutex Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager +@end ifinfo +@section Introduction + +The mutex manager ... + +The directives provided by the mutex manager are: + +@itemize @bullet +@item @code{sigaddset} - +@item @code{sigdelset} - +@item @code{sigfillset} - +@item @code{sigismember} - +@item @code{sigemptyset} - +@item @code{sigaction} - +@item @code{pthread_kill} - +@item @code{pthread_sigmask} - +@item @code{kill} - +@item @code{sigwait} - +@end itemize + +@ifinfo +@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager +@end ifinfo +@section Background + +@ifinfo +@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager +@end ifinfo +@section Operations + +@ifinfo +@node Mutex Manager Directives, sigaddset, Mutex Manager Operations, Mutex Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sigaddset:: +* sigdelset:: +* sigfillset:: +* sigismember:: +* sigemptyset:: +* sigaction:: +* pthread_kill:: +* pthread_sigmask:: +* kill:: +* sigwait:: +@end menu +@end ifinfo + +This section details the mutex manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sigaddset, sigdelset, Mutex Manager Directives, Mutex Manager Directives +@end ifinfo +@subsection sigaddset + +@subheading CALLING SEQUENCE: + +@example +int sigaddset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/clock.texi b/doc/new_chapters/clock.texi new file mode 100644 index 0000000000..1b64d91a6b --- /dev/null +++ b/doc/new_chapters/clock.texi @@ -0,0 +1,262 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Clock Manager, Clock Manager Introduction, pthread_getspecific, Top +@end ifinfo +@chapter Clock Manager +@ifinfo +@menu +* Clock Manager Introduction:: +* Clock Manager Background:: +* Clock Manager Operations:: +* Clock Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager +@end ifinfo +@section Introduction + +The clock manager ... + +The directives provided by the clock manager are: + +@itemize @bullet +@item @code{clock_gettime} - +@item @code{clock_settime} - +@item @code{clock_getres} - +@item @code{nanosleep} - +@item @code{time} - +@end itemize + +@ifinfo +@node Clock Manager Background, Clock Manager Operations, Clock Manager Introduction, Clock Manager +@end ifinfo +@section Background + +@ifinfo +@node Clock Manager Operations, Clock Manager Directives, Clock Manager Background, Clock Manager +@end ifinfo +@section Operations + +@ifinfo +@node Clock Manager Directives, clock_gettime, Clock Manager Operations, Clock Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* clock_gettime:: +* clock_settime:: +* clock_getres:: +* sleep:: +* nanosleep:: +* time:: +@end menu +@end ifinfo + +This section details the clock manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node clock_gettime, clock_settime, Clock Manager Directives, Clock Manager Directives +@end ifinfo +@subsection clock_gettime + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_gettime( + clockid_t clock_id, + struct timespec *tp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The tp pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node clock_settime, clock_getres, clock_gettime, Clock Manager Directives +@end ifinfo +@subsection clock_settime + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_settime( + clockid_t clock_id, + const struct timespec *tp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The tp pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. + +@item EINVAL +The contents of the tp structure are invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node clock_getres, sleep, clock_settime, Clock Manager Directives +@end ifinfo +@subsection clock_getres + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_getres( + clockid_t clock_id, + struct timespec *res +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The res pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If res is NULL, then the resolution is not returned. + +@page +@ifinfo +@node sleep, nanosleep, clock_getres, Clock Manager Directives +@end ifinfo +@subsection sleep + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +unsigned int sleep( + unsigned int seconds +); +@end example + +@subheading STATUS CODES: + +This routine returns the number of unslept seconds. + +@subheading DESCRIPTION: + +@subheading NOTES: + +This call is interruptible by a signal. + +@page +@ifinfo +@node nanosleep, time, sleep, Clock Manager Directives +@end ifinfo +@subsection nanosleep + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int nanosleep( + const struct timespec *rqtp, + struct timespec *rmtp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINTR +The routine was interrupted by a signal. + +@item EAGAIN +The requested sleep period specified negative seconds or nanoseconds. + +@item EINVAL +The requested sleep period specified an invalid number for the nanoseconds +field. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This call is interruptible by a signal. + +@page +@ifinfo +@node time, Scheduler Manager, nanosleep, Clock Manager Directives +@end ifinfo +@subsection nanosleep + +@subheading time SEQUENCE: + +@example +#include <time.h> + +int time( + time_t *tloc +); +@end example + +@subheading STATUS CODES: + +This routine returns the number of seconds since the Epoch. + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/cond.texi b/doc/new_chapters/cond.texi new file mode 100644 index 0000000000..284f0793a9 --- /dev/null +++ b/doc/new_chapters/cond.texi @@ -0,0 +1,384 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Condition Variable Manager, Condition Variable Manager Introduction, pthread_mutex_getprioceiling, Top +@end ifinfo +@chapter Condition Variable Manager +@ifinfo +@menu +* Condition Variable Manager Introduction:: +* Condition Variable Manager Background:: +* Condition Variable Manager Operations:: +* Condition Variable Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Condition Variable Manager Introduction, Condition Variable Manager Background, Condition Variable Manager, Condition Variable Manager +@end ifinfo +@section Introduction + +The condition variable manager ... + +The directives provided by the condition variable manager are: + +@itemize @bullet +@item @code{pthread_condattr_init} - +@item @code{pthread_condattr_destroy} - +@item @code{pthread_condattr_setpshared} - +@item @code{pthread_condattr_getpshared} - +@item @code{pthread_cond_init} - +@item @code{pthread_cond_destroy} - +@item @code{pthread_cond_signal} - +@item @code{pthread_cond_broadcast} - +@item @code{pthread_cond_wait} - +@item @code{pthread_cond_timedwait} - +@end itemize + +@ifinfo +@node Condition Variable Manager Background, Condition Variable Manager Operations, Condition Variable Manager Introduction, Condition Variable Manager +@end ifinfo +@section Background + +@ifinfo +@node Condition Variable Manager Operations, Condition Variable Manager Directives, Condition Variable Manager Background, Condition Variable Manager +@end ifinfo +@section Operations + +@ifinfo +@node Condition Variable Manager Directives, pthread_condattr_init, Condition Variable Manager Operations, Condition Variable Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_condattr_init:: +* pthread_condattr_destroy:: +* pthread_condattr_setpshared:: +* pthread_condattr_getpshared:: +* pthread_cond_init:: +* pthread_cond_destroy:: +* pthread_cond_signal:: +* pthread_cond_broadcast:: +* pthread_cond_wait:: +* pthread_cond_timedwait:: +@end menu +@end ifinfo + +This section details the condition variable manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_condattr_init, pthread_condattr_destroy, Condition Variable Manager Directives, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_init( + pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item ENOMEM +Insufficient memory is available to initialize the condition variable +attributes object. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_destroy, pthread_condattr_setpshared, pthread_condattr_init, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_destroy( + pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute object specified is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_setpshared, pthread_condattr_getpshared, pthread_condattr_destroy, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_setpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_setpshared( + pthread_condattr_t *attr, + int pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_getpshared, pthread_cond_init, pthread_condattr_setpshared, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_getpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_getpshared( + const pthread_condattr_t *attr, + int *pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_cond_init, pthread_cond_destroy, pthread_condattr_getpshared, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_init( + pthread_cond_t *cond, + const pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item EAGAIN +The system lacked a resource other than memory necessary to create the +initialize the condition variable object. + +@item ENOMEM +Insufficient memory is available to initialize the condition variable object. + +@item EBUSY +The specified condition variable has already been initialized. + +@item EINVAL +The specified attribute value is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_destroy, pthread_cond_signal, pthread_cond_init, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_destroy( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is invalid. + +@item EBUSY +The specified condition variable is currently in use. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_signal, pthread_cond_broadcast, pthread_cond_destroy, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_signal + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_signal( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is not valid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine should not be invoked from a handler from an asynchronous signal +handler or an interrupt service routine. + +@page +@ifinfo +@node pthread_cond_broadcast, pthread_cond_wait, pthread_cond_signal, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_broadcast + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_broadcast( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is not valid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine should not be invoked from a handler from an asynchronous signal +handler or an interrupt service routine. + +@page +@ifinfo +@node pthread_cond_wait, pthread_cond_timedwait, pthread_cond_broadcast, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_wait + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_wait( + pthread_cond_t *cond, + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable or mutex is not initialized OR different +mutexes were specified for concurrent pthread_cond_wait() and +pthread_cond_timedwait() operations on the same condition variable OR +the mutex was not owned by the current thread at the time of the call. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_timedwait, Key Manager, pthread_cond_wait, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_timedwait + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_timedwait( + pthread_cond_t *cond, + pthread_mutex_t *mutex, + const struct timespec *abstime +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable or mutex is not initialized OR different +mutexes were specified for concurrent pthread_cond_wait() and +pthread_cond_timedwait() operations on the same condition variable OR +the mutex was not owned by the current thread at the time of the call. + +@item ETIMEDOUT +The specified time has elapsed without the condition variable being +satisfied. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/key.texi b/doc/new_chapters/key.texi new file mode 100644 index 0000000000..90569d0e27 --- /dev/null +++ b/doc/new_chapters/key.texi @@ -0,0 +1,177 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Key Manager, Key Manager Introduction, pthread_cond_timedwait, Top +@end ifinfo +@chapter Key Manager +@ifinfo +@menu +* Key Manager Introduction:: +* Key Manager Background:: +* Key Manager Operations:: +* Key Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Key Manager Introduction, Key Manager Background, Key Manager, Key Manager +@end ifinfo +@section Introduction + +The key manager ... + +The directives provided by the key manager are: + +@itemize @bullet +@item @code{pthread_key_create} - +@item @code{pthread_key_delete} - +@item @code{pthread_setspecific} - +@item @code{pthread_getspecific} - +@end itemize + +@ifinfo +@node Key Manager Background, Key Manager Operations, Key Manager Introduction, Key Manager +@end ifinfo +@section Background + +@ifinfo +@node Key Manager Operations, Key Manager Directives, Key Manager Background, Key Manager +@end ifinfo +@section Operations + +@ifinfo +@node Key Manager Directives, pthread_key_create, Key Manager Operations, Key Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_key_create:: +* pthread_key_delete:: +* pthread_setspecific:: +* pthread_getspecific:: +@end menu +@end ifinfo + +This section details the key manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_key_create, pthread_key_delete, Key Manager Directives, Key Manager Directives +@end ifinfo +@subsection pthread_key_create + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_key_create( + pthread_key_t *key, + void (*destructor)( void * ) +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EAGAIN +There were not enough resources available to create another key. + +@item ENOMEM +Insufficient memory exists to create the key. + +@end table + +@page +@ifinfo +@node pthread_key_delete, pthread_setspecific, pthread_key_create, Key Manager Directives +@end ifinfo +@subsection pthread_key_delete + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_key_delete( + pthread_key_t key, +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The key was invalid + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_setspecific, pthread_getspecific, pthread_key_delete, Key Manager Directives +@end ifinfo +@subsection pthread_setspecific + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_setspecific( + pthread_key_t key, + const void *value +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified key is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_getspecific, Clock Manager, pthread_setspecific, Key Manager Directives +@end ifinfo +@subsection pthread_getspecific + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +void *pthread_getspecific( + pthread_key_t key +); +@end example + +@subheading STATUS CODES: +@table @b +@item NULL +There is no thread-specific data associated with the specified key. + +@item non-NULL +The data associated with the specified key. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/mutex.texi b/doc/new_chapters/mutex.texi new file mode 100644 index 0000000000..37ea926b96 --- /dev/null +++ b/doc/new_chapters/mutex.texi @@ -0,0 +1,640 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Mutex Manager, Mutex Manager Introduction, alarm, Top +@end ifinfo +@chapter Mutex Manager +@ifinfo +@menu +* Mutex Manager Introduction:: +* Mutex Manager Background:: +* Mutex Manager Operations:: +* Mutex Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager +@end ifinfo +@section Introduction + +The mutex manager ... + +The directives provided by the mutex manager are: + +@itemize @bullet +@item @code{pthread_mutexattr_init} - +@item @code{pthread_mutexattr_destroy} - +@item @code{pthread_mutexattr_setprotocol} - +@item @code{pthread_mutexattr_getprotocol} - +@item @code{pthread_mutexattr_setprioceiling} - +@item @code{pthread_mutexattr_getprioceiling} - +@item @code{pthread_mutexattr_setpshared} - +@item @code{pthread_mutexattr_getpshared} - +@item @code{pthread_mutex_init} - +@item @code{pthread_mutex_destroy} - +@item @code{pthread_mutex_lock} - +@item @code{pthread_mutex_trylock} - +@item @code{pthread_mutex_timedlock} - +@item @code{pthread_mutex_unlock} - +@item @code{pthread_mutex_setprioceiling} - +@item @code{pthread_mutex_getprioceiling} - +@end itemize + +@ifinfo +@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager +@end ifinfo +@section Background + +@ifinfo +@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager +@end ifinfo +@section Operations + +@ifinfo +@node Mutex Manager Directives, pthread_mutexattr_init, Mutex Manager Operations, Mutex Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_mutexattr_init:: +* pthread_mutexattr_destroy:: +* pthread_mutexattr_setprotocol:: +* pthread_mutexattr_getprotocol:: +* pthread_mutexattr_setprioceiling:: +* pthread_mutexattr_getprioceiling:: +* pthread_mutexattr_setpshared:: +* pthread_mutexattr_getpshared:: +* pthread_mutex_init:: +* pthread_mutex_destroy:: +* pthread_mutex_lock:: +* pthread_mutex_trylock:: +* pthread_mutex_timedlock:: +* pthread_mutex_unlock:: +* pthread_mutex_setprioceiling:: +* pthread_mutex_getprioceiling:: +@end menu +@end ifinfo + +This section details the mutex manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_mutexattr_init, pthread_mutexattr_destroy, Mutex Manager Directives, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_init( + pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_destroy, pthread_mutexattr_setprotocol, pthread_mutexattr_init, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_destroy( + pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol, pthread_mutexattr_destroy, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setprotocol + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setprotocol( + pthread_mutexattr_t *attr, + int protocol +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The protocol argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getprotocol, pthread_mutexattr_setprioceiling, pthread_mutexattr_setprotocol, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getprotocol + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getprotocol( + pthread_mutexattr_t *attr, + int *protocol +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The protocol pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling, pthread_mutexattr_getprotocol, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setprioceiling( + pthread_mutexattr_t *attr, + int prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The prioceiling argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getprioceiling, pthread_mutexattr_setpshared, pthread_mutexattr_setprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *attr, + int *prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The prioceiling pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setpshared, pthread_mutexattr_getpshared, pthread_mutexattr_getprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setpshared( + pthread_mutexattr_t *attr, + int pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The pshared argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getpshared, pthread_mutex_init, pthread_mutexattr_setpshared, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getpshared( + const pthread_mutexattr_t *attr, + int *pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The pshared pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_init, pthread_mutex_destroy, pthread_mutexattr_getpshared, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_init( + pthread_mutex_t *mutex, + const pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified protocol is invalid. + +@item EAGAIN +The system lacked the necessary resources to initialize another mutex. + +@item ENOMEM +Insufficient memory exists to initialize the mutex. + +@item EBUSY +Attempted to reinialize the object reference by mutex, a previously +initialized, but not yet destroyed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_init, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_destroy( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EBUSY +Attempted to destroy the object reference by mutex, while it is locked or +referenced by another thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_destroy, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_lock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_lock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_trylock, pthread_mutex_timedlock, pthread_mutex_lock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_trylock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_trylock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_trylock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_timedlock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> +#include <time.h> + +int pthread_mutex_timedlock( + pthread_mutex_t *mutex, + const struct timespec *timeout +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The nanoseconds field of timeout is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_mutex_unlock, pthread_mutex_setprioceiling, pthread_mutex_timedlock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_unlock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_unlock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_setprioceiling, pthread_mutex_getprioceiling, pthread_mutex_unlock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_setprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_setprioceiling( + pthread_mutex_t *mutex, + int prioceiling, + int *oldceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The oldceiling pointer parameter is invalid. + +@item EINVAL +The prioceiling parameter is an invalid priority. + +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_getprioceiling, Condition Variable Manager, pthread_mutex_setprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_getprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_getprioceiling( + pthread_mutex_t *mutex, + int *prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The prioceiling pointer parameter is invalid. + +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/posix_test_plan.texi b/doc/new_chapters/posix_test_plan.texi new file mode 100644 index 0000000000..a6dfffecd1 --- /dev/null +++ b/doc/new_chapters/posix_test_plan.texi @@ -0,0 +1,123 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename posix_test_plan +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file for the C 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 ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Posix Test Plan: (posix_test_plan). Posix Test Plan +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c variable substitution info: +@c +@c @set RTEMS-LANGUAGE C +@c the language is @value{RTEMS-LANGUAGE} +@c NOTE: don't use underscore in the name +@c + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS POSIX API Test Plan + +@setchapternewpage odd +@settitle RTEMS POSIX API Test Plan +@titlepage +@finalout + +@title RTEMS POSIX API Test Plan +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include preface.texi +@include thread.texi +@include signal.texi +@include mutex.texi +@include cond.texi +@include key.texi +@include clock.texi +@include sched.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top posix_test_plan + +This is the online version of the RTEMS POSIX API Test Plan. + +@menu +* Preface:: +* Thread Manager:: +* Signal Manager:: +* Mutex Manager:: +* Condition Variable Manager:: +* Key Manager:: +* Clock Manager:: +* Scheduler Manager:: +* 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, sched_yield, 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 + +@contents +@bye + diff --git a/doc/new_chapters/preface.texi b/doc/new_chapters/preface.texi new file mode 100644 index 0000000000..7a7fe781e7 --- /dev/null +++ b/doc/new_chapters/preface.texi @@ -0,0 +1,12 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, Thread Manager, Top, Top +@end ifinfo +@unnumbered Preface + +This is the test plan document for the POSIX API support for RTEMS. diff --git a/doc/new_chapters/sched.texi b/doc/new_chapters/sched.texi new file mode 100644 index 0000000000..f8211b51a7 --- /dev/null +++ b/doc/new_chapters/sched.texi @@ -0,0 +1,226 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Scheduler Manager, Scheduler Manager Introduction, time, Top +@end ifinfo +@chapter Scheduler Manager +@ifinfo +@menu +* Scheduler Manager Introduction:: +* Scheduler Manager Background:: +* Scheduler Manager Operations:: +* Scheduler Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Scheduler Manager Introduction, Scheduler Manager Background, Scheduler Manager, Scheduler Manager +@end ifinfo +@section Introduction + +The scheduler manager ... + +The directives provided by the scheduler manager are: + +@itemize @bullet +@item @code{sched_get_priority_min} - +@item @code{sched_get_priority_max} - +@item @code{sched_rr_get_interval} - +@item @code{sched_yield} - +@end itemize + +@ifinfo +@node Scheduler Manager Background, Priority, Scheduler Manager Introduction, Scheduler Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Priority:: +* Scheduling Policies:: +@end menu +@end ifinfo + +@ifinfo +@node Priority, Scheduling Policies, Scheduler Manager Background, Scheduler Manager Background +@end ifinfo +@subsection Priority + +In the RTEMS implementation of the POSIX API, the priorities range from +the low priority of sched_get_priority_min() to the highest priority of +sched_get_priority_max(). Numerically higher values represent higher +priorities. + +@ifinfo +@node Scheduling Policies, Scheduler Manager Operations, Priority, Scheduler Manager Background +@end ifinfo +@subsection Scheduling Policies + +The following scheduling policies are available: + +@table @b +@item SCHED_FIFO +Priority-based, preemptive scheduling with no timeslicing. This is equivalent +to what is called "manual round-robin" scheduling. + +@item SCHED_RR +Priority-based, preemptive scheduling with timeslicing. Time quantums are +maintained on a per-thread basis and are not reset at each context switch. +Thus, a thread which is preempted and subsequently resumes execution will +attempt to complete the unused portion of its time quantum. + +@item SCHED_OTHER +Priority-based, preemptive scheduling with timeslicing. Time quantums are +maintained on a per-thread basis and are reset at each context switch. + +@item SCHED_SPORADIC +Priority-based, preemptive scheduling utilizing three additional parameters: +budget, replenishment period, and low priority. Under this policy, the +thread is allowed to execute for "budget" amount of time before its priority +is lowered to "low priority". At the end of each replenishment period, +the thread resumes its initial priority and has its budget replenished. + +@end table + +@ifinfo +@node Scheduler Manager Operations, Scheduler Manager Directives, Scheduling Policies, Scheduler Manager +@end ifinfo +@section Operations + +@ifinfo +@node Scheduler Manager Directives, sched_get_priority_min, Scheduler Manager Operations, Scheduler Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sched_get_priority_min:: +* sched_get_priority_max:: +* sched_rr_get_interval:: +* sched_yield:: +@end menu +@end ifinfo + +This section details the scheduler manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sched_get_priority_min, sched_get_priority_max, Scheduler Manager Directives, Scheduler Manager Directives +@end ifinfo +@subsection sched_get_priority_min + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_get_priority_min( + int policy +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The indicated policy is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_get_priority_max, sched_rr_get_interval, sched_get_priority_min, Scheduler Manager Directives +@end ifinfo +@subsection sched_get_priority_max + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_get_priority_max( + int policy +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The indicated policy is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_rr_get_interval, sched_yield, sched_get_priority_max, Scheduler Manager Directives +@end ifinfo +@subsection sched_rr_get_interval + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_rr_get_interval( + pid_t pid, + struct timespec *interval +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item ESRCH +The indicated process id is invalid. + +@item EINVAL +The specified interval pointer parameter is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_yield, Command and Variable Index, sched_rr_get_interval, Scheduler Manager Directives +@end ifinfo +@subsection sched_yield + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_yield( void ); +@end example + +@subheading STATUS CODES: + +This routine always returns zero to indicate success. + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/new_chapters/signal.texi b/doc/new_chapters/signal.texi new file mode 100644 index 0000000000..3185aeff7d --- /dev/null +++ b/doc/new_chapters/signal.texi @@ -0,0 +1,689 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Signal Manager, Signal Manager Introduction, pthread_getschedparam, Top +@end ifinfo +@chapter Signal Manager +@ifinfo +@menu +* Signal Manager Introduction:: +* Signal Manager Background:: +* Signal Manager Operations:: +* Signal Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager +@end ifinfo +@section Introduction + +The signal manager ... + +The directives provided by the signal manager are: + +@itemize @bullet +@item @code{sigaddset} - +@item @code{sigdelset} - +@item @code{sigfillset} - +@item @code{sigismember} - +@item @code{sigemptyset} - +@item @code{sigaction} - +@item @code{pthread_kill} - +@item @code{sigprocmask} - +@item @code{pthread_sigmask} - +@item @code{kill} - +@item @code{sigpending} - +@item @code{sigsuspend} - +@item @code{pause} - +@item @code{sigwait} - +@item @code{sigwaitinfo} - +@item @code{sigtimedwait} - +@item @code{sigqueue} - +@item @code{alarm} - +@end itemize + +@ifinfo +@node Signal Manager Background, Signal Delivery, Signal Manager Introduction, Signal Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Signal Delivery:: +@end menu +@end ifinfo + + +@ifinfo +@node Signal Delivery, Signal Manager Operations, Signal Manager Background, Signal Manager Background +@end ifinfo +@subsection Signal Delivery + +Signals directed at a thread are delivered to the specified thread. + +Signals directed at a process are delivered to a thread which is selected +based on the following algorithm: + +@enumerate +@item If the action for this signal is currently SIG_IGN, then the signal +is simply ignored. + +@item If the currently executing thread has the signal unblocked, then +the signal is delivered to it. + +@item If any threads are currently blocked waiting for this signal +(sigwait()), then the signal is delivered to the highest priority +thread waiting for this signal. + +@item If any other threads are willing to accept delivery of the signal, then +the signal is delivered to the highest priority thread of this set. In the +event, multiple threads of the same priority are willing to accept this +signal, then priority is given first to ready threads, then to threads +blocked on calls which may be interrupted, and finally to threads blocked +on non-interruptible calls. + +@item In the event the signal still can not be delivered, then it is left +pending. The first thread to unblock the signal (sigprocmask() or +pthread_sigprocmask()) or to wait for this signal (sigwait()) will be +the recipient of the signal. + +@end enumerate + +@ifinfo +@node Signal Manager Operations, Signal Manager Directives, Signal Delivery, Signal Manager +@end ifinfo +@section Operations + +@ifinfo +@node Signal Manager Directives, sigaddset, Signal Manager Operations, Signal Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sigaddset:: +* sigdelset:: +* sigfillset:: +* sigismember:: +* sigemptyset:: +* sigaction:: +* pthread_kill:: +* sigprocmask:: +* pthread_sigmask:: +* kill:: +* sigpending:: +* sigsuspend:: +* pause:: +* sigwait:: +* sigwaitinfo:: +* sigtimedwait:: +* sigqueue:: +* alarm:: +@end menu +@end ifinfo + +This section details the signal manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sigaddset, sigdelset, Signal Manager Directives, Signal Manager Directives +@end ifinfo +@subsection sigaddset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigaddset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigdelset, sigfillset, sigaddset, Signal Manager Directives +@end ifinfo +@subsection sigdelset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigdelset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigfillset, sigismember, sigdelset, Signal Manager Directives +@end ifinfo +@subsection sigfillset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigfillset( + sigset_t *set +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigismember, sigemptyset, sigfillset, Signal Manager Directives +@end ifinfo +@subsection sigismember + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigismember( + const sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigemptyset, sigaction, sigismember, Signal Manager Directives +@end ifinfo +@subsection sigemptyset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigemptyset( + sigset_t *set +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigaction, pthread_kill, sigemptyset, Signal Manager Directives +@end ifinfo +@subsection sigaction + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigaction( + int sig, + const struct sigaction *act, + struct sigaction *oact +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@item ENOTSUP +Realtime Signals Extension option not supported. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +The signal number cannot be SIGKILL. +@page +@ifinfo +@node pthread_kill, sigprocmask, sigaction, Signal Manager Directives +@end ifinfo +@subsection pthread_kill + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pthread_kill( + pthread_t thread, + int sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread indicated by the parameter thread is invalid. + +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigprocmask, pthread_sigmask, pthread_kill, Signal Manager Directives +@end ifinfo +@subsection sigprocmask + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigprocmask( + int how, + const sigset_t *set, + sigset_t *oset +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_sigmask, kill, sigprocmask, Signal Manager Directives +@end ifinfo +@subsection pthread_sigmask + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pthread_sigmask( + int how, + const sigset_t *set, + sigset_t *oset +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node kill, sigpending, pthread_sigmask, Signal Manager Directives +@end ifinfo +@subsection kill + +@subheading CALLING SEQUENCE: + +@example +#include <sys/types.h> +#include <signal.h> + +int kill( + pid_t pid, + int sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@item EPERM +Process does not have permission to send the signal to any receiving process. + +@item ESRCH +The process indicated by the parameter pid is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node sigpending, sigsuspend, kill, Signal Manager Directives +@end ifinfo +@subsection sigpending + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigpending( + const sigset_t *set +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EFAULT +Invalid address for set. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigsuspend, pause, sigpending, Signal Manager Directives +@end ifinfo +@subsection sigsuspend + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigsuspend( + const sigset_t *sigmask +); +@end example + +@subheading STATUS CODES: +@table @b +Returns -1 and sets errno. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pause, sigwait, sigsuspend, Signal Manager Directives +@end ifinfo +@subsection pause + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pause( void ); +@end example + +@subheading STATUS CODES: +@table @b +Returns -1 and sets errno. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigwait, sigwaitinfo, pause, Signal Manager Directives +@end ifinfo +@subsection sigwait + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigwait( + const sigset_t *set, + int *sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigwaitinfo, sigtimedwait, sigwait, Signal Manager Directives +@end ifinfo +@subsection sigwaitinfo + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigwaitinfo( + const sigset_t *set, + siginfo_t *info +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigtimedwait, sigqueue, sigwaitinfo, Signal Manager Directives +@end ifinfo +@subsection sigtimedwait + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigtimedwait( + const sigset_t *set, + siginfo_t *info, + const struct timespec *timeout +); +@end example + +@subheading STATUS CODES: +@table @b +@item EAGAIN +Timed out while waiting for the specified signal set. + +@item EINVAL +Nanoseconds field of the timeout argument is invalid. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If timeout is NULL, then the thread will wait forever for the specified +signal set. + +@page +@ifinfo +@node sigqueue, alarm, sigtimedwait, Signal Manager Directives +@end ifinfo +@subsection sigqueue + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigqueue( + pid_t pid, + int signo, + const union sigval value +); +@end example + +@subheading STATUS CODES: + +@table @b + +@item EAGAIN +No resources available to queue the signal. The process has already +queued SIGQUEUE_MAX signals that are still pending at the receiver +or the systemwide resource limit has been exceeded. + +@item EINVAL +The value of the signo argument is an invalid or unsupported signal +number. + +@item EPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. + +@item ESRCH +The process pid does not exist. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node alarm, Mutex Manager, sigqueue, Signal Manager Directives +@end ifinfo +@subsection alarm + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +unsigned int alarm( + unsigned int seconds +); +@end example + +@subheading STATUS CODES: + +If there was a previous alarm() request with time remaining, then this routine +returns the number of seconds until that outstanding alarm would have fired. +If no previous alarm() request was outstanding, then zero is returned. + +@subheading DESCRIPTION: + +@subheading NOTES: + + diff --git a/doc/new_chapters/thread.texi b/doc/new_chapters/thread.texi new file mode 100644 index 0000000000..56f8bf9be5 --- /dev/null +++ b/doc/new_chapters/thread.texi @@ -0,0 +1,1023 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Thread Manager, Thread Manager Introduction, Preface, Top +@end ifinfo +@chapter Thread Manager +@ifinfo +@menu +* Thread Manager Introduction:: +* Thread Manager Background:: +* Thread Manager Operations:: +* Thread Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Thread Manager Introduction, Thread Manager Background, Thread Manager, Thread Manager +@end ifinfo +@section Introduction + +The thread manager ... + +The directives provided by the thread manager are: + +@itemize @bullet +@item @code{pthread_attr_init} - +@item @code{pthread_attr_destroy} - +@item @code{pthread_attr_setdetachstate} - +@item @code{pthread_attr_getdetachstate} - +@item @code{pthread_attr_setstacksize} - +@item @code{pthread_attr_getstacksize} - +@item @code{pthread_attr_setstackaddr} - +@item @code{pthread_attr_getstackaddr} - +@item @code{pthread_attr_setscope} - +@item @code{pthread_attr_getscope} - +@item @code{pthread_attr_setinheritsched} - +@item @code{pthread_attr_getinheritsched} - +@item @code{pthread_attr_setschedpolicy} - +@item @code{pthread_attr_getschedpolicy} - +@item @code{pthread_attr_setschedparam} - +@item @code{pthread_attr_getschedparam} - +@item @code{pthread_create} - +@item @code{pthread_exit} - +@item @code{pthread_detach} - +@item @code{pthread_join} - +@item @code{pthread_self} - +@item @code{pthread_equal} - +@item @code{pthread_once} - +@item @code{pthread_setschedparam} - +@item @code{pthread_getschedparam} - +@end itemize + +@ifinfo +@node Thread Manager Background, Thread Attributes, Thread Manager Introduction, Thread Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Thread Attributes:: +@end menu +@end ifinfo + +@ifinfo +@node Thread Attributes, Thread Manager Operations, Thread Manager Background, Thread Manager Background +@end ifinfo +@subsection Thread Attributes + +Thread attributes are utilized only at thread creation time. + +@table @b +@item stack address +is the address of the optionally user specified stack area for this thread. +If this value is NULL, then RTEMS allocates the memory for the thread stack +from the RTEMS Workspace Area. Otherwise, this is the user specified +address for the memory to be used for the thread's stack. Each thread must +have a distinct stack area. Each processor family has different alignment +rules which should be followed. + +@item stack size +is the minimum desired size for this thread's stack area. +If the size of this area as specified by the stack size attribute +is smaller than the minimum for this processor family and the stack +is not user specified, then RTEMS will automatically allocate a +stack of the minimum size for this processor family. + +@item contention scope +specifies the scheduling contention scope. RTEMS only supports the +PTHREAD_SCOPE_PROCESS scheduling contention scope. + +@item scheduling inheritance +specifies whether a user specified or the scheduling policy and +parameters of the currently executing thread are to be used. When +this is PTHREAD_INHERIT_SCHED, then the scheduling policy and +parameters of the currently executing thread are inherited by +the newly created thread. + +@item scheduling policy and parameters +specify the manner in which the thread will contend for the processor. +The scheduling parameters are interpreted based on the specified policy. +All policies utilize the thread priority parameter. + +@end table + +@ifinfo +@node Thread Manager Operations, Thread Manager Directives, Thread Attributes, Thread Manager +@end ifinfo +@section Operations + +@ifinfo +@node Thread Manager Directives, pthread_attr_init, Thread Manager Operations, Thread Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_attr_init:: +* pthread_attr_destroy:: +* pthread_attr_setdetachstate:: +* pthread_attr_getdetachstate:: +* pthread_attr_setstacksize:: +* pthread_attr_getstacksize:: +* pthread_attr_setstackaddr:: +* pthread_attr_getstackaddr:: +* pthread_attr_setscope:: +* pthread_attr_getscope:: +* pthread_attr_setinheritsched:: +* pthread_attr_getinheritsched:: +* pthread_attr_setschedpolicy:: +* pthread_attr_getschedpolicy:: +* pthread_attr_setschedparam:: +* pthread_attr_getschedparam:: +* pthread_create:: +* pthread_exit:: +* pthread_detach:: +* pthread_join:: +* pthread_self:: +* pthread_equal:: +* pthread_once:: +* pthread_setschedparam:: +* pthread_getschedparam:: +@end menu +@end ifinfo + +This section details the thread manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_attr_init, pthread_attr_destroy, Thread Manager Directives, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_init + +@subheading CALLING SEQUENCE: + + +@example +#include <pthread.h> + +int pthread_attr_init( + pthread_attr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_init, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_destroy( + pthread_attr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_destroy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setdetachstate + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setdetachstate( + pthread_attr_t *attr, + int detachstate +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The detachstate argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getdetachstate, pthread_attr_setstacksize, pthread_attr_setdetachstate, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getdetachstate + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getdetachstate( + const pthread_attr_t *attr, + int *detachstate +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The detatchstate pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setstacksize, pthread_attr_getstacksize, pthread_attr_getdetachstate, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setstacksize + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setstacksize( + pthread_attr_t *attr, + size_t stacksize +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If the specified stacksize is below the minimum required for this CPU, then +the stacksize will be set to the minimum for this CPU. + +@page +@ifinfo +@node pthread_attr_getstacksize, pthread_attr_setstackaddr, pthread_attr_setstacksize, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getstacksize + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getstacksize( + const pthread_attr_t *attr, + size_t *stacksize +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The stacksize pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setstackaddr, pthread_attr_getstackaddr, pthread_attr_getstacksize, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setstackaddr + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setstackaddr( + pthread_attr_t *attr, + void *stackaddr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getstackaddr, pthread_attr_setscope, pthread_attr_setstackaddr, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getstackaddr + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getstackaddr( + const pthread_attr_t *attr, + void **stackaddr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The stackaddr pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setscope, pthread_attr_getscope, pthread_attr_getstackaddr, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setscope + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setscope( + pthread_attr_t *attr, + int contentionscope +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The contention scope specified is not valid. + +@item ENOTSUP +The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getscope, pthread_attr_setinheritsched, pthread_attr_setscope, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getscope + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getscope( + const pthread_attr_t *attr, + int *contentionscope +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The contentionscope pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_getscope, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setinheritsched + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setinheritsched( + pthread_attr_t *attr, + int inheritsched +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler inheritance argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getinheritsched, pthread_attr_setschedpolicy, pthread_attr_setinheritsched, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getinheritsched + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getinheritsched( + const pthread_attr_t *attr, + int *inheritsched +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The inheritsched pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_getinheritsched, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setschedpolicy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setschedpolicy( + pthread_attr_t *attr, + int policy +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item ENOTSUP +The specified scheduler policy argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getschedpolicy, pthread_attr_setschedparam, pthread_attr_setschedpolicy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getschedpolicy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getschedpolicy( + const pthread_attr_t *attr, + int *policy +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler policy argument pointer is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_getschedpolicy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setschedparam( + pthread_attr_t *attr, + const struct sched_param param +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler parameter argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getschedparam, pthread_create, pthread_attr_setschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getschedparam( + const pthread_attr_t *attr, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler parameter argument pointer is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_create, pthread_exit, pthread_attr_getschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_create + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_create( + pthread_t *thread, + const pthread_attr_t *attr, + void (*start_routine)( void * ), + void *arg +); +@end example + +@subheading STATUS CODES: + +@table @b + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The user specified a stack address and the size of the area was not +large enough to meet this processor's minimum stack requirements. + +@item EINVAL +The specified scheduler inheritance policy was invalid. + +@item ENOTSUP +The specified contention scope was PTHREAD_SCOPE_PROCESS. + +@item EINVAL +The specified thread priority was invalid. + +@item EINVAL +The specified scheduling policy was invalid. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified replenishment +period is less than the initial budget. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified low priority +is invalid. + +@item EAGAIN +The system lacked the necessary resources to create another thread, or the +self imposed limit on the total number of threads in a process +PTHREAD_THREAD_MAX would be exceeded. + +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_exit, pthread_detach, pthread_create, Thread Manager Directives +@end ifinfo +@subsection pthread_exit + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +void pthread_exit( + void *status +); +@end example + +@subheading STATUS CODES: +@table @b +@item NONE + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_detach, pthread_join, pthread_exit, Thread Manager Directives +@end ifinfo +@subsection pthread_detach + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_detach( + pthread_t thread +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread specified is invalid. + +@item EINVAL +The thread specified is not a joinable thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If any threads have previously joined with the specified thread, then they +will remain joined with that thread. Any subsequent calls to pthread_join +on the specified thread will fail. + +@page +@ifinfo +@node pthread_join, pthread_self, pthread_detach, Thread Manager Directives +@end ifinfo +@subsection pthread_join + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_join( + pthread_t thread, + void **value_ptr +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread specified is invalid. + +@item EINVAL +The thread specified is not a joinable thread. + +@item EDEADLK +A deadlock was detected or thread is the calling thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If any threads have previously joined with the specified thread, then they +will remain joined with that thread. Any subsequent calls to pthread_join +on the specified thread will fail. + +If value_ptr is NULL, then no value is returned. + +@page +@ifinfo +@node pthread_self, pthread_equal, pthread_join, Thread Manager Directives +@end ifinfo +@subsection pthread_self + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +pthread_t pthread_self( void ); +@end example + +@subheading STATUS CODES: + +This routine returns the id of the calling thread. + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_equal, pthread_once, pthread_self, Thread Manager Directives +@end ifinfo +@subsection pthread_equal + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_equal( + pthread_t t1, + pthread_t t2 +); +@end example + +@subheading STATUS CODES: + +@table @b +@item zero +The thread ids are not equal. + +@item non-zero +The thread ids are equal. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +The behavior is undefined if the thread IDs are not valid. + +@page +@ifinfo +@node pthread_once, pthread_setschedparam, pthread_equal, Thread Manager Directives +@end ifinfo +@subsection pthread_once + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +pthread_once_t once_control = PTHREAD_ONCE_INIT; + +int pthread_once( + pthread_once_t *once_control, + void (*init_routine)(void) +); +@end example + +@subheading STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_setschedparam, pthread_getschedparam, pthread_once, Thread Manager Directives +@end ifinfo +@subsection pthread_setschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_setschedparam( + pthread_t thread, + int policy, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The scheduling parameters indicated by the parameter param is invalid. + +@item EINVAL +The value specified by policy is invalid. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified replenishment +period is less than the initial budget. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified low priority +is invalid. + +@item ESRCH +The thread indicated was invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_getschedparam, Signal Manager, pthread_setschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_getschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_getschedparam( + pthread_t thread, + int *policy, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The policy pointer argument is invalid. + +@item EINVAL +The scheduling parameters pointer argument is invalid. + +@item ESRCH +The thread indicated by the parameter thread is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/oaronly.jpg b/doc/oaronly.jpg Binary files differnew file mode 100644 index 0000000000..c87c151404 --- /dev/null +++ b/doc/oaronly.jpg diff --git a/doc/posix_users/Makefile b/doc/posix_users/Makefile new file mode 100644 index 0000000000..65977364ad --- /dev/null +++ b/doc/posix_users/Makefile @@ -0,0 +1,59 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=posix +DOCNAME=posix_test_plan + +all: + +COMMON_FILES=../common/cpright.texi +FILES= clock.texi cond.texi key.texi mutex.texi $(DOCNAME).texi preface.texi \ + sched.texi signal.texi thread.texi $(COMMON_FILES) + +all: + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: $(DOCNAME) +# cp $(DOCNAME) $(DOCNAME)-* $(INFO_INSTALL) + cp $(DOCNAME) $(INFO_INSTALL) + +posix_test_plan: $(FILES) + $(MAKEINFO) $(DOCNAME).texi + +vinfo: info + $(INFO) -f ./$(DOCNAME) + +dvi: $(DOCNAME).dvi +ps: $(DOCNAME).ps + +$(DOCNAME).ps: $(DOCNAME).dvi + dvips -o $(DOCNAME).ps $(DOCNAME).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(DOCNAME).dvi + +view: ps + $(GHOSTVIEW) $(DOCNAME).ps + +$(DOCNAME).dvi: $(FILES) + $(TEXI2DVI) $(DOCNAME).texi + +html: + -mkdir $(WWW_INSTALL)/$(DOCNAME) + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/c_$(PROJECT) \ + $(PROJECT).texi + cp ../rtems.html $(WWW_INSTALL) + + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(DOCNAME) $(DOCNAME)-* _* + diff --git a/doc/posix_users/base.texi b/doc/posix_users/base.texi new file mode 100644 index 0000000000..ee0c280d63 --- /dev/null +++ b/doc/posix_users/base.texi @@ -0,0 +1,96 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Mutex Manager, Mutex Manager Introduction, Preface, Top +@end ifinfo +@chapter Mutex Manager +@ifinfo +@menu +* Mutex Manager Introduction:: +* Mutex Manager Background:: +* Mutex Manager Operations:: +* Mutex Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager +@end ifinfo +@section Introduction + +The mutex manager ... + +The directives provided by the mutex manager are: + +@itemize @bullet +@item @code{sigaddset} - +@item @code{sigdelset} - +@item @code{sigfillset} - +@item @code{sigismember} - +@item @code{sigemptyset} - +@item @code{sigaction} - +@item @code{pthread_kill} - +@item @code{pthread_sigmask} - +@item @code{kill} - +@item @code{sigwait} - +@end itemize + +@ifinfo +@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager +@end ifinfo +@section Background + +@ifinfo +@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager +@end ifinfo +@section Operations + +@ifinfo +@node Mutex Manager Directives, sigaddset, Mutex Manager Operations, Mutex Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sigaddset:: +* sigdelset:: +* sigfillset:: +* sigismember:: +* sigemptyset:: +* sigaction:: +* pthread_kill:: +* pthread_sigmask:: +* kill:: +* sigwait:: +@end menu +@end ifinfo + +This section details the mutex manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sigaddset, sigdelset, Mutex Manager Directives, Mutex Manager Directives +@end ifinfo +@subsection sigaddset + +@subheading CALLING SEQUENCE: + +@example +int sigaddset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/clock.texi b/doc/posix_users/clock.texi new file mode 100644 index 0000000000..1b64d91a6b --- /dev/null +++ b/doc/posix_users/clock.texi @@ -0,0 +1,262 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Clock Manager, Clock Manager Introduction, pthread_getspecific, Top +@end ifinfo +@chapter Clock Manager +@ifinfo +@menu +* Clock Manager Introduction:: +* Clock Manager Background:: +* Clock Manager Operations:: +* Clock Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager +@end ifinfo +@section Introduction + +The clock manager ... + +The directives provided by the clock manager are: + +@itemize @bullet +@item @code{clock_gettime} - +@item @code{clock_settime} - +@item @code{clock_getres} - +@item @code{nanosleep} - +@item @code{time} - +@end itemize + +@ifinfo +@node Clock Manager Background, Clock Manager Operations, Clock Manager Introduction, Clock Manager +@end ifinfo +@section Background + +@ifinfo +@node Clock Manager Operations, Clock Manager Directives, Clock Manager Background, Clock Manager +@end ifinfo +@section Operations + +@ifinfo +@node Clock Manager Directives, clock_gettime, Clock Manager Operations, Clock Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* clock_gettime:: +* clock_settime:: +* clock_getres:: +* sleep:: +* nanosleep:: +* time:: +@end menu +@end ifinfo + +This section details the clock manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node clock_gettime, clock_settime, Clock Manager Directives, Clock Manager Directives +@end ifinfo +@subsection clock_gettime + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_gettime( + clockid_t clock_id, + struct timespec *tp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The tp pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node clock_settime, clock_getres, clock_gettime, Clock Manager Directives +@end ifinfo +@subsection clock_settime + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_settime( + clockid_t clock_id, + const struct timespec *tp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The tp pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. + +@item EINVAL +The contents of the tp structure are invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node clock_getres, sleep, clock_settime, Clock Manager Directives +@end ifinfo +@subsection clock_getres + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int clock_getres( + clockid_t clock_id, + struct timespec *res +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The res pointer parameter is invalid. + +@item EINVAL +The clock_id specified is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If res is NULL, then the resolution is not returned. + +@page +@ifinfo +@node sleep, nanosleep, clock_getres, Clock Manager Directives +@end ifinfo +@subsection sleep + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +unsigned int sleep( + unsigned int seconds +); +@end example + +@subheading STATUS CODES: + +This routine returns the number of unslept seconds. + +@subheading DESCRIPTION: + +@subheading NOTES: + +This call is interruptible by a signal. + +@page +@ifinfo +@node nanosleep, time, sleep, Clock Manager Directives +@end ifinfo +@subsection nanosleep + +@subheading CALLING SEQUENCE: + +@example +#include <time.h> + +int nanosleep( + const struct timespec *rqtp, + struct timespec *rmtp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINTR +The routine was interrupted by a signal. + +@item EAGAIN +The requested sleep period specified negative seconds or nanoseconds. + +@item EINVAL +The requested sleep period specified an invalid number for the nanoseconds +field. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This call is interruptible by a signal. + +@page +@ifinfo +@node time, Scheduler Manager, nanosleep, Clock Manager Directives +@end ifinfo +@subsection nanosleep + +@subheading time SEQUENCE: + +@example +#include <time.h> + +int time( + time_t *tloc +); +@end example + +@subheading STATUS CODES: + +This routine returns the number of seconds since the Epoch. + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/cond.texi b/doc/posix_users/cond.texi new file mode 100644 index 0000000000..284f0793a9 --- /dev/null +++ b/doc/posix_users/cond.texi @@ -0,0 +1,384 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Condition Variable Manager, Condition Variable Manager Introduction, pthread_mutex_getprioceiling, Top +@end ifinfo +@chapter Condition Variable Manager +@ifinfo +@menu +* Condition Variable Manager Introduction:: +* Condition Variable Manager Background:: +* Condition Variable Manager Operations:: +* Condition Variable Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Condition Variable Manager Introduction, Condition Variable Manager Background, Condition Variable Manager, Condition Variable Manager +@end ifinfo +@section Introduction + +The condition variable manager ... + +The directives provided by the condition variable manager are: + +@itemize @bullet +@item @code{pthread_condattr_init} - +@item @code{pthread_condattr_destroy} - +@item @code{pthread_condattr_setpshared} - +@item @code{pthread_condattr_getpshared} - +@item @code{pthread_cond_init} - +@item @code{pthread_cond_destroy} - +@item @code{pthread_cond_signal} - +@item @code{pthread_cond_broadcast} - +@item @code{pthread_cond_wait} - +@item @code{pthread_cond_timedwait} - +@end itemize + +@ifinfo +@node Condition Variable Manager Background, Condition Variable Manager Operations, Condition Variable Manager Introduction, Condition Variable Manager +@end ifinfo +@section Background + +@ifinfo +@node Condition Variable Manager Operations, Condition Variable Manager Directives, Condition Variable Manager Background, Condition Variable Manager +@end ifinfo +@section Operations + +@ifinfo +@node Condition Variable Manager Directives, pthread_condattr_init, Condition Variable Manager Operations, Condition Variable Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_condattr_init:: +* pthread_condattr_destroy:: +* pthread_condattr_setpshared:: +* pthread_condattr_getpshared:: +* pthread_cond_init:: +* pthread_cond_destroy:: +* pthread_cond_signal:: +* pthread_cond_broadcast:: +* pthread_cond_wait:: +* pthread_cond_timedwait:: +@end menu +@end ifinfo + +This section details the condition variable manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_condattr_init, pthread_condattr_destroy, Condition Variable Manager Directives, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_init( + pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item ENOMEM +Insufficient memory is available to initialize the condition variable +attributes object. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_destroy, pthread_condattr_setpshared, pthread_condattr_init, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_destroy( + pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute object specified is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_setpshared, pthread_condattr_getpshared, pthread_condattr_destroy, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_setpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_setpshared( + pthread_condattr_t *attr, + int pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_condattr_getpshared, pthread_cond_init, pthread_condattr_setpshared, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_condattr_getpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_condattr_getpshared( + const pthread_condattr_t *attr, + int *pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_cond_init, pthread_cond_destroy, pthread_condattr_getpshared, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_init( + pthread_cond_t *cond, + const pthread_condattr_t *attr +); +@end example + +@subheading STATUS CODES: +@table @b +@item EAGAIN +The system lacked a resource other than memory necessary to create the +initialize the condition variable object. + +@item ENOMEM +Insufficient memory is available to initialize the condition variable object. + +@item EBUSY +The specified condition variable has already been initialized. + +@item EINVAL +The specified attribute value is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_destroy, pthread_cond_signal, pthread_cond_init, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_destroy( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is invalid. + +@item EBUSY +The specified condition variable is currently in use. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_signal, pthread_cond_broadcast, pthread_cond_destroy, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_signal + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_signal( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is not valid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine should not be invoked from a handler from an asynchronous signal +handler or an interrupt service routine. + +@page +@ifinfo +@node pthread_cond_broadcast, pthread_cond_wait, pthread_cond_signal, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_broadcast + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_broadcast( + pthread_cond_t *cond +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable is not valid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine should not be invoked from a handler from an asynchronous signal +handler or an interrupt service routine. + +@page +@ifinfo +@node pthread_cond_wait, pthread_cond_timedwait, pthread_cond_broadcast, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_wait + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_wait( + pthread_cond_t *cond, + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable or mutex is not initialized OR different +mutexes were specified for concurrent pthread_cond_wait() and +pthread_cond_timedwait() operations on the same condition variable OR +the mutex was not owned by the current thread at the time of the call. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_cond_timedwait, Key Manager, pthread_cond_wait, Condition Variable Manager Directives +@end ifinfo +@subsection pthread_cond_timedwait + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_cond_timedwait( + pthread_cond_t *cond, + pthread_mutex_t *mutex, + const struct timespec *abstime +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified condition variable or mutex is not initialized OR different +mutexes were specified for concurrent pthread_cond_wait() and +pthread_cond_timedwait() operations on the same condition variable OR +the mutex was not owned by the current thread at the time of the call. + +@item ETIMEDOUT +The specified time has elapsed without the condition variable being +satisfied. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/key.texi b/doc/posix_users/key.texi new file mode 100644 index 0000000000..90569d0e27 --- /dev/null +++ b/doc/posix_users/key.texi @@ -0,0 +1,177 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Key Manager, Key Manager Introduction, pthread_cond_timedwait, Top +@end ifinfo +@chapter Key Manager +@ifinfo +@menu +* Key Manager Introduction:: +* Key Manager Background:: +* Key Manager Operations:: +* Key Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Key Manager Introduction, Key Manager Background, Key Manager, Key Manager +@end ifinfo +@section Introduction + +The key manager ... + +The directives provided by the key manager are: + +@itemize @bullet +@item @code{pthread_key_create} - +@item @code{pthread_key_delete} - +@item @code{pthread_setspecific} - +@item @code{pthread_getspecific} - +@end itemize + +@ifinfo +@node Key Manager Background, Key Manager Operations, Key Manager Introduction, Key Manager +@end ifinfo +@section Background + +@ifinfo +@node Key Manager Operations, Key Manager Directives, Key Manager Background, Key Manager +@end ifinfo +@section Operations + +@ifinfo +@node Key Manager Directives, pthread_key_create, Key Manager Operations, Key Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_key_create:: +* pthread_key_delete:: +* pthread_setspecific:: +* pthread_getspecific:: +@end menu +@end ifinfo + +This section details the key manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_key_create, pthread_key_delete, Key Manager Directives, Key Manager Directives +@end ifinfo +@subsection pthread_key_create + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_key_create( + pthread_key_t *key, + void (*destructor)( void * ) +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EAGAIN +There were not enough resources available to create another key. + +@item ENOMEM +Insufficient memory exists to create the key. + +@end table + +@page +@ifinfo +@node pthread_key_delete, pthread_setspecific, pthread_key_create, Key Manager Directives +@end ifinfo +@subsection pthread_key_delete + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_key_delete( + pthread_key_t key, +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The key was invalid + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_setspecific, pthread_getspecific, pthread_key_delete, Key Manager Directives +@end ifinfo +@subsection pthread_setspecific + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_setspecific( + pthread_key_t key, + const void *value +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The specified key is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_getspecific, Clock Manager, pthread_setspecific, Key Manager Directives +@end ifinfo +@subsection pthread_getspecific + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +void *pthread_getspecific( + pthread_key_t key +); +@end example + +@subheading STATUS CODES: +@table @b +@item NULL +There is no thread-specific data associated with the specified key. + +@item non-NULL +The data associated with the specified key. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/mutex.texi b/doc/posix_users/mutex.texi new file mode 100644 index 0000000000..37ea926b96 --- /dev/null +++ b/doc/posix_users/mutex.texi @@ -0,0 +1,640 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Mutex Manager, Mutex Manager Introduction, alarm, Top +@end ifinfo +@chapter Mutex Manager +@ifinfo +@menu +* Mutex Manager Introduction:: +* Mutex Manager Background:: +* Mutex Manager Operations:: +* Mutex Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager +@end ifinfo +@section Introduction + +The mutex manager ... + +The directives provided by the mutex manager are: + +@itemize @bullet +@item @code{pthread_mutexattr_init} - +@item @code{pthread_mutexattr_destroy} - +@item @code{pthread_mutexattr_setprotocol} - +@item @code{pthread_mutexattr_getprotocol} - +@item @code{pthread_mutexattr_setprioceiling} - +@item @code{pthread_mutexattr_getprioceiling} - +@item @code{pthread_mutexattr_setpshared} - +@item @code{pthread_mutexattr_getpshared} - +@item @code{pthread_mutex_init} - +@item @code{pthread_mutex_destroy} - +@item @code{pthread_mutex_lock} - +@item @code{pthread_mutex_trylock} - +@item @code{pthread_mutex_timedlock} - +@item @code{pthread_mutex_unlock} - +@item @code{pthread_mutex_setprioceiling} - +@item @code{pthread_mutex_getprioceiling} - +@end itemize + +@ifinfo +@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager +@end ifinfo +@section Background + +@ifinfo +@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager +@end ifinfo +@section Operations + +@ifinfo +@node Mutex Manager Directives, pthread_mutexattr_init, Mutex Manager Operations, Mutex Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_mutexattr_init:: +* pthread_mutexattr_destroy:: +* pthread_mutexattr_setprotocol:: +* pthread_mutexattr_getprotocol:: +* pthread_mutexattr_setprioceiling:: +* pthread_mutexattr_getprioceiling:: +* pthread_mutexattr_setpshared:: +* pthread_mutexattr_getpshared:: +* pthread_mutex_init:: +* pthread_mutex_destroy:: +* pthread_mutex_lock:: +* pthread_mutex_trylock:: +* pthread_mutex_timedlock:: +* pthread_mutex_unlock:: +* pthread_mutex_setprioceiling:: +* pthread_mutex_getprioceiling:: +@end menu +@end ifinfo + +This section details the mutex manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_mutexattr_init, pthread_mutexattr_destroy, Mutex Manager Directives, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_init( + pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_destroy, pthread_mutexattr_setprotocol, pthread_mutexattr_init, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_destroy( + pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol, pthread_mutexattr_destroy, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setprotocol + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setprotocol( + pthread_mutexattr_t *attr, + int protocol +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The protocol argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getprotocol, pthread_mutexattr_setprioceiling, pthread_mutexattr_setprotocol, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getprotocol + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getprotocol( + pthread_mutexattr_t *attr, + int *protocol +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The protocol pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling, pthread_mutexattr_getprotocol, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setprioceiling( + pthread_mutexattr_t *attr, + int prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The prioceiling argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getprioceiling, pthread_mutexattr_setpshared, pthread_mutexattr_setprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getprioceiling( + const pthread_mutexattr_t *attr, + int *prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The prioceiling pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_setpshared, pthread_mutexattr_getpshared, pthread_mutexattr_getprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_setpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_setpshared( + pthread_mutexattr_t *attr, + int pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The pshared argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutexattr_getpshared, pthread_mutex_init, pthread_mutexattr_setpshared, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutexattr_getpshared + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutexattr_getpshared( + const pthread_mutexattr_t *attr, + int *pshared +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The pshared pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_init, pthread_mutex_destroy, pthread_mutexattr_getpshared, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_init + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_init( + pthread_mutex_t *mutex, + const pthread_mutexattr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified protocol is invalid. + +@item EAGAIN +The system lacked the necessary resources to initialize another mutex. + +@item ENOMEM +Insufficient memory exists to initialize the mutex. + +@item EBUSY +Attempted to reinialize the object reference by mutex, a previously +initialized, but not yet destroyed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_init, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_destroy( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EBUSY +Attempted to destroy the object reference by mutex, while it is locked or +referenced by another thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_destroy, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_lock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_lock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_trylock, pthread_mutex_timedlock, pthread_mutex_lock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_trylock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_trylock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_trylock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_timedlock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> +#include <time.h> + +int pthread_mutex_timedlock( + pthread_mutex_t *mutex, + const struct timespec *timeout +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@item EINVAL +The nanoseconds field of timeout is invalid. + +@item EINVAL +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +priority of the calling thread is higher than the current priority +ceiling. + +@item EDEADLK +The current thread already owns the mutex. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_mutex_unlock, pthread_mutex_setprioceiling, pthread_mutex_timedlock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_unlock + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_unlock( + pthread_mutex_t *mutex +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_setprioceiling, pthread_mutex_getprioceiling, pthread_mutex_unlock, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_setprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_setprioceiling( + pthread_mutex_t *mutex, + int prioceiling, + int *oldceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The oldceiling pointer parameter is invalid. + +@item EINVAL +The prioceiling parameter is an invalid priority. + +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_mutex_getprioceiling, Condition Variable Manager, pthread_mutex_setprioceiling, Mutex Manager Directives +@end ifinfo +@subsection pthread_mutex_getprioceiling + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_mutex_getprioceiling( + pthread_mutex_t *mutex, + int *prioceiling +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The prioceiling pointer parameter is invalid. + +@item EINVAL +The specified mutex is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/posix_test_plan.texi b/doc/posix_users/posix_test_plan.texi new file mode 100644 index 0000000000..a6dfffecd1 --- /dev/null +++ b/doc/posix_users/posix_test_plan.texi @@ -0,0 +1,123 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename posix_test_plan +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file for the C 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 ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Posix Test Plan: (posix_test_plan). Posix Test Plan +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c variable substitution info: +@c +@c @set RTEMS-LANGUAGE C +@c the language is @value{RTEMS-LANGUAGE} +@c NOTE: don't use underscore in the name +@c + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS POSIX API Test Plan + +@setchapternewpage odd +@settitle RTEMS POSIX API Test Plan +@titlepage +@finalout + +@title RTEMS POSIX API Test Plan +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include preface.texi +@include thread.texi +@include signal.texi +@include mutex.texi +@include cond.texi +@include key.texi +@include clock.texi +@include sched.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top posix_test_plan + +This is the online version of the RTEMS POSIX API Test Plan. + +@menu +* Preface:: +* Thread Manager:: +* Signal Manager:: +* Mutex Manager:: +* Condition Variable Manager:: +* Key Manager:: +* Clock Manager:: +* Scheduler Manager:: +* 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, sched_yield, 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 + +@contents +@bye + diff --git a/doc/posix_users/preface.texi b/doc/posix_users/preface.texi new file mode 100644 index 0000000000..7a7fe781e7 --- /dev/null +++ b/doc/posix_users/preface.texi @@ -0,0 +1,12 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, Thread Manager, Top, Top +@end ifinfo +@unnumbered Preface + +This is the test plan document for the POSIX API support for RTEMS. diff --git a/doc/posix_users/sched.texi b/doc/posix_users/sched.texi new file mode 100644 index 0000000000..f8211b51a7 --- /dev/null +++ b/doc/posix_users/sched.texi @@ -0,0 +1,226 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Scheduler Manager, Scheduler Manager Introduction, time, Top +@end ifinfo +@chapter Scheduler Manager +@ifinfo +@menu +* Scheduler Manager Introduction:: +* Scheduler Manager Background:: +* Scheduler Manager Operations:: +* Scheduler Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Scheduler Manager Introduction, Scheduler Manager Background, Scheduler Manager, Scheduler Manager +@end ifinfo +@section Introduction + +The scheduler manager ... + +The directives provided by the scheduler manager are: + +@itemize @bullet +@item @code{sched_get_priority_min} - +@item @code{sched_get_priority_max} - +@item @code{sched_rr_get_interval} - +@item @code{sched_yield} - +@end itemize + +@ifinfo +@node Scheduler Manager Background, Priority, Scheduler Manager Introduction, Scheduler Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Priority:: +* Scheduling Policies:: +@end menu +@end ifinfo + +@ifinfo +@node Priority, Scheduling Policies, Scheduler Manager Background, Scheduler Manager Background +@end ifinfo +@subsection Priority + +In the RTEMS implementation of the POSIX API, the priorities range from +the low priority of sched_get_priority_min() to the highest priority of +sched_get_priority_max(). Numerically higher values represent higher +priorities. + +@ifinfo +@node Scheduling Policies, Scheduler Manager Operations, Priority, Scheduler Manager Background +@end ifinfo +@subsection Scheduling Policies + +The following scheduling policies are available: + +@table @b +@item SCHED_FIFO +Priority-based, preemptive scheduling with no timeslicing. This is equivalent +to what is called "manual round-robin" scheduling. + +@item SCHED_RR +Priority-based, preemptive scheduling with timeslicing. Time quantums are +maintained on a per-thread basis and are not reset at each context switch. +Thus, a thread which is preempted and subsequently resumes execution will +attempt to complete the unused portion of its time quantum. + +@item SCHED_OTHER +Priority-based, preemptive scheduling with timeslicing. Time quantums are +maintained on a per-thread basis and are reset at each context switch. + +@item SCHED_SPORADIC +Priority-based, preemptive scheduling utilizing three additional parameters: +budget, replenishment period, and low priority. Under this policy, the +thread is allowed to execute for "budget" amount of time before its priority +is lowered to "low priority". At the end of each replenishment period, +the thread resumes its initial priority and has its budget replenished. + +@end table + +@ifinfo +@node Scheduler Manager Operations, Scheduler Manager Directives, Scheduling Policies, Scheduler Manager +@end ifinfo +@section Operations + +@ifinfo +@node Scheduler Manager Directives, sched_get_priority_min, Scheduler Manager Operations, Scheduler Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sched_get_priority_min:: +* sched_get_priority_max:: +* sched_rr_get_interval:: +* sched_yield:: +@end menu +@end ifinfo + +This section details the scheduler manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sched_get_priority_min, sched_get_priority_max, Scheduler Manager Directives, Scheduler Manager Directives +@end ifinfo +@subsection sched_get_priority_min + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_get_priority_min( + int policy +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The indicated policy is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_get_priority_max, sched_rr_get_interval, sched_get_priority_min, Scheduler Manager Directives +@end ifinfo +@subsection sched_get_priority_max + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_get_priority_max( + int policy +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EINVAL +The indicated policy is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_rr_get_interval, sched_yield, sched_get_priority_max, Scheduler Manager Directives +@end ifinfo +@subsection sched_rr_get_interval + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_rr_get_interval( + pid_t pid, + struct timespec *interval +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item ESRCH +The indicated process id is invalid. + +@item EINVAL +The specified interval pointer parameter is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sched_yield, Command and Variable Index, sched_rr_get_interval, Scheduler Manager Directives +@end ifinfo +@subsection sched_yield + +@subheading CALLING SEQUENCE: + +@example +#include <sched.h> + +int sched_yield( void ); +@end example + +@subheading STATUS CODES: + +This routine always returns zero to indicate success. + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/signal.texi b/doc/posix_users/signal.texi new file mode 100644 index 0000000000..3185aeff7d --- /dev/null +++ b/doc/posix_users/signal.texi @@ -0,0 +1,689 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Signal Manager, Signal Manager Introduction, pthread_getschedparam, Top +@end ifinfo +@chapter Signal Manager +@ifinfo +@menu +* Signal Manager Introduction:: +* Signal Manager Background:: +* Signal Manager Operations:: +* Signal Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager +@end ifinfo +@section Introduction + +The signal manager ... + +The directives provided by the signal manager are: + +@itemize @bullet +@item @code{sigaddset} - +@item @code{sigdelset} - +@item @code{sigfillset} - +@item @code{sigismember} - +@item @code{sigemptyset} - +@item @code{sigaction} - +@item @code{pthread_kill} - +@item @code{sigprocmask} - +@item @code{pthread_sigmask} - +@item @code{kill} - +@item @code{sigpending} - +@item @code{sigsuspend} - +@item @code{pause} - +@item @code{sigwait} - +@item @code{sigwaitinfo} - +@item @code{sigtimedwait} - +@item @code{sigqueue} - +@item @code{alarm} - +@end itemize + +@ifinfo +@node Signal Manager Background, Signal Delivery, Signal Manager Introduction, Signal Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Signal Delivery:: +@end menu +@end ifinfo + + +@ifinfo +@node Signal Delivery, Signal Manager Operations, Signal Manager Background, Signal Manager Background +@end ifinfo +@subsection Signal Delivery + +Signals directed at a thread are delivered to the specified thread. + +Signals directed at a process are delivered to a thread which is selected +based on the following algorithm: + +@enumerate +@item If the action for this signal is currently SIG_IGN, then the signal +is simply ignored. + +@item If the currently executing thread has the signal unblocked, then +the signal is delivered to it. + +@item If any threads are currently blocked waiting for this signal +(sigwait()), then the signal is delivered to the highest priority +thread waiting for this signal. + +@item If any other threads are willing to accept delivery of the signal, then +the signal is delivered to the highest priority thread of this set. In the +event, multiple threads of the same priority are willing to accept this +signal, then priority is given first to ready threads, then to threads +blocked on calls which may be interrupted, and finally to threads blocked +on non-interruptible calls. + +@item In the event the signal still can not be delivered, then it is left +pending. The first thread to unblock the signal (sigprocmask() or +pthread_sigprocmask()) or to wait for this signal (sigwait()) will be +the recipient of the signal. + +@end enumerate + +@ifinfo +@node Signal Manager Operations, Signal Manager Directives, Signal Delivery, Signal Manager +@end ifinfo +@section Operations + +@ifinfo +@node Signal Manager Directives, sigaddset, Signal Manager Operations, Signal Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* sigaddset:: +* sigdelset:: +* sigfillset:: +* sigismember:: +* sigemptyset:: +* sigaction:: +* pthread_kill:: +* sigprocmask:: +* pthread_sigmask:: +* kill:: +* sigpending:: +* sigsuspend:: +* pause:: +* sigwait:: +* sigwaitinfo:: +* sigtimedwait:: +* sigqueue:: +* alarm:: +@end menu +@end ifinfo + +This section details the signal manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node sigaddset, sigdelset, Signal Manager Directives, Signal Manager Directives +@end ifinfo +@subsection sigaddset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigaddset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigdelset, sigfillset, sigaddset, Signal Manager Directives +@end ifinfo +@subsection sigdelset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigdelset( + sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigfillset, sigismember, sigdelset, Signal Manager Directives +@end ifinfo +@subsection sigfillset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigfillset( + sigset_t *set +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigismember, sigemptyset, sigfillset, Signal Manager Directives +@end ifinfo +@subsection sigismember + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigismember( + const sigset_t *set, + int signo +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigemptyset, sigaction, sigismember, Signal Manager Directives +@end ifinfo +@subsection sigemptyset + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigemptyset( + sigset_t *set +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigaction, pthread_kill, sigemptyset, Signal Manager Directives +@end ifinfo +@subsection sigaction + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigaction( + int sig, + const struct sigaction *act, + struct sigaction *oact +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument passed. + +@item ENOTSUP +Realtime Signals Extension option not supported. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +The signal number cannot be SIGKILL. +@page +@ifinfo +@node pthread_kill, sigprocmask, sigaction, Signal Manager Directives +@end ifinfo +@subsection pthread_kill + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pthread_kill( + pthread_t thread, + int sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread indicated by the parameter thread is invalid. + +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigprocmask, pthread_sigmask, pthread_kill, Signal Manager Directives +@end ifinfo +@subsection sigprocmask + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigprocmask( + int how, + const sigset_t *set, + sigset_t *oset +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node pthread_sigmask, kill, sigprocmask, Signal Manager Directives +@end ifinfo +@subsection pthread_sigmask + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pthread_sigmask( + int how, + const sigset_t *set, + sigset_t *oset +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node kill, sigpending, pthread_sigmask, Signal Manager Directives +@end ifinfo +@subsection kill + +@subheading CALLING SEQUENCE: + +@example +#include <sys/types.h> +#include <signal.h> + +int kill( + pid_t pid, + int sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@item EPERM +Process does not have permission to send the signal to any receiving process. + +@item ESRCH +The process indicated by the parameter pid is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node sigpending, sigsuspend, kill, Signal Manager Directives +@end ifinfo +@subsection sigpending + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigpending( + const sigset_t *set +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets errno to one of the following: + +@table @b +@item EFAULT +Invalid address for set. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigsuspend, pause, sigpending, Signal Manager Directives +@end ifinfo +@subsection sigsuspend + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigsuspend( + const sigset_t *sigmask +); +@end example + +@subheading STATUS CODES: +@table @b +Returns -1 and sets errno. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pause, sigwait, sigsuspend, Signal Manager Directives +@end ifinfo +@subsection pause + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int pause( void ); +@end example + +@subheading STATUS CODES: +@table @b +Returns -1 and sets errno. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigwait, sigwaitinfo, pause, Signal Manager Directives +@end ifinfo +@subsection sigwait + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigwait( + const sigset_t *set, + int *sig +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +Invalid argument passed. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigwaitinfo, sigtimedwait, sigwait, Signal Manager Directives +@end ifinfo +@subsection sigwaitinfo + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigwaitinfo( + const sigset_t *set, + siginfo_t *info +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node sigtimedwait, sigqueue, sigwaitinfo, Signal Manager Directives +@end ifinfo +@subsection sigtimedwait + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigtimedwait( + const sigset_t *set, + siginfo_t *info, + const struct timespec *timeout +); +@end example + +@subheading STATUS CODES: +@table @b +@item EAGAIN +Timed out while waiting for the specified signal set. + +@item EINVAL +Nanoseconds field of the timeout argument is invalid. + +@item EINTR +Signal interrupted this function. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If timeout is NULL, then the thread will wait forever for the specified +signal set. + +@page +@ifinfo +@node sigqueue, alarm, sigtimedwait, Signal Manager Directives +@end ifinfo +@subsection sigqueue + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +int sigqueue( + pid_t pid, + int signo, + const union sigval value +); +@end example + +@subheading STATUS CODES: + +@table @b + +@item EAGAIN +No resources available to queue the signal. The process has already +queued SIGQUEUE_MAX signals that are still pending at the receiver +or the systemwide resource limit has been exceeded. + +@item EINVAL +The value of the signo argument is an invalid or unsupported signal +number. + +@item EPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. + +@item ESRCH +The process pid does not exist. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + + +@page +@ifinfo +@node alarm, Mutex Manager, sigqueue, Signal Manager Directives +@end ifinfo +@subsection alarm + +@subheading CALLING SEQUENCE: + +@example +#include <signal.h> + +unsigned int alarm( + unsigned int seconds +); +@end example + +@subheading STATUS CODES: + +If there was a previous alarm() request with time remaining, then this routine +returns the number of seconds until that outstanding alarm would have fired. +If no previous alarm() request was outstanding, then zero is returned. + +@subheading DESCRIPTION: + +@subheading NOTES: + + diff --git a/doc/posix_users/thread.texi b/doc/posix_users/thread.texi new file mode 100644 index 0000000000..56f8bf9be5 --- /dev/null +++ b/doc/posix_users/thread.texi @@ -0,0 +1,1023 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Thread Manager, Thread Manager Introduction, Preface, Top +@end ifinfo +@chapter Thread Manager +@ifinfo +@menu +* Thread Manager Introduction:: +* Thread Manager Background:: +* Thread Manager Operations:: +* Thread Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Thread Manager Introduction, Thread Manager Background, Thread Manager, Thread Manager +@end ifinfo +@section Introduction + +The thread manager ... + +The directives provided by the thread manager are: + +@itemize @bullet +@item @code{pthread_attr_init} - +@item @code{pthread_attr_destroy} - +@item @code{pthread_attr_setdetachstate} - +@item @code{pthread_attr_getdetachstate} - +@item @code{pthread_attr_setstacksize} - +@item @code{pthread_attr_getstacksize} - +@item @code{pthread_attr_setstackaddr} - +@item @code{pthread_attr_getstackaddr} - +@item @code{pthread_attr_setscope} - +@item @code{pthread_attr_getscope} - +@item @code{pthread_attr_setinheritsched} - +@item @code{pthread_attr_getinheritsched} - +@item @code{pthread_attr_setschedpolicy} - +@item @code{pthread_attr_getschedpolicy} - +@item @code{pthread_attr_setschedparam} - +@item @code{pthread_attr_getschedparam} - +@item @code{pthread_create} - +@item @code{pthread_exit} - +@item @code{pthread_detach} - +@item @code{pthread_join} - +@item @code{pthread_self} - +@item @code{pthread_equal} - +@item @code{pthread_once} - +@item @code{pthread_setschedparam} - +@item @code{pthread_getschedparam} - +@end itemize + +@ifinfo +@node Thread Manager Background, Thread Attributes, Thread Manager Introduction, Thread Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Thread Attributes:: +@end menu +@end ifinfo + +@ifinfo +@node Thread Attributes, Thread Manager Operations, Thread Manager Background, Thread Manager Background +@end ifinfo +@subsection Thread Attributes + +Thread attributes are utilized only at thread creation time. + +@table @b +@item stack address +is the address of the optionally user specified stack area for this thread. +If this value is NULL, then RTEMS allocates the memory for the thread stack +from the RTEMS Workspace Area. Otherwise, this is the user specified +address for the memory to be used for the thread's stack. Each thread must +have a distinct stack area. Each processor family has different alignment +rules which should be followed. + +@item stack size +is the minimum desired size for this thread's stack area. +If the size of this area as specified by the stack size attribute +is smaller than the minimum for this processor family and the stack +is not user specified, then RTEMS will automatically allocate a +stack of the minimum size for this processor family. + +@item contention scope +specifies the scheduling contention scope. RTEMS only supports the +PTHREAD_SCOPE_PROCESS scheduling contention scope. + +@item scheduling inheritance +specifies whether a user specified or the scheduling policy and +parameters of the currently executing thread are to be used. When +this is PTHREAD_INHERIT_SCHED, then the scheduling policy and +parameters of the currently executing thread are inherited by +the newly created thread. + +@item scheduling policy and parameters +specify the manner in which the thread will contend for the processor. +The scheduling parameters are interpreted based on the specified policy. +All policies utilize the thread priority parameter. + +@end table + +@ifinfo +@node Thread Manager Operations, Thread Manager Directives, Thread Attributes, Thread Manager +@end ifinfo +@section Operations + +@ifinfo +@node Thread Manager Directives, pthread_attr_init, Thread Manager Operations, Thread Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* pthread_attr_init:: +* pthread_attr_destroy:: +* pthread_attr_setdetachstate:: +* pthread_attr_getdetachstate:: +* pthread_attr_setstacksize:: +* pthread_attr_getstacksize:: +* pthread_attr_setstackaddr:: +* pthread_attr_getstackaddr:: +* pthread_attr_setscope:: +* pthread_attr_getscope:: +* pthread_attr_setinheritsched:: +* pthread_attr_getinheritsched:: +* pthread_attr_setschedpolicy:: +* pthread_attr_getschedpolicy:: +* pthread_attr_setschedparam:: +* pthread_attr_getschedparam:: +* pthread_create:: +* pthread_exit:: +* pthread_detach:: +* pthread_join:: +* pthread_self:: +* pthread_equal:: +* pthread_once:: +* pthread_setschedparam:: +* pthread_getschedparam:: +@end menu +@end ifinfo + +This section details the thread manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node pthread_attr_init, pthread_attr_destroy, Thread Manager Directives, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_init + +@subheading CALLING SEQUENCE: + + +@example +#include <pthread.h> + +int pthread_attr_init( + pthread_attr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_init, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_destroy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_destroy( + pthread_attr_t *attr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_destroy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setdetachstate + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setdetachstate( + pthread_attr_t *attr, + int detachstate +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The detachstate argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getdetachstate, pthread_attr_setstacksize, pthread_attr_setdetachstate, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getdetachstate + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getdetachstate( + const pthread_attr_t *attr, + int *detachstate +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The detatchstate pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setstacksize, pthread_attr_getstacksize, pthread_attr_getdetachstate, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setstacksize + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setstacksize( + pthread_attr_t *attr, + size_t stacksize +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If the specified stacksize is below the minimum required for this CPU, then +the stacksize will be set to the minimum for this CPU. + +@page +@ifinfo +@node pthread_attr_getstacksize, pthread_attr_setstackaddr, pthread_attr_setstacksize, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getstacksize + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getstacksize( + const pthread_attr_t *attr, + size_t *stacksize +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The stacksize pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setstackaddr, pthread_attr_getstackaddr, pthread_attr_getstacksize, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setstackaddr + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setstackaddr( + pthread_attr_t *attr, + void *stackaddr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getstackaddr, pthread_attr_setscope, pthread_attr_setstackaddr, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getstackaddr + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getstackaddr( + const pthread_attr_t *attr, + void **stackaddr +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The stackaddr pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setscope, pthread_attr_getscope, pthread_attr_getstackaddr, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setscope + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setscope( + pthread_attr_t *attr, + int contentionscope +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The contention scope specified is not valid. + +@item ENOTSUP +The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getscope, pthread_attr_setinheritsched, pthread_attr_setscope, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getscope + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getscope( + const pthread_attr_t *attr, + int *contentionscope +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The contentionscope pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_getscope, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setinheritsched + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setinheritsched( + pthread_attr_t *attr, + int inheritsched +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler inheritance argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getinheritsched, pthread_attr_setschedpolicy, pthread_attr_setinheritsched, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getinheritsched + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getinheritsched( + const pthread_attr_t *attr, + int *inheritsched +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The inheritsched pointer argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_getinheritsched, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setschedpolicy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setschedpolicy( + pthread_attr_t *attr, + int policy +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item ENOTSUP +The specified scheduler policy argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getschedpolicy, pthread_attr_setschedparam, pthread_attr_setschedpolicy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getschedpolicy + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getschedpolicy( + const pthread_attr_t *attr, + int *policy +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler policy argument pointer is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_getschedpolicy, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_setschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_setschedparam( + pthread_attr_t *attr, + const struct sched_param param +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler parameter argument is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_attr_getschedparam, pthread_create, pthread_attr_setschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_attr_getschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_attr_getschedparam( + const pthread_attr_t *attr, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: +@table @b +@item EINVAL +The attribute pointer argument is invalid. + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The specified scheduler parameter argument pointer is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_create, pthread_exit, pthread_attr_getschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_create + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_create( + pthread_t *thread, + const pthread_attr_t *attr, + void (*start_routine)( void * ), + void *arg +); +@end example + +@subheading STATUS CODES: + +@table @b + +@item EINVAL +The attribute set is not initialized. + +@item EINVAL +The user specified a stack address and the size of the area was not +large enough to meet this processor's minimum stack requirements. + +@item EINVAL +The specified scheduler inheritance policy was invalid. + +@item ENOTSUP +The specified contention scope was PTHREAD_SCOPE_PROCESS. + +@item EINVAL +The specified thread priority was invalid. + +@item EINVAL +The specified scheduling policy was invalid. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified replenishment +period is less than the initial budget. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified low priority +is invalid. + +@item EAGAIN +The system lacked the necessary resources to create another thread, or the +self imposed limit on the total number of threads in a process +PTHREAD_THREAD_MAX would be exceeded. + +@item EINVAL +Invalid argument passed. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_exit, pthread_detach, pthread_create, Thread Manager Directives +@end ifinfo +@subsection pthread_exit + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +void pthread_exit( + void *status +); +@end example + +@subheading STATUS CODES: +@table @b +@item NONE + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_detach, pthread_join, pthread_exit, Thread Manager Directives +@end ifinfo +@subsection pthread_detach + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_detach( + pthread_t thread +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread specified is invalid. + +@item EINVAL +The thread specified is not a joinable thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If any threads have previously joined with the specified thread, then they +will remain joined with that thread. Any subsequent calls to pthread_join +on the specified thread will fail. + +@page +@ifinfo +@node pthread_join, pthread_self, pthread_detach, Thread Manager Directives +@end ifinfo +@subsection pthread_join + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_join( + pthread_t thread, + void **value_ptr +); +@end example + +@subheading STATUS CODES: +@table @b +@item ESRCH +The thread specified is invalid. + +@item EINVAL +The thread specified is not a joinable thread. + +@item EDEADLK +A deadlock was detected or thread is the calling thread. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +If any threads have previously joined with the specified thread, then they +will remain joined with that thread. Any subsequent calls to pthread_join +on the specified thread will fail. + +If value_ptr is NULL, then no value is returned. + +@page +@ifinfo +@node pthread_self, pthread_equal, pthread_join, Thread Manager Directives +@end ifinfo +@subsection pthread_self + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +pthread_t pthread_self( void ); +@end example + +@subheading STATUS CODES: + +This routine returns the id of the calling thread. + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_equal, pthread_once, pthread_self, Thread Manager Directives +@end ifinfo +@subsection pthread_equal + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_equal( + pthread_t t1, + pthread_t t2 +); +@end example + +@subheading STATUS CODES: + +@table @b +@item zero +The thread ids are not equal. + +@item non-zero +The thread ids are equal. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +The behavior is undefined if the thread IDs are not valid. + +@page +@ifinfo +@node pthread_once, pthread_setschedparam, pthread_equal, Thread Manager Directives +@end ifinfo +@subsection pthread_once + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +pthread_once_t once_control = PTHREAD_ONCE_INIT; + +int pthread_once( + pthread_once_t *once_control, + void (*init_routine)(void) +); +@end example + +@subheading STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_setschedparam, pthread_getschedparam, pthread_once, Thread Manager Directives +@end ifinfo +@subsection pthread_setschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_setschedparam( + pthread_t thread, + int policy, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The scheduling parameters indicated by the parameter param is invalid. + +@item EINVAL +The value specified by policy is invalid. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified replenishment +period is less than the initial budget. + +@item EINVAL +The scheduling policy was SCHED_SPORADIC and the specified low priority +is invalid. + +@item ESRCH +The thread indicated was invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@ifinfo +@node pthread_getschedparam, Signal Manager, pthread_setschedparam, Thread Manager Directives +@end ifinfo +@subsection pthread_getschedparam + +@subheading CALLING SEQUENCE: + +@example +#include <pthread.h> + +int pthread_getschedparam( + pthread_t thread, + int *policy, + struct sched_param *param +); +@end example + +@subheading STATUS CODES: + +@table @b +@item EINVAL +The policy pointer argument is invalid. + +@item EINVAL +The scheduling parameters pointer argument is invalid. + +@item ESRCH +The thread indicated by the parameter thread is invalid. + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/relnotes/Makefile b/doc/relnotes/Makefile new file mode 100644 index 0000000000..e50a845f11 --- /dev/null +++ b/doc/relnotes/Makefile @@ -0,0 +1,53 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=relnotes + +all: + +COMMON_FILES=../common/cpright.texi + +FILES=install.texi intro.texi probrep.texi relnotes.texi status.texi + +all: + +info: relnotes + cp $(PROJECT) $(wildcard $(PROJECT)-*) $(INFO_INSTALL) + +relnotes: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f relnotes + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +dv: dvi + $(XDVI) $(PROJECT).dvi + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +html: + -mkdir $(WWW_INSTALL)/relnotes + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f relnotes relnotes-* _* + diff --git a/doc/relnotes/install.texi b/doc/relnotes/install.texi new file mode 100644 index 0000000000..3f79e39da5 --- /dev/null +++ b/doc/relnotes/install.texi @@ -0,0 +1,174 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Installation Procedure, Installation Procedure Introduction, Introduction Documentation, Top +@end ifinfo +@chapter Installation Procedure +@ifinfo +@menu +* Installation Procedure Introduction:: +* Installation Procedure RTEMS FTP Site Organization:: +* Installation Procedure Unarchiving the RTEMS and GNU Components:: +* Installation Procedure Installing a Cross-Development GNU Toolset:: +* Installation Procedure Installing RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Installation Procedure Introduction, Installation Procedure RTEMS FTP Site Organization, Installation Procedure, Installation Procedure +@end ifinfo +@section Introduction + +This chapter describes the process of installing and +configuring RTEMS and a cross-development environment based on +freely available tools and libraries. + +@ifinfo +@node Installation Procedure RTEMS FTP Site Organization, Installation Procedure Unarchiving the RTEMS and GNU Components, Installation Procedure Introduction, Installation Procedure +@end ifinfo +@section RTEMS FTP Site Organization + +RTEMS is distributed only via anonymous ftp. + +This section will discuss how to navigate the RTEMS +ftp site and unarchive the files in the RTEMS and GNU package +distributions. All example commands will be given in a shell +independent fashion unless otherwise noted. + +Throughout the rest of this manual +<RTEMS_distribution> will be used as the parent of components +within the RTEMS distribution. For persons using the ftp +distribution found on the primary ftp site for RTEMS, +<RTEMS_distribution> is +ftp://ftp.OARcorp.com/oarcorp/rtems/@value{RTEMS-RELEASE}. + +The archive files for RTEMS Release @value{RTEMS-RELEASE} are found +under the directory <RTEMS_distribution>. This directory +contains the files which comprise this relase as well as any +patches which may be required for other tools. + +The complete source code and documentation set for +the C language implementation of RTEMS is provided. + +Documentation other than this on-line version is available to +OAR support customers. Please contact OAR for more information. + +@ifinfo +@node Installation Procedure Unarchiving the RTEMS and GNU Components, Installation Procedure Installing a Cross-Development GNU Toolset, Installation Procedure RTEMS FTP Site Organization, Installation Procedure +@end ifinfo +@section Unarchiving the RTEMS and GNU Components + +Many of the components of the RTEMS release are +"tarred, zipped" files and have the .tar.gz or .tgz extension. +The GNU zip package is required to unarchives these files on the +RTEMS ftp site. If this package is not installed, the source +can be found in the files +ftp://prep.ai.mit.edu/pub/gnu/gzip-1.2.4.shar or +ftp://prep.ai.mit.edu/pub/gnu/gzip-1.2.4.tar. It may be +restored using a command similar to the following: + +@example +@group +tar xvf gzip-1.2.4.tar + +OR + +sh gzip-1.2.4.shar +@end group +@end example + +This will create a subdirectory gzip-1.2.4 in the +current directory. Please examine the files README and INSTALL +and follow the instructions provided there. + +[Note: The GNU tools follow a standard packaging procedure +They will unarchive into a directory based on the package name and version +number. For detailed instructions on compilation and +installation of the GNU tools, please refer to the instructions for +each GNU tool.] + +Files which have been "tarred, zipped" (i.e. .tar.gz +or .tgz extension) may be unarchived with a command similar to +one of the following: + +@example +@group +gzcat <file>.tgz | tar xvof - + +OR + +gunzip -c <file>.tgz | tar xvof - + +OR + +gtar xzvf <file>.tgz +@end group +@end example + +NOTE: gunzip -c is equivalent to gzcat, while gtar is GNU tar. + +Given that the necessary utility programs are +installed, any of the above commands will extract the contents +of <file>.tar.gz into the current directory. All of the RTEMS +components will be extracted into the subdirectory rtems-@value{RTEMS-RELEASE}. +To view the contents of a component without restoring any files, +use a command similar to the following: + +@example +@group +gzcat <file>.tgz | tar tvf - +@end group +@end example + +@ifinfo +@node Installation Procedure Installing a Cross-Development GNU Toolset, Installation Procedure Installing RTEMS, Installation Procedure Unarchiving the RTEMS and GNU Components, Installation Procedure +@end ifinfo +@section Installing a Cross-Development GNU Toolset + +This sections describes how to build and install the +FSF GNU tools for use as a cross-compilation system. These +tools are used by the RTEMS developers. Every effort has been +made to make these instructions accurate and complete. However, +it is recommended that the individual doing the installation +read the appropriate installation notes for each of the tools in +the cross toolset. This will help insure that there are no +special requirements for a particular host. + +If the host and target processors are the same, then +it may be possible to use the host development tools. An +example of this scenario is using a SPARC based workstation +to develop an RTEMS application for the SPARC processor. Although +the native toolset is useable in this scenario, it is ultimately +more desirable to build a toolset specifically for the embedded environment. + +Instructions for building a cross environment using the GNU +tools is provided in the crossgcc FAQ available from ftp.cygnus.com +in /pub/embedded/crossgcc. It is recommended that the user following +these instructions. + +After the cross development toolset has been built +and installed, it will be necessary to modify the environment of +each RTEMS application developer to reflect at least the path of +the newly installed cross development toolset. + +The documentation for the FSF GNU and Cygnus tools is +formatted using TeX. The RTEMS developers use TeX 3.14t3 to +format the manuals for their own use. This document does not +contain instructions on the acquisition or installation of TeX +and supporting tools. + +NOTE: For "UNIX" processors, the native compiler binary utilities +should be used. + +@ifinfo +@node Installation Procedure Installing RTEMS, Development Environment Status, Installation Procedure Installing a Cross-Development GNU Toolset, Installation Procedure +@end ifinfo +@section Installing RTEMS + +For instructions on building and installing RTEMS, please refer to +the file README.configure in the source distribution. + diff --git a/doc/relnotes/intro.texi b/doc/relnotes/intro.texi new file mode 100644 index 0000000000..f185a40f17 --- /dev/null +++ b/doc/relnotes/intro.texi @@ -0,0 +1,223 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Introduction, Introduction Supporting Tools, Top, Top +@end ifinfo +@chapter Introduction +@ifinfo +@menu +* Introduction Supporting Tools:: +* Introduction Documentation:: +@end menu +@end ifinfo + +This document describes the contents, installation +procedure, and current status of Release @value{RTEMS-RELEASE} of the RTEMS +executive. An installation procedure is provided which +describes the steps necessary to load and configure the RTEMS +environment, including the GNU Development Environment and the +Cygnus NEWLIB ANSI C Library, on a host computer. The status of +the RTEMS environment is given, which includes supported +processors and target boards, versions of the GNU utilities +which were used by the RTEMS developers for this release, +support libraries status, features which are not implemented, +and any known existing problems. + +This RTEMS release package contains the following general components: + +@itemize @bullet +@item RTEMS C Executive + +@item RTEMS C Documentation Set + +@item RTEMS NEWLIB ANSI C Library + +@item Patches to GNU Development Tools + +@end itemize + +There is a mailing list dedicated to RTEMS. This is +a Majordomo style mailing list and may be subscribed to +by sending a message to rtems-list-request@@OARcorp.com with +the following line as the body: + +@example +subscribe rtems_user@@your_email_goes_here.com +@end example + +Please replace rtems_user@@your_email_goes_here.com with your +email address. + +@ifinfo +@node Introduction Supporting Tools, GNU Development Tools, Introduction, Introduction +@end ifinfo +@section Supporting Tools +@ifinfo +@menu +* GNU Development Tools:: +* ANSI C Libraries:: +* GNU C Library:: +* Cygnus NEWLIB C Library:: +@end menu +@end ifinfo + +This section discusses the freely available tools and +libraries which are part of the RTEMS Development Environment. +None of the tools discussed in this section were developed by +the RTEMS project, although many do include submissions from the +project. All of the tools and libraries required to build RTEMS +are freely available. The home ftp site for most of the non-RTEMS +specific tools is either prep.ai.mit.edu (18.71.0.38) or +ftp.cygnus.com (140.174.1.3). + +Specifically of interest to embedded systems developers +using the GNU tools is the crossgcc mailing list. This is +a Majordomo style mailing list and may be subscribed to +by sending a message to crossgcc-request@@cygnus.com with +the following line as the body: + +@example +subscribe rtems_user@@your_email_goes_here.com +@end example + +Please replace rtems_user@@your_email_goes_here.com with your +email address. The FAQ for crossgcc is in the /pub/embedded/crossgcc +directory on ftp.cygnus.com (205.180.83.42). + +@ifinfo +@node GNU Development Tools, ANSI C Libraries, Introduction Supporting Tools, Introduction Supporting Tools +@end ifinfo +@subsection GNU Development Tools + +Numerous GNU tools are used in the RTEMS Development +Environment including C and Ada compilers, the GNU make program, +GNU m4, the GNU assembler and binary utilities (linker, +librarian, etc.), GNU tar, GNU zip, and the GNU debugger. These +tools are distributed in source form and are all licensed under +the GNU Public License which allows for unrestricted +distribution under the condition that source code always be +available. The Free Software Foundation is officially the +originator of most of the GNU tools although many individuals +have contributed to the GNU projects. In keeping with the +spirit of the GPL, most of the time the GNU tools are +distributed as source code without executables. It is the +responsibility of the local site to install each tool. Numerous +organizations and individuals supply executables for the GNU +tools. All are required by the terms of the GPL to also make +the source code available to the end user. + +The primary ftp site for the FSF GNU tools is +prep.ai.mit.edu (18.71.0.38) in the /pub/gnu directory. These +tools are mirrored on numerous ftp sites. + +Intel maintains a toolset for their i960 processor +family based on the GNU tools referred to as GNU/960. The +source code for this toolset is available from ftp.intel.com +(143.185.65.2). [NOTE: The GNU/960 toolset generally includes +an older version of GCC than that available from the FSF. When +the FSF version of GNU C is significantly newer than that in the +GNU/960 release, the RTEMS developers replace the GCC in the +GNU/960 toolset with the FSF release.] + +Cygnus maintains an ftp site -- ftp.cygnus.com +(205.180.83.42) -- which contains a source code which appeals to +embedded developers. Of especial interest on this site are the +directories /pub/newlib and /pub/embedded. + +@ifinfo +@node ANSI C Libraries, GNU C Library, GNU Development Tools, Introduction Supporting Tools +@end ifinfo +@subsection ANSI C Libraries + +This section discusses the following freely +distributable ANSI C Libraries: + +@itemize @bullet +@item GNU C Library, and + +@item Cygnus NEWLIB +@end itemize + +No C Library is included in the standard RTEMS +distribution. It is the responsibility of the user to obtain +and install a C Library separately. + +@ifinfo +@node GNU C Library, Cygnus NEWLIB C Library, ANSI C Libraries, Introduction Supporting Tools +@end ifinfo +@subsection GNU C Library + +The GNU C Library is a robust and well-documented C +Library which is distributed under the terms of the Library GNU +Public License (LGPL). This library was not designed for use in +real-time, embedded systems and the resource requirements of +some of the routines in this library are an obvious indication +of this. Additionally, this library does not have support for +reentrancy in the sense that each task in a multitasking system +could safely invoke every routine in the library. Finally, the +distribution terms of the LGPL are considered undesirable by +many embedded systems developers. However, the GNU C Library is +very complete and is compliant with as many standards as +possible. Because of this, it may be the only choice for many +developers. + +There is currently no RTEMS support for the GNU C Library. + +The primary ftp site for this library is +prep.ai.mit.edu (18.71.0.38). + +@ifinfo +@node Cygnus NEWLIB C Library, Introduction Documentation, GNU C Library, Introduction Supporting Tools +@end ifinfo +@subsection Cygnus NEWLIB C Library + +The Cygnus NEWLIB C Library was specifically designed +for real-time embedded systems. It is a small, reasonably +documented Library with support for reentrancy. This library is +a collection of freely distributable and public domain source +code and is freely distributable with as few restrictions as +possible placed on the end user. + +The RTEMS specific support code for NEWLIB has been +submitted to the NEWLIB maintainers and should be included in a +future release. Until that time, it is recommended that the +beta version of NEWLIB with RTEMS support added be used by the +application developer. The beta version of NEWLIB with RTEMS +specific support is ONLY available on the OAR ftp site. This +beta version is strictly tied to a particular RTEMS release. + +The primary ftp site for this library is ftp.cygnus.com (205.180.83.42). + +@ifinfo +@node Introduction Documentation, Installation Procedure, Cygnus NEWLIB C Library, Introduction +@end ifinfo +@section Documentation + +The RTEMS Documentation Set is provided online at http://www.OARcorp.com/ +as reference information for all levels of RTEMS users. The set includes +the following documents: + +@itemize @bullet +@item C Applications User's Guide + +@item Intel i386 C Applications Supplement + +@item Intel i960CA C Applications Supplement + +@item Motorola MC68xxx C Applications Supplement + +@item Hewlett Packard PA-RISC 1.1 C Applications Supplement + +@item SPARC C Applications Supplement + +@item Development Environment Guide + +@item Release Notes +@end itemize + +The RTEMS documentation set is available in alternate formats to +support customers. diff --git a/doc/relnotes/probrep.texi b/doc/relnotes/probrep.texi new file mode 100644 index 0000000000..54f777a030 --- /dev/null +++ b/doc/relnotes/probrep.texi @@ -0,0 +1,60 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + + + +@ifinfo +@node RTEMS PROBLEM REPORT, Command and Variable Index, RTEMS Problem Reporting, Top +@end ifinfo +@chapter RTEMS PROBLEM REPORT + +@example + +Customer (Company) Name: + +Customer Address: + +Contact Name: + +Telephone Voice: Fax: + + + +Product: Version: + +Target Processor: Target System: + +Host Computer System: + +Host Operating System: Version: + + + +Report Type: Customer Impact: + + + +[ ] Problem/Error [ ] System is inoperable, cannot proceed + +[ ] Enhancement [ ] Must be corrected in the near future + +[ ] Inquiry Suggestion [ ] Problem may be avoided until fixed + +[ ] Other______________ [ ] Problem is not time critical + + [ ] Minor problem + +@end example + + +Please provide a detailed description of the +problem (Attachments including source code, example code, +makefiles, possible solutions, and any other information +describing the problem will be appreciated): + + + + diff --git a/doc/relnotes/relnotes.texi b/doc/relnotes/relnotes.texi new file mode 100644 index 0000000000..f4a2a24d36 --- /dev/null +++ b/doc/relnotes/relnotes.texi @@ -0,0 +1,116 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename relnotes +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file +@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 ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Release Notes: (relnotes). Release Notes +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c variable substitution info: +@c +@c @set RTEMS-LANGUAGE C +@c the language is @value{RTEMS-LANGUAGE} +@c NOTE: don't use underscore in the name +@c + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS Release Notes + +@setchapternewpage odd +@settitle RTEMS Release Notes +@titlepage +@finalout + +@title RTEMS Release Notes +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include intro.texi +@include install.texi +@include status.texi +@include probrep.texi + +@ifinfo +@node Top, Introduction, (dir), (dir) +@top relnotes + +This is the online version of the RTEMS Release Notes. + +@menu +* Introduction:: +* Installation Procedure:: +* Development Environment Status:: +* RTEMS PROBLEM REPORT:: +* 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, RTEMS PROBLEM REPORT, 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 + +@contents +@bye + diff --git a/doc/relnotes/status.texi b/doc/relnotes/status.texi new file mode 100644 index 0000000000..8a41b52b96 --- /dev/null +++ b/doc/relnotes/status.texi @@ -0,0 +1,258 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Development Environment Status, Development Environment Status RTEMS Executive Status, Installation Procedure Installing RTEMS, Top +@end ifinfo +@chapter Development Environment Status +@ifinfo +@menu +* Development Environment Status RTEMS Executive Status:: +* Development Environment Status Development Environment Status:: +* Development Environment Status Known Problems:: +@end menu +@end ifinfo + +This chapter will describe the current status of +release version @value{RTEMS-RELEASE} of the RTEMS Development Environment. + +@ifinfo +@node Development Environment Status RTEMS Executive Status, Development Environment Status Development Environment Status, Development Environment Status, Development Environment Status +@end ifinfo +@section RTEMS Executive Status + +Release @value{RTEMS-RELEASE} of the RTEMS Executive contains support +for both the classic RTEMS API based on the RTEID specification as well +as support for POSIX threads and real-time extensions. + +The classic RTEMS API has the following managers based upon the RTEID +specification: + +@itemize @bullet +@item Task +@item Initialization +@item Clock +@item Timer +@item Interrupt +@item Fatal Error +@item Message +@item Semaphore +@item Event +@item Signal +@item Region +@item Partition +@item Dual Ported Memory +@item I/O +@item Multiprocessing +@item Rate Monotonic +@item User Extensions +@end itemize + +RTEMS also has support for the following managers based upon the POSIX threads +and real-time extensions: + +@itemize @bullet +@item Thread +@item Clock +@item Key +@item Condition Variable +@item Mutex +@item Signal +@item Scheduler +@end itemize + +This release of the C implementation supports the +following processors and target boards: + +@itemize @bullet +@item Motorola M68k family +@itemize - +@item DY-4 DMV152, SVME153 +@item Motorola IDP +@item Motorola MVME135, MVME136 +@item Motorola MVME147, MVME147S +@item Motorola MVME162 +@item EFI 68000 and 68332 +@item Generic 68302 +@item Generic 68360 and 68360 in companion mode with 68040 +@end itemize + +@item Intel i386 family +@itemize - +@item Force CPU386 +@item Intel i386ex eval board +@item PC-AT i386 and above (go32) +@end itemize + +@item Intel i960 family +@itemize - +@item Cyclone CVME960, CVME961 +@end itemize + +@item Hewlett Packard PA-RISC family +@itemize - +@item Processor Simulator +@end itemize + +@item PowerPC +@itemize - +@item Papyrus (proprietary controller) +@end itemize + +@item SPARC +@itemize - +@item ERC32 (space-hardened V7) +@end itemize + +@item MIPS +@itemize - +@item P4000 with R4600 or R4650 +@end itemize + +@item AMD 29K +@itemize - +@item Portsw +@end itemize + +@item UNIX +@itemize - +@item Hewlett Packard HPUX (PA-RISC) +@item Sun Solaris 2.x (SPARC) +@item Linux (i386) +@end itemize + +@end itemize + +Support for the Cygnus NEWLIB Standard C Library is +provided with this release which may be used on any of the RTEMS +supported targets. The BSPs only provide support for console +I/O only using this library. Support for the reentrancy +capabilities of newlib is provided in the RTEMS distribution. + +@ifinfo +@node Development Environment Status Development Environment Status, Development Environment Status Known Problems, Development Environment Status RTEMS Executive Status, Development Environment Status +@end ifinfo +@section Development Environment Status + +This section details the versions of the tools used +to develop and maintain RTEMS @value{RTEMS-RELEASE}: + +@itemize @bullet +@item Cross Tools +@itemize - +@item gcc - 2.7.2.2 with rtems patch +@item binutils - 2.7 with rtems patch +@item zip - 1.2.4 +@item make - 3.74 +@end itemize +@end itemize + + +@ifinfo +@node Development Environment Status Known Problems, Executive Problems, Development Environment Status Development Environment Status, Development Environment Status +@end ifinfo +@section Known Problems +@ifinfo +@menu +* Executive Problems:: +* Development Environment Problems:: +* RTEMS Problem Reporting:: +@end menu +@end ifinfo + +Problems which are known to exist at the time of +release are described in the following sections. These are +provided as warnings to the user and where possible, workarounds +are provided until the problem is corrected. + +@ifinfo +@node Executive Problems, Development Environment Problems, Development Environment Status Known Problems, Development Environment Status Known Problems +@end ifinfo +@subsection Executive Problems + +There are no known bugs in the executive itself. + +@ifinfo +@node Development Environment Problems, RTEMS Problem Reporting, Executive Problems, Development Environment Status Known Problems +@end ifinfo +@subsection Development Environment Problems + +There are no known major problems with the +development environment. + +@ifinfo +@node RTEMS Problem Reporting, RTEMS PROBLEM REPORT, Development Environment Problems, Development Environment Status Known Problems +@end ifinfo +@subsection RTEMS Problem Reporting + +A problem report is provided at the end of this +document and may be copied by the RTEMS user. Please fill out +the form completely to assure a speedy response to the problem. +In filling out the problem report the following instructions +apply: + +@table @code +@item User Name and Address: +The full name +and mailing address of the customer or company where +correspondence from RTEMS support personnel may be shipped. + +@item Contact Name: +The name of the person with whom +RTEMS support personnel will correspond with concerning the +reported problem. + +@item Telephone Voice/FAX: +The telephone numbers which +will enable RTEMS support personnel to reach the designated +contact name. + +@item Product/Version: +The RTEMS product and the version that is currently in use. + +@item Target Processor/System: +The processor and board type that is the target. + +@item Host Computer System: +The manufacturer and model +number of the system on which RTEMS has been installed. + +@item Host Operating System/Version: +The operating system and version under which RTEMS has been installed. + +@c @item Report Type: +@c Check the most appropriate description of the reported problem. + +@item Customer Impact: +Indicate the severity of the impact of the reported problem. + +@item Detailed Description: +A written description of the +problem including the area of the RTEMS development environment +where the problem is located and its behavior. Please feel free +to provide source code listings, makefiles, possible solutions, +and any other information describing the problem. This +additional information may be submitted via email or anonymous +ftp. + +Support, training, ports, and custom development are provided +by On-Line Applications Research Corporation (OAR). Correspondence +regarding any aspect of RTEMS should be addressed as follows +(magnetic tapes should be marked: DO NOT X-RAY): +@end table + +@example +@group +RTEMS +On-Line Applications Research Corporation +4910-L Corporate Drive +Huntsville, AL 35805 +Voice: (205) 722-9985 +FAX: (205) 722-0985 +EMAIL: rtems@@OARcorp.com +@end group +@end example + diff --git a/doc/rtems.html b/doc/rtems.html new file mode 100644 index 0000000000..58e6a853f2 --- /dev/null +++ b/doc/rtems.html @@ -0,0 +1,26 @@ +<HTML> +<HEAD><TITLE>RTEMS On-Line Library</TITLE></HEAD> +<BODY BGCOLOR="FFFFFF"> +<A HREF="http://www.oarcorp.com" target="Text Frame"> + <IMG align=right BORDER=0 SRC="oaronly.jpg" ALT="OAR"> </A> +<FONT SIZE=-1> +<H1>RTEMS On-Line Library</H1> +<HR> +<BODY> +<MENU> +<LI><A HREF="c_user/Top.html">RTEMS Applications C User's Guide</A> +<LI><A HREF="relnotes/Top.html">RTEMS Release Notes</A> +<LI><A HREF="develenv/Top.html">RTEMS Development Environment Guide</A> +<LI><A HREF="HELP.html">RTEMS AMD 29K C Applications Supplement</A> +<LI><A HREF="c_i386/Top.html">RTEMS Intel i386 C Applications Supplement</A> +<LI><A HREF="c_i960/Top.html">RTEMS Intel i960 C Applications Supplement</A> +<LI><A HREF="HELP.html">RTEMS MIPS C Applications Supplement</A> +<LI><A HREF="c_m68k/Top.html">RTEMS Motorola MC68xxx C Applications Supplement</A> +<LI><A HREF="HELP.html">RTEMS PowerPC C Applications Supplement</A> +<LI><A HREF="c_sparc/Top.html">RTEMS SPARC C Applications Supplement</A> +<LI><A HREF="c_hppa1_1/Top.html">RTEMS Hewlett Packard PA-RISC C Applications Supplement</A> +<LI><A HREF="HELP.html">RTEMS UNIX Port C Applications Supplement</A> +</MENU> +<HR> +Copyright © 1997 <A HREF="http://www.oarcorp.com" target="Text Frame">OAR Corporation</A> +</BODY></HTML> diff --git a/doc/rtems_footer.html b/doc/rtems_footer.html new file mode 100644 index 0000000000..3644d47d88 --- /dev/null +++ b/doc/rtems_footer.html @@ -0,0 +1,3 @@ +<HR> +<P>Back to <A HREF="../rtems.html">RTEMS On-Line Library</A>.</P> +<P>Copyright © 1997 <A HREF="http://www.oarcorp.com" target="Text Frame">OAR Corporation</A> diff --git a/doc/rtems_header.html b/doc/rtems_header.html new file mode 100644 index 0000000000..75ed21efcf --- /dev/null +++ b/doc/rtems_header.html @@ -0,0 +1,6 @@ +<BODY BGCOLOR="FFFFFF"> +<A HREF="http://www.oarcorp.com" target="Text Frame"> + <IMG align=right BORDER=0 SRC="../oaronly.jpg" ALT="OAR"> </A> +<FONT SIZE=-1> +<H1>RTEMS On-Line Library</H1> +<HR> diff --git a/doc/supplements/hppa1_1/Makefile b/doc/supplements/hppa1_1/Makefile new file mode 100644 index 0000000000..ac49a22b33 --- /dev/null +++ b/doc/supplements/hppa1_1/Makefile @@ -0,0 +1,88 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=hppa1_1 +REPLACE=../tools/word-replace + +all: + +COMMON_FILES=../common/cpright.texi ../common/setup.texi \ + ../common/timing.texi + +FILES= $(PROJECT).texi \ + bsp.texi callconv.texi cpumodel.texi cputable.texi fatalerr.texi \ + intr.texi memmodel.texi preface.texi timetbl.texi timedata.texi wksheets.texi + +all: + +info: c_hppa1_1 + cp c_$(PROJECT) $(INFO_INSTALL) + +c_hppa1_1: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f c_hppa1_1 + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(PROJECT).dvi + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +replace: timedata.texi + +intr.texi: intr.t TIMES + ${REPLACE} -p TIMES intr.t + mv intr.t.fixed intr.texi + +timetbl.t: ../common/timetbl.t + sed -e 's/TIMETABLE_NEXT_LINK/Command and Variable Index/' \ + <../common/timetbl.t >timetbl.t + +timetbl.texi: timetbl.t TIMES + ${REPLACE} -p TIMES timetbl.t + mv timetbl.t.fixed timetbl.texi + +timedata.texi: timedata.t TIMES + ${REPLACE} -p TIMES timedata.t + mv timedata.t.fixed timedata.texi + +wksheets.t: ../common/wksheets.t + sed -e 's/WORKSHEETS_PREVIOUS_LINK/Processor Dependent Information Table CPU Dependent Information Table/' \ + -e 's/WORKSHEETS_NEXT_LINK/HP-7100 Timing Data/' \ + <../common/wksheets.t >wksheets.t + +wksheets.texi: wksheets.t TIMES + ${REPLACE} -p TIMES wksheets.t + mv wksheets.t.fixed wksheets.texi + +html: $(FILES) + -mkdir $(WWW_INSTALL)/c_hppa1_1 + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/c_$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(PROJECT) $(PROJECT)-* + rm -f c_hppa1_1 c_hppa1_1-* + rm -f timedata.texi timetbl.texi intr.texi wksheets.texi + rm -f timetbl.t wksheets.t + rm -f *.fixed _* + diff --git a/doc/supplements/hppa1_1/SIMHPPA_TIMES b/doc/supplements/hppa1_1/SIMHPPA_TIMES new file mode 100644 index 0000000000..485340715b --- /dev/null +++ b/doc/supplements/hppa1_1/SIMHPPA_TIMES @@ -0,0 +1,244 @@ +# +# PA-RISC Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL HP-7100 +# +# Interrupt Latency +# +# NOTE: In general, the text says it is hand-calculated to be +# RTEMS_MAXIMUM_DISABLE_PERIOD at RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ +# Mhz and this was last calculated for Release +# RTEMS_VERSION_FOR_MAXIMUM_DISABLE_PERIOD. +# +RTEMS_MAXIMUM_DISABLE_PERIOD TBD +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ TBD +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD TBD +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 1 +RTEMS_RESTORE_1ST_FP_TASK 2 +RTEMS_SAVE_INIT_RESTORE_INIT 3 +RTEMS_SAVE_IDLE_RESTORE_INIT 4 +RTEMS_SAVE_IDLE_RESTORE_IDLE 5 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 6 +RTEMS_TASK_IDENT_ONLY 7 +RTEMS_TASK_START_ONLY 8 +RTEMS_TASK_RESTART_CALLING_TASK 9 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 9 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 10 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 11 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 12 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 13 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 14 +RTEMS_TASK_DELETE_CALLING_TASK 15 +RTEMS_TASK_DELETE_SUSPENDED_TASK 16 +RTEMS_TASK_DELETE_BLOCKED_TASK 17 +RTEMS_TASK_DELETE_READY_TASK 18 +RTEMS_TASK_SUSPEND_CALLING_TASK 19 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 20 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 21 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 22 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 23 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 24 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 25 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 26 +RTEMS_TASK_MODE_NO_RESCHEDULE 27 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 28 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 29 +RTEMS_TASK_GET_NOTE_ONLY 30 +RTEMS_TASK_SET_NOTE_ONLY 31 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 32 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 33 +RTEMS_TASK_WAKE_WHEN_ONLY 34 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 35 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 36 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 37 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 38 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 39 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 40 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 41 +RTEMS_CLOCK_GET_ONLY 42 +RTEMS_CLOCK_TICK_ONLY 43 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 44 +RTEMS_TIMER_IDENT_ONLY 45 +RTEMS_TIMER_DELETE_INACTIVE 46 +RTEMS_TIMER_DELETE_ACTIVE 47 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 48 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 49 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 50 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 51 +RTEMS_TIMER_RESET_INACTIVE 52 +RTEMS_TIMER_RESET_ACTIVE 53 +RTEMS_TIMER_CANCEL_INACTIVE 54 +RTEMS_TIMER_CANCEL_ACTIVE 55 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 56 +RTEMS_SEMAPHORE_IDENT_ONLY 57 +RTEMS_SEMAPHORE_DELETE_ONLY 58 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 59 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 60 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 61 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 62 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 63 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 64 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 65 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 66 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 67 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 68 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 69 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 70 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 71 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 72 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 73 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 74 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 75 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 77 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 78 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 79 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 80 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 81 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 82 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 83 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 84 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 85 +RTEMS_EVENT_RECEIVE_AVAILABLE 86 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 87 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 88 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 89 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 90 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 91 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 92 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 93 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 94 +RTEMS_PARTITION_IDENT_ONLY 95 +RTEMS_PARTITION_DELETE_ONLY 96 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 97 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 98 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 99 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 100 +RTEMS_REGION_IDENT_ONLY 101 +RTEMS_REGION_DELETE_ONLY 102 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 103 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 104 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 105 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 106 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 107 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 108 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 109 +RTEMS_PORT_IDENT_ONLY 110 +RTEMS_PORT_DELETE_ONLY 111 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 112 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 113 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 114 +RTEMS_IO_OPEN_ONLY 115 +RTEMS_IO_CLOSE_ONLY 116 +RTEMS_IO_READ_ONLY 117 +RTEMS_IO_WRITE_ONLY 118 +RTEMS_IO_CONTROL_ONLY 119 +# +# Rate Monotonic Manager +# +RTEMS_RATE_MONOTONIC_CREATE_ONLY 120 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 121 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 122 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 123 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 124 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 125 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 126 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 127 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 128 +RTEMS_MINIMUM_CONFIGURATION xx,129 +RTEMS_MAXIMUM_CONFIGURATION xx,130 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE x,131 +RTEMS_INITIALIZATION_CODE_SIZE x,132 +RTEMS_TASK_CODE_SIZE x,133 +RTEMS_INTERRUPT_CODE_SIZE x,134 +RTEMS_CLOCK_CODE_SIZE x,135 +RTEMS_TIMER_CODE_SIZE x,136 +RTEMS_SEMAPHORE_CODE_SIZE x,137 +RTEMS_MESSAGE_CODE_SIZE x,138 +RTEMS_EVENT_CODE_SIZE x,139 +RTEMS_SIGNAL_CODE_SIZE x,140 +RTEMS_PARTITION_CODE_SIZE x,141 +RTEMS_REGION_CODE_SIZE x,142 +RTEMS_DPMEM_CODE_SIZE x,143 +RTEMS_IO_CODE_SIZE x,144 +RTEMS_FATAL_ERROR_CODE_SIZE x,145 +RTEMS_RATE_MONOTONIC_CODE_SIZE x,146 +RTEMS_MULTIPROCESSING_CODE_SIZE x,147 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 148 +RTEMS_SEMAPHORE_CODE_OPTSIZE 149 +RTEMS_MESSAGE_CODE_OPTSIZE 150 +RTEMS_EVENT_CODE_OPTSIZE 151 +RTEMS_SIGNAL_CODE_OPTSIZE 152 +RTEMS_PARTITION_CODE_OPTSIZE 153 +RTEMS_REGION_CODE_OPTSIZE 154 +RTEMS_DPMEM_CODE_OPTSIZE 155 +RTEMS_IO_CODE_OPTSIZE 156 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 157 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 158 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 159 +RTEMS_BYTES_PER_TIMER 160 +RTEMS_BYTES_PER_SEMAPHORE 161 +RTEMS_BYTES_PER_MESSAGE_QUEUE 162 +RTEMS_BYTES_PER_REGION 163 +RTEMS_BYTES_PER_PARTITION 164 +RTEMS_BYTES_PER_PORT 165 +RTEMS_BYTES_PER_PERIOD 166 +RTEMS_BYTES_PER_EXTENSION 167 +RTEMS_BYTES_PER_FP_TASK 168 +RTEMS_BYTES_PER_NODE 169 +RTEMS_BYTES_PER_GLOBAL_OBJECT 170 +RTEMS_BYTES_PER_PROXY 171 +# x,xxx alloted for numbers +RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS x,172 diff --git a/doc/supplements/hppa1_1/TIMES b/doc/supplements/hppa1_1/TIMES new file mode 100644 index 0000000000..485340715b --- /dev/null +++ b/doc/supplements/hppa1_1/TIMES @@ -0,0 +1,244 @@ +# +# PA-RISC Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL HP-7100 +# +# Interrupt Latency +# +# NOTE: In general, the text says it is hand-calculated to be +# RTEMS_MAXIMUM_DISABLE_PERIOD at RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ +# Mhz and this was last calculated for Release +# RTEMS_VERSION_FOR_MAXIMUM_DISABLE_PERIOD. +# +RTEMS_MAXIMUM_DISABLE_PERIOD TBD +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ TBD +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD TBD +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 1 +RTEMS_RESTORE_1ST_FP_TASK 2 +RTEMS_SAVE_INIT_RESTORE_INIT 3 +RTEMS_SAVE_IDLE_RESTORE_INIT 4 +RTEMS_SAVE_IDLE_RESTORE_IDLE 5 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 6 +RTEMS_TASK_IDENT_ONLY 7 +RTEMS_TASK_START_ONLY 8 +RTEMS_TASK_RESTART_CALLING_TASK 9 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 9 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 10 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 11 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 12 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 13 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 14 +RTEMS_TASK_DELETE_CALLING_TASK 15 +RTEMS_TASK_DELETE_SUSPENDED_TASK 16 +RTEMS_TASK_DELETE_BLOCKED_TASK 17 +RTEMS_TASK_DELETE_READY_TASK 18 +RTEMS_TASK_SUSPEND_CALLING_TASK 19 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 20 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 21 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 22 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 23 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 24 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 25 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 26 +RTEMS_TASK_MODE_NO_RESCHEDULE 27 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 28 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 29 +RTEMS_TASK_GET_NOTE_ONLY 30 +RTEMS_TASK_SET_NOTE_ONLY 31 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 32 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 33 +RTEMS_TASK_WAKE_WHEN_ONLY 34 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 35 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 36 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 37 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 38 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 39 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 40 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 41 +RTEMS_CLOCK_GET_ONLY 42 +RTEMS_CLOCK_TICK_ONLY 43 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 44 +RTEMS_TIMER_IDENT_ONLY 45 +RTEMS_TIMER_DELETE_INACTIVE 46 +RTEMS_TIMER_DELETE_ACTIVE 47 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 48 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 49 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 50 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 51 +RTEMS_TIMER_RESET_INACTIVE 52 +RTEMS_TIMER_RESET_ACTIVE 53 +RTEMS_TIMER_CANCEL_INACTIVE 54 +RTEMS_TIMER_CANCEL_ACTIVE 55 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 56 +RTEMS_SEMAPHORE_IDENT_ONLY 57 +RTEMS_SEMAPHORE_DELETE_ONLY 58 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 59 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 60 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 61 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 62 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 63 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 64 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 65 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 66 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 67 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 68 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 69 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 70 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 71 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 72 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 73 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 74 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 75 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 77 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 78 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 79 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 80 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 81 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 82 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 83 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 84 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 85 +RTEMS_EVENT_RECEIVE_AVAILABLE 86 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 87 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 88 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 89 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 90 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 91 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 92 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 93 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 94 +RTEMS_PARTITION_IDENT_ONLY 95 +RTEMS_PARTITION_DELETE_ONLY 96 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 97 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 98 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 99 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 100 +RTEMS_REGION_IDENT_ONLY 101 +RTEMS_REGION_DELETE_ONLY 102 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 103 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 104 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 105 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 106 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 107 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 108 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 109 +RTEMS_PORT_IDENT_ONLY 110 +RTEMS_PORT_DELETE_ONLY 111 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 112 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 113 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 114 +RTEMS_IO_OPEN_ONLY 115 +RTEMS_IO_CLOSE_ONLY 116 +RTEMS_IO_READ_ONLY 117 +RTEMS_IO_WRITE_ONLY 118 +RTEMS_IO_CONTROL_ONLY 119 +# +# Rate Monotonic Manager +# +RTEMS_RATE_MONOTONIC_CREATE_ONLY 120 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 121 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 122 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 123 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 124 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 125 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 126 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 127 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 128 +RTEMS_MINIMUM_CONFIGURATION xx,129 +RTEMS_MAXIMUM_CONFIGURATION xx,130 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE x,131 +RTEMS_INITIALIZATION_CODE_SIZE x,132 +RTEMS_TASK_CODE_SIZE x,133 +RTEMS_INTERRUPT_CODE_SIZE x,134 +RTEMS_CLOCK_CODE_SIZE x,135 +RTEMS_TIMER_CODE_SIZE x,136 +RTEMS_SEMAPHORE_CODE_SIZE x,137 +RTEMS_MESSAGE_CODE_SIZE x,138 +RTEMS_EVENT_CODE_SIZE x,139 +RTEMS_SIGNAL_CODE_SIZE x,140 +RTEMS_PARTITION_CODE_SIZE x,141 +RTEMS_REGION_CODE_SIZE x,142 +RTEMS_DPMEM_CODE_SIZE x,143 +RTEMS_IO_CODE_SIZE x,144 +RTEMS_FATAL_ERROR_CODE_SIZE x,145 +RTEMS_RATE_MONOTONIC_CODE_SIZE x,146 +RTEMS_MULTIPROCESSING_CODE_SIZE x,147 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 148 +RTEMS_SEMAPHORE_CODE_OPTSIZE 149 +RTEMS_MESSAGE_CODE_OPTSIZE 150 +RTEMS_EVENT_CODE_OPTSIZE 151 +RTEMS_SIGNAL_CODE_OPTSIZE 152 +RTEMS_PARTITION_CODE_OPTSIZE 153 +RTEMS_REGION_CODE_OPTSIZE 154 +RTEMS_DPMEM_CODE_OPTSIZE 155 +RTEMS_IO_CODE_OPTSIZE 156 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 157 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 158 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 159 +RTEMS_BYTES_PER_TIMER 160 +RTEMS_BYTES_PER_SEMAPHORE 161 +RTEMS_BYTES_PER_MESSAGE_QUEUE 162 +RTEMS_BYTES_PER_REGION 163 +RTEMS_BYTES_PER_PARTITION 164 +RTEMS_BYTES_PER_PORT 165 +RTEMS_BYTES_PER_PERIOD 166 +RTEMS_BYTES_PER_EXTENSION 167 +RTEMS_BYTES_PER_FP_TASK 168 +RTEMS_BYTES_PER_NODE 169 +RTEMS_BYTES_PER_GLOBAL_OBJECT 170 +RTEMS_BYTES_PER_PROXY 171 +# x,xxx alloted for numbers +RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS x,172 diff --git a/doc/supplements/hppa1_1/bsp.t b/doc/supplements/hppa1_1/bsp.t new file mode 100644 index 0000000000..b4b92a5bdb --- /dev/null +++ b/doc/supplements/hppa1_1/bsp.t @@ -0,0 +1,70 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of PA-RISC specific BSP +issues. For more information on developing a BSP, refer to the +chapter titled Board Support Packages in the RTEMS C +Applications User's Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated or +re-initiated when the PA-RISC processor is reset. The behavior +of a PA-RISC upon reset is implementation defined and thus is +beyond the scope of this manual. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +The precise requirements for initialization of a +particular implementation of the PA-RISC architecture are +implementation defined. Thus it is impossible to provide exact +details of this procedure in this manual. However, the +requirements of RTEMS which must be satisfied by this +initialization code can be discussed. + +RTEMS assumes that interrupts are disabled when the +initialize_executive directive is invoked. Interrupts are +enabled automatically by RTEMS as part of the initialize +executive directive and device driver initialization occurs +after interrupts are enabled. Thus all interrupt sources should +be quiescent until the system's device drivers have been +initialized and installed their interrupt handlers. + +If the processor requires initialization of the +cache, then it should be be done during the reset application +initialization code. + +Finally, the requirements in the Board Support +Packages chapter of the C Applications User's Manual for the +reset code which is executed before the call to initialize +executive must be satisfied. + + diff --git a/doc/supplements/hppa1_1/bsp.texi b/doc/supplements/hppa1_1/bsp.texi new file mode 100644 index 0000000000..b4b92a5bdb --- /dev/null +++ b/doc/supplements/hppa1_1/bsp.texi @@ -0,0 +1,70 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of PA-RISC specific BSP +issues. For more information on developing a BSP, refer to the +chapter titled Board Support Packages in the RTEMS C +Applications User's Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated or +re-initiated when the PA-RISC processor is reset. The behavior +of a PA-RISC upon reset is implementation defined and thus is +beyond the scope of this manual. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +The precise requirements for initialization of a +particular implementation of the PA-RISC architecture are +implementation defined. Thus it is impossible to provide exact +details of this procedure in this manual. However, the +requirements of RTEMS which must be satisfied by this +initialization code can be discussed. + +RTEMS assumes that interrupts are disabled when the +initialize_executive directive is invoked. Interrupts are +enabled automatically by RTEMS as part of the initialize +executive directive and device driver initialization occurs +after interrupts are enabled. Thus all interrupt sources should +be quiescent until the system's device drivers have been +initialized and installed their interrupt handlers. + +If the processor requires initialization of the +cache, then it should be be done during the reset application +initialization code. + +Finally, the requirements in the Board Support +Packages chapter of the C Applications User's Manual for the +reset code which is executed before the call to initialize +executive must be satisfied. + + diff --git a/doc/supplements/hppa1_1/callconv.t b/doc/supplements/hppa1_1/callconv.t new file mode 100644 index 0000000000..77f2b8a926 --- /dev/null +++ b/doc/supplements/hppa1_1/callconv.t @@ -0,0 +1,172 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features CPU Model Name, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Processor Background:: +* Calling Conventions Calling Mechanism:: +* Calling Conventions Register Usage:: +* Calling Conventions Parameter Passing:: +* Calling Conventions User-Provided Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Calling Conventions Introduction, Calling Conventions Processor Background, Calling Conventions, Calling Conventions +@end ifinfo +@section Introduction + +Each high-level language compiler generates +subroutine entry and exit code based upon a set of rules known +as the compiler's calling convention. These rules address the +following issues: + +@itemize @bullet +@item register preservation and usage + +@item parameter passing + +@item call and return mechanism +@end itemize + +A compiler's calling convention is of importance when +interfacing to subroutines written in another language either +assembly or high-level. Even when the high-level language and +target processor are the same, different compilers may use +different calling conventions. As a result, calling conventions +are both processor and compiler dependent. + +This chapter describes the calling conventions used +by the GNU C and standard HP-UX compilers for the PA-RISC +architecture. + +@ifinfo +@node Calling Conventions Processor Background, Calling Conventions Calling Mechanism, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Processor Background + +The PA-RISC architecture supports a simple yet +effective call and return mechanism for subroutine calls where +the caller and callee are both in the same address space. The +compiler will not automatically generate subroutine calls which +cross address spaces. A subroutine is invoked via the branch +and link (bl) or the branch and link register (blr). These +instructions save the return address in a caller specified +register. By convention, the return address is saved in r2. +The callee is responsible for maintaining the return address so +it can return to the correct address. The branch vectored (bv) +instruction is used to branch to the return address and thus +return from the subroutine to the caller. It is is important to +note that the PA-RISC subroutine call and return mechanism does +not automatically save or restore any registers. It is the +responsibility of the high-level language compiler to define the +register preservation and usage convention. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Processor Background, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked as standard +subroutines via a bl or a blr instruction with the return address +assumed to be in r2 and return to the user application via the +bv instruction. + +@ifinfo +@node Calling Conventions Register Usage, Calling Conventions Parameter Passing, Calling Conventions Calling Mechanism, Calling Conventions +@end ifinfo +@section Register Usage + +As discussed above, the bl and blr instructions do +not automatically save any registers. RTEMS uses the registers +r1, r19 - r26, and r31 as scratch registers. The PA-RISC +calling convention specifies that the first four (4) arguments +to subroutines are passed in registers r23 - r26. After the +arguments have been used, the contents of these registers may be +altered. Register r31 is the millicode scratch register. +Millicode is the set of routines which support high-level +languages on the PA-RISC by providing routines which are either +too complex or too long for the compiler to generate inline code +when these operations are needed. For example, indirect calls +utilize a millicode routine. The scratch registers are not +preserved by RTEMS directives therefore, the contents of these +registers should not be assumed upon return from any RTEMS +directive. + +Surprisingly, when using the GNU C compiler at least +integer multiplies are performed using the floating point +registers. This is an important optimization because the +PA-RISC does not have otherwise have hardware for multiplies. +This has important ramifications in regards to the PA-RISC port +of RTEMS. On most processors, the floating point unit is +ignored if the code only performs integer operations. This +makes it easy for the application developer to predict whether +or not any particular task will require floating point +operations. This property is taken advantage of by RTEMS on +other architectures to minimize the number of times the floating +point context is saved and restored. However, on the PA-RISC +architecture, every task is implicitly a floating point task. +Additionally the state of the floating point unit must be saved +and restored as part of the interrupt processing because for all +practical purposes it is impossible to avoid the use of the +floating point registers. It is unknown if the HP-UX C compiler +shares this property. + +@itemize @code{ } +@item @b{NOTE}: Later versions of the GNU C has a PA-RISC specific +option to disable use of the floating point registers. RTEMS +currently assumes that this option is not turned on. If the use +of this option sets a built-in define, then it should be +possible to modify the PA-RISC specific code such that all tasks +are considered floating point only when this option is not used. +@end itemize + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS assumes that the first four (4) arguments are +placed in the appropriate registers (r26, r25, r24, and r23) +and, if needed, additional are placed on the current stack +before the directive is invoked via the bl or blr instruction. +The first argument is placed in r26, the second is placed in +r25, and so forth. The following pseudo-code illustrates the +typical sequence used to call a RTEMS directive with three (3) +arguments: + + +@example +set r24 to the third argument +set r25 to the second argument +set r26 to the first argument +invoke directive +@end example + +The stack on the PA-RISC grows upward -- i.e. +"pushing" onto the stack results in the address in the stack +pointer becoming numerically larger. By convention, r27 is used +as the stack pointer. The standard stack frame consists of a +minimum of sixty-four (64) bytes and is the responsibility of +the callee to maintain. + +@ifinfo +@node Calling Conventions User-Provided Routines, Memory Model, Calling Conventions Parameter Passing, Calling Conventions +@end ifinfo +@section User-Provided Routines + +All user-provided routines invoked by RTEMS, such as +user extensions, device drivers, and MPCI routines, must also +adhere to these calling conventions. + + + + diff --git a/doc/supplements/hppa1_1/callconv.texi b/doc/supplements/hppa1_1/callconv.texi new file mode 100644 index 0000000000..77f2b8a926 --- /dev/null +++ b/doc/supplements/hppa1_1/callconv.texi @@ -0,0 +1,172 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features CPU Model Name, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Processor Background:: +* Calling Conventions Calling Mechanism:: +* Calling Conventions Register Usage:: +* Calling Conventions Parameter Passing:: +* Calling Conventions User-Provided Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Calling Conventions Introduction, Calling Conventions Processor Background, Calling Conventions, Calling Conventions +@end ifinfo +@section Introduction + +Each high-level language compiler generates +subroutine entry and exit code based upon a set of rules known +as the compiler's calling convention. These rules address the +following issues: + +@itemize @bullet +@item register preservation and usage + +@item parameter passing + +@item call and return mechanism +@end itemize + +A compiler's calling convention is of importance when +interfacing to subroutines written in another language either +assembly or high-level. Even when the high-level language and +target processor are the same, different compilers may use +different calling conventions. As a result, calling conventions +are both processor and compiler dependent. + +This chapter describes the calling conventions used +by the GNU C and standard HP-UX compilers for the PA-RISC +architecture. + +@ifinfo +@node Calling Conventions Processor Background, Calling Conventions Calling Mechanism, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Processor Background + +The PA-RISC architecture supports a simple yet +effective call and return mechanism for subroutine calls where +the caller and callee are both in the same address space. The +compiler will not automatically generate subroutine calls which +cross address spaces. A subroutine is invoked via the branch +and link (bl) or the branch and link register (blr). These +instructions save the return address in a caller specified +register. By convention, the return address is saved in r2. +The callee is responsible for maintaining the return address so +it can return to the correct address. The branch vectored (bv) +instruction is used to branch to the return address and thus +return from the subroutine to the caller. It is is important to +note that the PA-RISC subroutine call and return mechanism does +not automatically save or restore any registers. It is the +responsibility of the high-level language compiler to define the +register preservation and usage convention. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Processor Background, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked as standard +subroutines via a bl or a blr instruction with the return address +assumed to be in r2 and return to the user application via the +bv instruction. + +@ifinfo +@node Calling Conventions Register Usage, Calling Conventions Parameter Passing, Calling Conventions Calling Mechanism, Calling Conventions +@end ifinfo +@section Register Usage + +As discussed above, the bl and blr instructions do +not automatically save any registers. RTEMS uses the registers +r1, r19 - r26, and r31 as scratch registers. The PA-RISC +calling convention specifies that the first four (4) arguments +to subroutines are passed in registers r23 - r26. After the +arguments have been used, the contents of these registers may be +altered. Register r31 is the millicode scratch register. +Millicode is the set of routines which support high-level +languages on the PA-RISC by providing routines which are either +too complex or too long for the compiler to generate inline code +when these operations are needed. For example, indirect calls +utilize a millicode routine. The scratch registers are not +preserved by RTEMS directives therefore, the contents of these +registers should not be assumed upon return from any RTEMS +directive. + +Surprisingly, when using the GNU C compiler at least +integer multiplies are performed using the floating point +registers. This is an important optimization because the +PA-RISC does not have otherwise have hardware for multiplies. +This has important ramifications in regards to the PA-RISC port +of RTEMS. On most processors, the floating point unit is +ignored if the code only performs integer operations. This +makes it easy for the application developer to predict whether +or not any particular task will require floating point +operations. This property is taken advantage of by RTEMS on +other architectures to minimize the number of times the floating +point context is saved and restored. However, on the PA-RISC +architecture, every task is implicitly a floating point task. +Additionally the state of the floating point unit must be saved +and restored as part of the interrupt processing because for all +practical purposes it is impossible to avoid the use of the +floating point registers. It is unknown if the HP-UX C compiler +shares this property. + +@itemize @code{ } +@item @b{NOTE}: Later versions of the GNU C has a PA-RISC specific +option to disable use of the floating point registers. RTEMS +currently assumes that this option is not turned on. If the use +of this option sets a built-in define, then it should be +possible to modify the PA-RISC specific code such that all tasks +are considered floating point only when this option is not used. +@end itemize + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS assumes that the first four (4) arguments are +placed in the appropriate registers (r26, r25, r24, and r23) +and, if needed, additional are placed on the current stack +before the directive is invoked via the bl or blr instruction. +The first argument is placed in r26, the second is placed in +r25, and so forth. The following pseudo-code illustrates the +typical sequence used to call a RTEMS directive with three (3) +arguments: + + +@example +set r24 to the third argument +set r25 to the second argument +set r26 to the first argument +invoke directive +@end example + +The stack on the PA-RISC grows upward -- i.e. +"pushing" onto the stack results in the address in the stack +pointer becoming numerically larger. By convention, r27 is used +as the stack pointer. The standard stack frame consists of a +minimum of sixty-four (64) bytes and is the responsibility of +the callee to maintain. + +@ifinfo +@node Calling Conventions User-Provided Routines, Memory Model, Calling Conventions Parameter Passing, Calling Conventions +@end ifinfo +@section User-Provided Routines + +All user-provided routines invoked by RTEMS, such as +user extensions, device drivers, and MPCI routines, must also +adhere to these calling conventions. + + + + diff --git a/doc/supplements/hppa1_1/cpumodel.t b/doc/supplements/hppa1_1/cpumodel.t new file mode 100644 index 0000000000..be4541bd87 --- /dev/null +++ b/doc/supplements/hppa1_1/cpumodel.t @@ -0,0 +1,69 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node CPU Model Dependent Features, CPU Model Dependent Features Introduction, Preface, Top +@end ifinfo +@chapter CPU Model Dependent Features +@ifinfo +@menu +* CPU Model Dependent Features Introduction:: +* CPU Model Dependent Features CPU Model Name:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features, CPU Model Dependent Features +@end ifinfo +@section Introduction + +Microprocessors are generally classified into +families with a variety of CPU models or implementations within +that family. Within a processor family, there is a high level +of binary compatibility. This family may be based on either an +architectural specification or on maintaining compatibility with +a popular processor. Recent microprocessor families such as the +SPARC or PA-RISC are based on an architectural specification +which is independent or any particular CPU model or +implementation. Older families such as the M68xxx and the iX86 +evolved as the manufacturer strived to produce higher +performance processor models which maintained binary +compatibility with older models. + +RTEMS takes advantage of the similarity of the +various models within a CPU family. Although the models do vary +in significant ways, the high level of compatibility makes it +possible to share the bulk of the CPU dependent executive code +across the entire family. Each processor family supported by +RTEMS has a list of features which vary between CPU models +within a family. For example, the most common model dependent +feature regardless of CPU family is the presence or absence of a +floating point unit or coprocessor. When defining the list of +features present on a particular CPU model, one simply notes +that floating point hardware is or is not present and defines a +single constant appropriately. Conditional compilation is +utilized to include the appropriate source code for this CPU +model's feature set. It is important to note that this means +that RTEMS is thus compiled using the appropriate feature set +and compilation flags optimal for this CPU model used. The +alternative would be to generate a binary which would execute on +all family members using only the features which were always +present. + +This chapter presents the set of features which vary +across PA-RISC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/hppa1_1/hppa.h based upon the particular CPU +model defined on the compilation command line. + +@ifinfo +@node CPU Model Dependent Features CPU Model Name, Calling Conventions, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the Hewlett Packard +PA-7100 CPU model, this macro is set to the string "hppa 7100". diff --git a/doc/supplements/hppa1_1/cpumodel.texi b/doc/supplements/hppa1_1/cpumodel.texi new file mode 100644 index 0000000000..be4541bd87 --- /dev/null +++ b/doc/supplements/hppa1_1/cpumodel.texi @@ -0,0 +1,69 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node CPU Model Dependent Features, CPU Model Dependent Features Introduction, Preface, Top +@end ifinfo +@chapter CPU Model Dependent Features +@ifinfo +@menu +* CPU Model Dependent Features Introduction:: +* CPU Model Dependent Features CPU Model Name:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features, CPU Model Dependent Features +@end ifinfo +@section Introduction + +Microprocessors are generally classified into +families with a variety of CPU models or implementations within +that family. Within a processor family, there is a high level +of binary compatibility. This family may be based on either an +architectural specification or on maintaining compatibility with +a popular processor. Recent microprocessor families such as the +SPARC or PA-RISC are based on an architectural specification +which is independent or any particular CPU model or +implementation. Older families such as the M68xxx and the iX86 +evolved as the manufacturer strived to produce higher +performance processor models which maintained binary +compatibility with older models. + +RTEMS takes advantage of the similarity of the +various models within a CPU family. Although the models do vary +in significant ways, the high level of compatibility makes it +possible to share the bulk of the CPU dependent executive code +across the entire family. Each processor family supported by +RTEMS has a list of features which vary between CPU models +within a family. For example, the most common model dependent +feature regardless of CPU family is the presence or absence of a +floating point unit or coprocessor. When defining the list of +features present on a particular CPU model, one simply notes +that floating point hardware is or is not present and defines a +single constant appropriately. Conditional compilation is +utilized to include the appropriate source code for this CPU +model's feature set. It is important to note that this means +that RTEMS is thus compiled using the appropriate feature set +and compilation flags optimal for this CPU model used. The +alternative would be to generate a binary which would execute on +all family members using only the features which were always +present. + +This chapter presents the set of features which vary +across PA-RISC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/hppa1_1/hppa.h based upon the particular CPU +model defined on the compilation command line. + +@ifinfo +@node CPU Model Dependent Features CPU Model Name, Calling Conventions, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the Hewlett Packard +PA-7100 CPU model, this macro is set to the string "hppa 7100". diff --git a/doc/supplements/hppa1_1/cputable.t b/doc/supplements/hppa1_1/cputable.t new file mode 100644 index 0000000000..651dd69606 --- /dev/null +++ b/doc/supplements/hppa1_1/cputable.t @@ -0,0 +1,124 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Processor Dependent Information Table, Processor Dependent Information Table Introduction, Board Support Packages Processor Initialization, Top +@end ifinfo +@chapter Processor Dependent Information Table +@ifinfo +@menu +* Processor Dependent Information Table Introduction:: +* Processor Dependent Information Table CPU Dependent Information Table:: +@end menu +@end ifinfo + +@ifinfo +@node Processor Dependent Information Table Introduction, Processor Dependent Information Table CPU Dependent Information Table, Processor Dependent Information Table, Processor Dependent Information Table +@end ifinfo +@section Introduction + +Any highly processor dependent information required +to describe a processor to RTEMS is provided in the CPU +Dependent Information Table. This table is not required for all +processors supported by RTEMS. This chapter describes the +contents, if any, for a particular processor type. + +@ifinfo +@node Processor Dependent Information Table CPU Dependent Information Table, Memory Requirements, Processor Dependent Information Table Introduction, Processor Dependent Information Table +@end ifinfo +@section CPU Dependent Information Table + +The PA-RISC version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the PA-RISC. This +information is provided to allow RTEMS to interoperate +effectively with the BSP. The C structure definition is given +here: + +@example +typedef struct @{ + void (*pretasking_hook)( void ); + void (*predriver_hook)( void ); + void (*postdriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void * (*stack_allocate_hook)( unsigned32 ); + void (*stack_free_hook)( void * ); + /* end of fields required on all CPUs */ + + hppa_rtems_isr_entry spurious_handler; + + unsigned32 itimer_clicks_per_microsecond; /* for use by Clock driver */ +@} rtems_cpu_table; +@end example + +@table @code +@item pretasking_hook +is the address of the +user provided routine which is invoked once RTEMS initialization +is complete but before interrupts and tasking are enabled. This +field may be NULL to indicate that the hook is not utilized. + +@item predriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately before +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +but no device drivers are initialized. This field may be NULL to +indicate that the hook is not utilized. + +@item postdriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately after +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +and the device drivers are initialized. This field may be NULL +to indicate that the hook is not utilized. + +@item idle_task +is the address of the optional user +provided routine which is used as the system's IDLE task. If +this field is not NULL, then the RTEMS default IDLE task is not +used. This field may be NULL to indicate that the default IDLE +is to be used. + +@item do_zero_of_workspace +indicates whether RTEMS should +zero the Workspace as part of its initialization. If set to +TRUE, the Workspace is zeroed. Otherwise, it is not. + +@item interrupt_stack_size +is the size of the RTEMS allocated interrupt stack in bytes. +This value must be at least as large as MINIMUM_STACK_SIZE. + +@item extra_mpci_receive_server_stack +is the extra stack space allocated for the RTEMS MPCI receive server task +in bytes. The MPCI receive server may invoke nearly all directives and +may require extra stack space on some targets. + +@item stack_allocate_hook +is the address of the optional user provided routine which allocates +memory for task stacks. If this hook is not NULL, then a stack_free_hook +must be provided as well. + +@item stack_free_hook +is the address of the optional user provided routine which frees +memory for task stacks. If this hook is not NULL, then a stack_allocate_hook +must be provided as well. + +@item spurious_handler +is the address of the optional user provided routine which is invoked +when a spurious external interrupt occurs. A spurious interrupt is one +for which no handler is installed. + +@item itimer_clicks_per_microsecond +is the number of countdowns in the on-CPU timer which corresponds +to a microsecond. This is a function of the clock speed of the CPU +being used. + +@end table diff --git a/doc/supplements/hppa1_1/cputable.texi b/doc/supplements/hppa1_1/cputable.texi new file mode 100644 index 0000000000..651dd69606 --- /dev/null +++ b/doc/supplements/hppa1_1/cputable.texi @@ -0,0 +1,124 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Processor Dependent Information Table, Processor Dependent Information Table Introduction, Board Support Packages Processor Initialization, Top +@end ifinfo +@chapter Processor Dependent Information Table +@ifinfo +@menu +* Processor Dependent Information Table Introduction:: +* Processor Dependent Information Table CPU Dependent Information Table:: +@end menu +@end ifinfo + +@ifinfo +@node Processor Dependent Information Table Introduction, Processor Dependent Information Table CPU Dependent Information Table, Processor Dependent Information Table, Processor Dependent Information Table +@end ifinfo +@section Introduction + +Any highly processor dependent information required +to describe a processor to RTEMS is provided in the CPU +Dependent Information Table. This table is not required for all +processors supported by RTEMS. This chapter describes the +contents, if any, for a particular processor type. + +@ifinfo +@node Processor Dependent Information Table CPU Dependent Information Table, Memory Requirements, Processor Dependent Information Table Introduction, Processor Dependent Information Table +@end ifinfo +@section CPU Dependent Information Table + +The PA-RISC version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the PA-RISC. This +information is provided to allow RTEMS to interoperate +effectively with the BSP. The C structure definition is given +here: + +@example +typedef struct @{ + void (*pretasking_hook)( void ); + void (*predriver_hook)( void ); + void (*postdriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void * (*stack_allocate_hook)( unsigned32 ); + void (*stack_free_hook)( void * ); + /* end of fields required on all CPUs */ + + hppa_rtems_isr_entry spurious_handler; + + unsigned32 itimer_clicks_per_microsecond; /* for use by Clock driver */ +@} rtems_cpu_table; +@end example + +@table @code +@item pretasking_hook +is the address of the +user provided routine which is invoked once RTEMS initialization +is complete but before interrupts and tasking are enabled. This +field may be NULL to indicate that the hook is not utilized. + +@item predriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately before +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +but no device drivers are initialized. This field may be NULL to +indicate that the hook is not utilized. + +@item postdriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately after +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +and the device drivers are initialized. This field may be NULL +to indicate that the hook is not utilized. + +@item idle_task +is the address of the optional user +provided routine which is used as the system's IDLE task. If +this field is not NULL, then the RTEMS default IDLE task is not +used. This field may be NULL to indicate that the default IDLE +is to be used. + +@item do_zero_of_workspace +indicates whether RTEMS should +zero the Workspace as part of its initialization. If set to +TRUE, the Workspace is zeroed. Otherwise, it is not. + +@item interrupt_stack_size +is the size of the RTEMS allocated interrupt stack in bytes. +This value must be at least as large as MINIMUM_STACK_SIZE. + +@item extra_mpci_receive_server_stack +is the extra stack space allocated for the RTEMS MPCI receive server task +in bytes. The MPCI receive server may invoke nearly all directives and +may require extra stack space on some targets. + +@item stack_allocate_hook +is the address of the optional user provided routine which allocates +memory for task stacks. If this hook is not NULL, then a stack_free_hook +must be provided as well. + +@item stack_free_hook +is the address of the optional user provided routine which frees +memory for task stacks. If this hook is not NULL, then a stack_allocate_hook +must be provided as well. + +@item spurious_handler +is the address of the optional user provided routine which is invoked +when a spurious external interrupt occurs. A spurious interrupt is one +for which no handler is installed. + +@item itimer_clicks_per_microsecond +is the number of countdowns in the on-CPU timer which corresponds +to a microsecond. This is a function of the clock speed of the CPU +being used. + +@end table diff --git a/doc/supplements/hppa1_1/fatalerr.t b/doc/supplements/hppa1_1/fatalerr.t new file mode 100644 index 0000000000..3caedc2e06 --- /dev/null +++ b/doc/supplements/hppa1_1/fatalerr.t @@ -0,0 +1,45 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Default Fatal Error Processing, Default Fatal Error Processing Introduction, Interrupt Processing Disabling of Interrupts by RTEMS, Top +@end ifinfo +@chapter Default Fatal Error Processing +@ifinfo +@menu +* Default Fatal Error Processing Introduction:: +* Default Fatal Error Processing Default Fatal Error Handler Operations:: +@end menu +@end ifinfo + +@ifinfo +@node Default Fatal Error Processing Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Default Fatal Error Processing, Default Fatal Error Processing +@end ifinfo +@section Introduction + +Upon detection of a fatal error by either the +application or RTEMS the fatal error manager is invoked. The +fatal error manager will invoke a user-supplied fatal error +handler. If no user-supplied handler is configured, the RTEMS +provided default fatal error handler is invoked. If the +user-supplied fatal error handler returns to the executive the +default fatal error handler is then invoked. This chapter +describes the precise operations of the default fatal error +handler. + +@ifinfo +@node Default Fatal Error Processing Default Fatal Error Handler Operations, Board Support Packages, Default Fatal Error Processing Introduction, Default Fatal Error Processing +@end ifinfo +@section Default Fatal Error Handler Operations + +The default fatal error handler which is invoked by +the fatal_error_occurred directive when there is no user handler +configured or the user handler returns control to RTEMS. The +default fatal error handler disables processor interrupts (i.e. +sets the I bit in the PSW register to 0), places the error code +in r1, and executes a break instruction to simulate a halt +processor instruction. + diff --git a/doc/supplements/hppa1_1/fatalerr.texi b/doc/supplements/hppa1_1/fatalerr.texi new file mode 100644 index 0000000000..3caedc2e06 --- /dev/null +++ b/doc/supplements/hppa1_1/fatalerr.texi @@ -0,0 +1,45 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Default Fatal Error Processing, Default Fatal Error Processing Introduction, Interrupt Processing Disabling of Interrupts by RTEMS, Top +@end ifinfo +@chapter Default Fatal Error Processing +@ifinfo +@menu +* Default Fatal Error Processing Introduction:: +* Default Fatal Error Processing Default Fatal Error Handler Operations:: +@end menu +@end ifinfo + +@ifinfo +@node Default Fatal Error Processing Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Default Fatal Error Processing, Default Fatal Error Processing +@end ifinfo +@section Introduction + +Upon detection of a fatal error by either the +application or RTEMS the fatal error manager is invoked. The +fatal error manager will invoke a user-supplied fatal error +handler. If no user-supplied handler is configured, the RTEMS +provided default fatal error handler is invoked. If the +user-supplied fatal error handler returns to the executive the +default fatal error handler is then invoked. This chapter +describes the precise operations of the default fatal error +handler. + +@ifinfo +@node Default Fatal Error Processing Default Fatal Error Handler Operations, Board Support Packages, Default Fatal Error Processing Introduction, Default Fatal Error Processing +@end ifinfo +@section Default Fatal Error Handler Operations + +The default fatal error handler which is invoked by +the fatal_error_occurred directive when there is no user handler +configured or the user handler returns control to RTEMS. The +default fatal error handler disables processor interrupts (i.e. +sets the I bit in the PSW register to 0), places the error code +in r1, and executes a break instruction to simulate a halt +processor instruction. + diff --git a/doc/supplements/hppa1_1/hppa1_1.texi b/doc/supplements/hppa1_1/hppa1_1.texi new file mode 100644 index 0000000000..7245b31e01 --- /dev/null +++ b/doc/supplements/hppa1_1/hppa1_1.texi @@ -0,0 +1,118 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_hppa1_1 +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file for the Hewlett Packard PA-RISC C Applications Supplement +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Hewlett Packard PA-RISC C Applications Supplement (hppa1_1): +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS Hewlett Packard PA-RISC C Applications Supplement + +@setchapternewpage odd +@settitle RTEMS Hewlett Packard PA-RISC C Applications Supplement +@titlepage +@finalout + +@title RTEMS Hewlett Packard PA-RISC C Supplement +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include preface.texi +@include cpumodel.texi +@include callconv.texi +@include memmodel.texi +@include intr.texi +@include fatalerr.texi +@include bsp.texi +@include cputable.texi +@include wksheets.texi +@include ../common/timing.texi +@include timedata.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top c_hppa1_1 + +This is the online version of the RTEMS Hewlett Packard PA-RISC C +Applications Supplement. + +@menu +* Preface:: +* CPU Model Dependent Features:: +* Calling Conventions:: +* Memory Model:: +* Interrupt Processing:: +* Default Fatal Error Processing:: +* Board Support Packages:: +* Processor Dependent Information Table:: +* Memory Requirements:: +* Timing Specification:: +* HP-7100 Timing Data:: +* 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, HP-7100 Timing Data Directive Times, 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 + +@c @contents +@bye + diff --git a/doc/supplements/hppa1_1/intr.t b/doc/supplements/hppa1_1/intr.t new file mode 100644 index 0000000000..bea2a3e39e --- /dev/null +++ b/doc/supplements/hppa1_1/intr.t @@ -0,0 +1,214 @@ +@ifinfo +@node Interrupt Processing, Interrupt Processing Introduction, Memory Model Flat Memory Model, Top +@end ifinfo +@chapter Interrupt Processing +@ifinfo +@menu +* Interrupt Processing Introduction:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Interrupt Stack Frame:: +* Interrupt Processing External Interrupts and Traps:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Processing Introduction, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurence of an interrupt in their own unique fashion. In +addition, each processor type provides a control mechanism to +allow for the proper handling of an interrupt. The processor +dependent response to the interrupt modifies the current +execution state and results in a change in the execution stream. +Most processors require that an interrupt handler utilize some +special control mechanisms to return to the normal processing +stream. Although RTEMS hides many of the processor dependent +details of interrupt processing, it is important to understand +how the RTEMS interrupt manager is mapped onto the processor's +unique architecture. Discussed in this chapter are the PA-RISC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Interrupt Stack Frame, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the PA-RISC +automatically performs the following actions: + +@itemize @bullet +@item The PSW (Program Status Word) is saved in the IPSW +(Interrupt Program Status Word). + +@item The current privilege level is set to 0. + +@item The following defined bits in the PSW are set: + +@item E bit is set to the default endian bit + +@item M bit is set to 1 if the interrupt is a high-priority +machine check and 0 otherwise + +@item Q bit is set to zero thuse freezing the IIA +(Instruction Address) queues + +@item C and D bits are set to zero thus disabling all +protection and translation. + +@item I bit is set to zero this disabling all external, +powerfail, and low-priority machine check interrupts. + +@item All others bits are set to zero. + +@item General purpose registers r1, r8, r9, r16, r17, r24, and +r25 are copied to the shadow registers. + +@item Execution begins at the address given by the formula: +Interruption Vector Address + (32 * interrupt vector number). +@end itemize + +Once the processor has completed the actions it is is +required to perform for each interrupt, the RTEMS interrupt +management code (the beginning of which is stored in the +Interruption Vector Table) gains control and performs the +following actions upon each interrupt: + +@itemize @bullet +@item returns the processor to "virtual mode" thus reenabling +all code and data address translation. + +@item saves all necessary interrupt state information + +@item saves all floating point registers + +@item saves all integer registers + +@item switches the current stack to the interrupt stack + +@item dispatches to the appropriate user provided interrupt +service routine (ISR). If the ISR was installed with the +interrupt_catch directive, then it will be executed at this. +Because, the RTEMS interrupt handler saves all registers which +are not preserved according to the calling conventions and +invokes the application's ISR, the ISR can easily be written in +a high-level language. +@end itemize + +RTEMS refers to the combination of the interrupt +state information and registers saved when vectoring an +interrupt as the Interrupt Stack Frame (ISF). A nested +interrupt is processed similarly by the PA-RISC and RTEMS with +the exception that the nested interrupt occurred while executing +on the interrupt stack and, thus, the current stack need not be +switched. + +@ifinfo +@node Interrupt Processing Interrupt Stack Frame, Interrupt Processing External Interrupts and Traps, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Stack Frame + +The PA-RISC architecture does not alter the stack +while processing interrupts. However, RTEMS does save +information on the stack as part of processing an interrupt. +This following shows the format of the Interrupt Stack Frame for +the PA-RISC as defined by RTEMS: + +@example +@group + +------------------------+ + | Interrupt Context | 0xXXX + +------------------------+ + | Integer Context | 0xXXX + +------------------------+ + | Floating Point Context | 0xXXX + +------------------------+ +@end group +@end example + +@ifinfo +@node Interrupt Processing External Interrupts and Traps, Interrupt Processing Interrupt Levels, Interrupt Processing Interrupt Stack Frame, Interrupt Processing +@end ifinfo +@section External Interrupts and Traps + +In addition to the thirty-two unique interrupt +sources supported by the PA-RISC architecture, RTEMS also +supports the installation of handlers for each of the thirty-two +external interrupts supported by the PA-RISC architecture. +Except for interrupt vector 4, each of the interrupt vectors 0 +through 31 may be associated with a user-provided interrupt +handler. Interrupt vector 4 is used for external interrupts. +When an external interrupt occurs, the RTEMS external interrupt +handler is invoked and the actual interrupt source is indicated +by status bits in the EIR (External Interrupt Request) register. +The RTEMS external interrupt handler (or interrupt vector four) +examines the EIR to determine which interrupt source requires +servicing. + +RTEMS supports sixty-four interrupt vectors for the +PA-RISC. Vectors 0 through 31 map to the normal interrupt +sources while RTEMS interrupt vectors 32 through 63 are directly +associated with the external interrupt sources indicated by bits +0 through 31 in the EIR. + +The exact set of interrupt sources which are checked +for by the RTEMS external interrupt handler and the order in +which they are checked are configured by the user in the CPU +Configuration Table. If an external interrupt occurs which does +not have a handler configured, then the spurious interrupt +handler will be invoked. The spurious interrupt handler may +also be specifiec by the user in the CPU Configuration Table. + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing External Interrupts and Traps, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Two levels (enabled and disabled) of interrupt +priorities are supported by the PA-RISC architecture. Level +zero (0) indicates that interrupts are fully enabled (i.e. the I +bit of the PSW is 1). Level one (1) indicates that interrupts +are disabled (i.e. the I bit of the PSW is 0). Thirty-two +independent sources of external interrupts are supported by the +PA-RISC architecture. Each of these interrupts sources may be +individually enabled or disabled. When processor interrupts are +disabled, all sources of external interrupts are ignored. When +processor interrupts are enabled, the EIR (External Interrupt +Request) register is used to determine which sources are +currently allowed to generate interrupts. + +Although RTEMS supports 256 interrupt levels, the +PA-RISC architecture only supports two. RTEMS interrupt level 0 +indicates that interrupts are enabled and level 1 indicates that +interrupts are disabled. All other RTEMS interrupt levels are +undefined and their behavior is unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Default Fatal Error Processing, Interrupt Processing Interrupt Levels, Interrupt Processing +@end ifinfo +@section Disabling of Interrupts by RTEMS + +During the execution of directive calls, critical +sections of code may be executed. When these sections are +encountered, RTEMS disables external interrupts by setting the I +bit in the PSW to 0 before the execution of this section and +restores them to the previous level upon completion of the +section. RTEMS has been optimized to insure that interrupts are +disabled for less than XXX instructions when compiled with GNU +CC at optimization level 4. The exact execution time will vary +based on the based on the processor implementation, amount of +cache, the number of wait states for primary memory, and +processor speed present on the target board. + +Non-maskable interrupts (NMI) such as high-priority +machine checks cannot be disabled, and ISRs which execute at +this level MUST NEVER issue RTEMS system calls. If a directive +is invoked, unpredictable results may occur due to the inability +of RTEMS to protect its critical sections. However, ISRs that +make no system calls may safely execute as non-maskable +interrupts. + diff --git a/doc/supplements/hppa1_1/intr_NOTIMES.t b/doc/supplements/hppa1_1/intr_NOTIMES.t new file mode 100644 index 0000000000..bea2a3e39e --- /dev/null +++ b/doc/supplements/hppa1_1/intr_NOTIMES.t @@ -0,0 +1,214 @@ +@ifinfo +@node Interrupt Processing, Interrupt Processing Introduction, Memory Model Flat Memory Model, Top +@end ifinfo +@chapter Interrupt Processing +@ifinfo +@menu +* Interrupt Processing Introduction:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Interrupt Stack Frame:: +* Interrupt Processing External Interrupts and Traps:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Processing Introduction, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurence of an interrupt in their own unique fashion. In +addition, each processor type provides a control mechanism to +allow for the proper handling of an interrupt. The processor +dependent response to the interrupt modifies the current +execution state and results in a change in the execution stream. +Most processors require that an interrupt handler utilize some +special control mechanisms to return to the normal processing +stream. Although RTEMS hides many of the processor dependent +details of interrupt processing, it is important to understand +how the RTEMS interrupt manager is mapped onto the processor's +unique architecture. Discussed in this chapter are the PA-RISC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Interrupt Stack Frame, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the PA-RISC +automatically performs the following actions: + +@itemize @bullet +@item The PSW (Program Status Word) is saved in the IPSW +(Interrupt Program Status Word). + +@item The current privilege level is set to 0. + +@item The following defined bits in the PSW are set: + +@item E bit is set to the default endian bit + +@item M bit is set to 1 if the interrupt is a high-priority +machine check and 0 otherwise + +@item Q bit is set to zero thuse freezing the IIA +(Instruction Address) queues + +@item C and D bits are set to zero thus disabling all +protection and translation. + +@item I bit is set to zero this disabling all external, +powerfail, and low-priority machine check interrupts. + +@item All others bits are set to zero. + +@item General purpose registers r1, r8, r9, r16, r17, r24, and +r25 are copied to the shadow registers. + +@item Execution begins at the address given by the formula: +Interruption Vector Address + (32 * interrupt vector number). +@end itemize + +Once the processor has completed the actions it is is +required to perform for each interrupt, the RTEMS interrupt +management code (the beginning of which is stored in the +Interruption Vector Table) gains control and performs the +following actions upon each interrupt: + +@itemize @bullet +@item returns the processor to "virtual mode" thus reenabling +all code and data address translation. + +@item saves all necessary interrupt state information + +@item saves all floating point registers + +@item saves all integer registers + +@item switches the current stack to the interrupt stack + +@item dispatches to the appropriate user provided interrupt +service routine (ISR). If the ISR was installed with the +interrupt_catch directive, then it will be executed at this. +Because, the RTEMS interrupt handler saves all registers which +are not preserved according to the calling conventions and +invokes the application's ISR, the ISR can easily be written in +a high-level language. +@end itemize + +RTEMS refers to the combination of the interrupt +state information and registers saved when vectoring an +interrupt as the Interrupt Stack Frame (ISF). A nested +interrupt is processed similarly by the PA-RISC and RTEMS with +the exception that the nested interrupt occurred while executing +on the interrupt stack and, thus, the current stack need not be +switched. + +@ifinfo +@node Interrupt Processing Interrupt Stack Frame, Interrupt Processing External Interrupts and Traps, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Stack Frame + +The PA-RISC architecture does not alter the stack +while processing interrupts. However, RTEMS does save +information on the stack as part of processing an interrupt. +This following shows the format of the Interrupt Stack Frame for +the PA-RISC as defined by RTEMS: + +@example +@group + +------------------------+ + | Interrupt Context | 0xXXX + +------------------------+ + | Integer Context | 0xXXX + +------------------------+ + | Floating Point Context | 0xXXX + +------------------------+ +@end group +@end example + +@ifinfo +@node Interrupt Processing External Interrupts and Traps, Interrupt Processing Interrupt Levels, Interrupt Processing Interrupt Stack Frame, Interrupt Processing +@end ifinfo +@section External Interrupts and Traps + +In addition to the thirty-two unique interrupt +sources supported by the PA-RISC architecture, RTEMS also +supports the installation of handlers for each of the thirty-two +external interrupts supported by the PA-RISC architecture. +Except for interrupt vector 4, each of the interrupt vectors 0 +through 31 may be associated with a user-provided interrupt +handler. Interrupt vector 4 is used for external interrupts. +When an external interrupt occurs, the RTEMS external interrupt +handler is invoked and the actual interrupt source is indicated +by status bits in the EIR (External Interrupt Request) register. +The RTEMS external interrupt handler (or interrupt vector four) +examines the EIR to determine which interrupt source requires +servicing. + +RTEMS supports sixty-four interrupt vectors for the +PA-RISC. Vectors 0 through 31 map to the normal interrupt +sources while RTEMS interrupt vectors 32 through 63 are directly +associated with the external interrupt sources indicated by bits +0 through 31 in the EIR. + +The exact set of interrupt sources which are checked +for by the RTEMS external interrupt handler and the order in +which they are checked are configured by the user in the CPU +Configuration Table. If an external interrupt occurs which does +not have a handler configured, then the spurious interrupt +handler will be invoked. The spurious interrupt handler may +also be specifiec by the user in the CPU Configuration Table. + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing External Interrupts and Traps, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Two levels (enabled and disabled) of interrupt +priorities are supported by the PA-RISC architecture. Level +zero (0) indicates that interrupts are fully enabled (i.e. the I +bit of the PSW is 1). Level one (1) indicates that interrupts +are disabled (i.e. the I bit of the PSW is 0). Thirty-two +independent sources of external interrupts are supported by the +PA-RISC architecture. Each of these interrupts sources may be +individually enabled or disabled. When processor interrupts are +disabled, all sources of external interrupts are ignored. When +processor interrupts are enabled, the EIR (External Interrupt +Request) register is used to determine which sources are +currently allowed to generate interrupts. + +Although RTEMS supports 256 interrupt levels, the +PA-RISC architecture only supports two. RTEMS interrupt level 0 +indicates that interrupts are enabled and level 1 indicates that +interrupts are disabled. All other RTEMS interrupt levels are +undefined and their behavior is unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Default Fatal Error Processing, Interrupt Processing Interrupt Levels, Interrupt Processing +@end ifinfo +@section Disabling of Interrupts by RTEMS + +During the execution of directive calls, critical +sections of code may be executed. When these sections are +encountered, RTEMS disables external interrupts by setting the I +bit in the PSW to 0 before the execution of this section and +restores them to the previous level upon completion of the +section. RTEMS has been optimized to insure that interrupts are +disabled for less than XXX instructions when compiled with GNU +CC at optimization level 4. The exact execution time will vary +based on the based on the processor implementation, amount of +cache, the number of wait states for primary memory, and +processor speed present on the target board. + +Non-maskable interrupts (NMI) such as high-priority +machine checks cannot be disabled, and ISRs which execute at +this level MUST NEVER issue RTEMS system calls. If a directive +is invoked, unpredictable results may occur due to the inability +of RTEMS to protect its critical sections. However, ISRs that +make no system calls may safely execute as non-maskable +interrupts. + diff --git a/doc/supplements/hppa1_1/memmodel.t b/doc/supplements/hppa1_1/memmodel.t new file mode 100644 index 0000000000..8ac774de3d --- /dev/null +++ b/doc/supplements/hppa1_1/memmodel.t @@ -0,0 +1,80 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Memory Model, Memory Model Introduction, Calling Conventions User-Provided Routines, Top +@end ifinfo +@chapter Memory Model +@ifinfo +@menu +* Memory Model Introduction:: +* Memory Model Flat Memory Model:: +@end menu +@end ifinfo + +@ifinfo +@node Memory Model Introduction, Memory Model Flat Memory Model, Memory Model, Memory Model +@end ifinfo +@section Introduction + +A processor may support any combination of memory +models ranging from pure physical addressing to complex demand +paged virtual memory systems. RTEMS supports a flat memory +model which ranges contiguously over the processor's allowable +address space. RTEMS does not support segmentation or virtual +memory of any kind. The appropriate memory model for RTEMS +provided by the targeted processor and related characteristics +of that model are described in this chapter. + +@ifinfo +@node Memory Model Flat Memory Model, Interrupt Processing, Memory Model Introduction, Memory Model +@end ifinfo +@section Flat Memory Model + +RTEMS supports applications in which the application +and the executive execute within a single thirty-two bit address +space. Thus RTEMS and the application share a common four +gigabyte address space within a single space. The PA-RISC +automatically converts every address from a logical to a +physical address each time it is used. The PA-RISC uses +information provided in the page table to perform this +translation. The following protection levels are assumed: + +@itemize @bullet +@item a single code segment at protection level (0) which +contains all application and executive code. + +@item a single data segment at protection level zero (0) which +contains all application and executive data. +@end itemize + +The PA-RISC space registers and associated stack -- +including the stack pointer r27 -- must be initialized when the +initialize_executive directive is invoked. RTEMS treats the +space registers as system resources shared by all tasks and does +not modify or context switch them. + +This memory model supports a flat 32-bit address +space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4 +gigabytes). Each address is represented by a 32-bit value and +memory is addressable. The address may be used to reference a +single byte, half-word (2-bytes), or word (4 bytes). + +RTEMS does not require that logical addresses map +directly to physical addresses, although it is desirable in many +applications to do so. RTEMS does not need any additional +information when physical addresses do not map directly to +physical addresses. By not requiring that logical addresses map +directly to physical addresses, the memory space of an RTEMS +space can be separated from that of a ROM monitor. For example, +a ROM monitor may load application programs into a separate +logical address space from itself. + +RTEMS assumes that the space registers contain the +selector for the single data segment when a directive is +invoked. This assumption is especially important when +developing interrupt service routines. + diff --git a/doc/supplements/hppa1_1/memmodel.texi b/doc/supplements/hppa1_1/memmodel.texi new file mode 100644 index 0000000000..8ac774de3d --- /dev/null +++ b/doc/supplements/hppa1_1/memmodel.texi @@ -0,0 +1,80 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Memory Model, Memory Model Introduction, Calling Conventions User-Provided Routines, Top +@end ifinfo +@chapter Memory Model +@ifinfo +@menu +* Memory Model Introduction:: +* Memory Model Flat Memory Model:: +@end menu +@end ifinfo + +@ifinfo +@node Memory Model Introduction, Memory Model Flat Memory Model, Memory Model, Memory Model +@end ifinfo +@section Introduction + +A processor may support any combination of memory +models ranging from pure physical addressing to complex demand +paged virtual memory systems. RTEMS supports a flat memory +model which ranges contiguously over the processor's allowable +address space. RTEMS does not support segmentation or virtual +memory of any kind. The appropriate memory model for RTEMS +provided by the targeted processor and related characteristics +of that model are described in this chapter. + +@ifinfo +@node Memory Model Flat Memory Model, Interrupt Processing, Memory Model Introduction, Memory Model +@end ifinfo +@section Flat Memory Model + +RTEMS supports applications in which the application +and the executive execute within a single thirty-two bit address +space. Thus RTEMS and the application share a common four +gigabyte address space within a single space. The PA-RISC +automatically converts every address from a logical to a +physical address each time it is used. The PA-RISC uses +information provided in the page table to perform this +translation. The following protection levels are assumed: + +@itemize @bullet +@item a single code segment at protection level (0) which +contains all application and executive code. + +@item a single data segment at protection level zero (0) which +contains all application and executive data. +@end itemize + +The PA-RISC space registers and associated stack -- +including the stack pointer r27 -- must be initialized when the +initialize_executive directive is invoked. RTEMS treats the +space registers as system resources shared by all tasks and does +not modify or context switch them. + +This memory model supports a flat 32-bit address +space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4 +gigabytes). Each address is represented by a 32-bit value and +memory is addressable. The address may be used to reference a +single byte, half-word (2-bytes), or word (4 bytes). + +RTEMS does not require that logical addresses map +directly to physical addresses, although it is desirable in many +applications to do so. RTEMS does not need any additional +information when physical addresses do not map directly to +physical addresses. By not requiring that logical addresses map +directly to physical addresses, the memory space of an RTEMS +space can be separated from that of a ROM monitor. For example, +a ROM monitor may load application programs into a separate +logical address space from itself. + +RTEMS assumes that the space registers contain the +selector for the single data segment when a directive is +invoked. This assumption is especially important when +developing interrupt service routines. + diff --git a/doc/supplements/hppa1_1/preface.texi b/doc/supplements/hppa1_1/preface.texi new file mode 100644 index 0000000000..d93497020d --- /dev/null +++ b/doc/supplements/hppa1_1/preface.texi @@ -0,0 +1,34 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, CPU Model Dependent Features, Top, Top +@end ifinfo +@unnumbered Preface + +The Real Time Executive for Multiprocessor Systems +(RTEMS) is designed to be portable across multiple processor +architectures. However, the nature of real-time systems makes +it essential that the application designer understand certain +processor dependent implementation details. These processor +dependencies include calling convention, board support package +issues, interrupt processing, exact RTEMS memory requirements, +performance data, header files, and the assembly language +interface to the executive. + +For information on the PA-RISC V1.1 architecture in +general, refer to the following documents: + +@itemize @bullet +@item @cite{PA-RISC 1.1 Architecture and Instruction Set Reference +Manual, Third Edition. HP Part Number 09740-90039}. +@end itemize + +It is highly recommended that the PA-RISC RTEMS +application developer also obtain and become familiar with the +Technical Reference Manual for the particular implementation of +the PA-RISC being used. + diff --git a/doc/supplements/hppa1_1/timedata.t b/doc/supplements/hppa1_1/timedata.t new file mode 100644 index 0000000000..a26ce419c3 --- /dev/null +++ b/doc/supplements/hppa1_1/timedata.t @@ -0,0 +1,105 @@ +@ifinfo +@node HP-7100 Timing Data, HP-7100 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter HP-7100 Timing Data +@ifinfo +@menu +* HP-7100 Timing Data Introduction:: +* HP-7100 Timing Data Hardware Platform:: +* HP-7100 Timing Data Interrupt Latency:: +* HP-7100 Timing Data Context Switch:: +* HP-7100 Timing Data Directive Times:: +@end menu +@end ifinfo + +@ifinfo +@node HP-7100 Timing Data Introduction, HP-7100 Timing Data Hardware Platform, HP-7100 Timing Data, HP-7100 Timing Data +@end ifinfo +@section Introduction + +The timing data for the PA-RISC version of RTEMS is +provided along with the target dependent aspects concerning the +gathering of the timing data. The hardware platform used to +gather the times is described to give the reader a better +understanding of each directive time provided. Also, provided +is a description of the interrupt latency and the context +switch times as they pertain to the PA-RISC version of RTEMS. + +@ifinfo +@node HP-7100 Timing Data Hardware Platform, HP-7100 Timing Data Interrupt Latency, HP-7100 Timing Data Introduction, HP-7100 Timing Data +@end ifinfo +@section Hardware Platform + +No directive execution times are reported for the +HP-7100 because the target platform was proprietary and +executions times could not be released. + +@ifinfo +@node HP-7100 Timing Data Interrupt Latency, HP-7100 Timing Data Context Switch, HP-7100 Timing Data Hardware Platform, HP-7100 Timing Data +@end ifinfo +@section Interrupt Latency + +The maximum period with traps disabled or the +processor interrupt level set to it's highest value inside RTEMS +is less than RTEMS_MAXIMUM_DISABLE_PERIOD +microseconds including the instructions which +disable and re-enable interrupts. The time required for the +HP-7100 to vector an interrupt and for the RTEMS entry overhead +before invoking the user's trap handler are a total of +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK +microseconds. These combine to yield a worst case interrupt +latency of less than RTEMS_MAXIMUM_DISABLE_PERIOD + +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK microseconds at 15 Mhz. +[NOTE: The maximum period with interrupts disabled was last +determined for Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +It should be noted again that the maximum period with +interrupts disabled within RTEMS for the HP-7100 is hand calculated. + +@ifinfo +@node HP-7100 Timing Data Context Switch, HP-7100 Timing Data Directive Times, HP-7100 Timing Data Interrupt Latency, HP-7100 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microsections for the HP-7100 when no floating point context +switch is saved or restored. Saving and restoring the floating +point context adds additional time to the context +switch procedure. Additional execution time is required when a +TASK_SWITCH user extension is configured. The use of the +TASK_SWITCH extension is application dependent. Thus, its +execution time is not considered part of the raw context switch +time. + +Since RTEMS was designed specifically for embedded +missile applications which are floating point intensive, the +executive is optimized to avoid unnecessarily saving and +restoring the state of the numeric coprocessor. On many +processors, the state of the numeric coprocessor is only saved +when an FLOATING_POINT task is dispatched and that task was not +the last task to utilize the coprocessor. In a system with only +one FLOATING_POINT task, the state of the numeric coprocessor +will never be saved or restored. When the first FLOATING_POINT +task is dispatched, RTEMS does not need to save the current +state of the numeric coprocessor. As discussed in the Register +Usage section, on the HP-7100 the every task is considered to be +floating point registers and , as a rsule, every context switch +involves saving and restoring the state of the floating point +unit. + +The following table summarizes the context switch +times for the HP-7100 processor: + +@example +no times are available for the HP-7100 +@end example + +@ifinfo +@node HP-7100 Timing Data Directive Times, Command and Variable Index, HP-7100 Timing Data Context Switch, HP-7100 Timing Data +@end ifinfo +@section Directive Times + +No execution times are available for the HP-7100 +because the target platform was proprietary and no timing +information could be released. + diff --git a/doc/supplements/i386/FORCE386_TIMES b/doc/supplements/i386/FORCE386_TIMES new file mode 100644 index 0000000000..19959db3aa --- /dev/null +++ b/doc/supplements/i386/FORCE386_TIMES @@ -0,0 +1,244 @@ +# +# Intel i386/Force CPU-386 Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL i386 +# +# Interrupt Latency +# +# NOTE: In general, the text says it is hand-calculated to be +# RTEMS_MAXIMUM_DISABLE_PERIOD at RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ +# Mhz and this was last calculated for Release +# RTEMS_VERSION_FOR_MAXIMUM_DISABLE_PERIOD. +# +RTEMS_MAXIMUM_DISABLE_PERIOD 13.0 +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ 16 +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD 3.1.0 +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 34 +RTEMS_RESTORE_1ST_FP_TASK 57 +RTEMS_SAVE_INIT_RESTORE_INIT 59 +RTEMS_SAVE_IDLE_RESTORE_INIT 59 +RTEMS_SAVE_IDLE_RESTORE_IDLE 83 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 157 +RTEMS_TASK_IDENT_ONLY 748 +RTEMS_TASK_START_ONLY 86 +RTEMS_TASK_RESTART_CALLING_TASK 118 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 45 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 138 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 105 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 149 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 162 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 156 +RTEMS_TASK_DELETE_CALLING_TASK 187 +RTEMS_TASK_DELETE_SUSPENDED_TASK 147 +RTEMS_TASK_DELETE_BLOCKED_TASK 153 +RTEMS_TASK_DELETE_READY_TASK 157 +RTEMS_TASK_SUSPEND_CALLING_TASK 81 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 45 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 46 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 71 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 30 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 67 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 115 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 19 +RTEMS_TASK_MODE_NO_RESCHEDULE 21 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 27 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 66 +RTEMS_TASK_GET_NOTE_ONLY 32 +RTEMS_TASK_SET_NOTE_ONLY 32 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 18 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 63 +RTEMS_TASK_WAKE_WHEN_ONLY 128 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 12 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 13 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 12 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 10 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 13 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 58 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 85 +RTEMS_CLOCK_GET_ONLY 2 +RTEMS_CLOCK_TICK_ONLY 16 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 34 +RTEMS_TIMER_IDENT_ONLY 729 +RTEMS_TIMER_DELETE_INACTIVE 48 +RTEMS_TIMER_DELETE_ACTIVE 52 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 65 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 69 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 92 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 92 +RTEMS_TIMER_RESET_INACTIVE 58 +RTEMS_TIMER_RESET_ACTIVE 63 +RTEMS_TIMER_CANCEL_INACTIVE 32 +RTEMS_TIMER_CANCEL_ACTIVE 37 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 64 +RTEMS_SEMAPHORE_IDENT_ONLY 787 +RTEMS_SEMAPHORE_DELETE_ONLY 60 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 41 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 40 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 123 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 47 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 70 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 95 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 294 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 730 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 81 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 117 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 118 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 144 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 117 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 116 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 144 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 53 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 122 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 146 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 93 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 45 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 127 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 29 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 41 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 26 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 60 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 89 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS <1 +RTEMS_EVENT_RECEIVE_AVAILABLE 27 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 25 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 94 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 13 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 34 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 59 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 39 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 60 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 83 +RTEMS_PARTITION_IDENT_ONLY 730 +RTEMS_PARTITION_DELETE_ONLY 40 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 34 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 33 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 40 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 68 +RTEMS_REGION_IDENT_ONLY 739 +RTEMS_REGION_DELETE_ONLY 39 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 49 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 45 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 127 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 52 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 113 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 138 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 39 +RTEMS_PORT_IDENT_ONLY 728 +RTEMS_PORT_DELETE_ONLY 39 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 26 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 26 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 4 +RTEMS_IO_OPEN_ONLY 1 +RTEMS_IO_CLOSE_ONLY 1 +RTEMS_IO_READ_ONLY <1 +RTEMS_IO_WRITE_ONLY 1 +RTEMS_IO_CONTROL_ONLY 1 +# +# Rate Monotonic Manager +# +RTEMS_RATE_MONOTONIC_CREATE_ONLY 36 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 725 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 39 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 53 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 49 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 53 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 82 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 30 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 833 +RTEMS_MINIMUM_CONFIGURATION 22,660 +RTEMS_MAXIMUM_CONFIGURATION 39,592 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE 16,948 +RTEMS_INITIALIZATION_CODE_SIZE 916 +RTEMS_TASK_CODE_SIZE 3,436 +RTEMS_INTERRUPT_CODE_SIZE 52 +RTEMS_CLOCK_CODE_SIZE 296 +RTEMS_TIMER_CODE_SIZE 1,084 +RTEMS_SEMAPHORE_CODE_SIZE 1,500 +RTEMS_MESSAGE_CODE_SIZE 1,596 +RTEMS_EVENT_CODE_SIZE 1,036 +RTEMS_SIGNAL_CODE_SIZE 396 +RTEMS_PARTITION_CODE_SIZE 1,052 +RTEMS_REGION_CODE_SIZE 1,392 +RTEMS_DPMEM_CODE_SIZE 664 +RTEMS_IO_CODE_SIZE 676 +RTEMS_FATAL_ERROR_CODE_SIZE 20 +RTEMS_RATE_MONOTONIC_CODE_SIZE 1,132 +RTEMS_MULTIPROCESSING_CODE_SIZE 6,840 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 144 +RTEMS_SEMAPHORE_CODE_OPTSIZE 136 +RTEMS_MESSAGE_CODE_OPTSIZE 224 +RTEMS_EVENT_CODE_OPTSIZE 44 +RTEMS_SIGNAL_CODE_OPTSIZE 44 +RTEMS_PARTITION_CODE_OPTSIZE 104 +RTEMS_REGION_CODE_OPTSIZE 124 +RTEMS_DPMEM_CODE_OPTSIZE 104 +RTEMS_IO_CODE_OPTSIZE 0 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 136 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 228 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 372 +RTEMS_BYTES_PER_TIMER 68 +RTEMS_BYTES_PER_SEMAPHORE 124 +RTEMS_BYTES_PER_MESSAGE_QUEUE 148 +RTEMS_BYTES_PER_REGION 144 +RTEMS_BYTES_PER_PARTITION 56 +RTEMS_BYTES_PER_PORT 36 +RTEMS_BYTES_PER_PERIOD 36 +RTEMS_BYTES_PER_EXTENSION 64 +RTEMS_BYTES_PER_FP_TASK 108 +RTEMS_BYTES_PER_NODE 48 +RTEMS_BYTES_PER_GLOBAL_OBJECT 20 +RTEMS_BYTES_PER_PROXY 124 +# x,xxx alloted for numbers +RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS 6,768 diff --git a/doc/supplements/i386/Makefile b/doc/supplements/i386/Makefile new file mode 100644 index 0000000000..e24c227cd5 --- /dev/null +++ b/doc/supplements/i386/Makefile @@ -0,0 +1,88 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=i386 +REPLACE=../tools/word-replace + +all: + +COMMON_FILES=../common/cpright.texi ../common/setup.texi \ + ../common/timing.texi + +FILES= $(PROJECT).texi \ + bsp.texi callconv.texi cpumodel.texi cputable.texi fatalerr.texi \ + intr.texi memmodel.texi preface.texi timetbl.texi timedata.texi wksheets.texi + +all: + +info: c_i386 + cp c_$(PROJECT) c_$(PROJECT)-* $(INFO_INSTALL) + +c_i386: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f c_i386 + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(PROJECT).dvi + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +replace: timedata.texi + +intr.texi: intr.t FORCE386_TIMES + ${REPLACE} -p FORCE386_TIMES intr.t + mv intr.t.fixed intr.texi + +timetbl.t: ../common/timetbl.t + sed -e 's/TIMETABLE_NEXT_LINK/Command and Variable Index/' \ + <../common/timetbl.t >timetbl.t + +timetbl.texi: timetbl.t FORCE386_TIMES + ${REPLACE} -p FORCE386_TIMES timetbl.t + mv timetbl.t.fixed timetbl.texi + +timedata.texi: timedata.t FORCE386_TIMES + ${REPLACE} -p FORCE386_TIMES timedata.t + mv timedata.t.fixed timedata.texi + +wksheets.t: ../common/wksheets.t + sed -e 's/WORKSHEETS_PREVIOUS_LINK/Processor Dependent Information Table CPU Dependent Information Table/' \ + -e 's/WORKSHEETS_NEXT_LINK/i386 Timing Data/' \ + <../common/wksheets.t >wksheets.t + +wksheets.texi: wksheets.t FORCE386_TIMES + ${REPLACE} -p FORCE386_TIMES wksheets.t + mv wksheets.t.fixed wksheets.texi + +html: $(FILES) + -mkdir $(WWW_INSTALL)/c_i386 + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/c_$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(PROJECT) $(PROJECT)-* + rm -f c_i386 c_i386-* + rm -f timedata.texi timetbl.texi intr.texi wksheets.texi + rm -f timetbl.t wksheets.t + rm -f *.fixed _* + diff --git a/doc/supplements/i386/bsp.t b/doc/supplements/i386/bsp.t new file mode 100644 index 0000000000..110d155154 --- /dev/null +++ b/doc/supplements/i386/bsp.t @@ -0,0 +1,110 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of i386 specific BSP issues. +For more information on developing a BSP, refer to the chapter +titled Board Support Packages in the RTEMS C Applications User's +Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated when the i386 +processor is reset. When the i386 is reset, + +@itemize @bullet +@item The EAX register is set to indicate the results of the +processor's power-up self test. If the self-test was not +executed, the contents of this register are undefined. +Otherwise, a non-zero value indicates the processor is faulty +and a zero value indicates a successful self-test. + +@item The DX register holds a component identifier and +revision level. DH contains 3 to indicate an i386 component and +DL contains a unique revision level indicator. + +@item Control register zero (CR0) is set such that the +processor is in real mode with paging disabled. Other portions +of CR0 are used to indicate the presence of a numeric +coprocessor. + +@item All bits in the extended flags register (EFLAG) which +are not permanently set are cleared. This inhibits all maskable +interrupts. + +@item The Interrupt Descriptor Register (IDTR) is set to point +at address zero. + +@item All segment registers are set to zero. + +@item The instruction pointer is set to 0x0000FFF0. The +first instruction executed after a reset is actually at +0xFFFFFFF0 because the i386 asserts the upper twelve address +until the first intersegment (FAR) JMP or CALL instruction. +When a JMP or CALL is executed, the upper twelve address lines +are lowered and the processor begins executing in the first +megabyte of memory. +@end itemize + +Typically, an intersegment JMP to the application's +initialization code is placed at address 0xFFFFFFF0. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +This initialization code is responsible for +initializing all data structures required by the i386 in +protected mode and for actually entering protected mode. The +i386 must be placed in protected mode and the segment registers +and associated selectors must be initialized before the +initialize_executive directive is invoked. + +The initialization code is responsible for +initializing the Global Descriptor Table such that the i386 is +in the thirty-two bit flat memory model with paging disabled. +In this mode, the i386 automatically converts every address from +a logical to a physical address each time it is used. For more +information on the memory model used by RTEMS, please refer to +the Memory Model chapter in this document. + +If the application requires that the IDTR be some +value besides zero, then it should set it to the required value +at this point. All tasks share the same i386 IDTR value. +Because interrupts are enabled automatically by RTEMS as part of +the initialize_executive directive, the IDTR MUST be set +properly before this directive is invoked to insure correct +interrupt vectoring. If processor caching is to be utilized, +then it should be enabled during the reset application +initialization code. The reset code which is executed before +the call to initialize_executive has the following requirements: + +For more information regarding the i386s data +structures and their contents, refer to Intel's 386 +Programmer's Reference Manual. + diff --git a/doc/supplements/i386/bsp.texi b/doc/supplements/i386/bsp.texi new file mode 100644 index 0000000000..110d155154 --- /dev/null +++ b/doc/supplements/i386/bsp.texi @@ -0,0 +1,110 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of i386 specific BSP issues. +For more information on developing a BSP, refer to the chapter +titled Board Support Packages in the RTEMS C Applications User's +Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated when the i386 +processor is reset. When the i386 is reset, + +@itemize @bullet +@item The EAX register is set to indicate the results of the +processor's power-up self test. If the self-test was not +executed, the contents of this register are undefined. +Otherwise, a non-zero value indicates the processor is faulty +and a zero value indicates a successful self-test. + +@item The DX register holds a component identifier and +revision level. DH contains 3 to indicate an i386 component and +DL contains a unique revision level indicator. + +@item Control register zero (CR0) is set such that the +processor is in real mode with paging disabled. Other portions +of CR0 are used to indicate the presence of a numeric +coprocessor. + +@item All bits in the extended flags register (EFLAG) which +are not permanently set are cleared. This inhibits all maskable +interrupts. + +@item The Interrupt Descriptor Register (IDTR) is set to point +at address zero. + +@item All segment registers are set to zero. + +@item The instruction pointer is set to 0x0000FFF0. The +first instruction executed after a reset is actually at +0xFFFFFFF0 because the i386 asserts the upper twelve address +until the first intersegment (FAR) JMP or CALL instruction. +When a JMP or CALL is executed, the upper twelve address lines +are lowered and the processor begins executing in the first +megabyte of memory. +@end itemize + +Typically, an intersegment JMP to the application's +initialization code is placed at address 0xFFFFFFF0. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +This initialization code is responsible for +initializing all data structures required by the i386 in +protected mode and for actually entering protected mode. The +i386 must be placed in protected mode and the segment registers +and associated selectors must be initialized before the +initialize_executive directive is invoked. + +The initialization code is responsible for +initializing the Global Descriptor Table such that the i386 is +in the thirty-two bit flat memory model with paging disabled. +In this mode, the i386 automatically converts every address from +a logical to a physical address each time it is used. For more +information on the memory model used by RTEMS, please refer to +the Memory Model chapter in this document. + +If the application requires that the IDTR be some +value besides zero, then it should set it to the required value +at this point. All tasks share the same i386 IDTR value. +Because interrupts are enabled automatically by RTEMS as part of +the initialize_executive directive, the IDTR MUST be set +properly before this directive is invoked to insure correct +interrupt vectoring. If processor caching is to be utilized, +then it should be enabled during the reset application +initialization code. The reset code which is executed before +the call to initialize_executive has the following requirements: + +For more information regarding the i386s data +structures and their contents, refer to Intel's 386 +Programmer's Reference Manual. + diff --git a/doc/supplements/i386/callconv.t b/doc/supplements/i386/callconv.t new file mode 100644 index 0000000000..6d58ba2f7b --- /dev/null +++ b/doc/supplements/i386/callconv.t @@ -0,0 +1,119 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features Floating Point Unit, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Processor Background:: +* Calling Conventions Calling Mechanism:: +* Calling Conventions Register Usage:: +* Calling Conventions Parameter Passing:: +* Calling Conventions User-Provided Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Calling Conventions Introduction, Calling Conventions Processor Background, Calling Conventions, Calling Conventions +@end ifinfo +@section Introduction + +Each high-level language compiler generates +subroutine entry and exit code based upon a set of rules known +as the compiler's calling convention. These rules address the +following issues: + +@itemize @bullet +@item register preservation and usage + +@item parameter passing + +@item call and return mechanism +@end itemize + +A compiler's calling convention is of importance when +interfacing to subroutines written in another language either +assembly or high-level. Even when the high-level language and +target processor are the same, different compilers may use +different calling conventions. As a result, calling conventions +are both processor and compiler dependent. + +@ifinfo +@node Calling Conventions Processor Background, Calling Conventions Calling Mechanism, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Processor Background + +The i386 architecture supports a simple yet effective +call and return mechanism. A subroutine is invoked via the call +(call) instruction. This instruction pushes the return address +on the stack. The return from subroutine (ret) instruction pops +the return address off the current stack and transfers control +to that instruction. It is is important to note that the i386 +call and return mechanism does not automatically save or restore +any registers. It is the responsibility of the high-level +language compiler to define the register preservation and usage +convention. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Processor Background, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked using a call +instruction and return to the user application via the ret +instruction. + +@ifinfo +@node Calling Conventions Register Usage, Calling Conventions Parameter Passing, Calling Conventions Calling Mechanism, Calling Conventions +@end ifinfo +@section Register Usage + +As discussed above, the call instruction does not +automatically save any registers. RTEMS uses the registers EAX, +ECX, and EDX as scratch registers. These registers are not +preserved by RTEMS directives therefore, the contents of these +registers should not be assumed upon return from any RTEMS +directive. + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS assumes that arguments are placed on the +current stack before the directive is invoked via the call +instruction. The first argument is assumed to be closest to the +return address on the stack. This means that the first argument +of the C calling sequence is pushed last. The following +pseudo-code illustrates the typical sequence used to call a +RTEMS directive with three (3) arguments: + +@example +push third argument +push second argument +push first argument +invoke directive +remove arguments from the stack +@end example + +The arguments to RTEMS are typically pushed onto the +stack using a push instruction. These arguments must be removed +from the stack after control is returned to the caller. This +removal is typically accomplished by adding the size of the +argument list in bytes to the stack pointer. + +@ifinfo +@node Calling Conventions User-Provided Routines, Memory Model, Calling Conventions Parameter Passing, Calling Conventions +@end ifinfo +@section User-Provided Routines + +All user-provided routines invoked by RTEMS, such as +user extensions, device drivers, and MPCI routines, must also +adhere to these calling conventions. + diff --git a/doc/supplements/i386/callconv.texi b/doc/supplements/i386/callconv.texi new file mode 100644 index 0000000000..6d58ba2f7b --- /dev/null +++ b/doc/supplements/i386/callconv.texi @@ -0,0 +1,119 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features Floating Point Unit, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Processor Background:: +* Calling Conventions Calling Mechanism:: +* Calling Conventions Register Usage:: +* Calling Conventions Parameter Passing:: +* Calling Conventions User-Provided Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Calling Conventions Introduction, Calling Conventions Processor Background, Calling Conventions, Calling Conventions +@end ifinfo +@section Introduction + +Each high-level language compiler generates +subroutine entry and exit code based upon a set of rules known +as the compiler's calling convention. These rules address the +following issues: + +@itemize @bullet +@item register preservation and usage + +@item parameter passing + +@item call and return mechanism +@end itemize + +A compiler's calling convention is of importance when +interfacing to subroutines written in another language either +assembly or high-level. Even when the high-level language and +target processor are the same, different compilers may use +different calling conventions. As a result, calling conventions +are both processor and compiler dependent. + +@ifinfo +@node Calling Conventions Processor Background, Calling Conventions Calling Mechanism, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Processor Background + +The i386 architecture supports a simple yet effective +call and return mechanism. A subroutine is invoked via the call +(call) instruction. This instruction pushes the return address +on the stack. The return from subroutine (ret) instruction pops +the return address off the current stack and transfers control +to that instruction. It is is important to note that the i386 +call and return mechanism does not automatically save or restore +any registers. It is the responsibility of the high-level +language compiler to define the register preservation and usage +convention. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Processor Background, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked using a call +instruction and return to the user application via the ret +instruction. + +@ifinfo +@node Calling Conventions Register Usage, Calling Conventions Parameter Passing, Calling Conventions Calling Mechanism, Calling Conventions +@end ifinfo +@section Register Usage + +As discussed above, the call instruction does not +automatically save any registers. RTEMS uses the registers EAX, +ECX, and EDX as scratch registers. These registers are not +preserved by RTEMS directives therefore, the contents of these +registers should not be assumed upon return from any RTEMS +directive. + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS assumes that arguments are placed on the +current stack before the directive is invoked via the call +instruction. The first argument is assumed to be closest to the +return address on the stack. This means that the first argument +of the C calling sequence is pushed last. The following +pseudo-code illustrates the typical sequence used to call a +RTEMS directive with three (3) arguments: + +@example +push third argument +push second argument +push first argument +invoke directive +remove arguments from the stack +@end example + +The arguments to RTEMS are typically pushed onto the +stack using a push instruction. These arguments must be removed +from the stack after control is returned to the caller. This +removal is typically accomplished by adding the size of the +argument list in bytes to the stack pointer. + +@ifinfo +@node Calling Conventions User-Provided Routines, Memory Model, Calling Conventions Parameter Passing, Calling Conventions +@end ifinfo +@section User-Provided Routines + +All user-provided routines invoked by RTEMS, such as +user extensions, device drivers, and MPCI routines, must also +adhere to these calling conventions. + diff --git a/doc/supplements/i386/cpumodel.t b/doc/supplements/i386/cpumodel.t new file mode 100644 index 0000000000..4504572dca --- /dev/null +++ b/doc/supplements/i386/cpumodel.t @@ -0,0 +1,81 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node CPU Model Dependent Features, CPU Model Dependent Features Introduction, Preface, Top +@end ifinfo +@chapter CPU Model Dependent Features +@ifinfo +@menu +* CPU Model Dependent Features Introduction:: +* CPU Model Dependent Features CPU Model Name:: +* CPU Model Dependent Features Floating Point Unit:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features, CPU Model Dependent Features +@end ifinfo +@section Introduction + +Microprocessors are generally classified into +families with a variety of CPU models or implementations within +that family. Within a processor family, there is a high level +of binary compatibility. This family may be based on either an +architectural specification or on maintaining compatibility with +a popular processor. Recent microprocessor families such as the +SPARC or PA-RISC are based on an architectural specification +which is independent or any particular CPU model or +implementation. Older families such as the M68xxx and the iX86 +evolved as the manufacturer strived to produce higher +performance processor models which maintained binary +compatibility with older models. + +RTEMS takes advantage of the similarity of the +various models within a CPU family. Although the models do vary +in significant ways, the high level of compatibility makes it +possible to share the bulk of the CPU dependent executive code +across the entire family. Each processor family supported by +RTEMS has a list of features which vary between CPU models +within a family. For example, the most common model dependent +feature regardless of CPU family is the presence or absence of a +floating point unit or coprocessor. When defining the list of +features present on a particular CPU model, one simply notes +that floating point hardware is or is not present and defines a +single constant appropriately. Conditional compilation is +utilized to include the appropriate source code for this CPU +model's feature set. It is important to note that this means +that RTEMS is thus compiled using the appropriate feature set +and compilation flags optimal for this CPU model used. The +alternative would be to generate a binary which would execute on +all family members using only the features which were always +present. + +This chapter presents the set of features which vary +across i386 implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/i386/i386.h based upon the particular CPU +model defined on the compilation command line. + +@ifinfo +@node CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the Intel i386 without an +i387 coprocessor, this macro is set to the string "i386 with i387". + +@ifinfo +@node CPU Model Dependent Features Floating Point Unit, Calling Conventions, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features +@end ifinfo +@section Floating Point Unit + +The macro I386_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. The hardware floating point may be on-chip (as in the +case of an i486DX or Pentium) or as a coprocessor (as in the case of +an i386/i387 combination). diff --git a/doc/supplements/i386/cpumodel.texi b/doc/supplements/i386/cpumodel.texi new file mode 100644 index 0000000000..4504572dca --- /dev/null +++ b/doc/supplements/i386/cpumodel.texi @@ -0,0 +1,81 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node CPU Model Dependent Features, CPU Model Dependent Features Introduction, Preface, Top +@end ifinfo +@chapter CPU Model Dependent Features +@ifinfo +@menu +* CPU Model Dependent Features Introduction:: +* CPU Model Dependent Features CPU Model Name:: +* CPU Model Dependent Features Floating Point Unit:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features, CPU Model Dependent Features +@end ifinfo +@section Introduction + +Microprocessors are generally classified into +families with a variety of CPU models or implementations within +that family. Within a processor family, there is a high level +of binary compatibility. This family may be based on either an +architectural specification or on maintaining compatibility with +a popular processor. Recent microprocessor families such as the +SPARC or PA-RISC are based on an architectural specification +which is independent or any particular CPU model or +implementation. Older families such as the M68xxx and the iX86 +evolved as the manufacturer strived to produce higher +performance processor models which maintained binary +compatibility with older models. + +RTEMS takes advantage of the similarity of the +various models within a CPU family. Although the models do vary +in significant ways, the high level of compatibility makes it +possible to share the bulk of the CPU dependent executive code +across the entire family. Each processor family supported by +RTEMS has a list of features which vary between CPU models +within a family. For example, the most common model dependent +feature regardless of CPU family is the presence or absence of a +floating point unit or coprocessor. When defining the list of +features present on a particular CPU model, one simply notes +that floating point hardware is or is not present and defines a +single constant appropriately. Conditional compilation is +utilized to include the appropriate source code for this CPU +model's feature set. It is important to note that this means +that RTEMS is thus compiled using the appropriate feature set +and compilation flags optimal for this CPU model used. The +alternative would be to generate a binary which would execute on +all family members using only the features which were always +present. + +This chapter presents the set of features which vary +across i386 implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/i386/i386.h based upon the particular CPU +model defined on the compilation command line. + +@ifinfo +@node CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the Intel i386 without an +i387 coprocessor, this macro is set to the string "i386 with i387". + +@ifinfo +@node CPU Model Dependent Features Floating Point Unit, Calling Conventions, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features +@end ifinfo +@section Floating Point Unit + +The macro I386_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. The hardware floating point may be on-chip (as in the +case of an i486DX or Pentium) or as a coprocessor (as in the case of +an i386/i387 combination). diff --git a/doc/supplements/i386/cputable.t b/doc/supplements/i386/cputable.t new file mode 100644 index 0000000000..aea8db223e --- /dev/null +++ b/doc/supplements/i386/cputable.t @@ -0,0 +1,126 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Processor Dependent Information Table, Processor Dependent Information Table Introduction, Board Support Packages Processor Initialization, Top +@end ifinfo +@chapter Processor Dependent Information Table +@ifinfo +@menu +* Processor Dependent Information Table Introduction:: +* Processor Dependent Information Table CPU Dependent Information Table:: +@end menu +@end ifinfo + +@ifinfo +@node Processor Dependent Information Table Introduction, Processor Dependent Information Table CPU Dependent Information Table, Processor Dependent Information Table, Processor Dependent Information Table +@end ifinfo +@section Introduction + +Any highly processor dependent information required +to describe a processor to RTEMS is provided in the CPU +Dependent Information Table. This table is not required for all +processors supported by RTEMS. This chapter describes the +contents, if any, for a particular processor type. + +@ifinfo +@node Processor Dependent Information Table CPU Dependent Information Table, Memory Requirements, Processor Dependent Information Table Introduction, Processor Dependent Information Table +@end ifinfo +@section CPU Dependent Information Table + +The i386 version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the i386. This information +is provided to allow RTEMS to interoperate effectively with the +BSP. The C structure definition is given here: + +@example +struct cpu_configuration_table @{ + void (*pretasking_hook)( void ); + void (*predriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void * (*stack_allocate_hook)( unsigned32 ); + void (*stack_free_hook)( void* ); + /* end of fields required on all CPUs */ + + unsigned32 interrupt_segment; + void *interrupt_vector_table; +@}; +@end example + +@table @code +@item pretasking_hook +is the address of the +user provided routine which is invoked once RTEMS initialization +is complete but before interrupts and tasking are enabled. This +field may be NULL to indicate that the hook is not utilized. + +@item predriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately before +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +but no device drivers are initialized. This field may be NULL to +indicate that the hook is not utilized. + +@item postdriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately after +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +and the device drivers are initialized. This field may be NULL +to indicate that the hook is not utilized. + +@item idle_task +is the address of the optional user +provided routine which is used as the system's IDLE task. If +this field is not NULL, then the RTEMS default IDLE task is not +used. This field may be NULL to indicate that the default IDLE +is to be used. + +@item do_zero_of_workspace +indicates whether RTEMS should +zero the Workspace as part of its initialization. If set to +TRUE, the Workspace is zeroed. Otherwise, it is not. + +@item interrupt_stack_size +is the size of the RTEMS +allocated interrupt stack in bytes. This value must be at least +as large as MINIMUM_STACK_SIZE. + +@item extra_mpci_receive_server_stack +is the extra stack space allocated for the RTEMS MPCI receive server task +in bytes. The MPCI receive server may invoke nearly all directives and +may require extra stack space on some targets. + +@item stack_allocate_hook +is the address of the optional user provided routine which allocates +memory for task stacks. If this hook is not NULL, then a stack_free_hook +must be provided as well. + +@item stack_free_hook +is the address of the optional user provided routine which frees +memory for task stacks. If this hook is not NULL, then a stack_allocate_hook +must be provided as well. + +@item interrupt_segment +is the value of the selector which should be placed in a segment +register to access the Interrupt Descriptor Table. + +@item interrupt_vector_table +is the base address of the Interrupt Descriptor Table relative to the +interrupt_segment. + +@end table + +The contents of the i386 Interrupt Descriptor Table +are discussed in Intel's i386 User's Manual. Structure +definitions for the i386 IDT is provided by including the file +rtems.h. + diff --git a/doc/supplements/i386/cputable.texi b/doc/supplements/i386/cputable.texi new file mode 100644 index 0000000000..aea8db223e --- /dev/null +++ b/doc/supplements/i386/cputable.texi @@ -0,0 +1,126 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Processor Dependent Information Table, Processor Dependent Information Table Introduction, Board Support Packages Processor Initialization, Top +@end ifinfo +@chapter Processor Dependent Information Table +@ifinfo +@menu +* Processor Dependent Information Table Introduction:: +* Processor Dependent Information Table CPU Dependent Information Table:: +@end menu +@end ifinfo + +@ifinfo +@node Processor Dependent Information Table Introduction, Processor Dependent Information Table CPU Dependent Information Table, Processor Dependent Information Table, Processor Dependent Information Table +@end ifinfo +@section Introduction + +Any highly processor dependent information required +to describe a processor to RTEMS is provided in the CPU +Dependent Information Table. This table is not required for all +processors supported by RTEMS. This chapter describes the +contents, if any, for a particular processor type. + +@ifinfo +@node Processor Dependent Information Table CPU Dependent Information Table, Memory Requirements, Processor Dependent Information Table Introduction, Processor Dependent Information Table +@end ifinfo +@section CPU Dependent Information Table + +The i386 version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the i386. This information +is provided to allow RTEMS to interoperate effectively with the +BSP. The C structure definition is given here: + +@example +struct cpu_configuration_table @{ + void (*pretasking_hook)( void ); + void (*predriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void * (*stack_allocate_hook)( unsigned32 ); + void (*stack_free_hook)( void* ); + /* end of fields required on all CPUs */ + + unsigned32 interrupt_segment; + void *interrupt_vector_table; +@}; +@end example + +@table @code +@item pretasking_hook +is the address of the +user provided routine which is invoked once RTEMS initialization +is complete but before interrupts and tasking are enabled. This +field may be NULL to indicate that the hook is not utilized. + +@item predriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately before +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +but no device drivers are initialized. This field may be NULL to +indicate that the hook is not utilized. + +@item postdriver_hook +is the address of the user provided +routine which is invoked with tasking enabled immediately after +the MPCI and device drivers are initialized. RTEMS +initialization is complete, interrupts and tasking are enabled, +and the device drivers are initialized. This field may be NULL +to indicate that the hook is not utilized. + +@item idle_task +is the address of the optional user +provided routine which is used as the system's IDLE task. If +this field is not NULL, then the RTEMS default IDLE task is not +used. This field may be NULL to indicate that the default IDLE +is to be used. + +@item do_zero_of_workspace +indicates whether RTEMS should +zero the Workspace as part of its initialization. If set to +TRUE, the Workspace is zeroed. Otherwise, it is not. + +@item interrupt_stack_size +is the size of the RTEMS +allocated interrupt stack in bytes. This value must be at least +as large as MINIMUM_STACK_SIZE. + +@item extra_mpci_receive_server_stack +is the extra stack space allocated for the RTEMS MPCI receive server task +in bytes. The MPCI receive server may invoke nearly all directives and +may require extra stack space on some targets. + +@item stack_allocate_hook +is the address of the optional user provided routine which allocates +memory for task stacks. If this hook is not NULL, then a stack_free_hook +must be provided as well. + +@item stack_free_hook +is the address of the optional user provided routine which frees +memory for task stacks. If this hook is not NULL, then a stack_allocate_hook +must be provided as well. + +@item interrupt_segment +is the value of the selector which should be placed in a segment +register to access the Interrupt Descriptor Table. + +@item interrupt_vector_table +is the base address of the Interrupt Descriptor Table relative to the +interrupt_segment. + +@end table + +The contents of the i386 Interrupt Descriptor Table +are discussed in Intel's i386 User's Manual. Structure +definitions for the i386 IDT is provided by including the file +rtems.h. + diff --git a/doc/supplements/i386/fatalerr.t b/doc/supplements/i386/fatalerr.t new file mode 100644 index 0000000000..2743eb9a05 --- /dev/null +++ b/doc/supplements/i386/fatalerr.t @@ -0,0 +1,44 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Default Fatal Error Processing, Default Fatal Error Processing Introduction, Interrupt Processing Interrupt Stack, Top +@end ifinfo +@chapter Default Fatal Error Processing +@ifinfo +@menu +* Default Fatal Error Processing Introduction:: +* Default Fatal Error Processing Default Fatal Error Handler Operations:: +@end menu +@end ifinfo + +@ifinfo +@node Default Fatal Error Processing Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Default Fatal Error Processing, Default Fatal Error Processing +@end ifinfo +@section Introduction + +Upon detection of a fatal error by either the +application or RTEMS the fatal error manager is invoked. The +fatal error manager will invoke the user-supplied fatal error +handlers. If no user-supplied handlers are configured, the +RTEMS provided default fatal error handler is invoked. If the +user-supplied fatal error handlers return to the executive the +default fatal error handler is then invoked. This chapter +describes the precise operations of the default fatal error +handler. + +@ifinfo +@node Default Fatal Error Processing Default Fatal Error Handler Operations, Board Support Packages, Default Fatal Error Processing Introduction, Default Fatal Error Processing +@end ifinfo +@section Default Fatal Error Handler Operations + +The default fatal error handler which is invoked by +the fatal_error_occurred directive when there is no user handler +configured or the user handler returns control to RTEMS. The +default fatal error handler disables processor interrupts, +places the error code in EAX, and executes a HLT instruction to +halt the processor. + diff --git a/doc/supplements/i386/fatalerr.texi b/doc/supplements/i386/fatalerr.texi new file mode 100644 index 0000000000..2743eb9a05 --- /dev/null +++ b/doc/supplements/i386/fatalerr.texi @@ -0,0 +1,44 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Default Fatal Error Processing, Default Fatal Error Processing Introduction, Interrupt Processing Interrupt Stack, Top +@end ifinfo +@chapter Default Fatal Error Processing +@ifinfo +@menu +* Default Fatal Error Processing Introduction:: +* Default Fatal Error Processing Default Fatal Error Handler Operations:: +@end menu +@end ifinfo + +@ifinfo +@node Default Fatal Error Processing Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Default Fatal Error Processing, Default Fatal Error Processing +@end ifinfo +@section Introduction + +Upon detection of a fatal error by either the +application or RTEMS the fatal error manager is invoked. The +fatal error manager will invoke the user-supplied fatal error +handlers. If no user-supplied handlers are configured, the +RTEMS provided default fatal error handler is invoked. If the +user-supplied fatal error handlers return to the executive the +default fatal error handler is then invoked. This chapter +describes the precise operations of the default fatal error +handler. + +@ifinfo +@node Default Fatal Error Processing Default Fatal Error Handler Operations, Board Support Packages, Default Fatal Error Processing Introduction, Default Fatal Error Processing +@end ifinfo +@section Default Fatal Error Handler Operations + +The default fatal error handler which is invoked by +the fatal_error_occurred directive when there is no user handler +configured or the user handler returns control to RTEMS. The +default fatal error handler disables processor interrupts, +places the error code in EAX, and executes a HLT instruction to +halt the processor. + diff --git a/doc/supplements/i386/i386.texi b/doc/supplements/i386/i386.texi new file mode 100644 index 0000000000..8f0be73fda --- /dev/null +++ b/doc/supplements/i386/i386.texi @@ -0,0 +1,123 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_i386 +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file for the Intel i386 C Applications Supplement +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Intel i386 C Applications Supplement (i386): +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS Intel i386 C Applications Supplement + +@setchapternewpage odd +@settitle RTEMS Intel i386 C Applications Supplement +@titlepage +@finalout + +@title RTEMS Intel i386 C Supplement +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@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. + +@include preface.texi +@include cpumodel.texi +@include callconv.texi +@include memmodel.texi +@include intr.texi +@include fatalerr.texi +@include bsp.texi +@include cputable.texi +@include wksheets.texi +@include ../common/timing.texi +@include timedata.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top c_i386 + +This is the online version of the RTEMS Intel i386 C +Applications Supplement. + +@menu +* Preface:: +* CPU Model Dependent Features:: +* Calling Conventions:: +* Memory Model:: +* Interrupt Processing:: +* Default Fatal Error Processing:: +* Board Support Packages:: +* Processor Dependent Information Table:: +* Memory Requirements:: +* Timing Specification:: +* i386 Timing Data:: +* 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, i386 Timing Data Rate Monotonic Manager, 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 + +@c @contents +@bye + diff --git a/doc/supplements/i386/intr.t b/doc/supplements/i386/intr.t new file mode 100644 index 0000000000..5c36183970 --- /dev/null +++ b/doc/supplements/i386/intr.t @@ -0,0 +1,191 @@ +@ifinfo +@node Interrupt Processing, Interrupt Processing Introduction, Memory Model Flat Memory Model, Top +@end ifinfo +@chapter Interrupt Processing +@ifinfo +@menu +* Interrupt Processing Introduction:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Interrupt Stack Frame:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +* Interrupt Processing Interrupt Stack:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Processing Introduction, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurrence of an interrupt in their own unique fashion. In +addition, each processor type provides a control mechanism to +allow the proper handling of an interrupt. The processor +dependent response to the interrupt modifies the execution state +and results in the modification of the execution stream. This +modification usually requires that an interrupt handler utilize +the provided control mechanisms to return to the normal +processing stream. Although RTEMS hides many of the processor +dependent details of interrupt processing, it is important to +understand how the RTEMS interrupt manager is mapped onto the +processor's unique architecture. Discussed in this chapter are +the the processor's response and control mechanisms as they +pertain to RTEMS. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Interrupt Stack Frame, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Although the i386 supports multiple privilege levels, +RTEMS and all user software executes at privilege level 0. This +decision was made by the RTEMS designers to enhance +compatibility with processors which do not provide sophisticated +protection facilities like those of the i386. This decision +greatly simplifies the discussion of i386 processing, as one +need only consider interrupts without privilege transitions. + +Upon receipt of an interrupt the i386 automatically +performs the following actions: + +@itemize @bullet +@item pushes the EFLAGS register + +@item pushes the far address of the interrupted instruction + +@item vectors to the interrupt service routine (ISR). +@end itemize + +A nested interrupt is processed similarly by the +i386. + +@ifinfo +@node Interrupt Processing Interrupt Stack Frame, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Stack Frame + +The structure of the Interrupt Stack Frame for the +i386 which is placed on the interrupt stack by the processor in +response to an interrupt is as follows: + +@ifset use-ascii +@example +@group + +----------------------+ + | Old EFLAGS Register | ESP+8 + +----------+-----------+ + | UNUSED | Old CS | ESP+4 + +----------+-----------+ + | Old EIP | ESP + +----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil} +\cr +\multispan{4}\hrulefill\cr +& \multispan{3} Old EFLAGS Register\quad&&ESP+8\cr +\multispan{4}\hrulefill\cr +&UNUSED &&Old CS &&ESP+4\cr +\multispan{4}\hrulefill\cr +& \multispan{3} Old EIP && ESP\cr +\multispan{4}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="40%" BORDER=2> +<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EFLAGS Register</STRONG></TD> + <TD ALIGN=center>0x0</TD></TR> +<TR><TD ALIGN=center><STRONG>UNUSED</STRONG></TD> + <TD ALIGN=center><STRONG>Old CS</STRONG></TD> + <TD ALIGN=center>0x2</TD></TR> +<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EIP</STRONG></TD> + <TD ALIGN=center>0x4</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Stack Frame, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Although RTEMS supports 256 interrupt levels, the +i386 only supports two -- enabled and disabled. Interrupts are +enabled when the interrupt-enable flag (IF) in the extended +flags (EFLAGS) is set. Conversely, interrupt processing is +inhibited when the IF is cleared. During a non-maskable +interrupt, all other interrupts, including other non-maskable +ones, are inhibited. + +RTEMS interrupt levels 0 and 1 such that level zero +(0) indicates that interrupts are fully enabled and level one +that interrupts are disabled. All other RTEMS interrupt levels +are undefined and their behavior is unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Stack, Interrupt Processing Interrupt Levels, Interrupt Processing +@end ifinfo +@section Disabling of Interrupts by RTEMS + +During the execution of directive calls, critical +sections of code may be executed. When these sections are +encountered, RTEMS disables interrupts before the execution of +this section and restores them to the previous level upon +completion of the section. RTEMS has been optimized to insure +that interrupts are disabled for less than RTEMS_MAXIMUM_DISABLE_PERIOD +microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz i386 with zero +wait states. These numbers will vary based the number of wait states +and processor speed present on the target board. [NOTE: The maximum +period with interrupts disabled within RTEMS was last calculated for +Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +Non-maskable interrupts (NMI) cannot be disabled, and +ISRs which execute at this level MUST NEVER issue RTEMS system +calls. If a directive is invoked, unpredictable results may +occur due to the inability of RTEMS to protect its critical +sections. However, ISRs that make no system calls may safely +execute as non-maskable interrupts. + +@ifinfo +@node Interrupt Processing Interrupt Stack, Default Fatal Error Processing, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing +@end ifinfo +@section Interrupt Stack + +The i386 family does not support a dedicated hardware +interrupt stack. On this processor, RTEMS allocates and manages +a dedicated interrupt stack. As part of vectoring a non-nested +interrupt service routine, RTEMS switches from the stack of the +interrupted task to a dedicated interrupt stack. When a +non-nested interrupt returns, RTEMS switches back to the stack +of the interrupted stack. The current stack pointer is not +altered by RTEMS on nested interrupt. + +Without a dedicated interrupt stack, every task in +the system MUST have enough stack space to accommodate the worst +case stack usage of that particular task and the interrupt +service routines COMBINED. By supporting a dedicated interrupt +stack, RTEMS significantly lowers the stack requirements for +each task. + +RTEMS allocates the dedicated interrupt stack from +the Workspace Area. The amount of memory allocated for the +interrupt stack is determined by the interrupt_stack_size field +in the CPU Configuration Table. + diff --git a/doc/supplements/i386/intr_NOTIMES.t b/doc/supplements/i386/intr_NOTIMES.t new file mode 100644 index 0000000000..5c36183970 --- /dev/null +++ b/doc/supplements/i386/intr_NOTIMES.t @@ -0,0 +1,191 @@ +@ifinfo +@node Interrupt Processing, Interrupt Processing Introduction, Memory Model Flat Memory Model, Top +@end ifinfo +@chapter Interrupt Processing +@ifinfo +@menu +* Interrupt Processing Introduction:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Interrupt Stack Frame:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +* Interrupt Processing Interrupt Stack:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Processing Introduction, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurrence of an interrupt in their own unique fashion. In +addition, each processor type provides a control mechanism to +allow the proper handling of an interrupt. The processor +dependent response to the interrupt modifies the execution state +and results in the modification of the execution stream. This +modification usually requires that an interrupt handler utilize +the provided control mechanisms to return to the normal +processing stream. Although RTEMS hides many of the processor +dependent details of interrupt processing, it is important to +understand how the RTEMS interrupt manager is mapped onto the +processor's unique architecture. Discussed in this chapter are +the the processor's response and control mechanisms as they +pertain to RTEMS. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Interrupt Stack Frame, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Although the i386 supports multiple privilege levels, +RTEMS and all user software executes at privilege level 0. This +decision was made by the RTEMS designers to enhance +compatibility with processors which do not provide sophisticated +protection facilities like those of the i386. This decision +greatly simplifies the discussion of i386 processing, as one +need only consider interrupts without privilege transitions. + +Upon receipt of an interrupt the i386 automatically +performs the following actions: + +@itemize @bullet +@item pushes the EFLAGS register + +@item pushes the far address of the interrupted instruction + +@item vectors to the interrupt service routine (ISR). +@end itemize + +A nested interrupt is processed similarly by the +i386. + +@ifinfo +@node Interrupt Processing Interrupt Stack Frame, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Stack Frame + +The structure of the Interrupt Stack Frame for the +i386 which is placed on the interrupt stack by the processor in +response to an interrupt is as follows: + +@ifset use-ascii +@example +@group + +----------------------+ + | Old EFLAGS Register | ESP+8 + +----------+-----------+ + | UNUSED | Old CS | ESP+4 + +----------+-----------+ + | Old EIP | ESP + +----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil} +\cr +\multispan{4}\hrulefill\cr +& \multispan{3} Old EFLAGS Register\quad&&ESP+8\cr +\multispan{4}\hrulefill\cr +&UNUSED &&Old CS &&ESP+4\cr +\multispan{4}\hrulefill\cr +& \multispan{3} Old EIP && ESP\cr +\multispan{4}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="40%" BORDER=2> +<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EFLAGS Register</STRONG></TD> + <TD ALIGN=center>0x0</TD></TR> +<TR><TD ALIGN=center><STRONG>UNUSED</STRONG></TD> + <TD ALIGN=center><STRONG>Old CS</STRONG></TD> + <TD ALIGN=center>0x2</TD></TR> +<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EIP</STRONG></TD> + <TD ALIGN=center>0x4</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Stack Frame, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Although RTEMS supports 256 interrupt levels, the +i386 only supports two -- enabled and disabled. Interrupts are +enabled when the interrupt-enable flag (IF) in the extended +flags (EFLAGS) is set. Conversely, interrupt processing is +inhibited when the IF is cleared. During a non-maskable +interrupt, all other interrupts, including other non-maskable +ones, are inhibited. + +RTEMS interrupt levels 0 and 1 such that level zero +(0) indicates that interrupts are fully enabled and level one +that interrupts are disabled. All other RTEMS interrupt levels +are undefined and their behavior is unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Stack, Interrupt Processing Interrupt Levels, Interrupt Processing +@end ifinfo +@section Disabling of Interrupts by RTEMS + +During the execution of directive calls, critical +sections of code may be executed. When these sections are +encountered, RTEMS disables interrupts before the execution of +this section and restores them to the previous level upon +completion of the section. RTEMS has been optimized to insure +that interrupts are disabled for less than RTEMS_MAXIMUM_DISABLE_PERIOD +microseconds on a RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz i386 with zero +wait states. These numbers will vary based the number of wait states +and processor speed present on the target board. [NOTE: The maximum +period with interrupts disabled within RTEMS was last calculated for +Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +Non-maskable interrupts (NMI) cannot be disabled, and +ISRs which execute at this level MUST NEVER issue RTEMS system +calls. If a directive is invoked, unpredictable results may +occur due to the inability of RTEMS to protect its critical +sections. However, ISRs that make no system calls may safely +execute as non-maskable interrupts. + +@ifinfo +@node Interrupt Processing Interrupt Stack, Default Fatal Error Processing, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing +@end ifinfo +@section Interrupt Stack + +The i386 family does not support a dedicated hardware +interrupt stack. On this processor, RTEMS allocates and manages +a dedicated interrupt stack. As part of vectoring a non-nested +interrupt service routine, RTEMS switches from the stack of the +interrupted task to a dedicated interrupt stack. When a +non-nested interrupt returns, RTEMS switches back to the stack +of the interrupted stack. The current stack pointer is not +altered by RTEMS on nested interrupt. + +Without a dedicated interrupt stack, every task in +the system MUST have enough stack space to accommodate the worst +case stack usage of that particular task and the interrupt +service routines COMBINED. By supporting a dedicated interrupt +stack, RTEMS significantly lowers the stack requirements for +each task. + +RTEMS allocates the dedicated interrupt stack from +the Workspace Area. The amount of memory allocated for the +interrupt stack is determined by the interrupt_stack_size field +in the CPU Configuration Table. + diff --git a/doc/supplements/i386/memmodel.t b/doc/supplements/i386/memmodel.t new file mode 100644 index 0000000000..3d4ca55410 --- /dev/null +++ b/doc/supplements/i386/memmodel.t @@ -0,0 +1,85 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Memory Model, Memory Model Introduction, Calling Conventions User-Provided Routines, Top +@end ifinfo +@chapter Memory Model +@ifinfo +@menu +* Memory Model Introduction:: +* Memory Model Flat Memory Model:: +@end menu +@end ifinfo + +@ifinfo +@node Memory Model Introduction, Memory Model Flat Memory Model, Memory Model, Memory Model +@end ifinfo +@section Introduction + +A processor may support any combination of memory +models ranging from pure physical addressing to complex demand +paged virtual memory systems. RTEMS supports a flat memory +model which ranges contiguously over the processor's allowable +address space. RTEMS does not support segmentation or virtual +memory of any kind. The appropriate memory model for RTEMS +provided by the targeted processor and related characteristics +of that model are described in this chapter. + +@ifinfo +@node Memory Model Flat Memory Model, Interrupt Processing, Memory Model Introduction, Memory Model +@end ifinfo +@section Flat Memory Model + +RTEMS supports the i386 protected mode, flat memory +model with paging disabled. In this mode, the i386 +automatically converts every address from a logical to a +physical address each time it is used. The i386 uses +information provided in the segment registers and the Global +Descriptor Table to convert these addresses. RTEMS assumes the +existence of the following segments: + +@itemize @bullet +@item a single code segment at protection level (0) which +contains all application and executive code. + +@item a single data segment at protection level zero (0) which +contains all application and executive data. +@end itemize + +The i386 segment registers and associated selectors +must be initialized when the initialize_executive directive is +invoked. RTEMS treats the segment registers as system registers +and does not modify or context switch them. + +This i386 memory model supports a flat 32-bit address +space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4 +gigabytes). Each address is represented by a 32-bit value and +is byte addressable. The address may be used to reference a +single byte, half-word (2-bytes), or word (4 bytes). + +RTEMS does not require that logical addresses map +directly to physical addresses, although it is desirable in many +applications to do so. If logical and physical addresses are +not the same, then an additional selector will be required so +RTEMS can access the Interrupt Descriptor Table to install +interrupt service routines. The selector number of this segment +is provided to RTEMS in the CPU Dependent Information Table. + +By not requiring that logical addresses map directly +to physical addresses, the memory space of an RTEMS application +can be separated from that of a ROM monitor. For example, on +the Force Computers CPU386, the ROM monitor loads application +programs into a logical address space where logical address +0x00000000 corresponds to physical address 0x0002000. On this +board, RTEMS and the application use virtual addresses which do +not map to physical addresses. + +RTEMS assumes that the DS and ES registers contain +the selector for the single data segment when a directive is +invoked. This assumption is especially important when +developing interrupt service routines. + diff --git a/doc/supplements/i386/memmodel.texi b/doc/supplements/i386/memmodel.texi new file mode 100644 index 0000000000..3d4ca55410 --- /dev/null +++ b/doc/supplements/i386/memmodel.texi @@ -0,0 +1,85 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Memory Model, Memory Model Introduction, Calling Conventions User-Provided Routines, Top +@end ifinfo +@chapter Memory Model +@ifinfo +@menu +* Memory Model Introduction:: +* Memory Model Flat Memory Model:: +@end menu +@end ifinfo + +@ifinfo +@node Memory Model Introduction, Memory Model Flat Memory Model, Memory Model, Memory Model +@end ifinfo +@section Introduction + +A processor may support any combination of memory +models ranging from pure physical addressing to complex demand +paged virtual memory systems. RTEMS supports a flat memory +model which ranges contiguously over the processor's allowable +address space. RTEMS does not support segmentation or virtual +memory of any kind. The appropriate memory model for RTEMS +provided by the targeted processor and related characteristics +of that model are described in this chapter. + +@ifinfo +@node Memory Model Flat Memory Model, Interrupt Processing, Memory Model Introduction, Memory Model +@end ifinfo +@section Flat Memory Model + +RTEMS supports the i386 protected mode, flat memory +model with paging disabled. In this mode, the i386 +automatically converts every address from a logical to a +physical address each time it is used. The i386 uses +information provided in the segment registers and the Global +Descriptor Table to convert these addresses. RTEMS assumes the +existence of the following segments: + +@itemize @bullet +@item a single code segment at protection level (0) which +contains all application and executive code. + +@item a single data segment at protection level zero (0) which +contains all application and executive data. +@end itemize + +The i386 segment registers and associated selectors +must be initialized when the initialize_executive directive is +invoked. RTEMS treats the segment registers as system registers +and does not modify or context switch them. + +This i386 memory model supports a flat 32-bit address +space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4 +gigabytes). Each address is represented by a 32-bit value and +is byte addressable. The address may be used to reference a +single byte, half-word (2-bytes), or word (4 bytes). + +RTEMS does not require that logical addresses map +directly to physical addresses, although it is desirable in many +applications to do so. If logical and physical addresses are +not the same, then an additional selector will be required so +RTEMS can access the Interrupt Descriptor Table to install +interrupt service routines. The selector number of this segment +is provided to RTEMS in the CPU Dependent Information Table. + +By not requiring that logical addresses map directly +to physical addresses, the memory space of an RTEMS application +can be separated from that of a ROM monitor. For example, on +the Force Computers CPU386, the ROM monitor loads application +programs into a logical address space where logical address +0x00000000 corresponds to physical address 0x0002000. On this +board, RTEMS and the application use virtual addresses which do +not map to physical addresses. + +RTEMS assumes that the DS and ES registers contain +the selector for the single data segment when a directive is +invoked. This assumption is especially important when +developing interrupt service routines. + diff --git a/doc/supplements/i386/preface.texi b/doc/supplements/i386/preface.texi new file mode 100644 index 0000000000..ce96fe2ea4 --- /dev/null +++ b/doc/supplements/i386/preface.texi @@ -0,0 +1,39 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, CPU Model Dependent Features, Top, Top +@end ifinfo +@unnumbered Preface + +The Real Time Executive for Multiprocessor Systems +(RTEMS) is designed to be portable across multiple processor +architectures. However, the nature of real-time systems makes +it essential that the application designer understand certain +processor dependent implementation details. These processor +dependencies include calling convention, board support package +issues, interrupt processing, exact RTEMS memory requirements, +performance data, header files, and the assembly language +interface to the executive. + +For information on the i386 processor, refer to the +following documents: + +@itemize @bullet +@item @cite{386 Programmer's Reference Manual, Intel, Order No. 230985-002}. + +@item @cite{386 Microprocessor Hardware Reference Manual, Intel, +Order No. 231732-003}. + +@item @cite{80386 System Software Writer's Guide, Intel, Order No. 231499-001}. + +@item @cite{80387 Programmer's Reference Manual, Intel, Order No. 231917-001}. +@end itemize + +It is highly recommended that the i386 RTEMS +application developer obtain and become familiar with Intel's +386 Programmer's Reference Manual. + diff --git a/doc/supplements/i386/timeFORCE386.t b/doc/supplements/i386/timeFORCE386.t new file mode 100644 index 0000000000..03362e3c88 --- /dev/null +++ b/doc/supplements/i386/timeFORCE386.t @@ -0,0 +1,135 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node i386 Timing Data, i386 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter i386 Timing Data +@ifinfo +@menu +* i386 Timing Data Introduction:: +* i386 Timing Data Hardware Platform:: +* i386 Timing Data Interrupt Latency:: +* i386 Timing Data Context Switch:: +* i386 Timing Data Directive Times:: +* i386 Timing Data Task Manager:: +* i386 Timing Data Interrupt Manager:: +* i386 Timing Data Clock Manager:: +* i386 Timing Data Timer Manager:: +* i386 Timing Data Semaphore Manager:: +* i386 Timing Data Message Manager:: +* i386 Timing Data Event Manager:: +* i386 Timing Data Signal Manager:: +* i386 Timing Data Partition Manager:: +* i386 Timing Data Region Manager:: +* i386 Timing Data Dual-Ported Memory Manager:: +* i386 Timing Data I/O Manager:: +* i386 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node i386 Timing Data Introduction, i386 Timing Data Hardware Platform, i386 Timing Data, i386 Timing Data +@end ifinfo +@section Introduction + +The timing data for the i386 version of RTEMS is +provided along with the target dependent aspects concerning the +gathering of the timing data. The hardware platform used to +gather the times is described to give the reader a better +understanding of each directive time provided. Also, provided +is a description of the interrupt latency and the context +switch times as they pertain to the i386 version of RTEMS. + +@ifinfo +@node i386 Timing Data Hardware Platform, i386 Timing Data Interrupt Latency, i386 Timing Data Introduction, i386 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Force +Computers CPU386 board. The CPU386 is a 16 Mhz board with zero +wait state dynamic memory and an i80387 numeric coprocessor. +One of the count-down timers provided by a Motorola MC68901 was +used to measure elapsed time with one microsecond resolution. +All sources of hardware interrupts are disabled, although the +interrupt level of the i386 allows all interrupts. + +The maximum period interrupts are disabled was +measured by summing the number of CPU cycles required by each +assembly language instruction executed while interrupts were +disabled. Zero wait state memory was assumed. The total CPU +cycles executed with interrupts disabled, including the +instructions to disable and enable interrupts, was divided by 16 +to simulate a i386 executing at 16 Mhz. + +@ifinfo +@node i386 Timing Data Interrupt Latency, i386 Timing Data Context Switch, i386 Timing Data Hardware Platform, i386 Timing Data +@end ifinfo +@section Interrupt Latency + +The maximum period with interrupts disabled within +RTEMS is less than RTEMS_MAXIMUM_DISABLE_PERIOD microseconds +including the instructions +which disable and re-enable interrupts. The time required for +the i386 to generate an interrupt using the int instruction, +vectoring to an interrupt handler, and for the RTEMS entry +overhead before invoking the user's interrupt handler are a +total of 12 microseconds. These combine to yield a worst case +interrupt latency of less +RTEMS_MAXIMUM_DISABLE_PERIOD + RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK +microseconds. [NOTE: The +maximum period with interrupts disabled within RTEMS was last +calculated for Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +It should be noted again that the maximum period with +interrupts disabled within RTEMS is hand-timed. The interrupt +vector and entry overhead time was generated on the Force +Computers CPU386 benchmark platform using the int instruction as +the interrupt source. + +@ifinfo +@node i386 Timing Data Context Switch, i386 Timing Data Directive Times, i386 Timing Data Interrupt Latency, i386 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the Force Computers CPU386 benchmark platform. +This time represents the raw context switch time with no user +extensions configured. Additional execution time is required +when a TASK_SWITCH user extension is configured. The use of the +TASK_SWITCH extension is application dependent. Thus, its +execution time is not considered part of the base context switch +time. + +Since RTEMS was designed specifically for embedded +missile applications which are floating point intensive, the +executive is optimized to avoid unnecessarily saving and +restoring the state of the numeric coprocessor. The state of +the numeric coprocessor is only saved when a FLOATING_POINT task +is dispatched and that task was not the last task to utilize the +coprocessor. In a system with only one FLOATING_POINT task, the +state of the numeric coprocessor will never be saved or +restored. When the first FLOATING_POINT task is dispatched, +RTEMS does not need to save the current state of the numeric +coprocessor. + +The exact amount of time required to save and restore +floating point context is dependent on the state of the numeric +coprocessor. RTEMS places the coprocessor in the initialized +state when a task is started or restarted. Once the task has +utilized the coprocessor, it is in the idle state when floating +point instructions are not executing and the busy state when +floating point instructions are executing. The state of the +coprocessor is task specific. + +The following table summarizes the context switch +times for the Force Computers CPU386 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex diff --git a/doc/supplements/i386/timedata.t b/doc/supplements/i386/timedata.t new file mode 100644 index 0000000000..03362e3c88 --- /dev/null +++ b/doc/supplements/i386/timedata.t @@ -0,0 +1,135 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node i386 Timing Data, i386 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter i386 Timing Data +@ifinfo +@menu +* i386 Timing Data Introduction:: +* i386 Timing Data Hardware Platform:: +* i386 Timing Data Interrupt Latency:: +* i386 Timing Data Context Switch:: +* i386 Timing Data Directive Times:: +* i386 Timing Data Task Manager:: +* i386 Timing Data Interrupt Manager:: +* i386 Timing Data Clock Manager:: +* i386 Timing Data Timer Manager:: +* i386 Timing Data Semaphore Manager:: +* i386 Timing Data Message Manager:: +* i386 Timing Data Event Manager:: +* i386 Timing Data Signal Manager:: +* i386 Timing Data Partition Manager:: +* i386 Timing Data Region Manager:: +* i386 Timing Data Dual-Ported Memory Manager:: +* i386 Timing Data I/O Manager:: +* i386 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node i386 Timing Data Introduction, i386 Timing Data Hardware Platform, i386 Timing Data, i386 Timing Data +@end ifinfo +@section Introduction + +The timing data for the i386 version of RTEMS is +provided along with the target dependent aspects concerning the +gathering of the timing data. The hardware platform used to +gather the times is described to give the reader a better +understanding of each directive time provided. Also, provided +is a description of the interrupt latency and the context +switch times as they pertain to the i386 version of RTEMS. + +@ifinfo +@node i386 Timing Data Hardware Platform, i386 Timing Data Interrupt Latency, i386 Timing Data Introduction, i386 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Force +Computers CPU386 board. The CPU386 is a 16 Mhz board with zero +wait state dynamic memory and an i80387 numeric coprocessor. +One of the count-down timers provided by a Motorola MC68901 was +used to measure elapsed time with one microsecond resolution. +All sources of hardware interrupts are disabled, although the +interrupt level of the i386 allows all interrupts. + +The maximum period interrupts are disabled was +measured by summing the number of CPU cycles required by each +assembly language instruction executed while interrupts were +disabled. Zero wait state memory was assumed. The total CPU +cycles executed with interrupts disabled, including the +instructions to disable and enable interrupts, was divided by 16 +to simulate a i386 executing at 16 Mhz. + +@ifinfo +@node i386 Timing Data Interrupt Latency, i386 Timing Data Context Switch, i386 Timing Data Hardware Platform, i386 Timing Data +@end ifinfo +@section Interrupt Latency + +The maximum period with interrupts disabled within +RTEMS is less than RTEMS_MAXIMUM_DISABLE_PERIOD microseconds +including the instructions +which disable and re-enable interrupts. The time required for +the i386 to generate an interrupt using the int instruction, +vectoring to an interrupt handler, and for the RTEMS entry +overhead before invoking the user's interrupt handler are a +total of 12 microseconds. These combine to yield a worst case +interrupt latency of less +RTEMS_MAXIMUM_DISABLE_PERIOD + RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK +microseconds. [NOTE: The +maximum period with interrupts disabled within RTEMS was last +calculated for Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +It should be noted again that the maximum period with +interrupts disabled within RTEMS is hand-timed. The interrupt +vector and entry overhead time was generated on the Force +Computers CPU386 benchmark platform using the int instruction as +the interrupt source. + +@ifinfo +@node i386 Timing Data Context Switch, i386 Timing Data Directive Times, i386 Timing Data Interrupt Latency, i386 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the Force Computers CPU386 benchmark platform. +This time represents the raw context switch time with no user +extensions configured. Additional execution time is required +when a TASK_SWITCH user extension is configured. The use of the +TASK_SWITCH extension is application dependent. Thus, its +execution time is not considered part of the base context switch +time. + +Since RTEMS was designed specifically for embedded +missile applications which are floating point intensive, the +executive is optimized to avoid unnecessarily saving and +restoring the state of the numeric coprocessor. The state of +the numeric coprocessor is only saved when a FLOATING_POINT task +is dispatched and that task was not the last task to utilize the +coprocessor. In a system with only one FLOATING_POINT task, the +state of the numeric coprocessor will never be saved or +restored. When the first FLOATING_POINT task is dispatched, +RTEMS does not need to save the current state of the numeric +coprocessor. + +The exact amount of time required to save and restore +floating point context is dependent on the state of the numeric +coprocessor. RTEMS places the coprocessor in the initialized +state when a task is started or restarted. Once the task has +utilized the coprocessor, it is in the idle state when floating +point instructions are not executing and the busy state when +floating point instructions are executing. The state of the +coprocessor is task specific. + +The following table summarizes the context switch +times for the Force Computers CPU386 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex diff --git a/doc/supplements/i960/CVME961_TIMES b/doc/supplements/i960/CVME961_TIMES new file mode 100644 index 0000000000..f148a32d5c --- /dev/null +++ b/doc/supplements/i960/CVME961_TIMES @@ -0,0 +1,244 @@ +# +# Intel i960/Cyclone CVME961 (i960CA) Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL i960CA +# +# Interrupt Latency +# +# NOTE: In general, the text says it is hand-calculated to be +# RTEMS_MAXIMUM_DISABLE_PERIOD at RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ +# Mhz and this was last calculated for Release +# RTEMS_VERSION_FOR_MAXIMUM_DISABLE_PERIOD. +# +RTEMS_MAXIMUM_DISABLE_PERIOD 2.5 +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ 33 +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD 3.2.1 +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 1 +RTEMS_RESTORE_1ST_FP_TASK 2 +RTEMS_SAVE_INIT_RESTORE_INIT 3 +RTEMS_SAVE_IDLE_RESTORE_INIT 4 +RTEMS_SAVE_IDLE_RESTORE_IDLE 5 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 6 +RTEMS_TASK_IDENT_ONLY 7 +RTEMS_TASK_START_ONLY 8 +RTEMS_TASK_RESTART_CALLING_TASK 9 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 9 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 10 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 11 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 12 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 13 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 14 +RTEMS_TASK_DELETE_CALLING_TASK 15 +RTEMS_TASK_DELETE_SUSPENDED_TASK 16 +RTEMS_TASK_DELETE_BLOCKED_TASK 17 +RTEMS_TASK_DELETE_READY_TASK 18 +RTEMS_TASK_SUSPEND_CALLING_TASK 19 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 20 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 21 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 22 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 23 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 24 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 25 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 26 +RTEMS_TASK_MODE_NO_RESCHEDULE 27 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 28 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 29 +RTEMS_TASK_GET_NOTE_ONLY 30 +RTEMS_TASK_SET_NOTE_ONLY 31 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 32 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 33 +RTEMS_TASK_WAKE_WHEN_ONLY 34 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 35 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 36 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 37 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 38 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 39 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 40 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 41 +RTEMS_CLOCK_GET_ONLY 42 +RTEMS_CLOCK_TICK_ONLY 43 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 44 +RTEMS_TIMER_IDENT_ONLY 45 +RTEMS_TIMER_DELETE_INACTIVE 46 +RTEMS_TIMER_DELETE_ACTIVE 47 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 48 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 49 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 50 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 51 +RTEMS_TIMER_RESET_INACTIVE 52 +RTEMS_TIMER_RESET_ACTIVE 53 +RTEMS_TIMER_CANCEL_INACTIVE 54 +RTEMS_TIMER_CANCEL_ACTIVE 55 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 56 +RTEMS_SEMAPHORE_IDENT_ONLY 57 +RTEMS_SEMAPHORE_DELETE_ONLY 58 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 59 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 60 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 61 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 62 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 63 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 64 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 65 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 66 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 67 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 68 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 69 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 70 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 71 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 72 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 73 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 74 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 75 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 77 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 78 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 79 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 80 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 81 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 82 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 83 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 84 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 85 +RTEMS_EVENT_RECEIVE_AVAILABLE 86 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 87 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 88 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 89 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 90 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 91 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 92 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 93 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 94 +RTEMS_PARTITION_IDENT_ONLY 95 +RTEMS_PARTITION_DELETE_ONLY 96 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 97 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 98 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 99 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 100 +RTEMS_REGION_IDENT_ONLY 101 +RTEMS_REGION_DELETE_ONLY 102 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 103 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 104 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 105 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 106 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 107 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 108 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 109 +RTEMS_PORT_IDENT_ONLY 110 +RTEMS_PORT_DELETE_ONLY 111 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 112 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 113 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 114 +RTEMS_IO_OPEN_ONLY 115 +RTEMS_IO_CLOSE_ONLY 116 +RTEMS_IO_READ_ONLY 117 +RTEMS_IO_WRITE_ONLY 118 +RTEMS_IO_CONTROL_ONLY 119 +# +# Rate Monotonic Manager +# +RTEMS_RATE_MONOTONIC_CREATE_ONLY 120 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 121 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 122 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 123 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 124 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 125 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 126 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 127 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 128 +RTEMS_MINIMUM_CONFIGURATION xx,129 +RTEMS_MAXIMUM_CONFIGURATION xx,130 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE x,131 +RTEMS_INITIALIZATION_CODE_SIZE x,132 +RTEMS_TASK_CODE_SIZE x,133 +RTEMS_INTERRUPT_CODE_SIZE x,134 +RTEMS_CLOCK_CODE_SIZE x,135 +RTEMS_TIMER_CODE_SIZE x,136 +RTEMS_SEMAPHORE_CODE_SIZE x,137 +RTEMS_MESSAGE_CODE_SIZE x,138 +RTEMS_EVENT_CODE_SIZE x,139 +RTEMS_SIGNAL_CODE_SIZE x,140 +RTEMS_PARTITION_CODE_SIZE x,141 +RTEMS_REGION_CODE_SIZE x,142 +RTEMS_DPMEM_CODE_SIZE x,143 +RTEMS_IO_CODE_SIZE x,144 +RTEMS_FATAL_ERROR_CODE_SIZE x,145 +RTEMS_RATE_MONOTONIC_CODE_SIZE x,146 +RTEMS_MULTIPROCESSING_CODE_SIZE x,147 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 148 +RTEMS_SEMAPHORE_CODE_OPTSIZE 149 +RTEMS_MESSAGE_CODE_OPTSIZE 150 +RTEMS_EVENT_CODE_OPTSIZE 151 +RTEMS_SIGNAL_CODE_OPTSIZE 152 +RTEMS_PARTITION_CODE_OPTSIZE 153 +RTEMS_REGION_CODE_OPTSIZE 154 +RTEMS_DPMEM_CODE_OPTSIZE 155 +RTEMS_IO_CODE_OPTSIZE 156 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 157 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 158 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 159 +RTEMS_BYTES_PER_TIMER 160 +RTEMS_BYTES_PER_SEMAPHORE 161 +RTEMS_BYTES_PER_MESSAGE_QUEUE 162 +RTEMS_BYTES_PER_REGION 163 +RTEMS_BYTES_PER_PARTITION 164 +RTEMS_BYTES_PER_PORT 165 +RTEMS_BYTES_PER_PERIOD 166 +RTEMS_BYTES_PER_EXTENSION 167 +RTEMS_BYTES_PER_FP_TASK 168 +RTEMS_BYTES_PER_NODE 169 +RTEMS_BYTES_PER_GLOBAL_OBJECT 170 +RTEMS_BYTES_PER_PROXY 171 +# x,xxx alloted for numbers +RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS x,172 diff --git a/doc/supplements/i960/Makefile b/doc/supplements/i960/Makefile new file mode 100644 index 0000000000..13a1ebdef9 --- /dev/null +++ b/doc/supplements/i960/Makefile @@ -0,0 +1,88 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=i960 +REPLACE=../tools/word-replace + +all: + +COMMON_FILES=../common/cpright.texi ../common/setup.texi \ + ../common/timing.texi + +FILES= $(PROJECT).texi \ + bsp.texi callconv.texi cpumodel.texi cputable.texi fatalerr.texi \ + intr.texi memmodel.texi preface.texi timetbl.texi timedata.texi wksheets.texi + +all: + +info: c_i960 + cp c_$(PROJECT) $(INFO_INSTALL) + +c_i960: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f c_i960 + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(PROJECT).dvi + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +replace: timedata.texi + +intr.texi: intr.t CVME961_TIMES + ${REPLACE} -p CVME961_TIMES intr.t + mv intr.t.fixed intr.texi + +timetbl.t: ../common/timetbl.t + sed -e 's/TIMETABLE_NEXT_LINK/Command and Variable Index/' \ + <../common/timetbl.t >timetbl.t + +timetbl.texi: timetbl.t CVME961_TIMES + ${REPLACE} -p CVME961_TIMES timetbl.t + mv timetbl.t.fixed timetbl.texi + +timedata.texi: timedata.t CVME961_TIMES + ${REPLACE} -p CVME961_TIMES timedata.t + mv timedata.t.fixed timedata.texi + +wksheets.t: ../common/wksheets.t + sed -e 's/WORKSHEETS_PREVIOUS_LINK/Processor Dependent Information Table CPU Dependent Information Table/' \ + -e 's/WORKSHEETS_NEXT_LINK/i960CA Timing Data/' \ + <../common/wksheets.t >wksheets.t + +wksheets.texi: wksheets.t CVME961_TIMES + ${REPLACE} -p CVME961_TIMES wksheets.t + mv wksheets.t.fixed wksheets.texi + +html: $(FILES) + -mkdir $(WWW_INSTALL)/c_i960 + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/c_$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f $(PROJECT) $(PROJECT)-* + rm -f c_i960 c_i960-* + rm -f timedata.texi timetbl.texi intr.texi wksheets.texi + rm -f timetbl.t wksheets.t + rm -f *.fixed _* + diff --git a/doc/supplements/i960/bsp.t b/doc/supplements/i960/bsp.t new file mode 100644 index 0000000000..423cde737c --- /dev/null +++ b/doc/supplements/i960/bsp.t @@ -0,0 +1,71 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of i960CA specific BSP +issues. For more information on developing a BSP, refer to the +chapter titled Board Support Packages in the RTEMS C +Applications User's Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated when the +i960CA processor is reset. When the i960CA is reset, the +processor reads an Initial Memory Image (IMI) to establish its +state. The IMI consists of the Initialization Boot Record (IBR) +and the Process Control Block (PRCB) from an Initial Memory +Image (IMI) at location 0xFFFFFF00. The IBR contains the +initial bus configuration data, the address of the first +instruction to execute after reset, the address of the PRCB, and +the checksum used by the processor's self-test. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +The PRCB contains the base addresses for system data +structures, and initial configuration information for the core +and integrated peripherals. In particular, the PRCB contains +the initial contents of the Arithmetic Control (AC) Register as +well as the base addresses of the Interrupt Vector Table, System +Procedure Entry Table, Fault Entry Table, and the Control Table. +In addition, the PRCB is used to configure the depth of the +instruction and register caches and the actions when certain +types of faults are encountered. + +The Process Controls (PC) Register is initialized to +0xC01F2002 which sets the i960CA's interrupt level to 0x1F (31 +decimal). In addition, the Interrupt Mask (IMSK) Register +(alternately referred to as Special Function Register 1 or sf1) +is set to 0x00000000 to mask all external and DMA interrupt +sources. Thus, all interrupts are disabled when the first +instruction is executed. + +For more information regarding the i960CA's data +structures and their contents, refer to Intel's i960CA User's +Manual. diff --git a/doc/supplements/i960/bsp.texi b/doc/supplements/i960/bsp.texi new file mode 100644 index 0000000000..423cde737c --- /dev/null +++ b/doc/supplements/i960/bsp.texi @@ -0,0 +1,71 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, Default Fatal Error Processing Default Fatal Error Handler Operations, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages System Reset:: +* Board Support Packages Processor Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages System Reset, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +An RTEMS Board Support Package (BSP) must be designed +to support a particular processor and target board combination. +This chapter presents a discussion of i960CA specific BSP +issues. For more information on developing a BSP, refer to the +chapter titled Board Support Packages in the RTEMS C +Applications User's Guide. + +@ifinfo +@node Board Support Packages System Reset, Board Support Packages Processor Initialization, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section System Reset + +An RTEMS based application is initiated when the +i960CA processor is reset. When the i960CA is reset, the +processor reads an Initial Memory Image (IMI) to establish its +state. The IMI consists of the Initialization Boot Record (IBR) +and the Process Control Block (PRCB) from an Initial Memory +Image (IMI) at location 0xFFFFFF00. The IBR contains the +initial bus configuration data, the address of the first +instruction to execute after reset, the address of the PRCB, and +the checksum used by the processor's self-test. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +The PRCB contains the base addresses for system data +structures, and initial configuration information for the core +and integrated peripherals. In particular, the PRCB contains +the initial contents of the Arithmetic Control (AC) Register as +well as the base addresses of the Interrupt Vector Table, System +Procedure Entry Table, Fault Entry Table, and the Control Table. +In addition, the PRCB is used to configure the depth of the +instruction and register caches and the actions when certain +types of faults are encountered. + +The Process Controls (PC) Register is initialized to +0xC01F2002 which sets the i960CA's interrupt level to 0x1F (31 +decimal). In addition, the Interrupt Mask (IMSK) Register +(alternately referred to as Special Function Register 1 or sf1) +is set to 0x00000000 to mask all external and DMA interrupt +sources. Thus, all interrupts are disabled when the first +instruction is executed. + +For more information regarding the i960CA's data +structures and their contents, refer to Intel's i960CA User's +Manual. diff --git a/doc/supplements/i960/callconv.t b/doc/supplements/i960/callconv.t new file mode 100644 index 0000000000..7998baee2f --- /dev/null +++ b/doc/supplements/i960/callconv.t @@ -0,0 +1,130 @@ +@c +@c COPYRIGHT (c) 1988-1997. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features Floating Point Unit, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Processor Background:: +* Calling Conventions Calling Mechanism:: +* Calling Conventions Register Usage:: +* Calling Conventions Parameter Passing:: +* Calling Conventions User-Provided Routines:: +* Calling Conventions Leaf Procedures:: +@end menu +@end ifinfo + +@ifinfo +@node Calling Conventions Introduction, Calling Conventions Processor Background, Calling Conventions, Calling Conventions +@end ifinfo +@section Introduction + +Each high-level language compiler generates +subroutine entry and exit code based upon a set of rules known +as the compiler's calling convention. These rules address the +following issues: + +@itemize @bullet +@item register preservation and usage + +@item parameter passing + +@item call and return mechanism +@end itemize + +A compiler's calling convention is of importance when +interfacing to subroutines written in another language either +assembly or high-level. Even when the high-level language and +target processor are the same, different compilers may use +different calling conventions. As a result, calling conventions +are both processor and compiler dependent. + +@ifinfo +@node Calling Conventions Processor Background, Calling Conventions Calling Mechanism, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Processor Background + +All members of the i960 architecture family support +two methods for performing procedure calls: a RISC-style +branch-and-link and an integrated call and return mechanism. + +On a branch-and-link, the processor branches to the +invoked procedure and saves the return address in a register, +G14. Typically, the invoked procedure will not invoke another +procedure and is referred to as a leaf procedure. Many +high-level language compilers for the i960 family recognize leaf +procedures and automatically optimize them to utilize the +branch-and-link mechanism. Branch-and-link procedures are +invoked using the bal and balx instructions and return control +via the bx instruction. By convention, G14 is zero when not in +a leaf procedure. It is the responsibility of the leaf +procedure to clear G14 before returning. + +The integrated call and return mechanism also +branches to the invoked procedure and saves the return address +as did the branch and link mechanism. However, the important +difference is that the call, callx, and calls instructions save |
