mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2025-11-16 12:34:45 +00:00
Remove texinfo format documentation. Replaced by Sphinx formatted documentation.
updates #2812.
This commit is contained in:
Joel Sherrill
@@ -14,7 +14,7 @@ EXTRA_DIST += config-ml.in
|
||||
EXTRA_DIST += ampolish3
|
||||
|
||||
dist-hook:
|
||||
@files=`(cd $(srcdir); find doc cpukit c testsuites tools \
|
||||
@files=`(cd $(srcdir); find cpukit c testsuites tools \
|
||||
-name configure.ac -print | sed 's,/configure.ac,,' | sort)`; \
|
||||
for i in $$files; do \
|
||||
if test -f $(distdir)/$$i/configure.ac; then : ; \
|
||||
|
||||
@@ -54,15 +54,6 @@ rtems-$(rtems_version)/stamp.export.$(rtems_tag)$(TAG_SUFFIX):
|
||||
rtems-$(rtems_version)$(TAG_SUFFIX).tar.bz2: rtems-$(rtems_version)/stamp.autofiles \
|
||||
rtems-$(rtems_version)/excludes \
|
||||
rtems-$(rtems_version)/TOOL_VERSIONS
|
||||
cd rtems-$(rtems_version) ; \
|
||||
touch doc/ada_user/ada_user.texi doc/bsp_howto/bsp_howto.texi \
|
||||
doc/cpu_supplement/cpu_supplement.texi \
|
||||
doc/develenv/develenv.texi doc/filesystem/filesystem.texi \
|
||||
doc/networking/networking.texi \
|
||||
doc/new_chapters/new_chapters.texi \
|
||||
doc/porting/porting.texi doc/posix1003.1/posix1003_1.texi \
|
||||
doc/posix_users/posix_users.texi doc/relnotes/relnotes.texi \
|
||||
doc/started/started.texi doc/user/c_user.texi
|
||||
tar -cj -X rtems-$(rtems_version)/excludes \
|
||||
-f rtems-$(rtems_version)$(TAG_SUFFIX).tar.bz2 rtems-$(rtems_version)
|
||||
|
||||
|
||||
@@ -223,7 +223,6 @@ clean)
|
||||
needles="$needles install-sh"
|
||||
needles="$needles missing"
|
||||
needles="$needles mdate-sh"
|
||||
needles="$needles texinfo.tex"
|
||||
fi
|
||||
for j in $needles; do
|
||||
files=`find . -name "$j" -print`
|
||||
|
||||
@@ -30,10 +30,6 @@ RTEMS_ENABLE_MULTILIB
|
||||
RTEMS_ENABLE_PARAVIRT
|
||||
RTEMS_ENABLE_DRVMGR
|
||||
|
||||
AC_ARG_ENABLE([docs],
|
||||
[AS_HELP_STRING([--enable-docs],[enable building documentation
|
||||
(default:disabled)])])
|
||||
|
||||
## NOTES:
|
||||
## * tools/build are host-native tools to be installed on the host.
|
||||
## * tools/cpu are host-native or host-cross-target-tools
|
||||
@@ -52,9 +48,6 @@ AS_IF([test $host != $build],[
|
||||
RTEMS_HOST_CONFIG_SUBDIRS([tools/build])
|
||||
])
|
||||
|
||||
AS_IF([test x"${enable_docs}" = x"yes"],
|
||||
[RTEMS_BUILD_CONFIG_SUBDIRS([doc])])
|
||||
|
||||
AS_IF([test x"$enable_multilib" = x"yes"],[
|
||||
RTEMS_TARGET_CONFIG_SUBDIRS([cpukit])
|
||||
])
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
ACLOCAL_AMFLAGS = -I ../aclocal
|
||||
|
||||
# NOTE: The order of the directories is essential.
|
||||
# + tools, common and images are shared across many documents
|
||||
|
||||
SUBDIRS = tools started user bsp_howto porting develenv posix_users \
|
||||
posix1003.1 filesystem networking ada_user \
|
||||
new_chapters relnotes cpu_supplement shell
|
||||
|
||||
if USE_HTML
|
||||
html_DATA = index.html
|
||||
endif
|
||||
|
||||
EXTRA_DIST = common/cpright.texi common/setup.texi \
|
||||
common/treedef.tex common/rtems.texi.in
|
||||
|
||||
if USE_HTML
|
||||
html_imagesdir = $(htmldir)/images
|
||||
endif
|
||||
|
||||
HTML_IMAGES = images/dir-arrow.gif images/dvi.gif images/missing-arrow.gif \
|
||||
images/next-arrow.gif images/oaronly.jpg images/pdf.gif images/pdf1.gif \
|
||||
images/rtems_logo.jpg images/prev-arrow.gif images/ps.gif \
|
||||
images/up-arrow.gif
|
||||
|
||||
if USE_HTML
|
||||
html_images_DATA = $(HTML_IMAGES)
|
||||
endif
|
||||
|
||||
EXTRA_DIST += $(HTML_IMAGES)
|
||||
|
||||
CLEANFILES = common/rtems.texi
|
||||
DISTCLEANFILES = common/rtems.sed
|
||||
|
||||
# HACK: This should not be here, but it makes "make distcheck" work.
|
||||
EXTRA_DIST += ../scripts/setup.def ../COPYING
|
||||
48
doc/README
48
doc/README
@@ -1,48 +0,0 @@
|
||||
Tools Required
|
||||
==============
|
||||
The following tools are used in the production of this documentation:
|
||||
|
||||
TeX
|
||||
texi2html 1.82
|
||||
texinfo-tex 4.13a
|
||||
|
||||
texi2html will be deprecated in the upcomine texinfo release. At that point,
|
||||
we will need to provide support for texi2any.pl as an alternative means to
|
||||
produce html output.
|
||||
|
||||
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)
|
||||
|
||||
Changing the Version Number and Timestamp
|
||||
=========================================
|
||||
|
||||
RTEMS Version number is in configure.in. Edit that file and run bootstrap.
|
||||
|
||||
Documentation date is in common/setup.texi.in and also must be modified
|
||||
by hand. bootstrap does not have to be run after modifying this file.
|
||||
|
||||
Making the Documentation
|
||||
========================
|
||||
|
||||
cd rtems-XXX/doc
|
||||
../bootstrap
|
||||
./configure --enable-maintainer-mode
|
||||
make all
|
||||
make install
|
||||
|
||||
Cleaning
|
||||
========
|
||||
|
||||
make clean
|
||||
make distclean
|
||||
make maintainer-clean
|
||||
|
||||
Making a Source Distribution
|
||||
============================
|
||||
This generates a rtems-<version>.tar.gz in the toplevel directory.
|
||||
|
||||
Making a Preformatted Distribution
|
||||
==================================
|
||||
Install and tar it up. :)
|
||||
91
doc/TODO
91
doc/TODO
@@ -1,91 +0,0 @@
|
||||
This is a collection of things which need to be done to the various
|
||||
manuals.
|
||||
|
||||
General Issues
|
||||
==============
|
||||
May need a Documentation Roadmap - for now, the "Where to
|
||||
go from here" chapter in Getting Started is it.
|
||||
|
||||
Need a description of hello world and writing an application.
|
||||
|
||||
More automatic handling of version, date, revision, release, etc.
|
||||
|
||||
Eliminate use of gifs. [NOTE: ps, pdf, and dvi.gif are from
|
||||
http://www.cit.gu.edu.au/images and the various arrow and
|
||||
bookshelf icons came with texi2www.]
|
||||
|
||||
Redraw pictures as appropriate in open source tools.
|
||||
|
||||
|
||||
Getting Started (C and Ada versions)
|
||||
====================================
|
||||
Switch back to using @url{} when pdf generation error is fixed.
|
||||
|
||||
Classic Users Guide
|
||||
===================
|
||||
May need to enhance descriptions in Primitive Data Types Chapter
|
||||
|
||||
POSIX User Notes
|
||||
================
|
||||
|
||||
Add pages for network services.
|
||||
|
||||
Add timer() services if we have any.
|
||||
|
||||
|
||||
Development Environment Guide
|
||||
=============================
|
||||
Either rename to "A Tour of the RTEMS Source Tree" or include
|
||||
more information on the GNU tools.
|
||||
|
||||
The "C Suites" section is oddly named and the directory
|
||||
tree included is wrong in that make is no longer under
|
||||
the c directory. I think the build-tools make have
|
||||
moved as well.
|
||||
|
||||
All the paths should be provided as relative paths
|
||||
from the top of the RTEMS source tree. It wastes
|
||||
valuable screen space to do otherwise.
|
||||
|
||||
The last paragraph of "C Suites" is vague and could
|
||||
be written better. It should include the subdirectory
|
||||
names as part of the textual description.
|
||||
|
||||
Should this documentation even use the phrase "C Implementation"
|
||||
any longer?
|
||||
|
||||
Directory names should be in @code -- not "quoted".
|
||||
|
||||
In "Support Library Source Directory", look for "which installed"
|
||||
|
||||
In the latter part of the "libbsp" paragraph in "Support
|
||||
Library Source Directory", there is reference to the
|
||||
stubdr directory which is no longer there.
|
||||
|
||||
Update this section to include discussion of the shared
|
||||
subdirectory and its relationship to the BSPs. Write this
|
||||
in such a way that it can be passed on to Geoffroy Montel.
|
||||
|
||||
In the section, "Test Suite Source Directory", there is a
|
||||
numeric count of the number of tests in each suite. This
|
||||
should be eliminated for maintenance purposes.
|
||||
|
||||
The psxtest directory is not mentioned. Check that no others
|
||||
have been forgotten.
|
||||
|
||||
There should probably be no reference to the Ada sample
|
||||
applications. This document used to cover both implementations.
|
||||
This now seems inappropriate.
|
||||
|
||||
The hello world sample test discussion mentions that it provides
|
||||
a rudiementary test of the BSP startup code and the "RTEMS
|
||||
C Library". This should be rewritten to tell mroe about what
|
||||
this test shows (actually a lot). It should mention that this
|
||||
test tries to avoid using interrupts.
|
||||
|
||||
The ticker test should mention that in contrast to hello, it
|
||||
does use interrupts. :) It can be used to tune the clock
|
||||
tick.
|
||||
|
||||
The ticker test documentation says it calls "tm_get" -- jeez
|
||||
how old is this manual.
|
||||
@@ -1,18 +0,0 @@
|
||||
## _RTEMS_UPDATE_CONDITIONAL(FINAL,TMP)
|
||||
AC_DEFUN([_RTEMS_UPDATE_CONDITIONAL],[
|
||||
AS_IF([test -f $1],[
|
||||
AS_IF([cmp -s $1 $2 2>/dev/null],
|
||||
[
|
||||
AC_MSG_NOTICE([$1 is unchanged])
|
||||
rm -f $$2
|
||||
],[
|
||||
AC_MSG_NOTICE([creating $1])
|
||||
rm -f $1
|
||||
mv $2 $1
|
||||
])
|
||||
],[
|
||||
AC_MSG_NOTICE([creating $1])
|
||||
rm -f $1
|
||||
mv $2 $1
|
||||
])
|
||||
])
|
||||
@@ -1,72 +0,0 @@
|
||||
#
|
||||
# COPYRIGHT (c) 1988-2002.
|
||||
# On-Line Applications Research Corporation (OAR).
|
||||
# All rights reserved.
|
||||
|
||||
PROJECT = ada_user
|
||||
|
||||
include $(top_srcdir)/project.am
|
||||
include $(top_srcdir)/main.am
|
||||
|
||||
COMMON_FILES += \
|
||||
$(top_builddir)/user/barrier.texi $(top_builddir)/user/bsp.texi \
|
||||
$(top_builddir)/user/clock.texi $(top_builddir)/user/concepts.texi \
|
||||
$(top_builddir)/user/datatypes.texi $(top_builddir)/user/conf.texi \
|
||||
$(top_builddir)/user/dirstat.texi $(top_builddir)/user/dpmem.texi \
|
||||
$(top_builddir)/user/event.texi $(top_builddir)/user/fatal.texi \
|
||||
$(top_builddir)/user/glossary.texi $(top_builddir)/user/init.texi \
|
||||
$(top_builddir)/user/intr.texi $(top_builddir)/user/io.texi \
|
||||
$(top_builddir)/user/libpci.texi \
|
||||
$(top_builddir)/user/mp.texi $(top_builddir)/user/msg.texi \
|
||||
$(top_builddir)/user/overview.texi $(top_builddir)/user/part.texi \
|
||||
$(top_builddir)/user/preface.texi $(top_builddir)/user/region.texi \
|
||||
$(top_builddir)/user/rtmon.texi $(top_builddir)/user/schedule.texi \
|
||||
$(top_builddir)/user/sem.texi $(top_builddir)/user/signal.texi \
|
||||
$(top_builddir)/user/task.texi $(top_builddir)/user/timer.texi \
|
||||
$(top_builddir)/user/userext.texi $(top_builddir)/user/stackchk.texi \
|
||||
$(top_builddir)/user/cpuuse.texi $(top_srcdir)/common/cpright.texi \
|
||||
$(top_builddir)/user/object.texi $(top_builddir)/user/cbs.texi \
|
||||
$(top_builddir)/user/smp.texi
|
||||
|
||||
FILES = example.texi
|
||||
|
||||
ObjectId-16Bits.eps: $(top_srcdir)/user/ObjectId-16Bits.eps
|
||||
$(LN_S) $<
|
||||
ObjectId-32Bits.eps: $(top_srcdir)/user/ObjectId-32Bits.eps
|
||||
$(LN_S) $<
|
||||
rtemspie.eps: $(top_srcdir)/user/rtemspie.eps
|
||||
$(LN_S) $<
|
||||
semaphore_attributes.eps: $(top_srcdir)/user/semaphore_attributes.eps
|
||||
$(LN_S) $<
|
||||
states.eps: $(top_srcdir)/user/states.eps
|
||||
$(LN_S) $<
|
||||
CLEANFILES += ObjectId-16Bits.eps ObjectId-32Bits.eps rtemspie.eps semaphore_attributes.eps states.eps
|
||||
|
||||
ObjectId-16Bits.png: $(top_srcdir)/user/ObjectId-16Bits.png
|
||||
$(LN_S) $<
|
||||
ObjectId-32Bits.png: $(top_srcdir)/user/ObjectId-32Bits.png
|
||||
$(LN_S) $<
|
||||
rtemsarc.png: $(top_srcdir)/user/rtemsarc.png
|
||||
$(LN_S) $<
|
||||
rtemspie.png: $(top_srcdir)/user/rtemspie.png
|
||||
$(LN_S) $<
|
||||
semaphore_attributes.png: $(top_srcdir)/user/semaphore_attributes.png
|
||||
$(LN_S) $<
|
||||
states.png: $(top_srcdir)/user/states.png
|
||||
$(LN_S) $<
|
||||
CLEANFILES += ObjectId-16Bits.png ObjectId-32Bits.png rtemsarc.png rtemspie.png semaphore_attributes.png states.png
|
||||
|
||||
info_TEXINFOS = ada_user.texi
|
||||
ada_user_TEXINFOS = $(FILES) $(COMMON_FILES)
|
||||
|
||||
if USE_HTML
|
||||
html_project_DATA += rtemsarc.png rtemspie.png states.png \
|
||||
ObjectId-16Bits.png ObjectId-32Bits.png semaphore_attributes.png
|
||||
endif
|
||||
|
||||
$(PROJECT).dvi: rtemspie.eps states.eps ObjectId-16Bits.eps \
|
||||
ObjectId-32Bits.eps semaphore_attributes.eps
|
||||
PDF_IMAGES = rtemspie.pdf states.pdf ObjectId-16Bits.pdf \
|
||||
ObjectId-32Bits.pdf semaphore_attributes.pdf
|
||||
|
||||
CLEANFILES += ada_user.info ada_user.info-? ada_user.info-??
|
||||
@@ -1,183 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename ada_user.info
|
||||
@setcontentsaftertitlepage
|
||||
@syncodeindex vr fn
|
||||
@synindex ky cp
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2014.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c Master file for the Ada User's Guide
|
||||
@c
|
||||
|
||||
@c Joel's Questions
|
||||
@c
|
||||
@c 1. Why does paragraphindent only impact makeinfo?
|
||||
@c 2. Why does paragraphindent show up in HTML?
|
||||
@c
|
||||
|
||||
@include version.texi
|
||||
@include common/setup.texi
|
||||
@include common/rtems.texi
|
||||
|
||||
@ifset use-ascii
|
||||
@dircategory RTEMS On-Line Manual
|
||||
@direntry
|
||||
* RTEMS Ada User: (ada_user). The Ada User's Guide
|
||||
@end direntry
|
||||
@end ifset
|
||||
|
||||
|
||||
@c variable substitution info:
|
||||
@c
|
||||
@clear is-C
|
||||
@set is-Ada
|
||||
@set LANGUAGE Ada
|
||||
@set STRUCTURE record
|
||||
@set ROUTINE subprogram
|
||||
@set OR or
|
||||
@set RPREFIX RTEMS.
|
||||
@set DIRPREFIX rtems.
|
||||
@c the language is @value{LANGUAGE}
|
||||
@c NOTE: don't use underscore in the name
|
||||
@c
|
||||
|
||||
@c
|
||||
@c Title Page Stuff
|
||||
@c
|
||||
|
||||
@c
|
||||
@c I don't really like having a short title page. --joel
|
||||
@c
|
||||
@c @shorttitlepage RTEMS Applications Ada User's Guide
|
||||
|
||||
@setchapternewpage odd
|
||||
@settitle RTEMS Ada User's Guide
|
||||
@titlepage
|
||||
@finalout
|
||||
|
||||
@title RTEMS Applications Ada User's Guide
|
||||
@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION}
|
||||
@sp 1
|
||||
@subtitle @value{UPDATED}
|
||||
@author On-Line Applications Research Corporation
|
||||
@page
|
||||
@include common/cpright.texi
|
||||
@end titlepage
|
||||
|
||||
@c This prevents a black box from being printed on "overflow" lines.
|
||||
@c The alternative is to rework a sentence to avoid this problem.
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top, List of Figures, (dir), (dir)
|
||||
@top RTEMS Applications Ada User's Guide
|
||||
|
||||
@menu
|
||||
* List of Figures::
|
||||
* Preface::
|
||||
* Overview::
|
||||
* Key Concepts::
|
||||
* RTEMS Data Types::
|
||||
* 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::
|
||||
* Barrier Manager::
|
||||
* Board Support Packages::
|
||||
* User Extensions Manager::
|
||||
* Configuring a System::
|
||||
* Multiprocessing Manager::
|
||||
* Symmetric Multiprocessing Services::
|
||||
* PCI Library::
|
||||
* Stack Bounds Checker::
|
||||
* CPU Usage Statistics::
|
||||
* Object Services::
|
||||
* Chains::
|
||||
* Red-Black Trees::
|
||||
* Timespec Helpers::
|
||||
* Constant Bandwidth Server Scheduler API::
|
||||
* Directive Status Codes::
|
||||
* Example Application::
|
||||
* Glossary::
|
||||
* Command and Variable Index::
|
||||
* Concept Index::
|
||||
@end menu
|
||||
@end ifnottex
|
||||
|
||||
@node List of Figures, Preface, Top, Top
|
||||
@unnumbered List of Figures
|
||||
@listoffloats Figure
|
||||
|
||||
@include user/preface.texi
|
||||
@include user/overview.texi
|
||||
@include user/concepts.texi
|
||||
@include user/datatypes.texi
|
||||
@include user/init.texi
|
||||
@include user/task.texi
|
||||
@include user/intr.texi
|
||||
@include user/clock.texi
|
||||
@include user/timer.texi
|
||||
@include user/sem.texi
|
||||
@include user/msg.texi
|
||||
@include user/event.texi
|
||||
@include user/signal.texi
|
||||
@include user/part.texi
|
||||
@include user/region.texi
|
||||
@include user/dpmem.texi
|
||||
@include user/io.texi
|
||||
@include user/fatal.texi
|
||||
@include user/schedule.texi
|
||||
@include user/rtmon.texi
|
||||
@include user/barrier.texi
|
||||
@include user/bsp.texi
|
||||
@include user/userext.texi
|
||||
@include user/conf.texi
|
||||
@include user/mp.texi
|
||||
@include user/smp.texi
|
||||
@include user/libpci.texi
|
||||
@include user/stackchk.texi
|
||||
@include user/cpuuse.texi
|
||||
@include user/object.texi
|
||||
@include user/chains.texi
|
||||
@include user/rbtree.texi
|
||||
@include user/timespec.texi
|
||||
@include user/cbs.texi
|
||||
@include user/dirstat.texi
|
||||
@include example.texi
|
||||
@include user/glossary.texi
|
||||
|
||||
@node Command and Variable Index, Concept Index, Glossary, Top
|
||||
@unnumbered Command and Variable Index
|
||||
|
||||
@c There are currently no Command and Variable Index entries.
|
||||
|
||||
@printindex fn
|
||||
|
||||
@node Concept Index, , Command and Variable Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
@c There are currently no Concept Index entries.
|
||||
@printindex cp
|
||||
|
||||
@bye
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2014.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@node Example Application, Glossary, Directive Status Codes STATUS_TEXT - Returns the enumeration name for a status code, Top
|
||||
@chapter Example Application
|
||||
|
||||
@example
|
||||
|
||||
Currently there is no example Ada application provided.
|
||||
|
||||
@end example
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 24 February 2013
|
||||
@set UPDATED-MONTH February 2013
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 17 July 2015
|
||||
@set UPDATED-MONTH July 2015
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
Binary file not shown.
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB |
File diff suppressed because one or more lines are too long
Binary file not shown.
|
Before Width: | Height: | Size: 32 KiB |
@@ -1,135 +0,0 @@
|
||||
#
|
||||
# COPYRIGHT (c) 1988-2002.
|
||||
# On-Line Applications Research Corporation (OAR).
|
||||
# All rights reserved.
|
||||
|
||||
PROJECT = bsp_howto
|
||||
|
||||
include $(top_srcdir)/project.am
|
||||
include $(top_srcdir)/main.am
|
||||
|
||||
GENERATED_FILES = intro.texi target.texi makefiles.texi linkcmds.texi \
|
||||
support.texi adaintr.texi init.texi console.texi clock.texi timer.texi \
|
||||
rtc.texi ata.texi ide-ctrl.texi nvmem.texi network.texi shmsupp.texi \
|
||||
framebuffer.texi analog.texi discrete.texi
|
||||
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
PNG_FILES = Developer-User-Timeline.png BSPInitFlowchart-49.png \
|
||||
TERMIOSFlow.png
|
||||
|
||||
if USE_HTML
|
||||
html_project_DATA += $(PNG_FILES)
|
||||
endif
|
||||
|
||||
FILES =
|
||||
|
||||
info_TEXINFOS = bsp_howto.texi
|
||||
bsp_howto_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
|
||||
|
||||
#
|
||||
# Process Automatically Generated Files
|
||||
#
|
||||
|
||||
intro.texi: intro.t
|
||||
$(BMENU2) -p "Top" \
|
||||
-u "Top" \
|
||||
-n "Target Dependent Files" < $< > $@
|
||||
|
||||
target.texi: target.t
|
||||
$(BMENU2) -p "Introduction" \
|
||||
-u "Top" \
|
||||
-n "Makefiles" < $< > $@
|
||||
|
||||
makefiles.texi: makefiles.t
|
||||
$(BMENU2) -p "Target Dependent Files Board Support Package Structure" \
|
||||
-u "Top" \
|
||||
-n "Linker Script" < $< > $@
|
||||
|
||||
linkcmds.texi: linkcmds.t
|
||||
$(BMENU2) -p "Makefiles Creating a New BSP Make Customization File" \
|
||||
-u "Top" \
|
||||
-n "Ada95 Interrupt Support" < $< > $@
|
||||
|
||||
adaintr.texi: adaintr.t
|
||||
$(BMENU2) -p "Linker Script Initialized Data" \
|
||||
-u "Top" \
|
||||
-n "Miscellaneous Support Files" < $< > $@
|
||||
|
||||
support.texi: support.t
|
||||
$(BMENU2) -p "Ada95 Interrupt Support Version Requirements" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
init.texi: init.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
console.texi: console.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
clock.texi: clock.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
timer.texi: timer.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
rtc.texi: rtc.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
ata.texi: ata.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
ide-ctrl.texi: ide-ctrl.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
nvmem.texi: nvmem.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
#
|
||||
# Grab the chapter on writing a network device driver.
|
||||
#
|
||||
network.texi: ../networking/driver.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
shmsupp.texi: shmsupp.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
framebuffer.texi: framebuffer.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
analog.texi: analog.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
discrete.texi: discrete.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
CLEANFILES += bsp_howto.info bsp_howto.info-?
|
||||
|
||||
EXTRA_DIST = adaintr.t analog.t ata.t clock.t console.t discrete.t \
|
||||
ide-ctrl.t init.t intro.t linkcmds.t makefiles.t nvmem.t rtc.t shmsupp.t \
|
||||
support.t target.t timer.t $(PNG_FILES) $(EPS_IMAGES)
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 40 KiB |
@@ -1,78 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Ada95 Interrupt Support
|
||||
|
||||
@section Introduction
|
||||
|
||||
This chapter describes what is required to enable Ada interrupt
|
||||
and error exception handling when using GNAT over RTEMS.
|
||||
|
||||
The GNAT Ada95 interrupt support RTEMS was developed by
|
||||
Jiri Gaisler <jgais@@ws.estec.esa.nl> who also wrote this
|
||||
chapter.
|
||||
|
||||
@section Mapping Interrupts to POSIX Signals
|
||||
|
||||
In Ada95, interrupts can be attached with the interrupt_attach pragma.
|
||||
For most systems, the gnat run-time will use POSIX signal to implement
|
||||
the interrupt handling, mapping one signal per interrupt. For interrupts
|
||||
to be propagated to the attached Ada handler, the corresponding signal
|
||||
must be raised when the interrupt occurs.
|
||||
|
||||
The same mechanism is used to generate Ada error exceptions.
|
||||
Three error exceptions are defined: program, constraint and storage
|
||||
error. These are generated by raising the predefined signals: SIGILL,
|
||||
SIGFPE and SIGSEGV. These signals should be raised when a spurious
|
||||
or erroneous trap occurs.
|
||||
|
||||
To enable gnat interrupt and error exception support for a particular
|
||||
BSP, the following has to be done:
|
||||
|
||||
@enumerate
|
||||
|
||||
@item Write an interrupt/trap handler that will raise the corresponding
|
||||
signal depending on the interrupt/trap number.
|
||||
|
||||
@item Install the interrupt handler for all interrupts/traps that will be
|
||||
handled by gnat (including spurious).
|
||||
|
||||
@item At startup, gnat calls @code{__gnat_install_handler()}. The BSP
|
||||
must provide this function which installs the interrupt/trap handlers.
|
||||
|
||||
@end enumerate
|
||||
|
||||
Which CPU-interrupt will generate which signal is implementation
|
||||
defined. There are 32 POSIX signals (1 - 32), and all except the
|
||||
three error signals (SIGILL, SIGFPE and SIGSEGV) can be used. I
|
||||
would suggest to use the upper 16 (17 - 32) which do not
|
||||
have an assigned POSIX name.
|
||||
|
||||
Note that the pragma interrupt_attach will only bind a signal
|
||||
to a particular Ada handler - it will not unmask the
|
||||
interrupt or do any other things to enable it. This have to be
|
||||
done separately, typically by writing various device register.
|
||||
|
||||
@section Example Ada95 Interrupt Program
|
||||
|
||||
An example program (@code{irq_test}) is included in the
|
||||
Ada examples package to show how interrupts can be handled
|
||||
in Ada95. Note that generation of the test interrupt
|
||||
(@code{irqforce.c}) is BSP specific and must be edited.
|
||||
|
||||
NOTE: The @code{irq_test} example was written for the SPARC/ERC32
|
||||
BSP.
|
||||
|
||||
@section Version Requirements
|
||||
|
||||
With RTEMS 4.0, a patch was required to psignal.c in RTEMS
|
||||
sources (to correct a bug associated to the default action of
|
||||
signals 15-32). The SPARC/ERC32 RTEMS BSP includes the
|
||||
@code{gnatsupp} subdirectory that can be used as an example
|
||||
for other BSPs.
|
||||
|
||||
With GNAT 3.11p, a patch is required for @code{a-init.c} to invoke
|
||||
the BSP specific routine that installs the exception handlers.
|
||||
|
||||
@@ -1,163 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Analog Driver
|
||||
|
||||
The Analog driver is responsible for providing an
|
||||
interface to Digital to Analog Converters (DACs) and
|
||||
Analog to Digital Converters (ADCs). The capabilities provided
|
||||
by this class of device driver are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Initialize an Analog Board
|
||||
@item Open a Particular Analog
|
||||
@item Close a Particular Analog
|
||||
@item Read from a Particular Analog
|
||||
@item Write to a Particular Analog
|
||||
@item Reset DACs
|
||||
@item Reinitialize DACS
|
||||
@end itemize
|
||||
|
||||
Most analog devices are found on I/O cards that support multiple
|
||||
DACs or ADCs on a single card.
|
||||
|
||||
There are currently no analog device drivers included in the
|
||||
RTEMS source tree. The information provided in this chapter
|
||||
is based on drivers developed for applications using RTEMS.
|
||||
It is hoped that this driver model information can form the
|
||||
basis for a standard analog driver model that can be supported
|
||||
in future RTEMS distribution.
|
||||
|
||||
@section Major and Minor Numbers
|
||||
|
||||
The @b{major} number of a device driver is its index in the
|
||||
RTEMS Device Address Table.
|
||||
|
||||
A @b{minor} number is associated with each device instance
|
||||
managed by a particular device driver. An RTEMS minor number
|
||||
is an @code{unsigned32} entity. Convention calls
|
||||
dividing the bits in the minor number down into categories
|
||||
like the following:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @b{board} - indicates the board a particular device is located on
|
||||
@item @b{port} - indicates the particular device on a board.
|
||||
|
||||
@end itemize
|
||||
|
||||
From the above, it should be clear that a single device driver
|
||||
can support multiple copies of the same board in a single system.
|
||||
The minor number is used to distinguish the devices.
|
||||
|
||||
@section Analog Driver Configuration
|
||||
|
||||
There is not a standard analog driver configuration table but some
|
||||
fields are common across different drivers. The analog driver
|
||||
configuration table is typically an array of structures with each
|
||||
structure containing the information for a particular board.
|
||||
The following is a list of the type of information normally required
|
||||
to configure an analog board:
|
||||
|
||||
@table @b
|
||||
@item board_offset
|
||||
is the base address of a board.
|
||||
|
||||
@item DAC_initial_values
|
||||
is an array of the voltages that should be written to each DAC
|
||||
during initialization. This allows the driver to start the board
|
||||
in a known state.
|
||||
|
||||
@end table
|
||||
|
||||
@section Initialize an Analog Board
|
||||
|
||||
At system initialization, the analog driver's initialization entry point
|
||||
will be invoked. As part of initialization, the driver will perform
|
||||
whatever board initialization is required and then set all
|
||||
outputs to their configured initial state.
|
||||
|
||||
The analog driver may register a device name for each DAC and ADC in
|
||||
the system.
|
||||
|
||||
@section Open a Particular Analog
|
||||
|
||||
This is the driver open call. Usually this call does nothing other than
|
||||
validate the minor number.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is often the place
|
||||
to do this operation.
|
||||
|
||||
@section Close a Particular Analog
|
||||
|
||||
This is the driver close call. Usually this call does nothing.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is the place
|
||||
where that memory should be deallocated.
|
||||
|
||||
@section Read from a Particular Analog
|
||||
|
||||
This corresponds to the driver read call. After validating the minor
|
||||
number and arguments, this call reads the indicated device. Most analog
|
||||
devices store the last value written to a DAC. Since DACs are output
|
||||
only devices, saving the last written value gives the appearance that
|
||||
DACs can be read from also. If the device is an ADC, then it is sampled.
|
||||
|
||||
@b{NOTE:} Many boards have multiple analog inputs but only one ADC. On
|
||||
these boards, it will be necessary to provide some type of mutual exclusion
|
||||
during reads. On these boards, there is a MUX which must be switched
|
||||
before sampling the ADC. After the MUX is switched, the driver must
|
||||
delay some short period of time (usually microseconds) before the
|
||||
signal is stable and can be sampled. To make matters worse, some ADCs
|
||||
cannot respond to wide voltage swings in a single sample. On these
|
||||
ADCs, one must do two samples when the voltage swing is too large.
|
||||
On a practical basis, this means that the driver usually ends up
|
||||
double sampling the ADC on these systems.
|
||||
|
||||
The value returned is a single precision floating point number
|
||||
representing the voltage read. This value is stored in the
|
||||
@code{argument_block} passed in to the call. By returning the
|
||||
voltage, the caller is freed from having to know the number of
|
||||
bits in the analog and board dependent conversion algorithm.
|
||||
|
||||
@section Write to a Particular Analog
|
||||
|
||||
This corresponds to the driver write call. After validating the minor
|
||||
number and arguments, this call writes the indicated device. If the
|
||||
specified device is an ADC, then an error is usually returned.
|
||||
|
||||
The value written is a single precision floating point number
|
||||
representing the voltage to be written to the specified DAC.
|
||||
This value is stored in the @code{argument_block} passed in to the
|
||||
call. By passing the voltage to the device driver, the caller is
|
||||
freed from having to know the number of bits in the analog
|
||||
and board dependent conversion algorithm.
|
||||
|
||||
@section Reset DACs
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
all of the DACs are written to 0.0 volts.
|
||||
|
||||
@section Reinitialize DACS
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
all of the DACs are written with the initial value configured
|
||||
for this device.
|
||||
|
||||
@section Get Last Written Values
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the following information is returned to the caller:
|
||||
|
||||
@itemize @bullet
|
||||
@item last value written to the specified DAC
|
||||
@item timestamp of when the last write was performed
|
||||
@end itemize
|
||||
|
||||
@@ -1,196 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter ATA Driver
|
||||
|
||||
@section Terms
|
||||
|
||||
ATA device - physical device attached to an IDE controller
|
||||
|
||||
@section Introduction
|
||||
|
||||
ATA driver provides generic interface to an ATA device. ATA driver is
|
||||
hardware independent implementation of ATA standard defined in working draft
|
||||
"AT Attachment Interface with Extensions (ATA-2)" X3T10/0948D revision 4c,
|
||||
March 18, 1996. ATA Driver based on IDE Controller Driver and may be used for
|
||||
computer systems with single IDE controller and with multiple as well. Although
|
||||
current implementation has several restrictions detailed below ATA driver
|
||||
architecture allows easily extend the driver. Current restrictions are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Only mandatory (see draft p.29) and two optional (READ/WRITE MULTIPLE)
|
||||
commands are implemented
|
||||
@item Only PIO mode is supported but both poll and interrupt driven
|
||||
@end itemize
|
||||
|
||||
The reference implementation for ATA driver can be found in
|
||||
@code{cpukit/libblock/src/ata.c}.
|
||||
|
||||
@section Initialization
|
||||
|
||||
The @code{ata_initialize} routine is responsible for ATA driver
|
||||
initialization. The main goal of the initialization is to detect and
|
||||
register in the system all ATA devices attached to IDE controllers
|
||||
successfully initialized by the IDE Controller driver.
|
||||
|
||||
In the implementation of the driver, the following actions are performed:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver ata_initialize(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
initialize internal ATA driver data structure
|
||||
|
||||
for each IDE controller successfully initialized by the IDE Controller
|
||||
driver
|
||||
if the controller is interrupt driven
|
||||
set up interrupt handler
|
||||
|
||||
obtain information about ATA devices attached to the controller
|
||||
with help of EXECUTE DEVICE DIAGNOSTIC command
|
||||
|
||||
for each ATA device detected on the controller
|
||||
obtain device parameters with help of DEVICE IDENTIFY command
|
||||
|
||||
register new ATA device as new block device in the system
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
Special processing of ATA commands is required because of absence of
|
||||
multitasking environment during the driver initialization.
|
||||
|
||||
Detected ATA devices are registered in the system as physical block devices
|
||||
(see libblock library description). Device names are formed based on IDE
|
||||
controller minor number device is attached to and device number on the
|
||||
controller (0 - Master, 1 - Slave). In current implementation 64 minor
|
||||
numbers are reserved for each ATA device which allows to support up to 63
|
||||
logical partitions per device.
|
||||
|
||||
@example
|
||||
@group
|
||||
controller minor device number device name ata device minor
|
||||
0 0 hda 0
|
||||
0 1 hdb 64
|
||||
1 0 hdc 128
|
||||
1 1 hdd 172
|
||||
... ... ...
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section ATA Driver Architecture
|
||||
|
||||
@subsection ATA Driver Main Internal Data Structures
|
||||
|
||||
ATA driver works with ATA requests. ATA request is described by the
|
||||
following structure:
|
||||
|
||||
@example
|
||||
@group
|
||||
/* ATA request */
|
||||
typedef struct ata_req_s @{
|
||||
Chain_Node link; /* link in requests chain */
|
||||
char type; /* request type */
|
||||
ata_registers_t regs; /* ATA command */
|
||||
uint32_t cnt; /* Number of sectors to be exchanged */
|
||||
uint32_t cbuf; /* number of current buffer from breq in use */
|
||||
uint32_t pos; /* current position in 'cbuf' */
|
||||
blkdev_request *breq; /* blkdev_request which corresponds to the
|
||||
* ata request
|
||||
*/
|
||||
rtems_id sema; /* semaphore which is used if synchronous
|
||||
* processing of the ata request is required
|
||||
*/
|
||||
rtems_status_code status; /* status of ata request processing */
|
||||
int error; /* error code */
|
||||
@} ata_req_t;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
ATA driver supports separate ATA requests queues for each IDE
|
||||
controller (one queue per controller). The following structure contains
|
||||
information about controller's queue and devices attached to the controller:
|
||||
|
||||
@example
|
||||
@group
|
||||
/*
|
||||
* This structure describes controller state, devices configuration on the
|
||||
* controller and chain of ATA requests to the controller.
|
||||
*/
|
||||
typedef struct ata_ide_ctrl_s @{
|
||||
bool present; /* controller state */
|
||||
ata_dev_t device[2]; /* ata devices description */
|
||||
Chain_Control reqs; /* requests chain */
|
||||
@} ata_ide_ctrl_t;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
Driver uses array of the structures indexed by the controllers minor
|
||||
number.
|
||||
|
||||
The following structure allows to map an ATA device to the pair (IDE
|
||||
controller minor number device is attached to, device number
|
||||
on the controller):
|
||||
|
||||
@example
|
||||
@group
|
||||
/*
|
||||
* Mapping of rtems ATA devices to the following pairs:
|
||||
* (IDE controller number served the device, device number on the controller)
|
||||
*/
|
||||
typedef struct ata_ide_dev_s @{
|
||||
int ctrl_minor;/* minor number of IDE controller serves rtems ATA device */
|
||||
int device; /* device number on IDE controller (0 or 1) */
|
||||
@} ata_ide_dev_t;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
Driver uses array of the structures indexed by the ATA devices minor
|
||||
number.
|
||||
|
||||
ATA driver defines the following internal events:
|
||||
|
||||
@example
|
||||
@group
|
||||
/* ATA driver events */
|
||||
typedef enum ata_msg_type_s @{
|
||||
ATA_MSG_GEN_EVT = 1, /* general event */
|
||||
ATA_MSG_SUCCESS_EVT, /* success event */
|
||||
ATA_MSG_ERROR_EVT, /* error event */
|
||||
ATA_MSG_PROCESS_NEXT_EVT /* process next ata request event */
|
||||
@} ata_msg_type_t;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Brief ATA Driver Core Overview
|
||||
|
||||
All ATA driver functionality is available via ATA driver ioctl. Current
|
||||
implementation supports only two ioctls: BLKIO_REQUEST and
|
||||
ATAIO_SET_MULTIPLE_MODE. Each ATA driver ioctl() call generates an
|
||||
ATA request which is appended to the appropriate controller queue depending
|
||||
on ATA device the request belongs to. If appended request is single request in
|
||||
the controller's queue then ATA driver event is generated.
|
||||
|
||||
ATA driver task which manages queue of ATA driver events is core of ATA
|
||||
driver. In current driver version queue of ATA driver events implemented
|
||||
as RTEMS message queue. Each message contains event type, IDE controller
|
||||
minor number on which event happened and error if an error occurred. Events
|
||||
may be generated either by ATA driver ioctl call or by ATA driver task itself.
|
||||
Each time ATA driver task receives an event it gets controller minor number
|
||||
from event, takes first ATA request from controller queue and processes it
|
||||
depending on request and event types. An ATA request processing may also
|
||||
includes sending of several events. If ATA request processing is finished
|
||||
the ATA request is removed from the controller queue. Note, that in current
|
||||
implementation maximum one event per controller may be queued at any moment
|
||||
of the time.
|
||||
|
||||
(This part seems not very clear, hope I rewrite it soon)
|
||||
|
||||
|
||||
|
||||
@@ -1,121 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename bsp_howto.info
|
||||
@setcontentsaftertitlepage
|
||||
@syncodeindex vr fn
|
||||
@synindex ky cp
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2013.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c Master file for the Getting Started (C) Guide
|
||||
@c
|
||||
|
||||
@include version.texi
|
||||
@include common/setup.texi
|
||||
@include common/rtems.texi
|
||||
|
||||
@ifset use-ascii
|
||||
@dircategory RTEMS On-Line Manual
|
||||
@direntry
|
||||
* RTEMS BSP-Howto: (bsp_howto). BSP and Device Driver Development Guide.
|
||||
@end direntry
|
||||
@end ifset
|
||||
|
||||
@c
|
||||
@c Title Page Stuff
|
||||
@c
|
||||
|
||||
@c
|
||||
@c I don't really like having a short title page. --joel
|
||||
@c
|
||||
@c @shorttitlepage BSP and Device Driver Development Guide
|
||||
|
||||
@setchapternewpage odd
|
||||
@settitle BSP and Device Driver Development Guide
|
||||
@titlepage
|
||||
@finalout
|
||||
|
||||
@title BSP and Device Driver Development Guide
|
||||
@subtitle Edition @value{EDITION}, for @value{VERSION}
|
||||
@sp 1
|
||||
@subtitle @value{UPDATED}
|
||||
@author On-Line Applications Research Corporation
|
||||
@page
|
||||
@include common/cpright.texi
|
||||
@end titlepage
|
||||
|
||||
@c This prevents a black box from being printed on "overflow" lines.
|
||||
@c The alternative is to rework a sentence to avoid this problem.
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top, Introduction, (dir), (dir)
|
||||
@top RTEMS BSP and Device Driver Development Guide
|
||||
|
||||
@menu
|
||||
* Introduction::
|
||||
* Target Dependent Files::
|
||||
* Makefiles::
|
||||
* Linker Script::
|
||||
* Miscellaneous Support Files::
|
||||
* Ada95 Interrupt Support::
|
||||
* Initialization Code::
|
||||
* Console Driver::
|
||||
* Clock Driver::
|
||||
* Timer Driver::
|
||||
* Real-Time Clock Driver::
|
||||
* ATA Driver::
|
||||
* IDE Controller Driver::
|
||||
* Networking Driver::
|
||||
* Non-Volatile Memory Driver::
|
||||
* Shared Memory Support Driver::
|
||||
* Frame Buffer Driver::
|
||||
* Analog Driver::
|
||||
* Discrete Driver::
|
||||
* Command and Variable Index::
|
||||
* Concept Index::
|
||||
@end menu
|
||||
@end ifnottex
|
||||
|
||||
@include intro.texi
|
||||
@include target.texi
|
||||
@include makefiles.texi
|
||||
@include linkcmds.texi
|
||||
@include support.texi
|
||||
@include adaintr.texi
|
||||
@include init.texi
|
||||
@include console.texi
|
||||
@include clock.texi
|
||||
@include timer.texi
|
||||
@include rtc.texi
|
||||
@include ata.texi
|
||||
@include ide-ctrl.texi
|
||||
@include nvmem.texi
|
||||
@include network.texi
|
||||
@include shmsupp.texi
|
||||
@include framebuffer.texi
|
||||
@include analog.texi
|
||||
@include discrete.texi
|
||||
|
||||
@node Command and Variable Index, Concept Index, , Top
|
||||
@unnumbered Command and Variable Index
|
||||
|
||||
There are currently no Command and Variable Index entries.
|
||||
|
||||
@c @printindex fn
|
||||
|
||||
@node Concept Index, , Command and Variable Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
There are currently no Concept Index entries.
|
||||
@c @printindex cp
|
||||
|
||||
@bye
|
||||
|
||||
@@ -1,299 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Clock Driver
|
||||
|
||||
@section Introduction
|
||||
|
||||
The purpose of the clock driver is to provide two services for the operating
|
||||
system.
|
||||
@itemize @bullet
|
||||
@item A steady time basis to the kernel, so that the RTEMS primitives that need
|
||||
a clock tick work properly. See the @cite{Clock Manager} chapter of the
|
||||
@cite{RTEMS Application C User's Guide} for more details.
|
||||
@item An optional time counter to generate timestamps of the uptime and wall
|
||||
clock time.
|
||||
@end itemize
|
||||
|
||||
The clock driver is usually located in the @file{clock} directory of the BSP.
|
||||
Clock drivers should use the @dfn{Clock Driver Shell} available via the
|
||||
@file{clockdrv_shell.h} include file.
|
||||
|
||||
@section Clock Driver Shell
|
||||
|
||||
The @dfn{Clock Driver Shell} include file defines the clock driver functions
|
||||
declared in @code{#include <rtems/clockdrv.h>} which are used by RTEMS
|
||||
configuration file @code{#include <rtems/confdefs.h>}. In case the application
|
||||
configuration defines @code{#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER},
|
||||
then the clock driver is registered and should provide its services to the
|
||||
operating system. A hardware specific clock driver must provide some
|
||||
functions, defines and macros for the @dfn{Clock Driver Shell} which are
|
||||
explained here step by step. A clock driver file looks in general like this.
|
||||
|
||||
@example
|
||||
/*
|
||||
* A section with functions, defines and macros to provide hardware specific
|
||||
* functions for the Clock Driver Shell.
|
||||
*/
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection Initialization
|
||||
|
||||
Depending on the hardware capabilities one out of three clock driver variants
|
||||
must be selected.
|
||||
@itemize @bullet
|
||||
@item The most basic clock driver provides only a periodic interrupt service
|
||||
routine which calls @code{rtems_clock_tick()}. The interval is determined by
|
||||
the application configuration via @code{#define
|
||||
CONFIGURE_MICROSECONDS_PER_TICK} and can be obtained via
|
||||
@code{rtems_configuration_get_microseconds_per_tick()}. The timestamp
|
||||
resolution is limited to the clock tick interval.
|
||||
@item In case the hardware lacks support for a free running counter, then the
|
||||
module used for the clock tick may provide support for timestamps with a
|
||||
resolution below the clock tick interval. For this so called simple
|
||||
timecounters can be used.
|
||||
@item The desired variant uses a free running counter to provide accurate
|
||||
timestamps. This variant is mandatory on SMP configurations.
|
||||
@end itemize
|
||||
|
||||
@subsubsection Clock Tick Only Variant
|
||||
|
||||
@example
|
||||
static void some_support_initialize_hardware( void )
|
||||
@{
|
||||
/* Initialize hardware */
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_initialize_hardware() \
|
||||
some_support_initialize_hardware()
|
||||
|
||||
/* Indicate that this clock driver lacks a proper timecounter in hardware */
|
||||
#define CLOCK_DRIVER_USE_DUMMY_TIMECOUNTER
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsubsection Simple Timecounter Variant
|
||||
|
||||
@example
|
||||
#include <rtems/timecounter.h>
|
||||
|
||||
static rtems_timecounter_simple some_tc;
|
||||
|
||||
static uint32_t some_tc_get( rtems_timecounter_simple *tc )
|
||||
@{
|
||||
return some.counter;
|
||||
@}
|
||||
|
||||
static void some_tc_at_tick( rtems_timecounter_simple *tc )
|
||||
@{
|
||||
/*
|
||||
* Do work necessary at the clock tick interrupt, e.g. clear a pending flag.
|
||||
*/
|
||||
@}
|
||||
|
||||
static bool some_tc_is_pending( rtems_timecounter_simple *tc )
|
||||
@{
|
||||
return some.is_pending;
|
||||
@}
|
||||
|
||||
static uint32_t some_tc_get_timecount( struct timecounter *tc )
|
||||
@{
|
||||
return rtems_timecounter_simple_downcounter_get(
|
||||
tc,
|
||||
some_tc_get,
|
||||
some_tc_is_pending
|
||||
);
|
||||
@}
|
||||
|
||||
static void some_tc_tick( void )
|
||||
@{
|
||||
rtems_timecounter_simple_downcounter_tick(
|
||||
&some_tc,
|
||||
some_tc_get,
|
||||
some_tc_at_tick
|
||||
);
|
||||
@}
|
||||
|
||||
static void some_support_initialize_hardware( void )
|
||||
@{
|
||||
uint32_t frequency = 123456;
|
||||
uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
|
||||
uint32_t timecounter_ticks_per_clock_tick =
|
||||
( frequency * us_per_tick ) / 1000000;
|
||||
|
||||
/* Initialize hardware */
|
||||
|
||||
rtems_timecounter_simple_install(
|
||||
&some_tc,
|
||||
frequency,
|
||||
timecounter_ticks_per_clock_tick,
|
||||
some_tc_get_timecount
|
||||
);
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_initialize_hardware() \
|
||||
some_support_initialize_hardware()
|
||||
|
||||
#define Clock_driver_timecounter_tick() \
|
||||
some_tc_tick()
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsubsection Timecounter Variant
|
||||
|
||||
This variant is preferred since it is the most efficient and yields the most
|
||||
accurate timestamps. It is also mandatory on SMP configurations to obtain
|
||||
valid timestamps. The hardware must provide a periodic interrupt to service
|
||||
the clock tick and a free running counter for the timecounter. The free
|
||||
running counter must have a power of two period. The @code{tc_counter_mask}
|
||||
must be initialized to the free running counter period minus one, e.g. for a
|
||||
32-bit counter this is 0xffffffff. The @code{tc_get_timecount} function must
|
||||
return the current counter value (the counter values must increase, so if the
|
||||
counter counts down, a conversion is necessary). Use
|
||||
@code{RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER} for the @code{tc_quality}. Set
|
||||
@code{tc_frequency} to the frequency of the free running counter in Hz. All
|
||||
other fields of the @code{struct timecounter} must be zero initialized.
|
||||
Install the initialized timecounter via @code{rtems_timecounter_install()}.
|
||||
|
||||
@example
|
||||
#include <rtems/timecounter.h>
|
||||
|
||||
static struct timecounter some_tc;
|
||||
|
||||
static uint32_t some_tc_get_timecount( struct timecounter *tc )
|
||||
@{
|
||||
some.free_running_counter;
|
||||
@}
|
||||
|
||||
static void some_support_initialize_hardware( void )
|
||||
@{
|
||||
uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
|
||||
uint32_t frequency = 123456;
|
||||
|
||||
/*
|
||||
* The multiplication must be done in 64-bit arithmetic to avoid an integer
|
||||
* overflow on targets with a high enough counter frequency.
|
||||
*/
|
||||
uint32_t interval = (uint32_t) ( ( frequency * us_per_tick ) / 1000000 );
|
||||
|
||||
/*
|
||||
* Initialize hardware and set up a periodic interrupt for the configuration
|
||||
* based interval.
|
||||
*/
|
||||
|
||||
some_tc.tc_get_timecount = some_tc_get_timecount;
|
||||
some_tc.tc_counter_mask = 0xffffffff;
|
||||
some_tc.tc_frequency = frequency;
|
||||
some_tc.tc_quality = RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER;
|
||||
rtems_timecounter_install( &some_tc );
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_initialize_hardware() \
|
||||
some_support_initialize_hardware()
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection Install Clock Tick Interrupt Service Routine
|
||||
|
||||
The clock driver must provide a function to install the clock tick interrupt
|
||||
service routine via @code{Clock_driver_support_install_isr()}.
|
||||
|
||||
@example
|
||||
#include <bsp/irq.h>
|
||||
#include <bsp/fatal.h>
|
||||
|
||||
static void some_support_install_isr( rtems_interrupt_handler isr )
|
||||
@{
|
||||
rtems_status_code sc;
|
||||
|
||||
sc = rtems_interrupt_handler_install(
|
||||
SOME_IRQ,
|
||||
"Clock",
|
||||
RTEMS_INTERRUPT_UNIQUE,
|
||||
isr,
|
||||
NULL
|
||||
);
|
||||
if ( sc != RTEMS_SUCCESSFUL ) @{
|
||||
bsp_fatal( SOME_FATAL_IRQ_INSTALL );
|
||||
@}
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_install_isr( isr, old ) \
|
||||
some_support_install_isr( isr )
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection Support At Tick
|
||||
|
||||
The hardware specific support at tick is specified by
|
||||
@code{Clock_driver_support_at_tick()}.
|
||||
|
||||
@example
|
||||
static void some_support_at_tick( void )
|
||||
@{
|
||||
/* Clear interrupt */
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_at_tick() \
|
||||
some_support_at_tick()
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection System Shutdown Support
|
||||
|
||||
The @dfn{Clock Driver Shell} provides the routine @code{Clock_exit()} that is
|
||||
scheduled to be run during system shutdown via the @code{atexit()} routine.
|
||||
The hardware specific shutdown support is specified by
|
||||
@code{Clock_driver_support_shutdown_hardware()} which is used by
|
||||
@code{Clock_exit()}. It should disable the clock tick source if it was
|
||||
enabled. This can be used to prevent clock ticks after the system is shutdown.
|
||||
|
||||
@example
|
||||
static void some_support_shutdown_hardware( void )
|
||||
@{
|
||||
/* Shutdown hardware */
|
||||
@}
|
||||
|
||||
#define Clock_driver_support_shutdown_hardware() \
|
||||
some_support_shutdown_hardware()
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection Multiple Clock Driver Ticks Per Clock Tick
|
||||
|
||||
In case the hardware needs more than one clock driver tick per clock tick (e.g.
|
||||
due to a limited range of the hardware timer), then this can be specified with
|
||||
the optional @code{#define CLOCK_DRIVER_ISRS_PER_TICK} and @code{#define
|
||||
CLOCK_DRIVER_ISRS_PER_TICK_VALUE} defines. This is currently used only for x86
|
||||
and it hopefully remains that way.
|
||||
|
||||
@example
|
||||
/* Enable multiple clock driver ticks per clock tick */
|
||||
#define CLOCK_DRIVER_ISRS_PER_TICK 1
|
||||
|
||||
/* Specifiy the clock driver ticks per clock tick value */
|
||||
#define CLOCK_DRIVER_ISRS_PER_TICK_VALUE 123
|
||||
|
||||
#include "../../../shared/clockdrv_shell.h"
|
||||
@end example
|
||||
|
||||
@subsection Clock Driver Ticks Counter
|
||||
|
||||
The @dfn{Clock Driver Shell} provide a global variable that is simply a count
|
||||
of the number of clock driver interrupt service routines that have occurred.
|
||||
This information is valuable when debugging a system. This variable is
|
||||
declared as follows:
|
||||
|
||||
@example
|
||||
volatile uint32_t Clock_driver_ticks;
|
||||
@end example
|
||||
@@ -1,645 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2008.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Console Driver
|
||||
|
||||
@section Introduction
|
||||
|
||||
This chapter describes the operation of a console driver using
|
||||
the RTEMS POSIX Termios support. Traditionally RTEMS has referred
|
||||
to all serial device drivers as console device drivers. A
|
||||
console driver can be used to do raw data processing in addition
|
||||
to the "normal" standard input and output device functions required
|
||||
of a console.
|
||||
|
||||
The serial driver may be called as the consequence of a C Library
|
||||
call such as @code{printf} or @code{scanf} or directly via the
|
||||
@code{read} or @code{write} system calls.
|
||||
There are two main functioning modes:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item console: formatted input/output, with special characters (end of
|
||||
line, tabulations, etc.) recognition and processing,
|
||||
|
||||
@item raw: permits raw data processing.
|
||||
|
||||
@end itemize
|
||||
|
||||
One may think that two serial drivers are needed to handle these two types
|
||||
of data, but Termios permits having only one driver.
|
||||
|
||||
@section Termios
|
||||
|
||||
Termios is a standard for terminal management, included in the POSIX
|
||||
1003.1b standard. As part of the POSIX and Open Group Single UNIX
|
||||
Specification, is commonly provided on UNIX implementations. The
|
||||
Open Group has the termios portion of the POSIX standard online
|
||||
at @uref{http://opengroup.org/onlinepubs/007908775/xbd/termios.html
|
||||
,http://opengroup.org/onlinepubs/007908775/xbd/termios.html}.
|
||||
The requirements for the @code{<termios.h>} file are also provided
|
||||
and are at @uref{http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html,
|
||||
http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html}.
|
||||
|
||||
Having RTEMS support for Termios is beneficial because:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item from the user's side because it provides standard primitive operations
|
||||
to access the terminal and change configuration settings. These operations
|
||||
are the same under UNIX and RTEMS.
|
||||
|
||||
@item from the BSP developer's side because it frees the
|
||||
developer from dealing with buffer states and mutual exclusions on them.
|
||||
Early RTEMS console device drivers also did their own special
|
||||
character processing.
|
||||
|
||||
@item it is part of an internationally recognized standard.
|
||||
|
||||
@item it makes porting code from other environments easier.
|
||||
|
||||
@end itemize
|
||||
|
||||
Termios support includes:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item raw and console handling,
|
||||
|
||||
@item blocking or non-blocking characters receive, with or without
|
||||
Timeout.
|
||||
|
||||
@end itemize
|
||||
|
||||
At this time, RTEMS documentation does not include a thorough discussion
|
||||
of the Termios functionality. For more information on Termios,
|
||||
type @code{man termios} on a Unix box or point a web browser
|
||||
at
|
||||
@uref{http://www.freebsd.org/cgi/man.cgi}.
|
||||
|
||||
@section Driver Functioning Modes
|
||||
|
||||
There are generally three main functioning modes for an UART (Universal
|
||||
Asynchronous Receiver-Transmitter, i.e. the serial chip):
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item polled mode
|
||||
@item interrupt driven mode
|
||||
@item task driven mode
|
||||
|
||||
@end itemize
|
||||
|
||||
In polled mode, the processor blocks on sending/receiving characters.
|
||||
This mode is not the most efficient way to utilize the UART. But
|
||||
polled mode is usually necessary when one wants to print an
|
||||
error message in the event of a fatal error such as a fatal error
|
||||
in the BSP. This is also the simplest mode to
|
||||
program. Polled mode is generally preferred if the serial port is
|
||||
to be used primarily as a debug console. In a simple polled driver,
|
||||
the software will continuously check the status of the UART when
|
||||
it is reading or writing to the UART. Termios improves on this
|
||||
by delaying the caller for 1 clock tick between successive checks
|
||||
of the UART on a read operation.
|
||||
|
||||
In interrupt driven mode, the processor does not block on sending/receiving
|
||||
characters. Data is buffered between the interrupt service routine
|
||||
and application code. Two buffers are used to insulate the application
|
||||
from the relative slowness of the serial device. One of the buffers is
|
||||
used for incoming characters, while the other is used for outgoing characters.
|
||||
|
||||
An interrupt is raised when a character is received by the UART.
|
||||
The interrupt subroutine places the incoming character at the end
|
||||
of the input buffer. When an application asks for input,
|
||||
the characters at the front of the buffer are returned.
|
||||
|
||||
When the application prints to the serial device, the outgoing characters
|
||||
are placed at the end of the output buffer. The driver will place
|
||||
one or more characters in the UART (the exact number depends on the UART)
|
||||
An interrupt will be raised when all the characters have been transmitted.
|
||||
The interrupt service routine has to send the characters
|
||||
remaining in the output buffer the same way. When the transmitting side
|
||||
of the UART is idle, it is typically necessary to prime the transmitter
|
||||
before the first interrupt will occur.
|
||||
|
||||
The task driven mode is similar to interrupt driven mode, but the actual data
|
||||
processing is done in dedicated tasks instead of interrupt routines.
|
||||
|
||||
@section Serial Driver Functioning Overview
|
||||
|
||||
The following Figure shows how a Termios driven serial driver works:
|
||||
|
||||
@ifset use-ascii
|
||||
@center Figure not included in ASCII version
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@sp1
|
||||
@center{@image{TERMIOSFlow,,6in}}
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<P ALIGN="center"><IMG SRC="TERMIOSFlow.png" ALT="Termios Flow"></P>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
The following list describes the basic flow.
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item the application programmer uses standard C library call (printf,
|
||||
scanf, read, write, etc.),
|
||||
|
||||
@item C library (ctx.g. RedHat (formerly Cygnus) Newlib) calls
|
||||
the RTEMS system call interface. This code can be found in the
|
||||
@file{cpukit/libcsupport/src} directory.
|
||||
|
||||
@item Glue code calls the serial driver entry routines.
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Basics
|
||||
|
||||
The low-level driver API changed between RTEMS 4.10 and RTEMS 4.11. The legacy
|
||||
callback API is still supported, but its use is discouraged. The following
|
||||
functions are deprecated:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @code{rtems_termios_open()} - use @code{rtems_termios_device_open()} in
|
||||
combination with @code{rtems_termios_device_install()} instead.
|
||||
|
||||
@item @code{rtems_termios_close()} - use @code{rtems_termios_device_close()}
|
||||
instead.
|
||||
|
||||
@end itemize
|
||||
|
||||
This manual describes the new API. A new console driver should consist of
|
||||
three parts.
|
||||
|
||||
@enumerate
|
||||
|
||||
@item The basic console driver functions using the Termios support. Add this
|
||||
the BSPs Makefile.am:
|
||||
|
||||
@example
|
||||
@group
|
||||
[...]
|
||||
libbsp_a_SOURCES += ../../shared/console-termios.c
|
||||
[...]
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@item A general serial module specific low-level driver providing the handler
|
||||
table for the Termios @code{rtems_termios_device_install()} function. This
|
||||
low-level driver could be used for more than one BSP.
|
||||
|
||||
@item A BSP specific initialization routine @code{console_initialize()}, that
|
||||
calls @code{rtems_termios_device_install()} providing a low-level driver
|
||||
context for each installed device.
|
||||
|
||||
@end enumerate
|
||||
|
||||
You need to provide a device handler structure for the Termios device
|
||||
interface. The functions are described later in this chapter. The first open
|
||||
and set attributes handler return a boolean status to indicate success (true)
|
||||
or failure (false). The polled read function returns an unsigned character in
|
||||
case one is available or minus one otherwise.
|
||||
|
||||
If you want to use polled IO it should look like the following. Termios must
|
||||
be told the addresses of the handler that are to be used for simple character
|
||||
IO, i.e. pointers to the @code{my_driver_poll_read()} and
|
||||
@code{my_driver_poll_write()} functions described later in @ref{Console Driver
|
||||
Termios and Polled IO}.
|
||||
|
||||
@example
|
||||
@group
|
||||
const rtems_termios_handler my_driver_handler_polled = @{
|
||||
.first_open = my_driver_first_open,
|
||||
.last_close = my_driver_last_close,
|
||||
.poll_read = my_driver_poll_read,
|
||||
.write = my_driver_poll_write,
|
||||
.set_attributes = my_driver_set_attributes,
|
||||
.stop_remote_tx = NULL,
|
||||
.start_remote_tx = NULL,
|
||||
.mode = TERMIOS_POLLED
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
For an interrupt driven implementation you need the following. The driver
|
||||
functioning is quite different in this mode. There is no device driver read
|
||||
handler to be passed to Termios. Indeed a @code{console_read()} call returns the
|
||||
contents of Termios input buffer. This buffer is filled in the driver
|
||||
interrupt subroutine, see also @ref{Console Driver Termios and Interrupt Driven
|
||||
IO}. The driver is responsible for providing a pointer to the
|
||||
@code{my_driver_interrupt_write()} function.
|
||||
|
||||
@example
|
||||
@group
|
||||
const rtems_termios_handler my_driver_handler_interrupt = @{
|
||||
.first_open = my_driver_first_open,
|
||||
.last_close = my_driver_last_close,
|
||||
.poll_read = NULL,
|
||||
.write = my_driver_interrupt_write,
|
||||
.set_attributes = my_driver_set_attributes,
|
||||
.stopRemoteTx = NULL,
|
||||
.stop_remote_tx = NULL,
|
||||
.start_remote_tx = NULL,
|
||||
.mode = TERMIOS_IRQ_DRIVEN
|
||||
@};
|
||||
@end group
|
||||
@end example
|
||||
|
||||
You can also provide hander for remote transmission control. This
|
||||
is not covered in this manual, so they are set to @code{NULL} in the above
|
||||
examples.
|
||||
|
||||
The low-level driver should provide a data structure for its device context.
|
||||
The initialization routine must provide a context for each installed device via
|
||||
@code{rtems_termios_device_install()}. For simplicity of the console
|
||||
initialization example the device name is also present. Her is an example header file.
|
||||
|
||||
@example
|
||||
@group
|
||||
#ifndef MY_DRIVER_H
|
||||
#define MY_DRIVER_H
|
||||
|
||||
#include <rtems/termiostypes.h>
|
||||
|
||||
#include <some-chip-header.h>
|
||||
|
||||
/* Low-level driver specific data structure */
|
||||
typedef struct @{
|
||||
rtems_termios_device_context base;
|
||||
const char *device_name;
|
||||
volatile module_register_block *regs;
|
||||
/* More stuff */
|
||||
@} my_driver_context;
|
||||
|
||||
extern const rtems_termios_handler my_driver_handler_polled;
|
||||
|
||||
extern const rtems_termios_handler my_driver_handler_interrupt;
|
||||
|
||||
#endif /* MY_DRIVER_H */
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Termios and Polled IO
|
||||
|
||||
The following handler are provided by the low-level driver and invoked by
|
||||
Termios for simple character IO.
|
||||
|
||||
The @code{my_driver_poll_write()} routine is responsible for writing @code{n}
|
||||
characters from @code{buf} to the serial device specified by @code{tty}.
|
||||
|
||||
@example
|
||||
@group
|
||||
static void my_driver_poll_write(
|
||||
rtems_termios_device_context *base,
|
||||
const char *buf,
|
||||
size_t n
|
||||
)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
size_t i;
|
||||
|
||||
/* Write */
|
||||
for (i = 0; i < n; ++i) @{
|
||||
my_driver_write_char(ctx, buf[i]);
|
||||
@}
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The @code{my_driver_poll_read} routine is responsible for reading a single
|
||||
character from the serial device specified by @code{tty}. If no character is
|
||||
available, then the routine should return minus one.
|
||||
|
||||
@example
|
||||
@group
|
||||
static int my_driver_poll_read(rtems_termios_device_context *base)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
|
||||
/* Check if a character is available */
|
||||
if (my_driver_can_read_char(ctx)) @{
|
||||
/* Return the character */
|
||||
return my_driver_read_char(ctx);
|
||||
@} else @{
|
||||
/* Return an error status */
|
||||
return -1;
|
||||
@}
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Termios and Interrupt Driven IO
|
||||
|
||||
The UART generally generates interrupts when it is ready to accept or to emit a
|
||||
number of characters. In this mode, the interrupt subroutine is the core of
|
||||
the driver.
|
||||
|
||||
The @code{my_driver_interrupt_handler()} is responsible for processing
|
||||
asynchronous interrupts from the UART. There may be multiple interrupt
|
||||
handlers for a single UART. Some UARTs can generate a unique interrupt vector
|
||||
for each interrupt source such as a character has been received or the
|
||||
transmitter is ready for another character.
|
||||
|
||||
In the simplest case, the @code{my_driver_interrupt_handler()} will have to check
|
||||
the status of the UART and determine what caused the interrupt. The following
|
||||
describes the operation of an @code{my_driver_interrupt_handler} which has to
|
||||
do this:
|
||||
|
||||
@example
|
||||
@group
|
||||
static void my_driver_interrupt_handler(
|
||||
rtems_vector_number vector,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
rtems_termios_tty *tty = arg;
|
||||
my_driver_context *ctx = rtems_termios_get_device_context(tty);
|
||||
char buf[N];
|
||||
size_t n;
|
||||
|
||||
/*
|
||||
* Check if we have received something. The function reads the
|
||||
* received characters from the device and stores them in the
|
||||
* buffer. It returns the number of read characters.
|
||||
*/
|
||||
n = my_driver_read_received_chars(ctx, buf, N);
|
||||
if (n > 0) @{
|
||||
/* Hand the data over to the Termios infrastructure */
|
||||
rtems_termios_enqueue_raw_characters(tty, buf, n);
|
||||
@}
|
||||
|
||||
/*
|
||||
* Check if we have something transmitted. The functions returns
|
||||
* the number of transmitted characters since the last write to the
|
||||
* device.
|
||||
*/
|
||||
n = my_driver_transmitted_chars(ctx);
|
||||
if (n > 0) @{
|
||||
/*
|
||||
* Notify Termios that we have transmitted some characters. It
|
||||
* will call now the interrupt write function if more characters
|
||||
* are ready for transmission.
|
||||
*/
|
||||
rtems_termios_dequeue_characters(tty, n);
|
||||
@}
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The @code{my_driver_interrupt_write()} function is responsible for telling the
|
||||
device that the @code{n} characters at @code{buf} are to be transmitted. It
|
||||
the value @code{n} is zero to indicate that no more characters are to send.
|
||||
The driver can disable the transmit interrupts now. This routine is invoked
|
||||
either from task context with disabled interrupts to start a new transmission
|
||||
process with exactly one character in case of an idle output state or from the
|
||||
interrupt handler to refill the transmitter. If the routine is invoked to
|
||||
start the transmit process the output state will become busy and Termios starts
|
||||
to fill the output buffer. If the transmit interrupt arises before Termios was
|
||||
able to fill the transmit buffer you will end up with one interrupt per
|
||||
character.
|
||||
|
||||
@example
|
||||
@group
|
||||
static void my_driver_interrupt_write(
|
||||
rtems_termios_device_context *base,
|
||||
const char *buf,
|
||||
size_t n
|
||||
)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
|
||||
/*
|
||||
* Tell the device to transmit some characters from buf (less than
|
||||
* or equal to n). When the device is finished it should raise an
|
||||
* interrupt. The interrupt handler will notify Termios that these
|
||||
* characters have been transmitted and this may trigger this write
|
||||
* function again. You may have to store the number of outstanding
|
||||
* characters in the device data structure.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Termios will set n to zero to indicate that the transmitter is
|
||||
* now inactive. The output buffer is empty in this case. The
|
||||
* driver may disable the transmit interrupts now.
|
||||
*/
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Initialization
|
||||
|
||||
The BSP specific driver initialization is called once during the RTEMS
|
||||
initialization process.
|
||||
|
||||
The @code{console_initialize()} function may look like this:
|
||||
|
||||
@example
|
||||
@group
|
||||
#include <my-driver.h>
|
||||
#include <rtems/console.h>
|
||||
#include <bsp.h>
|
||||
#include <bsp/fatal.h>
|
||||
|
||||
static my_driver_context driver_context_table[M] = @{ /* Some values */ @};
|
||||
|
||||
rtems_device_driver console_initialize(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
rtems_status_code sc;
|
||||
#ifdef SOME_BSP_USE_INTERRUPTS
|
||||
const rtems_termios_handler *handler = &my_driver_handler_interrupt;
|
||||
#else
|
||||
const rtems_termios_handler *handler = &my_driver_handler_polled;
|
||||
#endif
|
||||
|
||||
/*
|
||||
* Initialize the Termios infrastructure. If Termios has already
|
||||
* been initialized by another device driver, then this call will
|
||||
* have no effect.
|
||||
*/
|
||||
rtems_termios_initialize();
|
||||
|
||||
/* Initialize each device */
|
||||
for (
|
||||
minor = 0;
|
||||
minor < RTEMS_ARRAY_SIZE(driver_context_table);
|
||||
++minor
|
||||
) @{
|
||||
my_driver_context *ctx = &driver_context_table[minor];
|
||||
|
||||
/*
|
||||
* Install this device in the file system and Termios. In order
|
||||
* to use the console (i.e. being able to do printf, scanf etc.
|
||||
* on stdin, stdout and stderr), one device must be registered as
|
||||
* "/dev/console" (CONSOLE_DEVICE_NAME).
|
||||
*/
|
||||
sc = rtems_termios_device_install(
|
||||
ctx->device_name,
|
||||
major,
|
||||
minor,
|
||||
handler,
|
||||
NULL,
|
||||
ctx
|
||||
);
|
||||
if (sc != RTEMS_SUCCESSFUL) @{
|
||||
bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
|
||||
@}
|
||||
@}
|
||||
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Opening a serial device
|
||||
|
||||
The @code{console_open()} function provided by @file{console-termios.c} is
|
||||
called whenever a serial device is opened. The device registered as
|
||||
@code{"/dev/console"} (@code{CONSOLE_DEVICE_NAME}) is opened automatically
|
||||
during RTEMS initialization. For instance, if UART channel 2 is registered as
|
||||
@code{"/dev/tty1"}, the @code{console_open()} entry point will be called as the
|
||||
result of an @code{fopen("/dev/tty1", mode)} in the application.
|
||||
|
||||
During the first open of the device Termios will call the
|
||||
@code{my_driver_first_open()} handler.
|
||||
|
||||
@example
|
||||
@group
|
||||
static bool my_driver_first_open(
|
||||
rtems_termios_tty *tty,
|
||||
rtems_termios_device_context *base,
|
||||
struct termios *term,
|
||||
rtems_libio_open_close_args_t *args
|
||||
)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
rtems_status_code sc;
|
||||
bool ok;
|
||||
|
||||
/*
|
||||
* You may add some initialization code here.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Sets the initial baud rate. This should be set to the value of
|
||||
* the boot loader. This function accepts only exact Termios baud
|
||||
* values.
|
||||
*/
|
||||
sc = rtems_termios_set_initial_baud(tty, MY_DRIVER_BAUD_RATE);
|
||||
if (sc != RTEMS_SUCCESSFUL) @{
|
||||
/* Not a valid Termios baud */
|
||||
@}
|
||||
|
||||
/*
|
||||
* Alternatively you can set the best baud.
|
||||
*/
|
||||
rtems_termios_set_best_baud(term, MY_DRIVER_BAUD_RATE);
|
||||
|
||||
/*
|
||||
* To propagate the initial Termios attributes to the device use
|
||||
* this.
|
||||
*/
|
||||
ok = my_driver_set_attributes(base, term);
|
||||
if (!ok) @{
|
||||
/* This is bad */
|
||||
@}
|
||||
|
||||
/*
|
||||
* Return true to indicate a successful set attributes, and false
|
||||
* otherwise.
|
||||
*/
|
||||
return true;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Closing a Serial Device
|
||||
|
||||
The @code{console_close()} provided by @file{console-termios.c} is invoked when
|
||||
the serial device is to be closed. This entry point corresponds to the device
|
||||
driver close entry point.
|
||||
|
||||
Termios will call the @code{my_driver_last_close()} handler if the last close
|
||||
happens on the device.
|
||||
@example
|
||||
@group
|
||||
static void my_driver_last_close(
|
||||
rtems_termios_tty *tty,
|
||||
rtems_termios_device_context *base,
|
||||
rtems_libio_open_close_args_t *args
|
||||
)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
|
||||
/*
|
||||
* The driver may do some cleanup here.
|
||||
*/
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Reading Characters from a Serial Device
|
||||
|
||||
The @code{console_read()} provided by @file{console-termios.c} is invoked when
|
||||
the serial device is to be read from. This entry point corresponds to the
|
||||
device driver read entry point.
|
||||
|
||||
@subsection Writing Characters to a Serial Device
|
||||
|
||||
The @code{console_write()} provided by @file{console-termios.c} is invoked when
|
||||
the serial device is to be written to. This entry point corresponds to the
|
||||
device driver write entry point.
|
||||
|
||||
@subsection Changing Serial Line Parameters
|
||||
|
||||
The @code{console_control()} provided by @file{console-termios.c} is invoked
|
||||
when the line parameters for a particular serial device are to be changed.
|
||||
This entry point corresponds to the device driver IO control entry point.
|
||||
|
||||
The application writer is able to control the serial line configuration with
|
||||
Termios calls (such as the @code{ioctl()} command, see the Termios
|
||||
documentation for more details). If the driver is to support dynamic
|
||||
configuration, then it must have the @code{console_control()} piece of code.
|
||||
Basically @code{ioctl()} commands call @code{console_control()} with the serial
|
||||
line configuration in a Termios defined data structure.
|
||||
|
||||
The driver is responsible for reinitializing the device with the correct
|
||||
settings. For this purpose Termios calls the @code{my_driver_set_attributes()}
|
||||
handler.
|
||||
|
||||
@example
|
||||
@group
|
||||
static bool my_driver_set_attributes(
|
||||
rtems_termios_device_context *base,
|
||||
const struct termios *term
|
||||
)
|
||||
@{
|
||||
my_driver_context *ctx = (my_driver_context *) base;
|
||||
|
||||
/*
|
||||
* Inspect the termios data structure and configure the device
|
||||
* appropriately. The driver should only be concerned with the
|
||||
* parts of the structure that specify hardware setting for the
|
||||
* communications channel such as baud, character size, etc.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Return true to indicate a successful set attributes, and false
|
||||
* otherwise.
|
||||
*/
|
||||
return true;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
@@ -1,183 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Discrete Driver
|
||||
|
||||
The Discrete driver is responsible for providing an
|
||||
interface to Discrete Input/Outputs. The capabilities provided
|
||||
by this class of device driver are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Initialize a Discrete I/O Board
|
||||
@item Open a Particular Discrete Bitfield
|
||||
@item Close a Particular Discrete Bitfield
|
||||
@item Read from a Particular Discrete Bitfield
|
||||
@item Write to a Particular Discrete Bitfield
|
||||
@item Reset DACs
|
||||
@item Reinitialize DACS
|
||||
@end itemize
|
||||
|
||||
Most discrete I/O devices are found on I/O cards that support many
|
||||
bits of discrete I/O on a single card. This driver model is centered
|
||||
on the notion of reading bitfields from the card.
|
||||
|
||||
There are currently no discrete I/O device drivers included in the
|
||||
RTEMS source tree. The information provided in this chapter
|
||||
is based on drivers developed for applications using RTEMS.
|
||||
It is hoped that this driver model information can form the
|
||||
discrete I/O driver model that can be supported in future RTEMS
|
||||
distribution.
|
||||
|
||||
@section Major and Minor Numbers
|
||||
|
||||
The @b{major} number of a device driver is its index in the
|
||||
RTEMS Device Address Table.
|
||||
|
||||
A @b{minor} number is associated with each device instance
|
||||
managed by a particular device driver. An RTEMS minor number
|
||||
is an @code{unsigned32} entity. Convention calls for
|
||||
dividing the bits in the minor number down into categories
|
||||
that specify a particular bitfield. This results in categories
|
||||
like the following:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @b{board} - indicates the board a particular bitfield is located on
|
||||
@item @b{word} - indicates the particular word of discrete bits the
|
||||
bitfield is located within
|
||||
@item @b{start} - indicates the starting bit of the bitfield
|
||||
@item @b{width} - indicates the width of the bitfield
|
||||
|
||||
@end itemize
|
||||
|
||||
From the above, it should be clear that a single device driver
|
||||
can support multiple copies of the same board in a single system.
|
||||
The minor number is used to distinguish the devices.
|
||||
|
||||
By providing a way to easily access a particular bitfield from
|
||||
the device driver, the application is insulated with knowing how
|
||||
to mask fields in and out of a discrete I/O.
|
||||
|
||||
@section Discrete I/O Driver Configuration
|
||||
|
||||
There is not a standard discrete I/O driver configuration table but some
|
||||
fields are common across different drivers. The discrete I/O driver
|
||||
configuration table is typically an array of structures with each
|
||||
structure containing the information for a particular board.
|
||||
The following is a list of the type of information normally required
|
||||
to configure an discrete I/O board:
|
||||
|
||||
@table @b
|
||||
@item board_offset
|
||||
is the base address of a board.
|
||||
|
||||
@item relay_initial_values
|
||||
is an array of the values that should be written to each output
|
||||
word on the board during initialization. This allows the driver
|
||||
to start with the board's output in a known state.
|
||||
|
||||
@end table
|
||||
|
||||
@section Initialize a Discrete I/O Board
|
||||
|
||||
At system initialization, the discrete I/O driver's initialization entry point
|
||||
will be invoked. As part of initialization, the driver will perform
|
||||
whatever board initializatin is required and then set all
|
||||
outputs to their configured initial state.
|
||||
|
||||
The discrete I/O driver may register a device name for bitfields of
|
||||
particular interest to the system. Normally this will be restricted
|
||||
to the names of each word and, if the driver supports it, an "all words".
|
||||
|
||||
@section Open a Particular Discrete Bitfield
|
||||
|
||||
This is the driver open call. Usually this call does nothing other than
|
||||
validate the minor number.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is often the place
|
||||
to do this operation.
|
||||
|
||||
@section Close a Particular Discrete Bitfield
|
||||
|
||||
This is the driver close call. Usually this call does nothing.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is the place
|
||||
where that memory should be deallocated.
|
||||
|
||||
@section Read from a Particular Discrete Bitfield
|
||||
|
||||
This corresponds to the driver read call. After validating the minor
|
||||
number and arguments, this call reads the indicated bitfield. A
|
||||
discrete I/O devices may have to store the last value written to
|
||||
a discrete output. If the bitfield is output only, saving the last
|
||||
written value gives the appearance that it can be read from also.
|
||||
If the bitfield is input, then it is sampled.
|
||||
|
||||
@b{NOTE:} Many discrete inputs have a tendency to bounce. The application
|
||||
may have to take account for bounces.
|
||||
|
||||
The value returned is an @code{unsigned32} number
|
||||
representing the bitfield read. This value is stored in the
|
||||
@code{argument_block} passed in to the call.
|
||||
|
||||
@b{NOTE:} Some discrete I/O drivers have a special minor number
|
||||
used to access all discrete I/O bits on the board. If this special
|
||||
minor is used, then the area pointed to by @code{argument_block} must
|
||||
be the correct size.
|
||||
|
||||
@section Write to a Particular Discrete Bitfield
|
||||
|
||||
This corresponds to the driver write call. After validating the minor
|
||||
number and arguments, this call writes the indicated device. If the
|
||||
specified device is an ADC, then an error is usually returned.
|
||||
|
||||
The value written is an @code{unsigned32} number
|
||||
representing the value to be written to the specified
|
||||
bitfield. This value is stored in the
|
||||
@code{argument_block} passed in to the call.
|
||||
|
||||
@b{NOTE:} Some discrete I/O drivers have a special minor number
|
||||
used to access all discrete I/O bits on the board. If this special
|
||||
minor is used, then the area pointed to by @code{argument_block} must
|
||||
be the correct size.
|
||||
|
||||
@section Disable Discrete Outputs
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the discrete outputs are disabled.
|
||||
|
||||
@b{NOTE:} It may not be possible to disable/enable discrete output on all
|
||||
discrete I/O boards.
|
||||
|
||||
@section Enable Discrete Outputs
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the discrete outputs are enabled.
|
||||
|
||||
@b{NOTE:} It may not be possible to disable/enable discrete output on all
|
||||
discrete I/O boards.
|
||||
|
||||
@section Reinitialize Outputs
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the discrete outputs are rewritten with the configured initial
|
||||
output values.
|
||||
|
||||
@section Get Last Written Values
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the following information is returned to the caller:
|
||||
|
||||
@itemize @bullet
|
||||
@item last value written to the specified output word
|
||||
@item timestamp of when the last write was performed
|
||||
@end itemize
|
||||
|
||||
@@ -1,251 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2009.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Frame Buffer Driver
|
||||
|
||||
In this chapter, we present the basic functionality implemented by a
|
||||
frame buffer driver: @code{frame_buffer_initialize()}, @code{frame_buffer_open()},
|
||||
@code{frame_buffer_close()}, @code{frame_buffer_read()}, @code{frame_buffer_write()}
|
||||
and @code{frame_buffer_control()}.
|
||||
|
||||
@section Introduction
|
||||
|
||||
The purpose of the frame buffer driver is to provide an abstraction for
|
||||
graphics hardware.
|
||||
By using the frame buffer interface, an application can display graphics
|
||||
without knowing anything about the low-level details of interfacing to a
|
||||
particular graphics adapter. The parameters governing the mapping of
|
||||
memory to displayed pixels (planar or linear, bit depth, etc) is still
|
||||
implementation-specific, but device-independent methods are provided to
|
||||
determine and potentially modify these parameters.
|
||||
|
||||
The frame buffer driver is commonly located in the @code{console}
|
||||
directory of the BSP and registered by the name @b{/dev/fb0}.
|
||||
Additional frame buffers (if available) are named @b{/dev/fb1},
|
||||
@b{/dev/fb2}, etc.
|
||||
|
||||
To work with the frame buffer, the following operation sequence is used:
|
||||
@code{open()}, @code{ioctls()} to get the frame buffer info, @code{read()} and/or
|
||||
@code{write()}, and @code{close()}.
|
||||
|
||||
@section Driver Function Overview
|
||||
|
||||
@subsection Initialization
|
||||
|
||||
The driver initialization is called once during the RTEMS initialization
|
||||
process and returns RTEMS_SUCCESSFUL when the device driver is successfully
|
||||
initialized. During the initialization, a name is assigned to the frame
|
||||
buffer device. If the graphics hardware supports console text output,
|
||||
as is the case with the pc386 VGA hardware, initialization into graphics
|
||||
mode may be deferred until the device is @code{open()}ed.
|
||||
|
||||
The @code{frame_buffer_initialize()} function may look like this:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_initialize(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg)
|
||||
@{
|
||||
rtems_status_code status;
|
||||
|
||||
printk( "frame buffer driver initializing..\n" );
|
||||
|
||||
/*
|
||||
* Register the device
|
||||
*/
|
||||
status = rtems_io_register_name("/dev/fb0", major, 0);
|
||||
if (status != RTEMS_SUCCESSFUL)
|
||||
@{
|
||||
printk("Error registering frame buffer device!\n");
|
||||
rtems_fatal_error_occurred( status );
|
||||
@}
|
||||
|
||||
/*
|
||||
* graphics hardware initialization goes here for non-console
|
||||
* devices
|
||||
*/
|
||||
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Opening the Frame Buffer Device
|
||||
|
||||
The @code{frame_buffer_open()} function is called whenever a frame buffer device is opened.
|
||||
If the frame buffer is registered as "/dev/fb0", the @code{frame_buffer_open} entry point
|
||||
will be called as the result of an @code{open("/dev/fb0", mode)} in the application.
|
||||
|
||||
Thread safety of the frame buffer driver is implementation-dependent.
|
||||
The VGA driver shown below uses a mutex to prevent multiple open()
|
||||
operations of the frame buffer device.
|
||||
|
||||
The @code{frame_buffer_open()} function returns RTEMS_SUCCESSFUL when the device driver
|
||||
is successfully opened, and RTEMS_UNSATISFIED if the device is already open:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_close(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
if (pthread_mutex_unlock(&mutex) == 0)@{
|
||||
/* restore previous state. for VGA this means return to text mode.
|
||||
* leave out if graphics hardware has been initialized in
|
||||
* frame_buffer_initialize() */
|
||||
ega_hwterm();
|
||||
printk( "FBVGA close called.\n" );
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
|
||||
return RTEMS_UNSATISFIED;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
In the previous example, the function @code{ega_hwinit()} takes care of
|
||||
hardware-specific initialization.
|
||||
|
||||
@subsection Closing the Frame Buffer Device
|
||||
|
||||
The @code{frame_buffer_close()} is invoked when the frame buffer device
|
||||
is closed. It frees up any resources allocated in
|
||||
@code{frame_buffer_open()}, and should restore previous hardware state.
|
||||
The entry point corresponds to the device driver close entry point.
|
||||
|
||||
Returns RTEMS_SUCCESSFUL when the device driver is successfully closed:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_close(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg)
|
||||
@{
|
||||
pthread_mutex_unlock(&mutex);
|
||||
/* TODO check mutex return value, RTEMS_UNSATISFIED if it failed. we
|
||||
* don't want to unconditionally call ega_hwterm()... */
|
||||
/* restore previous state. for VGA this means return to text mode.
|
||||
* leave out if graphics hardware has been initialized in
|
||||
* frame_buffer_initialize() */
|
||||
ega_hwterm();
|
||||
printk( "frame buffer close called.\n" );
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
||||
@subsection Reading from the Frame Buffer Device
|
||||
|
||||
The @code{frame_buffer_read()} is invoked from a @code{read()} operation
|
||||
on the frame buffer device.
|
||||
Read functions should allow normal and partial reading at the end of frame buffer memory.
|
||||
This method returns RTEMS_SUCCESSFUL when the device is successfully read from:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_read(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg;
|
||||
rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
|
||||
memcpy(rw_args->buffer, (const void *) (fb_fix.smem_start + rw_args->offset), rw_args->bytes_moved);
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Writing to the Frame Buffer Device
|
||||
|
||||
The @code{frame_buffer_write()} is invoked from a @code{write()}
|
||||
operation on the frame buffer device.
|
||||
The frame buffer write function is similar to the read function, and
|
||||
should handle similar cases involving partial writes.
|
||||
|
||||
This method returns RTEMS_SUCCESSFUL when the device is successfully
|
||||
written to:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_write(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg;
|
||||
rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
|
||||
memcpy( (void *) (fb_fix.smem_start + rw_args->offset), rw_args->buffer, rw_args->bytes_moved);
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
||||
@subsection Frame Buffer IO Control
|
||||
|
||||
The frame buffer driver allows several ioctls, partially compatible with
|
||||
the Linux kernel,
|
||||
to obtain information about the hardware.
|
||||
|
||||
All @code{ioctl()} operations on the frame buffer device invoke
|
||||
@code{frame_buffer_control()}.
|
||||
|
||||
Ioctls supported:
|
||||
@itemize @bullet
|
||||
@item ioctls to get the frame buffer screen info (fixed and variable).
|
||||
@item ioctl to set and get palette.
|
||||
@end itemize
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver frame_buffer_control(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
rtems_libio_ioctl_args_t *args = arg;
|
||||
|
||||
printk( "FBVGA ioctl called, cmd=%x\n", args->command );
|
||||
|
||||
switch( args->command ) @{
|
||||
case FBIOGET_FSCREENINFO:
|
||||
args->ioctl_return = get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer );
|
||||
break;
|
||||
case FBIOGET_VSCREENINFO:
|
||||
args->ioctl_return = get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer );
|
||||
break;
|
||||
case FBIOPUT_VSCREENINFO:
|
||||
/* not implemented yet*/
|
||||
args->ioctl_return = -1;
|
||||
return RTEMS_UNSATISFIED;
|
||||
case FBIOGETCMAP:
|
||||
args->ioctl_return = get_palette( ( struct fb_cmap * ) args->buffer );
|
||||
break;
|
||||
case FBIOPUTCMAP:
|
||||
args->ioctl_return = set_palette( ( struct fb_cmap * ) args->buffer );
|
||||
break;
|
||||
|
||||
default:
|
||||
args->ioctl_return = 0;
|
||||
break;
|
||||
@}
|
||||
return RTEMS_SUCCESSFUL;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
See @code{rtems/fb.h} for more information on the list of ioctls and
|
||||
data structures they work with.
|
||||
@@ -1,154 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter IDE Controller Driver
|
||||
|
||||
@section Introduction
|
||||
|
||||
The IDE Controller driver is responsible for providing an
|
||||
interface to an IDE Controller. The capabilities provided by this
|
||||
driver are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Read IDE Controller register
|
||||
@item Write IDE Controller register
|
||||
@item Read data block through IDE Controller Data Register
|
||||
@item Write data block through IDE Controller Data Register
|
||||
@end itemize
|
||||
|
||||
The reference implementation for an IDE Controller driver can
|
||||
be found in @code{$RTEMS_SRC_ROOT/c/src/libchip/ide}. This driver
|
||||
is based on the libchip concept and allows to work with any of the IDE
|
||||
Controller chips simply by appropriate configuration of BSP. Drivers for a
|
||||
particular IDE Controller chips locate in the following directories: drivers
|
||||
for well-known IDE Controller chips locate into
|
||||
@code{$RTEMS_SRC_ROOT/c/src/libchip/ide}, drivers for IDE Controller chips
|
||||
integrated with CPU locate into
|
||||
@code{$RTEMS_SRC_ROOT/c/src/lib/libcpu/myCPU} and
|
||||
drivers for custom IDE Controller chips (for example, implemented on FPGA)
|
||||
locate into @code{$RTEMS_SRC_ROOT/c/src/lib/libbsp/myBSP}.
|
||||
There is a README file in these directories for each supported
|
||||
IDE Controller chip. Each of these README explains how to configure a BSP
|
||||
for that particular IDE Controller chip.
|
||||
|
||||
@section Initialization
|
||||
|
||||
IDE Controller chips used by a BSP are statically configured into
|
||||
@code{IDE_Controller_Table}. The @code{ide_controller_initialize} routine is
|
||||
responsible for initialization of all configured IDE controller chips.
|
||||
Initialization order of the chips based on the order the chips are defined in
|
||||
the @code{IDE_Controller_Table}.
|
||||
|
||||
The following actions are performed by the IDE Controller driver
|
||||
initialization routine:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver ide_controller_initialize(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor_arg,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
for each IDE Controller chip configured in IDE_Controller_Table
|
||||
if (BSP dependent probe(if exists) AND device probe for this IDE chip
|
||||
indicates it is present)
|
||||
perform initialization of the particular chip
|
||||
register device with configured name for this chip
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Read IDE Controller Register
|
||||
|
||||
The @code{ide_controller_read_register} routine reads the content of the IDE
|
||||
Controller chip register. IDE Controller chip is selected via the minor
|
||||
number. This routine is not allowed to be called from an application.
|
||||
|
||||
@example
|
||||
@group
|
||||
void ide_controller_read_register(rtems_device_minor_number minor,
|
||||
unsigned32 reg, unsigned32 *value)
|
||||
@{
|
||||
get IDE Controller chip configuration information from
|
||||
IDE_Controller_Table by minor number
|
||||
|
||||
invoke read register routine for the chip
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Write IDE Controller Register
|
||||
|
||||
The @code{ide_controller_write_register} routine writes IDE Controller chip
|
||||
register with specified value. IDE Controller chip is selected via the minor
|
||||
number. This routine is not allowed to be called from an application.
|
||||
|
||||
@example
|
||||
@group
|
||||
void ide_controller_write_register(rtems_device_minor_number minor,
|
||||
unsigned32 reg, unsigned32 value)
|
||||
@{
|
||||
get IDE Controller chip configuration information from
|
||||
IDE_Controller_Table by minor number
|
||||
|
||||
invoke write register routine for the chip
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Read Data Block Through IDE Controller Data Register
|
||||
|
||||
The @code{ide_controller_read_data_block} provides multiple consequent read
|
||||
of the IDE Controller Data Register. IDE Controller chip is selected via the
|
||||
minor number. The same functionality may be achieved via separate multiple
|
||||
calls of @code{ide_controller_read_register} routine but
|
||||
@code{ide_controller_read_data_block} allows to escape functions call
|
||||
overhead. This routine is not allowed to be called from an application.
|
||||
|
||||
@example
|
||||
@group
|
||||
void ide_controller_read_data_block(
|
||||
rtems_device_minor_number minor,
|
||||
unsigned16 block_size,
|
||||
blkdev_sg_buffer *bufs,
|
||||
uint32_t *cbuf,
|
||||
uint32_t *pos
|
||||
)
|
||||
@{
|
||||
get IDE Controller chip configuration information from
|
||||
IDE_Controller_Table by minor number
|
||||
|
||||
invoke read data block routine for the chip
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Write Data Block Through IDE Controller Data Register
|
||||
|
||||
The @code{ide_controller_write_data_block} provides multiple consequent write
|
||||
into the IDE Controller Data Register. IDE Controller chip is selected via the
|
||||
minor number. The same functionality may be achieved via separate multiple
|
||||
calls of @code{ide_controller_write_register} routine but
|
||||
@code{ide_controller_write_data_block} allows to escape functions call
|
||||
overhead. This routine is not allowed to be called from an application.
|
||||
|
||||
@example
|
||||
@group
|
||||
void ide_controller_write_data_block(
|
||||
rtems_device_minor_number minor,
|
||||
unsigned16 block_size,
|
||||
blkdev_sg_buffer *bufs,
|
||||
uint32_t *cbuf,
|
||||
uint32_t *pos
|
||||
)
|
||||
@{
|
||||
get IDE Controller chip configuration information from
|
||||
IDE_Controller_Table by minor number
|
||||
|
||||
invoke write data block routine for the chip
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
@@ -1,425 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2008.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Initialization Code
|
||||
|
||||
@section Introduction
|
||||
|
||||
The initialization code is the first piece of code executed when there's a
|
||||
reset/reboot. Its purpose is to initialize the board for the application.
|
||||
This chapter contains a narrative description of the initialization
|
||||
process followed by a description of each of the files and routines
|
||||
commonly found in the BSP related to initialization. The remainder of
|
||||
this chapter covers special issues which require attention such
|
||||
as interrupt vector table and chip select initialization.
|
||||
|
||||
Most of the examples in this chapter will be based on the SPARC/ERC32 and
|
||||
m68k/gen68340 BSP initialization code. Like most BSPs, the initialization
|
||||
for these BSP is divided into two subdirectories under the BSP source
|
||||
directory. The BSP source code for these BSPs is in the following
|
||||
directories:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/m68k/gen68340
|
||||
c/src/lib/libbsp/sparc/erc32
|
||||
@end example
|
||||
|
||||
Both BSPs contain startup code written in assembly language and C.
|
||||
The gen68340 BSP has its early initialization start code in the
|
||||
@code{start340} subdirectory and its C startup code in the @code{startup}
|
||||
directory. In the @code{start340} directory are two source files.
|
||||
The file @code{startfor340only.s} is the simpler of these files as it only
|
||||
has initialization code for a MC68340 board. The file @code{start340.s}
|
||||
contains initialization for a 68349 based board as well.
|
||||
|
||||
Similarly, the ERC32 BSP has startup code written in assembly language
|
||||
and C. However, this BSP shares this code with other SPARC BSPs.
|
||||
Thus the @code{Makefile.am} explicitly references the following files
|
||||
for this functionality.
|
||||
|
||||
@example
|
||||
../../sparc/shared/start.S
|
||||
@end example
|
||||
|
||||
@b{NOTE:} In most BSPs, the directory named @code{start340} in the
|
||||
gen68340 BSP would be simply named @code{start} or start followed by a
|
||||
BSP designation.
|
||||
|
||||
@section Required Global Variables
|
||||
|
||||
Although not strictly part of initialization, there are a few global
|
||||
variables assumed to exist by reusable device drivers. These global
|
||||
variables should only defined by the BSP when using one of these device
|
||||
drivers.
|
||||
|
||||
The BSP author probably should be aware of the @code{Configuration}
|
||||
Table structure generated by @code{<rtems/confdefs.h>} during debug but
|
||||
should not explicitly reference it in the source code. There are helper
|
||||
routines provided by RTEMS to access individual fields.
|
||||
|
||||
In older RTEMS versions, the BSP included a number of required global
|
||||
variables. We have made every attempt to eliminate these in the interest
|
||||
of simplicity.
|
||||
|
||||
@section Board Initialization
|
||||
|
||||
This section describes the steps an application goes through from the
|
||||
time the first BSP code is executed until the first application task
|
||||
executes. The following figure illustrates the program flow during
|
||||
this sequence:
|
||||
|
||||
@ifset use-ascii
|
||||
IMAGE NOT AVAILABLE IN ASCII VERSION
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@image{BSPInitFlowchart-49,6in,,Initialization Sequence,.png}
|
||||
@c @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<center>
|
||||
<IMG SRC="BSPInitFlowchart-49.png" WIDTH=800 ALT="Initialization Sequence">
|
||||
</center>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
The above figure illustrates the flow from assembly language start code
|
||||
to the shared @code{bootcard.c} framework then through the C Library,
|
||||
RTEMS, device driver initialization phases, and the context switch
|
||||
to the first application task. After this, the application executes
|
||||
until it calls @code{exit}, @code{rtems_shutdown_executive}, or some
|
||||
other normal termination initiating routine and a fatal system state is
|
||||
reached. The optional @code{bsp_fatal_extension} initial extension can perform
|
||||
BSP specific system termination.
|
||||
|
||||
The routines invoked during this will be discussed and their location
|
||||
in the RTEMS source tree pointed out as we discuss each.
|
||||
|
||||
@subsection Start Code - Assembly Language Initialization
|
||||
|
||||
The assembly language code in the directory @code{start} is the first part
|
||||
of the application to execute. It is responsible for initializing the
|
||||
processor and board enough to execute the rest of the BSP. This includes:
|
||||
|
||||
@itemize @bullet
|
||||
@item initializing the stack
|
||||
@item zeroing out the uninitialized data section @code{.bss}
|
||||
@item disabling external interrupts
|
||||
@item copy the initialized data from ROM to RAM
|
||||
@end itemize
|
||||
|
||||
The general rule of thumb is that the start code in assembly should
|
||||
do the minimum necessary to allow C code to execute to complete the
|
||||
initialization sequence.
|
||||
|
||||
The initial assembly language start code completes its execution by
|
||||
invoking the shared routine @code{boot_card()}.
|
||||
|
||||
The label (symbolic name) associated with the starting address of the
|
||||
program is typically called @code{start}. The start object file is the
|
||||
first object file linked into the program image so it is ensured that
|
||||
the start code is at offset 0 in the @code{.text} section. It is the
|
||||
responsibility of the linker script in conjunction with the compiler
|
||||
specifications file to put the start code in the correct location in
|
||||
the application image.
|
||||
|
||||
@subsection boot_card() - Boot the Card
|
||||
|
||||
The @code{boot_card()} is the first C code invoked. This file is the
|
||||
core component in the RTEMS BSP Initialization Framework and provides
|
||||
the proper sequencing of initialization steps for the BSP, RTEMS and
|
||||
device drivers. All BSPs use the same shared version of @code{boot_card()}
|
||||
which is located in the following file:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/shared/bootcard.c
|
||||
@end example
|
||||
|
||||
The @code{boot_card()} routine performs the following functions:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item It disables processor interrupts.
|
||||
|
||||
@item It sets the command line argument variables
|
||||
for later use by the application.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_start()} which is
|
||||
written in C and thus able to perform more advanced initialization.
|
||||
Often MMU and bus initialization occurs here.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_work_area_initialize()}
|
||||
which is supposed to initialize the RTEMS Workspace and the C Program Heap.
|
||||
Usually the default implementation in
|
||||
@code{c/src/lib/libbsp/shared/bspgetworkarea.c} should be sufficient. Custom
|
||||
implementations can use @code{bsp_work_area_initialize_default()} or
|
||||
@code{bsp_work_area_initialize_with_table()} available as inline functions from
|
||||
@code{#include <bsp/bootcard.h>}.
|
||||
|
||||
@item It invokes the RTEMS directive
|
||||
@code{rtems_initialize_data_structures()} to initialize the RTEMS
|
||||
executive to a state where objects can be created but tasking is not
|
||||
enabled.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_libc_init()} to initialize
|
||||
the C Library. Usually the default implementation in
|
||||
@code{c/src/lib/libbsp/shared/bsplibc.c} should be sufficient.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_pretasking_hook}. On
|
||||
most BSPs which utilize the framework, this routine does nothing.
|
||||
|
||||
@item If @code{RTEMS_DEBUG} is enabled, then the RTEMS debug mask level
|
||||
is inialized appropriately.
|
||||
|
||||
@item It invokes the RTEMS directive
|
||||
@code{rtems_initialize_before_drivers()} to initialize the MPCI Server
|
||||
thread in a multiprocessor configuration and execute API specific
|
||||
extensions.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_predriver_hook}. For
|
||||
most BSPs, the implementation of this routine does nothing.
|
||||
|
||||
@item It invokes the RTEMS directive
|
||||
@code{rtems_initialize_device_drivers()} to initialize the statically
|
||||
configured set of device drivers in the order they were specified in
|
||||
the Configuration Table.
|
||||
|
||||
@item It invokes the BSP specific routine @code{bsp_postdriver_hook}. For
|
||||
most BSPs, the implementation of this routine does nothing. However, some
|
||||
BSPs use this hook and perform some initialization which must be done at
|
||||
this point in the initialization sequence. This is the last opportunity
|
||||
for the BSP to insert BSP specific code into the initialization sequence.
|
||||
|
||||
@item It invokes the RTEMS directive
|
||||
@code{rtems_initialize_start_multitasking()}
|
||||
which initiates multitasking and performs a context switch to the
|
||||
first user application task and may enable interrupts as a side-effect of
|
||||
that context switch. The context switch saves the executing context. The
|
||||
application runs now. The directive rtems_shutdown_executive() will return
|
||||
to the saved context. The exit() function will use this directive.
|
||||
|
||||
After a return to the saved context a fatal system state is reached. The
|
||||
fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
|
||||
passed to rtems_shutdown_executive().
|
||||
|
||||
The enabling of interrupts during the first context switch is often the source
|
||||
for fatal errors during BSP development because the BSP did not clear and/or
|
||||
disable all interrupt sources and a spurious interrupt will occur.
|
||||
|
||||
When in the context of the first task but before its body has been
|
||||
entered, any C++ Global Constructors will be invoked.
|
||||
|
||||
@end itemize
|
||||
|
||||
That's it. We just went through the entire sequence.
|
||||
|
||||
@subsection bsp_start() - BSP Specific Initialization
|
||||
|
||||
This is the first BSP specific C routine to execute during system
|
||||
initialization. This routine often performs required fundamental
|
||||
hardware initialization such as setting bus controller registers
|
||||
that do not have a direct impact on whether or not C code can execute.
|
||||
The source code for this routine is usually found in the following
|
||||
file:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
|
||||
@end example
|
||||
|
||||
On older BSPs not using @code{boot_card()}'s support for allocating memory
|
||||
to the C Program Heap and RTEMS Workspace, one of the most important
|
||||
functions performed by this routine is determining where the RTEMS
|
||||
Workspace is to be located in memory. All RTEMS objects and task stacks
|
||||
will be allocated from this Workspace. The RTEMS Workspace is distinct
|
||||
from the application heap used for @code{malloc()}. Many BSPs place
|
||||
the RTEMS Workspace area at the end of RAM although this is certainly
|
||||
not a requirement.
|
||||
|
||||
After completing execution, this routine returns to the @code{boot_card()}
|
||||
routine.
|
||||
|
||||
@subsection RTEMS Pretasking Callback
|
||||
|
||||
The method @code{bsp_pretasking_hook()} is the BSP specific routine invoked
|
||||
once RTEMS API initialization is complete but before interrupts and tasking are
|
||||
enabled. The idle thread exists at this time. The pretasking hook is optional
|
||||
and the user may use the shared version.
|
||||
|
||||
The @code{bsp_pretasking_hook()} routine is the appropriate place to initialize
|
||||
any BSP specific support components which depend on the RTEMS APIs.
|
||||
|
||||
@subsection RTEMS Predriver Callback
|
||||
|
||||
The @code{bsp_predriver_hook()} method is the BSP specific routine that
|
||||
is is invoked immediately before the the device drivers and MPCI are
|
||||
initialized. RTEMS initialization is complete but interrupts and tasking
|
||||
are disabled.
|
||||
|
||||
The BSP may use the shared version of this routine which is empty.
|
||||
Most BSPs do not provide a specific implementation of this callback.
|
||||
|
||||
@subsection Device Driver Initialization
|
||||
|
||||
At this point in the initialization sequence, the initialization
|
||||
routines for all of the device drivers specified in the Device
|
||||
Driver Table are invoked. The initialization routines are invoked
|
||||
in the order they appear in the Device Driver Table.
|
||||
|
||||
The Driver Address Table is part of the RTEMS Configuration Table. It
|
||||
defines device drivers entry points (initialization, open, close, read,
|
||||
write, and control). For more information about this table, please
|
||||
refer to the @b{Configuring a System} chapter in the
|
||||
@b{RTEMS Application C User's Guide}.
|
||||
|
||||
The RTEMS initialization procedure calls the initialization function for
|
||||
every driver defined in the RTEMS Configuration Table (this allows
|
||||
one to include only the drivers needed by the application).
|
||||
|
||||
All these primitives have a major and a minor number as arguments:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item the major number refers to the driver type,
|
||||
|
||||
@item the minor number is used to control two peripherals with the same
|
||||
driver (for instance, we define only one major number for the serial
|
||||
driver, but two minor numbers for channel A and B if there are two
|
||||
channels in the UART).
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection RTEMS Postdriver Callback
|
||||
|
||||
The @code{bsp_postdriver_hook()} BSP specific routine is invoked
|
||||
immediately after the the device drivers and MPCI are initialized.
|
||||
Interrupts and tasking are disabled.
|
||||
|
||||
Most BSPs use the shared implementation of this routine which is responsible for opening the device @code{/dev/console} for standard input, output and error if the application has configured the Console Device Driver. This file is located at:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/shared/bsppost.c
|
||||
@end example
|
||||
|
||||
@section The Interrupt Vector Table
|
||||
|
||||
The Interrupt Vector Table is called different things on different
|
||||
processor families but the basic functionality is the same. Each
|
||||
entry in the Table corresponds to the handler routine for a particular
|
||||
interrupt source. When an interrupt from that source occurs, the
|
||||
specified handler routine is invoked. Some context information is
|
||||
saved by the processor automatically when this happens. RTEMS saves
|
||||
enough context information so that an interrupt service routine
|
||||
can be implemented in a high level language.
|
||||
|
||||
On some processors, the Interrupt Vector Table is at a fixed address. If
|
||||
this address is in RAM, then usually the BSP only has to initialize
|
||||
it to contain pointers to default handlers. If the table is in ROM,
|
||||
then the application developer will have to take special steps to
|
||||
fill in the table.
|
||||
|
||||
If the base address of the Interrupt Vector Table can be dynamically
|
||||
changed to an arbitrary address, then the RTEMS port to that processor
|
||||
family will usually allocate its own table and install it. For example,
|
||||
on some members of the Motorola MC68xxx family, the Vector Base Register
|
||||
(@code{vbr}) contains this base address.
|
||||
|
||||
@subsection Interrupt Vector Table on the gen68340 BSP
|
||||
|
||||
The gen68340 BSP provides a default Interrupt Vector Table in the
|
||||
file @code{$BSP_ROOT/start340/start340.s}. After the @code{entry}
|
||||
label is the definition of space reserved for the table of
|
||||
interrupts vectors. This space is assigned the symbolic name
|
||||
of @code{__uhoh} in the @code{gen68340} BSP.
|
||||
|
||||
At @code{__uhoh} label is the default interrupt handler routine. This
|
||||
routine is only called when an unexpected interrupts is raised. One can
|
||||
add their own routine there (in that case there's a call to a routine -
|
||||
$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
|
||||
interrupt and the contents of the registers, stack, etc.), but this should
|
||||
not return.
|
||||
|
||||
@section Chip Select Initialization
|
||||
|
||||
When the microprocessor accesses a memory area, address decoding is
|
||||
handled by an address decoder, so that the microprocessor knows which
|
||||
memory chip(s) to access. The following figure illustrates this:
|
||||
|
||||
@example
|
||||
@group
|
||||
+-------------------+
|
||||
------------| |
|
||||
------------| |------------
|
||||
------------| Address |------------
|
||||
------------| Decoder |------------
|
||||
------------| |------------
|
||||
------------| |
|
||||
+-------------------+
|
||||
CPU Bus Chip Select
|
||||
@end group
|
||||
@end example
|
||||
|
||||
|
||||
The Chip Select registers must be programmed such that they match
|
||||
the @code{linkcmds} settings. In the gen68340 BSP, ROM and RAM
|
||||
addresses can be found in both the @code{linkcmds} and initialization
|
||||
code, but this is not a great way to do this. It is better to
|
||||
define addresses in the linker script.
|
||||
|
||||
@section Integrated Processor Registers Initialization
|
||||
|
||||
The CPUs used in many embedded systems are highly complex devices
|
||||
with multiple peripherals on the CPU itself. For these devices,
|
||||
there are always some specific integrated processor registers
|
||||
that must be initialized. Refer to the processors' manuals for
|
||||
details on these registers and be VERY careful programming them.
|
||||
|
||||
@section Data Section Recopy
|
||||
|
||||
The next initialization part can be found in
|
||||
@code{$BSP340_ROOT/start340/init68340.c}. First the Interrupt
|
||||
Vector Table is copied into RAM, then the data section recopy is initiated
|
||||
(_CopyDataClearBSSAndStart in @code{$BSP340_ROOT/start340/startfor340only.s}).
|
||||
|
||||
This code performs the following actions:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item copies the .data section from ROM to its location reserved in RAM
|
||||
(see @ref{Linker Script Initialized Data} for more details about this copy),
|
||||
|
||||
@item clear @code{.bss} section (all the non-initialized
|
||||
data will take value 0).
|
||||
|
||||
@end itemize
|
||||
|
||||
@section The RTEMS Configuration Table
|
||||
|
||||
The RTEMS configuration table contains the maximum number of objects RTEMS
|
||||
can handle during the application (e.g. maximum number of tasks,
|
||||
semaphores, etc.). It's used to allocate the size for the RTEMS inner data
|
||||
structures.
|
||||
|
||||
The RTEMS configuration table is application dependent, which means that
|
||||
one has to provide one per application. It is usually defined by defining
|
||||
macros and including the header file @code{<rtems/confdefs.h>}. In simple
|
||||
applications such as the tests provided with RTEMS, it is commonly found
|
||||
in the main module of the application. For more complex applications,
|
||||
it may be in a file by itself.
|
||||
|
||||
The header file @code{<rtems/confdefs.h>} defines a constant table
|
||||
named @code{Configuration}. With RTEMS 4.8 and older, it was accepted
|
||||
practice for the BSP to copy this table into a modifiable copy named
|
||||
@code{BSP_Configuration}. This copy of the table was modified to define
|
||||
the base address of the RTEMS Executive Workspace as well as to reflect
|
||||
any BSP and device driver requirements not automatically handled by the
|
||||
application. In 4.9 and newer, we have eliminated the BSP copies of the
|
||||
configuration tables and are making efforts to make the configuration
|
||||
information generated by @code{<rtems/confdefs.h>} constant and read only.
|
||||
|
||||
For more information on the RTEMS Configuration Table, refer to the
|
||||
@b{RTEMS Application C User's Guide}.
|
||||
|
||||
@@ -1,73 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Introduction
|
||||
|
||||
Before reading this documentation, it is strongly advised to read the
|
||||
RTEMS Development Environment Guide to get acquainted with the RTEMS
|
||||
directory structure. This document describes how to do a RTEMS Board
|
||||
Support Package, i.e. how to port RTEMS on a new target board. Discussions
|
||||
are provided for the following topics:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item RTEMS Board Support Package Organization
|
||||
|
||||
@item Makefiles and the Linker Command Script
|
||||
|
||||
@item Board Initialization Sequence
|
||||
|
||||
@item Device Drivers Including:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Console Driver
|
||||
|
||||
@item Clock Driver
|
||||
|
||||
@item Timer Driver
|
||||
|
||||
@item Real-Time Clock Driver
|
||||
|
||||
@item Non-Volatile Memory Driver
|
||||
|
||||
@item Networking Driver
|
||||
|
||||
@item Shared Memory Support Driver
|
||||
|
||||
@item Analog Driver
|
||||
|
||||
@item Discrete Driver
|
||||
|
||||
@end itemize
|
||||
|
||||
@end itemize
|
||||
|
||||
The original version of this manual was written by Geoffroy Montel
|
||||
<g_montel@@yahoo.com>. When he started development of the gen68340
|
||||
BSP, this manual did not exist. He wrote the initial version of
|
||||
this manual as the result of his experiences. At that time, this
|
||||
document was viewed internally as the most important "missing manual"
|
||||
in the RTEMS documentation set.
|
||||
|
||||
The gen68340 BSP is a good example of the life of an RTEMS BSP. It is
|
||||
based upon a part not recommended for new designs and none of the core RTEMS
|
||||
Project team members have one of these boards. Thus we are unlikely to
|
||||
perform major updates on this BSP. So as long as it compiles and links all
|
||||
tests, it will be available.
|
||||
|
||||
The RTEMS Project team members are always trying to identify common
|
||||
code across BSPs and refactoring the code into shared routines.
|
||||
As part of this effort, the we will enhance the common BSP Framework.
|
||||
Not surprisingly, not every BSP takes advantage of every feature in
|
||||
the framework. The gen68340 does not take advantage of as many features
|
||||
as the ERC32 BSP does. So in many ways, the ERC32 is a better example
|
||||
BSP at this point. But even the ERC32 BSP does not include examples
|
||||
of every driver template and framework available to the BSP author.
|
||||
So in this guide we will try to point out good examples from other BSPs.
|
||||
|
||||
Our goal is for you to be able to reuse as much code as possible and
|
||||
write as little board specific code as possible.
|
||||
|
||||
@@ -1,429 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Linker Script
|
||||
|
||||
@section What is a "linkcmds" file?
|
||||
|
||||
The @code{linkcmds} file is a script which is passed to the linker at linking
|
||||
time. This file describes the memory configuration of the board as needed
|
||||
to link the program. Specifically it specifies where the code and data
|
||||
for the application will reside in memory.
|
||||
|
||||
The format of the linker script is defined by the GNU Loader @code{ld}
|
||||
which is included as a component of the GNU Binary Utilities. If you
|
||||
are using GNU/Linux, then you probably have the documentation installed
|
||||
already and are using these same tools configured for @b{native} use.
|
||||
Please visit the Binutils project @uref{http://sourceware.org/binutils/}
|
||||
if you need more information.
|
||||
|
||||
@section Program Sections
|
||||
|
||||
An embedded systems programmer must be much more aware of the
|
||||
placement of their executable image in memory than the average
|
||||
applications programmer. A program destined to be embedded as well
|
||||
as the target system have some specific properties that must be
|
||||
taken into account. Embedded machines often mean average performances
|
||||
and small memory usage. It is the memory usage that concerns us
|
||||
when examining the linker command file.
|
||||
|
||||
Two types of memories have to be distinguished:
|
||||
|
||||
@itemize @bullet
|
||||
@item RAM - volatile offering read and write access
|
||||
@item ROM - non-volatile but read only
|
||||
@end itemize
|
||||
|
||||
Even though RAM and ROM can be found in every personal computer,
|
||||
one generally doesn't care about them. In a personal computer,
|
||||
a program is nearly always stored on disk and executed in RAM. Things
|
||||
are a bit different for embedded targets: the target will execute the
|
||||
program each time it is rebooted or switched on. The application
|
||||
program is stored in non-volatile memory such as ROM, PROM, EEPROM,
|
||||
or Flash. On the other hand, data processing occurs in RAM.
|
||||
|
||||
This leads us to the structure of an embedded program. In rough terms,
|
||||
an embedded program is made of sections. It is the responsibility of
|
||||
the application programmer to place these sections in the appropriate
|
||||
place in target memory. To make this clearer, if using the COFF
|
||||
object file format on the Motorola m68k family of microprocessors,
|
||||
the following sections will be present:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @b{code (@code{.text}) section}:
|
||||
is the program's code and it should not be modified.
|
||||
This section may be placed in ROM.
|
||||
|
||||
@item @b{non-initialized data (@code{.bss}) section}:
|
||||
holds uninitialized variables of the program. It can stay in RAM.
|
||||
|
||||
@item @b{initialized data (@code{.data}) section}:
|
||||
holds the initialized program data which may be modified during the
|
||||
program's life. This means they have to be in RAM.
|
||||
On the other hand, these variables must be set to predefined values, and
|
||||
those predefined values have to be stored in ROM.
|
||||
|
||||
@end itemize
|
||||
|
||||
@b{NOTE:} Many programs and support libraries unknowingly assume that the
|
||||
@code{.bss} section and, possibly, the application heap are initialized
|
||||
to zero at program start. This is not required by the ISO/ANSI C Standard
|
||||
but is such a common requirement that most BSPs do this.
|
||||
|
||||
That brings us up to the notion of the image of an executable: it consists
|
||||
of the set of the sections that together constitute the application.
|
||||
|
||||
@section Image of an Executable
|
||||
|
||||
As a program executable has many sections (note that the user can define
|
||||
their own, and that compilers define theirs without any notice), one has to
|
||||
specify the placement of each section as well as the type of memory
|
||||
(RAM or ROM) the sections will be placed into.
|
||||
For instance, a program compiled for a Personal Computer will see all the
|
||||
sections to go to RAM, while a program destined to be embedded will see
|
||||
some of his sections going into the ROM.
|
||||
|
||||
The connection between a section and where that section is loaded into
|
||||
memory is made at link time. One has to let the linker know where
|
||||
the different sections are to be placed once they are in memory.
|
||||
|
||||
The following example shows a simple layout of program sections. With
|
||||
some object formats, there are many more sections but the basic
|
||||
layout is conceptually similar.
|
||||
|
||||
@example
|
||||
@group
|
||||
+-----------------+
|
||||
| .text | RAM or ROM
|
||||
+-----------------+
|
||||
| .data | RAM
|
||||
+-----------------+
|
||||
| .bss | RAM
|
||||
+-----------------+
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Example Linker Command Script
|
||||
|
||||
The GNU linker has a command language to specify the image format. This
|
||||
command language can be quite complicated but most of what is required
|
||||
can be learned by careful examination of a well-documented example.
|
||||
The following is a heavily commented version of the linker script
|
||||
used with the the @code{gen68340} BSP This file can be found at
|
||||
$BSP340_ROOT/startup/linkcmds.
|
||||
|
||||
@example
|
||||
/*
|
||||
* Specify that the output is to be coff-m68k regardless of what the
|
||||
* native object format is.
|
||||
*/
|
||||
|
||||
OUTPUT_FORMAT(coff-m68k)
|
||||
|
||||
/*
|
||||
* Set the amount of RAM on the target board.
|
||||
*
|
||||
* NOTE: The default may be overridden by passing an argument to ld.
|
||||
*/
|
||||
|
||||
RamSize = DEFINED(RamSize) ? RamSize : 4M;
|
||||
|
||||
/*
|
||||
* Set the amount of RAM to be used for the application heap. Objects
|
||||
* allocated using malloc() come from this area. Having a tight heap
|
||||
* size is somewhat difficult and multiple attempts to squeeze it may
|
||||
* be needed reducing memory usage is important. If all objects are
|
||||
* allocated from the heap at system initialization time, this eases
|
||||
* the sizing of the application heap.
|
||||
*
|
||||
* NOTE 1: The default may be overridden by passing an argument to ld.
|
||||
*
|
||||
* NOTE 2: The TCP/IP stack requires additional memory in the Heap.
|
||||
*
|
||||
* NOTE 3: The GNAT/RTEMS run-time requires additional memory in
|
||||
* the Heap.
|
||||
*/
|
||||
|
||||
HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000;
|
||||
|
||||
/*
|
||||
* Set the size of the starting stack used during BSP initialization
|
||||
* until first task switch. After that point, task stacks allocated
|
||||
* by RTEMS are used.
|
||||
*
|
||||
* NOTE: The default may be overridden by passing an argument to ld.
|
||||
*/
|
||||
|
||||
StackSize = DEFINED(StackSize) ? StackSize : 0x1000;
|
||||
|
||||
/*
|
||||
* Starting addresses and length of RAM and ROM.
|
||||
*
|
||||
* The addresses must be valid addresses on the board. The
|
||||
* Chip Selects should be initialized such that the code addresses
|
||||
* are valid.
|
||||
*/
|
||||
|
||||
MEMORY @{
|
||||
ram : ORIGIN = 0x10000000, LENGTH = 4M
|
||||
rom : ORIGIN = 0x01000000, LENGTH = 4M
|
||||
@}
|
||||
|
||||
/*
|
||||
* This is for the network driver. See the Networking documentation
|
||||
* for more details.
|
||||
*/
|
||||
|
||||
ETHERNET_ADDRESS =
|
||||
DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12;
|
||||
|
||||
/*
|
||||
* The following defines the order in which the sections should go.
|
||||
* It also defines a number of variables which can be used by the
|
||||
* application program.
|
||||
*
|
||||
* NOTE: Each variable appears with 1 or 2 leading underscores to
|
||||
* ensure that the variable is accessible from C code with a
|
||||
* single underscore. Some object formats automatically add
|
||||
* a leading underscore to all C global symbols.
|
||||
*/
|
||||
|
||||
SECTIONS @{
|
||||
|
||||
/*
|
||||
* Make the RomBase variable available to the application.
|
||||
*/
|
||||
|
||||
_RamSize = RamSize;
|
||||
__RamSize = RamSize;
|
||||
|
||||
/*
|
||||
* Boot PROM - Set the RomBase variable to the start of the ROM.
|
||||
*/
|
||||
|
||||
rom : @{
|
||||
_RomBase = .;
|
||||
__RomBase = .;
|
||||
@} >rom
|
||||
|
||||
/*
|
||||
* Dynamic RAM - set the RamBase variable to the start of the RAM.
|
||||
*/
|
||||
|
||||
ram : @{
|
||||
_RamBase = .;
|
||||
__RamBase = .;
|
||||
@} >ram
|
||||
|
||||
/*
|
||||
* Text (code) goes into ROM
|
||||
*/
|
||||
|
||||
.text : @{
|
||||
/*
|
||||
* Create a symbol for each object (.o).
|
||||
*/
|
||||
|
||||
CREATE_OBJECT_SYMBOLS
|
||||
|
||||
/*
|
||||
* Put all the object files code sections here.
|
||||
*/
|
||||
|
||||
*(.text)
|
||||
|
||||
. = ALIGN (16); /* go to a 16-byte boundary */
|
||||
|
||||
/*
|
||||
* C++ constructors and destructors
|
||||
*
|
||||
* NOTE: See the CROSSGCC mailing-list FAQ for
|
||||
* more details about the "[......]".
|
||||
*/
|
||||
|
||||
__CTOR_LIST__ = .;
|
||||
[......]
|
||||
__DTOR_END__ = .;
|
||||
|
||||
/*
|
||||
* Declares where the .text section ends.
|
||||
*/
|
||||
|
||||
etext = .;
|
||||
_etext = .;
|
||||
@} >rom
|
||||
|
||||
/*
|
||||
* Exception Handler Frame section
|
||||
*/
|
||||
|
||||
.eh_fram : @{
|
||||
. = ALIGN (16);
|
||||
*(.eh_fram)
|
||||
@} >ram
|
||||
|
||||
/*
|
||||
* GCC Exception section
|
||||
*/
|
||||
|
||||
.gcc_exc : @{
|
||||
. = ALIGN (16);
|
||||
*(.gcc_exc)
|
||||
@} >ram
|
||||
|
||||
/*
|
||||
* Special variable to let application get to the dual-ported
|
||||
* memory.
|
||||
*/
|
||||
|
||||
dpram : @{
|
||||
m340 = .;
|
||||
_m340 = .;
|
||||
. += (8 * 1024);
|
||||
@} >ram
|
||||
|
||||
/*
|
||||
* Initialized Data section goes in RAM
|
||||
*/
|
||||
|
||||
.data : @{
|
||||
copy_start = .;
|
||||
*(.data)
|
||||
|
||||
. = ALIGN (16);
|
||||
_edata = .;
|
||||
copy_end = .;
|
||||
@} >ram
|
||||
|
||||
/*
|
||||
* Uninitialized Data section goes in ROM
|
||||
*/
|
||||
|
||||
.bss : @{
|
||||
/*
|
||||
* M68K specific: Reserve some room for the Vector Table
|
||||
* (256 vectors of 4 bytes).
|
||||
*/
|
||||
|
||||
M68Kvec = .;
|
||||
_M68Kvec = .;
|
||||
. += (256 * 4);
|
||||
|
||||
/*
|
||||
* Start of memory to zero out at initialization time.
|
||||
*/
|
||||
|
||||
clear_start = .;
|
||||
|
||||
/*
|
||||
* Put all the object files uninitialized data sections
|
||||
* here.
|
||||
*/
|
||||
|
||||
*(.bss)
|
||||
|
||||
*(COMMON)
|
||||
|
||||
. = ALIGN (16);
|
||||
_end = .;
|
||||
|
||||
/*
|
||||
* Start of the Application Heap
|
||||
*/
|
||||
|
||||
_HeapStart = .;
|
||||
__HeapStart = .;
|
||||
. += HeapSize;
|
||||
|
||||
/*
|
||||
* The Starting Stack goes after the Application Heap.
|
||||
* M68K stack grows down so start at high address.
|
||||
*/
|
||||
|
||||
. += StackSize;
|
||||
. = ALIGN (16);
|
||||
stack_init = .;
|
||||
|
||||
clear_end = .;
|
||||
|
||||
/*
|
||||
* The RTEMS Executive Workspace goes here. RTEMS
|
||||
* allocates tasks, stacks, semaphores, etc. from this
|
||||
* memory.
|
||||
*/
|
||||
|
||||
_WorkspaceBase = .;
|
||||
__WorkspaceBase = .;
|
||||
@} >ram
|
||||
@}
|
||||
@end example
|
||||
|
||||
@section Initialized Data
|
||||
|
||||
Now there's a problem with the initialized data: the @code{.data} section
|
||||
has to be in RAM as this data may be modified during the program execution.
|
||||
But how will the values be initialized at boot time?
|
||||
|
||||
One approach is to place the entire program image in RAM and reload
|
||||
the image in its entirety each time the program is run. This is fine
|
||||
for use in a debug environment where a high-speed connection is available
|
||||
between the development host computer and the target. But even in this
|
||||
environment, it is cumbersome.
|
||||
|
||||
The solution is to place a copy of the initialized data in a separate
|
||||
area of memory and copy it into the proper location each time the
|
||||
program is started. It is common practice to place a copy of the initialized
|
||||
@code{.data} section at the end of the code (@code{.text}) section
|
||||
in ROM when building a PROM image. The GNU tool @code{objcopy}
|
||||
can be used for this purpose.
|
||||
|
||||
The following figure illustrates the steps a linked program goes through
|
||||
to become a downloadable image.
|
||||
|
||||
@example
|
||||
@group
|
||||
+--------------+ +--------------------+
|
||||
| .data RAM | | .data RAM |
|
||||
+--------------+ +--------------------+
|
||||
| .bss RAM | | .bss RAM |
|
||||
+--------------+ +--------------------+ +----------------+
|
||||
| .text ROM | | .text ROM | | .text |
|
||||
+--------------+ +--------------------+ +----------------+
|
||||
| copy of .data ROM | | copy of .data |
|
||||
+--------------------+ +----------------+
|
||||
|
||||
Step 1 Step 2 Step 3
|
||||
@end group
|
||||
@end example
|
||||
|
||||
In Step 1, the program is linked together using the BSP linker script.
|
||||
|
||||
In Step 2, a copy is made of the @code{.data} section and placed
|
||||
after the @code{.text} section so it can be placed in PROM. This step
|
||||
is done after the linking time. There is an example
|
||||
of doing this in the file $RTEMS_ROOT/make/custom/gen68340.cfg:
|
||||
|
||||
@example
|
||||
# make a PROM image using objcopy
|
||||
m68k-rtems-objcopy \
|
||||
--adjust-section-vma .data= \
|
||||
|
||||
`m68k-rtems-objdump --section-headers \
|
||||
$(basename $@@).exe \
|
||||
| awk '[...]` \
|
||||
$(basename $@@).exe
|
||||
@end example
|
||||
|
||||
NOTE: The address of the "copy of @code{.data} section" is
|
||||
created by extracting the last address in the @code{.text}
|
||||
section with an @code{awk} script. The details of how
|
||||
this is done are not relevant.
|
||||
|
||||
Step 3 shows the final executable image as it logically appears in
|
||||
the target's non-volatile program memory. The board initialization
|
||||
code will copy the ""copy of @code{.data} section" (which are stored in
|
||||
ROM) to their reserved location in RAM.
|
||||
|
||||
@@ -1,218 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2008.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Makefiles
|
||||
|
||||
This chapter discusses the Makefiles associated with a BSP. It does not
|
||||
describe the process of configuring, building, and installing RTEMS.
|
||||
This chapter will not provide detailed information about this process.
|
||||
Nonetheless, it is important to remember that the general process consists
|
||||
of four phases as shown here:
|
||||
|
||||
@ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
@itemize @bullet
|
||||
@item bootstrap
|
||||
@item configure
|
||||
@item build
|
||||
@item install
|
||||
@end itemize
|
||||
@end group
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@image{Developer-User-Timeline,6in,,Developer User Timeline,.png}
|
||||
@c @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<center>
|
||||
<IMG SRC="Developer-User-Timeline.png" WIDTH=800 ALT="Developer User Timeline">
|
||||
</center>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
|
||||
During the bootstrap phase, you are using the @code{configure.ac} and
|
||||
@code{Makefile.am} files as input to GNU autoconf and automake to
|
||||
generate a variety of files. This is done by running the @code{bootstrap}
|
||||
script found at the top of the RTEMS source tree.
|
||||
|
||||
During the configure phase, a number of files are generated. These
|
||||
generated files are tailored for the specific host/target combination
|
||||
by the configure script. This set of files includes the Makefiles used
|
||||
to actually compile and install RTEMS.
|
||||
|
||||
During the build phase, the source files are compiled into object files
|
||||
and libraries are built.
|
||||
|
||||
During the install phase, the libraries, header files, and other support
|
||||
files are copied to the BSP specific installation point. After installation
|
||||
is successfully completed, the files generated by the configure and build
|
||||
phases may be removed.
|
||||
|
||||
@section Makefiles Used During The BSP Building Process
|
||||
|
||||
RTEMS uses the @b{GNU automake} and @b{GNU autoconf} automatic
|
||||
configuration package. Consequently, there are a number of
|
||||
automatically generated files in each directory in the RTEMS
|
||||
source tree. The @code{bootstrap} script found in the top level
|
||||
directory of the RTEMS source tree is executed to produce the
|
||||
automatically generated files. That script must be run from
|
||||
a directory with a @code{configure.ac} file in it. The @code{bootstrap}
|
||||
command is usually invoked in one of the following manners:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{bootstrap} to regenerate all files that are generated by
|
||||
autoconf and automake.
|
||||
@item @code{bootstrap -c} to remove all files generated by autoconf and
|
||||
automake.
|
||||
@item @code{bootstrap -p} to regenerate @code{preinstall.am} files.
|
||||
@end itemize
|
||||
|
||||
There is a file named @code{Makefile.am} in each directory of
|
||||
a BSP. This file is used by @b{automake} to produce the file named
|
||||
@code{Makefile.in} which is also found in each directory of a BSP.
|
||||
When modifying a @code{Makefile.am}, you can probably find examples of
|
||||
anything you need to do in one of the BSPs.
|
||||
|
||||
|
||||
The configure process specializes the @code{Makefile.in} files at the time that RTEMS
|
||||
is configured for a specific development host and target. Makefiles
|
||||
are automatically generated from the @code{Makefile.in} files. It is
|
||||
necessary for the BSP developer to provide the @code{Makefile.am}
|
||||
files and generate the @code{Makefile.in} files. Most of the
|
||||
time, it is possible to copy the @code{Makefile.am} from another
|
||||
similar directory and edit it.
|
||||
|
||||
The @code{Makefile} files generated are processed when configuring
|
||||
and building RTEMS for a given BSP.
|
||||
|
||||
The BSP developer is responsible for generating @code{Makefile.am}
|
||||
files which properly build all the files associated with their BSP.
|
||||
Most BSPs will only have a single @code{Makefile.am} which details
|
||||
the set of source files to build to compose the BSP support library
|
||||
along with the set of include files that are to be installed.
|
||||
|
||||
This single @code{Makefile.am} at the top of the BSP tree specifies
|
||||
the set of header files to install. This fragment from the SPARC/ERC32
|
||||
BSP results in four header files being installed.
|
||||
|
||||
@example
|
||||
include_HEADERS = include/bsp.h
|
||||
include_HEADERS += include/tm27.h
|
||||
include_HEADERS += include/erc32.h
|
||||
include_HEADERS += include/coverhd.h
|
||||
@end example
|
||||
|
||||
When adding new include files, you will be adding to the set of
|
||||
@code{include_HEADERS}. When you finish editing the @code{Makefile.am}
|
||||
file, do not forget to run @code{bootstrap -p} to regenerate the
|
||||
@code{preinstall.am}.
|
||||
|
||||
The @code{Makefile.am} also specifies which source files to build.
|
||||
By convention, logical components within the BSP each assign their
|
||||
source files to a unique variable. These variables which define
|
||||
the source files are collected into a single variable which instructs
|
||||
the GNU autotools that we are building @code{libbsp.a}. This fragment
|
||||
from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
|
||||
support code, and the console device driver source is managed
|
||||
in the @code{Makefile.am}.
|
||||
|
||||
@example
|
||||
startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
|
||||
../../shared/bsppredriverhook.c \
|
||||
../../shared/bsppost.c ../../sparc/shared/bspstart.c \
|
||||
../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
|
||||
startup/spurious.c startup/erc32mec.c startup/boardinit.S
|
||||
clock_SOURCES = clock/ckinit.c
|
||||
...
|
||||
noinst_LIBRARIES = libbsp.a
|
||||
libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
|
||||
@end example
|
||||
|
||||
When adding new files to an existing directory, do not forget to add
|
||||
the new files to the list of files to be built in the corresponding
|
||||
@code{XXX_SOURCES} variable in the @code{Makefile.am} and run
|
||||
@code{bootstrap}.
|
||||
|
||||
Some BSPs use code that is built in @code{libcpu}. If you BSP does
|
||||
this, then you will need to make sure the objects are pulled into your
|
||||
BSP library. The following from the SPARC/ERC32 BSP pulls in the cache,
|
||||
register window management and system call support code from the directory
|
||||
corresponding to its @code{RTEMS_CPU} model.
|
||||
|
||||
@example
|
||||
libbsp_a_LIBADD = ../../../libcpu/@@RTEMS_CPU@@/cache.rel \
|
||||
../../../libcpu/@@RTEMS_CPU@@/reg_win.rel \
|
||||
../../../libcpu/@@RTEMS_CPU@@/syscall.rel
|
||||
@end example
|
||||
|
||||
@b{NOTE:} The @code{Makefile.am} files are ONLY processed by
|
||||
@code{bootstrap} and the resulting @code{Makefile.in} files are only
|
||||
processed during the configure process of a RTEMS build. Therefore,
|
||||
when developing a BSP and adding a new file to a @code{Makefile.am},
|
||||
the already generated @code{Makefile} will not automatically
|
||||
include the new references unless you configured RTEMS with the
|
||||
@code{--enable-maintainer-mode} option. Otherwise, the new file not
|
||||
being be taken into account!
|
||||
|
||||
@section Creating a New BSP Make Customization File
|
||||
|
||||
When building a BSP or an application using that BSP, it is necessary
|
||||
to tailor the compilation arguments to account for compiler flags, use
|
||||
custom linker scripts, include the RTEMS libraries, etc.. The BSP
|
||||
must be built using this information. Later, once the BSP is installed
|
||||
with the toolset, this same information must be used when building the
|
||||
application. So a BSP must include a build configuration file. The
|
||||
configuration file is @code{make/custom/BSP.cfg}.
|
||||
|
||||
The configuration file is taken into account when building one's
|
||||
application using the RTEMS template Makefiles (@code{make/templates}).
|
||||
These application template Makefiles have been included with the
|
||||
RTEMS source distribution since the early 1990's. However there is
|
||||
a desire in the RTEMS user community to move all provided examples to
|
||||
GNU autoconf. They are included in the 4.9 release series and used for
|
||||
all examples provided with RTEMS. There is no definite time table for
|
||||
obsoleting them. You are free to use these but be warned they have
|
||||
fallen out of favor with many in the RTEMS community and may disappear
|
||||
in the future.
|
||||
|
||||
The following is a slightly shortened version of the make customization
|
||||
file for the gen68340 BSP. The original source for this file can be
|
||||
found in the @code{make/custom} directory.
|
||||
|
||||
@example
|
||||
# The RTEMS CPU Family and Model
|
||||
RTEMS_CPU=m68k
|
||||
RTEMS_CPU_MODEL=m68340
|
||||
|
||||
include $(RTEMS_ROOT)/make/custom/default.cfg
|
||||
|
||||
# This is the actual bsp directory used during the build process.
|
||||
RTEMS_BSP_FAMILY=gen68340
|
||||
|
||||
# This contains the compiler options necessary to select the CPU model
|
||||
# and (hopefully) optimize for it.
|
||||
CPU_CFLAGS = -mcpu=cpu32
|
||||
|
||||
# optimize flag: typically -O2
|
||||
CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
|
||||
@end example
|
||||
|
||||
The make customization files have generally grown simpler and simpler
|
||||
with each RTEMS release. Beginning in the 4.9 release series, the rules
|
||||
for linking an RTEMS application are shared by all BSPs. Only BSPs which
|
||||
need to perform a transformation from linked ELF file to a downloadable
|
||||
format have any additional actions for program link time. In 4.8 and
|
||||
older, every BSP specified the "make executable" or @code{make-exe}
|
||||
rule and duplicated the same actions.
|
||||
|
||||
It is generally easier to copy a @code{make/custom} file from a
|
||||
BSP similar to the one being developed.
|
||||
|
||||
@@ -1,231 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Non-Volatile Memory Driver
|
||||
|
||||
The Non-Volatile driver is responsible for providing an
|
||||
interface to various types of non-volatile memory. These
|
||||
types of memory include, but are not limited to, Flash, EEPROM,
|
||||
and battery backed RAM. The capabilities provided
|
||||
by this class of device driver are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Initialize the Non-Volatile Memory Driver
|
||||
@item Optional Disable Read and Write Handlers
|
||||
@item Open a Particular Memory Partition
|
||||
@item Close a Particular Memory Partition
|
||||
@item Read from a Particular Memory Partition
|
||||
@item Write to a Particular Memory Partition
|
||||
@item Erase the Non-Volatile Memory Area
|
||||
@end itemize
|
||||
|
||||
There is currently only one non-volatile device driver included in the
|
||||
RTEMS source tree. The information provided in this chapter
|
||||
is based on drivers developed for applications using RTEMS.
|
||||
It is hoped that this driver model information can form the
|
||||
basis for a standard non-volatile memory driver model that
|
||||
can be supported in future RTEMS distribution.
|
||||
|
||||
@section Major and Minor Numbers
|
||||
|
||||
The @b{major} number of a device driver is its index in the
|
||||
RTEMS Device Address Table.
|
||||
|
||||
A @b{minor} number is associated with each device instance
|
||||
managed by a particular device driver. An RTEMS minor number
|
||||
is an @code{unsigned32} entity. Convention calls
|
||||
dividing the bits in the minor number down into categories
|
||||
that specify an area of non-volatile memory and a partition
|
||||
with that area. This results in categories
|
||||
like the following:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @b{area} - indicates a block of non-volatile memory
|
||||
@item @b{partition} - indicates a particular address range with an area
|
||||
|
||||
@end itemize
|
||||
|
||||
From the above, it should be clear that a single device driver
|
||||
can support multiple types of non-volatile memory in a single system.
|
||||
The minor number is used to distinguish the types of memory and
|
||||
blocks of memory used for different purposes.
|
||||
|
||||
@section Non-Volatile Memory Driver Configuration
|
||||
|
||||
There is not a standard non-volatile driver configuration table but some
|
||||
fields are common across different drivers. The non-volatile memory driver
|
||||
configuration table is typically an array of structures with each
|
||||
structure containing the information for a particular area of
|
||||
non-volatile memory.
|
||||
The following is a list of the type of information normally required
|
||||
to configure each area of non-volatile memory.
|
||||
|
||||
@table @b
|
||||
@item memory_type
|
||||
is the type of memory device in this area. Choices are battery backed RAM,
|
||||
EEPROM, Flash, or an optional user-supplied type. If the user-supplied type
|
||||
is configured, then the user is responsible for providing a set of
|
||||
routines to program the memory.
|
||||
|
||||
@item memory
|
||||
is the base address of this memory area.
|
||||
|
||||
@item attributes
|
||||
is a pointer to a memory type specific attribute block. Some of
|
||||
the fields commonly contained in this memory type specific attribute
|
||||
structure area:
|
||||
|
||||
@table @b
|
||||
@item use_protection_algorithm
|
||||
is set to TRUE to indicate that the protection (i.e. locking) algorithm
|
||||
should be used for this area of non-volatile memory. A particular
|
||||
type of non-volatile memory may not have a protection algorithm.
|
||||
|
||||
@item access
|
||||
is an enumerated type to indicate the organization of the memory
|
||||
devices in this memory area. The following is a list of the
|
||||
access types supported by the current driver implementation:
|
||||
|
||||
@itemize @bullet
|
||||
@item simple unsigned8
|
||||
@item simple unsigned16
|
||||
@item simple unsigned32
|
||||
@item simple unsigned64
|
||||
@item single unsigned8 at offset 0 in an unsigned16
|
||||
@item single unsigned8 at offset 1 in an unsigned16
|
||||
@item single unsigned8 at offset 0 in an unsigned32
|
||||
@item single unsigned8 at offset 1 in an unsigned32
|
||||
@item single unsigned8 at offset 2 in an unsigned32
|
||||
@item single unsigned8 at offset 3 in an unsigned32
|
||||
@end itemize
|
||||
|
||||
@item depth
|
||||
is the depth of the progamming FIFO on this particular chip. Some
|
||||
chips, particularly EEPROMs, have the same programming algorithm but
|
||||
vary in the depth of the amount of data that can be programmed in a single
|
||||
block.
|
||||
|
||||
@end table
|
||||
|
||||
@item number_of_partitions
|
||||
is the number of logical partitions within this area.
|
||||
|
||||
@item Partitions
|
||||
is the address of the table that contains an entry to describe each
|
||||
partition in this area. Fields within each element of this
|
||||
table are defined as follows:
|
||||
|
||||
@table @b
|
||||
|
||||
@item offset
|
||||
is the offset of this partition from the base address of this area.
|
||||
|
||||
@item length
|
||||
is the length of this partition.
|
||||
|
||||
@end table
|
||||
@end table
|
||||
|
||||
By dividing an area of memory into multiple partitions, it is possible
|
||||
to easily divide the non-volatile memory for different purposes.
|
||||
|
||||
@section Initialize the Non-Volatile Memory Driver
|
||||
|
||||
At system initialization, the non-volatile memory driver's
|
||||
initialization entry point will be invoked. As part of
|
||||
initialization, the driver will perform
|
||||
whatever initializatin is required on each non-volatile memory area.
|
||||
|
||||
The discrete I/O driver may register device names for memory
|
||||
partitions of particular interest to the system. Normally this
|
||||
will be restricted to the device "/dev/nv_memory" to indicate
|
||||
the entire device driver.
|
||||
|
||||
@section Disable Read and Write Handlers
|
||||
|
||||
Depending on the target's non-volatile memory configuration, it may be
|
||||
possible to write to a status register and make the memory area completely
|
||||
inaccessible. This is target dependent and beyond the standard capabilities
|
||||
of any memory type. The user has the optional capability to provide
|
||||
handlers to disable and enable access to a partiticular memory area.
|
||||
|
||||
@section Open a Particular Memory Partition
|
||||
|
||||
This is the driver open call. Usually this call does nothing other than
|
||||
validate the minor number.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is often the place
|
||||
to do this operation.
|
||||
|
||||
@section Close a Particular Memory Partition
|
||||
|
||||
This is the driver close call. Usually this call does nothing.
|
||||
|
||||
With some drivers, it may be necessary to allocate memory when a particular
|
||||
device is opened. If that is the case, then this is the place
|
||||
where that memory should be deallocated.
|
||||
|
||||
@section Read from a Particular Memory Partition
|
||||
|
||||
This corresponds to the driver read call. After validating the minor
|
||||
number and arguments, this call enables reads from the specified
|
||||
memory area by invoking the user supplied "enable reads handler"
|
||||
and then reads the indicated memory area. When
|
||||
invoked the @code{argument_block} is actually a pointer to the following
|
||||
structure type:
|
||||
|
||||
@example
|
||||
@group
|
||||
typedef struct @{
|
||||
uint32_t offset;
|
||||
void *buffer;
|
||||
uint32_t length;
|
||||
uint32_t status;
|
||||
@} Non_volatile_memory_Driver_arguments;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The driver reads @code{length} bytes starting at @code{offset} into
|
||||
the partition and places them at @code{buffer}. The result is returned
|
||||
in @code{status}.
|
||||
|
||||
After the read operation is complete, the user supplied "disable reads handler"
|
||||
is invoked to protect the memory area again.
|
||||
|
||||
@section Write to a Particular Memory Partition
|
||||
|
||||
This corresponds to the driver write call. After validating the minor
|
||||
number and arguments, this call enables writes to the specified
|
||||
memory area by invoking the "enable writes handler", then unprotecting
|
||||
the memory area, and finally actually writing to the indicated memory
|
||||
area. When invoked the @code{argument_block} is actually a pointer to
|
||||
the following structure type:
|
||||
|
||||
@example
|
||||
@group
|
||||
typedef struct @{
|
||||
uint32_t offset;
|
||||
void *buffer;
|
||||
uint32_t length;
|
||||
uint32_t status;
|
||||
@} Non_volatile_memory_Driver_arguments;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The driver writes @code{length} bytes from @code{buffer} and
|
||||
writes them to the non-volatile memory starting at @code{offset} into
|
||||
the partition. The result is returned in @code{status}.
|
||||
|
||||
After the write operation is complete, the "disable writes handler"
|
||||
is invoked to protect the memory area again.
|
||||
|
||||
@section Erase the Non-Volatile Memory Area
|
||||
|
||||
This is one of the IOCTL functions supported by the I/O control
|
||||
device driver entry point. When this IOCTL function is invoked,
|
||||
the specified area of non-volatile memory is erased.
|
||||
|
||||
@@ -1,225 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Real-Time Clock Driver
|
||||
|
||||
@section Introduction
|
||||
|
||||
The Real-Time Clock (@b{RTC}) driver is responsible for providing an
|
||||
interface to an @b{RTC} device. [NOTE: In this chapter, the abbreviation
|
||||
@b{TOD} is used for @b{Time of Day}.] The capabilities provided by this
|
||||
driver are:
|
||||
|
||||
@itemize @bullet
|
||||
@item Set the RTC TOD to RTEMS TOD
|
||||
@item Set the RTEMS TOD to the RTC TOD
|
||||
@item Get the RTC TOD
|
||||
@item Set the RTC TOD to the Specified TOD
|
||||
@item Get the Difference Between the RTEMS and RTC TOD
|
||||
@end itemize
|
||||
|
||||
The reference implementation for a real-time clock driver can
|
||||
be found in @code{c/src/lib/libbsp/shared/tod.c}. This driver
|
||||
is based on the libchip concept and can be easily configured
|
||||
to work with any of the RTC chips supported by the RTC
|
||||
chip drivers in the directory @code{c/src/lib/lib/libchip/rtc}.
|
||||
There is a README file in this directory for each supported
|
||||
RTC chip. Each of these README explains how to configure the
|
||||
shared libchip implementation of the RTC driver for that particular
|
||||
RTC chip.
|
||||
|
||||
The DY-4 DMV177 BSP used the shared libchip implementation of the RTC
|
||||
driver. There were no DMV177 specific configuration routines. A BSP
|
||||
could use configuration routines to dynamically determine what type
|
||||
of real-time clock is on a particular board. This would be useful for
|
||||
a BSP supporting multiple board models. The relevant ports of
|
||||
the DMV177's @code{RTC_Table} configuration table is below:
|
||||
|
||||
@example
|
||||
|
||||
#include <bsp.h>
|
||||
#include <libchip/rtc.h>
|
||||
#include <libchip/icm7170.h>
|
||||
|
||||
bool dmv177_icm7170_probe(int minor);
|
||||
|
||||
rtc_tbl RTC_Table[] = @{
|
||||
@{ "/dev/rtc0", /* sDeviceName */
|
||||
RTC_ICM7170, /* deviceType */
|
||||
&icm7170_fns, /* pDeviceFns */
|
||||
dmv177_icm7170_probe, /* deviceProbe */
|
||||
(void *) ICM7170_AT_1_MHZ, /* pDeviceParams */
|
||||
DMV170_RTC_ADDRESS, /* ulCtrlPort1 */
|
||||
0, /* ulDataPort */
|
||||
icm7170_get_register_8, /* getRegister */
|
||||
icm7170_set_register_8, /* setRegister */
|
||||
@}
|
||||
@};
|
||||
|
||||
unsigned long RTC_Count = (sizeof(RTC_Table)/sizeof(rtc_tbl));
|
||||
rtems_device_minor_number RTC_Minor;
|
||||
|
||||
bool dmv177_icm7170_probe(int minor)
|
||||
@{
|
||||
volatile unsigned16 *card_resource_reg;
|
||||
|
||||
card_resource_reg = (volatile unsigned16 *) DMV170_CARD_RESORCE_REG;
|
||||
|
||||
if ( (*card_resource_reg & DMV170_RTC_INST_MASK) == DMV170_RTC_INSTALLED )
|
||||
return TRUE;
|
||||
return FALSE;
|
||||
@}
|
||||
|
||||
@end example
|
||||
|
||||
@section Initialization
|
||||
|
||||
The @code{rtc_initialize} routine is responsible for initializing the
|
||||
RTC chip so it can be used. The shared libchip implementation of this
|
||||
driver supports multiple RTCs and bases its initialization order on
|
||||
the order the chips are defined in the @code{RTC_Table}. Each chip
|
||||
defined in the table may or may not be present on this particular board.
|
||||
It is the responsibility of the @code{deviceProbe} to indicate the
|
||||
presence of a particular RTC chip. The first RTC found to be present
|
||||
is considered the preferred RTC.
|
||||
|
||||
In the shared libchip based implementation
|
||||
of the driver, the following actions are performed:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_device_driver rtc_initialize(
|
||||
rtems_device_major_number major,
|
||||
rtems_device_minor_number minor_arg,
|
||||
void *arg
|
||||
)
|
||||
@{
|
||||
for each RTC configured in RTC_Table
|
||||
if the deviceProbe for this RTC indicates it is present
|
||||
set RTC_Minor to this device
|
||||
set RTC_Present to TRUE
|
||||
break out of this loop
|
||||
|
||||
if RTC_Present is not TRUE
|
||||
return RTEMS_INVALID_NUMBER to indicate that no RTC is present
|
||||
|
||||
register this minor number as the "/dev/rtc"
|
||||
|
||||
perform the deviceInitialize routine for the preferred RTC chip
|
||||
|
||||
for RTCs past this one in the RTC_Table
|
||||
if the deviceProbe for this RTC indicates it is present
|
||||
perform the deviceInitialize routine for this RTC chip
|
||||
register the configured name for this RTC
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The @code{deviceProbe} routine returns TRUE if the device
|
||||
configured by this entry in the @code{RTC_Table} is present.
|
||||
This configuration scheme allows one to support multiple versions
|
||||
of the same board with a single BSP. For example, if the first
|
||||
generation of a board had Vendor A's RTC chip and the second
|
||||
generation had Vendor B's RTC chip, RTC_Table could contain
|
||||
information for both. The @code{deviceProbe} configured
|
||||
for Vendor A's RTC chip would need to return TRUE if the
|
||||
board was a first generation one. The @code{deviceProbe}
|
||||
routines are very board dependent and must be provided by
|
||||
the BSP.
|
||||
|
||||
@section setRealTimeToRTEMS
|
||||
|
||||
The @code{setRealTimeToRTEMS} routine sets the current RTEMS TOD to that
|
||||
of the preferred RTC.
|
||||
|
||||
@example
|
||||
@group
|
||||
void setRealTimeToRTEMS(void)
|
||||
@{
|
||||
if no RTCs are present
|
||||
return
|
||||
|
||||
invoke the deviceGetTime routine for the preferred RTC
|
||||
set the RTEMS TOD using rtems_clock_set
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section setRealTimeFromRTEMS
|
||||
|
||||
The @code{setRealTimeFromRTEMS} routine sets the preferred RTC TOD to the
|
||||
current RTEMS TOD.
|
||||
|
||||
@example
|
||||
@group
|
||||
void setRealTimeFromRTEMS(void)
|
||||
@{
|
||||
if no RTCs are present
|
||||
return
|
||||
|
||||
obtain the RTEMS TOD using rtems_clock_get
|
||||
invoke the deviceSetTime routine for the preferred RTC
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section getRealTime
|
||||
|
||||
The @code{getRealTime} returns the preferred RTC TOD to the
|
||||
caller.
|
||||
|
||||
@example
|
||||
@group
|
||||
void getRealTime( rtems_time_of_day *tod )
|
||||
@{
|
||||
if no RTCs are present
|
||||
return
|
||||
|
||||
invoke the deviceGetTime routine for the preferred RTC
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section setRealTime
|
||||
|
||||
The @code{setRealTime} routine sets the preferred RTC TOD to the
|
||||
TOD specified by the caller.
|
||||
|
||||
@example
|
||||
@group
|
||||
void setRealTime( rtems_time_of_day *tod )
|
||||
@{
|
||||
if no RTCs are present
|
||||
return
|
||||
|
||||
invoke the deviceSetTime routine for the preferred RTC
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section checkRealTime
|
||||
|
||||
The @code{checkRealTime} routine returns the number of seconds
|
||||
difference between the RTC TOD and the current RTEMS TOD.
|
||||
|
||||
@example
|
||||
@group
|
||||
int checkRealTime( void )
|
||||
@{
|
||||
if no RTCs are present
|
||||
return -1
|
||||
|
||||
|
||||
obtain the RTEMS TOD using rtems_clock_get
|
||||
get the TOD from the preferred RTC using the deviceGetTime routine
|
||||
|
||||
convert the RTEMS TOD to seconds
|
||||
convert the RTC TOD to seconds
|
||||
|
||||
return the RTEMS TOD in seconds - RTC TOD in seconds
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@@ -1,266 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Shared Memory Support Driver
|
||||
|
||||
The Shared Memory Support Driver is responsible for providing glue
|
||||
routines and configuration information required by the Shared
|
||||
Memory Multiprocessor Communications Interface (MPCI). The
|
||||
Shared Memory Support Driver tailors the portable Shared
|
||||
Memory Driver to a particular target platform.
|
||||
|
||||
This driver is only required in shared memory multiprocessing
|
||||
systems that use the RTEMS mulitprocessing support. For more
|
||||
information on RTEMS multiprocessing capabilities and the
|
||||
MPCI, refer to the @b{Multiprocessing Manager} chapter
|
||||
of the @b{RTEMS Application C User's Guide}.
|
||||
|
||||
@section Shared Memory Configuration Table
|
||||
|
||||
The Shared Memory Configuration Table is defined in the following
|
||||
structure:
|
||||
|
||||
@example
|
||||
@group
|
||||
typedef volatile uint32_t vol_u32;
|
||||
|
||||
typedef struct @{
|
||||
vol_u32 *address; /* write here for interrupt */
|
||||
vol_u32 value; /* this value causes interrupt */
|
||||
vol_u32 length; /* for this length (0,1,2,4) */
|
||||
@} Shm_Interrupt_information;
|
||||
|
||||
struct shm_config_info @{
|
||||
vol_u32 *base; /* base address of SHM */
|
||||
vol_u32 length; /* length (in bytes) of SHM */
|
||||
vol_u32 format; /* SHM is big or little endian */
|
||||
vol_u32 (*convert)(); /* neutral conversion routine */
|
||||
vol_u32 poll_intr; /* POLLED or INTR driven mode */
|
||||
void (*cause_intr)( uint32_t );
|
||||
Shm_Interrupt_information Intr; /* cause intr information */
|
||||
@};
|
||||
|
||||
typedef struct shm_config_info shm_config_table;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
where the fields are defined as follows:
|
||||
|
||||
@table @b
|
||||
@item base
|
||||
is the base address of the shared memory buffer used to pass
|
||||
messages between the nodes in the system.
|
||||
|
||||
@item length
|
||||
is the length (in bytes) of the shared memory buffer used to pass
|
||||
messages between the nodes in the system.
|
||||
|
||||
@item format
|
||||
is either SHM_BIG or SHM_LITTLE to indicate that the neutral format
|
||||
of the shared memory area is big or little endian. The format
|
||||
of the memory should be chosen to match most of the inter-node traffic.
|
||||
|
||||
@item convert
|
||||
is the address of a routine which converts from native format to
|
||||
neutral format. Ideally, the neutral format is the same as the
|
||||
native format so this routine is quite simple.
|
||||
|
||||
@item poll_intr
|
||||
is either INTR_MODE or POLLED_MODE to indicate how the node will be
|
||||
informed of incoming messages.
|
||||
|
||||
@item cause_intr
|
||||
|
||||
@item Intr
|
||||
is the information required to cause an interrupt on a node. This
|
||||
structure contains the following fields:
|
||||
@table @b
|
||||
@item address
|
||||
is the address to write at to cause an interrupt on that node.
|
||||
For a polled node, this should be NULL.
|
||||
|
||||
@item value
|
||||
is the value to write to cause an interrupt.
|
||||
|
||||
@item length
|
||||
is the length of the entity to write on the node to cause an interrupt.
|
||||
This can be 0 to indicate polled operation, 1 to write a byte, 2 to
|
||||
write a sixteen-bit entity, and 4 to write a thirty-two bit entity.
|
||||
@end table
|
||||
@end table
|
||||
|
||||
@section Primitives
|
||||
|
||||
@subsection Convert Address
|
||||
|
||||
The @code{Shm_Convert_address} is responsible for converting an address
|
||||
of an entity in the shared memory area into the address that should be
|
||||
used from this node. Most targets will simply return the address
|
||||
passed to this routine. However, some target boards will have a special
|
||||
window onto the shared memory. For example, some VMEbus boards have
|
||||
special address windows to access addresses that are normally reserved
|
||||
in the CPU's address space.
|
||||
|
||||
@example
|
||||
@group
|
||||
void *Shm_Convert_address( void *address )
|
||||
@{
|
||||
return the local address version of this bus address
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Get Configuration
|
||||
|
||||
The @code{Shm_Get_configuration} routine is responsible for filling in the
|
||||
Shared Memory Configuration Table passed to it.
|
||||
|
||||
@example
|
||||
@group
|
||||
void Shm_Get_configuration(
|
||||
uint32_t localnode,
|
||||
shm_config_table **shmcfg
|
||||
)
|
||||
@{
|
||||
fill in the Shared Memory Configuration Table
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsection Locking Primitives
|
||||
|
||||
This is a collection of routines that are invoked by the portable
|
||||
part of the Shared Memory Driver to manage locks in the shared
|
||||
memory buffer area. Accesses to the shared memory must be
|
||||
atomic. Two nodes in a multiprocessor system must not be manipulating
|
||||
the shared data structures simultaneously. The locking primitives
|
||||
are used to insure this.
|
||||
|
||||
To avoid deadlock, local processor interrupts should be disabled the entire
|
||||
time the locked queue is locked.
|
||||
|
||||
The locking primitives operate on the lock
|
||||
@code{field} of the @code{Shm_Locked_queue_Control}
|
||||
data structure. This structure is defined as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
typedef struct @{
|
||||
vol_u32 lock; /* lock field for this queue */
|
||||
vol_u32 front; /* first envelope on queue */
|
||||
vol_u32 rear; /* last envelope on queue */
|
||||
vol_u32 owner; /* receiving (i.e. owning) node */
|
||||
@} Shm_Locked_queue_Control;
|
||||
@end group
|
||||
@end example
|
||||
|
||||
where each field is defined as follows:
|
||||
|
||||
@table @b
|
||||
@item lock
|
||||
is the lock field. Every node in the system must agree on how this
|
||||
field will be used. Many processor families provide an atomic
|
||||
"test and set" instruction that is used to manage this field.
|
||||
|
||||
@item front
|
||||
is the index of the first message on this locked queue.
|
||||
|
||||
@item rear
|
||||
is the index of the last message on this locked queue.
|
||||
|
||||
@item owner
|
||||
is the node number of the node that currently has this structure locked.
|
||||
|
||||
@end table
|
||||
|
||||
@subsubsection Initializing a Shared Lock
|
||||
|
||||
The @code{Shm_Initialize_lock} routine is responsible for
|
||||
initializing the lock field. This routines usually is implemented
|
||||
as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
void Shm_Initialize_lock(
|
||||
Shm_Locked_queue_Control *lq_cb
|
||||
)
|
||||
@{
|
||||
lq_cb->lock = LQ_UNLOCKED;
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsubsection Acquiring a Shared Lock
|
||||
|
||||
The @code{Shm_Lock} routine is responsible for
|
||||
acquiring the lock field. Interrupts should be
|
||||
disabled while that lock is acquired. If the lock
|
||||
is currently unavailble, then the locking routine
|
||||
should delay a few microseconds to allow the other
|
||||
node to release the lock. Doing this reduces bus contention
|
||||
for the lock. This routines usually is implemented as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
void Shm_Lock(
|
||||
Shm_Locked_queue_Control *lq_cb
|
||||
)
|
||||
@{
|
||||
disable processor interrupts
|
||||
set Shm_isrstat to previous interrupt disable level
|
||||
|
||||
while ( TRUE ) @{
|
||||
atomically attempt to acquire the lock
|
||||
if the lock was acquired
|
||||
return
|
||||
delay some small period of time
|
||||
@}
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@subsubsection Releasing a Shared Lock
|
||||
|
||||
The @code{Shm_Unlock} routine is responsible for
|
||||
releasing the lock field and reenabling processor
|
||||
interrupts. This routines usually is implemented as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
void Shm_Unlock(
|
||||
Shm_Locked_queue_Control *lq_cb
|
||||
)
|
||||
@{
|
||||
set the lock to the unlocked value
|
||||
reenable processor interrupts to their level prior
|
||||
to the lock being acquired. This value was saved
|
||||
in the global variable Shm_isrstat
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@section Installing the MPCI ISR
|
||||
|
||||
The @code{Shm_setvec} is invoked by the portable portion
|
||||
of the shared memory to install the interrupt service routine
|
||||
that is invoked when an incoming message is announced. Some
|
||||
target boards support an interprocessor interrupt or mailbox
|
||||
scheme and this is where the ISR for that interrupt would be
|
||||
installed.
|
||||
|
||||
On an interrupt driven node, this routine would be implemented
|
||||
as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
void Shm_setvec( void )
|
||||
@{
|
||||
install the interprocessor communications ISR
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
On a polled node, this routine would be empty.
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 24 February 2013
|
||||
@set UPDATED-MONTH February 2013
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,366 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2011.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Miscellaneous Support Files
|
||||
|
||||
@section GCC Compiler Specifications File
|
||||
|
||||
The file @code{bsp_specs} defines the start files and libraries
|
||||
that are always used with this BSP. The format of this file
|
||||
is admittedly cryptic and this document will make no attempt
|
||||
to explain it completely. Below is the @code{bsp_specs}
|
||||
file from the PowerPC psim BSP:
|
||||
|
||||
@example
|
||||
@group
|
||||
%rename endfile old_endfile
|
||||
%rename startfile old_startfile
|
||||
%rename link old_link
|
||||
|
||||
*startfile:
|
||||
%@{!qrtems: %(old_startfile)@} \
|
||||
%@{!nostdlib: %@{qrtems: ecrti%O%s rtems_crti%O%s crtbegin.o%s start.o%s@}@}
|
||||
|
||||
*link:
|
||||
%@{!qrtems: %(old_link)@} %@{qrtems: -Qy -dp -Bstatic -e _start -u __vectors@}
|
||||
|
||||
*endfile:
|
||||
%@{!qrtems: %(old_endfile)@} %@{qrtems: crtend.o%s ecrtn.o%s@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The first section of this file renames the built-in definition of
|
||||
some specification variables so they can be augmented without
|
||||
embedded their original definition. The subsequent sections
|
||||
specify what behavior is expected when the @code{-qrtems} option is specified.
|
||||
|
||||
The @code{*startfile} section specifies that the BSP specific file
|
||||
@code{start.o} will be used instead of @code{crt0.o}. In addition,
|
||||
various EABI support files (@code{ecrti.o} etc.) will be linked in with
|
||||
the executable.
|
||||
|
||||
The @code{*link} section adds some arguments to the linker when it is
|
||||
invoked by GCC to link an application for this BSP.
|
||||
|
||||
The format of this file is specific to the GNU Compiler Suite. The
|
||||
argument used to override and extend the compiler built-in specifications
|
||||
is available in all recent GCC versions. The @code{-specs} option is
|
||||
present in all @code{egcs} distributions and @code{gcc} distributions
|
||||
starting with version 2.8.0.
|
||||
|
||||
@section README Files
|
||||
|
||||
Most BSPs provide one or more @code{README} files. Generally, there
|
||||
is a @code{README} file at the top of the BSP source. This file
|
||||
describes the board and its hardware configuration, provides vendor
|
||||
information, local configuration information, information on downloading
|
||||
code to the board, debugging, etc.. The intent of this
|
||||
file is to help someone begin to use the BSP faster.
|
||||
|
||||
A @code{README} file in a BSP subdirectory typically explains something
|
||||
about the contents of that subdirectory in greater detail. For example,
|
||||
it may list the documentation available for a particular peripheral
|
||||
controller and how to obtain that documentation. It may also explain some
|
||||
particularly cryptic part of the software in that directory or provide
|
||||
rationale on the implementation.
|
||||
|
||||
@section times
|
||||
|
||||
This file contains the results of the RTEMS Timing Test Suite. It is
|
||||
in a standard format so that results from one BSP can be easily compared
|
||||
with those of another target board.
|
||||
|
||||
If a BSP supports multiple variants, then there may be multiple @code{times}
|
||||
files. Usually these are named @code{times.VARIANTn}.
|
||||
|
||||
@section Tools Subdirectory
|
||||
|
||||
Some BSPs provide additional tools that aid in using the target board.
|
||||
These tools run on the development host and are built as part of building
|
||||
the BSP. Most common is a script to automate running the RTEMS Test Suites
|
||||
on the BSP. Examples of this include:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @code{powerpc/psim} includes scripts to ease use of the simulator
|
||||
|
||||
@item @code{m68k/mvme162} includes a utility to download across the
|
||||
VMEbus into target memory if the host is a VMEbus board in the same
|
||||
chasis.
|
||||
|
||||
@end itemize
|
||||
|
||||
@section bsp.h Include File
|
||||
|
||||
The file @code{include/bsp.h} contains prototypes and definitions
|
||||
specific to this board. Every BSP is required to provide a @code{bsp.h}.
|
||||
The best approach to writing a @code{bsp.h} is copying an existing one
|
||||
as a starting point.
|
||||
|
||||
Many @code{bsp.h} files provide prototypes of variables defined
|
||||
in the linker script (@code{linkcmds}).
|
||||
|
||||
@section tm27.h Include File
|
||||
|
||||
The @code{tm27} test from the RTEMS Timing Test Suite is designed to measure the length of time required to vector to and return from an interrupt handler. This test requires some help from the BSP to know how to cause and manipulate the interrupt source used for this measurement. The following is a list of these:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{MUST_WAIT_FOR_INTERRUPT} - modifies behavior of @code{tm27}.
|
||||
|
||||
@item @code{Install_tm27_vector} - installs the interrupt service
|
||||
routine for the Interrupt Benchmark Test (@code{tm27}).
|
||||
|
||||
@item @code{Cause_tm27_intr} - generates the interrupt source
|
||||
used in the Interrupt Benchmark Test (@code{tm27}).
|
||||
|
||||
@item @code{Clear_tm27_intr} - clears the interrupt source
|
||||
used in the Interrupt Benchmark Test (@code{tm27}).
|
||||
|
||||
@item @code{Lower_tm27_intr} - lowers the interrupt mask so the
|
||||
interrupt source used in the Interrupt Benchmark Test (@code{tm27})
|
||||
can generate a nested interrupt.
|
||||
|
||||
@end itemize
|
||||
|
||||
All members of the Timing Test Suite are designed to run @b{WITHOUT}
|
||||
the Clock Device Driver installed. This increases the predictability
|
||||
of the tests' execution as well as avoids occassionally including the
|
||||
overhead of a clock tick interrupt in the time reported. Because of
|
||||
this it is sometimes possible to use the clock tick interrupt source
|
||||
as the source of this test interrupt. On other architectures, it is
|
||||
possible to directly force an interrupt to occur.
|
||||
|
||||
@section Calling Overhead File
|
||||
|
||||
The file @code{include/coverhd.h} contains the overhead associated
|
||||
with invoking each directive. This overhead consists of the execution
|
||||
time required to package the parameters as well as to execute the "jump to
|
||||
subroutine" and "return from subroutine" sequence. The intent of this
|
||||
file is to help separate the calling overhead from the actual execution
|
||||
time of a directive. This file is only used by the tests in the
|
||||
RTEMS Timing Test Suite.
|
||||
|
||||
The numbers in this file are obtained by running the "Timer Overhead"
|
||||
@code{tmoverhd} test. The numbers in this file may be 0 and no
|
||||
overhead is subtracted from the directive execution times reported by
|
||||
the Timing Suite.
|
||||
|
||||
There is a shared implementation of @code{coverhd.h} which sets all of
|
||||
the overhead constants to 0. On faster processors, this is usually the
|
||||
best alternative for the BSP as the calling overhead is extremely small.
|
||||
This file is located at:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/shared/include/coverhd.h
|
||||
@end example
|
||||
|
||||
@section sbrk() Implementation
|
||||
|
||||
Although nearly all BSPs give all possible memory to the C Program Heap
|
||||
at initialization, it is possible for a BSP to configure the initial
|
||||
size of the heap small and let it grow on demand. If the BSP wants
|
||||
to dynamically extend the heap used by the C Library memory allocation
|
||||
routines (i.e. @code{malloc} family), then the@code{sbrk} routine must
|
||||
be functional. The following is the prototype for this routine:
|
||||
|
||||
@example
|
||||
void * sbrk(size_t increment)
|
||||
@end example
|
||||
|
||||
The @code{increment} amount is based upon the @code{sbrk_amount}
|
||||
parameter passed to the @code{bsp_libc_init} during system initialization.
|
||||
Historically initialization of the C Library was done as part of the
|
||||
BSP's Pretasking Hook but now the BSP Boot Card Framework can perform
|
||||
this operation.
|
||||
|
||||
@findex CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
|
||||
If your BSP does not want to support dynamic heap extension, then you do not have to do anything special. However, if you want to support @code{sbrk}, you must provide an implementation of this method and define @code{CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK} in @code{bsp.h}. This informs @code{rtems/confdefs.h} to configure the Malloc Family Extensions which support @code{sbrk}.
|
||||
|
||||
@section bsp_fatal_extension() - Cleanup the Hardware
|
||||
|
||||
The @code{bsp_fatal_extension()} is an optional BSP specific initial extension
|
||||
invoked once a fatal system state is reached. Most of the BSPs use the same
|
||||
shared version of @code{bsp_fatal_extension()} that does nothing or performs a
|
||||
system reset. This implementation is located in the following file:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/shared/bspclean.c
|
||||
@end example
|
||||
|
||||
The @code{bsp_fatal_extension()} routine can be used to return to a ROM
|
||||
monitor, insure that interrupt sources are disabled, etc.. This routine is the
|
||||
last place to ensure a clean shutdown of the hardware. The fatal source,
|
||||
internal error indicator, and the fatal code arguments are available to
|
||||
evaluate the fatal condition. All of the non-fatal shutdown sequences
|
||||
ultimately pass their exit status to @code{rtems_shutdown_executive} and this
|
||||
is what is passed to this routine in case the fatal source is
|
||||
RTEMS_FATAL_SOURCE_EXIT.
|
||||
|
||||
On some BSPs, it prints a message indicating that the application
|
||||
completed execution and waits for the user to press a key before
|
||||
resetting the board. The PowerPC/gen83xx and PowerPC/gen5200 BSPs do
|
||||
this when they are built to support the FreeScale evaluation boards.
|
||||
This is convenient when using the boards in a development environment
|
||||
and may be disabled for production use.
|
||||
|
||||
@section Configuration Macros
|
||||
|
||||
Each BSP can define macros in bsp.h which alter some of the the default configuration parameters in @code{rtems/confdefs.h}. This section describes those macros:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@findex CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
|
||||
@item @code{CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK} must be defined if the
|
||||
BSP has proper support for @code{sbrk}. This is discussed in more detail
|
||||
in the previous section.
|
||||
|
||||
@findex BSP_IDLE_TASK_BODY
|
||||
@item @code{BSP_IDLE_TASK_BODY} may be defined to the entry point of a
|
||||
BSP specific IDLE thread implementation. This may be overridden if the
|
||||
application provides its own IDLE task implementation.
|
||||
|
||||
@findex BSP_IDLE_TASK_STACK_SIZE
|
||||
@item @code{BSP_IDLE_TASK_STACK_SIZE} may be defined to the desired
|
||||
default stack size for the IDLE task as recommended when using this BSP.
|
||||
|
||||
@findex BSP_INTERRUPT_STACK_SIZE
|
||||
@item @code{BSP_INTERRUPT_STACK_SIZE} may be defined to the desired default interrupt stack size as recommended when using this BSP. This is sometimes required when the BSP developer has knowledge of stack intensive interrupt handlers.
|
||||
|
||||
@findex BSP_ZERO_WORKSPACE_AUTOMATICALLY
|
||||
@item @code{BSP_ZERO_WORKSPACE_AUTOMATICALLY} is defined when the BSP
|
||||
requires that RTEMS zero out the RTEMS C Program Heap at initialization.
|
||||
If the memory is already zeroed out by a test sequence or boot ROM,
|
||||
then the boot time can be reduced by not zeroing memory twice.
|
||||
|
||||
@findex BSP_DEFAULT_UNIFIED_WORK_AREAS
|
||||
@item @code{BSP_DEFAULT_UNIFIED_WORK_AREAS} is defined when the BSP
|
||||
recommends that the unified work areas configuration should always
|
||||
be used. This is desirable when the BSP is known to always have very
|
||||
little RAM and thus saving memory by any means is desirable.
|
||||
|
||||
@end itemize
|
||||
|
||||
@section set_vector() - Install an Interrupt Vector
|
||||
|
||||
On targets with Simple Vectored Interrupts, the BSP must provide
|
||||
an implementation of the @code{set_vector} routine. This routine is
|
||||
responsible for installing an interrupt vector. It invokes the support
|
||||
routines necessary to install an interrupt handler as either a "raw"
|
||||
or an RTEMS interrupt handler. Raw handlers bypass the RTEMS interrupt
|
||||
structure and are responsible for saving and restoring all their own
|
||||
registers. Raw handlers are useful for handling traps, debug vectors,
|
||||
etc..
|
||||
|
||||
The @code{set_vector} routine is a central place to perform interrupt
|
||||
controller manipulation and encapsulate that information. It is usually
|
||||
implemented as follows:
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_isr_entry set_vector( /* returns old vector */
|
||||
rtems_isr_entry handler, /* isr routine */
|
||||
rtems_vector_number vector, /* vector number */
|
||||
int type /* RTEMS or RAW intr */
|
||||
)
|
||||
@{
|
||||
if the type is RAW
|
||||
install the raw vector
|
||||
else
|
||||
use rtems_interrupt_catch to install the vector
|
||||
|
||||
perform any interrupt controller necessary to unmask
|
||||
the interrupt source
|
||||
|
||||
return the previous handler
|
||||
@}
|
||||
@end group
|
||||
@end example
|
||||
|
||||
@b{NOTE:} The i386, PowerPC and ARM ports use a Programmable
|
||||
Interrupt Controller model which does not require the BSP to implement
|
||||
@code{set_vector}. BSPs for these architectures must provide a different
|
||||
set of support routines.
|
||||
|
||||
@section Interrupt Delay Profiling
|
||||
|
||||
The RTEMS profiling needs support by the BSP for the interrupt delay times. In
|
||||
case profiling is enabled via the RTEMS build configuration option
|
||||
@code{--enable-profiling} (in this case the pre-processor symbol
|
||||
@code{RTEMS_PROFILING} is defined) a BSP may provide data for the interrupt
|
||||
delay times. The BSP can feed interrupt delay times with the
|
||||
@code{_Profiling_Update_max_interrupt_delay()} function
|
||||
(@code{#include <rtems/score/profiling.h>}). For an example please have a look
|
||||
at @code{c/src/lib/libbsp/sparc/leon3/clock/ckinit.c}.
|
||||
|
||||
@section Programmable Interrupt Controller API
|
||||
|
||||
A BSP can use the PIC API to install Interrupt Service Routines through
|
||||
a set of generic methods. In order to do so, the header files
|
||||
libbsp/shared/include/irq-generic.h and libbsp/shared/include/irq-info.h
|
||||
must be included by the bsp specific irq.h file present in the include/
|
||||
directory. The irq.h acts as a BSP interrupt support configuration file which
|
||||
is used to define some important MACROS. It contains the declarations for
|
||||
any required global functions like bsp_interrupt_dispatch(). Thus later on,
|
||||
every call to the PIC interface requires including <bsp/irq.h>
|
||||
|
||||
The generic interrupt handler table is intitalized by invoking the
|
||||
@code{bsp_interrupt_initialize()} method from bsp_start() in the bspstart.c
|
||||
file which sets up this table to store the ISR addresses, whose size is based
|
||||
on the definition of macros, BSP_INTERRUPT_VECTOR_MIN & BSP_INTERRUPT_VECTOR_MAX
|
||||
in include/bsp.h
|
||||
|
||||
For the generic handler table to properly function, some bsp specific code is
|
||||
required, that should be present in irq/irq.c . The bsp-specific functions required
|
||||
to be writen by the BSP developer are :
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@findex bsp_interrupt_facility_initialize()
|
||||
@item @code{bsp_interrupt_facility_initialize()} contains bsp specific interrupt
|
||||
initialization code(Clear Pending interrupts by modifying registers, etc.).
|
||||
This method is called from bsp_interrupt_initialize() internally while setting up
|
||||
the table.
|
||||
|
||||
@findex bsp_interrupt_handler_default()
|
||||
@item @code{bsp_interrupt_handler_default()} acts as a fallback handler when
|
||||
no ISR address has been provided corresponding to a vector in the table.
|
||||
|
||||
@findex bsp_interrupt_dispatch()
|
||||
@item @code{bsp_interrupt_dispatch()} service the ISR by handling
|
||||
any bsp specific code & calling the generic method bsp_interrupt_handler_dispatch()
|
||||
which in turn services the interrupt by running the ISR after looking it up in
|
||||
the table. It acts as an entry to the interrupt switchboard, since the bsp
|
||||
branches to this function at the time of occurrence of an interrupt.
|
||||
|
||||
@findex bsp_interrupt_vector_enable()
|
||||
@item @code{bsp_interrupt_vector_enable()} enables interrupts and is called in
|
||||
irq-generic.c while setting up the table.
|
||||
|
||||
@findex bsp_interrupt_vector_disable()
|
||||
@item @code{bsp_interrupt_vector_disable()} disables interrupts and is called in
|
||||
irq-generic.c while setting up the table & during other important parts.
|
||||
|
||||
@end itemize
|
||||
|
||||
An interrupt handler is installed or removed with the help of the following functions :
|
||||
|
||||
@example
|
||||
@group
|
||||
rtems_status_code rtems_interrupt_handler_install( /* returns status code */
|
||||
rtems_vector_number vector, /* interrupt vector */
|
||||
const char *info, /* custom identification text */
|
||||
rtems_option options, /* Type of Interrupt */
|
||||
rtems_interrupt_handler handler, /* interrupt handler */
|
||||
void *arg /* parameter to be passed to handler at the time of invocation */
|
||||
)
|
||||
|
||||
rtems_status_code rtems_interrupt_handler_remove( /* returns status code */
|
||||
rtems_vector_number vector, /* interrupt vector */
|
||||
rtems_interrupt_handler handler, /* interrupt handler */
|
||||
void *arg /* parameter to be passed to handler */
|
||||
)
|
||||
|
||||
@end group
|
||||
@end example
|
||||
@@ -1,236 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Target Dependent Files
|
||||
|
||||
RTEMS has a multi-layered approach to portability. This is done to
|
||||
maximize the amount of software that can be reused. Much of the
|
||||
RTEMS source code can be reused on all RTEMS platforms. Other parts
|
||||
of the executive are specific to hardware in some sense.
|
||||
RTEMS classifies target dependent code based upon its dependencies
|
||||
into one of the following categories.
|
||||
|
||||
@itemize @bullet
|
||||
@item CPU dependent
|
||||
@item Board dependent
|
||||
@item Peripheral dependent
|
||||
@end itemize
|
||||
|
||||
@section CPU Dependent
|
||||
|
||||
This class of code includes the foundation
|
||||
routines for the executive proper such as the context switch and
|
||||
the interrupt subroutine implementations. Sources for the supported
|
||||
processor families can be found in @code{cpukit/score/cpu}.
|
||||
A good starting point for a new family of processors is the
|
||||
@code{no_cpu} directory, which holds both prototypes and
|
||||
descriptions of each needed CPU dependent function.
|
||||
|
||||
CPU dependent code is further subcategorized if the implementation is
|
||||
dependent on a particular CPU model. For example, the MC68000 and MC68020
|
||||
processors are both members of the m68k CPU family but there are significant
|
||||
differences between these CPU models which RTEMS must take into account.
|
||||
|
||||
The source code found in the @code{cpukit/score/cpu} is required to
|
||||
only depend upon the CPU model variations that GCC distinguishes
|
||||
for the purposes of multilib'ing. Multilib is the term the GNU
|
||||
community uses to refer to building a single library source multiple
|
||||
times with different compiler options so the binary code generated
|
||||
is compatible. As an example, from GCC's perspective, many PowerPC
|
||||
CPU models are just a PPC603e. Remember that GCC only cares about
|
||||
the CPU code itself and need not be aware of any peripherals. In
|
||||
the embedded community, we are exposed to thousands of CPU models
|
||||
which are all based upon only a relative small number of CPU cores.
|
||||
|
||||
Similarly for the SPARC/ERC32 BSP, the @code{RTEMS_CPU} is specified as
|
||||
@code{erc32} which is the name of the CPU model and BSP for this SPARC V7
|
||||
system on chip. But the multilib variant used is actually @code{v7}
|
||||
which indicates the ERC32 CPU core is a SPARC V7.
|
||||
|
||||
@section Board Dependent
|
||||
|
||||
This class of code provides the most specific glue between RTEMS and
|
||||
a particular board. This code is represented by the Board Support Packages
|
||||
and associated Device Drivers. Sources for the BSPs included in the
|
||||
RTEMS distribution are located in the directory @code{c/src/lib/libbsp}.
|
||||
The BSP source directory is further subdivided based on the CPU family
|
||||
and BSP.
|
||||
|
||||
Some BSPs may support multiple board models within a single board family.
|
||||
This is necessary when the board supports multiple variants on a
|
||||
single base board. For example, the Motorola MVME162 board family has a
|
||||
fairly large number of variations based upon the particular CPU model
|
||||
and the peripherals actually placed on the board.
|
||||
|
||||
@section Peripheral Dependent
|
||||
|
||||
This class of code provides a reusable library of peripheral device
|
||||
drivers which can be tailored easily to a particular board. The
|
||||
libchip library is a collection of reusable software objects that
|
||||
correspond to standard controllers. Just as the hardware engineer
|
||||
chooses a standard controller when designing a board, the goal of
|
||||
this library is to let the software engineer do the same thing.
|
||||
|
||||
The source code for the reusable peripheral driver library may be found
|
||||
in the directory @code{c/src/lib/libchip}. The source code is further
|
||||
divided based upon the class of hardware. Example classes include serial
|
||||
communications controllers, real-time clocks, non-volatile memory, and
|
||||
network controllers.
|
||||
|
||||
@section Questions to Ask
|
||||
|
||||
When evaluating what is required to support RTEMS applications on
|
||||
a particular target board, the following questions should be asked:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Does a BSP for this board exist?
|
||||
|
||||
@item Does a BSP for a similar board exists?
|
||||
|
||||
@item Is the board's CPU supported?
|
||||
|
||||
@end itemize
|
||||
|
||||
If there is already a BSP for the board, then things may already be ready
|
||||
to start developing application software. All that remains is to verify
|
||||
that the existing BSP provides device drivers for all the peripherals
|
||||
on the board that the application will be using. For example, the application
|
||||
in question may require that the board's Ethernet controller be used and
|
||||
the existing BSP may not support this.
|
||||
|
||||
If the BSP does not exist and the board's CPU model is supported, then
|
||||
examine the reusable chip library and existing BSPs for a close match.
|
||||
Other BSPs and libchip provide starting points for the development
|
||||
of a new BSP. It is often possible to copy existing components in
|
||||
the reusable chip library or device drivers from BSPs from different
|
||||
CPU families as the starting point for a new device driver.
|
||||
This will help reduce the development effort required.
|
||||
|
||||
If the board's CPU family is supported but the particular CPU model on
|
||||
that board is not, then the RTEMS port to that CPU family will have to
|
||||
be augmented. After this is done, development of the new BSP can proceed.
|
||||
|
||||
Otherwise both CPU dependent code and the BSP will have to be written.
|
||||
|
||||
This type of development often requires specialized skills. If
|
||||
you need help in making these modifications to RTEMS, please
|
||||
consider using one of the RTEMS Service Providers. The current
|
||||
list of these is at @uref{@value{RTEMSHTTPURL}/support.html}.
|
||||
|
||||
@section CPU Dependent Executive Files
|
||||
|
||||
The CPU dependent files in the RTEMS executive source code are found
|
||||
in the following directory:
|
||||
|
||||
@example
|
||||
cpukit/score/cpu/@i{CPU}
|
||||
@end example
|
||||
|
||||
where @i{CPU} is replaced with the CPU family name.
|
||||
|
||||
Within each CPU dependent directory inside the executive proper is a
|
||||
file named @code{@i{CPU}.h} which contains information about each of the
|
||||
supported CPU models within that family.
|
||||
|
||||
@section CPU Dependent Support Files
|
||||
|
||||
The CPU dependent support files contain routines which aid in the development
|
||||
of applications using that CPU family. For example, the support routines
|
||||
may contain standard trap handlers for alignment or floating point exceptions
|
||||
or device drivers for peripheral controllers found on the CPU itself.
|
||||
This class of code may be found in the following directory:
|
||||
|
||||
@example
|
||||
c/src/lib/libcpu/@i{CPU}
|
||||
@end example
|
||||
|
||||
CPU model dependent support code is found in the following directory:
|
||||
|
||||
@example
|
||||
c/src/lib/libcpu/@i{CPU}/@i{CPU_MODEL}
|
||||
@end example
|
||||
|
||||
@i{CPU_MODEL} may be a specific CPU model name or a name indicating a CPU
|
||||
core or a set of related CPU models. The file @code{configure.ac} in each
|
||||
@code{c/src/lib/libcpu/@i{CPU}} directory contains the logic which enables
|
||||
the appropriate subdirectories for the specific CPU model your BSP has.
|
||||
|
||||
@section Board Support Package Structure
|
||||
|
||||
The BSPs are all under the @code{c/src/lib/libbsp} directory. Below this
|
||||
directory, there is a subdirectory for each CPU family. Each BSP
|
||||
is found under the subdirectory for the appropriate processor
|
||||
family (m68k, powerpc, etc.). In addition, there is source code
|
||||
available which may be shared across all BSPs regardless of
|
||||
the CPU family or just across BSPs within a single CPU family. This
|
||||
results in a BSP using the following directories:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/shared
|
||||
c/src/lib/libbsp/@i{CPU}/shared
|
||||
c/src/lib/libbsp/@i{CPU}/@i{BSP}
|
||||
@end example
|
||||
|
||||
Under each BSP specific directory, there is a collection of
|
||||
subdirectories. For commonly provided functionality, the BSPs
|
||||
follow a convention on subdirectory naming. The following list
|
||||
describes the commonly found subdirectories under each BSP.
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @b{console}:
|
||||
is technically the serial driver for the BSP rather
|
||||
than just a console driver, it deals with the board
|
||||
UARTs (i.e. serial devices).
|
||||
|
||||
@item @b{clock}:
|
||||
support for the clock tick -- a regular time basis to the kernel.
|
||||
|
||||
@item @b{timer}:
|
||||
support of timer devices.
|
||||
|
||||
@item @b{rtc} or @code{tod}:
|
||||
support for the hardware real-time clock.
|
||||
|
||||
@item @b{nvmem}:
|
||||
support for non-volatile memory such as EEPROM or Flash.
|
||||
|
||||
@item @b{network}:
|
||||
the Ethernet driver.
|
||||
|
||||
@item @b{shmsupp}:
|
||||
support of shared memory driver MPCI layer in a multiprocessor system,
|
||||
|
||||
@item @b{include}:
|
||||
include files for this BSP.
|
||||
|
||||
@item @b{gnatsupp}:
|
||||
BSP specific support for the GNU Ada run-time. Each BSP that wishes
|
||||
to have the possibility to map faults or exceptions into Ada language
|
||||
exceptions or hardware interrupts into Ada interrupt tasks must provide
|
||||
this support.
|
||||
|
||||
@end itemize
|
||||
|
||||
There may be other directories in the BSP tree and the name should
|
||||
be indicative of the functionality of the code within that directory.
|
||||
|
||||
The build order of the BSP is determined by the Makefile structure.
|
||||
This structure is discussed in more detail in the @ref{Makefiles}
|
||||
chapter.
|
||||
|
||||
@b{NOTE:} This manual refers to the gen68340 BSP for numerous concrete
|
||||
examples. You should have a copy of the gen68340 BSP available while
|
||||
reading this piece of documentation. This BSP is located in the
|
||||
following directory:
|
||||
|
||||
@example
|
||||
c/src/lib/libbsp/m68k/gen68340
|
||||
@end example
|
||||
|
||||
Later in this document, the $BSP340_ROOT label will be used
|
||||
to refer to this directory.
|
||||
|
||||
@@ -1,103 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Timer Driver
|
||||
|
||||
The timer driver is primarily used by the RTEMS Timing Tests.
|
||||
This driver provides as accurate a benchmark timer as possible.
|
||||
It typically reports its time in microseconds, CPU cycles, or
|
||||
bus cycles. This information can be very useful for determining
|
||||
precisely what pieces of code require optimization and to measure the
|
||||
impact of specific minor changes.
|
||||
|
||||
The gen68340 BSP also uses the Timer Driver to support a high performance
|
||||
mode of the on-CPU UART.
|
||||
|
||||
@section Benchmark Timer
|
||||
|
||||
The RTEMS Timing Test Suite requires a benchmark timer. The
|
||||
RTEMS Timing Test Suite is very helpful for determining
|
||||
the performance of target hardware and comparing its performance
|
||||
to that of other RTEMS targets.
|
||||
|
||||
This section describes the routines which are assumed to exist by
|
||||
the RTEMS Timing Test Suite. The names used are @b{EXACTLY} what
|
||||
is used in the RTEMS Timing Test Suite so follow the naming convention.
|
||||
|
||||
@subsection benchmark_timer_initialize
|
||||
|
||||
Initialize the timer source.
|
||||
|
||||
@example
|
||||
void benchmark_timer_initialize(void)
|
||||
@{
|
||||
initialize the benchmark timer
|
||||
@}
|
||||
@end example
|
||||
|
||||
@subsection Read_timer
|
||||
|
||||
The @code{benchmark_timer_read} routine returns the number of benchmark
|
||||
time units (typically microseconds) that have elapsed since the last
|
||||
call to @code{benchmark_timer_initialize}.
|
||||
|
||||
@example
|
||||
benchmark_timer_t benchmark_timer_read(void)
|
||||
@{
|
||||
stop time = read the hardware timer
|
||||
if the subtract overhead feature is enabled
|
||||
subtract overhead from stop time
|
||||
return the stop time
|
||||
@}
|
||||
@end example
|
||||
|
||||
Many implementations of this routine subtract the overhead required
|
||||
to initialize and read the benchmark timer. This makes the times reported
|
||||
more accurate.
|
||||
|
||||
Some implementations report 0 if the harware timer value change is
|
||||
sufficiently small. This is intended to indicate that the execution time
|
||||
is below the resolution of the timer.
|
||||
|
||||
@subsection benchmark_timer_disable_subtracting_average_overhead
|
||||
|
||||
This routine is invoked by the "Check Timer" (@code{tmck}) test in the
|
||||
RTEMS Timing Test Suite. It makes the @code{benchmark_timer_read}
|
||||
routine NOT subtract the overhead required
|
||||
to initialize and read the benchmark timer. This is used
|
||||
by the @code{tmoverhd} test to determine the overhead
|
||||
required to initialize and read the timer.
|
||||
|
||||
@example
|
||||
void benchmark_timer_disable_subtracting_average_overhead(bool find_flag)
|
||||
@{
|
||||
disable the subtract overhead feature
|
||||
@}
|
||||
@end example
|
||||
|
||||
The @code{benchmark_timer_find_average_overhead} variable is used to
|
||||
indicate the state of the "subtract overhead feature".
|
||||
|
||||
@section gen68340 UART FIFO Full Mode
|
||||
|
||||
The gen68340 BSP is an example of the use of the timer to support the UART
|
||||
input FIFO full mode (FIFO means First In First Out and roughly means
|
||||
buffer). This mode consists in the UART raising an interrupt when n
|
||||
characters have been received (@i{n} is the UART's FIFO length). It results
|
||||
in a lower interrupt processing time, but the problem is that a scanf
|
||||
primitive will block on a receipt of less than @i{n} characters. The solution
|
||||
is to set a timer that will check whether there are some characters
|
||||
waiting in the UART's input FIFO. The delay time has to be set carefully
|
||||
otherwise high rates will be broken:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item if no character was received last time the interrupt subroutine was
|
||||
entered, set a long delay,
|
||||
|
||||
@item otherwise set the delay to the delay needed for @i{n} characters
|
||||
receipt.
|
||||
|
||||
@end itemize
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 17 July 2015
|
||||
@set UPDATED-MONTH July 2015
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,39 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2015.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@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{} 1988 - 2015.@*
|
||||
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.
|
||||
|
||||
The RTEMS Project is hosted at @uref{http://www.rtems.org}. Any
|
||||
inquiries concerning RTEMS, its related support components, or its
|
||||
documentation should be directed to the Community Project hosted at
|
||||
@uref{http://www.rtems.org}.
|
||||
|
||||
Any inquiries for commercial services including training, support, custom
|
||||
development, application development assistance should be directed to
|
||||
@uref{http://www.rtems.com}.
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2009.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c The RTEMS Project has been granted permission from The Open Group
|
||||
@c IEEE to excerpt and use portions of the POSIX standards documents
|
||||
@c in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
|
||||
@c We have to include a specific acknowledgement paragraph in these
|
||||
@c documents (e.g. preface or copyright page) and another slightly
|
||||
@c different paragraph for each manual page that excerpts and uses
|
||||
@c text from the standards.
|
||||
@c
|
||||
@c This file should help ensure that the paragraphs are consistent
|
||||
@c and not duplicated.
|
||||
@c
|
||||
|
||||
@quotation
|
||||
Portions of this text are reprinted and reproduced in electronic
|
||||
form from IEEE Std 1003.1, 2004 Edition, Standard for Information
|
||||
Technology — Operating System Interface (POSIX), The Open
|
||||
Group Base Specifications Issue 6, Copyright © 2001-2004 by the
|
||||
Institute of Electrical and Electronics Engineers, Inc and The
|
||||
Open Group. In the event of any discrepancy between this version
|
||||
and the original IEEE and The Open Group Standard, the original
|
||||
IEEE and The Open Group Standard is the referee document. The
|
||||
original Standard can be obtained online at
|
||||
@uref{http://www.opengroup.org/unix/online.html,
|
||||
http://www.opengroup.org/unix/online.html}.
|
||||
@end quotation
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2009.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c The RTEMS Project has been granted permission from The Open Group
|
||||
@c IEEE to excerpt and use portions of the POSIX standards documents
|
||||
@c in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
|
||||
@c We have to include a specific acknowledgement paragraph in these
|
||||
@c documents (e.g. preface or copyright page) and another slightly
|
||||
@c different paragraph for each manual page that excerpts and uses
|
||||
@c text from the standards.
|
||||
@c
|
||||
@c This file should help ensure that the paragraphs are consistent
|
||||
@c and not duplicated
|
||||
@c
|
||||
|
||||
@quotation
|
||||
The Institute of Electrical and Electronics Engineers, Inc and The
|
||||
Open Group, have given us permission to reprint portions of their
|
||||
documentation.
|
||||
|
||||
Portions of this text are reprinted and reproduced in electronic
|
||||
form from IEEE Std 1003.1, 2004 Edition, Standard for Information
|
||||
Technology — Operating System Interface (POSIX), The Open
|
||||
Group Base Specifications Issue 6, Copyright © 2001-2004 by the
|
||||
Institute of Electrical and Electronics Engineers, Inc and The
|
||||
Open Group. In the event of any discrepancy between this version
|
||||
and the original IEEE and The Open Group Standard, the original
|
||||
IEEE and The Open Group Standard is the referee document. The
|
||||
original Standard can be obtained online at
|
||||
@uref{http://www.opengroup.org/unix/online.html,
|
||||
http://www.opengroup.org/unix/online.html}.
|
||||
|
||||
This notice shall appear on any product containing this material.
|
||||
@end quotation
|
||||
@@ -1,6 +0,0 @@
|
||||
@set RTEMSUSERS users@@rtems.org
|
||||
@set RTEMSDEVEL devel@@rtems.org
|
||||
@set RTEMSHTTPURL http://www.rtems.org
|
||||
@set RTEMSPREFIX @RTEMSPREFIX@
|
||||
@set RTEMSAPI @RTEMSAPI@
|
||||
@set RTEMSRPMPREFIX @RTEMSRPMPREFIX@
|
||||
@@ -1,60 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@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
|
||||
@c @clear use-html
|
||||
@c @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
|
||||
@@ -1,317 +0,0 @@
|
||||
% treedef.tex
|
||||
%
|
||||
% These definitions for tree macros are taken from "Trees in TeX",
|
||||
% by David Eppstein, as published in TUGboat 6#1, March 1985.
|
||||
% David Eppstein's address (as of 15 June 1988) is
|
||||
% Computer Science Department
|
||||
% Columbia University
|
||||
% New York, NY 10027
|
||||
% Eppstein@cs.Columbia.edu
|
||||
%
|
||||
% Tree -- a macro to make aligned (horizontal) trees in TeX
|
||||
%
|
||||
% Input is of the form
|
||||
% \tree
|
||||
% item
|
||||
% \subtree
|
||||
% \leaf{item}
|
||||
% .
|
||||
% .
|
||||
% .
|
||||
% \endsubtree
|
||||
% \subtree
|
||||
% .
|
||||
% .
|
||||
% .
|
||||
% \endsubtree
|
||||
% \endsubtree
|
||||
% \endtree
|
||||
%
|
||||
% Nesting is to any level. \leaf is defined as a subtree of one item:
|
||||
% \def\leaf#1{\subtree#1\endsubtree}.
|
||||
%
|
||||
% A structure:
|
||||
% \subtree
|
||||
% item_part1
|
||||
% item_part2
|
||||
% .
|
||||
% .
|
||||
% .
|
||||
%
|
||||
% will print item_part2 directly below item_part1 as a single item
|
||||
% as if they were in a \box.
|
||||
%
|
||||
% The macro is a 3-pass macro. On the first pass it sets up a data
|
||||
% structure from the \subtree ... \endsubtree definitions. On the second pass
|
||||
% it recursively calculates the width of each level of the tree. On the third
|
||||
% pass it sets up the boxes, glue and rules.
|
||||
%
|
||||
% By David Eppstein, TUGboat, vol. 6 (1985), no. 1, pp. 31--35.
|
||||
% Transcribed by Margaret Kromer (peg), Feb., 1986.
|
||||
%
|
||||
% Pass 1
|
||||
% At the end of pass 1, the tree is coded as a nested collection of \hboxes
|
||||
% and \vboxes.
|
||||
\newbox\treebox\newcount\treeboxcnt
|
||||
\def\tree{\message{Begin tree}\treeboxcnt=1\global\setbox\treebox=\boxtree}
|
||||
\def\subtree{\ettext \advance\treeboxcnt by 1 \boxtree}
|
||||
\def\leaf#1{\subtree#1\endsubtree}
|
||||
\def\endsubtree{\ettext \egroup \advance\treeboxcnt-1{}%
|
||||
\ifnum\treeboxcnt=-1 \treeerrora\fi}
|
||||
\def\endtree{\endsubtree \ifnum\treeboxcnt>0 \treeerrorb\fi%
|
||||
\settreesizes \typesettree \message{-- end tree}}
|
||||
% Error messages for unbalanced tree
|
||||
\def\treeerrora{\errhelp=\treeerrorahelp%
|
||||
\errmessage{Unbalanced tree -- too many endsubtrees}}
|
||||
\newhelp\treeerrorahelp{There are more subtrees closed than opened}
|
||||
\def\treeerrorb{\errhelp=\treeerrorbhelp%
|
||||
\errmessage{Unbalanced tree -- not enough endsubtrees}}
|
||||
\newhelp\treeerrorbhelp{Not all the subtrees of the tree are closed.
|
||||
If you continue, you'll get some mysterious secondary errors.}
|
||||
% Set up \vbox containing root of tree
|
||||
\newif\iftreetext\treetextfalse % Whether still aligning text
|
||||
\def\boxtree{\hbox\bgroup % Start outer box of tree or subtree
|
||||
\baselineskip 2.5ex % Narrow line spacing slightly
|
||||
\tabskip 0pt % No spurious glue in alignment
|
||||
\vbox\bgroup % Start inner text \vbox
|
||||
\treetexttrue % Remember for \ettext
|
||||
\let\par\crcr \obeylines % New line breaks without explicit \cr
|
||||
\halign\bgroup##\hfil\cr} % Start alignment with simple template
|
||||
\def\ettext{\iftreetext % Are we still in inner text \vbox?
|
||||
\crcr\egroup \egroup \fi} % Yes, end alignment and box
|
||||
% Pass 2
|
||||
% Recursively calculate widths of tree with \setsizes; keep results in
|
||||
% \treesizes; \treewidth contains total width calculated so far. \treeworkbox
|
||||
% is workspace containing subtree being sized.
|
||||
\newbox\treeworkbox
|
||||
\def\cons#1#2{\edef#2{\xmark #1#2}} % Add something to start of list
|
||||
\def\car#1{\expandafter\docar#1\docar} % Take first element of list
|
||||
\def\docar\xmark#1\xmark#2\docar{#1} % ..by ignoring rest in expansion
|
||||
\def\cdr#1{\expandafter\docdr#1\docdr#1}% Similarly, drop first element
|
||||
\def\docdr\xmark#1\xmark#2\docdr#3{\def#3{\xmark #2}}
|
||||
\def\xmark{\noexpand\xmark} % List separator expands to self
|
||||
\def\nil{\xmark} % Empty list is just separator
|
||||
\def\settreesizes{\setbox\treeworkbox=\copy\treebox%
|
||||
\global\let\treesizes\nil \setsizes}
|
||||
\newdimen\treewidth % Width of this part of the tree
|
||||
\def\setsizes{\setbox\treeworkbox=\hbox\bgroup% Get a horiz list as a workspace
|
||||
\unhbox\treeworkbox\unskip % Take tree, unpack it into horiz list
|
||||
\inittreewidth % Get old width at this level
|
||||
\sizesubtrees % Recurse through all subtrees
|
||||
\sizelevel % Now set width from remaining \vbox
|
||||
\egroup} % All done, finish our \hbox
|
||||
\def\inittreewidth{\ifx\treesizes\nil % If this is the first at this level
|
||||
\treewidth=0pt % ..then we have no previous max width
|
||||
\else \treewidth=\car\treesizes % Otherwise take old max level width
|
||||
\global\cdr\treesizes % ..and advance level width storage
|
||||
\fi} % ..in preparation for next level.
|
||||
\def\sizesubtrees{\loop % For each box in horiz list (subtree)
|
||||
\setbox\treeworkbox=\lastbox \unskip % ..pull it off list and flush glue
|
||||
\ifhbox\treeworkbox \setsizes % If hbox, it's a subtree - recurse
|
||||
\repeat} % ..and loop; end loop on tree text
|
||||
\def\sizelevel{%
|
||||
\ifdim\treewidth<\wd\treeworkbox % If greater than previous maximum
|
||||
\treewidth=\wd\treeworkbox \fi % Then set max to new high
|
||||
\global\cons{\the\treewidth}\treesizes}% In either case, put back on list
|
||||
% Pass 3
|
||||
% Recursively typeset tree with \maketree by adding an \hbox containing
|
||||
% a subtree (in \treebox) to the horizontal list.
|
||||
\newdimen\treeheight % Height of this part of the tree
|
||||
\newif\ifleaf % Tree has no subtrees (is a leaf)
|
||||
\newif\ifbotsub % Bottom subtree of parent
|
||||
\newif\iftopsub % Top subtree of parent
|
||||
\def\typesettree{\medskip\maketree\medskip} % Make whole tree
|
||||
\def\maketree{\hbox{\treewidth=\car\treesizes % Get width at this level
|
||||
\cdr\treesizes % Set up width list for recursion
|
||||
\makesubtreebox\unskip % Set \treebox to text, make subtrees
|
||||
\ifleaf \makeleaf % No subtrees, add glue
|
||||
\else \makeparent \fi}} % Have subtrees, stick them at right
|
||||
{\catcode`@=11 % Be able to use \voidb@x
|
||||
\gdef\makesubtreebox{\unhbox\treebox % Open up tree or subtree
|
||||
\unskip\global\setbox\treebox\lastbox % Pick up very last box
|
||||
\ifvbox\treebox % If we're already at the \vbox
|
||||
\global\leaftrue \let\next\relax % ..then this is a leaf
|
||||
\else \botsubtrue % Otherwise, we have subtrees
|
||||
\setbox\treeworkbox\box\voidb@x % Init stack of processed subs
|
||||
\botsubtrue \let\next\makesubtree % ..and call \maketree on them
|
||||
\fi \next}} % Finish up for whichever it was
|
||||
\def\makesubtree{\setbox1\maketree % Call \maketree on this subtree
|
||||
\unskip\global\setbox\treebox\lastbox % Pick up box before it
|
||||
\treeheight=\ht1 % Get height of subtree we made
|
||||
\advance\treeheight 2ex % Add some room around the edges
|
||||
\ifhbox\treebox \topsubfalse % If picked up box is a \vbox,
|
||||
\else \topsubtrue \fi % ..this is the top, otherwise not
|
||||
\addsubtreebox % Stack subtree with the rest
|
||||
\iftopsub \global\leaffalse % If top, remember not a leaf
|
||||
\let\next\relax \else % ..(after recursion), set return
|
||||
\botsubfalse \let\next\makesubtree % Otherwise, we have more subtrees
|
||||
\fi \next} % Do tail recursion or return
|
||||
\def\addsubtreebox{\setbox\treeworkbox=\vbox{\subtreebox\unvbox\treeworkbox}}
|
||||
\def\subtreebox{\hbox\bgroup % Start \hbox of tree and lines
|
||||
\vbox to \treeheight\bgroup % Start \vbox for vertical rules
|
||||
\ifbotsub \iftopsub \vfil % If both bottom and top subtree
|
||||
\hrule width 0.4pt % ..vertical rule is just a dot
|
||||
\else \treehalfrule \fi \vfil % Bottom gets half-height rule
|
||||
\else \iftopsub \vfil \treehalfrule % Top gets half-height the other way
|
||||
\else \hrule width 0.4pt height \treeheight \fi\fi % Middle, full height
|
||||
\egroup % Finish vertical rule \vbox
|
||||
\treectrbox{\hrule width 1em}\hskip 0.2em\treectrbox{\box1}\egroup}
|
||||
\def\treectrbox#1{\vbox to \treeheight{\vfil #1\vfil}}
|
||||
\def\treehalfrule{\dimen\treeworkbox=\treeheight % Get total height
|
||||
\divide\dimen\treeworkbox 2%
|
||||
\advance\dimen\treeworkbox 0.2pt % Divide by two, add half horiz height
|
||||
\hrule width 0.4pt height \dimen\treeworkbox}% Make a vertical rule that high
|
||||
\def\makeleaf{\box\treebox} % Add leaf box to horiz list
|
||||
\def\makeparent{\ifdim\ht\treebox>%
|
||||
\ht\treeworkbox % If text is higher than subtrees
|
||||
\treeheight=\ht\treebox % ..use that height
|
||||
\else \treeheight=\ht\treeworkbox \fi % Otherwise use height of subtrees
|
||||
\advance\treewidth-\wd\treebox % Take remainder of level width
|
||||
\advance\treewidth 1em % ..after accounting for text and glue
|
||||
\treectrbox{\box\treebox}\hskip 0.2em % Add text, space before connection
|
||||
\treectrbox{\hrule width \treewidth}%
|
||||
\treectrbox{\box\treeworkbox}} % Add \hrule, subs
|
||||
|
||||
************************************************
|
||||
% Plain TeX driver for tree.tex
|
||||
|
||||
\def\uncatcodespecials{\catcode`@=12\def\do##1{\catcode`##1=12}\dospecials}
|
||||
\def\setupverbatim{\tt\obeylines\uncatcodespecials\obeyspaces}
|
||||
{\obeyspaces\global\let =\ }
|
||||
\def\beginshowoff{\par\begingroup\setupverbatim\doverbatim}
|
||||
{\catcode`\!=0 \catcode`\\=12
|
||||
!obeylines!gdef!doverbatim^^M#1\endshowoff{#1!endgroup!medbreak!filbreak%
|
||||
!smallskip}}
|
||||
|
||||
% see The TeXbook, exercise 22.14
|
||||
%\input tree.tex
|
||||
\centerline{\bf TREE TREE}
|
||||
\bigskip
|
||||
\tree
|
||||
{Tree}
|
||||
Uses
|
||||
\subtree
|
||||
Computer
|
||||
Science
|
||||
\subtree
|
||||
Data
|
||||
Structures
|
||||
\leaf{Search Tree}
|
||||
\leaf{Priority Queue}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Parsing
|
||||
\leaf{Parse Tree}
|
||||
\leaf{Symbol Table}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Structured
|
||||
Programming
|
||||
\endsubtree
|
||||
\endsubtree
|
||||
\subtree
|
||||
Genealogy
|
||||
\leaf{Ancestors}
|
||||
\leaf{Descendants}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Electrical
|
||||
Engineering
|
||||
\subtree
|
||||
Paper
|
||||
\leaf{{\it Vitae}}
|
||||
\leaf{Announcements}
|
||||
\leaf{Proposals}
|
||||
\leaf{\TeX{} Samples}
|
||||
\endsubtree
|
||||
\endsubtree
|
||||
\subtree
|
||||
Construction
|
||||
\leaf{Fences}
|
||||
\subtree
|
||||
Buildings
|
||||
\subtree
|
||||
Houses
|
||||
\leaf{Human}
|
||||
\leaf{Dog}
|
||||
\leaf{Bird}
|
||||
\leaf{Tree}
|
||||
\endsubtree
|
||||
\leaf{Barns}
|
||||
\leaf{Other}
|
||||
\endsubtree
|
||||
\leaf{\dots}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Taxonomies
|
||||
\leaf{Tree Uses}
|
||||
\endsubtree
|
||||
\endtree
|
||||
|
||||
\vskip.5truein
|
||||
\beginshowoff
|
||||
% see The TeXbook, exercise 22.14
|
||||
\input tree.tex
|
||||
\centerline{TREE TREE}
|
||||
\bigskip
|
||||
\tree
|
||||
Tree
|
||||
Uses
|
||||
\subtree
|
||||
Computer
|
||||
Science
|
||||
\subtree
|
||||
Data
|
||||
Structures
|
||||
\leaf{Search Tree}
|
||||
\leaf{Priority Queue}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Parsing
|
||||
\leaf{Parse Tree}
|
||||
\leaf{Symbol Table}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Structured
|
||||
Programming
|
||||
\endsubtree
|
||||
\endsubtree
|
||||
\subtree
|
||||
Genealogy
|
||||
\leaf{Ancestors}
|
||||
\leaf{Descendants}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Electrical
|
||||
Engineering
|
||||
\subtree
|
||||
Paper
|
||||
\leaf{{\it Vitae}}
|
||||
\leaf{Announcements}
|
||||
\leaf{Proposals}
|
||||
\leaf{\TeX{} Samples}
|
||||
\endsubtree
|
||||
\endsubtree
|
||||
\subtree
|
||||
Construction
|
||||
\leaf{Fences}
|
||||
\subtree
|
||||
Buildings
|
||||
\subtree
|
||||
Houses
|
||||
\leaf{Human}
|
||||
\leaf{Dog}
|
||||
\leaf{Bird}
|
||||
\leaf{Tree}
|
||||
\endsubtree
|
||||
\leaf{Barns}
|
||||
\leaf{Other}
|
||||
\endsubtree
|
||||
\leaf{\dots}
|
||||
\endsubtree
|
||||
\subtree
|
||||
Taxonomies
|
||||
\leaf{Tree Uses}
|
||||
\endsubtree
|
||||
\endtree
|
||||
\endshowoff
|
||||
@@ -1,406 +0,0 @@
|
||||
@c ****** This comment is here to remind you not to edit the wksheets.t
|
||||
@c ****** in any directory but common.
|
||||
@c
|
||||
@c Figures ...
|
||||
@c RTEMS RAM Workspace Worksheet
|
||||
@c RTEMS Code Space Worksheet
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Memory Requirements
|
||||
|
||||
@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.
|
||||
|
||||
@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
|
||||
|
||||
@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
|
||||
|
||||
@section RTEMS Code Space Worksheet
|
||||
|
||||
The RTEMS Code Space Worksheet is a tool provided to
|
||||
aid the RTEMS application designer to accurately calculate the
|
||||
memory required by the RTEMS run-time environment. RTEMS allows
|
||||
the custom configuration of the executive by optionally
|
||||
excluding managers which are not required by a particular
|
||||
application. This worksheet provides the included and excluded
|
||||
size of each manager in tabular form allowing for the quick
|
||||
calculation of any custom configuration of RTEMS. The RTEMS
|
||||
Code Space Worksheet is below:
|
||||
|
||||
@ifset use-ascii
|
||||
@page
|
||||
@end ifset
|
||||
@ifset use-tex
|
||||
@page
|
||||
@end ifset
|
||||
|
||||
@page
|
||||
@center @b{RTEMS Code Space Worksheet}
|
||||
@sp 1
|
||||
|
||||
@ifset use-ascii
|
||||
|
||||
The following is a list of the components of the RTEMS code space. The first
|
||||
number in parentheses is the size when the component is included,
|
||||
while the second number indicates its size when not included. If the second
|
||||
number is "NA", then the component must always be included.
|
||||
|
||||
@itemize @bullet
|
||||
@item Core (RTEMS_CORE_CODE_SIZE, NA)
|
||||
@item Initialization (RTEMS_INITIALIZATION_CODE_SIZE, NA)
|
||||
@item Task (RTEMS_TASK_CODE_SIZE, NA)
|
||||
@item Interrupt (RTEMS_INTERRUPT_CODE_SIZE, NA)
|
||||
@item Clock (RTEMS_CLOCK_CODE_SIZE, NA)
|
||||
@item Timer (RTEMS_TIMER_CODE_SIZE, RTEMS_TIMER_CODE_OPTSIZE)
|
||||
@item Semaphore (RTEMS_SEMAPHORE_CODE_SIZE, RTEMS_SEMAPHORE_CODE_OPTSIZE)
|
||||
@item Message (RTEMS_MESSAGE_CODE_SIZE, RTEMS_MESSAGE_CODE_OPTSIZE)
|
||||
@item Event (RTEMS_EVENT_CODE_SIZE, RTEMS_EVENT_CODE_OPTSIZE)
|
||||
@item Signal (RTEMS_SIGNAL_CODE_SIZE, RTEMS_SIGNAL_CODE_OPTSIZE)
|
||||
@item Partition (RTEMS_PARTITION_CODE_SIZE, RTEMS_PARTITION_CODE_OPTSIZE)
|
||||
@item Region (RTEMS_REGION_CODE_SIZE, RTEMS_REGION_CODE_OPTSIZE)
|
||||
@item Dual Ported Memory (RTEMS_DPMEM_CODE_SIZE, RTEMS_DPMEM_CODE_OPTSIZE)
|
||||
@item I/O (RTEMS_IO_CODE_SIZE, RTEMS_IO_CODE_OPTSIZE)
|
||||
@item Fatal Error (RTEMS_FATAL_ERROR_CODE_SIZE, NA)
|
||||
@item Rate Monotonic (RTEMS_RATE_MONOTONIC_CODE_SIZE, RTEMS_RATE_MONOTONIC_CODE_OPTSIZE)
|
||||
@item Multiprocessing (RTEMS_MULTIPROCESSING_CODE_SIZE, RTEMS_MULTIPROCESSING_CODE_OPTSIZE)
|
||||
@end itemize
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
|
||||
@tex
|
||||
\line{\hskip 0.50in\vbox{\offinterlineskip\halign{
|
||||
\vrule\strut#&
|
||||
\hbox to 2.25in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.00in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.00in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.25in{\enskip\hfil#\hfil}&
|
||||
\vrule#\cr
|
||||
\noalign{\hrule}
|
||||
&\bf Component && \bf Included && \bf Not Included && \bf Size &\cr\noalign{\hrule}
|
||||
&Core && RTEMS_CORE_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Initialization && RTEMS_INITIALIZATION_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Task && RTEMS_TASK_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Interrupt && RTEMS_INTERRUPT_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Clock && RTEMS_CLOCK_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Timer && RTEMS_TIMER_CODE_SIZE && RTEMS_TIMER_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Semaphore && RTEMS_SEMAPHORE_CODE_SIZE && RTEMS_SEMAPHORE_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Message && RTEMS_MESSAGE_CODE_SIZE && RTEMS_MESSAGE_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Event && RTEMS_EVENT_CODE_SIZE && RTEMS_EVENT_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Signal && RTEMS_SIGNAL_CODE_SIZE && RTEMS_SIGNAL_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Partition && RTEMS_PARTITION_CODE_SIZE && RTEMS_PARTITION_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Region && RTEMS_REGION_CODE_SIZE && RTEMS_REGION_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Dual Ported Memory && RTEMS_DPMEM_CODE_SIZE && RTEMS_DPMEM_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&I/O && RTEMS_IO_CODE_SIZE && RTEMS_IO_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Fatal Error && RTEMS_FATAL_ERROR_CODE_SIZE && NA && &\cr\noalign{\hrule}
|
||||
&Rate Monotonic && RTEMS_RATE_MONOTONIC_CODE_SIZE && RTEMS_RATE_MONOTONIC_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&Multiprocessing && RTEMS_MULTIPROCESSING_CODE_SIZE && RTEMS_MULTIPROCESSING_CODE_OPTSIZE && &\cr\noalign{\hrule}
|
||||
&\multispan 5 \bf\hfil Total Code Space Requirements\qquad\hfil&&&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
@end tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<CENTER>
|
||||
<TABLE COLS=4 WIDTH="80%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Component</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Included</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Not Included</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Size</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=center>Core</TD>
|
||||
<TD ALIGN=center>RTEMS_CORE_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Initialization</TD>
|
||||
<TD ALIGN=center>RTEMS_INITIALIZATION_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Task</TD>
|
||||
<TD ALIGN=center>RTEMS_TASK_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Interrupt</TD>
|
||||
<TD ALIGN=center>RTEMS_INTERRUPT_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Clock</TD>
|
||||
<TD ALIGN=center>RTEMS_CLOCK_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Timer</TD>
|
||||
<TD ALIGN=center>RTEMS_TIMER_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_TIMER_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Semaphore</TD>
|
||||
<TD ALIGN=center>RTEMS_SEMAPHORE_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_SEMAPHORE_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Message</TD>
|
||||
<TD ALIGN=center>RTEMS_MESSAGE_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_MESSAGE_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Event</TD>
|
||||
<TD ALIGN=center>RTEMS_EVENT_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_EVENT_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Signal</TD>
|
||||
<TD ALIGN=center>RTEMS_SIGNAL_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_SIGNAL_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Partition</TD>
|
||||
<TD ALIGN=center>RTEMS_PARTITION_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_PARTITION_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Region</TD>
|
||||
<TD ALIGN=center>RTEMS_REGION_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_REGION_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Dual Ported Memory</TD>
|
||||
<TD ALIGN=center>RTEMS_DPMEM_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_DPMEM_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>I/O</TD>
|
||||
<TD ALIGN=center>RTEMS_IO_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_IO_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Fatal Error</TD>
|
||||
<TD ALIGN=center>RTEMS_FATAL_ERROR_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Rate Monotonic</TD>
|
||||
<TD ALIGN=center>RTEMS_RATE_MONOTONIC_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_RATE_MONOTONIC_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center>Multiprocessing</TD>
|
||||
<TD ALIGN=center>RTEMS_MULTIPROCESSING_CODE_SIZE</TD>
|
||||
<TD ALIGN=center>RTEMS_MULTIPROCESSING_CODE_OPTSIZE</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=center COLSPAN=3>
|
||||
<STRONG>Total Code Space Requirements</STRONG></TD>
|
||||
<TD><BR></TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
@page
|
||||
|
||||
@c ****** Next node is set by a sed script in the document Makefile.
|
||||
@c ****** This comment is here to remind you not to edit the wksheets.t
|
||||
@c ****** in any directory but common.
|
||||
|
||||
@section RTEMS RAM Workspace Worksheet
|
||||
|
||||
The RTEMS RAM Workspace Worksheet is a tool provided
|
||||
to aid the RTEMS application designer to accurately calculate
|
||||
the minimum memory block to be reserved for RTEMS use. This
|
||||
worksheet provides equations for calculating the amount of
|
||||
memory required based upon the number of objects configured,
|
||||
whether for single or multiple processor versions of the
|
||||
executive. This information is presented in tabular form, along
|
||||
with the fixed system requirements, allowing for quick
|
||||
calculation of any application defined configuration of RTEMS.
|
||||
The RTEMS RAM Workspace Worksheet is provided below:
|
||||
|
||||
@ifset use-ascii
|
||||
@page
|
||||
@end ifset
|
||||
@ifset use-tex
|
||||
@sp 2
|
||||
@end ifset
|
||||
|
||||
@center @b{RTEMS RAM Workspace Worksheet}
|
||||
@sp 2
|
||||
|
||||
@ifset use-ascii
|
||||
The total RTEMS RAM Workspace required is the sum of the following:
|
||||
|
||||
@itemize @bullet
|
||||
@item maximum_tasks * RTEMS_BYTES_PER_TASK
|
||||
@item maximum_timers * RTEMS_BYTES_PER_TIMER
|
||||
@item maximum_semaphores * RTEMS_BYTES_PER_SEMAPHORE
|
||||
@item maximum_message_queues * RTEMS_BYTES_PER_MESSAGE_QUEUE
|
||||
@item maximum_regions * RTEMS_BYTES_PER_REGION
|
||||
@item maximum_partitions * RTEMS_BYTES_PER_PARTITION
|
||||
@item maximum_ports * RTEMS_BYTES_PER_PORT
|
||||
@item maximum_periods * RTEMS_BYTES_PER_PERIOD
|
||||
@item maximum_extensions * RTEMS_BYTES_PER_EXTENSION
|
||||
@item Floating Point Tasks * RTEMS_BYTES_PER_FP_TASK
|
||||
@item Task Stacks
|
||||
@item maximum_nodes * RTEMS_BYTES_PER_NODE
|
||||
@item maximum_global_objects * RTEMS_BYTES_PER_GLOBAL_OBJECT
|
||||
@item maximum_proxies * RTEMS_BYTES_PER_PROXY
|
||||
@item Fixed System Requirements of RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS
|
||||
@end itemize
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@tex
|
||||
\line{\hskip 0.75in\vbox{\offinterlineskip\halign{
|
||||
\vrule\strut#&
|
||||
\hbox to 3.0in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 0.75in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.25in{\enskip\hfil#\hfil}&
|
||||
\vrule#\cr
|
||||
\noalign{\hrule}
|
||||
& \bf Description && \bf Equation && \bf Bytes Required &\cr\noalign{\hrule}
|
||||
& maximum\_tasks && * RTEMS_BYTES_PER_TASK = &&&\cr\noalign{\hrule}
|
||||
& maximum\_timers && * RTEMS_BYTES_PER_TIMER = &&&\cr\noalign{\hrule}
|
||||
& maximum\_semaphores && * RTEMS_BYTES_PER_SEMAPHORE = &&&\cr\noalign{\hrule}
|
||||
& maximum\_message\_queues && * RTEMS_BYTES_PER_MESSAGE_QUEUE = &&&\cr\noalign{\hrule}
|
||||
& maximum\_regions && * RTEMS_BYTES_PER_REGION = &&&\cr\noalign{\hrule}
|
||||
& maximum\_partitions && * RTEMS_BYTES_PER_PARTITION = &&&\cr\noalign{\hrule}
|
||||
& maximum\_ports && * RTEMS_BYTES_PER_PORT = &&&\cr\noalign{\hrule}
|
||||
& maximum\_periods && * RTEMS_BYTES_PER_PERIOD = &&&\cr\noalign{\hrule}
|
||||
& maximum\_extensions && * RTEMS_BYTES_PER_EXTENSION = &&&\cr\noalign{\hrule}
|
||||
& Floating Point Tasks && * RTEMS_BYTES_PER_FP_TASK = &&&\cr\noalign{\hrule}
|
||||
& Task Stacks &&\hskip 2.3em=&&&\cr\noalign{\hrule}
|
||||
& Total Single Processor Requirements &&&&&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
|
||||
\line{\hskip 0.75in\vbox{\offinterlineskip\halign{
|
||||
\vrule\strut#&
|
||||
\hbox to 3.0in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 0.75in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.25in{\enskip\hfil#\hfil}&
|
||||
\vrule#\cr
|
||||
\noalign{\hrule}
|
||||
& \bf Description && \bf Equation && \bf Bytes Required &\cr\noalign{\hrule}
|
||||
& maximum\_nodes && * RTEMS_BYTES_PER_NODE = &&&\cr\noalign{\hrule}
|
||||
& maximum\_global\_objects && * RTEMS_BYTES_PER_GLOBAL_OBJECT = &&&\cr\noalign{\hrule}
|
||||
& maximum\_proxies && * RTEMS_BYTES_PER_PROXY = &&&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
|
||||
\line{\hskip 0.75in\vbox{\offinterlineskip\halign{
|
||||
\vrule\strut#&
|
||||
\hbox to 3.0in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 0.75in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.25in{\enskip\hfil#\hfil}&
|
||||
\vrule#\cr
|
||||
\noalign{\hrule}
|
||||
& Total Multiprocessing Requirements &&&&&\cr\noalign{\hrule}
|
||||
& Fixed System Requirements && RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS &&&\cr\noalign{\hrule}
|
||||
& Total Single Processor Requirements &&&&&\cr\noalign{\hrule}
|
||||
& Total Multiprocessing Requirements &&&&&\cr\noalign{\hrule}
|
||||
& Minimum Bytes for RTEMS Workspace &&&&&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
@end tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<CENTER>
|
||||
<TABLE COLS=3 WIDTH="80%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Description</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Equation</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Bytes Required</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_tasks</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_TASK =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_timers</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_TIMER =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_semaphores</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_SEMAPHORE =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_message_queues</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_MESSAGE_QUEUE =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_regions</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_REGION =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_partitions</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_PARTITION =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_ports</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_PORT =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_periods</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_PERIOD =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_extensions</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_EXTENSION =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>Floating Point Tasks</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_FP_TASK =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>Task Stacks</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>
|
||||
<STRONG>Total Single Processor Requirements</STRONG></TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR></TR>
|
||||
<TR><TD ALIGN=center><STRONG>Description</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Equation</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Bytes Required</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_nodes</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_NODE =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_global_objects</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_GLOBAL_OBJECT =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left>maximum_proxies</TD>
|
||||
<TD ALIGN=right>* RTEMS_BYTES_PER_PROXY =</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>
|
||||
<STRONG>Total Multiprocessing Requirements</STRONG></TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>Fixed System Requirements</TD>
|
||||
<TD ALIGN=center>RTEMS_BYTES_OF_FIXED_SYSTEM_REQUIREMENTS</TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>Total Single Processor Requirements</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>Total Multiprocessing Requirements</TD>
|
||||
<TD><BR></TD></TR>
|
||||
<TR><TD ALIGN=left COLSPAN=2>
|
||||
<STRONG>Minimum Bytes for RTEMS Workspace</STRONG></TD>
|
||||
<TD><BR></TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
184
doc/configure.ac
184
doc/configure.ac
@@ -1,184 +0,0 @@
|
||||
dnl Process this file with autoconf to produce a configure script.
|
||||
|
||||
AC_PREREQ([2.69])
|
||||
|
||||
AC_INIT([rtems-doc],[_RTEMS_VERSION],[https://devel.rtems.org/newticket])
|
||||
AC_CONFIG_SRCDIR([project.am])
|
||||
RTEMS_TOP([..])
|
||||
|
||||
AM_INIT_AUTOMAKE([no-define foreign 1.12.2])
|
||||
AM_MAINTAINER_MODE
|
||||
|
||||
RTEMS_ENABLE_RPMPREFIX
|
||||
|
||||
AC_ARG_ENABLE(html,
|
||||
[ --disable-html disable html support ],
|
||||
[case $enableval in
|
||||
yes) ;;
|
||||
no) ;;
|
||||
*) AC_MSG_ERROR("invalid value");;
|
||||
esac],
|
||||
[enable_html="yes"]
|
||||
)
|
||||
|
||||
AC_ARG_ENABLE(dvi,
|
||||
[ --disable-dvi disable dvi support ],
|
||||
[case $enableval in
|
||||
yes) ;;
|
||||
no) ;;
|
||||
*) AC_MSG_ERROR("invalid value");;
|
||||
esac],
|
||||
[enable_dvi="yes"]
|
||||
)
|
||||
|
||||
AC_ARG_ENABLE(pdf,
|
||||
[ --disable-pdf disable pdf support ],
|
||||
[case $enableval in
|
||||
yes) ;;
|
||||
no) ;;
|
||||
*) AC_MSG_ERROR("invalid value");;
|
||||
esac],
|
||||
[enable_pdf="yes"]
|
||||
)
|
||||
|
||||
AC_ARG_ENABLE(ps,
|
||||
[ --disable-ps disable ps support ],
|
||||
[case $enableval in
|
||||
yes) ;;
|
||||
no) ;;
|
||||
*) AC_MSG_ERROR("invalid value");;
|
||||
esac],
|
||||
[enable_ps="yes"]
|
||||
)
|
||||
|
||||
AC_ARG_ENABLE(papersize,
|
||||
[ --enable-papersize=[letter|a4|] set papersize [default:system defaults]],
|
||||
[case $enableval in
|
||||
a4) papersize=a4 ;;
|
||||
letter) papersize=letter ;;
|
||||
yes) papersize= ;;
|
||||
no) papersize= ;;
|
||||
*) AC_MSG_ERROR([Invalid papersize])
|
||||
;;
|
||||
esac],
|
||||
[papersize=]
|
||||
)
|
||||
|
||||
pkgdocdir="\$(datadir)/rtems"
|
||||
AC_SUBST(pkgdocdir)
|
||||
|
||||
htmldir="\$(pkgdocdir)/html"
|
||||
AC_SUBST(htmldir)
|
||||
|
||||
dnl Checks for programs.
|
||||
AC_PROG_LN_S
|
||||
|
||||
AC_CHECK_PROGS(PERL,perl)
|
||||
|
||||
AC_CHECK_PROGS(TEXI2ANY,texi2any)
|
||||
AC_SUBST(TEXI2ANY)
|
||||
AM_CONDITIONAL(USE_TEXI2ANY,
|
||||
test "$enable_html" = "yes" \
|
||||
&& test x"$TEXI2ANY" != x"")
|
||||
|
||||
AC_CHECK_PROGS(TEXI2HTML,texi2html)
|
||||
AC_SUBST(TEXI2HTML)
|
||||
AM_CONDITIONAL(USE_TEXI2HTML,
|
||||
test "$enable_html" = "yes" \
|
||||
&& test x"$TEXI2ANY" = x"" \
|
||||
&& test x"$TEXI2HTML" != x"")
|
||||
|
||||
AC_CHECK_PROGS(GS,gs)
|
||||
AM_CONDITIONAL(GS,test x"$GS" != x"")
|
||||
|
||||
AC_CHECK_PROGS(TEXI2DVI,texi2dvi)
|
||||
AM_CONDITIONAL(TEXI2DVI,test x"$TEXI2DVI" != x"")
|
||||
|
||||
AC_CHECK_PROGS(EPSTOPDF,epstopdf)
|
||||
AM_CONDITIONAL(EPSTOPDF,
|
||||
test "$enable_pdf" = "yes" \
|
||||
&& test x"$EPSTOPDF" != x"" )
|
||||
|
||||
AC_CHECK_PROGS(TEXI2PDF,texi2pdf)
|
||||
AM_CONDITIONAL(TEXI2PDF,
|
||||
test "$enable_pdf" = "yes" \
|
||||
&& test x"$TEXI2PDF" != x"")
|
||||
|
||||
AM_CONDITIONAL(USE_HTML,
|
||||
test "$enable_html" = "yes" \
|
||||
&& test x"PERL" != x"" )
|
||||
|
||||
AM_CONDITIONAL(USE_DVI,
|
||||
test "$enable_dvi" = "yes" \
|
||||
&& test x"$TEXI2DVI" != x"" )
|
||||
|
||||
AM_CONDITIONAL(USE_PS,
|
||||
test "$enable_ps" = "yes" \
|
||||
&& test x"$TEXI2DVI" != x"" )
|
||||
|
||||
AM_CONDITIONAL(USE_PDF,
|
||||
test "$enable_pdf" = "yes" \
|
||||
&& test x"$TEXI2DVI" != x"" \
|
||||
&& test x"$TEXI2PDF" != x"" )
|
||||
|
||||
case $papersize in
|
||||
a4)
|
||||
TEXI2DVI="${TEXI2DVI} --texinfo=@afourpaper"
|
||||
TEXI2PDF="${TEXI2PDF} --texinfo=@afourpaper"
|
||||
DVIPS="dvips -t a4"
|
||||
;;
|
||||
letter)
|
||||
DVIPS="dvips -t letter"
|
||||
;;
|
||||
*)
|
||||
DVIPS="dvips"
|
||||
;;
|
||||
esac
|
||||
AC_SUBST(DVIPS)
|
||||
|
||||
BMENU2='$(top_builddir)/tools/bmenu/bmenu2'
|
||||
AC_SUBST(BMENU2)
|
||||
|
||||
dnl Checks for libraries.
|
||||
|
||||
dnl Checks for header files.
|
||||
|
||||
dnl Checks for typedefs, structures, and compiler characteristics.
|
||||
|
||||
dnl Checks for library functions.
|
||||
|
||||
AC_CONFIG_SUBDIRS(tools)
|
||||
|
||||
AC_CONFIG_FILES([Makefile],[],[
|
||||
test -d common || mkdir common
|
||||
cat << EOF > common/rtems.sed~
|
||||
:t
|
||||
s/@RTEMSAPI@/_RTEMS_API/;t t
|
||||
s,@RTEMSPREFIX@,$prefix,;t t
|
||||
s,@RTEMSRPMPREFIX@,$rpmprefix,;t t
|
||||
EOF
|
||||
_RTEMS_UPDATE_CONDITIONAL([common/rtems.sed],[common/rtems.sed~])
|
||||
])
|
||||
|
||||
AC_CONFIG_FILES([
|
||||
index.html
|
||||
develenv/Makefile
|
||||
user/Makefile
|
||||
bsp_howto/Makefile])
|
||||
|
||||
AC_CONFIG_FILES([
|
||||
porting/Makefile
|
||||
networking/Makefile
|
||||
posix_users/Makefile
|
||||
posix1003.1/Makefile
|
||||
filesystem/Makefile
|
||||
ada_user/Makefile
|
||||
started/Makefile
|
||||
relnotes/Makefile
|
||||
new_chapters/Makefile
|
||||
cpu_supplement/Makefile
|
||||
shell/Makefile
|
||||
texi2html_init
|
||||
texi2any_init
|
||||
])
|
||||
AC_OUTPUT
|
||||
@@ -1,149 +0,0 @@
|
||||
#
|
||||
# COPYRIGHT (c) 1988-2012.
|
||||
# On-Line Applications Research Corporation (OAR).
|
||||
# All rights reserved.
|
||||
|
||||
PROJECT = cpu_supplement
|
||||
|
||||
include $(top_srcdir)/project.am
|
||||
include $(top_srcdir)/main.am
|
||||
|
||||
REPLACE2 = $(PERL) $(top_srcdir)/tools/word-replace2
|
||||
|
||||
GENERATED_FILES =
|
||||
GENERATED_FILES += general.texi
|
||||
GENERATED_FILES += arm.texi
|
||||
GENERATED_FILES += avr.texi
|
||||
GENERATED_FILES += bfin.texi
|
||||
GENERATED_FILES += epiphany.texi
|
||||
GENERATED_FILES += h8300.texi
|
||||
GENERATED_FILES += i386.texi
|
||||
GENERATED_FILES += lm32.texi
|
||||
GENERATED_FILES += m32c.texi
|
||||
GENERATED_FILES += m32r.texi
|
||||
GENERATED_FILES += m68k.texi
|
||||
GENERATED_FILES += microblaze.texi
|
||||
GENERATED_FILES += mips.texi
|
||||
GENERATED_FILES += or1k.texi
|
||||
GENERATED_FILES += powerpc.texi
|
||||
GENERATED_FILES += nios2.texi
|
||||
GENERATED_FILES += sh.texi
|
||||
GENERATED_FILES += sparc.texi
|
||||
GENERATED_FILES += sparc64.texi
|
||||
GENERATED_FILES += v850.texi
|
||||
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
FILES = preface.texi
|
||||
|
||||
info_TEXINFOS = cpu_supplement.texi
|
||||
cpu_supplement_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
|
||||
|
||||
#
|
||||
# Chapters which get automatic processing
|
||||
#
|
||||
|
||||
general.texi: general.t
|
||||
$(BMENU2) -p "Preface" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
arm.texi: arm.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
avr.texi: avr.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
bfin.texi: bfin.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
epiphany.texi: epiphany.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
h8300.texi: h8300.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
i386.texi: i386.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
m32c.texi: m32c.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
m32r.texi: m32r.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
lm32.texi: lm32.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
m68k.texi: m68k.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
microblaze.texi: microblaze.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
mips.texi: mips.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
or1k.texi: or1k.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
powerpc.texi: powerpc.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
nios2.texi: nios2.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
sh.texi: sh.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
sparc.texi: sparc.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
sparc64.texi: sparc64.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
v850.texi: v850.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
CLEANFILES += cpu_supplement.info
|
||||
CLEANFILES += cpu_supplement.info-1
|
||||
CLEANFILES += cpu_supplement.info-2
|
||||
|
||||
@@ -1,182 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter ARM Specific Information
|
||||
|
||||
This chapter discusses the
|
||||
@uref{http://en.wikipedia.org/wiki/ARM_architecture,ARM architecture}
|
||||
dependencies in this port of RTEMS. The ARMv4T (and compatible), ARMv7-A,
|
||||
ARMv7-R and ARMv7-M architecture versions are supported by RTEMS. Processors
|
||||
with a MMU use a static configuration which is set up during system start. SMP
|
||||
is supported.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the ARM architecture refer to the
|
||||
@uref{http://infocenter.arm.com,ARM Infocenter}.
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This section presents the set of features which vary
|
||||
across ARM implementations and are of importance to RTEMS. The set of CPU
|
||||
model feature macros are defined in the file
|
||||
@file{cpukit/score/cpu/arm/rtems/score/arm.h} based upon the particular CPU
|
||||
model flags specified on the compilation command line.
|
||||
|
||||
@subsection CPU Model Name
|
||||
|
||||
The macro @code{CPU_MODEL_NAME} is a string which designates
|
||||
the architectural level of this CPU model. See in
|
||||
@file{cpukit/score/cpu/arm/rtems/score/arm.h} for the values.
|
||||
|
||||
@subsection Count Leading Zeroes Instruction
|
||||
|
||||
The ARMv5 and later has the count leading zeroes @code{clz} instruction which
|
||||
could be used to speed up the find first bit operation. The use of this
|
||||
instruction should significantly speed up the scheduling associated with a
|
||||
thread blocking. This is currently not used.
|
||||
|
||||
@subsection Floating Point Unit
|
||||
|
||||
The following floating point units are supported.
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item VFPv3-D32/NEON (for example available on Cortex-A processors)
|
||||
@item VFPv3-D16 (for example available on Cortex-R processors)
|
||||
@item FPv4-SP-D16 (for example available on Cortex-M processors)
|
||||
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Multilibs
|
||||
|
||||
The following multilibs are available:
|
||||
|
||||
@enumerate
|
||||
@item @code{.}: ARMv4T, ARM instruction set
|
||||
@item @code{thumb}: ARMv4T, Thumb-1 instruction set
|
||||
@item @code{thumb/armv6-m}: ARMv6M, subset of Thumb-2 instruction set
|
||||
@item @code{thumb/armv7-a}: ARMv7-A, Thumb-2 instruction set
|
||||
@item @code{thumb/armv7-a/neon/hard}: ARMv7-A, Thumb-2 instruction set with
|
||||
hard-float ABI Neon and VFP-D32 support
|
||||
@item @code{thumb/armv7-r}: ARMv7-R, Thumb-2 instruction set
|
||||
@item @code{thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Thumb-2 instruction set
|
||||
with hard-float ABI VFP-D16 support
|
||||
@item @code{thumb/armv7-m}: ARMv7-M, Thumb-2 instruction set with hardware
|
||||
integer division (SDIV/UDIV)
|
||||
@item @code{thumb/armv7-m/fpv4-sp-d16}: ARMv7-M, Thumb-2 instruction set with
|
||||
hardware integer division (SDIV/UDIV) and hard-float ABI FPv4-SP support
|
||||
@item @code{eb/thumb/armv7-r}: ARMv7-R, Big-endian Thumb-2 instruction set
|
||||
@item @code{eb/thumb/armv7-r/vfpv3-d16/hard}: ARMv7-R, Big-endian Thumb-2
|
||||
instruction set with hard-float ABI VFP-D16 support
|
||||
@end enumerate
|
||||
|
||||
Multilib 1. and 2. support the standard ARM7TDMI and ARM926EJ-S targets.
|
||||
|
||||
Multilib 3. supports the Cortex-M0 and Cortex-M1 cores.
|
||||
|
||||
Multilib 8. supports the Cortex-M3 and Cortex-M4 cores, which have a special
|
||||
hardware integer division instruction (this is not present in the A and R
|
||||
profiles).
|
||||
|
||||
Multilib 9. supports the Cortex-M4 cores with a floating point unit.
|
||||
|
||||
Multilib 4. and 5. support the Cortex-A processors.
|
||||
|
||||
Multilib 6., 7., 10. and 11. support the Cortex-R processors. Here also
|
||||
big-endian variants are available.
|
||||
|
||||
Use for example the following GCC options
|
||||
|
||||
@example
|
||||
-mthumb -march=armv7-a -mfpu=neon -mfloat-abi=hard -mtune=cortex-a9
|
||||
@end example
|
||||
|
||||
to build an application or BSP for the ARMv7-A architecture and tune the code
|
||||
for a Cortex-A9 processor. It is important to select the options used for the
|
||||
multilibs. For example
|
||||
|
||||
@example
|
||||
-mthumb -mcpu=cortex-a9
|
||||
@end example
|
||||
|
||||
alone will not select the ARMv7-A multilib.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
Please refer to the
|
||||
@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf,Procedure Call Standard for the ARM Architecture}.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
A flat 32-bit memory model is supported. The board support package must take
|
||||
care about the MMU if necessary.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
The ARMv4T (and compatible) architecture has seven exception types:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Reset
|
||||
@item Undefined
|
||||
@item Software Interrupt (SWI)
|
||||
@item Prefetch Abort
|
||||
@item Data Abort
|
||||
@item Interrupt (IRQ)
|
||||
@item Fast Interrupt (FIQ)
|
||||
|
||||
@end itemize
|
||||
|
||||
Of these types only the IRQ has explicit operating system support. It is
|
||||
intentional that the FIQ is not supported by the operating system. Without
|
||||
operating system support for the FIQ it is not necessary to disable them during
|
||||
critical sections of the system.
|
||||
|
||||
The ARMv7-M architecture has a completely different exception model. Here
|
||||
interrupts are disabled with a write of 0x80 to the @code{basepri_max}
|
||||
register. This means that all exceptions and interrupts with a priority value
|
||||
of greater than or equal to 0x80 are disabled. Thus exceptions and interrupts
|
||||
with a priority value of less than 0x80 are non-maskable with respect to the
|
||||
operating system and therefore must not use operating system services. Several
|
||||
support libraries of chip vendors implicitly shift the priority value somehow
|
||||
before the value is written to the NVIC IPR register. This can easily lead to
|
||||
confusion.
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
There are exactly two interrupt levels on ARM with respect to RTEMS. Level
|
||||
zero corresponds to interrupts enabled. Level one corresponds to interrupts
|
||||
disabled.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The board support package must initialize the interrupt stack. The memory for
|
||||
the stacks is usually reserved in the linker script.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture performs the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables operating system supported interrupts (IRQ),
|
||||
@item places the error code in @code{r0}, and
|
||||
@item executes an infinite loop to simulate a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is supported on ARMv7-A. Available platforms are the Altera Cyclone V and
|
||||
the Xilinx Zynq.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is supported.
|
||||
@@ -1,133 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2009.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Atmel AVR Specific Information
|
||||
|
||||
This chapter discusses the AVR architecture dependencies in this
|
||||
port of RTEMS.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the AVR architecture, refer to the following
|
||||
documents available from Atmel.
|
||||
|
||||
TBD
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item See other CPUs for documentation reference formatting examples.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
CPUs of the AVR 53X only differ in the peripherals and thus in the
|
||||
device drivers. This port does not yet support the 56X dual core variants.
|
||||
|
||||
@subsection Count Leading Zeroes Instruction
|
||||
|
||||
The AVR CPU has the XXX instruction which could be used to speed
|
||||
up the find first bit operation. The use of this instruction should
|
||||
significantly speed up the scheduling associated with a thread blocking.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
@subsection Processor Background
|
||||
|
||||
The AVR architecture supports a simple call and return mechanism.
|
||||
A subroutine is invoked via the call (@code{call}) instruction.
|
||||
This instruction saves the return address in the @code{RETS} register
|
||||
and transfers the execution to the given address.
|
||||
|
||||
It is the called funcions responsability to use the link instruction
|
||||
to reserve space on the stack for the local variables. Returning from
|
||||
a subroutine is done by using the RTS (@code{RTS}) instruction which
|
||||
loads the PC with the adress stored in RETS.
|
||||
|
||||
It is is important to note that the @code{call} instruction 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.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
A called function may clobber all registers, except RETS, R4-R7, P3-P5,
|
||||
FP and SP. It may also modify the first 12 bytes in the caller’s stack
|
||||
frame which is used as an argument area for the first three arguments
|
||||
(which are passed in R0...R3 but may be placed on the stack by the
|
||||
called function).
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
RTEMS assumes that the AVR GCC calling convention is followed.
|
||||
The first three parameters are stored in registers R0, R1, and R2.
|
||||
All other parameters are put pushed on the stack. The result is returned
|
||||
through register R0.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
The AVR family architecutre support a single unified 4 GB byte
|
||||
address space using 32-bit addresses. It maps all resources like internal
|
||||
and external memory and IO registers into separate sections of this
|
||||
common address space.
|
||||
|
||||
The AVR architcture supports some form of memory
|
||||
protection via its Memory Management Unit. Since the
|
||||
AVR port runs in supervisior mode this memory
|
||||
protection mechanisms are not used.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
Discussed in this chapter are the AVR's interrupt response and
|
||||
control mechanisms as they pertain to RTEMS.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
TBD
|
||||
|
||||
@subsection Disabling of Interrupts by RTEMS
|
||||
|
||||
During interrupt disable critical sections, RTEMS disables interrupts to
|
||||
level N (N) before the execution of this section and restores them
|
||||
to the previous level upon completion of the section. RTEMS uses the
|
||||
instructions CLI and STI to enable and disable Interrupts. Emulation,
|
||||
Reset, NMI and Exception Interrupts are never disabled.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The AVR Architecture works with two different kind of stacks,
|
||||
User and Supervisor Stack. Since RTEMS and its Application run
|
||||
in supervisor mode, all interrupts will use the interrupted
|
||||
tasks stack for execution.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for the AVR performs the following
|
||||
actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables processor interrupts,
|
||||
@item places the error code in @b{r0}, and
|
||||
@item executes an infinite loop (@code{while(0);} to
|
||||
simulate a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not supported due to a broken tool chain.
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
TBD
|
||||
@@ -1,146 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2006.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Blackfin Specific Information
|
||||
|
||||
This chapter discusses the Blackfin architecture dependencies in this
|
||||
port of RTEMS.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the Blackfin architecture, refer to the following
|
||||
documents available from Analog Devices.
|
||||
|
||||
TBD
|
||||
|
||||
@itemize @bullet
|
||||
@item @cite{"ADSP-BF533 Blackfin Processor Hardware Reference."}
|
||||
@file{http://www.analog.com/UploadedFiles/Associated_Docs/892485982bf533_hwr.pdf}
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
CPUs of the Blackfin 53X only differ in the peripherals and thus in the
|
||||
device drivers. This port does not yet support the 56X dual core variants.
|
||||
|
||||
@subsection Count Leading Zeroes Instruction
|
||||
|
||||
The Blackfin CPU has the BITTST instruction which could be used to speed
|
||||
up the find first bit operation. The use of this instruction should
|
||||
significantly speed up the scheduling associated with a thread blocking.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
This section is heavily based on content taken from the Blackfin uCLinux
|
||||
documentation wiki which is edited by Analog Devices and Arcturus
|
||||
Networks. @file{http://docs.blackfin.uclinux.org/}
|
||||
|
||||
@subsection Processor Background
|
||||
|
||||
The Blackfin architecture supports a simple call and return mechanism.
|
||||
A subroutine is invoked via the call (@code{call}) instruction.
|
||||
This instruction saves the return address in the @code{RETS} register
|
||||
and transfers the execution to the given address.
|
||||
|
||||
It is the called funcions responsability to use the link instruction
|
||||
to reserve space on the stack for the local variables. Returning from
|
||||
a subroutine is done by using the RTS (@code{RTS}) instruction which
|
||||
loads the PC with the adress stored in RETS.
|
||||
|
||||
It is is important to note that the @code{call} instruction 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.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
A called function may clobber all registers, except RETS, R4-R7, P3-P5,
|
||||
FP and SP. It may also modify the first 12 bytes in the caller’s stack
|
||||
frame which is used as an argument area for the first three arguments
|
||||
(which are passed in R0...R3 but may be placed on the stack by the
|
||||
called function).
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
RTEMS assumes that the Blackfin GCC calling convention is followed.
|
||||
The first three parameters are stored in registers R0, R1, and R2.
|
||||
All other parameters are put pushed on the stack. The result is returned
|
||||
through register R0.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
The Blackfin family architecutre support a single unified 4 GB byte
|
||||
address space using 32-bit addresses. It maps all resources like internal
|
||||
and external memory and IO registers into separate sections of this
|
||||
common address space.
|
||||
|
||||
The Blackfin architcture supports some form of memory
|
||||
protection via its Memory Management Unit. Since the
|
||||
Blackfin port runs in supervisior mode this memory
|
||||
protection mechanisms are not used.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
Discussed in this chapter are the Blackfin's interrupt response and
|
||||
control mechanisms as they pertain to RTEMS. The Blackfin architecture
|
||||
support 16 kinds of interrupts broken down into Core and general-purpose
|
||||
interrupts.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
RTEMS maps levels 0 -15 directly to Blackfins event vectors EVT0 -
|
||||
EVT15. Since EVT0 - EVT6 are core events and it is suggested to use
|
||||
EVT15 and EVT15 for Software interrupts, 7 Interrupts (EVT7-EVT13)
|
||||
are left for periferical use.
|
||||
|
||||
When installing an RTEMS interrupt handler RTEMS installs a generic
|
||||
Interrupt Handler which saves some context and enables nested interrupt
|
||||
servicing and then vectors to the users interrupt handler.
|
||||
|
||||
@subsection Disabling of Interrupts by RTEMS
|
||||
|
||||
During interrupt disable critical sections, RTEMS disables interrupts to
|
||||
level four (4) before the execution of this section and restores them
|
||||
to the previous level upon completion of the section. RTEMS uses the
|
||||
instructions CLI and STI to enable and disable Interrupts. Emulation,
|
||||
Reset, NMI and Exception Interrupts are never disabled.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The Blackfin Architecture works with two different kind of stacks,
|
||||
User and Supervisor Stack. Since RTEMS and its Application run
|
||||
in supervisor mode, all interrupts will use the interrupted
|
||||
tasks stack for execution.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for the Blackfin performs the following
|
||||
actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables processor interrupts,
|
||||
@item places the error code in @b{r0}, and
|
||||
@item executes an infinite loop (@code{while(0);} to
|
||||
simulate a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
TBD
|
||||
@@ -1,123 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename cpu_supplement.info
|
||||
@setcontentsaftertitlepage
|
||||
@syncodeindex vr fn
|
||||
@synindex ky cp
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2013.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c Master file for the CPU Supplement
|
||||
@c
|
||||
|
||||
@include version.texi
|
||||
@include common/setup.texi
|
||||
@include common/rtems.texi
|
||||
|
||||
@ifset use-ascii
|
||||
@dircategory RTEMS Target Supplement
|
||||
@direntry
|
||||
* RTEMS CPU Architecture Supplement: (cpu_supplement).
|
||||
@end direntry
|
||||
@end ifset
|
||||
|
||||
@c
|
||||
@c Title Page Stuff
|
||||
@c
|
||||
|
||||
@c
|
||||
@c I don't really like having a short title page. --joel
|
||||
@c
|
||||
@c @shorttitlepage RTEMS CPU Architecture Supplement
|
||||
|
||||
@setchapternewpage odd
|
||||
@settitle RTEMS CPU Architecture Supplement
|
||||
@titlepage
|
||||
@finalout
|
||||
|
||||
@title RTEMS CPU Architecture Supplement
|
||||
@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION}
|
||||
@sp 1
|
||||
@subtitle @value{UPDATED}
|
||||
@author On-Line Applications Research Corporation
|
||||
@page
|
||||
@include common/cpright.texi
|
||||
@end titlepage
|
||||
|
||||
@c This prevents a black box from being printed on "overflow" lines.
|
||||
@c The alternative is to rework a sentence to avoid this problem.
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top, Preface, (dir), (dir)
|
||||
@top RTEMS CPU Architecture Supplement
|
||||
|
||||
@menu
|
||||
* Preface::
|
||||
* Port Specific Information::
|
||||
* ARM Specific Information::
|
||||
* Atmel AVR Specific Information::
|
||||
* Blackfin Specific Information::
|
||||
* Epiphany Specific Information::
|
||||
* Renesas H8/300 Specific Information::
|
||||
* Intel/AMD x86 Specific Information::
|
||||
* Lattice Mico32 Specific Information::
|
||||
* Renesas M32C Specific Information::
|
||||
* Renesas M32R Specific Information::
|
||||
* M68xxx and Coldfire Specific Information::
|
||||
* Xilinx MicroBlaze Specific Information::
|
||||
* MIPS Specific Information::
|
||||
* OpenRISC 1000 Specific Information::
|
||||
* Altera Nios II Specific Information::
|
||||
* PowerPC Specific Information::
|
||||
* SuperH Specific Information::
|
||||
* SPARC Specific Information::
|
||||
* SPARC-64 Specific Information::
|
||||
* Command and Variable Index::
|
||||
* Concept Index::
|
||||
@end menu
|
||||
@end ifnottex
|
||||
|
||||
@include preface.texi
|
||||
@include general.texi
|
||||
@include arm.texi
|
||||
@include avr.texi
|
||||
@include bfin.texi
|
||||
@include epiphany.texi
|
||||
@include h8300.texi
|
||||
@include i386.texi
|
||||
@include lm32.texi
|
||||
@include m32c.texi
|
||||
@include m32r.texi
|
||||
@include m68k.texi
|
||||
@include microblaze.texi
|
||||
@include mips.texi
|
||||
@include nios2.texi
|
||||
@include or1k.texi
|
||||
@include powerpc.texi
|
||||
@include sh.texi
|
||||
@include sparc.texi
|
||||
@include sparc64.texi
|
||||
|
||||
@node Command and Variable Index, Concept Index, , Top
|
||||
@unnumbered Command and Variable Index
|
||||
|
||||
There are currently no Command and Variable Index entries.
|
||||
|
||||
@c @printindex fn
|
||||
|
||||
@node Concept Index, , Command and Variable Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
There are currently no Concept Index entries.
|
||||
@c @printindex cp
|
||||
|
||||
@bye
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
@c
|
||||
@c Copyright (c) 2015 University of York.
|
||||
@c Hesham ALMatary <hmka501@york.ac.uk>
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Epiphany Specific Information
|
||||
|
||||
This chapter discusses the
|
||||
@uref{http://adapteva.com/docs/epiphany_sdk_ref.pdf, Epiphany Architecture}
|
||||
dependencies in this port of RTEMS. Epiphany is a chip that can come with 16 and
|
||||
64 cores, each of which can run RTEMS separately or they can work together to
|
||||
run a SMP RTEMS application.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the Epiphany architecture refer to the
|
||||
@uref{http://adapteva.com/docs/epiphany_arch_ref.pdf,Epiphany Architecture Reference}.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
Please refer to the
|
||||
@uref{http://adapteva.com/docs/epiphany_sdk_ref.pdf, Epiphany SDK}
|
||||
Appendix A: Application Binary Interface
|
||||
|
||||
@subsection Floating Point Unit
|
||||
|
||||
A floating point unit is currently not supported.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
A flat 32-bit memory model is supported, no caches. Each core has its own 32 KiB
|
||||
strictly ordered local memory along with an access to a shared 32 MiB external
|
||||
DRAM.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
Every Epiphany core has 10 exception types:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Reset
|
||||
@item Software Exception
|
||||
@item Data Page Fault
|
||||
@item Timer 0
|
||||
@item Timer 1
|
||||
@item Message Interrupt
|
||||
@item DMA0 Interrupt
|
||||
@item DMA1 Interrupt
|
||||
@item WANT Interrupt
|
||||
@item User Interrupt
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
There are only two levels: interrupts enabled and interrupts disabled.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The Epiphany RTEMS port uses a dedicated software interrupt stack.
|
||||
The stack for interrupts is allocated during interrupt driver initialization.
|
||||
When an interrupt is entered, the _ISR_Handler routine is responsible for
|
||||
switching from the interrupted task stack to RTEMS software interrupt stack.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture performs the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables operating system supported interrupts (IRQ),
|
||||
@item places the error code in @code{r0}, and
|
||||
@item executes an infinite loop to simulate a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
@@ -1,455 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Port Specific Information
|
||||
|
||||
This chaper provides a general description of the type of
|
||||
architecture specific information which is in each of
|
||||
the architecture specific chapters that follow. The outline
|
||||
of this chapter is identical to that of the architecture
|
||||
specific chapters.
|
||||
|
||||
In each of the architecture specific chapters, this
|
||||
introductory section will provide an overview of the
|
||||
architecture
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
In each of the architecture specific chapters, this
|
||||
section will provide pointers on where to obtain
|
||||
documentation.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
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 PowerPC are based on an architectural specification
|
||||
which is independent or any particular CPU model or implementation.
|
||||
Older families such as the Motorola 68000 and the Intel x86 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.
|
||||
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/CPU/rtems/score/cpu.h} based upon the GNU tools
|
||||
multilib variant that is appropriate for the particular CPU model defined
|
||||
on the compilation command line.
|
||||
|
||||
In each of the architecture specific chapters, this section presents
|
||||
the set of features which vary across various implementations of the
|
||||
architecture that may be of importance to RTEMS application developers.
|
||||
|
||||
The subsections will vary amongst the target architecture chapters as
|
||||
the specific features may vary. However, each port will include a few
|
||||
common features such as the CPU Model Name and presence of a hardware
|
||||
Floating Point Unit. The common features are described here.
|
||||
|
||||
@subsection CPU Model Name
|
||||
|
||||
The macro @code{CPU_MODEL_NAME} is a string which designates
|
||||
the name of this CPU model. For example, for the MC68020
|
||||
processor model from the m68k architecture, this macro
|
||||
is set to the string "mc68020".
|
||||
|
||||
@subsection Floating Point Unit
|
||||
|
||||
In most architectures, the presence of a floating point unit is an option.
|
||||
It does not matter whether the hardware floating point support is
|
||||
incorporated on-chip or is an external coprocessor as long as it
|
||||
appears an FPU per the ISA. However, if a hardware FPU is not present,
|
||||
it is possible that the floating point emulation library for this
|
||||
CPU is not reentrant and thus context switched by RTEMS.
|
||||
|
||||
RTEMS provides two feature macros to indicate the FPU configuration:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item CPU_HARDWARE_FP
|
||||
is set to TRUE to indicate that a hardware FPU is present.
|
||||
|
||||
@item CPU_SOFTWARE_FP
|
||||
is set to TRUE to indicate that a hardware FPU is not present and that
|
||||
the FP software emulation will be context switched.
|
||||
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Multilibs
|
||||
|
||||
Newlib and GCC provide several target libraries like the @file{libc.a},
|
||||
@file{libm.a} and @file{libgcc.a}. These libraries are artifacts of the GCC
|
||||
build process. Newlib is built together with GCC. To provide optimal support
|
||||
for various chip derivatives and instruction set revisions multiple variants of
|
||||
these libraries are available for each architecture. For example one set may
|
||||
use software floating point support and another set may use hardware floating
|
||||
point instructions. These sets of libraries are called @emph{multilibs}. Each
|
||||
library set corresponds to an application binary interface (ABI) and
|
||||
instruction set.
|
||||
|
||||
A multilib variant can be usually detected via built-in compiler defines at
|
||||
compile-time. This mechanism is used by RTEMS to select for example the
|
||||
context switch support for a particular BSP. The built-in compiler defines
|
||||
corresponding to multilibs are the only architecture specific defines allowed
|
||||
in the @code{cpukit} area of the RTEMS sources.
|
||||
|
||||
Invoking the GCC with the @code{-print-multi-lib} option lists the available
|
||||
multilibs. Each line of the output describes one multilib variant. The
|
||||
default variant is denoted by @code{.} which is selected when no or
|
||||
contradicting GCC machine options are selected. The multilib selection for a
|
||||
target is specified by target makefile fragments (see file @file{t-rtems} in
|
||||
the GCC sources and section
|
||||
@uref{https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment,The Target Makefile Fragment}
|
||||
in the @uref{https://gcc.gnu.org/onlinedocs/gccint/,GCC Internals Manual}.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Calling Conventions
|
||||
|
||||
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.
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
describe the instruction(s) used to perform a @i{normal} subroutine
|
||||
invocation. All RTEMS directives are invoked as @i{normal} C language
|
||||
functions so it is important to the user application to understand the
|
||||
call and return mechanism.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
detail the set of registers which are @b{NOT} preserved across subroutine
|
||||
invocations. The registers which are not preserved are assumed to be
|
||||
available for use as scratch registers. Therefore, the contents of these
|
||||
registers should not be assumed upon return from any RTEMS directive.
|
||||
|
||||
In some architectures, there may be a set of registers made available
|
||||
automatically as a side-effect of the subroutine invocation
|
||||
mechanism.
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
describe the mechanism by which the parameters or arguments are passed
|
||||
by the caller to a subroutine. In some architectures, all parameters
|
||||
are passed on the stack while in others some are passed in registers.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Memory Model
|
||||
|
||||
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.
|
||||
|
||||
@subsection Flat Memory Model
|
||||
|
||||
Most RTEMS target processors can be initialized to support a flat address
|
||||
space. Although the size of addresses varies between architectures, on
|
||||
most RTEMS targets, an address is 32-bits wide which defines 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 may be performed in little or
|
||||
big endian fashion.
|
||||
|
||||
On smaller CPU architectures supported by RTEMS, the address space
|
||||
may only be 20 or 24 bits wide.
|
||||
|
||||
If the CPU model has support for virtual memory or segmentation, it is
|
||||
the responsibility of the Board Support Package (BSP) to initialize the
|
||||
MMU hardware to perform address translations which correspond to flat
|
||||
memory model.
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
describe any architecture characteristics that differ from this general
|
||||
description.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Interrupt Processing
|
||||
|
||||
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.
|
||||
|
||||
RTEMS supports a dedicated interrupt stack for all architectures.
|
||||
On architectures with hardware support for a dedicated interrupt stack,
|
||||
it will be initialized such that when an interrupt occurs, the processor
|
||||
automatically switches to this dedicated stack. On architectures without
|
||||
hardware support for a dedicated interrupt stack which is separate from
|
||||
those of the tasks, RTEMS will support switching to a dedicated stack
|
||||
for interrupt processing.
|
||||
|
||||
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.
|
||||
|
||||
A nested interrupt is processed similarly with the exception that since
|
||||
the CPU is already executing on the interrupt stack, there is no need
|
||||
to switch to the interrupt stack.
|
||||
|
||||
In some configurations, RTEMS allocates the interrupt stack from the
|
||||
Workspace Area. The amount of memory allocated for the interrupt stack
|
||||
is user configured and based upon the @code{confdefs.h} parameter
|
||||
@code{CONFIGURE_INTERRUPT_STACK_SIZE}. This parameter is described
|
||||
in detail in the Configuring a System chapter of the User's Guide.
|
||||
On configurations in which RTEMS allocates the interrupt stack, during
|
||||
the initialization process, RTEMS will also install its interrupt stack.
|
||||
In other configurations, the interrupt stack is allocated and installed
|
||||
by the Board Support Package (BSP).
|
||||
|
||||
In each of the architecture specific chapters, this section discesses
|
||||
the interrupt response and control mechanisms of the architecture as
|
||||
they pertain to RTEMS.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
describe the architecture specific details of the interrupt vectoring
|
||||
process. In particular, it should include a description of the
|
||||
Interrupt Stack Frame (ISF).
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
In each of the architecture specific chapters, this subsection will
|
||||
describe how the interrupt levels available on this particular architecture
|
||||
are mapped onto the 255 reserved in the task mode. The interrupt level
|
||||
value of zero (0) should always mean that interrupts are enabled.
|
||||
|
||||
Any use of an interrupt level that is is not undefined on a particular
|
||||
architecture may result in behavior that is unpredictable.
|
||||
|
||||
@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
|
||||
external interrupts before the execution of this section and restores
|
||||
them to the previous level upon completion of the section. RTEMS has
|
||||
been optimized to ensure that interrupts are disabled for the shortest
|
||||
number of instructions possible. Since the precise number of instructions
|
||||
and their execution time varies based upon target CPU family, CPU model,
|
||||
board memory speed, compiler version, and optimization level, it is
|
||||
not practical to provide the precise number for all possible RTEMS
|
||||
configurations.
|
||||
|
||||
Historically, the measurements were made by hand analyzing and counting
|
||||
the execution time of instruction sequences during interrupt disable
|
||||
critical sections. For reference purposes, on a 16 Mhz Motorola
|
||||
MC68020, the maximum interrupt disable period was typically approximately
|
||||
ten (10) to thirteen (13) microseconds. This architecture was memory bound
|
||||
and had a slow bit scan instruction. In contrast, during the same
|
||||
period a 14 Mhz SPARC would have a worst case disable time of approximately
|
||||
two (2) to three (3) microseconds because it had a single cycle bit scan
|
||||
instruction and used fewer cycles for memory accesses.
|
||||
|
||||
If you are interested in knowing the worst case execution time for
|
||||
a particular version of RTEMS, please contact OAR Corporation and
|
||||
we will be happy to product the results as a consulting service.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
Upon detection of a fatal error by either the application or RTEMS during
|
||||
initialization the @code{rtems_fatal_error_occurred} directive supplied
|
||||
by 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 or all of them return without taking action to
|
||||
shutdown the processor or reset, a default fatal error handler is invoked.
|
||||
|
||||
Most of the action performed as part of processing the fatal error are
|
||||
described in detail in the Fatal Error Manager chapter in the User's
|
||||
Guide. However, the if no user provided extension or BSP specific fatal
|
||||
error handler takes action, the final default action is to invoke a
|
||||
CPU architecture specific function. Typically this function disables
|
||||
interrupts and halts the processor.
|
||||
|
||||
In each of the architecture specific chapters, this describes the precise
|
||||
operations of the default CPU specific fatal error handler.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
This section contains information about the Symmetric Multiprocessing (SMP)
|
||||
status of a particular architecture.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
In order to support thread-local storage (TLS) the CPU port must implement the
|
||||
facilities mandated by the application binary interface (ABI) of the CPU
|
||||
architecture. The CPU port must initialize the TLS area in the
|
||||
@code{_CPU_Context_Initialize()} function. There are support functions available
|
||||
via @code{#include <rtems/score/tls.h>} which implement Variants I and II
|
||||
according to Ulrich Drepper, @cite{ELF Handling For Thread-Local Storage}.
|
||||
|
||||
@table @code
|
||||
|
||||
@item _TLS_TCB_at_area_begin_initialize()
|
||||
Uses Variant I, TLS offsets emitted by linker takes the TCB into account. For
|
||||
a reference implementation see @file{cpukit/score/cpu/arm/cpu.c}.
|
||||
|
||||
@item _TLS_TCB_before_TLS_block_initialize()
|
||||
Uses Variant I, TLS offsets emitted by linker neglects the TCB. For a
|
||||
reference implementation see
|
||||
@file{c/src/lib/libcpu/powerpc/new-exceptions/cpu.c}.
|
||||
|
||||
@item _TLS_TCB_after_TLS_block_initialize()
|
||||
Uses Variant II. For a reference implementation see
|
||||
@file{cpukit/score/cpu/sparc/cpu.c}.
|
||||
|
||||
@end table
|
||||
|
||||
The board support package (BSP) must provide the following sections and symbols
|
||||
in its linker command file:
|
||||
|
||||
@example
|
||||
.tdata : @{
|
||||
_TLS_Data_begin = .;
|
||||
*(.tdata .tdata.* .gnu.linkonce.td.*)
|
||||
_TLS_Data_end = .;
|
||||
@}
|
||||
.tbss : @{
|
||||
_TLS_BSS_begin = .;
|
||||
*(.tbss .tbss.* .gnu.linkonce.tb.*) *(.tcommon)
|
||||
_TLS_BSS_end = .;
|
||||
@}
|
||||
_TLS_Data_size = _TLS_Data_end - _TLS_Data_begin;
|
||||
_TLS_Data_begin = _TLS_Data_size != 0 ? _TLS_Data_begin : _TLS_BSS_begin;
|
||||
_TLS_Data_end = _TLS_Data_size != 0 ? _TLS_Data_end : _TLS_BSS_begin;
|
||||
_TLS_BSS_size = _TLS_BSS_end - _TLS_BSS_begin;
|
||||
_TLS_Size = _TLS_BSS_end - _TLS_Data_begin;
|
||||
_TLS_Alignment = MAX (ALIGNOF (.tdata), ALIGNOF (.tbss));
|
||||
@end example
|
||||
|
||||
@section CPU counter
|
||||
|
||||
The CPU support must implement the CPU counter interface. A CPU counter is
|
||||
some free-running counter. It ticks usually with a frequency close to the CPU
|
||||
or system bus clock. On some architectures the actual implementation is board
|
||||
support package dependent. The CPU counter is used for profiling of low-level
|
||||
functions. It is also used to implement two busy wait functions
|
||||
@code{rtems_counter_delay_ticks()} and @code{rtems_counter_delay_nanoseconds()}
|
||||
which may be used in device drivers. It may be also used as an entropy source
|
||||
for random number generators.
|
||||
|
||||
The CPU counter interface uses a CPU port specific unsigned integer type
|
||||
@code{CPU_Counter_ticks} to represent CPU counter values. The CPU port must
|
||||
provide the following two functions
|
||||
|
||||
@itemize
|
||||
@item @code{_CPU_Counter_read()} to read the current CPU counter value, and
|
||||
@item @code{_CPU_Counter_difference()} to get the difference between two CPU
|
||||
counter values.
|
||||
@end itemize
|
||||
|
||||
@section Interrupt Profiling
|
||||
|
||||
The RTEMS profiling needs support by the CPU port for the interrupt entry and
|
||||
exit times. In case profiling is enabled via the RTEMS build configuration
|
||||
option @code{--enable-profiling} (in this case the pre-processor symbol
|
||||
@code{RTEMS_PROFILING} is defined) the CPU port may provide data for the
|
||||
interrupt entry and exit times of the outer-most interrupt. The CPU port can
|
||||
feed interrupt entry and exit times with the
|
||||
@code{_Profiling_Outer_most_interrupt_entry_and_exit()} function
|
||||
(@code{#include <rtems/score/profiling.h>}). For an example please have a look
|
||||
at @code{cpukit/score/cpu/arm/arm_exc_interrupt.S}.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
An RTEMS Board Support Package (BSP) must be designed to support a
|
||||
particular processor model and target board combination.
|
||||
|
||||
In each of the architecture specific chapters, this section will present
|
||||
a discussion of architecture specific BSP issues. For more information
|
||||
on developing a BSP, refer to BSP and Device Driver Development Guide
|
||||
and the chapter titled Board Support Packages in the RTEMS
|
||||
Applications User's Guide.
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated or re-initiated when the processor
|
||||
is reset or transfer is passed to it from a boot monitor or ROM monitor.
|
||||
|
||||
In each of the architecture specific chapters, this subsection describes
|
||||
the actions that the BSP must tak assuming the application gets control
|
||||
when the microprocessor is reset.
|
||||
@@ -1,11 +0,0 @@
|
||||
@c Copyright (c) 2014 embedded brains GmbH. All rights reserved.
|
||||
|
||||
@chapter Renesas H8/300 Specific Information
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,373 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Intel/AMD x86 Specific Information
|
||||
|
||||
This chapter discusses the Intel x86 architecture dependencies
|
||||
in this port of RTEMS. This family has multiple implementations
|
||||
from multiple vendors and suffers more from having evolved rather
|
||||
than being designed for growth.
|
||||
|
||||
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
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This section presents the set of features which vary
|
||||
across i386 implementations and are of importance to RTEMS.
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/i386/i386.h} based upon the particular CPU
|
||||
model specified on the compilation command line.
|
||||
|
||||
@subsection bswap Instruction
|
||||
|
||||
The macro @code{I386_HAS_BSWAP} is set to 1 to indicate that
|
||||
this CPU model has the @code{bswap} instruction which
|
||||
endian swaps a thirty-two bit quantity. This instruction
|
||||
appears to be present in all CPU models
|
||||
i486's and above.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Calling Conventions
|
||||
|
||||
@subsection Processor Background
|
||||
|
||||
The i386 architecture supports a simple yet effective
|
||||
call and return mechanism. A subroutine is invoked via the call
|
||||
(@code{call}) instruction. This instruction pushes the return address
|
||||
on the stack. The return from subroutine (@code{ret}) instruction pops
|
||||
the return address off the current stack and transfers control
|
||||
to that instruction. It is is important to note that the i386
|
||||
call and return mechanism does not automatically save or restore
|
||||
any registers. It is the responsibility of the high-level
|
||||
language compiler to define the register preservation and usage
|
||||
convention.
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
All RTEMS directives are invoked using a call instruction and return to
|
||||
the user application via the ret instruction.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
As discussed above, the call instruction does not automatically save
|
||||
any registers. RTEMS uses the registers EAX, ECX, and EDX as scratch
|
||||
registers. These registers are not preserved by RTEMS directives
|
||||
therefore, the contents of these registers should not be assumed upon
|
||||
return from any RTEMS directive.
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
RTEMS assumes that arguments are placed on the
|
||||
current stack before the directive is invoked via the call
|
||||
instruction. The first argument is assumed to be closest to the
|
||||
return address on the stack. This means that the first argument
|
||||
of the C calling sequence is pushed last. The following
|
||||
pseudo-code illustrates the typical sequence used to call a
|
||||
RTEMS directive with three (3) arguments:
|
||||
|
||||
@example
|
||||
push third argument
|
||||
push second argument
|
||||
push first argument
|
||||
invoke directive
|
||||
remove arguments from the stack
|
||||
@end example
|
||||
|
||||
The arguments to RTEMS are typically pushed onto the
|
||||
stack using a push instruction. These arguments must be removed
|
||||
from the stack after control is returned to the caller. This
|
||||
removal is typically accomplished by adding the size of the
|
||||
argument list in bytes to the stack pointer.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Memory Model
|
||||
|
||||
@subsection 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).
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
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.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@subsection Interrupt Stack Frame
|
||||
|
||||
The structure of the Interrupt Stack Frame for the
|
||||
i386 which is placed on the interrupt stack by the processor in
|
||||
response to an interrupt is as follows:
|
||||
|
||||
@ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
+----------------------+
|
||||
| Old EFLAGS Register | ESP+8
|
||||
+----------+-----------+
|
||||
| UNUSED | Old CS | ESP+4
|
||||
+----------+-----------+
|
||||
| Old EIP | ESP
|
||||
+----------------------+
|
||||
@end group
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@sp 1
|
||||
@tex
|
||||
\centerline{\vbox{\offinterlineskip\halign{
|
||||
\strut\vrule#&
|
||||
\hbox to 1.00in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 1.00in{\enskip\hfil#\hfil}&
|
||||
\vrule#&
|
||||
\hbox to 0.75in{\enskip\hfil#\hfil}
|
||||
\cr
|
||||
\multispan{4}\hrulefill\cr
|
||||
& \multispan{3} Old EFLAGS Register\quad&&ESP+8\cr
|
||||
\multispan{4}\hrulefill\cr
|
||||
&UNUSED &&Old CS &&ESP+4\cr
|
||||
\multispan{4}\hrulefill\cr
|
||||
& \multispan{3} Old EIP && ESP\cr
|
||||
\multispan{4}\hrulefill\cr
|
||||
}}\hfil}
|
||||
@end tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<CENTER>
|
||||
<TABLE COLS=3 WIDTH="40%" BORDER=2>
|
||||
<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EFLAGS Register</STRONG></TD>
|
||||
<TD ALIGN=center>0x0</TD></TR>
|
||||
<TR><TD ALIGN=center><STRONG>UNUSED</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Old CS</STRONG></TD>
|
||||
<TD ALIGN=center>0x2</TD></TR>
|
||||
<TR><TD ALIGN=center COLSPAN=2><STRONG>Old EIP</STRONG></TD>
|
||||
<TD ALIGN=center>0x4</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture disables processor
|
||||
interrupts, places the error code in EAX, and executes a HLT instruction
|
||||
to halt the processor.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated when the i386 processor is reset.
|
||||
When the i386 is reset,
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item The EAX register is set to indicate the results of the processor's
|
||||
power-up self test. If the self-test was not executed, the contents of
|
||||
this register are undefined. Otherwise, a non-zero value indicates the
|
||||
processor is faulty and a zero value indicates a successful self-test.
|
||||
|
||||
@item The DX register holds a component identifier and revision level. DH
|
||||
contains 3 to indicate an i386 component and DL contains a unique revision
|
||||
level indicator.
|
||||
|
||||
@item Control register zero (CR0) is set such that the processor is in real
|
||||
mode with paging disabled. Other portions of CR0 are used to indicate the
|
||||
presence of a numeric coprocessor.
|
||||
|
||||
@item All bits in the extended flags register (EFLAG) which are not
|
||||
permanently set are cleared. This inhibits all maskable interrupts.
|
||||
|
||||
@item The Interrupt Descriptor Register (IDTR) is set to point at address
|
||||
zero.
|
||||
|
||||
@item All segment registers are set to zero.
|
||||
|
||||
@item The instruction pointer is set to 0x0000FFF0. The first instruction
|
||||
executed after a reset is actually at 0xFFFFFFF0 because the i386 asserts
|
||||
the upper twelve address until the first intersegment (FAR) JMP or CALL
|
||||
instruction. When a JMP or CALL is executed, the upper twelve address
|
||||
lines are lowered and the processor begins executing in the first megabyte
|
||||
of memory.
|
||||
|
||||
@end itemize
|
||||
|
||||
Typically, an intersegment JMP to the application's initialization code is
|
||||
placed at address 0xFFFFFFF0.
|
||||
|
||||
@subsection Processor Initialization
|
||||
|
||||
This initialization code is responsible for initializing all data
|
||||
structures required by the i386 in protected mode and for actually entering
|
||||
protected mode. The i386 must be placed in protected mode and the segment
|
||||
registers and associated selectors must be initialized before the
|
||||
initialize_executive directive is invoked.
|
||||
|
||||
The initialization code is responsible for initializing the Global
|
||||
Descriptor Table such that the i386 is in the thirty-two bit flat memory
|
||||
model with paging disabled. In this mode, the i386 automatically converts
|
||||
every address from a logical to a physical address each time it is used.
|
||||
For more information on the memory model used by RTEMS, please refer to the
|
||||
Memory Model chapter in this document.
|
||||
|
||||
Since the processor is in real mode upon reset, the processor must be
|
||||
switched to protected mode before RTEMS can execute. Before switching to
|
||||
protected mode, at least one descriptor table and two descriptors must be
|
||||
created. Descriptors are needed for a code segment and a data segment. (
|
||||
This will give you the flat memory model.) The stack can be placed in a
|
||||
normal read/write data segment, so no descriptor for the stack is needed.
|
||||
Before the GDT can be used, the base address and limit must be loaded into
|
||||
the GDTR register using an LGDT instruction.
|
||||
|
||||
If the hardware allows an NMI to be generated, you need to create the IDT
|
||||
and a gate for the NMI interrupt handler. Before the IDT can be used, the
|
||||
base address and limit for the idt must be loaded into the IDTR register
|
||||
using an LIDT instruction.
|
||||
|
||||
Protected mode is entered by setting thye PE bit in the CR0 register.
|
||||
Either a LMSW or MOV CR0 instruction may be used to set this bit. Because
|
||||
the processor overlaps the interpretation of several instructions, it is
|
||||
necessary to discard the instructions from the read-ahead cache. A JMP
|
||||
instruction immediately after the LMSW changes the flow and empties the
|
||||
processor if intructions which have been pre-fetched and/or decoded. At
|
||||
this point, the processor is in protected mode and begins to perform
|
||||
protected mode application initialization.
|
||||
|
||||
If the application requires that the IDTR be some value besides zero, then
|
||||
it should set it to the required value at this point. All tasks share the
|
||||
same i386 IDTR value. Because interrupts are enabled automatically by
|
||||
RTEMS as part of the initialize_executive directive, the IDTR MUST be set
|
||||
properly before this directive is invoked to insure correct interrupt
|
||||
vectoring. If processor caching is to be utilized, then it should be
|
||||
enabled during the reset application initialization code. The reset code
|
||||
which is executed before the call to initialize_executive has the following
|
||||
requirements:
|
||||
|
||||
For more information regarding the i386 data structures and their
|
||||
contents, refer to Intel's 386 Programmer's Reference Manual.
|
||||
|
||||
@@ -1,192 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
@c Jukka Pietarinen <jukka.pietarinen@mrf.fi>, 2008,
|
||||
@c Micro-Research Finland Oy
|
||||
@c
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter Lattice Mico32 Specific Information
|
||||
|
||||
This chaper discusses the Lattice Mico32 architecture dependencies in
|
||||
this port of RTEMS. The Lattice Mico32 is a 32-bit Harvard, RISC
|
||||
architecture "soft" microprocessor, available for free with an open IP
|
||||
core licensing agreement. Although mainly targeted for Lattice FPGA
|
||||
devices the microprocessor can be implemented on other vendors' FPGAs,
|
||||
too.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the Lattice Mico32 architecture, refer to the
|
||||
following documents available from Lattice Semiconductor
|
||||
@file{http://www.latticesemi.com/}.
|
||||
|
||||
@itemize @bullet
|
||||
@item @cite{"LatticeMico32 Processor Reference Manual"}
|
||||
@file{http://www.latticesemi.com/dynamic/view_document.cfm?document_id=20890}
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
The Lattice Mico32 architecture allows for different configurations of
|
||||
the processor. This port is based on the assumption that the following options are implemented:
|
||||
|
||||
@itemize @bullet
|
||||
@item hardware multiplier
|
||||
@item hardware divider
|
||||
@item hardware barrel shifter
|
||||
@item sign extension instructions
|
||||
@item instruction cache
|
||||
@item data cache
|
||||
@item debug
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Register Architecture
|
||||
|
||||
This section gives a brief introduction to the register architecture
|
||||
of the Lattice Mico32 processor.
|
||||
|
||||
The Lattice Mico32 is a RISC archictecture processor with a
|
||||
32-register file of 32-bit registers.
|
||||
|
||||
@multitable {Register Name} {general pupose / global pointer}
|
||||
@headitem Register Name @tab Function
|
||||
@item r0 @tab holds value zero
|
||||
@item r1-r25 @tab general purpose
|
||||
@item r26/gp @tab general pupose / global pointer
|
||||
@item r27/fp @tab general pupose / frame pointer
|
||||
@item r28/sp @tab stack pointer
|
||||
@item r29/ra @tab return address
|
||||
@item r30/ea @tab exception address
|
||||
@item r31/ba @tab breakpoint address
|
||||
@end multitable
|
||||
|
||||
Note that on processor startup all register values are undefined
|
||||
including r0, thus r0 has to be initialized to zero.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Calling Conventions
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
A call instruction places the return address to register r29 and a
|
||||
return from subroutine (ret) is actually a branch to r29/ra.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
A subroutine may freely use registers r1 to r10 which are @b{not}
|
||||
preserved across subroutine invocations.
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
When calling a C function the first eight arguments are stored in
|
||||
registers r1 to r8. Registers r1 and r2 hold the return value.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Memory Model
|
||||
|
||||
The Lattice Mico32 processor supports a flat memory model with a 4
|
||||
Gbyte address space with 32-bit addresses.
|
||||
|
||||
The following data types are supported:
|
||||
|
||||
@multitable {unsigned half-word} {Bits} {unsigned int / unsigned long}
|
||||
@headitem Type @tab Bits @tab C Compiler Type
|
||||
@item unsigned byte @tab 8 @tab unsigned char
|
||||
@item signed byte @tab 8 @tab char
|
||||
@item unsigned half-word @tab 16 @tab unsigned short
|
||||
@item signed half-word @tab 16 @tab short
|
||||
@item unsigned word @tab 32 @tab unsigned int / unsigned long
|
||||
@item signed word @tab 32 @tab int / long
|
||||
@end multitable
|
||||
|
||||
Data accesses need to be aligned, with unaligned accesses result are
|
||||
undefined.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Interrupt Processing
|
||||
|
||||
The Lattice Mico32 has 32 interrupt lines which are however served by
|
||||
only one exception vector. When an interrupt occurs following happens:
|
||||
|
||||
@itemize @bullet
|
||||
@item address of next instruction placed in r30/ea
|
||||
@item IE field of IE CSR saved to EIE field and IE field cleared preventing further exceptions from occuring.
|
||||
@item branch to interrupt exception address EBA CSR + 0xC0
|
||||
@end itemize
|
||||
|
||||
The interrupt exception handler determines from the state of the
|
||||
interrupt pending registers (IP CSR) and interrupt enable register (IE
|
||||
CSR) which interrupt to serve and jumps to the interrupt routine
|
||||
pointed to by the corresponding interrupt vector.
|
||||
|
||||
For now there is no dedicated interrupt stack so 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.
|
||||
|
||||
Nested interrupts are not supported.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
Upon detection of a fatal error by either the application or RTEMS during
|
||||
initialization the @code{rtems_fatal_error_occurred} directive supplied
|
||||
by 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 or all of them return without taking action to
|
||||
shutdown the processor or reset, a default fatal error handler is invoked.
|
||||
|
||||
Most of the action performed as part of processing the fatal error are
|
||||
described in detail in the Fatal Error Manager chapter in the User's
|
||||
Guide. However, the if no user provided extension or BSP specific fatal
|
||||
error handler takes action, the final default action is to invoke a
|
||||
CPU architecture specific function. Typically this function disables
|
||||
interrupts and halts the processor.
|
||||
|
||||
In each of the architecture specific chapters, this describes the precise
|
||||
operations of the default CPU specific fatal error handler.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
An RTEMS Board Support Package (BSP) must be designed to support a
|
||||
particular processor model and target board combination.
|
||||
|
||||
In each of the architecture specific chapters, this section will present
|
||||
a discussion of architecture specific BSP issues. For more information
|
||||
on developing a BSP, refer to BSP and Device Driver Development Guide
|
||||
and the chapter titled Board Support Packages in the RTEMS
|
||||
Applications User's Guide.
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated or re-initiated when the processor
|
||||
is reset.
|
||||
@@ -1,11 +0,0 @@
|
||||
@c Copyright (c) 2014 embedded brains GmbH. All rights reserved.
|
||||
|
||||
@chapter Renesas M32C Specific Information
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,11 +0,0 @@
|
||||
@c Copyright (c) 2014 embedded brains GmbH. All rights reserved.
|
||||
|
||||
@chapter Renesas M32R Specific Information
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,439 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter M68xxx and Coldfire Specific Information
|
||||
|
||||
This chapter discusses the Freescale (formerly Motorola) MC68xxx
|
||||
and Coldfire architectural dependencies. The MC68xxx family has a
|
||||
wide variety of CPU models within it based upon different CPU core
|
||||
implementations. Ignoring the Coldfire parts, 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.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the MC68xxx and Coldfire architecture, refer to the following documents available from Freescale website (@file{http//www.freescale.com/}):
|
||||
|
||||
@itemize @bullet
|
||||
@item @cite{M68000 Family Reference, Motorola, FR68K/D}.
|
||||
@item @cite{MC68020 User's Manual, Motorola, MC68020UM/AD}.
|
||||
@item @cite{MC68881/MC68882 Floating-Point Coprocessor User's Manual,
|
||||
Motorola, MC68881UM/AD}.
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
|
||||
This section presents the set of features which vary
|
||||
across m68k/Coldfire implementations that are of importance to RTEMS.
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/m68k/m68k.h} based upon the particular CPU
|
||||
model selected on the compilation command line.
|
||||
|
||||
@subsection BFFFO Instruction
|
||||
|
||||
The macro @code{M68K_HAS_BFFFO} is set to 1 to indicate that
|
||||
this CPU model has the bfffo instruction.
|
||||
|
||||
@subsection Vector Base Register
|
||||
|
||||
The macro @code{M68K_HAS_VBR} is set to 1 to indicate that
|
||||
this CPU model has a vector base register (vbr).
|
||||
|
||||
@subsection Separate Stacks
|
||||
|
||||
The macro @code{M68K_HAS_SEPARATE_STACKS} is set to 1 to
|
||||
indicate that this CPU model has separate interrupt, user, and
|
||||
supervisor mode stacks.
|
||||
|
||||
@subsection Pre-Indexing Address Mode
|
||||
|
||||
The macro @code{M68K_HAS_PREINDEXING} is set to 1 to indicate that
|
||||
this CPU model has the pre-indexing address mode.
|
||||
|
||||
@subsection Extend Byte to Long Instruction
|
||||
|
||||
The macro @code{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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Calling Conventions
|
||||
|
||||
The MC68xxx architecture supports a simple yet effective call and
|
||||
return mechanism. A subroutine is invoked via the branch to subroutine
|
||||
(@code{bsr}) or the jump to subroutine (@code{jsr}) instructions.
|
||||
These instructions push the return address on the current stack.
|
||||
The return from subroutine (@code{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.
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
All RTEMS directives are invoked using either a @code{bsr} or @code{jsr}
|
||||
instruction and return to the user application via the rts instruction.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
As discussed above, the @code{bsr} and @code{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.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Interrupt Processing
|
||||
|
||||
Discussed in this section are the MC68xxx's interrupt response and
|
||||
control mechanisms as they pertain to RTEMS.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
Depending on whether or not the particular CPU supports a separate
|
||||
interrupt stack, the MC68xxx family has two different interrupt handling
|
||||
models.
|
||||
|
||||
@subsubsection 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
|
||||
|
||||
@subsubsection 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
|
||||
<CENTER>
|
||||
<TABLE COLS=2 WIDTH="40%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Status Register</STRONG></TD>
|
||||
<TD ALIGN=center>0x0</TD></TR>
|
||||
<TR><TD ALIGN=center><STRONG>Program Counter High</STRONG></TD>
|
||||
<TD ALIGN=center>0x2</TD></TR>
|
||||
<TR><TD ALIGN=center><STRONG>Program Counter Low</STRONG></TD>
|
||||
<TD ALIGN=center>0x4</TD></TR>
|
||||
<TR><TD ALIGN=center><STRONG>Format/Vector Offset</STRONG></TD>
|
||||
<TD ALIGN=center>0x6</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
@subsection CPU Models Without VBR and RAM at 0
|
||||
|
||||
This is from a post by Zoltan Kocsi <zoltan@@bendor.com.au> and is
|
||||
a nice trick in certain situations. In his words:
|
||||
|
||||
I think somebody on this list asked about the interupt vector handling
|
||||
w/o VBR and RAM at 0. The usual trick is to initialise the vector table
|
||||
(except the first 2 two entries, of course) to point to the same location
|
||||
BUT you also add the vector number times 0x1000000 to them. That is,
|
||||
bits 31-24 contain the vector number and 23-0 the address of the common
|
||||
handler. Since the PC is 32 bit wide but the actual address bus is only
|
||||
24, the top byte will be in the PC but will be ignored when jumping onto
|
||||
your routine.
|
||||
|
||||
Then your common interrupt routine gets this info by loading the PC
|
||||
into some register and based on that info, you can jump to a vector in
|
||||
a vector table pointed by a virtual VBR:
|
||||
|
||||
@example
|
||||
//
|
||||
// Real vector table at 0
|
||||
//
|
||||
|
||||
.long initial_sp
|
||||
.long initial_pc
|
||||
.long myhandler+0x02000000
|
||||
.long myhandler+0x03000000
|
||||
.long myhandler+0x04000000
|
||||
...
|
||||
.long myhandler+0xff000000
|
||||
|
||||
|
||||
//
|
||||
// This handler will jump to the interrupt routine of which
|
||||
// the address is stored at VBR[ vector_no ]
|
||||
// The registers and stackframe will be intact, the interrupt
|
||||
// routine will see exactly what it would see if it was called
|
||||
// directly from the HW vector table at 0.
|
||||
//
|
||||
|
||||
.comm VBR,4,2 // This defines the 'virtual' VBR
|
||||
// From C: extern void *VBR;
|
||||
|
||||
myhandler: // At entry, PC contains the full vector
|
||||
move.l %d0,-(%sp) // Save d0
|
||||
move.l %a0,-(%sp) // Save a0
|
||||
lea 0(%pc),%a0 // Get the value of the PC
|
||||
move.l %a0,%d0 // Copy it to a data reg, d0 is VV??????
|
||||
swap %d0 // Now d0 is ????VV??
|
||||
and.w #0xff00,%d0 // Now d0 is ????VV00 (1)
|
||||
lsr.w #6,%d0 // Now d0.w contains the VBR table offset
|
||||
move.l VBR,%a0 // Get the address from VBR to a0
|
||||
move.l (%a0,%d0.w),%a0 // Fetch the vector
|
||||
move.l 4(%sp),%d0 // Restore d0
|
||||
move.l %a0,4(%sp) // Place target address to the stack
|
||||
move.l (%sp)+,%a0 // Restore a0, target address is on TOS
|
||||
ret // This will jump to the handler and
|
||||
// restore the stack
|
||||
|
||||
(1) If 'myhandler' is guaranteed to be in the first 64K, e.g. just
|
||||
after the vector table then that insn is not needed.
|
||||
|
||||
@end example
|
||||
|
||||
There are probably shorter ways to do this, but it I believe is enough
|
||||
to illustrate the trick. Optimisation is left as an exercise to the
|
||||
reader :-)
|
||||
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture disables processor
|
||||
interrupts to level 7, places the error code in D0, and executes a
|
||||
@code{stop} instruction to simulate a halt processor instruction.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is supported.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
@subsection 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
|
||||
|
||||
@subsection 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 context switch to the
|
||||
first task, the VBR MUST be set by either RTEMS of the BSP before this
|
||||
occurs ensure 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 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
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
@c Copyright (c) 2014 embedded brains GmbH. All rights reserved.
|
||||
|
||||
@chapter Xilinx MicroBlaze Specific Information
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,151 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter MIPS Specific Information
|
||||
|
||||
This chapter discusses the MIPS architecture dependencies
|
||||
in this port of RTEMS. The MIPS family has a wide variety
|
||||
of implementations by a wide range of vendors. Consequently,
|
||||
there are many, many CPU models within it.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
IDT docs are online at http://www.idt.com/products/risc/Welcome.html
|
||||
|
||||
For information on the XXX architecture, refer to the following documents
|
||||
available from VENDOR (@file{http//www.XXX.com/}):
|
||||
|
||||
@itemize @bullet
|
||||
@item @cite{XXX Family Reference, VENDOR, PART NUMBER}.
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This section presents the set of features which vary
|
||||
across MIPS implementations and are of importance to RTEMS.
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/mips/mips.h} based upon the particular CPU
|
||||
model specified on the compilation command line.
|
||||
|
||||
@subsection Another Optional Feature
|
||||
|
||||
The macro XXX
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
@subsection Processor Background
|
||||
|
||||
TBD
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
TBD
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
TBD
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
TBD
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Memory Model
|
||||
|
||||
@subsection Flat Memory Model
|
||||
|
||||
The MIPS 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 MIPS family members such as the support virtual memory and
|
||||
segmentation. RTEMS does not support virtual memory or
|
||||
segmentation on any of these family members.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
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 MIPS's
|
||||
interrupt response and control mechanisms as they pertain to
|
||||
RTEMS.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
Upon receipt of an interrupt the XXX family
|
||||
members with separate interrupt stacks automatically perform the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item TBD
|
||||
|
||||
@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.
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
TBD
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this target architecture disables
|
||||
processor interrupts, places the error code in @b{XXX}, and executes a
|
||||
@code{XXX} instruction to simulate a halt processor instruction.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Board Support Packages
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated or
|
||||
re-initiated when the processor is reset. When the
|
||||
processor is reset, it performs the following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item TBD
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Processor Initialization
|
||||
|
||||
TBD
|
||||
@@ -1,11 +0,0 @@
|
||||
@c Copyright (c) 2014 embedded brains GmbH. All rights reserved.
|
||||
|
||||
@chapter Altera Nios II Specific Information
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,80 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 2014 Hesham ALMatary <heshamelmatary@gmail.com>
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter OpenRISC 1000 Specific Information
|
||||
|
||||
This chapter discusses the
|
||||
@uref{http://opencores.org/or1k/Main_Page, OpenRISC 1000 architecture}
|
||||
dependencies in this port of RTEMS. There are many implementations
|
||||
for OpenRISC like or1200 and mor1kx. Currently RTEMS supports basic
|
||||
features that all implementations should have.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the OpenRISC 1000 architecture refer to the
|
||||
@uref{http://openrisc.github.io/or1k.html,OpenRISC 1000 architecture manual}.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
Please refer to the
|
||||
@uref{http://openrisc.github.io/or1k.html#__RefHeading__504887_595890882,Function Calling Sequence}.
|
||||
|
||||
@subsection Floating Point Unit
|
||||
|
||||
A floating point unit is currently not supported.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
A flat 32-bit memory model is supported.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
OpenRISC 1000 architecture has 13 exception types:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Reset
|
||||
@item Bus Error
|
||||
@item Data Page Fault
|
||||
@item Instruction Page Fault
|
||||
@item Tick Timer
|
||||
@item Alignment
|
||||
@item Illegal Instruction
|
||||
@item External Interrupt
|
||||
@item D-TLB Miss
|
||||
@item I-TLB Miss
|
||||
@item Range
|
||||
@item System Call
|
||||
@item Floating Point
|
||||
@item Trap
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
There are only two levels: interrupts enabled and interrupts disabled.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The OpenRISC RTEMS port uses a dedicated software interrupt stack.
|
||||
The stack for interrupts is allocated during interrupt driver initialization.
|
||||
When an interrupt is entered, the _ISR_Handler routine is responsible for
|
||||
switching from the interrupted task stack to RTEMS software interrupt stack.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture performs the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables operating system supported interrupts (IRQ),
|
||||
@item places the error code in @code{r0}, and
|
||||
@item executes an infinite loop to simulate a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
@@ -1,721 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2007.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter PowerPC Specific Information
|
||||
|
||||
This chapter discusses the PowerPC architecture dependencies
|
||||
in this port of RTEMS. The PowerPC family has a wide variety
|
||||
of implementations by a range of vendors. Consequently,
|
||||
there are many, many CPU models within it.
|
||||
|
||||
It is highly recommended that the PowerPC 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 PowerPC architecture which
|
||||
corresponds to that processor.
|
||||
|
||||
@subheading PowerPC Architecture Documents
|
||||
|
||||
For information on the PowerPC architecture, refer to
|
||||
the following documents available from Motorola and IBM:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item @cite{PowerPC Microprocessor Family: The Programming Environment}
|
||||
(Motorola Document MPRPPCFPE-01).
|
||||
|
||||
@item @cite{IBM PPC403GB Embedded Controller User's Manual}.
|
||||
|
||||
@item @cite{PoweRisControl MPC500 Family RCPU RISC Central Processing
|
||||
Unit Reference Manual} (Motorola Document RCPUURM/AD).
|
||||
|
||||
@item @cite{PowerPC 601 RISC Microprocessor User's Manual}
|
||||
(Motorola Document MPR601UM/AD).
|
||||
|
||||
@item @cite{PowerPC 603 RISC Microprocessor User's Manual}
|
||||
(Motorola Document MPR603UM/AD).
|
||||
|
||||
@item @cite{PowerPC 603e RISC Microprocessor User's Manual}
|
||||
(Motorola Document MPR603EUM/AD).
|
||||
|
||||
@item @cite{PowerPC 604 RISC Microprocessor User's Manual}
|
||||
(Motorola Document MPR604UM/AD).
|
||||
|
||||
@item @cite{PowerPC MPC821 Portable Systems Microprocessor User's Manual}
|
||||
(Motorola Document MPC821UM/AD).
|
||||
|
||||
@item @cite{PowerQUICC MPC860 User's Manual} (Motorola Document MPC860UM/AD).
|
||||
|
||||
@end itemize
|
||||
|
||||
Motorola maintains an on-line electronic library for the PowerPC
|
||||
at the following URL:
|
||||
|
||||
@itemize @code{ }
|
||||
@item @cite{http://www.mot.com/powerpc/library/library.html}
|
||||
@end itemize
|
||||
|
||||
This site has a a wealth of information and examples. Many of the
|
||||
manuals are available from that site in electronic format.
|
||||
|
||||
@subheading PowerPC Processor Simulator Information
|
||||
|
||||
PSIM is a program which emulates the Instruction Set Architecture
|
||||
of the PowerPC microprocessor family. It is reely available in source
|
||||
code form under the terms of the GNU General Public License (version
|
||||
2 or later). PSIM can be integrated with the GNU Debugger (gdb) to
|
||||
execute and debug PowerPC executables on non-PowerPC hosts. PSIM
|
||||
supports the addition of user provided device models which can be
|
||||
used to allow one to develop and debug embedded applications using
|
||||
the simulator.
|
||||
|
||||
The latest version of PSIM is included in GDB and enabled on pre-built
|
||||
binaries provided by the RTEMS Project.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This section presents the set of features which vary
|
||||
across PowerPC implementations and are of importance to RTEMS.
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/powerpc/powerpc.h} based upon the particular CPU
|
||||
model specified on the compilation command line.
|
||||
|
||||
@subsection Alignment
|
||||
|
||||
The macro PPC_ALIGNMENT is set to the PowerPC model's worst case alignment
|
||||
requirement for data types on a byte boundary. This value is used
|
||||
to derive the alignment restrictions for memory allocated from
|
||||
regions and partitions.
|
||||
|
||||
@subsection Cache Alignment
|
||||
|
||||
The macro PPC_CACHE_ALIGNMENT is set to the line size of the cache. It is
|
||||
used to align the entry point of critical routines so that as much code
|
||||
as possible can be retrieved with the initial read into cache. This
|
||||
is done for the interrupt handler as well as the context switch routines.
|
||||
|
||||
In addition, the "shortcut" data structure used by the PowerPC implementation
|
||||
to ease access to data elements frequently accessed by RTEMS routines
|
||||
implemented in assembly language is aligned using this value.
|
||||
|
||||
@subsection Maximum Interrupts
|
||||
|
||||
The macro PPC_INTERRUPT_MAX is set to the number of exception sources
|
||||
supported by this PowerPC model.
|
||||
|
||||
@subsection Has Double Precision Floating Point
|
||||
|
||||
The macro PPC_HAS_DOUBLE is set to 1 to indicate that the PowerPC model
|
||||
has support for double precision floating point numbers. This is
|
||||
important because the floating point registers need only be four bytes
|
||||
wide (not eight) if double precision is not supported.
|
||||
|
||||
@subsection Critical Interrupts
|
||||
|
||||
The macro PPC_HAS_RFCI is set to 1 to indicate that the PowerPC model
|
||||
has the Critical Interrupt capability as defined by the IBM 403 models.
|
||||
|
||||
@subsection Use Multiword Load/Store Instructions
|
||||
|
||||
The macro PPC_USE_MULTIPLE is set to 1 to indicate that multiword load and
|
||||
store instructions should be used to perform context switch operations.
|
||||
The relative efficiency of multiword load and store instructions versus
|
||||
an equivalent set of single word load and store instructions varies based
|
||||
upon the PowerPC model.
|
||||
|
||||
@subsection Instruction Cache Size
|
||||
|
||||
The macro PPC_I_CACHE is set to the size in bytes of the instruction cache.
|
||||
|
||||
@subsection Data Cache Size
|
||||
|
||||
The macro PPC_D_CACHE is set to the size in bytes of the data cache.
|
||||
|
||||
@subsection Debug Model
|
||||
|
||||
The macro PPC_DEBUG_MODEL is set to indicate the debug support features
|
||||
present in this CPU model. The following debug support feature sets
|
||||
are currently supported:
|
||||
|
||||
@table @b
|
||||
|
||||
@item @code{PPC_DEBUG_MODEL_STANDARD}
|
||||
indicates that the single-step trace enable (SE) and branch trace
|
||||
enable (BE) bits in the MSR are supported by this CPU model.
|
||||
|
||||
@item @code{PPC_DEBUG_MODEL_SINGLE_STEP_ONLY}
|
||||
indicates that only the single-step trace enable (SE) bit in the MSR
|
||||
is supported by this CPU model.
|
||||
|
||||
@item @code{PPC_DEBUG_MODEL_IBM4xx}
|
||||
indicates that the debug exception enable (DE) bit in the MSR is supported
|
||||
by this CPU model. At this time, this particular debug feature set
|
||||
has only been seen in the IBM 4xx series.
|
||||
|
||||
@end table
|
||||
|
||||
@subsubsection Low Power Model
|
||||
|
||||
The macro PPC_LOW_POWER_MODE is set to indicate the low power model
|
||||
supported by this CPU model. The following low power modes are currently
|
||||
supported.
|
||||
|
||||
@table @b
|
||||
|
||||
@item @code{PPC_LOW_POWER_MODE_NONE}
|
||||
indicates that this CPU model has no low power mode support.
|
||||
|
||||
@item @code{PPC_LOW_POWER_MODE_STANDARD}
|
||||
indicates that this CPU model follows the low power model defined for
|
||||
the PPC603e.
|
||||
|
||||
@end table
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Multilibs
|
||||
|
||||
The following multilibs are available:
|
||||
|
||||
@enumerate
|
||||
@item @code{.}: 32-bit PowerPC with FPU
|
||||
@item @code{nof}: 32-bit PowerPC with software floating point support
|
||||
@item @code{m403}: Instruction set for PPC403 with FPU
|
||||
@item @code{m505}: Instruction set for MPC505 with FPU
|
||||
@item @code{m603e}: Instruction set for MPC603e with FPU
|
||||
@item @code{m603e/nof}: Instruction set for MPC603e with software floating
|
||||
point support
|
||||
@item @code{m604}: Instruction set for MPC604 with FPU
|
||||
@item @code{m604/nof}: Instruction set for MPC604 with software floating point
|
||||
support
|
||||
@item @code{m860}: Instruction set for MPC860 with FPU
|
||||
@item @code{m7400}: Instruction set for MPC7500 with FPU
|
||||
@item @code{m7400/nof}: Instruction set for MPC7500 with software floating
|
||||
point support
|
||||
@item @code{m8540}: Instruction set for e200, e500 and e500v2 cores with
|
||||
single-precision FPU and SPE
|
||||
@item @code{m8540/gprsdouble}: Instruction set for e200, e500 and e500v2 cores
|
||||
with double-precision FPU and SPE
|
||||
@item @code{m8540/nof/nospe}: Instruction set for e200, e500 and e500v2 cores
|
||||
with software floating point support and no SPE
|
||||
@item @code{me6500/m32}: 32-bit instruction set for e6500 core with FPU and
|
||||
AltiVec
|
||||
@item @code{me6500/m32/nof/noaltivec}: 32-bit instruction set for e6500 core
|
||||
with software floating point support and no AltiVec
|
||||
@end enumerate
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
RTEMS supports the Embedded Application Binary Interface (EABI)
|
||||
calling convention. Documentation for EABI is available by sending
|
||||
a message with a subject line of "EABI" to eabi@@goth.sis.mot.com.
|
||||
|
||||
@subsection Programming Model
|
||||
|
||||
This section discusses the programming model for the
|
||||
PowerPC architecture.
|
||||
|
||||
@subsubsection Non-Floating Point Registers
|
||||
|
||||
The PowerPC architecture defines thirty-two non-floating point registers
|
||||
directly visible to the programmer. In thirty-two bit implementations, each
|
||||
register is thirty-two bits wide. In sixty-four bit implementations, each
|
||||
register is sixty-four bits wide.
|
||||
|
||||
These registers are referred to as @code{gpr0} to @code{gpr31}.
|
||||
|
||||
Some of the registers serve defined roles in the EABI programming model.
|
||||
The following table describes the role of each of these registers:
|
||||
|
||||
@ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
+---------------+----------------+------------------------------+
|
||||
| Register Name | Alternate Name | Description |
|
||||
+---------------+----------------+------------------------------+
|
||||
| r1 | sp | stack pointer |
|
||||
+---------------+----------------+------------------------------+
|
||||
| | | global pointer to the Small |
|
||||
| r2 | na | Constant Area (SDA2) |
|
||||
+---------------+----------------+------------------------------+
|
||||
| r3 - r12 | na | parameter and result passing |
|
||||
+---------------+----------------+------------------------------+
|
||||
| | | global pointer to the Small |
|
||||
| r13 | na | Data Area (SDA) |
|
||||
+---------------+----------------+------------------------------+
|
||||
@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 2.50in{\enskip\hfil#\hfil}&
|
||||
\vrule#\cr
|
||||
\noalign{\hrule}
|
||||
&\bf Register Name &&\bf Alternate Names&&\bf Description&\cr\noalign{\hrule}
|
||||
&r1&&sp&&stack pointer&\cr\noalign{\hrule}
|
||||
&r2&&NA&&global pointer to the Small&\cr
|
||||
&&&&&Constant Area (SDA2)&\cr\noalign{\hrule}
|
||||
&r3 - r12&&NA&¶meter and result passing&\cr\noalign{\hrule}
|
||||
&r13&&NA&&global pointer to the Small&\cr
|
||||
&&&&&Data Area (SDA2)&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
@end tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<CENTER>
|
||||
<TABLE COLS=3 WIDTH="80%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Register Name</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Alternate Name</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=center>r1</TD>
|
||||
<TD ALIGN=center>sp</TD>
|
||||
<TD ALIGN=center>stack pointer</TD></TR>
|
||||
<TR><TD ALIGN=center>r2</TD>
|
||||
<TD ALIGN=center>na</TD>
|
||||
<TD ALIGN=center>global pointer to the Small Constant Area (SDA2)</TD></TR>
|
||||
<TR><TD ALIGN=center>r3 - r12</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD ALIGN=center>parameter and result passing</TD></TR>
|
||||
<TR><TD ALIGN=center>r13</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD ALIGN=center>global pointer to the Small Data Area (SDA)</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
|
||||
@subsubsection Floating Point Registers
|
||||
|
||||
The PowerPC architecture includes thirty-two, sixty-four bit
|
||||
floating point registers. All PowerPC floating point instructions
|
||||
interpret these registers as 32 double precision floating point registers,
|
||||
regardless of whether the processor has 64-bit or 32-bit implementation.
|
||||
|
||||
The floating point status and control register (fpscr) records exceptions
|
||||
and the type of result generated by floating-point operations.
|
||||
Additionally, it controls the rounding mode of operations and allows the
|
||||
reporting of floating exceptions to be enabled or disabled.
|
||||
|
||||
@subsubsection Special Registers
|
||||
|
||||
The PowerPC architecture includes a number of special registers
|
||||
which are critical to the programming model:
|
||||
|
||||
@table @b
|
||||
|
||||
@item Machine State Register
|
||||
|
||||
The MSR contains the processor mode, power management mode, endian mode,
|
||||
exception information, privilege level, floating point available and
|
||||
floating point excepiton mode, address translation information and
|
||||
the exception prefix.
|
||||
|
||||
@item Link Register
|
||||
|
||||
The LR contains the return address after a function call. This register
|
||||
must be saved before a subsequent subroutine call can be made. The
|
||||
use of this register is discussed further in the @b{Call and Return
|
||||
Mechanism} section below.
|
||||
|
||||
@item Count Register
|
||||
|
||||
The CTR contains the iteration variable for some loops. It may also be used
|
||||
for indirect function calls and jumps.
|
||||
|
||||
@end table
|
||||
|
||||
@subsection Call and Return Mechanism
|
||||
|
||||
The PowerPC architecture supports a simple yet effective call
|
||||
and return mechanism. A subroutine is invoked
|
||||
via the "branch and link" (@code{bl}) and
|
||||
"brank and link absolute" (@code{bla})
|
||||
instructions. This instructions place the return address
|
||||
in the Link Register (LR). The callee returns to the caller by
|
||||
executing a "branch unconditional to the link register" (@code{blr})
|
||||
instruction. Thus the callee returns to the caller via a jump
|
||||
to the return address which is stored in the LR.
|
||||
|
||||
The previous contents of the LR are not automatically saved
|
||||
by either the @code{bl} or @code{bla}. It is the responsibility
|
||||
of the callee to save the contents of the LR before invoking
|
||||
another subroutine. If the callee invokes another subroutine,
|
||||
it must restore the LR before executing the @code{blr} instruction
|
||||
to return to the caller.
|
||||
|
||||
It is important to note that the PowerPC subroutine
|
||||
call and return mechanism does not automatically save and
|
||||
restore any registers.
|
||||
|
||||
The LR may be accessed as special purpose register 8 (@code{SPR8}) using the
|
||||
"move from special register" (@code{mfspr}) and
|
||||
"move to special register" (@code{mtspr}) instructions.
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
All RTEMS directives are invoked using the regular
|
||||
PowerPC EABI calling convention via the @code{bl} or
|
||||
@code{bla} instructions.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
As discussed above, the call instruction does not
|
||||
automatically save any registers. It is the responsibility
|
||||
of the callee to save and restore any registers which must be preserved
|
||||
across subroutine calls. The callee is responsible for saving
|
||||
callee-preserved registers to the program stack and restoring them
|
||||
before returning to the caller.
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
RTEMS assumes that arguments are placed in the
|
||||
general purpose registers with the first argument in
|
||||
register 3 (@code{r3}), the second argument in general purpose
|
||||
register 4 (@code{r4}), and so forth until the seventh
|
||||
argument is in general purpose register 10 (@code{r10}).
|
||||
If there are more than seven arguments, then subsequent arguments
|
||||
are placed on the program stack. The following pseudo-code
|
||||
illustrates the typical sequence used to call a RTEMS directive
|
||||
with three (3) arguments:
|
||||
|
||||
@example
|
||||
load third argument into r5
|
||||
load second argument into r4
|
||||
load first argument into r3
|
||||
invoke directive
|
||||
@end example
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Memory Model
|
||||
|
||||
@subsection Flat Memory Model
|
||||
|
||||
The PowerPC architecture supports a variety of memory models.
|
||||
RTEMS supports the PowerPC using a flat memory model with
|
||||
paging disabled. In this mode, the PowerPC automatically
|
||||
converts every address from a logical to a physical address
|
||||
each time it is used. The PowerPC uses information provided
|
||||
in the Block Address Translation (BAT) to convert these addresses.
|
||||
|
||||
Implementations of the PowerPC architecture may be thirty-two or sixty-four bit.
|
||||
The PowerPC architecture supports a flat thirty-two or sixty-four bit address
|
||||
space with addresses ranging from 0x00000000 to 0xFFFFFFFF (4
|
||||
gigabytes) in thirty-two bit implementations or to 0xFFFFFFFFFFFFFFFF
|
||||
in sixty-four bit implementations. Each address is represented
|
||||
by either a thirty-two bit or sixty-four bit value and is byte addressable.
|
||||
The address may be used to reference a single byte, half-word
|
||||
(2-bytes), word (4 bytes), or in sixty-four bit implementations a
|
||||
doubleword (8 bytes). Memory accesses within the address space are
|
||||
performed in big or little endian fashion by the PowerPC based
|
||||
upon the current setting of the Little-endian mode enable bit (LE)
|
||||
in the Machine State Register (MSR). While the processor is in
|
||||
big endian mode, memory accesses which are not properly aligned
|
||||
generate an "alignment exception" (vector offset 0x00600). In
|
||||
little endian mode, the PowerPC architecture does not require
|
||||
the processor to generate alignment exceptions.
|
||||
|
||||
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
|
||||
<CENTER>
|
||||
<TABLE COLS=2 WIDTH="60%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Data Type</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Alignment Requirement</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=center>byte</TD>
|
||||
<TD ALIGN=center>1</TD></TR>
|
||||
<TR><TD ALIGN=center>half-word</TD>
|
||||
<TD ALIGN=center>2</TD></TR>
|
||||
<TR><TD ALIGN=center>word</TD>
|
||||
<TD ALIGN=center>4</TD></TR>
|
||||
<TR><TD ALIGN=center>doubleword</TD>
|
||||
<TD ALIGN=center>8</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
Doubleword load and store operations are only available in
|
||||
PowerPC CPU models which are sixty-four bit implementations.
|
||||
|
||||
RTEMS does not directly support any PowerPC Memory Management
|
||||
Units, therefore, virtual memory or segmentation systems
|
||||
involving the PowerPC are not supported.
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2007.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
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 PowerPC's
|
||||
interrupt response and control mechanisms as they pertain to
|
||||
RTEMS.
|
||||
|
||||
RTEMS and associated documentation uses the terms interrupt and vector.
|
||||
In the PowerPC architecture, these terms correspond to exception and
|
||||
exception handler, respectively. The terms will be used interchangeably
|
||||
in this manual.
|
||||
|
||||
@subsection Synchronous Versus Asynchronous Exceptions
|
||||
|
||||
In the PowerPC architecture exceptions can be either precise or
|
||||
imprecise and either synchronous or asynchronous. Asynchronous
|
||||
exceptions occur when an external event interrupts the processor.
|
||||
Synchronous exceptions are caused by the actions of an
|
||||
instruction. During an exception SRR0 is used to calculate where
|
||||
instruction processing should resume. All instructions prior to
|
||||
the resume instruction will have completed execution. SRR1 is used to
|
||||
store the machine status.
|
||||
|
||||
There are two asynchronous nonmaskable, highest-priority exceptions
|
||||
system reset and machine check. There are two asynchrononous maskable
|
||||
low-priority exceptions external interrupt and decrementer. Nonmaskable
|
||||
execptions are never delayed, therefore if two nonmaskable, asynchronous
|
||||
exceptions occur in immediate succession, the state information saved by
|
||||
the first exception may be overwritten when the subsequent exception occurs.
|
||||
|
||||
The PowerPC arcitecure defines one imprecise exception, the imprecise
|
||||
floating point enabled exception. All other synchronous exceptions are
|
||||
precise. The synchronization occuring during asynchronous precise
|
||||
exceptions conforms to the requirements for context synchronization.
|
||||
|
||||
@subsection Vectoring of Interrupt Handler
|
||||
|
||||
Upon determining that an exception can be taken the PowerPC automatically
|
||||
performs the following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item an instruction address is loaded into SRR0
|
||||
|
||||
@item bits 33-36 and 42-47 of SRR1 are loaded with information
|
||||
specific to the exception.
|
||||
|
||||
@item bits 0-32, 37-41, and 48-63 of SRR1 are loaded with corresponding
|
||||
bits from the MSR.
|
||||
|
||||
@item the MSR is set based upon the exception type.
|
||||
|
||||
@item instruction fetch and execution resumes, using the new MSR value, at a location specific to the execption type.
|
||||
|
||||
@end itemize
|
||||
|
||||
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 saves all registers which are not normally preserved
|
||||
by the calling sequence so the user's interrupt service
|
||||
routine can be written in a high-level language.
|
||||
|
||||
@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 exceptions,
|
||||
|
||||
@item invokes the vectors to a user interrupt service routine (ISR).
|
||||
@end itemize
|
||||
|
||||
Asynchronous interrupts are ignored while exceptions are
|
||||
disabled. Synchronous interrupts which occur while 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.
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
The PowerPC architecture supports only a single external
|
||||
asynchronous interrupt source. This interrupt source
|
||||
may be enabled and disabled via the External Interrupt Enable (EE)
|
||||
bit in the Machine State Register (MSR). Thus only two level (enabled
|
||||
and disabled) of external device interrupt priorities are
|
||||
directly supported by the PowerPC architecture.
|
||||
|
||||
Some PowerPC implementations include a Critical Interrupt capability
|
||||
which is often used to receive interrupts from high priority external
|
||||
devices.
|
||||
|
||||
The RTEMS interrupt level mapping scheme for the PowerPC is not
|
||||
a numeric level as on most RTEMS ports. It is a bit mapping in
|
||||
which the least three significiant bits of the interrupt level
|
||||
are mapped directly to the enabling of specific interrupt
|
||||
sources as follows:
|
||||
|
||||
@table @b
|
||||
|
||||
@item Critical Interrupt
|
||||
Setting bit 0 (the least significant bit) of the interrupt level
|
||||
enables the Critical Interrupt source, if it is available on this
|
||||
CPU model.
|
||||
|
||||
@item Machine Check
|
||||
Setting bit 1 of the interrupt level enables Machine Check execptions.
|
||||
|
||||
@item External Interrupt
|
||||
Setting bit 2 of the interrupt level enables External Interrupt execptions.
|
||||
|
||||
@end table
|
||||
|
||||
All other bits in the RTEMS task interrupt level are ignored.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture performs the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item places the error code in r3, and
|
||||
|
||||
@item executes a trap instruction which results in a Program Exception.
|
||||
|
||||
@end itemize
|
||||
|
||||
If the Program Exception returns, then the following actions are performed:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item disables all processor exceptions by loading a 0 into the MSR, and
|
||||
|
||||
@item goes into an infinite loop to simulate a halt processor instruction.
|
||||
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is supported. Available platforms are the Freescale QorIQ P series (e.g.
|
||||
P1020) and T series (e.g. T2080, T4240).
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is supported.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated or
|
||||
re-initiated when the PowerPC processor is reset. The PowerPC
|
||||
architecture defines a Reset Exception, but leaves the
|
||||
details of the CPU state as implementation specific. Please
|
||||
refer to the User's Manual for the CPU model in question.
|
||||
|
||||
In general, at power-up the PowerPC begin execution at address
|
||||
0xFFF00100 in supervisor mode with all exceptions disabled. For
|
||||
soft resets, the CPU will vector to either 0xFFF00100 or 0x00000100
|
||||
depending upon the setting of the Exception Prefix bit in the MSR.
|
||||
If during a soft reset, a Machine Check Exception occurs, then the
|
||||
CPU may execute a hard reset.
|
||||
|
||||
@subsection Processor Initialization
|
||||
|
||||
If this PowerPC implementation supports on-chip caching
|
||||
and this is to be utilized, then it should be enabled during the
|
||||
reset application initialization code. On-chip caching has been
|
||||
observed to prevent some emulators from working properly, so it
|
||||
may be necessary to run with caching disabled to use these emulators.
|
||||
|
||||
In addition to the requirements described in the
|
||||
@b{Board Support Packages} chapter of the RTEMS C
|
||||
Applications User's Manual for the reset code
|
||||
which is executed before the call to @code{rtems_initialize_executive},
|
||||
the PowrePC version has the following specific requirements:
|
||||
|
||||
@itemize @bullet
|
||||
@item Must leave the PR bit of the Machine State Register (MSR) set
|
||||
to 0 so the PowerPC remains in the supervisor state.
|
||||
|
||||
@item Must set stack pointer (sp or r1) such that a minimum stack
|
||||
size of MINIMUM_STACK_SIZE bytes is provided for the RTEMS initialization
|
||||
sequence.
|
||||
|
||||
@item Must disable all external interrupts (i.e. clear the EI (EE)
|
||||
bit of the machine state register).
|
||||
|
||||
@item Must enable traps so window overflow and underflow
|
||||
conditions can be properly handled.
|
||||
|
||||
@item Must initialize the PowerPC's initial Exception Table with default
|
||||
handlers.
|
||||
|
||||
@end itemize
|
||||
@@ -1,50 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2011.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@node Preface, Port Specific Information, Top, Top
|
||||
@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.
|
||||
|
||||
Each architecture represents a CPU family and usually there are
|
||||
a wide variety of CPU models within it. These models share a
|
||||
common Instruction Set Architecture (ISA) which often varies
|
||||
based upon some well-defined rules. There are often
|
||||
multiple implementations of the ISA and these may be from
|
||||
one or multiple vendors.
|
||||
|
||||
On top of variations in the ISA, there may also be variations
|
||||
which occur when a CPU core implementation is combined with
|
||||
a set of peripherals to form a system on chip. For example,
|
||||
there are many ARM CPU models from numerous semiconductor
|
||||
vendors and a wide variety of peripherals. But at the
|
||||
ISA level, they share a common compatibility.
|
||||
|
||||
RTEMS depends upon this core similarity across the CPU models
|
||||
and leverages that to minimize the source code that is specific
|
||||
to any particular CPU core implementation or CPU model.
|
||||
|
||||
This manual is separate and distinct from the RTEMS Porting
|
||||
Guide. That manual is a guide on porting RTEMS to a new
|
||||
architecture. This manual is focused on the more mundane
|
||||
CPU architecture specific issues that may impact
|
||||
application development. For example, if you need to write
|
||||
a subroutine in assembly language, it is critical to understand
|
||||
the calling conventions for the target architecture.
|
||||
|
||||
The first chapter in this manual describes these issues
|
||||
in general terms. In a sense, it is posing the questions
|
||||
one should be aware may need to be answered and understood
|
||||
when porting an RTEMS application to a new architecture.
|
||||
Each subsequent chapter gives the answers to those questions
|
||||
for a particular CPU architecture.
|
||||
@@ -1,169 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter SuperH Specific Information
|
||||
|
||||
This chapter discusses the SuperH architecture dependencies
|
||||
in this port of RTEMS. The SuperH family has a wide variety
|
||||
of implementations by a wide range of vendors. Consequently,
|
||||
there are many, many CPU models within it.
|
||||
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the SuperH architecture,
|
||||
refer to the following documents available from VENDOR
|
||||
(@file{http//www.XXX.com/}):
|
||||
|
||||
@itemize @bullet
|
||||
@item @cite{SuperH Family Reference, VENDOR, PART NUMBER}.
|
||||
@end itemize
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This chapter presents the set of features which vary
|
||||
across SuperH implementations and are of importance to RTEMS.
|
||||
The set of CPU model feature macros are defined in the file
|
||||
@code{cpukit/score/cpu/sh/sh.h} based upon the particular CPU
|
||||
model specified on the compilation command line.
|
||||
|
||||
@subsection Another Optional Feature
|
||||
|
||||
The macro XXX
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
All RTEMS directives are invoked using a @code{XXX}
|
||||
instruction and return to the user application via the
|
||||
@code{XXX} instruction.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
The SH1 has 16 general registers (r0..r15).
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item r0..r3 used as general volatile registers
|
||||
|
||||
@item r4..r7 used to pass up to 4 arguments to functions, arguments
|
||||
above 4 are
|
||||
passed via the stack)
|
||||
|
||||
@item r8..13 caller saved registers (i.e. push them to the stack if you
|
||||
need them inside of a function)
|
||||
|
||||
@item r14 frame pointer
|
||||
|
||||
@item r15 stack pointer
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Parameter Passing
|
||||
|
||||
XXX
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Memory Model
|
||||
|
||||
@subsection Flat Memory Model
|
||||
|
||||
The SuperH 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 SuperH family members support virtual memory and
|
||||
segmentation. RTEMS does not support virtual memory or
|
||||
segmentation on any of the SuperH family members. It is the
|
||||
responsibility of the BSP to initialize the mapping for
|
||||
a flat memory model.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
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 MIPS's
|
||||
interrupt response and control mechanisms as they pertain to
|
||||
RTEMS.
|
||||
|
||||
@subsection Vectoring of an Interrupt Handler
|
||||
|
||||
Upon receipt of an interrupt the XXX family
|
||||
members with separate interrupt stacks automatically perform the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item TBD
|
||||
|
||||
@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.
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
TBD
|
||||
|
||||
@c
|
||||
@c
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture disables processor
|
||||
interrupts, places the error code in @b{XXX}, and executes a @code{XXX}
|
||||
instruction to simulate a halt processor instruction.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
@subsection System Reset
|
||||
|
||||
An RTEMS based application is initiated or
|
||||
re-initiated when the processor is reset. When the
|
||||
processor is reset, it performs the following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item TBD
|
||||
|
||||
@end itemize
|
||||
|
||||
@subsection Processor Initialization
|
||||
|
||||
TBD
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,806 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter SPARC-64 Specific Information
|
||||
|
||||
This document discusses the SPARC Version 9 (aka SPARC-64, SPARC64 or SPARC V9)
|
||||
architecture dependencies in this port of RTEMS.
|
||||
|
||||
The SPARC V9 architecture leaves a lot of undefined implemenation dependencies
|
||||
which are defined by the processor models. Consult the specific CPU model
|
||||
section in this document for additional documents covering the implementation
|
||||
dependent architectural features.
|
||||
|
||||
@subheading sun4u Specific Information
|
||||
sun4u is the subset of the SPARC V9 implementations comprising the UltraSPARC I
|
||||
through UltraSPARC IV processors.
|
||||
|
||||
The following documents were used in developing the SPARC-64 sun4u port:
|
||||
@itemize @bullet
|
||||
@item UltraSPARC User’s Manual
|
||||
(http://www.sun.com/microelectronics/manuals/ultrasparc/802-7220-02.pdf)
|
||||
@item UltraSPARC IIIi Processor (datasheets.chipdb.org/Sun/UltraSparc-IIIi.pdf)
|
||||
@end itemize
|
||||
|
||||
@subheading sun4v Specific Information
|
||||
sun4v is the subset of the SPARC V9 implementations comprising the
|
||||
UltraSPARC T1 or T2 processors.
|
||||
|
||||
The following documents were used in developing the SPARC-64 sun4v port:
|
||||
@itemize @bullet
|
||||
@item UltraSPARC Architecture 2005 Specification
|
||||
(http://opensparc-t1.sunsource.net/specs/UA2005-current-draft-P-EXT.pdf)
|
||||
@item UltraSPARC T1 supplement to UltraSPARC Architecture 2005 Specification
|
||||
(http://opensparc-t1.sunsource.net/specs/UST1-UASuppl-current-draft-P-EXT.pdf)
|
||||
@end itemize
|
||||
|
||||
The defining feature that separates the sun4v architecture from its
|
||||
predecessor is the existence of a super-privileged hypervisor that
|
||||
is responsible for providing virtualized execution environments. The impact
|
||||
of the hypervisor on the real-time guarantees available with sun4v has not
|
||||
yet been determined.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
@subsection CPU Model Feature Flags
|
||||
This section presents the set of features which vary across
|
||||
SPARC-64 implementations and
|
||||
are of importance to RTEMS. The set of CPU model feature macros
|
||||
are defined in the file
|
||||
cpukit/score/cpu/sparc64/sparc64.h based upon the particular
|
||||
CPU model defined on the compilation command line.
|
||||
|
||||
@subsubsection CPU Model Name
|
||||
|
||||
The macro CPU MODEL NAME is a string which designates
|
||||
the name of this CPU model.
|
||||
For example, for the UltraSPARC T1 SPARC V9 model,
|
||||
this macro is set to the string "sun4v".
|
||||
|
||||
@subsubsection 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.
|
||||
|
||||
@subsubsection 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 for a maximum of
|
||||
thirty-two register window sets although most implementations
|
||||
only include eight.
|
||||
|
||||
@subsection CPU Model Implementation Notes
|
||||
|
||||
This section describes the implemenation dependencies of the
|
||||
CPU Models sun4u and sun4v of the SPARC V9 architecture.
|
||||
|
||||
@subsubsection sun4u Notes
|
||||
|
||||
XXX
|
||||
|
||||
@subsection sun4v Notes
|
||||
|
||||
XXX
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
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.
|
||||
|
||||
The following document also provides some conventions on the
|
||||
global register usage in SPARC V9:
|
||||
http://developers.sun.com/solaris/articles/sparcv9abi.html
|
||||
|
||||
@subsection Programming Model
|
||||
|
||||
This section discusses the programming model for the
|
||||
SPARC architecture.
|
||||
|
||||
@subsubsection 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
|
||||
<CENTER>
|
||||
<TABLE COLS=3 WIDTH="80%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Register Number</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Register Names</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Description</STRONG></TD>
|
||||
<TR><TD ALIGN=center>0 - 7</TD>
|
||||
<TD ALIGN=center>g0 - g7</TD>
|
||||
<TD ALIGN=center>Global Registers</TD></TR>
|
||||
<TR><TD ALIGN=center>8 - 15</TD>
|
||||
<TD ALIGN=center>o0 - o7</TD>
|
||||
<TD ALIGN=center>Output Registers</TD></TR>
|
||||
<TR><TD ALIGN=center>16 - 23</TD>
|
||||
<TD ALIGN=center>l0 - l7</TD>
|
||||
<TD ALIGN=center>Local Registers</TD></TR>
|
||||
<TR><TD ALIGN=center>24 - 31</TD>
|
||||
<TD ALIGN=center>i0 - i7</TD>
|
||||
<TD ALIGN=center>Input Registers</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@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
|
||||
<CENTER>
|
||||
<TABLE COLS=3 WIDTH="80%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Register Name</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Alternate Name</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=center>g0</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD ALIGN=center>reads return 0 ; writes are ignored</TD></TR>
|
||||
<TR><TD ALIGN=center>o6</TD>
|
||||
<TD ALIGN=center>sp</TD>
|
||||
<TD ALIGN=center>stack pointer</TD></TR>
|
||||
<TR><TD ALIGN=center>i6</TD>
|
||||
<TD ALIGN=center>fp</TD>
|
||||
<TD ALIGN=center>frame pointer</TD></TR>
|
||||
<TR><TD ALIGN=center>i7</TD>
|
||||
<TD ALIGN=center>NA</TD>
|
||||
<TD ALIGN=center>return address</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
|
||||
@subsubsection Floating Point Registers
|
||||
|
||||
The SPARC V9 architecture includes sixty-four,
|
||||
thirty-two bit registers. These registers may be viewed as
|
||||
follows:
|
||||
|
||||
@itemize @bullet
|
||||
@item 32 32-bit single precision floating point or integer registers
|
||||
(f0, f1, ... f31)
|
||||
|
||||
@item 32 64-bit double precision floating point registers (f0, f2,
|
||||
f4, ... f62)
|
||||
|
||||
@item 16 128-bit extended precision floating point registers (f0, f4,
|
||||
f8, ... f60)
|
||||
@end itemize
|
||||
|
||||
The floating point state register (fsr) specifies
|
||||
the behavior of the floating point unit for rounding, contains
|
||||
its condition codes, version specification, and trap information.
|
||||
|
||||
@subsubsection Special Registers
|
||||
|
||||
The SPARC architecture includes a number of special registers:
|
||||
@table @b
|
||||
|
||||
@item @code{Ancillary State Registers (ASRs)}
|
||||
The ancillary state registers (ASRs) are optional state registers that
|
||||
may be privileged or nonprivileged. ASRs 16-31 are implementation-
|
||||
dependent. The SPARC V9 ASRs include: y, ccr, asi, tick, pc, fprs.
|
||||
The sun4u ASRs include: pcr, pic, dcr, gsr, softint set, softint clr,
|
||||
softint, and tick cmpr. The sun4v ASRs include: pcr, pic, gsr, soft-
|
||||
int set, softint clr, softint, tick cmpr, stick, and stick cmpr.
|
||||
|
||||
@item @code{Processor State Register (pstate)}
|
||||
The privileged pstate register contains control fields for the proces-
|
||||
sor’s current state. Its flag fields include the interrupt enable, privi-
|
||||
leged mode, and enable FPU.
|
||||
|
||||
@item @code{Processor Interrupt Level (pil)}
|
||||
The PIL specifies the interrupt level above which interrupts will be
|
||||
accepted.
|
||||
|
||||
@item @code{Trap Registers}
|
||||
The trap handling mechanism of the SPARC V9 includes a number of
|
||||
registers, including: trap program counter (tpc), trap next pc (tnpc),
|
||||
trap state (tstate), trap type (tt), trap base address (tba), and trap
|
||||
level (tl).
|
||||
|
||||
@item @code{Alternate Globals}
|
||||
The AG bit of the pstate register provides access to an alternate set
|
||||
of global registers. On sun4v, the AG bit is replaced by the global
|
||||
level (gl) register, providing access to at least two and at most eight
|
||||
alternate sets of globals.
|
||||
|
||||
@item @code{Register Window registers}
|
||||
A number of registers assist in register window management.
|
||||
These include the current window pointer (cwp), savable windows
|
||||
(cansave), restorable windows (canrestore), clean windows (clean-
|
||||
win), other windows (otherwin), and window state (wstate).
|
||||
|
||||
@end table
|
||||
|
||||
@subsection 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 increments 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 decrements 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 cansave, canrestore, otherwin, and cwp are used in conjunction
|
||||
to manage the finite set of register windows and detect the window
|
||||
overflow and underflow conditions. The first three of these
|
||||
registers must satisfy the invariant cansave + canrestore + otherwin =
|
||||
nwindow - 2, where nwindow is the number of register windows.
|
||||
The cwp contains the index of the register window currently in use.
|
||||
RTEMS does not use the cleanwin and otherwin registers.
|
||||
|
||||
The save instruction increments the cwp modulo the number of
|
||||
register windows, and if cansave is 0 then it also generates a
|
||||
window overflow. Similarly, the restore instruction decrements the
|
||||
cwp modulo the number of register windows, and if canrestore is 0 then it
|
||||
also generates a window underflow.
|
||||
|
||||
Unlike with the SPARC model, the SPARC-64 port does not assume that
|
||||
a register window is available for a trap. The window overflow
|
||||
and underflow conditions are not detected without hardware generating
|
||||
the trap. (These conditions can be detected by reading the register window
|
||||
registers and doing some simple arithmetic.)
|
||||
|
||||
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.
|
||||
|
||||
@subsection 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.
|
||||
This allows for the compiler to generate leaf-optimized functions
|
||||
that utilize the caller’s output registers without using save and restore.
|
||||
|
||||
@subsection Calling Mechanism
|
||||
|
||||
All RTEMS directives are invoked using the regular
|
||||
SPARC calling convention via the call instruction.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@subsection 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
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@subsection Flat Memory Model
|
||||
|
||||
The SPARC-64 architecture supports a flat 64-bit address space with
|
||||
addresses ranging from 0x0000000000000000 to 0xFFFFFFFFFFFFFFFF.
|
||||
Each address is represented by a 64-bit value (and an 8-bit address
|
||||
space identifider or ASI) and is byte addressable. The address
|
||||
may be used to reference a single byte, half-word (2-bytes),
|
||||
word (4 bytes), doubleword (8 bytes), or quad-word (16 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 0x34). 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 |
|
||||
| quadword | 16 |
|
||||
+--------------+-----------------------+
|
||||
@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}
|
||||
&quadword&&16&\cr\noalign{\hrule}
|
||||
}}\hfil}
|
||||
@end tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<CENTER>
|
||||
<TABLE COLS=2 WIDTH="60%" BORDER=2>
|
||||
<TR><TD ALIGN=center><STRONG>Data Type</STRONG></TD>
|
||||
<TD ALIGN=center><STRONG>Alignment Requirement</STRONG></TD></TR>
|
||||
<TR><TD ALIGN=center>byte</TD>
|
||||
<TD ALIGN=center>1</TD></TR>
|
||||
<TR><TD ALIGN=center>half-word</TD>
|
||||
<TD ALIGN=center>2</TD></TR>
|
||||
<TR><TD ALIGN=center>word</TD>
|
||||
<TD ALIGN=center>4</TD></TR>
|
||||
<TR><TD ALIGN=center>doubleword</TD>
|
||||
<TD ALIGN=center>8</TD></TR>
|
||||
<TR><TD ALIGN=center>quadword</TD>
|
||||
<TD ALIGN=center>16</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
RTEMS currently does not support any SPARC Memory Management
|
||||
Units, therefore, virtual memory or segmentation systems
|
||||
involving the SPARC are not supported.
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
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. Note that in the SPARC manuals,
|
||||
interrupts are a subset of the traps that are delivered to software
|
||||
interrupt handlers.
|
||||
|
||||
@subsection Synchronous Versus Asynchronous Traps
|
||||
|
||||
The SPARC architecture includes two classes of traps:
|
||||
synchronous (precise) and asynchronous (deferred).
|
||||
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.
|
||||
|
||||
@subsection Vectoring of Interrupt Handler
|
||||
|
||||
Upon receipt of an interrupt the SPARC automatically
|
||||
performs the following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item The trap level is set. This provides access to a fresh set of
|
||||
privileged trap-state registers used to save the current state,
|
||||
in effect, pushing a frame on the trap stack.
|
||||
TL <- TL + 1
|
||||
@item Existing state is preserved
|
||||
@itemize @bullet
|
||||
@item TSTATE[TL].CCR <- CCR
|
||||
@item TSTATE[TL].ASI <- ASI
|
||||
@item TSTATE[TL].PSTATE <- PSTATE
|
||||
@item TSTATE[TL].CWP <- CWP
|
||||
@item TPC[TL] <- PC
|
||||
@item TNPC[TL] <- nPC
|
||||
@end itemize
|
||||
@item The trap type is preserved. TT[TL] <- the trap type
|
||||
@item The PSTATE register is updated to a predefined state
|
||||
@itemize @bullet
|
||||
@item PSTATE.MM is unchanged
|
||||
@item PSTATE.RED <- 0
|
||||
@item PSTATE.PEF <- 1 if FPU is present, 0 otherwise
|
||||
@item PSTATE.AM <- 0 (address masking is turned off)
|
||||
@item PSTATE.PRIV <- 1 (the processor enters privileged mode)
|
||||
@item PSTATE.IE <- 0 (interrupts are disabled)
|
||||
@item PSTATE.AG <- 1 (global regs are replaced with alternate globals)
|
||||
@item PSTATE.CLE <- PSTATE.TLE (set endian mode for traps)
|
||||
@end itemize
|
||||
@item For a register-window trap only, CWP is set to point to the register
|
||||
window that must be accessed by the trap-handler software, that is:
|
||||
@itemize @bullet
|
||||
@item If TT[TL] = 0x24 (a clean window trap), then CWP <- CWP + 1.
|
||||
@item If (0x80 <= TT[TL] <= 0xBF) (window spill trap), then CWP <- CWP +
|
||||
CANSAVE + 2.
|
||||
@item If (0xC0 <= TT[TL] <= 0xFF) (window fill trap), then CWP <- CWP1.
|
||||
@item For non-register-window traps, CWP is not changed.
|
||||
@end itemize
|
||||
@item Control is transferred into the trap table:
|
||||
@itemize @bullet
|
||||
@item PC <- TBA<63:15> (TL>0) TT[TL] 0 0000
|
||||
@item nPC <- TBA<63:15> (TL>0) TT[TL] 0 0100
|
||||
@item where (TL>0) is 0 if TL = 0, and 1 if TL > 0.
|
||||
@end itemize
|
||||
|
||||
@end itemize
|
||||
|
||||
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 switches the processor to trap level 0,
|
||||
|
||||
@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 may 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.
|
||||
|
||||
@subsection Traps and Register Windows
|
||||
|
||||
XXX
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@subsection Disabling of Interrupts by RTEMS
|
||||
|
||||
XXX
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@subsection 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.
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is supported.
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@section Board Support Packages
|
||||
|
||||
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
|
||||
Applications User's Guide.
|
||||
|
||||
@subsection HelenOS and Open Firmware
|
||||
The provided BSPs make use of some bootstrap and low-level hardware code
|
||||
of the HelenOS operating system. These files can be found in the shared/helenos
|
||||
directory of the sparc64 bsp directory. Consult the sources for more
|
||||
detailed information.
|
||||
|
||||
The shared BSP code also uses the Open Firmware interface to re-use firmware
|
||||
code, primarily for console support and default trap handlers.
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 24 February 2013
|
||||
@set UPDATED-MONTH February 2013
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,112 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@ifinfo
|
||||
@end ifinfo
|
||||
@chapter V850 Specific Information
|
||||
|
||||
This chapter discusses the
|
||||
@uref{http://en.wikipedia.org/wiki/V850,V850 architecture}
|
||||
dependencies in this port of RTEMS. The V850 was originally manufactured
|
||||
by NEC but is now part of the Renesas Electronics product line.
|
||||
|
||||
@subheading Architecture Documents
|
||||
|
||||
For information on the V850 architecture refer to the
|
||||
@uref{http://am.renesas.com/products/mpumcu/v850/index.jsp,Renesas v850 product page}.
|
||||
|
||||
@section CPU Model Dependent Features
|
||||
|
||||
This section presents the set of features which vary across V850 implementations and are of importance to RTEMS. The set of CPU model feature macros are defined in the file @file{cpukit/score/cpu/v850/rtems/score/v850.h} based upon the particular CPU
|
||||
model flags specified on the compilation command line.
|
||||
|
||||
@subsection CPU Model Name
|
||||
|
||||
The macro @code{CPU_MODEL_NAME} is a string which designates
|
||||
the architectural level of this CPU model. See in
|
||||
@file{cpukit/score/cpu/v850/rtems/score/v850.h} for the values.
|
||||
|
||||
@subsection Count Leading Zeroes Instruction
|
||||
|
||||
The V850v5 and later has the count leading zeroes @code{clz} instruction which
|
||||
could be used to speed up the find first bit operation. The use of this
|
||||
instruction should significantly speed up the scheduling associated with a
|
||||
thread blocking. This is currently not used.
|
||||
|
||||
@subsection Floating Point Unit
|
||||
|
||||
A floating point unit is currently not supported.
|
||||
|
||||
@section Calling Conventions
|
||||
|
||||
Please refer to the
|
||||
@uref{http://www.filibeto.org/unix/tru64/lib/ossc/doc/cygnus_doc-99r1/html/6_embed/embV850.html,
|
||||
Procedure Call Standard for the V850 Architecture} or the GCC source
|
||||
code for detailed information on the calling conventions.
|
||||
|
||||
@subsection Register Usage
|
||||
|
||||
Fixed registers are never available for register allocation in the
|
||||
compiler. By default the following registers are fixed in GCC:
|
||||
|
||||
@itemize @bullet
|
||||
@item r0 (zero)
|
||||
@item r3 (sp)
|
||||
@item r4 (gp)
|
||||
@item r30 (ep)
|
||||
@end itemize
|
||||
|
||||
@c r1 is mentioned as special purpose but I do not see a purpose
|
||||
|
||||
Caller saved registers can be used by the compiler to hold values that
|
||||
do not live across function calls. The caller saved registers are r2,
|
||||
r5 through r19, and r31.
|
||||
|
||||
Callee saved registers retain their value across function calls. The
|
||||
callee saved registers are r20 through r29.
|
||||
|
||||
r6 through r9 are parameter registers while r10 and r11 are function return registers. r31 is the return pointer.
|
||||
|
||||
r29 is used as the frame pointer in some functions.
|
||||
|
||||
@section Memory Model
|
||||
|
||||
A flat 32-bit memory model is supported.
|
||||
|
||||
@section Interrupt Processing
|
||||
|
||||
The V850 architecture has ...
|
||||
|
||||
@subsection Interrupt Levels
|
||||
|
||||
The RTEMS interrupt level mapping scheme for the V850 is very simple. If
|
||||
the requested interrupt level is 1, then interrupts are disabled in the
|
||||
PSW register using the @code{di} instruction. If the requested interrupt
|
||||
level is 0, then interrupts are enabled in the PSW register using the
|
||||
@code{ei} instruction or restoring the previous value of the PSW register.
|
||||
|
||||
@subsection Interrupt Stack
|
||||
|
||||
The board support package must initialize the interrupt stack. The memory for
|
||||
the stacks is usually reserved in the linker script.
|
||||
|
||||
@section Default Fatal Error Processing
|
||||
|
||||
The default fatal error handler for this architecture performs the
|
||||
following actions:
|
||||
|
||||
@itemize @bullet
|
||||
@item disables operating system supported interrupts (IRQ),
|
||||
@item places the error code in @code{r10}, and
|
||||
@item executes a halt processor instruction.
|
||||
@end itemize
|
||||
|
||||
@section Symmetric Multiprocessing
|
||||
|
||||
SMP is not supported.
|
||||
|
||||
@section Thread-Local Storage
|
||||
|
||||
Thread-local storage is not implemented.
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 17 July 2015
|
||||
@set UPDATED-MONTH July 2015
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,37 +0,0 @@
|
||||
#
|
||||
# COPYRIGHT (c) 1988-2002.
|
||||
# On-Line Applications Research Corporation (OAR).
|
||||
# All rights reserved.
|
||||
|
||||
PROJECT = develenv
|
||||
|
||||
include $(top_srcdir)/project.am
|
||||
include $(top_srcdir)/main.am
|
||||
|
||||
FILES = direct.texi intro.texi sample.texi utils.texi
|
||||
|
||||
GENERATED_FILES = direct.texi sample.texi utils.texi
|
||||
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
info_TEXINFOS = develenv.texi
|
||||
develenv_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
|
||||
|
||||
direct.texi: direct.t
|
||||
$(BMENU2) -p "Introduction" \
|
||||
-u "Top" \
|
||||
-n "Sample Applications" < $< > $@
|
||||
|
||||
sample.texi: sample.t
|
||||
$(BMENU2) -p "Directory Structure Documentation Directory" \
|
||||
-u "Top" \
|
||||
-n "RTEMS Specific Utilities" < $< > $@
|
||||
|
||||
utils.texi: utils.t
|
||||
$(BMENU2) -p "Sample Applications Network Loopback Test" \
|
||||
-u "Top" \
|
||||
-n "Command and Variable Index" < $< > $@
|
||||
|
||||
CLEANFILES += develenv.info
|
||||
|
||||
EXTRA_DIST = direct.t sample.t utils.t
|
||||
@@ -1,105 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename develenv.info
|
||||
@setcontentsaftertitlepage
|
||||
@syncodeindex vr fn
|
||||
@synindex ky cp
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2013.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@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 version.texi
|
||||
@include common/setup.texi
|
||||
@include common/rtems.texi
|
||||
|
||||
@ifset use-ascii
|
||||
@dircategory RTEMS On-Line Manual
|
||||
@direntry
|
||||
* RTEMS Development Environment Guide: (develenv).
|
||||
@end direntry
|
||||
@end ifset
|
||||
|
||||
|
||||
@c variable substitution info:
|
||||
@c
|
||||
@c @set LANGUAGE C
|
||||
@c the language is @value{LANGUAGE}
|
||||
@c NOTE: don't use underscore in the name
|
||||
@c
|
||||
|
||||
@c
|
||||
@c Title Page Stuff
|
||||
@c
|
||||
|
||||
@c
|
||||
@c I don't really like having a short title page. --joel
|
||||
@c
|
||||
@c @shorttitlepage RTEMS Development Environment Guide
|
||||
|
||||
@setchapternewpage odd
|
||||
@settitle RTEMS Development Environment Guide
|
||||
@titlepage
|
||||
@finalout
|
||||
|
||||
@title RTEMS Development Environment Guide
|
||||
@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION}
|
||||
@sp 1
|
||||
@subtitle @value{UPDATED}
|
||||
@author On-Line Applications Research Corporation
|
||||
@page
|
||||
@include common/cpright.texi
|
||||
@end titlepage
|
||||
|
||||
@c This prevents a black box from being printed on "overflow" lines.
|
||||
@c The alternative is to rework a sentence to avoid this problem.
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top, Introduction, (dir), (dir)
|
||||
@top RTEMS Development Environment Guide
|
||||
|
||||
@menu
|
||||
* Introduction::
|
||||
* Directory Structure::
|
||||
* Sample Applications::
|
||||
* RTEMS Specific Utilities::
|
||||
* Command and Variable Index::
|
||||
* Concept Index::
|
||||
@end menu
|
||||
@end ifnottex
|
||||
|
||||
@include intro.texi
|
||||
@include direct.texi
|
||||
@include sample.texi
|
||||
@include utils.texi
|
||||
|
||||
@node Command and Variable Index, Concept Index, RTEMS Specific Utilities unhex - Convert Hexadecimal File into Binary Equivalent, Top
|
||||
@unnumbered Command and Variable Index
|
||||
|
||||
There are currently no Command and Variable Index entries.
|
||||
|
||||
@c @printindex fn
|
||||
|
||||
@node Concept Index, , Command and Variable Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
There are currently no Concept Index entries.
|
||||
@c @printindex cp
|
||||
|
||||
@bye
|
||||
|
||||
@@ -1,689 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2010.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Directory Structure
|
||||
|
||||
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 target boards.
|
||||
|
||||
@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
|
||||
board dependent source files isolated from generic files. When
|
||||
RTEMS is configured and built, object directories and
|
||||
an install point will be automatically created based upon
|
||||
the target CPU family and BSP selected.
|
||||
|
||||
The placement of object files based upon the selected BSP name
|
||||
ensures that object files are not mixed across CPUs or targets.
|
||||
This in combination with the makefiles 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 @i{packed} to conserve
|
||||
memory. It is impossible to achieve this degree of flexibility
|
||||
without providing source code.
|
||||
|
||||
The RTEMS source tree is organized based on the following variables:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item functionality,
|
||||
@item target processor family,
|
||||
@item target processor model,
|
||||
@item peripherals, and
|
||||
@item target board.
|
||||
|
||||
@end itemize
|
||||
|
||||
Each of the following sections will describe the
|
||||
contents of the directories in the RTEMS source
|
||||
tree. The top of the tree will be referenced
|
||||
as @code{$@{RTEMS_ROOT@}} in this discussion.
|
||||
|
||||
@c
|
||||
@c Top Level Tree
|
||||
@c
|
||||
|
||||
@c @ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
rtems-VERSION
|
||||
|
|
||||
+--------+----+----+----+--+-----+---+-------+--------+
|
||||
| | | | | | | | |
|
||||
aclocal automake c contrib cpukit doc make testsuites tools
|
||||
@end group
|
||||
@end example
|
||||
@c @end ifset
|
||||
|
||||
@ifset use-tex
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
@table @code
|
||||
@item $@{RTEMS_ROOT@}/aclocal/
|
||||
This directory contains the custom M4 macros which are available to
|
||||
the various GNU autoconf @code{configure.ac} scripts throughout
|
||||
the RTEMS source tree. GNU autoconf interprets @code{configure.ac}
|
||||
files to produce the @code{configure} files used to tailor
|
||||
RTEMS build for a particular host and target environment. The
|
||||
contents of this directory will not be discussed further in this
|
||||
document.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/automake/
|
||||
This directory contains the custom GNU automake fragments
|
||||
which are used to support the various @code{Makefile.am}
|
||||
files throughout the RTEMS source tree. The
|
||||
contents of this directory will not be discussed
|
||||
further in this document.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/
|
||||
This directory is the root of the portions of the RTEMS source
|
||||
tree which must be built tailored for a particular CPU model
|
||||
or BSP. The contents of this directory will be discussed
|
||||
in the @ref{Directory Structure c/ Directory} section.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/contrib/
|
||||
This directory contains contributed support software. Currently
|
||||
this directory contains the RPM specifications for cross-compilers
|
||||
hosted on GNU/Linux that target various operating systems
|
||||
including MinGW, Cygwin, FreeBSD, and Solaris. The
|
||||
cross-compilers produced using these specifications are then
|
||||
used in a Canadian cross build procedure to produce the various
|
||||
RTEMS toolsets on a GNU/Linux host.
|
||||
|
||||
This directory also contains RPM specifications for the
|
||||
prebuilt cross-compilation toolsets provided by the
|
||||
RTEMS project. There are separate subdirectories
|
||||
for each of the components in the RTEMS Cross Compilation
|
||||
Environment unde the @code{contrib/crossrpms/} directory.
|
||||
This directory is configured, built, and installed separately
|
||||
from the RTEMS executive and tests. This directory will not
|
||||
be discussed further in this document.
|
||||
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/
|
||||
This directory is the root for all of the "multilib'able"
|
||||
portions of RTEMS. This is a GNU way of saying the
|
||||
contents of this directory can be compiled like the
|
||||
C Library (@code{libc.a}) and the functionality is
|
||||
neither CPU model nor BSP specific. The source code
|
||||
for most RTEMS services reside under this directory.
|
||||
The contents of this directory will be discussed
|
||||
in the @ref{Directory Structure CPU Kit Directory} section.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/
|
||||
This directory is the root for all RTEMS documentation.
|
||||
The source for RTEMS is written in GNU TeXinfo and
|
||||
used to produce HTML, PDF, and "info" files.
|
||||
The RTEMS documentation is configured, built,
|
||||
and installed separately from the RTEMS executive and tests.
|
||||
The contents of this directory will be discussed
|
||||
in the @ref{Directory Structure Documentation Directory} section.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/make/
|
||||
This directory contains files which support the
|
||||
RTEMS Makefile's. From a user's perspective, the
|
||||
most important parts are found in the @code{custom/}
|
||||
subdirectory. Each ".cfg" file in this directory
|
||||
is associated with a specific BSP and describes
|
||||
the CPU model, compiler flags, and procedure to
|
||||
produce an executable for the target board.
|
||||
These files are described in detail in the
|
||||
@b{RTEMS BSP and Device Driver Development Guide}
|
||||
and will not be discussed further in this document.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/
|
||||
This directory contains the test suites for the
|
||||
various RTEMS APIs and support libraries. The
|
||||
contents of this directory are discussed in the
|
||||
@ref{Directory Structure testsuites/ Test Suites} section.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/tools/
|
||||
This directory contains RTEMS specific support utilities which
|
||||
execute on the development host. These utilities are divided
|
||||
into subdirectories based upon whether they are used in the process
|
||||
of building RTEMS and applications, are CPU specific, or are
|
||||
used to assist in updating the RTEMS source tree and applications.
|
||||
The support utilities used in the process of building RTEMS are
|
||||
described in @ref{RTEMS Specific Utilities}. These are the
|
||||
only components of this subtree that will be discussed in this
|
||||
document.
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
|
||||
@c
|
||||
@c c/ Directions
|
||||
@c
|
||||
@section c/ Directory
|
||||
|
||||
The @code{$@{RTEMS_ROOT@}/c/} directory was formerly
|
||||
the root directory of all RTEMS source code. At this time, it contains
|
||||
the root directory for only those RTEMS components
|
||||
which must be compiled or linked in a way that is specific to a
|
||||
particular CPU model or board. This directory contains the
|
||||
following subdirectories:
|
||||
|
||||
@table @code
|
||||
@item $@{RTEMS_ROOT@}/c/src/
|
||||
This directory is logically the root for the RTEMS components
|
||||
which are CPU model or board dependent. Thus this directory
|
||||
is the root for the BSPs and the Ada Test Suites as well
|
||||
as CPU model and BSP dependent libraries. The contents of
|
||||
this directory are discussed in the
|
||||
@ref{Directory Structure c/src/ Directory} section.
|
||||
@end table
|
||||
|
||||
@c
|
||||
@c c/src/ Directory
|
||||
@c
|
||||
@subsection c/src/ Directory
|
||||
|
||||
As mentioned previously, this directory is logically
|
||||
the root for the RTEMS components
|
||||
which are CPU model or board dependent. The
|
||||
following is a list of the subdirectories in this
|
||||
directory and a description of each.
|
||||
|
||||
@table @code
|
||||
@item $@{RTEMS_ROOT@}/c/src/aclocal/
|
||||
This directory contains the custom M4 macros which are available to
|
||||
the various GNU autoconf @code{configure.ac} scripts throughout
|
||||
this portion of the RTEMS source tree. GNU autoconf interprets
|
||||
@code{configure.ac} files to produce the @code{configure} files used
|
||||
to tailor RTEMS build for a particular host and target environment. The
|
||||
contents of this directory will not be discussed further in this
|
||||
document.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/ada/
|
||||
This directory contains the Ada95 language bindings to the
|
||||
RTEMS Classic API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/ada-tests/
|
||||
This directory contains the test suite for the Ada
|
||||
language bindings to the Classic API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/automake/
|
||||
This directory contains files which are "Makefile fragments."
|
||||
They are included as required by the various @code{Makefile.am}
|
||||
files throughout this portion of the RTEMS source tree.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/lib/
|
||||
This directory contains the directories @code{libbsp/}
|
||||
and @code{libcpu/} which contain the source code for
|
||||
the Board Support Packages (BSPs) and CPU Model
|
||||
specific source code for RTEMS.
|
||||
|
||||
The @code{libbsp/} is organized based upon the CPU
|
||||
family and boards BSPs. The contents of @code{libbsp/}
|
||||
are discussed briefly in
|
||||
@ref{Directory Structure c/src/lib/libbsp BSP Directory}
|
||||
and presented in detail in the
|
||||
@b{RTEMS BSP and Device Driver Development Guide}.
|
||||
|
||||
The @code{libcpu/} directory is also organized by
|
||||
CPU family with further divisions based upon CPU
|
||||
model and features that are shared across CPU models
|
||||
such as caching and DMA.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/libchip/
|
||||
This directory contains device drivers for various
|
||||
peripheral chips which are designed to be CPU and
|
||||
board dependent. This directory contains a variety
|
||||
of drivers for serial devices, network interface
|
||||
controllers, shared memory and real-time clocks.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/librtems++/
|
||||
This directory contains C++ classes which map to the RTEMS
|
||||
Classic API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/make/
|
||||
This directory is used to generate the bulk of the supporting
|
||||
rules files which are installed as part of the Application Makefiles.
|
||||
This file contains settings for various Makefile variables to
|
||||
tailor them to the particular CPU model and BSP configured.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/nfsclient/
|
||||
This directory contains a Network File System (NFS) client
|
||||
for RTEMS. With this file system, a user's application can
|
||||
access files on a remote computer.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/optman/
|
||||
This directory contains stubs for the RTEMS Classic API
|
||||
Managers which are considered optional and whose use
|
||||
may be explicitly forbidden by an application. All of the
|
||||
directive implementations in this Optional Managers
|
||||
return @code{E_NOTCONFIGURED}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/support/
|
||||
This directory exists solely to generate the RTEMS
|
||||
version string which includes the RTEMS version,
|
||||
CPU architecture, CPU model, and BSP name.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/wrapup/
|
||||
This directory is responsible for taking the individual
|
||||
libraries and objects built in each of the components
|
||||
in the RTEMS source tree and bundling them together to form
|
||||
the single RTEMS library @code{librtemsbsp.a}. This
|
||||
library contains all BSP and CPU model specific software.
|
||||
|
||||
@end table
|
||||
|
||||
@c
|
||||
@c c/src/lib/libbsp BSP Directory
|
||||
@c
|
||||
|
||||
@subsubsection c/src/lib/libbsp BSP Directory
|
||||
|
||||
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
|
||||
|
||||
The "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 broken down into specific target board
|
||||
environments. The "no_cpu" subdirectory provides a starting point
|
||||
template BSP which can be used to develop a specific BSP for an
|
||||
unsupported target board. The files in this subdirectory 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
|
||||
|
||||
@c @ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
Each BSP
|
||||
|
|
||||
+-----------+----------+-----+-----+----------+----------+
|
||||
| | | | | |
|
||||
clock console include shmsupp startup timer
|
||||
@end group
|
||||
@end example
|
||||
@c @end ifset
|
||||
|
||||
@c
|
||||
@c CPU Kit Directory
|
||||
@c
|
||||
@section CPU Kit Directory
|
||||
|
||||
@c The @code{cpukit/} directory structure is as follows:
|
||||
|
||||
@c
|
||||
@c CPU Kit Tree
|
||||
@c
|
||||
|
||||
@c @ifset use-ascii
|
||||
@c @example
|
||||
@c @group
|
||||
@c cpukit
|
||||
@c |
|
||||
@c +-----------+----------+-----------+----------+
|
||||
@c | | | | |
|
||||
@c posix rtems sapi score wrapup
|
||||
@c @end group
|
||||
@c @end example
|
||||
@c @end ifset
|
||||
|
||||
The @code{cpukit/} directory contains a set of subdirectories which
|
||||
contains the source files comprising the executive portion of
|
||||
the RTEMS development environment as well as portable support
|
||||
libraries such as support for the C Library and filesystems.
|
||||
The API specific and "SuperCore" (e.g. @code{score/} directory)
|
||||
source code files are separated into distinct directory trees.
|
||||
|
||||
The following is a description of each of the subdirectories
|
||||
under @code{cpukit/}:
|
||||
|
||||
@table @code
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/aclocal/
|
||||
This directory contains the custom M4 macros which are available to
|
||||
the various GNU autoconf @code{configure.ac} scripts throughout
|
||||
the CPU Kit portion of the RTEMS source tree.
|
||||
GNU autoconf interprets @code{configure.ac}
|
||||
files to produce the @code{configure} files used to tailor
|
||||
RTEMS build for a particular host and target environment. The
|
||||
contents of this directory will not be discussed further in this
|
||||
document.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/automake/
|
||||
This directory contains files which are "Makefile fragments."
|
||||
They are included as required by the various @code{Makefile.am}
|
||||
files throughout the CPU Kit portion of the RTEMS source tree.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/ftpd/
|
||||
This directory contains the RTEMS ftpd server.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/httpd/
|
||||
This directory contains the port of the GoAhead
|
||||
web server to RTEMS.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/include/
|
||||
This directory contains header files which are private to
|
||||
RTEMS and not considered to be owned by any other component
|
||||
in the CPU Kit.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libblock/
|
||||
This directory contains support code for using
|
||||
Block Devices such as hard drives, floppies, and
|
||||
CD-ROMs. It includes the generic IO primitives
|
||||
for block device drivers, disk caching support,
|
||||
and a RAM disk block device driver.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libcsupport/
|
||||
This directory contains the RTEMS specific support routines
|
||||
for the Newlib C Library. This includes what are referred
|
||||
to as system calls and found in section 2 of the traditional
|
||||
UNIX manual. In addition, it contains a thread-safe
|
||||
implementation of the Malloc family of routines as well
|
||||
as BSD and POSIX services not found in Newlib.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libfs/
|
||||
This directory contains the various non-networked
|
||||
filesystem implementations for RTEMS. It includes
|
||||
the In-Memory FileSystem (IMFS), the mini-IMFS,
|
||||
and FAT filesystems.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libi2c/
|
||||
This directory contains the RTEMS I2C framework.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libmd/
|
||||
This directory contains a port of the standard MD5
|
||||
checksum code.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/c/src/libmisc/
|
||||
This directory contains support facilities which
|
||||
are RTEMS specific but otherwise unclassified. In
|
||||
general, they do not adhere to a standard API.
|
||||
Among the support facilities in this directory are
|
||||
a @code{/dev/null} device driver, the Stack
|
||||
Overflow Checker, a mini-shell, the CPU and
|
||||
rate monotonic period usage monitoring libraries,
|
||||
and a utility to "dump a buffer" in a nicely
|
||||
formatted way similar to many ROM monitors.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libnetworking/
|
||||
This directory contains the port of the FreeBSD
|
||||
TCP/IP stack to RTEMS.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/librpc/
|
||||
This directory contains the port of the FreeBSD
|
||||
RPC/XDR source to RTEMS.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/libpci/
|
||||
This directory contains RTEMS PCI Library.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/posix/
|
||||
This directory contains the RTEMS implementation
|
||||
of the threading portions of the POSIX API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/pppd/
|
||||
This directory contains a port of the free implementation
|
||||
of the PPPD network protocol.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/rtems/
|
||||
This directory contains the implementation of the
|
||||
Classic API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/sapi/
|
||||
This directory contains the implementation of RTEMS
|
||||
services which are required but beyond the realm
|
||||
of any standardization efforts. It includes
|
||||
initialization, shutdown, and IO services.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/score/
|
||||
This directory contains the "SuperCore" of RTEMS.
|
||||
All APIs are implemented in terms of SuperCore services.
|
||||
For example, Classic API tasks and POSIX threads
|
||||
are all implemented in terms of SuperCore threads.
|
||||
This provides a common infrastructure and a high degree
|
||||
of interoperability between the APIs. For example,
|
||||
services from all APIs may be used by any task/thread
|
||||
independent of the API used to create it.
|
||||
|
||||
Within the @code{score/} directory the CPU dependent modules are found.
|
||||
The @code{score/cpu/} subdirectory contains a subdirectory for each
|
||||
target CPU supported by this release of the RTEMS
|
||||
executive. Each processor directory contains the CPU dependent
|
||||
code necessary to host RTEMS. The @code{no_cpu} directory provides a
|
||||
starting point for developing a new port to an unsupported
|
||||
processor. The files contained within the @code{no_cpu} directory
|
||||
may also be used as a reference for the other ports to specific
|
||||
processors.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/shttpd/
|
||||
This directory contains the port of the Simple HTTPD
|
||||
web server to RTEMS.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/telnetd/
|
||||
This directory contains the RTEMS telnetd server.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/wrapup/
|
||||
This directory is responsible for taking the individual
|
||||
libraries and objects built in each of the components
|
||||
in the RTEMS CPU Kit source tree and bundling them
|
||||
together to form the single RTEMS library @code{librtemscpu.a}. This
|
||||
library contains all BSP and CPU model specific software.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/cpukit/zlib/
|
||||
This directory contains a port of the GNU Zlib compression
|
||||
library to RTEMS.
|
||||
|
||||
@end table
|
||||
|
||||
@c
|
||||
@c testsuites/ Test Suites
|
||||
@c
|
||||
@section testsuites/ Test Suites
|
||||
|
||||
This directory provides all of the RTEMS Test Suite
|
||||
except those for the Classic API Ada95 binding
|
||||
This 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 following table lists the test suites
|
||||
currently included with the RTEMS and the directory in which
|
||||
they may be located:
|
||||
|
||||
@table @code
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/libtests/
|
||||
This directory contains the test suite for the
|
||||
various RTEMS support components.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/mptests/
|
||||
This directory contains the test suite for the
|
||||
multiprocessor support in the Classic API.
|
||||
The tests provided address two node configurations
|
||||
and provide coverage for the multiprocessor code found
|
||||
in RTEMS.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/psxtests/
|
||||
This directory contains the test suite for the
|
||||
RTEMS POSIX API.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/samples/
|
||||
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. They are discussed in
|
||||
@ref{Sample Applications}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/sptests/
|
||||
This directory contains the test suite for the RTEMS
|
||||
Classic API when executing on a single processor.
|
||||
The tests were originally designed to provide
|
||||
near complete test coverage for the entire
|
||||
executive code. With the addition of multiple APIs,
|
||||
this is no longer the case as some SuperCore functionality
|
||||
is not available through the Classic API. Thus
|
||||
some functionality in the SuperCore is only covered
|
||||
by tests in the POSIX API Test Suites.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/support/
|
||||
This directory contains support software and header files
|
||||
for the various test suites.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/tmtests/
|
||||
This directory contains the timing test suite for
|
||||
the RTEMS Classic API. This include tests that
|
||||
benchmark each directive in the Classic API
|
||||
as well as a set of critical SuperCore functions.
|
||||
These tests are important for helping to verify
|
||||
that RTEMS performs as expected on your target hardware.
|
||||
It is not uncommon to discover mistakes in board
|
||||
initialization such as caching being disabled as
|
||||
a side-effect of analyzing the results of these tests.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/testsuites/tools/
|
||||
This directory contains tools which execute on
|
||||
the development host and aid in executing and
|
||||
evaluating the results of the test suite. The
|
||||
tools @code{difftest} compares the output of one
|
||||
or more tests with the expected output. If you
|
||||
place the output of all the @code{tmtests/} in
|
||||
a single file, then the utility @code{sorttimes}
|
||||
will be able to produce a report organizing the
|
||||
execution times by manager.
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
@c
|
||||
@c Documentation Directory
|
||||
@c
|
||||
@section Documentation Directory
|
||||
|
||||
This directory contains the source code for all RTEMS documentation
|
||||
in @code{TexInfo} format as well as utilities used in the generation
|
||||
of the RTEMS documentation set. This source code is used to produce
|
||||
the RTEMS documentation in various formats including PDF, HTML,
|
||||
and PostScript.
|
||||
|
||||
@table @code
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/ada_user/
|
||||
This directory contains the source code for the @cite{RTEMS
|
||||
Applications Ada User's Guide} which documents the Ada95
|
||||
binding to the Classic API. This manual is produced from
|
||||
from the same source base as the @cite{RTEMS Application
|
||||
C User's Guide}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/bsp_howto/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS BSP and Device Driver Development Guide}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/common/
|
||||
This directory contains the source code for the files which
|
||||
are shared across multiple manuals in the RTEMS Documentation Set.
|
||||
This includes the copyright page as well as the timing
|
||||
tables which can be filled in on a per BSP basis in the
|
||||
CPU supplements.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/cpu_supplement/
|
||||
This directory contains the source code for the
|
||||
RTEMS CPU Supplement.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/develenv/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS Development Environment Guide}. This is
|
||||
the document you are currently reading.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/filesystem/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS Filesystem Design Guide}. This manual
|
||||
is a continuous work in process as it attempts to
|
||||
capture the design of the interface between system
|
||||
calls and filesystem implementations as well as the
|
||||
information required by those implementing filesystems.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/images/
|
||||
This directory contains the source code for the graphics
|
||||
used in the HTML version of the RTEMS Documentation.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/networking/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS Network Supplement}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/new_chapters/
|
||||
This directory contains the source code for the new documentation
|
||||
components which have not yet been collected into a new manual or
|
||||
merged into an existing document. Currently, this primarily
|
||||
contains draft documentation for some portions of
|
||||
the facilities implemented in @code{$@{RTEMS_ROOT@}/c/src/libmisc/}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/porting/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS Porting Guide}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/posix1003.1/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS POSIX 1003.1 Compliance Guide}.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/posix_users/
|
||||
This directory contains the source code for the
|
||||
@cite{RTEMS POSIX API User's Guide}. It is important to
|
||||
note that RTEMS' support for POSIX is a combination of
|
||||
functionality provided by RTEMS and the Newlib C Library
|
||||
so some functionality is documented by Newlib.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/relnotes/
|
||||
This directory contains the source code for a formally
|
||||
release notes document. This has not been used for
|
||||
recent RTEMS releases.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/started/
|
||||
This directory contains the source code for the
|
||||
@cite{Getting Started with RTEMS for C/C++ Users} manual.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/tools/
|
||||
This directory contains the source code for the tools
|
||||
used on the development host to assist in producing the
|
||||
RTEMS Documentation. The most important of these tools
|
||||
is @code{bmenu} which generates the hierarchical node
|
||||
linking commands based upon chapter, section, and
|
||||
subsection organization.
|
||||
|
||||
@item $@{RTEMS_ROOT@}/doc/user/
|
||||
This directory contains the source code for the @cite{RTEMS
|
||||
Applications C User's Guide} which documents the Classic API.
|
||||
|
||||
@end table
|
||||
@@ -1,53 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2011.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@node Introduction, Directory Structure, Top, Top
|
||||
@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.
|
||||
@@ -1,464 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2007.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Sample Applications
|
||||
|
||||
@section Introduction
|
||||
|
||||
The RTEMS source distribution includes a set of sample applications
|
||||
that are located in the @code{$@{RTEMS_ROOT@}/testsuites/samples/}
|
||||
directory. These applications are intended to illustrate the
|
||||
basic format of RTEMS single and multiple processor
|
||||
applications and the use of some features. In addition, these
|
||||
relatively simple applications can be used to test locally
|
||||
developed board support packages and device drivers as they
|
||||
exercise a critical subset of RTEMS functionality that is often
|
||||
broken in new BSPs.
|
||||
|
||||
Some of the following sample applications will be covered in
|
||||
more detail in subsequent sections:
|
||||
|
||||
@table @b
|
||||
@item Hello World
|
||||
The RTEMS Hello World test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/hello/}.
|
||||
This test is helpful when testing new RTEMS development environment.
|
||||
|
||||
@item Clock Tick
|
||||
The @code{$@{RTEMS_ROOT@}/testsuites/samples/ticker/}
|
||||
subdirectory provides a test for verification of clock chip
|
||||
device drivers of BSPs.
|
||||
|
||||
@item Base Single Processor
|
||||
A simple single processor test similar to those in the
|
||||
single processor test suite is provided in
|
||||
@code{$@{RTEMS_ROOT@}/testsuites/samples/base_sp/}.
|
||||
|
||||
@item Base Multiple Processor
|
||||
A simple two node multiprocessor test capable of testing an newly
|
||||
developed MPCI layer is provided in
|
||||
@code{$@{RTEMS_ROOT@}/testsuites/samples/base_mp/}.
|
||||
|
||||
@item Capture
|
||||
The RTEMS Capture test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/capture/}.
|
||||
This is an interactive test which demonstrates the capabilities
|
||||
of the RTEMS Capture Engine. It includes a few test threads
|
||||
which generate interesting execution patterns. Look at the
|
||||
file @code{$@{RTEMS_ROOT@}/testsuites/samples/capture/capture.scn}
|
||||
for a sample session.
|
||||
|
||||
@item Constructor/Destructor C++ Test
|
||||
The @code{$@{RTEMS_ROOT@}/testsuites/samples/cdtest/}
|
||||
subdirectory provides a simple C++ application using
|
||||
constructors and destructors. It is only built when
|
||||
C++ is enabled and its primary purpose is to demonstrate
|
||||
that global constructors and destructors work. Since this
|
||||
requires that the linker script for your BSP be correct, this is
|
||||
an important test.
|
||||
|
||||
@item File IO
|
||||
The RTEMS File IO test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/fileio/}.
|
||||
This is an interactive test which allows the user to interact with
|
||||
an ATA/IDE device. It will read the partition table and allow the
|
||||
user to dynamically mount one of the FAT32 partitions it finds.
|
||||
Commands are also provided to write and read files on the disk.
|
||||
|
||||
@item IO Stream
|
||||
The RTEMS IO Stream test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/iostream/}.
|
||||
This test is a simple C++ application which demonstrates that
|
||||
C++ iostreams are functional. This requires that the RTEMS C++
|
||||
run-time support is functioning properly. This test is only
|
||||
build when C++ is enabled.
|
||||
|
||||
@item Network Loopback Test
|
||||
The @code{$@{RTEMS_ROOT@}/testsuites/samples/loopback/}
|
||||
directory contains a sample test that demonstrates the use of
|
||||
sockets and the loopback network device. It does not require
|
||||
the presence of network hardware in order to run.
|
||||
It is only built if RTEMS was configured with networking enabled.
|
||||
|
||||
@item Minimum Size Test
|
||||
The directory
|
||||
@code{$@{RTEMS_ROOT@}/testsuites/samples/minimum/}
|
||||
contains a simple RTEMS program that results in a non-functional
|
||||
executable. It is intended to show the size of a minimum footprint
|
||||
application based upon the current RTEMS configuration.
|
||||
|
||||
@item Nanoseconds
|
||||
The RTEMS Nanoseconds test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/nsecs/}.
|
||||
This test demonstrates that the BSP has support for nanosecond
|
||||
timestamp granularity. It prints the time of day and uptime multiple
|
||||
times as quickly as possible. It should be possible from the output
|
||||
to determine if your BSP has nanosecond accurate clock support
|
||||
and it is functional.
|
||||
|
||||
@item Paranoia Floating Point Test
|
||||
The directory @code{$@{RTEMS_ROOT@}/testsuites/samples/paranoia/}
|
||||
contains the public domain floating point and math library test.
|
||||
|
||||
@item Point-to-Point Protocol Daemon
|
||||
The RTEMS Point-to-Point Protocol Daemon test is provided in
|
||||
the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/pppd/}.
|
||||
This test primarily serves as the baseline for a user application
|
||||
using the PPP protocol.
|
||||
|
||||
@item Unlimited Object Allocation
|
||||
The @code{$@{RTEMS_ROOT@}/testsuites/samples/unlimited/}
|
||||
directory contains a sample test that demonstrates the use of the
|
||||
@i{unlimited} object allocation configuration option to RTEMS.
|
||||
|
||||
@end table
|
||||
|
||||
The sample tests are written using the Classic API so the reader
|
||||
should be familiar with the terms used and
|
||||
material presented in the @b{RTEMS Applications Users Guide}.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Hello World
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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 uses 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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Clock Tick
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Base Single Processor Application
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Base Multiple Processor Application
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Constructor/Destructor C++ Application
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Minimum Size Test
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/samples/minimum/
|
||||
@end example
|
||||
|
||||
This sample application is designed to produce the
|
||||
minimum code space required for any RTEMS application
|
||||
based upon the current RTEMS configuration and
|
||||
BSP. In many situations, the bulk of this executable
|
||||
consists of hardware and RTEMS initialization, basic
|
||||
infrastructure such as malloc(), and RTEMS and
|
||||
hardware shutdown support.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Nanosecond Granularity Application
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/samples/nsecs/
|
||||
@end example
|
||||
|
||||
This sample application exercises the Clock Driver
|
||||
for this BSP and demonstrates its ability to generate
|
||||
accurate timestamps. This application does this by
|
||||
exercising the time subsystem in three ways:
|
||||
|
||||
@itemize @bullet
|
||||
@item Obtain Time of Day Twice Back to Back
|
||||
@item Obtain System Up Time Twice Back to Back
|
||||
@item Use System Up Time to Measure Loops
|
||||
@end itemize
|
||||
|
||||
The following is an example of what the output of this
|
||||
test may appear like:
|
||||
|
||||
@example
|
||||
*** NANOSECOND CLOCK TEST ***
|
||||
10 iterations of getting TOD
|
||||
Start: Sat Mar 24 11:15:00 2007:540000
|
||||
Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:3974000
|
||||
Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:7510000
|
||||
Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:11054000
|
||||
Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:14638000
|
||||
Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:18301000
|
||||
Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:21901000
|
||||
Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:25526000
|
||||
Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000
|
||||
Start: Sat Mar 24 11:15:00 2007:29196000
|
||||
Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000
|
||||
Start: Sat Mar 24 11:15:00 2007:32826000
|
||||
Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000
|
||||
|
||||
10 iterations of getting Uptime
|
||||
0:38977000 0:38986000 --> 0:9000
|
||||
0:40324000 0:40332000 --> 0:8000
|
||||
0:41636000 0:41645000 --> 0:9000
|
||||
0:42949000 0:42958000 --> 0:9000
|
||||
0:44295000 0:44304000 --> 0:9000
|
||||
0:45608000 0:45617000 --> 0:9000
|
||||
0:46921000 0:46930000 --> 0:9000
|
||||
0:48282000 0:48291000 --> 0:9000
|
||||
0:49595000 0:49603000 --> 0:8000
|
||||
0:50908000 0:50917000 --> 0:9000
|
||||
|
||||
10 iterations of getting Uptime with different loop values
|
||||
loop of 10000 0:119488000 0:119704000 --> 0:216000
|
||||
loop of 20000 0:124028000 0:124463000 --> 0:435000
|
||||
loop of 30000 0:128567000 0:129220000 --> 0:653000
|
||||
loop of 40000 0:133097000 0:133964000 --> 0:867000
|
||||
loop of 50000 0:137643000 0:138728000 --> 0:1085000
|
||||
loop of 60000 0:142265000 0:143572000 --> 0:1307000
|
||||
loop of 70000 0:146894000 0:148416000 --> 0:1522000
|
||||
loop of 80000 0:151519000 0:153260000 --> 0:1741000
|
||||
loop of 90000 0:156145000 0:158099000 --> 0:1954000
|
||||
loop of 100000 0:160770000 0:162942000 --> 0:2172000
|
||||
*** END OF NANOSECOND CLOCK TEST ***
|
||||
@end example
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Paranoia Floating Point Application
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/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.
|
||||
|
||||
@c
|
||||
@c
|
||||
@c
|
||||
@section Network Loopback Test
|
||||
|
||||
This sample application is in the following directory:
|
||||
|
||||
@example
|
||||
$@{RTEMS_ROOT@}/testsuites/samples/loopback/
|
||||
@end example
|
||||
|
||||
This sample application uses the network loopback device to
|
||||
demonstrate the use of the RTEMS TCP/IP stack. This sample
|
||||
test illustrates the basic configuration and initialization
|
||||
of the TCP/IP stack as well as simple socket usage.
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 24 February 2013
|
||||
@set UPDATED-MONTH February 2013
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,182 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2007.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter RTEMS Specific Utilities
|
||||
|
||||
This section describes the additional commands
|
||||
available within the @b{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.
|
||||
|
||||
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.
|
||||
|
||||
@c
|
||||
@c packhex
|
||||
@c
|
||||
@section packhex - Compress Hexadecimal File
|
||||
|
||||
@subheading SYNOPSIS
|
||||
|
||||
@example
|
||||
packhex <source >destination
|
||||
@end example
|
||||
|
||||
@subheading DESCRIPTION
|
||||
|
||||
packhex accepts Intel Hexadecimal or Motorola Srecord
|
||||
on its standard input and attempts to pack as many contiguous
|
||||
bytes as possible into a single hexadecimal record. Many
|
||||
programs output hexadecimal records which are less than 80 bytes
|
||||
long (for human viewing). The overhead required by each
|
||||
unnecessary record is significant and packhex can often reduce
|
||||
the size of the download image by 20%. packhex attempts to
|
||||
output records which are as long as the hexadecimal format
|
||||
allows.
|
||||
|
||||
@subheading OPTIONS
|
||||
|
||||
This command has no options.
|
||||
|
||||
@subheading EXAMPLES
|
||||
|
||||
Assume the current directory contains the Motorola
|
||||
Srecord file download.sr. Then executing the command:
|
||||
|
||||
@example
|
||||
packhex <download.sr >packed.sr
|
||||
@end example
|
||||
|
||||
will generate the file packed.sr which is usually
|
||||
smaller than download.sr.
|
||||
|
||||
@subheading CREDITS
|
||||
|
||||
The source for packhex first appeared in the May 1993
|
||||
issue of Embedded Systems magazine. The code was downloaded
|
||||
from their BBS. Unfortunately, the author's name was not
|
||||
provided in the listing.
|
||||
|
||||
@c
|
||||
@c unhex
|
||||
@c
|
||||
@section 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
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 17 July 2015
|
||||
@set UPDATED-MONTH July 2015
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
@@ -1,65 +0,0 @@
|
||||
#
|
||||
# COPYRIGHT (c) 1988-2002.
|
||||
# On-Line Applications Research Corporation (OAR).
|
||||
# All rights reserved.
|
||||
|
||||
PROJECT = filesystem
|
||||
|
||||
include $(top_srcdir)/project.am
|
||||
include $(top_srcdir)/main.am
|
||||
|
||||
BMENU2 += -c
|
||||
|
||||
GENERATED_FILES = patheval.texi init.texi mounting.texi syscalls.texi \
|
||||
fsrequirements.texi imfs.texi miniimfs.texi tftp.texi
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
FILES = preface.texi
|
||||
|
||||
info_TEXINFOS = filesystem.texi
|
||||
filesystem_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
|
||||
|
||||
patheval.texi: patheval.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
init.texi: init.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
mounting.texi: mounting.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
syscalls.texi: syscalls.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
fsrequirements.texi: fsrequirements.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
imfs.texi: imfs.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
miniimfs.texi: miniimfs.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
tftp.texi: tftp.t
|
||||
$(BMENU2) -p "" \
|
||||
-u "Top" \
|
||||
-n "" < $< > $@
|
||||
|
||||
EXTRA_DIST = fsrequirements.t imfs.t init.t miniimfs.t mounting.t patheval.t \
|
||||
syscalls.t tftp.t
|
||||
|
||||
CLEANFILES += filesystem.info filesystem.info-?
|
||||
@@ -1,101 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename filesystem.info
|
||||
@setcontentsaftertitlepage
|
||||
@syncodeindex vr fn
|
||||
@synindex ky cp
|
||||
@paragraphindent 0
|
||||
@c %**end of header
|
||||
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2013.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@c
|
||||
@c Master file for the Filesystem Design Guide
|
||||
@c
|
||||
|
||||
@include version.texi
|
||||
@include common/setup.texi
|
||||
@include common/rtems.texi
|
||||
|
||||
@ifset use-ascii
|
||||
@dircategory RTEMS On-Line Manual
|
||||
@direntry
|
||||
* RTEMS Filesystem Design Guide: (filesystem).
|
||||
@end direntry
|
||||
@end ifset
|
||||
|
||||
@c
|
||||
@c Title Page Stuff
|
||||
@c
|
||||
|
||||
@c
|
||||
@c I don't really like having a short title page. --joel
|
||||
@c
|
||||
@c @shorttitlepage RTEMS Filesystem Design Guide
|
||||
|
||||
@setchapternewpage odd
|
||||
@settitle RTEMS Filesystem Design Guide
|
||||
@titlepage
|
||||
@finalout
|
||||
|
||||
@title RTEMS Filesystem Design Guide
|
||||
@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION}
|
||||
@sp 1
|
||||
@subtitle @value{UPDATED}
|
||||
@author On-Line Applications Research Corporation
|
||||
@page
|
||||
@include common/cpright.texi
|
||||
@end titlepage
|
||||
|
||||
@c This prevents a black box from being printed on "overflow" lines.
|
||||
@c The alternative is to rework a sentence to avoid this problem.
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top, Preface, (dir), (dir)
|
||||
@top RTEMS Filesystem Design Guide
|
||||
|
||||
@menu
|
||||
* Preface::
|
||||
* Pathname Evaluation::
|
||||
* System Initialization::
|
||||
* Mounting and Unmounting Filesystems::
|
||||
* System Call Development Notes::
|
||||
* Filesystem Implementation Requirements::
|
||||
* In-Memory Filesystem::
|
||||
* Miniature In-Memory Filesystem::
|
||||
* Trivial FTP Client Filesystem::
|
||||
* Command and Variable Index::
|
||||
* Concept Index::
|
||||
@end menu
|
||||
@end ifnottex
|
||||
|
||||
@include preface.texi
|
||||
@include patheval.texi
|
||||
@include init.texi
|
||||
@include mounting.texi
|
||||
@include syscalls.texi
|
||||
@include fsrequirements.texi
|
||||
@include imfs.texi
|
||||
@include miniimfs.texi
|
||||
@include tftp.texi
|
||||
|
||||
@node Command and Variable Index, Concept Index, , Top
|
||||
@unnumbered Command and Variable Index
|
||||
|
||||
There are currently no Command and Variable Index entries.
|
||||
|
||||
@c @printindex fn
|
||||
|
||||
@node Concept Index, , Command and Variable Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
There are currently no Concept Index entries.
|
||||
@c @printindex cp
|
||||
|
||||
@bye
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,110 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter System Initialization
|
||||
|
||||
After the RTEMS initialization is performed, the application's
|
||||
initialization will be performed. Part of initialization is a call to
|
||||
rtems_filesystem_initialize(). This routine will mount the `In Memory File
|
||||
System' as the base filesystem. Mounting the base filesystem consists
|
||||
of the following:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Initialization of mount table chain control structure
|
||||
|
||||
@item Allocation of a @code{jnode} structure that will server as the root node
|
||||
of the `In Memory Filesystem'
|
||||
|
||||
@item Initialization of the allocated @code{jnode} with the appropriate OPS,
|
||||
directory handlers and pathconf limits and options.
|
||||
|
||||
@item Allocation of a memory region for filesystem specific global
|
||||
management variables
|
||||
|
||||
@item Creation of first mount table entry for the base filesystem
|
||||
|
||||
@item Initialization of the first mount table chain entry to indicate that
|
||||
the mount point is NULL and the mounted filesystem is the base file
|
||||
system
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
After the base filesystem has been mounted, the following operations are
|
||||
performed under its directory structure:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Creation of the /dev directory
|
||||
|
||||
@item Registration of devices under /dev directory
|
||||
|
||||
@end itemize
|
||||
|
||||
@section Base Filesystem
|
||||
|
||||
RTEMS initially mounts a RAM based file system known as the base file system.
|
||||
The root directory of this file system tree serves as the logical root of the
|
||||
directory hierarchy (Figure 3). Under the root directory a `/dev' directory
|
||||
is created under which all I/O device directories and files are registered as
|
||||
part of the file system hierarchy.
|
||||
|
||||
@example
|
||||
Figure of the tree structure goes here.
|
||||
@end example
|
||||
|
||||
A RAM based file system draws its management resources from memory. File and
|
||||
directory nodes are simply allocated blocks of memory. Data associated with
|
||||
regular files is stored in collections of memory blocks. When the system is
|
||||
turned off or restarted all memory-based components of the file system are
|
||||
lost.
|
||||
|
||||
The base file system serves as a starting point for the mounting of file
|
||||
systems that are resident on semi-permanent storage media. Examples of such
|
||||
media include non- volatile memory, flash memory and IDE hard disk drives
|
||||
(Figure 3). File systems of other types will be mounted onto mount points
|
||||
within the base file system or other file systems that are subordinate to the
|
||||
base file system. The framework set up under the base file system will allow
|
||||
for these new file system types and the unique data and functionality that is
|
||||
required to manage the future file systems.
|
||||
|
||||
@subsection Base Filesystem Mounting
|
||||
|
||||
At present, the first file system to be mounted is the `In Memory File
|
||||
System'. It is mounted using a standard MOUNT() command in which the mount
|
||||
point is NULL. This flags the mount as the first file system to be
|
||||
registered under the operating system and appropriate initialization of file
|
||||
system management information is performed (See figures 4 and 5). If a
|
||||
different file system type is desired as the base file system, alterations
|
||||
must be made to base_fs.c. This routine handles the mount of the base file
|
||||
system.
|
||||
|
||||
|
||||
@example
|
||||
Figure of the mount table chain goes here.
|
||||
@end example
|
||||
|
||||
|
||||
Once the root of the base file system has been established and it has been
|
||||
recorded as the mount point of the base file system, devices are integrated
|
||||
into the base file system. For every device that is configured into the
|
||||
system (See ioman.c) a device registration process is performed. Device
|
||||
registration produces a unique dev_t handle that consists of a major and
|
||||
minor device number. In addition, the configuration information for each
|
||||
device contains a text string that represents the fully qualified pathname to
|
||||
that device's place in the base file system's hierarchy. A file system node
|
||||
is created for the device along the specified registration path.
|
||||
|
||||
|
||||
@example
|
||||
Figure of the Mount Table Processing goes here.
|
||||
@end example
|
||||
|
||||
|
||||
Note: Other file systems can be mounted but they are mounted onto points
|
||||
(directory mount points) in the base file system.
|
||||
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Miniature In-Memory Filesystem
|
||||
|
||||
This chapter describes the Miniature In-Memory FileSystem (miniIMFS).
|
||||
The miniIMFS is a reduced feature version of the IMFS designed to
|
||||
provide minimal functionality and have a low memory footprint.
|
||||
|
||||
This chapter should be written after the IMFS chapter is completed
|
||||
and describe the implementation of the mini-IMFS.
|
||||
@@ -1,168 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Mounting and Unmounting Filesystems
|
||||
|
||||
@section Mount Points
|
||||
|
||||
The following is the list of the characteristics of a mount point:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item The mount point must be a directory. It may have files and other
|
||||
directories under it. These files and directories will be hidden when the
|
||||
filesystem is mounted.
|
||||
|
||||
@item The task must have read/write/execute permissions to the mount point
|
||||
or the mount attempt will be rejected.
|
||||
|
||||
@item Only one filesystem can be mounted to a single mount point.
|
||||
|
||||
@item The Root of the mountable filesystem will be referenced by the name
|
||||
of the mount point after the mount is complete.
|
||||
|
||||
@end itemize
|
||||
|
||||
@section Mount Table Chain
|
||||
|
||||
The mount table chain is a dynamic list of structures that describe
|
||||
mounted filesystems a specific points in the filesystem hierarchy. It is
|
||||
initialized to an empty state during the base filesystem initialization.
|
||||
The mount operation will add entries to the mount table chain. The
|
||||
un-mount operation will remove entries from the mount table chain.
|
||||
|
||||
Each entry in the mount table chain is of the following type:
|
||||
|
||||
@example
|
||||
struct rtems_filesystem_mount_table_entry_tt
|
||||
@{
|
||||
Chain_Node Node;
|
||||
rtems_filesystem_location_info_t mt_point_node;
|
||||
rtems_filesystem_location_info_t mt_fs_root;
|
||||
int options;
|
||||
void *fs_info;
|
||||
|
||||
rtems_filesystem_limits_and_options_t pathconf_limits_and_options;
|
||||
|
||||
/*
|
||||
* When someone adds a mounted filesystem on a real device,
|
||||
* this will need to be used.
|
||||
*
|
||||
* The best option long term for this is probably an
|
||||
* open file descriptor.
|
||||
*/
|
||||
char *dev;
|
||||
@};
|
||||
@end example
|
||||
|
||||
@table @b
|
||||
@item Node
|
||||
The Node is used to produce a linked list of mount table entry nodes.
|
||||
|
||||
@item mt_point_node
|
||||
The mt_point_node contains all information necessary to access the
|
||||
directory where a filesystem is mounted onto. This element may contain
|
||||
memory that is allocated during a path evaluation of the filesystem
|
||||
containing the mountpoint directory. The generic code allows this
|
||||
memory to be returned by unmount when the filesystem identified by
|
||||
mt_fs_root is unmounted.
|
||||
|
||||
@item mt_fs_root
|
||||
The mt_fs_root contains all information necessary to identify the root
|
||||
of the mounted filesystem. The user is never allowed access to this
|
||||
node by the generic code, but it is used to identify to the mounted
|
||||
filesystem where to start evaluation of pathnames at.
|
||||
|
||||
@item options
|
||||
XXX
|
||||
|
||||
@item fs_info
|
||||
The fs_info element is a location available for use by the mounted file
|
||||
system to identify unique things applicable to this instance of the file
|
||||
system. For example the IMFS uses this space to provide node
|
||||
identification that is unique for each instance (mounting) of the filesystem.
|
||||
|
||||
@item pathconf_limits_and_options
|
||||
XXX
|
||||
|
||||
@item dev
|
||||
This character string represents the device where the filesystem will reside.
|
||||
|
||||
@end table
|
||||
|
||||
@section Adding entries to the chain during mount
|
||||
|
||||
When a filesystem is mounted, its presence and location in the file
|
||||
system hierarchy is recorded in a dynamic list structure known as a chain.
|
||||
A unique rtems_filesystem_mount_table_entry_tt structure is logged for
|
||||
each filesystem that is mounted. This includes the base filesystem.
|
||||
|
||||
@section Removing entries from the chain during unmount
|
||||
|
||||
When a filesystem is dismounted its entry in the mount table chain is
|
||||
extracted and the memory for this entry is freed.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,106 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Pathname Evaluation
|
||||
|
||||
This chapter describes the pathname evaluation process for the
|
||||
RTEMS Filesystem Infrastructure.
|
||||
|
||||
@example
|
||||
XXX Include graphic of the path evaluation process
|
||||
@end example
|
||||
|
||||
@section Pathname Evaluation Handlers
|
||||
|
||||
There are two pathname evaluation routines. The handler patheval()
|
||||
is called to find, verify privlages on and return information on a node
|
||||
that exists. The handler evalformake() is called to find, verify
|
||||
permissions, and return information on a node that is to become a parent.
|
||||
Additionally, evalformake() returns a pointer to the start of the name of
|
||||
the new node to be created.
|
||||
|
||||
Pathname evaluation is specific to a filesystem.
|
||||
Each filesystem is required to provide both a patheval() and an evalformake()
|
||||
routine. Both of these routines gets a name to evaluate and a node indicating
|
||||
where to start the evaluation.
|
||||
|
||||
@section Crossing a Mount Point During Path Evaluation
|
||||
|
||||
If the filesystem supports the mount command, the evaluate routines
|
||||
must handle crossing the mountpoint. The evaluate routine should evaluate
|
||||
the name upto the first directory node where the new filesystem is mounted.
|
||||
The filesystem may process terminator characters prior to calling the
|
||||
evaluate routine for the new filesystem. A pointer to the portion of the
|
||||
name which has not been evaluated along with the root node of the new
|
||||
file system ( gotten from the mount table entry ) is passed to the correct
|
||||
mounted filesystem evaluate routine.
|
||||
|
||||
|
||||
@section The rtems_filesystem_location_info_t Structure
|
||||
|
||||
The @code{rtems_filesystem_location_info_t} structure contains all information
|
||||
necessary for identification of a node.
|
||||
|
||||
The generic rtems filesystem code defines two global
|
||||
rtems_filesystem_location_info_t structures, the
|
||||
@code{rtems_filesystem_root} and the @code{rtems_filesystem_current}.
|
||||
Both are initially defined to be the root node of the base filesystem.
|
||||
Once the chdir command is correctly used the @code{rtems_filesystem_current}
|
||||
is set to the location specified by the command.
|
||||
|
||||
The filesystem generic code peeks at the first character in the name to be
|
||||
evaluated. If this character is a valid seperator, the
|
||||
@code{rtems_filesystem_root} is used as the node to start the evaluation
|
||||
with. Otherwise, the @code{rtems_filesystem_current} node is used as the
|
||||
node to start evaluating with. Therefore, a valid
|
||||
rtems_filesystem_location_info_t is given to the evaluate routine to start
|
||||
evaluation with. The evaluate routines are then responsible for making
|
||||
any changes necessary to this structure to correspond to the name being
|
||||
parsed.
|
||||
|
||||
@example
|
||||
struct rtems_filesystem_location_info_tt @{
|
||||
void *node_access;
|
||||
rtems_filesystem_file_handlers_r *handlers;
|
||||
rtems_filesystem_operations_table *ops;
|
||||
rtems_filesystem_mount_table_entry_t *mt_entry;
|
||||
@};
|
||||
@end example
|
||||
|
||||
@table @b
|
||||
|
||||
@item node_access
|
||||
This element is filesystem specific. A filesystem can define and store
|
||||
any information necessary to identify a node at this location. This element
|
||||
is normally filled in by the filesystem's evaluate routine. For the
|
||||
filesystem's root node, the filesystem's initilization routine should
|
||||
fill this in, and it should remain valid until the instance of the
|
||||
filesystem is unmounted.
|
||||
|
||||
@item handlers
|
||||
This element is defined as a set of routines that may change within a
|
||||
given filesystem based upon node type. For example a directory and a
|
||||
memory file may have to completely different read routines. This element
|
||||
is set to an initialization state defined by the mount table, and may
|
||||
be set to the desired state by the evaluation routines.
|
||||
|
||||
@item ops
|
||||
This element is defined as a set of routines that remain static for the
|
||||
filesystem. This element identifies entry points into the filesystem
|
||||
to the generic code.
|
||||
|
||||
@item mt_entry
|
||||
This element identifies the mount table entry for this instance of the
|
||||
filesystem.
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1989-2011.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@node Preface, , Top, Top
|
||||
@unnumbered Preface
|
||||
|
||||
This document describes the implementation of the RTEMS filesystem
|
||||
infrastructure. This infrastructure supports the following
|
||||
capabilities:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item Mountable file systems
|
||||
|
||||
@item Hierarchical file system directory structure
|
||||
|
||||
@item POSIX compliant set of routines for the manipulation of files and directories
|
||||
|
||||
@item Individual file and directory support for the following:
|
||||
|
||||
@enumerate
|
||||
|
||||
@item Permissions for read, write and execute
|
||||
|
||||
@item User ID
|
||||
|
||||
@item Group ID
|
||||
|
||||
@item Access time
|
||||
|
||||
@item Modification time
|
||||
|
||||
@item Creation time
|
||||
|
||||
@end enumerate
|
||||
|
||||
@item Hard links to files and directories
|
||||
|
||||
@item Symbolic links to files and directories
|
||||
|
||||
@end itemize
|
||||
|
||||
This has been implemented to provide the framework for a UNIX-like
|
||||
file system support. POSIX file and directory functions have been
|
||||
implemented that allow a standard method of accessing file, device and
|
||||
directory information within file systems. The file system concept that
|
||||
has been implemented allows for expansion and adaptation of the file
|
||||
system to a variety of existing and future data storage devices. To this
|
||||
end, file system mount and unmount capabilities have been included in this
|
||||
RTEMS framework.
|
||||
|
||||
This framework slightly alters the manner in which devices are handled
|
||||
under RTEMS from that of public release 4.0.0 and earlier. Devices that
|
||||
are defined under a given RTEMS configuration will now be registered as
|
||||
files in a mounted file system. Access to these device drivers and their
|
||||
associated devices may now be performed through the traditional file system
|
||||
open(), read(), write(), lseek(), fstat() and ioctl() functions in addition
|
||||
to the interface provided by the IO Manager in the RTEMS Classic API.
|
||||
|
||||
An In-Memory File System (IMFS) is included which provides full POSIX
|
||||
filesystem functionality yet is RAM based. The IMFS maintains a
|
||||
node structure for each file, device, and directory in each mounted
|
||||
instantiation of its file system. The node structure is used to
|
||||
manage ownership, access rights, access time, modification time,
|
||||
and creation time. A union of structures within the IMFS nodal
|
||||
structure provide for manipulation of file data, device selection,
|
||||
or directory content as required by the nodal type. Manipulation of
|
||||
these properties is accomplished through the POSIX set of file and
|
||||
directory functions. In addition to being useful in its own right,
|
||||
the IMFS serves as a full featured example filesystem.
|
||||
|
||||
The intended audience for this document is those persons implementing
|
||||
their own filesystem. Users of the filesystem may find information
|
||||
on the implementation useful. But the user interface to the filesystem
|
||||
is through the ISO/ANSI C Library and POSIX 1003.1b file and directory
|
||||
APIs.
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 24 February 2013
|
||||
@set UPDATED-MONTH February 2013
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,11 +0,0 @@
|
||||
@c
|
||||
@c COPYRIGHT (c) 1988-2002.
|
||||
@c On-Line Applications Research Corporation (OAR).
|
||||
@c All rights reserved.
|
||||
|
||||
@chapter Trivial FTP Client Filesystem
|
||||
|
||||
This chapter describes the Trivial FTP (TFTP) Client Filesystem.
|
||||
|
||||
This chapter should be written after the IMFS chapter is completed
|
||||
and describe the implementation of the TFTP.
|
||||
@@ -1,4 +0,0 @@
|
||||
@set UPDATED 17 July 2015
|
||||
@set UPDATED-MONTH July 2015
|
||||
@set EDITION 4.10.99.0
|
||||
@set VERSION 4.10.99.0
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 2.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 156 B |
Binary file not shown.
|
Before Width: | Height: | Size: 166 B |
Binary file not shown.
|
Before Width: | Height: | Size: 275 B |
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user