From ae68ff085724dd35d60151bd153e80b8b0776873 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 27 May 1997 12:40:11 +0000 Subject: Initial revision --- doc/HELP.html | 23 + doc/Make.config | 18 + doc/Makefile | 24 + doc/README | 33 + doc/archgrey.gif | Bin 0 -> 12160 bytes doc/common/cpright.texi | 42 + doc/common/missing-arrow.gif | Bin 0 -> 166 bytes doc/common/next-arrow.gif | Bin 0 -> 275 bytes doc/common/oaronly.jpg | Bin 0 -> 1584 bytes doc/common/prev-arrow.gif | Bin 0 -> 279 bytes doc/common/setup.texi | 69 + doc/common/timemac.texi | 34 + doc/common/timetbl.t | 1364 ++++++++++ doc/common/timing.texi | 457 ++++ doc/common/up-arrow.gif | Bin 0 -> 264 bytes doc/common/wksheets.t | 424 +++ doc/develenv/Makefile | 55 + doc/develenv/compile.texi | 157 ++ doc/develenv/develenv.texi | 119 + doc/develenv/direct.texi | 712 +++++ doc/develenv/intro.texi | 56 + doc/develenv/sample.texi | 287 +++ doc/develenv/utils.texi | 310 +++ doc/do_docs | 18 + doc/import_ami_txt | 81 + doc/new_chapters/Makefile | 59 + doc/new_chapters/base.texi | 96 + doc/new_chapters/clock.texi | 262 ++ doc/new_chapters/cond.texi | 384 +++ doc/new_chapters/key.texi | 177 ++ doc/new_chapters/mutex.texi | 640 +++++ doc/new_chapters/posix_test_plan.texi | 123 + doc/new_chapters/preface.texi | 12 + doc/new_chapters/sched.texi | 226 ++ doc/new_chapters/signal.texi | 689 +++++ doc/new_chapters/thread.texi | 1023 ++++++++ doc/oaronly.jpg | Bin 0 -> 1584 bytes doc/posix_users/Makefile | 59 + doc/posix_users/base.texi | 96 + doc/posix_users/clock.texi | 262 ++ doc/posix_users/cond.texi | 384 +++ doc/posix_users/key.texi | 177 ++ doc/posix_users/mutex.texi | 640 +++++ doc/posix_users/posix_test_plan.texi | 123 + doc/posix_users/preface.texi | 12 + doc/posix_users/sched.texi | 226 ++ doc/posix_users/signal.texi | 689 +++++ doc/posix_users/thread.texi | 1023 ++++++++ doc/relnotes/Makefile | 53 + doc/relnotes/install.texi | 174 ++ doc/relnotes/intro.texi | 223 ++ doc/relnotes/probrep.texi | 60 + doc/relnotes/relnotes.texi | 116 + doc/relnotes/status.texi | 258 ++ doc/rtems.html | 26 + doc/rtems_footer.html | 3 + doc/rtems_header.html | 6 + doc/supplements/hppa1_1/Makefile | 88 + doc/supplements/hppa1_1/SIMHPPA_TIMES | 244 ++ doc/supplements/hppa1_1/TIMES | 244 ++ doc/supplements/hppa1_1/bsp.t | 70 + doc/supplements/hppa1_1/bsp.texi | 70 + doc/supplements/hppa1_1/callconv.t | 172 ++ doc/supplements/hppa1_1/callconv.texi | 172 ++ doc/supplements/hppa1_1/cpumodel.t | 69 + doc/supplements/hppa1_1/cpumodel.texi | 69 + doc/supplements/hppa1_1/cputable.t | 124 + doc/supplements/hppa1_1/cputable.texi | 124 + doc/supplements/hppa1_1/fatalerr.t | 45 + doc/supplements/hppa1_1/fatalerr.texi | 45 + doc/supplements/hppa1_1/hppa1_1.texi | 118 + doc/supplements/hppa1_1/intr.t | 214 ++ doc/supplements/hppa1_1/intr_NOTIMES.t | 214 ++ doc/supplements/hppa1_1/memmodel.t | 80 + doc/supplements/hppa1_1/memmodel.texi | 80 + doc/supplements/hppa1_1/preface.texi | 34 + doc/supplements/hppa1_1/timedata.t | 105 + doc/supplements/i386/FORCE386_TIMES | 244 ++ doc/supplements/i386/Makefile | 88 + doc/supplements/i386/bsp.t | 110 + doc/supplements/i386/bsp.texi | 110 + doc/supplements/i386/callconv.t | 119 + doc/supplements/i386/callconv.texi | 119 + doc/supplements/i386/cpumodel.t | 81 + doc/supplements/i386/cpumodel.texi | 81 + doc/supplements/i386/cputable.t | 126 + doc/supplements/i386/cputable.texi | 126 + doc/supplements/i386/fatalerr.t | 44 + doc/supplements/i386/fatalerr.texi | 44 + doc/supplements/i386/i386.texi | 123 + doc/supplements/i386/intr.t | 191 ++ doc/supplements/i386/intr_NOTIMES.t | 191 ++ doc/supplements/i386/memmodel.t | 85 + doc/supplements/i386/memmodel.texi | 85 + doc/supplements/i386/preface.texi | 39 + doc/supplements/i386/timeFORCE386.t | 135 + doc/supplements/i386/timedata.t | 135 + doc/supplements/i960/CVME961_TIMES | 244 ++ doc/supplements/i960/Makefile | 88 + doc/supplements/i960/bsp.t | 71 + doc/supplements/i960/bsp.texi | 71 + doc/supplements/i960/callconv.t | 130 + doc/supplements/i960/callconv.texi | 130 + doc/supplements/i960/cpumodel.t | 79 + doc/supplements/i960/cpumodel.texi | 79 + doc/supplements/i960/cputable.t | 130 + doc/supplements/i960/cputable.texi | 130 + doc/supplements/i960/fatalerr.t | 43 + doc/supplements/i960/fatalerr.texi | 43 + doc/supplements/i960/i960.texi | 117 + doc/supplements/i960/intr.t | 220 ++ doc/supplements/i960/intr_NOTIMES.t | 220 ++ doc/supplements/i960/memmodel.t | 53 + doc/supplements/i960/memmodel.texi | 53 + doc/supplements/i960/preface.texi | 38 + doc/supplements/i960/timeCVME961.t | 123 + doc/supplements/i960/timedata.t | 123 + doc/supplements/m68k/MVME136_TIMES | 244 ++ doc/supplements/m68k/Makefile | 87 + doc/supplements/m68k/bsp.t | 110 + doc/supplements/m68k/callconv.t | 121 + doc/supplements/m68k/cpumodel.t | 128 + doc/supplements/m68k/cputable.t | 118 + doc/supplements/m68k/fatalerr.t | 44 + doc/supplements/m68k/intr_NOTIMES.t | 230 ++ doc/supplements/m68k/m68k.texi | 118 + doc/supplements/m68k/memmodel.t | 52 + doc/supplements/m68k/preface.texi | 58 + doc/supplements/m68k/timeMVME136.t | 143 ++ doc/supplements/m68k/timedata.t | 143 ++ doc/supplements/sparc/ERC32_TIMES | 244 ++ doc/supplements/sparc/Makefile | 90 + doc/supplements/sparc/SIS_TIMES | 244 ++ doc/supplements/sparc/bsp.t | 103 + doc/supplements/sparc/bsp.texi | 103 + doc/supplements/sparc/callconv.t | 445 ++++ doc/supplements/sparc/callconv.texi | 445 ++++ doc/supplements/sparc/cpumodel.t | 169 ++ doc/supplements/sparc/cpumodel.texi | 169 ++ doc/supplements/sparc/cputable.t | 109 + doc/supplements/sparc/cputable.texi | 109 + doc/supplements/sparc/fatalerr.t | 45 + doc/supplements/sparc/fatalerr.texi | 45 + doc/supplements/sparc/intr.t | 226 ++ doc/supplements/sparc/intr_NOTIMES.t | 226 ++ doc/supplements/sparc/memmodel.t | 117 + doc/supplements/sparc/memmodel.texi | 117 + doc/supplements/sparc/preface.texi | 89 + doc/supplements/sparc/sparc.texi | 117 + doc/supplements/sparc/timeERC32.t | 156 ++ doc/supplements/sparc/timedata.t | 156 ++ doc/texinfo/texinfo.tex | 4426 ++++++++++++++++++++++++++++++++ doc/tools/bmenu/Makefile | 43 + doc/tools/bmenu/address.h | 112 + doc/tools/bmenu/address.inl | 107 + doc/tools/bmenu/base.h | 106 + doc/tools/bmenu/bmenu | Bin 0 -> 38028 bytes doc/tools/bmenu/chain.c | 232 ++ doc/tools/bmenu/chain.h | 349 +++ doc/tools/bmenu/chain.inl | 273 ++ doc/tools/bmenu/chain.o | Bin 0 -> 6752 bytes doc/tools/bmenu/isr.h | 11 + doc/tools/bmenu/main.c | 985 +++++++ doc/tools/bmenu/main.o | Bin 0 -> 28012 bytes doc/tools/bmenu/system.h | 29 + doc/tools/update | 215 ++ doc/tools/word-replace | 85 + doc/user/Makefile | 59 + doc/user/bsp.t | 377 +++ doc/user/c_user.texi | 159 ++ doc/user/clock.t | 356 +++ doc/user/concepts.t | 322 +++ doc/user/conf.t | 752 ++++++ doc/user/dirstat.texi | 40 + doc/user/dpmem.t | 324 +++ doc/user/event.t | 351 +++ doc/user/example.texi | 103 + doc/user/fatal.t | 180 ++ doc/user/glossary.texi | 772 ++++++ doc/user/init.t | 408 +++ doc/user/intr.t | 300 +++ doc/user/io.t | 528 ++++ doc/user/mp.t | 628 +++++ doc/user/msg.t | 714 ++++++ doc/user/overview.t | 578 +++++ doc/user/part.t | 423 +++ doc/user/preface.texi | 173 ++ doc/user/region.t | 601 +++++ doc/user/rtemsarc.gif | Bin 0 -> 7653 bytes doc/user/rtemspie.gif | Bin 0 -> 31070 bytes doc/user/rtmon.t | 1148 +++++++++ doc/user/schedule.t | 426 +++ doc/user/sem.t | 722 ++++++ doc/user/signal.t | 354 +++ doc/user/states.gif | Bin 0 -> 31256 bytes doc/user/task.t | 1313 ++++++++++ doc/user/timer.t | 441 ++++ doc/user/userext.t | 649 +++++ 198 files changed, 44720 insertions(+) create mode 100644 doc/HELP.html create mode 100644 doc/Make.config create mode 100644 doc/Makefile create mode 100644 doc/README create mode 100644 doc/archgrey.gif create mode 100644 doc/common/cpright.texi create mode 100644 doc/common/missing-arrow.gif create mode 100644 doc/common/next-arrow.gif create mode 100644 doc/common/oaronly.jpg create mode 100644 doc/common/prev-arrow.gif create mode 100644 doc/common/setup.texi create mode 100644 doc/common/timemac.texi create mode 100644 doc/common/timetbl.t create mode 100644 doc/common/timing.texi create mode 100644 doc/common/up-arrow.gif create mode 100644 doc/common/wksheets.t create mode 100644 doc/develenv/Makefile create mode 100644 doc/develenv/compile.texi create mode 100644 doc/develenv/develenv.texi create mode 100644 doc/develenv/direct.texi create mode 100644 doc/develenv/intro.texi create mode 100644 doc/develenv/sample.texi create mode 100644 doc/develenv/utils.texi create mode 100755 doc/do_docs create mode 100644 doc/import_ami_txt create mode 100644 doc/new_chapters/Makefile create mode 100644 doc/new_chapters/base.texi create mode 100644 doc/new_chapters/clock.texi create mode 100644 doc/new_chapters/cond.texi create mode 100644 doc/new_chapters/key.texi create mode 100644 doc/new_chapters/mutex.texi create mode 100644 doc/new_chapters/posix_test_plan.texi create mode 100644 doc/new_chapters/preface.texi create mode 100644 doc/new_chapters/sched.texi create mode 100644 doc/new_chapters/signal.texi create mode 100644 doc/new_chapters/thread.texi create mode 100644 doc/oaronly.jpg create mode 100644 doc/posix_users/Makefile create mode 100644 doc/posix_users/base.texi create mode 100644 doc/posix_users/clock.texi create mode 100644 doc/posix_users/cond.texi create mode 100644 doc/posix_users/key.texi create mode 100644 doc/posix_users/mutex.texi create mode 100644 doc/posix_users/posix_test_plan.texi create mode 100644 doc/posix_users/preface.texi create mode 100644 doc/posix_users/sched.texi create mode 100644 doc/posix_users/signal.texi create mode 100644 doc/posix_users/thread.texi create mode 100644 doc/relnotes/Makefile create mode 100644 doc/relnotes/install.texi create mode 100644 doc/relnotes/intro.texi create mode 100644 doc/relnotes/probrep.texi create mode 100644 doc/relnotes/relnotes.texi create mode 100644 doc/relnotes/status.texi create mode 100644 doc/rtems.html create mode 100644 doc/rtems_footer.html create mode 100644 doc/rtems_header.html create mode 100644 doc/supplements/hppa1_1/Makefile create mode 100644 doc/supplements/hppa1_1/SIMHPPA_TIMES create mode 100644 doc/supplements/hppa1_1/TIMES create mode 100644 doc/supplements/hppa1_1/bsp.t create mode 100644 doc/supplements/hppa1_1/bsp.texi create mode 100644 doc/supplements/hppa1_1/callconv.t create mode 100644 doc/supplements/hppa1_1/callconv.texi create mode 100644 doc/supplements/hppa1_1/cpumodel.t create mode 100644 doc/supplements/hppa1_1/cpumodel.texi create mode 100644 doc/supplements/hppa1_1/cputable.t create mode 100644 doc/supplements/hppa1_1/cputable.texi create mode 100644 doc/supplements/hppa1_1/fatalerr.t create mode 100644 doc/supplements/hppa1_1/fatalerr.texi create mode 100644 doc/supplements/hppa1_1/hppa1_1.texi create mode 100644 doc/supplements/hppa1_1/intr.t create mode 100644 doc/supplements/hppa1_1/intr_NOTIMES.t create mode 100644 doc/supplements/hppa1_1/memmodel.t create mode 100644 doc/supplements/hppa1_1/memmodel.texi create mode 100644 doc/supplements/hppa1_1/preface.texi create mode 100644 doc/supplements/hppa1_1/timedata.t create mode 100644 doc/supplements/i386/FORCE386_TIMES create mode 100644 doc/supplements/i386/Makefile create mode 100644 doc/supplements/i386/bsp.t create mode 100644 doc/supplements/i386/bsp.texi create mode 100644 doc/supplements/i386/callconv.t create mode 100644 doc/supplements/i386/callconv.texi create mode 100644 doc/supplements/i386/cpumodel.t create mode 100644 doc/supplements/i386/cpumodel.texi create mode 100644 doc/supplements/i386/cputable.t create mode 100644 doc/supplements/i386/cputable.texi create mode 100644 doc/supplements/i386/fatalerr.t create mode 100644 doc/supplements/i386/fatalerr.texi create mode 100644 doc/supplements/i386/i386.texi create mode 100644 doc/supplements/i386/intr.t create mode 100644 doc/supplements/i386/intr_NOTIMES.t create mode 100644 doc/supplements/i386/memmodel.t create mode 100644 doc/supplements/i386/memmodel.texi create mode 100644 doc/supplements/i386/preface.texi create mode 100644 doc/supplements/i386/timeFORCE386.t create mode 100644 doc/supplements/i386/timedata.t create mode 100644 doc/supplements/i960/CVME961_TIMES create mode 100644 doc/supplements/i960/Makefile create mode 100644 doc/supplements/i960/bsp.t create mode 100644 doc/supplements/i960/bsp.texi create mode 100644 doc/supplements/i960/callconv.t create mode 100644 doc/supplements/i960/callconv.texi create mode 100644 doc/supplements/i960/cpumodel.t create mode 100644 doc/supplements/i960/cpumodel.texi create mode 100644 doc/supplements/i960/cputable.t create mode 100644 doc/supplements/i960/cputable.texi create mode 100644 doc/supplements/i960/fatalerr.t create mode 100644 doc/supplements/i960/fatalerr.texi create mode 100644 doc/supplements/i960/i960.texi create mode 100644 doc/supplements/i960/intr.t create mode 100644 doc/supplements/i960/intr_NOTIMES.t create mode 100644 doc/supplements/i960/memmodel.t create mode 100644 doc/supplements/i960/memmodel.texi create mode 100644 doc/supplements/i960/preface.texi create mode 100644 doc/supplements/i960/timeCVME961.t create mode 100644 doc/supplements/i960/timedata.t create mode 100644 doc/supplements/m68k/MVME136_TIMES create mode 100644 doc/supplements/m68k/Makefile create mode 100644 doc/supplements/m68k/bsp.t create mode 100644 doc/supplements/m68k/callconv.t create mode 100644 doc/supplements/m68k/cpumodel.t create mode 100644 doc/supplements/m68k/cputable.t create mode 100644 doc/supplements/m68k/fatalerr.t create mode 100644 doc/supplements/m68k/intr_NOTIMES.t create mode 100644 doc/supplements/m68k/m68k.texi create mode 100644 doc/supplements/m68k/memmodel.t create mode 100644 doc/supplements/m68k/preface.texi create mode 100644 doc/supplements/m68k/timeMVME136.t create mode 100644 doc/supplements/m68k/timedata.t create mode 100644 doc/supplements/sparc/ERC32_TIMES create mode 100644 doc/supplements/sparc/Makefile create mode 100644 doc/supplements/sparc/SIS_TIMES create mode 100644 doc/supplements/sparc/bsp.t create mode 100644 doc/supplements/sparc/bsp.texi create mode 100644 doc/supplements/sparc/callconv.t create mode 100644 doc/supplements/sparc/callconv.texi create mode 100644 doc/supplements/sparc/cpumodel.t create mode 100644 doc/supplements/sparc/cpumodel.texi create mode 100644 doc/supplements/sparc/cputable.t create mode 100644 doc/supplements/sparc/cputable.texi create mode 100644 doc/supplements/sparc/fatalerr.t create mode 100644 doc/supplements/sparc/fatalerr.texi create mode 100644 doc/supplements/sparc/intr.t create mode 100644 doc/supplements/sparc/intr_NOTIMES.t create mode 100644 doc/supplements/sparc/memmodel.t create mode 100644 doc/supplements/sparc/memmodel.texi create mode 100644 doc/supplements/sparc/preface.texi create mode 100644 doc/supplements/sparc/sparc.texi create mode 100644 doc/supplements/sparc/timeERC32.t create mode 100644 doc/supplements/sparc/timedata.t create mode 100644 doc/texinfo/texinfo.tex create mode 100644 doc/tools/bmenu/Makefile create mode 100644 doc/tools/bmenu/address.h create mode 100644 doc/tools/bmenu/address.inl create mode 100644 doc/tools/bmenu/base.h create mode 100644 doc/tools/bmenu/bmenu create mode 100644 doc/tools/bmenu/chain.c create mode 100644 doc/tools/bmenu/chain.h create mode 100644 doc/tools/bmenu/chain.inl create mode 100644 doc/tools/bmenu/chain.o create mode 100644 doc/tools/bmenu/isr.h create mode 100644 doc/tools/bmenu/main.c create mode 100644 doc/tools/bmenu/main.o create mode 100644 doc/tools/bmenu/system.h create mode 100644 doc/tools/update create mode 100755 doc/tools/word-replace create mode 100644 doc/user/Makefile create mode 100644 doc/user/bsp.t create mode 100644 doc/user/c_user.texi create mode 100644 doc/user/clock.t create mode 100644 doc/user/concepts.t create mode 100644 doc/user/conf.t create mode 100644 doc/user/dirstat.texi create mode 100644 doc/user/dpmem.t create mode 100644 doc/user/event.t create mode 100644 doc/user/example.texi create mode 100644 doc/user/fatal.t create mode 100644 doc/user/glossary.texi create mode 100644 doc/user/init.t create mode 100644 doc/user/intr.t create mode 100644 doc/user/io.t create mode 100644 doc/user/mp.t create mode 100644 doc/user/msg.t create mode 100644 doc/user/overview.t create mode 100644 doc/user/part.t create mode 100644 doc/user/preface.texi create mode 100644 doc/user/region.t create mode 100644 doc/user/rtemsarc.gif create mode 100644 doc/user/rtemspie.gif create mode 100644 doc/user/rtmon.t create mode 100644 doc/user/schedule.t create mode 100644 doc/user/sem.t create mode 100644 doc/user/signal.t create mode 100644 doc/user/states.gif create mode 100644 doc/user/task.t create mode 100644 doc/user/timer.t create mode 100644 doc/user/userext.t (limited to 'doc') 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 @@ + +RTEMS On-Line Library + + + OAR + +

RTEMS On-Line Library

+
+ +The following supplement manuals do not currently exist: + +
  • RTEMS AMD 29K C Applications Supplement
    • +
  • RTEMS MIPS C Applications Supplement
    • +
  • RTEMS PowerPC C Applications Supplement
    • +
  • RTEMS UNIX Port C Applications Supplement
    • +     +If you have knowledge of the processors used in the above ports and +want to contribute to RTEMS, please contact +rtems@OARcorp.com + +
    +Copyright © 1996 OAR Corporation + 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 new file mode 100644 index 0000000000..d315b028f2 Binary files /dev/null and b/doc/archgrey.gif differ 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 new file mode 100644 index 0000000000..c686c80b5f Binary files /dev/null and b/doc/common/missing-arrow.gif differ diff --git a/doc/common/next-arrow.gif b/doc/common/next-arrow.gif new file mode 100644 index 0000000000..57f5cddb81 Binary files /dev/null and b/doc/common/next-arrow.gif differ diff --git a/doc/common/oaronly.jpg b/doc/common/oaronly.jpg new file mode 100644 index 0000000000..c87c151404 Binary files /dev/null and b/doc/common/oaronly.jpg differ diff --git a/doc/common/prev-arrow.gif b/doc/common/prev-arrow.gif new file mode 100644 index 0000000000..350785be10 Binary files /dev/null and b/doc/common/prev-arrow.gif differ 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 +
    + + + + + + + + + + + + +
    No Floating Point ContextsRTEMS_NO_FP_CONTEXTS
    Floating Point Contexts
    restore first FP task
    		RTEMS_RESTORE_1ST_FP_TASK
    save initialized, restore initialized
    		RTEMS_SAVE_INIT_RESTORE_INIT
    save idle, restore initialized
    		RTEMS_SAVE_IDLE_RESTORE_INIT
    save idle, restore idle
    		RTEMS_SAVE_IDLE_RESTORE_IDLE
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TASK_CREATERTEMS_TASK_CREATE_ONLY
    TASK_IDENTRTEMS_TASK_IDENT_ONLY
    TASK_STARTRTEMS_TASK_START_ONLY
    TASK_RESTART
    calling task
    		RTEMS_TASK_RESTART_CALLING_TASK
    suspended task -- returns to caller
    		RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER
    blocked task -- returns to caller
    		RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER
    ready task -- returns to caller
    		RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER
    suspended task -- preempts caller
    		RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER
    blocked task -- preempts caller
    		RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER
    ready task -- preempts caller
    		RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER
    TASK_DELETE
    calling task
    		RTEMS_TASK_DELETE_CALLING_TASK
    suspended task
    		RTEMS_TASK_DELETE_SUSPENDED_TASK
    blocked task
    		RTEMS_TASK_DELETE_BLOCKED_TASK
    ready task
    		RTEMS_TASK_DELETE_READY_TASK
    TASK_SUSPEND
    calling task
    		RTEMS_TASK_SUSPEND_CALLING_TASK
    returns to caller
    		RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER
    TASK_RESUME
    task readied -- returns to caller
    		RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER
    TASK_SET_PRIORITY
    obtain current priority
    		RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY
    returns to caller
    		RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER
    preempts caller
    		RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER
    TASK_MODE
    obtain current mode
    		RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE
    no reschedule
    		RTEMS_TASK_MODE_NO_RESCHEDULE
    reschedule -- returns to caller
    		RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER
    reschedule -- preempts caller
    		RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER
    TASK_GET_NOTERTEMS_TASK_GET_NOTE_ONLY
    TASK_SET_NOTERTEMS_TASK_SET_NOTE_ONLY
    TASK_WAKE_AFTER
    yield -- returns to caller
    		RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER
    yield -- preempts caller
    		RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER
    TASK_WAKE_WHENRTEMS_TASK_WAKE_WHEN_ONLY
    +
    +@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 +
    + + + + + + + + + + + + + + + +
    Interrupt Entry Overhead
    returns to nested interrupt
    		RTEMS_INTR_ENTRY_RETURNS_TO_NESTED
    returns to interrupted task
    		RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK
    returns to preempting task
    		RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK
    Interrupt Exit Overhead
    returns to nested interrupt
    		RTEMS_INTR_EXIT_RETURNS_TO_NESTED
    returns to interrupted task
    		RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK
    returns to preempting task
    		RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK
    +
    +@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 +
    + + + + + + + +
    CLOCK_SETRTEMS_CLOCK_SET_ONLY
    CLOCK_GETRTEMS_CLOCK_GET_ONLY
    CLOCK_TICKRTEMS_CLOCK_TICK_ONLY
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TIMER_CREATERTEMS_TIMER_CREATE_ONLY
    TIMER_IDENTRTEMS_TIMER_IDENT_ONLY
    TIMER_DELETE
    inactive
    		RTEMS_TIMER_DELETE_INACTIVE
    active
    		RTEMS_TIMER_DELETE_ACTIVE
    TIMER_FIRE_AFTER
    inactive
    		RTEMS_TIMER_FIRE_AFTER_INACTIVE
    active
    		RTEMS_TIMER_FIRE_AFTER_ACTIVE
    TIMER_FIRE_WHEN
    inactive
    		RTEMS_TIMER_FIRE_WHEN_INACTIVE
    active
    		RTEMS_TIMER_FIRE_WHEN_ACTIVE
    TIMER_RESET
    inactive
    		RTEMS_TIMER_RESET_INACTIVE
    active
    		RTEMS_TIMER_RESET_ACTIVE
    TIMER_CANCEL
    inactive
    		RTEMS_TIMER_CANCEL_INACTIVE
    active
    		RTEMS_TIMER_CANCEL_ACTIVE
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + +
    SEMAPHORE_CREATERTEMS_SEMAPHORE_CREATE_ONLY
    SEMAPHORE_IDENTRTEMS_SEMAPHORE_IDENT_ONLY
    SEMAPHORE_DELETERTEMS_SEMAPHORE_DELETE_ONLY
    SEMAPHORE_OBTAIN
    available
    		RTEMS_SEMAPHORE_OBTAIN_AVAILABLE
    not available -- NO_WAIT
    		RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT
    not available -- caller blocks
    		RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS
    SEMAPHORE_RELEASE
    no waiting tasks
    		RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS
    task readied -- returns to caller
    		RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    MESSAGE_QUEUE_CREATERTEMS_MESSAGE_QUEUE_CREATE_ONLY
    MESSAGE_QUEUE_IDENTRTEMS_MESSAGE_QUEUE_IDENT_ONLY
    MESSAGE_QUEUE_DELETERTEMS_MESSAGE_QUEUE_DELETE_ONLY
    MESSAGE_QUEUE_SEND
    no waiting tasks
    		RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS
    task readied -- returns to caller
    		RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER
    MESSAGE_QUEUE_URGENT
    no waiting tasks
    		RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS
    task readied -- returns to caller
    		RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER
    MESSAGE_QUEUE_BROADCAST
    no waiting tasks
    		RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS
    task readied -- returns to caller
    		RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER
    MESSAGE_QUEUE_RECEIVE
    available
    		RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE
    not available -- NO_WAIT
    		RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT
    not available -- caller blocks
    		RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS
    MESSAGE_QUEUE_FLUSH
    no messages flushed
    		RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED
    messages flushed
    		RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + +
    EVENT_SEND
    no task readied
    		RTEMS_EVENT_SEND_NO_TASK_READIED
    task readied -- returns to caller
    		RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER
    EVENT_RECEIVE
    obtain current events
    		RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS
    available
    		RTEMS_EVENT_RECEIVE_AVAILABLE
    not available -- NO_WAIT
    		RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT
    not available -- caller blocks
    		RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS
    +
    +@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 +
    + + + + + + + + + + + + + +
    SIGNAL_CATCHRTEMS_SIGNAL_CATCH_ONLY
    SIGNAL_SEND
    returns to caller
    		RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER
    signal to self
    		RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF
    EXIT ASR OVERHEAD
    returns to calling task
    		 + RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK
    returns to preempting task
    		 + RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK
    +
    +@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 +
    + + + + + + + + + + + + + + +
    PARTITION_CREATERTEMS_PARTITION_CREATE_ONLY
    PARTITION_IDENTRTEMS_PARTITION_IDENT_ONLY
    PARTITION_DELETERTEMS_PARTITION_DELETE_ONLY
    PARTITION_GET_BUFFER
    available
    		RTEMS_PARTITION_GET_BUFFER_AVAILABLE
    not available
    		RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE
    PARTITION_RETURN_BUFFERRTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + +
    REGION_CREATERTEMS_REGION_CREATE_ONLY
    REGION_IDENTRTEMS_REGION_IDENT_ONLY
    REGION_DELETERTEMS_REGION_DELETE_ONLY
    REGION_GET_SEGMENT
    available
    		RTEMS_REGION_GET_SEGMENT_AVAILABLE
    not available -- NO_WAIT
    		 + RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT
    not available -- caller blocks
    		 + RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS
    REGION_RETURN_SEGMENT
    no waiting tasks
    		RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS
    task readied -- returns to caller
    		 + RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER
    task readied -- preempts caller
    		 + RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER
    +
    +@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 +
    + + + + + + + + + + + + +
    PORT_CREATERTEMS_PORT_CREATE_ONLY
    PORT_IDENTRTEMS_PORT_IDENT_ONLY
    PORT_DELETERTEMS_PORT_DELETE_ONLY
    PORT_INTERNAL_TO_EXTERNALRTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY
    PORT_EXTERNAL_TO_INTERNALRTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY
    +
    +@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 +
    + + + + + + + + + + + + + +
    IO_INITIALIZERTEMS_IO_INITIALIZE_ONLY
    IO_OPENRTEMS_IO_OPEN_ONLY
    IO_CLOSERTEMS_IO_CLOSE_ONLY
    IO_READRTEMS_IO_READ_ONLY
    IO_WRITERTEMS_IO_WRITE_ONLY
    IO_CONTROLRTEMS_IO_CONTROL_ONLY
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + +
    RATE_MONOTONIC_CREATERTEMS_RATE_MONOTONIC_CREATE_ONLY
    RATE_MONOTONIC_IDENTRTEMS_RATE_MONOTONIC_IDENT_ONLY
    RATE_MONOTONIC_CANCELRTEMS_RATE_MONOTONIC_CANCEL_ONLY
    RATE_MONOTONIC_DELETE
    active
    		RTEMS_RATE_MONOTONIC_DELETE_ACTIVE
    inactive
    		RTEMS_RATE_MONOTONIC_DELETE_INACTIVE
    RATE_MONOTONIC_PERIOD
    initiate period -- returns to caller
    		 + RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER
    conclude period -- caller blocks
    		 + RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS
    obtain status
    		RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS
    +
    +@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 new file mode 100644 index 0000000000..82aa8ccc68 Binary files /dev/null and b/doc/common/up-arrow.gif differ 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 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ComponentIncludedNot IncludedSize
    CoreRTEMS_CORE_CODE_SIZENA
    InitializationRTEMS_INITIALIZATION_CODE_SIZENA
    TaskRTEMS_TASK_CODE_SIZENA
    InterruptRTEMS_INTERRUPT_CODE_SIZENA
    ClockRTEMS_CLOCK_CODE_SIZENA
    TimerRTEMS_TIMER_CODE_SIZERTEMS_TIMER_CODE_OPTSIZE
    SemaphoreRTEMS_SEMAPHORE_CODE_SIZERTEMS_SEMAPHORE_CODE_OPTSIZE
    MessageRTEMS_MESSAGE_CODE_SIZERTEMS_MESSAGE_CODE_OPTSIZE
    EventRTEMS_EVENT_CODE_SIZERTEMS_EVENT_CODE_OPTSIZE
    SignalRTEMS_SIGNAL_CODE_SIZERTEMS_SIGNAL_CODE_OPTSIZE
    PartitionRTEMS_PARTITION_CODE_SIZERTEMS_PARTITION_CODE_OPTSIZE
    RegionRTEMS_REGION_CODE_SIZERTEMS_REGION_CODE_OPTSIZE
    Dual Ported MemoryRTEMS_DPMEM_CODE_SIZERTEMS_DPMEM_CODE_OPTSIZE
    I/ORTEMS_IO_CODE_SIZERTEMS_IO_CODE_OPTSIZE
    Fatal ErrorRTEMS_FATAL_ERROR_CODE_SIZENA
    Rate MonotonicRTEMS_RATE_MONOTONIC_CODE_SIZERTEMS_RATE_MONOTONIC_CODE_OPTSIZE
    MultiprocessingRTEMS_MULTIPROCESSING_CODE_SIZERTEMS_MULTIPROCESSING_CODE_OPTSIZE
    + Total Code Space Requirements
    +
    +@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 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    DescriptionEquationBytes Required
    maximum_tasks* RTEMS_BYTES_PER_TASK =
    maximum_timers* RTEMS_BYTES_PER_TIMER =
    maximum_semaphores* RTEMS_BYTES_PER_SEMAPHORE =
    maximum_message_queues* RTEMS_BYTES_PER_MESSAGE_QUEUE =
    maximum_regions* RTEMS_BYTES_PER_REGION =
    maximum_partitions* RTEMS_BYTES_PER_PARTITION =
    maximum_ports* RTEMS_BYTES_PER_PORT =
    maximum_periods* RTEMS_BYTES_PER_PERIOD =
    maximum_extensions* RTEMS_BYTES_PER_EXTENSION =
    Floating Point Tasks* RTEMS_BYTES_PER_FP_TASK =
    Task Stacks
    + Total Single Processor Requirements
    DescriptionEquationBytes Required
    maximum_nodes* RTEMS_BYTES_PER_NODE =
    maximum_global_objects* RTEMS_BYTES_PER_GLOBAL_OBJECT =
    maximum_proxies* RTEMS_BYTES_PER_PROXY =
    + Total Multiprocessing Requirements
    Fixed System RequirementsRTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS
    Total Single Processor Requirements
    Total Multiprocessing Requirements
    + Minimum Bytes for RTEMS Workspace
    +
    +@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 +
    + + + + + + + + + +
    allperform compilation but do not install
    installperform compilation if directory contains source + but do not install
    cleandelete most generated files and directories for + the current CPU and target
    clobberdelete all generated files and directories for + the current CPU and target
    +
    +@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 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/.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 +
    + + + + + + + + + + + + + + + +
    Support Libraries (BSPs, C library, CPU support)$RTEMS_ROOT/c/src/lib
    Single Processor Tests$RTEMS_ROOT/c/src/tests/sptests
    Timing Tests$RTEMS_ROOT/c/src/tests/tmtests
    Multiprocessor Tests$RTEMS_ROOT/c/src/tests/mptests
    Sample Applications$RTEMS_ROOT/c/src/tests/samples
    RTEMS Build Tools$RTEMS_SRC_BASE/c/build_tools
    Make Support$RTEMS_ROOT/c/make
    +
    +@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 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 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 -Z and -M + # 2. Tackle paragraph style issues + # 3. Directive status code lines + + tr -d '\032\015' <${orig}/$i | + sed -e 's//@chapter /' | + sed -e 's//@section /' | + sed -e 's//@subsection /' | + sed -e 's//@subsection /' | + sed -e 's///' | + sed -e 's//@item /' | + sed -e 's//@itemize /' | + sed -e 's//@item /' | + sed -e 's//@item /' | + sed -e 's/
    /@item /' | + sed -e 's//@item /' | + sed -e 's/
    + + + + + + + +
    Old EFLAGS Register0x0
    UNUSEDOld CS0x2
    Old EIP0x4
    + +@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 +
    + + + + + + + + +
    Old EFLAGS Register0x0
    UNUSEDOld CS0x2
    Old EIP0x4
    +
    +@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 +the local register set (R0 through R15) before transferring +control to the invoked procedure. The ret instruction +automatically restores the previous local register set. The +i960CA provides a register cache which can be configured to +retain the last five to sixteen recent register caches. When +the register cache is full, the oldest cached register set is +written to the stack. + +@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 either a call +or callx instruction and return to the user 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 and callx instructions +automatically save the current contents of the local register +set (R0 through R15). The contents of the local registers will +be restored as part of returning to the application. The +contents of global registers G0 through G7 are not preserved by +RTEMS directives. + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS uses the standard i960 family C parameter +passing mechanism in which G0 contains the first parameter, G1 +the second, and so on for the remaining parameters. No RTEMS +directive requires more than six parameters. + +@ifinfo +@node Calling Conventions User-Provided Routines, Calling Conventions Leaf Procedures, 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. + +@ifinfo +@node Calling Conventions Leaf Procedures, Memory Model, Calling Conventions User-Provided Routines, Calling Conventions +@end ifinfo +@section Leaf Procedures + +RTEMS utilizes leaf procedures internally to improve +performance. This improves execution speed as well as reducing +stack usage and the number of register sets which must be cached. + + diff --git a/doc/supplements/i960/callconv.texi b/doc/supplements/i960/callconv.texi new file mode 100644 index 0000000000..7998baee2f --- /dev/null +++ b/doc/supplements/i960/callconv.texi @@ -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 +the local register set (R0 through R15) before transferring +control to the invoked procedure. The ret instruction +automatically restores the previous local register set. The +i960CA provides a register cache which can be configured to +retain the last five to sixteen recent register caches. When +the register cache is full, the oldest cached register set is +written to the stack. + +@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 either a call +or callx instruction and return to the user 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 and callx instructions +automatically save the current contents of the local register +set (R0 through R15). The contents of the local registers will +be restored as part of returning to the application. The +contents of global registers G0 through G7 are not preserved by +RTEMS directives. + +@ifinfo +@node Calling Conventions Parameter Passing, Calling Conventions User-Provided Routines, Calling Conventions Register Usage, Calling Conventions +@end ifinfo +@section Parameter Passing + +RTEMS uses the standard i960 family C parameter +passing mechanism in which G0 contains the first parameter, G1 +the second, and so on for the remaining parameters. No RTEMS +directive requires more than six parameters. + +@ifinfo +@node Calling Conventions User-Provided Routines, Calling Conventions Leaf Procedures, 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. + +@ifinfo +@node Calling Conventions Leaf Procedures, Memory Model, Calling Conventions User-Provided Routines, Calling Conventions +@end ifinfo +@section Leaf Procedures + +RTEMS utilizes leaf procedures internally to improve +performance. This improves execution speed as well as reducing +stack usage and the number of register sets which must be cached. + + diff --git a/doc/supplements/i960/cpumodel.t b/doc/supplements/i960/cpumodel.t new file mode 100644 index 0000000000..18ec1d7311 --- /dev/null +++ b/doc/supplements/i960/cpumodel.t @@ -0,0 +1,79 @@ +@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 i960 implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/i960/i960.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 i960CA, +this macro is set to the string "i960ca". + +@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 I960_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. diff --git a/doc/supplements/i960/cpumodel.texi b/doc/supplements/i960/cpumodel.texi new file mode 100644 index 0000000000..18ec1d7311 --- /dev/null +++ b/doc/supplements/i960/cpumodel.texi @@ -0,0 +1,79 @@ +@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 i960 implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/i960/i960.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 i960CA, +this macro is set to the string "i960ca". + +@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 I960_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. diff --git a/doc/supplements/i960/cputable.t b/doc/supplements/i960/cputable.t new file mode 100644 index 0000000000..dbeebd5a68 --- /dev/null +++ b/doc/supplements/i960/cputable.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 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 i960CA version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the i960CA. 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 (*postdriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void (*stack_free_hook)( void* ); + /* end of fields required on all CPUs */ + +#if defined(__i960CA__) || defined(__i960_CA__) || defined(__i960CA) + i960ca_PRCB *Prcb; +#endif + +@}; +@end example + +The contents of the i960CA Processor Control Block +are discussed in Intel's i960CA User's Manual. Structure +definitions for the i960CA PRCB and Control Table are provided +by including the file rtems.h. + +@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 Prcb +is the base address of the i960CA's Processor +Control Block. It is primarily used by RTEMS to install +interrupt handlers. +@end table + + + + + + diff --git a/doc/supplements/i960/cputable.texi b/doc/supplements/i960/cputable.texi new file mode 100644 index 0000000000..dbeebd5a68 --- /dev/null +++ b/doc/supplements/i960/cputable.texi @@ -0,0 +1,130 @@ +@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 i960CA version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the i960CA. 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 (*postdriver_hook)( void ); + void (*idle_task)( void ); + boolean do_zero_of_workspace; + unsigned32 interrupt_stack_size; + unsigned32 extra_mpci_receive_server_stack; + void (*stack_free_hook)( void* ); + /* end of fields required on all CPUs */ + +#if defined(__i960CA__) || defined(__i960_CA__) || defined(__i960CA) + i960ca_PRCB *Prcb; +#endif + +@}; +@end example + +The contents of the i960CA Processor Control Block +are discussed in Intel's i960CA User's Manual. Structure +definitions for the i960CA PRCB and Control Table are provided +by including the file rtems.h. + +@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 Prcb +is the base address of the i960CA's Processor +Control Block. It is primarily used by RTEMS to install +interrupt handlers. +@end table + + + + + + diff --git a/doc/supplements/i960/fatalerr.t b/doc/supplements/i960/fatalerr.t new file mode 100644 index 0000000000..6ce95fe669 --- /dev/null +++ b/doc/supplements/i960/fatalerr.t @@ -0,0 +1,43 @@ +@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 is 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 to +level 31, places the error code in G0, and executes a branch to +self instruction to simulate a halt processor instruction. diff --git a/doc/supplements/i960/fatalerr.texi b/doc/supplements/i960/fatalerr.texi new file mode 100644 index 0000000000..6ce95fe669 --- /dev/null +++ b/doc/supplements/i960/fatalerr.texi @@ -0,0 +1,43 @@ +@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 is 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 to +level 31, places the error code in G0, and executes a branch to +self instruction to simulate a halt processor instruction. diff --git a/doc/supplements/i960/i960.texi b/doc/supplements/i960/i960.texi new file mode 100644 index 0000000000..a1cc5aad45 --- /dev/null +++ b/doc/supplements/i960/i960.texi @@ -0,0 +1,117 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_i960 +@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 Intel i960 C Applications Supplement +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Intel i960 C Applications Supplement (i960): +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 i960 C Applications Supplement + +@setchapternewpage odd +@settitle RTEMS Intel i960 C Applications Supplement +@titlepage +@finalout + +@title RTEMS Intel i960 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_i960 + +This is the online version of the RTEMS Intel i960 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:: +* i960CA 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, i960CA 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/i960/intr.t b/doc/supplements/i960/intr.t new file mode 100644 index 0000000000..45b80fead9 --- /dev/null +++ b/doc/supplements/i960/intr.t @@ -0,0 +1,220 @@ +@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 Record:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +* Interrupt Processing Register Cache Flushing:: +* 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 its 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 which 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 Record, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the i960CA +automatically performs the following actions: + +@itemize @bullet +@item saves the local register set, + +@item sets the Frame Pointer (FP) to point to the interrupt +stack, + +@item increments the FP by sixteen (16) to make room for the +Interrupt Record, + +@item saves the current values of the arithmetic-controls (AC) +register, the process-controls (PC) register, and the interrupt +vector number are saved in the Interrupt Record, + +@item the CPU sets the Instruction Pointer (IP) to the address +of the first instruction in the interrupt handler, + +@item the return-status field of the Previous Frame Pointer +(PFP or R0) register is set to interrupt return, + +@item sets the PC state bit to interrupted, + +@item sets the current interrupt disable level in the PC to +the level of the current interrupt, and + +@item disables tracing. +@end itemize + +A nested interrupt is processed similarly by the +i960CA with the exception that the Frame Pointer (FP) already +points to the interrupt stack. This means that the FP is NOT +overwritten before space for the Interrupt Record is allocated. + +The state flag bit of the saved PC register in the +Interrupt Record is examined by RTEMS to determine when an outer +most interrupt is being exited. Therefore, the user application +code MUST NOT modify this bit. + +@ifinfo +@node Interrupt Processing Interrupt Record, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Record + +The structure of the Interrupt Record for the i960CA +which is placed on the interrupt stack by the processor in +response to an interrupt is as follows: + +@ifset use-ascii +@example +@group + +---------------------------+ + | Saved Process Controls | NFP-16 + +---------------------------+ + | Saved Arithmetic Controls | NFP-12 + +---------------------------+ + | UNUSED | NFP-8 + +---------------------------+ + | UNUSED | NFP-4 + +---------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 2.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil} +\cr +\multispan{3}\hrulefill\cr +& Saved Process Controls && NFP-16\cr +\multispan{3}\hrulefill\cr +& Saved Arithmetic Controls && NFP-12\cr +\multispan{3}\hrulefill\cr +& UNUSED && NFP-8\cr +\multispan{3}\hrulefill\cr +& UNUSED && NFP-4\cr +\multispan{3}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + +
    Saved Process ControlsNFP-16
    Saved Arithmetic ControlsNFP-12
    UNUSEDNFP-8
    UNUSEDNFP-4
    +
    +@end html +@end ifset + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Record, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Thirty-two levels (0-31) of interrupt priorities are +supported by the i960CA microprocessor with level thirty-one +(31) being the highest priority. Level zero (0) indicates that +interrupts are fully enabled. Interrupt requests for interrupts +with priorities less than or equal to the current interrupt mask +level are ignored. + +Although RTEMS supports 256 interrupt levels, the +i960CA only supports thirty-two. RTEMS interrupt levels 0 +through 31 directly correspond to i960CA interrupt levels. All +other RTEMS interrupt levels are undefined and their behavior is +unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Register Cache Flushing, 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 to level thirty-one (31) +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 i960CA with zero wait states. +These numbers will vary based the number of wait states and +processor speed present on the target board. [NOTE: This +calculation was most recently performed 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 Register Cache Flushing, Interrupt Processing Interrupt Stack, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing +@end ifinfo +@section Register Cache Flushing + +The i960CA version of the RTEMS interrupt manager is +optimized to insure that the flushreg instruction is only +executed when a context switch is necessary. The flushreg +instruction flushes the i960CA register set cache and takes (14 ++ 23 * number of sets flushed) cycles to execute. As the i960CA +supports caching of from five to sixteen register sets, this +instruction takes from 129 to 382 cycles (3.90 to 11.57 +microseconds at 33 Mhz) to execute given no wait state memory. +RTEMS flushes the register set cache only at the conclusion of +the outermost ISR when a context switch is necessary. The +register set cache will not be flushed as part of processing a +nested interrupt or when a context switch is not necessary. +This optimization is essential to providing high-performance +interrupt management on the i960CA. + +@ifinfo +@node Interrupt Processing Interrupt Stack, Default Fatal Error Processing, Interrupt Processing Register Cache Flushing, Interrupt Processing +@end ifinfo +@section Interrupt Stack + +On the i960CA, RTEMS allocates the 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. During the initialization +process, RTEMS will install its interrupt stack. + + diff --git a/doc/supplements/i960/intr_NOTIMES.t b/doc/supplements/i960/intr_NOTIMES.t new file mode 100644 index 0000000000..45b80fead9 --- /dev/null +++ b/doc/supplements/i960/intr_NOTIMES.t @@ -0,0 +1,220 @@ +@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 Record:: +* Interrupt Processing Interrupt Levels:: +* Interrupt Processing Disabling of Interrupts by RTEMS:: +* Interrupt Processing Register Cache Flushing:: +* 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 its 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 which 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 Record, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the i960CA +automatically performs the following actions: + +@itemize @bullet +@item saves the local register set, + +@item sets the Frame Pointer (FP) to point to the interrupt +stack, + +@item increments the FP by sixteen (16) to make room for the +Interrupt Record, + +@item saves the current values of the arithmetic-controls (AC) +register, the process-controls (PC) register, and the interrupt +vector number are saved in the Interrupt Record, + +@item the CPU sets the Instruction Pointer (IP) to the address +of the first instruction in the interrupt handler, + +@item the return-status field of the Previous Frame Pointer +(PFP or R0) register is set to interrupt return, + +@item sets the PC state bit to interrupted, + +@item sets the current interrupt disable level in the PC to +the level of the current interrupt, and + +@item disables tracing. +@end itemize + +A nested interrupt is processed similarly by the +i960CA with the exception that the Frame Pointer (FP) already +points to the interrupt stack. This means that the FP is NOT +overwritten before space for the Interrupt Record is allocated. + +The state flag bit of the saved PC register in the +Interrupt Record is examined by RTEMS to determine when an outer +most interrupt is being exited. Therefore, the user application +code MUST NOT modify this bit. + +@ifinfo +@node Interrupt Processing Interrupt Record, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Interrupt Record + +The structure of the Interrupt Record for the i960CA +which is placed on the interrupt stack by the processor in +response to an interrupt is as follows: + +@ifset use-ascii +@example +@group + +---------------------------+ + | Saved Process Controls | NFP-16 + +---------------------------+ + | Saved Arithmetic Controls | NFP-12 + +---------------------------+ + | UNUSED | NFP-8 + +---------------------------+ + | UNUSED | NFP-4 + +---------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 2.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil} +\cr +\multispan{3}\hrulefill\cr +& Saved Process Controls && NFP-16\cr +\multispan{3}\hrulefill\cr +& Saved Arithmetic Controls && NFP-12\cr +\multispan{3}\hrulefill\cr +& UNUSED && NFP-8\cr +\multispan{3}\hrulefill\cr +& UNUSED && NFP-4\cr +\multispan{3}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + +
    Saved Process ControlsNFP-16
    Saved Arithmetic ControlsNFP-12
    UNUSEDNFP-8
    UNUSEDNFP-4
    +
    +@end html +@end ifset + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Interrupt Record, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Thirty-two levels (0-31) of interrupt priorities are +supported by the i960CA microprocessor with level thirty-one +(31) being the highest priority. Level zero (0) indicates that +interrupts are fully enabled. Interrupt requests for interrupts +with priorities less than or equal to the current interrupt mask +level are ignored. + +Although RTEMS supports 256 interrupt levels, the +i960CA only supports thirty-two. RTEMS interrupt levels 0 +through 31 directly correspond to i960CA interrupt levels. All +other RTEMS interrupt levels are undefined and their behavior is +unpredictable. + +@ifinfo +@node Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Register Cache Flushing, 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 to level thirty-one (31) +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 i960CA with zero wait states. +These numbers will vary based the number of wait states and +processor speed present on the target board. [NOTE: This +calculation was most recently performed 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 Register Cache Flushing, Interrupt Processing Interrupt Stack, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing +@end ifinfo +@section Register Cache Flushing + +The i960CA version of the RTEMS interrupt manager is +optimized to insure that the flushreg instruction is only +executed when a context switch is necessary. The flushreg +instruction flushes the i960CA register set cache and takes (14 ++ 23 * number of sets flushed) cycles to execute. As the i960CA +supports caching of from five to sixteen register sets, this +instruction takes from 129 to 382 cycles (3.90 to 11.57 +microseconds at 33 Mhz) to execute given no wait state memory. +RTEMS flushes the register set cache only at the conclusion of +the outermost ISR when a context switch is necessary. The +register set cache will not be flushed as part of processing a +nested interrupt or when a context switch is not necessary. +This optimization is essential to providing high-performance +interrupt management on the i960CA. + +@ifinfo +@node Interrupt Processing Interrupt Stack, Default Fatal Error Processing, Interrupt Processing Register Cache Flushing, Interrupt Processing +@end ifinfo +@section Interrupt Stack + +On the i960CA, RTEMS allocates the 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. During the initialization +process, RTEMS will install its interrupt stack. + + diff --git a/doc/supplements/i960/memmodel.t b/doc/supplements/i960/memmodel.t new file mode 100644 index 0000000000..ce057bc94c --- /dev/null +++ b/doc/supplements/i960/memmodel.t @@ -0,0 +1,53 @@ +@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 Leaf Procedures, 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 + +The i960CA supports a flat 32-bit address space with +addresses ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes). +Although the i960CA reserves portions of this address space, +application code and data may be placed in any non-reserved +areas. 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), word (4 bytes), double-word (8 +bytes), triple-word (12 bytes) or quad-word (16 bytes). The +i960CA does not support virtual memory or segmentation. + +The i960CA allows the memory space to be partitioned +into sixteen regions which may be configured individually as big +or little endian. RTEMS assumes that the memory regions in +which its code, data, and the RTEMS Workspace reside are +configured as little endian. + + diff --git a/doc/supplements/i960/memmodel.texi b/doc/supplements/i960/memmodel.texi new file mode 100644 index 0000000000..ce057bc94c --- /dev/null +++ b/doc/supplements/i960/memmodel.texi @@ -0,0 +1,53 @@ +@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 Leaf Procedures, 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 + +The i960CA supports a flat 32-bit address space with +addresses ranging from 0x00000000 to 0xFFFFFFFF (4 gigabytes). +Although the i960CA reserves portions of this address space, +application code and data may be placed in any non-reserved +areas. 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), word (4 bytes), double-word (8 +bytes), triple-word (12 bytes) or quad-word (16 bytes). The +i960CA does not support virtual memory or segmentation. + +The i960CA allows the memory space to be partitioned +into sixteen regions which may be configured individually as big +or little endian. RTEMS assumes that the memory regions in +which its code, data, and the RTEMS Workspace reside are +configured as little endian. + + diff --git a/doc/supplements/i960/preface.texi b/doc/supplements/i960/preface.texi new file mode 100644 index 0000000000..713f58156a --- /dev/null +++ b/doc/supplements/i960/preface.texi @@ -0,0 +1,38 @@ +@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 i960CA and the i960 processor +family in general, refer to the following documents: + +@itemize @bullet +@item @cite{80960CA User's Manual, Intel, Order No. 270710}. + +@item @cite{32-Bit Embedded Controller Handbook, Intel, Order No. 270647}. + +@item @cite{Glenford J. Meyers and David L. Budde. The 80960 +Microprocessor Architecture. Wiley. New York. 1988}. +@end itemize + +It is highly recommended that the i960CA RTEMS +application developer obtain and become familiar with Intel's +i960CA User's Manual. + + diff --git a/doc/supplements/i960/timeCVME961.t b/doc/supplements/i960/timeCVME961.t new file mode 100644 index 0000000000..e8dd9736b1 --- /dev/null +++ b/doc/supplements/i960/timeCVME961.t @@ -0,0 +1,123 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node i960CA Timing Data, i960CA Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter Timing Data +@ifinfo +@menu +* i960CA Timing Data Introduction:: +* i960CA Timing Data Hardware Platform:: +* i960CA Timing Data Interrupt Latency:: +* i960CA Timing Data Context Switch:: +* i960CA Timing Data Directive Times:: +* i960CA Timing Data Task Manager:: +* i960CA Timing Data Interrupt Manager:: +* i960CA Timing Data Clock Manager:: +* i960CA Timing Data Timer Manager:: +* i960CA Timing Data Semaphore Manager:: +* i960CA Timing Data Message Manager:: +* i960CA Timing Data Event Manager:: +* i960CA Timing Data Signal Manager:: +* i960CA Timing Data Partition Manager:: +* i960CA Timing Data Region Manager:: +* i960CA Timing Data Dual-Ported Memory Manager:: +* i960CA Timing Data I/O Manager:: +* i960CA Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +NOTE: The i960CA board used by the RTEMS Project to +obtain i960CA times is currently broken. The information in +this chapter was obtained using Release 3.2.1. + +@ifinfo +@node i960CA Timing Data Introduction, i960CA Timing Data Hardware Platform, i960CA Timing Data, i960CA Timing Data +@end ifinfo +@section Introduction + +The timing data for the i960CA 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 i960CA version of RTEMS. + +@ifinfo +@node i960CA Timing Data Hardware Platform, i960CA Timing Data Interrupt Latency, i960CA Timing Data Introduction, i960CA Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Cyclone +Microsystems CVME961 board. The CVME961 is a 33 Mhz board with +dynamic RAM which has two wait state dynamic memory (four CPU +cycles) for read accesses and one wait state (two CPU cycles) +for write accesses. The Z8536 on a SQUALL SQSIO4 mezzanine +board was used to measure elapsed time with one-half microsecond +resolution. All sources of hardware interrupts are disabled, +although the interrupt level of the i960CA allows all interrupts. + +The maximum interrupt disable period 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 33 to simulate a +i960CA executing at 33 Mhz with zero wait states. + +@ifinfo +@node i960CA Timing Data Interrupt Latency, i960CA Timing Data Context Switch, i960CA Timing Data Hardware Platform, i960CA 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 i960CA to generate an interrupt using the sysctl +instruction, vectoring to an interrupt handler, and for the +RTEMS entry overhead before invoking the user's interrupt +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. [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 Cyclone +CVME961 benchmark platform using the sysctl instruction as the +interrupt source. + +@ifinfo +@node i960CA Timing Data Context Switch, i960CA Timing Data Directive Times, i960CA Timing Data Interrupt Latency, i960CA Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the Cyclone CVME961 benchmark platform. This +time represents the raw context switch time with no user +extensions configured. Additional execution time is required +when a TSWITCH user extension is configured. The use of the +TSWITCH extension is application dependent. Thus, its execution +time is not considered part of the base context switch time. + +The i960CA has no hardware floating point capability +and floating point tasks are not supported. + +The following table summarizes the context switch +times for the CVME961 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex + diff --git a/doc/supplements/i960/timedata.t b/doc/supplements/i960/timedata.t new file mode 100644 index 0000000000..e8dd9736b1 --- /dev/null +++ b/doc/supplements/i960/timedata.t @@ -0,0 +1,123 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node i960CA Timing Data, i960CA Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter Timing Data +@ifinfo +@menu +* i960CA Timing Data Introduction:: +* i960CA Timing Data Hardware Platform:: +* i960CA Timing Data Interrupt Latency:: +* i960CA Timing Data Context Switch:: +* i960CA Timing Data Directive Times:: +* i960CA Timing Data Task Manager:: +* i960CA Timing Data Interrupt Manager:: +* i960CA Timing Data Clock Manager:: +* i960CA Timing Data Timer Manager:: +* i960CA Timing Data Semaphore Manager:: +* i960CA Timing Data Message Manager:: +* i960CA Timing Data Event Manager:: +* i960CA Timing Data Signal Manager:: +* i960CA Timing Data Partition Manager:: +* i960CA Timing Data Region Manager:: +* i960CA Timing Data Dual-Ported Memory Manager:: +* i960CA Timing Data I/O Manager:: +* i960CA Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +NOTE: The i960CA board used by the RTEMS Project to +obtain i960CA times is currently broken. The information in +this chapter was obtained using Release 3.2.1. + +@ifinfo +@node i960CA Timing Data Introduction, i960CA Timing Data Hardware Platform, i960CA Timing Data, i960CA Timing Data +@end ifinfo +@section Introduction + +The timing data for the i960CA 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 i960CA version of RTEMS. + +@ifinfo +@node i960CA Timing Data Hardware Platform, i960CA Timing Data Interrupt Latency, i960CA Timing Data Introduction, i960CA Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Cyclone +Microsystems CVME961 board. The CVME961 is a 33 Mhz board with +dynamic RAM which has two wait state dynamic memory (four CPU +cycles) for read accesses and one wait state (two CPU cycles) +for write accesses. The Z8536 on a SQUALL SQSIO4 mezzanine +board was used to measure elapsed time with one-half microsecond +resolution. All sources of hardware interrupts are disabled, +although the interrupt level of the i960CA allows all interrupts. + +The maximum interrupt disable period 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 33 to simulate a +i960CA executing at 33 Mhz with zero wait states. + +@ifinfo +@node i960CA Timing Data Interrupt Latency, i960CA Timing Data Context Switch, i960CA Timing Data Hardware Platform, i960CA 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 i960CA to generate an interrupt using the sysctl +instruction, vectoring to an interrupt handler, and for the +RTEMS entry overhead before invoking the user's interrupt +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. [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 Cyclone +CVME961 benchmark platform using the sysctl instruction as the +interrupt source. + +@ifinfo +@node i960CA Timing Data Context Switch, i960CA Timing Data Directive Times, i960CA Timing Data Interrupt Latency, i960CA Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the Cyclone CVME961 benchmark platform. This +time represents the raw context switch time with no user +extensions configured. Additional execution time is required +when a TSWITCH user extension is configured. The use of the +TSWITCH extension is application dependent. Thus, its execution +time is not considered part of the base context switch time. + +The i960CA has no hardware floating point capability +and floating point tasks are not supported. + +The following table summarizes the context switch +times for the CVME961 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex + diff --git a/doc/supplements/m68k/MVME136_TIMES b/doc/supplements/m68k/MVME136_TIMES new file mode 100644 index 0000000000..3faa666049 --- /dev/null +++ b/doc/supplements/m68k/MVME136_TIMES @@ -0,0 +1,244 @@ +# +# M68020/MVME136 Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL MC68020 +# +# 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 20 +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD 3.2.1 +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 35 +RTEMS_RESTORE_1ST_FP_TASK 39 +RTEMS_SAVE_INIT_RESTORE_INIT 66 +RTEMS_SAVE_IDLE_RESTORE_INIT 66 +RTEMS_SAVE_IDLE_RESTORE_IDLE 68 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 148 +RTEMS_TASK_IDENT_ONLY 350 +RTEMS_TASK_START_ONLY 76 +RTEMS_TASK_RESTART_CALLING_TASK 95 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 89 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 124 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 92 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 125 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 149 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 142 +RTEMS_TASK_DELETE_CALLING_TASK 170 +RTEMS_TASK_DELETE_SUSPENDED_TASK 138 +RTEMS_TASK_DELETE_BLOCKED_TASK 143 +RTEMS_TASK_DELETE_READY_TASK 144 +RTEMS_TASK_SUSPEND_CALLING_TASK 71 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 43 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 45 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 67 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 31 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 64 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 106 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 14 +RTEMS_TASK_MODE_NO_RESCHEDULE 16 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 23 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 60 +RTEMS_TASK_GET_NOTE_ONLY 33 +RTEMS_TASK_SET_NOTE_ONLY 33 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 16 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 56 +RTEMS_TASK_WAKE_WHEN_ONLY 117 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 12 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 9 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 9 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED <1 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 8 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 54 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 86 +RTEMS_CLOCK_GET_ONLY 1 +RTEMS_CLOCK_TICK_ONLY 17 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 28 +RTEMS_TIMER_IDENT_ONLY 343 +RTEMS_TIMER_DELETE_INACTIVE 43 +RTEMS_TIMER_DELETE_ACTIVE 47 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 58 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 61 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 88 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 88 +RTEMS_TIMER_RESET_INACTIVE 54 +RTEMS_TIMER_RESET_ACTIVE 58 +RTEMS_TIMER_CANCEL_INACTIVE 31 +RTEMS_TIMER_CANCEL_ACTIVE 34 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 60 +RTEMS_SEMAPHORE_IDENT_ONLY 367 +RTEMS_SEMAPHORE_DELETE_ONLY 58 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 38 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 38 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 109 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 44 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 66 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 87 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 200 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 341 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 80 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 97 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 101 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 123 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 96 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 101 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 123 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 53 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 111 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 133 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 79 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 43 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 114 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 29 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 39 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 24 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 60 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 84 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 1 +RTEMS_EVENT_RECEIVE_AVAILABLE 28 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 23 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 84 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 15 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 37 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 55 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 37 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 54 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 70 +RTEMS_PARTITION_IDENT_ONLY 341 +RTEMS_PARTITION_DELETE_ONLY 42 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 35 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 33 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 43 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 63 +RTEMS_REGION_IDENT_ONLY 348 +RTEMS_REGION_DELETE_ONLY 39 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 52 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 49 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 123 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 54 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 114 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 136 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 35 +RTEMS_PORT_IDENT_ONLY 340 +RTEMS_PORT_DELETE_ONLY 39 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 26 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 27 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 4 +RTEMS_IO_OPEN_ONLY 2 +RTEMS_IO_CLOSE_ONLY 1 +RTEMS_IO_READ_ONLY 2 +RTEMS_IO_WRITE_ONLY 3 +RTEMS_IO_CONTROL_ONLY 2 +# +# Rate Monotonic Manager +# +RTEMS_RATE_MONOTONIC_CREATE_ONLY 32 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 341 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 39 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 51 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 48 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 54 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 74 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 31 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 723 +RTEMS_MINIMUM_CONFIGURATION 18,980 +RTEMS_MAXIMUM_CONFIGURATION 36,438 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE 12,674 +RTEMS_INITIALIZATION_CODE_SIZE 970 +RTEMS_TASK_CODE_SIZE 3,562 +RTEMS_INTERRUPT_CODE_SIZE 54 +RTEMS_CLOCK_CODE_SIZE 334 +RTEMS_TIMER_CODE_SIZE 1,110 +RTEMS_SEMAPHORE_CODE_SIZE 1,632 +RTEMS_MESSAGE_CODE_SIZE 1,754 +RTEMS_EVENT_CODE_SIZE 1,000 +RTEMS_SIGNAL_CODE_SIZE 418 +RTEMS_PARTITION_CODE_SIZE 1,164 +RTEMS_REGION_CODE_SIZE 1,494 +RTEMS_DPMEM_CODE_SIZE 724 +RTEMS_IO_CODE_SIZE 686 +RTEMS_FATAL_ERROR_CODE_SIZE 24 +RTEMS_RATE_MONOTONIC_CODE_SIZE 1,212 +RTEMS_MULTIPROCESSING_CODE_SIZE 6.952 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 184 +RTEMS_SEMAPHORE_CODE_OPTSIZE 172 +RTEMS_MESSAGE_CODE_OPTSIZE 288 +RTEMS_EVENT_CODE_OPTSIZE 56 +RTEMS_SIGNAL_CODE_OPTSIZE 56 +RTEMS_PARTITION_CODE_OPTSIZE 132 +RTEMS_REGION_CODE_OPTSIZE 160 +RTEMS_DPMEM_CODE_OPTSIZE 132 +RTEMS_IO_CODE_OPTSIZE 0 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 184 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 332 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 400 +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 332 +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 8,872 diff --git a/doc/supplements/m68k/Makefile b/doc/supplements/m68k/Makefile new file mode 100644 index 0000000000..94a56dcf99 --- /dev/null +++ b/doc/supplements/m68k/Makefile @@ -0,0 +1,87 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=m68k +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_m68k + cp c_$(PROJECT) c_$(PROJECT)-* $(INFO_INSTALL) + +c_m68k: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f c_m68k + +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 MVME136_TIMES + ${REPLACE} -p MVME136_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 MVME136_TIMES + ${REPLACE} -p MVME136_TIMES timetbl.t + mv timetbl.t.fixed timetbl.texi + +timedata.texi: timedata.t MVME136_TIMES + ${REPLACE} -p MVME136_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/MC68020 Timing Data/' \ + <../common/wksheets.t >wksheets.t + +wksheets.texi: wksheets.t MVME136_TIMES + ${REPLACE} -p MVME136_TIMES wksheets.t + mv wksheets.t.fixed wksheets.texi + +html: $(FILES) + -mkdir $(WWW_INSTALL)/c_m68k + $(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_m68k c_m68k-* + rm -f timedata.texi timetbl.texi intr.texi wksheets.texi + rm -f timetbl.t wksheets.t + rm -f *.fixed _* diff --git a/doc/supplements/m68k/bsp.t b/doc/supplements/m68k/bsp.t new file mode 100644 index 0000000000..60c889c495 --- /dev/null +++ b/doc/supplements/m68k/bsp.t @@ -0,0 +1,110 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 MC68020 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 MC68020 processor is reset. When the +MC68020 is reset, the processor performs the following actions: + +@itemize @bullet +@item The tracing bits of the status register are cleared to +disable tracing. + +@item The supervisor interrupt state is entered by setting the +supervisor (S) bit and clearing the master/interrupt (M) bit of +the status register. + +@item The interrupt mask of the status register is set to +level 7 to effectively disable all maskable interrupts. + +@item The vector base register (VBR) is set to zero. + +@item The cache control register (CACR) is set to zero to +disable and freeze the processor cache. + +@item The interrupt stack pointer (ISP) is set to the value +stored at vector 0 (bytes 0-3) of the exception vector table +(EVT). + +@item The program counter (PC) is set to the value stored at +vector 1 (bytes 4-7) of the EVT. + +@item The processor begins execution at the address stored in +the PC. +@end itemize + +@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 address of the application's initialization code +should be stored in the first vector of the EVT which will allow +the immediate vectoring to the application code. If the +application requires that the VBR be some value besides zero, +then it should be set to the required value at this point. All +tasks share the same MC68020's VBR value. Because interrupts +are enabled automatically by RTEMS as part of the initialize +executive directive, the VBR MUST be set 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. + +In addition to the requirements described 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, the MC68020 version has the following +specific requirements: + +@itemize @bullet +@item Must leave the S bit of the status register set so that +the MC68020 remains in the supervisor state. + +@item Must set the M bit of the status register to remove the +MC68020 from the interrupt state. + +@item Must set the master stack pointer (MSP) such that a +minimum stack size of MINIMUM_STACK_SIZE bytes is provided for +the initialize executive directive. + +@item Must initialize the MC68020's vector table. +@end itemize + +Note that the BSP is not responsible for allocating +or installing the interrupt stack. RTEMS does this +automatically as part of initialization. If the BSP does not +install an interrupt stack and -- for whatever reason -- an +interrupt occurs before initialize_executive is invoked, then +the results are unpredictable. + diff --git a/doc/supplements/m68k/callconv.t b/doc/supplements/m68k/callconv.t new file mode 100644 index 0000000000..2bcc2188fa --- /dev/null +++ b/doc/supplements/m68k/callconv.t @@ -0,0 +1,121 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Calling Conventions, Calling Conventions Introduction, CPU Model Dependent Features Extend Byte to Long Instruction, 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 MC68xxx architecture supports a simple yet +effective call and return mechanism. A subroutine is invoked +via the branch to subroutine (bsr) or the jump to subroutine +(jsr) instructions. These instructions push the return address +on the current stack. The return from subroutine (rts) +instruction pops the return address off the current stack and +transfers control to that instruction. It is is important to +note that the MC68xxx 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 either a bsr +or jsr instruction and return to the user application via the +rts 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 bsr and jsr instructions do +not automatically save any registers. RTEMS uses the registers +D0, D1, A0, and A1 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 bsr or jsr +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 +@group +push third argument +push second argument +push first argument +invoke directive +remove arguments from the stack +@end group +@end example + +The arguments to RTEMS are typically pushed onto the +stack using a move instruction with a pre-decremented stack +pointer as the destination. 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 current 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/m68k/cpumodel.t b/doc/supplements/m68k/cpumodel.t new file mode 100644 index 0000000000..becfcf123d --- /dev/null +++ b/doc/supplements/m68k/cpumodel.t @@ -0,0 +1,128 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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:: +* CPU Model Dependent Features BFFFO Instruction:: +* CPU Model Dependent Features Vector Base Register:: +* CPU Model Dependent Features Separate Stacks:: +* CPU Model Dependent Features Pre-Indexing Address Mode:: +* CPU Model Dependent Features Extend Byte to Long Instruction:: +@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 SPARC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/m68k/m68k.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 MC68020 +processor, this macro is set to the string "mc68020". + +@ifinfo +@node CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features BFFFO Instruction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features +@end ifinfo +@section Floating Point Unit + +The macro M68K_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. It does not matter whether the hardware floating +point support is incorporated on-chip or is an external +coprocessor. + +@ifinfo +@node CPU Model Dependent Features BFFFO Instruction, CPU Model Dependent Features Vector Base Register, CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features +@end ifinfo +@section BFFFO Instruction + +The macro M68K_HAS_BFFFO is set to 1 to indicate that +this CPU model has the bfffo instruction. + +@ifinfo +@node CPU Model Dependent Features Vector Base Register, CPU Model Dependent Features Separate Stacks, CPU Model Dependent Features BFFFO Instruction, CPU Model Dependent Features +@end ifinfo +@section Vector Base Register + +The macro M68K_HAS_VBR is set to 1 to indicate that +this CPU model has a vector base register (vbr). + +@ifinfo +@node CPU Model Dependent Features Separate Stacks, CPU Model Dependent Features Pre-Indexing Address Mode, CPU Model Dependent Features Vector Base Register, CPU Model Dependent Features +@end ifinfo +@section Separate Stacks + +The macro M68K_HAS_SEPARATE_STACKS is set to 1 to +indicate that this CPU model has separate interrupt, user, and +supervisor mode stacks. + +@ifinfo +@node CPU Model Dependent Features Pre-Indexing Address Mode, CPU Model Dependent Features Extend Byte to Long Instruction, CPU Model Dependent Features Separate Stacks, CPU Model Dependent Features +@end ifinfo +@section Pre-Indexing Address Mode + +The macro M68K_HAS_PREINDEXING is set to 1 to indicate that +this CPU model has the pre-indexing address mode. + +@ifinfo +@node CPU Model Dependent Features Extend Byte to Long Instruction, Calling Conventions, CPU Model Dependent Features Pre-Indexing Address Mode, CPU Model Dependent Features +@end ifinfo +@section Extend Byte to Long Instruction + +The macro M68K_HAS_EXTB_L is set to 1 to indicate that this CPU model +has the extb.l instruction. This instruction is supposed to be available +in all models based on the cpu32 core as well as mc68020 and up models. diff --git a/doc/supplements/m68k/cputable.t b/doc/supplements/m68k/cputable.t new file mode 100644 index 0000000000..0119084d32 --- /dev/null +++ b/doc/supplements/m68k/cputable.t @@ -0,0 +1,118 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 MC68xxx version of the RTEMS CPU Dependent +Information Table contains the information required to interface +a Board Support Package and RTEMS on the MC68xxx. This +information is provided to allow RTEMS to interoperate +effectively with the BSP. The C structure definition is given +here: + +@example +@group +struct cpu_configuration_table @{ + 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 */ + + m68k_isr *interrupt_vector_table; +@}; +@end group +@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_vector_table +is the base address of the CPU's Exception Vector Table. + +@end table diff --git a/doc/supplements/m68k/fatalerr.t b/doc/supplements/m68k/fatalerr.t new file mode 100644 index 0000000000..5b94c7a9c9 --- /dev/null +++ b/doc/supplements/m68k/fatalerr.t @@ -0,0 +1,44 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 to +level 7, places the error code in D0, and executes a stop +instruction to simulate a halt processor instruction. + diff --git a/doc/supplements/m68k/intr_NOTIMES.t b/doc/supplements/m68k/intr_NOTIMES.t new file mode 100644 index 0000000000..07e51b0116 --- /dev/null +++ b/doc/supplements/m68k/intr_NOTIMES.t @@ -0,0 +1,230 @@ +@c +@c +@c Interrupt Stack Frame Picture +@c + +@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 an Interrupt Handler:: +* 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 an Interrupt Handler, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurrence of an interrupt in its 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 MC68xxx's +interrupt response and control mechanisms as they pertain to +RTEMS. + +@ifinfo +@node Interrupt Processing Vectoring of an Interrupt Handler, Models Without Separate Interrupt Stacks, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Vectoring of an Interrupt Handler +@ifinfo +@menu +* Models Without Separate Interrupt Stacks:: +* Models With Separate Interrupt Stacks:: +@end menu +@end ifinfo + +Depending on whether or not the particular CPU +supports a separate interrupt stack, the MC68xxx family has two +different interrupt handling models. + +@ifinfo +@node Models Without Separate Interrupt Stacks, Models With Separate Interrupt Stacks, Interrupt Processing Vectoring of an Interrupt Handler, Interrupt Processing Vectoring of an Interrupt Handler +@end ifinfo +@subsection Models Without Separate Interrupt Stacks + +Upon receipt of an interrupt the MC68xxx family +members without separate interrupt stacks automatically perform +the following actions: + +@itemize @bullet +@item To Be Written +@end itemize + +@ifinfo +@node Models With Separate Interrupt Stacks, Interrupt Processing Interrupt Levels, Models Without Separate Interrupt Stacks, Interrupt Processing Vectoring of an Interrupt Handler +@end ifinfo +@subsection Models With Separate Interrupt Stacks + +Upon receipt of an interrupt the MC68xxx family +members with separate interrupt stacks automatically perform the +following actions: + +@itemize @bullet +@item saves the current status register (SR), + +@item clears the master/interrupt (M) bit of the SR to +indicate the switch from master state to interrupt state, + +@item sets the privilege mode to supervisor, + +@item suppresses tracing, + +@item sets the interrupt mask level equal to the level of the +interrupt being serviced, + +@item pushes an interrupt stack frame (ISF), which includes +the program counter (PC), the status register (SR), and the +format/exception vector offset (FVO) word, onto the supervisor +and interrupt stacks, + +@item switches the current stack to the interrupt stack and +vectors to an interrupt service routine (ISR). If the ISR was +installed with the interrupt_catch directive, then the RTEMS +interrupt handler will begin execution. The RTEMS interrupt +handler saves all registers which are not preserved according to +the calling conventions and invokes the application's ISR. +@end itemize + +A nested interrupt is processed similarly by these +CPU models with the exception that only a single ISF is placed +on the interrupt stack and the current stack need not be +switched. + +The FVO word in the Interrupt Stack Frame is examined +by RTEMS to determine when an outer most interrupt is being +exited. Since the FVO is used by RTEMS for this purpose, the +user application code MUST NOT modify this field. + +The following shows the Interrupt Stack Frame for +MC68xxx CPU models with separate interrupt stacks: + +@ifset use-ascii +@example +@group + +----------------------+ + | Status Register | 0x0 + +----------------------+ + | Program Counter High | 0x2 + +----------------------+ + | Program Counter Low | 0x4 + +----------------------+ + | Format/Vector Offset | 0x6 + +----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 2.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil} +\cr +\multispan{3}\hrulefill\cr +& Status Register && 0x0\cr +\multispan{3}\hrulefill\cr +& Program Counter High && 0x2\cr +\multispan{3}\hrulefill\cr +& Program Counter Low && 0x4\cr +\multispan{3}\hrulefill\cr +& Format/Vector Offset && 0x6\cr +\multispan{3}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + +
    Status Register0x0
    Program Counter High0x2
    Program Counter Low0x4
    Format/Vector Offset0x6
    +
    +@end html +@end ifset + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Models With Separate Interrupt Stacks, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Eight levels (0-7) of interrupt priorities are +supported by MC68xxx family members with level seven (7) being +the highest priority. Level zero (0) indicates that interrupts +are fully enabled. Interrupt requests for interrupts with +priorities less than or equal to the current interrupt mask +level are ignored. + +Although RTEMS supports 256 interrupt levels, the +MC68xxx family only supports eight. RTEMS interrupt levels 0 +through 7 directly correspond to MC68xxx interrupt levels. 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 to level seven (7) 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 MC68020 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 is hand calculated. This +calculation was last performed 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 + +RTEMS allocates the 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. During the initialization +process, RTEMS will install its interrupt stack. + +The MC68xxx port of RTEMS supports a software managed +dedicated interrupt stack on those CPU models which do not +support a separate interrupt stack in hardware. + + diff --git a/doc/supplements/m68k/m68k.texi b/doc/supplements/m68k/m68k.texi new file mode 100644 index 0000000000..157dabb594 --- /dev/null +++ b/doc/supplements/m68k/m68k.texi @@ -0,0 +1,118 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_m68k +@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 Motorola MC68xxx C Applications Supplement +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS Motorola MC68xxx C Applications Supplement (m68k): +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 Motorola MC68xxx C Applications Supplement + +@setchapternewpage odd +@settitle RTEMS Motorola MC68xxx C Applications Supplement +@titlepage +@finalout + +@title RTEMS Motorola MC68xxx 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_m68k + +This is the online version of the RTEMS Motorola MC68xxx 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:: +* MC68020 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, MC68020 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/m68k/memmodel.t b/doc/supplements/m68k/memmodel.t new file mode 100644 index 0000000000..91ccf8010d --- /dev/null +++ b/doc/supplements/m68k/memmodel.t @@ -0,0 +1,52 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 + +The MC68xxx family 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, word (2-bytes), or long word (4 bytes). Memory +accesses within this address space are performed in big endian +fashion by the processors in this family. + +Some of the MC68xxx family members such as the +MC68020, MC68030, and MC68040 support virtual memory and +segmentation. The MC68020 requires external hardware support +such as the MC68851 Paged Memory Management Unit coprocessor +which is typically used to perform address translations for +these systems. RTEMS does not support virtual memory or +segmentation on any of the MC68xxx family members. + diff --git a/doc/supplements/m68k/preface.texi b/doc/supplements/m68k/preface.texi new file mode 100644 index 0000000000..e42754c347 --- /dev/null +++ b/doc/supplements/m68k/preface.texi @@ -0,0 +1,58 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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. + +This document discusses the Motorola MC68xxx +architecture dependencies in this port of RTEMS. The MC68xxx +family has a wide variety of CPU models within it. The part +numbers for these models are generally divided into MC680xx and +MC683xx. The MC680xx models are more general purpose processors +with no integrated peripherals. The MC683xx models, on the +other hand, are more specialized and have a variety of +peripherals on chip including sophisticated timers and serial +communications controllers. + +It is highly recommended that the Motorola MC68xxx +RTEMS application developer obtain and become familiar with the +documentation for the processor being used as well as the +documentation for the family as a whole. + +@subheading Architecture Documents + +For information on the Motorola MC68xxx architecture, +refer to the following documents available from Motorola +(@file{http//www.moto.com/}): + +@itemize @bullet +@item @cite{M68000 Family Reference, Motorola, FR68K/D}. +@end itemize + +@subheading MODEL SPECIFIC DOCUMENTS + +For information on specific processor models and +their associated coprocessors, refer to the following documents: + +@itemize @bullet +@item @cite{MC68020 User's Manual, Motorola, MC68020UM/AD}. + +@item @cite{MC68881/MC68882 Floating-Point Coprocessor User's +Manual, Motorola, MC68881UM/AD}. +@end itemize + diff --git a/doc/supplements/m68k/timeMVME136.t b/doc/supplements/m68k/timeMVME136.t new file mode 100644 index 0000000000..fe99c38fef --- /dev/null +++ b/doc/supplements/m68k/timeMVME136.t @@ -0,0 +1,143 @@ + +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node MC68020 Timing Data, MC68020 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter MC68020 Timing Data +@ifinfo +@menu +* MC68020 Timing Data Introduction:: +* MC68020 Timing Data Hardware Platform:: +* MC68020 Timing Data Interrupt Latency:: +* MC68020 Timing Data Context Switch:: +* MC68020 Timing Data Directive Times:: +* MC68020 Timing Data Task Manager:: +* MC68020 Timing Data Interrupt Manager:: +* MC68020 Timing Data Clock Manager:: +* MC68020 Timing Data Timer Manager:: +* MC68020 Timing Data Semaphore Manager:: +* MC68020 Timing Data Message Manager:: +* MC68020 Timing Data Event Manager:: +* MC68020 Timing Data Signal Manager:: +* MC68020 Timing Data Partition Manager:: +* MC68020 Timing Data Region Manager:: +* MC68020 Timing Data Dual-Ported Memory Manager:: +* MC68020 Timing Data I/O Manager:: +* MC68020 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node MC68020 Timing Data Introduction, MC68020 Timing Data Hardware Platform, MC68020 Timing Data, MC68020 Timing Data +@end ifinfo +@section Introduction + +The timing data for the MC68020 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 MC68020 version of RTEMS. + +@ifinfo +@node MC68020 Timing Data Hardware Platform, MC68020 Timing Data Interrupt Latency, MC68020 Timing Data Introduction, MC68020 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Motorola +MVME135 CPU board. The MVME135 is a 20Mhz board with one wait +state dynamic memory and a MC68881 numeric coprocessor. The +Zilog 8036 countdown timer on this board was used to measure +elapsed time with a one-half microsecond resolution. All +sources of hardware interrupts were disabled, although the +interrupt level of the MC68020 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. The worst case times of the MC68020 microprocessor +were used for each instruction. 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 20 to simulate a 20Mhz MC68020. It +should be noted that the worst case instruction times for the +MC68020 assume that the internal cache is disabled and that no +instructions overlap. + +@ifinfo +@node MC68020 Timing Data Interrupt Latency, MC68020 Timing Data Context Switch, MC68020 Timing Data Hardware Platform, MC68020 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 MC68020 to vector an interrupt and for the RTEMS entry +overhead before invoking the user's interrupt 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 20Mhz. [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 is hand-timed and based upon +worst case (i.e. CPU cache disabled and no instruction overlap) +times for a 20Mhz MC68020. The interrupt vector and entry +overhead time was generated on an MVME135 benchmark platform +using the Multiprocessing Communications registers to generate +as the interrupt source. + +@ifinfo +@node MC68020 Timing Data Context Switch, MC68020 Timing Data Directive Times, MC68020 Timing Data Interrupt Latency, MC68020 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the MVME135 benchmark platform when no floating +point context is saved or restored. 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. 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. + +The exact amount of time required to save and restore +floating point context is dependent on whether an MC68881 or +MC68882 is being used as well as the state of the numeric +coprocessor. These numeric coprocessors define three operating +states: initialized, idle, and busy. 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 MVME135 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex diff --git a/doc/supplements/m68k/timedata.t b/doc/supplements/m68k/timedata.t new file mode 100644 index 0000000000..fe99c38fef --- /dev/null +++ b/doc/supplements/m68k/timedata.t @@ -0,0 +1,143 @@ + +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node MC68020 Timing Data, MC68020 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter MC68020 Timing Data +@ifinfo +@menu +* MC68020 Timing Data Introduction:: +* MC68020 Timing Data Hardware Platform:: +* MC68020 Timing Data Interrupt Latency:: +* MC68020 Timing Data Context Switch:: +* MC68020 Timing Data Directive Times:: +* MC68020 Timing Data Task Manager:: +* MC68020 Timing Data Interrupt Manager:: +* MC68020 Timing Data Clock Manager:: +* MC68020 Timing Data Timer Manager:: +* MC68020 Timing Data Semaphore Manager:: +* MC68020 Timing Data Message Manager:: +* MC68020 Timing Data Event Manager:: +* MC68020 Timing Data Signal Manager:: +* MC68020 Timing Data Partition Manager:: +* MC68020 Timing Data Region Manager:: +* MC68020 Timing Data Dual-Ported Memory Manager:: +* MC68020 Timing Data I/O Manager:: +* MC68020 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node MC68020 Timing Data Introduction, MC68020 Timing Data Hardware Platform, MC68020 Timing Data, MC68020 Timing Data +@end ifinfo +@section Introduction + +The timing data for the MC68020 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 MC68020 version of RTEMS. + +@ifinfo +@node MC68020 Timing Data Hardware Platform, MC68020 Timing Data Interrupt Latency, MC68020 Timing Data Introduction, MC68020 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported except for the maximum period +interrupts are disabled by RTEMS were measured using a Motorola +MVME135 CPU board. The MVME135 is a 20Mhz board with one wait +state dynamic memory and a MC68881 numeric coprocessor. The +Zilog 8036 countdown timer on this board was used to measure +elapsed time with a one-half microsecond resolution. All +sources of hardware interrupts were disabled, although the +interrupt level of the MC68020 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. The worst case times of the MC68020 microprocessor +were used for each instruction. 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 20 to simulate a 20Mhz MC68020. It +should be noted that the worst case instruction times for the +MC68020 assume that the internal cache is disabled and that no +instructions overlap. + +@ifinfo +@node MC68020 Timing Data Interrupt Latency, MC68020 Timing Data Context Switch, MC68020 Timing Data Hardware Platform, MC68020 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 MC68020 to vector an interrupt and for the RTEMS entry +overhead before invoking the user's interrupt 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 20Mhz. [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 is hand-timed and based upon +worst case (i.e. CPU cache disabled and no instruction overlap) +times for a 20Mhz MC68020. The interrupt vector and entry +overhead time was generated on an MVME135 benchmark platform +using the Multiprocessing Communications registers to generate +as the interrupt source. + +@ifinfo +@node MC68020 Timing Data Context Switch, MC68020 Timing Data Directive Times, MC68020 Timing Data Interrupt Latency, MC68020 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is RTEMS_NO_FP_CONTEXTS +microseconds on the MVME135 benchmark platform when no floating +point context is saved or restored. 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. 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. + +The exact amount of time required to save and restore +floating point context is dependent on whether an MC68881 or +MC68882 is being used as well as the state of the numeric +coprocessor. These numeric coprocessors define three operating +states: initialized, idle, and busy. 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 MVME135 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex diff --git a/doc/supplements/sparc/ERC32_TIMES b/doc/supplements/sparc/ERC32_TIMES new file mode 100644 index 0000000000..5edd01c56f --- /dev/null +++ b/doc/supplements/sparc/ERC32_TIMES @@ -0,0 +1,244 @@ +# +# SPARC/ERC32/SIS Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL ERC32 +# +# 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 15.0 +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD 3.5.17 +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 21 +RTEMS_RESTORE_1ST_FP_TASK 26 +RTEMS_SAVE_INIT_RESTORE_INIT 24 +RTEMS_SAVE_IDLE_RESTORE_INIT 23 +RTEMS_SAVE_IDLE_RESTORE_IDLE 33 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 59 +RTEMS_TASK_IDENT_ONLY 163 +RTEMS_TASK_START_ONLY 30 +RTEMS_TASK_RESTART_CALLING_TASK 64 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 36 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 47 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 37 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 77 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 84 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 75 +RTEMS_TASK_DELETE_CALLING_TASK 91 +RTEMS_TASK_DELETE_SUSPENDED_TASK 47 +RTEMS_TASK_DELETE_BLOCKED_TASK 50 +RTEMS_TASK_DELETE_READY_TASK 51 +RTEMS_TASK_SUSPEND_CALLING_TASK 56 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 16 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 17 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 52 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 10 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 25 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 67 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 5 +RTEMS_TASK_MODE_NO_RESCHEDULE 6 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 9 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 42 +RTEMS_TASK_GET_NOTE_ONLY 10 +RTEMS_TASK_SET_NOTE_ONLY 10 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 6 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 49 +RTEMS_TASK_WAKE_WHEN_ONLY 75 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 7 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 8 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 8 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 5 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 7 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 14 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 33 +RTEMS_CLOCK_GET_ONLY 4 +RTEMS_CLOCK_TICK_ONLY 6 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 11 +RTEMS_TIMER_IDENT_ONLY 159 +RTEMS_TIMER_DELETE_INACTIVE 15 +RTEMS_TIMER_DELETE_ACTIVE 17 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 21 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 23 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 34 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 34 +RTEMS_TIMER_RESET_INACTIVE 20 +RTEMS_TIMER_RESET_ACTIVE 22 +RTEMS_TIMER_CANCEL_INACTIVE 10 +RTEMS_TIMER_CANCEL_ACTIVE 13 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 19 +RTEMS_SEMAPHORE_IDENT_ONLY 171 +RTEMS_SEMAPHORE_DELETE_ONLY 19 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 12 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 12 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 14 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 23 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 57 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 114 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 159 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 25 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 36 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 38 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 36 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 38 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 15 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 42 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 83 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 30 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 13 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 9 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 13 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 9 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 22 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 58 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 1 +RTEMS_EVENT_RECEIVE_AVAILABLE 10 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 9 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 60 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 6 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 14 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 22 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 27 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 56 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 34 +RTEMS_PARTITION_IDENT_ONLY 159 +RTEMS_PARTITION_DELETE_ONLY 14 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 12 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 10 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 16 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 22 +RTEMS_REGION_IDENT_ONLY 162 +RTEMS_REGION_DELETE_ONLY 14 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 19 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 19 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 17 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 44 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 77 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 14 +RTEMS_PORT_IDENT_ONLY 159 +RTEMS_PORT_DELETE_ONLY 13 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 9 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 9 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 2 +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 12 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 159 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 14 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 19 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 16 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 20 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 55 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 9 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 9059 +RTEMS_MINIMUM_CONFIGURATION 28,288 +RTEMS_MAXIMUM_CONFIGURATION 50,432 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE 20,336 +RTEMS_INITIALIZATION_CODE_SIZE 1,408 +RTEMS_TASK_CODE_SIZE 4,496 +RTEMS_INTERRUPT_CODE_SIZE 72 +RTEMS_CLOCK_CODE_SIZE 576 +RTEMS_TIMER_CODE_SIZE 1,336 +RTEMS_SEMAPHORE_CODE_SIZE 1,888 +RTEMS_MESSAGE_CODE_SIZE 2,032 +RTEMS_EVENT_CODE_SIZE 1,696 +RTEMS_SIGNAL_CODE_SIZE 664 +RTEMS_PARTITION_CODE_SIZE 1,368 +RTEMS_REGION_CODE_SIZE 1,736 +RTEMS_DPMEM_CODE_SIZE 872 +RTEMS_IO_CODE_SIZE 1,144 +RTEMS_FATAL_ERROR_CODE_SIZE 32 +RTEMS_RATE_MONOTONIC_CODE_SIZE 1,656 +RTEMS_MULTIPROCESSING_CODE_SIZE 8,328 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 208 +RTEMS_SEMAPHORE_CODE_OPTSIZE 192 +RTEMS_MESSAGE_CODE_OPTSIZE 320 +RTEMS_EVENT_CODE_OPTSIZE 64 +RTEMS_SIGNAL_CODE_OPTSIZE 64 +RTEMS_PARTITION_CODE_OPTSIZE 152 +RTEMS_REGION_CODE_OPTSIZE 176 +RTEMS_DPMEM_CODE_OPTSIZE 152 +RTEMS_IO_CODE_OPTSIZE 0 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 208 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 408 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 488 +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 136 +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 10,072 diff --git a/doc/supplements/sparc/Makefile b/doc/supplements/sparc/Makefile new file mode 100644 index 0000000000..510ab94d83 --- /dev/null +++ b/doc/supplements/sparc/Makefile @@ -0,0 +1,90 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=sparc +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: + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: c_sparc + cp c_$(PROJECT) c_$(PROJECT)-* $(INFO_INSTALL) + +c_sparc: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f c_sparc + +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 SIS_TIMES + ${REPLACE} -p SIS_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 SIS_TIMES + ${REPLACE} -p SIS_TIMES timetbl.t + mv timetbl.t.fixed timetbl.texi + +timedata.texi: timedata.t SIS_TIMES + ${REPLACE} -p SIS_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/ERC32 Timing Data/' \ + <../common/wksheets.t >wksheets.t + +wksheets.texi: wksheets.t SIS_TIMES + ${REPLACE} -p SIS_TIMES wksheets.t + mv wksheets.t.fixed wksheets.texi + +html: $(FILES) + -mkdir $(WWW_INSTALL)/c_sparc + $(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_sparc c_sparc-* + rm -f timedata.texi timetbl.texi intr.texi wksheets.texi + rm -f timetbl.t wksheets.t + rm -f *.fixed _* + diff --git a/doc/supplements/sparc/SIS_TIMES b/doc/supplements/sparc/SIS_TIMES new file mode 100644 index 0000000000..5edd01c56f --- /dev/null +++ b/doc/supplements/sparc/SIS_TIMES @@ -0,0 +1,244 @@ +# +# SPARC/ERC32/SIS Timing and Size Information +# + +# +# CPU Model Information +# +RTEMS_CPU_MODEL ERC32 +# +# 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 15.0 +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD 3.5.17 +# +# Context Switch Times +# +RTEMS_NO_FP_CONTEXTS 21 +RTEMS_RESTORE_1ST_FP_TASK 26 +RTEMS_SAVE_INIT_RESTORE_INIT 24 +RTEMS_SAVE_IDLE_RESTORE_INIT 23 +RTEMS_SAVE_IDLE_RESTORE_IDLE 33 +# +# Task Manager Times +# +RTEMS_TASK_CREATE_ONLY 59 +RTEMS_TASK_IDENT_ONLY 163 +RTEMS_TASK_START_ONLY 30 +RTEMS_TASK_RESTART_CALLING_TASK 64 +RTEMS_TASK_RESTART_SUSPENDED_RETURNS_TO_CALLER 36 +RTEMS_TASK_RESTART_BLOCKED_RETURNS_TO_CALLER 47 +RTEMS_TASK_RESTART_READY_RETURNS_TO_CALLER 37 +RTEMS_TASK_RESTART_SUSPENDED_PREEMPTS_CALLER 77 +RTEMS_TASK_RESTART_BLOCKED_PREEMPTS_CALLER 84 +RTEMS_TASK_RESTART_READY_PREEMPTS_CALLER 75 +RTEMS_TASK_DELETE_CALLING_TASK 91 +RTEMS_TASK_DELETE_SUSPENDED_TASK 47 +RTEMS_TASK_DELETE_BLOCKED_TASK 50 +RTEMS_TASK_DELETE_READY_TASK 51 +RTEMS_TASK_SUSPEND_CALLING_TASK 56 +RTEMS_TASK_SUSPEND_RETURNS_TO_CALLER 16 +RTEMS_TASK_RESUME_TASK_READIED_RETURNS_TO_CALLER 17 +RTEMS_TASK_RESUME_TASK_READIED_PREEMPTS_CALLER 52 +RTEMS_TASK_SET_PRIORITY_OBTAIN_CURRENT_PRIORITY 10 +RTEMS_TASK_SET_PRIORITY_RETURNS_TO_CALLER 25 +RTEMS_TASK_SET_PRIORITY_PREEMPTS_CALLER 67 +RTEMS_TASK_MODE_OBTAIN_CURRENT_MODE 5 +RTEMS_TASK_MODE_NO_RESCHEDULE 6 +RTEMS_TASK_MODE_RESCHEDULE_RETURNS_TO_CALLER 9 +RTEMS_TASK_MODE_RESCHEDULE_PREEMPTS_CALLER 42 +RTEMS_TASK_GET_NOTE_ONLY 10 +RTEMS_TASK_SET_NOTE_ONLY 10 +RTEMS_TASK_WAKE_AFTER_YIELD_RETURNS_TO_CALLER 6 +RTEMS_TASK_WAKE_AFTER_YIELD_PREEMPTS_CALLER 49 +RTEMS_TASK_WAKE_WHEN_ONLY 75 +# +# Interrupt Manager +# +RTEMS_INTR_ENTRY_RETURNS_TO_NESTED 7 +RTEMS_INTR_ENTRY_RETURNS_TO_INTERRUPTED_TASK 8 +RTEMS_INTR_ENTRY_RETURNS_TO_PREEMPTING_TASK 8 +RTEMS_INTR_EXIT_RETURNS_TO_NESTED 5 +RTEMS_INTR_EXIT_RETURNS_TO_INTERRUPTED_TASK 7 +RTEMS_INTR_EXIT_RETURNS_TO_PREEMPTING_TASK 14 +# +# Clock Manager +# +RTEMS_CLOCK_SET_ONLY 33 +RTEMS_CLOCK_GET_ONLY 4 +RTEMS_CLOCK_TICK_ONLY 6 +# +# Timer Manager +# +RTEMS_TIMER_CREATE_ONLY 11 +RTEMS_TIMER_IDENT_ONLY 159 +RTEMS_TIMER_DELETE_INACTIVE 15 +RTEMS_TIMER_DELETE_ACTIVE 17 +RTEMS_TIMER_FIRE_AFTER_INACTIVE 21 +RTEMS_TIMER_FIRE_AFTER_ACTIVE 23 +RTEMS_TIMER_FIRE_WHEN_INACTIVE 34 +RTEMS_TIMER_FIRE_WHEN_ACTIVE 34 +RTEMS_TIMER_RESET_INACTIVE 20 +RTEMS_TIMER_RESET_ACTIVE 22 +RTEMS_TIMER_CANCEL_INACTIVE 10 +RTEMS_TIMER_CANCEL_ACTIVE 13 +# +# Semaphore Manager +# +RTEMS_SEMAPHORE_CREATE_ONLY 19 +RTEMS_SEMAPHORE_IDENT_ONLY 171 +RTEMS_SEMAPHORE_DELETE_ONLY 19 +RTEMS_SEMAPHORE_OBTAIN_AVAILABLE 12 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_NO_WAIT 12 +RTEMS_SEMAPHORE_OBTAIN_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_SEMAPHORE_RELEASE_NO_WAITING_TASKS 14 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_RETURNS_TO_CALLER 23 +RTEMS_SEMAPHORE_RELEASE_TASK_READIED_PREEMPTS_CALLER 57 +# +# Message Manager +# +RTEMS_MESSAGE_QUEUE_CREATE_ONLY 114 +RTEMS_MESSAGE_QUEUE_IDENT_ONLY 159 +RTEMS_MESSAGE_QUEUE_DELETE_ONLY 25 +RTEMS_MESSAGE_QUEUE_SEND_NO_WAITING_TASKS 36 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_RETURNS_TO_CALLER 38 +RTEMS_MESSAGE_QUEUE_SEND_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_URGENT_NO_WAITING_TASKS 36 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_RETURNS_TO_CALLER 38 +RTEMS_MESSAGE_QUEUE_URGENT_TASK_READIED_PREEMPTS_CALLER 76 +RTEMS_MESSAGE_QUEUE_BROADCAST_NO_WAITING_TASKS 15 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_RETURNS_TO_CALLER 42 +RTEMS_MESSAGE_QUEUE_BROADCAST_TASK_READIED_PREEMPTS_CALLER 83 +RTEMS_MESSAGE_QUEUE_RECEIVE_AVAILABLE 30 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_NO_WAIT 13 +RTEMS_MESSAGE_QUEUE_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_MESSAGE_QUEUE_FLUSH_NO_MESSAGES_FLUSHED 9 +RTEMS_MESSAGE_QUEUE_FLUSH_MESSAGES_FLUSHED 13 +# +# Event Manager +# +RTEMS_EVENT_SEND_NO_TASK_READIED 9 +RTEMS_EVENT_SEND_TASK_READIED_RETURNS_TO_CALLER 22 +RTEMS_EVENT_SEND_TASK_READIED_PREEMPTS_CALLER 58 +RTEMS_EVENT_RECEIVE_OBTAIN_CURRENT_EVENTS 1 +RTEMS_EVENT_RECEIVE_AVAILABLE 10 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_NO_WAIT 9 +RTEMS_EVENT_RECEIVE_NOT_AVAILABLE_CALLER_BLOCKS 60 +# +# Signal Manager +# +RTEMS_SIGNAL_CATCH_ONLY 6 +RTEMS_SIGNAL_SEND_RETURNS_TO_CALLER 14 +RTEMS_SIGNAL_SEND_SIGNAL_TO_SELF 22 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_CALLING_TASK 27 +RTEMS_SIGNAL_EXIT_ASR_OVERHEAD_RETURNS_TO_PREEMPTING_TASK 56 +# +# Partition Manager +# +RTEMS_PARTITION_CREATE_ONLY 34 +RTEMS_PARTITION_IDENT_ONLY 159 +RTEMS_PARTITION_DELETE_ONLY 14 +RTEMS_PARTITION_GET_BUFFER_AVAILABLE 12 +RTEMS_PARTITION_GET_BUFFER_NOT_AVAILABLE 10 +RTEMS_PARTITION_RETURN_BUFFER_ONLY 16 +# +# Region Manager +# +RTEMS_REGION_CREATE_ONLY 22 +RTEMS_REGION_IDENT_ONLY 162 +RTEMS_REGION_DELETE_ONLY 14 +RTEMS_REGION_GET_SEGMENT_AVAILABLE 19 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_NO_WAIT 19 +RTEMS_REGION_GET_SEGMENT_NOT_AVAILABLE_CALLER_BLOCKS 67 +RTEMS_REGION_RETURN_SEGMENT_NO_WAITING_TASKS 17 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_RETURNS_TO_CALLER 44 +RTEMS_REGION_RETURN_SEGMENT_TASK_READIED_PREEMPTS_CALLER 77 +# +# Dual-Ported Memory Manager +# +RTEMS_PORT_CREATE_ONLY 14 +RTEMS_PORT_IDENT_ONLY 159 +RTEMS_PORT_DELETE_ONLY 13 +RTEMS_PORT_INTERNAL_TO_EXTERNAL_ONLY 9 +RTEMS_PORT_EXTERNAL_TO_INTERNAL_ONLY 9 +# +# IO Manager +# +RTEMS_IO_INITIALIZE_ONLY 2 +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 12 +RTEMS_RATE_MONOTONIC_IDENT_ONLY 159 +RTEMS_RATE_MONOTONIC_CANCEL_ONLY 14 +RTEMS_RATE_MONOTONIC_DELETE_ACTIVE 19 +RTEMS_RATE_MONOTONIC_DELETE_INACTIVE 16 +RTEMS_RATE_MONOTONIC_PERIOD_INITIATE_PERIOD_RETURNS_TO_CALLER 20 +RTEMS_RATE_MONOTONIC_PERIOD_CONCLUDE_PERIOD_CALLER_BLOCKS 55 +RTEMS_RATE_MONOTONIC_PERIOD_OBTAIN_STATUS 9 +# +# Size Information +# +# +# xxx alloted for numbers +# +RTEMS_DATA_SPACE 9059 +RTEMS_MINIMUM_CONFIGURATION 28,288 +RTEMS_MAXIMUM_CONFIGURATION 50,432 +# x,xxx alloted for numbers +RTEMS_CORE_CODE_SIZE 20,336 +RTEMS_INITIALIZATION_CODE_SIZE 1,408 +RTEMS_TASK_CODE_SIZE 4,496 +RTEMS_INTERRUPT_CODE_SIZE 72 +RTEMS_CLOCK_CODE_SIZE 576 +RTEMS_TIMER_CODE_SIZE 1,336 +RTEMS_SEMAPHORE_CODE_SIZE 1,888 +RTEMS_MESSAGE_CODE_SIZE 2,032 +RTEMS_EVENT_CODE_SIZE 1,696 +RTEMS_SIGNAL_CODE_SIZE 664 +RTEMS_PARTITION_CODE_SIZE 1,368 +RTEMS_REGION_CODE_SIZE 1,736 +RTEMS_DPMEM_CODE_SIZE 872 +RTEMS_IO_CODE_SIZE 1,144 +RTEMS_FATAL_ERROR_CODE_SIZE 32 +RTEMS_RATE_MONOTONIC_CODE_SIZE 1,656 +RTEMS_MULTIPROCESSING_CODE_SIZE 8,328 +# xxx alloted for numbers +RTEMS_TIMER_CODE_OPTSIZE 208 +RTEMS_SEMAPHORE_CODE_OPTSIZE 192 +RTEMS_MESSAGE_CODE_OPTSIZE 320 +RTEMS_EVENT_CODE_OPTSIZE 64 +RTEMS_SIGNAL_CODE_OPTSIZE 64 +RTEMS_PARTITION_CODE_OPTSIZE 152 +RTEMS_REGION_CODE_OPTSIZE 176 +RTEMS_DPMEM_CODE_OPTSIZE 152 +RTEMS_IO_CODE_OPTSIZE 0 +RTEMS_RATE_MONOTONIC_CODE_OPTSIZE 208 +RTEMS_MULTIPROCESSING_CODE_OPTSIZE 408 +# xxx alloted for numbers +RTEMS_BYTES_PER_TASK 488 +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 136 +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 10,072 diff --git a/doc/supplements/sparc/bsp.t b/doc/supplements/sparc/bsp.t new file mode 100644 index 0000000000..78ffa3ac26 --- /dev/null +++ b/doc/supplements/sparc/bsp.t @@ -0,0 +1,103 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 SPARC 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 SPARC processor is reset. When the SPARC +is reset, the processor performs the following actions: + +@itemize @bullet +@item the enable trap (ET) of the psr is set to 0 to disable +traps, + +@item the supervisor bit (S) of the psr is set to 1 to enter +supervisor mode, and + +@item the PC is set 0 and the nPC is set to 4. +@end itemize + +The processor then begins to execute the code at +location 0. It is important to note that all fields in the psr +are not explicitly set by the above steps and all other +registers retain their value from the previous execution mode. +This is true even of the Trap Base Register (TBR) whose contents +reflect the last trap which occurred before the reset. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +It is the responsibility of the application's +initialization code to initialize the TBR and install trap +handlers for at least the register window overflow and register +window underflow conditions. Traps should be enabled before +invoking any subroutines to allow for register window +management. However, interrupts should be disabled by setting +the Processor Interrupt Level (pil) field of the psr to 15. +RTEMS installs it's own Trap Table as part of initialization +which is initialized with the contents of the Trap Table in +place when the rtems_initialize_executive directive was invoked. +Upon completion of executive initialization, interrupts are +enabled. + +If this SPARC implementation supports on-chip caching +and this is to be utilized, then it should be enabled during the +reset application initialization code. + +In addition to the requirements described in the +Board Support Packages chapter of the C Applications User's +Manual for the reset code which is executed before the call to +rtems_initialize executive, the SPARC version has the following +specific requirements: + +@itemize @bullet +@item Must leave the S bit of the status register set so that +the SPARC remains in the supervisor state. + +@item Must set stack pointer (sp) such that a minimum stack +size of MINIMUM_STACK_SIZE bytes is provided for the +rtems_initialize executive directive. + +@item Must disable all external interrupts (i.e. set the pil +to 15). + +@item Must enable traps so window overflow and underflow +conditions can be properly handled. + +@item Must initialize the SPARC's initial trap table with at +least trap handlers for register window overflow and register +window underflow. +@end itemize + diff --git a/doc/supplements/sparc/bsp.texi b/doc/supplements/sparc/bsp.texi new file mode 100644 index 0000000000..78ffa3ac26 --- /dev/null +++ b/doc/supplements/sparc/bsp.texi @@ -0,0 +1,103 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 SPARC 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 SPARC processor is reset. When the SPARC +is reset, the processor performs the following actions: + +@itemize @bullet +@item the enable trap (ET) of the psr is set to 0 to disable +traps, + +@item the supervisor bit (S) of the psr is set to 1 to enter +supervisor mode, and + +@item the PC is set 0 and the nPC is set to 4. +@end itemize + +The processor then begins to execute the code at +location 0. It is important to note that all fields in the psr +are not explicitly set by the above steps and all other +registers retain their value from the previous execution mode. +This is true even of the Trap Base Register (TBR) whose contents +reflect the last trap which occurred before the reset. + +@ifinfo +@node Board Support Packages Processor Initialization, Processor Dependent Information Table, Board Support Packages System Reset, Board Support Packages +@end ifinfo +@section Processor Initialization + +It is the responsibility of the application's +initialization code to initialize the TBR and install trap +handlers for at least the register window overflow and register +window underflow conditions. Traps should be enabled before +invoking any subroutines to allow for register window +management. However, interrupts should be disabled by setting +the Processor Interrupt Level (pil) field of the psr to 15. +RTEMS installs it's own Trap Table as part of initialization +which is initialized with the contents of the Trap Table in +place when the rtems_initialize_executive directive was invoked. +Upon completion of executive initialization, interrupts are +enabled. + +If this SPARC implementation supports on-chip caching +and this is to be utilized, then it should be enabled during the +reset application initialization code. + +In addition to the requirements described in the +Board Support Packages chapter of the C Applications User's +Manual for the reset code which is executed before the call to +rtems_initialize executive, the SPARC version has the following +specific requirements: + +@itemize @bullet +@item Must leave the S bit of the status register set so that +the SPARC remains in the supervisor state. + +@item Must set stack pointer (sp) such that a minimum stack +size of MINIMUM_STACK_SIZE bytes is provided for the +rtems_initialize executive directive. + +@item Must disable all external interrupts (i.e. set the pil +to 15). + +@item Must enable traps so window overflow and underflow +conditions can be properly handled. + +@item Must initialize the SPARC's initial trap table with at +least trap handlers for register window overflow and register +window underflow. +@end itemize + diff --git a/doc/supplements/sparc/callconv.t b/doc/supplements/sparc/callconv.t new file mode 100644 index 0000000000..fd9b9a5846 --- /dev/null +++ b/doc/supplements/sparc/callconv.t @@ -0,0 +1,445 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 Implementation Notes, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Programming Model:: +* Calling Conventions Register Windows:: +* Calling Conventions Call and Return Mechanism:: +* 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 Programming Model, 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 Programming Model, Non-Floating Point Registers, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Programming Model +@ifinfo +@menu +* Non-Floating Point Registers:: +* Floating Point Registers:: +* Special Registers:: +@end menu +@end ifinfo + +This section discusses the programming model for the +SPARC architecture. + +@ifinfo +@node Non-Floating Point Registers, Floating Point Registers, Calling Conventions Programming Model, Calling Conventions Programming Model +@end ifinfo +@subsection Non-Floating Point Registers + +The SPARC architecture defines thirty-two +non-floating point registers directly visible to the programmer. +These are divided into four sets: + +@itemize @bullet +@item input registers + +@item local registers + +@item output registers + +@item global registers +@end itemize + +Each register is referred to by either two or three +names in the SPARC reference manuals. First, the registers are +referred to as r0 through r31 or with the alternate notation +r[0] through r[31]. Second, each register is a member of one of +the four sets listed above. Finally, some registers have an +architecturally defined role in the programming model which +provides an alternate name. The following table describes the +mapping between the 32 registers and the register sets: + +@ifset use-ascii +@example +@group + +-----------------+----------------+------------------+ + | Register Number | Register Names | Description | + +-----------------+----------------+------------------+ + | 0 - 7 | g0 - g7 | Global Registers | + +-----------------+----------------+------------------+ + | 8 - 15 | o0 - o7 | Output Registers | + +-----------------+----------------+------------------+ + | 16 - 23 | l0 - l7 | Local Registers | + +-----------------+----------------+------------------+ + | 24 - 31 | i0 - i7 | Input Registers | + +-----------------+----------------+------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Number &&\bf Register Names&&\bf Description&\cr\noalign{\hrule} +&0 - 7&&g0 - g7&&Global Registers&\cr\noalign{\hrule} +&8 - 15&&o0 - o7&&Output Registers&\cr\noalign{\hrule} +&16 - 23&&l0 - l7&&Local Registers&\cr\noalign{\hrule} +&24 - 31&&i0 - i7&&Input Registers&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + +
    Register NumberRegister NamesDescription
    0 - 7g0 - g7Global Registers
    8 - 15o0 - o7Output Registers
    16 - 23l0 - l7Local Registers
    24 - 31i0 - i7Input Registers
    +
    +@end html +@end ifset + +As mentioned above, some of the registers serve +defined roles in the programming model. The following table +describes the role of each of these registers: + +@ifset use-ascii +@example +@group + +---------------+----------------+----------------------+ + | Register Name | Alternate Name | Description | + +---------------+----------------+----------------------+ + | g0 | na | reads return 0 | + | | | writes are ignored | + +---------------+----------------+----------------------+ + | o6 | sp | stack pointer | + +---------------+----------------+----------------------+ + | i6 | fp | frame pointer | + +---------------+----------------+----------------------+ + | i7 | na | return address | + +---------------+----------------+----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule} +&g0&&NA&&reads return 0; &\cr +&&&&&writes are ignored&\cr\noalign{\hrule} +&o6&&sp&&stack pointer&\cr\noalign{\hrule} +&i6&&fp&&frame pointer&\cr\noalign{\hrule} +&i7&&NA&&return address&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + +
    Register NameAlternate NameDescription
    g0NAreads return 0 ; writes are ignored
    o6spstack pointer
    i6fpframe pointer
    i7NAreturn address
    +
    +@end html +@end ifset + + +@ifinfo +@node Floating Point Registers, Special Registers, Non-Floating Point Registers, Calling Conventions Programming Model +@end ifinfo +@subsection Floating Point Registers + +The SPARC V7 architecture includes thirty-two, +thirty-two bit registers. These registers may be viewed as +follows: + +@itemize @bullet +@item 32 single precision floating point or integer registers +(f0, f1, ... f31) + +@item 16 double precision floating point registers (f0, f2, +f4, ... f30) + +@item 8 extended precision floating point registers (f0, f4, +f8, ... f28) +@end itemize + +The floating point status register (fpsr) specifies +the behavior of the floating point unit for rounding, contains +its condition codes, version specification, and trap information. + +A queue of the floating point instructions which have +started execution but not yet completed is maintained. This +queue is needed to support the multiple cycle nature of floating +point operations and to aid floating point exception trap +handlers. Once a floating point exception has been encountered, +the queue is frozen until it is emptied by the trap handler. +The floating point queue is loaded by launching instructions. +It is emptied normally when the floating point completes all +outstanding instructions and by floating point exception +handlers with the store double floating point queue (stdfq) +instruction. + +@ifinfo +@node Special Registers, Calling Conventions Register Windows, Floating Point Registers, Calling Conventions Programming Model +@end ifinfo +@subsection Special Registers + +The SPARC architecture includes two special registers +which are critical to the programming model: the Processor State +Register (psr) and the Window Invalid Mask (wim). The psr +contains the condition codes, processor interrupt level, trap +enable bit, supervisor mode and previous supervisor mode bits, +version information, floating point unit and coprocessor enable +bits, and the current window pointer (cwp). The cwp field of +the psr and wim register are used to manage the register windows +in the SPARC architecture. The register windows are discussed +in more detail below. + +@ifinfo +@node Calling Conventions Register Windows, Calling Conventions Call and Return Mechanism, Special Registers, Calling Conventions +@end ifinfo +@section Register Windows + +The SPARC architecture includes the concept of +register windows. An overly simplistic way to think of these +windows is to imagine them as being an infinite supply of +"fresh" register sets available for each subroutine to use. In +reality, they are much more complicated. + +The save instruction is used to obtain a new register +window. This instruction decrements the current window pointer, +thus providing a new set of registers for use. This register +set includes eight fresh local registers for use exclusively by +this subroutine. When done with a register set, the restore +instruction increments the current window pointer and the +previous register set is once again available. + +The two primary issues complicating the use of +register windows are that (1) the set of register windows is +finite, and (2) some registers are shared between adjacent +registers windows. + +Because the set of register windows is finite, it is +possible to execute enough save instructions without +corresponding restore's to consume all of the register windows. +This is easily accomplished in a high level language because +each subroutine typically performs a save instruction upon +entry. Thus having a subroutine call depth greater than the +number of register windows will result in a window overflow +condition. The window overflow condition generates a trap which +must be handled in software. The window overflow trap handler +is responsible for saving the contents of the oldest register +window on the program stack. + +Similarly, the subroutines will eventually complete +and begin to perform restore's. If the restore results in the +need for a register window which has previously been written to +memory as part of an overflow, then a window underflow condition +results. Just like the window overflow, the window underflow +condition must be handled in software by a trap handler. The +window underflow trap handler is responsible for reloading the +contents of the register window requested by the restore +instruction from the program stack. + +The Window Invalid Mask (wim) and the Current Window +Pointer (cwp) field in the psr are used in conjunction to manage +the finite set of register windows and detect the window +overflow and underflow conditions. The cwp contains the index +of the register window currently in use. The save instruction +decrements the cwp modulo the number of register windows. +Similarly, the restore instruction increments the cwp modulo the +number of register windows. Each bit in the wim represents +represents whether a register window contains valid information. +The value of 0 indicates the register window is valid and 1 +indicates it is invalid. When a save instruction causes the cwp +to point to a register window which is marked as invalid, a +window overflow condition results. Conversely, the restore +instruction may result in a window underflow condition. + +Other than the assumption that a register window is +always available for trap (i.e. interrupt) handlers, the SPARC +architecture places no limits on the number of register windows +simultaneously marked as invalid (i.e. number of bits set in the +wim). However, RTEMS assumes that only one register window is +marked invalid at a time (i.e. only one bit set in the wim). +This makes the maximum possible number of register windows +available to the user while still meeting the requirement that +window overflow and underflow conditions can be detected. + +The window overflow and window underflow trap +handlers are a critical part of the run-time environment for a +SPARC application. The SPARC architectural specification allows +for the number of register windows to be any power of two less +than or equal to 32. The most common choice for SPARC +implementations appears to be 8 register windows. This results +in the cwp ranging in value from 0 to 7 on most implementations. + + +The second complicating factor is the sharing of +registers between adjacent register windows. While each +register window has its own set of local registers, the input +and output registers are shared between adjacent windows. The +output registers for register window N are the same as the input +registers for register window ((N - 1) modulo RW) where RW is +the number of register windows. An alternative way to think of +this is to remember how parameters are passed to a subroutine on +the SPARC. The caller loads values into what are its output +registers. Then after the callee executes a save instruction, +those parameters are available in its input registers. This is +a very efficient way to pass parameters as no data is actually +moved by the save or restore instructions. + +@ifinfo +@node Calling Conventions Call and Return Mechanism, Calling Conventions Calling Mechanism, Calling Conventions Register Windows, Calling Conventions +@end ifinfo +@section Call and Return Mechanism + +The SPARC architecture supports a simple yet +effective call and return mechanism. A subroutine is invoked +via the call (call) instruction. This instruction places the +return address in the caller's output register 7 (o7). After +the callee executes a save instruction, this value is available +in input register 7 (i7) until the corresponding restore +instruction is executed. + +The callee returns to the caller via a jmp to the +return address. There is a delay slot following this +instruction which is commonly used to execute a restore +instruction -- if a register window was allocated by this +subroutine. + +It is important to note that the SPARC subroutine +call and return mechanism does not automatically save and +restore any registers. This is accomplished via the save and +restore instructions which manage the set of registers windows. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Call and Return Mechanism, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked using the regular +SPARC calling convention via the call 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. The save and restore +instructions are used to allocate and deallocate register +windows. When a register window is allocated, the new set of +local registers are available for the exclusive use of the +subroutine which allocated this register set. + +@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 in the +caller's output registers with the first argument in output +register 0 (o0), the second argument in output register 1 (o1), +and so forth. Until the callee executes a save instruction, the +parameters are still visible in the output registers. After the +callee executes a save instruction, the parameters are visible +in the corresponding input registers. The following pseudo-code +illustrates the typical sequence used to call a RTEMS directive +with three (3) arguments: + +@example +load third argument into o2 +load second argument into o1 +load first argument into o0 +invoke directive +@end example + +@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/sparc/callconv.texi b/doc/supplements/sparc/callconv.texi new file mode 100644 index 0000000000..fd9b9a5846 --- /dev/null +++ b/doc/supplements/sparc/callconv.texi @@ -0,0 +1,445 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 Implementation Notes, Top +@end ifinfo +@chapter Calling Conventions +@ifinfo +@menu +* Calling Conventions Introduction:: +* Calling Conventions Programming Model:: +* Calling Conventions Register Windows:: +* Calling Conventions Call and Return Mechanism:: +* 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 Programming Model, 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 Programming Model, Non-Floating Point Registers, Calling Conventions Introduction, Calling Conventions +@end ifinfo +@section Programming Model +@ifinfo +@menu +* Non-Floating Point Registers:: +* Floating Point Registers:: +* Special Registers:: +@end menu +@end ifinfo + +This section discusses the programming model for the +SPARC architecture. + +@ifinfo +@node Non-Floating Point Registers, Floating Point Registers, Calling Conventions Programming Model, Calling Conventions Programming Model +@end ifinfo +@subsection Non-Floating Point Registers + +The SPARC architecture defines thirty-two +non-floating point registers directly visible to the programmer. +These are divided into four sets: + +@itemize @bullet +@item input registers + +@item local registers + +@item output registers + +@item global registers +@end itemize + +Each register is referred to by either two or three +names in the SPARC reference manuals. First, the registers are +referred to as r0 through r31 or with the alternate notation +r[0] through r[31]. Second, each register is a member of one of +the four sets listed above. Finally, some registers have an +architecturally defined role in the programming model which +provides an alternate name. The following table describes the +mapping between the 32 registers and the register sets: + +@ifset use-ascii +@example +@group + +-----------------+----------------+------------------+ + | Register Number | Register Names | Description | + +-----------------+----------------+------------------+ + | 0 - 7 | g0 - g7 | Global Registers | + +-----------------+----------------+------------------+ + | 8 - 15 | o0 - o7 | Output Registers | + +-----------------+----------------+------------------+ + | 16 - 23 | l0 - l7 | Local Registers | + +-----------------+----------------+------------------+ + | 24 - 31 | i0 - i7 | Input Registers | + +-----------------+----------------+------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Number &&\bf Register Names&&\bf Description&\cr\noalign{\hrule} +&0 - 7&&g0 - g7&&Global Registers&\cr\noalign{\hrule} +&8 - 15&&o0 - o7&&Output Registers&\cr\noalign{\hrule} +&16 - 23&&l0 - l7&&Local Registers&\cr\noalign{\hrule} +&24 - 31&&i0 - i7&&Input Registers&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + +
    Register NumberRegister NamesDescription
    0 - 7g0 - g7Global Registers
    8 - 15o0 - o7Output Registers
    16 - 23l0 - l7Local Registers
    24 - 31i0 - i7Input Registers
    +
    +@end html +@end ifset + +As mentioned above, some of the registers serve +defined roles in the programming model. The following table +describes the role of each of these registers: + +@ifset use-ascii +@example +@group + +---------------+----------------+----------------------+ + | Register Name | Alternate Name | Description | + +---------------+----------------+----------------------+ + | g0 | na | reads return 0 | + | | | writes are ignored | + +---------------+----------------+----------------------+ + | o6 | sp | stack pointer | + +---------------+----------------+----------------------+ + | i6 | fp | frame pointer | + +---------------+----------------+----------------------+ + | i7 | na | return address | + +---------------+----------------+----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule} +&g0&&NA&&reads return 0; &\cr +&&&&&writes are ignored&\cr\noalign{\hrule} +&o6&&sp&&stack pointer&\cr\noalign{\hrule} +&i6&&fp&&frame pointer&\cr\noalign{\hrule} +&i7&&NA&&return address&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + +
    Register NameAlternate NameDescription
    g0NAreads return 0 ; writes are ignored
    o6spstack pointer
    i6fpframe pointer
    i7NAreturn address
    +
    +@end html +@end ifset + + +@ifinfo +@node Floating Point Registers, Special Registers, Non-Floating Point Registers, Calling Conventions Programming Model +@end ifinfo +@subsection Floating Point Registers + +The SPARC V7 architecture includes thirty-two, +thirty-two bit registers. These registers may be viewed as +follows: + +@itemize @bullet +@item 32 single precision floating point or integer registers +(f0, f1, ... f31) + +@item 16 double precision floating point registers (f0, f2, +f4, ... f30) + +@item 8 extended precision floating point registers (f0, f4, +f8, ... f28) +@end itemize + +The floating point status register (fpsr) specifies +the behavior of the floating point unit for rounding, contains +its condition codes, version specification, and trap information. + +A queue of the floating point instructions which have +started execution but not yet completed is maintained. This +queue is needed to support the multiple cycle nature of floating +point operations and to aid floating point exception trap +handlers. Once a floating point exception has been encountered, +the queue is frozen until it is emptied by the trap handler. +The floating point queue is loaded by launching instructions. +It is emptied normally when the floating point completes all +outstanding instructions and by floating point exception +handlers with the store double floating point queue (stdfq) +instruction. + +@ifinfo +@node Special Registers, Calling Conventions Register Windows, Floating Point Registers, Calling Conventions Programming Model +@end ifinfo +@subsection Special Registers + +The SPARC architecture includes two special registers +which are critical to the programming model: the Processor State +Register (psr) and the Window Invalid Mask (wim). The psr +contains the condition codes, processor interrupt level, trap +enable bit, supervisor mode and previous supervisor mode bits, +version information, floating point unit and coprocessor enable +bits, and the current window pointer (cwp). The cwp field of +the psr and wim register are used to manage the register windows +in the SPARC architecture. The register windows are discussed +in more detail below. + +@ifinfo +@node Calling Conventions Register Windows, Calling Conventions Call and Return Mechanism, Special Registers, Calling Conventions +@end ifinfo +@section Register Windows + +The SPARC architecture includes the concept of +register windows. An overly simplistic way to think of these +windows is to imagine them as being an infinite supply of +"fresh" register sets available for each subroutine to use. In +reality, they are much more complicated. + +The save instruction is used to obtain a new register +window. This instruction decrements the current window pointer, +thus providing a new set of registers for use. This register +set includes eight fresh local registers for use exclusively by +this subroutine. When done with a register set, the restore +instruction increments the current window pointer and the +previous register set is once again available. + +The two primary issues complicating the use of +register windows are that (1) the set of register windows is +finite, and (2) some registers are shared between adjacent +registers windows. + +Because the set of register windows is finite, it is +possible to execute enough save instructions without +corresponding restore's to consume all of the register windows. +This is easily accomplished in a high level language because +each subroutine typically performs a save instruction upon +entry. Thus having a subroutine call depth greater than the +number of register windows will result in a window overflow +condition. The window overflow condition generates a trap which +must be handled in software. The window overflow trap handler +is responsible for saving the contents of the oldest register +window on the program stack. + +Similarly, the subroutines will eventually complete +and begin to perform restore's. If the restore results in the +need for a register window which has previously been written to +memory as part of an overflow, then a window underflow condition +results. Just like the window overflow, the window underflow +condition must be handled in software by a trap handler. The +window underflow trap handler is responsible for reloading the +contents of the register window requested by the restore +instruction from the program stack. + +The Window Invalid Mask (wim) and the Current Window +Pointer (cwp) field in the psr are used in conjunction to manage +the finite set of register windows and detect the window +overflow and underflow conditions. The cwp contains the index +of the register window currently in use. The save instruction +decrements the cwp modulo the number of register windows. +Similarly, the restore instruction increments the cwp modulo the +number of register windows. Each bit in the wim represents +represents whether a register window contains valid information. +The value of 0 indicates the register window is valid and 1 +indicates it is invalid. When a save instruction causes the cwp +to point to a register window which is marked as invalid, a +window overflow condition results. Conversely, the restore +instruction may result in a window underflow condition. + +Other than the assumption that a register window is +always available for trap (i.e. interrupt) handlers, the SPARC +architecture places no limits on the number of register windows +simultaneously marked as invalid (i.e. number of bits set in the +wim). However, RTEMS assumes that only one register window is +marked invalid at a time (i.e. only one bit set in the wim). +This makes the maximum possible number of register windows +available to the user while still meeting the requirement that +window overflow and underflow conditions can be detected. + +The window overflow and window underflow trap +handlers are a critical part of the run-time environment for a +SPARC application. The SPARC architectural specification allows +for the number of register windows to be any power of two less +than or equal to 32. The most common choice for SPARC +implementations appears to be 8 register windows. This results +in the cwp ranging in value from 0 to 7 on most implementations. + + +The second complicating factor is the sharing of +registers between adjacent register windows. While each +register window has its own set of local registers, the input +and output registers are shared between adjacent windows. The +output registers for register window N are the same as the input +registers for register window ((N - 1) modulo RW) where RW is +the number of register windows. An alternative way to think of +this is to remember how parameters are passed to a subroutine on +the SPARC. The caller loads values into what are its output +registers. Then after the callee executes a save instruction, +those parameters are available in its input registers. This is +a very efficient way to pass parameters as no data is actually +moved by the save or restore instructions. + +@ifinfo +@node Calling Conventions Call and Return Mechanism, Calling Conventions Calling Mechanism, Calling Conventions Register Windows, Calling Conventions +@end ifinfo +@section Call and Return Mechanism + +The SPARC architecture supports a simple yet +effective call and return mechanism. A subroutine is invoked +via the call (call) instruction. This instruction places the +return address in the caller's output register 7 (o7). After +the callee executes a save instruction, this value is available +in input register 7 (i7) until the corresponding restore +instruction is executed. + +The callee returns to the caller via a jmp to the +return address. There is a delay slot following this +instruction which is commonly used to execute a restore +instruction -- if a register window was allocated by this +subroutine. + +It is important to note that the SPARC subroutine +call and return mechanism does not automatically save and +restore any registers. This is accomplished via the save and +restore instructions which manage the set of registers windows. + +@ifinfo +@node Calling Conventions Calling Mechanism, Calling Conventions Register Usage, Calling Conventions Call and Return Mechanism, Calling Conventions +@end ifinfo +@section Calling Mechanism + +All RTEMS directives are invoked using the regular +SPARC calling convention via the call 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. The save and restore +instructions are used to allocate and deallocate register +windows. When a register window is allocated, the new set of +local registers are available for the exclusive use of the +subroutine which allocated this register set. + +@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 in the +caller's output registers with the first argument in output +register 0 (o0), the second argument in output register 1 (o1), +and so forth. Until the callee executes a save instruction, the +parameters are still visible in the output registers. After the +callee executes a save instruction, the parameters are visible +in the corresponding input registers. The following pseudo-code +illustrates the typical sequence used to call a RTEMS directive +with three (3) arguments: + +@example +load third argument into o2 +load second argument into o1 +load first argument into o0 +invoke directive +@end example + +@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/sparc/cpumodel.t b/doc/supplements/sparc/cpumodel.t new file mode 100644 index 0000000000..6f137ad48d --- /dev/null +++ b/doc/supplements/sparc/cpumodel.t @@ -0,0 +1,169 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 Feature Flags:: +* CPU Model Dependent Features CPU Model Implementation Notes:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Feature Flags, 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. + +@ifinfo +@node CPU Model Dependent Features CPU Model Feature Flags, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Feature Flags +@ifinfo +@menu +* CPU Model Dependent Features CPU Model Name:: +* CPU Model Dependent Features Floating Point Unit:: +* CPU Model Dependent Features Bitscan Instruction:: +* CPU Model Dependent Features Number of Register Windows:: +* CPU Model Dependent Features Low Power Mode:: +@end menu +@end ifinfo + +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 section presents the set of features which vary +across SPARC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/sparc/sparc.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 CPU Model Feature Flags, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the European Space +Agency's ERC32 SPARC model, this macro is set to the string +"erc32". + +@ifinfo +@node CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Floating Point Unit + +The macro SPARC_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. + +@ifinfo +@node CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Bitscan Instruction + +The macro SPARC_HAS_BITSCAN is set to 1 to indicate +that this CPU model has the bitscan instruction. For example, +this instruction is supported by the Fujitsu SPARClite family. + +@ifinfo +@node CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Number of Register Windows + +The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to +indicate the number of register window sets implemented by this +CPU model. The SPARC architecture allows a for a maximum of +thirty-two register window sets although most implementations +only include eight. + +@ifinfo +@node CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features CPU Model Implementation Notes, CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Low Power Mode + +The macro SPARC_HAS_LOW_POWER_MODE is set to one to +indicate that this CPU model has a low power mode. If low power +is enabled, then there must be CPU model specific implementation +of the IDLE task in c/src/exec/score/cpu/sparc/cpu.c. The low +power mode IDLE task should be of the form: + +@example +while ( TRUE ) @{ + enter low power mode +@} +@end example + +The code required to enter low power mode is CPU model specific. + +@ifinfo +@node CPU Model Dependent Features CPU Model Implementation Notes, Calling Conventions, CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features +@end ifinfo +@section CPU Model Implementation Notes + +The ERC is a custom SPARC V7 implementation based on the Cypress 601/602 +chipset. This CPU has a number of on-board peripherals and was developed by +the European Space Agency to target space applications. RTEMS currently +provides support for the following peripherals: + +@itemize @bullet +@item UART Channels A and B +@item General Purpose Timer +@item Real Time Clock +@item Watchdog Timer (so it can be disabled) +@item Control Register (so powerdown mode can be enabled) +@item Memory Control Register +@item Interrupt Control +@end itemize + +The General Purpose Timer and Real Time Clock Timer provided with the ERC32 +share the Timer Control Register. Because the Timer Control Register is write +only, we must mirror it in software and insure that writes to one timer do not +alter the current settings and status of the other timer. Routines are +provided in erc32.h which promote the view that the two timers are completely +independent. By exclusively using these routines to access the Timer Control +Register, the application can view the system as having a General Purpose +Timer Control Register and a Real Time Clock Timer Control Register +rather than the single shared value. + +The RTEMS Idle thread take advantage of the low power mode provided by the +ERC32. Low power mode is entered during idle loops and is enabled at +initialization time. diff --git a/doc/supplements/sparc/cpumodel.texi b/doc/supplements/sparc/cpumodel.texi new file mode 100644 index 0000000000..6f137ad48d --- /dev/null +++ b/doc/supplements/sparc/cpumodel.texi @@ -0,0 +1,169 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 Feature Flags:: +* CPU Model Dependent Features CPU Model Implementation Notes:: +@end menu +@end ifinfo + +@ifinfo +@node CPU Model Dependent Features Introduction, CPU Model Dependent Features CPU Model Feature Flags, 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. + +@ifinfo +@node CPU Model Dependent Features CPU Model Feature Flags, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features Introduction, CPU Model Dependent Features +@end ifinfo +@section CPU Model Feature Flags +@ifinfo +@menu +* CPU Model Dependent Features CPU Model Name:: +* CPU Model Dependent Features Floating Point Unit:: +* CPU Model Dependent Features Bitscan Instruction:: +* CPU Model Dependent Features Number of Register Windows:: +* CPU Model Dependent Features Low Power Mode:: +@end menu +@end ifinfo + +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 section presents the set of features which vary +across SPARC implementations and are of importance to RTEMS. +The set of CPU model feature macros are defined in the file +c/src/exec/score/cpu/sparc/sparc.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 CPU Model Feature Flags, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection CPU Model Name + +The macro CPU_MODEL_NAME is a string which designates +the name of this CPU model. For example, for the European Space +Agency's ERC32 SPARC model, this macro is set to the string +"erc32". + +@ifinfo +@node CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features CPU Model Name, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Floating Point Unit + +The macro SPARC_HAS_FPU is set to 1 to indicate that +this CPU model has a hardware floating point unit and 0 +otherwise. + +@ifinfo +@node CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features Floating Point Unit, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Bitscan Instruction + +The macro SPARC_HAS_BITSCAN is set to 1 to indicate +that this CPU model has the bitscan instruction. For example, +this instruction is supported by the Fujitsu SPARClite family. + +@ifinfo +@node CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features Bitscan Instruction, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Number of Register Windows + +The macro SPARC_NUMBER_OF_REGISTER_WINDOWS is set to +indicate the number of register window sets implemented by this +CPU model. The SPARC architecture allows a for a maximum of +thirty-two register window sets although most implementations +only include eight. + +@ifinfo +@node CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features CPU Model Implementation Notes, CPU Model Dependent Features Number of Register Windows, CPU Model Dependent Features CPU Model Feature Flags +@end ifinfo +@subsection Low Power Mode + +The macro SPARC_HAS_LOW_POWER_MODE is set to one to +indicate that this CPU model has a low power mode. If low power +is enabled, then there must be CPU model specific implementation +of the IDLE task in c/src/exec/score/cpu/sparc/cpu.c. The low +power mode IDLE task should be of the form: + +@example +while ( TRUE ) @{ + enter low power mode +@} +@end example + +The code required to enter low power mode is CPU model specific. + +@ifinfo +@node CPU Model Dependent Features CPU Model Implementation Notes, Calling Conventions, CPU Model Dependent Features Low Power Mode, CPU Model Dependent Features +@end ifinfo +@section CPU Model Implementation Notes + +The ERC is a custom SPARC V7 implementation based on the Cypress 601/602 +chipset. This CPU has a number of on-board peripherals and was developed by +the European Space Agency to target space applications. RTEMS currently +provides support for the following peripherals: + +@itemize @bullet +@item UART Channels A and B +@item General Purpose Timer +@item Real Time Clock +@item Watchdog Timer (so it can be disabled) +@item Control Register (so powerdown mode can be enabled) +@item Memory Control Register +@item Interrupt Control +@end itemize + +The General Purpose Timer and Real Time Clock Timer provided with the ERC32 +share the Timer Control Register. Because the Timer Control Register is write +only, we must mirror it in software and insure that writes to one timer do not +alter the current settings and status of the other timer. Routines are +provided in erc32.h which promote the view that the two timers are completely +independent. By exclusively using these routines to access the Timer Control +Register, the application can view the system as having a General Purpose +Timer Control Register and a Real Time Clock Timer Control Register +rather than the single shared value. + +The RTEMS Idle thread take advantage of the low power mode provided by the +ERC32. Low power mode is entered during idle loops and is enabled at +initialization time. diff --git a/doc/supplements/sparc/cputable.t b/doc/supplements/sparc/cputable.t new file mode 100644 index 0000000000..6aabd6cfa5 --- /dev/null +++ b/doc/supplements/sparc/cputable.t @@ -0,0 +1,109 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 SPARC version of the RTEMS CPU Dependent +Information Table is given by the C structure definition is +shown below: + +@example +struct cpu_configuration_table @{ + 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 */ + +@}; +@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. + +@end table + diff --git a/doc/supplements/sparc/cputable.texi b/doc/supplements/sparc/cputable.texi new file mode 100644 index 0000000000..6aabd6cfa5 --- /dev/null +++ b/doc/supplements/sparc/cputable.texi @@ -0,0 +1,109 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 SPARC version of the RTEMS CPU Dependent +Information Table is given by the C structure definition is +shown below: + +@example +struct cpu_configuration_table @{ + 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 */ + +@}; +@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. + +@end table + diff --git a/doc/supplements/sparc/fatalerr.t b/doc/supplements/sparc/fatalerr.t new file mode 100644 index 0000000000..1406097f3a --- /dev/null +++ b/doc/supplements/sparc/fatalerr.t @@ -0,0 +1,45 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 to +level 15, places the error code in g1, and goes into an infinite +loop to simulate a halt processor instruction. + + diff --git a/doc/supplements/sparc/fatalerr.texi b/doc/supplements/sparc/fatalerr.texi new file mode 100644 index 0000000000..1406097f3a --- /dev/null +++ b/doc/supplements/sparc/fatalerr.texi @@ -0,0 +1,45 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 to +level 15, places the error code in g1, and goes into an infinite +loop to simulate a halt processor instruction. + + diff --git a/doc/supplements/sparc/intr.t b/doc/supplements/sparc/intr.t new file mode 100644 index 0000000000..73224c1008 --- /dev/null +++ b/doc/supplements/sparc/intr.t @@ -0,0 +1,226 @@ +@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 Synchronous Versus Asynchronous Traps:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Traps and Register Windows:: +* 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 Synchronous Versus Asynchronous Traps, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurrence of an interrupt in its 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 SPARC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +RTEMS and associated documentation uses the terms +interrupt and vector. In the SPARC architecture, these terms +correspond to traps and trap type, respectively. The terms will +be used interchangeably in this manual. + +@ifinfo +@node Interrupt Processing Synchronous Versus Asynchronous Traps, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Synchronous Versus Asynchronous Traps + +The SPARC architecture includes two classes of traps: +synchronous and asynchronous. Asynchronous traps occur when an +external event interrupts the processor. These traps are not +associated with any instruction executed by the processor and +logically occur between instructions. The instruction currently +in the execute stage of the processor is allowed to complete +although subsequent instructions are annulled. The return +address reported by the processor for asynchronous traps is the +pair of instructions following the current instruction. + +Synchronous traps are caused by the actions of an +instruction. The trap stimulus in this case either occurs +internally to the processor or is from an external signal that +was provoked by the instruction. These traps are taken +immediately and the instruction that caused the trap is aborted +before any state changes occur in the processor itself. The +return address reported by the processor for synchronous traps +is the instruction which caused the trap and the following +instruction. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Traps and Register Windows, Interrupt Processing Synchronous Versus Asynchronous Traps, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the SPARC automatically +performs the following actions: + +@itemize @bullet +@item disables traps (sets the ET bit of the psr to 0), + +@item the S bit of the psr is copied into the Previous +Supervisor Mode (PS) bit of the psr, + +@item the cwp is decremented by one (modulo the number of +register windows) to activate a trap window, + +@item the PC and nPC are loaded into local register 1 and 2 +(l0 and l1), + +@item the trap type (tt) field of the Trap Base Register (TBR) +is set to the appropriate value, and + +@item if the trap is not a reset, then the PC is written with +the contents of the TBR and the nPC is written with TBR + 4. If +the trap is a reset, then the PC is set to zero and the nPC is +set to 4. +@end itemize + +Trap processing on the SPARC has two features which +are noticeably different than interrupt processing on other +architectures. First, the value of psr register in effect +immediately before the trap occurred is not explicitly saved. +Instead only reversible alterations are made to it. Second, the +Processor Interrupt Level (pil) is not set to correspond to that +of the interrupt being processed. When a trap occurs, ALL +subsequent traps are disabled. In order to safely invoke a +subroutine during trap handling, traps must be enabled to allow +for the possibility of register window overflow and underflow +traps. + +If the interrupt handler was installed as an RTEMS +interrupt handler, then upon receipt of the interrupt, the +processor passes control to the RTEMS interrupt handler which +performs the following actions: + +@itemize @bullet +@item saves the state of the interrupted task on it's stack, + +@item insures that a register window is available for +subsequent traps, + +@item if this is the outermost (i.e. non-nested) interrupt, +then the RTEMS interrupt handler switches from the current stack +to the interrupt stack, + +@item enables traps, + +@item invokes the vectors to a user interrupt service routine (ISR). +@end itemize + +Asynchronous interrupts are ignored while traps are +disabled. Synchronous traps which occur while traps are +disabled result in the CPU being forced into an error mode. + +A nested interrupt is processed similarly with the +exception that the current stack need not be switched to the +interrupt stack. + +@ifinfo +@node Interrupt Processing Traps and Register Windows, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Traps and Register Windows + +One of the register windows must be reserved at all +times for trap processing. This is critical to the proper +operation of the trap mechanism in the SPARC architecture. It +is the responsibility of the trap handler to insure that there +is a register window available for a subsequent trap before +re-enabling traps. It is likely that any high level language +routines invoked by the trap handler (such as a user-provided +RTEMS interrupt handler) will allocate a new register window. +The save operation could result in a window overflow trap. This +trap cannot be correctly processed unless (1) traps are enabled +and (2) a register window is reserved for traps. Thus, the +RTEMS interrupt handler insures that a register window is +available for subsequent traps before enabling traps and +invoking the user's interrupt handler. + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Traps and Register Windows, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Sixteen levels (0-15) of interrupt priorities are +supported by the SPARC architecture with level fifteen (15) +being the highest priority. Level zero (0) indicates that +interrupts are fully enabled. Interrupt requests for interrupts +with priorities less than or equal to the current interrupt mask +level are ignored. + +Although RTEMS supports 256 interrupt levels, the +SPARC only supports sixteen. RTEMS interrupt levels 0 through +15 directly correspond to SPARC processor interrupt levels. 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 to level seven (15) +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 ERC32 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 is hand calculated. This +calculation was last performed for Release +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +[NOTE: It is thought that the length of time at which +the processor interrupt level is elevated to fifteen by RTEMS is +not anywhere near as long as the length of time ALL traps are +disabled as part of the "flush all register windows" operation.] + +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 SPARC architecture does not provide for a +dedicated interrupt stack. Thus by default, trap handlers would +execute on the stack of the RTEMS task which they interrupted. +This artificially inflates the stack requirements for each task +since EVERY task stack would have to include enough space to +account for the worst case interrupt stack requirements in +addition to it's own worst case usage. RTEMS addresses this +problem on the SPARC by providing a dedicated interrupt stack +managed by software. + +During system initialization, RTEMS allocates the +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. As +part of processing a non-nested interrupt, RTEMS will switch to +the interrupt stack before invoking the installed handler. + diff --git a/doc/supplements/sparc/intr_NOTIMES.t b/doc/supplements/sparc/intr_NOTIMES.t new file mode 100644 index 0000000000..73224c1008 --- /dev/null +++ b/doc/supplements/sparc/intr_NOTIMES.t @@ -0,0 +1,226 @@ +@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 Synchronous Versus Asynchronous Traps:: +* Interrupt Processing Vectoring of Interrupt Handler:: +* Interrupt Processing Traps and Register Windows:: +* 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 Synchronous Versus Asynchronous Traps, Interrupt Processing, Interrupt Processing +@end ifinfo +@section Introduction + +Different types of processors respond to the +occurrence of an interrupt in its 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 SPARC's +interrupt response and control mechanisms as they pertain to +RTEMS. + +RTEMS and associated documentation uses the terms +interrupt and vector. In the SPARC architecture, these terms +correspond to traps and trap type, respectively. The terms will +be used interchangeably in this manual. + +@ifinfo +@node Interrupt Processing Synchronous Versus Asynchronous Traps, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Introduction, Interrupt Processing +@end ifinfo +@section Synchronous Versus Asynchronous Traps + +The SPARC architecture includes two classes of traps: +synchronous and asynchronous. Asynchronous traps occur when an +external event interrupts the processor. These traps are not +associated with any instruction executed by the processor and +logically occur between instructions. The instruction currently +in the execute stage of the processor is allowed to complete +although subsequent instructions are annulled. The return +address reported by the processor for asynchronous traps is the +pair of instructions following the current instruction. + +Synchronous traps are caused by the actions of an +instruction. The trap stimulus in this case either occurs +internally to the processor or is from an external signal that +was provoked by the instruction. These traps are taken +immediately and the instruction that caused the trap is aborted +before any state changes occur in the processor itself. The +return address reported by the processor for synchronous traps +is the instruction which caused the trap and the following +instruction. + +@ifinfo +@node Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing Traps and Register Windows, Interrupt Processing Synchronous Versus Asynchronous Traps, Interrupt Processing +@end ifinfo +@section Vectoring of Interrupt Handler + +Upon receipt of an interrupt the SPARC automatically +performs the following actions: + +@itemize @bullet +@item disables traps (sets the ET bit of the psr to 0), + +@item the S bit of the psr is copied into the Previous +Supervisor Mode (PS) bit of the psr, + +@item the cwp is decremented by one (modulo the number of +register windows) to activate a trap window, + +@item the PC and nPC are loaded into local register 1 and 2 +(l0 and l1), + +@item the trap type (tt) field of the Trap Base Register (TBR) +is set to the appropriate value, and + +@item if the trap is not a reset, then the PC is written with +the contents of the TBR and the nPC is written with TBR + 4. If +the trap is a reset, then the PC is set to zero and the nPC is +set to 4. +@end itemize + +Trap processing on the SPARC has two features which +are noticeably different than interrupt processing on other +architectures. First, the value of psr register in effect +immediately before the trap occurred is not explicitly saved. +Instead only reversible alterations are made to it. Second, the +Processor Interrupt Level (pil) is not set to correspond to that +of the interrupt being processed. When a trap occurs, ALL +subsequent traps are disabled. In order to safely invoke a +subroutine during trap handling, traps must be enabled to allow +for the possibility of register window overflow and underflow +traps. + +If the interrupt handler was installed as an RTEMS +interrupt handler, then upon receipt of the interrupt, the +processor passes control to the RTEMS interrupt handler which +performs the following actions: + +@itemize @bullet +@item saves the state of the interrupted task on it's stack, + +@item insures that a register window is available for +subsequent traps, + +@item if this is the outermost (i.e. non-nested) interrupt, +then the RTEMS interrupt handler switches from the current stack +to the interrupt stack, + +@item enables traps, + +@item invokes the vectors to a user interrupt service routine (ISR). +@end itemize + +Asynchronous interrupts are ignored while traps are +disabled. Synchronous traps which occur while traps are +disabled result in the CPU being forced into an error mode. + +A nested interrupt is processed similarly with the +exception that the current stack need not be switched to the +interrupt stack. + +@ifinfo +@node Interrupt Processing Traps and Register Windows, Interrupt Processing Interrupt Levels, Interrupt Processing Vectoring of Interrupt Handler, Interrupt Processing +@end ifinfo +@section Traps and Register Windows + +One of the register windows must be reserved at all +times for trap processing. This is critical to the proper +operation of the trap mechanism in the SPARC architecture. It +is the responsibility of the trap handler to insure that there +is a register window available for a subsequent trap before +re-enabling traps. It is likely that any high level language +routines invoked by the trap handler (such as a user-provided +RTEMS interrupt handler) will allocate a new register window. +The save operation could result in a window overflow trap. This +trap cannot be correctly processed unless (1) traps are enabled +and (2) a register window is reserved for traps. Thus, the +RTEMS interrupt handler insures that a register window is +available for subsequent traps before enabling traps and +invoking the user's interrupt handler. + +@ifinfo +@node Interrupt Processing Interrupt Levels, Interrupt Processing Disabling of Interrupts by RTEMS, Interrupt Processing Traps and Register Windows, Interrupt Processing +@end ifinfo +@section Interrupt Levels + +Sixteen levels (0-15) of interrupt priorities are +supported by the SPARC architecture with level fifteen (15) +being the highest priority. Level zero (0) indicates that +interrupts are fully enabled. Interrupt requests for interrupts +with priorities less than or equal to the current interrupt mask +level are ignored. + +Although RTEMS supports 256 interrupt levels, the +SPARC only supports sixteen. RTEMS interrupt levels 0 through +15 directly correspond to SPARC processor interrupt levels. 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 to level seven (15) +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 ERC32 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 is hand calculated. This +calculation was last performed for Release +RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +[NOTE: It is thought that the length of time at which +the processor interrupt level is elevated to fifteen by RTEMS is +not anywhere near as long as the length of time ALL traps are +disabled as part of the "flush all register windows" operation.] + +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 SPARC architecture does not provide for a +dedicated interrupt stack. Thus by default, trap handlers would +execute on the stack of the RTEMS task which they interrupted. +This artificially inflates the stack requirements for each task +since EVERY task stack would have to include enough space to +account for the worst case interrupt stack requirements in +addition to it's own worst case usage. RTEMS addresses this +problem on the SPARC by providing a dedicated interrupt stack +managed by software. + +During system initialization, RTEMS allocates the +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. As +part of processing a non-nested interrupt, RTEMS will switch to +the interrupt stack before invoking the installed handler. + diff --git a/doc/supplements/sparc/memmodel.t b/doc/supplements/sparc/memmodel.t new file mode 100644 index 0000000000..d99ef26f96 --- /dev/null +++ b/doc/supplements/sparc/memmodel.t @@ -0,0 +1,117 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 + +The SPARC architecture 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), word (4 bytes), or doubleword +(8 bytes). Memory accesses within this address space are +performed in big endian fashion by the SPARC. Memory accesses +which are not properly aligned generate a "memory address not +aligned" trap (type number 7). The following table lists the +alignment requirements for a variety of data accesses: + +@ifset use-ascii +@example +@group + +--------------+-----------------------+ + | Data Type | Alignment Requirement | + +--------------+-----------------------+ + | byte | 1 | + | half-word | 2 | + | word | 4 | + | doubleword | 8 | + +--------------+-----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Data Type &&\bf Alignment Requirement&\cr\noalign{\hrule} +&byte&&1&\cr\noalign{\hrule} +&half-word&&2&\cr\noalign{\hrule} +&word&&4&\cr\noalign{\hrule} +&doubleword&&8&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + +
    Data TypeAlignment Requirement
    byte1
    half-word2
    word4
    doubleword8
    +
    +@end html +@end ifset + +Doubleword load and store operations must use a pair +of registers as their source or destination. This pair of +registers must be an adjacent pair of registers with the first +of the pair being even numbered. For example, a valid +destination for a doubleword load might be input registers 0 and +1 (i0 and i1). The pair i1 and i2 would be invalid. [NOTE: +Some assemblers for the SPARC do not generate an error if an odd +numbered register is specified as the beginning register of the +pair. In this case, the assembler assumes that what the +programmer meant was to use the even-odd pair which ends at the +specified register. This may or may not have been a correct +assumption.] + +RTEMS does not support any SPARC Memory Management +Units, therefore, virtual memory or segmentation systems +involving the SPARC are not supported. + diff --git a/doc/supplements/sparc/memmodel.texi b/doc/supplements/sparc/memmodel.texi new file mode 100644 index 0000000000..d99ef26f96 --- /dev/null +++ b/doc/supplements/sparc/memmodel.texi @@ -0,0 +1,117 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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 + +The SPARC architecture 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), word (4 bytes), or doubleword +(8 bytes). Memory accesses within this address space are +performed in big endian fashion by the SPARC. Memory accesses +which are not properly aligned generate a "memory address not +aligned" trap (type number 7). The following table lists the +alignment requirements for a variety of data accesses: + +@ifset use-ascii +@example +@group + +--------------+-----------------------+ + | Data Type | Alignment Requirement | + +--------------+-----------------------+ + | byte | 1 | + | half-word | 2 | + | word | 4 | + | doubleword | 8 | + +--------------+-----------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.75in{\enskip\hfil#\hfil}& +\vrule#\cr +\noalign{\hrule} +&\bf Data Type &&\bf Alignment Requirement&\cr\noalign{\hrule} +&byte&&1&\cr\noalign{\hrule} +&half-word&&2&\cr\noalign{\hrule} +&word&&4&\cr\noalign{\hrule} +&doubleword&&8&\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + +
    Data TypeAlignment Requirement
    byte1
    half-word2
    word4
    doubleword8
    +
    +@end html +@end ifset + +Doubleword load and store operations must use a pair +of registers as their source or destination. This pair of +registers must be an adjacent pair of registers with the first +of the pair being even numbered. For example, a valid +destination for a doubleword load might be input registers 0 and +1 (i0 and i1). The pair i1 and i2 would be invalid. [NOTE: +Some assemblers for the SPARC do not generate an error if an odd +numbered register is specified as the beginning register of the +pair. In this case, the assembler assumes that what the +programmer meant was to use the even-odd pair which ends at the +specified register. This may or may not have been a correct +assumption.] + +RTEMS does not support any SPARC Memory Management +Units, therefore, virtual memory or segmentation systems +involving the SPARC are not supported. + diff --git a/doc/supplements/sparc/preface.texi b/doc/supplements/sparc/preface.texi new file mode 100644 index 0000000000..572d24a174 --- /dev/null +++ b/doc/supplements/sparc/preface.texi @@ -0,0 +1,89 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@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. + +This document discusses the SPARC architecture +dependencies in this port of RTEMS. Currently, only +implementations of SPARC Version 7 are supported by RTEMS. + +It is highly recommended that the SPARC RTEMS +application developer obtain and become familiar with the +documentation for the processor being used as well as the +specification for the revision of the SPARC architecture which +corresponds to that processor. + +@subheading SPARC Architecture Documents + +For information on the SPARC architecture, refer to +the following documents available from SPARC International, Inc. +(http://www.sparc.com): + +@itemize @bullet +@item SPARC Standard Version 7. + +@item SPARC Standard Version 8. + +@item SPARC Standard Version 9. +@end itemize + +@subheading ERC32 Specific Information + +The European Space Agency's ERC32 is a three chip +computing core implementing a SPARC V7 processor and associated +support circuitry for embedded space applications. The integer +and floating-point units (90C601E & 90C602E) are based on the +Cypress 7C601 and 7C602, with additional error-detection and +recovery functions. The memory controller (MEC) implements +system support functions such as address decoding, memory +interface, DMA interface, UARTs, timers, interrupt control, +write-protection, memory reconfiguration and error-detection. +The core is designed to work at 25MHz, but using space qualified +memories limits the system frequency to around 15 MHz, resulting +in a performance of 10 MIPS and 2 MFLOPS. + +Information on the ERC32 and a number of development +support tools, such as the SPARC Instruction Simulator (SIS), +are freely available on the Internet. The following documents +and SIS are available via anonymous ftp or pointing your web +browser at ftp://ftp.estec.esa.nl/pub/ws/wsd/erc32. + +@itemize @bullet +@item ERC32 System Design Document + +@item MEC Device Specification +@end itemize + +Additionally, the SPARC RISC User's Guide from Matra +MHS documents the functionality of the integer and floating +point units including the instruction set information. To +obtain this document as well as ERC32 components and VHDL models +contact: + +@example +Matra MHS SA +3 Avenue du Centre, BP 309, +78054 St-Quentin-en-Yvelines, +Cedex, France +VOICE: +31-1-30607087 +FAX: +31-1-30640693 +@end example + +Amar Guennon (amar.guennon@@matramhs.fr) is familiar with the ERC32. + diff --git a/doc/supplements/sparc/sparc.texi b/doc/supplements/sparc/sparc.texi new file mode 100644 index 0000000000..763da87f35 --- /dev/null +++ b/doc/supplements/sparc/sparc.texi @@ -0,0 +1,117 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_sparc +@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 SPARC C Applications Supplement +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS SPARC C Applications Supplement (sparc): +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 SPARC C Applications Supplement + +@setchapternewpage odd +@settitle RTEMS SPARC C Applications Supplement +@titlepage +@finalout + +@title RTEMS SPARC 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_sparc + +This is the online version of the RTEMS SPARC 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:: +* ERC32 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, ERC32 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/sparc/timeERC32.t b/doc/supplements/sparc/timeERC32.t new file mode 100644 index 0000000000..22cc6a1202 --- /dev/null +++ b/doc/supplements/sparc/timeERC32.t @@ -0,0 +1,156 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node ERC32 Timing Data, ERC32 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter ERC32 Timing Data +@ifinfo +@menu +* ERC32 Timing Data Introduction:: +* ERC32 Timing Data Hardware Platform:: +* ERC32 Timing Data Interrupt Latency:: +* ERC32 Timing Data Context Switch:: +* ERC32 Timing Data Directive Times:: +* ERC32 Timing Data Task Manager:: +* ERC32 Timing Data Interrupt Manager:: +* ERC32 Timing Data Clock Manager:: +* ERC32 Timing Data Timer Manager:: +* ERC32 Timing Data Semaphore Manager:: +* ERC32 Timing Data Message Manager:: +* ERC32 Timing Data Event Manager:: +* ERC32 Timing Data Signal Manager:: +* ERC32 Timing Data Partition Manager:: +* ERC32 Timing Data Region Manager:: +* ERC32 Timing Data Dual-Ported Memory Manager:: +* ERC32 Timing Data I/O Manager:: +* ERC32 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node ERC32 Timing Data Introduction, ERC32 Timing Data Hardware Platform, ERC32 Timing Data, ERC32 Timing Data +@end ifinfo +@section Introduction + +The timing data for RTEMS on the ERC32 implementation +of the SPARC architecture 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 +SPARC version of RTEMS. + +@ifinfo +@node ERC32 Timing Data Hardware Platform, ERC32 Timing Data Interrupt Latency, ERC32 Timing Data Introduction, ERC32 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported in this chapter were measured +using the SPARC Instruction Simulator (SIS) developed by the +European Space Agency. SIS simulates the ERC32 -- a custom low +power implementation combining the Cypress 90C601 integer unit, +the Cypress 90C602 floating point unit, and a number of +peripherals such as counter timers, interrupt controller and a +memory controller. + +For the RTEMS tests, SIS is configured with the +following characteristics: + +@itemize @bullet +@item 15 Mhz clock speed + +@item 0 wait states for PROM accesses + +@item 0 wait states for RAM accesses +@end itemize + +The ERC32's General Purpose Timer was used to gather +all timing information. This timer was programmed to operate +with one microsecond accuracy. All sources of hardware +interrupts were disabled, although traps were enabled and the +interrupt level of the SPARC allows all interrupts. + +@ifinfo +@node ERC32 Timing Data Interrupt Latency, ERC32 Timing Data Context Switch, ERC32 Timing Data Hardware Platform, ERC32 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 +ERC32 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 +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz. +[NOTE: The maximum period with interrupts disabled was last +determined for Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +The maximum period with interrupts disabled within +RTEMS is hand-timed with some assistance from SIS. The maximum +period with interrupts disabled with RTEMS occurs during a +context switch when traps are disabled to flush all the register +windows to memory. The length of time spent flushing the +register windows varies based on the number of windows which +must be flushed. Based on the information reported by SIS, it +takes from 4.0 to 18.0 microseconds (37 to 122 instructions) to +flush the register windows. It takes approximately 41 CPU +cycles (2.73 microseconds) to flush each register window set to +memory. The register window flush operation is heavily memory +bound. + +[NOTE: All traps are disabled during the register +window flush thus disabling both software generate traps and +external interrupts. During a normal RTEMS critical section, +the processor interrupt level (pil) is raised to level 15 and +traps are left enabled. The longest path for a normal critical +section within RTEMS is less than 50 instructions.] + +The interrupt vector and entry overhead time was +generated on the SIS benchmark platform using the ERC32's +ability to forcibly generate an arbitrary interrupt as the +source of the "benchmark" interrupt. + +@ifinfo +@node ERC32 Timing Data Context Switch, RTEMS_CPU_MODEL Timing Data Directive Times, ERC32 Timing Data Interrupt Latency, ERC32 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is 10 +microseconds on the SIS benchmark platform when no floating +point context is saved or restored. 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. 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. + +The following table summarizes the context switch +times for the ERC32 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex + + diff --git a/doc/supplements/sparc/timedata.t b/doc/supplements/sparc/timedata.t new file mode 100644 index 0000000000..22cc6a1202 --- /dev/null +++ b/doc/supplements/sparc/timedata.t @@ -0,0 +1,156 @@ +@include ../common/timemac.texi +@tex +\global\advance \smallskipamount by -4pt +@end tex + +@ifinfo +@node ERC32 Timing Data, ERC32 Timing Data Introduction, Memory Requirements RTEMS RAM Workspace Worksheet, Top +@end ifinfo +@chapter ERC32 Timing Data +@ifinfo +@menu +* ERC32 Timing Data Introduction:: +* ERC32 Timing Data Hardware Platform:: +* ERC32 Timing Data Interrupt Latency:: +* ERC32 Timing Data Context Switch:: +* ERC32 Timing Data Directive Times:: +* ERC32 Timing Data Task Manager:: +* ERC32 Timing Data Interrupt Manager:: +* ERC32 Timing Data Clock Manager:: +* ERC32 Timing Data Timer Manager:: +* ERC32 Timing Data Semaphore Manager:: +* ERC32 Timing Data Message Manager:: +* ERC32 Timing Data Event Manager:: +* ERC32 Timing Data Signal Manager:: +* ERC32 Timing Data Partition Manager:: +* ERC32 Timing Data Region Manager:: +* ERC32 Timing Data Dual-Ported Memory Manager:: +* ERC32 Timing Data I/O Manager:: +* ERC32 Timing Data Rate Monotonic Manager:: +@end menu +@end ifinfo + +@ifinfo +@node ERC32 Timing Data Introduction, ERC32 Timing Data Hardware Platform, ERC32 Timing Data, ERC32 Timing Data +@end ifinfo +@section Introduction + +The timing data for RTEMS on the ERC32 implementation +of the SPARC architecture 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 +SPARC version of RTEMS. + +@ifinfo +@node ERC32 Timing Data Hardware Platform, ERC32 Timing Data Interrupt Latency, ERC32 Timing Data Introduction, ERC32 Timing Data +@end ifinfo +@section Hardware Platform + +All times reported in this chapter were measured +using the SPARC Instruction Simulator (SIS) developed by the +European Space Agency. SIS simulates the ERC32 -- a custom low +power implementation combining the Cypress 90C601 integer unit, +the Cypress 90C602 floating point unit, and a number of +peripherals such as counter timers, interrupt controller and a +memory controller. + +For the RTEMS tests, SIS is configured with the +following characteristics: + +@itemize @bullet +@item 15 Mhz clock speed + +@item 0 wait states for PROM accesses + +@item 0 wait states for RAM accesses +@end itemize + +The ERC32's General Purpose Timer was used to gather +all timing information. This timer was programmed to operate +with one microsecond accuracy. All sources of hardware +interrupts were disabled, although traps were enabled and the +interrupt level of the SPARC allows all interrupts. + +@ifinfo +@node ERC32 Timing Data Interrupt Latency, ERC32 Timing Data Context Switch, ERC32 Timing Data Hardware Platform, ERC32 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 +ERC32 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 +RTEMS_MAXIMUM_DISABLE_PERIOD_MHZ Mhz. +[NOTE: The maximum period with interrupts disabled was last +determined for Release RTEMS_RELEASE_FOR_MAXIMUM_DISABLE_PERIOD.] + +The maximum period with interrupts disabled within +RTEMS is hand-timed with some assistance from SIS. The maximum +period with interrupts disabled with RTEMS occurs during a +context switch when traps are disabled to flush all the register +windows to memory. The length of time spent flushing the +register windows varies based on the number of windows which +must be flushed. Based on the information reported by SIS, it +takes from 4.0 to 18.0 microseconds (37 to 122 instructions) to +flush the register windows. It takes approximately 41 CPU +cycles (2.73 microseconds) to flush each register window set to +memory. The register window flush operation is heavily memory +bound. + +[NOTE: All traps are disabled during the register +window flush thus disabling both software generate traps and +external interrupts. During a normal RTEMS critical section, +the processor interrupt level (pil) is raised to level 15 and +traps are left enabled. The longest path for a normal critical +section within RTEMS is less than 50 instructions.] + +The interrupt vector and entry overhead time was +generated on the SIS benchmark platform using the ERC32's +ability to forcibly generate an arbitrary interrupt as the +source of the "benchmark" interrupt. + +@ifinfo +@node ERC32 Timing Data Context Switch, RTEMS_CPU_MODEL Timing Data Directive Times, ERC32 Timing Data Interrupt Latency, ERC32 Timing Data +@end ifinfo +@section Context Switch + +The RTEMS processor context switch time is 10 +microseconds on the SIS benchmark platform when no floating +point context is saved or restored. 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. 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. + +The following table summarizes the context switch +times for the ERC32 benchmark platform: + +@include timetbl.texi + +@tex +\global\advance \smallskipamount by 4pt +@end tex + + diff --git a/doc/texinfo/texinfo.tex b/doc/texinfo/texinfo.tex new file mode 100644 index 0000000000..8fcde98a03 --- /dev/null +++ b/doc/texinfo/texinfo.tex @@ -0,0 +1,4426 @@ +%% TeX macros to handle texinfo files + +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 Free Software Foundation, Inc. + +%This texinfo.tex file is free software; you can redistribute it and/or +%modify it under the terms of the GNU General Public License as +%published by the Free Software Foundation; either version 2, or (at +%your option) any later version. + +%This texinfo.tex file is distributed in the hope that it will be +%useful, but WITHOUT ANY WARRANTY; without even the implied warranty +%of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +%General Public License for more details. + +%You should have received a copy of the GNU General Public License +%along with this texinfo.tex file; see the file COPYING. If not, write +%to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, +%USA. + + +%In other words, you are welcome to use, share and improve this program. +%You are forbidden to forbid anyone else to use, share and improve +%what you give them. Help stamp out software-hoarding! + + +% Send bug reports to bug-texinfo@prep.ai.mit.edu. +% Please include a *precise* test case in each bug report. + + +% Make it possible to create a .fmt file just by loading this file: +% if the underlying format is not loaded, start by loading it now. +% Added by gildea November 1993. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi + +% This automatically updates the version number based on RCS. +\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} +\deftexinfoversion$Revision$ +\message{Loading texinfo package [Version \texinfoversion]:} + +% If in a .fmt file, print the version number +% and turn on active characters that we couldn't do earlier because +% they might have appeared in the input file name. +\everyjob{\message{[Texinfo version \texinfoversion]}\message{} + \catcode`+=\active \catcode`\_=\active} + +% Save some parts of plain tex whose names we will redefine. + +\let\ptextilde=\~ +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexdots=\dots +\let\ptexdot=\. +\let\ptexstar=\* +\let\ptexend=\end +\let\ptexbullet=\bullet +\let\ptexb=\b +\let\ptexc=\c +\let\ptexi=\i +\let\ptext=\t +\let\ptexl=\l +\let\ptexL=\L + +% Be sure we're in horizontal mode when doing a tie, since we make space +% equivalent to this in @example-like environments. Otherwise, a space +% at the beginning of a line will start with \penalty -- and +% since \penalty is valid in vertical mode, we'd end up putting the +% penalty on the vertical list instead of in the new paragraph. +{\catcode`@ = 11 + % Avoid using \@M directly, because that causes trouble + % if the definition is written into an index file. + \global\let\tiepenalty = \@M + \gdef\tie{\leavevmode\penalty\tiepenalty\ } +} +\let\~ = \tie % And make it available as @~. + +\message{Basics,} +\chardef\other=12 + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Set up fixed words for English. +\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% +\def\putwordInfo{Info}% +\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% +\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% +\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% +\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% +\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% +\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% +\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% +\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% +\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% + +% Ignore a token. +% +\def\gobble#1{} + +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen \bindingoffset \bindingoffset=0pt +\newdimen \normaloffset \normaloffset=\hoffset +\newdimen\pagewidth \newdimen\pageheight +\pagewidth=\hsize \pageheight=\vsize + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{\tracingcommands2 \tracingstats2 + \tracingpages1 \tracingoutput1 \tracinglostchars1 + \tracingmacros2 \tracingparagraphs1 \tracingrestores1 + \showboxbreadth\maxdimen\showboxdepth\maxdimen +}% + +%---------------------Begin change----------------------- +% +%%%% For @cropmarks command. +% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\cornerlong \newdimen\cornerthick +\newdimen \topandbottommargin +\newdimen \outerhsize \newdimen \outervsize +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\outerhsize=7in +%\outervsize=9.5in +% Alternative @smallbook page size is 9.25in +\outervsize=9.25in +\topandbottommargin=.75in +% +%---------------------End change----------------------- + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions itself, but you have to call it yourself. +\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} +\def\onepageout#1{\hoffset=\normaloffset +\ifodd\pageno \advance\hoffset by \bindingoffset +\else \advance\hoffset by -\bindingoffset\fi +{\escapechar=`\\\relax % makes sure backslash is used in output files. +\shipout\vbox{{\let\hsize=\pagewidth \makeheadline} \pagebody{#1}% +{\let\hsize=\pagewidth \makefootline}}}% +\advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi} + +%%%% For @cropmarks command %%%% + +% Here is a modification of the main output routine for Near East Publications +% This provides right-angle cropmarks at all four corners. +% The contents of the page are centerlined into the cropmarks, +% and any desired binding offset is added as an \hskip on either +% site of the centerlined box. (P. A. MacKay, 12 November, 1986) +% +\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up +{\escapechar=`\\\relax % makes sure backslash is used in output files. + \shipout + \vbox to \outervsize{\hsize=\outerhsize + \vbox{\line{\ewtop\hfill\ewtop}} + \nointerlineskip + \line{\vbox{\moveleft\cornerthick\nstop} + \hfill + \vbox{\moveright\cornerthick\nstop}} + \vskip \topandbottommargin + \centerline{\ifodd\pageno\hskip\bindingoffset\fi + \vbox{ + {\let\hsize=\pagewidth \makeheadline} + \pagebody{#1} + {\let\hsize=\pagewidth \makefootline}} + \ifodd\pageno\else\hskip\bindingoffset\fi} + \vskip \topandbottommargin plus1fill minus1fill + \boxmaxdepth\cornerthick + \line{\vbox{\moveleft\cornerthick\nsbot} + \hfill + \vbox{\moveright\cornerthick\nsbot}} + \nointerlineskip + \vbox{\line{\ewbot\hfill\ewbot}} + }} + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi} +% +% Do @cropmarks to get crop marks +\def\cropmarks{\let\onepageout=\croppageout } + +\newinsert\margin \dimen\margin=\maxdimen + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +% marginal hacks, juha@viisa.uucp (Juha Takala) +\ifvoid\margin\else % marginal info is present + \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi +\dimen@=\dp#1 \unvbox#1 +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg#1{% + \let\next = #1% + \begingroup + \obeylines + \futurelet\temp\parseargx +} + +% If the next token is an obeyed space (from an @example environment or +% the like), remove it and recurse. Otherwise, we're done. +\def\parseargx{% + % \obeyedspace is defined far below, after the definition of \sepspaces. + \ifx\obeyedspace\temp + \expandafter\parseargdiscardspace + \else + \expandafter\parseargline + \fi +} + +% Remove a single space (as the delimiter token to the macro call). +{\obeyspaces % + \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + % + % First remove any @c comment, then any @comment. + % Result of each macro is put in \toks0. + \argremovec #1\c\relax % + \expandafter\argremovecomment \the\toks0 \comment\relax % + % + % Call the caller's macro, saved as \next in \parsearg. + \expandafter\next\expandafter{\the\toks0}% + }% +} + +% Since all \c{,omment} does is throw away the argument, we can let TeX +% do that for us. The \relax here is matched by the \relax in the call +% in \parseargline; it could be more or less anything, its purpose is +% just to delimit the argument to the \c. +\def\argremovec#1\c#2\relax{\toks0 = {#1}} +\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} + +% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% @end itemize @c foo +% will have two active spaces as part of the argument with the +% `itemize'. Here we remove all active spaces from #1, and assign the +% result to \toks0. +% +% This loses if there are any *other* active characters besides spaces +% in the argument -- _ ^ +, for example -- since they get expanded. +% Fortunately, Texinfo does not define any such commands. (If it ever +% does, the catcode of the characters in questionwill have to be changed +% here.) But this means we cannot call \removeactivespaces as part of +% \argremovec{,omment}, since @c uses \parsearg, and thus the argument +% that \parsearg gets might well have any character at all in it. +% +\def\removeactivespaces#1{% + \begingroup + \ignoreactivespaces + \edef\temp{#1}% + \global\toks0 = \expandafter{\temp}% + \endgroup +} + +% Change the active space to expand to nothing. +% +\begingroup + \obeyspaces + \gdef\ignoreactivespaces{\obeyspaces\let =\empty} +\endgroup + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +%% These are used to keep @begin/@end levels from running away +%% Call \inENV within environments (after a \begingroup) +\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} +\def\ENVcheck{% +\ifENV\errmessage{Still within an environment. Type Return to continue.} +\endgroup\fi} % This is not perfect, but it should reduce lossage + +% @begin foo is the same as @foo, for now. +\newhelp\EMsimple{Type to continue.} + +\outer\def\begin{\parsearg\beginxxx} + +\def\beginxxx #1{% +\expandafter\ifx\csname #1\endcsname\relax +{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else +\csname #1\endcsname\fi} + +% @end foo executes the definition of \Efoo. +% +\def\end{\parsearg\endxxx} +\def\endxxx #1{% + \removeactivespaces{#1}% + \edef\endthing{\the\toks0}% + % + \expandafter\ifx\csname E\endthing\endcsname\relax + \expandafter\ifx\csname \endthing\endcsname\relax + % There's no \foo, i.e., no ``environment'' foo. + \errhelp = \EMsimple + \errmessage{Undefined command `@end \endthing'}% + \else + \unmatchedenderror\endthing + \fi + \else + % Everything's ok; the right environment has been started. + \csname E\endthing\endcsname + \fi +} + +% There is an environment #1, but it hasn't been started. Give an error. +% +\def\unmatchedenderror#1{% + \errhelp = \EMsimple + \errmessage{This `@end #1' doesn't have a matching `@#1'}% +} + +% Define the control sequence \E#1 to give an unmatched @end error. +% +\def\defineunmatchedend#1{% + \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +} + + +% Single-spacing is done by various environments (specifically, in +% \nonfillstart and \quotations). +\newskip\singlespaceskip \singlespaceskip = 12.5pt +\def\singlespace{% + % Why was this kern here? It messes up equalizing space above and below + % environments. --karl, 6may93 + %{\advance \baselineskip by -\singlespaceskip + %\kern \baselineskip}% + \setleading \singlespaceskip +} + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt \char '100}} + +% This is turned off because it was never documented +% and you can use @w{...} around a quote to suppress ligatures. +%% Define @` and @' to be the same as ` and ' +%% but suppressing ligatures. +%\def\`{{`}} +%\def\'{{'}} + +% Used to generate quoted braces. + +\def\mylbrace {{\tt \char '173}} +\def\myrbrace {{\tt \char '175}} +\let\{=\mylbrace +\let\}=\myrbrace + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=3000 } + +% @enddots{} is an end-of-sentence ellipsis. +\gdef\enddots{$\mathinner{\ldotp\ldotp\ldotp\ldotp}$\spacefactor=3000} + +% @! is an end-of-sentence bang. +\gdef\!{!\spacefactor=3000 } + +% @? is an end-of-sentence query. +\gdef\?{?\spacefactor=3000 } + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +\def\group{\begingroup + \ifnum\catcode13=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + % + % The \vtop we start below produces a box with normal height and large + % depth; thus, TeX puts \baselineskip glue before it, and (when the + % next line of text is done) \lineskip glue after it. (See p.82 of + % the TeXbook.) Thus, space below is not quite equal to space + % above. But it's pretty close. + \def\Egroup{% + \egroup % End the \vtop. + \endgroup % End the \group. + }% + % + \vtop\bgroup + % We have to put a strut on the last line in case the @group is in + % the midst of an example, rather than completely enclosing it. + % Otherwise, the interline space between the last line of the group + % and the first line afterwards is too small. But we can't put the + % strut in \Egroup, since there it would be on a line by itself. + % Hence this just inserts a strut at the beginning of each line. + \everypar = {\strut}% + % + % Since we have a strut on every line, we don't need any of TeX's + % normal interline spacing. + \offinterlineskip + % + % OK, but now we have to do something about blank + % lines in the input in @example-like environments, which normally + % just turn into \lisppar, which will insert no space now that we've + % turned off the interline space. Simplest is to make them be an + % empty paragraph. + \ifx\par\lisppar + \edef\par{\leavevmode \par}% + % + % Reset ^^M's definition to new definition of \par. + \obeylines + \fi + % + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +\def\need{\parsearg\needx} + +% Old definition--didn't work. +%\def\needx #1{\par % +%% This method tries to make TeX break the page naturally +%% if the depth of the box does not fit. +%{\baselineskip=0pt% +%\vtop to #1\mil{\vfil}\kern -#1\mil\penalty 10000 +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Go into vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % Don't add any leading before our big empty box, but allow a page + % break, since the best break might be right here. + \allowbreak + \nointerlineskip + \vtop to #1\mil{\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output some dots + +\def\dots{$\ldots$} + +% @page forces the start of a new page + +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\def\exdent{\parsearg\exdentyyy} +\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} + +% This defn is used inside nofill environments such as @example. +\def\nofillexdent{\parsearg\nofillexdentyyy} +\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount +\leftline{\hskip\leftskip{\rm#1}}}} + +%\hbox{{\rm#1}}\hfil\break}} + +% @include file insert text of that file as input. + +\def\include{\parsearg\includezzz} +%Use \input\thisfile to avoid blank after \input, which may be an active +%char (in which case the blank would become the \input argument). +%The grouping keeps the value of \thisfile correct even when @include +%is nested. +\def\includezzz #1{\begingroup +\def\thisfile{#1}\input\thisfile +\endgroup} + +\def\thisfile{} + +% @center line outputs that line, centered + +\def\center{\parsearg\centerzzz} +\def\centerzzz #1{{\advance\hsize by -\leftskip +\advance\hsize by -\rightskip +\centerline{#1}}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\par \vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment + +\def\comment{\catcode 64=\other \catcode 123=\other \catcode 125=\other% +\parsearg \commentxxx} + +\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } + +\let\c=\comment + +% Prevent errors for section commands. +% Used in @ignore and in failing conditionals. +\def\ignoresections{% +\let\chapter=\relax +\let\unnumbered=\relax +\let\top=\relax +\let\unnumberedsec=\relax +\let\unnumberedsection=\relax +\let\unnumberedsubsec=\relax +\let\unnumberedsubsection=\relax +\let\unnumberedsubsubsec=\relax +\let\unnumberedsubsubsection=\relax +\let\section=\relax +\let\subsec=\relax +\let\subsubsec=\relax +\let\subsection=\relax +\let\subsubsection=\relax +\let\appendix=\relax +\let\appendixsec=\relax +\let\appendixsection=\relax +\let\appendixsubsec=\relax +\let\appendixsubsection=\relax +\let\appendixsubsubsec=\relax +\let\appendixsubsubsection=\relax +\let\contents=\relax +\let\smallbook=\relax +\let\titlepage=\relax +} + +% Used in nested conditionals, where we have to parse the Texinfo source +% and so want to turn off most commands, in case they are used +% incorrectly. +% +\def\ignoremorecommands{% + \let\defcv = \relax + \let\deffn = \relax + \let\deffnx = \relax + \let\defindex = \relax + \let\defivar = \relax + \let\defmac = \relax + \let\defmethod = \relax + \let\defop = \relax + \let\defopt = \relax + \let\defspec = \relax + \let\deftp = \relax + \let\deftypefn = \relax + \let\deftypefun = \relax + \let\deftypevar = \relax + \let\deftypevr = \relax + \let\defun = \relax + \let\defvar = \relax + \let\defvr = \relax + \let\ref = \relax + \let\xref = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\settitle = \relax + \let\include = \relax + \let\lowersections = \relax + \let\down = \relax + \let\raisesections = \relax + \let\up = \relax + \let\set = \relax + \let\clear = \relax + \let\item = \relax + \let\message = \relax +} + +% Ignore @ignore ... @end ignore. +% +\def\ignore{\doignore{ignore}} + +% Also ignore @ifinfo, @ifhtml, @html, @menu, and @direntry text. +% +\def\ifinfo{\doignore{ifinfo}} +\def\ifhtml{\doignore{ifhtml}} +\def\html{\doignore{html}} +\def\menu{\doignore{menu}} +\def\direntry{\doignore{direntry}} + +% Ignore text until a line `@end #1'. +% +\def\doignore#1{\begingroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define a command to swallow text until we reach `@end #1'. + \long\def\doignoretext##1\end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode32 = 10 + % + % And now expand that command. + \doignoretext +} + +% What we do to finish off ignored text. +% +\def\enddoignore{\endgroup\ignorespaces}% + +\newif\ifwarnedobs\warnedobsfalse +\def\obstexwarn{% + \ifwarnedobs\relax\else + % We need to warn folks that they may have trouble with TeX 3.0. + % This uses \immediate\write16 rather than \message to get newlines. + \immediate\write16{} + \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} + \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} + \immediate\write16{If you are running another version of TeX, relax.} + \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} + \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{If you are stuck with version 3.0, run the} + \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} + \immediate\write16{ to use a workaround.} + \immediate\write16{} + \warnedobstrue + \fi +} + +% **In TeX 3.0, setting text in \nullfont hangs tex. For a +% workaround (which requires the file ``dummy.tfm'' to be installed), +% uncomment the following line: +%%%%%\font\nullfont=dummy\let\obstexwarn=\relax + +% Ignore text, except that we keep track of conditional commands for +% purposes of nesting, up to an `@end #1' command. +% +\def\nestedignore#1{% + \obstexwarn + % We must actually expand the ignored text to look for the @end + % command, so that nested ignore constructs work. Thus, we put the + % text into a \vbox and then do nothing with the result. To minimize + % the change of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook: make the current font be a dummy font. + % + \setbox0 = \vbox\bgroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define `@end #1' to end the box, which will in turn undefine the + % @end command again. + \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% + % + % We are going to be parsing Texinfo commands. Most cause no + % trouble when they are used incorrectly, but some commands do + % complicated argument parsing or otherwise get confused, so we + % undefine them. + % + % We can't do anything about stray @-signs, unfortunately; + % they'll produce `undefined control sequence' errors. + \ignoremorecommands + % + % Set the current font to be \nullfont, a TeX primitive, and define + % all the font commands to also use \nullfont. We don't use + % dummy.tfm, as suggested in the TeXbook, because not all sites + % might have that installed. Therefore, math mode will still + % produce output, but that should be an extremely small amount of + % stuff compared to the main input. + % + \nullfont + \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont + \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont + \let\tensf = \nullfont + % Similarly for index fonts (mostly for their use in + % smallexample) + \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont + \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont + \let\indsf = \nullfont + % + % Don't complain when characters are missing from the fonts. + \tracinglostchars = 0 + % + % Don't bother to do space factor calculations. + \frenchspacing + % + % Don't report underfull hboxes. + \hbadness = 10000 + % + % Do minimal line-breaking. + \pretolerance = 10000 + % + % Do not execute instructions in @tex + \def\tex{\doignore{tex}} +} + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% Since we want to separate VAR from REST-OF-LINE (which might be +% empty), we can't just use \parsearg; we have to insert a space of our +% own to delimit the rest of the line, and then take it out again if we +% didn't need it. +% +\def\set{\parsearg\setxxx} +\def\setxxx#1{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + \def\temp{#2}% + \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty + \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. + \fi +} +% Can't use \xdef to pre-expand #2 and save some time, since \temp or +% \next or other control sequences that we've defined might get us into +% an infinite loop. Consider `@set foo @cite{bar}'. +\def\setzzz#1#2 \endsetzzz{\expandafter\gdef\csname SET#1\endcsname{#2}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\def\clear{\parsearg\clearxxx} +\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} + +% @value{foo} gets the text saved in variable foo. +% +\def\value#1{\expandafter + \ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}} + \else \csname SET#1\endcsname \fi} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\ifsetxxx} +\def\ifsetxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifsetfail + \else + \expandafter\ifsetsucceed + \fi +} +\def\ifsetsucceed{\conditionalsucceed{ifset}} +\def\ifsetfail{\nestedignore{ifset}} +\defineunmatchedend{ifset} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +\def\ifclear{\parsearg\ifclearxxx} +\def\ifclearxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifclearsucceed + \else + \expandafter\ifclearfail + \fi +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex always succeeds; we read the text following, through @end +% iftex). But `@end iftex' should be valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\defineunmatchedend{iftex} + +% We can't just want to start a group at @iftex (for example) and end it +% at @end iftex, since then @set commands inside the conditional have no +% effect (they'd get reverted at the end of the group). So we must +% define \Eiftex to redefine itself to be its previous value. (We can't +% just define it to fail again with an ``unmatched end'' error, since +% the @ifset might be nested.) +% +\def\conditionalsucceed#1{% + \edef\temp{% + % Remember the current value of \E#1. + \let\nece{prevE#1} = \nece{E#1}% + % + % At the `@end #1', redefine \E#1 to be its previous value. + \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% + }% + \temp +} + +% We need to expand lots of \csname's, but we don't want to expand the +% control sequences after we've constructed them. +% +\def\nece#1{\expandafter\noexpand\csname#1\endcsname} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math means output in math mode. +% We don't use $'s directly in the definition of \math because control +% sequences like \math are expanded when the toc file is written. Then, +% we read the toc file back, the $'s will be normal characters (as they +% should be, according to the definition of Texinfo). So we must use a +% control sequence to switch into and out of math mode. +% +% This isn't quite enough for @math to work properly in indices, but it +% seems unlikely it will ever be needed there. +% +\let\implicitmath = $ +\def\math#1{\implicitmath #1\implicitmath} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +\def\donoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\setref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\unnumbnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\appendixnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\let\refill=\relax + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \readauxfile + \opencontents + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + \comment % Ignore the actual filename. +} + +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +\message{fonts,} + +% Font-change commands. + +% Texinfo supports the sans serif font style, which plain TeX does not. +% So we set up a \sf analogous to plain's \rm, etc. +\newfam\sffam +\def\sf{\fam=\sffam \tensf} +\let\li = \sf % Sometimes we call it \li, not \sf. + +%% Try out Computer Modern fonts at \magstephalf +\let\mainmagstep=\magstephalf + +% Set the font macro #1 to the font named #2, adding on the +% specified font prefix (normally `cm'). +\def\setfont#1#2{\font#1=\fontprefix#2} + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% before you read in texinfo.tex. +\ifx\fontprefix\undefined +\def\fontprefix{cm} +\fi + +\ifx\bigger\relax +\let\mainmagstep=\magstep1 +\setfont\textrm{r12} +\setfont\texttt{tt12} +\else +\setfont\textrm{r10 scaled \mainmagstep} +\setfont\texttt{tt10 scaled \mainmagstep} +\fi +% Instead of cmb10, you many want to use cmbx10. +% cmbx10 is a prettier font on its own, but cmb10 +% looks better when embedded in a line with cmr10. +\setfont\textbf{b10 scaled \mainmagstep} +\setfont\textit{ti10 scaled \mainmagstep} +\setfont\textsl{sl10 scaled \mainmagstep} +\setfont\textsf{ss10 scaled \mainmagstep} +\setfont\textsc{csc10 scaled \mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\setfont\defbf{bx10 scaled \magstep1} %was 1314 +\setfont\deftt{tt10 scaled \magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices and small examples. +% We actually use the slanted font rather than the italic, +% because texinfo normally uses the slanted fonts for that. +% Do not make many font distinctions in general in the index, since they +% aren't very useful. +\setfont\ninett{tt9} +\setfont\indrm{r9} +\setfont\indit{sl9} +\let\indsl=\indit +\let\indtt=\ninett +\let\indsf=\indrm +\let\indbf=\indrm +\setfont\indsc{csc10 at 9pt} +\font\indi=cmmi9 +\font\indsy=cmsy9 + +% Fonts for headings +\setfont\chaprm{bx12 scaled \magstep2} +\setfont\chapit{ti12 scaled \magstep2} +\setfont\chapsl{sl12 scaled \magstep2} +\setfont\chaptt{tt12 scaled \magstep2} +\setfont\chapsf{ss12 scaled \magstep2} +\let\chapbf=\chaprm +\setfont\chapsc{csc10 scaled\magstep3} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +\setfont\secrm{bx12 scaled \magstep1} +\setfont\secit{ti12 scaled \magstep1} +\setfont\secsl{sl12 scaled \magstep1} +\setfont\sectt{tt12 scaled \magstep1} +\setfont\secsf{ss12 scaled \magstep1} +\setfont\secbf{bx12 scaled \magstep1} +\setfont\secsc{csc10 scaled\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. +% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. +% \setfont\ssecsl{sl10 scaled \magstep1} +% \setfont\ssectt{tt10 scaled \magstep1} +% \setfont\ssecsf{ss10 scaled \magstep1} + +%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than +%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. +%\setfont\ssectt{tt10 scaled 1315} +%\setfont\ssecsf{ss10 scaled 1315} + +%\let\ssecbf=\ssecrm + +\setfont\ssecrm{bx12 scaled \magstephalf} +\setfont\ssecit{ti12 scaled \magstephalf} +\setfont\ssecsl{sl12 scaled \magstephalf} +\setfont\ssectt{tt12 scaled \magstephalf} +\setfont\ssecsf{ss12 scaled \magstephalf} +\setfont\ssecbf{bx12 scaled \magstephalf} +\setfont\ssecsc{csc10 scaled \magstep1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled \magstep1 +% The smallcaps and symbol fonts should actually be scaled \magstep1.5, +% but that is not a standard magnification. + +% Fonts for title page: +\setfont\titlerm{bx12 scaled \magstep3} +\let\authorrm = \secrm + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts, we +% don't bother to reset \scriptfont and \scriptscriptfont (which would +% also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy + \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf + \textfont\ttfam = \tentt \textfont\sffam = \tensf +} + + +% The font-changing commands redefine the meanings of \tenSTYLE, instead +% of just \STYLE. We do this so that font changes will continue to work +% in math mode, where it is the current \fam that is relevant in most +% cases, not the current. Plain TeX does, for example, +% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need +% to redefine \bf itself. +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \resetmathfonts} +\def\chapfonts{% + \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl + \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \resetmathfonts} +\def\secfonts{% + \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl + \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \resetmathfonts} +\def\subsecfonts{% + \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl + \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \resetmathfonts} +\def\indexfonts{% + \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl + \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy + \resetmathfonts} + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\setfont\shortcontrm{r12} +\setfont\shortcontbf{bx12} +\setfont\shortcontsl{sl12} + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \smartitalic{ARG} outputs arg in italics, followed by an italic correction +% unless the following character is such as not to need one. +\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} +\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartitalic +\let\dfn=\smartitalic +\let\emph=\smartitalic +\let\cite=\smartitalic + +\def\b#1{{\bf #1}} +\let\strong=\b + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +\def\t#1{% + {\tt \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont=\t +\def\samp #1{`\tclose{#1}'\null} +\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +\let\file=\samp + +% @code is a modification of @t, +% which makes spaces the same size as normal in the surrounding text. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \frenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in \code. +% Otherwise, it is too hard to avoid overful hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate an a dash. +% -- rms. +{ +\catcode`\-=\active +\catcode`\_=\active +\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} +% The following is used by \doprintindex to insure that long function names +% wrap around. It is necessary for - and _ to be active before the index is +% read from the file, as \entry parses the arguments long before \code is +% ever called. -- mycroft +\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} +} + +\def\realdash{-} +\def\realunder{_} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{\normalunderscore\discretionary{}{}{}} +\def\codex #1{\tclose{#1}\endgroup} + +%\let\exp=\tclose %Was temporary + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. + +\def\xkey{\key} +\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% +\ifx\one\xkey\ifx\threex\three \key{#2}% +\else\tclose{\look}\fi +\else\tclose{\look}\fi} + +% Typeset a dimension, e.g., `in' or `pt'. The only reason for the +% argument is to make the input look right: @dmn{pt} instead of +% @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} + +\def\l#1{{\li #1}\null} % + +\def\r#1{{\rm #1}} % roman font +% Use of \lowercase was suggested. +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\def\titlefont#1{{\titlerm #1}} + +\newif\ifseenauthor +\newif\iffinishedtitlepage + +\def\shorttitlepage{\parsearg\shorttitlepagezzz} +\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\def\titlepage{\begingroup \parindent=0pt \textfonts + \let\subtitlerm=\tenrm +% I deinstalled the following change because \cmr12 is undefined. +% This change was not in the ChangeLog anyway. --rms. +% \let\subtitlerm=\cmr12 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + % + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % + % Now you can print the title using @title. + \def\title{\parsearg\titlezzz}% + \def\titlezzz##1{\leftline{\titlefont{##1}} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Now you can put text using @subtitle. + \def\subtitle{\parsearg\subtitlezzz}% + \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% + % + % @author should come last, but may come many times. + \def\author{\parsearg\authorzzz}% + \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi + {\authorfont \leftline{##1}}}% + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \oldpage + \let\page = \oldpage + \hbox{}}% +% \def\page{\oldpage \hbox{}} +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + \HEADINGSon +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks \evenheadline % Token sequence for heading line of even pages +\newtoks \oddheadline % Token sequence for heading line of odd pages +\newtoks \evenfootline % Token sequence for footing line of even pages +\newtoks \oddfootline % Token sequence for footing line of odd pages + +% Now make Tex use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + +\def\evenheading{\parsearg\evenheadingxxx} +\def\oddheading{\parsearg\oddheadingxxx} +\def\everyheading{\parsearg\everyheadingxxx} + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\oddfooting{\parsearg\oddfootingxxx} +\def\everyfooting{\parsearg\everyfootingxxx} + +{\catcode`\@=0 % + +\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} +\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} +\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} +\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} +\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} +\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} +\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +% +}% unbind the catcode of @. + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\HEADINGSoff{ +\global\evenheadline={\hfil} \global\evenfootline={\hfil} +\global\oddheadline={\hfil} \global\oddfootline={\hfil}} +\HEADINGSoff +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +% Subroutines used in generating headings +% Produces Day Month Year style of output. +\def\today{\number\day\space +\ifcase\month\or +January\or February\or March\or April\or May\or June\or +July\or August\or September\or October\or November\or December\fi +\space\number\year} + +% Use this if you want the Month Day, Year style of output. +%\def\today{\ifcase\month\or +%January\or February\or March\or April\or May\or June\or +%July\or August\or September\or October\or November\or December\fi +%\space\number\day, \number\year} + +% @settitle line... specifies the title of the document, for headings +% It generates no output of its own + +\def\thistitle{No Title} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + +\message{tables,} + +% @tabs -- simple alignment + +% These don't work. For one thing, \+ is defined as outer. +% So these macros cannot even be defined. + +%\def\tabs{\parsearg\tabszzz} +%\def\tabszzz #1{\settabs\+#1\cr} +%\def\tabline{\parsearg\tablinezzz} +%\def\tablinezzz #1{\+#1\cr} +%\def\&{&} + +% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @vtable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} +\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} + +\def\internalBkitem{\smallbreak \parsearg\kitemzzz} +\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} + +\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% + \itemzzz {#1}} + +\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% + \itemzzz {#1}} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemfont{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % Be sure we are not still in the middle of a paragraph. + %{\parskip = 0in + %\par + %}% + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. Unfortunately + % we can't prevent a possible page break at the following + % \baselineskip glue. + \nobreak + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. Since that + % text will be indented by \tableindent, we make the item text be in + % a zero-width box. + \noindent + \rlap{\hskip -\tableindent\box0}\ignorespaces% + \endgroup% + \itemxneedsnegativevskiptrue% + \fi +} + +\def\item{\errmessage{@item while not in a table}} +\def\itemx{\errmessage{@itemx while not in a table}} +\def\kitem{\errmessage{@kitem while not in a table}} +\def\kitemx{\errmessage{@kitemx while not in a table}} +\def\xitem{\errmessage{@xitem while not in a table}} +\def\xitemx{\errmessage{@xitemx while not in a table}} + +%% Contains a kludge to get @end[description] to work +\def\description{\tablez{\dontindex}{1}{}{}{}{}} + +\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} +{\obeylines\obeyspaces% +\gdef\tablex #1^^M{% +\tabley\dontindex#1 \endtabley}} + +\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} +{\obeylines\obeyspaces% +\gdef\ftablex #1^^M{% +\tabley\fnitemindex#1 \endtabley +\def\Eftable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} +{\obeylines\obeyspaces% +\gdef\vtablex #1^^M{% +\tabley\vritemindex#1 \endtabley +\def\Evtable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\dontindex #1{} +\def\fnitemindex #1{\doind {fn}{\code{#1}}}% +\def\vritemindex #1{\doind {vr}{\code{#1}}}% + +{\obeyspaces % +\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% +\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} + +\def\tablez #1#2#3#4#5#6{% +\aboveenvbreak % +\begingroup % +\def\Edescription{\Etable}% Necessary kludge. +\let\itemindex=#1% +\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % +\ifnum 0#4>0 \tableindent=#4\mil \fi % +\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % +\def\itemfont{#2}% +\itemmax=\tableindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \tableindent % +\exdentamount=\tableindent +\parindent = 0pt +\parskip = \smallskipamount +\ifdim \parskip=0pt \parskip=2pt \fi% +\def\Etable{\endgraf\afterenvbreak\endgroup}% +\let\item = \internalBitem % +\let\itemx = \internalBitemx % +\let\kitem = \internalBkitem % +\let\kitemx = \internalBkitemx % +\let\xitem = \internalBxitem % +\let\xitemx = \internalBxitemx % +} + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\def\itemize{\parsearg\itemizezzz} + +\def\itemizezzz #1{% + \begingroup % ended by the @end itemsize + \itemizey {#1}{\Eitemize} +} + +\def\itemizey #1#2{% +\aboveenvbreak % +\itemmax=\itemindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \itemindent % +\exdentamount=\itemindent +\parindent = 0pt % +\parskip = \smallskipamount % +\ifdim \parskip=0pt \parskip=2pt \fi% +\def#2{\endgraf\afterenvbreak\endgroup}% +\def\itemcontents{#1}% +\let\item=\itemizeitem} + +% Set sfcode to normal for the chars that usually have another value. +% These are `.?!:;,' +\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 + \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\def\enumerate{\parsearg\enumeratezzz} +\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + \begingroup % ended by the @end enumerate + % + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a . + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call itemizey, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \itemizey{#1.}\Eenumerate\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + +% Definition of @item while inside @itemize. + +\def\itemizeitem{% +\advance\itemno by 1 +{\let\par=\endgraf \smallbreak}% +\ifhmode \errmessage{\in hmode at itemizeitem}\fi +{\parskip=0in \hskip 0pt +\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% +\vadjust{\penalty 1200}}% +\flushcr} + +% @multitable macros +% Amy Hendrickson, 8/18/94 +% +% @multitable ... @endmultitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @percentofhsize .2 .3 .5 +% @item ... +% +% Numbers following @percentofhsize are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab, @multicolumn or @endmulticolumn do not need to be on their +% own lines, but it will not hurt if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @endmultitable + +% Default dimensions may be reset by user. +% @intableparskip will set vertical space between paragraphs in table. +% @intableparindent will set paragraph indent in table. +% @spacebetweencols will set horizontal space to be left between columns. +% @spacebetweenlines will set vertical space to be left between lines. + +%%%% +% Dimensions + +\newdimen\intableparskip +\newdimen\intableparindent +\newdimen\spacebetweencols +\newdimen\spacebetweenlines +\intableparskip=0pt +\intableparindent=6pt +\spacebetweencols=12pt +\spacebetweenlines=12pt + +%%%% +% Macros used to set up halign preamble: +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\percentofhsize\relax +\def\xpercentofhsize{\percentofhsize} +\newif\ifsetpercent + +\newcount\colcount +\def\setuptable#1{\def\firstarg{#1}% +\ifx\firstarg\xendsetuptable\let\go\relax% +\else + \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \else + \ifsetpercent + \if#1.\else% + \global\advance\colcount by1 % + \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% + \fi + \else + \global\advance\colcount by1 + \setbox0=\hbox{#1}% + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi% + \fi% + \let\go\setuptable% +\fi\go} +%%%% +% multitable syntax +\def\tab{&} + +%%%% +% @multitable ... @endmultitable definitions: + +\def\multitable#1\item{\bgroup +\let\item\cr +\tolerance=9500 +\hbadness=9500 +\parskip=\intableparskip +\parindent=\intableparindent +\overfullrule=0pt +\global\colcount=0\relax% +\def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% + % To parse everything between @multitable and @item : +\def\one{#1}\expandafter\setuptable\one\endsetuptable + % Need to reset this to 0 after \setuptable. +\global\colcount=0\relax% + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. +\halign\bgroup&\global\advance\colcount by 1\relax% +\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname + % In order to keep entries from bumping into each other + % we will add a \leftskip of \spacebetweencols to all columns after + % the first one. + % If a template has been used, we will add \spacebetweencols + % to the width of each template entry. + % If user has set preamble in terms of percent of \hsize + % we will use that dimension as the width of the column, and + % the \leftskip will keep entries from bumping into each other. + % Table will start at left margin and final column will justify at + % right margin. +\ifnum\colcount=1 +\else + \ifsetpercent + \else + % If user has set preamble in terms of percent of \hsize + % we will advance \hsize by \spacebetweencols + \advance\hsize by \spacebetweencols + \fi + % In either case we will make \leftskip=\spacebetweencols: +\leftskip=\spacebetweencols +\fi +\noindent##}\cr% + % \everycr will reset column counter, \colcount, at the end of + % each line. Every column entry will cause \colcount to advance by one. + % The table preamble + % looks at the current \colcount to find the correct column width. +\global\everycr{\noalign{\nointerlineskip\vskip\spacebetweenlines +\filbreak%% keeps underfull box messages off when table breaks over pages. +\global\colcount=0\relax}}} + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within \newindex. +{\catcode`\@=11 +\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. + +\def\newindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#1}} +} + +% @defindex foo == \newindex{foo} + +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. + +\def\newcodeindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#1}} +} + +\def\defcodeindex{\parsearg\newcodeindex} + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +\def\synindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#2}}% +} + +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +\def\syncodeindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#2}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +\def\indexdummies{% +% Take care of the plain tex accent commands. +\def\"{\realbackslash "}% +\def\`{\realbackslash `}% +\def\'{\realbackslash '}% +\def\^{\realbackslash ^}% +\def\~{\realbackslash ~}% +\def\={\realbackslash =}% +\def\b{\realbackslash b}% +\def\c{\realbackslash c}% +\def\d{\realbackslash d}% +\def\u{\realbackslash u}% +\def\v{\realbackslash v}% +\def\H{\realbackslash H}% +% Take care of the plain tex special European modified letters. +\def\oe{\realbackslash oe}% +\def\ae{\realbackslash ae}% +\def\aa{\realbackslash aa}% +\def\OE{\realbackslash OE}% +\def\AE{\realbackslash AE}% +\def\AA{\realbackslash AA}% +\def\o{\realbackslash o}% +\def\O{\realbackslash O}% +\def\l{\realbackslash l}% +\def\L{\realbackslash L}% +\def\ss{\realbackslash ss}% +% Take care of texinfo commands likely to appear in an index entry. +\def\_{{\realbackslash _}}% +\def\w{\realbackslash w }% +\def\bf{\realbackslash bf }% +\def\rm{\realbackslash rm }% +\def\sl{\realbackslash sl }% +\def\sf{\realbackslash sf}% +\def\tt{\realbackslash tt}% +\def\gtr{\realbackslash gtr}% +\def\less{\realbackslash less}% +\def\hat{\realbackslash hat}% +\def\char{\realbackslash char}% +\def\TeX{\realbackslash TeX}% +\def\dots{\realbackslash dots }% +\def\copyright{\realbackslash copyright }% +\def\tclose##1{\realbackslash tclose {##1}}% +\def\code##1{\realbackslash code {##1}}% +\def\samp##1{\realbackslash samp {##1}}% +\def\t##1{\realbackslash r {##1}}% +\def\r##1{\realbackslash r {##1}}% +\def\i##1{\realbackslash i {##1}}% +\def\b##1{\realbackslash b {##1}}% +\def\cite##1{\realbackslash cite {##1}}% +\def\key##1{\realbackslash key {##1}}% +\def\file##1{\realbackslash file {##1}}% +\def\var##1{\realbackslash var {##1}}% +\def\kbd##1{\realbackslash kbd {##1}}% +\def\dfn##1{\realbackslash dfn {##1}}% +\def\emph##1{\realbackslash emph {##1}}% +\unsepspaces +} + +% If an index command is used in an @example environment, any spaces +% therein should become regular spaces in the raw index file, not the +% expansion of \tie (\\leavevmode \penalty \@M \ ). +{\obeyspaces + \gdef\unsepspaces{\obeyspaces\let =\space}} + +% \indexnofonts no-ops all font-change commands. +% This is used when outputting the strings to sort the index by. +\def\indexdummyfont#1{#1} +\def\indexdummytex{TeX} +\def\indexdummydots{...} + +\def\indexnofonts{% +% Just ignore accents. +\let\"=\indexdummyfont +\let\`=\indexdummyfont +\let\'=\indexdummyfont +\let\^=\indexdummyfont +\let\~=\indexdummyfont +\let\==\indexdummyfont +\let\b=\indexdummyfont +\let\c=\indexdummyfont +\let\d=\indexdummyfont +\let\u=\indexdummyfont +\let\v=\indexdummyfont +\let\H=\indexdummyfont +% Take care of the plain tex special European modified letters. +\def\oe{oe}% +\def\ae{ae}% +\def\aa{aa}% +\def\OE{OE}% +\def\AE{AE}% +\def\AA{AA}% +\def\o{o}% +\def\O{O}% +\def\l{l}% +\def\L{L}% +\def\ss{ss}% +\let\w=\indexdummyfont +\let\t=\indexdummyfont +\let\r=\indexdummyfont +\let\i=\indexdummyfont +\let\b=\indexdummyfont +\let\emph=\indexdummyfont +\let\strong=\indexdummyfont +\let\cite=\indexdummyfont +\let\sc=\indexdummyfont +%Don't no-op \tt, since it isn't a user-level command +% and is used in the definitions of the active chars like <, >, |... +%\let\tt=\indexdummyfont +\let\tclose=\indexdummyfont +\let\code=\indexdummyfont +\let\file=\indexdummyfont +\let\samp=\indexdummyfont +\let\kbd=\indexdummyfont +\let\key=\indexdummyfont +\let\var=\indexdummyfont +\let\TeX=\indexdummytex +\let\dots=\indexdummydots +} + +% To define \realbackslash, we must make \ not be an escape. +% We must first make another character (@) an escape +% so we do not become unable to do a definition. + +{\catcode`\@=0 \catcode`\\=\other +@gdef@realbackslash{\}} + +\let\indexbackslash=0 %overridden during \printindex. + +\let\SETmarginindex=\relax %initialize! +% workhorse for all \fooindexes +% #1 is name of index, #2 is stuff to put there +\def\doind #1#2{% +% Put the index entry in the margin if desired. +\ifx\SETmarginindex\relax\else% +\insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% +\fi% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% Expand all macros now EXCEPT \folio +\def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now +% so it will be output as is; and it will print as backslash in the indx. +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}}}% +\temp }% +}\penalty\count10}} + +\def\dosubind #1#2#3{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% +\def\rawbackslashxx{\indexbackslash}% +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2 #3}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% +\temp }% +}\penalty\count10}} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% This is what you call to cause a particular index to get printed. +% Write +% @unnumbered Function Index +% @printindex fn + +\def\printindex{\parsearg\doprintindex} + +\def\doprintindex#1{% + \tex + \dobreak \chapheadingskip {10000} + \catcode`\%=\other\catcode`\&=\other\catcode`\#=\other + \catcode`\$=\other + \catcode`\~=\other + \indexbreaks + % + % The following don't help, since the chars were translated + % when the raw index was written, and their fonts were discarded + % due to \indexnofonts. + %\catcode`\"=\active + %\catcode`\^=\active + %\catcode`\_=\active + %\catcode`\|=\active + %\catcode`\<=\active + %\catcode`\>=\active + % % + \def\indexbackslash{\rawbackslashxx} + \indexfonts\rm \tolerance=9500 \advance\baselineskip -1pt + \begindoublecolumns + % + % See if the index file exists and is nonempty. + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + (Index is nonexistent) + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + (Index is empty) + \else + \input \jobname.#1s + \fi + \fi + \closein 1 + \enddoublecolumns + \Etex +} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +% Same as \bigskipamount except no shrink. +% \balancecolumns gets confused if there is any shrink. +\newskip\initialskipamount \initialskipamount 12pt plus4pt + +\def\initial #1{% +{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt +\ifdim\lastskip<\initialskipamount +\removelastskip \penalty-200 \vskip \initialskipamount\fi +\line{\secbf#1\hfill}\kern 2pt\penalty10000}} + +% This typesets a paragraph consisting of #1, dot leaders, and then #2 +% flush to the right margin. It is used for index and table of contents +% entries. The paragraph is indented by \leftskip. +% +\def\entry #1#2{\begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent=2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % Start a ``paragraph'' for the index entry so the line breaking + % parameters we've set above will have an effect. + \noindent + % + % Insert the text of the index entry. TeX will do line-breaking on it. + #1% + % The following is kludged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \def\tempa{{\rm }}% + \def\tempb{#2}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd\ \else% + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ #2% The page number ends the paragraph. + \fi% + \par +\endgroup} + +% Like \dotfill except takes at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm + +\def\secondary #1#2{ +{\parfillskip=0in \parskip=0in +\hangindent =1in \hangafter=1 +\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par +}} + +%% Define two-column mode, which is used in indexes. +%% Adapted from the TeXbook, page 416. +\catcode `\@=11 + +\newbox\partialpage + +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup + % Grab any single-column material above us. + \output = {\global\setbox\partialpage + =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% + \eject + % + % Now switch to the double-column output routine. + \output={\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it once. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +- < + % 1pt) as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize + \doublecolumnpagegoal +} + +\def\enddoublecolumns{\eject \endgroup \pagegoal=\vsize \unvbox\partialpage} + +\def\doublecolumnsplit{\splittopskip=\topskip \splitmaxdepth=\maxdepth + \global\dimen@=\pageheight \global\advance\dimen@ by-\ht\partialpage + \global\setbox1=\vsplit255 to\dimen@ \global\setbox0=\vbox{\unvbox1} + \global\setbox3=\vsplit255 to\dimen@ \global\setbox2=\vbox{\unvbox3} + \ifdim\ht0>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi + \ifdim\ht2>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi +} +\def\doublecolumnpagegoal{% + \dimen@=\vsize \advance\dimen@ by-2\ht\partialpage \global\pagegoal=\dimen@ +} +\def\pagesofar{\unvbox\partialpage % + \hsize=\doublecolumnhsize % have to restore this since output routine + \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}} +\def\doublecolumnout{% + \setbox5=\copy255 + {\vbadness=10000 \doublecolumnsplit} + \ifvbox255 + \setbox0=\vtop to\dimen@{\unvbox0} + \setbox2=\vtop to\dimen@{\unvbox2} + \onepageout\pagesofar \unvbox255 \penalty\outputpenalty + \else + \setbox0=\vbox{\unvbox5} + \ifvbox0 + \dimen@=\ht0 \advance\dimen@ by\topskip \advance\dimen@ by-\baselineskip + \divide\dimen@ by2 \splittopskip=\topskip \splitmaxdepth=\maxdepth + {\vbadness=10000 + \loop \global\setbox5=\copy0 + \setbox1=\vsplit5 to\dimen@ + \setbox3=\vsplit5 to\dimen@ + \ifvbox5 \global\advance\dimen@ by1pt \repeat + \setbox0=\vbox to\dimen@{\unvbox1} + \setbox2=\vbox to\dimen@{\unvbox3} + \global\setbox\partialpage=\vbox{\pagesofar} + \doublecolumnpagegoal + } + \fi + \fi +} + +\catcode `\@=\other +\message{sectioning,} +% Define chapters, sections, etc. + +\newcount \chapno +\newcount \secno \secno=0 +\newcount \subsecno \subsecno=0 +\newcount \subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount \appendixno \appendixno = `\@ +\def\appendixletter{\char\the\appendixno} + +\newwrite \contentsfile +% This is called from \setfilename. +\def\opencontents{\openout \contentsfile = \jobname.toc} + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise + +\def\thischapter{} \def\thissection{} +\def\seccheck#1{\if \pageno<0 % +\errmessage{@#1 not allowed after generating table of contents}\fi +% +} + +\def\chapternofonts{% +\let\rawbackslash=\relax% +\let\frenchspacing=\relax% +\def\result{\realbackslash result} +\def\equiv{\realbackslash equiv} +\def\expansion{\realbackslash expansion} +\def\print{\realbackslash print} +\def\TeX{\realbackslash TeX} +\def\dots{\realbackslash dots} +\def\copyright{\realbackslash copyright} +\def\tt{\realbackslash tt} +\def\bf{\realbackslash bf } +\def\w{\realbackslash w} +\def\less{\realbackslash less} +\def\gtr{\realbackslash gtr} +\def\hat{\realbackslash hat} +\def\char{\realbackslash char} +\def\tclose##1{\realbackslash tclose {##1}} +\def\code##1{\realbackslash code {##1}} +\def\samp##1{\realbackslash samp {##1}} +\def\r##1{\realbackslash r {##1}} +\def\b##1{\realbackslash b {##1}} +\def\key##1{\realbackslash key {##1}} +\def\file##1{\realbackslash file {##1}} +\def\kbd##1{\realbackslash kbd {##1}} +% These are redefined because @smartitalic wouldn't work inside xdef. +\def\i##1{\realbackslash i {##1}} +\def\cite##1{\realbackslash cite {##1}} +\def\var##1{\realbackslash var {##1}} +\def\emph##1{\realbackslash emph {##1}} +\def\dfn##1{\realbackslash dfn {##1}} +} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raise/lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% Choose a numbered-heading macro +% #1 is heading level if unmodified by @raisesections or @lowersections +% #2 is text for heading +\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \chapterzzz{#2} +\or + \seczzz{#2} +\or + \numberedsubseczzz{#2} +\or + \numberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \chapterzzz{#2} + \else + \numberedsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses appendix heading levels +\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \appendixzzz{#2} +\or + \appendixsectionzzz{#2} +\or + \appendixsubseczzz{#2} +\or + \appendixsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \appendixzzz{#2} + \else + \appendixsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses numberless heading levels +\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \unnumberedzzz{#2} +\or + \unnumberedseczzz{#2} +\or + \unnumberedsubseczzz{#2} +\or + \unnumberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \unnumberedzzz{#2} + \else + \unnumberedsubsubseczzz{#2} + \fi +\fi +} + + +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{\seccheck{chapter}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \chapno by 1 \message{\putwordChapter \the\chapno}% +\chapmacro {#1}{\the\chapno}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +% We don't substitute the actual chapter name into \thischapter +% because we don't want its macros evaluated now. +\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec +}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{\seccheck{appendix}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \appendixno by 1 \message{Appendix \appendixletter}% +\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry + {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\global\let\section = \appendixsec +\global\let\subsection = \appendixsubsec +\global\let\subsubsection = \appendixsubsubsec +}} + +\outer\def\top{\parsearg\unnumberedyyy} +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{\seccheck{unnumbered}% +\secno=0 \subsecno=0 \subsubsecno=0 +% +% This used to be simply \message{#1}, but TeX fully expands the +% argument to \message. Therefore, if #1 contained @-commands, TeX +% expanded them. For example, in `@unnumbered The @cite{Book}', TeX +% expanded @cite (which turns out to cause errors because \cite is meant +% to be executed, not expanded). +% +% Anyway, we don't want the fully-expanded definition of @cite to appear +% as a result of the \message, we just want `@cite' itself. We use +% \the to achieve this: TeX expands \the only once, +% simply yielding the contents of the . +\toks0 = {#1}\message{(\the\toks0)}% +% +\unnumbchapmacro {#1}% +\gdef\thischapter{#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\global\let\section = \unnumberedsec +\global\let\subsection = \unnumberedsubsec +\global\let\subsubsection = \unnumberedsubsubsec +}} + +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{\seccheck{section}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{\seccheck{appendixsection}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{\seccheck{subsection}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry % + {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} + {\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry{#1}% + {\appendixletter} + {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +% These are variants which are not "outer", so they can appear in @ifinfo. +% Actually, they should now be obsolete; ordinary section commands should work. +\def\infotop{\parsearg\unnumberedzzz} +\def\infounnumbered{\parsearg\unnumberedzzz} +\def\infounnumberedsec{\parsearg\unnumberedseczzz} +\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} +\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} + +\def\infoappendix{\parsearg\appendixzzz} +\def\infoappendixsec{\parsearg\appendixseczzz} +\def\infoappendixsubsec{\parsearg\appendixsubseczzz} +\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} + +\def\infochapter{\parsearg\chapterzzz} +\def\infosection{\parsearg\sectionzzz} +\def\infosubsection{\parsearg\subsectionzzz} +\def\infosubsubsection{\parsearg\subsubsectionzzz} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +% NOTE on use of \vbox for chapter headings, section headings, and +% such: +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. +% 3) Likewise, headings look best if no \parindent is used, and +% if justification is not attempted. Hence \raggedright. + + +\def\majorheading{\parsearg\majorheadingzzz} +\def\majorheadingzzz #1{% +{\advance\chapheadingskip by 10pt \chapbreak }% +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\chapheading{\parsearg\chapheadingzzz} +\def\chapheadingzzz #1{\chapbreak % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\heading{\parsearg\secheadingi} + +\def\subheading{\parsearg\subsecheadingi} + +\def\subsubheading{\parsearg\subsubsecheadingi} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +%%% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} + +%%% Define plain chapter starts, and page on/off switching for it +% Parameter controlling skip before chapter headings (if needed) + +\newskip \chapheadingskip \chapheadingskip = 30pt plus 8pt minus 4pt + +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{ +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{ +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{ +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain} + +\def\chfplain #1#2{% + \pchapsepmacro + {% + \chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #2\enspace #1}% + }% + \bigskip + \penalty5000 +} + +\def\unnchfplain #1{% +\pchapsepmacro % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} + +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen} + +% Parameter controlling skip before section headings. + +\newskip \subsecheadingskip \subsecheadingskip = 17pt plus 8pt minus 4pt +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} + +\newskip \secheadingskip \secheadingskip = 21pt plus 8pt minus 4pt +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} + +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + +% Section fonts are the base font at magstep2, which produces +% a size a bit more than 14 points in the default situation. + +\def\secheading #1#2#3{\secheadingi {#2.#3\enspace #1}} +\def\plainsecheading #1{\secheadingi {#1}} +\def\secheadingi #1{{\advance \secheadingskip by \parskip % +\secheadingbreak}% +{\secfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + + +% Subsection fonts are the base font at magstep1, +% which produces a size of 12 points. + +\def\subsecheading #1#2#3#4{\subsecheadingi {#2.#3.#4\enspace #1}} +\def\subsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + +\def\subsubsecfonts{\subsecfonts} % Maybe this should change: + % Perhaps make sssec fonts scaled + % magstep half +\def\subsubsecheading #1#2#3#4#5{\subsubsecheadingi {#2.#3.#4.#5\enspace #1}} +\def\subsubsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsubsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000} + + +\message{toc printing,} + +% Finish up the main text and prepare to read what we've written +% to \contentsfile. + +\newskip\contentsrightmargin \contentsrightmargin=1in +\def\startcontents#1{% + \pagealignmacro + \immediate\closeout \contentsfile + \ifnum \pageno>0 + \pageno = -1 % Request roman numbered pages. + \fi + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + \catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. +} + + +% Normal (long) toc. +\outer\def\contents{% + \startcontents{\putwordTableofContents}% + \input \jobname.toc + \endgroup + \vfill \eject +} + +% And just the chapters. +\outer\def\summarycontents{% + \startcontents{\putwordShortContents}% + % + \let\chapentry = \shortchapentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \rm + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\unnumbsecentry ##1##2{} + \def\subsecentry ##1##2##3##4##5{} + \def\unnumbsubsecentry ##1##2{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \def\unnumbsubsubsecentry ##1##2{} + \input \jobname.toc + \endgroup + \vfill \eject +} +\let\shortcontents = \summarycontents + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Chapter-level things, for both the long and short contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} + +% See comments in \dochapentry re vbox and related settings +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% +} + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. +% We could simplify the code here by writing out an \appendixentry +% command in the toc file for appendices, instead of using \chapentry +% for both, but it doesn't seem worth it. +\setbox0 = \hbox{\shortcontrm \putwordAppendix } +\newdimen\shortappendixwidth \shortappendixwidth = \wd0 + +\def\shortchaplabel#1{% + % We typeset #1 in a box of constant width, regardless of the text of + % #1, so the chapter titles will come out aligned. + \setbox0 = \hbox{#1}% + \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi + % + % This space should be plenty, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in in \shortchapentry above.) + \advance\dimen0 by 1.1em + \hbox to \dimen0{#1\hfil}% +} + +\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} +\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} + + +% This parameter controls the indentation of the various levels. +\newdimen\tocindent \tocindent = 3pc + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we would want to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno{#2}}% + \endgroup + \nobreak\vskip .25\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +% Final typesetting of a toc entry; we use the same \entry macro as for +% the index entries, but we want to suppress hyphenation here. (We +% can't do that in the \entry macro, since index entries might consist +% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) +% +% \turnoffactive is for the sake of @" used for umlauts. +\def\tocentry#1#2{\begingroup + \hyphenpenalty = 10000 + \entry{\turnoffactive #1}{\turnoffactive #2}% +\endgroup} + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\let\subsecentryfonts = \textfonts +\let\subsubsecentryfonts = \textfonts + + +\message{environments,} + +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% Furthermore, these definitions must come after we define our fonts. +\newbox\dblarrowbox \newbox\longdblarrowbox +\newbox\pushcharbox \newbox\bullbox +\newbox\equivbox \newbox\errorbox + +\let\ptexequiv = \equiv + +%{\tentt +%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} +%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} +%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} +%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} +% Adapted from the manmac format (p.420 of TeXbook) +%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex +% depth .1ex\hfil} +%} + +\def\point{$\star$} + +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} + +\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% Adapted from the TeXbook's \boxit. +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} + +\global\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{ + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} + +% The @error{} command. +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @tex ... @end tex escapes into raw Tex temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain tex @ character. + +\def\tex{\begingroup +\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 +\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 +\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie +\catcode `\%=14 +\catcode 43=12 +\catcode`\"=12 +\catcode`\==12 +\catcode`\|=12 +\catcode`\<=12 +\catcode`\>=12 +\escapechar=`\\ +% +\let\~=\ptextilde +\let\{=\ptexlbrace +\let\}=\ptexrbrace +\let\.=\ptexdot +\let\*=\ptexstar +\let\dots=\ptexdots +\def\@{@}% +\let\bullet=\ptexbullet +\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext \let\l=\ptexl +\let\L=\ptexL +% +\let\Etex=\endgroup} + +% Define @lisp ... @endlisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @endlisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% Make each space character in the input produce a normal interword +% space in the output. Don't allow a line break at this space, as this +% is used only in environments like @example, where each line of input +% should produce a line of output anyway. +% +{\obeyspaces % +\gdef\sepspaces{\obeyspaces\let =\tie}} + +% Define \obeyedspace to be our active space, whatever it is. This is +% for use in \parsearg. +{\sepspaces% +\global\let\obeyedspace= } + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip +% +\def\aboveenvbreak{{\advance\envskipamount by \parskip +\endgraf \ifdim\lastskip<\envskipamount +\removelastskip \penalty-50 \vskip\envskipamount \fi}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \cartouche: draw rectangle w/rounded corners around argument +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\long\def\cartouche{% +\begingroup + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt %we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip +\def\Ecartouche{% + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup +\endgroup +}} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \inENV % This group ends at the end of the body + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \singlespace + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + \parindent = 0pt + \emergencystretch = 0pt % don't try to avoid overfull boxes + % @cartouche defines \nonarrowing to inhibit narrowing + % at next level down. + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \let\exdent=\nofillexdent + \let\nonarrowing=\relax + \fi +} + +% To ending an @example-like environment, we first end the paragraph +% (via \afterenvbreak's vertical glue), and then the group. That way we +% keep the zero \parskip that the environments set -- \parskip glue +% will be inserted at the beginning of the next paragraph in the +% document, after the environment. +% +\def\nonfillfinish{\afterenvbreak\endgroup}% + +% This macro is +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + \rawbackslash % have \ input char produce \ char from current font + \gobble +} + +% Define the \E... control sequence only if we are inside the +% environment, so the error checking in \end will work. +% +% We must call \lisp last in the definition, since it reads the +% return following the @example (or whatever) command. +% +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} +\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp. This is not used unless the @smallbook +% command is given. Originally contributed by Pavel@xerox. +% +\def\smalllispx{\begingroup + \nonfillstart + \let\Esmalllisp = \nonfillfinish + \let\Esmallexample = \nonfillfinish + % + % Smaller interline space and fonts for small examples. + \setleading{10pt}% + \indexfonts \tt + \rawbackslash % make \ output the \ character from the current font (tt) + \gobble +} + +% This is @display; same as @lisp except use roman font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} + +% This is @format; same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} + +% @flushleft (same as @format) and @flushright. +% +\def\flushleft{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushleft = \nonfillfinish + \gobble +} +\def\flushright{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushright = \nonfillfinish + \advance\leftskip by 0pt plus 1fill + \gobble} + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. +% +\def\quotation{% + \begingroup\inENV %This group ends at the end of the @quotation body + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \singlespace + \parindent=0pt + % We have retained a nonzero parskip for the environment, since we're + % doing normal filling. So to avoid extra space below the environment... + \def\Equotation{\parskip = 0pt \nonfillfinish}% + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \advance\rightskip by \lispnarrowing + \exdentamount = \lispnarrowing + \let\nonarrowing = \relax + \fi +} + +\message{defuns,} +% Define formatter for defuns +% First, allow user to change definition object font (\df) internally +\def\setdeffont #1 {\csname DEF#1\endcsname} + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deftypemargin \deftypemargin=12pt +\newskip\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount +% define \functionparens, which makes ( and ) and & do special things. +% \functionparens affects the group it is contained in. +\def\activeparens{% +\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active +\catcode`\[=\active \catcode`\]=\active} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +\global\let(=\lparen \global\let)=\rparen +\global\let[=\lbrack \global\let]=\rbrack + +\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } +\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} +% This is used to turn on special parens +% but make & act ordinary (given that it's active). +\gdef\boldbraxnoamp{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb\let&=\ampnr} + +% Definitions of (, ) and & used in args for functions. +% This is the definition of ( outside of all parentheses. +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % +\global\advance\parencount by 1 } +% +% This is the definition of ( when already inside a level of parens. +\gdef\opnested{\char`\(\global\advance\parencount by 1 } +% +\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. +% also in that case restore the outer-level definition of (. +\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi +\global\advance \parencount by -1 } +% If we encounter &foo, then turn on ()-hacking afterwards +\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } +% +\gdef\normalparens{\boldbrax\let&=\ampnr} +} % End of definition inside \activeparens +%% These parens (in \boldbrax) actually are a little bolder than the +%% contained text. This is especially needed for [ and ] +\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} + +% First, defname, which formats the header line itself. +% #1 should be the function name. +% #2 should be the type of definition, such as "Function". + +\def\defname #1#2{% +% Get the values of \leftskip and \rightskip as they were +% outside the @def... +\dimen2=\leftskip +\advance\dimen2 by -\defbodyindent +\dimen3=\rightskip +\advance\dimen3 by -\defbodyindent +\noindent % +\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% +\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line +\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations +\parshape 2 0in \dimen0 \defargsindent \dimen1 % +% Now output arg 2 ("Function" or some such) +% ending at \deftypemargin from the right margin, +% but stuck inside a box of width 0 so it does not interfere with linebreaking +{% Adjust \hsize to exclude the ambient margins, +% so that \rightline will obey them. +\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 +\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% +% Make all lines underfull and no complaints: +\tolerance=10000 \hbadness=10000 +\advance\leftskip by -\defbodyindent +\exdentamount=\defbodyindent +{\df #1}\enskip % Generate function name +} + +% Actually process the body of a definition +% #1 should be the terminating control sequence, such as \Edefun. +% #2 should be the "another name" control sequence, such as \defunx. +% #3 should be the control sequence that actually processes the header, +% such as \defunheader. + +\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % 61 is `=' +\obeylines\activeparens\spacesplit#3} + +\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} + +\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} + +% These parsing functions are similar to the preceding ones +% except that they do not make parens into active characters. +% These are used for "variables" since they have no arguments. + +\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % +\obeylines\spacesplit#3} + +% This is used for \def{tp,vr}parsebody. It could probably be used for +% some of the others, too, with some judicious conditionals. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV % + \medbreak % + % Define the end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% + \parindent=0in + \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent + \exdentamount=\defbodyindent + \begingroup\obeylines +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{#3{#4}}% +} + +% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the +% type is just `struct', because we lose the braces in `{struct +% termios}' when \spacesplit reads its undelimited argument. Sigh. +% \let\deftpparsebody=\defvrparsebody +% +% So, to get around this, we put \empty in with the type name. That +% way, TeX won't find exactly `{...}' as an undelimited argument, and +% won't strip off the braces. +% +\def\deftpparsebody #1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{\parsetpheaderline{#3{#4}}}\empty +} + +% Fine, but then we have to eventually remove the \empty *and* the +% braces (if any). That's what this does, putting the result in \tptemp. +% +\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% + +% After \spacesplit has done its work, this is called -- #1 is the final +% thing to call, #2 the type name (which starts with \empty), and #3 +% (which might be empty) the arguments. +% +\def\parsetpheaderline#1#2#3{% + \removeemptybraces#2\relax + #1{\tptemp}{#3}% +}% + +\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\spacesplit{#3{#5}}} + +% Split up #2 at the first space token. +% call #1 with two arguments: +% the first is all of #2 before the space token, +% the second is all of #2 after that space token. +% If #2 contains no space token, all of it is passed as the first arg +% and the second is passed as empty. + +{\obeylines +\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% +\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% +\ifx\relax #3% +#1{#2}{}\else #1{#2}{#3#4}\fi}} + +% So much for the things common to all kinds of definitions. + +% Define @defun. + +% First, define the processing that is wanted for arguments of \defun +% Use this to expand the args and terminate the paragraph they make up + +\def\defunargs #1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\hyphenchar\tensl=0 +#1% +\hyphenchar\tensl=45 +\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +\def\deftypefunargs #1{% +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +% Use \boldbraxnoamp, not \functionparens, so that & is not special. +\boldbraxnoamp +\tclose{#1}% avoid \code because of side effects on active chars +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +% Do complete processing of one @defun or @defunx line already parsed. + +% @deffn Command forward-char nchars + +\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} + +\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% +\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defun == @deffn Function + +\def\defun{\defparsebody\Edefun\defunx\defunheader} + +\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Function}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefun int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} + +% #1 is the data type. #2 is the name and args. +\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} +% #1 is the data type, #2 the name, #3 the args. +\def\deftypefunheaderx #1#2 #3\relax{% +\doind {fn}{\code{#2}}% Make entry in function index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Function}% +\deftypefunargs {#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} + +% \defheaderxcond#1\relax$$$ +% puts #1 in @code, followed by a space, but does nothing if #1 is null. +\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi} + +% #1 is the classification. #2 is the data type. #3 is the name and args. +\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} +% #1 is the classification, #2 the data type, #3 the name, #4 the args. +\def\deftypefnheaderx #1#2#3 #4\relax{% +\doind {fn}{\code{#3}}% Make entry in function index +\begingroup +\normalparens % notably, turn off `&' magic, which prevents +% at least some C++ text from working +\defname {\defheaderxcond#2\relax$$$#3}{#1}% +\deftypefunargs {#4}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defmac == @deffn Macro + +\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} + +\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Macro}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defspec == @deffn Special Form + +\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} + +\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Special Form}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% This definition is run if you use @defunx +% anywhere other than immediately after a @defun or @defunx. + +\def\deffnx #1 {\errmessage{@deffnx in invalid context}} +\def\defunx #1 {\errmessage{@defunx in invalid context}} +\def\defmacx #1 {\errmessage{@defmacx in invalid context}} +\def\defspecx #1 {\errmessage{@defspecx in invalid context}} +\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} + +% @defmethod, and so on + +% @defop {Funny Method} foo-class frobnicate argument + +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} + +\def\defopheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index +\begingroup\defname {#2}{\defoptype{} on #1}% +\defunargs {#3}\endgroup % +} + +% @defmethod == @defop Method + +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} + +\def\defmethodheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% entry in function index +\begingroup\defname {#2}{Method on #1}% +\defunargs {#3}\endgroup % +} + +% @defcv {Class Option} foo-class foo-flag + +\def\defcv #1 {\def\defcvtype{#1}% +\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} + +\def\defcvarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{\defcvtype{} of #1}% +\defvarargs {#3}\endgroup % +} + +% @defivar == @defcv {Instance Variable} + +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} + +\def\defivarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{Instance Variable of #1}% +\defvarargs {#3}\endgroup % +} + +% These definitions are run if you use @defmethodx, etc., +% anywhere other than immediately after a @defmethod, etc. + +\def\defopx #1 {\errmessage{@defopx in invalid context}} +\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} +\def\defcvx #1 {\errmessage{@defcvx in invalid context}} +\def\defivarx #1 {\errmessage{@defivarx in invalid context}} + +% Now @defvar + +% First, define the processing that is wanted for arguments of @defvar. +% This is actually simple: just print them in roman. +% This must expand the args and terminate the paragraph they make up +\def\defvarargs #1{\normalparens #1% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000} + +% @defvr Counter foo-count + +\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} + +\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% +\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} + +% @defvar == @defvr Variable + +\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} + +\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{Variable}% +\defvarargs {#2}\endgroup % +} + +% @defopt == @defvr {User Option} + +\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} + +\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{User Option}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name. +\def\deftypevarheader #1#2{% +\doind {vr}{\code{#2}}% Make entry in variables index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% This definition is run if you use @defvarx +% anywhere other than immediately after a @defvar or @defvarx. + +\def\defvrx #1 {\errmessage{@defvrx in invalid context}} +\def\defvarx #1 {\errmessage{@defvarx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} + +% Now define @deftp +% Args are printed in bold, a slight difference from @defvar. + +\def\deftpargs #1{\bf \defvarargs{#1}} + +% @deftp Class window height width ... + +\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} + +\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% +\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} + +% This definition is run if you use @deftpx, etc +% anywhere other than immediately after a @deftp, etc. + +\def\deftpx #1 {\errmessage{@deftpx in invalid context}} + +\message{cross reference,} +% Define cross-reference macros +\newwrite \auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% \setref{foo} defines a cross-reference point named foo. + +\def\setref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ysectionnumberandtype}} + +\def\unnumbsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ynothing}} + +\def\appendixsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Yappendixletterandtype}} + +% \xref, \pxref, and \ref generate cross-references to specified points. +% For \xrefX, #1 is the node name, #2 the name of the Info +% cross-reference, #3 the printed node name, #4 the name of the Info +% file, #5 the name of the printed manual. All but the node name can be +% omitted. +% +\def\href#1{\hrefX[#1,,,]} +\def\hrefX[#1,#2,#3,#4]{#1} +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup + \def\printedmanual{\ignorespaces #5}% + \def\printednodename{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual}% + \setbox0=\hbox{\printednodename}% + \ifdim \wd0 = 0pt + % No printed node name was explicitly given. + \ifx\SETxref-automatic-section-title\thisisundefined + % Use the node name inside the square brackets. + \def\printednodename{\ignorespaces #1}% + \else + % Use the actual chapter/section title appear inside + % the square brackets. Use the real section title if we have it. + \ifdim \wd1>0pt% + % It is in another manual, so we don't have it. + \def\printednodename{\ignorespaces #1}% + \else + \ifhavexrefs + % We know the real title if we have the xref values. + \def\printednodename{\refx{#1-title}{}}% + \else + % Otherwise just copy the Info node name. + \def\printednodename{\ignorespaces #1}% + \fi% + \fi + \fi + \fi + % + % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not + % insert empty discretionaries after hyphens, which means that it will + % not find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, this + % is a loss. Therefore, we give the text of the node name again, so it + % is as if TeX is seeing it for the first time. + \ifdim \wd1 > 0pt + \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% + \else + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive \refx{#1-snt}{}}% + \space [\printednodename],\space + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi +\endgroup} + +% \dosetq is the interface for calls from other macros + +% Use \turnoffactive so that punctuation chars such as underscore +% work in node names. +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% +\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% +\next}} + +% \internalsetq {foo}{page} expands into +% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} +% When the aux file is read, ' is the escape character + +\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} + +% Things to be expanded by \internalsetq + +\def\Ypagenumber{\folio} + +\def\Ytitle{\thissection} + +\def\Ynothing{} + +\def\Ysectionnumberandtype{% +\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % +\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\def\Yappendixletterandtype{% +\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% +\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\gdef\xreftie{'tie} + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Non-3.0. +\else + \def\linenumber{\the\inputlineno:\space} +\fi + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. + +\def\refx#1#2{% + \expandafter\ifx\csname X#1\endcsname\relax + % If not defined, say something at least. + $\langle$un\-de\-fined$\rangle$% + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \else + % It's defined, so just use it. + \csname X#1\endcsname + \fi + #2% Output the suffix in any case. +} + +% Read the last existing aux file, if any. No error if none exists. + +% This is the macro invoked by entries in the aux file. +\def\xrdef #1#2{ +{\catcode`\'=\other\expandafter \gdef \csname X#1\endcsname {#2}}} + +\def\readauxfile{% +\begingroup +\catcode `\^^@=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\^^C=\other +\catcode `\^^D=\other +\catcode `\^^E=\other +\catcode `\^^F=\other +\catcode `\^^G=\other +\catcode `\^^H=\other +\catcode `\ =\other +\catcode `\^^L=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode 26=\other +\catcode `\^^[=\other +\catcode `\^^\=\other +\catcode `\^^]=\other +\catcode `\^^^=\other +\catcode `\^^_=\other +\catcode `\@=\other +\catcode `\^=\other +\catcode `\~=\other +\catcode `\[=\other +\catcode `\]=\other +\catcode`\"=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode `\$=\other +\catcode `\#=\other +\catcode `\&=\other +% `\+ does not work, so use 43. +\catcode 43=\other +% Make the characters 128-255 be printing characters +{% + \count 1=128 + \def\loop{% + \catcode\count 1=\other + \advance\count 1 by 1 + \ifnum \count 1<256 \loop \fi + }% +}% +% the aux file uses ' as the escape. +% Turn off \ as an escape so we do not lose on +% entries which were dumped with control sequences in their names. +% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ +% Reference to such entries still does not work the way one would wish, +% but at least they do not bomb out when the aux file is read in. +\catcode `\{=1 \catcode `\}=2 +\catcode `\%=\other +\catcode `\'=0 +\catcode`\^=7 % to make ^^e4 etc usable in xref tags +\catcode `\\=\other +\openin 1 \jobname.aux +\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue +\global\warnedobstrue +\fi +% Open the new aux file. Tex will close it automatically at exit. +\openout \auxfile=\jobname.aux +\endgroup} + + +% Footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for info output only.. +\let\footnotestyle=\comment + +\let\ptexfootnote=\footnote + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \footnotezzz +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +\long\gdef\footnotezzz#1{\insert\footins{% + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + % Hang the footnote text off the number. + \hang + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + #1\strut}% +} + +}%end \catcode `\@=11 + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +\def\setleading#1{% + \normalbaselineskip = #1\relax + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + + +% End of control word definitions. + +\message{and turning on texinfo input format.} + +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% Set some numeric style parameters, for 8.5 x 11 format. + +%\hsize = 6.5in +\newdimen\defaultparindent \defaultparindent = 15pt +\parindent = \defaultparindent +\parskip 18pt plus 1pt +\setleading{15pt} +\advance\topskip by 1.2cm + +% Prevent underfull vbox error messages. +\vbadness=10000 + +% Following George Bush, just get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. This makes it come to about 9pt for the 8.5x11 format. +% +\ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% +\else + \emergencystretch = \hsize + \divide\emergencystretch by 45 +\fi + +% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) +\def\smallbook{ + +% These values for secheadingskip and subsecheadingskip are +% experiments. RJC 7 Aug 1992 +\global\secheadingskip = 17pt plus 6pt minus 3pt +\global\subsecheadingskip = 14pt plus 6pt minus 3pt + +\global\lispnarrowing = 0.3in +\setleading{12pt} +\advance\topskip by -1cm +\global\parskip 3pt plus 1pt +\global\hsize = 5in +\global\vsize=7.5in +\global\tolerance=700 +\global\hfuzz=1pt +\global\contentsrightmargin=0pt +\global\deftypemargin=0pt +\global\defbodyindent=.5cm + +\global\pagewidth=\hsize +\global\pageheight=\vsize + +\global\let\smalllisp=\smalllispx +\global\let\smallexample=\smalllispx +\global\def\Esmallexample{\Esmalllisp} +} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{ +\global\tolerance=700 +\global\hfuzz=1pt +\setleading{12pt} +\global\parskip 15pt plus 1pt + +\global\vsize= 53\baselineskip +\advance\vsize by \topskip +%\global\hsize= 5.85in % A4 wide 10pt +\global\hsize= 6.5in +\global\outerhsize=\hsize +\global\advance\outerhsize by 0.5in +\global\outervsize=\vsize +\global\advance\outervsize by 0.6in + +\global\pagewidth=\hsize +\global\pageheight=\vsize +} + +% Allow control of the text dimensions. Parameters in order: textheight; +% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% header is additional; added length extends the bottom of the page. + +\def\changepagesizes#1#2#3#4#5{ + \global\vsize= #1 + \advance\vsize by \topskip + \global\voffset= #3 + \global\hsize= #2 + \global\outerhsize=\hsize + \global\advance\outerhsize by 0.5in + \global\outervsize=\vsize + \global\advance\outervsize by 0.6in + \global\pagewidth=\hsize + \global\pageheight=\vsize + \global\normaloffset= #4 + \global\bindingoffset= #5} + +% This layout is compatible with Latex on A4 paper. + +\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} + +% Use @afourwide to print on European A4 paper in wide format. +\def\afourwide{\afourpaper +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other +\catcode`\~=\other +\catcode`\^=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode`\+=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} + +% This macro is used to make a character print one way in ttfont +% where it can probably just be output, and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. Since all the Computer Modern typewriter fonts have zero +% interword stretch (and shrink), and it is reasonable to expect all +% typewriter fonts to have this, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\the\font=0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt \char '042}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt \char '176}} +\chardef\hat=`\^ +\catcode`\^=\active +\def\auxhat{\def^{'hat}} +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +% Subroutine for the previous macro. +\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} + +\catcode`\|=\active +\def|{{\tt \char '174}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +%\catcode 27=\active +%\def^^[{$\diamondsuit$} + +% Set up an active definition for =, but don't enable it most of the time. +{\catcode`\==\active +\global\def={{\tt \char 61}}} + +\catcode`+=\active +\catcode`\_=\active + +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have \everyjob (or @setfilename) turn them on. +% \otherifyactive is called near the end of this file. +\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +\catcode`\@=0 + +% \rawbackslashxx output one backslash character in current font +\global\chardef\rawbackslashxx=`\\ +%{\catcode`\\=\other +%@gdef@rawbackslashxx{\}} + +% \rawbackslash redefines \ as input to do \rawbackslashxx. +{\catcode`\\=\active +@gdef@rawbackslash{@let\=@rawbackslashxx }} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +% Say @foo, not \foo, in error messages. +\escapechar=`\@ + +% \catcode 17=0 % Define control-q +\catcode`\\=\active + +% Used sometimes to turn off (effectively) the active characters +% even after parsing them. +@def@turnoffactive{@let"=@normaldoublequote +@let\=@realbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +@def@normalturnoffactive{@let"=@normaldoublequote +@let\=@normalbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +% Make _ and + \other characters, temporarily. +% This is canceled by @fixbackslash. +@otherifyactive + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\{ in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% Also back turn on active characters that might appear in the input +% file name, in case not using a pre-dumped format. +% +@gdef@fixbackslash{@ifx\@eatinput @let\ = @normalbackslash @fi + @catcode`+=@active @catcode`@_=@active} + +%% These look ok in all fonts, so just make them not special. The @rm below +%% makes sure that the current font starts out as the newly loaded cmr10 +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other + +@textfonts +@rm + +@c Local variables: +@c page-delimiter: "^\\\\message" +@c End: diff --git a/doc/tools/bmenu/Makefile b/doc/tools/bmenu/Makefile new file mode 100644 index 0000000000..597593dc57 --- /dev/null +++ b/doc/tools/bmenu/Makefile @@ -0,0 +1,43 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +CC=gcc +#CFLAGS=-O4 -fomit-frame-pointer +CFLAGS=-g + +#TEXINPUTS=/home/gnu/work/binutils-2.6/texinfo:. +PROG=bmenu + +all: $(PROG) + +$(BASE).txt: $(BASE).d ./$(PROG) + ./$(PROG) $(BASE).d + +$(PROG): main.o chain.o + gcc main.o chain.o -o $(PROG) + +main.o: main.c base.h + +chain.o: chain.c + +info: c_user.texinfo timer.texi + makeinfo c_user.texinfo + +TESTER=init +test: all + #rm -f timer.txt + #./bmenu -v timer.texi + cp ../user/$(TESTER).texi . + ./bmenu $(TESTER).texi + mv $(TESTER).txt $(TESTER).texi + makeinfo c_user.texinfo + + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f c_user c_user-* _* + diff --git a/doc/tools/bmenu/address.h b/doc/tools/bmenu/address.h new file mode 100644 index 0000000000..f4ebf905b3 --- /dev/null +++ b/doc/tools/bmenu/address.h @@ -0,0 +1,112 @@ +/* address.h + * + * This include file contains the information required to manipulate + * physical addresses. + * + * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. + * On-Line Applications Research Corporation (OAR). + * All rights assigned to U.S. Government, 1994. + * + * This material may be reproduced by or for the U.S. Government pursuant + * to the copyright license under the clause at DFARS 252.227-7013. This + * notice must appear in all copies of this file and its derivatives. + */ + +#ifndef __ADDRESSES_h +#define __ADDRESSES_h + +/* + * _Addresses_Add_offset + * + * DESCRIPTION: + * + * This function is used to add an offset to a base address. + * It returns the resulting address. This address is typically + * converted to an access type before being used further. + */ + +STATIC INLINE void *_Addresses_Add_offset ( + void *base, + unsigned32 offset +); + +/* + * _Addresses_Subtract_offset + * + * DESCRIPTION: + * + * This function is used to subtract an offset from a base + * address. It returns the resulting address. This address is + * typically converted to an access type before being used further. + */ + +STATIC INLINE void *_Addresses_Subtract_offset( + void *base, + unsigned32 offset +); + +/* + * _Addresses_Add + * + * DESCRIPTION: + * + * This function is used to add two addresses. It returns the + * resulting address. This address is typically converted to an + * access type before being used further. + */ + +STATIC INLINE void *_Addresses_Add ( + void *left, + void *right +); + +/* + * _Addresses_Subtract + * + * DESCRIPTION: + * + * This function is used to subtract two addresses. It returns the + * resulting offset. + */ + +STATIC INLINE unsigned32 _Addresses_Subtract ( + void *left, + void *right +); + +/* + * _Addresses_Is_aligned + * + * DESCRIPTION: + * + * This function returns TRUE if the given address is correctly + * aligned for this processor and FALSE otherwise. Proper alignment + * is based on correctness and efficiency. + */ + +STATIC INLINE boolean _Addresses_Is_aligned ( + void *address +); + +/* + * _Addresses_Is_in_range + * + * DESCRIPTION: + * + * This function returns TRUE if the given address is within the + * memory range specified and FALSE otherwise. base is the address + * of the first byte in the memory range and limit is the address + * of the last byte in the memory range. The base address is + * assumed to be lower than the limit address. + */ + +STATIC INLINE boolean _Addresses_Is_in_range ( + void *address, + void *base, + void *limit +); + +#include "address.inl" + +#endif +/* end of include file */ diff --git a/doc/tools/bmenu/address.inl b/doc/tools/bmenu/address.inl new file mode 100644 index 0000000000..8b7489c257 --- /dev/null +++ b/doc/tools/bmenu/address.inl @@ -0,0 +1,107 @@ +/* inline/address.inl + * + * This include file contains the bodies of the routines + * about addresses which are inlined. + * + * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. + * On-Line Applications Research Corporation (OAR). + * All rights assigned to U.S. Government, 1994. + * + * This material may be reproduced by or for the U.S. Government pursuant + * to the copyright license under the clause at DFARS 252.227-7013. This + * notice must appear in all copies of this file and its derivatives. + */ + +#ifndef __INLINE_ADDRESSES_inl +#define __INLINE_ADDRESSES_inl + +/*PAGE + * + * _Addresses_Add_offset + * + */ + +STATIC INLINE void *_Addresses_Add_offset ( + void *base, + unsigned32 offset +) +{ + return (base + offset); +} + +/*PAGE + * + * _Addresses_Subtract_offset + * + */ + +STATIC INLINE void *_Addresses_Subtract_offset ( + void *base, + unsigned32 offset +) +{ + return (base - offset); +} + +/*PAGE + * + * _Addresses_Add + * + * NOTE: The cast of an address to an unsigned32 makes this code + * dependent on an addresses being thirty two bits. + */ + +STATIC INLINE void *_Addresses_Add ( + void *left, + void *right +) +{ + return (left + (unsigned32)right); +} + +/*PAGE + * + * _Addresses_Subtract + * + * NOTE: The cast of an address to an unsigned32 makes this code + * dependent on an addresses being thirty two bits. + */ + +STATIC INLINE unsigned32 _Addresses_Subtract ( + void *left, + void *right +) +{ + return (left - right); +} + +/*PAGE + * + * _Addresses_Is_aligned + * + */ + +STATIC INLINE boolean _Addresses_Is_aligned ( + void *address +) +{ + return ( ( (unsigned32)address % 4 ) == 0 ); +} + +/*PAGE + * + * _Addresses_Is_aligned + * + */ + +STATIC INLINE boolean _Addresses_Is_in_range ( + void *address, + void *base, + void *limit +) +{ + return ( address >= base && address <= limit ); +} + +#endif +/* end of include file */ diff --git a/doc/tools/bmenu/base.h b/doc/tools/bmenu/base.h new file mode 100644 index 0000000000..2e60938aa9 --- /dev/null +++ b/doc/tools/bmenu/base.h @@ -0,0 +1,106 @@ + +#ifndef __PDL2AMI_h +#define __PDL2AMI_h + +#include "system.h" +#include "chain.h" + +#ifndef EXTERN +#define EXTERN extern +#endif + +/* + * Paragraph size should be kept down because it is allocated for each + * Line_Control. If this number is large, the memory requirements for + * the program increase significantly. + */ + +#define BUFFER_SIZE (2 * 1024) +#define PARAGRAPH_SIZE (2 * 1024) + +#define NUMBER_ELEMENTS( _x ) (sizeof(_x) / sizeof _x[0]) + +void exit_application( + int status +); + +void ProcessFile( + char *inname, + char *outname +); + +void strtolower( + char *dest, + char *src +); + +void strtoInitialCaps( + char *dest, + char *src +); + +void StripBlanks( void ); + +void MergeParagraphs( void ); + +int CheckForIncomplete( void ); + +int CheckOutline( void ); + +int CheckSections( void ); + +void GenerateLists( void ); + +void GenerateAList( + char *section, + Chain_Control *the_list +); + +void LookForInternalInconsistencies( void ); + +int Match_Argument( + char **array, + int entries, + char *users +); + +void usage( void ); + +void ReadFileIntoChain( + char *inname +); + +int MergeText( void ); + +int CheckForBadWhiteSpace(); + +void RemoveCopyright(); + +void RemovePagebreaks(); + +int RemoveExtraBlankLines(); + +void FormatToTexinfo( void ); + +void PrintFile( + char *out +); + +void DumpList( + Chain_Control *the_list +); + +void ReleaseFile(); + +EXTERN boolean Verbose; /* status/debug msgs */ +EXTERN boolean BlankAsWarnings; +EXTERN Chain_Control Lines; + +EXTERN int NumberOfAttributes; +EXTERN int NumberOfAssociations; +EXTERN int NumberOfAbstractTypes; +EXTERN int NumberOfDataItems; +EXTERN int NumberOfMethods; +EXTERN int NumberOfTasks; + +#endif diff --git a/doc/tools/bmenu/bmenu b/doc/tools/bmenu/bmenu new file mode 100644 index 0000000000..91796a8862 Binary files /dev/null and b/doc/tools/bmenu/bmenu differ diff --git a/doc/tools/bmenu/chain.c b/doc/tools/bmenu/chain.c new file mode 100644 index 0000000000..5ea2e0c51a --- /dev/null +++ b/doc/tools/bmenu/chain.c @@ -0,0 +1,232 @@ +/* + * Chain Handler + * + * + * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. + * On-Line Applications Research Corporation (OAR). + * All rights assigned to U.S. Government, 1994. + * + * This material may be reproduced by or for the U.S. Government pursuant + * to the copyright license under the clause at DFARS 252.227-7013. This + * notice must appear in all copies of this file and its derivatives. + */ + +#include "system.h" +#include "address.h" +#include "chain.h" +#include "isr.h" + +/*PAGE + * + * _Chain_Initialize + * + * This kernel routine initializes a doubly linked chain. + * + * Input parameters: + * the_chain - pointer to chain header + * starting_address - starting address of first node + * number_nodes - number of nodes in chain + * node_size - size of node in bytes + * + * Output parameters: NONE + */ + +void _Chain_Initialize( + Chain_Control *the_chain, + void *starting_address, + unsigned32 number_nodes, + unsigned32 node_size +) +{ + unsigned32 count; + Chain_Node *current; + Chain_Node *next; + + count = number_nodes; + current = _Chain_Head( the_chain ); + the_chain->permanent_null = NULL; + next = (Chain_Node *)starting_address; + while ( count-- ) { + current->next = next; + next->previous = current; + current = next; + next = (Chain_Node *) + _Addresses_Add_offset( (void *) next, node_size ); + } + current->next = _Chain_Tail( the_chain ); + the_chain->last = current; +} + +/*PAGE + * + * _Chain_Get_first_unprotected + */ + +#ifndef USE_INLINES +STATIC INLINE Chain_Node *_Chain_Get_first_unprotected( + Chain_Control *the_chain +) +{ + Chain_Node *return_node; + Chain_Node *new_first; + + return_node = the_chain->first; + new_first = return_node->next; + the_chain->first = new_first; + new_first->previous = _Chain_Head( the_chain ); + + return return_node; +} +#endif /* USE_INLINES */ + +/*PAGE + * + * _Chain_Get + * + * This kernel routine returns a pointer to a node taken from the + * given chain. + * + * Input parameters: + * the_chain - pointer to chain header + * + * Output parameters: + * return_node - pointer to node in chain allocated + * CHAIN_END - if no nodes available + * + * INTERRUPT LATENCY: + * only case + */ + +Chain_Node *_Chain_Get( + Chain_Control *the_chain +) +{ + ISR_Level level; + Chain_Node *return_node; + + return_node = NULL; + _ISR_Disable( level ); + if ( !_Chain_Is_empty( the_chain ) ) + return_node = _Chain_Get_first_unprotected( the_chain ); + _ISR_Enable( level ); + return return_node; +} + +/*PAGE + * + * _Chain_Append + * + * This kernel routine puts a node on the end of the specified chain. + * + * Input parameters: + * the_chain - pointer to chain header + * node - address of node to put at rear of chain + * + * Output parameters: NONE + * + * INTERRUPT LATENCY: + * only case + */ + +void _Chain_Append( + Chain_Control *the_chain, + Chain_Node *node +) +{ + ISR_Level level; + + _ISR_Disable( level ); + _Chain_Append_unprotected( the_chain, node ); + _ISR_Enable( level ); +} + +/*PAGE + * + * _Chain_Extract + * + * This kernel routine deletes the given node from a chain. + * + * Input parameters: + * node - pointer to node in chain to be deleted + * + * Output parameters: NONE + * + * INTERRUPT LATENCY: + * only case + */ + +void _Chain_Extract( + Chain_Node *node +) +{ + ISR_Level level; + + _ISR_Disable( level ); + _Chain_Extract_unprotected( node ); + _ISR_Enable( level ); +} + +/*PAGE + * + * _Chain_Insert + * + * This kernel routine inserts a given node after a specified node + * a requested chain. + * + * Input parameters: + * after_node - pointer to node in chain to be inserted after + * node - pointer to node to be inserted + * + * Output parameters: NONE + * + * INTERRUPT LATENCY: + * only case + */ + +void _Chain_Insert( + Chain_Node *after_node, + Chain_Node *node +) +{ + ISR_Level level; + + _ISR_Disable( level ); + _Chain_Insert_unprotected( after_node, node ); + _ISR_Enable( level ); +} + +/*PAGE + * + * _Chain_Insert_chain + * + * This routine inserts a chain after the specified node in another + * chain. It is assumed that the insert after node is not on the + * second chain. + * + * Input parameters: + * insert_after - insert the chain after this node + * to_insert - the chain to insert + */ + +void _Chain_Insert_chain( + Chain_Node *insert_after, + Chain_Control *to_insert +) +{ + Chain_Node *first; + Chain_Node *last; + Chain_Node *insert_after_next; + + first = to_insert->first; + last = to_insert->last; + + insert_after_next = insert_after->next; + + insert_after->next = first; + first->previous = insert_after; + + insert_after_next->previous = last; + last->next = insert_after_next; + + _Chain_Initialize_empty( to_insert ); +} diff --git a/doc/tools/bmenu/chain.h b/doc/tools/bmenu/chain.h new file mode 100644 index 0000000000..ba5d54e998 --- /dev/null +++ b/doc/tools/bmenu/chain.h @@ -0,0 +1,349 @@ +/* chain.h + * + * This include file contains all the constants and structures associated + * with the Doubly Linked Chain Handler. + * + * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. + * On-Line Applications Research Corporation (OAR). + * All rights assigned to U.S. Government, 1994. + * + * This material may be reproduced by or for the U.S. Government pursuant + * to the copyright license under the clause at DFARS 252.227-7013. This + * notice must appear in all copies of this file and its derivatives. + */ + +#ifndef __CHAIN_h +#define __CHAIN_h + +#include "address.h" + +/* + * This is used to manage each element (node) which is placed + * on a chain. + * + * NOTE: Typically, a more complicated structure will use the + * chain package. The more complicated structure will + * include a chain node as the first element in its + * control structure. It will then call the chain package + * with a pointer to that node element. The node pointer + * and the higher level structure start at the same address + * so the user can cast the pointers back and forth. + */ + +typedef struct Chain_Node_struct Chain_Node; + +struct Chain_Node_struct { + Chain_Node *next; + Chain_Node *previous; +}; + +/* + * This is used to manage a chain. A chain consists of a doubly + * linked list of zero or more nodes. + * + * NOTE: This implementation does not require special checks for + * manipulating the first and last elements on the chain. + * To accomplish this the chain control structure is + * treated as two overlapping chain nodes. The permanent + * head of the chain overlays a node structure on the + * first and permanent_null fields. The permanent tail + * of the chain overlays a node structure on the + * permanent_null and last elements of the structure. + */ + +typedef struct { + Chain_Node *first; + Chain_Node *permanent_null; + Chain_Node *last; +} Chain_Control; + +/* + * _Chain_Initialize + * + * This routine initializes the_chain structure to manage the + * contiguous array of number_nodes nodes which starts at + * starting_address. Each node is of node_size bytes. + */ + +void _Chain_Initialize( + Chain_Control *the_chain, + void *starting_address, + unsigned32 number_nodes, + unsigned32 node_size +); + +/* + * _Chain_Initialize_empty + * + * This routine initializes the specified chain to contain zero nodes. + */ + +STATIC INLINE void _Chain_Initialize_empty( + Chain_Control *the_chain +); + +/* + * _Chain_Extract_unprotected + * + * This routine extracts the_node from the chain on which it resides. + * It does NOT disable interrupts to insure the atomicity of the + * extract operation. + */ + +STATIC INLINE void _Chain_Extract_unprotected( + Chain_Node *the_node +); + +/* + * _Chain_Extract + * + * This routine extracts the_node from the chain on which it resides. + * It disables interrupts to insure the atomicity of the + * extract operation. + */ + +void _Chain_Extract( + Chain_Node *the_node +); + +/* + * _Chain_Get_unprotected + * + * This function removes the first node from the_chain and returns + * a pointer to that node. If the_chain is empty, then NULL is returned. + * It does NOT disable interrupts to insure the atomicity of the + * get operation. + */ + +STATIC INLINE Chain_Node *_Chain_Get_unprotected( + Chain_Control *the_chain +); + +/* + * _Chain_Get + * + * This function removes the first node from the_chain and returns + * a pointer to that node. If the_chain is empty, then NULL is returned. + * It disables interrupts to insure the atomicity of the + * get operation. + */ + +Chain_Node *_Chain_Get( + Chain_Control *the_chain +); + +/* + * _Chain_Get_first_unprotected + * + * This function removes the first node from the_chain and returns + * a pointer to that node. It does NOT disable interrupts to insure + * the atomicity of the get operation. + */ + +STATIC INLINE Chain_Node *_Chain_Get_first_unprotected( + Chain_Control *the_chain +); + +/* + * _Chain_Insert_unprotected + * + * This routine inserts the_node on a chain immediately following + * after_node. It does NOT disable interrupts to insure the atomicity + * of the extract operation. + */ + +STATIC INLINE void _Chain_Insert_unprotected( + Chain_Node *after_node, + Chain_Node *the_node +); + +/* + * _Chain_Insert + * + * This routine inserts the_node on a chain immediately following + * after_node. It disables interrupts to insure the atomicity + * of the extract operation. + */ + +void _Chain_Insert( + Chain_Node *after_node, + Chain_Node *the_node +); + +/* + * _Chain_Append_unprotected + * + * This routine appends the_node onto the end of the_chain. + * It does NOT disable interrupts to insure the atomicity of the + * append operation. + */ + +STATIC INLINE void _Chain_Append_unprotected( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Append + * + * This routine appends the_node onto the end of the_chain. + * It disables interrupts to insure the atomicity of the + * append operation. + */ + +void _Chain_Append( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Prepend_unprotected + * + * This routine prepends the_node onto the front of the_chain. + * It does NOT disable interrupts to insure the atomicity of the + * prepend operation. + */ + +STATIC INLINE void _Chain_Prepend_unprotected( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Prepend + * + * This routine prepends the_node onto the front of the_chain. + * It disables interrupts to insure the atomicity of the + * prepend operation. + */ + +STATIC INLINE void _Chain_Prepend( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Insert_chain + * + * This routine inserts a chain after the specified node in another + * chain. It is assumed that the insert after node is not on the + * second chain. + */ + +void _Chain_Insert_chain( + Chain_Node *insert_after, + Chain_Control *to_insert +); + +/* + * _Chain_Head + * + * This function returns a pointer to the first node on the chain. + */ + +STATIC INLINE Chain_Node *_Chain_Head( + Chain_Control *the_chain +); + +/* + * _Chain_Tail + * + * This function returns a pointer to the last node on the chain. + */ + +STATIC INLINE Chain_Node *_Chain_Tail( + Chain_Control *the_chain +); + +/* + * _Chain_Is_head + * + * This function returns TRUE if the_node is the head of the_chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_head( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Is_tail + * + * This function returns TRUE if the_node is the tail of the_chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_tail( + Chain_Control *the_chain, + Chain_Node *the_node +); + +/* + * _Chain_Is_first + * + * This function returns TRUE if the_node is the first node on a chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_first( + Chain_Node *the_node +); + +/* + * _Chain_Is_last + * + * This function returns TRUE if the_node is the last node on a chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_last( + Chain_Node *the_node +); + +/* + * _Chain_Is_empty + * + * This function returns TRUE if there a no nodes on the_chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_empty( + Chain_Control *the_chain +); + +/* + * _Chain_Has_only_one_node + * + * This function returns TRUE if there is only one node on the_chain and + * FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Has_only_one_node( + Chain_Control *the_chain +); + +/* + * _Chain_Is_null + * + * This function returns TRUE if the_chain is NULL and FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_null( + Chain_Control *the_chain +); + +/* + * _Chain_Is_null_node + * + * This function returns TRUE if the_node is NULL and FALSE otherwise. + */ + +STATIC INLINE boolean _Chain_Is_null_node( + Chain_Node *the_node +); + +#include "chain.inl" + +#endif +/* end of include file */ diff --git a/doc/tools/bmenu/chain.inl b/doc/tools/bmenu/chain.inl new file mode 100644 index 0000000000..a1f7149732 --- /dev/null +++ b/doc/tools/bmenu/chain.inl @@ -0,0 +1,273 @@ +/* inline/chain.inl + * + * This include file contains the bodies of the routines which are + * associated with doubly linked chains and inlined. + * + * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. + * On-Line Applications Research Corporation (OAR). + * All rights assigned to U.S. Government, 1994. + * + * This material may be reproduced by or for the U.S. Government pursuant + * to the copyright license under the clause at DFARS 252.227-7013. This + * notice must appear in all copies of this file and its derivatives. + */ + +#ifndef __INLINE_CHAIN_inl +#define __INLINE_CHAIN_inl + +/*PAGE + * + * _Chain_Is_null + */ + +STATIC INLINE boolean _Chain_Is_null( + Chain_Control *the_chain +) +{ + return ( the_chain == NULL ); +} + +/*PAGE + * + * _Chain_Is_null_node + */ + +STATIC INLINE boolean _Chain_Is_null_node( + Chain_Node *the_node +) +{ + return ( the_node == NULL ); +} + +/*PAGE + * + * _Chain_Head + */ + +STATIC INLINE Chain_Node *_Chain_Head( + Chain_Control *the_chain +) +{ + return (Chain_Node *) the_chain; +} + +/*PAGE + * + * _Chain_Tail + */ + +STATIC INLINE Chain_Node *_Chain_Tail( + Chain_Control *the_chain +) +{ + return (Chain_Node *) &the_chain->permanent_null; +} + +/*PAGE + * + * _Chain_Is_empty + */ + +STATIC INLINE boolean _Chain_Is_empty( + Chain_Control *the_chain +) +{ + return ( the_chain->first == _Chain_Tail( the_chain ) ); +} + +/*PAGE + * + * _Chain_Is_first + */ + +STATIC INLINE boolean _Chain_Is_first( + Chain_Node *the_node +) +{ + return ( the_node->previous == NULL ); +} + +/*PAGE + * + * _Chain_Is_last + */ + +STATIC INLINE boolean _Chain_Is_last( + Chain_Node *the_node +) +{ + return ( the_node->next == NULL ); +} + +/*PAGE + * + * _Chain_Has_only_one_node + */ + +STATIC INLINE boolean _Chain_Has_only_one_node( + Chain_Control *the_chain +) +{ + return ( the_chain->first == the_chain->last ); +} + +/*PAGE + * + * _Chain_Is_head + */ + +STATIC INLINE boolean _Chain_Is_head( + Chain_Control *the_chain, + Chain_Node *the_node +) +{ + return ( the_node == _Chain_Head( the_chain ) ); +} + +/*PAGE + * + * _Chain_Is_tail + */ + +STATIC INLINE boolean _Chain_Is_tail( + Chain_Control *the_chain, + Chain_Node *the_node +) +{ + return ( the_node == _Chain_Tail( the_chain ) ); +} + +/*PAGE + * + * Chain_Initialize_empty + */ + +STATIC INLINE void _Chain_Initialize_empty( + Chain_Control *the_chain +) +{ + the_chain->first = _Chain_Tail( the_chain ); + the_chain->permanent_null = NULL; + the_chain->last = _Chain_Head( the_chain ); +} + +/*PAGE + * + * _Chain_Extract_unprotected + */ + +STATIC INLINE void _Chain_Extract_unprotected( + Chain_Node *the_node +) +{ + Chain_Node *next; + Chain_Node *previous; + + next = the_node->next; + previous = the_node->previous; + next->previous = previous; + previous->next = next; +} + +/*PAGE + * + * _Chain_Get_first_unprotected + */ + +STATIC INLINE Chain_Node *_Chain_Get_first_unprotected( + Chain_Control *the_chain +) +{ + Chain_Node *return_node; + Chain_Node *new_first; + + return_node = the_chain->first; + new_first = return_node->next; + the_chain->first = new_first; + new_first->previous = _Chain_Head( the_chain ); + + return return_node; +} + +/*PAGE + * + * Chain_Get_unprotected + */ + +STATIC INLINE Chain_Node *_Chain_Get_unprotected( + Chain_Control *the_chain +) +{ + if ( !_Chain_Is_empty( the_chain ) ) + return _Chain_Get_first_unprotected( the_chain ); + else + return NULL; +} + +/*PAGE + * + * _Chain_Insert_unprotected + */ + +STATIC INLINE void _Chain_Insert_unprotected( + Chain_Node *after_node, + Chain_Node *the_node +) +{ + Chain_Node *before_node; + + the_node->previous = after_node; + before_node = after_node->next; + after_node->next = the_node; + the_node->next = before_node; + before_node->previous = the_node; +} + +/*PAGE + * + * _Chain_Append_unprotected + */ + +STATIC INLINE void _Chain_Append_unprotected( + Chain_Control *the_chain, + Chain_Node *the_node +) +{ + Chain_Node *old_last_node; + + the_node->next = _Chain_Tail( the_chain ); + old_last_node = the_chain->last; + the_chain->last = the_node; + old_last_node->next = the_node; + the_node->previous = old_last_node; +} + +/*PAGE + * + * _Chain_Prepend_unprotected + */ + +STATIC INLINE void _Chain_Prepend_unprotected( + Chain_Control *the_chain, + Chain_Node *the_node +) +{ + _Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node ); + +} + +/*PAGE + * + * _Chain_Prepend + */ + +STATIC INLINE void _Chain_Prepend( + Chain_Control *the_chain, + Chain_Node *the_node +) +{ + _Chain_Insert( _Chain_Head( the_chain ), the_node ); +} + +#endif +/* end of include file */ diff --git a/doc/tools/bmenu/chain.o b/doc/tools/bmenu/chain.o new file mode 100644 index 0000000000..f26dd12af6 Binary files /dev/null and b/doc/tools/bmenu/chain.o differ diff --git a/doc/tools/bmenu/isr.h b/doc/tools/bmenu/isr.h new file mode 100644 index 0000000000..9c8344ca57 --- /dev/null +++ b/doc/tools/bmenu/isr.h @@ -0,0 +1,11 @@ + + +#ifndef __ISR_h +#define __ISR_h + +typedef unsigned32 ISR_Level; + +#define _ISR_Disable +#define _ISR_Enable + +#endif diff --git a/doc/tools/bmenu/main.c b/doc/tools/bmenu/main.c new file mode 100644 index 0000000000..1a9a309831 --- /dev/null +++ b/doc/tools/bmenu/main.c @@ -0,0 +1,985 @@ +/* + * main.c + * + * This program takes a texinfo file without node and menu commands, + * build those commands and inserts them. + * + * It works by reading the input file into a linked list of lines + * and then performing sweeps on that list until all formatting is + * complete. After the program is run, there is still a little + * clean up to be performed by hand. The following have to be fixed + * by hand: + * + previous of the first node + * + next of the last node + */ + +#include +#include +#include +#include +#include +#include + +/* XXX -- just for testing -- these should be set by options */ +char DocsNextNode[] = ""; +char DocsPreviousNode[] = "Top"; +char DocsUpNode[] = "Top"; + +extern int optind; /* Why is this not in ? */ +extern char *optarg; /* Why is this not in ? */ + +#ifndef NAME_MAX +#define NAME_MAX 14 /* Why is the one in limits.h not showing up? */ +#endif +#define INIT_DATA +#define EXTERN + +#include "base.h" + +FILE *OutFile = stdout; + +/************************************************************************* + ************************************************************************* + ***** DATA TYPES AND CONSTANT TABLES ***** + ************************************************************************* + *************************************************************************/ +/* + * Usage Information + */ + +char *Usage_Strings[] = { + "\n", + "usage: cmd [-bv] files ...\n", + "\n", + "EOF" +}; + +/* + * The page separator is not really a keyword and will be purged before + * it is seen elsewhere. + */ + +#define PAGE_SEPARATOR "#PAGE" + +/* + * Section Delimiter Keywords + */ + +#define MAXIMUM_KEYWORD_LENGTH 32 + +/* + * Level indicates where in the format the delimiter is allowed to occur. + * 1 indicates a major section divider (e.g. "ATTRIBUTE DESCRIPTIONS:"). + * 2 indicates a subsection (e.g. "ATTRIBUTE:"). + * 3 indicates a heading (e.g. "DESCRIPTION:"). + */ + +#define TEXT 0 +#define SECTION 1 +#define SUBSECTION 2 +#define HEADING 3 + +typedef enum { + UNUSED, /* dummy 0 slot */ + KEYWORD_CHAPTER, + KEYWORD_CHAPHEADING, + KEYWORD_SECTION, + KEYWORD_SUBSECTION, + KEYWORD_OTHER, + KEYWORD_END + +} Keyword_indices_t; + +#define KEYWORD_FIRST KEYOWRD_CHAPTER +#define KEYWORD_LAST KEYWORD_END + +/* + * Line Management Structure + */ + +typedef enum { + NO_EXTRA_FORMATTING_INFO, + RAW_OUTPUT, + PARAGRAPH_OUTPUT +} ExtraFormat_info_t; + +typedef struct { + Chain_Node Node; + Keyword_indices_t keyword; /* unused is unknown/undecided */ + ExtraFormat_info_t format; + int number; + char Contents[ PARAGRAPH_SIZE ]; +} Line_Control; + +typedef enum { + RT_FORBIDDEN, /* no text to right allowed */ + RT_OPTIONAL, /* text to right optional -- none below */ + RT_NONE, /* text to right is "none" or nothing -- none below */ + RT_REQUIRED, /* text to right required -- none below */ + RT_BELOW, /* text to right forbidden -- text below required */ + RT_NONE_OR_BELOW, /* text to right is "none" OR there is text below */ + RT_EITHER, /* text to right OR below */ + RT_BOTH /* text to right AND below */ +} Keywords_text_mode_t; + +typedef enum { + BL_FORBIDDEN, /* text below forbidden */ + BL_FORMATTED, /* text below is to be formatted as paragraphs */ + BL_RAW, /* text below is to be unprocessed by this program */ +} Keywords_text_below_t; + +typedef (*Keyword_validater_t)( Line_Control * ); + +typedef struct { + char Name[ MAXIMUM_KEYWORD_LENGTH ]; + int level; + Keywords_text_mode_t text_mode; + Keywords_text_below_t text_below_mode; + Keyword_validater_t keyword_validation_routine; +} Keyword_info_t; + +Keyword_info_t Keywords[] = { + { "unused", + 0, 0, 0, NULL }, /* so 0 can be invalid */ + { "@chapter", SECTION, RT_FORBIDDEN, BL_FORBIDDEN, NULL }, + { "@chapheading",SECTION, RT_FORBIDDEN, BL_FORBIDDEN, NULL }, + { "@section", SECTION, RT_FORBIDDEN, BL_FORBIDDEN, NULL }, + { "@subsection", SUBSECTION, RT_FORBIDDEN, BL_FORBIDDEN, NULL }, + { "", HEADING, RT_FORBIDDEN, BL_FORBIDDEN, NULL }, + { "END OF FILE", SECTION, RT_FORBIDDEN, BL_FORBIDDEN, NULL } +}; + +#define NUMBER_OF_KEYWORDS \ + ( sizeof( Keywords ) / sizeof( Keyword_info_t ) ) - 2 + +/* + * exit_application + */ + +void exit_application( + int status +) +{ + fprintf( stderr, "*** Error encountered ***\n" ); +/* + fprintf( stderr, "*** Error encountered on line %d ***\n", CurrentLine ); +*/ + fclose( OutFile ); + exit( status ); +} + +/************************************************************************* + ************************************************************************* + ***** LINE MANIPULATION ROUTINES ***** + ************************************************************************* + *************************************************************************/ + +/* + * PrintLine + */ + +void PrintLine( + Line_Control *line +) +{ + assert( line ); + + if ( line->number == -1 ) + fprintf( stderr, " " ); + else + fprintf( stderr, "%5d", line->number ); + +#if 0 + fprintf( stderr, "%s\n", line->Contents ); +#else + /* + * Include some debugging information + */ + fprintf( + stderr, + "<%d,%d>:%s\n", + line->keyword, + line->format, + line->Contents + ); +#endif +} + +Chain_Control Line_Pool; + +/* + * FillLinePool + */ + +void FillLinePool( void ) +{ + void *pool; + +#define LINE_POOL_FILL_COUNT 100 + + pool = malloc( sizeof( Line_Control ) * LINE_POOL_FILL_COUNT ); + assert( pool ); + + _Chain_Initialize( + &Line_Pool, + pool, + LINE_POOL_FILL_COUNT, + sizeof( Line_Control ) + ); +} + +/* + * AllocateLine + */ + +Line_Control *AllocateLine( void ) +{ + Line_Control *new_line; + + new_line = (Line_Control *) _Chain_Get( &Line_Pool ); + if ( !new_line ) { + FillLinePool(); + new_line = (Line_Control *) _Chain_Get( &Line_Pool ); + assert( new_line ); + } + +/* + * This is commented out because although it is helpful during debug, + * it consumes a significant percentage of the program's execution time. + + memset( new_line->Contents, '\0', sizeof( new_line->Contents ) ); +*/ + new_line->number = -1; + + new_line->keyword = UNUSED; + new_line->format = NO_EXTRA_FORMATTING_INFO; + + new_line->Node.next = NULL; + new_line->Node.previous = NULL; + + return new_line; +} + +/* + * FreeLine + */ + +void FreeLine( + Line_Control *line +) +{ + fflush( stdout ); + _Chain_Append( &Line_Pool, &line->Node ); +} + +/* + * DeleteLine + */ + +Line_Control *DeleteLine( + Line_Control *line +) +{ + Line_Control *next; + + next = (Line_Control *)line->Node.next; + _Chain_Extract( &line->Node ); + FreeLine( line ); + return next; +} + +/* + * PrintSurroundingLines + */ + +void PrintSurroundingLines( + Line_Control *line, + int backward, + int forward +) +{ + int i; + int real_backward; + Line_Control *local; + + for ( local=line, real_backward=0, i=1 ; + i<=backward ; + i++, real_backward++ ) { + if ( &local->Node == Lines.first ) + break; + local = (Line_Control *) local->Node.previous; + } + + for ( i=1 ; i<=real_backward ; i++ ) { + PrintLine( local ); + local = (Line_Control *) local->Node.next; + } + + PrintLine( local ); + + for ( i=1 ; i<=forward ; i++ ) { + local = (Line_Control *) local->Node.next; + if ( _Chain_Is_last( &local->Node ) ) + break; + PrintLine( local ); + } + +} + +/* + * SetLineFormat + */ + +void SetLineFormat( + Line_Control *line, + ExtraFormat_info_t format +) +{ + if ( line->format != NO_EXTRA_FORMATTING_INFO ) { + fprintf( stderr, "Line %d is already formatted\n", line->number ); + PrintLine( line ); + assert( FALSE ); + } + + line->format = format; +} + +/* + * LineCopyFromRight + */ + +void LineCopyFromRight( + Line_Control *line, + char *dest +) +{ + char *p; + + for ( p=line->Contents ; *p != ' ' ; p++ ) + ; + p++; /* skip the ' ' */ + for ( ; isspace( *p ) ; p++ ) + ; + + strcpy( dest, p ); + +} + +/* + * LineCopySectionName + */ + +void LineCopySectionName( + Line_Control *line, + char *dest +) +{ + char *p; + char *d; + + p = line->Contents; + d = dest; + + if ( *p == '@' ) { /* skip texinfo command */ + while ( !isspace( *p++ ) ) + ; + } + + for ( ; *p ; ) + *d++ = *p++; + + *d = '\0'; +} + +/************************************************************************* + ************************************************************************* + ***** END OF LINE MANIPULATION ROUTINES ***** + ************************************************************************* + *************************************************************************/ + +/* + * main + */ + +int main( + int argc, + char **argv +) +{ + int c; + int index; + boolean single_file_mode; + + Verbose = FALSE; + + while ((c = getopt(argc, argv, "bv")) != EOF) { + switch (c) { + case 'v': + Verbose = TRUE; + break; + case '?': + usage(); + return 0; + } + } + + if ( Verbose ) + fprintf( stderr, "Arguments successfully parsed\n" ); + + FillLinePool(); + + for ( index=optind ; index < argc ; index++ ) { + ProcessFile( argv[ index ], NULL ); + } + + if ( Verbose ) + fprintf( stderr, "Exitting\n" ); + + return 0; +} + +/* + * ProcessFile + */ + +void ProcessFile( + char *inname, + char *outname +) +{ + char out[ 256 ]; + int index; + + /* + * Automatically generate the output file name. + */ + + if ( outname == NULL ) { + for( index=0 ; inname[index] && inname[index] != '.' ; index++ ) { + out[ index ] = inname[ index ]; + } + + out[ index++ ] = '.'; + out[ index++ ] = 't'; + out[ index++ ] = 'x'; + out[ index++ ] = 't'; + out[ index ] = '\0'; + + } + + /* + * Read the file into our internal data structure + */ + + if ( Verbose ) + printf( "Processing (%s) -> (%s)\n", inname, out ); + + ReadFileIntoChain( inname ); + + if ( Verbose ) + fprintf( stderr, "-------->FILE READ IN\n" ); + + /* + * Remove any spaces before the keyword and mark each keyword line as + * such. Also remove extra white space at the end of lines. + */ + + StripBlanks(); + + if ( Verbose ) + fprintf( stderr, "-------->BLANKS BEFORE KEYWORDS STRIPPED\n" ); + + + FormatToTexinfo(); + + if ( Verbose ) + fprintf( stderr, "-------->FILE FORMATTED TO TEXINFO\n" ); + + /* + * Print the file + */ + + PrintFile( out ); + + if ( Verbose ) + fprintf( stderr, "-------->FILE PRINTED\n" ); + + /* + * Clean Up + */ + + ReleaseFile(); + + if ( Verbose ) + fprintf( stderr, "-------->FILE RELEASED\n" ); +} + +/* + * usage + */ + +void usage( void ) +{ + int index; + + for ( index=0 ; strcmp( Usage_Strings[ index ], "EOF" ) ; index++ ) + fprintf( stderr, Usage_Strings[ index ] ); +} + +/* + * ReadFileIntoChain + */ + +void ReadFileIntoChain( + char *inname +) +{ + FILE *InFile; + int line_count; + int max_length; + char *line; + char Buffer[ BUFFER_SIZE ]; + Line_Control *new_line; + + InFile = fopen( inname, "r" ); + + if ( !InFile ) { + fprintf( stderr, "Unable to open (%s)\n", inname ); + exit( 1 ); + } + assert( InFile ); + + max_length = 0; + line_count = 0; + + _Chain_Initialize_empty( &Lines ); + + for ( ;; ) { + line = fgets( Buffer, BUFFER_SIZE, InFile ); + if ( !line ) + break; + + Buffer[ strlen( Buffer ) - 1 ] = '\0'; + + new_line = AllocateLine(); + + strcpy( new_line->Contents, Buffer ); + + new_line->number = ++line_count; + + _Chain_Append( &Lines, &new_line->Node ); + } + + fclose( InFile ); +} + +/* + * StripBlanks + */ + +void StripBlanks( void ) +{ + Line_Control *line; + Keyword_indices_t index; + int indentation; + int length; + + for ( line = (Line_Control *) Lines.first ; + !_Chain_Is_last( &line->Node ) ; + line = (Line_Control *) line->Node.next + ) { + + /* + * Strip white space from the end of each line + */ + + length = strlen( line->Contents ); + + while ( isspace( line->Contents[ --length ] ) ) + line->Contents[ length ] = '\0'; + + if ( strstr( line->Contents, "@chapter" ) ) + line->keyword = KEYWORD_CHAPTER; + else if ( strstr( line->Contents, "@chapheading" ) ) + line->keyword = KEYWORD_CHAPHEADING; + else if ( strstr( line->Contents, "@section" ) ) + line->keyword = KEYWORD_SECTION; + else if ( strstr( line->Contents, "@subsection" ) ) + line->keyword = KEYWORD_SUBSECTION; + else + line->keyword = KEYWORD_OTHER; + + } + line = AllocateLine(); + line->keyword = KEYWORD_END; + _Chain_Append( &Lines, &line->Node ); +} + +/* + * strIsAllSpace + */ + +boolean strIsAllSpace( + char *s +) +{ + char *p; + + for ( p = s ; *p ; p++ ) + if ( !isspace( *p ) ) + return FALSE; + + return TRUE; +} + +/* + * BuildTexinfoNodes + */ + +void BuildTexinfoNodes( void ) +{ + Line_Control *line; + Line_Control *new_line; + Line_Control *next_node; + char Buffer[ BUFFER_SIZE ]; + char ChapterName[ BUFFER_SIZE ]; + char NodeName[ BUFFER_SIZE ]; + char NextNode[ BUFFER_SIZE ]; + char NextNodeName[ BUFFER_SIZE ]; + char PreviousNodeName[ BUFFER_SIZE ]; + char UpNodeName[ BUFFER_SIZE ]; + char SectionName[ BUFFER_SIZE ]; + char MenuBuffer[ BUFFER_SIZE ]; + Line_Control *node_insert_point; + Line_Control *menu_insert_point; + Line_Control *node_line; + boolean next_found; + int menu_items; + + strcpy( PreviousNodeName, DocsPreviousNode ); + + for ( line = (Line_Control *) Lines.first ; + !_Chain_Is_last( &line->Node ) ; + line = (Line_Control *) line->Node.next + ) { + + menu_insert_point = (Line_Control *) line->Node.next; + + switch ( Keywords[ line->keyword ].level ) { + case TEXT: + case HEADING: + break; + case SECTION: + if ( line->keyword == KEYWORD_END ) + goto bottom; + + if ( line->keyword == KEYWORD_CHAPTER || + line->keyword == KEYWORD_CHAPHEADING ) { + LineCopyFromRight( line, ChapterName ); + strcpy( UpNodeName, DocsUpNode ); + strcpy( NodeName, ChapterName ); + } else { + LineCopySectionName( line, Buffer ); + sprintf( NodeName, "%s %s", ChapterName, Buffer ); + strcpy( UpNodeName, ChapterName ); + } + strcpy( SectionName, NodeName ); + + /* + * Go ahead and put it on the chain in the right order (ahead of + * the menu) and we can fill it in later (after the menu is built). + */ + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@ifinfo" ); + _Chain_Insert( line->Node.previous, &new_line->Node ); + + node_line = AllocateLine(); + _Chain_Insert( line->Node.previous, &node_line->Node ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@end ifinfo" ); + _Chain_Insert( line->Node.previous, &new_line->Node ); + + menu_items = 0; + + if ( line->keyword == KEYWORD_CHAPTER || line->keyword == KEYWORD_CHAPHEADING ) { + next_node = (Line_Control *) line->Node.next; + next_found = FALSE; + for ( ; ; ) { + if ( next_node->keyword == KEYWORD_END ) + break; + if ( Keywords[ next_node->keyword ].level == SECTION ) { + LineCopySectionName( next_node, Buffer ); + if ( !next_found ) { + next_found = TRUE; + sprintf( NextNodeName, "%s %s", ChapterName, Buffer ); + } + + if ( menu_items == 0 ) { + new_line = AllocateLine(); + strcpy( new_line->Contents, "@ifinfo" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@menu" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + } + + menu_items++; + + new_line = AllocateLine(); + sprintf( new_line->Contents, "* %s %s::", ChapterName, Buffer ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + } + next_node = (Line_Control *) next_node->Node.next; + } + } else { + next_node = (Line_Control *) line->Node.next; + + next_found = FALSE; + for ( ; ; ) { + if ( Keywords[ next_node->keyword ].level == SECTION ) { + if ( !next_found ) { + if ( next_node->keyword == KEYWORD_END ) { + strcpy( NextNodeName, DocsNextNode ); + } else { + LineCopySectionName( next_node, Buffer ); + sprintf( NextNodeName, "%s %s", ChapterName, Buffer ); + } + next_found = TRUE; + } + break; + } else if ( Keywords[ next_node->keyword ].level == SUBSECTION ) { + LineCopySectionName( next_node, MenuBuffer ); /* has next node */ + + if ( menu_items == 0 ) { + new_line = AllocateLine(); + strcpy( new_line->Contents, "@ifinfo" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@menu" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + } + + menu_items++; + + new_line = AllocateLine(); + sprintf( new_line->Contents, "* %s::", MenuBuffer ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + + if ( !next_found ) { + next_found = TRUE; + strcpy( NextNodeName, MenuBuffer ); + } + } + next_node = (Line_Control *) next_node->Node.next; + } + } + + if ( menu_items ) { + new_line = AllocateLine(); + strcpy( new_line->Contents, "@end menu" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@end ifinfo" ); + _Chain_Insert( menu_insert_point->Node.previous, &new_line->Node ); + } +#if 0 + fprintf( + stderr, + "@node %s, %s, %s, %s\n", + NodeName, + NextNodeName, + PreviousNodeName, + UpNodeName + ); +#endif + /* node_line was previously inserted */ + sprintf( + node_line->Contents, + "@node %s, %s, %s, %s", + NodeName, + NextNodeName, + PreviousNodeName, + UpNodeName + ); + + strcpy( PreviousNodeName, NodeName ); + break; + + case SUBSECTION: + strcpy( UpNodeName, SectionName ); + + LineCopyFromRight( line, NodeName ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@ifinfo" ); + _Chain_Insert( line->Node.previous, &new_line->Node ); + + next_node = (Line_Control *) line->Node.next; + for ( ; ; ) { + if ( Keywords[ next_node->keyword ].level == SECTION ) { + if ( next_node->keyword == KEYWORD_END ) { + strcpy( NextNodeName, DocsNextNode ); + } else { + LineCopySectionName( next_node, Buffer ); + sprintf( NextNodeName, "%s %s", ChapterName, Buffer ); + } + break; + } else if ( Keywords[ next_node->keyword ].level == SUBSECTION ) { + LineCopyFromRight( next_node, NextNodeName ); + break; + } + next_node = (Line_Control *) next_node->Node.next; + } + +#if 0 + fprintf( + stderr, + "@node %s, %s, %s, %s\n", + NodeName, + NextNodeName, + PreviousNodeName, + UpNodeName + ); +#endif + new_line = AllocateLine(); + sprintf( + new_line->Contents, + "@node %s, %s, %s, %s", + NodeName, + NextNodeName, + PreviousNodeName, + UpNodeName + ); + _Chain_Insert( line->Node.previous, &new_line->Node ); + + new_line = AllocateLine(); + strcpy( new_line->Contents, "@end ifinfo" ); + _Chain_Insert( line->Node.previous, &new_line->Node ); + + strcpy( PreviousNodeName, NodeName ); + break; + } + } +bottom: +} + +/* + * FormatToTexinfo + */ + +void FormatToTexinfo( void ) +{ + if ( Verbose ) + fprintf( stderr, "-------->INSERTING TEXINFO MENUS\n" ); + + BuildTexinfoNodes(); +} + +/* + * PrintFile + */ + +void PrintFile( + char *out +) +{ + Line_Control *line; + + OutFile = fopen( out, "w+" ); + + if ( !OutFile ) { + fprintf( stderr, "Unable to open (%s) for output\n", out ); + exit_application( 1 ); + } + assert( OutFile ); + + for ( line = (Line_Control *) Lines.first ; + !_Chain_Is_last( &line->Node ) ; + line = (Line_Control *) line->Node.next ) { + fprintf( OutFile, "%s\n", line->Contents ); +/* + fprintf( + OutFile, + "(%d,%d)%s\n", + line->keyword, + line->format, + line->Contents + ); +*/ + } +} + +/* + * DumpList + */ + +void DumpList( + Chain_Control *the_list +) +{ + Line_Control *line; + + fprintf( stderr, "---> Dumping list (%p)\n", the_list ); + + for ( line = (Line_Control *) the_list->first ; + !_Chain_Is_last( &line->Node ) ; + line = (Line_Control *) line->Node.next ) { + fprintf( stderr, "%s\n", line->Contents ); + } +} + +/* + * ReleaseFile + */ + +void ReleaseFile() +{ + Line_Control *line; + Line_Control *next; + + for ( line = (Line_Control *) Lines.first ; + !_Chain_Is_last( &line->Node ) ; + ) { + next = (Line_Control *) line->Node.next; + line = next; + } +} + +/* + * strtoInitialCaps + */ + +void strtoInitialCaps( + char *dest, + char *src +) +{ + char *source = src; + char *destination = dest; + + source = src; + destination = (dest) ? dest : src; + + while ( *source ) { + while ( isspace( *source ) ) + *destination++ = *source++; + + if ( !*source ) + break; + + *destination++ = toupper( *source++ ); + + for ( ; *source && !isspace( *source ) ; source++ ) + *destination++ = tolower( *source ); + + if ( !*source ) + break; + } + + *destination = '\0'; +} diff --git a/doc/tools/bmenu/main.o b/doc/tools/bmenu/main.o new file mode 100644 index 0000000000..e4b1fa7579 Binary files /dev/null and b/doc/tools/bmenu/main.o differ diff --git a/doc/tools/bmenu/system.h b/doc/tools/bmenu/system.h new file mode 100644 index 0000000000..21e163a35e --- /dev/null +++ b/doc/tools/bmenu/system.h @@ -0,0 +1,29 @@ + +#ifndef __SYSTEM_h +#define __SYSTEM_h + +typedef unsigned int unsigned32; +typedef unsigned short unsigned16; +typedef unsigned char unsigned8; + +#define USE_INLINES +#define STATIC static +#define INLINE inline + +#ifndef NULL +#define NULL 0 +#endif + +typedef unsigned int boolean; + +#if !defined( TRUE ) || (TRUE != 1) +#undef TRUE +#define TRUE (1) +#endif + +#if !defined( FALSE ) || (FALSE != 0) +#undef FALSE +#define FALSE 0 +#endif + +#endif diff --git a/doc/tools/update b/doc/tools/update new file mode 100644 index 0000000000..284bb3f2b2 --- /dev/null +++ b/doc/tools/update @@ -0,0 +1,215 @@ +#!/bin/ksh +# +# update,v 1.2 1995/05/31 17:20:58 joel Exp +# +# Either bash or ksh will be ok for this; requires 'test -ot' +# (-p above just says to not parse $ENV file; makes it faster for +# those of us who set $ENV) +# +# +# NOTE +# +# This is potentially a very dangerous program. + +# progname=`basename $0` +progname=${0##*/} # fast basename hack for ksh, bash + +USAGE=\ +" +usage: $progname [ -vs ] [ -b base_directory ] [-p file] [-f] [files...] + -v -- verbose + -p -- file with replacement instructions + -s -- skip prompt for backup verification + -f -- do files at end of line + +base_directory is the root directory of the source code to update. It +defaults to the current directory. + +This program updates C, H, and .inl files. +" + +fatal() { + if [ "$1" ] + then + echo >&2 + echo $* >&2 + echo >&2 + fi + echo "$USAGE" 1>&2 + exit 1 +} + +# +# KLUDGE to figure out at runtime how to echo a line without a +# newline. +# +count=`echo "\\c" | wc -c` +if [ ${count} -ne 0 ] ; then + EARG="-n" + EOL="" +else + EARG="" + EOL="\\c" +fi + +# +# Function to make sure they do a backup +# + +WARNING=\ +" + +******************************************************************************* +******************************************************************************* +******************************************************************************* +**** **** +**** WARNING!!! WARNING!!! WARNING!!! **** +**** **** +**** ALL SOURCE CODE SHOULD BE BACKED UP BEFORE RUNNING THIS PROGRAM!! **** +**** **** +**** WARNING!!! WARNING!!! WARNING!!! **** +**** **** +******************************************************************************* +******************************************************************************* +******************************************************************************* + +" + +verify_backup() +{ + echo "$WARNING" + continue="yes" + while [ $continue = "yes" ] + do +echo ${EARG} "Do you wish to update the source tree at this time [y|n]? " ${EOL} + read answer + case $answer in + [yY]*) + continue="no" + ;; + [nN]*) + echo + echo "Exitting at user request" + echo + exit 0 + ;; + esac + done +} + +# +# Default tools to use... +# +# NOTE: The GNU versions of both of these are faster. +# +find_prog=find +xargs_prog=xargs + +# +# process the options +# + +verbose="" +suffix="" +mode="" +base_directory=. +do_files="no" +do_prompt="yes" +replacement_file="${RTEMS_HOME}/update-tools/310_to_320_list" + +while getopts sfp:b:v OPT +do + case "$OPT" in + v) + verbose="yes";; + s) + do_prompt="no";; + b) + base_directory=${OPTARG};; + p) + replacement_file=${OPTARG};; + f) + do_files="yes";; + *) + fatal + esac +done + +let $((shiftcount = $OPTIND - 1)) +shift $shiftcount + +args=$* + +# +# Make sure they have done a backup +# + +if [ ${do_prompt} = "yes" ] +then + verify_backup +fi + +# +# Validate the base directory +# + +if [ ! -d $base_directory ] +then + fatal "${base_directory} does not exist" +fi + +# +# Validate the replacement file +# + +if [ ! -r $replacement_file ] +then + fatal "${replacement_file} does not exist or is not readable" +fi + + +# +# Verify enough of the RTEMS environment variables are set +# + +if [ ! -d "${RTEMS_HOME}" ] +then + fatal "RTEMS_HOME environment variable is not initialized" +fi + +# +# Update the files +# + +generate_list() +{ + if [ ${do_files} = "yes" ] + then + for i in $args + do + echo $i + done + else + ${find_prog} ${base_directory} \( -name "*.[ch]" -o -name "*.inl" \) -print + fi +} + +generate_list | ${xargs_prog} | + while read line + do + ${RTEMS_HOME}/update-tools/word-replace -p ${replacement_file} ${line} + if [ $? -ne 0 ] + then + exit 1 + fi + for file in ${line} + do + mv ${file}.fixed ${file} + done + done + +exit 0 + +# Local Variables: *** +# mode:ksh *** +# End: *** diff --git a/doc/tools/word-replace b/doc/tools/word-replace new file mode 100755 index 0000000000..2bfd2afb88 --- /dev/null +++ b/doc/tools/word-replace @@ -0,0 +1,85 @@ +#!/usr/bin/perl +eval "exec /usr/local/bin/perl -S $0 $*" + if $running_under_some_shell; + +require 'getopts.pl'; +&Getopts("p:vh"); # help, pattern file, verbose, + +if ($opt_h || ! $opt_p) { + print STDERR <) +{ + chop; + s/#.*//; + next if /^$/; + ($orig, $new, $junk, @rest) = split; + next if ( ! $orig || ! $new || $junk); # <2 or >2 patterns + die "pattern appears 2x: '$orig' in '$pattern_file'--" if defined($patterns{$orig}); + $patterns{$orig} = $new; +} +close PATTERNS; + +# walk thru each line in each file +foreach $file (@ARGV) +{ + print "$file\t"; + + open (INFILE, "<$file") || + die "could not open input file $file: $!"; + + $outfile = $file . ".fixed";; + open (OUTFILE, ">$outfile") || + die "could not open output file $outfile: $!"; + + while () + { + study; # maybe make s/// faster + foreach $key (keys %patterns) + { + if ( s/\b$key\b/$patterns{$key}/ge ) + { + print "."; + } + } + print OUTFILE $_; + } + print "\n"; + close INFILE; + close OUTFILE; +} + diff --git a/doc/user/Makefile b/doc/user/Makefile new file mode 100644 index 0000000000..4830a70879 --- /dev/null +++ b/doc/user/Makefile @@ -0,0 +1,59 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=c_user + +all: + +COMMON_FILES=../common/cpright.texi +FILES= bsp.texi c_user.texi clock.texi concepts.texi conf.texi \ +dirstat.texi dpmem.texi event.texi example.texi fatal.texi \ +glossary.texi init.texi intr.texi io.texi mp.texi msg.texi overview.texi \ +part.texi preface.texi region.texi rtmon.texi schedule.texi sem.texi \ +signal.texi task.texi timer.texi userext.texi $(COMMON_FILES) + +all: + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: c_user + cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL) + +c_user: $(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) + +dv: dvi + $(XDVI) $(PROJECT).dvi + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +html: + -mkdir $(WWW_INSTALL)/c_user + cp rtemsarc.gif rtemspie.gif states.gif $(WWW_INSTALL)/c_user + $(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 c_user c_user-* _* + diff --git a/doc/user/bsp.t b/doc/user/bsp.t new file mode 100644 index 0000000000..85b87f1078 --- /dev/null +++ b/doc/user/bsp.t @@ -0,0 +1,377 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages Reset and Initialization:: +* Board Support Packages Device Drivers:: +* Board Support Packages User Extensions:: +* Board Support Packages Multiprocessor Communications Interface (MPCI):: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages Reset and Initialization, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +A board support package (BSP) is a collection of +user-provided facilities which interface RTEMS and an +application with a specific hardware platform. These facilities +may include hardware initialization, device drivers, user +extensions, and a Multiprocessor Communications Interface +(MPCI). However, a minimal BSP need only support processor +reset and initialization and, if needed, a clock tick. + +@ifinfo +@node Board Support Packages Reset and Initialization, Interrupt Stack Requirements, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section Reset and Initialization +@ifinfo +@menu +* Interrupt Stack Requirements:: +* Processors with a Separate Interrupt Stack:: +* Processors without a Separate Interrupt Stack:: +@end menu +@end ifinfo + +An RTEMS based application is initiated or +re-initiated when the processor is reset. This initialization +code is responsible for preparing the target platform for the +RTEMS application. Although the exact actions performed by the +initialization code are highly processor and target dependent, +the logical functionality of these actions are similar across a +variety of processors and target platforms. + +Normally, the application's initialization is +performed at two separate times: before the call to +initialize_executive (reset application initialization) and +after initialize_executive in the user's initialization tasks +(local and global application initialization). The order of the +startup procedure is as follows: + +@enumerate +@item Reset application initialization. +@item Call to initialize_executive +@item Local and global application initialization. +@end enumerate + +The reset application initialization code is executed +first when the processor is reset. All of the hardware must be +initialized to a quiescent state by this software before +initializing RTEMS. When in quiescent state, devices do not +generate any interrupts or require any servicing by the +application. Some of the hardware components may be initialized +in this code as well as any application initialization that does +not involve calls to RTEMS directives. + +The processor's Interrupt Vector Table which will be +used by the application may need to be set to the required value +by the reset application initialization code. Because +interrupts are enabled automatically by RTEMS as part of the +initialize_executive directive, the Interrupt Vector Table MUST +be set before this directive is invoked to insure correct +interrupt vectoring. The processor's Interrupt Vector Table +must be accessible by RTEMS as it will be modified by the +interrupt_catch directive. On some CPUs, RTEMS installs it's +own Interrupt Vector Table as part of initialization and thus +these requirements are met automatically. The reset code which +is executed before the call to initialize_executive has the +following requirements: + +@itemize @bullet +@item Must not make any RTEMS directive calls. + +@item If the processor supports multiple privilege levels, +must leave the processor in the most privileged, or supervisory, +state. + +@item Must allocate a stack of at least MINIMUM_STACK_SIZE +bytes and initialize the stack pointer for the +initialize_executive directive. + +@item Must initialize the processor's Interrupt Vector Table. + +@item Must disable all maskable interrupts. + +@item If the processor supports a separate interrupt stack, +must allocate the interrupt stack and initialize the interrupt +stack pointer. +@end itemize + +The initialize_executive directive does not return to +the initialization code, but causes the highest priority +initialization task to begin execution. Initialization tasks +are used to perform both local and global application +initialization which is dependent on RTEMS facilities. The user +initialization task facility is typically used to create the +application's set of tasks. + +@ifinfo +@node Interrupt Stack Requirements, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Interrupt Stack Requirements + +The worst-case stack usage by interrupt service +routines must be taken into account when designing an +application. If the processor supports interrupt nesting, the +stack usage must include the deepest nest level. The worst-case +stack usage must account for the following requirements: + +@itemize @bullet +@item Processor's interrupt stack frame + +@item Processor's subroutine call stack frame + +@item RTEMS system calls + +@item Registers saved on stack + +@item Application subroutine calls +@end itemize + +The size of the interrupt stack must be greater than +or equal to the constant MINIMUM_STACK_SIZE. + +@ifinfo +@node Processors with a Separate Interrupt Stack, Processors without a Separate Interrupt Stack, Interrupt Stack Requirements, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Processors with a Separate Interrupt Stack + +Some processors support a separate stack for +interrupts. When an interrupt is vectored and the interrupt is +not nested, the processor will automatically switch from the +current stack to the interrupt stack. The size of this stack is +based solely on the worst-case stack usage by interrupt service +routines. + +The dedicated interrupt stack for the entire +application is supplied and initialized by the reset and +initialization code of the user's board support package. Since +all ISRs use this stack, the stack size must take into account +the worst case stack usage by any combination of nested ISRs. + +@ifinfo +@node Processors without a Separate Interrupt Stack, Board Support Packages Device Drivers, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Processors without a Separate Interrupt Stack + +Some processors do not support a separate stack for +interrupts. In this case, without special assistance every +task's stack must include enough space to handle the task's +worst-case stack usage as well as the worst-case interrupt stack +usage. This is necessary because the worst-case interrupt +nesting could occur while any task is executing. + +On many processors without dedicated hardware managed +interrupt stacks, RTEMS manages a dedicated interrupt stack in +software. If this capability is supported on a CPU, then it is +logically equivalent to the processor supporting a separate +interrupt stack in hardware. + +@ifinfo +@node Board Support Packages Device Drivers, Clock Tick Device Driver, Processors without a Separate Interrupt Stack, Board Support Packages +@end ifinfo +@section Device Drivers +@ifinfo +@menu +* Clock Tick Device Driver:: +@end menu +@end ifinfo + +Device drivers consist of control software for +special peripheral devices and provide a logical interface for +the application developer. The RTEMS I/O manager provides +directives which allow applications to access these device +drivers in a consistent fashion. A Board Support Package may +include device drivers to access the hardware on the target +platform. These devices typically include serial and parallel +ports, counter/timer peripherals, real-time clocks, disk +interfaces, and network controllers. + +For more information on device drivers, refer to the +I/O Manager chapter. + +@ifinfo +@node Clock Tick Device Driver, Board Support Packages User Extensions, Board Support Packages Device Drivers, Board Support Packages Device Drivers +@end ifinfo +@subsection Clock Tick Device Driver + +Most RTEMS applications will include a clock tick +device driver which invokes the clock_tick directive at regular +intervals. The clock tick is necessary if the application is to +utilize timeslicing, the clock manager, the timer manager, the +rate monotonic manager, or the timeout option on blocking +directives. + +The clock tick is usually provided as an interrupt +from a counter/timer or a real-time clock device. When a +counter/timer is used to provide the clock tick, the device is +typically programmed to operate in continuous mode. This mode +selection causes the device to automatically reload the initial +count and continue the countdown without programmer +intervention. This reduces the overhead required to manipulate +the counter/timer in the clock tick ISR and increases the +accuracy of tick occurrences. The initial count can be based on +the microseconds_per_tick field in the RTEMS Configuration +Table. An alternate approach is to set the initial count for a +fixed time period (such as one millisecond) and have the ISR +invoke clock_tick on the microseconds_per_tick boundaries. +Obviously, this can induce some error if the configured +microseconds_per_tick is not evenly divisible by the chosen +clock interrupt quantum. + +It is important to note that the interval between +clock ticks directly impacts the granularity of RTEMS timing +operations. In addition, the frequency of clock ticks is an +important factor in the overall level of system overhead. A +high clock tick frequency results in less processor time being +available for task execution due to the increased number of +clock tick ISRs. + +@ifinfo +@node Board Support Packages User Extensions, Board Support Packages Multiprocessor Communications Interface (MPCI), Clock Tick Device Driver, Board Support Packages +@end ifinfo +@section User Extensions + +RTEMS allows the application developer to augment +selected features by invoking user-supplied extension routines +when the following system events occur: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begin +@item Task exits +@item Fatal error detection +@end itemize + +User extensions can be used to implement a wide variety of +functions including execution profiling, non-standard +coprocessor support, debug support, and error detection and +recovery. For example, the context of a non-standard numeric +coprocessor may be maintained via the user extensions. In this +example, the task creation and deletion extensions are +responsible for allocating and deallocating the context area, +the task initiation and reinitiation extensions would be +responsible for priming the context area, and the task context +switch extension would save and restore the context of the +device. + +For more information on user extensions, refer to the +User Extensions chapter. + +@ifinfo +@node Board Support Packages Multiprocessor Communications Interface (MPCI), Tightly-Coupled Systems, Board Support Packages User Extensions, Board Support Packages +@end ifinfo +@section Multiprocessor Communications Interface (MPCI) +@ifinfo +@menu +* Tightly-Coupled Systems:: +* Loosely-Coupled Systems:: +* Systems with Mixed Coupling:: +* Heterogeneous Systems:: +@end menu +@end ifinfo + +RTEMS requires that an MPCI layer be provided when a +multiple node application is developed. This MPCI layer must +provide an efficient and reliable communications mechanism +between the multiple nodes. Tasks on different nodes +communicate and synchronize with one another via the MPCI. Each +MPCI layer must be tailored to support the architecture of the +target platform. + +For more information on the MPCI, refer to the +Multiprocessing Manager chapter. + +@ifinfo +@node Tightly-Coupled Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI), Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Tightly-Coupled Systems + +A tightly-coupled system is a multiprocessor +configuration in which the processors communicate solely via +shared global memory. The MPCI can simply place the RTEMS +packets in the shared memory space. The two primary +considerations when designing an MPCI for a tightly-coupled +system are data consistency and informing another node of a +packet. + +The data consistency problem may be solved using +atomic "test and set" operations to provide a "lock" in the +shared memory. It is important to minimize the length of time +any particular processor locks a shared data structure. + +The problem of informing another node of a packet can +be addressed using one of two techniques. The first technique +is to use an interprocessor interrupt capability to cause an +interrupt on the receiving node. This technique requires that +special support hardware be provided by either the processor +itself or the target platform. The second technique is to have +a node poll for arrival of packets. The drawback to this +technique is the overhead associated with polling. + +@ifinfo +@node Loosely-Coupled Systems, Systems with Mixed Coupling, Tightly-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Loosely-Coupled Systems + +A loosely-coupled system is a multiprocessor +configuration in which the processors communicate via some type +of communications link which is not shared global memory. The +MPCI sends the RTEMS packets across the communications link to +the destination node. The characteristics of the communications +link vary widely and have a significant impact on the MPCI +layer. For example, the bandwidth of the communications link +has an obvious impact on the maximum MPCI throughput. + +The characteristics of a shared network, such as +Ethernet, lend themselves to supporting an MPCI layer. These +networks provide both the point-to-point and broadcast +capabilities which are expected by RTEMS. + +@ifinfo +@node Systems with Mixed Coupling, Heterogeneous Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Systems with Mixed Coupling + +A mixed-coupling system is a multiprocessor +configuration in which the processors communicate via both +shared memory and communications links. A unique characteristic +of mixed-coupling systems is that a node may not have access to +all communication methods. There may be multiple shared memory +areas and communication links. Therefore, one of the primary +functions of the MPCI layer is to efficiently route RTEMS +packets between nodes. This routing may be based on numerous +algorithms. In addition, the router may provide alternate +communications paths in the event of an overload or a partial +failure. + +@ifinfo +@node Heterogeneous Systems, User Extensions Manager, Systems with Mixed Coupling, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Heterogeneous Systems + +Designing an MPCI layer for a heterogeneous system +requires special considerations by the developer. RTEMS is +designed to eliminate many of the problems associated with +sharing data in a heterogeneous environment. The MPCI layer +need only address the representation of thirty-two (32) bit +unsigned quantities. + +For more information on supporting a heterogeneous +system, refer the Supporting Heterogeneous Environments in the +Multiprocessing Manager chapter. diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi new file mode 100644 index 0000000000..625f9f934d --- /dev/null +++ b/doc/user/c_user.texi @@ -0,0 +1,159 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_user +@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 C User: (c_user). 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 Applications C User's Guide + +@setchapternewpage odd +@settitle RTEMS C User's Guide +@titlepage +@finalout + +@title RTEMS Applications C User's 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 preface.texi +@include overview.texi +@include concepts.texi +@include init.texi +@include task.texi +@include intr.texi +@include clock.texi +@include timer.texi +@include sem.texi +@include msg.texi +@include event.texi +@include signal.texi +@include part.texi +@include region.texi +@include dpmem.texi +@include io.texi +@include fatal.texi +@include schedule.texi +@include rtmon.texi +@include bsp.texi +@include userext.texi +@include conf.texi +@include mp.texi +@include dirstat.texi +@include example.texi +@include glossary.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top c_user + +This is the online version of the RTEMS C User's Guide. + +@menu +* Preface:: +* Overview:: +* Key Concepts:: +* Initialization Manager:: +* Task Manager:: +* Interrupt Manager:: +* Clock Manager:: +* Timer Manager:: +* Semaphore Manager:: +* Message Manager:: +* Event Manager:: +* Signal Manager:: +* Partition Manager:: +* Region Manager:: +* Dual-Ported Memory Manager:: +* I/O Manager:: +* Fatal Error Manager:: +* Scheduling Concepts:: +* Rate Monotonic Manager:: +* Board Support Packages:: +* User Extensions Manager:: +* Configuring a System:: +* Multiprocessing Manager:: +* Directive Status Codes:: +* Example Application:: +* Glossary:: +* 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, Glossary, 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/user/clock.t b/doc/user/clock.t new file mode 100644 index 0000000000..f90d5c20b6 --- /dev/null +++ b/doc/user/clock.t @@ -0,0 +1,356 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Clock Manager, Clock Manager Introduction, INTERRUPT_CATCH - Establish an ISR, 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 provides support for time of day +and other time related capabilities. The directives provided by +the clock manager are: + +@itemize @bullet +@item @code{clock_set} - Set system date and time +@item @code{clock_get} - Get system date and time information +@item @code{clock_tick} - Announce a clock tick +@end itemize + +@ifinfo +@node Clock Manager Background, Required Support, Clock Manager Introduction, Clock Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Required Support:: +* Time and Date Data Structures:: +* Clock Tick and Timeslicing:: +* Delays:: +* Timeouts:: +@end menu +@end ifinfo + +@ifinfo +@node Required Support, Time and Date Data Structures, Clock Manager Background, Clock Manager Background +@end ifinfo +@subsection Required Support + +For the features provided by the clock manager to be +utilized, periodic timer interrupts are required. Therefore, a +real-time clock or hardware timer is necessary to create the +timer interrupts. The clock_tick directive is normally called +by the timer ISR to announce to RTEMS that a system clock tick +has occurred. Elapsed time is measured in ticks. A tick is +defined to be an integral number of microseconds which is +specified by the user in the Configuration Table. + +@ifinfo +@node Time and Date Data Structures, Clock Tick and Timeslicing, Required Support, Clock Manager Background +@end ifinfo +@subsection Time and Date Data Structures + +The clock facilities of the clock manager operate +upon calendar time. These directives utilize the following date +and time structure for the native time and date format: + +@example +struct rtems_tod_control @{ + rtems_unsigned32 year; /* greater than 1987 */ + rtems_unsigned32 month; /* 1 - 12 */ + rtems_unsigned32 day; /* 1 - 31 */ + rtems_unsigned32 hour; /* 0 - 23 */ + rtems_unsigned32 minute; /* 0 - 59 */ + rtems_unsigned32 second; /* 0 - 59 */ + rtems_unsigned32 ticks; /* elapsed between seconds */ +@}; + +typedef struct rtems_tod_control rtems_time_of_day; +@end example + + +The native date and time format is the only format +supported when setting the system date and time using the +clock_get directive. Some applications expect to operate on a +"UNIX-style" date and time data structure. The clock_get +directive can optionally return the current date and time in the +following structure: + +@example +@group +typedef struct @{ + rtems_unsigned32 seconds; /* seconds since RTEMS epoch*/ + rtems_unsigned32 microseconds; /* since last second */ +@} rtems_clock_time_value_control; +@end group +@end example + + +The seconds field in this structure is the number of +seconds since the RTEMS epoch of January 1, 1988. + +@ifinfo +@node Clock Tick and Timeslicing, Delays, Time and Date Data Structures, Clock Manager Background +@end ifinfo +@subsection Clock Tick and Timeslicing + +Timeslicing is a task scheduling discipline in which +tasks of equal priority are executed for a specific period of +time before control of the CPU is passed to another task. It is +also sometimes referred to as the automatic round-robin +scheduling algorithm. The length of time allocated to each task +is known as the quantum or timeslice. + +The system's timeslice is defined as an integral +number of ticks, and is specified in the Configuration Table. +The timeslice is defined for the entire system of tasks, but +timeslicing is enabled and disabled on a per task basis. + +The clock_tick directive implements timeslicing by +decrementing the running task's time-remaining counter when both +timeslicing and preemption are enabled. If the task's timeslice +has expired, then that task will be preempted if there exists a +ready task of equal priority. + +@ifinfo +@node Delays, Timeouts, Clock Tick and Timeslicing, Clock Manager Background +@end ifinfo +@subsection Delays + +A sleep timer allows a task to delay for a given +interval or up until a given time, and then wake and continue +execution. This type of timer is created automatically by the +task_wake_after and task_wake_when directives and, as a result, +does not have an RTEMS ID. Once activated, a sleep timer cannot +be explicitly deleted. Each task may activate one and only one +sleep timer at a time. + +@ifinfo +@node Timeouts, Clock Manager Operations, Delays, Clock Manager Background +@end ifinfo +@subsection Timeouts + +Timeouts are a special type of timer automatically +created when the timeout option is used on the +message_queue_receive, event_receive, semaphore_obtain and +region_get_segment directives. Each task may have one and only +one timeout active at a time. When a timeout expires, it +unblocks the task with a timeout status code. + +@ifinfo +@node Clock Manager Operations, Announcing a Tick, Timeouts, Clock Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Tick:: +* Setting the Time:: +* Obtaining the Time:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Tick, Setting the Time, Clock Manager Operations, Clock Manager Operations +@end ifinfo +@subsection Announcing a Tick + +RTEMS provides the clock_tick directive which is +called from the user's real-time clock ISR to inform RTEMS that +a tick has elapsed. The tick frequency value, defined in +microseconds, is a configuration parameter found in the +Configuration Table. RTEMS divides one million microseconds +(one second) by the number of microseconds per tick to determine +the number of calls to the clock_tick directive per second. The +frequency of clock_tick calls determines the resolution +(granularity) for all time dependent RTEMS actions. For +example, calling clock_tick ten times per second yields a higher +resolution than calling clock_tick two times per second. The +clock_tick directive is responsible for maintaining both +calendar time and the dynamic set of timers. + +@ifinfo +@node Setting the Time, Obtaining the Time, Announcing a Tick, Clock Manager Operations +@end ifinfo +@subsection Setting the Time + +The clock_set directive allows a task or an ISR to +set the date and time maintained by RTEMS. If setting the date +and time causes any outstanding timers to pass their deadline, +then the expired timers will be fired during the invocation of +the clock_set directive. + +@ifinfo +@node Obtaining the Time, Clock Manager Directives, Setting the Time, Clock Manager Operations +@end ifinfo +@subsection Obtaining the Time + +The clock_get directive allows a task or an ISR to +obtain the current date and time or date and time related +information. The current date and time can be returned in +either native or UNIX-style format. Additionally, the +application can obtain date and time related information such as +the number of seconds since the RTEMS epoch, the number of ticks +since the executive was initialized, and the number of ticks per +second. The information returned by the clock_get directive is +dependent on the option selected by the caller. The following +options are available: + +@itemize @bullet +@item CLOCK_GET_TOD - obtain native style date and time +@item CLOCK_GET_TIME_VALUE - obtain UNIX-style date and time +@item CLOCK_GET_TICKS_SINCE_BOOT - obtain number of ticks since RTEMS was initialized +@item CLOCK_GET_SECONDS_SINCE_EPOCH - obtain number of seconds since RTEMS epoch +@item CLOCK_GET_TICKS_PER_SECOND - obtain number of clock ticks per second +@end itemize + +Calendar time operations will return an error code if +invoked before the date and time have been set. + +@ifinfo +@node Clock Manager Directives, CLOCK_SET - Set system date and time, Obtaining the Time, Clock Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* CLOCK_SET - Set system date and time:: +* CLOCK_GET - Get system date and time information:: +* CLOCK_TICK - Announce a clock tick:: +@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_SET - Set system date and time, CLOCK_GET - Get system date and time information, Clock Manager Directives, Clock Manager Directives +@end ifinfo +@subsection CLOCK_SET - Set system date and time + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_set( + rtems_time_of_day *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - date and time set successfully@* +@code{INVALID_TIME_OF_DAY} - invalid time of day + +@subheading DESCRIPTION: + +This directive sets the system date and time. The +date, time, and ticks in the time_buffer structure are all +range-checked, and an error is returned if any one is out of its +valid range. + +@subheading NOTES: + +Years before 1988 are invalid. + +The system date and time are based on the configured +tick rate (number of microseconds in a tick). + +Setting the time forward may cause a higher priority +task, blocked waiting on a specific time, to be made ready. In +this case, the calling task will be preempted after the next +clock tick. + +Re-initializing RTEMS causes the system date and time +to be reset to an uninitialized state. Another call to +clock_set is required to re-initialize the system date and time +to application specific specifications. + +@page +@ifinfo +@node CLOCK_GET - Get system date and time information, CLOCK_TICK - Announce a clock tick, CLOCK_SET - Set system date and time, Clock Manager Directives +@end ifinfo +@subsection CLOCK_GET - Get system date and time information + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_get( + rtems_clock_get_options option, + void *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - current time obtained successfully@* +@code{NOT_DEFINED} - system date and time is not set + +@subheading DESCRIPTION: + +This directive obtains the system date and time. If +the caller is attempting to obtain the date and time (i.e. +option is set to either CLOCK_GET_SECONDS_SINCE_EPOCH, +CLOCK_GET_TOD, or CLOCK_GET_TIME_VALUE) and the date and time +has not been set with a previous call to clock_set, then the +NOT_DEFINED status code is returned. The caller can always +obtain the number of ticks per second (option is +CLOCK_GET_TICKS_PER_SECOND) and the number of ticks since the +executive was initialized option is CLOCK_GET_TICKS_SINCE_BOOT). + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the running task to be +preempted. Re-initializing RTEMS causes the system date and +time to be reset to an uninitialized state. Another call to +clock_set is required to re-initialize the system date and time +to application specific specifications. + +@page +@ifinfo +@node CLOCK_TICK - Announce a clock tick, Timer Manager, CLOCK_GET - Get system date and time information, Clock Manager Directives +@end ifinfo +@subsection CLOCK_TICK - Announce a clock tick + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_tick( void ); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - current time obtained successfully + +@subheading DESCRIPTION: + +This directive announces to RTEMS that a system clock +tick has occurred. The directive is usually called from the +timer interrupt ISR of the local processor. This directive +maintains the system date and time, decrements timers for +delayed tasks, timeouts, rate monotonic periods, and implements +timeslicing. + +@subheading NOTES: + +This directive is typically called from an ISR. + +The microseconds_per_tick and ticks_per_timeslice +parameters in the Configuration Table contain the number of +microseconds per tick and number of ticks per timeslice, +respectively. + diff --git a/doc/user/concepts.t b/doc/user/concepts.t new file mode 100644 index 0000000000..fabcfdf57d --- /dev/null +++ b/doc/user/concepts.t @@ -0,0 +1,322 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c The following figure was replaced with an ASCII equivalent. +@c Figure 2-1 Object ID Composition +@c +@ifinfo +@node Key Concepts, Key Concepts Introduction, Overview Manual Organization, Top +@end ifinfo +@chapter Key Concepts +@ifinfo +@menu +* Key Concepts Introduction:: +* Key Concepts Objects:: +* Key Concepts Communication and Synchronization:: +* Key Concepts Time:: +* Key Concepts Memory Management:: +@end menu +@end ifinfo + +@ifinfo +@node Key Concepts Introduction, Key Concepts Objects, Key Concepts, Key Concepts +@end ifinfo +@section Introduction + +The facilities provided by RTEMS are built upon a +foundation of very powerful concepts. These concepts must be +understood before the application developer can efficiently +utilize RTEMS. The purpose of this chapter is to familiarize +one with these concepts. + +@ifinfo +@node Key Concepts Objects, Key Concepts Communication and Synchronization, Key Concepts Introduction, Key Concepts +@end ifinfo +@section Objects + +RTEMS provides directives which can be used to +dynamically create, delete, and manipulate a set of predefined +object types. These types include tasks, message queues, +semaphores, memory regions, memory partitions, timers, ports, +and rate monotonic periods. The object-oriented nature of RTEMS +encourages the creation of modular applications built upon +re-usable "building block" routines. + +All objects are created on the local node as required +by the application and have an RTEMS assigned ID. All objects +have a user-assigned name. Although a relationship exists +between an object's name and its RTEMS assigned ID, the name and +ID are not identical. Object names are completely arbitrary and +selected by the user as a meaningful "tag" which may commonly +reflect the object's use in the application. Conversely, object +IDs are designed to facilitate efficient object manipulation by +the executive. + +An object name is an unsigned thirty-two bit entity +associated with the object by the user. Although not required +by RTEMS, object names are typically composed of four ASCII +characters which help identify that object. For example, a task +which causes a light to blink might be called "LITE". Utilities +are provided to build an object name from four ASCII characters +and to decompose an object name into four ASCII characters. +However, it is not required that the application use ASCII +characters to build object names. For example, if an +application requires one-hundred tasks, it would be difficult to +assign meaningful ASCII names to each task. A more convenient +approach would be to name them the binary values one through +one-hundred, respectively. + +@need 3000 + +An object ID is a unique unsigned thirty-two bit +entity composed of three parts: object class, node, and index. +The most significant six bits are the object class. The next +ten bits are the number of the node on which this object was +created. The node number is always one (1) in a single +processor system. The least significant sixteen bits form an +identifier within a particular object type. This identifier, +called the object index, ranges in value from 1 to the maximum +number of objects configured for this object type. + +@ifset use-ascii +ASCII +@example +@group + 31 26 25 16 15 0 + +-----------+------------------+-------------------------------+ + | | | | + | Class | Node | Index | + | | | | + +-----------+------------------+-------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +#& +\hbox to 1.00in{\enskip#}& +\hbox to 1.00in{\enskip#}& +#\cr +\multispan{9}\cr +\multispan{2}31\hfil&\multispan{2}\hfil26\enskip& + \multispan{1}\enskip25\hfil&\multispan{2}\hfil16\enskip& + \multispan{1}\enskip15\hfil&\multispan{2}\hfil0\cr +&&&&&&&&&\cr +}}\hfil} +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#\cr +\multispan{9}\cr +\noalign{\hrule} +&&&&&&&&&\cr +&\multispan{2}\hfil Class\hfil&& + \multispan{2}\hfil Node\hfil&& + \multispan{2}\hfil Index\hfil&\cr +&&&&&&&&&\cr +\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + +
    31262516150
    +
    +
    + + + + +
    ClassNodeIndex
    +
    +@end html +@end ifset + + +The three components of an object ID make it possible +to quickly locate any object in even the most complicated +multiprocessor system. Object ID's are associated with an +object by RTEMS when the object is created and the corresponding +ID is returned by the appropriate object create directive. The +object ID is required as input to all directives involving +objects, except those which create an object or obtain the ID of +an object. + +The object identification directives can be used to +dynamically obtain a particular object's ID given its name. +This mapping is accomplished by searching the name table +associated with this object type. If the name is non-unique, +then the ID associated with the first occurrence of the name +will be returned to the application. Since object IDs are +returned when the object is created, the object identification +directives are not necessary in a properly designed single +processor application. + +An object control block is a data structure defined +by RTEMS which contains the information necessary to manage a +particular object type. For efficiency reasons, the format of +each object type's control block is different. However, many of +the fields are similar in function. The number of each type of +control block is application dependent and determined by the +values specified in the user's Configuration Table. An object +control block is allocated at object create time and freed when +the object is deleted. With the exception of user extension +routines, object control blocks are not directly manipulated by +user applications. + +@ifinfo +@node Key Concepts Communication and Synchronization, Key Concepts Time, Key Concepts Objects, Key Concepts +@end ifinfo +@section Communication and Synchronization + +In real-time multitasking applications, the ability +for cooperating execution threads to communicate and synchronize +with each other is imperative. A real-time executive should +provide an application with the following capabilities: + +@itemize @bullet +@item Data transfer between cooperating tasks +@item Data transfer between tasks and ISRs +@item Synchronization of cooperating tasks +@item Synchronization of tasks and ISRs +@end itemize + +Most RTEMS managers can be used to provide some form +of communication and/or synchronization. However, managers +dedicated specifically to communication and synchronization +provide well established mechanisms which directly map to the +application's varying needs. This level of flexibility allows +the application designer to match the features of a particular +manager with the complexity of communication and synchronization +required. The following managers were specifically designed for +communication and synchronization: + +@itemize @bullet +@item Semaphore +@item Message Queue +@item Event +@item Signal +@end itemize + +The semaphore manager supports mutual exclusion +involving the synchronization of access to one or more shared +user resources. Binary semaphores may utilize the optional +priority inheritance algorithm to avoid the problem of priority +inversion. The message manager supports both communication and +synchronization, while the event manager primarily provides a +high performance synchronization mechanism. The signal manager +supports only asynchronous communication and is typically used +for exception handling. + +@ifinfo +@node Key Concepts Time, Key Concepts Memory Management, Key Concepts Communication and Synchronization, Key Concepts +@end ifinfo +@section Time + +The development of responsive real-time applications +requires an understanding of how RTEMS maintains and supports +time-related operations. The basic unit of time in RTEMS is +known as a tick. The frequency of clock ticks is completely +application dependent and determines the granularity and +accuracy of all interval and calendar time operations. + +By tracking time in units of ticks, RTEMS is capable +of supporting interval timing functions such as task delays, +timeouts, timeslicing, the delayed execution of timer service +routines, and the rate monotonic scheduling of tasks. An +interval is defined as a number of ticks relative to the current +time. For example, when a task delays for an interval of ten +ticks, it is implied that the task will not execute until ten +clock ticks have occurred. + +A characteristic of interval timing is that the +actual interval period may be a fraction of a tick less than the +interval requested. This occurs because the time at which the +delay timer is set up occurs at some time between two clock +ticks. Therefore, the first countdown tick occurs in less than +the complete time interval for a tick. This can be a problem if +the clock granularity is large. + +The rate monotonic scheduling algorithm is a hard +real-time scheduling methodology. This methodology provides +rules which allows one to guarantee that a set of independent +periodic tasks will always meet their deadlines -- even under +transient overload conditions. The rate monotonic manager +provides directives built upon the Clock Manager's interval +timer support routines. + +Interval timing is not sufficient for the many +applications which require that time be kept in wall time or +true calendar form. Consequently, RTEMS maintains the current +date and time. This allows selected time operations to be +scheduled at an actual calendar date and time. For example, a +task could request to delay until midnight on New Year's Eve +before lowering the ball at Times Square. + +Obviously, the directives which use intervals or wall +time cannot operate without some external mechanism which +provides a periodic clock tick. This clock tick is typically +provided by a real time clock or counter/timer device. + +@ifinfo +@node Key Concepts Memory Management, Initialization Manager, Key Concepts Time, Key Concepts +@end ifinfo +@section Memory Management + +RTEMS memory management facilities can be grouped +into two classes: dynamic memory allocation and address +translation. Dynamic memory allocation is required by +applications whose memory requirements vary through the +application's course of execution. Address translation is +needed by applications which share memory with another CPU or an +intelligent Input/Output processor. The following RTEMS +managers provide facilities to manage memory: + +@itemize @bullet +@item Region + +@item Partition + +@item Dual Ported Memory +@end itemize + +RTEMS memory management features allow an application +to create simple memory pools of fixed size buffers and/or more +complex memory pools of variable size segments. The partition +manager provides directives to manage and maintain pools of +fixed size entities such as resource control blocks. +Alternatively, the region manager provides a more general +purpose memory allocation scheme that supports variable size +blocks of memory which are dynamically obtained and freed by the +application. The dual-ported memory manager provides executive +support for address translation between internal and external +dual-ported RAM address space. diff --git a/doc/user/conf.t b/doc/user/conf.t new file mode 100644 index 0000000000..126d9b584b --- /dev/null +++ b/doc/user/conf.t @@ -0,0 +1,752 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top +@end ifinfo +@chapter Configuring a System +@ifinfo +@menu +* Configuring a System Configuration Table:: +* Configuring a System RTEMS API Configuration Table:: +* Configuring a System POSIX API Configuration Table:: +* Configuring a System CPU Dependent Information Table:: +* Configuring a System Initialization Task Table:: +* Configuring a System Driver Address Table:: +* Configuring a System User Extensions Table:: +* Configuring a System Multiprocessor Configuration Table:: +* Configuring a System Multiprocessor Communications Interface Table:: +* Configuring a System Determining Memory Requirements:: +* Configuring a System Sizing the RTEMS RAM Workspace:: +@end menu +@end ifinfo + +@ifinfo +@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System +@end ifinfo +@section Configuration Table + +The RTEMS Configuration Table is used to tailor an +application for its specific needs. For example, the user can +configure the number of device drivers or which APIs may be used. +THe address of the user-defined Configuration Table is passed as an +argument to the initialize_executive directive, which MUST be +the first RTEMS directive called. The RTEMS Configuration Table +is defined in the following C structure: + +@example +@group +typedef struct @{ + void *work_space_start; + rtems_unsigned32 work_space_size; + rtems_unsigned32 maximum_extensions; + rtems_unsigned32 microseconds_per_tick; + rtems_unsigned32 ticks_per_timeslice; + rtems_unsigned32 maximum_devices; + rtems_unsigned32 number_of_device_drivers; + rtems_driver_address_table *Device_driver_table; + rtems_extensions_table *User_extension_table; + rtems_multiprocessing_table *User_multiprocessing_table; + rtems_api_configuration_table *RTEMS_api_configuration; + posix_api_configuration_table *POSIX_api_configuration; +@} rtems_configuration_table; +@end group +@end example + +@table @b +@item work_space_start +is the address of the RTEMS RAM Workspace. +This area contains items such as the +various object control blocks (TCBs, QCBs, ...) and task stacks. +If the address is not aligned on a four-word boundary, then +RTEMS will invoke the fatal error handler during +initialize_executive. + +@item work_space_size +is the calculated size of the +RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace +details how to arrive at this number. + +@item microseconds_per_tick +is number of microseconds per clock tick. + +@item ticks_per_timeslice +is the number of clock ticks for a timeslice. + +@item maximum_devices +is the maximum number of devices that can be registered. + +@item number_of_device_drivers +is the number of device drivers for the system. There should be +the same number of entries in the Device Driver Table. If this field +is zero, then the User_driver_address_table entry should be NULL. + +@item Device_driver_table +is the address of the Device Driver Table. This table contains the entry +points for each device driver. If the number_of_device_drivers field is zero, +then this entry should be NULL. The format of this table will be +discussed below. + +@item User_extension_table +is the address of the User +Extension Table. This table contains the entry points for the +static set of optional user extensions. If no user extensions +are configured, then this entry should be NULL. The format of +this table will be discussed below. + +@item User_multiprocessing_table +is the address of the Multiprocessor Configuration Table. This +table contains information needed by RTEMS only when used in a multiprocessor +configuration. This field must be NULL when RTEMS is used in a +single processor configuration. + +@item RTEMS_api_configuration +is the address of the RTEMS API Configuration Table. This table +contains information needed by the RTEMS API. This field should be +NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API +is required to support support components such as BSPs and libraries +which use this API.] + +@item POSIX_api_configuration +is the address of the POSIX API Configuration Table. This table +contains information needed by the POSIX API. This field should be +NULL if the POSIX API is not used. + +@end table + +@ifinfo +@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System +@end ifinfo +@section RTEMS API Configuration Table + +The RTEMS API Configuration Table is used to configure the +managers which constitute the RTEMS API for a particular application. +For example, the user can configure the maximum number of tasks for +this application. The RTEMS API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + rtems_unsigned32 maximum_tasks; + rtems_unsigned32 maximum_timers; + rtems_unsigned32 maximum_semaphores; + rtems_unsigned32 maximum_message_queues; + rtems_unsigned32 maximum_partitions; + rtems_unsigned32 maximum_regions; + rtems_unsigned32 maximum_ports; + rtems_unsigned32 maximum_periods; + rtems_unsigned32 number_of_initialization_tasks; + rtems_initialization_tasks_table *User_initialization_tasks_table; +@} rtems_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_tasks +is the maximum number of tasks that +can be concurrently active (created) in the system including +initialization tasks. + +@item maximum_timers +is the maximum number of timers +that can be concurrently active in the system. + +@item maximum_semaphores +is the maximum number of +semaphores that can be concurrently active in the system. + +@item maximum_message_queues +is the maximum number of +message queues that can be concurrently active in the system. + +@item maximum_partitions +is the maximum number of +partitions that can be concurrently active in the system. + +@item maximum_regions +is the maximum number of regions +that can be concurrently active in the system. + +@item maximum_ports +is the maximum number of ports into +dual-port memory areas that can be concurrently active in the +system. + +@item number_of_initialization_tasks +is the number of initialization tasks configured. At least one +initialization task must be configured. + +@item User_initialization_tasks_table +is the address of the Initialization Task Table. This table contains the +information needed to create and start each of the +initialization tasks. The format of this table will be discussed below. + +@end table + +@ifinfo +@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System +@end ifinfo +@section POSIX API Configuration Table + +The POSIX API Configuration Table is used to configure the +managers which constitute the POSIX API for a particular application. +For example, the user can configure the maximum number of threads for +this application. The POSIX API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + void *(*entry)(void *); +@} posix_initialization_threads_table; + +typedef struct @{ + int maximum_threads; + int maximum_mutexes; + int maximum_condition_variables; + int maximum_keys; + int maximum_queued_signals; + int number_of_initialization_tasks; + posix_initialization_threads_table *User_initialization_tasks_table; +@} posix_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_threads +is the maximum number of threads that +can be concurrently active (created) in the system including +initialization threads. + +@item maximum_mutexes +is the maximum number of mutexes that can be concurrently +active in the system. + +@item maximum_condition_variables +is the maximum number of condition variables that can be +concurrently active in the system. + +@item maximum_keys +is the maximum number of keys that can be concurrently active in the system. + +@item maximum_queued_signals +is the maximum number of queued signals that can be concurrently +pending in the system. + +@item number_of_initialization_threads +is the number of initialization threads configured. At least one +initialization threads must be configured. + +@item User_initialization_threads_table +is the address of the Initialization Threads Table. This table contains the +information needed to create and start each of the initialization threads. +The format of each entry in this table is defined in the +posix_initialization_threads_table structure. + +@end table + +@ifinfo +@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System +@end ifinfo +@section CPU Dependent Information Table + +The CPU Dependent Information Table is used to +describe processor dependent information required by RTEMS. +This table is generally used to supply RTEMS with information +only known by the Board Support Package. The contents of this +table are discussed in the CPU Dependent Information Table +chapter of the C Applications Supplement document for a specific +target processor. + +@ifinfo +@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System +@end ifinfo +@section Initialization Task Table + +The Initialization Task Table is used to describe +each of the user initialization tasks to the Initialization +Manager. The table contains one entry for each initialization +task the user wishes to create and start. The fields of this +data structure directly correspond to arguments to the +task_create and task_start directives. The number of entries is +found in the number_of_initialization_tasks entry in the +Configuration Table. The format of each entry in the +Initialization Task Table is defined in the following C +structure: + +@example +typedef struct @{ + rtems_name name; + rtems_unsigned32 stack_size; + rtems_task_priority initial_priority; + rtems_attribute attribute_set; + rtems_task_entry entry_point; + rtems_mode mode_set; + rtems_task_argument argument; +@} rtems_initialization_tasks_table; +@end example + +@table @b +@item name +is the name of this initialization task. + +@item stack_size +is the size of the stack for this initialization task. + +@item initial_priority +is the priority of this initialization task. + +@item attribute_set +is the attribute set used during creation of this initialization task. + +@item entry_point +is the address of the entry point of this initialization task. + +@item mode_set +is the initial execution mode of this initialization task. + +@item argument +is the initial argument for this initialization task. + +@end table + +A typical declaration for an Initialization Task Table might appear as follows: + +@example +rtems_initialization_tasks_table +Initialization_tasks[2] = @{ + @{ INIT_1_NAME, + 1024, + 1, + DEFAULT_ATTRIBUTES, + Init_1, + DEFAULT_MODES, + 1 + + @}, + @{ INIT_2_NAME, + 1024, + 250, + FLOATING_POINT, + Init_2, + INTERRUPT_LEVEL(0)|NO_PREEMPT, + 2 + + @} +@}; +@end example + +@ifinfo +@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System +@end ifinfo +@section Driver Address Table + +The Device Driver Table is used to inform the I/O +Manager of the set of entry points for each device driver +configured in the system. The table contains one entry for each +device driver required by the application. The number of +entries is defined in the number_of_device_drivers entry in the +Configuration Table. The format of each entry in the Device +Driver Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_device_driver_entry initialization; + rtems_device_driver_entry open; + rtems_device_driver_entry close; + rtems_device_driver_entry read; + rtems_device_driver_entry write; + rtems_device_driver_entry control; +@} rtems_driver_address_table; +@end example + +@table @b +@item initialization +is the address of the entry point called by io_initialize +to initialize a device driver and its associated devices. + +@item open +is the address of the entry point called by io_open. + +@item close +is the address of the entry point called by io_close. + +@item read +is the address of the entry point called by io_read. + +@item write +is the address of the entry point called by io_write. + +@item control +is the address of the entry point called by io_control. + +@end table + +Driver entry points configured as NULL will always +return a status code of SUCCESSFUL. No user code will be +executed in this situation. + +A typical declaration for a Device Driver Table might appear as follows: + +@example +rtems_driver_address_table Driver_table[2] = @{ + @{ tty_initialize, tty_open, tty_close, /* major = 0 */ + tty_read, tty_write, tty_control + @}, + @{ lp_initialize, lp_open, lp_close, /* major = 1 */ + NULL, lp_write, lp_control + @} +@}; +@end example + +More information regarding the construction and +operation of device drivers is provided in the I/O Manager +chapter. + +@ifinfo +@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System +@end ifinfo +@section User Extensions Table + +The User Extensions Table is used to inform RTEMS of +the optional user-supplied static extension set. This table +contains one entry for each possible extension. The entries are +called at critical times in the life of the system and +individual tasks. The application may create dynamic extensions +in addition to this single static set. The format of each entry +in the User Extensions Table is defined in the following C +structure: + +@example +typedef struct @{ + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_post_switch_extension thread_post_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_error_extension fatal; +@} User_extensions_Table; +@end example + +@table @b + +@item thread_create +is the address of the +user-supplied subroutine for the TASK_CREATE extension. If this +extension for task creation is defined, it is called from the +task_create directive. A value of NULL indicates that no +extension is provided. + +@item thread_start +is the address of the user-supplied +subroutine for the TASK_START extension. If this extension for +task initiation is defined, it is called from the task_start +directive. A value of NULL indicates that no extension is +provided. + +@item thread_restart +is the address of the user-supplied +subroutine for the TASK_RESTART extension. If this extension +for task re-initiation is defined, it is called from the +task_restart directive. A value of NULL indicates that no +extension is provided. + +@item thread_delete +is the address of the user-supplied +subroutine for the TASK_DELETE extension. If this RTEMS +extension for task deletion is defined, it is called from the +task_delete directive. A value of NULL indicates that no +extension is provided. + +@item thread_switch +is the address of the user-supplied +subroutine for the task context switch extension. This +subroutine is called from RTEMS dispatcher after the current +task has been swapped out but before the new task has been +swapped in. A value of NULL indicates that no extension is +provided. As this routine is invoked after saving the current +task's context and before restoring the heir task's context, it +is not necessary for this routine to save and restore any +registers. + +@item thread_post_switch +is the address of the +user-supplied subroutine for the post task context switch +extension. This subroutine is called from RTEMS dispatcher in +the context of the task which has just been swapped in. + +@item thread_begin +is the address of the user-supplied +subroutine which is invoked immediately before a task begins +execution. It is invoked in the context of the beginning task. +A value of NULL indicates that no extension is provided. + +@item thread_exitted +is the address of the user-supplied +subroutine which is invoked when a task exits. This procedure +is responsible for some action which will allow the system to +continue execution (i.e. delete or restart the task) or to +terminate with a fatal error. If this field is set to NULL, the +default RTEMS task_exitted handler will be invoked. + +@item fatal +is the address of the user-supplied +subroutine for the FATAL extension. This RTEMS extension of +fatal error handling is called from the fatal_error_occurred +directive. If the user's fatal error handler returns or if this +entry is NULL then the default RTEMS fatal error handler will be +executed. + +@end table + +A typical declaration for a User Extension Table +which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and +FATAL extension might appear as follows: + +@example +rtems_extensions_table User_extensions = @{ + task_create_extension, + NULL, + NULL, + task_delete_extension, + task_switch_extension, + NULL, + NULL, + fatal_extension +@}; +@end example + +More information regarding the user extensions is +provided in the User Extensions chapter. + +@ifinfo +@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System +@end ifinfo +@section Multiprocessor Configuration Table + +The Multiprocessor Configuration Table contains +information needed when using RTEMS in a multiprocessor +configuration. Many of the details associated with configuring +a multiprocessor system are dependent on the multiprocessor +communications layer provided by the user. The address of the +Multiprocessor Configuration Table should be placed in the +User_multiprocessing_table entry in the primary Configuration +Table. Further details regarding many of the entries in the +Multiprocessor Configuration Table will be provided in the +Multiprocessing chapter. The format of the Multiprocessor +Configuration Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 node; + rtems_unsigned32 maximum_nodes; + rtems_unsigned32 maximum_global_objects; + rtems_unsigned32 maximum_proxies; + rtems_mpci_table *User_mpci_table; +@} rtems_multiprocessing_table; +@end example + +@table @b +@item node +is a unique processor identifier +and is used in routing messages between nodes in a +multiprocessor configuration. Each processor must have a unique +node number. RTEMS assumes that node numbers start at one and +increase sequentially. This assumption can be used to advantage +by the user-supplied MPCI layer. Typically, this requirement is +made when the node numbers are used to calculate the address of +inter-processor communication links. Zero should be avoided as +a node number because some MPCI layers use node zero to +represent broadcasted packets. Thus, it is recommended that +node numbers start at one and increase sequentially. + +@item maximum_nodes +is the number of processor nodes in the system. + +@item maximum_global_objects +is the maximum number of global objects which can exist at any +given moment in the entire system. If this parameter is not the +same on all nodes in the system, then a fatal error is generated +to inform the user that the system is inconsistent. + +@item maximum_proxies +is the maximum number of proxies which can exist at any given moment +on this particular node. A proxy is a substitute task control block +which represent a task residing on a remote node when that task blocks +on a remote object. Proxies are used in situations in which delayed +interaction is required with a remote node. + +@item User_mpci_table +is the address of the Multiprocessor Communications Interface +Table. This table contains the entry points of user-provided functions +which constitute the multiprocessor communications layer. This table +must be provided in multiprocessor configurations with all +entries configured. The format of this table and details +regarding its entries can be found in the next section. + +@end table + +@ifinfo +@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System +@end ifinfo +@section Multiprocessor Communications Interface Table + +The format of this table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 default_timeout; /* in ticks */ + rtems_unsigned32 maximum_packet_size; + rtems_mpci_initialization_entry initialization; + rtems_mpci_get_packet_entry get_packet; + rtems_mpci_return_packet_entry return_packet; + rtems_mpci_send_entry send; + rtems_mpci_receive_entry receive; +@} rtems_mpci_table; +@end example + +@table @b +@item default_timeout +is the default maximum length of time a task should block waiting for +a response to a directive which results in communication with a remote node. +The maximum length of time is a function the user supplied +multiprocessor communications layer and the media used. This +timeout only applies to directives which would not block if the +operation were performed locally. + +@item maximum_packet_size +is the size in bytes of the longest packet which the MPCI layer is capable +of sending. This value should represent the total number of bytes available +for a RTEMS interprocessor messages. + +@item initialization +is the address of the entry point for the initialization procedure of the +user supplied multiprocessor communications layer. + +@item get_packet +is the address of the entry point for the procedure called by RTEMS to +obtain a packet from the user supplied multiprocessor communications layer. + +@item return_packet +is the address of the entry point for the procedure called by RTEMS to +return a packet to the user supplied multiprocessor communications layer. + +@item send +is the address of the entry point for the procedure called by RTEMS to +send an envelope to another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@item receive +is the address of the entry point for the +procedure called by RTEMS to retrieve an envelope containing a +message from another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@end table + +More information regarding the required functionality of these +entry points is provided in the Multiprocessor chapter. + +@ifinfo +@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System +@end ifinfo +@section Determining Memory Requirements + +Since memory is a critical resource in many real-time +embedded systems, RTEMS was specifically designed to allow +unused managers to be excluded from the run-time environment. +This allows the application designer the flexibility to tailor +RTEMS to most efficiently meet system requirements while still +satisfying even the most stringent memory constraints. As +result, the size of the RTEMS executive is application +dependent. A Memory Requirements worksheet is provided in the C +Applications Supplement document for a specific target +processor. This worksheet can be used to calculate the memory +requirements of a custom RTEMS run-time environment. To insure +that enough memory is allocated for future versions of RTEMS, +the application designer should round these memory requirements +up. The following managers may be optionally excluded: + +@itemize @bullet +@item signal +@item region +@item dual ported memory +@item event +@item multiprocessing +@item partition +@item timer +@item semaphore +@item message +@item rate monotonic +@end itemize + +RTEMS based applications must somehow provide memory +for RTEMS' code and data space. Although RTEMS' data space must +be in RAM, its code space can be located in either ROM or RAM. +In addition, the user must allocate RAM for the RTEMS RAM +Workspace. The size of this area is application dependent and +can be calculated using the formula provided in the Memory +Requirements chapter of the C Applications Supplement document +for a specific target processor. + +All RTEMS data variables and routine names used by +RTEMS begin with the underscore ( _ ) character followed by an +upper-case letter. If RTEMS is linked with an application, then +the application code should NOT contain any symbols which begin +with the underscore character and followed by an upper-case +letter to avoid any naming conflicts. All RTEMS directive names +should be treated as reserved words. + +@ifinfo +@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System +@end ifinfo +@section Sizing the RTEMS RAM Workspace + +The RTEMS RAM Workspace is a user-specified block of +memory reserved for use by RTEMS. The application should NOT +modify this memory. This area consists primarily of the RTEMS +data structures whose exact size depends upon the values +specified in the Configuration Table. In addition, task stacks +and floating point context areas are dynamically allocated from +the RTEMS RAM Workspace. + +The starting address of the RTEMS RAM Workspace must +be aligned on a four-byte boundary. Failure to properly align +the workspace area will result in the fatal_error_occurred +directive being invoked with the INVALID_ADDRESS error code. + +A worksheet is provided in the Memory Requirements +chapter of the C Applications Supplement document for a specific +target processor to assist the user in calculating the minimum +size of the RTEMS RAM Workspace for each application. The value +calculated with this worksheet is the minimum value that should +be specified as the work_space_size parameter of the +Configuration Table. The user is cautioned that future versions +of RTEMS may not have the same memory requirements per object. +Although the value calculated is sufficient for a particular +target processor and release of RTEMS, memory usage is subject +to change across versions and target processors. The user is +advised to allocate somewhat more memory than the worksheet +recommends to insure compatibility with future releases for a +specific target processor and other target processors. To avoid +problems, the user should recalculate the memory requirements +each time one of the following events occurs: + +@itemize @bullet +@item a configuration parameter is modified, +@item task or interrupt stack requirements change, +@item task floating point attribute is altered, +@item RTEMS is upgraded, or +@item the target processor is changed. +@end itemize + +Failure to provide enough space in the RTEMS RAM +Workspace will result in the fatal_error_occurred directive +being invoked with the appropriate error code. diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi new file mode 100644 index 0000000000..b703ec5043 --- /dev/null +++ b/doc/user/dirstat.texi @@ -0,0 +1,40 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Directive Status Codes, Example Application, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Top +@end ifinfo +@chapter Directive Status Codes +@table @b +@item @b{SUCCESSFUL} - successful completion +@item @b{TASK_EXITTED} - returned from a task +@item @b{MP_NOT_CONFIGURED} - multiprocessing not configured +@item @b{INVALID_NAME} - invalid object name +@item @b{INVALID_ID} - invalid object id +@item @b{TOO_MANY} - too many +@item @b{TIMEOUT} - timed out waiting +@item @b{OBJECT_WAS_DELETED} - object was deleted while waiting +@item @b{INVALID_SIZE} - invalid specified size +@item @b{INVALID_ADDRESS} - invalid address specified +@item @b{INVALID_NUMBER} - number was invalid +@item @b{NOT_DEFINED} - item not initialized +@item @b{RESOURCE_IN_USE} - resources outstanding +@item @b{UNSATISFIED} - request not satisfied +@item @b{INCORRECT_STATE} - task is in wrong state +@item @b{ALREADY_SUSPENDED} - task already in state +@item @b{ILLEGAL_ON_SELF} - illegal for calling task +@item @b{ILLEGAL_ON_REMOTE_OBJECT} - illegal for remote object +@item @b{CALLED_FROM_ISR} - invalid environment +@item @b{INVALID_PRIORITY} - invalid task priority +@item @b{INVALID_CLOCK} - invalid time buffer +@item @b{INVALID_NODE} - invalid node id +@item @b{NOT_CONFIGURED} - directive not configured +@item @b{NOT_OWNER_OF_RESOURCE} - not owner of resource +@item @b{NOT_IMPLEMENTED} - directive not implemented +@item @b{INTERNAL_ERROR} - RTEMS inconsistency detected +@item @b{NO_MEMORY} - could not get enough memory +@end table + diff --git a/doc/user/dpmem.t b/doc/user/dpmem.t new file mode 100644 index 0000000000..9432323b02 --- /dev/null +++ b/doc/user/dpmem.t @@ -0,0 +1,324 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Dual-Ported Memory Manager, Dual-Ported Memory Manager Introduction, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Top +@end ifinfo +@chapter Dual-Ported Memory Manager +@ifinfo +@menu +* Dual-Ported Memory Manager Introduction:: +* Dual-Ported Memory Manager Background:: +* Dual-Ported Memory Manager Operations:: +* Dual-Ported Memory Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager, Dual-Ported Memory Manager +@end ifinfo +@section Introduction + +The dual-ported memory manager provides a mechanism +for converting addresses between internal and external +representations for multiple dual-ported memory areas (DPMA). +The directives provided by the dual-ported memory manager are: + +@itemize @bullet +@item @code{port_create} - Create a port +@item @code{port_ident} - Get ID of a port +@item @code{port_delete} - Delete a port +@item @code{port_external_to_internal} - Convert external to internal address +@item @code{port_internal_to_external} - Convert internal to external address +@end itemize + +@ifinfo +@node Dual-Ported Memory Manager Background, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager +@end ifinfo +@section Background + +A dual-ported memory area (DPMA) is an contiguous +block of RAM owned by a particular processor but which can be +accessed by other processors in the system. The owner accesses +the memory using internal addresses, while other processors must +use external addresses. RTEMS defines a port as a particular +mapping of internal and external addresses. + +There are two system configurations in which +dual-ported memory is commonly found. The first is +tightly-coupled multiprocessor computer systems where the +dual-ported memory is shared between all nodes and is used for +inter-node communication. The second configuration is computer +systems with intelligent peripheral controllers. These +controllers typically utilize the DPMA for high-performance data +transfers. + +@ifinfo +@node Dual-Ported Memory Manager Operations, Creating a Port, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Port:: +* Obtaining Port IDs:: +* Converting an Address:: +* Deleting a DPMA Port:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Creating a Port + +The port_create directive creates a port into a DPMA +with the user-defined name. The user specifies the association +between internal and external representations for the port being +created. RTEMS allocates a Dual-Ported Memory Control Block +(DPCB) from the DPCB free list to maintain the newly created +DPMA. RTEMS also generates a unique dual-ported memory port ID +which is returned to the calling task. RTEMS does not +initialize the dual-ported memory area or access any memory +within it. + +@ifinfo +@node Obtaining Port IDs, Converting an Address, Creating a Port, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Obtaining Port IDs + +When a port is created, RTEMS generates a unique port +ID and assigns it to the created port until it is deleted. The +port ID may be obtained by either of two methods. First, as the +result of an invocation of the port_create directive, the task +ID is stored in a user provided location. Second, the port ID +may be obtained later using the port_ident directive. The port +ID is used by other dual-ported memory manager directives to +access this port. + +@ifinfo +@node Converting an Address, Deleting a DPMA Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Converting an Address + +The port_external_to_internal directive is used to +convert an address from external to internal representation for +the specified port. The port_internal_to_external directive is +used to convert an address from internal to external +representation for the specified port. If an attempt is made to +convert an address which lies outside the specified DPMA, then +the address to be converted will be returned. + +@ifinfo +@node Deleting a DPMA Port, Dual-Ported Memory Manager Directives, Converting an Address, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Deleting a DPMA Port + +A port can be removed from the system and returned to +RTEMS with the port_delete directive. When a port is deleted, +its control block is returned to the DPCB free list. + +@ifinfo +@node Dual-Ported Memory Manager Directives, PORT_CREATE - Create a port, Deleting a DPMA Port, Dual-Ported Memory Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* PORT_CREATE - Create a port:: +* PORT_IDENT - Get ID of a port:: +* PORT_DELETE - Delete a port:: +* PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address:: +* PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address:: +@end menu +@end ifinfo + +This section details the dual-ported memory 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 PORT_CREATE - Create a port, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_CREATE - Create a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + rtems_unsigned32 length, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{TOO_MANY} - too many DP memory areas created + +@subheading DESCRIPTION: + +This directive creates a port which resides on the +local node for the specified DPMA. The assigned port id is +returned in id. This port id is used as an argument to other +dual-ported memory manager directives to convert addresses +within this DPMA. + +For control and maintenance of the port, RTEMS +allocates and initializes an DPCB from the DPCB free pool. Thus +memory from the dual-ported memory area is not used to store the +DPCB. + +@subheading NOTES: + +The internal_address and external_address parameters +must be on a four byte boundary. + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node PORT_IDENT - Get ID of a port, PORT_DELETE - Delete a port, PORT_CREATE - Create a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_IDENT - Get ID of a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port identified successfully@* +@code{INVALID_NAME} - port name not found + +@subheading DESCRIPTION: + +This directive obtains the port id associated with +the specified name to be acquired. If the port name is not +unique, then the port id will match one of the DPMAs with that +name. However, this port id is not guaranteed to correspond to +the desired DPMA. The port id is used to access this DPMA in +other dual-ported memory area related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node PORT_DELETE - Delete a port, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_DELETE - Delete a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port deleted successfully@* +@code{INVALID_ID} - invalid port id + +@subheading DESCRIPTION: + +This directive deletes the dual-ported memory area +specified by id. The DPCB for the deleted dual-ported memory +area is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The calling task does not have to be the task that +created the port. Any local task that knows the port id can +delete the port. + +@page +@ifinfo +@node PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, PORT_DELETE - Delete a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive converts a dual-ported memory address +from external to internal representation for the specified port. +If the given external address is invalid for the specified +port, then the internal address is set to the given external +address. + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, I/O Manager, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive converts a dual-ported memory address +from internal to external representation so that it can be +passed to owner of the DPMA represented by the specified port. +If the given internal address is an invalid dual-ported address, +then the external address is set to the given internal address. + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the calling task to be +preempted. + + + + + diff --git a/doc/user/event.t b/doc/user/event.t new file mode 100644 index 0000000000..0ec198a5c0 --- /dev/null +++ b/doc/user/event.t @@ -0,0 +1,351 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Event Manager, Event Manager Introduction, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Top +@end ifinfo +@chapter Event Manager +@ifinfo +@menu +* Event Manager Introduction:: +* Event Manager Background:: +* Event Manager Operations:: +* Event Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Event Manager Introduction, Event Manager Background, Event Manager, Event Manager +@end ifinfo +@section Introduction + +The event manager provides a high performance method +of intertask communication and synchronization. The directives +provided by the event manager are: + +@itemize @bullet +@item @code{event_send} - Send event set to a task +@item @code{event_receive} - Receive event condition +@end itemize + +@ifinfo +@node Event Manager Background, Event Sets, Event Manager Introduction, Event Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Event Sets:: +* Building an Event Set or Condition:: +* Building an EVENT_RECEIVE Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Event Sets, Building an Event Set or Condition, Event Manager Background, Event Manager Background +@end ifinfo +@subsection Event Sets + +An event flag is used by a task (or ISR) to inform +another task of the occurrence of a significant situation. +Thirty-two event flags are associated with each task. A +collection of one or more event flags is referred to as an event +set. The application developer should remember the following +key characteristics of event operations when utilizing the event +manager: + +@itemize @bullet +@item Events provide a simple synchronization facility. + +@item Events are aimed at tasks. + +@item Tasks can wait on more than one event simultaneously. + +@item Events are independent of one another. + +@item Events do not hold or transport data. + +@item Events are not queued. In other words, if an event is +sent more than once before being received, the second and +subsequent send operations have no effect. +@end itemize + +An event set is posted when it is directed (or sent) +to a task. A pending event is an event that has been posted but +not received. An event condition is used to specify the events +which the task desires to receive and the algorithm which will +be used to determine when the request is satisfied. An event +condition is satisfied based upon one of two algorithms which +are selected by the user. The EVENT_ANY algorithm states that +an event condition is satisfied when at least a single requested +event is posted. The EVENT_ALL algorithm states that an event +condition is satisfied when every requested event is posted. + +@ifinfo +@node Building an Event Set or Condition, Building an EVENT_RECEIVE Option Set, Event Sets, Event Manager Background +@end ifinfo +@subsection Building an Event Set or Condition + +An event set or condition is built by a bitwise OR of +the desired events. The set of valid events is EVENT_0 through +EVENT_31. If an event is not explicitly specified in the set or +condition, then it is not present. Events are specifically +designed to be mutually exclusive, therefore bitwise OR and +addition operations are equivalent as long as each event appears +exactly once in the event set list. + +For example, when sending the event set consisting of +EVENT_6, EVENT_15, and EVENT_31, the event parameter to the +event_send directive should be EVENT_6 | EVENT_15 | EVENT_31. + +@ifinfo +@node Building an EVENT_RECEIVE Option Set, Event Manager Operations, Building an Event Set or Condition, Event Manager Background +@end ifinfo +@subsection Building an EVENT_RECEIVE Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +event_receive directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for event (default) +@item NO_WAIT - task should not wait +@item EVENT_ALL - return after all events (default) +@item EVENT_ANY - return after any events +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each option appears exactly once in +the component list. An option listed as a default is not +required to appear in the option list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for all events in a particular event condition to +arrive. The option parameter passed to the event_receive +directive should be either EVENT_ALL | NO_WAIT or NO_WAIT. The +option parameter can be set to NO_WAIT because EVENT_ALL is the +default condition for event_receive. + +@ifinfo +@node Event Manager Operations, Sending an Event Set, Building an EVENT_RECEIVE Option Set, Event Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Sending an Event Set:: +* Receiving an Event Set:: +* Determining the Pending Event Set:: +* Receiving all Pending Events:: +@end menu +@end ifinfo + +@ifinfo +@node Sending an Event Set, Receiving an Event Set, Event Manager Operations, Event Manager Operations +@end ifinfo +@subsection Sending an Event Set + +The event_send directive allows a task (or an ISR) to +direct an event set to a target task. Based upon the state of +the target task, one of the following situations applies: + +@itemize @bullet +@item Target Task is Blocked Waiting for Events + +@itemize - + +@item If the waiting task's input event condition is +satisfied, then the task is made ready for execution. + +@item If the waiting task's input event condition is not +satisfied, then the event set is posted but left pending and the +task remains blocked. + +@end itemize + +@item Target Task is Not Waiting for Events + +@itemize - +@item The event set is posted and left pending. +@end itemize + +@end itemize + +@ifinfo +@node Receiving an Event Set, Determining the Pending Event Set, Sending an Event Set, Event Manager Operations +@end ifinfo +@subsection Receiving an Event Set + +The event_receive directive is used by tasks to +accept a specific input event condition. The task also +specifies whether the request is satisfied when all requested +events are available or any single requested event is available. +If the requested event condition is satisfied by pending +events, then a successful return code and the satisfying event +set are returned immediately. If the condition is not +satisfied, then one of the following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever for the +event condition to be satisfied. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the period the task will +wait before returning with an error status code. +@end itemize + +@ifinfo +@node Determining the Pending Event Set, Receiving all Pending Events, Receiving an Event Set, Event Manager Operations +@end ifinfo +@subsection Determining the Pending Event Set + +A task can determine the pending event set by calling +the event_receive directive with a value of PENDING_EVENTS for +the input event condition. The pending events are returned to +the calling task but the event set is left unaltered. + +@ifinfo +@node Receiving all Pending Events, Event Manager Directives, Determining the Pending Event Set, Event Manager Operations +@end ifinfo +@subsection Receiving all Pending Events + +A task can receive all of the currently pending +events by calling the event_receive directive with a value of +ALL_EVENTS for the input event condition and NO_WAIT | EVENT_ANY +for the option set. The pending events are returned to the +calling task and the event set is cleared. If no events are +pending then the UNSATISFIED status code will be returned. + +@ifinfo +@node Event Manager Directives, EVENT_SEND - Send event set to a task, Receiving all Pending Events, Event Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* EVENT_SEND - Send event set to a task:: +* EVENT_RECEIVE - Receive event condition:: +@end menu +@end ifinfo + +This section details the event 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 EVENT_SEND - Send event set to a task, EVENT_RECEIVE - Receive event condition, Event Manager Directives, Event Manager Directives +@end ifinfo +@subsection EVENT_SEND - Send event set to a task + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_event_send ( + rtems_id id, + rtems_event_set event_in +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - event set sent successfully@* +@code{INVALID_ID} - invalid task id + +@subheading DESCRIPTION: + +This directive sends an event set, event_in, to the +task specified by id. If a blocked task's input event condition +is satisfied by this directive, then it will be made ready. If +its input event condition is not satisfied, then the events +satisfied are updated and the events not satisfied are left +pending. If the task specified by id is not blocked waiting for +events, then the events sent are left pending. + +@subheading NOTES: + +Specifying SELF for id results in the event set being +sent to the calling task. + +Identical events sent to a task are not queued. In +other words, the second, and subsequent, posting of an event to +a task before it can perform an event_receive has no effect. + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending an event set to a global task which does not +reside on the local node will generate a request telling the +remote node to send the event set to the appropriate task. + +@page +@ifinfo +@node EVENT_RECEIVE - Receive event condition, Signal Manager, EVENT_SEND - Send event set to a task, Event Manager Directives +@end ifinfo +@subsection EVENT_RECEIVE - Receive event condition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_event_receive ( + rtems_event_set event_in, + rtems_option option_set, + rtems_interval ticks, + rtems_event_set *event_out +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - event received successfully@* +@code{UNSATISFIED} - input event not satisfied (NO_WAIT)@* +@code{TIMEOUT} - timed out waiting for event + +@subheading DESCRIPTION: + +This directive attempts to receive the event +condition specified in event_in. If event_in is set to +PENDING_EVENTS, then the current pending events are returned in +event_out and left pending. The WAIT and NO_WAIT options in the +option_set parameter are used to specify whether or not the task +is willing to wait for the event condition to be satisfied. +EVENT_ANY and EVENT_ALL are used in the option_set parameter are +used to specify whether a single event or the complete event set +is necessary to satisfy the event condition. The event_out +parameter is returned to the calling task with the value that +corresponds to the events in event_in that were satisfied. + +If pending events satisfy the event condition, then +event_out is set to the satisfied events and the pending events +in the event condition are cleared. If the event condition is +not satisfied and NO_WAIT is specified, then event_out is set to +the currently satisfied events. If the calling task chooses to +wait, then it will block waiting for the event condition. + +If the calling task must wait for the event condition +to be satisfied, then the timeout parameter is used to specify +the maximum interval to wait. If it is set to NO_TIMEOUT, then +the calling task will wait forever. + +@subheading NOTES: + +This directive only affects the events specified in +event_in. Any pending events that do not correspond to any of +the events specified in event_in will be left pending. + +The following event receive option constants are defined by +RTEMS: + +@itemize @bullet +@item WAIT task will wait for event (default) +@item NO_WAIT task should not wait +@item EVENT_ALL return after all events (default) +@item EVENT_ANY return after any events +@end itemize + diff --git a/doc/user/example.texi b/doc/user/example.texi new file mode 100644 index 0000000000..545cf8e8f4 --- /dev/null +++ b/doc/user/example.texi @@ -0,0 +1,103 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Example Application, Glossary, Directive Status Codes, Top +@end ifinfo +@chapter Example Application + +@example +/* example.c + * + * This file contains an example of a simple RTEMS + * application. It contains a Configuration Table, a + * user initialization task, and a simple task. + * + * This example assumes that a board support package exists + * and invokes the initialize_executive() directive. + */ + +#include "rtems.h" + +rtems_task init_task(); + +#define INIT_NAME build_name( 'A', 'B', 'C', ' ' ' ) + +rtems_initialization_tasks_table init_task = @{ + @{ INIT_NAME, /* init task name "ABC" */ + 1024, /* init task stack size */ + 1, /* init task priority */ + DEFAULT_ATTRIBUTES, /* init task attributes */ + init_task, /* init task entry point */ + TIMESLICE, /* init task initial mode */ + 0 /* init task argument */ + @} +@}; + +rtems_configuration_table User_Configuration_Table = @{ + NULL, /* filled in by the BSP */ + 65536, /* executive RAM size */ + 2, /* maximum tasks */ + 0, /* maximum timers */ + 0, /* maximum semaphores */ + 0, /* maximum message queues */ + 0, /* maximum messages */ + 0, /* maximum partitions */ + 0, /* maximum regions */ + 0, /* maximum ports */ + 0, /* maximum periods */ + 0, /* maximum extensions */ + RTEMS_MILLISECONDS_TO_MICROSECONDS(10), /* number of ms in a tick */ + 1, /* num of ticks in a timeslice */ + 1, /* number of user init tasks */ + init_task_tbl, /* user init task(s) table */ + 0, /* number of device drivers */ + NULL, /* ptr to driver address table */ + NULL, /* ptr to extension table */ + NULL /* ptr to MP config table */ +@}; + +task user_application( + rtems_task_argument ignored +); + +#define USER_APP_NAME 1 /* any 32-bit name; unique helps */ + +rtems_task init_task( + rtems_task_argument ignored +) +@{ + rtems_id tid; + + /* example assumes SUCCESSFUL return value */ + + (void) rtems_task_create( USER_APP_NAME, 1, 1024, + RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid ); + (void) rtems_task_start( tid, user_application, 0 ); + (void) rtems_task_delete( SELF ); +@} + + + +rtems_task user_application() + +@{ + /* application specific initialization goes here */ + + while ( 1 ) @{ /* infinite loop */ + + /* APPLICATION CODE GOES HERE + * + * This code will typically include at least one + * directive which causes the calling task to + * give up the processor. + */ + @} +@} +@end example + + + diff --git a/doc/user/fatal.t b/doc/user/fatal.t new file mode 100644 index 0000000000..4f15684195 --- /dev/null +++ b/doc/user/fatal.t @@ -0,0 +1,180 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Fatal Error Manager, Fatal Error Manager Introduction, IO_CONTROL - Special device services, Top +@end ifinfo +@chapter Fatal Error Manager +@ifinfo +@menu +* Fatal Error Manager Introduction:: +* Fatal Error Manager Background:: +* Fatal Error Manager Operations:: +* Fatal Error Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Fatal Error Manager Introduction, Fatal Error Manager Background, Fatal Error Manager, Fatal Error Manager +@end ifinfo +@section Introduction + +The fatal error manager processes all fatal or +irrecoverable errors. The directive provided by the fatal error +manager is: + +@itemize @bullet +@item @code{fatal_error_occurred} - Invoke the fatal error handler +@end itemize + + + +@ifinfo +@node Fatal Error Manager Background, Fatal Error Manager Operations, Fatal Error Manager Introduction, Fatal Error Manager +@end ifinfo +@section Background + +The fatal error manager is called upon detection of +an irrecoverable error condition by either RTEMS or the +application software. Fatal errors can be detected from three +sources: + +@itemize @bullet +@item the executive (RTEMS) +@item user system code +@item user application code +@end itemize + +RTEMS automatically invokes the fatal error manager +upon detection of an error it considers to be fatal. Similarly, +the user should invoke the fatal error manager upon detection of +a fatal error. + +Each status or dynamic user extension set may include +a fatal error handler. The fatal error handler in the static +extension set can be used to provide access to debuggers and +monitors which may be present on the target hardware. If any +user-supplied fatal error handlers are installed, the fatal +error manager will invoke them. If no user handlers are +configured or if all the user handler return control to the +fatal error manager, then the RTEMS default fatal error handler +is invoked. If the default fatal error handler is invoked, then +the system state is marked as failed. + +Although the precise behavior of the default fatal +error handler is processor specific, in general, it will disable +all maskable interrupts, place the error code in a known +processor dependent place (generally either on the stack or in a +register), and halt the processor. The precise actions of the +RTEMS fatal error are discussed in the Default Fatal Error +Processing chapter of the C Applications Supplement document for +a specific target processor. + +@ifinfo +@node Fatal Error Manager Operations, Announcing a Fatal Error, Fatal Error Manager Background, Fatal Error Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Fatal Error:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Fatal Error, Fatal Error Manager Directives, Fatal Error Manager Operations, Fatal Error Manager Operations +@end ifinfo +@subsection Announcing a Fatal Error + +The fatal_error_occurred directive is invoked when a +fatal error is detected. Before invoking any user-supplied +fatal error handlers or the RTEMS fatal error handler, the +fatal_error_occurred directive stores useful information in the +variable _Internal_errors_What_happened. This structure +contains three pieces of information: + +@itemize @bullet +@item the source of the error (API or executive core), + +@item whether the error was generated internally by the +executive, and a + +@item a numeric code to indicate the error type. +@end itemize + +The error type indicator is dependent on the source +of the error and whether or not the error was internally +generated by the executive. + +The fatal_error_directive directive is responsible +for invoking an optional user-supplied fatal error handler +and/or the RTEMS fatal error handler. All fatal error handlers +are passed an error code to describe the error detected. + +Occasionally, an application requires more +sophisticated fatal error processing such as passing control to +a debugger. For these cases, a user-supplied fatal error +handler can be specified in the RTEMS configuration table. The +User Extension Table field fatal contains the address of the +fatal error handler to be executed when the fatal_error_occurred +directive is called. If the field is set to NULL or if the +configured fatal error handler returns to the executive, then +the default handler provided by RTEMS is executed. This default +handler will halt execution on the processor where the error +occurred. + +@ifinfo +@node Fatal Error Manager Directives, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Announcing a Fatal Error, Fatal Error Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* FATAL_ERROR_OCCURRED - Invoke the fatal error handler:: +@end menu +@end ifinfo + +This section details the fatal error 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 FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Scheduling Concepts, Fatal Error Manager Directives, Fatal Error Manager Directives +@end ifinfo +@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler + +@subheading CALLING SEQUENCE: + +@example +void volatile rtems_fatal_error_occurred( + rtems_unsigned32 the_error +); +@end example + +@subheading DIRECTIVE STATUS CODES + +NONE + +@subheading DESCRIPTION: + +This directive processes fatal errors. If the FATAL +error extension is defined in the configuration table, then the +user-defined error extension is called. If configured and the +provided FATAL error extension returns, then the RTEMS default +error handler is invoked. This directive can be invoked by +RTEMS or by the user's application code including initialization +tasks, other tasks, and ISRs. + +@subheading NOTES: + +This directive supports local operations only. + +Unless the user-defined error extension takes special +actions such as restarting the calling task, this directive WILL +NOT RETURN to the caller. + +The user-defined extension for this directive may +wish to initiate a global shutdown. diff --git a/doc/user/glossary.texi b/doc/user/glossary.texi new file mode 100644 index 0000000000..58b57061f0 --- /dev/null +++ b/doc/user/glossary.texi @@ -0,0 +1,772 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Glossary, Command and Variable Index, Example Application, Top +@end ifinfo +@chapter Glossary + +@table @b +@item active +A term used to describe an object +which has been created by an application. + +@item aperiodic task +A task which must execute only at +irregular intervals and has only a soft deadline. + +@item application +In this document, software which makes +use of RTEMS. + +@item ASR +see Asynchronous Signal Routine. + +@item asynchronous +Not related in order or timing to +other occurrences in the system. + +@item Asynchronous Signal Routine +Similar to a hardware +interrupt except that it is associated with a task and is run in +the context of a task. The directives provided by the signal +manager are used to service signals. + +@item awakened +A term used to describe a task that has +been unblocked and may be scheduled to the CPU. + +@item big endian +A data representation scheme in which +the bytes composing a numeric value are arranged such that the +most significant byte is at the lowest address. + +@item bit-mapped +A data encoding scheme in which each bit +in a variable is used to represent something different. This +makes for compact data representation. + +@item block +A physically contiguous area of memory. + +@item blocked +The task state entered by a task which has +been previously started and cannot continue execution until the +reason for waiting has been satisfied. + +@item broadcast +To simultaneously send a message to a +logical set of destinations. + +@item BSP +see Board Support Package. + +@item Board Support Package +A collection of device +initialization and control routines specific to a particular +type of board or collection of boards. + +@item buffer +A fixed length block of memory allocated +from a partition. + +@item calling convention +The processor and compiler +dependent rules which define the mechanism used to invoke +subroutines in a high-level language. These rules define the +passing of arguments, the call and return mechanism, and the +register set which must be preserved. + +@item Central Processing Unit +This term is equivalent to +the terms processor and microprocessor. + +@item chain +A data structure which allows for efficient +dynamic addition and removal of elements. It differs from an +array in that it is not limited to a predefined size. + +@item coalesce +The process of merging adjacent holes into +a single larger hole. Sometimes this process is referred to as +garbage collection. + +@item Configuration Table +A table which contains +information used to tailor RTEMS for a particular application. + +@item context +All of the processor registers and +operating system data structures associated with a task. + +@item context switch +Alternate term for task switch. +Taking control of the processor from one task and transferring +it to another task. + +@item control block +A data structure used by the +executive to define and control an object. + +@item core +When used in this manual, this term refers to +the internal executive utility functions. In the interest of +application portability, the core of the executive should not be +used directly by applications. + +@item CPU +An acronym for Central Processing Unit. + +@item critical section +A section of code which must be +executed indivisibly. + +@item CRT +An acronym for Cathode Ray Tube. Normally used +in reference to the man-machine interface. + +@item deadline +A fixed time limit by which a task must +have completed a set of actions. Beyond this point, the results +are of reduced value and may even be considered useless or +harmful. + +@item device +A peripheral used by the application that +requires special operation software. See also device driver. + +@item device driver +Control software for special +peripheral devices used by the application. + +@item directives +RTEMS' provided routines that provide +support mechanisms for real-time applications. + +@item dispatch +The act of loading a task's context onto +the CPU and transferring control of the CPU to that task. + +@item dormant +The state entered by a task after it is +created and before it has been started. + +@item Device Driver Table +A table which contains the +entry points for each of the configured device drivers. + +@item dual-ported +A term used to describe memory which +can be accessed at two different addresses. + +@item embedded +An application that is delivered as a +hidden part of a larger system. For example, the software in a +fuel-injection control system is an embedded application found +in many late-model automobiles. + +@item envelope +A buffer provided by the MPCI layer to +RTEMS which is used to pass messages between nodes in a +multiprocessor system. It typically contains routing +information needed by the MPCI. The contents of an envelope are +referred to as a packet. + +@item entry point +The address at which a function or task +begins to execute. In C, the entry point of a function is the +function's name. + +@item events +A method for task communication and +synchronization. The directives provided by the event manager +are used to service events. + +@item exception +A synonym for interrupt. + +@item executing +The task state entered by a task after it +has been given control of the CPU. + +@item executive +In this document, this term is used to +referred to RTEMS. Commonly, an executive is a small real-time +operating system used in embedded systems. + +@item exported +An object known by all nodes in a +multiprocessor system. An object created with the GLOBAL +attribute will be exported. + +@item external address +The address used to access +dual-ported memory by all the nodes in a system which do not own +the memory. + +@item FIFO +An acronym for First In First Out. + +@item First In First Out +A discipline for manipulating +entries in a data structure. + +@item floating point coprocessor +A component used in +computer systems to enhance performance in mathematically +intensive situations. It is typically viewed as a logical +extension of the primary processor. + +@item freed +A resource that has been released by the +application to RTEMS. + +@item global +An object that has been created with the +GLOBAL attribute and exported to all nodes in a multiprocessor +system. + +@item handler +The equivalent of a manager, except that it +is internal to RTEMS and forms part of the core. A handler is a +collection of routines which provide a related set of functions. +For example, there is a handler used by RTEMS to manage all +objects. + +@item hard real-time system +A real-time system in which a +missed deadline causes the worked performed to have no value or +to result in a catastrophic effect on the integrity of the +system. + +@item heap +A data structure used to dynamically allocate +and deallocate variable sized blocks of memory. + +@item heterogeneous +A multiprocessor computer system +composed of dissimilar processors. + +@item homogeneous +A multiprocessor computer system +composed of a single type of processor. + +@item ID +An RTEMS assigned identification tag used to +access an active object. + +@item IDLE task +A special low priority task which assumes +control of the CPU when no other task is able to execute. + +@item interface +A specification of the methodology used +to connect multiple independent subsystems. + +@item internal address +The address used to access +dual-ported memory by the node which owns the memory. + +@item interrupt +A hardware facility that causes the CPU +to suspend execution, save its status, and transfer control to a +specific location. + +@item interrupt level +A mask used to by the CPU to +determine which pending interrupts should be serviced. If a +pending interrupt is below the current interrupt level, then the +CPU does not recognize that interrupt. + +@item Interrupt Service Routine +An ISR is invoked by the +CPU to process a pending interrupt. + +@item I/O +An acronym for Input/Output. + +@item ISR +An acronym for Interrupt Service Routine. + +@item kernel +In this document, this term is used as a +synonym for executive. + +@item list +A data structure which allows for dynamic +addition and removal of entries. It is not statically limited +to a particular size. + +@item little endian +A data representation scheme in which +the bytes composing a numeric value are arranged such that the +least significant byte is at the lowest address. + +@item local +An object which was created with the LOCAL +attribute and is accessible only on the node it was created and +resides upon. In a single processor configuration, all objects +are local. + +@item local operation +The manipulation of an object which +resides on the same node as the calling task. + +@item logical address +An address used by an application. +In a system without memory management, logical addresses will +equal physical addresses. + +@item loosely-coupled +A multiprocessor configuration +where shared memory is not used for communication. + +@item major number +The index of a device driver in the +Device Driver Table. + +@item manager +A group of related RTEMS' directives which +provide access and control over resources. + +@item memory pool +Used interchangeably with heap. + +@item message +A sixteen byte entity used to communicate +between tasks. Messages are sent to message queues and stored +in message buffers. + +@item message buffer +A block of memory used to store +messages. + +@item message queue +An RTEMS object used to synchronize +and communicate between tasks by transporting messages between +sending and receiving tasks. + +@item Message Queue Control Block +A data structure +associated with each message queue used by RTEMS to manage that +message queue. + +@item minor number +A numeric value passed to a device +driver, the exact usage of which is driver dependent. + +@item mode +An entry in a task's control block that is +used to determine if the task allows preemption, timeslicing, +processing of signals, and the interrupt disable level used by +the task. + +@item MPCI +An acronym for Multiprocessor Communications +Interface Layer. + +@item multiprocessing +The simultaneous execution of two +or more processes by a multiple processor computer system. + +@item multiprocessor +A computer with multiple CPUs +available for executing applications. + +@item Multiprocessor Communications Interface Layer +A set +of user-provided routines which enable the nodes in a +multiprocessor system to communicate with one another. + +@item Multiprocessor Configuration Table +The data +structure defining the characteristics of the multiprocessor +target system with which RTEMS will communicate. + +@item multitasking +The alternation of execution amongst a +group of processes on a single CPU. A scheduling algorithm is +used to determine which process executes at which time. + +@item mutual exclusion +A term used to describe the act of +preventing other tasks from accessing a resource simultaneously. + +@item nested +A term used to describe an ASR that occurs +during another ASR or an ISR that occurs during another ISR. + +@item node +A term used to reference a processor running +RTEMS in a multiprocessor system. + +@item non-existent +The state occupied by an uncreated or +deleted task. + +@item numeric coprocessor +A component used in computer +systems to enhance performance in mathematically intensive +situations. It is typically viewed as a logical extension of +the primary processor. + +@item object +In this document, this term is used to refer +collectively to tasks, timers, message queues, partitions, +regions, semaphores, ports, and rate monotonic periods. All +RTEMS objects have IDs and user-assigned names. + +@item object-oriented +A term used to describe systems +with common mechanisms for utilizing a variety of entities. +Object-oriented systems shield the application from +implementation details. + +@item operating system +The software which controls all +the computer's resources and provides the base upon which +application programs can be written. + +@item overhead +The portion of the CPUs processing power +consumed by the operating system. + +@item packet +A buffer which contains the messages passed +between nodes in a multiprocessor system. A packet is the +contents of an envelope. + +@item partition +An RTEMS object which is used to allocate +and deallocate fixed size blocks of memory from an dynamically +specified area of memory. + +@item Partition Control Block +A data structure associated +with each partition used by RTEMS to manage that partition. + +@item pending +A term used to describe a task blocked +waiting for an event, message, semaphore, or signal. + +@item periodic task +A task which must execute at regular +intervals and comply with a hard deadline. + +@item physical address +The actual hardware address of a +resource. + +@item poll +A mechanism used to determine if an event has +occurred by periodically checking for a particular status. +Typical events include arrival of data, completion of an action, +and errors. + +@item pool +A collection from which resources are +allocated. + +@item portability +A term used to describe the ease with +which software can be rehosted on another computer. + +@item posting +The act of sending an event, message, +semaphore, or signal to a task. + +@item preempt +The act of forcing a task to relinquish the +processor and dispatching to another task. + +@item priority +A mechanism used to represent the relative +importance of an element in a set of items. RTEMS uses priority +to determine which task should execute. + +@item priority inheritance +An algorithm that calls for +the lower priority task holding a resource to have its priority +increased to that of the highest priority task blocked waiting +for that resource. This avoids the problem of priority +inversion. + +@item priority inversion +A form of indefinite +postponement which occurs when a high priority tasks requests +access to shared resource currently allocated to low priority +task. The high priority task must block until the low priority +task releases the resource. + +@item processor utilization +The percentage of processor +time used by a task or a set of tasks. + +@item proxy +An RTEMS control structure used to represent, +on a remote node, a task which must block as part of a remote +operation. + +@item Proxy Control Block +A data structure associated +with each proxy used by RTEMS to manage that proxy. + +@item PTCB +An acronym for Partition Control Block. + +@item PXCB +An acronym for Proxy Control Block. + +@item quantum +The application defined unit of time in +which the processor is allocated. + +@item queue +Alternate term for message queue. + +@item QCB +An acronym for Message Queue Control Block. + +@item ready +A task occupies this state when it is +available to be given control of the CPU. + +@item real-time +A term used to describe systems which are +characterized by requiring deterministic response times to +external stimuli. The external stimuli require that the +response occur at a precise time or the response is incorrect. + +@item reentrant +A term used to describe routines which do +not modify themselves or global variables. + +@item region +An RTEMS object which is used to allocate +and deallocate variable size blocks of memory from a dynamically +specified area of memory. + +@item Region Control Block +A data structure associated +with each region used by RTEMS to manage that region. + +@item registers +Registers are locations physically +located within a component, typically used for device control or +general purpose storage. + +@item remote +Any object that does not reside on the local +node. + +@item remote operation +The manipulation of an object +which does not reside on the same node as the calling task. + +@item return code +Also known as error code or return +value. + +@item resource +A hardware or software entity to which +access must be controlled. + +@item resume +Removing a task from the suspend state. If +the task's state is ready following a call to the task_resume +directive, then the task is available for scheduling. + +@item return code +A value returned by RTEMS directives to +indicate the completion status of the directive. + +@item RNCB +An acronym for Region Control Block. + +@item round-robin +A task scheduling discipline in which +tasks of equal priority are executed in the order in which they +are made ready. + +@item RS-232 +A standard for serial communications. + +@item running +The state of a rate monotonic timer while +it is being used to delineate a period. The timer exits this +state by either expiring or being canceled. + +@item schedule +The process of choosing which task should +next enter the executing state. + +@item schedulable +A set of tasks which can be guaranteed +to meet their deadlines based upon a specific scheduling +algorithm. + +@item segments +Variable sized memory blocks allocated +from a region. + +@item semaphore +An RTEMS object which is used to +synchronize tasks and provide mutually exclusive access to +resources. + +@item Semaphore Control Block +A data structure associated +with each semaphore used by RTEMS to manage that semaphore. + +@item shared memory +Memory which is accessible by +multiple nodes in a multiprocessor system. + +@item signal +An RTEMS provided mechanism to communicate +asynchronously with a task. Upon reception of a signal, the ASR +of the receiving task will be invoked. + +@item signal set +A thirty-two bit entity which is used to +represent a task's collection of pending signals and the signals +sent to a task. + +@item SMCB +An acronym for Semaphore Control Block. + +@item soft real-time system +A real-time system in which a +missed deadline does not compromise the integrity of the system. + +@item sporadic task +A task which executes at irregular +intervals and must comply with a hard deadline. A minimum +period of time between successive iterations of the task can be +guaranteed. + +@item stack +A data structure that is managed using a Last +In First Out (LIFO) discipline. Each task has a stack +associated with it which is used to store return information +and local variables. + +@item status code +Also known as error code or return +value. + +@item suspend +A term used to describe a task that is not +competing for the CPU because it has had a task_suspend +directive. + +@item synchronous +Related in order or timing to other +occurrences in the system. + +@item system call +In this document, this is used as an +alternate term for directive. + +@item target +The system on which the application will +ultimately execute. + +@item task +A logically complete thread of execution. The +CPU is allocated among the ready tasks. + +@item Task Control Block +A data structure associated with +each task used by RTEMS to manage that task. + +@item task switch +Alternate terminology for context +switch. Taking control of the processor from one task and given +to another. + +@item TCB +An acronym for Task Control Block. + +@item tick +The basic unit of time used by RTEMS. It is a +user-configurable number of microseconds. The current tick +expires when the clock_tick directive is invoked. + +@item tightly-coupled +A multiprocessor configuration +system which communicates via shared memory. + +@item timeout +An argument provided to a number of +directives which determines the maximum length of time an +application task is willing to wait to acquire the resource if +it is not immediately available. + +@item timer +An RTEMS object used to invoke subprograms at +a later time. + +@item Timer Control Block +A data structure associated +with each timer used by RTEMS to manage that timer. + +@item timeslicing +A task scheduling discipline in which +tasks of equal priority are executed for a specific period of +time before being preempted by another task. + +@item timeslice +The application defined unit of time in +which the processor is allocated. + +@item TMCB +An acronym for Timer Control Block. + +@item transient overload +A temporary rise in system +activity which may cause deadlines to be missed. Rate Monotonic +Scheduling can be used to determine if all deadlines will be met +under transient overload. + +@item user extensions +Software routines provided by the +application to enhance the functionality of RTEMS. + +@item User Extension Table +A table which contains the +entry points for each user extensions. + +@item User Initialization Tasks Table +A table which +contains the information needed to create and start each of the +user initialization tasks. + +@item user-provided +Alternate term for user-supplied. +This term is used to designate any software routines which must +be written by the application designer. + +@item user-supplied +Alternate term for user-provided. +This term is used to designate any software routines which must +be written by the application designer. + +@item vector +Memory pointers used by the processor to +fetch the address of routines which will handle various +exceptions and interrupts. + +@item wait queue +The list of tasks blocked pending the +release of a particular resource. Message queues, regions, and +semaphores have a wait queue associated with them. + +@item yield +When a task voluntarily releases control of the processor. + +@end table + diff --git a/doc/user/init.t b/doc/user/init.t new file mode 100644 index 0000000000..6b558d4ab4 --- /dev/null +++ b/doc/user/init.t @@ -0,0 +1,408 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Initialization Manager, Initialization Manager Introduction, Key Concepts Memory Management, Top +@end ifinfo +@chapter Initialization Manager +@ifinfo +@menu +* Initialization Manager Introduction:: +* Initialization Manager Background:: +* Initialization Manager Operations:: +* Initialization Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Initialization Manager Introduction, Initialization Manager Background, Initialization Manager, Initialization Manager +@end ifinfo +@section Introduction + +The initialization manager is responsible for +initiating and shutting down RTEMS. Initiating RTEMS involves +creating and starting all configured initialization tasks, and +for invoking the initialization routine for each user-supplied +device driver. In a multiprocessor configuration, this manager +also initializes the interprocessor communications layer. The +directives provided by the initialization manager are: + +@itemize @bullet +@item @code{initialize_executive} - Initialize RTEMS +@item @code{initialize_executive_early} - Initialize RTEMS and do NOT Start Multitasking +@item @code{initialize_executive_late} - Complete Initialization and Start Multitasking +@item @code{shutdown_executive} - Shutdown RTEMS +@end itemize + +@ifinfo +@node Initialization Manager Background, Initialization Tasks, Initialization Manager Introduction, Initialization Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Initialization Tasks:: +* The System Initialization Task:: +* The Idle Task:: +* Initialization Manager Failure:: +@end menu +@end ifinfo + +@ifinfo +@node Initialization Tasks, The System Initialization Task, Initialization Manager Background, Initialization Manager Background +@end ifinfo +@subsection Initialization Tasks + +Initialization task(s) are the mechanism by which +RTEMS transfers initial control to the user's application. +Initialization tasks differ from other application tasks in that +they are defined in the User Initialization Tasks Table and +automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are +scheduled using the same algorithm as all other RTEMS tasks, +they must be configured at a priority and mode which will insure +that they will complete execution before other application tasks +execute. Although there is no upper limit on the number of +initialization tasks, an application is required to define at +least one. + +A typical initialization task will create and start +the static set of application tasks. It may also create any +other objects used by the application. Initialization tasks +which only perform initialization should delete themselves upon +completion to free resources for other tasks. Initialization +tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and +execution mode. RTEMS does not automatically delete the +initialization tasks. + +@ifinfo +@node The System Initialization Task, The Idle Task, Initialization Tasks, Initialization Manager Background +@end ifinfo +@subsection The System Initialization Task + +The System Initialization Task is responsible for +initializing all device drivers. As a result, this task has a +higher priority than all other tasks to insure that no +application tasks executes until all device drivers are +initialized. After device initialization in a single processor +system, this task will delete itself. + +The System Initialization Task must have enough stack +space to successfully execute the initialization routines for +all device drivers and, in multiprocessor configurations, the +Multiprocessor Communications Interface Layer initialization +routine. The CPU Configuration Table contains a field which +allows the application or BSP to increase the default amount of +stack space allocated for this task. + +In multiprocessor configurations, the System +Initialization Task does not delete itself after initializing +the device drivers. Instead it transforms itself into the +Multiprocessing Server which initializes the Multiprocessor +Communications Interface Layer, verifies multiprocessor system +consistency, and processes all requests from remote nodes. + +@ifinfo +@node The Idle Task, Initialization Manager Failure, The System Initialization Task, Initialization Manager Background +@end ifinfo +@subsection The Idle Task + +The Idle Task is the lowest priority task in a system +and executes only when no other task is ready to execute. This +task consists of an infinite loop and will be preempted when any +other task is made ready to execute. + +@ifinfo +@node Initialization Manager Failure, Initialization Manager Operations, The Idle Task, Initialization Manager Background +@end ifinfo +@subsection Initialization Manager Failure + +The fatal_error_occurred directive will be called +from initialize_executive for any of the following reasons: + +@itemize @bullet +@item If either the Configuration Table or the CPU Dependent +Information Table is not provided. + +@item If the starting address of the RTEMS RAM Workspace, +supplied by the application in the Configuration Table, is NULL +or is not aligned on a four-byte boundary. + +@item If the size of the RTEMS RAM Workspace is not large +enough to initialize and configure the system. + +@item If the interrupt stack size specified is too small. + +@item If multiprocessing is configured and the node entry in +the Multiprocessor Configuration Table is not between one and +the maximum_nodes entry. + +@item If a multiprocessor system is being configured and no +Multiprocessor Communications Interface is specified. + +@item If no user initialization tasks are configured. At +least one initialization task must be configured to allow RTEMS +to pass control to the application at the end of the executive +initialization sequence. + +@item If any of the user initialization tasks cannot be +created or started successfully. +@end itemize + +@ifinfo +@node Initialization Manager Operations, Initializing RTEMS, Initialization Manager Failure, Initialization Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Initializing RTEMS:: +* Shutting Down RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Initializing RTEMS, Shutting Down RTEMS, Initialization Manager Operations, Initialization Manager Operations +@end ifinfo +@subsection Initializing RTEMS + +The initialize_executive directive is called by the +board support package at the completion of its initialization +sequence. RTEMS assumes that the board support package +successfully completed its initialization activities. The +initialize_executive directive completes the initialization +sequence by performing the following actions: + +@itemize @bullet +@item Initializing internal RTEMS variables; +@item Allocating system resources; +@item Creating and starting the System Initialization Task; +@item Creating and starting the Idle Task; +@item Creating and starting the user initialization task(s); and +@item Initiating multitasking. +@end itemize + +This directive MUST be called before any other RTEMS +directives. The effect of calling any RTEMS directives before +initialize_executive is unpredictable. Many of RTEMS actions +during initialization are based upon the contents of the +Configuration Table and CPU Dependent Information Table. For +more information regarding the format and contents of these +tables, please refer to the chapter Configuring a System. + +The final step in the initialization sequence is the +initiation of multitasking. When the scheduler and dispatcher +are enabled, the highest priority, ready task will be dispatched +to run. Control will not be returned to the board support +package after multitasking is enabled until shutdown_executive +the directive is called. + +The initialize_executive directive provides a +conceptually simple way to initialize RTEMS. However, in +certain cases, this mechanism cannot be used. The +initialize_executive_early and initialize_executive_late +directives are provided as an alternative mechanism for +initializing RTEMS. The initialize_executive_early directive +returns to the caller BEFORE initiating multitasking. The +initialize_executive_late directive is invoked to start +multitasking. It is critical that only one of the RTEMS +initialization sequences be used in an application. + +@ifinfo +@node Shutting Down RTEMS, Initialization Manager Directives, Initializing RTEMS, Initialization Manager Operations +@end ifinfo +@subsection Shutting Down RTEMS + +The shutdown_executive directive is invoked by the +application to end multitasking and return control to the board +support package. The board support package resumes execution at +the code immediately following the invocation of the +initialize_executive directive. + +@ifinfo +@node Initialization Manager Directives, INITIALIZE_EXECUTIVE - Initialize RTEMS, Shutting Down RTEMS, Initialization Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* INITIALIZE_EXECUTIVE - Initialize RTEMS:: +* INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking:: +* INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking:: +* SHUTDOWN_EXECUTIVE - Shutdown RTEMS:: +@end menu +@end ifinfo + +This section details the initialization 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 INITIALIZE_EXECUTIVE - Initialize RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS + +@subheading CALLING SEQUENCE: + +@example +rtems_interrupt_level rtems_initialize_executive_early( + rtems_configuration_table *configuration_table, + rtems_cpu_table *cpu_table +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the board support +package has completed its initialization to allow RTEMS to +initialize the application environment based upon the +information in the Configuration Table, CPU Dependent +Information Table, User Initialization Tasks Table, Device +Driver Table, User Extension Table, Multiprocessor Configuration +Table, and the Multiprocessor Communications Interface (MPCI) +Table. This directive starts multitasking and does not return +to the caller until the shutdown_executive directive is invoked. + +@subheading NOTES: + +This directive MUST be the first RTEMS directive +called and it DOES NOT RETURN to the caller until the +shutdown_executive is invoked. + +This directive causes all nodes in the system to +verify that certain configuration parameters are the same as +those of the local node. If an inconsistency is detected, then +a fatal error is generated. + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. The +initialize_executive directive is logically equivalent to +invoking initialize_executive_early and +initialize_executive_late with no intervening actions. + +@page +@ifinfo +@node INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, INITIALIZE_EXECUTIVE - Initialize RTEMS, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking + +@subheading CALLING SEQUENCE: + +@example +rtems_interrupt_level rtems_initialize_executive_early( + rtems_configuration_table *configuration_table, + rtems_cpu_table *cpu_table +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the board support +package has completed its initialization to allow RTEMS to +initialize the application environment based upon the +information in the Configuration Table, CPU Dependent +Information Table, User Initialization Tasks Table, Device +Driver Table, User Extension Table, Multiprocessor Configuration +Table, and the Multiprocessor Communications Interface (MPCI) +Table. This directive returns to the caller after completing +the basic RTEMS initialization but before multitasking is +initiated. The interrupt level in place when the directive is +invoked is returned to the caller. This interrupt level should +be the same one passed to initialize_executive_late. + +@subheading NOTES: + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. + +@page +@ifinfo +@node INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking + +@subheading CALLING SEQUENCE: + +@example +void rtems_initialize_executive_late( + rtems_interrupt_level bsp_level +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called after the +initialize_executive_early directive has been called to complete +the RTEMS initialization sequence and initiate multitasking. +The interrupt level returned by the initialize_executive_early +directive should be in bsp_level and this value is restored as +part of this directive returning to the caller after the +shutdown_executive directive is invoked. + +@subheading NOTES: + +This directive MUST be the second RTEMS directive +called and it DOES NOT RETURN to the caller until the +shutdown_executive is invoked. + +This directive causes all nodes in the system to +verify that certain configuration parameters are the same as +those of the local node. If an inconsistency is detected, then +a fatal error is generated. + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. + + + +@page +@ifinfo +@node SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Task Manager, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, Initialization Manager Directives +@end ifinfo +@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS + +@subheading CALLING SEQUENCE: + +@example +void rtems_shutdown_executive( + rtems_unsigned32 result +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the application wishes +to shutdown RTEMS and return control to the board support +package. The board support package resumes execution at the +code immediately following the invocation of the +initialize_executive directive. + +@subheading NOTES: + +This directive MUST be the last RTEMS directive +invoked by an application and it DOES NOT RETURN to the caller. + +This directive should not be invoked until the +executive has successfully completed initialization. diff --git a/doc/user/intr.t b/doc/user/intr.t new file mode 100644 index 0000000000..8eb076e8f4 --- /dev/null +++ b/doc/user/intr.t @@ -0,0 +1,300 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Interrupt Manager, Interrupt Manager Introduction, TASK_WAKE_WHEN - Wake up when specified, Top +@end ifinfo +@chapter Interrupt Manager +@ifinfo +@menu +* Interrupt Manager Introduction:: +* Interrupt Manager Background:: +* Interrupt Manager Operations:: +* Interrupt Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Manager Introduction, Interrupt Manager Background, Interrupt Manager, Interrupt Manager +@end ifinfo +@section Introduction + +Any real-time executive must provide a mechanism for +quick response to externally generated interrupts to satisfy the +critical time constraints of the application. The interrupt +manager provides this mechanism for RTEMS. This manager permits +quick interrupt response times by providing the critical ability +to alter task execution which allows a task to be preempted upon +exit from an ISR. The interrupt manager includes the following +directive: + +@itemize @bullet +@item @code{interrupt_catch} - Establish an ISR +@end itemize + +@ifinfo +@node Interrupt Manager Background, Processing an Interrupt, Interrupt Manager Introduction, Interrupt Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Processing an Interrupt:: +* RTEMS Interrupt Levels:: +* Disabling of Interrupts by RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Processing an Interrupt, RTEMS Interrupt Levels, Interrupt Manager Background, Interrupt Manager Background +@end ifinfo +@subsection Processing an Interrupt + +The interrupt manager allows the application to +connect a function to a hardware interrupt vector. When an +interrupt occurs, the processor will automatically vector to +RTEMS. RTEMS saves and restores all registers which are not +preserved by the normal C calling convention for the target +processor and invokes the user's ISR. The user's ISR is +responsible for processing the interrupt, clearing the interrupt +if necessary, and device specific manipulation. + +The interrupt_catch directive connects a procedure to +an interrupt vector. The interrupt service routine is assumed +to abide by these conventions and have a prototype similar to +the following: + +@example +rtems_isr user_isr( + rtems_vector_number vector +); +@end example + +The vector number argument is provided by RTEMS to +allow the application to identify the interrupt source. This +could be used to allow a single routine to service interrupts +from multiple instances of the same device. For example, a +single routine could service interrupts from multiple serial +ports and use the vector number to identify which port requires +servicing. + +To minimize the masking of lower or equal priority +level interrupts, the ISR should perform the minimum actions +required to service the interrupt. Other non-essential actions +should be handled by application tasks. Once the user's ISR has +completed, it returns control to the RTEMS interrupt manager +which will perform task dispatching and restore the registers +saved before the ISR was invoked. + +The RTEMS interrupt manager guarantees that proper +task scheduling and dispatching are performed at the conclusion +of an ISR. A system call made by the ISR may have readied a +task of higher priority than the interrupted task. Therefore, +when the ISR completes, the postponed dispatch processing must +be performed. No dispatch processing is performed as part of +directives which have been invoked by an ISR. + +Applications must adhere to the following rule if +proper task scheduling and dispatching is to be performed: + +@itemize @code{ } + +@item @b{The interrupt manager must be used for all ISRs which +may be interrupted by the highest priority ISR which invokes an +RTEMS directive.} + +@end itemize + + +Consider a processor which allows a numerically low +interrupt level to interrupt a numerically greater interrupt +level. In this example, if an RTEMS directive is used in a +level 4 ISR, then all ISRs which execute at levels 0 through 4 +must use the interrupt manager. + +Interrupts are nested whenever an interrupt occurs +during the execution of another ISR. RTEMS supports efficient +interrupt nesting by allowing the nested ISRs to terminate +without performing any dispatch processing. Only when the +outermost ISR terminates will the postponed dispatching occur. + + + +@ifinfo +@node RTEMS Interrupt Levels, Disabling of Interrupts by RTEMS, Processing an Interrupt, Interrupt Manager Background +@end ifinfo +@subsection RTEMS Interrupt Levels + +Many processors support multiple interrupt levels or +priorities. The exact number of interrupt levels is processor +dependent. RTEMS internally supports 256 interrupt levels which +are mapped to the processor's interrupt levels. For specific +information on the mapping between RTEMS and the target +processor's interrupt levels, refer to the Interrupt Processing +chapter of the C Applications Supplement document for a specific +target processor. + +@ifinfo +@node Disabling of Interrupts by RTEMS, Interrupt Manager Operations, RTEMS Interrupt Levels, Interrupt Manager Background +@end ifinfo +@subsection 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 all maskable interrupts before the +execution of the section and restores them to the previous level +upon completion of the section. RTEMS has been optimized to +insure that interrupts are disabled for a minimum length of +time. The maximum length of time interrupts are disabled by +RTEMS is processor dependent and is detailed in the Timing +Specification chapter of the C Applications Supplement document +for a specific target processor. + +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 Manager Operations, Establishing an ISR, Disabling of Interrupts by RTEMS, Interrupt Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Establishing an ISR:: +* Directives Allowed from an ISR:: +@end menu +@end ifinfo + +@ifinfo +@node Establishing an ISR, Directives Allowed from an ISR, Interrupt Manager Operations, Interrupt Manager Operations +@end ifinfo +@subsection Establishing an ISR + +The interrupt_catch directive establishes an ISR for +the system. The address of the ISR and its associated CPU +vector number are specified to this directive. This directive +installs the RTEMS interrupt wrapper in the processor's +Interrupt Vector Table and the address of the user's ISR in the +RTEMS' Vector Table. This directive returns the previous +contents of the specified vector in the RTEMS' Vector Table. + +@ifinfo +@node Directives Allowed from an ISR, Interrupt Manager Directives, Establishing an ISR, Interrupt Manager Operations +@end ifinfo +@subsection Directives Allowed from an ISR + +Using the interrupt manager insures that RTEMS knows +when a directive is being called from an ISR. The ISR may then +use system calls to synchronize itself with an application task. +The synchronization may involve messages, events or signals +being passed by the ISR to the desired task. Directives invoked +by an ISR must operate only on objects which reside on the local +node. The following is a list of RTEMS system calls that may be +made from an ISR: + +@itemize @bullet +@item Task Management + +@itemize - +@item task_get_note, task_set_note, task_suspend, task_resume +@end itemize + +@item Clock Management + +@itemize - +@item clock_get, clock_tick +@end itemize + +@item Message, Event, and Signal Management + +@itemize - +@item message_queue_send, message_queue_urgent +@item event_send +@item signal_send +@end itemize + +@item Semaphore Management + +@itemize - +@item semaphore_release +@end itemize + +@item Dual-Ported Memory Management + +@itemize - +@item port_external_to_internal, port_internal_to_external +@end itemize + +@item IO Management + +@itemize - +@item io_initialize, io_open, io_close, io_read, io_write, io_control +@end itemize + +@item Fatal Error Management + +@itemize - +@item fatal_error_occurred +@end itemize + +@item Multiprocessing + +@itemize - +@item multiprocessing_announce +@end itemize +@end itemize + +@ifinfo +@node Interrupt Manager Directives, INTERRUPT_CATCH - Establish an ISR, Directives Allowed from an ISR, Interrupt Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* INTERRUPT_CATCH - Establish an ISR:: +@end menu +@end ifinfo + +This section details the interrupt 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 INTERRUPT_CATCH - Establish an ISR, Clock Manager, Interrupt Manager Directives, Interrupt Manager Directives +@end ifinfo +@subsection INTERRUPT_CATCH - Establish an ISR + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - ISR established successfully@* +@code{INVALID_NUMBER} - illegal vector number@* +@code{INVALID_ADDRESS} - illegal ISR entry point + +@subheading DESCRIPTION: + +This directive establishes an interrupt service +routine (ISR) for the specified interrupt vector number. The +new_isr_handler parameter specifies the entry point of the ISR. +The entry point of the previous ISR for the specified vector is +returned in old_isr_handler. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + diff --git a/doc/user/io.t b/doc/user/io.t new file mode 100644 index 0000000000..5176b89224 --- /dev/null +++ b/doc/user/io.t @@ -0,0 +1,528 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node I/O Manager, I/O Manager Introduction, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, Top +@end ifinfo +@chapter I/O Manager +@ifinfo +@menu +* I/O Manager Introduction:: +* I/O Manager Background:: +* I/O Manager Operations:: +* I/O Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node I/O Manager Introduction, I/O Manager Background, I/O Manager, I/O Manager +@end ifinfo +@section Introduction + +The input/output interface manager provides a +well-defined mechanism for accessing device drivers and a +structured methodology for organizing device drivers. The +directives provided by the I/O manager are: + +@itemize @bullet +@item @code{io_initialize} - Initialize a device driver +@item @code{io_register_name} - Register a device name +@item @code{io_lookup_name} - Look up a device name +@item @code{io_open} - Open a device +@item @code{io_close} - Close a device +@item @code{io_read} - Read from a device +@item @code{io_write} - Write to a device +@item @code{io_control} - Special device services +@end itemize + + + +@ifinfo +@node I/O Manager Background, Device Driver Table, I/O Manager Introduction, I/O Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Device Driver Table:: +* Major and Minor Device Numbers:: +* Device Names:: +* Device Driver Environment:: +* Device Driver Interface:: +* Device Driver Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Device Driver Table, Major and Minor Device Numbers, I/O Manager Background, I/O Manager Background +@end ifinfo +@subsection Device Driver Table + +Each application utilizing the RTEMS I/O manager must +specify the address of a Device Driver Table in its +Configuration Table. This table contains each device driver's +entry points. Each device driver may contain the following +entry points: + +@itemize @bullet +@item Initialization +@item Open +@item Close +@item Read +@item Write +@item Control +@end itemize + +If the device driver does not support a particular +entry point, then that entry in the Configuration Table should +be NULL. RTEMS will return SUCCESSFUL as the executive's and +zero (0) as the device driver's return code for these device +driver entry points. + +@ifinfo +@node Major and Minor Device Numbers, Device Names, Device Driver Table, I/O Manager Background +@end ifinfo +@subsection Major and Minor Device Numbers + +Each call to the I/O manager must provide a device's +major and minor numbers as arguments. The major number is the +index of the requested driver's entry points in the Device +Driver Table, and is used to select a specific device driver. +The exact usage of the minor number is driver specific, but is +commonly used to distinguish between a number of devices +controlled by the same driver. + +@ifinfo +@node Device Names, Device Driver Environment, Major and Minor Device Numbers, I/O Manager Background +@end ifinfo +@subsection Device Names + +The I/O Manager provides facilities to associate a +name with a particular device. Directives are provided to +register the name of a device and to look up the major/minor +number pair associated with a device name. + +@ifinfo +@node Device Driver Environment, Device Driver Interface, Device Names, I/O Manager Background +@end ifinfo +@subsection Device Driver Environment + +Application developers, as well as device driver +developers, must be aware of the following regarding the RTEMS +I/O Manager: + +@itemize @bullet +@item A device driver routine executes in the context of the +invoking task. Thus if the driver blocks, the invoking task +blocks. + +@item The device driver is free to change the modes of the +invoking task, although the driver should restore them to their +original values. + +@item Device drivers may be invoked from ISRs. + +@item Only local device drivers are accessible through the I/O +manager. + +@item A device driver routine may invoke all other RTEMS +directives, including I/O directives, on both local and global +objects. + +@end itemize + +Although the RTEMS I/O manager provides a framework +for device drivers, it makes no assumptions regarding the +construction or operation of a device driver. + +@ifinfo +@node Device Driver Interface, Device Driver Initialization, Device Driver Environment, I/O Manager Background +@end ifinfo +@subsection Device Driver Interface + +When an application invokes an I/O manager directive, +RTEMS determines which device driver entry point must be +invoked. The information passed by the application to RTEMS is +then passed to the correct device driver entry point. RTEMS +will invoke each device driver entry point assuming it is +compatible with the following prototype: + +@example +rtems_device_driver io_entry( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument_block +); +@end example + + + +The format and contents of the parameter block are +device driver and entry point dependent. + +It is recommended that a device driver avoid +generating error codes which conflict with those used by +application components. A common technique used to generate +driver specific error codes is to make the most significant part +of the status indicate a driver specific code. + +@ifinfo +@node Device Driver Initialization, I/O Manager Operations, Device Driver Interface, I/O Manager Background +@end ifinfo +@subsection Device Driver Initialization + +RTEMS automatically initializes all device drivers +when multitasking is initiated via the initialize_executive +directive. RTEMS initializes the device drivers by invoking +each device driver initialization entry point with the following +parameters: + +@table @asis +@item major +the major device number for this device driver. + +@item minor +zero. + +@item argument_block +will point to the Configuration Table. + +@end table + +The returned status will be ignored by RTEMS. If the driver +cannot successfully initialize the device, then it should invoke +the fatal_error_occurred directive. + +@ifinfo +@node I/O Manager Operations, Register and Lookup Name, Device Driver Initialization, I/O Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Register and Lookup Name:: +* Accessing an Device Driver:: +@end menu +@end ifinfo + +@ifinfo +@node Register and Lookup Name, Accessing an Device Driver, I/O Manager Operations, I/O Manager Operations +@end ifinfo +@subsection Register and Lookup Name + +The io_register directive associates a name with the +specified device (i.e. major/minor number pair). Device names +are typically registered as part of the device driver +initialization sequence. The io_lookup directive is used to +determine the major/minor number pair associated with the +specified device name. The use of these directives frees the +application from being dependent on the arbitrary assignment of +major numbers in a particular application. No device naming +conventions are dictated by RTEMS. + +@ifinfo +@node Accessing an Device Driver, I/O Manager Directives, Register and Lookup Name, I/O Manager Operations +@end ifinfo +@subsection Accessing an Device Driver + +The I/O manager provides directives which enable the +application program to utilize device drivers in a standard +manner. There is a direct correlation between the RTEMS I/O +manager directives io_initialize, io_open, io_close, io_read, +io_write, and io_control and the underlying device driver entry +points. + +@ifinfo +@node I/O Manager Directives, IO_INITIALIZE - Initialize a device driver, Accessing an Device Driver, I/O Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* IO_INITIALIZE - Initialize a device driver:: +* IO_REGISTER_NAME - Register a device:: +* IO_LOOKUP_NAME - Lookup a device:: +* IO_OPEN - Open a device:: +* IO_CLOSE - Close a device:: +* IO_READ - Read from a device:: +* IO_WRITE - Write to a device:: +* IO_CONTROL - Special device services:: +@end menu +@end ifinfo + +This section details the I/O 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 IO_INITIALIZE - Initialize a device driver, IO_REGISTER_NAME - Register a device, I/O Manager Directives, I/O Manager Directives +@end ifinfo +@subsection IO_INITIALIZE - Initialize a device driver + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver initialization +routine specified in the Device Driver Table for this major +number. This directive is automatically invoked for each device +driver when multitasking is initiated via the +initialize_executive directive. + +A device driver initialization module is responsible +for initializing all hardware and data structures associated +with a device. If necessary, it can allocate memory to be used +during other operations. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +initialized. + +@page +@ifinfo +@node IO_REGISTER_NAME - Register a device, IO_LOOKUP_NAME - Lookup a device, IO_INITIALIZE - Initialize a device driver, I/O Manager Directives +@end ifinfo +@subsection IO_REGISTER_NAME - Register a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_register_name( + char *name, + rtems_device_major_number major, + rtems_device_minor_number minor +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{TOO_MANY} - too many devices registered + +@subheading DESCRIPTION: + +This directive associates name with the specified +major/minor number pair. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node IO_LOOKUP_NAME - Lookup a device, IO_OPEN - Open a device, IO_REGISTER_NAME - Register a device, I/O Manager Directives +@end ifinfo +@subsection IO_LOOKUP_NAME - Lookup a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_lookup( + const char *name, + rtems_driver_name_t **device_info +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{UNSATISFIED} - name not registered + +@subheading DESCRIPTION: + +This directive returns the major/minor number pair +associated with the given device name in device_info. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node IO_OPEN - Open a device, IO_CLOSE - Close a device, IO_LOOKUP_NAME - Lookup a device, I/O Manager Directives +@end ifinfo +@subsection IO_OPEN - Open a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver open routine +specified in the Device Driver Table for this major number. The +open entry point is commonly used by device drivers to provide +exclusive access to a device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_CLOSE - Close a device, IO_READ - Read from a device, IO_OPEN - Open a device, I/O Manager Directives +@end ifinfo +@subsection IO_CLOSE - Close a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver close routine +specified in the Device Driver Table for this major number. The +close entry point is commonly used by device drivers to +relinquish exclusive access to a device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_READ - Read from a device, IO_WRITE - Write to a device, IO_CLOSE - Close a device, I/O Manager Directives +@end ifinfo +@subsection IO_READ - Read from a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver read routine +specified in the Device Driver Table for this major number. +Read operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be replaced with data from the device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_WRITE - Write to a device, IO_CONTROL - Special device services, IO_READ - Read from a device, I/O Manager Directives +@end ifinfo +@subsection IO_WRITE - Write to a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver write routine +specified in the Device Driver Table for this major number. +Write operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be sent to the device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_CONTROL - Special device services, Fatal Error Manager, IO_WRITE - Write to a device, I/O Manager Directives +@end ifinfo +@subsection IO_CONTROL - Special device services + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver I/O control +routine specified in the Device Driver Table for this major +number. The exact functionality of the driver entry called by +this directive is driver dependent. It should not be assumed +that the control entries of two device drivers are compatible. +For example, an RS-232 driver I/O control operation may change +the baud rate of a serial line, while an I/O control operation +for a floppy disk driver may cause a seek operation. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + + + diff --git a/doc/user/mp.t b/doc/user/mp.t new file mode 100644 index 0000000000..05a62978c4 --- /dev/null +++ b/doc/user/mp.t @@ -0,0 +1,628 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Multiprocessing Manager, Multiprocessing Manager Introduction, Configuring a System Sizing the RTEMS RAM Workspace, Top +@end ifinfo +@chapter Multiprocessing Manager +@ifinfo +@menu +* Multiprocessing Manager Introduction:: +* Multiprocessing Manager Background:: +* Multiprocessing Manager Multiprocessor Communications Interface Layer:: +* Multiprocessing Manager Operations:: +* Multiprocessing Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Multiprocessing Manager Introduction, Multiprocessing Manager Background, Multiprocessing Manager, Multiprocessing Manager +@end ifinfo +@section Introduction + +In multiprocessor real-time systems, new +requirements, such as sharing data and global resources between +processors, are introduced. This requires an efficient and +reliable communications vehicle which allows all processors to +communicate with each other as necessary. In addition, the +ramifications of multiple processors affect each and every +characteristic of a real-time system, almost always making them +more complicated. + +RTEMS addresses these issues by providing simple and +flexible real-time multiprocessing capabilities. The executive +easily lends itself to both tightly-coupled and loosely-coupled +configurations of the target system hardware. In addition, +RTEMS supports systems composed of both homogeneous and +heterogeneous mixtures of processors and target boards. + +A major design goal of the RTEMS executive was to +transcend the physical boundaries of the target hardware +configuration. This goal is achieved by presenting the +application software with a logical view of the target system +where the boundaries between processor nodes are transparent. +As a result, the application developer may designate objects +such as tasks, queues, events, signals, semaphores, and memory +blocks as global objects. These global objects may then be +accessed by any task regardless of the physical location of the +object and the accessing task. RTEMS automatically determines +that the object being accessed resides on another processor and +performs the actions required to access the desired object. +Simply stated, RTEMS allows the entire system, both hardware and +software, to be viewed logically as a single system. + +@ifinfo +@node Multiprocessing Manager Background, Nodes, Multiprocessing Manager Introduction, Multiprocessing Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Nodes:: +* Global Objects:: +* Global Object Table:: +* Remote Operations:: +* Proxies:: +* Multiprocessor Configuration Table:: +@end menu +@end ifinfo + +RTEMS makes no assumptions regarding the connection +media or topology of a multiprocessor system. The tasks which +compose a particular application can be spread among as many +processors as needed to satisfy the application's timing +requirements. The application tasks can interact using a subset +of the RTEMS directives as if they were on the same processor. +These directives allow application tasks to exchange data, +communicate, and synchronize regardless of which processor they +reside upon. + +The RTEMS multiprocessor execution model is multiple +instruction streams with multiple data streams (MIMD). This +execution model has each of the processors executing code +independent of the other processors. Because of this +parallelism, the application designer can more easily guarantee +deterministic behavior. + +By supporting heterogeneous environments, RTEMS +allows the systems designer to select the most efficient +processor for each subsystem of the application. Configuring +RTEMS for a heterogeneous environment is no more difficult than +for a homogeneous one. In keeping with RTEMS philosophy of +providing transparent physical node boundaries, the minimal +heterogeneous processing required is isolated in the MPCI layer. + +@ifinfo +@node Nodes, Global Objects, Multiprocessing Manager Background, Multiprocessing Manager Background +@end ifinfo +@subsection Nodes + +A processor in a RTEMS system is referred to as a +node. Each node is assigned a unique non-zero node number by +the application designer. RTEMS assumes that node numbers are +assigned consecutively from one to maximum_nodes. The node +number, node, and the maximum number of nodes, maximum_nodes, in +a system are found in the Multiprocessor Configuration Table. +The maximum_nodes field and the number of global objects, +maximum_global_objects, is required to be the same on all nodes +in a system. + +The node number is used by RTEMS to identify each +node when performing remote operations. Thus, the +Multiprocessor Communications Interface Layer (MPCI) must be +able to route messages based on the node number. + +@ifinfo +@node Global Objects, Global Object Table, Nodes, Multiprocessing Manager Background +@end ifinfo +@subsection Global Objects + +All RTEMS objects which are created with the GLOBAL +attribute will be known on all other nodes. Global objects can +be referenced from any node in the system, although certain +directive specific restrictions (e.g. one cannot delete a remote +object) may apply. A task does not have to be global to perform +operations involving remote objects. The maximum number of +global objects is the system is user configurable and can be +found in the maximum_global_objects field in the Multiprocessor +Configuration Table. The distribution of tasks to processors is +performed during the application design phase. Dynamic task +relocation is not supported by RTEMS. + +@ifinfo +@node Global Object Table, Remote Operations, Global Objects, Multiprocessing Manager Background +@end ifinfo +@subsection Global Object Table + +RTEMS maintains two tables containing object +information on every node in a multiprocessor system: a local +object table and a global object table. The local object table +on each node is unique and contains information for all objects +created on this node whether those objects are local or global. +The global object table contains information regarding all +global objects in the system and, consequently, is the same on +every node. + +Since each node must maintain an identical copy of +the global object table, the maximum number of entries in each +copy of the table must be the same. The maximum number of +entries in each copy is determined by the +maximum_global_objects parameter in the Multiprocessor +Configuration Table. This parameter, as well as the +maximum_nodes parameter, is required to be the same on all +nodes. To maintain consistency among the table copies, every +node in the system must be informed of the creation or deletion +of a global object. + +@ifinfo +@node Remote Operations, Proxies, Global Object Table, Multiprocessing Manager Background +@end ifinfo +@subsection Remote Operations + +When an application performs an operation on a remote +global object, RTEMS must generate a Remote Request (RQ) message +and send it to the appropriate node. After completing the +requested operation, the remote node will build a Remote +Response (RR) message and send it to the originating node. +Messages generated as a side-effect of a directive (such as +deleting a global task) are known as Remote Processes (RP) and +do not require the receiving node to respond. + +Other than taking slightly longer to execute +directives on remote objects, the application is unaware of the +location of the objects it acts upon. The exact amount of +overhead required for a remote operation is dependent on the +media connecting the nodes and, to a lesser degree, on the +efficiency of the user-provided MPCI routines. + +The following shows the typical transaction sequence +during a remote application: + +@enumerate + +@item The application issues a directive accessing a +remote global object. + +@item RTEMS determines the node on which the object +resides. + +@item RTEMS calls the user-provided MPCI routine +GET_PACKET to obtain a packet in which to build a RQ message. + +@item After building a message packet, RTEMS calls the +user-provided MPCI routine SEND_PACKET to transmit the packet to +the node on which the object resides (referred to as the +destination node). + +@item The calling task is blocked until the RR message +arrives, and control of the processor is transferred to another +task. + +@item The MPCI layer on the destination node senses the +arrival of a packet (commonly in an ISR), and calls the +multiprocessing_announce directive. This directive readies the +Multiprocessing Server. + +@item The Multiprocessing Server calls the user-provided +MPCI routine RECEIVE_PACKET, performs the requested operation, +builds an RR message, and returns it to the originating node. + +@item The MPCI layer on the originating node senses the +arrival of a packet (typically via an interrupt), and calls the +RTEMS multiprocessing_announce directive. This directive +readies the Multiprocessing Server. + +@item The Multiprocessing Server calls the user-provided +MPCI routine RECEIVE_PACKET, readies the original requesting +task, and blocks until another packet arrives. Control is +transferred to the original task which then completes processing +of the directive. + +@end enumerate + +If an uncorrectable error occurs in the user-provided +MPCI layer, the fatal error handler should be invoked. RTEMS +assumes the reliable transmission and reception of messages by +the MPCI and makes no attempt to detect or correct errors. + +@ifinfo +@node Proxies, Multiprocessor Configuration Table, Remote Operations, Multiprocessing Manager Background +@end ifinfo +@subsection Proxies + +A proxy is an RTEMS data structure which resides on a +remote node and is used to represent a task which must block as +part of a remote operation. This action can occur as part of the +semaphore_obtain and message_queue_receive directives. If the +object were local, the task's control block would be available +for modification to indicate it was blocking on a message queue +or semaphore. However, the task's control block resides only on +the same node as the task. As a result, the remote node must +allocate a proxy to represent the task until it can be readied. + +The maximum number of proxies is defined in the +Multiprocessor Configuration Table. Each node in a +multiprocessor system may require a different number of proxies +to be configured. The distribution of proxy control blocks is +application dependent and is different from the distribution of +tasks. + +@ifinfo +@node Multiprocessor Configuration Table, Multiprocessing Manager Multiprocessor Communications Interface Layer, Proxies, Multiprocessing Manager Background +@end ifinfo +@subsection Multiprocessor Configuration Table + +The Multiprocessor Configuration Table contains +information needed by RTEMS when used in a multiprocessor +system. This table is discussed in detail in the section +Multiprocessor Configuration Table of the Configuring a System +chapter. + +@ifinfo +@node Multiprocessing Manager Multiprocessor Communications Interface Layer, INITIALIZATION, Multiprocessor Configuration Table, Multiprocessing Manager +@end ifinfo +@section Multiprocessor Communications Interface Layer +@ifinfo +@menu +* INITIALIZATION:: +* GET_PACKET:: +* RETURN_PACKET:: +* RECEIVE_PACKET:: +* SEND_PACKET:: +* Supporting Heterogeneous Environments:: +@end menu +@end ifinfo + +The Multiprocessor Communications Interface Layer +(MPCI) is a set of user-provided procedures which enable the +nodes in a multiprocessor system to communicate with one +another. These routines are invoked by RTEMS at various times +in the preparation and processing of remote requests. +Interrupts are enabled when an MPCI procedure is invoked. It is +assumed that if the execution mode and/or interrupt level are +altered by the MPCI layer, that they will be restored prior to +returning to RTEMS. + +The MPCI layer is responsible for managing a pool of +buffers called packets and for sending these packets between +system nodes. Packet buffers contain the messages sent between +the nodes. Typically, the MPCI layer will encapsulate the +packet within an envelope which contains the information needed +by the MPCI layer. The number of packets available is dependent +on the MPCI layer implementation. + +The entry points to the routines in the user's MPCI +layer should be placed in the Multiprocessor Communications +Interface Table. The user must provide entry points for each of +the following table entries in a multiprocessor system: + +@itemize @bullet +@item initialization initialize the MPCI +@item get_packet obtain a packet buffer +@item return_packet return a packet buffer +@item send_packet send a packet to another node +@item receive_packet called to get an arrived packet +@end itemize + +A packet is sent by RTEMS in each of the following +situations: + +@itemize @bullet +@item an RQ is generated on an originating node; +@item an RR is generated on a destination node; +@item a global object is created; +@item a global object is deleted; +@item a local task blocked on a remote object is deleted; +@item during system initialization to check for system consistency. +@end itemize + +If the target hardware supports it, the arrival of a +packet at a node may generate an interrupt. Otherwise, the +real-time clock ISR can check for the arrival of a packet. In +any case, the multiprocessing_announce directive must be called +to announce the arrival of a packet. After exiting the ISR, +control will be passed to the Multiprocessing Server to process +the packet. The Multiprocessing Server will call the get_packet +entry to obtain a packet buffer and the receive_entry entry to +copy the message into the buffer obtained. + +@ifinfo +@node INITIALIZATION, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection INITIALIZATION + +The INITIALIZATION component of the user-provided +MPCI layer is called as part of the initialize_executive +directive to initialize the MPCI layer and associated hardware. +It is invoked immediately after all of the device drivers have +been initialized. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_initialization( + rtems_configuration_table *configuration +); +@end group +@end example + +where configuration is the address of the user's +Configuration Table. Operations on global objects cannot be +performed until this component is invoked. The INITIALIZATION +component is invoked only once in the life of any system. If +the MPCI layer cannot be successfully initialized, the fatal +error manager should be invoked by this routine. + +One of the primary functions of the MPCI layer is to +provide the executive with packet buffers. The INITIALIZATION +routine must create and initialize a pool of packet buffers. +There must be enough packet buffers so RTEMS can obtain one +whenever needed. + +@ifinfo +@node GET_PACKET, RETURN_PACKET, INITIALIZATION, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection GET_PACKET + +The GET_PACKET component of the user-provided MPCI +layer is called when RTEMS must obtain a packet buffer to send +or broadcast a message. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_get_packet( + rtems_packet_prefix **packet +); +@end group +@end example + +where packet is the address of a pointer to a packet. +This routine always succeeds and, upon return, packet will +contain the address of a packet. If for any reason, a packet +cannot be successfully obtained, then the fatal error manager +should be invoked. + +RTEMS has been optimized to avoid the need for +obtaining a packet each time a message is sent or broadcast. +For example, RTEMS sends response messages (RR) back to the +originator in the same packet in which the request message (RQ) +arrived. + +@ifinfo +@node RETURN_PACKET, RECEIVE_PACKET, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection RETURN_PACKET + +The RETURN_PACKET component of the user-provided MPCI +layer is called when RTEMS needs to release a packet to the free +packet buffer pool. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_return_packet( + rtems_packet_prefix *packet +); +@end group +@end example + +where packet is the address of a packet. If the +packet cannot be successfully returned, the fatal error manager +should be invoked. + +@ifinfo +@node RECEIVE_PACKET, SEND_PACKET, RETURN_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection RECEIVE_PACKET + +The RECEIVE_PACKET component of the user-provided +MPCI layer is called when RTEMS needs to obtain a packet which +has previously arrived. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_receive_packet( + rtems_packet_prefix **packet +); +@end group +@end example + +where packet is a pointer to the address of a packet +to place the message from another node. If a message is +available, then packet will contain the address of the message +from another node. If no messages are available, this entry +packet should contain NULL. + +@ifinfo +@node SEND_PACKET, Supporting Heterogeneous Environments, RECEIVE_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection SEND_PACKET + +The SEND_PACKET component of the user-provided MPCI +layer is called when RTEMS needs to send a packet containing a +message to another node. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_send_packet( + rtems_unsigned32 node, + rtems_packet_prefix **packet +); +@end group +@end example + +where node is the node number of the destination and packet is the +address of a packet which containing a message. If the packet cannot +be successfully sent, the fatal error manager should be invoked. + +If node is set to zero, the packet is to be +broadcasted to all other nodes in the system. Although some +MPCI layers will be built upon hardware which support a +broadcast mechanism, others may be required to generate a copy +of the packet for each node in the system. + +Many MPCI layers use the packet_length field of the MP_packet_prefix +of the packet to avoid sending unnecessary data. This is especially +useful if the media connecting the nodes is relatively slow. + +The to_convert field of the MP_packet_prefix portion of the packet indicates +how much of the packet (in unsigned32's) may require conversion in a +heterogeneous system. + +@ifinfo +@node Supporting Heterogeneous Environments, Multiprocessing Manager Operations, SEND_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection Supporting Heterogeneous Environments + +Developing an MPCI layer for a heterogeneous system +requires a thorough understanding of the differences between the +processors which comprise the system. One difficult problem is +the varying data representation schemes used by different +processor types. The most pervasive data representation problem +is the order of the bytes which compose a data entity. +Processors which place the least significant byte at the +smallest address are classified as little endian processors. +Little endian byte-ordering is shown below: + + +@example +@group ++---------------+----------------+---------------+----------------+ +| | | | | +| Byte 3 | Byte 2 | Byte 1 | Byte 0 | +| | | | | ++---------------+----------------+---------------+----------------+ +@end group +@end example + +Conversely, processors which place the most +significant byte at the smallest address are classified as big +endian processors. Big endian byte-ordering is shown below: + +@example +@group ++---------------+----------------+---------------+----------------+ +| | | | | +| Byte 0 | Byte 1 | Byte 2 | Byte 3 | +| | | | | ++---------------+----------------+---------------+----------------+ +@end group +@end example + +Unfortunately, sharing a data structure between big +endian and little endian processors requires translation into a +common endian format. An application designer typically chooses +the common endian format to minimize conversion overhead. + +Another issue in the design of shared data structures +is the alignment of data structure elements. Alignment is both +processor and compiler implementation dependent. For example, +some processors allow data elements to begin on any address +boundary, while others impose restrictions. Common restrictions +are that data elements must begin on either an even address or +on a long word boundary. Violation of these restrictions may +cause an exception or impose a performance penalty. + +Other issues which commonly impact the design of +shared data structures include the representation of floating +point numbers, bit fields, decimal data, and character strings. +In addition, the representation method for negative integers +could be one's or two's complement. These factors combine to +increase the complexity of designing and manipulating data +structures shared between processors. + +RTEMS addressed these issues in the design of the +packets used to communicate between nodes. The RTEMS packet +format is designed to allow the MPCI layer to perform all +necessary conversion without burdening the developer with the +details of the RTEMS packet format. As a result, the MPCI layer +must be aware of the following: + +@itemize @bullet +@item All packets must begin on a four byte boundary. + +@item Packets are composed of both RTEMS and application data. +All RTEMS data is treated as thirty-two (32) bit unsigned +quantities and is in the first MINIMUM_UNSIGNED32S_TO_CONVERT +thirty-two (32) quantities of the packet. + +@item The RTEMS data component of the packet must be in native +endian format. Endian conversion may be performed by either the +sending or receiving MPCI layer. + +@item RTEMS makes no assumptions regarding the application +data component of the packet. +@end itemize + +@ifinfo +@node Multiprocessing Manager Operations, Announcing a Packet, Supporting Heterogeneous Environments, Multiprocessing Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Packet:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Packet, Multiprocessing Manager Directives, Multiprocessing Manager Operations, Multiprocessing Manager Operations +@end ifinfo +@subsection Announcing a Packet + +The multiprocessing_announce directive is called by +the MPCI layer to inform RTEMS that a packet has arrived from +another node. This directive can be called from an interrupt +service routine or from within a polling routine. + +@ifinfo +@node Multiprocessing Manager Directives, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Announcing a Packet, Multiprocessing Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet:: +@end menu +@end ifinfo + +This section details the additional directives +required to support RTEMS in a multiprocessor configuration. 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 MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Directive Status Codes, Multiprocessing Manager Directives, Multiprocessing Manager Directives +@end ifinfo +@subsection MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet + +@subheading CALLING SEQUENCE: + +@example +void rtems_multiprocessing_announce( void ); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive informs RTEMS that a multiprocessing +communications packet has arrived from another node. This +directive is called by the user-provided MPCI, and is only used +in multiprocessor configurations. + +@subheading NOTES: + +This directive is typically called from an ISR. + +This directive will almost certainly cause the +calling task to be preempted. + +This directive does not generate activity on remote nodes. diff --git a/doc/user/msg.t b/doc/user/msg.t new file mode 100644 index 0000000000..832b69ef2e --- /dev/null +++ b/doc/user/msg.t @@ -0,0 +1,714 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Message Manager, Message Manager Introduction, SEMAPHORE_RELEASE - Release a semaphore, Top +@end ifinfo +@chapter Message Manager +@ifinfo +@menu +* Message Manager Introduction:: +* Message Manager Background:: +* Message Manager Operations:: +* Message Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Message Manager Introduction, Message Manager Background, Message Manager, Message Manager +@end ifinfo +@section Introduction + +The message manager provides communication and +synchronization capabilities using RTEMS message queues. The +directives provided by the message manager are: + +@itemize @bullet +@item @code{message_queue_create} - Create a queue +@item @code{message_queue_ident} - Get ID of a queue +@item @code{message_queue_delete} - Delete a queue +@item @code{message_queue_send} - Put message at rear of a queue +@item @code{message_queue_urgent} - Put message at front of a queue +@item @code{message_queue_broadcast} - Broadcast N messages to a queue +@item @code{message_queue_receive} - Receive message from a queue +@item @code{message_queue_flush} - Flush all messages on a queue +@end itemize + +@ifinfo +@node Message Manager Background, Messages, Message Manager Introduction, Message Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Messages:: +* Message Queues:: +* Building a Message Queue's Attribute Set:: +* Building a MESSAGE_QUEUE_RECEIVE Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Messages, Message Queues, Message Manager Background, Message Manager Background +@end ifinfo +@subsection Messages + +A message is a variable length buffer where +information can be stored to support communication. The length +of the message and the information stored in that message are +user-defined and can be actual data, pointer(s), or empty. + +@ifinfo +@node Message Queues, Building a Message Queue's Attribute Set, Messages, Message Manager Background +@end ifinfo +@subsection Message Queues + +A message queue permits the passing of messages among +tasks and ISRs. Message queues can contain a variable number of +messages. Normally messages are sent to and received from the +queue in FIFO order using the message_queue_send directive. +However, the message_queue_urgent directive can be used to place +messages at the head of a queue in LIFO order. + +Synchronization can be accomplished when a task can +wait for a message to arrive at a queue. Also, a task may poll +a queue for the arrival of a message. + +The maximum length message which can be sent is set +on a per message queue basis. + +@ifinfo +@node Building a Message Queue's Attribute Set, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Queues, Message Manager Background +@end ifinfo +@subsection Building a Message Queue's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid message +queue attributes is provided in the following table: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item LOCAL - local message queue (default) +@item GLOBAL - global message queue +@end itemize + + + +An attribute listed as a default is not required to +appear in the attribute list, although it is a good programming +practice to specify default attributes. If all defaults are +desired, the attribute DEFAULT_ATTRIBUTES should be specified on +this call. + +This example demonstrates the attribute_set parameter +needed to create a local message queue with the task priority +waiting queue discipline. The attribute_set parameter to the +message_queue_create directive could be either PRIORITY or LOCAL +| PRIORITY. The attribute_set parameter can be set to PRIORITY +because LOCAL is the default for all created message queues. If +a similar message queue were to be known globally, then the +attribute_set parameter would be GLOBAL | PRIORITY. + +@ifinfo +@node Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager Operations, Building a Message Queue's Attribute Set, Message Manager Background +@end ifinfo +@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +message_queue_receive directive are listed in the following +table: + +@itemize @bullet +@item WAIT - task will wait for a message (default) +@item NO_WAIT - task should not wait +@end itemize + +An option listed as a default is not required to +appear in the option OR list, although it is a good programming +practice to specify default options. If all defaults are +desired, the option DEFAULT_OPTIONS should be specified on this +call. + +This example demonstrates the option parameter needed +to poll for a message to arrive. The option parameter passed to +the message_queue_receive directive should be NO_WAIT. + +@ifinfo +@node Message Manager Operations, Creating a Message Queue, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Message Queue:: +* Obtaining Message Queue IDs:: +* Receiving a Message:: +* Sending a Message:: +* Broadcasting a Message:: +* Deleting a Message Queue:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Message Queue, Obtaining Message Queue IDs, Message Manager Operations, Message Manager Operations +@end ifinfo +@subsection Creating a Message Queue + +The message_queue_create directive creates a message +queue with the user-defined name. The user specifies the +maximum message size and maximum number of messages which can be +placed in the message queue at one time. The user may select +FIFO or task priority as the method for placing waiting tasks in +the task wait queue. RTEMS allocates a Queue Control Block +(QCB) from the QCB free list to maintain the newly created queue +as well as memory for the message buffer pool associated with +this message queue. RTEMS also generates a message queue ID +which is returned to the calling task. + +For GLOBAL message queues, the maximum message size +is effectively limited to the longest message which the MPCI is +capable of transmitting. + +@ifinfo +@node Obtaining Message Queue IDs, Receiving a Message, Creating a Message Queue, Message Manager Operations +@end ifinfo +@subsection Obtaining Message Queue IDs + +When a message queue is created, RTEMS generates a +unique message queue ID. The message queue ID may be obtained +by either of two methods. First, as the result of an invocation +of the message_queue_create directive, the queue ID is stored in +a user provided location. Second, the queue ID may be obtained +later using the message_queue_ident directive. The queue ID is +used by other message manager directives to access this message +queue. + +@ifinfo +@node Receiving a Message, Sending a Message, Obtaining Message Queue IDs, Message Manager Operations +@end ifinfo +@subsection Receiving a Message + +The message_queue_receive directive attempts to +retrieve a message from the specified message queue. If at +least one message is in the queue, then the message is removed +from the queue, copied to the caller's message buffer, and +returned immediately along with the length of the message. When +messages are unavailable, one of the following situations +applies: + +@itemize @bullet +@item By default, the calling task will wait forever for the +message to arrive. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the period the task will +wait before returning with an error status. +@end itemize + +If the task waits for a message, then it is placed in +the message queue's task wait queue in either FIFO or task +priority order. All tasks waiting on a message queue are +returned an error code when the message queue is deleted. + +@ifinfo +@node Sending a Message, Broadcasting a Message, Receiving a Message, Message Manager Operations +@end ifinfo +@subsection Sending a Message + +Messages can be sent to a queue with the +message_queue_send and message_queue_urgent directives. These +directives work identically when tasks are waiting to receive a +message. A task is removed from the task waiting queue, +unblocked, and the message is copied to a waiting task's +message buffer. + +When no tasks are waiting at the queue, +message_queue_send places the message at the rear of the message +queue, while message_queue_urgent places the message at the +front of the queue. The message is copied to a message buffer +from this message queue's buffer pool and then placed in the +message queue. Neither directive can successfully send a +message to a message queue which has a full queue of pending +messages. + +@ifinfo +@node Broadcasting a Message, Deleting a Message Queue, Sending a Message, Message Manager Operations +@end ifinfo +@subsection Broadcasting a Message + +The message_queue_broadcast directive sends the same +message to every task waiting on the specified message queue as +an atomic operation. The message is copied to each waiting +task's message buffer and each task is unblocked. The number of +tasks which were unblocked is returned to the caller. + +@ifinfo +@node Deleting a Message Queue, Message Manager Directives, Broadcasting a Message, Message Manager Operations +@end ifinfo +@subsection Deleting a Message Queue + +The message_queue_delete directive removes a message +queue from the system and frees its control block as well as the +memory associated with this message queue's message buffer pool. +A message queue can be deleted by any local task that knows the +message queue's ID. As a result of this directive, all tasks +blocked waiting to receive a message from the message queue will +be readied and returned a status code which indicates that the +message queue was deleted. Any subsequent references to the +message queue's name and ID are invalid. Any messages waiting +at the message queue are also deleted and deallocated. + +@ifinfo +@node Message Manager Directives, MESSAGE_QUEUE_CREATE - Create a queue, Deleting a Message Queue, Message Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* MESSAGE_QUEUE_CREATE - Create a queue:: +* MESSAGE_QUEUE_IDENT - Get ID of a queue:: +* MESSAGE_QUEUE_DELETE - Delete a queue:: +* MESSAGE_QUEUE_SEND - Put message at rear of a queue:: +* MESSAGE_QUEUE_URGENT - Put message at front of a queue:: +* MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue:: +* MESSAGE_QUEUE_RECEIVE - Receive message from a queue:: +* MESSAGE_QUEUE_FLUSH - Flush all messages on a queue:: +@end menu +@end ifinfo + +This section details the message 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 MESSAGE_QUEUE_CREATE - Create a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_CREATE - Create a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_create( + rtems_name name, + rtems_unsigned32 count, + rtems_unsigned32 max_message_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_NUMBER} - invalid message count@* +@code{INVALID_SIZE} - invalid message size@* +@code{TOO_MANY} - too many queues created@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a message queue which resides +on the local node with the user-defined name specified in name. +For control and maintenance of the queue, RTEMS allocates and +initializes a QCB. Memory is allocated from the RTEMS Workspace +for the specified count of messages, each of max_message_size +bytes in length. The RTEMS-assigned queue id, returned in id, +is used to access the message queue. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a message to be serviced according to task priority. +When FIFO is specified, waiting tasks are serviced in First +In-First Out order. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following message queue attribute constants are +defined by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item LOCAL - local message queue (default) +@item GLOBAL - global message queue +@end itemize + +Message queues should not be made global unless +remote tasks must interact with the created message queue. This +is to avoid the system overhead incurred by the creation of a +global message queue. When a global message queue is created, +the message queue's name and id must be transmitted to every +node in the system for insertion in the local copy of the global +object table. + +For GLOBAL message queues, the maximum message size +is effectively limited to the longest message which the MPCI is +capable of transmitting. + +The total number of global objects, including message +queues, is limited by the maximum_global_objects field in the +configuration table. + +@page +@ifinfo +@node MESSAGE_QUEUE_IDENT - Get ID of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_CREATE - Create a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue identified successfully@* +@code{INVALID_NAME} - queue name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the queue id associated with +the queue name specified in name. If the queue name is not +unique, then the queue id will match one of the queues with that +name. However, this queue id is not guaranteed to correspond to +the desired queue. The queue id is used with other message +related directives to access the message queue. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the message queues exported +by the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_DELETE - Delete a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue deleted successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue + +@subheading DESCRIPTION: + +This directive deletes the message queue specified by +id. As a result of this directive, all tasks blocked waiting to +receive a message from this queue will be readied and returned a +status code which indicates that the message queue was deleted. +If no tasks are waiting, but the queue contains messages, then +RTEMS returns these message buffers back to the system message +buffer pool. The QCB for this queue as well as the memory for +the message buffers is reclaimed by RTEMS. + +@subheading NOTES: + +The calling task will be preempted if its preemption +mode is enabled and one or more local tasks with a higher +priority than the calling task are waiting on the deleted queue. +The calling task will NOT be preempted if the tasks that are +waiting are remote tasks. + +The calling task does not have to be the task that +created the queue, although the task and queue must reside on +the same node. + +When the queue is deleted, any messages in the queue +are returned to the free message buffer pool. Any information +stored in those messages is lost. + +When a global message queue is deleted, the message +queue id must be transmitted to every node in the system for +deletion from the local copy of the global object table. + +Proxies, used to represent remote tasks, are +reclaimed when the message queue is deleted. + +@page +@ifinfo +@node MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_send( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message sent successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size@* +@code{UNSATISFIED} - out of message buffers@* +@code{TOO_MANY} - queue's limit has been reached + +@subheading DESCRIPTION: + +This directive sends the message buffer of size bytes +in length to the queue specified by id. If a task is waiting at +the queue, then the message is copied to the waiting task's +buffer and the task is unblocked. If no tasks are waiting at the +queue, then the message is copied to a message buffer which is +obtained from this message queue's message buffer pool. The +message buffer is then placed at the rear of the queue. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending a message to a global message queue which +does not reside on the local node will generate a request to the +remote node to post the message on the specified message queue. + +If the task to be unblocked resides on a different +node from the message queue, then the message is forwarded to +the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_urgent( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message sent successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size@* +@code{UNSATISFIED} - out of message buffers@* +@code{TOO_MANY} - queue's limit has been reached + +@subheading DESCRIPTION: + +This directive sends the message buffer of size bytes +in length to the queue specified by id. If a task is waiting on +the queue, then the message is copied to the task's buffer and +the task is unblocked. If no tasks are waiting on the queue, +then the message is copied to a message buffer which is obtained +from this message queue's message buffer pool. The message +buffer is then placed at the front of the queue. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending a message to a global message queue which +does not reside on the local node will generate a request +telling the remote node to post the message on the specified +message queue. + +If the task to be unblocked resides on a different +node from the message queue, then the message is forwarded to +the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + void *buffer, + rtems_unsigned32 size, + rtems_unsigned32 *count +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message broadcasted successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size + +@subheading DESCRIPTION: + +This directive causes all tasks that are waiting at +the queue specified by id to be unblocked and sent the message +contained in buffer. Before a task is unblocked, the message +buffer of size byes in length is copied to that task's message +buffer. The number of tasks that were unblocked is returned in +count. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +The execution time of this directive is directly +related to the number of tasks waiting on the message queue, +although it is more efficient than the equivalent number of +invocations of message_queue_send. + +Broadcasting a message to a global message queue +which does not reside on the local node will generate a request +telling the remote node to broadcast the message to the +specified message queue. + +When a task is unblocked which resides on a different +node from the message queue, a copy of the message is forwarded +to the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + rtems_unsigned32 *size, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message received successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{UNSATISFIED} - queue is empty@* +@code{TIMEOUT} - timed out waiting for message@* +@code{OBJECT_WAS_DELETED} - queue deleted while waiting + +@subheading DESCRIPTION: + +This directive receives a message from the message +queue specified in id. The WAIT and NO_WAIT options of the +options parameter allow the calling task to specify whether to +wait for a message to become available or return immediately. +For either option, if there is at least one message in the +queue, then it is copied to buffer, size is set to return the +length of the message in bytes, and this directive returns +immediately with a successful return code. + +If the calling task chooses to return immediately and +the queue is empty, then a status code indicating this condition +is returned. If the calling task chooses to wait at the message +queue and the queue is empty, then the calling task is placed on +the message wait queue and blocked. If the queue was created +with the PRIORITY option specified, then the calling task is +inserted into the wait queue according to its priority. But, if +the queue was created with the FIFO option specified, then the +calling task is placed at the rear of the wait queue. + +A task choosing to wait at the queue can optionally +specify a timeout value in the timeout parameter. The timeout +parameter specifies the maximum interval to wait before the +calling task desires to be unblocked. If it is set to +NO_TIMEOUT, then the calling task will wait forever. + +@subheading NOTES: + +The following message receive option constants are +defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for a message (default) +@item NO_WAIT - task should not wait +@end itemize + + +Receiving a message from a global message queue which +does not reside on the local node will generate a request to the +remote node to obtain a message from the specified message +queue. If no message is available and WAIT was specified, then +the task must be blocked until a message is posted. A proxy is +allocated on the remote node to represent the task until the +message is posted. + +@page +@ifinfo +@node MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Event Manager, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_flush( + rtems_id id, + rtems_unsigned32 *count +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message received successfully@* +@code{INVALID_ID} - invalid queue id + +@subheading DESCRIPTION: + +This directive removes all pending messages from the +specified queue id. The number of messages removed is returned +in count. If no messages are present on the queue, count is set +to zero. + +@subheading NOTES: + +Flushing all messages on a global message queue which +does not reside on the local node will generate a request to the +remote node to actually flush the specified message queue. + + + diff --git a/doc/user/overview.t b/doc/user/overview.t new file mode 100644 index 0000000000..a1c4d4ef01 --- /dev/null +++ b/doc/user/overview.t @@ -0,0 +1,578 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c This chapter is missing the following figures: +@c +@c Figure 1-1 RTEMS Application Architecture +@c Figure 1-2 RTEMS Internal Architecture +@c + +@ifinfo +@node Overview, Overview Introduction, Preface, Top +@end ifinfo +@chapter Overview +@ifinfo +@menu +* Overview Introduction:: +* Overview Real-time Application Systems:: +* Overview Real-time Executive:: +* Overview RTEMS Application Architecture:: +* Overview RTEMS Internal Architecture:: +* Overview User Customization and Extensibility:: +* Overview Portability:: +* Overview Memory Requirements:: +* Overview Audience:: +* Overview Conventions:: +* Overview Manual Organization:: +@end menu +@end ifinfo + +@ifinfo +@node Overview Introduction, Overview Real-time Application Systems, Overview, Overview +@end ifinfo +@section Introduction + +RTEMS, Real-Time Executive for Multiprocessor Systems, is a +real-time executive (kernel) which provides a high performance +environment for embedded military applications including the +following features: + +@itemize @bullet +@item multitasking capabilities +@item homogeneous and heterogeneous multiprocessor systems +@item event-driven, priority-based, preemptive scheduling +@item optional rate monotonic scheduling +@item intertask communication and synchronization +@item priority inheritance +@item responsive interrupt management +@item dynamic memory allocation +@item high level of user configurability +@end itemize + +This manual describes the usage of RTEMS for +applications written in the C programming language. Those +implementation details that are processor dependent are provided +in the C Applications Supplement documents. A supplement +document which addresses specific architectural issues that +affect RTEMS is provided for each processor type that is +supported. + +@ifinfo +@node Overview Real-time Application Systems, Overview Real-time Executive, Overview Introduction, Overview +@end ifinfo +@section Real-time Application Systems + +Real-time application systems are a special class of +computer applications. They have a complex set of +characteristics that distinguish them from other software +problems. Generally, they must adhere to more rigorous +requirements. The correctness of the system depends not only on +the results of computations, but also on the time at which the +results are produced. The most important and complex +characteristic of real-time application systems is that they +must receive and respond to a set of external stimuli within +rigid and critical time constraints referred to as deadlines. +Systems can be buried by an avalanche of interdependent, +asynchronous or cyclical event streams. + +Deadlines can be further characterized as either hard +or soft based upon the value of the results when produced after +the deadline has passed. A deadline is hard if the results have +no value or if their use will result in a catastrophic event. +In contrast, results which are produced after a soft deadline +may have some value. + +Another distinguishing requirement of real-time +application systems is the ability to coordinate or manage a +large number of concurrent activities. Since software is a +synchronous entity, this presents special problems. One +instruction follows another in a repeating synchronous cycle. +Even though mechanisms have been developed to allow for the +processing of external asynchronous events, the software design +efforts required to process and manage these events and tasks +are growing more complicated. + +The design process is complicated further by +spreading this activity over a set of processors instead of a +single processor. The challenges associated with designing and +building real-time application systems become very complex when +multiple processors are involved. New requirements such as +interprocessor communication channels and global resources that +must be shared between competing processors are introduced. The +ramifications of multiple processors complicate each and every +characteristic of a real-time system. + +@ifinfo +@node Overview Real-time Executive, Overview RTEMS Application Architecture, Overview Real-time Application Systems, Overview +@end ifinfo +@section Real-time Executive + +Fortunately, real-time operating systems or real-time +executives serve as a cornerstone on which to build the +application system. A real-time multitasking executive allows +an application to be cast into a set of logical, autonomous +processes or tasks which become quite manageable. Each task is +internally synchronous, but different tasks execute +independently, resulting in an asynchronous processing stream. +Tasks can be dynamically paused for many reasons resulting in a +different task being allowed to execute for a period of time. +The executive also provides an interface to other system +components such as interrupt handlers and device drivers. +System components may request the executive to allocate and +coordinate resources, and to wait for and trigger synchronizing +conditions. The executive system calls effectively extend the +CPU instruction set to support efficient multitasking. By +causing tasks to travel through well-defined state transitions, +system calls permit an application to demand-switch between +tasks in response to real-time events. + +By proper grouping of responses to stimuli into +separate tasks, a system can now asynchronously switch between +independent streams of execution, directly responding to +external stimuli as they occur. This allows the system design +to meet critical performance specifications which are typically +measured by guaranteed response time and transaction throughput. +The multiprocessor extensions of RTEMS provide the features +necessary to manage the extra requirements introduced by a +system distributed across several processors. It removes the +physical barriers of processor boundaries from the world of the +system designer, enabling more critical aspects of the system to +receive the required attention. Such a system, based on an +efficient real-time, multiprocessor executive, is a more +realistic model of the outside world or environment for which it +is designed. As a result, the system will always be more +logical, efficient, and reliable. + +By using the directives provided by RTEMS, the +real-time applications developer is freed from the problem of +controlling and synchronizing multiple tasks and processors. In +addition, one need not develop, test, debug, and document +routines to manage memory, pass messages, or provide mutual +exclusion. The developer is then able to concentrate solely on +the application. By using standard software components, the +time and cost required to develop sophisticated real-time +applications is significantly reduced. + +@ifinfo +@node Overview RTEMS Application Architecture, Overview RTEMS Internal Architecture, Overview Real-time Executive, Overview +@end ifinfo +@section RTEMS Application Architecture + +One important design goal of RTEMS was to provide a +bridge between two critical layers of typical real-time systems. +As shown in the following figure, RTEMS serves as a buffer between the +project dependent application code and the target hardware. +Most hardware dependencies for real-time applications can be +localized to the low level device drivers. The RTEMS I/O +interface manager provides an efficient tool for incorporating +these hardware dependencies into the system while simultaneously +providing a general mechanism to the application code that +accesses them. A well designed real-time system can benefit +from this architecture by building a rich library of standard +application components which can be used repeatedly in other +real-time projects. + +@ifset use-ascii +@example +@group + +-----------------------------------------------------------+ + | Application Dependent Software | + | +----------------------------------------+ | + | | Standard Application Components | | + | | +-------------+---+ | + | +---+-----------+ | | | + | | Board Support | | RTEMS | | + | | Package | | | | + +----+---------------+--------------+-----------------+-----| + | Target Hardware | + +-----------------------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#\cr +\multispan{17}\hrulefill\cr +% to force all columns to desired width +& \enskip && \enskip && \enskip && \enskip && + \enskip && \enskip &&\enskip &&\enskip &\cr +% For debugging columns +%& \enskip 0&& \enskip 1&& \enskip 2&& \enskip 3&& +% \enskip 4&& \enskip 5&&\enskip 6&&\enskip 7&\cr +\strut&\multispan{15}&\cr +&\multispan{15}\hfil Application Dependent Software\hfil&\cr +\strut&\multispan{15}&\cr +&\multispan{2}&&\multispan{8}\hrulefill &\multispan{2}&\cr +\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr +&\multispan{2}&&&\multispan{7}\hfil Standard Application Components\hfil& + &\multispan{2}&&\cr +\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr +&&\multispan{5}\hrulefill&&\multispan{7}\hrulefill&&\cr +\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr +&&&\multispan{3}\hfil Device\hfil&&&&\multispan{5}\hfil RTEMS\hfil&&&\cr +&&&\multispan{3}\hfil Drivers\hfil&&&&\multispan{5}&&&\cr +\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr +\multispan{17}\hrulefill\cr +\strut&\multispan{15}&\cr +&\multispan{15}\hfil Target Hardware\hfil&\cr +\strut&\multispan{15}&\cr +\multispan{17}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +RTEMS Application Architecture +@end html +@end ifset + +@ifinfo +@node Overview RTEMS Internal Architecture, Overview User Customization and Extensibility, Overview RTEMS Application Architecture, Overview +@end ifinfo +@section RTEMS Internal Architecture + +RTEMS can be viewed as a set of layered components that work in +harmony to provide a set of services to a real-time application +system. The executive interface presented to the application is +formed by grouping directives into logical sets called resource managers. +Functions utilized by multiple managers such as scheduling, +dispatching, and object management are provided in the executive +core. The executive core depends on a small set of CPU dependent routines. +Together these components provide a powerful run time +environment that promotes the development of efficient real-time +application systems. The following figure illustrates this organization: + +@ifset use-ascii +@example +@group + +-----------------------------------------------+ + | RTEMS Executive Interface | + +-----------------------------------------------+ + | RTEMS Core | + +-----------------------------------------------+ + | CPU Dependent Code | + +-----------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@c for now use the ascii version +@example +@group + +-----------------------------------------------+ + | RTEMS Executive Interface | + +-----------------------------------------------+ + | RTEMS Core | + +-----------------------------------------------+ + | CPU Dependent Code | + +-----------------------------------------------+ +@end group +@end example +@tex +@end tex +@end ifset + +@ifset use-html +@html +RTEMS Architecture +@end html +@end ifset +Subsequent chapters present a detailed description of the capabilities +provided by each of the following RTEMS managers: + +@itemize @bullet +@item initialization +@item task +@item interrupt +@item clock +@item timer +@item semaphore +@item message +@item event +@item signal +@item partition +@item region +@item dual ported memory +@item I/O +@item fatal error +@item rate monotonic +@item user extensions +@item multiprocessing +@end itemize + +@ifinfo +@node Overview User Customization and Extensibility, Overview Portability, Overview RTEMS Internal Architecture, Overview +@end ifinfo +@section User Customization and Extensibility + +As thirty-two bit microprocessors have decreased in +cost, they have become increasingly common in a variety of +embedded systems. A wide range of custom and general-purpose +processor boards are based on various thirty-two bit processors. +RTEMS was designed to make no assumptions concerning the +characteristics of individual microprocessor families or of +specific support hardware. In addition, RTEMS allows the system +developer a high degree of freedom in customizing and extending +its features. + +RTEMS assumes the existence of a supported +microprocessor and sufficient memory for both RTEMS and the +real-time application. Board dependent components such as +clocks, interrupt controllers, or I/O devices can be easily +integrated with RTEMS. The customization and extensibility +features allow RTEMS to efficiently support as many environments +as possible. + +@ifinfo +@node Overview Portability, Overview Memory Requirements, Overview User Customization and Extensibility, Overview +@end ifinfo +@section Portability + +The issue of portability was the major factor in the +creation of RTEMS. Since RTEMS is designed to isolate the +hardware dependencies in the specific board support packages, +the real-time application should be easily ported to any other +processor. The use of RTEMS allows the development of real-time +applications which can be completely independent of a particular +microprocessor architecture. + +@ifinfo +@node Overview Memory Requirements, Overview Audience, Overview Portability, Overview +@end ifinfo +@section Memory Requirements + +Since memory is a critical resource in many real-time +embedded systems, RTEMS was specifically designed to allow +unused managers to be excluded from the run-time environment. +This allows the application designer the flexibility to tailor +RTEMS to most efficiently meet system requirements while still +satisfying even the most stringent memory constraints. As a +result, the size of the RTEMS executive is application +dependent. A worksheet is provided in the Memory Requirements +chapter of the C Applications Supplement document for a specific +target processor. The worksheet is used to calculate the memory +requirements of a custom RTEMS run-time environment. The +following managers may be optionally excluded: + +@itemize @bullet +@item clock +@item timer +@item semaphore +@item message +@item event +@item signal +@item partition +@item region +@item dual ported memory +@item I/O +@item rate monotonic +@item fatal error +@item multiprocessing +@end itemize + +RTEMS utilizes memory for both code and data space. +Although RTEMS' data space must be in RAM, its code space can be +located in either ROM or RAM. + +@ifinfo +@node Overview Audience, Overview Conventions, Overview Memory Requirements, Overview +@end ifinfo +@section Audience + +This manual was written for experienced real-time +software developers. Although some background is provided, it +is assumed that the reader is familiar with the concepts of task +management as well as intertask communication and +synchronization. Since directives, user related data +structures, and examples are presented in C, a basic +understanding of the C programming language is required to fully +understand the material presented. However, because of the +similarity of the Ada and C RTEMS implementations, users will +find that the use and behavior of the two implementations is +very similar. A working knowledge of the target processor is +helpful in understanding some of RTEMS' features. A thorough +understanding of the executive cannot be obtained without +studying the entire manual because many of RTEMS' concepts and +features are interrelated. Experienced RTEMS users will find +that the manual organization facilitates its use as a reference +document. + +@ifinfo +@node Overview Conventions, Overview Manual Organization, Overview Audience, Overview +@end ifinfo +@section Conventions + +The following conventions are used in this manual: + +@itemize @bullet +@item Significant words or phrases as well as all directive +names are printed in bold type. + +@item Items in bold capital letters are constants defined by +RTEMS. Each language interface provided by RTEMS includes a +file containing the standard set of constants, data types, and +structure definitions which can be incorporated into the user +application. + +@item A number of type definitions are provided by RTEMS and +can be found in rtems.h. + +@item The characters "0x" preceding a number indicates that +the number is in hexadecimal format. Any other numbers are +assumed to be in decimal format. +@end itemize + +@ifinfo +@node Overview Manual Organization, Key Concepts, Overview Conventions, Overview +@end ifinfo +@section Manual Organization + +This first chapter has presented the introductory and +background material for the RTEMS executive. The remaining +chapters of this manual present a detailed description of RTEMS +and the environment, including run time behavior, it creates for +the user. + +A chapter is dedicated to each manager and provides a +detailed discussion of each RTEMS manager and the directives +which it provides. The presentation format for each directive +includes the following sections: + +@itemize @bullet +@item Calling sequence +@item Directive status codes +@item Description +@item Notes +@end itemize + +The following provides an overview of the remainder +of this manual: + +@table @asis +@item Chapter 2 +Key Concepts: presents an +introduction to the ideas which are common across multiple RTEMS +managers. + +@item Chapter 3: +Initialization Manager: describes the functionality and directives +provided by the Initialization Manager. + +@item Chapter 4: +Task Manager: describes the functionality and directives provided +by the Task Manager. + +@item Chapter 5: +Interrupt Manager: describes the functionality and directives +provided by the Interrupt Manager. + +@item Chapter 6: +Clock Manager: describes the functionality and directives +provided by the Clock Manager. + +@item Chapter 7 +Timer Manager: describes the functionality and directives provided +by the Timer Manager. + +@item Chapter 8: +Semaphore Manager: describes the functionality and directives +provided by the Semaphore Manager. + +@item Chapter 9: +Message Manager: describes the functionality and directives +provided by the Message Manager. + +@item Chapter 10: +Event Manager: describes the +functionality and directives provided by the Event Manager. + +@item Chapter 11: +Signal Manager: describes the +functionality and directives provided by the Signal Manager. + +@item Chapter 12: +Partition Manager: describes the +functionality and directives provided by the Partition Manager. + +@item Chapter 13: +Region Manager: describes the +functionality and directives provided by the Region Manager. + +@item Chapter 14: +Dual-Ported Memory Manager: describes +the functionality and directives provided by the Dual-Ported +Memory Manager. + +@item Chapter 15: +I/O Manager: describes the +functionality and directives provided by the I/O Manager. + +@item Chapter 16: +Fatal Error Manager: describes the functionality and directives +provided by the Fatal Error Manager. + +@item Chapter 17: +Scheduling Concepts: details the RTEMS scheduling algorithm and +task state transitions. + +@item Chapter 18: +Rate Monotonic Manager: describes the functionality and directives +provided by the Rate Monotonic Manager. + +@item Chapter 19: +Board Support Packages: defines the +functionality required of user-supplied board support packages. + +@item Chapter 20: +User Extensions: shows the user how to +extend RTEMS to incorporate custom features. + +@item Chapter 21: +Configuring a System: details the process by which one tailors RTEMS +for a particular single-processor or multiprocessor application. + +@item Chapter 22: +Multiprocessing Manager: presents a +conceptual overview of the multiprocessing capabilities provided +by RTEMS as well as describing the Multiprocessing +Communications Interface Layer and Multiprocessing Manager +directives. + +@item Chapter 23: +Directive Status Codes: provides a definition of each of the +directive status codes referenced in this manual. + +@item Chapter 24: +Example Application: provides a template for simple RTEMS applications. + +@item Chapter 25: +Glossary: defines terms used throughout this manual. + +@end table + + diff --git a/doc/user/part.t b/doc/user/part.t new file mode 100644 index 0000000000..302f426497 --- /dev/null +++ b/doc/user/part.t @@ -0,0 +1,423 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Partition Manager, Partition Manager Introduction, SIGNAL_SEND - Send signal set to a task, Top +@end ifinfo +@chapter Partition Manager +@ifinfo +@menu +* Partition Manager Introduction:: +* Partition Manager Background:: +* Partition Manager Operations:: +* Partition Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Partition Manager Introduction, Partition Manager Background, Partition Manager, Partition Manager +@end ifinfo +@section Introduction + +The partition manager provides facilities to +dynamically allocate memory in fixed-size units. The directives +provided by the partition manager are: + +@itemize @bullet +@item @code{partition_create} - Create a partition +@item @code{partition_ident} - Get ID of a partition +@item @code{partition_delete} - Delete a partition +@item @code{partition_get_buffer} - Get buffer from a partition +@item @code{partition_return_buffer} - Return buffer to a partition +@end itemize + +@ifinfo +@node Partition Manager Background, Partition Manager Definitions, Partition Manager Introduction, Partition Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Partition Manager Definitions:: +* Building a Partition's Attribute Set:: +@end menu +@end ifinfo + +@ifinfo +@node Partition Manager Definitions, Building a Partition's Attribute Set, Partition Manager Background, Partition Manager Background +@end ifinfo +@subsection Partition Manager Definitions + +A partition is a physically contiguous memory area +divided into fixed-size buffers that can be dynamically +allocated and deallocated. + +Partitions are managed and maintained as a list of +buffers. Buffers are obtained from the front of the partition's +free buffer chain and returned to the rear of the same chain. +When a buffer is on the free buffer chain, RTEMS uses eight +bytes of each buffer as the free buffer chain. When a buffer is +allocated, the entire buffer is available for application use. +Therefore, modifying memory that is outside of an allocated +buffer could destroy the free buffer chain or the contents of an +adjacent allocated buffer. + +@ifinfo +@node Building a Partition's Attribute Set, Partition Manager Operations, Partition Manager Definitions, Partition Manager Background +@end ifinfo +@subsection Building a Partition's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid partition +attributes is provided in the following table: + +@itemize @bullet +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + + + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. The attribute_set parameter should be +GLOBAL to indicate that the partition is to be known globally. + +@ifinfo +@node Partition Manager Operations, Creating a Partition, Building a Partition's Attribute Set, Partition Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Partition:: +* Obtaining Partition IDs:: +* Acquiring a Buffer:: +* Releasing a Buffer:: +* Deleting a Partition:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Partition, Obtaining Partition IDs, Partition Manager Operations, Partition Manager Operations +@end ifinfo +@subsection Creating a Partition + +The partition_create directive creates a partition +with a user-specified name. The partition's name, starting +address, length and buffer size are all specified to the +partition_create directive. RTEMS allocates a Partition Control +Block (PTCB) from the PTCB free list. This data structure is +used by RTEMS to manage the newly created partition. The number +of buffers in the partition is calculated based upon the +specified partition length and buffer size, and returned to the +calling task along with a unique partition ID. + +@ifinfo +@node Obtaining Partition IDs, Acquiring a Buffer, Creating a Partition, Partition Manager Operations +@end ifinfo +@subsection Obtaining Partition IDs + +When a partition is created, RTEMS generates a unique +partition ID and assigned it to the created partition until it +is deleted. The partition ID may be obtained by either of two +methods. First, as the result of an invocation of the +partition_create directive, the partition ID is stored in a user +provided location. Second, the partition ID may be obtained +later using the partition_ident directive. The partition ID is +used by other partition manager directives to access this +partition. + +@ifinfo +@node Acquiring a Buffer, Releasing a Buffer, Obtaining Partition IDs, Partition Manager Operations +@end ifinfo +@subsection Acquiring a Buffer + +A buffer can be obtained by calling the +partition_get_buffer directive. If a buffer is available, then +it is returned immediately with a successful return code. +Otherwise, an unsuccessful return code is returned immediately +to the caller. Tasks cannot block to wait for a buffer to +become available. + +@ifinfo +@node Releasing a Buffer, Deleting a Partition, Acquiring a Buffer, Partition Manager Operations +@end ifinfo +@subsection Releasing a Buffer + +Buffers are returned to a partition's free buffer +chain with the partition_return_buffer directive. This +directive returns an error status code if the returned buffer +was not previously allocated from this partition. + +@ifinfo +@node Deleting a Partition, Partition Manager Directives, Releasing a Buffer, Partition Manager Operations +@end ifinfo +@subsection Deleting a Partition + +The partition_delete directive allows a partition to +be removed and returned to RTEMS. When a partition is deleted, +the PTCB for that partition is returned to the PTCB free list. +A partition with buffers still allocated cannot be deleted. Any +task attempting to do so will be returned an error status code. + +@ifinfo +@node Partition Manager Directives, PARTITION_CREATE - Create a partition, Deleting a Partition, Partition Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* PARTITION_CREATE - Create a partition:: +* PARTITION_IDENT - Get ID of a partition:: +* PARTITION_DELETE - Delete a partition:: +* PARTITION_GET_BUFFER - Get buffer from a partition:: +* PARTITION_RETURN_BUFFER - Return buffer to a partition:: +@end menu +@end ifinfo + +This section details the partition 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 PARTITION_CREATE - Create a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives, Partition Manager Directives +@end ifinfo +@subsection PARTITION_CREATE - Create a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_create( + rtems_name name, + void *starting_address, + rtems_unsigned32 length, + rtems_unsigned32 buffer_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many partitions created@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{INVALID_SIZE} - length or buffer size is 0@* +@code{INVALID_SIZE} - length is less than the buffer size@* +@code{INVALID_SIZE} - buffer size not a multiple of 4@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a partition of fixed size +buffers from a physically contiguous memory space which starts +at starting_address and is length bytes in size. Each allocated +buffer is to be of buffer_length in bytes. The assigned +partition id is returned in id. This partition id is used to +access the partition with other partition related directives. +For control and maintenance of the partition, RTEMS allocates a +PTCB from the local PTCB free pool and initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The starting_address and buffer_size parameters must +be multiples of four. + +Memory from the partition is not used by RTEMS to +store the Partition Control Block. + +The following partition attribute constants are +defined by RTEMS: + +@itemize @bullet +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + +The PTCB for a global partition is allocated on the +local node. The memory space used for the partition must reside +in shared memory. Partitions should not be made global unless +remote tasks must interact with the partition. This is to avoid +the overhead incurred by the creation of a global partition. +When a global partition is created, the partition's name and id +must be transmitted to every node in the system for insertion in +the local copy of the global object table. + +The total number of global objects, including +partitions, is limited by the maximum_global_objects field in +the Configuration Table. + +@page +@ifinfo +@node PARTITION_IDENT - Get ID of a partition, PARTITION_DELETE - Delete a partition, PARTITION_CREATE - Create a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_IDENT - Get ID of a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition identified successfully@* +@code{INVALID_NAME} - partition name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the partition id associated +with the partition name. If the partition name is not unique, +then the partition id will match one of the partitions with that +name. However, this partition id is not guaranteed to +correspond to the desired partition. The partition id is used +with other partition related directives to access the partition. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the partitions exported by +the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node PARTITION_DELETE - Delete a partition, PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_DELETE - Delete a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition deleted successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{RESOURCE_IN_USE} - buffers still in use@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote partition + +@subheading DESCRIPTION: + +This directive deletes the partition specified by id. +The partition cannot be deleted if any of its buffers are still +allocated. The PTCB for the deleted partition is reclaimed by +RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The calling task does not have to be the task that +created the partition. Any local task that knows the partition +id can delete the partition. + +When a global partition is deleted, the partition id +must be transmitted to every node in the system for deletion +from the local copy of the global object table. + +The partition must reside on the local node, even if +the partition was created with the GLOBAL option. + +@page +@ifinfo +@node PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_RETURN_BUFFER - Return buffer to a partition, PARTITION_DELETE - Delete a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_GET_BUFFER - Get buffer from a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - buffer obtained successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{UNSATISFIED} - all buffers are allocated + +@subheading DESCRIPTION: + +This directive allows a buffer to be obtained from +the partition specified in id. The address of the allocated +buffer is returned in buffer. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +All buffers begin on a four byte boundary. + +A task cannot wait on a buffer to become available. + +Getting a buffer from a global partition which does +not reside on the local node will generate a request telling the +remote node to allocate a buffer from the specified partition. + +@page +@ifinfo +@node PARTITION_RETURN_BUFFER - Return buffer to a partition, Region Manager, PARTITION_GET_BUFFER - Get buffer from a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - buffer returned successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{INVALID_ADDRESS} - buffer address not in partition + +@subheading DESCRIPTION: + +This directive returns the buffer specified by buffer +to the partition specified by id. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +Returning a buffer to a global partition which does +not reside on the local node will generate a request telling the +remote node to return the buffer to the specified partition. diff --git a/doc/user/preface.texi b/doc/user/preface.texi new file mode 100644 index 0000000000..c9154192a6 --- /dev/null +++ b/doc/user/preface.texi @@ -0,0 +1,173 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, Overview, Top, Top +@end ifinfo +@unnumbered Preface + +In recent years, the cost required to develop a +software product has increased significantly while the target +hardware costs have decreased. Now a larger portion of money is +expended in developing, using, and maintaining software. The +trend in computing costs is the complete dominance of software +over hardware costs. Because of this, it is necessary that +formal disciplines be established to increase the probability +that software is characterized by a high degree of correctness, +maintainability, and portability. In addition, these +disciplines must promote practices that aid in the consistent +and orderly development of a software system within schedule and +budgetary constraints. To be effective, these disciplines must +adopt standards which channel individual software efforts toward +a common goal. + +The push for standards in the software development +field has been met with various degrees of success. The +Microprocessor Operating Systems Interfaces (MOSI) effort has +experienced only limited success. As popular as the UNIX +operating system has grown, the attempt to develop a standard +interface definition to allow portable application development +has only recently begun to produce the results needed in this +area. Unfortunately, very little effort has been expended to +provide standards addressing the needs of the real-time +community. Several organizations have addressed this need +during recent years. + +The Real Time Executive Interface Definition (RTEID) +was developed by Motorola with technical input from Software +Components Group. RTEID was adopted by the VMEbus International +Trade Association (VITA) as a baseline draft for their proposed +standard multiprocessor, real-time executive interface, Open +Real-Time Kernel Interface Definition (ORKID). These two groups +are currently working together with the IEEE P1003.4 committee +to insure that the functionality of their proposed standards is +adopted as the real-time extensions to POSIX. + +This emerging standard defines an interface for the +development of real-time software to ease the writing of +real-time application programs that are directly portable across +multiple real-time executive implementations. This interface +includes both the source code interfaces and run-time behavior +as seen by a real-time application. It does not include the +details of how a kernel implements these functions. The +standard's goal is to serve as a complete definition of external +interfaces so that application code that conforms to these +interfaces will execute properly in all real-time executive +environments. With the use of a standards compliant executive, +routines that acquire memory blocks, create and manage message +queues, establish and use semaphores, and send and receive +signals need not be redeveloped for a different real-time +environment as long as the new environment is compliant with the +standard. Software developers need only concentrate on the +hardware dependencies of the real-time system. Furthermore, +most hardware dependencies for real-time applications can be +localized to the device drivers. + +A compliant executive provides simple and flexible +real-time multiprocessing. It easily lends itself to both +tightly-coupled and loosely-coupled configurations (depending on +the system hardware configuration). Objects such as tasks, +queues, events, signals, semaphores, and memory blocks can be +designated as global objects and accessed by any task regardless +of which processor the object and the accessing task reside. + +The acceptance of a standard for real-time executives +will produce the same advantages enjoyed from the push for UNIX +standardization by AT&T's System V Interface Definition and +IEEE's POSIX efforts. A compliant multiprocessing executive +will allow close coupling between UNIX systems and real-time +executives to provide the many benefits of the UNIX development +environment to be applied to real-time software development. +Together they provide the necessary laboratory environment to +implement real-time, distributed, embedded systems using a wide +variety of computer architectures. + +A study was completed in 1988, within the Research, +Development, and Engineering Center, U.S. Army Missile Command, +which compared the various aspects of the Ada programming +language as they related to the application of Ada code in +distributed and/or multiple processing systems. Several +critical conclusions were derived from the study. These +conclusions have a major impact on the way the Army develops +application software for embedded applications. These impacts +apply to both in-house software development and contractor +developed software. + +A conclusion of the analysis, which has been +previously recognized by other agencies attempting to utilize +Ada in a distributed or multiprocessing environment, is that the +Ada programming language does not adequately support +multiprocessing. Ada does provide a mechanism for +multi-tasking, however, this capability exists only for a single +processor system. The language also does not have inherent +capabilities to access global named variables, flags or program +code. These critical features are essential in order for data +to be shared between processors. However, these drawbacks do +have workarounds which are sometimes awkward and defeat the +intent of software maintainability and portability goals. + +Another conclusion drawn from the analysis, was that +the run time executives being delivered with the Ada compilers +were too slow and inefficient to be used in modern missile +systems. A run time executive is the core part of the run time +system code, or operating system code, that controls task +scheduling, input/output management and memory management. +Traditionally, whenever efficient executive (also known as +kernel) code was required by the application, the user developed +in-house software. This software was usually written in +assembly language for optimization. + +Because of this shortcoming in the Ada programming +language, software developers in research and development and +contractors for project managed systems, are mandated by +technology to purchase and utilize off-the-shelf third party +kernel code. The contractor, and eventually the Government, +must pay a licensing fee for every copy of the kernel code used +in an embedded system. + +The main drawback to this development environment is +that the Government does not own, nor has the right to modify +code contained within the kernel. V&V techniques in this +situation are more difficult than if the complete source code +were available. Responsibility for system failures due to faulty +software is yet another area to be resolved under this +environment. + +The Guidance and Control Directorate began a software +development effort to address these problems. A project to +develop an experimental run time kernel was begun that will +eliminate the major drawbacks of the Ada programming language +mentioned above. The Real Time Executive for Multiprocessor Systems +(RTEMS) provides full capabilities for management of tasks, +interrupts, time, and multiple processors in addition to those +features typical of generic operating systems. The code is +Government owned, so no licensing fees are necessary. RTEMS has +been implemented in both the Ada and C programming languages. +It has been ported to the Motorola MC68xxx family, the Intel +i80386 and above, and the Intel i80960 family. Support for +other processor families, including RISC, CISC, and DSP, is +planned. Since almost all of RTEMS is written in a high level +language, ports to additional processor families require minimal +effort. + +RTEMS multiprocessor support is capable of handling +either homogeneous or heterogeneous systems. The kernel +automatically compensates for architectural differences (byte +swapping, etc.) between processors. This allows a much easier +transition from one processor family to another without a major +system redesign. + +Since the proposed standards are still in draft form, +RTEMS cannot and does not claim compliance. However, the status +of the standard is being carefully monitored to guarantee that +RTEMS provides the functionality specified in the standard. +Once approved, RTEMS will be made compliant. + +This document is a detailed users guide for a +functionally compliant real-time multiprocessor executive. It +describes the user interface and run-time behavior of Release +@value{RTEMS-RELEASE} of the C implementation of RTEMS. + diff --git a/doc/user/region.t b/doc/user/region.t new file mode 100644 index 0000000000..22a24cfb95 --- /dev/null +++ b/doc/user/region.t @@ -0,0 +1,601 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Region Manager, Region Manager Introduction, PARTITION_RETURN_BUFFER - Return buffer to a partition, Top +@end ifinfo +@chapter Region Manager +@ifinfo +@menu +* Region Manager Introduction:: +* Region Manager Background:: +* Region Manager Operations:: +* Region Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Region Manager Introduction, Region Manager Background, Region Manager, Region Manager +@end ifinfo +@section Introduction + +The region manager provides facilities to dynamically +allocate memory in variable sized units. The directives +provided by the region manager are: + +@itemize @bullet +@item @code{region_create} - Create a region +@item @code{region_ident} - Get ID of a region +@item @code{region_delete} - Delete a region +@item @code{region_extend} - Add memory to a region +@item @code{region_get_segment} - Get segment from a region +@item @code{region_return_segment} - Return segment to a region +@item @code{region_get_segment_size} - Obtain size of a segment +@end itemize + +@ifinfo +@node Region Manager Background, Region Manager Definitions, Region Manager Introduction, Region Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Region Manager Definitions:: +* Building an Attribute Set:: +* Building an Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Region Manager Definitions, Building an Attribute Set, Region Manager Background, Region Manager Background +@end ifinfo +@subsection Region Manager Definitions + +A region makes up a physically contiguous memory +space with user-defined boundaries from which variable-sized +segments are dynamically allocated and deallocated. A segment +is a variable size section of memory which is allocated in +multiples of a user-defined page size. This page size is +required to be a multiple of four greater than or equal to four. +For example, if a request for a 350-byte segment is made in a +region with 256-byte pages, then a 512-byte segment is allocated. + +Regions are organized as doubly linked chains of +variable sized memory blocks. Memory requests are allocated +using a first-fit algorithm. If available, the requester +receives the number of bytes requested (rounded up to the next +page size). RTEMS requires some overhead from the region's +memory for each segment that is allocated. Therefore, an +application should only modify the memory of a segment that has +been obtained from the region. The application should NOT +modify the memory outside of any obtained segments and within +the region's boundaries while the region is currently active in +the system. + +Upon return to the region, the free block is +coalesced with its neighbors (if free) on both sides to produce +the largest possible unused block. + +@ifinfo +@node Building an Attribute Set, Building an Option Set, Region Manager Definitions, Region Manager Background +@end ifinfo +@subsection Building an Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid region +attributes is provided in the following table: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@end itemize + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. + +This example demonstrates the attribute_set parameter +needed to create a region with the task priority waiting queue +discipline. The attribute_set parameter to the region_create +directive should be PRIORITY. + +@ifinfo +@node Building an Option Set, Region Manager Operations, Building an Attribute Set, Region Manager Background +@end ifinfo +@subsection Building an Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +region_get_segment directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each option appears exactly once in +the component list. An option listed as a default is not +required to appear in the option list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for a segment. The option parameter passed to the +region_get_segment directive should be NO_WAIT. + +@ifinfo +@node Region Manager Operations, Creating a Region, Building an Option Set, Region Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Region:: +* Obtaining Region IDs:: +* Adding Memory to a Region:: +* Acquiring a Segment:: +* Releasing a Segment:: +* Obtaining the Size of a Segment:: +* Deleting a Region:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Region, Obtaining Region IDs, Region Manager Operations, Region Manager Operations +@end ifinfo +@subsection Creating a Region + +The region_create directive creates a region with the +user-defined name. The user may select FIFO or task priority as +the method for placing waiting tasks in the task wait queue. +RTEMS allocates a Region Control Block (RNCB) from the RNCB free +list to maintain the newly created region. RTEMS also generates +a unique region ID which is returned to the calling task. + +It is not possible to calculate the exact number of +bytes available to the user since RTEMS requires overhead for +each segment allocated. For example, a region with one segment +that is the size of the entire region has more available bytes +than a region with two segments that collectively are the size +of the entire region. This is because the region with one +segment requires only the overhead for one segment, while the +other region requires the overhead for two segments. + +Due to automatic coalescing, the number of segments +in the region dynamically changes. Therefore, the total +overhead required by RTEMS dynamically changes. + +@ifinfo +@node Obtaining Region IDs, Adding Memory to a Region, Creating a Region, Region Manager Operations +@end ifinfo +@subsection Obtaining Region IDs + +When a region is created, RTEMS generates a unique +region ID and assigns it to the created region until it is +deleted. The region ID may be obtained by either of two +methods. First, as the result of an invocation of the +region_create directive, the region ID is stored in a user +provided location. Second, the region ID may be obtained later +using the region_ident directive. The region ID is used by +other region manager directives to access this region. + +@ifinfo +@node Adding Memory to a Region, Acquiring a Segment, Obtaining Region IDs, Region Manager Operations +@end ifinfo +@subsection Adding Memory to a Region + +The region_extend directive may be used to add memory +to an existing region. The caller specifies the size in bytes +and starting address of the memory being added. + +NOTE: Please see the release notes or RTEMS source +code for information regarding restrictions on the location of +the memory being added in relation to memory already in the +region. + +@ifinfo +@node Acquiring a Segment, Releasing a Segment, Adding Memory to a Region, Region Manager Operations +@end ifinfo +@subsection Acquiring a Segment + +The region_get_segment directive attempts to acquire +a segment from a specified region. If the region has enough +available free memory, then a segment is returned successfully +to the caller. When the segment cannot be allocated, one of the +following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever to acquire the segment. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the interval the task will +wait before returning with an error status code. +@end itemize + +If the task waits for the segment, then it is placed +in the region's task wait queue in either FIFO or task priority +order. All tasks waiting on a region are returned an error when +the message queue is deleted. + +@ifinfo +@node Releasing a Segment, Obtaining the Size of a Segment, Acquiring a Segment, Region Manager Operations +@end ifinfo +@subsection Releasing a Segment + +When a segment is returned to a region by the +region_return_segment directive, it is merged with its +unallocated neighbors to form the largest possible segment. The +first task on the wait queue is examined to determine if its +segment request can now be satisfied. If so, it is given a +segment and unblocked. This process is repeated until the first +task's segment request cannot be satisfied. + +@ifinfo +@node Obtaining the Size of a Segment, Deleting a Region, Releasing a Segment, Region Manager Operations +@end ifinfo +@subsection Obtaining the Size of a Segment + +The region_get_segment_size directive returns the +size in bytes of the specified segment. The size returned +includes any "extra" memory included in the segment because of +rounding up to a page size boundary. + +@ifinfo +@node Deleting a Region, Region Manager Directives, Obtaining the Size of a Segment, Region Manager Operations +@end ifinfo +@subsection Deleting a Region + +A region can be removed from the system and returned +to RTEMS with the region_delete directive. When a region is +deleted, its control block is returned to the RNCB free list. A +region with segments still allocated is not allowed to be +deleted. Any task attempting to do so will be returned an +error. As a result of this directive, all tasks blocked waiting +to obtain a segment from the region will be readied and returned +a status code which indicates that the region was deleted. + +@ifinfo +@node Region Manager Directives, REGION_CREATE - Create a region, Deleting a Region, Region Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* REGION_CREATE - Create a region:: +* REGION_IDENT - Get ID of a region:: +* REGION_DELETE - Delete a region:: +* REGION_EXTEND - Add memory to a region:: +* REGION_GET_SEGMENT - Get segment from a region:: +* REGION_RETURN_SEGMENT - Return segment to a region:: +* REGION_GET_SEGMENT_SIZE - Obtain size of a segment:: +@end menu +@end ifinfo + +This section details the region 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 REGION_CREATE - Create a region, REGION_IDENT - Get ID of a region, Region Manager Directives, Region Manager Directives +@end ifinfo +@subsection REGION_CREATE - Create a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + rtems_unsigned32 length, + rtems_unsigned32 page_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{TOO_MANY} - too many regions created@* +@code{INVALID_SIZE} - invalid page size + +@subheading DESCRIPTION: + +This directive creates a region from a physically +contiguous memory space which starts at starting_address and is +length bytes long. Segments allocated from the region will be a +multiple of page_size bytes in length. The assigned region id +is returned in id. This region id is used as an argument to +other region related directives to access the region. + +For control and maintenance of the region, RTEMS +allocates and initializes an RNCB from the RNCB free pool. Thus +memory from the region is not used to store the RNCB. However, +some overhead within the region is required by RTEMS each time a +segment is constructed in the region. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a segment to be serviced according to task priority. +Specifying FIFO in attribute_set or selecting +DEFAULT_ATTRIBUTES will cause waiting tasks to be serviced in +First In-First Out order. + +The starting_address parameter must be aligned on a +four byte boundary. The page_size parameter must be a multiple +of four greater than or equal to four. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following region attribute constants are defined +by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@end itemize + +@page +@ifinfo +@node REGION_IDENT - Get ID of a region, REGION_DELETE - Delete a region, REGION_CREATE - Create a region, Region Manager Directives +@end ifinfo +@subsection REGION_IDENT - Get ID of a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region identified successfully@* +@code{INVALID_NAME} - region name not found + +@subheading DESCRIPTION: + +This directive obtains the region id associated with +the region name to be acquired. If the region name is not +unique, then the region id will match one of the regions with +that name. However, this region id is not guaranteed to +correspond to the desired region. The region id is used to +access this region in other region manager directives. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +@page +@ifinfo +@node REGION_DELETE - Delete a region, REGION_EXTEND - Add memory to a region, REGION_IDENT - Get ID of a region, Region Manager Directives +@end ifinfo +@subsection REGION_DELETE - Delete a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region deleted successfully@* +@code{INVALID_ID} - invalid region id@* +@code{RESOURCE_IN_USE} - segments still in use + +@subheading DESCRIPTION: + +This directive deletes the region specified by id. +The region cannot be deleted if any of its segments are still +allocated. The RNCB for the deleted region is reclaimed by +RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be preempted. + +The calling task does not have to be the task that +created the region. Any local task that knows the region id can +delete the region. + +@page +@ifinfo +@node REGION_EXTEND - Add memory to a region, REGION_GET_SEGMENT - Get segment from a region, REGION_DELETE - Delete a region, Region Manager Directives +@end ifinfo +@subsection REGION_EXTEND - Add memory to a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + rtems_unsigned32 length +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region extended successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - invalid address of area to add + +@subheading DESCRIPTION: + +This directive adds the memory which starts at +starting_address for length bytes to the region specified by id. + +@subheading NOTES: + +This directive will not cause the calling task to be preempted. + +The calling task does not have to be the task that +created the region. Any local task that knows the region id can +extend the region. + +@page +@ifinfo +@node REGION_GET_SEGMENT - Get segment from a region, REGION_RETURN_SEGMENT - Return segment to a region, REGION_EXTEND - Add memory to a region, Region Manager Directives +@end ifinfo +@subsection REGION_GET_SEGMENT - Get segment from a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_get_segment( + rtems_id id, + rtems_unsigned32 size, + rtems_option option_set, + rtems_interval timeout, + void **segment +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment obtained successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_SIZE} - request is for zero bytes or exceeds +the size of maximum segment which is possible for this region@* +@code{UNSATISFIED} - segment of requested size not available@* +@code{TIMEOUT} - timed out waiting for segment@* +@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting + +@subheading DESCRIPTION: + +This directive obtains a variable size segment from +the region specified by id. The address of the allocated +segment is returned in segment. The WAIT and NO_WAIT components +of the options parameter are used to specify whether the calling +tasks wish to wait for a segment to become available or return +immediately if no segment is available. For either option, if a +sufficiently sized segment is available, then the segment is +successfully acquired by returning immediately with the +SUCCESSFUL status code. + +If the calling task chooses to return immediately and +a segment large enough is not available, then an error code +indicating this fact is returned. If the calling task chooses +to wait for the segment and a segment large enough is not +available, then the calling task is placed on the region's +segment wait queue and blocked. If the region was created with +the PRIORITY option, then the calling task is inserted into the +wait queue according to its priority. However, if the region +was created with the FIFO option, then the calling task is +placed at the rear of the wait queue. + +The timeout parameter specifies the maximum interval +that a task is willing to wait to obtain a segment. If timeout +is set to NO_TIMEOUT, then the calling task will wait forever. + +@subheading NOTES: + +The actual length of the allocated segment may be +larger than the requested size because a segment size is always +a multiple of the region's page size. + +The following segment acquisition option constants +are defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +@page +@ifinfo +@node REGION_RETURN_SEGMENT - Return segment to a region, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, REGION_GET_SEGMENT - Get segment from a region, Region Manager Directives +@end ifinfo +@subsection REGION_RETURN_SEGMENT - Return segment to a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_return_segment( + rtems_id id, + void *segment +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment returned successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - segment address not in region + +@subheading DESCRIPTION: + +This directive returns the segment specified by +segment to the region specified by id. The returned segment is +merged with its neighbors to form the largest possible segment. +The first task on the wait queue is examined to determine if its +segment request can now be satisfied. If so, it is given a +segment and unblocked. This process is repeated until the first +task's segment request cannot be satisfied. + +@subheading NOTES: + +This directive will cause the calling task to be +preempted if one or more local tasks are waiting for a segment +and the following conditions exist: + +@itemize @bullet +@item a waiting task has a higher priority than the calling task + +@item the size of the segment required by the waiting task +is less than or equal to the size of the segment returned. +@end itemize + +@page +@ifinfo +@node REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Dual-Ported Memory Manager, REGION_RETURN_SEGMENT - Return segment to a region, Region Manager Directives +@end ifinfo +@subsection REGION_GET_SEGMENT_SIZE - Obtain size of a segment + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + rtems_unsigned32 *size +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment obtained successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - segment address not in region + +@subheading DESCRIPTION: + +This directive obtains the size in bytes of the specified segment. + +@subheading NOTES: + +The actual length of the allocated segment may be +larger than the requested size because a segment size is always +a multiple of the region's page size. + diff --git a/doc/user/rtemsarc.gif b/doc/user/rtemsarc.gif new file mode 100644 index 0000000000..fea62ecb42 Binary files /dev/null and b/doc/user/rtemsarc.gif differ diff --git a/doc/user/rtemspie.gif b/doc/user/rtemspie.gif new file mode 100644 index 0000000000..8341861b0d Binary files /dev/null and b/doc/user/rtemspie.gif differ diff --git a/doc/user/rtmon.t b/doc/user/rtmon.t new file mode 100644 index 0000000000..91fb23b2bf --- /dev/null +++ b/doc/user/rtmon.t @@ -0,0 +1,1148 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Open Issues +@c - nicen up the tables +@c - use math mode to print formulas +@c + +@ifinfo +@node Rate Monotonic Manager, Rate Monotonic Manager Introduction, Scheduling Concepts Task State Transitions, Top +@end ifinfo +@chapter Rate Monotonic Manager +@ifinfo +@menu +* Rate Monotonic Manager Introduction:: +* Rate Monotonic Manager Background:: +* Rate Monotonic Manager Operations:: +* Rate Monotonic Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Rate Monotonic Manager Introduction, Rate Monotonic Manager Background, Rate Monotonic Manager, Rate Monotonic Manager +@end ifinfo +@section Introduction + +The rate monotonic manager provides facilities to +implement tasks which execute in a periodic fashion. The +directives provided by the rate monotonic manager are: + +@itemize @bullet +@item @code{rate_monotonic_create} - Create a rate monotonic period +@item @code{rate_monotonic_ident} - Get ID of a period +@item @code{rate_monotonic_cancel} - Cancel a period +@item @code{rate_monotonic_delete} - Delete a rate monotonic period +@item @code{rate_monotonic_period} - Conclude current/Start next period +@item @code{rate_monotonic_get_status} - Obtain status information on period +@end itemize + +@ifinfo +@node Rate Monotonic Manager Background, Rate Monotonic Manager Definitions, Rate Monotonic Manager Introduction, Rate Monotonic Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Rate Monotonic Manager Definitions:: +* Rate Monotonic Scheduling Algorithm:: +* Schedulability Analysis:: +* Assumptions:: +* Processor Utilization Rule:: +* Processor Utilization Rule Example:: +* First Deadline Rule:: +* First Deadline Rule Example:: +* Relaxation of Assumptions:: +* Further Reading:: +@end menu +@end ifinfo + +The rate monotonic manager provides facilities to +manage the execution of periodic tasks. This manager was +designed to support application designers who utilize the Rate +Monotonic Scheduling Algorithm (RMS) to insure that their +periodic tasks will meet their deadlines, even under transient +overload conditions. Although designed for hard real-time +systems, the services provided by the rate monotonic manager may +be used by any application which requires periodic tasks. + +@ifinfo +@node Rate Monotonic Manager Definitions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background, Rate Monotonic Manager Background +@end ifinfo +@subsection Rate Monotonic Manager Definitions + +A periodic task is one which must be executed at a +regular interval. The interval between successive iterations of +the task is referred to as its period. Periodic tasks can be +characterized by the length of their period and execution time. +The period and execution time of a task can be used to determine +the processor utilization for that task. Processor utilization +is the percentage of processor time used and can be calculated +on a per-task or system-wide basis. Typically, the task's +worst-case execution time will be less than its period. For +example, a periodic task's requirements may state that it should +execute for 10 milliseconds every 100 milliseconds. Although +the execution time may be the average, worst, or best case, the +worst-case execution time is more appropriate for use when +analyzing system behavior under transient overload conditions. + +In contrast, an aperiodic task executes at irregular +intervals and has only a soft deadline. In other words, the +deadlines for aperiodic tasks are not rigid, but adequate +response times are desirable. For example, an aperiodic task +may process user input from a terminal. + +Finally, a sporadic task is an aperiodic task with a +hard deadline and minimum interarrival time. The minimum +interarrival time is the minimum period of time which exists +between successive iterations of the task. For example, a +sporadic task could be used to process the pressing of a fire +button on a joystick. The mechanical action of the fire button +insures a minimum time period between successive activations, +but the missile must be launched by a hard deadline. + +@ifinfo +@node Rate Monotonic Scheduling Algorithm, Schedulability Analysis, Rate Monotonic Manager Definitions, Rate Monotonic Manager Background +@end ifinfo +@subsection Rate Monotonic Scheduling Algorithm + +The Rate Monotonic Scheduling Algorithm (RMS) is +important to real-time systems designers because it allows one +to guarantee that a set of tasks is schedulable. A set of tasks +is said to be schedulable if all of the tasks can meet their +deadlines. RMS provides a set of rules which can be used to +perform a guaranteed schedulability analysis for a task set. +This analysis determines whether a task set is schedulable under +worst-case conditions and emphasizes the predictability of the +system's behavior. It has been proven that: + +@itemize @code{ } +@b{RMS is an optimal static priority algorithm for +scheduling independent, preemptible, periodic tasks +on a single processor.} +@end itemize + +RMS is optimal in the sense that if a set of tasks +can be scheduled by any static priority algorithm, then RMS will +be able to schedule that task set. RMS bases it schedulability +analysis on the processor utilization level below which all +deadlines can be met. + +RMS calls for the static assignment of task +priorities based upon their period. The shorter a task's +period, the higher its priority. For example, a task with a 1 +millisecond period has higher priority than a task with a 100 +millisecond period. If two tasks have the same period, than RMS +does not distinguish between the tasks. However, RTEMS +specifies that when given tasks of equal priority, the task +which has been ready longest will execute first. RMS's priority +assignment scheme does not provide one with exact numeric values +for task priorities. For example, consider the following task +set and priority assignments: + +@ifset use-ascii +@example +@group ++--------------------+---------------------+---------------------+ +| Task | Period | Priority | +| | (in milliseconds) | | ++--------------------+---------------------+---------------------+ +| 1 | 100 | Low | ++--------------------+---------------------+---------------------+ +| 2 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 3 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 4 | 25 | High | ++--------------------+---------------------+---------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf Period && \bf Priority &\cr +& && \bf (in milliseconds) && &\cr\noalign{\hrule} +& 1 && 100 && Low &\cr\noalign{\hrule} +& 2 && 50 && Medium &\cr\noalign{\hrule} +& 3 && 50 && Medium &\cr\noalign{\hrule} +& 4 && 25 && Low &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + +
    TaskPeriod (in milliseconds)Priority
    1100 Low
    250 Medium
    350 Medium
    425 High
    +
    +@end html +@end ifset + +RMS only calls for task 1 to have the lowest +priority, task 4 to have the highest priority, and tasks 2 and 3 +to have an equal priority between that of tasks 1 and 4. The +actual RTEMS priorities assigned to the tasks must only adhere +to those guidelines. + +Many applications have tasks with both hard and soft +deadlines. The tasks with hard deadlines are typically referred +to as the critical task set, with the soft deadline tasks being +the non-critical task set. The critical task set can be +scheduled using RMS, with the non-critical tasks not executing +under transient overload, by simply assigning priorities such +that the lowest priority critical task (i.e. longest period) has +a higher priority than the highest priority non-critical task. +Although RMS may be used to assign priorities to the +non-critical tasks, it is not necessary. In this instance, +schedulability is only guaranteed for the critical task set. + +@ifinfo +@node Schedulability Analysis, Assumptions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background +@end ifinfo +@subsection Schedulability Analysis + +RMS allows application designers to insure that tasks +can meet all deadlines, even under transient overload, without +knowing exactly when any given task will execute by applying +proven schedulability analysis rules. + +@lowersections + +@ifinfo +@node Assumptions, Processor Utilization Rule, Schedulability Analysis, Rate Monotonic Manager Background +@end ifinfo +@subsection Assumptions + +The schedulability analysis rules for RMS were +developed based on the following assumptions: + + +@itemize @bullet +@item The requests for all tasks for which hard deadlines +exist are periodic, with a constant interval between requests. + +@item Each task must complete before the next request for it +occurs. + +@item The tasks are independent in that a task does not depend +on the initiation or completion of requests for other tasks. + +@item The execution time for each task without preemption or +interruption is constant and does not vary. + +@item Any non-periodic tasks in the system are special. These +tasks displace periodic tasks while executing and do not have +hard, critical deadlines. +@end itemize + +Once the basic schedulability analysis is understood, +some of the above assumptions can be relaxed and the +side-effects accounted for. + +@ifinfo +@node Processor Utilization Rule, Processor Utilization Rule Example, Assumptions, Rate Monotonic Manager Background +@end ifinfo +@subsection Processor Utilization Rule + +The Processor Utilization Rule requires that +processor utilization be calculated based upon the period and +execution time of each task. The fraction of processor time +spent executing task index is Time(index) / Period(index). The +processor utilization can be calculated as follows: + +@example +@group +Utilization = 0 + +for index = 1 to maximum_tasks + Utilization = Utilization + (Time(index)/Period(index)) +@end group +@end example + +To insure schedulability even under transient +overload, the processor utilization must adhere to the following +rule: + +@example +Utilization = maximum_tasks * (2(1/maximum_tasks) - 1) +@end example + +As the number of tasks increases, the above formula +approaches ln(2) for a worst-case utilization factor of +approximately 0.693. Many tasks sets can be scheduled with a +greater utilization factor. In fact, the average processor +utilization threshold for a randomly generated task set is +approximately 0.88. + +@ifinfo +@node Processor Utilization Rule Example, First Deadline Rule, Processor Utilization Rule, Rate Monotonic Manager Background +@end ifinfo +@subsection Processor Utilization Rule Example + +This example illustrates the application of the +Processor Utilization Rule to an application with three critical +periodic tasks. The following table details the RMS priority, +period, execution time, and processor utilization for each task: + +@ifset use-ascii +@example +@group + +------------+----------+--------+-----------+-------------+ + | Task | RMS | Period | Execution | Processor | + | | Priority | | Time | Utilization | + +------------+----------+--------+-----------+-------------+ + | 1 | High | 100 | 15 | 0.15 | + +------------+----------+--------+-----------+-------------+ + | 2 | Medium | 200 | 50 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 3 | Low | 300 | 100 | 0.33 | + +------------+----------+--------+-----------+-------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr +& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule} +& 1 && High && 100 && 15 && 0.15 &\cr\noalign{\hrule} +& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule} +& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + + + + + + +
    TaskRMS PriorityPeriodExecution TimeProcessor Utilization
    1High100150.15
    2Medium200500.25
    3Low3001000.33
    +
    +@end html +@end ifset + +The total processor utilization for this task set is +0.73 which is below the upper bound of 3 * (2(1/3) - 1), or +0.779, imposed by the Processor Utilization Rule. Therefore, +this task set is guaranteed to be schedulable using RMS. + +@ifinfo +@node First Deadline Rule, First Deadline Rule Example, Processor Utilization Rule Example, Rate Monotonic Manager Background +@end ifinfo +@subsection First Deadline Rule + +If a given set of tasks do exceed the processor +utilization upper limit imposed by the Processor Utilization +Rule, they can still be guaranteed to meet all their deadlines +by application of the First Deadline Rule. This rule can be +stated as follows: + +For a given set of independent periodic tasks, if +each task meets its first deadline when all tasks are started at +the same time, then the deadlines will always be met for any +combination of start times. + +A key point with this rule is that ALL periodic tasks +are assumed to start at the exact same instant in time. +Although this assumption may seem to be invalid, RTEMS makes it +quite easy to insure. By having a non-preemptible user +initialization task, all application tasks, regardless of +priority, can be created and started before the initialization +deletes itself. This technique insures that all tasks begin to +compete for execution time at the same instant -- when the user +initialization task deletes itself. + +@ifinfo +@node First Deadline Rule Example, Relaxation of Assumptions, First Deadline Rule, Rate Monotonic Manager Background +@end ifinfo +@subsection First Deadline Rule Example + +The First Deadline Rule can insure schedulability +even when the Processor Utilization Rule fails. The example +below is a modification of the Processor Utilization Rule +example where task execution time has been increased from 15 to +25 units. The following table details the RMS priority, period, +execution time, and processor utilization for each task: + +@ifset use-ascii +@example +@group + +------------+----------+--------+-----------+-------------+ + | Task | RMS | Period | Execution | Processor | + | | Priority | | Time | Utilization | + +------------+----------+--------+-----------+-------------+ + | 1 | High | 100 | 25 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 2 | Medium | 200 | 50 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 3 | Low | 300 | 100 | 0.33 | + +------------+----------+--------+-----------+-------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr +& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule} +& 1 && High && 100 && 25 && 0.25 &\cr\noalign{\hrule} +& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule} +& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + + + + + + +
    TaskRMS PriorityPeriodExecution TimeProcessor Utilization
    1High100250.25
    2Medium200500.25
    3Low3001000.33
    +
    +@end html +@end ifset + +The total processor utilization for the modified task +set is 0.83 which is above the upper bound of 3 * (2(1/3) - 1), +or 0.779, imposed by the Processor Utilization Rule. Therefore, +this task set is not guaranteed to be schedulable using RMS. +However, the First Deadline Rule can guarantee the +schedulability of this task set. This rule calls for one to +examine each occurrence of deadline until either all tasks have +met their deadline or one task failed to meet its first +deadline. The following table details the time of each deadline +occurrence, the maximum number of times each task may have run, +the total execution time, and whether all the deadlines have +been met. + +@ifset use-ascii +@example +@group ++----------+------+------+------+----------------------+---------------+ +| Deadline | Task | Task | Task | Total | All Deadlines | +| Time | 1 | 2 | 3 | Execution Time | Met? | ++----------+------+------+------+----------------------+---------------+ +| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | ++----------+------+------+------+----------------------+---------------+ +| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | ++----------+------+------+------+----------------------+---------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 2.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Deadline&& \bf Task &&\bf Task&&\bf Task&&\bf Total &&\bf All Deadlines &\cr +&\bf Time && \bf 1 &&\bf 2 &&\bf 3 &&\bf Execution Time &&\bf Net?&\cr\noalign{\hrule} +& 100&& 1 && 1 && 1 && 25 + 50 + 100 = 175 && NO &\cr\noalign{\hrule} +& 200&& 2 && 1 && 1 && 50 + 50 + 100 = 200 && YES &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + + + + +
    Deadline TimeTask 1Task 2Task 3Total Execution TimeAll Deadlines Met?
    10011125 + 50 + 100 = 175NO
    20021150 + 50 + 100 = 175YES
    +
    +@end html +@end ifset + +The key to this analysis is to recognize when each +task will execute. For example at time 100, task 1 must have +met its first deadline, but tasks 2 and 3 may also have begun +execution. In this example, at time 100 tasks 1 and 2 have +completed execution and thus have met their first deadline. +Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100 +- 75) = 25 time units for task 3 to begin. Because task 3 takes +100 ticks to execute, it will not have completed execution at +time 100. Thus at time 100, all of the tasks except task 3 have +met their first deadline. + +At time 200, task 1 must have met its second deadline +and task 2 its first deadline. As a result, of the first 200 +time units, task 1 uses (2 * 25) = 50 and task 2 uses 50, +leaving (200 - 100) time units for task 3. Task 3 requires 100 +time units to execute, thus it will have completed execution at +time 200. Thus, all of the tasks have met their first deadlines +at time 200, and the task set is schedulable using the First +Deadline Rule. + +@ifinfo +@node Relaxation of Assumptions, Further Reading, First Deadline Rule Example, Rate Monotonic Manager Background +@end ifinfo +@subsection Relaxation of Assumptions + +The assumptions used to develop the RMS +schedulability rules are uncommon in most real-time systems. +For example, it was assumed that tasks have constant unvarying +execution time. It is possible to relax this assumption, simply +by using the worst-case execution time of each task. + +Another assumption is that the tasks are independent. +This means that the tasks do not wait for one another or +contend for resources. This assumption can be relaxed by +accounting for the amount of time a task spends waiting to +acquire resources. Similarly, each task's execution time must +account for any I/O performed and any RTEMS directive calls. + +In addition, the assumptions did not account for the +time spent executing interrupt service routines. This can be +accounted for by including all the processor utilization by +interrupt service routines in the utilization calculation. +Similarly, one should also account for the impact of delays in +accessing local memory caused by direct memory access and other +processors accessing local dual-ported memory. + +The assumption that nonperiodic tasks are used only +for initialization or failure-recovery can be relaxed by placing +all periodic tasks in the critical task set. This task set can +be scheduled and analyzed using RMS. All nonperiodic tasks are +placed in the non-critical task set. Although the critical task +set can be guaranteed to execute even under transient overload, +the non-critical task set is not guaranteed to execute. + +In conclusion, the application designer must be fully +cognizant of the system and its run-time behavior when +performing schedulability analysis for a system using RMS. +Every hardware and software factor which impacts the execution +time of each task must be accounted for in the schedulability +analysis. + +@ifinfo +@node Further Reading, Rate Monotonic Manager Operations, Relaxation of Assumptions, Rate Monotonic Manager Background +@end ifinfo +@subsection Further Reading + +For more information on Rate Monotonic Scheduling and +its schedulability analysis, the reader is referred to the +following: + +@itemize @code{ } +@item @cite{C. L. Liu and J. W. Layland. "Scheduling Algorithms for +Multiprogramming in a Hard Real Time Environment." @b{Journal of +the Association of Computing Machinery}. January 1973. pp. 46-61.} + +@item @cite{John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic +Scheduling Algorithm: Exact Characterization and Average Case +Behavior." @b{IEEE Real-Time Systems Symposium}. 1989. pp. 166-171.} + +@item @cite{Lui Sha and John Goodenough. "Real-Time Scheduling +Theory and Ada." @b{IEEE Computer}. April 1990. pp. 53-62.} + +@item @cite{Alan Burns. "Scheduling hard real-time systems: a +review." @b{Software Engineering Journal}. May 1991. pp. 116-128.} +@end itemize + +@raisesections + +@ifinfo +@node Rate Monotonic Manager Operations, Creating a Rate Monotonic Period, Further Reading, Rate Monotonic Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Rate Monotonic Period:: +* Manipulating a Period:: +* Obtaining a Period's Status:: +* Canceling a Period:: +* Deleting a Rate Monotonic Period:: +* Examples:: +* Simple Periodic Task:: +* Task with Multiple Periods:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Rate Monotonic Period, Manipulating a Period, Rate Monotonic Manager Operations, Rate Monotonic Manager Operations +@end ifinfo +@subsection Creating a Rate Monotonic Period + +The rate_monotonic_create directive creates a rate +monotonic period which is to be used by the calling task to +delineate a period. RTEMS allocates a Period Control Block +(PCB) from the PCB free list. This data structure is used by +RTEMS to manage the newly created rate monotonic period. RTEMS +returns a unique period ID to the application which is used by +other rate monotonic manager directives to access this rate +monotonic period. + +@ifinfo +@node Manipulating a Period, Obtaining a Period's Status, Creating a Rate Monotonic Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Manipulating a Period + +The rate_monotonic_period directive is used to +establish and maintain periodic execution utilizing a previously +created rate monotonic period. Once initiated by the +rate_monotonic_period directive, the period is said to run until +it either expires or is reinitiated. The state of the rate +monotonic period results in one of the following scenarios: + +@itemize @bullet +@item If the rate monotonic period is running, the calling +task will be blocked for the remainder of the outstanding period +and, upon completion of that period, the period will be +reinitiated with the specified period. + +@item If the rate monotonic period is not currently running +and has not expired, it is initiated with a length of period +ticks and the calling task returns immediately. + +@item If the rate monotonic period has expired before the task +invokes the rate_monotonic_period directive, the period will be +initiated with a length of period ticks and the calling task +returns immediately with a timeout error status. +@end itemize + +@ifinfo +@node Obtaining a Period's Status, Canceling a Period, Manipulating a Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Obtaining a Period's Status + +If the rate_monotonic_period directive is invoked +with a period of PERIOD_STATUS ticks, the current state of the +specified rate monotonic period will be returned. The following +table details the relationship between the period's status and +the directive status code returned by the rate_monotonic_period +directive: + +@itemize @bullet +@item SUCCESSFUL - period is running + +@item TIMEOUT - period has expired + +@item NOT_DEFINED - period has never been initiated +@end itemize + +Obtaining the status of a rate monotonic period does +not alter the state or length of that period. + +@ifinfo +@node Canceling a Period, Deleting a Rate Monotonic Period, Obtaining a Period's Status, Rate Monotonic Manager Operations +@end ifinfo +@subsection Canceling a Period + +The rate_monotonic_cancel directive is used to stop +the period maintained by the specified rate monotonic period. +The period is stopped and the rate monotonic period can be +reinitiated using the rate_monotonic_period directive. + +@ifinfo +@node Deleting a Rate Monotonic Period, Examples, Canceling a Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Deleting a Rate Monotonic Period + +The rate_monotonic_delete directive is used to delete +a rate monotonic period. If the period is running and has not +expired, the period is automatically canceled. The rate +monotonic period's control block is returned to the PCB free +list when it is deleted. A rate monotonic period can be deleted +by a task other than the task which created the period. + +@ifinfo +@node Examples, Simple Periodic Task, Deleting a Rate Monotonic Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Examples + +The following sections illustrate common uses of rate +monotonic periods to construct periodic tasks. + +@ifinfo +@node Simple Periodic Task, Task with Multiple Periods, Examples, Rate Monotonic Manager Operations +@end ifinfo +@subsection Simple Periodic Task + +This example consists of a single periodic task +which, after initialization, executes every 100 clock ticks. + +@page +@example +rtems_task Periodic_task() +@{ + rtems_name name; + rtems_id period; + rtems_status_code status; + + name = build_name( 'P', 'E', 'R', 'D' ); + + (void) rate_monotonic_create( name, &period ); + + while ( 1 ) @{ + if ( rate_monotonic_period( period, 100 ) == TIMEOUT ) + break; + + /* Perform some periodic actions */ + @} + + /* missed period so delete period and SELF */ + + (void) rate_monotonic_delete( period ); + (void) task_delete( SELF ); +@} +@end example + + +The above task creates a rate monotonic period as +part of its initialization. The first time the loop is +executed, the rate_monotonic_period directive will initiate the +period for 100 ticks and return immediately. Subsequent +invocations of the rate_monotonic_period directive will result +in the task blocking for the remainder of the 100 tick period. +If, for any reason, the body of the loop takes more than 100 +ticks to execute, the rate_monotonic_period directive will +return the TIMEOUT status. If the above task misses its +deadline, it will delete the rate monotonic period and itself. + +@ifinfo +@node Task with Multiple Periods, Rate Monotonic Manager Directives, Simple Periodic Task, Rate Monotonic Manager Operations +@end ifinfo +@subsection Task with Multiple Periods + +This example consists of a single periodic task +which, after initialization, performs two sets of actions every +100 clock ticks. The first set of actions is performed in the +first forty clock ticks of every 100 clock ticks, while the +second set of actions is performed between the fortieth and +seventieth clock ticks. The last thirty clock ticks are not +used by this task. + +@page +@example +task Periodic_task() +@{ + rtems_name name_1, name_2; + rtems_id period_1, period_2; + rtems_status_code status; + + name_1 = build_name( 'P', 'E', 'R', '1' ); + name_2 = build_name( 'P', 'E', 'R', '2' ); + + (void ) rate_monotonic_create( name_1, &period_1 ); + (void ) rate_monotonic_create( name_2, &period_2 ); + + while ( 1 ) @{ + if ( rate_monotonic_period( period_1, 100 ) == TIMEOUT ) + break; + + if ( rate_monotonic_period( period_2, 40 ) == TIMEOUT ) + break; + + /* + * Perform first set of actions between clock + * ticks 0 and 39 of every 100 ticks. + */ + + if ( rate_monotonic_period( period_2, 30 ) == TIMEOUT ) + break; + + /* + * Perform second set of actions between clock 40 and 69 + * of every 100 ticks. THEN ... + * + * Check to make sure we didn't miss the period_2 period. + */ + + if ( rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) + break; + + (void) rate_monotonic_cancel( period_2 ); + @} + + /* missed period so delete period and SELF */ + + (void ) rate_monotonic_delete( period_1 ); + (void ) rate_monotonic_delete( period_2 ); + (void ) task_delete( SELF ); +@} +@end example + +The above task creates two rate monotonic periods as +part of its initialization. The first time the loop is +executed, the rate_monotonic_period directive will initiate the +period_1 period for 100 ticks and return immediately. +Subsequent invocations of the rate_monotonic_period directive +for period_1 will result in the task blocking for the remainder +of the 100 tick period. The period_2 period is used to control +the execution time of the two sets of actions within each 100 +tick period established by period_1. The rate_monotonic_cancel( +period_2 ) call is performed to insure that the period_2 period +does not expire while the task is blocked on the period_1 +period. If this cancel operation were not performed, every time +the rate_monotonic_period( period_1, 40 ) call is executed, +except for the initial one, a directive status of TIMEOUT is +returned. It is important to note that every time this call is +made, the period_1 period will be initiated immediately and the +task will not block. + +If, for any reason, the task misses any deadline, the +rate_monotonic_period directive will return the TIMEOUT +directive status. If the above task misses its deadline, it +will delete the rate monotonic periods and itself. + +@ifinfo +@node Rate Monotonic Manager Directives, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Task with Multiple Periods, Rate Monotonic Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* RATE_MONOTONIC_CREATE - Create a rate monotonic period:: +* RATE_MONOTONIC_IDENT - Get ID of a period:: +* RATE_MONOTONIC_CANCEL - Cancel a period:: +* RATE_MONOTONIC_DELETE - Delete a rate monotonic period:: +* RATE_MONOTONIC_PERIOD - Conclude current/Start next period:: +* RATE_MONOTONIC_GET_STATUS - Obtain status information on period:: +@end menu +@end ifinfo + +This section details the rate monotonic 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 RATE_MONOTONIC_CREATE - Create a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - rate monotonic period created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many periods created + +@subheading DESCRIPTION: + +This directive creates a rate monotonic period. The +assigned rate monotonic id is returned in id. This id is used +to access the period with other rate monotonic manager +directives. For control and maintenance of the rate monotonic +period, RTEMS allocates a PCB from the local PCB free pool and +initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node RATE_MONOTONIC_IDENT - Get ID of a period, RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_IDENT - Get ID of a period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period identified successfully@* +@code{INVALID_NAME} - period name not found + +@subheading DESCRIPTION: + +This directive obtains the period id associated with +the period name to be acquired. If the period name is not +unique, then the period id will match one of the periods with +that name. However, this period id is not guaranteed to +correspond to the desired period. The period id is used to +access this period in other rate monotonic manager directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_CANCEL - Cancel a period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period canceled successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task + +@subheading DESCRIPTION: + +This directive cancels the rate monotonic period id. +This period will be reinitiated by the next invocation of +rate_monotonic_period with id. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +The rate monotonic period specified by id must have +been created by the calling task. + +@page +@ifinfo +@node RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_CANCEL - Cancel a period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period deleted successfully@* +@code{INVALID_ID} - invalid rate monotonic period id + +@subheading DESCRIPTION: + +This directive deletes the rate monotonic period +specified by id. If the period is running, it is automatically +canceled. The PCB for the deleted period is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A rate monotonic period can be deleted by a task +other than the task which created the period. + +@page +@ifinfo +@node RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period initiated successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{NOT_OWNER_OF_RESOURCE} - period not created by calling task@* +@code{NOT_DEFINED} - period has never been initiated@* +@code{TIMEOUT} - period has expired + +@subheading DESCRIPTION: + +This directive initiates the rate monotonic period id +with a length of period ticks. If id is running, then the +calling task will block for the remainder of the period before +reinitiating the period with the specified period. If id was +not running (either expired or never initiated), the period is +immediately initiated and the directive returns immediately. + +If invoked with a period of PERIOD_STATUS ticks, the +current state of id will be returned. The directive status +indicates the current state of the period. This does not alter +the state or period of the period. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +--------------------- +@page +@ifinfo +@node RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Board Support Packages, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_rate_monotonic_period_status *status +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period initiated successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{INVALID_ADDRESS} - invalid address of status@* + +@subheading DESCRIPTION: + +This directive returns status information associated with +the rate monotonic period id in the following data structure: + +@example +typedef struct @{ + rtems_rate_monotonic_period_states state; + unsigned32 ticks_since_last_period; + unsigned32 ticks_executed_since_last_period; +@} rtems_rate_monotonic_period_status; +@end example + +If the period's state is RATE_MONOTONIC_INACTIVE, both +ticks_since_last_period and ticks_executed_since_last_period +will be set to 0. Otherwise, ticks_since_last_period will +contain the number of clock ticks which have occurred since +the last invocation of the rtems_rate_monotonic_period directive. +Also in this case, the ticks_executed_since_last_period will indicate +how much processor time the owning task has consumed since the invocation +of the rtems_rate_monotonic_period directive. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. diff --git a/doc/user/schedule.t b/doc/user/schedule.t new file mode 100644 index 0000000000..5781a670b7 --- /dev/null +++ b/doc/user/schedule.t @@ -0,0 +1,426 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c This figure is not included: +@c Figure 17-1 RTEMS Task State Transitions +@c + +@ifinfo +@node Scheduling Concepts, Scheduling Concepts Introduction, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Top +@end ifinfo +@chapter Scheduling Concepts +@ifinfo +@menu +* Scheduling Concepts Introduction:: +* Scheduling Concepts Scheduling Mechanisms:: +* Scheduling Concepts Task State Transitions:: +@end menu +@end ifinfo + +@ifinfo +@node Scheduling Concepts Introduction, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts, Scheduling Concepts +@end ifinfo +@section Introduction + +The concept of scheduling in real-time systems +dictates the ability to provide immediate response to specific +external events, particularly the necessity of scheduling tasks +to run within a specified time limit after the occurrence of an +event. For example, software embedded in life-support systems +used to monitor hospital patients must take instant action if a +change in the patient's status is detected. + +The component of RTEMS responsible for providing this +capability is appropriately called the scheduler. The +scheduler's sole purpose is to allocate the all important +resource of processor time to the various tasks competing for +attention. The RTEMS scheduler allocates the processor using a +priority-based, preemptive algorithm augmented to provide +round-robin characteristics within individual priority groups. +The goal of this algorithm is to guarantee that the task which +is executing on the processor at any point in time is the one +with the highest priority among all tasks in the ready state. + +There are two common methods of accomplishing the +mechanics of this algorithm. Both ways involve a list or chain +of tasks in the ready state. One method is to randomly place +tasks in the ready chain forcing the scheduler to scan the +entire chain to determine which task receives the processor. +The other method is to schedule the task by placing it in the +proper place on the ready chain based on the designated +scheduling criteria at the time it enters the ready state. +Thus, when the processor is free, the first task on the ready +chain is allocated the processor. RTEMS schedules tasks using +the second method to guarantee faster response times to external +events. + +@ifinfo +@node Scheduling Concepts Scheduling Mechanisms, Task Priority and Scheduling, Scheduling Concepts Introduction, Scheduling Concepts +@end ifinfo +@section Scheduling Mechanisms +@ifinfo +@menu +* Task Priority and Scheduling:: +* Preemption:: +* Timeslicing:: +* Manual Round-Robin:: +* Dispatching Tasks:: +@end menu +@end ifinfo + +RTEMS provides four mechanisms which allow the user +to impact the task scheduling process: + +@itemize @bullet +@item user-selectable task priority level +@item task preemption control +@item task timeslicing control +@item manual round-robin selection +@end itemize + +Each of these methods provides a powerful capability +to customize sets of tasks to satisfy the unique and particular +requirements encountered in custom real-time applications. +Although each mechanism operates independently, there is a +precedence relationship which governs the effects of scheduling +modifications. The evaluation order for scheduling +characteristics is always priority, preemption mode, and +timeslicing. When reading the descriptions of timeslicing and +manual round-robin it is important to keep in mind that +preemption (if enabled) of a task by higher priority tasks will +occur as required, overriding the other factors presented in the +description. + +@ifinfo +@node Task Priority and Scheduling, Preemption, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Task Priority and Scheduling + +The most significant of these mechanisms is the +ability for the user to assign a priority level to each +individual task when it is created and to alter a task's +priority at run-time. RTEMS provides 255 priority levels. +Level 255 is the lowest priority and level 1 is the highest. +When a task is added to the ready chain, it is placed behind all +other tasks of the same priority. This rule provides a +round-robin within priority group scheduling characteristic. +This means that in a group of equal priority tasks, tasks will +execute in the order they become ready or FIFO order. Even +though there are ways to manipulate and adjust task priorities, +the most important rule to remember is: + +@itemize @code{ } +@item @b{The RTEMS scheduler will always select the highest +priority task that is ready to run when allocating the processor +to a task.} +@end itemize + +@ifinfo +@node Preemption, Timeslicing, Task Priority and Scheduling, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Preemption + +Another way the user can alter the basic scheduling +algorithm is by manipulating the preemption mode flag +(PREEMPT_MASK) of individual tasks. If preemption is disabled +for a task (NO_PREEMPT), then the task will not relinquish +control of the processor until it terminates, blocks, or +re-enables preemption. Even tasks which become ready to run and +possess higher priority levels will not be allowed to execute. +Note that the preemption setting has no effect on the manner in +which a task is scheduled. It only applies once a task has +control of the processor. + +@ifinfo +@node Timeslicing, Manual Round-Robin, Preemption, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Timeslicing + +Timeslicing or round-robin scheduling is an +additional method which can be used to alter the basic +scheduling algorithm. Like preemption, timeslicing is specified +on a task by task basis using the timeslicing mode flag +(TIMESLICE_MASK). If timeslicing is enabled for a task +(TIMESLICE), then RTEMS will limit the amount of time the task +can execute before the processor is allocated to another task. +Each tick of the real-time clock reduces the currently running +task's timeslice. When the execution time equals the timeslice, +RTEMS will dispatch another task of the same priority to +execute. If there are no other tasks of the same priority ready +to execute, then the current task is allocated an additional +timeslice and continues to run. Remember that a higher priority +task will preempt the task (unless preemption is disabled) as +soon as it is ready to run, even if the task has not used up its +entire timeslice. + +@ifinfo +@node Manual Round-Robin, Dispatching Tasks, Timeslicing, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Manual Round-Robin + +The final mechanism for altering the RTEMS scheduling +algorithm is called manual round-robin. Manual round-robin is +invoked by using the task_wake_after directive with a time +interval of YIELD_PROCESSOR. This allows a task to give up the +processor and be immediately returned to the ready chain at the +end of its priority group. If no other tasks of the same +priority are ready to run, then the task does not lose control +of the processor. + +@ifinfo +@node Dispatching Tasks, Scheduling Concepts Task State Transitions, Manual Round-Robin, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Dispatching Tasks + +The dispatcher is the RTEMS component responsible for +allocating the processor to a ready task. In order to allocate +the processor to one task, it must be deallocated or retrieved +from the task currently using it. This involves a concept +called a context switch. To perform a context switch, the +dispatcher saves the context of the current task and restores +the context of the task which has been allocated to the +processor. Saving and restoring a task's context is the +storing/loading of all the essential information about a task to +enable it to continue execution without any effects of the +interruption. For example, the contents of a task's register +set must be the same when it is given the processor as they were +when it was taken away. All of the information that must be +saved or restored for a context switch is located either in the +TCB or on the task's stacks. + +Tasks that utilize a numeric coprocessor and are +created with the FLOATING_POINT attribute require additional +operations during a context switch. These additional operations +are necessary to save and restore the floating point context of +FLOATING_POINT tasks. To avoid unnecessary save and restore +operations, 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. + +@ifinfo +@node Scheduling Concepts Task State Transitions, Rate Monotonic Manager, Dispatching Tasks, Scheduling Concepts +@end ifinfo +@section Task State Transitions + +Tasks in an RTEMS system must always be in one of the +five allowable task states. These states are: executing, ready, +blocked, dormant, and non-existent. + +@ifset use-ascii +@example +@group + +-------------------------------------------------------------+ + | Non-existent | + | +-------------------------------------------------------+ | + | | | | + | | | | + | | Creating +---------+ Deleting | | + | | -------------------> | Dormant | -------------------> | | + | | +---------+ | | + | | | | | + | | Starting | | | + | | | | | + | | V Deleting | | + | | +-------> +-------+ -------------------> | | + | | Yielding / +----- | Ready | ------+ | | + | | / / +-------+ <--+ \ | | + | | / / \ \ Blocking | | + | | / / Dispatching Readying \ \ | | + | | / V \ V | | + | | +-----------+ Blocking +---------+ | | + | | | Executing | --------------> | Blocked | | | + | | +-----------+ +---------+ | | + | | | | + | | | | + | +-------------------------------------------------------+ | + | Non-existent | + +-------------------------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@c for now use the ascii version +@example +@group + +-------------------------------------------------------------+ + | Non-existent | + | +-------------------------------------------------------+ | + | | | | + | | | | + | | Creating +---------+ Deleting | | + | | -------------------> | Dormant | -------------------> | | + | | +---------+ | | + | | | | | + | | Starting | | | + | | | | | + | | V Deleting | | + | | +-------> +-------+ -------------------> | | + | | Yielding / +----- | Ready | ------+ | | + | | / / +-------+ <--+ \ | | + | | / / \ \ Blocking | | + | | / / Dispatching Readying \ \ | | + | | / V \ V | | + | | +-----------+ Blocking +---------+ | | + | | | Executing | --------------> | Blocked | | | + | | +-----------+ +---------+ | | + | | | | + | | | | + | +-------------------------------------------------------+ | + | Non-existent | + +-------------------------------------------------------------+ +@end group +@end example +@tex +@end tex +@end ifset + +@ifset use-html +@html +RTEMS Task States +@end html +@end ifset + +A task occupies the non-existent state before a +task_create has been issued on its behalf. A task enters the +non-existent state from any other state in the system when it is +deleted with the task_delete directive. While a task occupies +this state it does not have a TCB or a task ID assigned to it; +therefore, no other tasks in the system may reference this task. + +When a task is created via the task_create directive +it enters the dormant state. This state is not entered through +any other means. Although the task exists in the system, it +cannot actively compete for system resources. It will remain in +the dormant state until it is started via the task_start +directive, at which time it enters the ready state. The task is +now permitted to be scheduled for the processor and to compete +for other system resources. + +A task occupies the blocked state whenever it is +unable to be scheduled to run. A running task may block itself +or be blocked by other tasks in the system. The running task +blocks itself through voluntary operations that cause the task +to wait. The only way a task can block a task other than itself +is with the task_suspend directive. A task enters the blocked +state due to any of the following conditions: + +@itemize @bullet +@item A task issues a task_suspend directive which blocks +either itself or another task in the system. + +@item The running task issues a message_queue_receive +directive with the wait option and the message queue is empty. + +@item The running task issues an event_receive directive with +the wait option and the currently pending events do not satisfy +the request. + +@item The running task issues a semaphore_obtain directive +with the wait option and the requested semaphore is unavailable. + +@item The running task issues a task_wake_after directive +which blocks the task for the given time interval. If the time +interval specified is zero, the task yields the processor and +remains in the ready state. + +@item The running task issues a task_wake_when directive which +blocks the task until the requested date and time arrives. + +@item The running task issues a region_get_segment directive +with the wait option and there is not an available segment large +enough to satisfy the task's request. + +@item The running task issues a rate_monotonic_period +directive and must wait for the specified rate monotonic period +to conclude. +@end itemize + +A blocked task may also be suspended. Therefore, +both the suspension and the blocking condition must be removed +before the task becomes ready to run again. + +A task occupies the ready state when it is able to be +scheduled to run, but currently does not have control of the +processor. Tasks of the same or higher priority will yield the +processor by either becoming blocked, completing their +timeslice, or being deleted. All tasks with the same priority +will execute in FIFO order. A task enters the ready state due +to any of the following conditions: + +@itemize @bullet + +@item A running task issues a task_resume directive for a task +that is suspended and the task is not blocked waiting on any +resource. + +@item A running task issues a message_queue_send, +message_queue_broadcast, or a message_queue_urgent directive +which posts a message to the queue on which the blocked task is +waiting. + +@item A running task issues an event_send directive which +sends an event condition to a task which is blocked waiting on +that event condition. + +@item A running task issues a semaphore_release directive +which releases the semaphore on which the blocked task is +waiting. + +@item A timeout interval expires for a task which was blocked +by a call to the task_wake_after directive. + +@item A timeout period expires for a task which blocked by a +call to the task_wake_when directive. + +@item A running task issues a region_return_segment directive +which releases a segment to the region on which the blocked task +is waiting and a resulting segment is large enough to satisfy +the task's request. + +@item A rate monotonic period expires for a task which blocked +by a call to the rate_monotonic_period directive. + +@item A timeout interval expires for a task which was blocked +waiting on a message, event, semaphore, or segment with a +timeout specified. + +@item A running task issues a directive which deletes a +message queue, a semaphore, or a region on which the blocked +task is waiting. + +@item A running task issues a task_restart directive for the +blocked task. + +@item The running task, with its preemption mode enabled, may +be made ready by issuing any of the directives that may unblock +a task with a higher priority. This directive may be issued +from the running task itself or from an ISR. + +A ready task occupies the executing state when it has +control of the CPU. A task enters the executing state due to +any of the following conditions: + +@item The task is the highest priority ready task in the +system. + +@item The running task blocks and the task is next in the +scheduling queue. The task may be of equal priority as in +round-robin scheduling or the task may possess the highest +priority of the remaining ready tasks. + +@item The running task may reenable its preemption mode and a +task exists in the ready queue that has a higher priority than +the running task. + +@item The running task lowers its own priority and another +task is of higher priority as a result. + +@item The running task raises the priority of a task above its +own and the running task is in preemption mode. + +@end itemize diff --git a/doc/user/sem.t b/doc/user/sem.t new file mode 100644 index 0000000000..2e45af686c --- /dev/null +++ b/doc/user/sem.t @@ -0,0 +1,722 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Semaphore Manager, Semaphore Manager Introduction, TIMER_RESET - Reset an interval timer, Top +@end ifinfo +@chapter Semaphore Manager +@ifinfo +@menu +* Semaphore Manager Introduction:: +* Semaphore Manager Background:: +* Semaphore Manager Operations:: +* Semaphore Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Semaphore Manager Introduction, Semaphore Manager Background, Semaphore Manager, Semaphore Manager +@end ifinfo +@section Introduction + +The semaphore manager utilizes standard Dijkstra +counting semaphores to provide synchronization and mutual +exclusion capabilities. The directives provided by the +semaphore manager are: + +@itemize @bullet +@item @code{semaphore_create} - Create a semaphore +@item @code{semaphore_ident} - Get ID of a semaphore +@item @code{semaphore_delete} - Delete a semaphore +@item @code{semaphore_obtain} - Acquire a semaphore +@item @code{semaphore_release} - Release a semaphore +@end itemize + +@ifinfo +@node Semaphore Manager Background, Nested Resource Access, Semaphore Manager Introduction, Semaphore Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Nested Resource Access:: +* Priority Inversion:: +* Priority Inheritance:: +* Priority Ceiling:: +* Building a Semaphore's Attribute Set:: +* Building a SEMAPHORE_OBTAIN Option Set:: +@end menu +@end ifinfo + +A semaphore can be viewed as a protected variable +whose value can be modified only with the semaphore_create, +semaphore_obtain, and semaphore_release directives. RTEMS +supports both binary and counting semaphores. A binary semaphore +is restricted to values of zero or one, while a counting +semaphore can assume any non-negative integer value. + +A binary semaphore can be used to control access to a +single resource. In particular, it can be used to enforce +mutual exclusion for a critical section in user code. In this +instance, the semaphore would be created with an initial count +of one to indicate that no task is executing the critical +section of code. Upon entry to the critical section, a task +must issue the semaphore_obtain directive to prevent other tasks +from entering the critical section. Upon exit from the critical +section, the task must issue the semaphore_release directive to +allow another task to execute the critical section. + +A counting semaphore can be used to control access to +a pool of two or more resources. For example, access to three +printers could be administered by a semaphore created with an +initial count of three. When a task requires access to one of +the printers, it issues the semaphore_obtain directive to obtain +access to a printer. If a printer is not currently available, +the task can wait for a printer to become available or return +immediately. When the task has completed printing, it should +issue the semaphore_release directive to allow other tasks +access to the printer. + +Task synchronization may be achieved by creating a +semaphore with an initial count of zero. One task waits for the +arrival of another task by issuing a semaphore_obtain directive +when it reaches a synchronization point. The other task +performs a corresponding semaphore_release operation when it +reaches its synchronization point, thus unblocking the pending +task. + +@ifinfo +@node Nested Resource Access, Priority Inversion, Semaphore Manager Background, Semaphore Manager Background +@end ifinfo +@subsection Nested Resource Access + +Deadlock occurs when a task owning a binary semaphore +attempts to acquire that same semaphore and blocks as result. +Since the semaphore is allocated to a task, it cannot be +deleted. Therefore, the task that currently holds the semaphore +and is also blocked waiting for that semaphore will never +execute again. + +RTEMS addresses this problem by allowing the task +holding the binary semaphore to obtain the same binary semaphore +multiple times in a nested manner. Each semaphore_obtain must +be accompanied with a semaphore_release. The semaphore will +only be made available for acquisition by other tasks when the +outermost semaphore_obtain is matched with a semaphore_release. + + +@ifinfo +@node Priority Inversion, Priority Inheritance, Nested Resource Access, Semaphore Manager Background +@end ifinfo +@subsection Priority Inversion + +Priority inversion is a form of indefinite +postponement which is common in multitasking, preemptive +executives with shared resources. Priority inversion occurs +when a high priority tasks requests access to shared resource +which is currently allocated to low priority task. The high +priority task must block until the low priority task releases +the resource. This problem is exacerbated when the low priority +task is prevented from executing by one or more medium priority +tasks. Because the low priority task is not executing, it +cannot complete its interaction with the resource and release +that resource. The high priority task is effectively prevented +from executing by lower priority tasks. + +@ifinfo +@node Priority Inheritance, Priority Ceiling, Priority Inversion, Semaphore Manager Background +@end ifinfo +@subsection Priority Inheritance + +Priority inheritance is an algorithm that calls for +the lower priority task holding a resource to have its priority +increased to that of the highest priority task blocked waiting +for that resource. Each time a task blocks attempting to obtain +the resource, the task holding the resource may have its +priority increased. + +RTEMS supports priority inheritance for local, binary +semaphores that use the priority task wait queue blocking +discipline. When a task of higher priority than the task +holding the semaphore blocks, the priority of the task holding +the semaphore is increased to that of the blocking task. When +the task holding the task completely releases the binary +semaphore (i.e. not for a nested release), the holder's priority +is restored to the value it had before any higher priority was +inherited. + +The RTEMS implementation of the priority inheritance +algorithm takes into account the scenario in which a task holds +more than one binary semaphore. The holding task will execute +at the priority of the higher of the highest ceiling priority or +at the priority of the highest priority task blocked waiting for +any of the semaphores the task holds. Only when the task +releases ALL of the binary semaphores it holds will its priority +be restored to the normal value. + +@ifinfo +@node Priority Ceiling, Building a Semaphore's Attribute Set, Priority Inheritance, Semaphore Manager Background +@end ifinfo +@subsection Priority Ceiling + +Priority ceiling is an algorithm that calls for the +lower priority task holding a resource to have its priority +increased to that of the highest priority task which will EVER +block waiting for that resource. This algorithm addresses the +problem of priority inversion although it avoids the possibility +of changing the priority of the task holding the resource +multiple times. The priority ceiling algorithm will only change +the priority of the task holding the resource a maximum of one +time. The ceiling priority is set at creation time and must be +the priority of the highest priority task which will ever +attempt to acquire that semaphore. + +RTEMS supports priority ceiling for local, binary +semaphores that use the priority task wait queue blocking +discipline. When a task of lower priority than the ceiling +priority successfully obtains the semaphore, its priority is +raised to the ceiling priority. When the task holding the task +completely releases the binary semaphore (i.e. not for a nested +release), the holder's priority is restored to the value it had +before any higher priority was put into effect. + +The need to identify the highest priority task which +will attempt to obtain a particular semaphore can be a difficult +task in a large, complicated system. Although the priority +ceiling algorithm is more efficient than the priority +inheritance algorithm with respect to the maximum number of task +priority changes which may occur while a task holds a particular +semaphore, the priority inheritance algorithm is more forgiving +in that it does not require this apriori information. + +The RTEMS implementation of the priority ceiling +algorithm takes into account the scenario in which a task holds +more than one binary semaphore. The holding task will execute +at the priority of the higher of the highest ceiling priority or +at the priority of the highest priority task blocked waiting for +any of the semaphores the task holds. Only when the task +releases ALL of the binary semaphores it holds will its priority +be restored to the normal value. + +@ifinfo +@node Building a Semaphore's Attribute Set, Building a SEMAPHORE_OBTAIN Option Set, Priority Ceiling, Semaphore Manager Background +@end ifinfo +@subsection Building a Semaphore's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The following table lists +the set of valid semaphore attributes: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default) +@item COUNTING_SEMAPHORE - no restriction on values +@item NO_INHERIT_PRIORITY - do not use priority inheritance (default) +@item INHERIT_PRIORITY - use priority inheritance +@item PRIORITY_CEILING - use priority ceiling +@item NO_PRIORITY_CEILING - do not use priority ceiling (default) +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. + +This example demonstrates the attribute_set parameter +needed to create a local semaphore with the task priority +waiting queue discipline. The attribute_set parameter passed to +the semaphore_create directive could be either PRIORITY or LOCAL +| PRIORITY. The attribute_set parameter can be set to PRIORITY +because LOCAL is the default for all created tasks. If a +similar semaphore were to be known globally, then the +attribute_set parameter would be GLOBAL | PRIORITY. + +@ifinfo +@node Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager Operations, Building a Semaphore's Attribute Set, Semaphore Manager Background +@end ifinfo +@subsection Building a SEMAPHORE_OBTAIN Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +semaphore_obtain directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An option listed as a default is not +required to appear in the list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for a semaphore. The option parameter passed to the +semaphore_obtain directive should be NO_WAIT. + +@ifinfo +@node Semaphore Manager Operations, Creating a Semaphore, Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Semaphore:: +* Obtaining Semaphore IDs:: +* Acquiring a Semaphore:: +* Releasing a Semaphore:: +* Deleting a Semaphore:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations, Semaphore Manager Operations +@end ifinfo +@subsection Creating a Semaphore + +The semaphore_create directive creates a binary or +counting semaphore with a user-specified name as well as an +initial count. If a binary semaphore is created with a count of +zero (0) to indicate that it has been allocated, then the task +creating the semaphore is considered the current holder of the +semaphore. At create time the method for ordering waiting tasks +in the semaphore's task wait queue (by FIFO or task priority) is +specified. Additionally, the priority inheritance or priority +ceiling algorithm may be selected for local, binary semaphores +that use the priority task wait queue blocking discipline. If +the priority ceiling algorithm is selected, then the highest +priority of any task which will attempt to obtain this semaphore +must be specified. RTEMS allocates a Semaphore Control Block +(SMCB) from the SMCB free list. This data structure is used by +RTEMS to manage the newly created semaphore. Also, a unique +semaphore ID is generated and returned to the calling task. + +@ifinfo +@node Obtaining Semaphore IDs, Acquiring a Semaphore, Creating a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Obtaining Semaphore IDs + +When a semaphore is created, RTEMS generates a unique +semaphore ID and assigns it to the created semaphore until it is +deleted. The semaphore ID may be obtained by either of two +methods. First, as the result of an invocation of the +semaphore_create directive, the semaphore ID is stored in a user +provided location. Second, the semaphore ID may be obtained +later using the semaphore_ident directive. The semaphore ID is +used by other semaphore manager directives to access this +semaphore. + +@ifinfo +@node Acquiring a Semaphore, Releasing a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations +@end ifinfo +@subsection Acquiring a Semaphore + +The semaphore_obtain directive is used to acquire the +specified semaphore. A simplified version of the +semaphore_obtain directive can be described as follows: + +@example +if semaphore's count is greater than zero + then decrement semaphore's count + else wait for release of semaphore + +return SUCCESSFUL +@end example + +When the semaphore cannot be immediately acquired, +one of the following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever to +acquire the semaphore. + +@item Specifying NO_WAIT forces an immediate return with an +error status code. + +@item Specifying a timeout limits the interval the task will +wait before returning with an error status code. +@end itemize + +If the task waits to acquire the semaphore, then it +is placed in the semaphore's task wait queue in either FIFO or +task priority order. If the task blocked waiting for a binary +semaphore using priority inheritance and the task's priority is +greater than that of the task currently holding the semaphore, +then the holding task will inherit the priority of the blocking +task. All tasks waiting on a semaphore are returned an error +code when the semaphore is deleted. + +When a task successfully obtains a semaphore using +priority ceiling and the priority ceiling for this semaphore is +greater than that of the holder, then the holder's priority will +be elevated. + +@ifinfo +@node Releasing a Semaphore, Deleting a Semaphore, Acquiring a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Releasing a Semaphore + +The semaphore_release directive is used to release +the specified semaphore. A simplified version of the +semaphore_release directive can be described as follows: + +@example +if no tasks are waiting on this semaphore + then increment semaphore's count + else assign semaphore to a waiting task + +return SUCCESSFUL +@end example + +If this is the outermost release of a binary +semaphore that uses priority inheritance or priority ceiling and +the task does not currently hold any other binary semaphores, +then the task performing the semaphore_release will have its +priority restored to its normal value. + +@ifinfo +@node Deleting a Semaphore, Semaphore Manager Directives, Releasing a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Deleting a Semaphore + +The semaphore_delete directive removes a semaphore +from the system and frees its control block. A semaphore can be +deleted by any local task that knows the semaphore's ID. As a +result of this directive, all tasks blocked waiting to acquire +the semaphore will be readied and returned a status code which +indicates that the semaphore was deleted. Any subsequent +references to the semaphore's name and ID are invalid. + +@ifinfo +@node Semaphore Manager Directives, SEMAPHORE_CREATE - Create a semaphore, Deleting a Semaphore, Semaphore Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* SEMAPHORE_CREATE - Create a semaphore:: +* SEMAPHORE_IDENT - Get ID of a semaphore:: +* SEMAPHORE_DELETE - Delete a semaphore:: +* SEMAPHORE_OBTAIN - Acquire a semaphore:: +* SEMAPHORE_RELEASE - Release a semaphore:: +@end menu +@end ifinfo + +This section details the semaphore 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 SEMAPHORE_CREATE - Create a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_CREATE - Create a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_create( + rtems_name name, + rtems_unsigned32 count, + rtems_attribute attribute_set, + rtems_task_priority priority_ceiling, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many semaphores created@* +@code{NOT_DEFINED} - invalid attribute set@* +@code{INVALID_NUMBER} - invalid starting count for binary semaphore@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a semaphore which resides on +the local node. The created semaphore has the user-defined name +specified in name and the initial count specified in count. For +control and maintenance of the semaphore, RTEMS allocates and +initializes a SMCB. The RTEMS-assigned semaphore id is returned +in id. This semaphore id is used with other semaphore related +directives to access the semaphore. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a semaphore to be serviced according to task +priority. When FIFO is selected, tasks are serviced in First +In-First Out order. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The priority inheritance and priority ceiling +algorithms are only supported for local, binary semaphores that +use the priority task wait queue blocking discipline. + +The following semaphore attribute constants are +defined by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default) +@item COUNTING_SEMAPHORE - no restriction on values +@item NO_INHERIT_PRIORITY - do not use priority inheritance (default) +@item INHERIT_PRIORITY - use priority inheritance +@item PRIORITY_CEILING - use priority ceiling +@item NO_PRIORITY_CEILING - do not use priority ceiling (default) +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + + + +Semaphores should not be made global unless remote +tasks must interact with the created semaphore. This is to +avoid the system overhead incurred by the creation of a global +semaphore. When a global semaphore is created, the semaphore's +name and id must be transmitted to every node in the system for +insertion in the local copy of the global object table. + +The total number of global objects, including +semaphores, is limited by the maximum_global_objects field in +the Configuration Table. + +@page +@ifinfo +@node SEMAPHORE_IDENT - Get ID of a semaphore, SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_CREATE - Create a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_IDENT - Get ID of a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore identified successfully@* +@code{INVALID_NAME} - semaphore name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the semaphore id associated +with the semaphore name. If the semaphore name is not unique, +then the semaphore id will match one of the semaphores with that +name. However, this semaphore id is not guaranteed to +correspond to the desired semaphore. The semaphore id is used +by other semaphore related directives to access the semaphore. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the semaphores exported by +the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_DELETE - Delete a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore deleted successfully@* +@code{INVALID_ID} - invalid semaphore id@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@* +@code{RESOURCE_IN_USE} - binary semaphore is in use + +@subheading DESCRIPTION: + +This directive deletes the semaphore specified by id. +All tasks blocked waiting to acquire the semaphore will be +readied and returned a status code which indicates that the +semaphore was deleted. The SMCB for this semaphore is reclaimed +by RTEMS. + +@subheading NOTES: + +The calling task will be preempted if it is enabled +by the task's execution mode and a higher priority local task is +waiting on the deleted semaphore. The calling task will NOT be +preempted if all of the tasks that are waiting on the semaphore +are remote tasks. + +The calling task does not have to be the task that +created the semaphore. Any local task that knows the semaphore +id can delete the semaphore. + +When a global semaphore is deleted, the semaphore id +must be transmitted to every node in the system for deletion +from the local copy of the global object table. + +The semaphore must reside on the local node, even if +the semaphore was created with the GLOBAL option. + +Proxies, used to represent remote tasks, are +reclaimed when the semaphore is deleted. + +@page +@ifinfo +@node SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_RELEASE - Release a semaphore, SEMAPHORE_DELETE - Delete a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_OBTAIN - Acquire a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_obtain( + rtems_id id, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore obtained successfully@* +@code{UNSATISFIED} - semaphore not available@* +@code{TIMEOUT} - timed out waiting for semaphore@* +@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting@* +@code{INVALID_ID} - invalid semaphore id + +@subheading DESCRIPTION: + +This directive acquires the semaphore specified by +id. The WAIT and NO_WAIT components of the options parameter +indicate whether the calling task wants to wait for the +semaphore to become available or return immediately if the +semaphore is not currently available. With either WAIT or +NO_WAIT, if the current semaphore count is positive, then it is +decremented by one and the semaphore is successfully acquired by +returning immediately with a successful return code. + +If the calling task chooses to return immediately and +the current semaphore count is zero or negative, then a status +code is returned indicating that the semaphore is not available. +If the calling task chooses to wait for a semaphore and the +current semaphore count is zero or negative, then it is +decremented by one and the calling task is placed on the +semaphore's wait queue and blocked. If the semaphore was +created with the PRIORITY attribute, then the calling task is +inserted into the queue according to its priority. However, if +the semaphore was created with the FIFO attribute, then the +calling task is placed at the rear of the wait queue. If the +binary semaphore was created with the INHERIT_PRIORITY +attribute, then the priority of the task currently holding the +binary semaphore is guaranteed to be greater than or equal to +that of the blocking task. If the binary semaphore was created +with the PRIORITY_CEILING attribute, a task successfully obtains +the semaphore, and the priority of that task is greater than the +ceiling priority for this semaphore, then the priority of the +task obtaining the semaphore is elevated to that of the ceiling. + +The timeout parameter specifies the maximum interval +the calling task is willing to be blocked waiting for the +semaphore. If it is set to NO_TIMEOUT, then the calling task +will wait forever. If the semaphore is available or the NO_WAIT +option component is set, then timeout is ignored. + +@subheading NOTES: +The following semaphore acquisition option constants +are defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Attempting to obtain a global semaphore which does not reside on +the local node will generate a request to the remote node to +access the semaphore. If the semaphore is not available and +NO_WAIT was not specified, then the task must be blocked until +the semaphore is released. A proxy is allocated on the remote +node to represent the task until the semaphore is released. + +@page +@ifinfo +@node SEMAPHORE_RELEASE - Release a semaphore, Message Manager, SEMAPHORE_OBTAIN - Acquire a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_RELEASE - Release a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_release( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore released successfully@* +@code{INVALID_ID} - invalid semaphore id@* +@code{NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore + +@subheading DESCRIPTION: + +This directive releases the semaphore specified by +id. The semaphore count is incremented by one. If the count is +zero or negative, then the first task on this semaphore's wait +queue is removed and unblocked. The unblocked task may preempt +the running task if the running task's preemption mode is +enabled and the unblocked task has a higher priority than the +running task. + +@subheading NOTES: + +The calling task may be preempted if it causes a +higher priority task to be made ready for execution. + +Releasing a global semaphore which does not reside on +the local node will generate a request telling the remote node +to release the semaphore. + +If the task to be unblocked resides on a different +node from the semaphore, then the semaphore allocation is +forwarded to the appropriate node, the waiting task is +unblocked, and the proxy used to represent the task is reclaimed. + +The outermost release of a local, binary, priority +inheritance or priority ceiling semaphore may result in the +calling task having its priority lowered. This will occur if +the calling task holds no other binary semaphores and it has +inherited a higher priority. + diff --git a/doc/user/signal.t b/doc/user/signal.t new file mode 100644 index 0000000000..f6a53c1967 --- /dev/null +++ b/doc/user/signal.t @@ -0,0 +1,354 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Signal Manager, Signal Manager Introduction, EVENT_RECEIVE - Receive event condition, 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 provides the capabilities required +for asynchronous communication. The directives provided by the +signal manager are: + +@itemize @bullet +@item @code{signal_catch} - Establish an ASR +@item @code{signal_send} - Send signal set to a task +@end itemize + +@ifinfo +@node Signal Manager Background, Signal Manager Definitions, Signal Manager Introduction, Signal Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Signal Manager Definitions:: +* A Comparison of ASRs and ISRs:: +* Building a Signal Set:: +* Building an ASR's Mode:: +@end menu +@end ifinfo + +@ifinfo +@node Signal Manager Definitions, A Comparison of ASRs and ISRs, Signal Manager Background, Signal Manager Background +@end ifinfo +@subsection Signal Manager Definitions + +The signal manager allows a task to optionally define +an asynchronous signal routine (ASR). An ASR is to a task what +an ISR is to an application's set of tasks. When the processor +is interrupted, the execution of an application is also +interrupted and an ISR is given control. Similarly, when a +signal is sent to a task, that task's execution path will be +"interrupted" by the ASR. Sending a signal to a task has no +effect on the receiving task's current execution state. + +A signal flag is used by a task (or ISR) to inform +another task of the occurrence of a significant situation. +Thirty-two signal flags are associated with each task. A +collection of one or more signals is referred to as a signal +set. A signal set is posted when it is directed (or sent) to a +task. A pending signal is a signal that has been sent to a task +with a valid ASR, but has not been processed by that task's ASR. + + +@ifinfo +@node A Comparison of ASRs and ISRs, Building a Signal Set, Signal Manager Definitions, Signal Manager Background +@end ifinfo +@subsection A Comparison of ASRs and ISRs + +The format of an ASR is similar to that of an ISR +with the following exceptions: + +@itemize @bullet +@item ISRs are scheduled by the processor hardware. ASRs are +scheduled by RTEMS. + +@item ISRs do not execute in the context of a task and may +invoke only a subset of directives. ASRs execute in the context +of a task and may execute any directive. + +@item When an ISR is invoked, it is passed the vector number +as its argument. When an ASR is invoked, it is passed the +signal set as its argument. + +@item An ASR has a task mode which can be different from that +of the task. An ISR does not execute as a task and, as a +result, does not have a task mode. +@end itemize + +@ifinfo +@node Building a Signal Set, Building an ASR's Mode, A Comparison of ASRs and ISRs, Signal Manager Background +@end ifinfo +@subsection Building a Signal Set + +A signal set is built by a bitwise OR of the desired +signals. The set of valid signals is SIGNAL_0 through +SIGNAL_31. If a signal is not explicitly specified in the +signal set, then it is not present. Signal values are +specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as +each signal appears exactly once in the component list. + +This example demonstrates the signal parameter used +when sending the signal set consisting of SIGNAL_6, SIGNAL_15, +and SIGNAL_31. The signal parameter provided to the signal_send +directive should be SIGNAL_6 | SIGNAL_15 | SIGNAL_31. + +@ifinfo +@node Building an ASR's Mode, Signal Manager Operations, Building a Signal Set, Signal Manager Background +@end ifinfo +@subsection Building an ASR's Mode + +In general, an ASR's mode is built by a bitwise OR of +the desired mode components. The set of valid mode components +is the same as those allowed with the task_create and task_mode +directives. A complete list of mode options is provided in the +following table: + +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize + +Mode values are specifically designed to be mutually +exclusive, therefore bitwise OR and addition operations are +equivalent as long as each mode appears exactly once in the +component list. A mode component listed as a default is not +required to appear in the mode list, although it is a good +programming practice to specify default components. If all +defaults are desired, the mode DEFAULT_MODES should be specified +on this call. + +This example demonstrates the mode parameter used +with the signal_catch to establish an ASR which executes at +interrupt level three and is non-preemptible. The mode should +be set to INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the +desired processor mode and interrupt level. + +@ifinfo +@node Signal Manager Operations, Establishing an ASR, Building an ASR's Mode, Signal Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Establishing an ASR:: +* Sending a Signal Set:: +* Processing an ASR:: +@end menu +@end ifinfo + +@ifinfo +@node Establishing an ASR, Sending a Signal Set, Signal Manager Operations, Signal Manager Operations +@end ifinfo +@subsection Establishing an ASR + +The signal_catch directive establishes an ASR for the +calling task. The address of the ASR and its execution mode are +specified to this directive. The ASR's mode is distinct from +the task's mode. For example, the task may allow preemption, +while that task's ASR may have preemption disabled. Until a +task calls signal_catch the first time, its ASR is invalid, and +no signal sets can be sent to the task. + +A task may invalidate its ASR and discard all pending +signals by calling signal_catch with a value of NULL for the +ASR's address. When a task's ASR is invalid, new signal sets +sent to this task are discarded. + +A task may disable ASR processing (NO_ASR) via the +task_mode directive. When a task's ASR is disabled, the signals +sent to it are left pending to be processed later when the ASR +is enabled. + +Any directive that can be called from a task can also +be called from an ASR. A task is only allowed one active ASR. +Thus, each call to signal_catch replaces the previous one. + +Normally, signal processing is disabled for the ASR's +execution mode, but if signal processing is enabled for the ASR, +the ASR must be reentrant. + +@ifinfo +@node Sending a Signal Set, Processing an ASR, Establishing an ASR, Signal Manager Operations +@end ifinfo +@subsection Sending a Signal Set + +The signal_send directive allows both tasks and ISRs +to send signals to a target task. The target task and a set of +signals are specified to the signal_send directive. The sending +of a signal to a task has no effect on the execution state of +that task. If the task is not the currently running task, then +the signals are left pending and processed by the task's ASR the +next time the task is dispatched to run. The ASR is executed +immediately before the task is dispatched. If the currently +running task sends a signal to itself or is sent a signal from +an ISR, its ASR is immediately dispatched to run provided signal +processing is enabled. + +If an ASR with signals enabled is preempted by +another task or an ISR and a new signal set is sent, then a new +copy of the ASR will be invoked, nesting the preempted ASR. +Upon completion of processing the new signal set, control will +return to the preempted ASR. In this situation, the ASR must be +reentrant. + +Like events, identical signals sent to a task are not +queued. In other words, sending the same signal multiple times +to a task (without any intermediate signal processing occurring +for the task), has the same result as sending that signal to +that task once. + +@ifinfo +@node Processing an ASR, Signal Manager Directives, Sending a Signal Set, Signal Manager Operations +@end ifinfo +@subsection Processing an ASR + +Asynchronous signals were designed to provide the +capability to generate software interrupts. The processing of +software interrupts parallels that of hardware interrupts. As a +result, the differences between the formats of ASRs and ISRs is +limited to the meaning of the single argument passed to an ASR. +The ASR should have the following calling sequence and adhere to +C calling conventions: + +@example +rtems_asr user_routine( + rtems_signal_set signals +); +@end example + +When the ASR returns to RTEMS the mode and execution +path of the interrupted task (or ASR) is restored to the context +prior to entering the ASR. + +@ifinfo +@node Signal Manager Directives, SIGNAL_CATCH - Establish an ASR, Processing an ASR, Signal Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* SIGNAL_CATCH - Establish an ASR:: +* SIGNAL_SEND - Send signal set to a task:: +@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 SIGNAL_CATCH - Establish an ASR, SIGNAL_SEND - Send signal set to a task, Signal Manager Directives, Signal Manager Directives +@end ifinfo +@subsection SIGNAL_CATCH - Establish an ASR + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_signal_catch( + rtems_asr_entry asr_handler, + rtems_mode mode +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive establishes an asynchronous signal +routine (ASR) for the calling task. The asr_handler parameter +specifies the entry point of the ASR. If asr_handler is NULL, +the ASR for the calling task is invalidated and all pending +signals are cleared. Any signals sent to a task with an invalid +ASR are discarded. The mode parameter specifies the execution +mode for the ASR. This execution mode supersedes the task's +execution mode while the ASR is executing. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following task mode constants are defined by RTEMS: + +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize + +@page +@ifinfo +@node SIGNAL_SEND - Send signal set to a task, Partition Manager, SIGNAL_CATCH - Establish an ASR, Signal Manager Directives +@end ifinfo +@subsection SIGNAL_SEND - Send signal set to a task + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_signal_send( + rtems_id id, + rtems_signal_set signal_set +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - signal sent successfully@* +@code{INVALID_ID} - task id invalid@* +@code{NOT_DEFINED} - ASR invalid + +@subheading DESCRIPTION: + +This directive sends a signal set to the task +specified in id. The signal_set parameter contains the signal +set to be sent to the task. + +If a caller sends a signal set to a task with an +invalid ASR, then an error code is returned to the caller. If a +caller sends a signal set to a task whose ASR is valid but +disabled, then the signal set will be caught and left pending +for the ASR to process when it is enabled. If a caller sends a +signal set to a task with an ASR that is both valid and enabled, +then the signal set is caught and the ASR will execute the next +time the task is dispatched to run. + +@subheading NOTES: + +Sending a signal set to a task has no effect on that +task's state. If a signal set is sent to a blocked task, then +the task will remain blocked and the signals will be processed +when the task becomes the running task. + +Sending a signal set to a global task which does not +reside on the local node will generate a request telling the +remote node to send the signal set to the specified task. + diff --git a/doc/user/states.gif b/doc/user/states.gif new file mode 100644 index 0000000000..cd0799ea2e Binary files /dev/null and b/doc/user/states.gif differ diff --git a/doc/user/task.t b/doc/user/task.t new file mode 100644 index 0000000000..730bb73ad2 --- /dev/null +++ b/doc/user/task.t @@ -0,0 +1,1313 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Task Manager, Task Manager Introduction, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Top +@end ifinfo + +@chapter Task Manager + +@ifinfo +@menu +* Task Manager Introduction:: +* Task Manager Background:: +* Task Manager Operations:: +* Task Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Task Manager Introduction, Task Manager Background, Task Manager, Task Manager +@end ifinfo +@section Introduction + +The task manager provides a comprehensive set of directives to +create, delete, and administer tasks. The directives provided +by the task manager are: + +@itemize @bullet +@item @code{task_create} - Create a task +@item @code{task_ident} - Get ID of a task +@item @code{task_start} - Start a task +@item @code{task_restart} - Restart a task +@item @code{task_delete} - Delete a task +@item @code{task_suspend} - Suspend a task +@item @code{task_resume} - Resume a task +@item @code{task_set_priority} - Set task priority +@item @code{task_mode} - Change current task's mode +@item @code{task_get_note} - Get task notepad entry +@item @code{task_set_note} - Set task notepad entry +@item @code{task_wake_after} - Wake up after interval +@item @code{task_wake_when} - Wake up when specified +@end itemize + +@ifinfo +@node Task Manager Background, Task Definition, Task Manager Introduction, Task Manager +@end ifinfo + +@section Background + +@ifinfo +@menu +* Task Definition:: +* Task Control Block:: +* Task States:: +* Task Priority:: +* Task Mode:: +* Accessing Task Arguments:: +* Floating Point Considerations:: +* Building a Task's Attribute Set:: +* Building a Mode and Mask:: +@end menu + +@end ifinfo + +@ifinfo +@node Task Definition, Task Control Block, Task Manager Background, Task Manager Background +@end ifinfo + +@subsection Task Definition + +Many definitions of a task have been proposed in computer +literature. Unfortunately, none of these definitions +encompasses all facets of the concept in a manner which is +operating system independent. Several of the more common +definitions are provided to enable each user to select a +definition which best matches their own experience and +understanding of the task concept: + +@itemize @bullet +@item a "dispatchable" unit. + +@item an entity to which the processor is allocated. + +@item an atomic unit of a real-time, multiprocessor system. + +@item single threads of execution which concurrently compete for resources. + +@item a sequence of closely related computations which can execute +concurrently with other computational sequences. + +@end itemize + +From RTEMS' perspective, a task is the smallest thread of +execution which can compete on its own for system resources. A +task is manifested by the existence of a task control block +(TCB). + +@ifinfo +@node Task Control Block, Task States, Task Definition, Task Manager Background +@end ifinfo +@subsection Task Control Block + +The Task Control Block (TCB) is an RTEMS defined data structure +which contains all the information that is pertinent to the +execution of a task. During system initialization, RTEMS +reserves a TCB for each task configured. A TCB is allocated +upon creation of the task and is returned to the TCB free list +upon deletion of the task. + +The TCB's elements are modified as a result of system calls made +by the application in response to external and internal stimuli. +TCBs are the only RTEMS internal data structure that can be +accessed by an application via user extension routines. The TCB +contains a task's name, ID, current priority, current and +starting states, execution mode, set of notepad locations, TCB +user extension pointer, scheduling control structures, as well +as data required by a blocked task. + +A task's context is stored in the TCB when a task switch occurs. +When the task regains control of the processor, its context is +restored from the TCB. When a task is restarted, the initial +state of the task is restored from the starting context area in +the task's TCB. + +@ifinfo +@node Task States, Task Priority, Task Control Block, Task Manager Background +@end ifinfo +@subsection Task States + +A task may exist in one of the following five states: + +@itemize @bullet +@item @code{executing} - Currently scheduled to the CPU +@item @code{ready} - May be scheduled to the CPU +@item @code{blocked} - Unable to be scheduled to the CPU +@item @code{dormant} - Created task that is not started +@item @code{non-existent} - Uncreated or deleted task +@end itemize + +An active task may occupy the executing, ready, blocked or +dormant state, otherwise the task is considered non-existent. +One or more tasks may be active in the system simultaneously. +Multiple tasks communicate, synchronize, and compete for system +resources with each other via system calls. The multiple tasks +appear to execute in parallel, but actually each is dispatched +to the CPU for periods of time determined by the RTEMS +scheduling algorithm. The scheduling of a task is based on its +current state and priority. + +@ifinfo +@node Task Priority, Task Mode, Task States, Task Manager Background +@end ifinfo +@subsection Task Priority + +A task's priority determines its importance in relation to the +other tasks executing on the same processor. RTEMS supports 255 +levels of priority ranging from 1 to 255. Tasks of numerically +smaller priority values are more important tasks than tasks of +numerically larger priority values. For example, a task at +priority level 5 is of higher privilege than a task at priority +level 10. There is no limit to the number of tasks assigned to +the same priority. + +Each task has a priority associated with it at all times. The +initial value of this priority is assigned at task creation +time. The priority of a task may be changed at any subsequent +time. + +Priorities are used by the scheduler to determine which ready +task will be allowed to execute. In general, the higher the +logical priority of a task, the more likely it is to receive +processor execution time. + +@ifinfo +@node Task Mode, Accessing Task Arguments, Task Priority, Task Manager Background +@end ifinfo +@subsection Task Mode + +A task's mode is a combination of the following four components: + +@itemize @bullet +@item preemption +@item ASR processing +@item timeslicing +@item interrupt level +@end itemize + +It is used to modify RTEMS' scheduling process and to alter the +execution environment of the task. + +The preemption component allows a task to determine when control +of the processor is relinquished. If preemption is disabled +(NO_PREEMPT), the task will retain control of the processor as +long as it is in the executing state -- even if a higher +priority task is made ready. If preemption is enabled (PREEMPT) +and a higher priority task is made ready, then the processor +will be taken away from the current task immediately and given +to the higher priority task. + +The timeslicing component is used by the RTEMS scheduler to +determine how the processor is allocated to tasks of equal +priority. If timeslicing is enabled (TIMESLICE), then RTEMS +will limit the amount of time the task can execute before the +processor is allocated to another ready task of equal priority. +The length of the timeslice is application dependent and +specified in the Configuration Table. If timeslicing is +disabled (NO_TIMESLICE), then the task will be allowed to +execute until a task of higher priority is made ready. If +NO_PREEMPT is selected, then the timeslicing component is +ignored by the scheduler. + +The asynchronous signal processing component is used to +determine when received signals are to be processed by the task. + If signal processing is enabled (ASR), then signals sent to the +task will be processed the next time the task executes. If +signal processing is disabled (NO_ASR), then all signals +received by the task will remain posted until signal processing +is enabled. This component affects only tasks which have +established a routine to process asynchronous signals. + +The interrupt level component is used to determine which +interrupts will be enabled when the task is executing. +INTERRUPT_LEVEL(n) specifies that the task will execute at +interrupt level n. + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +@ifinfo +@node Accessing Task Arguments, Floating Point Considerations, Task Mode, Task Manager Background +@end ifinfo +@subsection Accessing Task Arguments + +All RTEMS tasks are invoked with a single argument which is +specified when they are started or restarted. The argument is +commonly used to communicate startup information to the task. +The simplest manner in which to define a task which accesses it +argument is: + +@example +rtems_task user_task( + rtems_task_argument argument +); +@end example + +Application tasks requiring more information may view this +single argument as an index into an array of parameter blocks. + +@ifinfo +@node Floating Point Considerations, Building a Task's Attribute Set, Accessing Task Arguments, Task Manager Background +@end ifinfo +@subsection Floating Point Considerations + +Creating a task with the FLOATING_POINT flag results in +additional memory being allocated for the TCB to store the state +of the numeric coprocessor during task switches. This +additional memory is NOT allocated for NO_FLOATING_POINT tasks. +Saving and restoring the context of a FLOATING_POINT task takes +longer than that of a NO_FLOATING_POINT task because of the +relatively large amount of time required for the numeric +coprocessor to save or restore its computational state. + +Since RTEMS was designed specifically for embedded military +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. + +Although the overhead imposed by FLOATING_POINT tasks is +minimal, some applications may wish to completely avoid the +overhead associated with FLOATING_POINT tasks and still utilize +a numeric coprocessor. By preventing a task from being +preempted while performing a sequence of floating point +operations, a NO_FLOATING_POINT task can utilize the numeric +coprocessor without incurring the overhead of a FLOATING_POINT +context switch. This approach also avoids the allocation of a +floating point context area. However, if this approach is taken +by the application designer, NO tasks should be created as +FLOATING_POINT tasks. Otherwise, the floating point context +will not be correctly maintained because RTEMS assumes that the +state of the numeric coprocessor will not be altered by +NO_FLOATING_POINT tasks. + +If the supported processor type does not have hardware floating +capabilities or a standard numeric coprocessor, RTEMS will not +provide built-in support for hardware floating point on that +processor. In this case, all tasks are considered +NO_FLOATING_POINT whether created as FLOATING_POINT or +NO_FLOATING_POINT tasks. A floating point emulation software +library must be utilized for floating point operations. + +On some processors, it is possible to disable the floating point +unit dynamically. If this capability is supported by the target +processor, then RTEMS will utilize this capability to enable the +floating point unit only for tasks which are created with the +FLOATING_POINT attribute. The consequence of a +NO_FLOATING_POINT task attempting to access the floating point +unit is CPU dependent but will i general result in an exception +condition. + +@ifinfo +@node Building a Task's Attribute Set, Building a Mode and Mask, Floating Point Considerations, Task Manager Background +@end ifinfo +@subsection Building a Task's Attribute Set + +In general, an attribute set is built by a bitwise OR of the +desired components. The set of valid task attribute components +is listed below: + +@itemize @bullet +@item @code{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{GLOBAL} - global task +@end itemize + +Attribute values are specifically designed to be mutually +exclusive, therefore bitwise OR and addition operations are +equivalent as long as each attribute appears exactly once in the +component list. A component listed as a default is not required +to appear in the component list, although it is a good +programming practice to specify default components. If all +defaults are desired, then DEFAULT_ATTRIBUTES should be used. + +This example demonstrates the attribute_set parameter needed to +create a local task which utilizes the numeric coprocessor. The +attribute_set parameter could be FLOATING_POINT or LOCAL | +FLOATING_POINT. The attribute_set parameter can be set to +FLOATING_POINT because LOCAL is the default for all created +tasks. If the task were global and used the numeric +coprocessor, then the attribute_set parameter would be GLOBAL | +FLOATING_POINT. + +@ifinfo +@node Building a Mode and Mask, Task Manager Operations, Building a Task's Attribute Set, Task Manager Background +@end ifinfo +@subsection Building a Mode and Mask + +In general, a mode and its corresponding mask is built by a +bitwise OR of the desired components. The set of valid mode +constants and each mode's corresponding mask constant is +listed below: + +@ifset use-ascii +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Mode ConstantMask ConstantDescription
    PREEMPTPREEMPT_MASKenables preemption
    NO_PREEMPTPREEMPT_MASKdisables preemption
    NO_TIMESLICETIMESLICE_MASKdisables timeslicing
    TIMESLICETIMESLICE_MASKenables timeslicing
    ASRASR_MASKenables ASR processing
    NO_ASRASR_MASKdisables ASR processing
    INTERRUPT_LEVEL(0)INTERRUPT_MASKenables all interrupts
    INTERRUPT_LEVEL(n)INTERRUPT_MASKsets interrupts level n
    +
    +@end html +@end ifset + + + + +Mode values are specifically designed to be mutually exclusive, +therefore bitwise OR and addition operations are equivalent as +long as each mode appears exactly once in the component list. A +mode component listed as a default is not required to appear in +the mode component list, although it is a good programming +practice to specify default components. If all defaults are +desired, the mode DEFAULT_MODES and the mask ALL_MODE_MASKS +should be used. + +The following example demonstrates the mode and mask parameters +used with the task_mode directive to place a task at interrupt +level 3 and make it non-preemptible. The mode should be set to +INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the desired +preemption mode and interrupt level, while the mask parameter +should be set to INTERRUPT_MASK | NO_PREEMPT_MASK to indicate +that the calling task's interrupt level and preemption mode are +being altered. + +@ifinfo +@node Task Manager Operations, Creating Tasks, Building a Mode and Mask, Task Manager +@end ifinfo + +@section Operations + +@ifinfo +@menu +* Creating Tasks:: +* Obtaining Task IDs:: +* Starting and Restarting Tasks:: +* Suspending and Resuming Tasks:: +* Delaying the Currently Executing Task:: +* Changing Task Priority:: +* Changing Task Mode:: +* Notepad Locations:: +* Task Deletion:: +@end menu +@end ifinfo + +@ifinfo +@node Creating Tasks, Obtaining Task IDs, Task Manager Operations, Task Manager Operations +@end ifinfo +@subsection Creating Tasks + +The task_create directive creates a task by allocating a task +control block, assigning the task a user-specified name, +allocating it a stack and floating point context area, setting a +user-specified initial priority, setting a user-specified +initial mode, and assigning it a task ID. Newly created tasks +are initially placed in the dormant state. All RTEMS tasks +execute in the most privileged mode of the processor. + +@ifinfo +@node Obtaining Task IDs, Starting and Restarting Tasks, Creating Tasks, Task Manager Operations +@end ifinfo +@subsection Obtaining Task IDs + +When a task is created, RTEMS generates a unique task ID and +assigns it to the created task until it is deleted. The task ID +may be obtained by either of two methods. First, as the result +of an invocation of the task_create directive, the task ID is +stored in a user provided location. Second, the task ID may be +obtained later using the task_ident directive. The task ID is +used by other directives to manipulate this task. + +@ifinfo +@node Starting and Restarting Tasks, Suspending and Resuming Tasks, Obtaining Task IDs, Task Manager Operations +@end ifinfo +@subsection Starting and Restarting Tasks + +The task_start directive is used to place a dormant task in the +ready state. This enables the task to compete, based on its +current priority, for the processor and other system resources. +Any actions, such as suspension or change of priority, performed +on a task prior to starting it are nullified when the task is +started. + +With the task_start directive the user specifies the task's +starting address and argument. The argument is used to +communicate some startup information to the task. As part of +this directive, RTEMS initializes the task's stack based upon +the task's initial execution mode and start address. The +starting argument is passed to the task in accordance with the +target processor's calling convention. + +The task_restart directive restarts a task at its initial +starting address with its original priority and execution mode, +but with a possibly different argument. The new argument may be +used to distinguish between the original invocation of the task +and subsequent invocations. The task's stack and control block +are modified to reflect their original creation values. +Although references to resources that have been requested are +cleared, resources allocated by the task are NOT automatically +returned to RTEMS. A task cannot be restarted unless it has +previously been started (i.e. dormant tasks cannot be +restarted). All restarted tasks are placed in the ready state. + +@ifinfo +@node Suspending and Resuming Tasks, Delaying the Currently Executing Task, Starting and Restarting Tasks, Task Manager Operations +@end ifinfo +@subsection Suspending and Resuming Tasks + +The task_suspend directive is used to place either the caller or +another task into a suspended state. The task remains suspended +until a task_resume directive is issued. This implies that a +task may be suspended as well as blocked waiting either to +acquire a resource or for the expiration of a timer. + +The task_resume directive is used to remove another task from +the suspended state. If the task is not also blocked, resuming +it will place it in the ready state, allowing it to once again +compete for the processor and resources. If the task was +blocked as well as suspended, this directive clears the +suspension and leaves the task in the blocked state. + +@ifinfo +@node Delaying the Currently Executing Task, Changing Task Priority, Suspending and Resuming Tasks, Task Manager Operations +@end ifinfo +@subsection Delaying the Currently Executing Task + +The task_wake_after directive creates a sleep timer which allows +a task to go to sleep for a specified interval. The task is +blocked until the delay interval has elapsed, at which time the +task is unblocked. A task calling the task_wake_after directive +with a delay interval of YIELD_PROCESSOR ticks will yield the +processor to any other ready task of equal or greater priority +and remain ready to execute. + +The task_wake_when directive creates a sleep timer which allows +a task to go to sleep until a specified date and time. The +calling task is blocked until the specified date and time has +occurred, at which time the task is unblocked. + +@ifinfo +@node Changing Task Priority, Changing Task Mode, Delaying the Currently Executing Task, Task Manager Operations +@end ifinfo +@subsection Changing Task Priority + +The task_set_priority directive is used to obtain or change the +current priority of either the calling task or another task. If +the new priority requested is CURRENT_PRIORITY or the task's +actual priority, then the current priority will be returned and +the task's priority will remain unchanged. If the task's +priority is altered, then the task will be scheduled according +to its new priority. + +The task_restart directive resets the priority of a task to its +original value. + +@ifinfo +@node Changing Task Mode, Notepad Locations, Changing Task Priority, Task Manager Operations +@end ifinfo +@subsection Changing Task Mode + +The task_mode directive is used to obtain or change the current +execution mode of the calling task. A task's execution mode is +used to enable preemption, timeslicing, ASR processing, and to +set the task's interrupt level. + +The task_restart directive resets the mode of a task to its +original value. + +@ifinfo +@node Notepad Locations, Task Deletion, Changing Task Mode, Task Manager Operations +@end ifinfo +@subsection Notepad Locations + +RTEMS provides sixteen notepad locations for each task. Each +notepad location may contain a note consisting of four bytes of +information. RTEMS provides two directives, task_set_note and +task_get_note, that enable a user to access and change the +notepad locations. The task_set_note directive enables the user +to set a task's notepad entry to a specified note. The +task_get_note directive allows the user to obtain the note +contained in any one of the sixteen notepads of a specified task. + +@ifinfo +@node Task Deletion, Task Manager Directives, Notepad Locations, Task Manager Operations +@end ifinfo +@subsection Task Deletion + +RTEMS provides the task_delete directive to allow a task to +delete itself or any other task. This directive removes all +RTEMS references to the task, frees the task's control block, +removes it from resource wait queues, and deallocates its stack +as well as the optional floating point context. The task's name +and ID become inactive at this time, and any subsequent +references to either of them is invalid. In fact, RTEMS may +reuse the task ID for another task which is created later in the +application. + +Unexpired delay timers (i.e. those used by task_wake_after and +task_wake_when) and timeout timers associated with the task are +automatically deleted, however, other resources dynamically +allocated by the task are NOT automatically returned to RTEMS. +Therefore, before a task is deleted, all of its dynamically +allocated resources should be deallocated by the user. This may +be accomplished by instructing the task to delete itself rather +than directly deleting the task. Other tasks may instruct a +task to delete itself by sending a "delete self" message, event, +or signal, or by restarting the task with special arguments +which instruct the task to delete itself. + +@ifinfo +@node Task Manager Directives, TASK_CREATE - Create a task, Task Deletion, Task Manager +@end ifinfo + +@section Directives + +@ifinfo +@menu +* TASK_CREATE - Create a task:: +* TASK_IDENT - Get ID of a task:: +* TASK_START - Start a task:: +* TASK_RESTART - Restart a task:: +* TASK_DELETE - Delete a task:: +* TASK_SUSPEND - Suspend a task:: +* TASK_RESUME - Resume a task:: +* TASK_SET_PRIORITY - Set task priority:: +* TASK_MODE - Change current task's mode:: +* TASK_GET_NOTE - Get task notepad entry:: +* TASK_SET_NOTE - Set task notepad entry:: +* TASK_WAKE_AFTER - Wake up after interval:: +* TASK_WAKE_WHEN - Wake up when specified:: +@end menu +@end ifinfo + +This section details the task 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 TASK_CREATE - Create a task, TASK_IDENT - Get ID of a task, Task Manager Directives, Task Manager Directives +@end ifinfo +@subsection TASK_CREATE - Create a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + rtems_unsigned32 stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_SIZE} - stack too small@* +@code{INVALID_PRIORITY} - invalid task priority@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many tasks created@* +@code{UNSATISFIED} - not enough memory for stack/FP context@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: +This directive creates a task which resides on the local node. +It allocates and initializes a TCB, a stack, and an optional +floating point context area. The mode parameter contains values +which sets the task's initial execution mode. The +FLOATING_POINT attribute should be specified if the created task +is to use a numeric coprocessor. For performance reasons, it is +recommended that tasks not using the numeric coprocessor should +specify the NO_FLOATING_POINT attribute. If the GLOBAL +attribute is specified, the task can be accessed from remote +nodes. The task id, returned in id, is used in other task +related directives to access the task. When created, a task is +placed in the dormant state and can only be made ready to +execute using the directive task_start. + +@subheading NOTES: +This directive will not cause the calling task to be preempted. + +Valid task priorities range from a high of 1 to a low of 255. + +RTEMS supports a maximum of 256 interrupt levels which are +mapped onto the interrupt levels actually supported by the +target processor. + +The requested stack size should be at least MINIMUM_STACK_SIZE +bytes. The value of MINIMUM_STACK_SIZE is processor dependent. +Application developers should consider the stack usage of the +device drivers when calculating the stack size required for +tasks which utilize the driver. + +The following task attribute constants are defined by RTEMS: + +@itemize @bullet +@item @code{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{GLOBAL} - global task +@end itemize + +The following task mode constants are defined by RTEMS: + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +Tasks should not be made global unless remote tasks must +interact with them. This avoids the system overhead incurred by +the creation of a global task. When a global task is created, +the task's name and id must be transmitted to every node in the +system for insertion in the local copy of the global object +table. + +The total number of global objects, including tasks, is limited +by the maximum_global_objects field in the Configuration Table. + +@page + +@ifinfo +@node TASK_IDENT - Get ID of a task, TASK_START - Start a task, TASK_CREATE - Create a task, Task Manager Directives +@end ifinfo +@subsection TASK_IDENT - Get ID of a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task identified successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: +This directive obtains the task id associated with the task name +specified in name. A task may obtain its own id by specifying +SELF or its own task name in name. If the task name is not +unique, then the task id returned will match one of the tasks +with that name. However, this task id is not guaranteed to +correspond to the desired task. The task id, returned in id, is +used in other task related directives to access the task. + +@subheading NOTES: +This directive will not cause the running task to be preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched with the +local node being searched first. All other nodes are searched +with the lowest numbered node searched first. + +If node is a valid node number which does not represent the +local node, then only the tasks exported by the designated node +are searched. + +This directive does not generate activity on remote nodes. It +accesses only the local copy of the global object table. + +@page + +@ifinfo +@node TASK_START - Start a task, TASK_RESTART - Restart a task, TASK_IDENT - Get ID of a task, Task Manager Directives +@end ifinfo +@subsection TASK_START - Start a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - ask started successfully@* +@code{INVALID_ADDRESS} - invalid task entry point@* +@code{INVALID_ID} - invalid task id@* +@code{INCORRECT_STATE} - task not in the dormant state@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task + +@subheading DESCRIPTION: +This directive readies the task, specified by tid, for execution +based on the priority and execution mode specified when the task +was created. The starting address of the task is given in +entry_point. The task's starting argument is contained in +argument. This argument can be a single value or used as an +index into an array of parameter blocks. + +@subheading NOTES: +The calling task will be preempted if its preemption mode is +enabled and the task being started has a higher priority. + +Any actions performed on a dormant task such as suspension or +change of priority are nullified when the task is initiated via +the task_start directive. + +@page + +@ifinfo +@node TASK_RESTART - Restart a task, TASK_DELETE - Delete a task, TASK_START - Start a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESTART - Restart a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{INCORRECT_STATE} - task never started@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task + +@subheading DESCRIPTION: +This directive resets the task specified by id to begin +execution at its original starting address. The task's priority +and execution mode are set to the original creation values. If +the task is currently blocked, RTEMS automatically makes the +task ready. A task can be restarted from any state, except the +dormant state. + +The task's starting argument is contained in argument. This +argument can be a single value or an index into an array of +parameter blocks. This new argument may be used to distinguish +between the initial task_start of the task and any ensuing calls +to task_restart of the task. This can be beneficial in deleting +a task. Instead of deleting a task using the task_delete +directive, a task can delete another task by restarting that +task, and allowing that task to release resources back to RTEMS +and then delete itself. + +@subheading NOTES: +If id is SELF, the calling task will be restarted and will not +return from this directive. + +The calling task will be preempted if its preemption mode is +enabled and the task being restarted has a higher priority. + +The task must reside on the local node, even if the task was +created with the GLOBAL option. + +@page + +@ifinfo +@node TASK_DELETE - Delete a task, TASK_SUSPEND - Suspend a task, TASK_RESTART - Restart a task, Task Manager Directives +@end ifinfo +@subsection TASK_DELETE - Delete a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task + +@subheading DESCRIPTION: +This directive deletes a task, either the calling task or +another task, as specified by id. RTEMS stops the execution of +the task and reclaims the stack memory, any allocated delay or +timeout timers, the TCB, and, if the task is FLOATING_POINT, its +floating point context area. RTEMS does not reclaim the +following resources: region segments, partition buffers, +semaphores, timers, or rate monotonic periods. + +@subheading NOTES: +A task is responsible for releasing its resources back to RTEMS +before deletion. To insure proper deallocation of resources, a +task should not be deleted unless it is unable to execute or +does not hold any RTEMS resources. If a task holds RTEMS +resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release +its resources and delete itself by restarting it with a special +argument or by sending it a message, an event, or a signal. + +Deletion of the current task (SELF) will force RTEMS to select +another task to execute. + +When a global task is deleted, the task id must be transmitted +to every node in the system for deletion from the local copy of +the global object table. + +The task must reside on the local node, even if the task was +created with the GLOBAL option. + +@page + +@ifinfo +@node TASK_SUSPEND - Suspend a task, TASK_RESUME - Resume a task, TASK_DELETE - Delete a task, Task Manager Directives +@end ifinfo +@subsection TASK_SUSPEND - Suspend a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_suspend( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{ALREADY_SUSPENDED} - task already suspended + +@subheading DESCRIPTION: +This directive suspends the task specified by id from further +execution by placing it in the suspended state. This state is +additive to any other blocked state that the task may already be +in. The task will not execute again until another task issues +the task_resume directive for this task and any blocked state +has been removed. + +@subheading NOTES: +The requesting task can suspend itself by specifying SELF as id. +In this case, the task will be suspended and a successful +return code will be returned when the task is resumed. + +Suspending a global task which does not reside on the local node +will generate a request to the remote node to suspend the +specified task. + +@page + +@ifinfo +@node TASK_RESUME - Resume a task, TASK_SET_PRIORITY - Set task priority, TASK_SUSPEND - Suspend a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESUME - Resume a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_resume( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{INCORRECT_STATE} - task not suspended + +@subheading DESCRIPTION: +This directive removes the task specified by id from the +suspended state. If the task is in the ready state after the +suspension is removed, then it will be scheduled to run. If the +task is still in a blocked state after the suspension is +removed, then it will remain in that blocked state. + +@subheading NOTES: +The running task may be preempted if its preemption mode is +enabled and the local task being resumed has a higher priority. + +Resuming a global task which does not reside on the local node +will generate a request to the remote node to resume the +specified task. + +@page + +@ifinfo +@node TASK_SET_PRIORITY - Set task priority, TASK_MODE - Change current task's mode, TASK_RESUME - Resume a task, Task Manager Directives +@end ifinfo +@subsection TASK_SET_PRIORITY - Set task priority + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task priority set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_PRIORITY} - invalid task priority + +@subheading DESCRIPTION: +This directive manipulates the priority of the task specified by +id. An id of SELF is used to indicate the calling task. When +new_priority is not equal to CURRENT_PRIORITY, the specified +task's previous priority is returned in old_priority. When +new_priority is CURRENT_PRIORITY, the specified task's current +priority is returned in old_priority. Valid priorities range +from a high of 1 to a low of 255. + +@subheading NOTES: +The calling task may be preempted if its preemption mode is +enabled and it lowers its own priority or raises another task's +priority. + +Setting the priority of a global task which does not reside on +the local node will generate a request to the remote node to +change the priority of the specified task. + +If the task specified by id is currently holding any binary +semaphores which use the priority inheritance algorithm, then +the task's priority cannot be lowered immediately. If the +task's priority were lowered immediately, then priority +inversion results. The requested lowering of the task's +priority will occur when the task has released all priority +inheritance binary semaphores. The task's priority can be +increased regardless of the task's use of priority inheritance +binary semaphores. + +@page + +@ifinfo +@node TASK_MODE - Change current task's mode, TASK_GET_NOTE - Get task notepad entry, TASK_SET_PRIORITY - Set task priority, Task Manager Directives +@end ifinfo +@subsection TASK_MODE - Change current task's mode + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task mode set successfully + +@subheading DESCRIPTION: +This directive manipulates the execution mode of the calling +task. A task's execution mode enables and disables preemption, +timeslicing, asynchronous signal processing, as well as +specifying the current interrupt level. To modify an execution +mode, the mode class(es) to be changed must be specified in the +mask parameter and the desired mode(s) must be specified in the +mode parameter. + +@subheading NOTES: +The calling task will be preempted if it enables preemption and +a higher priority task is ready to run. + +Enabling timeslicing has no effect if preemption is enabled. + +A task can obtain its current execution mode, without modifying +it, by calling this directive with a mask value of CURRENT_MODE. + +To temporarily disable the processing of a valid ASR, a task +should call this directive with the NO_ASR indicator specified +in mode. + +The set of task mode constants and each mode's corresponding +mask constant is provided in the following table: + +@ifset use-ascii +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Mode ConstantMask ConstantDescription
    PREEMPTPREEMPT_MASKenables preemption
    NO_PREEMPTPREEMPT_MASKdisables preemption
    NO_TIMESLICETIMESLICE_MASKdisables timeslicing
    TIMESLICETIMESLICE_MASKenables timeslicing
    ASRASR_MASKenables ASR processing
    NO_ASRASR_MASKdisables ASR processing
    INTERRUPT_LEVEL(0)INTERRUPT_MASKenables all interrupts
    INTERRUPT_LEVEL(n)INTERRUPT_MASKsets interrupts level n
    +
    +@end html +@end ifset + +@page + +@ifinfo +@node TASK_GET_NOTE - Get task notepad entry, TASK_SET_NOTE - Set task notepad entry, TASK_MODE - Change current task's mode, Task Manager Directives +@end ifinfo +@subsection TASK_GET_NOTE - Get task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_get_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 *note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - note obtained successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive returns the note contained in the notepad +location of the task specified by id. + +@subheading NOTES: +This directive will not cause the running task to be preempted. + +If id is set to SELF, the calling task accesses its own notepad. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through NOTEPAD_15. + +Getting a note of a global task which does not reside on the +local node will generate a request to the remote node to obtain +the notepad entry of the specified task. + +@page + +@ifinfo +@node TASK_SET_NOTE - Set task notepad entry, TASK_WAKE_AFTER - Wake up after interval, TASK_GET_NOTE - Get task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_SET_NOTE - Set task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task's note set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive sets the notepad entry for the task specified by +id to the value note. + +@subheading NOTES: +If id is set to SELF, the calling task accesses its own notepad +locations. + +This directive will not cause the running task to be preempted. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through NOTEPAD_15. + +Setting a notepad location of a global task which does not +reside on the local node will generate a request to the remote +node to set the specified notepad entry. + +@page + +@ifinfo +@node TASK_WAKE_AFTER - Wake up after interval, TASK_WAKE_WHEN - Wake up when specified, TASK_SET_NOTE - Set task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_AFTER - Wake up after interval + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_wake_after( + rtems_interval ticks +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: +This directive blocks the calling task for the specified number +of system clock ticks. When the requested interval has elapsed, +the task is made ready. The clock_tick directive automatically +updates the delay period. + +@subheading NOTES: +Setting the system date and time with the clock_set directive +has no effect on a task_wake_after blocked task. + +A task may give up the processor and remain in the ready state +by specifying a value of YIELD_PROCESSOR in ticks. + +The maximum timer interval that can be specified is the maximum +value which can be represented by the rtems_unsigned32 type. + +@page + +@ifinfo +@node TASK_WAKE_WHEN - Wake up when specified, Interrupt Manager, TASK_WAKE_AFTER - Wake up after interval, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_WHEN - Wake up when specified + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - awakened at date/time successfully@* +@code{INVALID_TIME_OF_DAY} - invalid time buffer@* +@code{NOT_DEFINED} - system date and time is not set + +@subheading DESCRIPTION: +This directive blocks a task until the date and time specified +in time_buffer. At the requested date and time, the calling +task will be unblocked and made ready to execute. + +@subheading NOTES: +The ticks portion of time_buffer structure is ignored. The +timing granularity of this directive is a second. diff --git a/doc/user/timer.t b/doc/user/timer.t new file mode 100644 index 0000000000..d0dcb8ba71 --- /dev/null +++ b/doc/user/timer.t @@ -0,0 +1,441 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Timer Manager, Timer Manager Introduction, CLOCK_TICK - Announce a clock tick, Top +@end ifinfo +@chapter Timer Manager +@ifinfo +@menu +* Timer Manager Introduction:: +* Timer Manager Background:: +* Timer Manager Operations:: +* Timer Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Timer Manager Introduction, Timer Manager Background, Timer Manager, Timer Manager +@end ifinfo +@section Introduction + +The timer manager provides support for timer +facilities. The directives provided by the timer manager are: + +@itemize @bullet +@item @code{timer_create} - Create a timer +@item @code{timer_ident} - Get ID of a timer +@item @code{timer_cancel} - Cancel a timer +@item @code{timer_delete} - Delete a timer +@item @code{timer_fire_after} - Fire timer after interval +@item @code{timer_fire_when} - Fire timer when specified +@item @code{timer_reset} - Reset an interval timer +@end itemize + + +@ifinfo +@node Timer Manager Background, Timers, Timer Manager Introduction, Timer Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Timers:: +* Timer Service Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Timers, Timer Service Routines, Timer Manager Background, Timer Manager Background +@end ifinfo +@subsection Timers + +A timer is an RTEMS object which allows the +application to schedule operations to occur at specific times in +the future. User supplied timer service routines are invoked by +the clock_tick directive when the timer fires. Timer service +routines may perform any operations or directives which normally +would be performed by the application code which invoked the +clock_tick directive. + +The timer can be used to implement watchdog routines +which only fire to denote that an application error has +occurred. The timer is reset at specific points in the +application to insure that the watchdog does not fire. Thus, if +the application does not reset the watchdog timer, then the +timer service routine will fire to indicate that the application +has failed to reach a reset point. This use of a timer is +sometimes referred to as a "keep alive" or a "deadman" timer. + +@ifinfo +@node Timer Service Routines, Timer Manager Operations, Timers, Timer Manager Background +@end ifinfo +@subsection Timer Service Routines + +The timer service routine should adhere to C calling +conventions and have a prototype similar to the following:: + +@example +rtems_timer_service_routine user_routine( + rtems_id timer_id, + void *user_data +); +@end example + + + +Where the timer_id parameter is the RTEMS object ID +of the timer which is being fired and user_data is a pointer to +user-defined information which may be utilized by the timer +service routine. The argument user_data may be NULL. + +@ifinfo +@node Timer Manager Operations, Creating a Timer, Timer Service Routines, Timer Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Timer:: +* Obtaining Timer IDs:: +* Initiating an Interval Timer:: +* Initiating a Time of Day Timer:: +* Canceling a Timer:: +* Resetting a Timer:: +* Deleting a Timer:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Timer, Obtaining Timer IDs, Timer Manager Operations, Timer Manager Operations +@end ifinfo +@subsection Creating a Timer + +The timer_create directive creates a timer by +allocating a Timer Control Block (TMCB), assigning the timer a +user-specified name, and assigning it a timer ID. Newly created +timers do not have a timer service routine associated with them +and are not active. + +@ifinfo +@node Obtaining Timer IDs, Initiating an Interval Timer, Creating a Timer, Timer Manager Operations +@end ifinfo +@subsection Obtaining Timer IDs + +When a timer is created, RTEMS generates a unique +timer ID and assigns it to the created timer until it is +deleted. The timer ID may be obtained by either of two methods. +First, as the result of an invocation of the timer_create +directive, the timer ID is stored in a user provided location. +Second, the timer ID may be obtained later using the timer_ident +directive. The timer ID is used by other directives to +manipulate this timer. + +@ifinfo +@node Initiating an Interval Timer, Initiating a Time of Day Timer, Obtaining Timer IDs, Timer Manager Operations +@end ifinfo +@subsection Initiating an Interval Timer + +The timer_fire_after directive initiates a timer to +fire a user provided timer service routine after the specified +number of clock ticks have elapsed. When the interval has +elapsed, the timer service routine will be invoked from the +clock_tick directive. + +@ifinfo +@node Initiating a Time of Day Timer, Canceling a Timer, Initiating an Interval Timer, Timer Manager Operations +@end ifinfo +@subsection Initiating a Time of Day Timer + +The timer_fire_when directive initiates a timer to +fire a user provided timer service routine when the specified +time of day has been reached. When the interval has elapsed, +the timer service routine will be invoked from the clock_tick +directive. + +@ifinfo +@node Canceling a Timer, Resetting a Timer, Initiating a Time of Day Timer, Timer Manager Operations +@end ifinfo +@subsection Canceling a Timer + +The timer_cancel directive is used to halt the +specified timer. Once canceled, the timer service routine will +not fire unless the timer is reinitiated. The timer can be +reinitiated using the timer_reset, timer_fire_after, and +timer_fire_when directives. + +@ifinfo +@node Resetting a Timer, Deleting a Timer, Canceling a Timer, Timer Manager Operations +@end ifinfo +@subsection Resetting a Timer + +The timer_reset directive is used to restore an +interval timer initiated by a previous invocation of +timer_fire_after to its original interval length. The timer +service routine is not changed or fired by this directive. + +@ifinfo +@node Deleting a Timer, Timer Manager Directives, Resetting a Timer, Timer Manager Operations +@end ifinfo +@subsection Deleting a Timer + +The timer_delete directive is used to delete a timer. +If the timer is running and has not expired, the timer is +automatically canceled. The timer's control block is returned +to the TMCB free list when it is deleted. A timer can be +deleted by a task other than the task which created the timer. +Any subsequent references to the timer's name and ID are invalid. + +@ifinfo +@node Timer Manager Directives, TIMER_CREATE - Create a timer, Deleting a Timer, Timer Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* TIMER_CREATE - Create a timer:: +* TIMER_IDENT - Get ID of a timer:: +* TIMER_CANCEL - Cancel a timer:: +* TIMER_DELETE - Delete a timer:: +* TIMER_FIRE_AFTER - Fire timer after interval:: +* TIMER_FIRE_WHEN - Fire timer when specified:: +* TIMER_RESET - Reset an interval timer:: +@end menu +@end ifinfo + +This section details the timer 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 TIMER_CREATE - Create a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives, Timer Manager Directives +@end ifinfo +@subsection TIMER_CREATE - Create a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_create( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer created successfully@* +@code{INVALID_NAME} - invalid timer name@* +@code{TOO_MANY} - too many timers created + +@subheading DESCRIPTION: + +This directive creates a timer. The assigned timer +id is returned in id. This id is used to access the timer with +other timer manager directives. For control and maintenance of +the timer, RTEMS allocates a TMCB from the local TMCB free pool +and initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node TIMER_IDENT - Get ID of a timer, TIMER_CANCEL - Cancel a timer, TIMER_CREATE - Create a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_IDENT - Get ID of a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer identified successfully@* +@code{INVALID_NAME} - timer name not found + +@subheading DESCRIPTION: + +This directive obtains the timer id associated with +the timer name to be acquired. If the timer name is not unique, +then the timer id will match one of the timers with that name. +However, this timer id is not guaranteed to correspond to the +desired timer. The timer id is used to access this timer in +other timer related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_CANCEL - Cancel a timer, TIMER_DELETE - Delete a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_CANCEL - Cancel a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_cancel( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer canceled successfully@* +@code{INVALID_ID} - invalid timer id + +@subheading DESCRIPTION: + +This directive cancels the timer id. This timer will +be reinitiated by the next invocation of timer_reset, +timer_fire_after, or timer_fire_when with id. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +@page +@ifinfo +@node TIMER_DELETE - Delete a timer, TIMER_FIRE_AFTER - Fire timer after interval, TIMER_CANCEL - Cancel a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_DELETE - Delete a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer deleted successfully@* +@code{INVALID_ID} - invalid timer id + +@subheading DESCRIPTION: + +This directive deletes the timer specified by id. If +the timer is running, it is automatically canceled. The TMCB +for the deleted timer is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A timer can be deleted by a task other than the task +which created the timer. + +@page +@ifinfo +@node TIMER_FIRE_AFTER - Fire timer after interval, TIMER_FIRE_WHEN - Fire timer when specified, TIMER_DELETE - Delete a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_FIRE_AFTER - Fire timer after interval + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer initiated successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{INVALID_NUMBER} - invalid interval + +@subheading DESCRIPTION: + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire after an +interval ticks clock ticks has passed. When the timer fires, +the timer service routine routine will be invoked with the +argument user_data. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_FIRE_WHEN - Fire timer when specified, TIMER_RESET - Reset an interval timer, TIMER_FIRE_AFTER - Fire timer after interval, Timer Manager Directives +@end ifinfo +@subsection TIMER_FIRE_WHEN - Fire timer when specified + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_fire_when( + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer initiated successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{NOT_DEFINED} - system date and time is not set@* +@code{INVALID_CLOCK} - invalid time of day + +@subheading DESCRIPTION: + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire at the time of +day specified by wall_time. When the timer fires, the timer +service routine routine will be invoked with the argument +user_data. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_RESET - Reset an interval timer, Semaphore Manager, TIMER_FIRE_WHEN - Fire timer when specified, Timer Manager Directives +@end ifinfo +@subsection TIMER_RESET - Reset an interval timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_reset( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer reset successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{NOT_DEFINED} - attempted to reset a when timer + +@subheading DESCRIPTION: + +This directive resets the timer associated with id. +This timer must have been previously initiated with a +timer_fire_after directive. If active the timer is canceled, +after which the timer is reinitiated using the same interval and +timer service routine which the original timer_fire_after +directive used. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + diff --git a/doc/user/userext.t b/doc/user/userext.t new file mode 100644 index 0000000000..8166aa1a0e --- /dev/null +++ b/doc/user/userext.t @@ -0,0 +1,649 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node User Extensions Manager, User Extensions Manager Introduction, Heterogeneous Systems, Top +@end ifinfo +@chapter User Extensions Manager +@ifinfo +@menu +* User Extensions Manager Introduction:: +* User Extensions Manager Background:: +* User Extensions Manager Operations:: +* User Extensions Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node User Extensions Manager Introduction, User Extensions Manager Background, User Extensions Manager, User Extensions Manager +@end ifinfo +@section Introduction + +The RTEMS User Extensions Manager allows the +application developer to augment the executive by allowing them +to supply extension routines which are invoked at critical +system events. The directives provided by the user extensions +manager are: + +@itemize @bullet +@item @code{extension_create} - Create an extension set +@item @code{extension_ident} - Get ID of an extension set +@item @code{extension_delete} - Delete an extension set +@end itemize + +@ifinfo +@node User Extensions Manager Background, Extension Sets, User Extensions Manager Introduction, User Extensions Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Extension Sets:: +* TCB Extension Area:: +* Extensions:: +* TASK_CREATE Extension:: +* TASK_START Extension:: +* TASK_RESTART Extension:: +* TASK_DELETE Extension:: +* TASK_SWITCH Extension:: +* TASK_POST_SWITCH Extension:: +* TASK_BEGIN Extension:: +* TASK_EXITTED Extension:: +* FATAL Error Extension:: +* Order of Invocation:: +@end menu +@end ifinfo + +User extension routines are invoked when the +following system events occur: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begin +@item Task exits +@item Fatal error detection +@end itemize + +These extensions are invoked as a function with +arguments that are appropriate to the system event. + +@ifinfo +@node Extension Sets, TCB Extension Area, User Extensions Manager Background, User Extensions Manager Background +@end ifinfo +@subsection Extension Sets + +An extension set is defined as a set of routines +which are invoked at each of the critical system events at which +user extension routines are invoked. Together a set of these +routines typically perform a specific functionality such as +performance monitoring or debugger support. RTEMS is informed of +the entry points which constitute an extension set via the +following structure: + +@example +@group +typedef struct @{ + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_post_switch_extension thread_post_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_error_extension fatal; +@} User_extensions_Table; +@end group +@end example + + +RTEMS allows the user to have multiple extension sets +active at the same time. First, a single static extension set +may be defined as the application's User Extension Table which +is included as part of the Configuration Table. This extension +set is active for the entire life of the system and may not be +deleted. This extension set is especially important because it +is the only way the application can provided a FATAL error +extension which is invoked if RTEMS fails during the +initialize_executive directive. The static extension set is +optional and may be configured as NULL if no static extension +set is required. + +Second, the user can install dynamic extensions using +the extension_create directive. These extensions are RTEMS +objects in that they have a name, an ID, and can be dynamically +created and deleted. In contrast to the static extension set, +these extensions can only be created and installed after the +initialize_executive directive successfully completes execution. +Dynamic extensions are useful for encapsulating the +functionality of an extension set. For example, the application +could use extensions to manage a special coprocessor, do +performance monitoring, and to do stack bounds checking. Each +of these extension sets could be written and installed +independently of the others. + +All user extensions are optional and RTEMS places no +naming restrictions on the user. + +@ifinfo +@node TCB Extension Area, Extensions, Extension Sets, User Extensions Manager Background +@end ifinfo +@subsection TCB Extension Area + +RTEMS provides for a pointer to a user-defined data +area for each extension set to be linked to each task's control +block. This set of pointers is an extension of the TCB and can +be used to store additional data required by the user's +extension functions. It is also possible for a user extension +to utilize the notepad locations associated with each task +although this may conflict with application usage of those +particular notepads. + +The TCB extension is an array of pointers in the TCB. +The number of pointers in the area is the same as the number of +user extension sets configured. This allows an application to +augment the TCB with user-defined information. For example, an +application could implement task profiling by storing timing +statistics in the TCB's extended memory area. When a task +context switch is being executed, the TASK_SWITCH extension +could read a real-time clock to calculate how long the task +being swapped out has run as well as timestamp the starting time +for the task being swapped in. + +If used, the extended memory area for the TCB should +be allocated and the TCB extension pointer should be set at the +time the task is created or started by either the TASK_CREATE or +TASK_START extension. The application is responsible for +managing this extended memory area for the TCBs. The memory may +be reinitialized by the TASK_RESTART extension and should be +deallocated by the TASK_DELETE extension when the task is +deleted. Since the TCB extension buffers would most likely be +of a fixed size, the RTEMS partition manager could be used to +manage the application's extended memory area. The application +could create a partition of fixed size TCB extension buffers and +use the partition manager's allocation and deallocation +directives to obtain and release the extension buffers. + +@ifinfo +@node Extensions, TASK_CREATE Extension, TCB Extension Area, User Extensions Manager Background +@end ifinfo +@subsection Extensions + +The sections that follow will contain a description +of each extension. Each section will contain a prototype of a +function with the appropriate calling sequence for the +corresponding extension. The names given for the C function and +its arguments are all defined by the user. The names used in +the examples were arbitrarily chosen and impose no naming +conventions on the user. + +@ifinfo +@node TASK_CREATE Extension, TASK_START Extension, Extensions, User Extensions Manager Background +@end ifinfo +@subsection TASK_CREATE Extension + +The TASK_CREATE extension directly corresponds to the +task_create directive. If this extension is defined in any +static or dynamic extension set and a task is being created, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_create( + rtems_tcb *current_task, + rtems_tcb *new_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and new_task can be used to access +the TCB for the new task being created. This extension is +invoked from the task_create directive after new_task has been +completely initialized, but before it is placed on a ready TCB +chain. + +@ifinfo +@node TASK_START Extension, TASK_RESTART Extension, TASK_CREATE Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_START Extension + +The TASK_START extension directly corresponds to the +task_start directive. If this extension is defined in any +static or dynamic extension set and a task is being started, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_start( + rtems_tcb *current_task, + rtems_tcb *started_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and started_task can be used to +access the TCB for the dormant task being started. This +extension is invoked from the task_start directive after +started_task has been made ready to start execution, but before +it is placed on a ready TCB chain. + +@ifinfo +@node TASK_RESTART Extension, TASK_DELETE Extension, TASK_START Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_RESTART Extension + +The TASK_RESTART extension directly corresponds to +the task_restart directive. If this extension is defined in any +static or dynamic extension set and a task is being restarted, +then the extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_restart( + rtems_tcb *current_task, + rtems_tcb *restarted_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and restarted_task can be used to +access the TCB for the task being restarted. This extension is +invoked from the task_restart directive after restarted_task has +been made ready to start execution, but before it is placed on a +ready TCB chain. + +@ifinfo +@node TASK_DELETE Extension, TASK_SWITCH Extension, TASK_RESTART Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_DELETE Extension + +The TASK_DELETE extension is associated with the +task_delete directive. If this extension is defined in any +static or dynamic extension set and a task is being deleted, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_delete( + rtems_tcb *current_task, + rtems_tcb *deleted_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and deleted_task can be used to +access the TCB for the task being deleted. This extension is +invoked from the task_delete directive after the TCB has been +removed from a ready TCB chain, but before all its resources +including the TCB have been returned to their respective free +pools. This extension should not call any RTEMS directives if a +task is deleting itself (current_task is equal to deleted_task). + +@ifinfo +@node TASK_SWITCH Extension, TASK_POST_SWITCH Extension, TASK_DELETE Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_SWITCH Extension + +The TASK_SWITCH extension corresponds to a task +context switch. If this extension is defined in any static or +dynamic extension set and a task context switch is in progress, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_switch( + rtems_tcb *current_task, + rtems_tcb *heir_task +); +@end example + +where current_task can be used to access the TCB for +the task that is being swapped out, and heir_task can be used to +access the TCB for the task being swapped in. This extension is +invoked from RTEMS' dispatcher routine after the current_task +context has been saved, but before the heir_task context has +been restored. This extension should not call any RTEMS +directives. + +@ifinfo +@node TASK_POST_SWITCH Extension, TASK_BEGIN Extension, TASK_SWITCH Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_POST_SWITCH Extension + +The TASK_POST_SWITCH extension corresponds to a task +context switch. If this extension is defined in any static or +dynamic extension set and a raw task context switch has been +completed, then the extension routine will automatically be +invoked by RTEMS. The extension should have a prototype similar +to the following: + +@example +rtems_extension user_task_post_switch( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the task that is being swapped out, and heir_task can be used to +access the TCB for the task being swapped in. This extension is +invoked from RTEMS' dispatcher routine after the current_task +context has been restored and the extension runs in the context +of the current_task. + +@ifinfo +@node TASK_BEGIN Extension, TASK_EXITTED Extension, TASK_POST_SWITCH Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_BEGIN Extension + +The TASK_BEGIN extension is invoked when a task +begins execution. It is invoked immediately before the body of +the starting procedure and executes in the context in the task. +This user extension have a prototype similar to the following: + +@example +rtems_extension user_task_begin( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task which has begun. The distinction +between the TASK_BEGIN and TASK_START extension is that the +TASK_BEGIN extension is executed in the context of the actual +task while the TASK_START extension is executed in the context +of the task performing the task_start directive. For most +extensions, this is not a critical distinction. + +@ifinfo +@node TASK_EXITTED Extension, FATAL Error Extension, TASK_BEGIN Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_EXITTED Extension + +The TASK_EXITTED extension is invoked when a task +exits the body of the starting procedure by either an implicit +or explicit return statement. This user extension have a +prototype similar to the following: + +@example +rtems_extension user_task_exitted( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task which has just exitted. + +Although exiting of task is often considered to be a +fatal error, this extension allows recovery by either restarting +or deleting the exiting task. If the user does not wish to +recover, then a fatal error may be reported. If the user does +not provide a TASK_EXITTED extension or the provided handler +returns control to RTEMS, then the RTEMS default handler will be +used. This default handler invokes the directive +fatal_error_occurred with the TASK_EXITTED directive status. + +@lowersections + +@ifinfo +@node FATAL Error Extension, Order of Invocation, TASK_EXITTED Extension, User Extensions Manager Background +@end ifinfo +@subsection FATAL Error Extension + +The FATAL error extension is associated with the +fatal_error_occurred directive. If this extension is defined in +any static or dynamic extension set and the fatal_error_occurred +directive has been invoked, then this extension will be called. +This extension should have a prototype similar to the following: + +@example +rtems_extension user_fatal_error_extension( + Internal_errors_Source the_source, + rtems_boolean is_internal, + rtems_unsigned32 the_error +); +@end example + +where the_error is the error code passed to the +fatal_error_occurred directive. This extension is invoked from +the fatal_error_occurred directive. + +If defined, the user's FATAL error extension is +invoked before RTEMS' default fatal error routine is invoked and +the processor is stopped. For example, this extension could be +used to pass control to a debugger when a fatal error occurs. +This extension should not call any RTEMS directives. + +@raisesections + +@ifinfo +@node Order of Invocation, User Extensions Manager Operations, FATAL Error Extension, User Extensions Manager Background +@end ifinfo +@subsection Order of Invocation + +When one of the critical system events occur, the +user extensions are invoked in either "forward" or "reverse" +order. Forward order indicates that the static extension set is +invoked followed by the dynamic extension sets in the order in +which they were created. Reverse order means that the dynamic +extension sets are invoked in the opposite of the order in which +they were created followed by the static extension set. By +invoking the extension sets in this order, extensions can be +built upon one another. At the following system events, the +extensions are invoked in forward order: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begins to execute +@end itemize + + +At the following system events, the extensions are +invoked in reverse order: + +@itemize @bullet +@item Task deletion +@item Fatal error detection +@end itemize + +At these system events, the extensions are invoked in +reverse order to insure that if an extension set is built upon +another, the more complicated extension is invoked before the +extension set it is built upon. For example, by invoking the +static extension set last it is known that the "system" fatal +error extension will be the last fatal error extension executed. +Another example is use of the task delete extension by the +Standard C Library. Extension sets which are installed after +the Standard C Library will operate correctly even if they +utilize the C Library because the C Library's TASK_DELETE +extension is invoked after that of the other extensions. + +@ifinfo +@node User Extensions Manager Operations, Creating an Extension Set, Order of Invocation, User Extensions Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating an Extension Set:: +* Obtaining Extension Set IDs:: +* Deleting an Extension Set:: +@end menu +@end ifinfo + +@ifinfo +@node Creating an Extension Set, Obtaining Extension Set IDs, User Extensions Manager Operations, User Extensions Manager Operations +@end ifinfo +@subsection Creating an Extension Set + +The extension_create directive creates and installs +an extension set by allocating a Extension Set Control Block +(ESCB), assigning the extension set a user-specified name, and +assigning it an extension set ID. Newly created extension sets +are immediately installed and are invoked upon the next system +even supporting an extension. + +@ifinfo +@node Obtaining Extension Set IDs, Deleting an Extension Set, Creating an Extension Set, User Extensions Manager Operations +@end ifinfo +@subsection Obtaining Extension Set IDs + +When an extension set is created, RTEMS generates a +unique extension set ID and assigns it to the created extension +set until it is deleted. The extension ID may be obtained by +either of two methods. First, as the result of an invocation of +the extension_create directive, the extension set ID is stored +in a user provided location. Second, the extension set ID may +be obtained later using the extension_ident directive. The +extension set ID is used by other directives to manipulate this +extension set. + +@ifinfo +@node Deleting an Extension Set, User Extensions Manager Directives, Obtaining Extension Set IDs, User Extensions Manager Operations +@end ifinfo +@subsection Deleting an Extension Set + +The extension_delete directive is used to delete an +extension set. The extension set's control block is returned to +the ESCB free list when it is deleted. An extension set can be +deleted by a task other than the task which created the +extension set. Any subsequent references to the extension's +name and ID are invalid. + +@ifinfo +@node User Extensions Manager Directives, EXTENSION_CREATE - Create a extension set, Deleting an Extension Set, User Extensions Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* EXTENSION_CREATE - Create a extension set:: +* EXTENSION_IDENT - Get ID of a extension set:: +* EXTENSION_DELETE - Delete a extension set:: +@end menu +@end ifinfo + +This section details the user extension 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 EXTENSION_CREATE - Create a extension set, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_CREATE - Create a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_create( + rtems_name name, + rtems_extensions_table *table, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set created successfully@* +@code{INVALID_NAME} - invalid extension set name@* +@code{TOO_MANY} - too many extension sets created + +@subheading DESCRIPTION: + +This directive creates a extension set. The assigned +extension set id is returned in id. This id is used to access +the extension set with other user extension manager directives. +For control and maintenance of the extension set, RTEMS +allocates an ESCB from the local ESCB free pool and initializes +it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node EXTENSION_IDENT - Get ID of a extension set, EXTENSION_DELETE - Delete a extension set, EXTENSION_CREATE - Create a extension set, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_IDENT - Get ID of a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set identified successfully@* +@code{INVALID_NAME} - extension set name not found + +@subheading DESCRIPTION: + +This directive obtains the extension set id +associated with the extension set name to be acquired. If the +extension set name is not unique, then the extension set id will +match one of the extension sets with that name. However, this +extension set id is not guaranteed to correspond to the desired +extension set. The extension set id is used to access this +extension set in other extension set related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node EXTENSION_DELETE - Delete a extension set, Configuring a System, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_DELETE - Delete a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set deleted successfully@* +@code{INVALID_ID} - invalid extension set id + +@subheading DESCRIPTION: + +This directive deletes the extension set specified by +id. If the extension set is running, it is automatically +canceled. The ESCB for the deleted extension set is reclaimed +by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A extension set can be deleted by a task other than +the task which created the extension set. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. -- cgit v1.2.3