summaryrefslogtreecommitdiffstats
path: root/cpukit/score
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--cpukit/score/Doxyfile1078
-rw-r--r--cpukit/score/cpu/no_cpu/rtems/score/cpu.h763
-rw-r--r--cpukit/score/include/rtems/debug.h10
-rw-r--r--cpukit/score/include/rtems/score/address.h19
-rw-r--r--cpukit/score/include/rtems/score/apiext.h112
-rw-r--r--cpukit/score/include/rtems/score/apimutex.h88
-rw-r--r--cpukit/score/include/rtems/score/bitfield.h69
-rw-r--r--cpukit/score/include/rtems/score/chain.h163
-rw-r--r--cpukit/score/include/rtems/score/context.h125
-rw-r--r--cpukit/score/include/rtems/score/copyrt.h18
-rw-r--r--cpukit/score/include/rtems/score/coremsg.h251
-rw-r--r--cpukit/score/include/rtems/score/coremutex.h223
-rw-r--r--cpukit/score/include/rtems/score/coresem.h115
-rw-r--r--cpukit/score/include/rtems/score/heap.h232
-rw-r--r--cpukit/score/include/rtems/score/interr.h32
-rw-r--r--cpukit/score/include/rtems/score/isr.h124
-rw-r--r--cpukit/score/include/rtems/score/mpci.h206
-rw-r--r--cpukit/score/include/rtems/score/mppkt.h50
-rw-r--r--cpukit/score/include/rtems/score/objectmp.h56
-rw-r--r--cpukit/score/include/rtems/score/priority.h22
-rw-r--r--cpukit/score/include/rtems/score/stack.h18
-rw-r--r--cpukit/score/include/rtems/score/states.h18
-rw-r--r--cpukit/score/include/rtems/score/sysstate.h18
-rw-r--r--cpukit/score/include/rtems/score/thread.h400
-rw-r--r--cpukit/score/include/rtems/score/threadmp.h54
-rw-r--r--cpukit/score/include/rtems/score/threadq.h135
-rw-r--r--cpukit/score/include/rtems/score/tod.h198
-rw-r--r--cpukit/score/include/rtems/score/tqdata.h18
-rw-r--r--cpukit/score/include/rtems/score/userext.h133
-rw-r--r--cpukit/score/include/rtems/score/watchdog.h166
-rw-r--r--cpukit/score/include/rtems/score/wkspace.h45
-rw-r--r--cpukit/score/include/rtems/seterr.h9
-rw-r--r--cpukit/score/include/rtems/system.h11
-rw-r--r--cpukit/score/inline/rtems/score/address.inl53
-rw-r--r--cpukit/score/inline/rtems/score/chain.inl174
-rw-r--r--cpukit/score/inline/rtems/score/coremsg.inl100
-rw-r--r--cpukit/score/inline/rtems/score/coremutex.inl61
-rw-r--r--cpukit/score/inline/rtems/score/coresem.inl57
-rw-r--r--cpukit/score/inline/rtems/score/heap.inl116
-rw-r--r--cpukit/score/inline/rtems/score/isr.inl31
-rw-r--r--cpukit/score/inline/rtems/score/mppkt.inl32
-rw-r--r--cpukit/score/inline/rtems/score/objectmp.inl37
-rw-r--r--cpukit/score/inline/rtems/score/priority.inl93
-rw-r--r--cpukit/score/inline/rtems/score/stack.inl39
-rw-r--r--cpukit/score/inline/rtems/score/states.inl164
-rw-r--r--cpukit/score/inline/rtems/score/sysstate.inl72
-rw-r--r--cpukit/score/inline/rtems/score/thread.inl172
-rw-r--r--cpukit/score/inline/rtems/score/threadmp.inl30
-rw-r--r--cpukit/score/inline/rtems/score/tod.inl37
-rw-r--r--cpukit/score/inline/rtems/score/tqdata.inl39
-rw-r--r--cpukit/score/inline/rtems/score/userext.inl53
-rw-r--r--cpukit/score/inline/rtems/score/watchdog.inl121
-rw-r--r--cpukit/score/inline/rtems/score/wkspace.inl30
-rw-r--r--cpukit/score/mainpage.h5
54 files changed, 3697 insertions, 2798 deletions
diff --git a/cpukit/score/Doxyfile b/cpukit/score/Doxyfile
new file mode 100644
index 0000000000..4f009ac628
--- /dev/null
+++ b/cpukit/score/Doxyfile
@@ -0,0 +1,1078 @@
+# Doxyfile 1.3.4
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+# TAG = value [value, ...]
+# For lists items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME = RTEMS SuperCore
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER =
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY =
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch,
+# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en
+# (Japanese with English messages), Korean, Norwegian, Polish, Portuguese,
+# Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
+
+OUTPUT_LANGUAGE = English
+
+# This tag can be used to specify the encoding used in the generated output.
+# The encoding is not always determined by the language that is chosen,
+# but also whether or not the output is meant for Windows or non-Windows users.
+# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES
+# forces the Windows encoding (this is the default for the Windows binary),
+# whereas setting the tag to NO uses a Unix-style encoding (the default for
+# all platforms other than Windows).
+
+USE_WINDOWS_ENCODING = NO
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
+# members of a class in the documentation of that class as if those members were
+# ordinary class members. Constructors, destructors and assignment operators of
+# the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. It is allowed to use relative paths in the argument list.
+
+STRIP_FROM_PATH =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like the Qt-style comments (thus requiring an
+# explict @brief command for a brief description.
+
+JAVADOC_AUTOBRIEF = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# reimplements.
+
+INHERIT_DOCS = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
+# only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = YES
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
+# only. Doxygen will then generate output that is more tailored for Java.
+# For instance, namespaces will be presented as packages, qualified scopes
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = YES
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES = NO
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# users are advised to set this option to NO.
+
+CASE_SENSE_NAMES = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS = YES
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR = YES
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text.
+
+WARN_FORMAT = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT = include inline no_cpu
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
+# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc
+
+FILE_PATTERNS = *.h *.inl
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE = YES
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
+# that are symbolic links (a Unix filesystem feature) are excluded from the input.
+
+EXCLUDE_SYMLINKS = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories.
+
+EXCLUDE_PATTERNS =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS =
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output.
+
+INPUT_FILTER =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+
+SOURCE_BROWSER = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default)
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default)
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION = YES
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER =
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER =
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet
+
+HTML_STYLESHEET =
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output dir.
+
+CHM_FILE =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX = NO
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
+# probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX = YES
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE = a4wide
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX = NO
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimised for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assigments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_XML = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader. This is useful
+# if you want to understand what is going on. On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_PREDEFINED tags.
+
+EXPAND_ONLY_PREDEF = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed.
+
+PREDEFINED = RTEMS_INLINES
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line, have an all uppercase name, and do not end with a semicolon. Such
+# function macros are typically used for boiler-plate code, and will confuse the
+# parser if not removed.
+
+SKIP_FUNCTION_MACROS = YES
+
+#---------------------------------------------------------------------------
+# Configuration::addtions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+# TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+# TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base or
+# super classes. Setting the tag to NO turns the diagrams off. Note that this
+# option is superceded by the HAVE_DOT option below. This is only a fallback. It is
+# recommended to install and use dot, since it yields more powerful graphs.
+
+CLASS_DIAGRAMS = YES
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT = NO
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similiar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH = YES
+
+# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will
+# generate a call dependency graph for every global function or class method.
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable call graphs for selected
+# functions only using the \callgraph command.
+
+CALL_GRAPH = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found on the path.
+
+DOT_PATH =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS =
+
+# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_WIDTH = 1024
+
+# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_HEIGHT = 1024
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes that
+# lay further from the root node will be omitted. Note that setting this option to
+# 1 or 2 may greatly reduce the computation time needed for large code bases. Also
+# note that a graph may be further truncated if the graph's image dimensions are
+# not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH and MAX_DOT_GRAPH_HEIGHT).
+# If 0 is used for the depth value (the default), the graph is not depth-constrained.
+
+MAX_DOT_GRAPH_DEPTH = 0
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP = YES
+
+#---------------------------------------------------------------------------
+# Configuration::addtions related to the search engine
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE = NO
diff --git a/cpukit/score/cpu/no_cpu/rtems/score/cpu.h b/cpukit/score/cpu/no_cpu/rtems/score/cpu.h
index 0c56f78232..d5d8f8aba1 100644
--- a/cpukit/score/cpu/no_cpu/rtems/score/cpu.h
+++ b/cpukit/score/cpu/no_cpu/rtems/score/cpu.h
@@ -1,9 +1,22 @@
-/* cpu.h
+/** @file cpu.h
*
* This include file contains information pertaining to the XXX
* processor.
*
- * COPYRIGHT (c) 1989-1999.
+ * @note This file is part of a porting template that is intended
+ * to be used as the starting point when porting RTEMS to a new
+ * CPU family. The following needs to be done when using this as
+ * the starting point for a new port:
+ *
+ * + Anywhere there is an XXX, it should be replaced
+ * with information about the CPU family being ported to.
+ *
+ * + At the end of each comment section, there is a heading which
+ * says "Port Specific Information:". When porting to RTEMS,
+ * add CPU family specific information in this section
+ */
+
+/* COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -27,30 +40,30 @@ extern "C" {
/* conditional compilation parameters */
-/*
- * Should the calls to _Thread_Enable_dispatch be inlined?
+/**
+ * Should the calls to @ref _Thread_Enable_dispatch be inlined?
*
* If TRUE, then they are inlined.
* If FALSE, then a subroutine call is made.
*
- * Basically this is an example of the classic trade-off of size
+ * This conditional is an example of the classic trade-off of size
* versus speed. Inlining the call (TRUE) typically increases the
* size of RTEMS while speeding up the enabling of dispatching.
- * [NOTE: In general, the _Thread_Dispatch_disable_level will
+ *
+ * @note In general, the @ref _Thread_Dispatch_disable_level will
* only be 0 or 1 unless you are in an interrupt handler and that
* interrupt handler invokes the executive.] When not inlined
- * something calls _Thread_Enable_dispatch which in turns calls
- * _Thread_Dispatch. If the enable dispatch is inlined, then
- * one subroutine call is avoided entirely.]
+ * something calls @ref _Thread_Enable_dispatch which in turns calls
+ * @ref _Thread_Dispatch. If the enable dispatch is inlined, then
+ * one subroutine call is avoided entirely.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_INLINE_ENABLE_DISPATCH FALSE
-/*
+/**
* Should the body of the search loops in _Thread_queue_Enqueue_priority
* be unrolled one time? In unrolled each iteration of the loop examines
* two "nodes" on the chain being searched. Otherwise, only one node
@@ -67,17 +80,16 @@ extern "C" {
* code is the longest interrupt disable period in RTEMS. So it is
* necessary to strike a balance when setting this parameter.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_UNROLL_ENQUEUE_PRIORITY TRUE
-/*
+/**
* Does RTEMS manage a dedicated interrupt stack in software?
*
- * If TRUE, then a stack is allocated in _ISR_Handler_initialization.
+ * If TRUE, then a stack is allocated in @ref _ISR_Handler_initialization.
* If FALSE, nothing is done.
*
* If the CPU supports a dedicated interrupt stack in hardware,
@@ -89,75 +101,73 @@ extern "C" {
* stack of the interrupted task, and (2) have RTEMS manage a dedicated
* interrupt stack.
*
- * If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
*
- * Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
- * CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is
+ * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
+ * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is
* possible that both are FALSE for a particular CPU. Although it
* is unclear what that would imply about the interrupt processing
* procedure on that CPU.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_HAS_SOFTWARE_INTERRUPT_STACK FALSE
-/*
+/**
* Does this CPU have hardware support for a dedicated interrupt stack?
*
* If TRUE, then it must be installed during initialization.
* If FALSE, then no installation is performed.
*
- * If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
+ * If this is TRUE, @ref CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.
*
- * Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and
- * CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is
+ * Only one of @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK and
+ * @ref CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is
* possible that both are FALSE for a particular CPU. Although it
* is unclear what that would imply about the interrupt processing
* procedure on that CPU.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_HAS_HARDWARE_INTERRUPT_STACK TRUE
-/*
+/**
* Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?
*
* If TRUE, then the memory is allocated during initialization.
* If FALSE, then the memory is allocated during initialization.
*
- * This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
- * or CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
+ * This should be TRUE is @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE
+ * or @ref CPU_INSTALL_HARDWARE_INTERRUPT_STACK is TRUE.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
-/*
+/**
* Does the RTEMS invoke the user's ISR with the vector number and
* a pointer to the saved interrupt frame (1) or just the vector
* number (0)?
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_ISR_PASSES_FRAME_POINTER 0
-/*
+/**
+ * @def CPU_HARDWARE_FP
+ *
* Does the CPU have hardware floating point?
*
- * If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported.
- * If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.
+ * If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is supported.
+ * If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is ignored.
*
* If there is a FP coprocessor such as the i387 or mc68881, then
* the answer is TRUE.
@@ -167,18 +177,25 @@ extern "C" {
* example, it would be possible to have an i386_nofp CPU model
* which set this to false to indicate that you have an i386 without
* an i387 and wish to leave floating point support out of RTEMS.
+ */
+
+/**
+ * @def CPU_SOFTWARE_FP
+ *
+ * Does the CPU have no hardware floating point and GCC provides a
+ * software floating point implementation which must be context
+ * switched?
*
- * The CPU_SOFTWARE_FP is used to indicate whether or not there
+ * This feature conditional is used to indicate whether or not there
* is software implemented floating point that must be context
* switched. The determination of whether or not this applies
* is very tool specific and the state saved/restored is also
* compiler specific.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#if ( NO_CPU_HAS_FPU == 1 )
#define CPU_HARDWARE_FP TRUE
#else
@@ -186,11 +203,11 @@ extern "C" {
#endif
#define CPU_SOFTWARE_FP FALSE
-/*
+/**
* Are all tasks RTEMS_FLOATING_POINT tasks implicitly?
*
- * If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed.
- * If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.
+ * If TRUE, then the @ref RTEMS_FLOATING_POINT task attribute is assumed.
+ * If FALSE, then the @ref RTEMS_FLOATING_POINT task attribute is followed.
*
* So far, the only CPUs in which this option has been used are the
* HP PA-RISC and PowerPC. On the PA-RISC, The HP C compiler and
@@ -204,19 +221,18 @@ extern "C" {
* then one can not easily predict which tasks will use the FP hardware.
* In this case, this option should be TRUE.
*
- * If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
+ * If @ref CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_ALL_TASKS_ARE_FP TRUE
-/*
+/**
* Should the IDLE task have a floating point context?
*
- * If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task
+ * If TRUE, then the IDLE task is created as a @ref RTEMS_FLOATING_POINT task
* and it has a floating point context which is switched in and out.
* If FALSE, then the IDLE task does not have a floating point context.
*
@@ -224,14 +240,13 @@ extern "C" {
* the IDLE task from an interrupt because the floating point context
* must be saved as part of the preemption.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_IDLE_TASK_IS_FP FALSE
-/*
+/**
* Should the saving of the floating point registers be deferred
* until a context switch is made to another different floating point
* task?
@@ -256,19 +271,18 @@ extern "C" {
* Thus in a system with only one FP task, the FP context will never
* be saved or restored.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_USE_DEFERRED_FP_SWITCH TRUE
-/*
+/**
* Does this port provide a CPU dependent IDLE task implementation?
*
- * If TRUE, then the routine _CPU_Thread_Idle_body
+ * If TRUE, then the routine @ref _CPU_Thread_Idle_body
* must be provided and is the default IDLE thread body instead of
- * _CPU_Thread_Idle_body.
+ * @ref _CPU_Thread_Idle_body.
*
* If FALSE, then use the generic IDLE thread body if the BSP does
* not provide one.
@@ -279,32 +293,30 @@ extern "C" {
*
* The order of precedence for selecting the IDLE thread body is:
*
- * 1. BSP provided
- * 2. CPU dependent (if provided)
- * 3. generic (if no BSP and no CPU dependent)
+ * -# BSP provided
+ * -# CPU dependent (if provided)
+ * -# generic (if no BSP and no CPU dependent)
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_PROVIDES_IDLE_THREAD_BODY TRUE
-/*
+/**
* Does the stack grow up (toward higher addresses) or down
* (toward lower addresses)?
*
* If TRUE, then the grows upward.
* If FALSE, then the grows toward smaller addresses.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_STACK_GROWS_UP TRUE
-/*
+/**
* The following is the variable attribute used to force alignment
* of critical RTEMS structures. On some processors it may make
* sense to have these aligned on tighter boundaries than
@@ -318,64 +330,91 @@ extern "C" {
*
* __attribute__ ((aligned (32)))
*
- * NOTE: Currently only the Priority Bit Map table uses this feature.
- * To benefit from using this, the data must be heavily
- * used so it will stay in the cache and used frequently enough
- * in the executive to justify turning this on.
+ * @note Currently only the Priority Bit Map table uses this feature.
+ * To benefit from using this, the data must be heavily
+ * used so it will stay in the cache and used frequently enough
+ * in the executive to justify turning this on.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_STRUCTURE_ALIGNMENT
-/*
+/**
+ * @defgroup CPUEndian Processor Dependent Endianness Support
+ *
+ * This group assists in issues related to processor endianness.
+ */
+
+/**
+ * @ingroup CPUEndian
* Define what is required to specify how the network to host conversion
* routines are handled.
*
- * NO_CPU Specific Information:
+ * @note @a CPU_BIG_ENDIAN and @a CPU_LITTLE_ENDIAN should NOT have the
+ * same values.
+ *
+ * @see CPU_LITTLE_ENDIAN
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
-#define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES FALSE
#define CPU_BIG_ENDIAN TRUE
+
+/**
+ * @ingroup CPUEndian
+ * Define what is required to specify how the network to host conversion
+ * routines are handled.
+ *
+ * @note @ref CPU_BIG_ENDIAN and @ref CPU_LITTLE_ENDIAN should NOT have the
+ * same values.
+ *
+ * @see CPU_BIG_ENDIAN
+ *
+ * Port Specific Information:
+ *
+ * XXX document implementation including references if appropriate
+ */
#define CPU_LITTLE_ENDIAN FALSE
-/*
+/**
+ * @ingroup CPUInterrupt
* The following defines the number of bits actually used in the
* interrupt field of the task mode. How those bits map to the
- * CPU interrupt levels is defined by the routine _CPU_ISR_Set_level().
+ * CPU interrupt levels is defined by the routine @ref _CPU_ISR_Set_level.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_MODES_INTERRUPT_MASK 0x00000001
/*
* Processor defined structures required for cpukit/score.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
/* may need to put some structures here. */
-/*
- * Contexts
+/**
+ * @defgroup CPUContext Processor Dependent Context Management
*
- * Generally there are 2 types of context to save.
- * 1. Interrupt registers to save
- * 2. Task level registers to save
+ * From the highest level viewpoint, there are 2 types of context to save.
*
- * This means we have the following 3 context items:
- * 1. task level context stuff:: Context_Control
- * 2. floating point task stuff:: Context_Control_fp
- * 3. special interrupt level context :: Context_Control_interrupt
+ * -# Interrupt registers to save
+ * -# Task level registers to save
+ *
+ * Since RTEMS handles integer and floating point contexts separately, this
+ * means we have the following 3 context items:
+ *
+ * -# task level context stuff:: Context_Control
+ * -# floating point task stuff:: Context_Control_fp
+ * -# special interrupt level context :: CPU_Interrupt_frame
*
* On some processors, it is cost-effective to save only the callee
* preserved registers during a task context switch. This means
@@ -399,54 +438,109 @@ extern "C" {
* this is enough information for RTEMS, it is probably not enough for
* a debugger such as gdb. But that is another problem.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
+/**
+ * @ingroup CPUContext Management
+ * This defines the minimal set of integer and processor state registers
+ * that must be saved during a voluntary context switch from one thread
+ * to another.
+ */
typedef struct {
+ /** This field is a hint that a port will have a number of integer
+ * registers that need to be saved at a context switch.
+ */
uint32_t some_integer_register;
+ /** This field is a hint that a port will have a number of system
+ * registers that need to be saved at a context switch.
+ */
uint32_t some_system_register;
} Context_Control;
+/**
+ * @ingroup CPUContext Management
+ * This defines the complete set of floating point registers that must
+ * be saved during any context switch from one thread to another.
+ */
typedef struct {
double some_float_register;
} Context_Control_fp;
+/**
+ * @ingroup CPUContext Management
+ * This defines the set of integer and processor state registers that must
+ * be saved during an interrupt. This set does not include any which are
+ * in @ref Context_Control.
+ */
typedef struct {
+ /** This field is a hint that a port will have a number of integer
+ * registers that need to be saved when an interrupt occurs or
+ * when a context switch occurs at the end of an ISR.
+ */
uint32_t special_interrupt_register;
} CPU_Interrupt_frame;
-/*
+/**
* The following table contains the information required to configure
* the XXX processor specific parameters.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
typedef struct {
+ /** This element points to the BSP's pretasking hook. */
void (*pretasking_hook)( void );
+ /** This element points to the BSP's predriver hook. */
void (*predriver_hook)( void );
+ /** This element points to the BSP's postdriver hook. */
void (*postdriver_hook)( void );
+ /** This element points to the BSP's optional idle task which may override
+ * the default one provided with RTEMS.
+ */
void (*idle_task)( void );
+ /** If this element is TRUE, then RTEMS will zero the Executive Workspace.
+ * When this element is FALSE, it is assumed that the BSP or invoking
+ * environment has ensured that memory was cleared before RTEMS was
+ * invoked.
+ */
boolean do_zero_of_workspace;
+ /** This field specifies the size of the IDLE task's stack. If less than or
+ * equal to the minimum stack size, then the IDLE task will have the minimum
+ * stack size.
+ */
uint32_t idle_task_stack_size;
+ /** This field specifies the size of the interrupt stack. If less than or
+ * equal to the minimum stack size, then the interrupt stack will be of
+ * minimum stack size.
+ */
uint32_t interrupt_stack_size;
+ /** The MPCI Receive server is assumed to have a stack of at least
+ * minimum stack size. This field specifies the amount of extra
+ * stack this task will be given in bytes.
+ */
uint32_t extra_mpci_receive_server_stack;
+ /** The BSP may want to provide it's own stack allocation routines.
+ * In this case, the BSP will provide this stack allocation hook.
+ */
void * (*stack_allocate_hook)( uint32_t );
- void (*stack_free_hook)( void* );
+ /** The BSP may want to provide it's own stack free routines.
+ * In this case, the BSP will provide this stack free hook.
+ */
+ void (*stack_free_hook)( void *);
/* end of fields required on all CPUs */
-
} rtems_cpu_table;
/*
* Macros to access required entires in the CPU Table are in
* the file rtems/system.h.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
@@ -454,256 +548,279 @@ typedef struct {
/*
* Macros to access NO_CPU specific additions to the CPU Table
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
/* There are no CPU specific additions to the CPU Table for this port. */
-/*
+/**
* This variable is optional. It is used on CPUs on which it is difficult
* to generate an "uninitialized" FP context. It is filled in by
- * _CPU_Initialize and copied into the task's FP context area during
- * _CPU_Context_Initialize.
+ * @ref _CPU_Initialize and copied into the task's FP context area during
+ * @ref _CPU_Context_Initialize.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context;
-/*
+/**
+ * @defgroup CPUInterrupt Processor Dependent Interrupt Management
+ *
* On some CPUs, RTEMS supports a software managed interrupt stack.
* This stack is allocated by the Interrupt Manager and the switch
- * is performed in _ISR_Handler. These variables contain pointers
+ * is performed in @ref _ISR_Handler. These variables contain pointers
* to the lowest and highest addresses in the chunk of memory allocated
* for the interrupt stack. Since it is unknown whether the stack
* grows up or down (in general), this give the CPU dependent
* code the option of picking the version it wants to use.
*
- * NOTE: These two variables are required if the macro
- * CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
+ * @note These two variables are required if the macro
+ * @ref CPU_HAS_SOFTWARE_INTERRUPT_STACK is defined as TRUE.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
+/**
+ * @ingroup CPUInterrupt
+ * This variable points to the lowest physical address of the interrupt
+ * stack.
+ */
SCORE_EXTERN void *_CPU_Interrupt_stack_low;
+
+/**
+ * @ingroup CPUInterrupt
+ * This variable points to the lowest physical address of the interrupt
+ * stack.
+ */
SCORE_EXTERN void *_CPU_Interrupt_stack_high;
-/*
+/**
+ * @ingroup CPUInterrupt
* With some compilation systems, it is difficult if not impossible to
* call a high-level language routine from assembly language. This
* is especially true of commercial Ada compilers and name mangling
* C++ ones. This variable can be optionally defined by the CPU porter
- * and contains the address of the routine _Thread_Dispatch. This
+ * and contains the address of the routine @ref _Thread_Dispatch. This
* can make it easier to invoke that routine at the end of the interrupt
* sequence (if a dispatch is necessary).
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
SCORE_EXTERN void (*_CPU_Thread_dispatch_pointer)();
/*
* Nothing prevents the porter from declaring more CPU specific variables.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
/* XXX: if needed, put more variables here */
-/*
+/**
+ * @ingroup CPUContext
* The size of the floating point context area. On some CPUs this
* will not be a "sizeof" because the format of the floating point
* area is not defined -- only the size is. This is usually on
* CPUs with a "floating point save context" instruction.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
-/*
+/**
* Amount of extra stack (above minimum stack size) required by
* MPCI receive server thread. Remember that in a multiprocessor
* system this thread must exist and be able to process all directives.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
-/*
- * This defines the number of entries in the ISR_Vector_table managed
+/**
+ * @ingroup CPUInterrupt
+ * This defines the number of entries in the @ref _ISR_Vector_table managed
* by RTEMS.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_INTERRUPT_NUMBER_OF_VECTORS 32
+
+/**
+ * @ingroup CPUInterrupt
+ * This defines the highest interrupt vector number for this port.
+ */
#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
-/*
+/**
+ * @ingroup CPUInterrupt
* This is defined if the port has a special way to report the ISR nesting
- * level. Most ports maintain the variable _ISR_Nest_level.
+ * level. Most ports maintain the variable @a _ISR_Nest_level.
*/
-
#define CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
-/*
- * Should be large enough to run all RTEMS tests. This insures
+/**
+ * @ingroup CPUContext
+ * Should be large enough to run all RTEMS tests. This ensures
* that a "reasonable" small application should not have any problems.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_STACK_MINIMUM_SIZE (1024*4)
-/*
+/**
* CPU's worst alignment requirement for data types on a byte boundary. This
* alignment does not take into account the requirements for the stack.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_ALIGNMENT 8
-/*
+/**
* This number corresponds to the byte alignment requirement for the
* heap handler. This alignment requirement may be stricter than that
- * for the data types alignment specified by CPU_ALIGNMENT. It is
+ * for the data types alignment specified by @ref CPU_ALIGNMENT. It is
* common for the heap to follow the same alignment requirement as
- * CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the heap,
- * then this should be set to CPU_ALIGNMENT.
+ * @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is strict enough for
+ * the heap, then this should be set to @ref CPU_ALIGNMENT.
*
- * NOTE: This does not have to be a power of 2 although it should be
+ * @note This does not have to be a power of 2 although it should be
* a multiple of 2 greater than or equal to 2. The requirement
* to be a multiple of 2 is because the heap uses the least
* significant field of the front and back flags to indicate
* that a block is in use or free. So you do not want any odd
* length blocks really putting length data in that bit.
*
- * On byte oriented architectures, CPU_HEAP_ALIGNMENT normally will
- * have to be greater or equal to than CPU_ALIGNMENT to ensure that
+ * On byte oriented architectures, @ref CPU_HEAP_ALIGNMENT normally will
+ * have to be greater or equal to than @ref CPU_ALIGNMENT to ensure that
* elements allocated from the heap meet all restrictions.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT
-/*
+/**
* This number corresponds to the byte alignment requirement for memory
* buffers allocated by the partition manager. This alignment requirement
* may be stricter than that for the data types alignment specified by
- * CPU_ALIGNMENT. It is common for the partition to follow the same
- * alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict
- * enough for the partition, then this should be set to CPU_ALIGNMENT.
+ * @ref CPU_ALIGNMENT. It is common for the partition to follow the same
+ * alignment requirement as @ref CPU_ALIGNMENT. If the @ref CPU_ALIGNMENT is
+ * strict enough for the partition, then this should be set to
+ * @ref CPU_ALIGNMENT.
*
- * NOTE: This does not have to be a power of 2. It does have to
- * be greater or equal to than CPU_ALIGNMENT.
+ * @note This does not have to be a power of 2. It does have to
+ * be greater or equal to than @ref CPU_ALIGNMENT.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT
-/*
+/**
* This number corresponds to the byte alignment requirement for the
* stack. This alignment requirement may be stricter than that for the
- * data types alignment specified by CPU_ALIGNMENT. If the CPU_ALIGNMENT
- * is strict enough for the stack, then this should be set to 0.
+ * data types alignment specified by @ref CPU_ALIGNMENT. If the
+ * @ref CPU_ALIGNMENT is strict enough for the stack, then this should be
+ * set to 0.
*
- * NOTE: This must be a power of 2 either 0 or greater than CPU_ALIGNMENT.
+ * @note This must be a power of 2 either 0 or greater than @ref CPU_ALIGNMENT.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define CPU_STACK_ALIGNMENT 0
/*
* ISR handler macros
*/
-/*
+/**
+ * @ingroup CPUInterrupt
* Support routine to initialize the RTEMS vector table after it is allocated.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Initialize_vectors()
-/*
+/**
+ * @ingroup CPUInterrupt
* Disable all interrupts for an RTEMS critical section. The previous
- * level is returned in _level.
+ * level is returned in @a _isr_cookie.
+ *
+ * @param _isr_cookie (out) will contain the previous level cookie
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_ISR_Disable( _isr_cookie ) \
{ \
(_isr_cookie) = 0; /* do something to prevent warnings */ \
}
-/*
+/**
+ * @ingroup CPUInterrupt
* Enable interrupts to the previous level (returned by _CPU_ISR_Disable).
* This indicates the end of an RTEMS critical section. The parameter
- * _level is not modified.
+ * @a _isr_cookie is not modified.
+ *
+ * @param _isr_cookie (in) contain the previous level cookie
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_ISR_Enable( _isr_cookie ) \
{ \
}
-/*
- * This temporarily restores the interrupt to _level before immediately
+/**
+ * @ingroup CPUInterrupt
+ * This temporarily restores the interrupt to @a _isr_cookie before immediately
* disabling them again. This is used to divide long RTEMS critical
- * sections into two or more parts. The parameter _level is not
- * modified.
+ * sections into two or more parts. The parameter @a _isr_cookie is not
+ * modified.
+ *
+ * @param _isr_cookie (in) contain the previous level cookie
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_ISR_Flash( _isr_cookie ) \
{ \
}
-/*
- * Map interrupt level in task mode onto the hardware that the CPU
+/**
+ * @ingroup CPUInterrupt
+ *
+ * This routine and @ref _CPU_ISR_Get_level
+ * Map the interrupt level in task mode onto the hardware that the CPU
* actually provides. Currently, interrupt levels which do not
* map onto the CPU in a generic fashion are undefined. Someday,
* it would be nice if these were "mapped" by the application
@@ -712,24 +829,33 @@ SCORE_EXTERN void (*_CPU_Thread_dispatch_pointer)();
* This could be used to manage a programmable interrupt controller
* via the rtems_task_mode directive.
*
- * The get routine usually must be implemented as a subroutine.
- *
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_ISR_Set_level( new_level ) \
{ \
}
+/**
+ * @ingroup CPUInterrupt
+ * Return the current interrupt disable level for this task in
+ * the format used by the interrupt level portion of the task mode.
+ *
+ * @note This routine usually must be implemented as a subroutine.
+ *
+ * Port Specific Information:
+ *
+ * XXX document implementation including references if appropriate
+ */
uint32_t _CPU_ISR_Get_level( void );
/* end of ISR handler macros */
/* Context handler macros */
-/*
+/**
+ * @ingroup CPUContext
* Initialize the context to a state suitable for starting a
* task after a context restore operation. Generally, this
* involves:
@@ -744,16 +870,21 @@ uint32_t _CPU_ISR_Get_level( void );
* in the context. The state of the "general data" registers is
* undefined at task start time.
*
- * NOTE: This is_fp parameter is TRUE if the thread is to be a floating
+ * @param _the_context (in) is the context structure to be initialized
+ * @param _stack_base (in) is the lowest physical address of this task's stack
+ * @param _size (in) is the size of this task's stack
+ * @param _isr (in) is the interrupt disable level
+ * @param _entry_point (in) is the thread's entry point. This is
+ * always @a _Thread_Handler
+ * @param _is_fp (in) is TRUE if the thread is to be a floating
* point thread. This is typically only used on CPUs where the
* FPU may be easily disabled by software such as on the SPARC
* where the PSR contains an enable FPU bit.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Context_Initialize( _the_context, _stack_base, _size, \
_isr, _entry_point, _is_fp ) \
{ \
@@ -764,19 +895,19 @@ uint32_t _CPU_ISR_Get_level( void );
* executing task. If you are lucky, then all that is necessary
* is restoring the context. Otherwise, there will need to be
* a special assembly routine which does something special in this
- * case. Context_Restore should work most of the time. It will
+ * case. @ref _CPU_Context_Restore should work most of the time. It will
* not work if restarting self conflicts with the stack frame
* assumptions of restoring a context.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Context_Restart_self( _the_context ) \
_CPU_Context_restore( (_the_context) );
-/*
+/**
+ * @ingroup CPUContext
* The purpose of this macro is to allow the initial pointer into
* a floating point context area (used to save the floating point
* context) to be at an arbitrary place in the floating point
@@ -789,30 +920,35 @@ uint32_t _CPU_ISR_Get_level( void );
* a "dump context" instruction which could fill in from high to low
* or low to high based on the whim of the CPU designers.
*
- * NO_CPU Specific Information:
+ * @param _base (in) is the lowest physical address of the floating point
+ * context area
+ * @param _offset (in) is the offset into the floating point area
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Context_Fp_start( _base, _offset ) \
( (void *) _Addresses_Add_offset( (_base), (_offset) ) )
-/*
+/**
* This routine initializes the FP context area passed to it to.
* There are a few standard ways in which to initialize the
* floating point context. The code included for this macro assumes
* that this is a CPU in which a "initial" FP context was saved into
- * _CPU_Null_fp_context and it simply copies it to the destination
+ * @a _CPU_Null_fp_context and it simply copies it to the destination
* context passed to it.
*
- * Other models include (1) not doing anything, and (2) putting
- * a "null FP status word" in the correct place in the FP context.
+ * Other floating point context save/restore models include:
+ * -# not doing anything, and
+ * -# putting a "null FP status word" in the correct place in the FP context.
*
- * NO_CPU Specific Information:
+ * @param _destination (in) is the floating point context area
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Context_Initialize_fp( _destination ) \
{ \
*((Context_Control_fp *) *((void **) _destination)) = _CPU_Null_fp_context; \
@@ -822,16 +958,15 @@ uint32_t _CPU_ISR_Get_level( void );
/* Fatal Error manager macros */
-/*
+/**
* This routine copies _error into a known place -- typically a stack
* location or a register, optionally disables interrupts, and
* halts/stops the CPU.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#define _CPU_Fatal_halt( _error ) \
{ \
}
@@ -840,29 +975,55 @@ uint32_t _CPU_ISR_Get_level( void );
/* Bitfield handler macros */
-/*
- * This routine sets _output to the bit number of the first bit
- * set in _value. _value is of CPU dependent type Priority_Bit_map_control.
- * This type may be either 16 or 32 bits wide although only the 16
- * least significant bits will be used.
+/**
+ * @defgroup CPUBitfield Processor Dependent Bitfield Manipulation
+ *
+ * This set of routines are used to implement fast searches for
+ * the most important ready task.
+ */
+
+/**
+ * @ingroup CPUBitfield
+ * This definition is set to TRUE if the port uses the generic bitfield
+ * manipulation implementation.
+ */
+#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
+
+/**
+ * @ingroup CPUBitfield
+ * This definition is set to TRUE if the port uses the data tables provided
+ * by the generic bitfield manipulation implementation.
+ * This can occur when actually using the generic bitfield manipulation
+ * implementation or when implementing the same algorithm in assembly
+ * language for improved performance. It is unlikely that a port will use
+ * the data if it has a bitfield scan instruction.
+ */
+#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
+
+/**
+ * @ingroup CPUBitfield
+ * This routine sets @a _output to the bit number of the first bit
+ * set in @a _value. @a _value is of CPU dependent type
+ * @a Priority_Bit_map_control. This type may be either 16 or 32 bits
+ * wide although only the 16 least significant bits will be used.
*
* There are a number of variables in using a "find first bit" type
* instruction.
*
- * (1) What happens when run on a value of zero?
- * (2) Bits may be numbered from MSB to LSB or vice-versa.
- * (3) The numbering may be zero or one based.
- * (4) The "find first bit" instruction may search from MSB or LSB.
+ * -# What happens when run on a value of zero?
+ * -# Bits may be numbered from MSB to LSB or vice-versa.
+ * -# The numbering may be zero or one based.
+ * -# The "find first bit" instruction may search from MSB or LSB.
*
* RTEMS guarantees that (1) will never happen so it is not a concern.
- * (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
- * _CPU_Priority_bits_index(). These three form a set of routines
+ * (2),(3), (4) are handled by the macros @ref _CPU_Priority_Mask and
+ * @ref _CPU_Priority_bits_index. These three form a set of routines
* which must logically operate together. Bits in the _value are
- * set and cleared based on masks built by _CPU_Priority_mask().
- * The basic major and minor values calculated by _Priority_Major()
- * and _Priority_Minor() are "massaged" by _CPU_Priority_bits_index()
+ * set and cleared based on masks built by @ref _CPU_Priority_Mask.
+ * The basic major and minor values calculated by @ref _Priority_Major
+ * and @ref _Priority_Minor are "massaged" by @ref _CPU_Priority_bits_index
* to properly range between the values returned by the "find first bit"
- * instruction. This makes it possible for _Priority_Get_highest() to
+ * instruction. This makes it possible for @ref _Priority_Get_highest to
* calculate the major and directly index into the minor table.
* This mapping is necessary to ensure that 0 (a high priority major/minor)
* is the first bit found.
@@ -878,51 +1039,50 @@ uint32_t _CPU_ISR_Get_level( void );
* there are ways to make do without it. Here are a handful of ways
* to implement this in software:
*
- * - a series of 16 bit test instructions
- * - a "binary search using if's"
- * - _number = 0
- * if _value > 0x00ff
- * _value >>=8
- * _number = 8;
- *
- * if _value > 0x0000f
- * _value >=8
- * _number += 4
- *
- * _number += bit_set_table[ _value ]
- *
+@verbatim
+ - a series of 16 bit test instructions
+ - a "binary search using if's"
+ - _number = 0
+ if _value > 0x00ff
+ _value >>=8
+ _number = 8;
+
+ if _value > 0x0000f
+ _value >=8
+ _number += 4
+
+ _number += bit_set_table[ _value ]
+@endverbatim
+
* where bit_set_table[ 16 ] has values which indicate the first
* bit set
*
- * NO_CPU Specific Information:
+ * @param _value (in) is the value to be scanned
+ * @param _output (in) is the first bit set
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
-#define CPU_USE_GENERIC_BITFIELD_DATA TRUE
-
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
-
#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
{ \
(_output) = 0; /* do something to prevent warnings */ \
}
-
#endif
/* end of Bitfield handler macros */
-/*
+/**
* This routine builds the mask which corresponds to the bit fields
- * as searched by _CPU_Bitfield_Find_first_bit(). See the discussion
+ * as searched by @ref _CPU_Bitfield_Find_first_bit. See the discussion
* for that routine.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
#define _CPU_Priority_Mask( _bit_number ) \
@@ -930,17 +1090,19 @@ uint32_t _CPU_ISR_Get_level( void );
#endif
-/*
+/**
+ * @ingroup CPUBitfield
* This routine translates the bit numbers returned by
- * _CPU_Bitfield_Find_first_bit() into something suitable for use as
+ * @ref _CPU_Bitfield_Find_first_bit into something suitable for use as
* a major or minor component of a priority. See the discussion
* for that routine.
*
- * NO_CPU Specific Information:
+ * @param _priority (in) is the major or minor number to translate
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
#define _CPU_Priority_bits_index( _priority ) \
@@ -952,145 +1114,155 @@ uint32_t _CPU_ISR_Get_level( void );
/* functions */
-/*
- * _CPU_Initialize
- *
+/**
* This routine performs CPU dependent initialization.
*
- * NO_CPU Specific Information:
+ * @param cpu_table (in) is the CPU Dependent Configuration Table
+ * @param thread_dispatch (in) is the address of @ref _Thread_Dispatch
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Initialize(
rtems_cpu_table *cpu_table,
void (*thread_dispatch)
);
-/*
- * _CPU_ISR_install_raw_handler
- *
+/**
+ * @ingroup CPUInterrupt
* This routine installs a "raw" interrupt handler directly into the
* processor's vector table.
*
- * NO_CPU Specific Information:
+ * @param vector (in) is the vector number
+ * @param new_handler (in) is the raw ISR handler to install
+ * @param old_handler (in) is the previously installed ISR Handler
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_ISR_install_raw_handler(
uint32_t vector,
proc_ptr new_handler,
proc_ptr *old_handler
);
-/*
- * _CPU_ISR_install_vector
- *
+/**
+ * @ingroup CPUInterrupt
* This routine installs an interrupt vector.
*
- * NO_CPU Specific Information:
+ * @param vector (in) is the vector number
+ * @param new_handler (in) is the RTEMS ISR handler to install
+ * @param old_handler (in) is the previously installed ISR Handler
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_ISR_install_vector(
uint32_t vector,
proc_ptr new_handler,
proc_ptr *old_handler
);
-/*
- * _CPU_Install_interrupt_stack
- *
+/**
+ * @ingroup CPUInterrupt
* This routine installs the hardware interrupt stack pointer.
*
- * NOTE: It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STACK
+ * @note It need only be provided if @ref CPU_HAS_HARDWARE_INTERRUPT_STACK
* is TRUE.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Install_interrupt_stack( void );
-/*
- * _CPU_Thread_Idle_body
- *
+/**
* This routine is the CPU dependent IDLE thread body.
*
- * NOTE: It need only be provided if CPU_PROVIDES_IDLE_THREAD_BODY
+ * @note It need only be provided if @ref CPU_PROVIDES_IDLE_THREAD_BODY
* is TRUE.
*
- * NO_CPU Specific Information:
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Thread_Idle_body( void );
-/*
- * _CPU_Context_switch
- *
+/**
+ * @ingroup CPUContext
* This routine switches from the run context to the heir context.
*
- * NO_CPU Specific Information:
+ * @param run (in) points to the context of the currently executing task
+ * @param heir (in) points to the context of the heir task
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Context_switch(
Context_Control *run,
Context_Control *heir
);
-/*
- * _CPU_Context_restore
- *
+/**
+ * @ingroup CPUContext
* This routine is generally used only to restart self in an
- * efficient manner. It may simply be a label in _CPU_Context_switch.
+ * efficient manner. It may simply be a label in @ref _CPU_Context_switch.
*
- * NOTE: May be unnecessary to reload some registers.
+ * @param new_context (in) points to the context to be restored.
*
- * NO_CPU Specific Information:
+ * @note May be unnecessary to reload some registers.
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Context_restore(
Context_Control *new_context
);
-/*
- * _CPU_Context_save_fp
- *
+/**
+ * @ingroup CPUContext
* This routine saves the floating point context passed to it.
*
- * NO_CPU Specific Information:
+ * @param fp_context_ptr (in) is a pointer to a pointer to a floating
+ * point context area
+ *
+ * @return on output @a *fp_context_ptr will contain the address that
+ * should be used with @ref _CPU_Context_restore_fp to restore this context.
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Context_save_fp(
void **fp_context_ptr
);
-/*
- * _CPU_Context_restore_fp
- *
+/**
+ * @ingroup CPUContext
* This routine restores the floating point context passed to it.
*
- * NO_CPU Specific Information:
+ * @param fp_context_ptr (in) is a pointer to a pointer to a floating
+ * point context area to restore
+ *
+ * @return on output @a *fp_context_ptr will contain the address that
+ * should be used with @ref _CPU_Context_save_fp to save this context.
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
void _CPU_Context_restore_fp(
void **fp_context_ptr
);
-/* The following routine swaps the endian format of an unsigned int.
+/**
+ * @ingroup CPUEndian
+ * The following routine swaps the endian format of an unsigned int.
* It must be static because it is referenced indirectly.
*
* This version will work on any processor, but if there is a better
@@ -1109,11 +1281,13 @@ void _CPU_Context_restore_fp(
* endianness for ALL fetches -- both code and data -- so the code
* will be fetched incorrectly.
*
- * NO_CPU Specific Information:
+ * @param value (in) is the value to be swapped
+ * @return the value after being endian swapped
+ *
+ * Port Specific Information:
*
* XXX document implementation including references if appropriate
*/
-
static inline unsigned int CPU_swap_u32(
unsigned int value
)
@@ -1129,6 +1303,13 @@ static inline unsigned int CPU_swap_u32(
return( swapped );
}
+/**
+ * @ingroup CPUEndian
+ * This routine swaps a 16 bir quantity.
+ *
+ * @param value (in) is the value to be swapped
+ * @return the value after being endian swapped
+ */
#define CPU_swap_u16( value ) \
(((value&0xff) << 8) | ((value >> 8)&0xff))
diff --git a/cpukit/score/include/rtems/debug.h b/cpukit/score/include/rtems/debug.h
index 0946cd5b91..9cfd989e19 100644
--- a/cpukit/score/include/rtems/debug.h
+++ b/cpukit/score/include/rtems/debug.h
@@ -1,11 +1,13 @@
-/* debug.h
+/**
+ * @file debug.h
*
* This include file contains the information pertaining to the debug
* support within RTEMS. It is currently cast in the form of a
* Manager since it is externally accessible.
- *
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
diff --git a/cpukit/score/include/rtems/score/address.h b/cpukit/score/include/rtems/score/address.h
index 587d42a07f..66c7c62a95 100644
--- a/cpukit/score/include/rtems/score/address.h
+++ b/cpukit/score/include/rtems/score/address.h
@@ -1,9 +1,12 @@
-/* address.h
+/**
+ * @file address.h
*
* This include file contains the information required to manipulate
* physical addresses.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,14 @@
#ifndef __RTEMS_ADDRESSES_h
#define __RTEMS_ADDRESSES_h
+/**
+ * @defgroup ScoreAddress Address Handler
+ *
+ * This group contains functionality which abstracts address manipulation
+ * in a portable manner.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -26,5 +37,7 @@ extern "C" {
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h
index d5e496c001..cdf09f8013 100644
--- a/cpukit/score/include/rtems/score/apiext.h
+++ b/cpukit/score/include/rtems/score/apiext.h
@@ -1,8 +1,11 @@
-/* apiext.h
+/**
+ * @file apiext.h
*
* This is the API Extensions Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -12,90 +15,109 @@
* $Id$
*/
-
#ifndef __API_EXTENSIONS_h
#define __API_EXTENSIONS_h
+/**
+ * @defgroup ScoreAPIExtension API Extension Handler
+ *
+ * This group contains functionality which provides mechanisms for the
+ * SuperCore to perform API specific actions without there being
+ * "up-references" from the SuperCore to APIs. If these references
+ * were allowed in the implementation, the cohesion would be too high
+ * and adding an API would be more difficult. The SuperCore is supposed
+ * to be largely independent of any API.
+ */
+/**@{*/
+
#include <rtems/score/chain.h>
#include <rtems/score/thread.h>
-/*
- * The control structure which defines the points at which an API
- * can add an extension to the system initialization thread.
+/**
+ * This type defines the prototype of the Predriver Hook.
*/
-
typedef void (*API_extensions_Predriver_hook)(void);
+
+/**
+ * This type defines the prototype of the Postdriver Hook.
+ */
typedef void (*API_extensions_Postdriver_hook)(void);
+
+/**
+ * This type defines the prototype of the Postswitch Hook.
+ */
typedef void (*API_extensions_Postswitch_hook)(
Thread_Control *
);
-
+/**
+ * The control structure which defines the points at which an API
+ * can add an extension to the system initialization thread.
+ */
typedef struct {
+ /** This field allows this structure to be used with the Chain Handler. */
Chain_Node Node;
+ /**
+ * This field is the callout invoked during RTEMS initialization after
+ * RTEMS data structures are initialized before device driver initialization
+ * has occurred.
+ *
+ * @note If this field is NULL, no extension is invoked.
+ */
API_extensions_Predriver_hook predriver_hook;
+ /**
+ * This field is the callout invoked during RTEMS initialization after
+ * RTEMS data structures and device driver initialization has occurred
+ * but before multitasking is initiated.
+ *
+ * @note If this field is NULL, no extension is invoked.
+ */
API_extensions_Postdriver_hook postdriver_hook;
+ /**
+ * This field is the callout invoked during each context switch
+ * in the context of the heir thread.
+ *
+ * @note If this field is NULL, no extension is invoked.
+ */
API_extensions_Postswitch_hook postswitch_hook;
} API_extensions_Control;
-/*
+/**
* This is the list of API extensions to the system initialization.
*/
-
SCORE_EXTERN Chain_Control _API_extensions_List;
-/*
- * _API_extensions_Initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the API extension handler.
- *
*/
-
void _API_extensions_Initialization( void );
-/*
- * _API_extensions_Add
+/**
+ * This routine adds an extension to the active set of API extensions.
*
- * DESCRIPTION:
- *
- * XXX
+ * @param the_extension (in) is the extension set to add.
*/
-
void _API_extensions_Add(
API_extensions_Control *the_extension
);
-/*
- * _API_extensions_Run_predriver
- *
- * DESCRIPTION:
- *
- * XXX
+/**
+ * This routine executes all of the predriver callouts.
*/
-
void _API_extensions_Run_predriver( void );
-/*
- * _API_extensions_Run_postdriver
- *
- * DESCRIPTION:
- *
- * XXX
+/**
+ * This routine executes all of the postdriver callouts.
*/
-
void _API_extensions_Run_postdriver( void );
-/*
- * _API_extensions_Run_postswitch
- *
- * DESCRIPTION:
- *
- * XXX
+/**
+ * This routine executes all of the post context switch callouts.
+ */
*/
-
void _API_extensions_Run_postswitch( void );
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h
index ed345c7c76..ad30e0b18b 100644
--- a/cpukit/score/include/rtems/score/apimutex.h
+++ b/cpukit/score/include/rtems/score/apimutex.h
@@ -1,10 +1,13 @@
-/* apimutex.h
+/**
+ * @file apimutex.h
*
* This include file contains all the constants and structures associated
* with the API Mutex Handler. This handler is used by API level
* routines to manage mutual exclusion.
- *
- * COPYRIGHT (c) 1989-2002.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,14 @@
#ifndef __API_MUTEX_h
#define __API_MUTEX_h
+/**
+ * @defgroup ScoreAPIMutex API Mutex Handler
+ *
+ * This group contains functionality which provides mutexes to be used
+ * in the implementation of API functionality.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -25,30 +36,29 @@ extern "C" {
#include <rtems/score/isr.h>
#include <rtems/score/object.h>
-/*
- * The following defines the control block used to manage each mutex.
+/**
+ * The following defines the control block used to manage each API mutex.
+ * An API Mutex is an aggregration of an Object and a SuperCore Mutex.
*/
-
typedef struct {
+ /** This field allows each API Mutex to be a full-fledged RTEMS object.
Objects_Control Object;
+ /** This field contains the SuperCore mutex information. */
CORE_mutex_Control Mutex;
} API_Mutex_Control;
-/*
- * The following defines the information control block used to manage
+/**
+ * The following variable is the information control block used to manage
* this class of objects.
*/
-
SCORE_EXTERN Objects_Information _API_Mutex_Information;
-/*
- * _API_Mutex_Initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
+ *
+ * @param _maximum_mutexes (in) is the maximum number of API mutexes
+ * that may exist at any time
*/
-
#if defined(RTEMS_MULTIPROCESSING)
#define _API_Mutex_Initialization( _maximum_mutexes ) \
_Objects_Initialize_information( \
@@ -75,14 +85,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
);
#endif
-/*
- * _API_Mutex_Allocate
- *
- * DESCRIPTION:
+/**
+ * This routine allocates an API mutex from the inactive set.
*
- * This routine allocates an api mutex from the inactive set.
+ * @param _the_mutex (out) will contain the allocated mutex.
*/
-
#define _API_Mutex_Allocate( _the_mutex ) \
do { \
CORE_mutex_Attributes attr = \
@@ -94,14 +101,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
&(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \
} while (0)
-/*
- * _API_Mutex_Lock
+/**
+ * This routine acquires the specified API mutex.
*
- * DESCRIPTION:
- *
- * This routine acquires the specified api mutex.
+ * @param _the_mutex (in) is the mutex to acquire.
*/
-
#define _API_Mutex_Lock( _the_mutex ) \
do { \
ISR_Level _level; \
@@ -110,12 +114,10 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
&(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \
} while (0)
-/*
- * _API_Mutex_Unlock
- *
- * DESCRIPTION:
+/**
+ * This routine releases the specified API mutex.
*
- * This routine releases the specified api mutex.
+ * @param _the_mutex (in) is the mutex to release.
*/
#define _API_Mutex_Unlock( _the_mutex ) \
@@ -126,15 +128,29 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
_Thread_Enable_dispatch(); \
} while (0);
-/*XXX when the APIs all use this for allocation and deallocation
- *XXX protection, then they should be renamed and probably moved
+/**
+ * This variable points to the API Mutex instance that is used
+ * to protect all memory allocation and deallocation in RTEMS.
+ *
+ * @note When the APIs all use this for allocation and deallocation
+ * protection, then this possibly should be renamed and moved to a
+ * higher level in the hierarchy.
*/
-
SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex;
+/**
+ * This macro locks the RTEMS Allocation Mutex.
+ *
+ * @see _RTEMS_Allocator_Mutex
+ */
#define _RTEMS_Lock_allocator() \
_API_Mutex_Lock( _RTEMS_Allocator_Mutex )
+/**
+ * This macro unlocks the RTEMS Allocation Mutex.
+ *
+ * @see _RTEMS_Allocator_Mutex
+ */
#define _RTEMS_Unlock_allocator() \
_API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
@@ -150,5 +166,7 @@ SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex;
}
#endif
+/*!@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/bitfield.h b/cpukit/score/include/rtems/score/bitfield.h
index 5b4c678457..2f097a0c1a 100644
--- a/cpukit/score/include/rtems/score/bitfield.h
+++ b/cpukit/score/include/rtems/score/bitfield.h
@@ -1,8 +1,11 @@
-/* bitfield.h
+/**
+ * @file bitfield.h
*
* This include file contains all bit field manipulation routines.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -15,30 +18,26 @@
#ifndef __RTEMS_BITFIELD_h
#define __RTEMS_BITFIELD_h
+/**
+ * @defgroup ScoreBitfield Bitfield Handler
+ *
+ * This group contains functionality that is used to manipulate the
+ * priority bitfields used to lookup which priority has the highest
+ * priority ready to execute thread.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/*
- * _Bitfield_Find_first_bit
- *
- * DESCRIPTION:
- *
- * This routine returns the bit_number of the first bit set
- * in the specified value. The correspondence between bit_number
- * and actual bit position is processor dependent. The search for
- * the first bit set may run from most to least significant bit
- * or vice-versa.
- *
- * NOTE:
- *
- * This routine is used when the executing thread is removed
- * from the ready state and, as a result, its performance has a
- * significant impact on the performance of the executive as a whole.
- */
-
#if ( CPU_USE_GENERIC_BITFIELD_DATA == TRUE )
+/**
+ * This table is used by the generic bitfield routines to perform
+ * a highly optimized bit scan without the use of special CPU
+ * instructions.
+ */
#ifndef SCORE_INIT
extern const unsigned char __log2table[256];
#else
@@ -64,18 +63,27 @@ const unsigned char __log2table[256] = {
#endif
+/**
+ * This routine returns the @a _bit_number of the first bit set
+ * in the specified value. The correspondence between @a _bit_number
+ * and actual bit position is processor dependent. The search for
+ * the first bit set may run from most to least significant bit
+ * or vice-versa.
+ *
+ * @param _value (in) is the value to bit scan.
+ * @param _bit_number (in) is the position of the first bit set.
+ *
+ * @note This routine is used when the executing thread is removed
+ * from the ready state and, as a result, its performance has a
+ * significant impact on the performance of the executive as a whole.
+ *
+ * @note This routine must be a macro because if a CPU specific version
+ * is used it will most likely use inline assembly.
+ */
#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
-
#define _Bitfield_Find_first_bit( _value, _bit_number ) \
_CPU_Bitfield_Find_first_bit( _value, _bit_number )
-
#else
-
-/*
- * The following must be a macro because if a CPU specific version
- * is used it will most likely use inline assembly.
- */
-
#define _Bitfield_Find_first_bit( _value, _bit_number ) \
{ \
register uint32_t __value = (uint32_t ) (_value); \
@@ -86,12 +94,13 @@ const unsigned char __log2table[256] = {
else \
(_bit_number) = __p[ __value >> 8 ]; \
}
-
#endif
#ifdef __cplusplus
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h
index 5e70652f43..fc739fc5dd 100644
--- a/cpukit/score/include/rtems/score/chain.h
+++ b/cpukit/score/include/rtems/score/chain.h
@@ -1,9 +1,12 @@
-/* chain.h
+/**
+ * @file chain.h
*
* This include file contains all the constants and structures associated
- * with the Doubly Linked Chain Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ * with the Doubly-Linked Chain Handler.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,140 +19,158 @@
#ifndef __RTEMS_CHAIN_h
#define __RTEMS_CHAIN_h
+/**
+ * @defgroup ScoreChain Chain Handler
+ *
+ * The Chain Handler contains XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
#include <rtems/score/address.h>
-/*
+/**
+ * @typedef Chain_Node
+ *
+ * This type definition promotes the name for the Chain Node used by
+ * all RTEMS code. It is a separate type definition because a forward
+ * reference is required to define it.
+ */
+typedef struct Chain_Node_struct Chain_Node;
+
+/**
+ * @struct Chain_Node_struct
+ *
* This is used to manage each element (node) which is placed
* on a chain.
*
- * NOTE: Typically, a more complicated structure will use the
- * chain package. The more complicated structure will
- * include a chain node as the first element in its
- * control structure. It will then call the chain package
- * with a pointer to that node element. The node pointer
- * and the higher level structure start at the same address
- * so the user can cast the pointers back and forth.
+ * @note Typically, a more complicated structure will use the
+ * chain package. The more complicated structure will
+ * include a chain node as the first element in its
+ * control structure. It will then call the chain package
+ * with a pointer to that node element. The node pointer
+ * and the higher level structure start at the same address
+ * so the user can cast the pointers back and forth.
*
*/
-
-typedef struct Chain_Node_struct Chain_Node;
-
struct Chain_Node_struct {
+ /** This points to the node after to this one on this chain. */
Chain_Node *next;
+ /** This points to the node immediate prior to this one on this chain. */
Chain_Node *previous;
};
-/*
- * This is used to manage a chain. A chain consists of a doubly
- * linked list of zero or more nodes.
- *
- * NOTE: This implementation does not require special checks for
- * manipulating the first and last elements on the chain.
- * To accomplish this the chain control structure is
- * treated as two overlapping chain nodes. The permanent
- * head of the chain overlays a node structure on the
- * first and permanent_null fields. The permanent tail
- * of the chain overlays a node structure on the
- * permanent_null and last elements of the structure.
+/**
+ * @struct Chain_Control
+ *
+ * This is used to manage a chain. A chain consists of a doubly
+ * linked list of zero or more nodes.
+ *
+ * @note This implementation does not require special checks for
+ * manipulating the first and last elements on the chain.
+ * To accomplish this the @a Chain_Control structure is
+ * treated as two overlapping @ref Chain_Node structures.
+ * The permanent head of the chain overlays a node structure on the
+ * @a first and @a permanent_null fields. The permanent tail
+ * of the chain overlays a node structure on the
+ * @a permanent_null and @a last elements of the structure.
*
*/
-
typedef struct {
+ /** This points to the first node on this chain. */
Chain_Node *first;
+ /** This field is always 0. */
Chain_Node *permanent_null;
+ /** This points to the last node on this chain. */
Chain_Node *last;
} Chain_Control;
-/*
- * _Chain_Initialize
- *
- * DESCRIPTION:
+/**
+ * @brief Initialize a Chain Header
*
- * This routine initializes the_chain structure to manage the
- * contiguous array of number_nodes nodes which starts at
- * starting_address. Each node is of node_size bytes.
+ * This routine initializes @a the_chain structure to manage the
+ * contiguous array of @a number_nodes nodes which starts at
+ * @a starting_address. Each node is of @a node_size bytes.
*
+ * @param the_chain (in) specifies the chain to initialize
+ * @param starting_address (in) is the starting address of the array
+ * of elements
+ * @param number_nodes (in) is the numebr of nodes that will be in the chain
+ * @param node_size (in) is the size of each node
*/
-
void _Chain_Initialize(
Chain_Control *the_chain,
void *starting_address,
- uint32_t number_nodes,
- uint32_t node_size
+ unsigned32 number_nodes,
+ unsigned32 node_size
);
-/*
- * _Chain_Get_first_unprotected
- */
-
#ifndef RTEMS_INLINES
+/**
+ * @brief Get the first node (do not disable interrupts)
+ *
+ * This method attempts to obtain the first node from \a the_chain.
+ *
+ * @param the_chain (in) points to the chain to operate upon
+ * @return If successful, a chain node is returned. Otherwise, NULL
+ * is returned.
+ */
Chain_Node *_Chain_Get_first_unprotected(
Chain_Control *the_chain
);
#endif
-/*
- * _Chain_Extract
- *
- * DESCRIPTION:
+/**
+ * @brief Extract the specified node from a chain
*
- * This routine extracts the_node from the chain on which it resides.
+ * This routine extracts \a the_node from the chain on which it resides.
* It disables interrupts to insure the atomicity of the
* extract operation.
*
+ * @arg the_node specifies the node to extract
*/
-
void _Chain_Extract(
Chain_Node *the_node
);
-/*
- * _Chain_Get
+/**
+ * @brief Obtain the first node on a chain
*
- * DESCRIPTION:
+ * This function removes the first node from \a the_chain and returns
+ * a pointer to that node. If \a the_chain is empty, then NULL is returned.
*
- * This function removes the first node from the_chain and returns
- * a pointer to that node. If the_chain is empty, then NULL is returned.
- * It disables interrupts to insure the atomicity of the
+ * @note It disables interrupts to insure the atomicity of the
* get operation.
- *
*/
-
Chain_Node *_Chain_Get(
Chain_Control *the_chain
);
-/*
- * _Chain_Insert
+/**
+ * @brief Insert a node on a chain
*
- * DESCRIPTION:
+ * This routine inserts \a the_node on a chain immediately following
+ * \a after_node.
*
- * This routine inserts the_node on a chain immediately following
- * after_node. It disables interrupts to insure the atomicity
+ * @note It disables interrupts to insure the atomicity
* of the extract operation.
- *
*/
-
void _Chain_Insert(
Chain_Node *after_node,
Chain_Node *the_node
);
-/*
- * _Chain_Append
+/**
+ * @brief Append a node on the end of a chain
*
- * DESCRIPTION:
+ * This routine appends \a the_node onto the end of \a the_chain.
*
- * This routine appends the_node onto the end of the_chain.
- * It disables interrupts to insure the atomicity of the
+ * @note It disables interrupts to insure the atomicity of the
* append operation.
- *
*/
-
void _Chain_Append(
Chain_Control *the_chain,
Chain_Node *the_node
@@ -163,5 +184,7 @@ void _Chain_Append(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h
index f1ea268c13..7c0b5df16d 100644
--- a/cpukit/score/include/rtems/score/context.h
+++ b/cpukit/score/include/rtems/score/context.h
@@ -1,8 +1,11 @@
-/* context.h
+/**
+ * @file context.h
*
- * This include file contains all information about a context.
- *
- * COPYRIGHT (c) 1989-1999.
+ * This include file contains all information about each thread's context.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -15,113 +18,121 @@
#ifndef __RTEMS_CONTEXT_h
#define __RTEMS_CONTEXT_h
+/**
+ * @defgroup ScoreContext Context Handler
+ *
+ * This group contains functionality which abstracts thread context
+ * management in a portable manner.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
#include <rtems/score/cpu.h>
-/*
- * The following constant defines the number of bytes required
+/**
+ * @ingroup ScoreContext
+ * This constant defines the number of bytes required
* to store a full floating point context.
*/
-
#define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE
-/*
- * The following variable is set to TRUE when a reschedule operation
+/**
+ * @ingroup ScoreContext
+ * This variable is set to TRUE when a reschedule operation
* has determined that the processor should be taken away from the
* currently executing thread and given to the heir thread.
*/
SCORE_EXTERN volatile boolean _Context_Switch_necessary;
-/*
- * _Context_Initialize
- *
- * DESCRIPTION:
- *
- * This routine initializes THE_CONTEXT such that the stack
+/**
+ * @ingroup ScoreContext
+ * This routine initializes @a _the_context such that the stack
* pointer, interrupt level, and entry point are correct for the
* thread's initial state.
+ *
+ * @param _the_context (in) will be initialized
+ * @param _stack (in) is the lowest physical address of the thread's
+ * context
+ * @param _size (in) is the size in octets of the thread's context
+ * @param _isr (in) is the ISR enable level for this thread
+ * @param _entry (in) is this thread's entry point
+ * @param _is_fp (in) is set to TRUE if this thread has floating point
+ * enabled
*/
-
#define \
_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \
_CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp )
-/*
- * _Context_Switch
- *
- * DESCRIPTION:
+/**
+ * @ingroup ScoreContext
+ * This routine saves the current context into the @a _executing
+ * context record and restores the context specified by @a _heir.
*
- * This routine saves the current context into the EXECUTING
- * context record and restores the context specified by HEIR.
+ * @param _executing (in) is the currently executing thread's context
+ * @param _heir (in) is the context of the thread to be switched to
*/
-
#define _Context_Switch( _executing, _heir ) \
_CPU_Context_switch( _executing, _heir )
-/*
- * _Context_Restart_self
- *
- * DESCRIPTION:
- *
+/**
+ * @ingroup ScoreContext
* This routine restarts the calling thread by restoring its initial
* stack pointer and returning to the thread's entry point.
+ *
+ * @param _the_context (in) is the context of the thread to restart
*/
-
#define _Context_Restart_self( _the_context ) \
_CPU_Context_Restart_self( _the_context )
-/*
- * _Context_Fp_start
- *
- * DESCRIPTION:
- *
+/**
+ * @ingroup ScoreContext
* This function returns the starting address of the floating
* point context save area. It is assumed that the are reserved
* for the floating point save area is large enough.
+ *
+ * @param _base (in) is lowest physical address of the floating point
+ * context save area.
+ * @param _offset (in) is XXX
+ *
+ * @return the initial FP context pointer
*/
-
#define _Context_Fp_start( _base, _offset ) \
_CPU_Context_Fp_start( (_base), (_offset) )
-/*
- * _Context_Initialize_fp
- *
- * DESCRIPTION:
- *
+/**
+ * @ingroup ScoreContext
* This routine initializes the floating point context save
* area to contain an initial known state.
+ *
+ * @param _fp_area (in) is the base address of the floating point
+ * context save area to initialize.
*/
-
#define _Context_Initialize_fp( _fp_area ) \
_CPU_Context_Initialize_fp( _fp_area )
-/*
- * _Context_Restore_fp
- *
- * DESCRIPTION:
- *
+/**
+ * @ingroup ScoreContext
* This routine restores the floating point context contained
- * in the FP_CONTEXT area. It is assumed that the current
+ * in the @a _fp area. It is assumed that the current
* floating point context has been saved by a previous invocation
- * of SAVE_FP.
+ * of @a _Context_Save_fp.
+ *
+ * @param _fp (in) points to the floating point context area to restore.
*/
-
#define _Context_Restore_fp( _fp ) \
_CPU_Context_restore_fp( _fp )
-/*
- * _Context_Save_fp
- *
- * DESCRIPTION:
- *
+/**
+ * @ingroup ScoreContext
* This routine saves the current floating point context
- * in the FP_CONTEXT area.
+ * in the @a _fp area.
+ *
+ * @param _fp (in) points to the floating point context area to restore.
*/
-
#define _Context_Save_fp( _fp ) \
_CPU_Context_save_fp( _fp )
@@ -129,5 +140,7 @@ SCORE_EXTERN volatile boolean _Context_Switch_necessary;
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/copyrt.h b/cpukit/score/include/rtems/score/copyrt.h
index f18e3c675e..e300f4276a 100644
--- a/cpukit/score/include/rtems/score/copyrt.h
+++ b/cpukit/score/include/rtems/score/copyrt.h
@@ -1,9 +1,12 @@
-/* copyrt.h
+/**
+ * @file copyrt.h
*
* This include file contains the copyright notice for RTEMS
* which is included in every binary copy of the executive.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -20,16 +23,15 @@
extern "C" {
#endif
+/**
+ * This is the copyright string for RTEMS.
+ */
#ifdef SCORE_INIT
-
const char _Copyright_Notice[] =
-"COPYRIGHT (c) 1989-1999.\n\
+"COPYRIGHT (c) 1989-2004.\n\
On-Line Applications Research Corporation (OAR).\n";
-
#else
-
extern const char _Copyright_Notice[];
-
#endif
#ifdef __cplusplus
diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h
index 70906135a4..a1789ab111 100644
--- a/cpukit/score/include/rtems/score/coremsg.h
+++ b/cpukit/score/include/rtems/score/coremsg.h
@@ -1,9 +1,12 @@
-/* coremsg.h
+/**
+ * @file coremsg.h
*
* This include file contains all the constants and structures associated
* with the Message queue Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,14 @@
#ifndef __RTEMS_CORE_MESSAGE_QUEUE_h
#define __RTEMS_CORE_MESSAGE_QUEUE_h
+/**
+ * @defgroup ScoreMessageQueue Message Queue Handler
+ *
+ * This group contains functionality which provides the foundation
+ * Message Queue services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -26,122 +37,176 @@ extern "C" {
#include <rtems/score/priority.h>
#include <rtems/score/watchdog.h>
-/*
+/**
* The following type defines the callout which the API provides
* to support global/multiprocessor operations on message_queues.
*/
-
typedef void ( *CORE_message_queue_API_mp_support_callout )(
Thread_Control *,
Objects_Id
);
-/*
+/**
* The following defines the data types needed to manipulate
* the contents of message buffers.
*
- * NOTE: The buffer field is normally longer than a single uint32_t .
+ * @note The buffer field is normally longer than a single uint32_t
* but since messages are variable length we just make a ptr to 1.
*/
-
typedef struct {
- uint32_t size;
- uint32_t buffer[1];
+ /** This field is the size of this message. */
+ uint32_t size;
+ /** This field contains the actual message. */
+ uint32_t buffer[1];
} CORE_message_queue_Buffer;
-/*
+/**
* The following records define the organization of a message
* buffer.
*/
-
typedef struct {
+ /** This element allows this structure to be placed on chains. */
Chain_Node Node;
+ /** This field is the priority of this message. */
int priority;
+ /** This field points to the contents of the message. */
CORE_message_queue_Buffer Contents;
} CORE_message_queue_Buffer_control;
-/*
- * Blocking disciplines for a message_queue.
+/**
+ * Blocking disciplines for a message queue.
*/
-
typedef enum {
+ /** This value indicates that pending messages are in FIFO order. */
CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO,
+ /** This value indicates that pending messages are in priority order. */
CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY
} CORE_message_queue_Disciplines;
-/*
+/**
+ * This is the priority constant used when appending messages onto
+ * a message queue.
+ */
+#define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX
+
+/**
+ * This is the priority constant used when prepending messages onto
+ * a message queue.
+ */
+#define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
+
+/**
* The following enumerated type details the modes in which a message
* may be submitted to a message queue. The message may be posted
* in a send or urgent fashion.
*
- * NOTE: All other values are message priorities. Numerically smaller
+ * @note All other values are message priorities. Numerically smaller
* priorities indicate higher priority messages.
- *
*/
-
-#define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX
-#define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN
-
typedef int CORE_message_queue_Submit_types;
-/*
+/**
* Core Message queue handler return statuses.
*/
-
typedef enum {
+ /** This value indicates the operation completed sucessfully. */
CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL,
+ /** This value indicates that the message was too large for this queue. */
CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE,
+ /** This value indicates that there are too many messages pending. */
CORE_MESSAGE_QUEUE_STATUS_TOO_MANY,
+ /** This value indicates that a receive was unsuccessful. */
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED,
+ /** This value indicates that a blocking send was unsuccessful. */
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT,
+ /** This value indicates that the message queue being blocked upon
+ * was deleted while the thread was waiting.
+ */
CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED,
+ /** This value indicates that the thread had to timeout while waiting
+ * to receive a message because one did not become available.
+ */
CORE_MESSAGE_QUEUE_STATUS_TIMEOUT,
+ /** This value indicates that a blocking receive was unsuccessful. */
CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT
} CORE_message_queue_Status;
-/*
+/**
* The following defines the control block used to manage the
* attributes of each message queue.
*/
-
typedef struct {
+ /** This field specifies the order in which blocking tasks will be ordered. */
CORE_message_queue_Disciplines discipline;
} CORE_message_queue_Attributes;
-/*
+/**
* The following defines the type for a Notification handler. A notification
* handler is invoked when the message queue makes a 0->1 transition on
* pending messages.
*/
-
typedef void (*CORE_message_queue_Notify_Handler)( void * );
-/*
+/**
* The following defines the control block used to manage each
* counting message_queue.
*/
-
typedef struct {
+ /** This field is the Waiting Queue used to manage the set of tasks
+ * which are blocked waiting to receive a message from this queue.
+ */
Thread_queue_Control Wait_queue;
+ /** This element is the set of attributes which define this instance's
+ * behavior.
+ */
CORE_message_queue_Attributes Attributes;
+ /** This element is maximum number of messages which may be pending
+ * at any given time.
+ */
uint32_t maximum_pending_messages;
+ /** This element is the number of messages which are currently pending.
+ */
uint32_t number_of_pending_messages;
+ /** This is the size in bytes of the largest message which may be
+ * sent via this queue.
+ */
uint32_t maximum_message_size;
+ /** This chain is the set of pending messages. It may be ordered by
+ * message priority or in FIFO order.
+ */
Chain_Control Pending_messages;
+ /** This is the address of the memory allocated for message buffers.
+ * It is allocated are part of message queue initialization and freed
+ * as part of destroying it.
+ */
CORE_message_queue_Buffer *message_buffers;
+ /** This is the routine invoked when the message queue transitions
+ * from zero (0) messages pending to one (1) message pending.
+ */
CORE_message_queue_Notify_Handler notify_handler;
+ /** This field is the argument passed to the @ref notify_argument. */
void *notify_argument;
+ /** This chain is the set of inactive messages. A message is inactive
+ * when it does not contain a pending message.
+ */
Chain_Control Inactive_messages;
} CORE_message_queue_Control;
-/*
- * _CORE_message_queue_Initialize
+/**
+ * This routine initializes the message_queue based on the parameters passed.
*
- * DESCRIPTION:
+ * @param the_message_queue (in) points to the message queue to initialize
+ * @param the_message_queue_attributes (in) points to the attributes that
+ * will be used with this message queue instance
+ * @param maximum_pending_messages (in) is the maximum number of messages
+ * that will be allowed to pend at any given time
+ * @param maximum_message_size (in) is the size of largest message that
+ * may be sent to this message queue instance
*
- * This routine initializes the message_queue based on the parameters passed.
+ * @return TRUE if the message queue can be initialized. In general,
+ * FALSE will only be returned if memory for the pending
+ * messages cannot be allocated.
*/
-
boolean _CORE_message_queue_Initialize(
CORE_message_queue_Control *the_message_queue,
CORE_message_queue_Attributes *the_message_queue_attributes,
@@ -149,72 +214,71 @@ boolean _CORE_message_queue_Initialize(
uint32_t maximum_message_size
);
-/*
- * _CORE_message_queue_Close
- *
- * DESCRIPTION:
- *
+/**
* This function closes a message by returning all allocated space and
* flushing the message_queue's task wait queue.
+ *
+ * @param the_message_queue (in) points to the message queue to close
+ * @param remote_extract_callout (in) is the routine to call for each thread
+ * that is extracted from the set of waiting threads
+ * @param status (in) is the status that each waiting thread will return
+ * from it's blocking service
*/
-
void _CORE_message_queue_Close(
CORE_message_queue_Control *the_message_queue,
Thread_queue_Flush_callout remote_extract_callout,
uint32_t status
);
-/*
- * _CORE_message_queue_Flush
- *
- * DESCRIPTION:
- *
+/**
* This function flushes the message_queue's pending message queue. The
* number of messages flushed from the queue is returned.
*
+ * @param the_message_queue (in) points to the message queue to flush
+ * @return the number of message pending messages flushed
*/
-
uint32_t _CORE_message_queue_Flush(
CORE_message_queue_Control *the_message_queue
);
-/*
- * _CORE_message_queue_Flush_support
- *
- * DESCRIPTION:
- *
+/**
* This routine flushes all outstanding messages and returns
* them to the inactive message chain.
+ *
+ * @param the_message_queue (in) points to the message queue to flush
+ * @return the number of message pending messages flushed
*/
-
uint32_t _CORE_message_queue_Flush_support(
CORE_message_queue_Control *the_message_queue
);
-/*
- * _CORE_message_queue_Flush_waiting_threads
- *
- * DESCRIPTION:
- *
+/**
* This function flushes the threads which are blocked on this
* message_queue's pending message queue. They are unblocked whether
* blocked sending or receiving.
+ *
+ * @param the_message_queue (in) points to the message queue to flush
*/
-
void _CORE_message_queue_Flush_waiting_threads(
CORE_message_queue_Control *the_message_queue
);
-/*
- * _CORE_message_queue_Broadcast
- *
- * DESCRIPTION:
- *
+/**
* This function sends a message for every thread waiting on the queue and
* returns the number of threads made ready by the message.
*
+ * @param the_message_queue (in) points to the message queue
+ * @param buffer (in) is the starting address of the message to broadcast
+ * @param size (in) is the size of the message being broadcast
+ * @param id (in) is the RTEMS object Id associated with this message queue.
+ * It is used when unblocking a remote thread.
+ * @param api_message_queue_mp_support (in) is the routine to invoke if
+ * a thread that is unblocked is actually a remote thread.
+ * @param count (out) points to the variable that will contain the
+ * number of tasks that are sent this message
+ * @return @a *count will contain the number of messages sent
+ * @return indication of the successful completion or reason for failure
*/
-
CORE_message_queue_Status _CORE_message_queue_Broadcast(
CORE_message_queue_Control *the_message_queue,
void *buffer,
@@ -224,11 +288,7 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast(
uint32_t *count
);
-/*
- * _CORE_message_queue_Submit
- *
- * DESCRIPTION:
- *
+/**
* This routine implements the send and urgent message functions. It
* processes a message that is to be submitted to the designated
* message queue. The message will either be processed as a
@@ -236,8 +296,21 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast(
* or it will be processed as an urgent message which will be inserted
* at the front of the queue.
*
+ * @param the_message_queue (in) points to the message queue
+ * @param buffer (in) is the starting address of the message to send
+ * @param size (in) is the size of the message being send
+ * @param id (in) is the RTEMS object Id associated with this message queue.
+ * It is used when unblocking a remote thread.
+ * @param api_message_queue_mp_support (in) is the routine to invoke if
+ * a thread that is unblocked is actually a remote thread.
+ * @param submit_type (in) determines whether the message is prepended,
+ * appended, or enqueued in priority order.
+ * @param wait (in) indicates whether the calling thread is willing to block
+ * if the message queue is full.
+ * @param timeout (in) is the maximum number of clock ticks that the calling
+ * thread is willing to block if the message queue is full.
+ * @return indication of the successful completion or reason for failure
*/
-
CORE_message_queue_Status _CORE_message_queue_Submit(
CORE_message_queue_Control *the_message_queue,
void *buffer,
@@ -249,19 +322,27 @@ CORE_message_queue_Status _CORE_message_queue_Submit(
Watchdog_Interval timeout
);
-/*
- * _CORE_message_queue_Seize
- *
- * DESCRIPTION:
- *
+/**
* This kernel routine dequeues a message, copies the message buffer to
* a given destination buffer, and frees the message buffer to the
* inactive message pool. The thread will be blocked if wait is TRUE,
* otherwise an error will be given to the thread if no messages are available.
*
- * NOTE: Returns message priority via return are in TCB.
+ * @param the_message_queue (in) points to the message queue
+ * @param id (in) is the RTEMS object Id associated with this message queue.
+ * It is used when unblocking a remote thread.
+ * @param buffer (in) is the starting address of the message buffer to
+ * to be filled in with a message
+ * @param size (in) is the size of the @a buffer and indicates the maximum
+ * size message that the caller can receive.
+ * @param wait (in) indicates whether the calling thread is willing to block
+ * if the message queue is empty.
+ * @param timeout (in) is the maximum number of clock ticks that the calling
+ * thread is willing to block if the message queue is empty.
+ *
+ * @return indication of the successful completion or reason for failure
+ * @note Returns message priority via return are in TCB.
*/
-
void _CORE_message_queue_Seize(
CORE_message_queue_Control *the_message_queue,
Objects_Id id,
@@ -271,16 +352,16 @@ void _CORE_message_queue_Seize(
Watchdog_Interval timeout
);
-/*
- * _CORE_message_queue_Insert_message
- *
- * DESCRIPTION:
- *
+/**
* This kernel routine inserts the specified message into the
* message queue. It is assumed that the message has been filled
* in before this routine is called.
+ *
+ * @param the_message_queue (in) points to the message queue
+ * @param the_message (in) is the message to enqueue
+ * @param submit_type (in) determines whether the message is prepended,
+ * appended, or enqueued in priority order.
*/
-
void _CORE_message_queue_Insert_message(
CORE_message_queue_Control *the_message_queue,
CORE_message_queue_Buffer_control *the_message,
@@ -295,5 +376,7 @@ void _CORE_message_queue_Insert_message(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h
index ec55009843..5be229f2ea 100644
--- a/cpukit/score/include/rtems/score/coremutex.h
+++ b/cpukit/score/include/rtems/score/coremutex.h
@@ -1,11 +1,14 @@
-/* mutex.h
+/**
+ * @file coremutex.h
*
* This include file contains all the constants and structures associated
* with the Mutex Handler. A mutex is an enhanced version of the standard
* Dijkstra binary semaphore used to provide synchronization and mutual
* exclusion capabilities.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -18,6 +21,14 @@
#ifndef __RTEMS_CORE_MUTEX_h
#define __RTEMS_CORE_MUTEX_h
+/**
+ * @defgroup ScoreMutex Mutex Handler
+ *
+ * This group contains functionality which provides the foundation
+ * Mutex services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -29,155 +40,230 @@ extern "C" {
#include <rtems/score/interr.h>
#include <rtems/score/sysstate.h>
-/*
+/**
* The following type defines the callout which the API provides
* to support global/multiprocessor operations on mutexes.
*/
-
typedef void ( *CORE_mutex_API_mp_support_callout )(
Thread_Control *,
Objects_Id
);
-/*
+/**
* Blocking disciplines for a mutex.
*/
-
typedef enum {
+ /** This specifies that threads will wait for the mutex in FIFO order. */
CORE_MUTEX_DISCIPLINES_FIFO,
+ /** This specifies that threads will wait for the mutex in priority order. */
CORE_MUTEX_DISCIPLINES_PRIORITY,
+ /** This specifies that threads will wait for the mutex in priority order.
+ * Additionally, the Priority Inheritance Protocol will be in effect.
+ */
CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
+ /** This specifies that threads will wait for the mutex in priority order.
+ * Additionally, the Priority Ceiling Protocol will be in effect.
+ */
CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
} CORE_mutex_Disciplines;
-/*
+/**
* Mutex handler return statuses.
*/
-
typedef enum {
+ /** This status indicates that the operation completed successfully. */
CORE_MUTEX_STATUS_SUCCESSFUL,
+ /** This status indicates that the calling task did not want to block
+ * and the operation was unable to complete immediately because the
+ * resource was unavailable.
+ */
CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
+ /** This status indicates that an attempt was made to relock a mutex
+ * for which nesting is not configured.
+ */
CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
+ /** This status indicates that an attempt was made to release a mutex
+ * by a thread other than the thread which locked it.
+ */
CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
+ /** This status indicates that the thread was blocked waiting for an
+ * operation to complete and the mutex was deleted.
+ */
CORE_MUTEX_WAS_DELETED,
+ /** This status indicates that the calling task was willing to block
+ * but the operation was unable to complete within the time allotted
+ * because the resource never became available.
+ */
CORE_MUTEX_TIMEOUT,
+ /** This status indicates that a thread of logically greater importance
+ * than the ceiling priority attempted to lock this mutex.
+ */
CORE_MUTEX_STATUS_CEILING_VIOLATED
} CORE_mutex_Status;
-/*
+/**
* Mutex lock nesting behavior
*
- * CORE_MUTEX_NESTING_ACQUIRES:
+ * + CORE_MUTEX_NESTING_ACQUIRES:
* This sequence has no blocking or errors:
- * lock(m)
- * lock(m)
- * unlock(m)
- * unlock(m)
*
- * CORE_MUTEX_NESTING_IS_ERROR
+ * + lock(m)
+ * + lock(m)
+ * + unlock(m)
+ * + unlock(m)
+ *
+ * + CORE_MUTEX_NESTING_IS_ERROR
* This sequence returns an error at the indicated point:
- * lock(m)
- * lock(m) - already locked error
- * unlock(m)
*
- * CORE_MUTEX_NESTING_BLOCKS
+ * + lock(m)
+ * + lock(m) - already locked error
+ * + unlock(m)
+ *
+ * + CORE_MUTEX_NESTING_BLOCKS
* This sequence performs as indicated:
- * lock(m)
- * lock(m) - deadlocks or timeouts
- * unlock(m) - releases
+ * + lock(m)
+ * + lock(m) - deadlocks or timeouts
+ * + unlock(m) - releases
*/
-
typedef enum {
CORE_MUTEX_NESTING_ACQUIRES,
CORE_MUTEX_NESTING_IS_ERROR,
CORE_MUTEX_NESTING_BLOCKS
} CORE_mutex_Nesting_behaviors;
-/*
- * Locked and unlocked values
+/**
+ * This is the value of a mutex when it is unlocked.
*/
-
#define CORE_MUTEX_UNLOCKED 1
+
+/**
+ * This is the value of a mutex when it is locked.
+ */
#define CORE_MUTEX_LOCKED 0
-/*
+/**
* The following defines the control block used to manage the
* attributes of each mutex.
*/
-
typedef struct {
+ /** This field determines what the behavior of this mutex instance will
+ * be when attempting to acquire the mutex when it is already locked.
+ */
CORE_mutex_Nesting_behaviors lock_nesting_behavior;
+ /** When this field is TRUE, then only the thread that locked the mutex
+ * is allowed to unlock it.
+ */
boolean only_owner_release;
+ /** This field indicates whether threads waiting on the mutex block in
+ * FIFO or priority order.
+ */
CORE_mutex_Disciplines discipline;
+ /** This field contains the ceiling priority to be used if that protocol
+ * is selected.
+ */
Priority_Control priority_ceiling;
} CORE_mutex_Attributes;
-/*
+/**
* The following defines the control block used to manage each mutex.
*/
-
typedef struct {
+ /** This field is the Waiting Queue used to manage the set of tasks
+ * which are blocked waiting to lock the mutex.
+ */
Thread_queue_Control Wait_queue;
+ /** This element is the set of attributes which define this instance's
+ * behavior.
+ */
CORE_mutex_Attributes Attributes;
+ /** This element contains the current state of the mutex.
+ */
uint32_t lock;
+ /** This element contains the number of times the mutex has been acquired
+ * nested. This must be zero (0) before the mutex is actually unlocked.
+ */
uint32_t nest_count;
+ /** This is the number of waiting threads. */
uint32_t blocked_count;
+ /** This element points to the thread which is currently holding this mutex.
+ * The holder is the last thread to successfully lock the mutex and which
+ * has not unlocked it. If the thread is not locked, there is no holder.
+ */
Thread_Control *holder;
+ /** This element contains the object Id of the holding thread. */
Objects_Id holder_id;
} CORE_mutex_Control;
-/*
- * _CORE_mutex_Initialize
- *
- * DESCRIPTION:
+/**
*
* This routine initializes the mutex based on the parameters passed.
+ *
+ * @param the_mutex (in) is the mutex to initalize
+ * @param the_mutex_attributes (in) is the attributes associated with this
+ * mutex instance
+ * @param initial_lock (in) is the initial value of the mutex
*/
-
void _CORE_mutex_Initialize(
CORE_mutex_Control *the_mutex,
CORE_mutex_Attributes *the_mutex_attributes,
uint32_t initial_lock
);
-/*
- * _CORE_mutex_Seize
- *
- * DESCRIPTION:
- *
+#ifndef __RTEMS_APPLICATION__
+/**
* This routine attempts to receive a unit from the_mutex.
* If a unit is available or if the wait flag is FALSE, then the routine
* returns. Otherwise, the calling task is blocked until a unit becomes
* available.
*
- * NOTE: For performance reasons, this routine is implemented as
+ * @param the_mutex (in) is the mutex to attempt to lock
+ * @param level_p (in) is the interrupt level holder
+ *
+ * @note For performance reasons, this routine is implemented as
* a macro that uses two support routines.
*/
-
-
-#ifndef __RTEMS_APPLICATION__
RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
CORE_mutex_Control *the_mutex,
ISR_Level *level_p
);
+/**
+ * This routine performs the blocking portion of a mutex obtain.
+ * It is an actual subroutine and is not implemented as something
+ * that may be inlined.
+ *
+ * @param the_mutex (in) is the mutex to attempt to lock
+ * @param timeout (in) is the maximum number of ticks to block
+ */
void _CORE_mutex_Seize_interrupt_blocking(
CORE_mutex_Control *the_mutex,
Watchdog_Interval timeout
);
+/**
+ * This routine attempts to obtain the mutex. If the mutex is available,
+ * then it will return immediately. Otherwise, it will invoke the
+ * support routine @a _Core_mutex_Seize_interrupt_blocking.
+ *
+ * @param _the_mutex (in) is the mutex to attempt to lock
+ * @param _id (in) is the Id of the owning API level Semaphore object
+ * @param _wait (in) is TRUE if the thread is willing to wait
+ * @param _timeout (in) is the maximum number of ticks to block
+ * @param _level (in) is a temporary variable used to contain the ISR
+ * disable level cookie
+ */
#define _CORE_mutex_Seize( \
_the_mutex, _id, _wait, _timeout, _level ) \
do { \
- if ( _Thread_Dispatch_disable_level \
- && (_wait) \
- && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
- ) { \
- _Internal_error_Occurred( \
- INTERNAL_ERROR_CORE, \
- FALSE, \
- 18 /* called from wrong environment */); \
- } \
+ if ( _Thread_Dispatch_disable_level \
+ && (_wait) \
+ && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
+ ) { \
+ _Internal_error_Occurred( \
+ INTERNAL_ERROR_CORE, \
+ FALSE, \
+ 18 /* called from wrong environment */); \
+ } \
if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) { \
if ( !_wait ) { \
_ISR_Enable( _level ); \
@@ -194,31 +280,34 @@ void _CORE_mutex_Seize_interrupt_blocking(
} \
} while (0)
-/*
- * _CORE_mutex_Surrender
- *
- * DESCRIPTION:
- *
+/**
* This routine frees a unit to the mutex. If a task was blocked waiting for
* a unit from this mutex, then that task will be readied and the unit
* given to that task. Otherwise, the unit will be returned to the mutex.
+ *
+ * @param the_mutex (in) is the mutex to surrender
+ * @param id (in) is the id of the RTEMS Object associated with this mutex
+ * @param api_mutex_mp_support (in) is the routine that will be called when
+ * unblocking a remote mutex
+ *
+ * @return an indication of whether the routine succeeded or failed
*/
-
CORE_mutex_Status _CORE_mutex_Surrender(
CORE_mutex_Control *the_mutex,
Objects_Id id,
CORE_mutex_API_mp_support_callout api_mutex_mp_support
);
-/*
- * _CORE_mutex_Flush
- *
- * DESCRIPTION:
- *
+/**
* This routine assists in the deletion of a mutex by flushing the associated
* wait queue.
+ *
+ * @param the_mutex (in) is the mutex to flush
+ * @param remote_extract_callout (in) is the routine to invoke when a remote
+ * thread is extracted
+ * @param status (in) is the status value which each unblocked thread will
+ * return to its caller.
*/
-
void _CORE_mutex_Flush(
CORE_mutex_Control *the_mutex,
Thread_queue_Flush_callout remote_extract_callout,
@@ -232,5 +321,7 @@ void _CORE_mutex_Flush(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h
index e9be0036ab..333cd1874f 100644
--- a/cpukit/score/include/rtems/score/coresem.h
+++ b/cpukit/score/include/rtems/score/coresem.h
@@ -1,11 +1,14 @@
-/* core_sem.h
+/**
+ * @file coresem.h
*
* This include file contains all the constants and structures associated
* with the Counting Semaphore Handler. A counting semaphore is the
* standard Dijkstra binary semaphore used to provide synchronization
* and mutual exclusion capabilities.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -18,6 +21,14 @@
#ifndef __RTEMS_CORE_COUNTING_SEMAPHORE_h
#define __RTEMS_CORE_COUNTING_SEMAPHORE_h
+/**
+ * @defgroup ScoreSemaphore Semaphore Handler
+ *
+ * This group contains functionality which provides the foundation
+ * Semaphore services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -27,83 +38,108 @@ extern "C" {
#include <rtems/score/priority.h>
#include <rtems/score/watchdog.h>
-/*
+/**
* The following type defines the callout which the API provides
* to support global/multiprocessor operations on semaphores.
*/
-
typedef void ( *CORE_semaphore_API_mp_support_callout )(
Thread_Control *,
Objects_Id
);
-/*
+/**
* Blocking disciplines for a semaphore.
*/
-
typedef enum {
+ /** This specifies that threads will wait for the semaphore in FIFO order. */
CORE_SEMAPHORE_DISCIPLINES_FIFO,
+ /** This specifies that threads will wait for the semaphore in
+ * priority order.
+ */
CORE_SEMAPHORE_DISCIPLINES_PRIORITY
} CORE_semaphore_Disciplines;
-/*
+/**
* Core Semaphore handler return statuses.
*/
-
typedef enum {
+ /** This status indicates that the operation completed successfully. */
CORE_SEMAPHORE_STATUS_SUCCESSFUL,
+ /** This status indicates that the calling task did not want to block
+ * and the operation was unable to complete immediately because the
+ * resource was unavailable.
+ */
CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT,
+ /** This status indicates that the thread was blocked waiting for an
+ * operation to complete and the semaphore was deleted.
+ */
CORE_SEMAPHORE_WAS_DELETED,
+ /** This status indicates that the calling task was willing to block
+ * but the operation was unable to complete within the time allotted
+ * because the resource never became available.
+ */
CORE_SEMAPHORE_TIMEOUT,
+ /** This status indicates that an attempt was made to unlock the semaphore
+ * and this would have made its count greater than that allowed.
CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED
} CORE_semaphore_Status;
-/*
+/**
* The following defines the control block used to manage the
* attributes of each semaphore.
*/
-
typedef struct {
+ /** This element indicates the maximum count this semaphore may have. */
uint32_t maximum_count;
+ /** This field indicates whether threads waiting on the semaphore block in
+ * FIFO or priority order.
+ */
CORE_semaphore_Disciplines discipline;
} CORE_semaphore_Attributes;
-/*
+/**
* The following defines the control block used to manage each
* counting semaphore.
*/
-
typedef struct {
+ /** This field is the Waiting Queue used to manage the set of tasks
+ * which are blocked waiting to obtain the semaphore.
+ */
Thread_queue_Control Wait_queue;
+ /** This element is the set of attributes which define this instance's
+ * behavior.
+ */
CORE_semaphore_Attributes Attributes;
+ /** This element contains the current count of this semaphore. */
uint32_t count;
} CORE_semaphore_Control;
-/*
- * _CORE_semaphore_Initialize
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the semaphore based on the parameters passed.
+ *
+ * @param the_semaphore (in) is the semaphore to initialize
+ * @param the_semaphore_attributes (in) define the behavior of this instance
+ * @param initial_value (in) is the initial count of the semaphore
*/
-
void _CORE_semaphore_Initialize(
CORE_semaphore_Control *the_semaphore,
CORE_semaphore_Attributes *the_semaphore_attributes,
uint32_t initial_value
);
-/*
- * _CORE_semaphore_Seize
- *
- * DESCRIPTION:
- *
+/**
* This routine attempts to receive a unit from the_semaphore.
* If a unit is available or if the wait flag is FALSE, then the routine
* returns. Otherwise, the calling task is blocked until a unit becomes
* available.
+ *
+ * @param the_semaphore (in) is the semaphore to seize
+ * @param id (in) is the Id of the API level Semaphore object associated
+ * with this instance of a SuperCore Semaphore
+ * @param wait (in) is TRUE if the calling thread is willing to wait
+ * @param timeout (in) is the number of ticks the calling thread is willing
+ * to wait if @a wait is TRUE.
*/
-
void _CORE_semaphore_Seize(
CORE_semaphore_Control *the_semaphore,
Objects_Id id,
@@ -111,31 +147,34 @@ void _CORE_semaphore_Seize(
Watchdog_Interval timeout
);
-/*
- * _CORE_semaphore_Surrender
- *
- * DESCRIPTION:
- *
+/**
* This routine frees a unit to the semaphore. If a task was blocked waiting
* for a unit from this semaphore, then that task will be readied and the unit
* given to that task. Otherwise, the unit will be returned to the semaphore.
+ *
+ * @param the_semaphore (in) is the semaphore to surrender
+ * @param id (in) is the Id of the API level Semaphore object associated
+ * with this instance of a SuperCore Semaphore
+ * @param api_semaphore_mp_support (in) is the routine to invoke if the
+ * thread unblocked is remote
+ *
+ * @return an indication of whether the routine succeeded or failed
*/
-
CORE_semaphore_Status _CORE_semaphore_Surrender(
CORE_semaphore_Control *the_semaphore,
Objects_Id id,
CORE_semaphore_API_mp_support_callout api_semaphore_mp_support
);
-/*
- * _CORE_semaphore_Flush
- *
- * DESCRIPTION:
- *
+/**
* This routine assists in the deletion of a semaphore by flushing the
* associated wait queue.
+ *
+ * @param the_semaphore (in) is the semaphore to flush
+ * @param remote_extract_callout (in) is the routine to invoke if the
+ * thread unblocked is remote
+ * @param status (in) is the status to be returned to the unblocked thread
*/
-
void _CORE_semaphore_Flush(
CORE_semaphore_Control *the_semaphore,
Thread_queue_Flush_callout remote_extract_callout,
@@ -150,5 +189,7 @@ void _CORE_semaphore_Flush(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/heap.h b/cpukit/score/include/rtems/score/heap.h
index 9b1387ecbf..0745fab95f 100644
--- a/cpukit/score/include/rtems/score/heap.h
+++ b/cpukit/score/include/rtems/score/heap.h
@@ -1,4 +1,5 @@
-/* heap.h
+/**
+ * @file heap.h
*
* This include file contains the information pertaining to the Heap
* Handler. A heap is a doubly linked list of variable size
@@ -7,8 +8,10 @@
* coalescing neighbor blocks. Control information for both allocated
* and unallocated blocks is contained in the heap space. A heap header
* contains control information for the heap.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -21,104 +24,122 @@
#ifndef __RTEMS_HEAP_h
#define __RTEMS_HEAP_h
+/**
+ * @defgroup ScoreHeap Heap Handler
+ *
+ * This group contains functionality which provides the foundation
+ * Heap services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/*
+/**
* Status codes for heap_extend
*/
-
typedef enum {
HEAP_EXTEND_SUCCESSFUL,
HEAP_EXTEND_ERROR,
HEAP_EXTEND_NOT_IMPLEMENTED
} Heap_Extend_status;
-/*
+/**
* Status codes for _Heap_Get_information
*/
-
typedef enum {
HEAP_GET_INFORMATION_SUCCESSFUL = 0,
HEAP_GET_INFORMATION_SYSTEM_STATE_ERROR,
HEAP_GET_INFORMATION_BLOCK_ERROR
} Heap_Get_information_status;
-/*
+/**
* Information block returned by _Heap_Get_information
*/
-
typedef struct {
+ /** This field is the number of free blocks in this heap. */
uint32_t free_blocks;
+ /** This field is the amount of free memory in this heap. */
uint32_t free_size;
+ /** This field is the number of used blocks in this heap. */
uint32_t used_blocks;
+ /** This field is the amount of used memory in this heap. */
uint32_t used_size;
} Heap_Information_block;
-/*
- * Constants used in the size/used field of each heap block to
- * indicate when a block is free or in use.
+/**
+ * This constant is used in the size/used field of each heap block to
+ * indicate when a block is in use.
*/
+#define HEAP_BLOCK_USED 1
-#define HEAP_BLOCK_USED 1 /* indicates block is in use */
-#define HEAP_BLOCK_FREE 0 /* indicates block is free */
+/**
+ * This constant is used in the size/used field of each heap block to
+ * indicate when a block is free.
+ */
+#define HEAP_BLOCK_FREE 0
-/*
+/**
* The size/used field value for the dummy front and back flags.
*/
-
#define HEAP_DUMMY_FLAG (0 + HEAP_BLOCK_USED)
/*
* The following constants reflect various requirements of the
* heap data structures which impact the management of a heap.
*
- * NOTE: Because free block overhead is greater than used block
+ * NOTE: Because free block overhead is greater than used block
* overhead AND a portion of the allocated space is from
* the extra free block overhead, the absolute lower bound
* of the minimum fragment size is equal to the size of
* the free block overhead.
*/
-#define HEAP_OVERHEAD \
- (sizeof( uint32_t ) * 2) /* size dummy first and last blocks */
-#define HEAP_BLOCK_USED_OVERHEAD \
- (sizeof( void * ) * 2) /* num bytes overhead in used block */
-#define HEAP_MINIMUM_SIZE \
- (HEAP_OVERHEAD + sizeof (Heap_Block))
- /* min number of bytes the user may */
- /* specify for the heap size */
+/** size dummy first and last blocks */
+#define HEAP_OVERHEAD (sizeof( uint32_t ) * 2)
-/*
+/** number of bytes of overhead in used block */
+#define HEAP_BLOCK_USED_OVERHEAD (sizeof( void * ) * 2)
+
+/** Minimum number of bytes the user may specify for the heap size */
+#define HEAP_MINIMUM_SIZE (HEAP_OVERHEAD + sizeof (Heap_Block))
+
+/**
+ * Forward reference
+ *
+ * @ref Heap_Block
+ */
+typedef struct Heap_Block_struct Heap_Block;
+
+/**
* The following defines the data structure used to manage
* individual blocks in a heap. When the block is allocated, the
* next and previous fields are not used by the Heap Handler
* and thus the address returned for the block starts at
* the address of the next field.
*
- * NOTE: The next and previous pointers are only valid when the
+ * @note The next and previous pointers are only valid when the
* block is free. Caution must be exercised to insure that
* allocated blocks are large enough to contain them and
* that they are not accidentally overwritten when the
* block is actually allocated.
*/
-
-typedef struct Heap_Block_struct Heap_Block;
-
struct Heap_Block_struct {
- uint32_t back_flag; /* size and status of prev block */
- uint32_t front_flag; /* size and status of block */
- Heap_Block *next; /* pointer to next block */
- Heap_Block *previous; /* pointer to previous block */
+ /** size and status of prev block */
+ uint32_t back_flag;
+ /** size and status of block */
+ uint32_t front_flag;
+ /** pointer to next block */
+ Heap_Block *next;
+ /** pointer to previous block */
+ Heap_Block *previous;
};
-/*
+/**
* The following defines the control block used to manage each heap.
*
- * NOTE:
- *
- * This structure is layed out such that it can be used a a dummy
+ * @note This structure is layed out such that it can be used a a dummy
* first and last block on the free block chain. The extra padding
* insures the dummy last block is the correct size.
*
@@ -126,29 +147,37 @@ struct Heap_Block_struct {
* final. This is effectively the same trick as is used in the Chain
* Handler.
*/
-
typedef struct {
- Heap_Block *start; /* first valid block address in heap */
- Heap_Block *final; /* last valid block address in heap */
-
- Heap_Block *first; /* pointer to first block in heap */
- Heap_Block *permanent_null; /* always NULL pointer */
- Heap_Block *last; /* pointer to last block in heap */
- uint32_t page_size; /* allocation unit */
+ /** first valid block address in heap */
+ Heap_Block *start;
+ /** last valid block address in heap */
+ Heap_Block *final;
+
+ /** pointer to first block in heap */
+ Heap_Block *first;
+ /** always NULL pointer */
+ Heap_Block *permanent_null;
+ /** pointer to last block in heap */
+ Heap_Block *last;
+ /** allocation unit */
+ uint32_t page_size;
+ /** reserved field */
uint32_t reserved;
} Heap_Control;
-/*
- * _Heap_Initialize
- *
- * DESCRIPTION:
- *
- * This routine initializes the_heap record to manage the
- * contiguous heap of size bytes which starts at starting_address.
+/**
+ * This routine initializes @a the_heap record to manage the
+ * contiguous heap of @a size bytes which starts at @a starting_address.
* Blocks of memory are allocated from the heap in multiples of
- * page_size byte units.
+ * @a page_size byte units.
+ *
+ * @param the_heap (in) is the heap to operate upon
+ * @param starting_address (in) is the starting address of the memory for
+ * the heap
+ * @param size (in) is the size in bytes of the memory area for the heap
+ * @param page_size (in) is the size in bytes of the allocation unit
+ * @return XXX
*/
-
uint32_t _Heap_Initialize(
Heap_Control *the_heap,
void *starting_address,
@@ -156,15 +185,18 @@ uint32_t _Heap_Initialize(
uint32_t page_size
);
-/*
- * _Heap_Extend
+/**
+ * This routine grows @a the_heap memory area using the size bytes which
+ * begin at @a starting_address.
*
- * DESCRIPTION:
- *
- * This routine grows the_heap memory area using the size bytes which
- * begin at starting_address.
+ * @param the_heap (in) is the heap to operate upon
+ * @param starting_address (in) is the starting address of the memory
+ * to add to the heap
+ * @param size (in) is the size in bytes of the memory area to add
+ * @param amount_extended (in) points to a user area to return the
+ * @return a status indicating success or the reason for failure
+ * @return *size filled in with the amount of memory added to the heap
*/
-
Heap_Extend_status _Heap_Extend(
Heap_Control *the_heap,
void *starting_address,
@@ -172,85 +204,75 @@ Heap_Extend_status _Heap_Extend(
uint32_t *amount_extended
);
-/*
- * _Heap_Allocate
- *
- * DESCRIPTION:
- *
- * DESCRIPTION:
- *
+/**
* This function attempts to allocate a block of size bytes from
- * the_heap. If insufficient memory is free in the_heap to allocate
+ * @a the_heap. If insufficient memory is free in @a the_heap to allocate
* a block of the requested size, then NULL is returned.
+ *
+ * @param the_heap (in) is the heap to operate upon
+ * @param size (in) is the amount of memory to allocate in bytes
+ * @return NULL if unsuccessful and a pointer to the block if successful
*/
-
void *_Heap_Allocate(
Heap_Control *the_heap,
uint32_t size
);
-/*
- * _Heap_Size_of_user_area
- *
- * DESCRIPTION:
- *
+/**
* This kernel routine sets size to the size of the given heap block.
- * It returns TRUE if the starting_address is in the heap, and FALSE
+ * It returns TRUE if the @a starting_address is in @a the_heap, and FALSE
* otherwise.
+ *
+ * @param the_heap (in) is the heap to operate upon
+ * @param starting_address (in) is the starting address of the user block
+ * to obtain the size of
+ * @param size (in) points to a user area to return the size in
+ * @return TRUE if successfully able to determine the size, FALSE otherwise
+ * @return *size filled in with the size of the user area for this block
*/
-
boolean _Heap_Size_of_user_area(
Heap_Control *the_heap,
void *starting_address,
uint32_t *size
);
-/*
- * _Heap_Free
- *
- * DESCRIPTION:
- *
+/**
* This routine returns the block of memory which begins
- * at starting_address to the_heap. Any coalescing which is
+ * at @a starting_address to @a the_heap. Any coalescing which is
* possible with the freeing of this routine is performed.
+ *
+ * @param the_heap (in) is the heap to operate upon
+ * @param starting_address (in) is the starting address of the user block
+ * to free
+ * @return TRUE if successfully freed, FALSE otherwise
*/
-
boolean _Heap_Free(
Heap_Control *the_heap,
void *start_address
);
-/*
- * _Heap_Walk
- *
- * DESCRIPTION:
- *
+/**
* This routine walks the heap to verify its integrity.
+ *
+ * @param the_heap (in) is the heap to operate upon
+ * @param source (in) XXX
+ * @param do_dump (in) is set to TRUE if errors should be printed
*/
-
void _Heap_Walk(
Heap_Control *the_heap,
int source,
boolean do_dump
);
-/*PAGE
- *
- * _Heap_Get_information
- *
+/**
* This kernel routine walks the heap and tots up the free and allocated
* sizes. Derived from _Heap_Walk.
*
- * Input parameters:
- * the_heap - pointer to heap header
- * the_info - pointer to information block
- *
- * Output parameters:
- * *the_info - status information
- * return 0=success, otherwise heap is corrupt.
+ * @param the_heap (in) pointer to heap header
+ * @param the_info (in) pointer to a status information area
+ * @return *the_info is filled with status information
+ * @return 0=success, otherwise heap is corrupt.
*/
-
-
Heap_Get_information_status _Heap_Get_information(
Heap_Control *the_heap,
Heap_Information_block *the_info
@@ -265,5 +287,7 @@ Heap_Get_information_status _Heap_Get_information(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h
index 536e30bef0..eb5c2b499c 100644
--- a/cpukit/score/include/rtems/score/interr.h
+++ b/cpukit/score/include/rtems/score/interr.h
@@ -1,10 +1,12 @@
-/* interr.h
+/**
+ * @file interr.h
*
* This include file contains constants and prototypes related
* to the Internal Error Handler.
- *
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,15 +19,22 @@
#ifndef __RTEMS_INTERNAL_ERROR_h
#define __RTEMS_INTERNAL_ERROR_h
+/**
+ * @defgroup ScoreIntErr Internal Error Handler
+ *
+ * This group contains functionality which provides the foundation
+ * Semaphore services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/*
+/**
* This type lists the possible sources from which an error
* can be reported.
*/
-
typedef enum {
INTERNAL_ERROR_CORE,
INTERNAL_ERROR_RTEMS_API,
@@ -36,7 +45,6 @@ typedef enum {
/*
* A list of errors which are generated internally by the executive core.
*/
-
typedef enum {
INTERNAL_ERROR_NO_CONFIGURATION_TABLE,
INTERNAL_ERROR_NO_CPU_TABLE,
@@ -60,7 +68,6 @@ typedef enum {
/*
* This type holds the fatal error information.
*/
-
typedef struct {
Internal_errors_Source the_source;
boolean is_internal;
@@ -70,18 +77,13 @@ typedef struct {
/*
* When a fatal error occurs, the error information is stored here.
*/
-
SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened;
-/*
- * _Internal_error_Occurred
- *
- * DESCRIPTION:
+/** @brief Internal error Occurred
*
* This routine is invoked when the application or the executive itself
* determines that a fatal error has occurred.
*/
-
void volatile _Internal_error_Occurred(
Internal_errors_Source the_source,
boolean is_internal,
@@ -92,5 +94,7 @@ void volatile _Internal_error_Occurred(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h
index 6064d1ed1e..a932eafcf7 100644
--- a/cpukit/score/include/rtems/score/isr.h
+++ b/cpukit/score/include/rtems/score/isr.h
@@ -1,11 +1,14 @@
-/* isr.h
+/**
+ * @file isr.h
*
* This include file contains all the constants and structures associated
* with the management of processor interrupt levels. This handler
* supports interrupt critical sections, vectoring of user interrupt
* handlers, nesting of interrupts, and manipulating interrupt levels.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -18,33 +21,37 @@
#ifndef __ISR_h
#define __ISR_h
+/**
+ * @defgroup ScoreISR ISR Handler
+ *
+ * This group contains functionality which provides the foundation
+ * ISR services used in all of the APIs supported by RTEMS.
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/*
+/**
* The following type defines the control block used to manage
* the interrupt level portion of the status register.
*/
-
typedef uint32_t ISR_Level;
-/*
+/**
* The following type defines the type used to manage the vectors.
*/
-
typedef uint32_t ISR_Vector_number;
-/*
+/**
* Return type for ISR Handler
*/
-
typedef void ISR_Handler;
-/*
+/**
* Pointer to an ISR Handler
*/
-
#if (CPU_ISR_PASSES_FRAME_POINTER == 1)
typedef ISR_Handler ( *ISR_Handler_entry )(
ISR_Vector_number,
@@ -55,82 +62,59 @@ typedef ISR_Handler ( *ISR_Handler_entry )(
ISR_Vector_number
);
#endif
-/*
+
+/**
* This constant promotes out the number of vectors truly supported by
* the current CPU being used. This is usually the number of distinct vectors
* the cpu can vector.
*/
-
#define ISR_NUMBER_OF_VECTORS CPU_INTERRUPT_NUMBER_OF_VECTORS
-/*
+/**
* This constant promotes out the highest valid interrupt vector number.
*/
-
#define ISR_INTERRUPT_MAXIMUM_VECTOR_NUMBER CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER
-/*
+/**
* The following is TRUE if signals have been sent to the currently
* executing thread by an ISR handler.
*/
-
SCORE_EXTERN boolean _ISR_Signals_to_thread_executing;
-/*
+/**
* The following contains the interrupt service routine nest level.
* When this variable is zero, a thread is executing.
*/
-
SCORE_EXTERN volatile uint32_t _ISR_Nest_level;
-/*
+/**
* The following declares the Vector Table. Application
* interrupt service routines are vectored by the ISR Handler via this table.
*/
-
SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table;
-/*
- * _ISR_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
*/
-
void _ISR_Handler_initialization ( void );
-/*
- * _ISR_Disable
- *
- * DESCRIPTION:
- *
+/**
* This routine disables all interrupts so that a critical section
* of code can be executing without being interrupted. Upon return,
* the argument _level will contain the previous interrupt mask level.
*/
-
#define _ISR_Disable( _level ) \
_CPU_ISR_Disable( _level )
-/*
- * _ISR_Enable
- *
- * DESCRIPTION:
- *
+/**
* This routine enables interrupts to the previous interrupt mask
* LEVEL. It is used at the end of a critical section of code to
* enable interrupts so they can be processed again.
*/
-
#define _ISR_Enable( _level ) \
_CPU_ISR_Enable( _level )
-/*
- * _ISR_Flash
- *
- * DESCRIPTION:
- *
+/**
* This routine temporarily enables interrupts to the previous
* interrupt mask level and then disables all interrupts so that
* the caller can continue into the second part of a critical
@@ -142,52 +126,32 @@ void _ISR_Handler_initialization ( void );
* must be selected with care to insure that the critical section
* properly protects itself.
*/
-
#define _ISR_Flash( _level ) \
_CPU_ISR_Flash( _level )
-/*
- * _ISR_Install_vector
- *
- * DESCRIPTION:
- *
+/**
* This routine installs new_handler as the interrupt service routine
* for the specified vector. The previous interrupt service routine is
* returned as old_handler.
*/
-
#define _ISR_Install_vector( _vector, _new_handler, _old_handler ) \
_CPU_ISR_install_vector( _vector, _new_handler, _old_handler )
-/*
- * _ISR_Get_level
- *
- * DESCRIPTION:
- *
+/**
* This routine returns the current interrupt level.
*/
-
#define _ISR_Get_level() \
_CPU_ISR_Get_level()
-/*
- * _ISR_Set_level
- *
- * DESCRIPTION:
- *
+/**
* This routine sets the current interrupt level to that specified
* by new_level. The new interrupt level is effective when the
* routine exits.
*/
-
#define _ISR_Set_level( _new_level ) \
_CPU_ISR_Set_level( _new_level )
-/*
- * _ISR_Handler
- *
- * DESCRIPTION:
- *
+/**
* This routine is the interrupt dispatcher. ALL interrupts
* are vectored to this routine so that minimal context can be saved
* and setup performed before the application's high-level language
@@ -197,40 +161,28 @@ void _ISR_Handler_initialization ( void );
* insure that the necessary thread scheduling operations are
* performed when the outermost interrupt service routine exits.
*
- * NOTE: Implemented in assembly language.
+ * @note Implemented in assembly language.
*/
-
void _ISR_Handler( void );
-/*
- * _ISR_Dispatch
- *
- * DESCRIPTION:
- *
+/**
* This routine provides a wrapper so that the routine
- * _Thread_Dispatch can be invoked when a reschedule is necessary
+ * @ref _Thread_Dispatch can be invoked when a reschedule is necessary
* at the end of the outermost interrupt service routine. This
* wrapper is necessary to establish the processor context needed
* by _Thread_Dispatch and to save the processor context which is
* corrupted by _Thread_Dispatch. This context typically consists
* of registers which are not preserved across routine invocations.
*
- * NOTE: Implemented in assembly language.
+ * @note Implemented in assembly language.
*/
-
void _ISR_Dispatch( void );
-/*PAGE
- *
- * _ISR_Is_in_progress
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the processor is currently servicing
* and interrupt and FALSE otherwise. A return value of TRUE indicates
* that the caller is an interrupt service routine, NOT a thread. The
*/
-
#if (CPU_PROVIDES_ISR_IS_IN_PROGRESS == TRUE)
boolean _ISR_Is_in_progress( void );
#else
@@ -244,5 +196,7 @@ boolean _ISR_Is_in_progress( void );
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h
index 118e31afaa..da5636957d 100644
--- a/cpukit/score/include/rtems/score/mpci.h
+++ b/cpukit/score/include/rtems/score/mpci.h
@@ -1,9 +1,12 @@
-/* mpci.h
+/**
+ * @file mpci.h
*
* This include file contains all the constants and structures associated
* with the MPCI layer. It provides mechanisms to utilize packets.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __MPCI_h
#define __MPCI_h
+/**
+ * @defgroup ScoreMPCI MPCI Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -32,7 +42,6 @@ extern "C" {
* The following constants define the stack size requirements for
* the system threads.
*/
-
#define MPCI_RECEIVE_SERVER_STACK_SIZE \
( STACK_MINIMUM_SIZE + \
CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK + \
@@ -42,7 +51,6 @@ extern "C" {
/*
* The following defines the node number used when a broadcast is desired.
*/
-
#define MPCI_ALL_NODES 0
/*
@@ -51,7 +59,6 @@ extern "C" {
* the MPCI driver sets an upper limit on how long a remote request
* should take to complete.
*/
-
#define MPCI_DEFAULT_TIMEOUT 0xFFFFFFFF
/*
@@ -63,268 +70,224 @@ extern "C" {
* we need a timeout. This is a per-driver timeout: default_timeout
*/
+/**
+ * This type is returned by all user provided MPCI routines.
+ */
typedef void MPCI_Entry;
+/**
+ * This type is XXX
+ */
typedef MPCI_Entry ( *MPCI_initialization_entry )( void );
+/**
+ * This type is XXX
+ */
typedef MPCI_Entry ( *MPCI_get_packet_entry )(
MP_packet_Prefix **
);
+/**
+ * This type is XXX
+ */
typedef MPCI_Entry ( *MPCI_return_packet_entry )(
MP_packet_Prefix *
);
+/**
+ * This type is XXX
+ */
typedef MPCI_Entry ( *MPCI_send_entry )(
uint32_t ,
MP_packet_Prefix *
);
+/**
+ * This type is XXX
+ */
typedef MPCI_Entry ( *MPCI_receive_entry )(
MP_packet_Prefix **
);
+/**
+ * This type is XXX
+ */
typedef struct {
- uint32_t default_timeout; /* in ticks */
+ /** timeout for MPCI operations in ticks */
+ uint32_t default_timeout;
+ /** XXX */
uint32_t maximum_packet_size;
+ /** XXX */
MPCI_initialization_entry initialization;
+ /** XXX */
MPCI_get_packet_entry get_packet;
+ /** XXX */
MPCI_return_packet_entry return_packet;
+ /** XXX */
MPCI_send_entry send_packet;
+ /** XXX */
MPCI_receive_entry receive_packet;
} MPCI_Control;
-/*
+/**
* The following defines the type for packet processing routines
* invoked by the MPCI Receive server.
*/
-
typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * );
-/*
+/**
* The following enumerated type defines the list of
* internal MP operations.
*/
-
typedef enum {
MPCI_PACKETS_SYSTEM_VERIFY = 0
} MPCI_Internal_Remote_operations;
-/*
+/**
* The following data structure defines the packet used to perform
* remote event operations.
*/
-
typedef struct {
+ /** XXX */
MP_packet_Prefix Prefix;
+ /** XXX */
MPCI_Internal_Remote_operations operation;
+ /** XXX */
uint32_t maximum_nodes;
+ /** XXX */
uint32_t maximum_global_objects;
} MPCI_Internal_packet;
-/*
+/**
* This is the core semaphore which the MPCI Receive Server blocks on.
*/
-
SCORE_EXTERN CORE_semaphore_Control _MPCI_Semaphore;
-/*
+
+/**
* The following thread queue is used to maintain a list of tasks
* which currently have outstanding remote requests.
*/
-
SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads;
-/*
+/**
* The following define the internal pointers to the user's
* configuration information.
*/
-
SCORE_EXTERN MPCI_Control *_MPCI_table;
-/*
+/**
* The following points to the MPCI Receive Server.
*/
-
SCORE_EXTERN Thread_Control *_MPCI_Receive_server_tcb;
-/*
+/**
* The following table contains the process packet routines provided
* by each object that supports MP operations.
*/
-
SCORE_EXTERN MPCI_Packet_processor
_MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1];
-/*
- * _MPCI_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
*/
-
void _MPCI_Handler_initialization(
MPCI_Control *users_mpci_table,
uint32_t timeout_status
);
-/*
- * _MPCI_Create_server
- *
- * DESCRIPTION:
- *
+/**
* This routine creates the packet receive server used in MP systems.
*/
-
void _MPCI_Create_server( void );
-/*
- * _MPCI_Initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the MPCI driver by
* invoking the user provided MPCI initialization callout.
*/
-
void _MPCI_Initialization ( void );
-/*
- * _MPCI_Register_packet_processor
- *
- * DESCRIPTION:
- *
+/**
* This routine registers the MPCI packet processor for the
* designated object class.
*/
-
void _MPCI_Register_packet_processor(
MP_packet_Classes the_class,
MPCI_Packet_processor the_packet_processor
);
-/*
- * _MPCI_Get_packet
- *
- * DESCRIPTION:
- *
+/**
* This function obtains a packet by invoking the user provided
* MPCI get packet callout.
*/
-
MP_packet_Prefix *_MPCI_Get_packet ( void );
-/*
- * _MPCI_Return_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine returns a packet by invoking the user provided
* MPCI return packet callout.
*/
-
void _MPCI_Return_packet (
MP_packet_Prefix *the_packet
);
-/*
- * _MPCI_Send_process_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine sends a process packet by invoking the user provided
* MPCI send callout.
*/
-
void _MPCI_Send_process_packet (
uint32_t destination,
MP_packet_Prefix *the_packet
);
-/*
- * _MPCI_Send_request_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine sends a request packet by invoking the user provided
* MPCI send callout.
*/
-
uint32_t _MPCI_Send_request_packet (
uint32_t destination,
MP_packet_Prefix *the_packet,
States_Control extra_state
);
-/*
- * _MPCI_Send_response_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine sends a response packet by invoking the user provided
* MPCI send callout.
*/
-
void _MPCI_Send_response_packet (
uint32_t destination,
MP_packet_Prefix *the_packet
);
-/*
- * _MPCI_Receive_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine receives a packet by invoking the user provided
* MPCI receive callout.
*/
-
MP_packet_Prefix *_MPCI_Receive_packet ( void );
-/*
- * _MPCI_Process_response
- *
- * DESCRIPTION:
- *
+/**
* This routine obtains a packet by invoking the user provided
* MPCI get packet callout.
*/
-
Thread_Control *_MPCI_Process_response (
MP_packet_Prefix *the_packet
);
-/*PAGE
- *
- * _MPCI_Receive_server
- *
+/**
+ * This is the server thread which receives and processes all MCPI packets.
*/
-
Thread _MPCI_Receive_server(
uint32_t ignored
);
-/*PAGE
- *
- * _MPCI_Announce
- *
- * DESCRIPTION:
- *
- * XXX
+/**
+ * This routine informs RTEMS of the availability of an MPCI packet.
*/
-
void _MPCI_Announce ( void );
-/*
- * _MPCI_Internal_packets_Send_process_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine performs a remote procedure call so that a
* process operation can be performed on another node.
*/
-
void _MPCI_Internal_packets_Send_process_packet (
MPCI_Internal_Remote_operations operation
);
@@ -332,8 +295,6 @@ void _MPCI_Internal_packets_Send_process_packet (
/*
* _MPCI_Internal_packets_Send_request_packet
*
- * DESCRIPTION:
- *
* This routine performs a remote procedure call so that a
* directive operation can be initiated on another node.
*
@@ -344,8 +305,6 @@ void _MPCI_Internal_packets_Send_process_packet (
/*
* _MPCI_Internal_packets_Send_response_packet
*
- * DESCRIPTION:
- *
* This routine performs a remote procedure call so that a
* directive can be performed on another node.
*
@@ -353,16 +312,10 @@ void _MPCI_Internal_packets_Send_process_packet (
* packets to be sent by this manager.
*/
-/*
- *
- * _MPCI_Internal_packets_Process_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the actions specific to this package for
* the request from another node.
*/
-
void _MPCI_Internal_packets_Process_packet (
MP_packet_Prefix *the_packet_prefix
);
@@ -370,8 +323,6 @@ void _MPCI_Internal_packets_Process_packet (
/*
* _MPCI_Internal_packets_Send_object_was_deleted
*
- * DESCRIPTION:
- *
* This routine is invoked indirectly by the thread queue
* when a proxy has been removed from the thread queue and
* the remote node must be informed of this.
@@ -383,8 +334,6 @@ void _MPCI_Internal_packets_Process_packet (
/*
* _MPCI_Internal_packets_Send_extract_proxy
*
- * DESCRIPTION:
- *
* This routine is invoked when a task is deleted and it
* has a proxy which must be removed from a thread queue and
* the remote node must be informed of this.
@@ -393,19 +342,16 @@ void _MPCI_Internal_packets_Process_packet (
* deleted by this manager.
*/
-/*
- * _MPCI_Internal_packets_Get_packet
- *
- * DESCRIPTION:
- *
+/**
* This routine is used to obtain a internal threads mp packet.
*/
-
- MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
+MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
#ifdef __cplusplus
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/mppkt.h b/cpukit/score/include/rtems/score/mppkt.h
index 3c70225cc1..515d67150f 100644
--- a/cpukit/score/include/rtems/score/mppkt.h
+++ b/cpukit/score/include/rtems/score/mppkt.h
@@ -1,13 +1,15 @@
-/* mppkt.h
+/**
+ * @file mppkt.h
*
* This package is the specification for the Packet Handler.
* This handler defines the basic packet and provides
* mechanisms to utilize packets based on this prefix.
* Packets are the fundamental basis for messages passed between
* nodes in an MP system.
- *
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -20,6 +22,13 @@
#ifndef __MP_PACKET_h
#define __MP_PACKET_h
+/**
+ * @defgroup ScoreMPPacket MP Packet Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -28,14 +37,13 @@ extern "C" {
#include <rtems/score/priority.h>
#include <rtems/score/watchdog.h>
-/*
+/**
* The following enumerated type defines the packet classes.
*
- * NOTE: In general, each class corresponds to a manager
+ * @note In general, each class corresponds to a manager
* which supports global operations. Each manager
* defines the set of supported operations.
*/
-
typedef enum {
MP_PACKET_MPCI_INTERNAL = 0,
MP_PACKET_TASKS = 1,
@@ -47,43 +55,55 @@ typedef enum {
MP_PACKET_SIGNAL = 7
} MP_packet_Classes;
+/**
+ * XXX
+ */
#define MP_PACKET_CLASSES_FIRST MP_PACKET_MPCI_INTERNAL
+
+/**
+ * XXX
+ */
#define MP_PACKET_CLASSES_LAST MP_PACKET_SIGNAL
-/*
+/**
* The following record contains the prefix for every packet
* passed between nodes in an MP system.
*
- * NOTE: This structure is padded to ensure that anything following it
+ * @note This structure is padded to ensure that anything following it
* is on a 16 byte boundary. This is the most stringent structure
* alignment rule encountered yet.
*/
-
typedef struct {
+ /** XXX */
MP_packet_Classes the_class;
+ /** XXX */
Objects_Id id;
+ /** XXX */
Objects_Id source_tid;
+ /** XXX */
Priority_Control source_priority;
+ /** XXX */
uint32_t return_code;
+ /** XXX */
uint32_t length;
+ /** XXX */
uint32_t to_convert;
+ /** XXX */
Watchdog_Interval timeout;
} MP_packet_Prefix;
-/*
+/**
* An MPCI must support packets of at least this size.
*/
-
#define MP_PACKET_MINIMUM_PACKET_SIZE 64
-/*
+/**
* The following constant defines the number of uint32_t 's
* in a packet which must be converted to native format in a
* heterogeneous system. In packets longer than
* MP_PACKET_MINIMUN_HETERO_CONVERSION uint32_t 's, some of the "extra" data
* may a user message buffer which is not automatically endian swapped.
*/
-
#define MP_PACKET_MINIMUN_HETERO_CONVERSION \
( sizeof( MP_packet_Prefix ) / sizeof( uint32_t ) )
@@ -95,5 +115,7 @@ typedef struct {
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/objectmp.h b/cpukit/score/include/rtems/score/objectmp.h
index 947b03c59d..cf6a4d68d2 100644
--- a/cpukit/score/include/rtems/score/objectmp.h
+++ b/cpukit/score/include/rtems/score/objectmp.h
@@ -1,9 +1,12 @@
-/* objectmp.h
+/**
+ * @file objectmp.h
*
* This include file contains all the constants and structures associated
* with the manipulation of Global RTEMS Objects.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __RTEMS_OBJECTS_MP_h
#define __RTEMS_OBJECTS_MP_h
+/**
+ * @defgroup ScoreObjectMP Object Handler Multiprocessing Support
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -24,33 +34,24 @@ extern "C" {
* This defines the Global Object Control Block used to manage
* objects resident on other nodes.
*/
-
typedef struct {
Objects_Control Object;
uint32_t name; /* XXX broken but works */
/* XXX If any API is MP with variable length names .. BOOM!!!! */
} Objects_MP_Control;
-/*
- * _Objects_MP_Handler_initialization
- *
- * DESCRIPTION:
+/** @brief Objects MP Handler initialization
*
* This routine intializes the inactive global object chain
* based on the maximum number of global objects configured.
*/
-
void _Objects_MP_Handler_initialization (
uint32_t node,
uint32_t maximum_nodes,
uint32_t maximum_global_objects
);
-/*PAGE
- *
- * _Objects_MP_Open
- *
- * DESCRIPTION:
+/** @brief Objects MP Open
*
* This routine place the specified global object in the
* specified information table.
@@ -63,17 +64,13 @@ void _Objects_MP_Open (
Objects_Id the_id
);
-/*
- * _Objects_MP_Allocate_and_open
- *
- * DESCRIPTION:
+/** @brief Objects MP Allocate and open
*
* This routine allocates a global object control block
* and places it in the specified information table. If the
* allocation fails, then is_fatal_error determines the
* error processing actions taken.
*/
-
boolean _Objects_MP_Allocate_and_open (
Objects_Information *information,
uint32_t the_name, /* XXX -- wrong for variable length */
@@ -81,30 +78,22 @@ boolean _Objects_MP_Allocate_and_open (
boolean is_fatal_error
);
-/*
- * _Objects_MP_Close
- *
- * DESCRIPTION:
+/** @brief Objects MP Close
*
* This routine removes a global object from the specified
* information table and deallocates the global object control block.
*/
-
void _Objects_MP_Close (
Objects_Information *information,
Objects_Id the_id
);
-/*
- * _Objects_MP_Global_name_search
- *
- * DESCRIPTION:
+/** @brief Objects MP Global name search
*
* This routine looks for the object with the_name in the global
* object tables indicated by information. It returns the ID of the
* object with that name if one is found.
*/
-
Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
Objects_Information *information,
Objects_Name the_name,
@@ -112,10 +101,7 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
Objects_Id *the_id
);
-/*
- * _Objects_MP_Is_remote
- *
- * DESCRIPTION:
+/** @brief Objects MP Is remote
*
* This function searches the Global Object Table managed
* by information for the object indicated by ID. If the object
@@ -123,7 +109,6 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
* location is set to objects_error. In both cases, the_object
* is undefined.
*/
-
void _Objects_MP_Is_remote (
Objects_Information *information,
Objects_Id the_id,
@@ -135,7 +120,6 @@ void _Objects_MP_Is_remote (
* The following chain header is used to manage the set of
* inactive global object control blocks.
*/
-
SCORE_EXTERN uint32_t _Objects_MP_Maximum_global_objects;
SCORE_EXTERN Chain_Control _Objects_MP_Inactive_global_objects;
@@ -147,5 +131,7 @@ SCORE_EXTERN Chain_Control _Objects_MP_Inactive_global_objects;
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h
index 3c8454f203..9ab1bc3c8c 100644
--- a/cpukit/score/include/rtems/score/priority.h
+++ b/cpukit/score/include/rtems/score/priority.h
@@ -1,10 +1,13 @@
-/* priority.h
+/**
+ * @file priority.h
*
* This include file contains all thread priority manipulation routines.
* This Handler provides mechanisms which can be used to
* initialize and manipulate thread priorities.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,13 @@
#ifndef __PRIORITY_h
#define __PRIORITY_h
+/**
+ * @defgroup ScorePriority Priority Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -25,7 +35,7 @@ extern "C" {
* The following type defines the control block used to manage
* thread priorities.
*
- * NOTE: Priority 0 is reserved for internal threads only.
+ * @note Priority 0 is reserved for internal threads only.
*/
typedef uint32_t Priority_Control;
@@ -69,7 +79,7 @@ SCORE_EXTERN Priority_Bit_map_control
/*
* Priority Bitfield Manipulation Routines
*
- * NOTE:
+ * @note
*
* These may simply be pass throughs to CPU dependent routines.
*/
@@ -92,5 +102,7 @@ SCORE_EXTERN Priority_Bit_map_control
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/stack.h b/cpukit/score/include/rtems/score/stack.h
index 16c01f7ea3..39c8f94cc0 100644
--- a/cpukit/score/include/rtems/score/stack.h
+++ b/cpukit/score/include/rtems/score/stack.h
@@ -1,10 +1,13 @@
-/* stack.h
+/**
+ * @file stack.h
*
* This include file contains all information about the thread
* Stack Handler. This Handler provides mechanisms which can be used to
* initialize and utilize stacks.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,13 @@
#ifndef __STACK_h
#define __STACK_h
+/**
+ * @defgroup ScoreStack Stack Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -45,5 +55,7 @@ typedef struct {
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/states.h b/cpukit/score/include/rtems/score/states.h
index 59d27c274e..0ed5db73b1 100644
--- a/cpukit/score/include/rtems/score/states.h
+++ b/cpukit/score/include/rtems/score/states.h
@@ -1,8 +1,11 @@
-/* states.h
+/**
+ * @file states.h
*
* This include file contains thread execution state information.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -15,6 +18,13 @@
#ifndef __RTEMS_STATES_h
#define __RTEMS_STATES_h
+/**
+ * @defgroup ScoreStates Thread States Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -79,5 +89,7 @@ typedef uint32_t States_Control;
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/sysstate.h b/cpukit/score/include/rtems/score/sysstate.h
index 2f0636399b..3302be767c 100644
--- a/cpukit/score/include/rtems/score/sysstate.h
+++ b/cpukit/score/include/rtems/score/sysstate.h
@@ -1,8 +1,11 @@
-/* sysstates.h
+/**
+ * @file sysstate.h
*
* This include file contains information regarding the system state.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -15,6 +18,13 @@
#ifndef __RTEMS_SYSTEM_STATE_h
#define __RTEMS_SYSTEM_STATE_h
+/**
+ * @defgroup ScoreSysState System State Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -62,5 +72,7 @@ SCORE_EXTERN System_state_Codes _System_state_Current;
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index 8090656461..3e9fb9335e 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -1,9 +1,12 @@
-/* thread.h
+/**
+ * @file thread.h
*
* This include file contains all constants and structures associated
* with the thread control block.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __THREAD_h
#define __THREAD_h
+/**
+ * @defgroup ScoreThread Thread Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -33,25 +43,23 @@ extern "C" {
#include <rtems/score/tqdata.h>
#include <rtems/score/watchdog.h>
-/*
+/**
* The following defines the "return type" of a thread.
*
- * NOTE: This cannot always be right. Some APIs have void
+ * @note This cannot always be right. Some APIs have void
* tasks/threads, others return pointers, others may
* return a numeric value. Hopefully a pointer is
* always at least as big as an uint32_t . :)
*/
-
typedef void *Thread;
-/*
+/**
* The following defines the ways in which the entry point for a
* thread can be invoked. Basically, it can be passed any
* combination/permutation of a pointer and an uint32_t value.
*
- * NOTE: For now, we are ignoring the return type.
+ * @note For now, we are ignoring the return type.
*/
-
typedef enum {
THREAD_START_NUMERIC,
THREAD_START_POINTER,
@@ -59,21 +67,31 @@ typedef enum {
THREAD_START_BOTH_NUMERIC_FIRST
} Thread_Start_types;
+/**
+ */
typedef Thread ( *Thread_Entry )(); /* basic type */
typedef Thread ( *Thread_Entry_numeric )( uint32_t );
+
+/**
+ */
typedef Thread ( *Thread_Entry_pointer )( void * );
+
+/**
+ */
typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t );
+
+/**
+ */
typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t , void * );
-/*
+/**
* The following lists the algorithms used to manage the thread cpu budget.
*
* Reset Timeslice: At each context switch, reset the time quantum.
* Exhaust Timeslice: Only reset the quantum once it is consumed.
* Callout: Execute routine when budget is consumed.
*/
-
typedef enum {
THREAD_CPU_BUDGET_ALGORITHM_NONE,
THREAD_CPU_BUDGET_ALGORITHM_RESET_TIMESLICE,
@@ -81,31 +99,47 @@ typedef enum {
THREAD_CPU_BUDGET_ALGORITHM_CALLOUT
} Thread_CPU_budget_algorithms;
+/**
+ */
typedef struct Thread_Control_struct Thread_Control;
+/**
+ */
typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
-/*
- * Per task variable structure
+/** @brief Per Task Variable Manager Structure Forward Reference
+ *
+ * Forward reference to the per task variable structure.
*/
-
struct rtems_task_variable_tt;
+/** @brief Per Task Variable Manager Structure
+ *
+ * This is the internal structure used to manager per Task Variables.
+ */
struct rtems_task_variable_tt {
+ /** This field points to the next per task variable for this task. */
struct rtems_task_variable_tt *next;
+ /** This field points to the physical memory location of this per
+ * task variable.
+ */
void **ptr;
+ /** This field is to the global value for this per task variable. */
void *gval;
+ /** This field is to this thread's value for this per task variable. */
void *tval;
+ /** This field points to the destructor for this per task variable. */
void (*dtor)(void *);
};
+/**
+ */
typedef struct rtems_task_variable_tt rtems_task_variable_t;
-/*
+/**
* The following structure contains the information which defines
* the starting state of a thread.
*/
-
typedef struct {
Thread_Entry entry_point; /* starting thread address */
Thread_Start_types prototype; /* how task is invoked */
@@ -125,38 +159,50 @@ typedef struct {
void *stack; /* initial stack area address */
} Thread_Start_information;
-/*
+/**
* The following structure contains the information necessary to manage
* a thread which it is waiting for a resource.
*/
-
#define THREAD_STATUS_PROXY_BLOCKING 0x1111111
+/** @brief Thread Blocking Management Information
+ *
+ * This contains the information required to manage a thread while it is
+ * blocked and to return information to it.
+ */
typedef struct {
- Objects_Id id; /* waiting on this object */
- uint32_t count; /* "generic" fields to be used */
- void *return_argument; /* when blocking */
+ /** This field is the Id of the object this thread is waiting upon. */
+ Objects_Id id;
+ /** This field is used to return an integer while when blocked. */
+ uint32_t count;
+ /** This field is the first pointer to a user return argument. */
+ void *return_argument;
+ /** This field is the second pointer to a user return argument. */
void *return_argument_1;
+ /** This field contains any options in effect on this blocking operation. */
uint32_t option;
-
- /*
- * NOTE: The following assumes that all API return codes can be
- * treated as an uint32_t .
+ /** This field will contain the return status from a blocking operation.
+ *
+ * @note The following assumes that all API return codes can be
+ * treated as an uint32_t.
*/
- uint32_t return_code; /* status for thread awakened */
+ uint32_t return_code;
- Chain_Control Block2n; /* 2 - n priority blocked chain */
- Thread_queue_Control *queue; /* pointer to thread queue */
+ /** This field is the chain header for the second through Nth tasks
+ * of the same priority blocked waiting on the same object.
+ */
+ Chain_Control Block2n;
+ /** This field points to the thread queue on which this thread is blocked. */
+ Thread_queue_Control *queue;
} Thread_Wait_information;
-/*
+/**
* The following defines the control block used to manage
* each thread proxy.
*
- * NOTE: It is critical that proxies and threads have identical
+ * @note It is critical that proxies and threads have identical
* memory images for the shared part.
*/
-
typedef struct {
Objects_Control Object;
States_Control current_state;
@@ -172,24 +218,29 @@ typedef struct {
Chain_Node Active;
} Thread_Proxy_control;
-
-/*
+/**
* The following record defines the control block used
* to manage each thread.
*
- * NOTE: It is critical that proxies and threads have identical
+ * @note It is critical that proxies and threads have identical
* memory images for the shared part.
*/
-
typedef enum {
THREAD_API_RTEMS,
THREAD_API_POSIX,
THREAD_API_ITRON
} Thread_APIs;
+/**
+ */
#define THREAD_API_FIRST THREAD_API_RTEMS
+
+/**
+ */
#define THREAD_API_LAST THREAD_API_ITRON
+/**
+ */
struct Thread_Control_struct {
Objects_Control Object;
States_Control current_state;
@@ -226,98 +277,86 @@ struct Thread_Control_struct {
rtems_task_variable_t *task_variables;
};
-/*
+/**
* Self for the GNU Ada Run-Time
*/
-
SCORE_EXTERN void *rtems_ada_self;
-/*
+/**
* The following defines the information control block used to
* manage this class of objects.
*/
-
SCORE_EXTERN Objects_Information _Thread_Internal_information;
-/*
+/**
* The following define the thread control pointers used to access
* and manipulate the idle thread.
*/
-
SCORE_EXTERN Thread_Control *_Thread_Idle;
-/*
+/**
* The following context area contains the context of the "thread"
* which invoked the start multitasking routine. This context is
* restored as the last action of the stop multitasking routine. Thus
* control of the processor can be returned to the environment
* which initiated the system.
*/
-
SCORE_EXTERN Context_Control _Thread_BSP_context;
-/*
+/***
* The following declares the dispatch critical section nesting
* counter which is used to prevent context switches at inopportune
* moments.
*/
-
SCORE_EXTERN volatile uint32_t _Thread_Dispatch_disable_level;
-/*
+/**
* If this is non-zero, then the post-task switch extension
* is run regardless of the state of the per thread flag.
*/
-
SCORE_EXTERN uint32_t _Thread_Do_post_task_switch_extension;
-/*
+/**
* The following holds how many user extensions are in the system. This
* is used to determine how many user extension data areas to allocate
* per thread.
*/
-
SCORE_EXTERN uint32_t _Thread_Maximum_extensions;
-/*
+/**
* The following is used to manage the length of a timeslice quantum.
*/
-
SCORE_EXTERN uint32_t _Thread_Ticks_per_timeslice;
-/*
+/**
* The following points to the array of FIFOs used to manage the
* set of ready threads.
*/
-
SCORE_EXTERN Chain_Control *_Thread_Ready_chain;
-/*
+/**
* The following points to the thread which is currently executing.
* This thread is implicitly manipulated by numerous directives.
*/
-
SCORE_EXTERN Thread_Control *_Thread_Executing;
-/*
+/**
* The following points to the highest priority ready thread
* in the system. Unless the current thread is not preemptibl,
* then this thread will be context switched to when the next
* dispatch occurs.
*/
-
SCORE_EXTERN Thread_Control *_Thread_Heir;
-/*
+/**
* The following points to the thread whose floating point
* context is currently loaded.
*/
-
#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
SCORE_EXTERN Thread_Control *_Thread_Allocated_fp;
#endif
-/*
+/**
* The C library re-enter-rant global pointer. Some C library implementations
* such as newlib have a single global pointer that changed during a context
* switch. The pointer points to that global pointer. The Thread control block
@@ -325,49 +364,30 @@ SCORE_EXTERN Thread_Control *_Thread_Allocated_fp;
*/
SCORE_EXTERN struct _reent **_Thread_libc_reent;
-/*
- * _Thread_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
*/
-
void _Thread_Handler_initialization (
uint32_t ticks_per_timeslice,
uint32_t maximum_extensions,
uint32_t maximum_proxies
);
-/*
- * _Thread_Create_idle
- *
- * DESCRIPTION:
- *
+/**
* This routine creates the idle thread.
*
- * WARNING!! No thread should be created before this one.
+ * @warning No thread should be created before this one.
*/
-
void _Thread_Create_idle( void );
-/*
- * _Thread_Start_multitasking
- *
- * DESCRIPTION:
- *
+/**
* This routine initiates multitasking. It is invoked only as
* part of initialization and its invocation is the last act of
* the non-multitasking part of the system initialization.
*/
-
void _Thread_Start_multitasking( void );
-/*
- * _Thread_Dispatch
- *
- * DESCRIPTION:
- *
+/**
* This routine is responsible for transferring control of the
* processor from the executing thread to the heir thread. As part
* of this process, it is responsible for the following actions:
@@ -376,21 +396,13 @@ void _Thread_Start_multitasking( void );
* + restoring the context of the heir thread
* + dispatching any signals for the resulting executing thread
*/
-
void _Thread_Dispatch( void );
-/*
- * _Thread_Stack_Allocate
- *
- * DESCRIPTION:
- *
+/**
* Allocate the requested stack space for the thread.
* return the actual size allocated after any adjustment
* or return zero if the allocation failed.
* Set the Start.stack field to the address of the stack
- *
- * NOTES: NONE
- *
*/
uint32_t _Thread_Stack_Allocate(
@@ -398,38 +410,24 @@ uint32_t _Thread_Stack_Allocate(
uint32_t stack_size
);
-/*
- * _Thread_Stack_Free
- *
- * DESCRIPTION:
- *
+/**
* Deallocate the Thread's stack.
- * NOTES: NONE
- *
*/
-
void _Thread_Stack_Free(
Thread_Control *the_thread
);
-/*
- * _Thread_Initialize
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the specified the thread. It allocates
* all memory associated with this thread. It completes by adding
* the thread to the local object table so operations on this
* thread id are allowed.
*
- * NOTES:
+ * @note If stack_area is NULL, it is allocated from the workspace.
*
- * If stack_area is NULL, it is allocated from the workspace.
- *
- * If the stack is allocated from the workspace, then it is guaranteed to be
- * of at least minimum size.
+ * @note If the stack is allocated from the workspace, then it is
+ * guaranteed to be of at least minimum size.
*/
-
boolean _Thread_Initialize(
Objects_Information *information,
Thread_Control *the_thread,
@@ -444,16 +442,11 @@ boolean _Thread_Initialize(
Objects_Name name
);
-/*
- * _Thread_Start
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the executable information for a thread
* and makes it ready to execute. After this routine executes, the
* thread competes with all other threads for CPU time.
*/
-
boolean _Thread_Start(
Thread_Control *the_thread,
Thread_Start_types the_prototype,
@@ -462,118 +455,78 @@ boolean _Thread_Start(
uint32_t numeric_argument
);
-/*
- * _Thread_Restart
- *
- * DESCRIPTION:
- *
+/**
* This support routine restarts the specified task in a way that the
* next time this thread executes, it will begin execution at its
* original starting point.
+ *
+ * TODO: multiple task arg profiles
*/
-
-/* XXX multiple task arg profiles */
-
boolean _Thread_Restart(
Thread_Control *the_thread,
void *pointer_argument,
uint32_t numeric_argument
);
-/*
- * _Thread_Reset
- *
- * DESCRIPTION:
- *
+/**
* This routine resets a thread to its initial state but does
* not restart it.
*/
-
void _Thread_Reset(
Thread_Control *the_thread,
void *pointer_argument,
uint32_t numeric_argument
);
-/*
- * _Thread_Close
- *
- * DESCRIPTION:
- *
+/**
* This routine frees all memory associated with the specified
* thread and removes it from the local object table so no further
* operations on this thread are allowed.
*/
-
void _Thread_Close(
Objects_Information *information,
Thread_Control *the_thread
);
-/*
- * _Thread_Ready
- *
- * DESCRIPTION:
- *
+/**
* This routine removes any set states for the_thread. It performs
* any necessary scheduling operations including the selection of
* a new heir thread.
*/
-
void _Thread_Ready(
Thread_Control *the_thread
);
-/*
- * _Thread_Clear_state
- *
- * DESCRIPTION:
- *
+/**
* This routine clears the indicated STATES for the_thread. It performs
* any necessary scheduling operations including the selection of
* a new heir thread.
*/
-
void _Thread_Clear_state(
Thread_Control *the_thread,
States_Control state
);
-/*
- * _Thread_Set_state
- *
- * DESCRIPTION:
- *
+/**
* This routine sets the indicated states for the_thread. It performs
* any necessary scheduling operations including the selection of
* a new heir thread.
- *
*/
-
void _Thread_Set_state(
Thread_Control *the_thread,
States_Control state
);
-/*
- * _Thread_Set_transient
- *
- * DESCRIPTION:
- *
+/**
* This routine sets the TRANSIENT state for the_thread. It performs
* any necessary scheduling operations including the selection of
* a new heir thread.
*/
-
void _Thread_Set_transient(
Thread_Control *the_thread
);
-/*
- * _Thread_Reset_timeslice
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked upon expiration of the currently
* executing thread's timeslice. If no other thread's are ready
* at the priority of the currently executing thread, then the
@@ -581,198 +534,131 @@ void _Thread_Set_transient(
* currently executing thread is placed at the rear of the
* FIFO for this priority and a new heir is selected.
*/
-
void _Thread_Reset_timeslice( void );
-/*
- * _Thread_Tickle_timeslice
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked as part of processing each clock tick.
* It is responsible for determining if the current thread allows
* timeslicing and, if so, when its timeslice expires.
*/
-
void _Thread_Tickle_timeslice( void );
-/*
- * _Thread_Yield_processor
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked when a thread wishes to voluntarily
* transfer control of the processor to another thread of equal
* or greater priority.
*/
-
void _Thread_Yield_processor( void );
-/*
- * _Thread_Rotate_Ready_Queue
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked to rotate the ready queue for the
* given priority. It can be used to yeild the processor
* by rotating the executing threads ready queue.
*/
-
void _Thread_Rotate_Ready_Queue(
Priority_Control priority
);
-/*
- * _Thread_Load_environment
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the context of the_thread to its
* appropriate starting state.
*/
-
void _Thread_Load_environment(
Thread_Control *the_thread
);
-/*
- * _Thread_Handler
- *
- * DESCRIPTION:
- *
+/**
* This routine is the wrapper function for all threads. It is
* the starting point for all threads. The user provided thread
* entry point is invoked by this routine. Operations
* which must be performed immediately before and after the user's
* thread executes are found here.
*/
-
void _Thread_Handler( void );
-/*
- * _Thread_Delay_ended
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked when a thread must be unblocked at the
* end of a time based delay (i.e. wake after or wake when).
*/
-
void _Thread_Delay_ended(
Objects_Id id,
void *ignored
);
-/*
- * _Thread_Change_priority
- *
- * DESCRIPTION:
- *
+/**
* This routine changes the current priority of the_thread to
* new_priority. It performs any necessary scheduling operations
* including the selection of a new heir thread.
*/
-
void _Thread_Change_priority (
Thread_Control *the_thread,
Priority_Control new_priority,
boolean prepend_it
);
-/*
- * _Thread_Set_priority
- *
- * DESCRIPTION:
- *
+/**
* This routine updates the priority related fields in the_thread
* control block to indicate the current priority is now new_priority.
*/
-
void _Thread_Set_priority(
Thread_Control *the_thread,
Priority_Control new_priority
);
-/*
- * _Thread_Suspend
- *
- * DESCRIPTION:
- *
+/**
* This routine updates the related suspend fields in the_thread
* control block to indicate the current nested level.
*/
-
void _Thread_Suspend(
Thread_Control *the_thread
);
-/*
- * _Thread_Resume
- *
- * DESCRIPTION:
- *
+/**
* This routine updates the related suspend fields in the_thread
* control block to indicate the current nested level. A force
* parameter of TRUE will force a resume and clear the suspend count.
*/
-
void _Thread_Resume(
Thread_Control *the_thread,
boolean force
);
-/*
- * _Thread_Evaluate_mode
- *
- * DESCRIPTION:
- *
+/**
* This routine evaluates the current scheduling information for the
* system and determines if a context switch is required. This
* is usually called after changing an execution mode such as preemptability
* for a thread.
*/
-
boolean _Thread_Evaluate_mode( void );
-/*
- * _Thread_Get
- *
- * NOTE: If we are not using static inlines, this must be a real
+#ifndef RTEMS_INLINES
+/**
+ * @note If we are not using static inlines, this must be a real
* subroutine call.
*/
-
-#ifndef RTEMS_INLINES
Thread_Control *_Thread_Get (
Objects_Id id,
Objects_Locations *location
);
#endif
-/*
- * _Thread_Idle_body
- *
- * DESCRIPTION:
- *
+#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE)
+/**
* This routine is the body of the system idle thread.
*/
-
-#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE)
Thread _Thread_Idle_body(
uint32_t ignored
);
#endif
-/*
- * rtems_iterate_over_all_tasks
- *
- * DESCRIPTION:
- *
- * This routine iterates over all threads regardless of API and
- * invokes the specified routine.
+/**
*/
-
typedef void (*rtems_per_thread_routine)( Thread_Control * );
+/**
+ * This routine iterates over all threads regardless of API and
+ * invokes the specified routine.
+ */
void rtems_iterate_over_all_threads(
rtems_per_thread_routine routine
);
@@ -788,5 +674,7 @@ void rtems_iterate_over_all_threads(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/threadmp.h b/cpukit/score/include/rtems/score/threadmp.h
index ad5efb7fb0..1a4f3087d4 100644
--- a/cpukit/score/include/rtems/score/threadmp.h
+++ b/cpukit/score/include/rtems/score/threadmp.h
@@ -1,9 +1,12 @@
-/* threadmp.h
+/**
+ * @file threadmp.h
*
* This include file contains the specification for all routines
* and data specific to the multiprocessing portion of the thread package.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,64 +19,63 @@
#ifndef __RTEMS_THREAD_MP_h
#define __RTEMS_THREAD_MP_h
+/**
+ * @defgroup ScoreThreadMP Thread Handler Multiprocessing Support
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
-/*
- * _Thread_MP_Handler_initialization
- *
- * DESCRIPTION:
+/** @brief _Thread_MP_Handler_initialization
*
* This routine initializes the multiprocessing portion of the Thread Handler.
*/
-
void _Thread_MP_Handler_initialization (
uint32_t maximum_proxies
);
-
-/*
- * _Thread_MP_Allocate_proxy
- *
- * DESCRIPTION:
+/** @brief _Thread_MP_Allocate_proxy
*
* This allocates a proxy control block from
* the inactive chain of free proxy control blocks.
*
- * NOTE: This function returns a thread control pointer
+ * @note This function returns a thread control pointer
* because proxies are substitutes for remote threads.
*/
-
Thread_Control *_Thread_MP_Allocate_proxy (
States_Control the_state
);
-/*
- * _Thread_MP_Find_proxy
- *
- * DESCRIPTION:
+/** @brief _Thread_MP_Find_proxy
*
* This function removes the proxy control block for the specified
* id from the active chain of proxy control blocks.
*/
-
Thread_Control *_Thread_MP_Find_proxy (
Objects_Id the_id
);
-/*
+/** @brief Pointer to MP Thread Control Block
+ *
* The following is used to determine when the multiprocessing receive
* thread is executing so that a proxy can be allocated instead of
* blocking the multiprocessing receive thread.
*/
-
SCORE_EXTERN Thread_Control *_Thread_MP_Receive;
-/*
- * The following chains are used to manage proxies.
+/* @brief Active Proxy Set
+ *
+ * The following chain is used to manage the active set proxies.
*/
-
SCORE_EXTERN Chain_Control _Thread_MP_Active_proxies;
+
+/** @brief Inactive Proxy Set
+ *
+ * The following chain is used to manage the inactive set of proxies.
+ */
SCORE_EXTERN Chain_Control _Thread_MP_Inactive_proxies;
#ifndef __RTEMS_APPLICATION__
@@ -84,5 +86,7 @@ SCORE_EXTERN Chain_Control _Thread_MP_Inactive_proxies;
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index cbbb85e345..83b2563b96 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -1,9 +1,12 @@
-/* threadq.h
+/**
+ * @file threadq.h
*
* This include file contains all the constants and structures associated
* with the manipulation of objects.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __THREAD_QUEUE_h
#define __THREAD_QUEUE_h
+/**
+ * @defgroup ScoreThreadQ Thread Queue Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -26,132 +36,87 @@ extern "C" {
#include <rtems/score/thread.h>
#include <rtems/score/watchdog.h>
-/*
+/**
* Constant for indefinite wait.
*/
-
#define THREAD_QUEUE_WAIT_FOREVER WATCHDOG_NO_TIMEOUT
-/*
+/**
* The following type defines the callout used when a remote task
* is extracted from a local thread queue.
*/
-
typedef void ( *Thread_queue_Flush_callout )(
Thread_Control *
);
-/*
- * The following type defines the callout used when a local task
- * is extracted from a remote thread queue (i.e. it's proxy must
- * extracted from the remote queue).
- */
-
-#if 0
-typedef void ( *Thread_queue_Extract_callout )(
- Thread_Control *
- );
-
-SCORE_EXTERN Thread_queue_Extract_callout
- _Thread_queue_Extract_table[ OBJECTS_CLASSES_LAST + 1 ];
-#endif
-
-/*
- * _Thread_queue_Dequeue
- *
- * DESCRIPTION:
+/** @brief Thread queue Dequeue
*
* This function returns a pointer to a thread waiting on
* the_thread_queue. The selection of this thread is based on
* the discipline of the_thread_queue. If no threads are waiting
* on the_thread_queue, then NULL is returned.
*/
-
Thread_Control *_Thread_queue_Dequeue(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_Enqueue
- *
- * DESCRIPTION:
+/** @brief Thread queue Enqueue
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout.
*/
-
void _Thread_queue_Enqueue(
Thread_queue_Control *the_thread_queue,
Watchdog_Interval timeout
);
-/*
- * _Thread_queue_Extract
- *
- * DESCRIPTION:
+/** @brief Thread queue Extract
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
*/
-
void _Thread_queue_Extract(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread
);
-/*
- * _Thread_queue_Extract_with_proxy
- *
- * DESCRIPTION:
+/** @brief Thread queue Extract with proxy
*
* This routine extracts the_thread from the_thread_queue
* and ensures that if there is a proxy for this task on
* another node, it is also dealt with.
*/
-
boolean _Thread_queue_Extract_with_proxy(
Thread_Control *the_thread
);
-/*
- * _Thread_queue_First
- *
- * DESCRIPTION:
+/** @brief Thread queue First
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The "first" thread is selected
* based on the discipline of the_thread_queue.
*/
-
Thread_Control *_Thread_queue_First(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_Flush
- *
- * DESCRIPTION:
+/** @brief Thread queue Flush
*
* This routine unblocks all threads blocked on the_thread_queue
* and cancels any associated timeouts.
*/
-
void _Thread_queue_Flush(
Thread_queue_Control *the_thread_queue,
Thread_queue_Flush_callout remote_extract_callout,
uint32_t status
);
-/*
- * _Thread_queue_Initialize
- *
- * DESCRIPTION:
+/** @brief Thread queue Initialize
*
* This routine initializes the_thread_queue based on the
* discipline indicated in attribute_set. The state set on
* threads which block on the_thread_queue is state.
*/
-
void _Thread_queue_Initialize(
Thread_queue_Control *the_thread_queue,
Thread_queue_Disciplines the_discipline,
@@ -159,126 +124,91 @@ void _Thread_queue_Initialize(
uint32_t timeout_status
);
-/*
- * _Thread_queue_Dequeue_priority
- *
- * DESCRIPTION:
+/** @brief Thread queue Dequeue priority
*
* This function returns a pointer to the highest priority
* thread waiting on the_thread_queue. If no threads are waiting
* on the_thread_queue, then NULL is returned.
*/
-
Thread_Control *_Thread_queue_Dequeue_priority(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_Enqueue_priority
- *
- * DESCRIPTION:
+/** @brief Thread queue Enqueue priority
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout using the
* priority discipline.
*/
-
void _Thread_queue_Enqueue_priority(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread,
Watchdog_Interval timeout
);
-/*
- * _Thread_queue_Extract_priority
- *
- * DESCRIPTION:
+/** @brief Thread queue Extract priority
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
*/
-
void _Thread_queue_Extract_priority(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread
);
-/*
- * _Thread_queue_First_priority
- *
- * DESCRIPTION:
+/** @brief Thread queue First priority
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The "first" thread is the highest
* priority thread waiting on the_thread_queue.
*/
-
Thread_Control *_Thread_queue_First_priority(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_Dequeue_FIFO
- *
- * DESCRIPTION:
+/** @brief Thread queue Dequeue FIFO
*
* This function returns a pointer to the thread which has
* been waiting the longest on the_thread_queue. If no
* threads are waiting on the_thread_queue, then NULL is returned.
*/
-
Thread_Control *_Thread_queue_Dequeue_fifo(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_Enqueue_FIFO
- *
- * DESCRIPTION:
+/** @brief Thread queue Enqueue FIFO
*
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout using the
* FIFO discipline.
*/
-
void _Thread_queue_Enqueue_fifo(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread,
Watchdog_Interval timeout
);
-/*
- * _Thread_queue_Extract_FIFO
- *
- * DESCRIPTION:
+/** @brief Thread queue Extract FIFO
*
* This routine removes the_thread from the_thread_queue
* and cancels any timeouts associated with this blocking.
*/
-
void _Thread_queue_Extract_fifo(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread
);
-/*
- * _Thread_queue_First_FIFO
- *
- * DESCRIPTION:
+/** @brief Thread queue First FIFO
*
* This function returns a pointer to the "first" thread
* on the_thread_queue. The first thread is the thread
* which has been waiting longest on the_thread_queue.
*/
-
Thread_Control *_Thread_queue_First_fifo(
Thread_queue_Control *the_thread_queue
);
-/*
- * _Thread_queue_timeout
- *
- * DESCRIPTION:
+/** @brief Thread queue timeout
*
* This routine is invoked when a task's request has not
* been satisfied after the timeout interval specified to
@@ -286,7 +216,6 @@ Thread_Control *_Thread_queue_First_fifo(
* its status code will be set in it's control block to indicate
* that a timeout has occurred.
*/
-
void _Thread_queue_Timeout (
Objects_Id id,
void *ignored
@@ -296,5 +225,7 @@ void _Thread_queue_Timeout (
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h
index 8966c8b06c..b938899293 100644
--- a/cpukit/score/include/rtems/score/tod.h
+++ b/cpukit/score/include/rtems/score/tod.h
@@ -1,9 +1,12 @@
-/* tod.h
+/**
+ * @file tod.h
*
* This include file contains all the constants and structures associated
* with the Time of Day Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __TIME_OF_DAY_h
#define __TIME_OF_DAY_h
+/**
+ * @defgroup ScoreTOD Time Of Day (TOD) Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -23,93 +33,142 @@ extern "C" {
#include <rtems/score/object.h>
#include <rtems/score/watchdog.h>
-/*
+/** @defgroup ScoreTODConstants TOD Constants
* The following constants are related to the time of day.
*/
+/**@{*/
+/**
+ * XXX
+ */
#define TOD_SECONDS_PER_MINUTE (uint32_t )60
+
+/**
+ * XXX
+ */
#define TOD_MINUTES_PER_HOUR (uint32_t )60
+
+/**
+ * XXX
+ */
#define TOD_MONTHS_PER_YEAR (uint32_t )12
+
+/**
+ * XXX
+ */
#define TOD_DAYS_PER_YEAR (uint32_t )365
+
+/**
+ * XXX
+ */
#define TOD_HOURS_PER_DAY (uint32_t )24
+
+/**
+ * XXX
+ */
#define TOD_SECONDS_PER_DAY (uint32_t ) (TOD_SECONDS_PER_MINUTE * \
TOD_MINUTES_PER_HOUR * \
TOD_HOURS_PER_DAY)
+
+/**
+ * XXX
+ */
#define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY)
+/**
+ * XXX
+ */
#define TOD_MILLISECONDS_PER_SECOND (uint32_t )1000
+
+/**
+ * XXX
+ */
#define TOD_MICROSECONDS_PER_SECOND (uint32_t )1000000
+
+/**
+ * XXX
+ */
#define TOD_NANOSECONDS_PER_SECOND (uint32_t )1000000000
+
+/**
+ * XXX
+ */
#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t )1000
-/*
+/**@}*/
+
+/** @brief RTEMS Epoch Year
+ *
* The following constant define the earliest year to which an
* time of day can be initialized. This is considered the
* epoch.
*/
-
#define TOD_BASE_YEAR 1988
-/*
+/**
* The following record defines the time of control block. This
* control block is used to maintain the current time of day.
+ *
+ * @note This is an RTEID style time/date.
*/
-
-typedef struct { /* RTEID style time/date */
- uint32_t year; /* year, A.D. */
- uint32_t month; /* month, 1 -> 12 */
- uint32_t day; /* day, 1 -> 31 */
- uint32_t hour; /* hour, 0 -> 23 */
- uint32_t minute; /* minute, 0 -> 59 */
- uint32_t second; /* second, 0 -> 59 */
- uint32_t ticks; /* elapsed ticks between secs */
+typedef struct {
+ /** This field is the year, A.D. */
+ uint32_t year;
+ /** This field is the month, 1 -> 12 */
+ uint32_t month;
+ /** This field is the day, 1 -> 31 */
+ uint32_t day;
+ /** This field is the hour, 0 -> 23 */
+ uint32_t hour;
+ /** This field is the minute, 0 -> 59 */
+ uint32_t minute;
+ /** This field is the second, 0 -> 59 */
+ uint32_t second;
+ /** This field is the elapsed ticks between secs */
+ uint32_t ticks;
} TOD_Control;
-/*
- * The following is TRUE if the application has set the current
+/** @brief Is the Time Of Day Set
+ *
+ * This is TRUE if the application has set the current
* time of day, and FALSE otherwise.
*/
-
SCORE_EXTERN boolean _TOD_Is_set;
-/*
+/** @brief Current Time of Day
* The following contains the current time of day.
*/
-
SCORE_EXTERN TOD_Control _TOD_Current;
-/*
+/** @brief Seconds Since RTEMS Epoch
* The following contains the number of seconds from 00:00:00
* January 1, TOD_BASE_YEAR until the current time of day.
*/
-
SCORE_EXTERN Watchdog_Interval _TOD_Seconds_since_epoch;
-/*
+/** @brief Microseconds per Clock Tick
+ *
* The following contains the number of microseconds per tick.
*/
-
SCORE_EXTERN uint32_t _TOD_Microseconds_per_tick;
-/*
- * The following contains the number of clock ticks per second.
+/** @brief Clock Ticks per Second
*
- * NOTE:
+ * The following contains the number of clock ticks per second.
*
- * If one second is NOT evenly divisible by the number of microseconds
+ * @note If one second is NOT evenly divisible by the number of microseconds
* per clock tick, this value will contain only the integer portion
* of the division. This means that the interval between clock ticks
* can be a source of error in the current time of day.
*/
-
SCORE_EXTERN uint32_t _TOD_Ticks_per_second;
-/*
+/** @brief Watchdog Set Managed by Seconds
+ *
* This is the control structure for the watchdog timer which
* fires to service the seconds chain.
*/
-
SCORE_EXTERN Watchdog_Control _TOD_Seconds_watchdog;
#ifdef SCORE_INIT
@@ -120,7 +179,6 @@ SCORE_EXTERN Watchdog_Control _TOD_Seconds_watchdog;
* The second dimension should range from 1 to 12 for January to
* February, respectively.
*/
-
const uint32_t _TOD_Days_per_month[ 2 ][ 13 ] = {
{ 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 },
{ 0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
@@ -131,7 +189,6 @@ const uint32_t _TOD_Days_per_month[ 2 ][ 13 ] = {
* up to the month indicated by the index of the second dimension.
* The first dimension should be 1 for leap years, and 0 otherwise.
*/
-
const uint16_t _TOD_Days_to_date[2][13] = {
{ 0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 },
{ 0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335 }
@@ -143,122 +200,95 @@ const uint16_t _TOD_Days_to_date[2][13] = {
* years, and the number of years since the beginning of a leap
* year otherwise.
*/
-
const uint16_t _TOD_Days_since_last_leap_year[4] = { 0, 366, 731, 1096 };
#else
+/** @brief
+ *
+ */
extern const uint16_t _TOD_Days_to_date[2][13]; /* Julian days */
+
+/** @brief
+ *
+ */
extern const uint16_t _TOD_Days_since_last_leap_year[4];
+
+/** @brief
+ *
+ */
extern const uint32_t _TOD_Days_per_month[2][13];
#endif
-/*
- * _TOD_Handler_initialization
- *
- * DESCRIPTION:
+/** @brief _TOD_Handler_initialization
*
* This routine performs the initialization necessary for this handler.
*/
-
void _TOD_Handler_initialization(
uint32_t microseconds_per_tick
);
-/*
- * _TOD_Set
- *
- * DESCRIPTION:
+/** @brief _TOD_Set
*
* This routine sets the current time of day to THE_TOD and
* the equivalent SECONDS_SINCE_EPOCH.
*/
-
void _TOD_Set(
TOD_Control *the_tod,
Watchdog_Interval seconds_since_epoch
);
-/*
- * _TOD_Validate
- *
- * DESCRIPTION:
+/** @brief _TOD_Validate
*
* This function returns TRUE if THE_TOD contains
* a valid time of day, and FALSE otherwise.
*/
-
boolean _TOD_Validate(
TOD_Control *the_tod
);
-/*
- * _TOD_To_seconds
- *
- * DESCRIPTION:
+/** @brief _TOD_To_seconds
*
* This function returns the number seconds between the epoch and THE_TOD.
*/
-
Watchdog_Interval _TOD_To_seconds(
TOD_Control *the_tod
);
-/*
- * _TOD_Tickle
- *
- * DESCRIPTION:
+/** @brief _TOD_Tickle
*
* This routine is scheduled as a watchdog function and is invoked at
* each second boundary. It updates the current time of day to indicate
* that a second has passed and processes the seconds watchdog chain.
*/
-
void _TOD_Tickle(
Objects_Id id,
void *ignored
);
-/*
- * TOD_MILLISECONDS_TO_MICROSECONDS
- *
- * DESCRIPTION:
+/** @brief TOD_MILLISECONDS_TO_MICROSECONDS
*
* This routine converts an interval expressed in milliseconds to microseconds.
*
- * NOTE:
- *
- * This must be a macro so it can be used in "static" tables.
+ * @note This must be a macro so it can be used in "static" tables.
*/
-
#define TOD_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000)
-/*
- * TOD_MICROSECONDS_TO_TICKS
- *
- * DESCRIPTION:
+/** @brief TOD_MICROSECONDS_TO_TICKS
*
* This routine converts an interval expressed in microseconds to ticks.
*
- * NOTE:
- *
- * This must be a macro so it can be used in "static" tables.
+ * @note This must be a macro so it can be used in "static" tables.
*/
-
#define TOD_MICROSECONDS_TO_TICKS(_us) \
((_us) / _TOD_Microseconds_per_tick)
-/*
- * TOD_MILLISECONDS_TO_TICKS
- *
- * DESCRIPTION:
+/** @brief TOD_MILLISECONDS_TO_TICKS
*
* This routine converts an interval expressed in milliseconds to ticks.
*
- * NOTE:
- *
- * This must be a macro so it can be used in "static" tables.
+ * @note This must be a macro so it can be used in "static" tables.
*/
#define TOD_MILLISECONDS_TO_TICKS(_ms) \
@@ -272,5 +302,7 @@ void _TOD_Tickle(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/tqdata.h b/cpukit/score/include/rtems/score/tqdata.h
index 4945c74e3f..f7ba664e17 100644
--- a/cpukit/score/include/rtems/score/tqdata.h
+++ b/cpukit/score/include/rtems/score/tqdata.h
@@ -1,9 +1,12 @@
-/* tqdata.h
+/**
+ * @file tqdata.h
*
* This include file contains all the constants and structures
* needed to declare a thread queue.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,6 +19,13 @@
#ifndef __THREAD_QUEUE_DATA_h
#define __THREAD_QUEUE_DATA_h
+/**
+ * @defgroup ScoreThreadQData Thread Queue Handler Data Definition
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -85,5 +95,7 @@ typedef struct {
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h
index c0f5a4b0a8..8215eb5f45 100644
--- a/cpukit/score/include/rtems/score/userext.h
+++ b/cpukit/score/include/rtems/score/userext.h
@@ -1,10 +1,13 @@
-/* userext.h
+/**
+ * @file userext.h
*
* This include file contains all information about user extensions. This
* Handler provides mechanisms which can be used to initialize and manipulate
* all user extensions.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,13 @@
#ifndef __USER_EXTENSIONS_h
#define __USER_EXTENSIONS_h
+/**
+ * @defgroup ScoreUserExt User Extension Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -25,193 +35,210 @@ extern "C" {
#include <rtems/score/chain.h>
#include <rtems/score/thread.h>
-/*
+/** @defgroup ScoreUserExtStruct User Extension Handler Structures
+ *
* The following records defines the User Extension Table.
* This table defines the application dependent routines which
* are invoked at critical points in the life of each thread and
* the system as a whole.
*/
+/*@{*/
+/**
+ * XXX
+ */
typedef void User_extensions_routine;
+/**
+ * XXX
+ */
typedef boolean ( *User_extensions_thread_create_extension )(
Thread_Control *,
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_delete_extension )(
Thread_Control *,
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_start_extension )(
Thread_Control *,
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_restart_extension )(
Thread_Control *,
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_switch_extension )(
Thread_Control *,
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine (
*User_extensions_thread_post_switch_extension )(
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_begin_extension )(
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )(
Thread_Control *
);
+/**
+ * XXX
+ */
typedef User_extensions_routine ( *User_extensions_fatal_extension )(
Internal_errors_Source /* the_source */,
boolean /* is_internal */,
uint32_t /* the_error */
);
-
+/**
+ * XXX
+ */
typedef struct {
+ /** This field is XXX */
User_extensions_thread_create_extension thread_create;
+ /** This field is XXX */
User_extensions_thread_start_extension thread_start;
+ /** This field is XXX */
User_extensions_thread_restart_extension thread_restart;
+ /** This field is XXX */
User_extensions_thread_delete_extension thread_delete;
+ /** This field is XXX */
User_extensions_thread_switch_extension thread_switch;
+ /** This field is XXX */
User_extensions_thread_begin_extension thread_begin;
+ /** This field is XXX */
User_extensions_thread_exitted_extension thread_exitted;
+ /** This field is XXX */
User_extensions_fatal_extension fatal;
} User_extensions_Table;
-/*
- * The following is used to manage the list of switch handlers.
- */
+/*@}*/
+/**
+ * This is used to manage the list of switch handlers.
+ */
typedef struct {
+ /** This field is XXX */
Chain_Node Node;
+ /** This field is XXX */
User_extensions_thread_switch_extension thread_switch;
} User_extensions_Switch_control;
-/*
- * The following is used to manage each user extension set.
+/**
+ * This is used to manage each user extension set.
* The switch control is part of the extensions control even
* if not used due to the extension not having a switch
* handler.
*/
-
typedef struct {
+ /** This field is XXX */
Chain_Node Node;
+ /** This field is XXX */
User_extensions_Switch_control Switch;
+ /** This field is XXX */
User_extensions_Table Callouts;
} User_extensions_Control;
-/*
- * The following is used to manage the list of active extensions.
+/**
+ * This is used to manage the list of active extensions.
*/
-
SCORE_EXTERN Chain_Control _User_extensions_List;
-/*
- * The following is used to manage a chain of user extension task
+/**
+ * This is used to manage a chain of user extension task
* switch nodes.
*/
-
SCORE_EXTERN Chain_Control _User_extensions_Switches_list;
-/*
- * _User_extensions_Thread_create
- *
- * DESCRIPTION:
+/** @brief User extensions Thread create
*
* This routine is used to invoke the user extension for
* the thread creation operate.
*/
-
boolean _User_extensions_Thread_create (
Thread_Control *the_thread
);
-/*
- * _User_extensions_Thread_delete
- *
- * DESCRIPTION:
+/** @brief User extensions Thread delete
*
* This routine is used to invoke the user extension for
* the thread deletion operation.
*/
-
void _User_extensions_Thread_delete (
Thread_Control *the_thread
);
-/*
- * _User_extensions_Thread_start
- *
- * DESCRIPTION:
+/** @brief User extensions Thread start
*
* This routine is used to invoke the user extension for
* the thread start operation.
*/
-
void _User_extensions_Thread_start (
Thread_Control *the_thread
);
-/*
- * _User_extensions_Thread_restart
- *
- * DESCRIPTION:
+/** @brief User extensions Thread restart
*
* This routine is used to invoke the user extension for
* the thread restart operation.
*/
-
void _User_extensions_Thread_restart (
Thread_Control *the_thread
);
-/*
- * _User_extensions_Thread_begin
- *
- * DESCRIPTION:
+/** @brief User extensions Thread begin
*
* This routine is used to invoke the user extension which
* is invoked when a thread begins.
*/
-
void _User_extensions_Thread_begin (
Thread_Control *executing
);
-/*
- * _User_extensions_Thread_exitted
- *
- * DESCRIPTION:
+/** @brief User extensions Thread exitted
*
* This routine is used to invoke the user extension which
* is invoked when a thread exits.
*/
-
void _User_extensions_Thread_exitted (
Thread_Control *executing
);
-/*
- * _User_extensions_Fatal
- *
- * DESCRIPTION:
+/** @brief User extensions Fatal
*
* This routine is used to invoke the user extension invoked
* when a fatal error occurs.
*/
-
void _User_extensions_Fatal (
Internal_errors_Source the_source,
boolean is_internal,
@@ -226,5 +253,7 @@ void _User_extensions_Fatal (
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h
index cb70d13120..91d2a166c0 100644
--- a/cpukit/score/include/rtems/score/watchdog.h
+++ b/cpukit/score/include/rtems/score/watchdog.h
@@ -1,10 +1,13 @@
-/* watchdog.h
+/**
+ * @file watchdog.h
*
* This include file contains all the constants and structures associated
* with watchdog timers. This Handler provides mechanisms which can be
- * used to initialize and manipulate watchdog timers.
- *
- * COPYRIGHT (c) 1989-1999.
+ * used to initialize and manipulate watchdog timers.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,67 +20,94 @@
#ifndef __WATCHDOG_h
#define __WATCHDOG_h
+/**
+ * @defgroup ScoreWatchdog Watchdog Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
#include <rtems/score/object.h>
-/*
+/** @brief Maximum Interval Length
+ *
* The following type defines the control block used to manage
* intervals.
*/
-
#define WATCHDOG_MAXIMUM_INTERVAL ((Watchdog_Interval) 0xffffffff)
+/** @brief Watchdog Interval Type
+ *
+ * This type is used to specify the length of intervals.
+ */
typedef uint32_t Watchdog_Interval;
-/*
- * The following types define a pointer to a watchdog service routine.
+/** @brief Watchdog Service Routine Return Type
+ *
+ * This type defines the return type from a Watchdog Service Routine.
*/
-
typedef void Watchdog_Service_routine;
+/** @brief Watchdog Service Routine Pointer Type
+ *
+ * This type define a pointer to a watchdog service routine.
+ */
typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )(
Objects_Id,
void *
);
-/*
- * Constant for indefinite wait. (actually an illegal interval)
+/** @brief No timeout constant
+ *
+ * This is the constant for indefinite wait. It is actually an
+ * illegal interval.
*/
-
#define WATCHDOG_NO_TIMEOUT 0
-/*
- * The following enumerated type lists the states in which a
+/** @brief Watchdog States Type
+ *
+ * This enumerated type is the set of the states in which a
* watchdog timer may be at any given time.
*/
typedef enum {
- WATCHDOG_INACTIVE, /* off all chains */
- WATCHDOG_BEING_INSERTED, /* off all chains, searching for insertion point */
- WATCHDOG_ACTIVE, /* on chain, allowed to fire */
- WATCHDOG_REMOVE_IT /* on chain, remove without firing if expires */
+ /** This is the state when the watchdog is off all chains */
+ WATCHDOG_INACTIVE,
+ /** This is the state when the watchdog is off all chains, but we are
+ * currently searching for the insertion point.
+ */
+ WATCHDOG_BEING_INSERTED,
+ /** This is the state when the watchdog is on a chain, and allowed to fire. */
+ WATCHDOG_ACTIVE,
+ /** This is the state when the watchdog is on a chain, but we should
+ * remove without firing if it expires.
+ */
+ WATCHDOG_REMOVE_IT
} Watchdog_States;
-/*
+/** @brief Watchdog Adjustment Directions Type
+ *
* The following enumerated type details the manner in which
- * a watchdog chain may be adjusted by the Watchdog_Adjust
+ * a watchdog chain may be adjusted by the @ref _Watchdog_Adjust
* routine. The direction indicates a movement FORWARD
* or BACKWARD in time.
*/
-
typedef enum {
- WATCHDOG_FORWARD, /* adjust delta value forward */
- WATCHDOG_BACKWARD /* adjust delta value backward */
+ /** adjust delta value forward */
+ WATCHDOG_FORWARD,
+ /** adjust delta value backward */
+ WATCHDOG_BACKWARD
} Watchdog_Adjust_directions;
-/*
+/** @brief Watchdog Control Structure
+ *
* The following record defines the control block used
* to manage each watchdog timer.
*/
-
typedef struct {
Chain_Node Node;
Watchdog_States state;
@@ -90,93 +120,93 @@ typedef struct {
void *user_data;
} Watchdog_Control;
-/*
- * The following are used for synchronization purposes
+/** @brief Watchdog Synchronization Level
+ *
+ * This used for synchronization purposes
* during an insert on a watchdog delta chain.
*/
-
SCORE_EXTERN volatile uint32_t _Watchdog_Sync_level;
+
+/** @brief Watchdog Synchronization Count
+ *
+ * This used for synchronization purposes
+ * during an insert on a watchdog delta chain.
+ */
SCORE_EXTERN volatile uint32_t _Watchdog_Sync_count;
-/*
- * The following contains the number of ticks since the
- * system was booted.
+/** @brief Ticks Since System Boot
+ *
+ * This contains the number of ticks since the system was booted.
*/
SCORE_EXTERN volatile Watchdog_Interval _Watchdog_Ticks_since_boot;
-/*
- * The following defines the watchdog chains which are managed
- * on ticks and second boundaries.
+/** @brief Per Ticks Watchdog List
+ *
+ * This is the watchdog chain which is managed at ticks.
*/
-
SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain;
-SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain;
-/*
- * _Watchdog_Handler_initialization
+/** @brief Per Seconds Watchdog List
*
- * DESCRIPTION:
+ * This is the watchdog chain which is managed at second boundaries.
+ */
+SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain;
+
+/** @brief Watchdog Handler Initialization
*
* This routine initializes the watchdog handler. The watchdog
* synchronization flag is initialized and the watchdog chains are
* initialized and emptied.
*/
-
void _Watchdog_Handler_initialization( void );
-/*
- * _Watchdog_Remove
- *
- * DESCRIPTION:
+/** @brief Remove Watchdog from List
*
- * This routine removes THE_WATCHDOG from the watchdog chain on which
- * it resides and returns the state THE_WATCHDOG timer was in.
+ * This routine removes @a the_watchdog from the watchdog chain on which
+ * it resides and returns the state @a the_watchdog timer was in.
+ *
+ * @param the_watchdog (in) will be removed
+ * @return the state in which @a the_watchdog was in when removed
*/
-
Watchdog_States _Watchdog_Remove (
Watchdog_Control *the_watchdog
);
-/*
- * _Watchdog_Adjust
+/** @brief Watchdog Adjust
*
- * DESCRIPTION:
+ * This routine adjusts the @a header watchdog chain in the forward
+ * or backward @a direction for @a units ticks.
*
- * This routine adjusts the HEADER watchdog chain in the forward
- * or backward DIRECTION for UNITS ticks.
+ * @param header (in) is the watchdog chain to adjust
+ * @param direction (in) is the direction to adjust @a header
+ * @param units (in) is the number of units to adjust @a header
*/
-
void _Watchdog_Adjust (
Chain_Control *header,
Watchdog_Adjust_directions direction,
Watchdog_Interval units
);
-/*
- * _Watchdog_Insert
- *
- * DESCRIPTION:
+/** @brief Watchdog Insert
*
- * This routine inserts THE_WATCHDOG into the HEADER watchdog chain
- * for a time of UNITS. The INSERT_MODE indicates whether
- * THE_WATCHDOG is to be activated automatically or later, explicitly
- * by the caller.
+ * This routine inserts @a the_watchdog into the @a header watchdog chain
+ * for a time of @a units.
*
+ * @param header (in) is @a the_watchdog list to insert @a the_watchdog on
+ * @param the_watchdog (in) is the watchdog to insert
*/
-
void _Watchdog_Insert (
Chain_Control *header,
Watchdog_Control *the_watchdog
);
-/*
- * _Watchdog_Tickle
- *
- * DESCRIPTION:
+/** @brief Watchdog Tickle
*
* This routine is invoked at appropriate intervals to update
- * the HEADER watchdog chain.
+ * the @a header watchdog chain.
+ *
+ * @param header (in) is the watchdog chain to tickle
*/
void _Watchdog_Tickle (
@@ -191,5 +221,7 @@ void _Watchdog_Tickle (
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h
index aff79c78d5..dd3869df05 100644
--- a/cpukit/score/include/rtems/score/wkspace.h
+++ b/cpukit/score/include/rtems/score/wkspace.h
@@ -1,10 +1,13 @@
-/* wkspace.h
+/**
+ * @file wkspace.h
*
* This include file contains information related to the
* RAM Workspace. This Handler provides mechanisms which can be used to
* define, initialize and manipulate the workspace.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,13 @@
#ifndef __WORKSPACE_h
#define __WORKSPACE_h
+/**
+ * @defgroup ScoreWorkspace Workspace Handler
+ *
+ * This group contains functionality which XXX
+ */
+/**@{*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -24,36 +34,35 @@ extern "C" {
#include <rtems/score/heap.h>
#include <rtems/score/interr.h>
-/*
- * The following is used to manage the Workspace.
+/** @brief Executive Workspace Control
*
+ * The is the heap control structure that used to manage the
+ * RTEMS Executive Workspace.
*/
-
SCORE_EXTERN Heap_Control _Workspace_Area; /* executive heap header */
-/*
- * _Workspace_Handler_initialization
- *
- * DESCRIPTION:
+/** @brief Workspace Handler Initialization
*
* This routine performs the initialization necessary for this handler.
+ *
+ * @param starting_address (in) is the base address of the RTEMS Executive
+ * Workspace
+ * @param size (in) is the number of bytes in the RTEMS Executive Workspace
*/
-
void _Workspace_Handler_initialization(
void *starting_address,
uint32_t size
);
-/*
- * _Workspace_Allocate_or_fatal_error
+/** @brief Workspace Allocate or Fail with Fatal Error
*
- * DESCRIPTION:
- *
- * This routine returns the address of a block of memory of size
+ * This routine returns the address of a block of memory of @a size
* bytes. If a block of the appropriate size cannot be allocated
* from the workspace, then the internal error handler is invoked.
+ *
+ * @param size (in) is the desired number of bytes to allocate
+ * @return If successful, the starting address of the allocated memory
*/
-
void *_Workspace_Allocate_or_fatal_error(
uint32_t size
);
@@ -66,5 +75,7 @@ void *_Workspace_Allocate_or_fatal_error(
}
#endif
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/include/rtems/seterr.h b/cpukit/score/include/rtems/seterr.h
index d45345ba6d..621ee5932e 100644
--- a/cpukit/score/include/rtems/seterr.h
+++ b/cpukit/score/include/rtems/seterr.h
@@ -1,5 +1,12 @@
+/**
+ * @file seterr.h
+ *
+ * This file contains macros and definitions which ease the burden
+ * of consistently setting errno and returning -1.
+ */
+
/*
- * COPYRIGHT (c) 1989-1999.
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
diff --git a/cpukit/score/include/rtems/system.h b/cpukit/score/include/rtems/system.h
index 90501dd3d3..e441f8890d 100644
--- a/cpukit/score/include/rtems/system.h
+++ b/cpukit/score/include/rtems/system.h
@@ -1,10 +1,13 @@
-/* system.h
+/**
+ * @file system.h
*
* This include file contains information that is included in every
* function in the executive. This must be the first include file
* included in all internal RTEMS files.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -168,7 +171,7 @@ SCORE_EXTERN rtems_cpu_table _CPU_Table; /* CPU dependent info */
/*
* Macros to access CPU Table fields required by ALL ports.
*
- * NOTE: Similar macros to access port specific fields in in the
+ * @note Similar macros to access port specific fields in in the
* appropriate cpu.h file.
*/
diff --git a/cpukit/score/inline/rtems/score/address.inl b/cpukit/score/inline/rtems/score/address.inl
index 28fa7f5c77..7f1f298ae4 100644
--- a/cpukit/score/inline/rtems/score/address.inl
+++ b/cpukit/score/inline/rtems/score/address.inl
@@ -1,9 +1,12 @@
-/* inline/address.inl
+/**
+ * @file address.inl
*
* This include file contains the bodies of the routines
* about addresses which are inlined.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __INLINE_ADDRESSES_inl
#define __INLINE_ADDRESSES_inl
-/*PAGE
- *
- * _Addresses_Add_offset
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreAddress
+ * @{
+ */
+
+/**
* This function is used to add an offset to a base address.
* It returns the resulting address. This address is typically
* converted to an access type before being used further.
@@ -35,12 +38,7 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Add_offset (
return (void *)((char *)base + offset);
}
-/*PAGE
- *
- * _Addresses_Subtract_offset
- *
- * DESCRIPTION:
- *
+/**
* This function is used to subtract an offset from a base
* address. It returns the resulting address. This address is
* typically converted to an access type before being used further.
@@ -54,16 +52,11 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Subtract_offset (
return (void *)((char *)base - offset);
}
-/*PAGE
- *
- * _Addresses_Subtract
- *
- * DESCRIPTION:
- *
+/**
* This function is used to subtract two addresses. It returns the
* resulting offset.
*
- * NOTE: The cast of an address to an uint32_t makes this code
+ * @note The cast of an address to an uint32_t makes this code
* dependent on an addresses being thirty two bits.
*/
@@ -75,12 +68,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Addresses_Subtract (
return ((char *) left - (char *) right);
}
-/*PAGE
- *
- * _Addresses_Is_aligned
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the given address is correctly
* aligned for this processor and FALSE otherwise. Proper alignment
* is based on correctness and efficiency.
@@ -99,12 +87,7 @@ RTEMS_INLINE_ROUTINE boolean _Addresses_Is_aligned (
#endif
}
-/*PAGE
- *
- * _Addresses_Is_in_range
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the given address is within the
* memory range specified and FALSE otherwise. base is the address
* of the first byte in the memory range and limit is the address
@@ -121,5 +104,7 @@ RTEMS_INLINE_ROUTINE boolean _Addresses_Is_in_range (
return ( address >= base && address <= limit );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/chain.inl b/cpukit/score/inline/rtems/score/chain.inl
index 8f9c68389d..a21841f413 100644
--- a/cpukit/score/inline/rtems/score/chain.inl
+++ b/cpukit/score/inline/rtems/score/chain.inl
@@ -1,13 +1,16 @@
-/* inline/chain.inl
+/**
+ * @file chain.inl
*
* This include file contains the bodies of the routines which are
* associated with doubly linked chains and inlined.
*
- * NOTE: The routines in this file are ordered from simple
+ * @note The routines in this file are ordered from simple
* to complex. No other Chain Handler routine is referenced
* unless it has already been defined.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -20,16 +23,15 @@
#ifndef __INLINE_CHAIN_inl
#define __INLINE_CHAIN_inl
-/*PAGE
- *
- * _Chain_Are_nodes_equal
- *
- * DESCRIPTION:
- *
- * This function returns TRUE if LEFT and RIGHT are equal,
- * and FALSE otherwise.
+/**
+ * @addtogroup ScoreChain
+ * @{
*/
+/**
+ * This function returns TRUE if \a left and \a right are equal,
+ * and FALSE otherwise.
+ */
RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal(
Chain_Node *left,
Chain_Node *right
@@ -38,28 +40,16 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal(
return left == right;
}
-/*PAGE
- *
- * _Chain_Is_null
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_chain is NULL and FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_null(
Chain_Control *the_chain
)
{
return ( the_chain == NULL );
}
-
-/*PAGE
- *
- * _Chain_Is_null_node
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_node is NULL and FALSE otherwise.
*/
@@ -70,15 +60,9 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node(
return ( the_node == NULL );
}
-/*PAGE
- *
- * _Chain_Head
- *
- * DESCRIPTION:
- *
+/**
* This function returns a pointer to the first node on the chain.
*/
-
RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head(
Chain_Control *the_chain
)
@@ -86,15 +70,9 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head(
return (Chain_Node *) the_chain;
}
-/*PAGE
- *
- * _Chain_Tail
- *
- * DESCRIPTION:
- *
+/**
* This function returns a pointer to the last node on the chain.
*/
-
RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail(
Chain_Control *the_chain
)
@@ -102,16 +80,10 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail(
return (Chain_Node *) &the_chain->permanent_null;
}
-/*PAGE
- *
- * _Chain_Is_empty
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if there a no nodes on the_chain and
* FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty(
Chain_Control *the_chain
)
@@ -119,16 +91,10 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty(
return ( the_chain->first == _Chain_Tail( the_chain ) );
}
-/*PAGE
- *
- * _Chain_Is_first
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_node is the first node on a chain and
* FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_first(
Chain_Node *the_node
)
@@ -136,16 +102,10 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_first(
return ( the_node->previous == NULL );
}
-/*PAGE
- *
- * _Chain_Is_last
- *
- * DESCRIPTION:
- *
- * This function returns TRUE if the_node is the last node on a chain and
+/**
+ * This function returns TRUE if \a the_node is the last node on a chain and
* FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_last(
Chain_Node *the_node
)
@@ -153,13 +113,8 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_last(
return ( the_node->next == NULL );
}
-/*PAGE
- *
- * _Chain_Has_only_one_node
- *
- * DESCRIPTION:
- *
- * This function returns TRUE if there is only one node on the_chain and
+/**
+ * This function returns TRUE if there is only one node on \a the_chain and
* FALSE otherwise.
*/
@@ -170,16 +125,10 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node(
return ( the_chain->first == the_chain->last );
}
-/*PAGE
- *
- * _Chain_Is_head
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_node is the head of the_chain and
* FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_head(
Chain_Control *the_chain,
Chain_Node *the_node
@@ -188,16 +137,10 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_head(
return ( the_node == _Chain_Head( the_chain ) );
}
-/*PAGE
- *
- * _Chain_Is_tail
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_node is the tail of the_chain and
* FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail(
Chain_Control *the_chain,
Chain_Node *the_node
@@ -206,12 +149,7 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail(
return ( the_node == _Chain_Tail( the_chain ) );
}
-/*PAGE
- *
- * Chain_Initialize_empty
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the specified chain to contain zero nodes.
*/
@@ -224,17 +162,11 @@ RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty(
the_chain->last = _Chain_Head( the_chain );
}
-/*PAGE
- *
- * _Chain_Extract_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This routine extracts the_node from the chain on which it resides.
* It does NOT disable interrupts to insure the atomicity of the
* extract operation.
*/
-
RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected(
Chain_Node *the_node
)
@@ -248,17 +180,11 @@ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected(
previous->next = next;
}
-/*PAGE
- *
- * _Chain_Get_first_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This function removes the first node from the_chain and returns
* a pointer to that node. It does NOT disable interrupts to insure
* the atomicity of the get operation.
*/
-
RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected(
Chain_Control *the_chain
)
@@ -274,18 +200,12 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected(
return return_node;
}
-/*PAGE
- *
- * Chain_Get_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This function removes the first node from the_chain and returns
* a pointer to that node. If the_chain is empty, then NULL is returned.
* It does NOT disable interrupts to insure the atomicity of the
* get operation.
*/
-
RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected(
Chain_Control *the_chain
)
@@ -296,12 +216,7 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected(
return NULL;
}
-/*PAGE
- *
- * _Chain_Insert_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This routine inserts the_node on a chain immediately following
* after_node. It does NOT disable interrupts to insure the atomicity
* of the extract operation.
@@ -321,17 +236,11 @@ RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected(
before_node->previous = the_node;
}
-/*PAGE
- *
- * _Chain_Append_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This routine appends the_node onto the end of the_chain.
* It does NOT disable interrupts to insure the atomicity of the
* append operation.
*/
-
RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected(
Chain_Control *the_chain,
Chain_Node *the_node
@@ -346,37 +255,24 @@ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected(
the_node->previous = old_last_node;
}
-/*PAGE
- *
- * _Chain_Prepend_unprotected
- *
- * DESCRIPTION:
- *
+/**
* This routine prepends the_node onto the front of the_chain.
* It does NOT disable interrupts to insure the atomicity of the
* prepend operation.
*/
-
RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected(
Chain_Control *the_chain,
Chain_Node *the_node
)
{
_Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node );
-
}
-/*PAGE
- *
- * _Chain_Prepend
- *
- * DESCRIPTION:
- *
+/**
* This routine prepends the_node onto the front of the_chain.
* It disables interrupts to insure the atomicity of the
* prepend operation.
*/
-
RTEMS_INLINE_ROUTINE void _Chain_Prepend(
Chain_Control *the_chain,
Chain_Node *the_node
@@ -385,5 +281,7 @@ RTEMS_INLINE_ROUTINE void _Chain_Prepend(
_Chain_Insert( _Chain_Head( the_chain ), the_node );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/coremsg.inl b/cpukit/score/inline/rtems/score/coremsg.inl
index 7d152aec6b..56dea73b6d 100644
--- a/cpukit/score/inline/rtems/score/coremsg.inl
+++ b/cpukit/score/inline/rtems/score/coremsg.inl
@@ -1,9 +1,12 @@
-/* coremsg.inl
+/**
+ * @file coremsg.inl
*
* This include file contains the static inline implementation of all
* inlined routines in the Core Message Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,14 +19,14 @@
#ifndef __CORE_MESSAGE_QUEUE_inl
#define __CORE_MESSAGE_QUEUE_inl
+/**
+ * @addtogroup ScoreMessageQueue
+ * @{
+ */
+
#include <string.h> /* needed for memcpy */
-/*PAGE
- *
- * _CORE_message_queue_Send
- *
- * DESCRIPTION:
- *
+/**
* This routine sends a message to the end of the specified message queue.
*/
@@ -53,12 +56,7 @@ RTEMS_INLINE_ROUTINE CORE_message_queue_Status _CORE_message_queue_Send(
);
}
-/*PAGE
- *
- * _CORE_message_queue_Urgent
- *
- * DESCRIPTION:
- *
+/**
* This routine sends a message to the front of the specified message queue.
*/
@@ -88,12 +86,7 @@ RTEMS_INLINE_ROUTINE CORE_message_queue_Status _CORE_message_queue_Urgent(
);
}
-/*PAGE
- *
- * _CORE_message_queue_Copy_buffer
- *
- * DESCRIPTION:
- *
+/**
* This routine copies the contents of the source message buffer
* to the destination message buffer.
*/
@@ -107,12 +100,7 @@ RTEMS_INLINE_ROUTINE void _CORE_message_queue_Copy_buffer (
memcpy(destination, source, size);
}
-/*PAGE
- *
- * _CORE_message_queue_Allocate_message_buffer
- *
- * DESCRIPTION:
- *
+/**
* This function allocates a message buffer from the inactive
* message buffer chain.
*/
@@ -126,12 +114,7 @@ _CORE_message_queue_Allocate_message_buffer (
_Chain_Get( &the_message_queue->Inactive_messages );
}
-/*PAGE
- *
- * _CORE_message_queue_Free_message_buffer
- *
- * DESCRIPTION:
- *
+/**
* This routine frees a message buffer to the inactive
* message buffer chain.
*/
@@ -144,12 +127,7 @@ RTEMS_INLINE_ROUTINE void _CORE_message_queue_Free_message_buffer (
_Chain_Append( &the_message_queue->Inactive_messages, &the_message->Node );
}
-/*PAGE
- *
- * _CORE_message_queue_Get_pending_message
- *
- * DESCRIPTION:
- *
+/**
* This function removes the first message from the_message_queue
* and returns a pointer to it.
*/
@@ -163,12 +141,7 @@ RTEMS_INLINE_ROUTINE
_Chain_Get_unprotected( &the_message_queue->Pending_messages );
}
-/*PAGE
- *
- * _CORE_message_queue_Is_priority
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the priority attribute is
* enabled in the attribute_set and FALSE otherwise.
*/
@@ -180,12 +153,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_message_queue_Is_priority(
return (the_attribute->discipline == CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY);
}
-/*PAGE
- *
- * _CORE_message_queue_Append
- *
- * DESCRIPTION:
- *
+/**
* This routine places the_message at the rear of the outstanding
* messages on the_message_queue.
*/
@@ -198,12 +166,7 @@ RTEMS_INLINE_ROUTINE void _CORE_message_queue_Append (
_Chain_Append( &the_message_queue->Pending_messages, &the_message->Node );
}
-/*PAGE
- *
- * _CORE_message_queue_Prepend
- *
- * DESCRIPTION:
- *
+/**
* This routine places the_message at the front of the outstanding
* messages on the_message_queue.
*/
@@ -219,12 +182,7 @@ RTEMS_INLINE_ROUTINE void _CORE_message_queue_Prepend (
);
}
-/*PAGE
- *
- * _CORE_message_queue_Is_null
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_message_queue is TRUE and FALSE otherwise.
*/
@@ -235,12 +193,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_message_queue_Is_null (
return ( the_message_queue == NULL );
}
-/*PAGE
- *
- * _CORE_message_queue_Is_notify_enabled
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if notification is enabled on this message
* queue and FALSE otherwise.
*/
@@ -252,12 +205,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_message_queue_Is_notify_enabled (
return (the_message_queue->notify_handler != NULL);
}
-/*PAGE
- *
- * _CORE_message_queue_Set_notify
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the notification information for the_message_queue.
*/
@@ -271,5 +219,7 @@ RTEMS_INLINE_ROUTINE void _CORE_message_queue_Set_notify (
the_message_queue->notify_argument = the_argument;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/coremutex.inl b/cpukit/score/inline/rtems/score/coremutex.inl
index 2d884b79f9..3040142636 100644
--- a/cpukit/score/inline/rtems/score/coremutex.inl
+++ b/cpukit/score/inline/rtems/score/coremutex.inl
@@ -1,9 +1,12 @@
-/* inline/coremutex.inl
+/**
+ * @file coremutex.inl
*
* This include file contains all of the inlined routines associated
* with the CORE mutexes.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __INLINE_CORE_MUTEX_inl
#define __INLINE_CORE_MUTEX_inl
-/*PAGE
- *
- * _CORE_mutex_Is_locked
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreMutex
+ * @{
+ */
+
+/**
* This routine returns TRUE if the mutex specified is locked and FALSE
* otherwise.
*/
@@ -33,12 +36,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked(
return the_mutex->lock == CORE_MUTEX_LOCKED;
}
-/*PAGE
- *
- * _CORE_mutex_Is_fifo
- *
- * DESCRIPTION:
- *
+/**
* This routine returns TRUE if the mutex's wait discipline is FIFO and FALSE
* otherwise.
*/
@@ -50,12 +48,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo(
return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_FIFO;
}
-/*PAGE
- *
- * _CORE_mutex_Is_priority
- *
- * DESCRIPTION:
- *
+/**
* This routine returns TRUE if the mutex's wait discipline is PRIORITY and
* FALSE otherwise.
*/
@@ -67,12 +60,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority(
return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY;
}
-/*PAGE
- *
- * _CORE_mutex_Is_inherit_priority
- *
- * DESCRIPTION:
- *
+/**
* This routine returns TRUE if the mutex's wait discipline is
* INHERIT_PRIORITY and FALSE otherwise.
*/
@@ -84,12 +72,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_inherit_priority(
return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT;
}
-/*PAGE
- *
- * _CORE_mutex_Is_priority_ceiling
- *
- * DESCRIPTION:
- *
+/**
* This routine returns TRUE if the mutex's wait discipline is
* PRIORITY_CEILING and FALSE otherwise.
*/
@@ -101,12 +84,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling(
return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING;
}
-/*PAGE
- *
- * _CORE_mutex_Seize_interrupt_trylock
- *
- * DESCRIPTION:
- *
+/*
* This routine returns 0 if "trylock" can resolve whether or not the
* mutex is immediately obtained or there was an error attempting to
* get it. It returns 1 to indicate that the caller cannot obtain
@@ -115,8 +93,9 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling(
* NOTE: There is no MACRO version of this routine.
* A body is in coremutexseize.c that is duplicated
* from the .inl by hand.
+ *
+ * NOTE: The Doxygen for this routine is in the .h file.
*/
-
RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
CORE_mutex_Control *the_mutex,
ISR_Level *level_p
@@ -192,5 +171,7 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
return 1;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/coresem.inl b/cpukit/score/inline/rtems/score/coresem.inl
index 4c39764e23..b2a6282b39 100644
--- a/cpukit/score/inline/rtems/score/coresem.inl
+++ b/cpukit/score/inline/rtems/score/coresem.inl
@@ -1,9 +1,12 @@
-/* inline/coresem.inl
+/**
+ * @file coresem.inl
*
* This include file contains all of the inlined routines associated
* with the CORE semaphore.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,19 +19,21 @@
#ifndef __INLINE_CORE_SEMAPHORE_inl
#define __INLINE_CORE_SEMAPHORE_inl
+/**
+ * @addtogroup ScoreSemaphore
+ * @{
+ */
+
#include <rtems/score/thread.h>
#include <rtems/score/threadq.h>
-/*PAGE
- *
- * _CORE_semaphore_Is_priority
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the priority attribute is
* enabled in the attribute_set and FALSE otherwise.
+ *
+ * @param the_attribute (in) is the attribute set to test
+ * @return TRUE if the priority attribute is enabled
*/
-
RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority(
CORE_semaphore_Attributes *the_attribute
)
@@ -36,36 +41,34 @@ RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority(
return ( the_attribute->discipline == CORE_SEMAPHORE_DISCIPLINES_PRIORITY );
}
-/*PAGE
- *
- * _CORE_semaphore_Get_count
- *
- * DESCRIPTION:
- *
+/**
* This routine returns the current count associated with the semaphore.
+ *
+ * @param the_semaphore (in) is the semaphore to obtain the count of
+ * @return the current count of this semaphore
*/
-
-RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count(
+RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count(
CORE_semaphore_Control *the_semaphore
)
{
return the_semaphore->count;
}
-/*PAGE
- *
- * _CORE_semaphore_Seize_isr_disable
- *
- * DESCRIPTION:
- *
+/**
* This routine attempts to receive a unit from the_semaphore.
* If a unit is available or if the wait flag is FALSE, then the routine
* returns. Otherwise, the calling task is blocked until a unit becomes
* available.
*
- * NOTE: There is currently no MACRO version of this routine.
+ * @param the_semaphore (in) is the semaphore to obtain
+ * @param id (in) is the Id of the owning API level Semaphore object
+ * @param wait (in) is TRUE if the thread is willing to wait
+ * @param timeout (in) is the maximum number of ticks to block
+ * @param level_p (in) is a temporary variable used to contain the ISR
+ * disable level cookie
+ *
+ * @note There is currently no MACRO version of this routine.
*/
-
RTEMS_INLINE_ROUTINE void _CORE_semaphore_Seize_isr_disable(
CORE_semaphore_Control *the_semaphore,
Objects_Id id,
@@ -103,5 +106,7 @@ RTEMS_INLINE_ROUTINE void _CORE_semaphore_Seize_isr_disable(
_Thread_Enable_dispatch();
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/heap.inl b/cpukit/score/inline/rtems/score/heap.inl
index ae41cf6244..f8d2cca0c3 100644
--- a/cpukit/score/inline/rtems/score/heap.inl
+++ b/cpukit/score/inline/rtems/score/heap.inl
@@ -1,9 +1,12 @@
-/* heap.inl
+/**
+ * @file heap.inl
*
* This file contains the static inline implementation of the inlined
* routines from the heap handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,14 +19,14 @@
#ifndef __HEAP_inl
#define __HEAP_inl
+/**
+ * @addtogroup ScoreHeap
+ * @{
+ */
+
#include <rtems/score/address.h>
-/*PAGE
- *
- * _Heap_Head
- *
- * DESCRIPTION:
- *
+/**
* This function returns the head of the specified heap.
*/
@@ -34,12 +37,7 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head (
return (Heap_Block *)&the_heap->start;
}
-/*PAGE
- *
- * _Heap_Tail
- *
- * DESCRIPTION:
- *
+/**
* This function returns the tail of the specified heap.
*/
@@ -50,12 +48,7 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail (
return (Heap_Block *)&the_heap->final;
}
-/*PAGE
- *
- * _Heap_Previous_block
- *
- * DESCRIPTION:
- *
+/**
* This function returns the address of the block which physically
* precedes the_block in memory.
*/
@@ -70,16 +63,11 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Previous_block (
);
}
-/*PAGE
- *
- * _Heap_Next_block
- *
- * DESCRIPTION:
- *
+/**
* This function returns the address of the block which physically
* follows the_block in memory.
*
- * NOTE: Next_block assumes that the block is free.
+ * @note Next_block assumes that the block is free.
*/
RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Next_block (
@@ -92,12 +80,7 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Next_block (
);
}
-/*PAGE
- *
- * _Heap_Block_at
- *
- * DESCRIPTION:
- *
+/**
* This function calculates and returns a block's location (address)
* in the heap based upon a base address and an offset.
*/
@@ -110,12 +93,7 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at(
return (Heap_Block *) _Addresses_Add_offset( (void *)base, offset );
}
-/*PAGE
- *
- * _Heap_User_block_at
- *
- * DESCRIPTION:
- *
+/**
* XXX
*/
@@ -129,12 +107,7 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_User_block_at(
return _Heap_Block_at( base, -offset + -HEAP_BLOCK_USED_OVERHEAD);
}
-/*PAGE
- *
- * _Heap_Is_previous_block_free
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the previous block of the_block
* is free, and FALSE otherwise.
*/
@@ -146,12 +119,7 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_previous_block_free (
return !(the_block->back_flag & HEAP_BLOCK_USED);
}
-/*PAGE
- *
- * _Heap_Is_block_free
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the block is free, and FALSE otherwise.
*/
@@ -162,12 +130,7 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_free (
return !(the_block->front_flag & HEAP_BLOCK_USED);
}
-/*PAGE
- *
- * _Heap_Is_block_used
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the block is currently allocated,
* and FALSE otherwise.
*/
@@ -179,12 +142,7 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_used (
return (the_block->front_flag & HEAP_BLOCK_USED);
}
-/*PAGE
- *
- * _Heap_Block_size
- *
- * DESCRIPTION:
- *
+/**
* This function returns the size of the_block in bytes.
*/
@@ -195,12 +153,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size (
return (the_block->front_flag & ~HEAP_BLOCK_USED);
}
-/*PAGE
- *
- * _Heap_Start_of_user_area
- *
- * DESCRIPTION:
- *
+/**
* This function returns the starting address of the portion of the block
* which the user may access.
*/
@@ -212,12 +165,7 @@ RTEMS_INLINE_ROUTINE void *_Heap_Start_of_user_area (
return (void *) &the_block->next;
}
-/*PAGE
- *
- * _Heap_Is_block_in
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_block is within the memory area
* managed by the_heap, and FALSE otherwise.
*/
@@ -230,12 +178,7 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_in (
return _Addresses_Is_in_range( the_block, the_heap->start, the_heap->final );
}
-/*PAGE
- *
- * _Heap_Is_page_size_valid
- *
- * DESCRIPTION:
- *
+/**
* This function validates a specified heap page size. If the page size
* is 0 or if lies outside a page size alignment boundary it is invalid
* and FALSE is returned. Otherwise, the page size is valid and TRUE is
@@ -250,12 +193,7 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_page_size_valid(
((page_size % CPU_HEAP_ALIGNMENT) == 0));
}
-/*PAGE
- *
- * _Heap_Build_flag
- *
- * DESCRIPTION:
- *
+/**
* This function returns the block flag composed of size and in_use_flag.
* The flag returned is suitable for use as a back or front flag in a
* heap block.
@@ -269,5 +207,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Heap_Build_flag (
return size | in_use_flag;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/isr.inl b/cpukit/score/inline/rtems/score/isr.inl
index 637098b297..dedbd150cd 100644
--- a/cpukit/score/inline/rtems/score/isr.inl
+++ b/cpukit/score/inline/rtems/score/isr.inl
@@ -1,9 +1,12 @@
-/* isr.inl
+/**
+ * @file isr.inl
*
* This include file contains the static implementation of all
* inlined routines in the Interrupt Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __ISR_inl
#define __ISR_inl
-/*PAGE
- *
- * _ISR_Is_vector_number_valid
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreISR
+ * @{
+ */
+
+/**
* This function returns TRUE if the vector is a valid vector number
* for this processor and FALSE otherwise.
*/
@@ -33,13 +36,7 @@ RTEMS_INLINE_ROUTINE boolean _ISR_Is_vector_number_valid (
return ( vector <= CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER );
}
-/*PAGE
- *
- * _ISR_Is_valid_user_handler
- *
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if handler is the entry point of a valid
* use interrupt service routine and FALSE otherwise.
*/
@@ -51,5 +48,7 @@ RTEMS_INLINE_ROUTINE boolean _ISR_Is_valid_user_handler (
return ( handler != NULL);
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/mppkt.inl b/cpukit/score/inline/rtems/score/mppkt.inl
index a26713776d..77f5664eb0 100644
--- a/cpukit/score/inline/rtems/score/mppkt.inl
+++ b/cpukit/score/inline/rtems/score/mppkt.inl
@@ -1,9 +1,12 @@
-/* inline/mppkt.inl
+/**
+ * @file mppkt.inl
*
* This package is the implementation of the Packet Handler
* routines which are inlined.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,16 +19,16 @@
#ifndef __INLINE_MP_PACKET_inl
#define __INLINE_MP_PACKET_inl
-/*PAGE
- *
- * _Mp_packet_Is_valid_packet_class
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreMPPacket
+ * @{
+ */
+
+/**
* This function returns TRUE if the the_packet_class is valid,
* and FALSE otherwise.
*
- * NOTE: Check for lower bounds (MP_PACKET_CLASSES_FIRST ) is unnecessary
+ * @note Check for lower bounds (MP_PACKET_CLASSES_FIRST ) is unnecessary
* because this enum starts at lower bound of zero.
*/
@@ -36,12 +39,7 @@ RTEMS_INLINE_ROUTINE boolean _Mp_packet_Is_valid_packet_class (
return ( the_packet_class <= MP_PACKET_CLASSES_LAST );
}
-/*PAGE
- *
- * _Mp_packet_Is_null
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the the_packet_class is null,
* and FALSE otherwise.
*/
@@ -53,5 +51,7 @@ RTEMS_INLINE_ROUTINE boolean _Mp_packet_Is_null (
return the_packet == NULL;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/objectmp.inl b/cpukit/score/inline/rtems/score/objectmp.inl
index 462a670876..ddd48fdf1b 100644
--- a/cpukit/score/inline/rtems/score/objectmp.inl
+++ b/cpukit/score/inline/rtems/score/objectmp.inl
@@ -1,9 +1,12 @@
-/* inline/objectmp.inl
+/**
+ * @file objectmp.inl
*
* This include file contains the bodies of all inlined routines
* which deal with global objects.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __INLINE_MP_OBJECTS_inl
#define __INLINE_MP_OBJECTS_inl
-/*PAGE
- *
- * _Objects_MP_Allocate_global_object
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreObjectMP
+ * @{
+ */
+
+/**
* This function allocates a Global Object control block.
*/
@@ -33,12 +36,7 @@ RTEMS_INLINE_ROUTINE Objects_MP_Control *_Objects_MP_Allocate_global_object (
_Chain_Get( &_Objects_MP_Inactive_global_objects );
}
-/*PAGE
- *
- * _Objects_MP_Free_global_object
- *
- * DESCRIPTION:
- *
+/**
* This routine deallocates a Global Object control block.
*/
@@ -52,12 +50,7 @@ RTEMS_INLINE_ROUTINE void _Objects_MP_Free_global_object (
);
}
-/*PAGE
- *
- * _Objects_MP_Is_null_global_object
- *
- * DESCRIPTION:
- *
+/**
* This function returns whether the global object is NULL or not.
*/
@@ -68,5 +61,7 @@ RTEMS_INLINE_ROUTINE boolean _Objects_MP_Is_null_global_object (
return( the_object == NULL );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/priority.inl b/cpukit/score/inline/rtems/score/priority.inl
index ef7e366213..509b52e5f2 100644
--- a/cpukit/score/inline/rtems/score/priority.inl
+++ b/cpukit/score/inline/rtems/score/priority.inl
@@ -1,9 +1,12 @@
-/* priority.inl
+/**
+ * @file priority.inl
*
* This file contains the static inline implementation of all inlined
* routines in the Priority Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,14 +19,14 @@
#ifndef __PRIORITY_inl
#define __PRIORITY_inl
+/**
+ * @addtogroup ScorePriority
+ * @{
+ */
+
#include <rtems/score/bitfield.h>
-/*PAGE
- *
- * _Priority_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
*/
@@ -36,12 +39,7 @@ RTEMS_INLINE_ROUTINE void _Priority_Handler_initialization( void )
_Priority_Bit_map[ index ] = 0;
}
-/*PAGE
- *
- * _Priority_Is_valid
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_priority if valid for a
* user task, and FALSE otherwise.
*/
@@ -58,12 +56,7 @@ RTEMS_INLINE_ROUTINE boolean _Priority_Is_valid (
return ( the_priority <= PRIORITY_MAXIMUM );
}
-/*PAGE
- *
- * _Priority_Major
- *
- * DESCRIPTION:
- *
+/**
* This function returns the major portion of the_priority.
*/
@@ -74,12 +67,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Priority_Major (
return ( the_priority / 16 );
}
-/*PAGE
- *
- * _Priority_Minor
- *
- * DESCRIPTION:
- *
+/**
* This function returns the minor portion of the_priority.
*/
@@ -92,12 +80,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Priority_Minor (
#if ( CPU_USE_GENERIC_BITFIELD_CODE == TRUE )
-/*PAGE
- *
- * _Priority_Mask
- *
- * DESCRIPTION:
- *
+/**
* This function returns the mask associated with the major or minor
* number passed to it.
*/
@@ -110,12 +93,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Priority_Mask (
}
-/*PAGE
- *
- * _Priority_Bits_index
- *
- * DESCRIPTION:
- *
+/**
* This function translates the bit numbers returned by the bit scan
* of a priority bit field into something suitable for use as
* a major or minor component of a priority.
@@ -130,12 +108,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Priority_Bits_index (
#endif
-/*PAGE
- *
- * _Priority_Add_to_bit_map
- *
- * DESCRIPTION:
- *
+/**
* This routine uses the_priority_map to update the priority
* bit maps to indicate that a thread has been readied.
*/
@@ -148,12 +121,7 @@ RTEMS_INLINE_ROUTINE void _Priority_Add_to_bit_map (
_Priority_Major_bit_map |= the_priority_map->ready_major;
}
-/*PAGE
- *
- * _Priority_Remove_from_bit_map
- *
- * DESCRIPTION:
- *
+/**
* This routine uses the_priority_map to update the priority
* bit maps to indicate that a thread has been removed from the
* ready state.
@@ -168,12 +136,7 @@ RTEMS_INLINE_ROUTINE void _Priority_Remove_from_bit_map (
_Priority_Major_bit_map &= the_priority_map->block_major;
}
-/*PAGE
- *
- * _Priority_Get_highest
- *
- * DESCRIPTION:
- *
+/**
* This function returns the priority of the highest priority
* ready thread.
*/
@@ -190,12 +153,7 @@ RTEMS_INLINE_ROUTINE Priority_Control _Priority_Get_highest( void )
_Priority_Bits_index( minor );
}
-/*PAGE
- *
- * _Priority_Initialize_information
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the_priority_map so that it
* contains the information necessary to manage a thread
* at new_priority.
@@ -225,12 +183,7 @@ RTEMS_INLINE_ROUTINE void _Priority_Initialize_information(
the_priority_map->block_minor = ~mask;
}
-/*PAGE
- *
- * _Priority_Is_group_empty
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the priority GROUP is empty, and
* FALSE otherwise.
*/
@@ -242,5 +195,7 @@ RTEMS_INLINE_ROUTINE boolean _Priority_Is_group_empty (
return the_priority == 0;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/stack.inl b/cpukit/score/inline/rtems/score/stack.inl
index 5bfd3c1622..e02da4fbe0 100644
--- a/cpukit/score/inline/rtems/score/stack.inl
+++ b/cpukit/score/inline/rtems/score/stack.inl
@@ -1,9 +1,12 @@
-/* stack.inl
+/**
+ * @file stack.inl
*
* This file contains the static inline implementation of the inlined
* routines from the Stack Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __STACK_inl
#define __STACK_inl
-/*PAGE
- *
- * _Stack_Initialize
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreStack
+ * @{
+ */
+
+/**
* This routine initializes the_stack record to indicate that
* size bytes of memory starting at starting_address have been
* reserved for a stack.
@@ -37,12 +40,7 @@ RTEMS_INLINE_ROUTINE void _Stack_Initialize (
the_stack->size = size;
}
-/*PAGE
- *
- * _Stack_Is_enough
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if size bytes is enough memory for
* a valid stack area on this processor, and FALSE otherwise.
*/
@@ -54,17 +52,12 @@ RTEMS_INLINE_ROUTINE boolean _Stack_Is_enough (
return ( size >= STACK_MINIMUM_SIZE );
}
-/*PAGE
- *
- * _Stack_Adjust_size
- *
- * DESCRIPTION:
- *
+/**
* This function increases the stack size to insure that the thread
* has the desired amount of stack space after the initial stack
* pointer is determined based on alignment restrictions.
*
- * NOTE:
+ * @note
*
* The amount of adjustment for alignment is CPU dependent.
*/
@@ -76,5 +69,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Stack_Adjust_size (
return size + CPU_STACK_ALIGNMENT;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/states.inl b/cpukit/score/inline/rtems/score/states.inl
index 0122f74e7d..2701692f19 100644
--- a/cpukit/score/inline/rtems/score/states.inl
+++ b/cpukit/score/inline/rtems/score/states.inl
@@ -1,9 +1,12 @@
-/* states.inl
+/**
+ * @file states.inl
*
* This file contains the macro implementation of the inlined
* routines associated with thread state information.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __STATES_inl
#define __STATES_inl
-/*PAGE
- *
- * _States_Set
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreStates
+ * @{
+ */
+
+/**
* This function sets the given states_to_set into the current_state
* passed in. The result is returned to the user in current_state.
*/
@@ -34,12 +37,7 @@ RTEMS_INLINE_ROUTINE States_Control _States_Set (
return (current_state | states_to_set);
}
-/*PAGE
- *
- * _States_Clear
- *
- * DESCRIPTION:
- *
+/**
* This function clears the given states_to_clear into the current_state
* passed in. The result is returned to the user in current_state.
*/
@@ -52,12 +50,7 @@ RTEMS_INLINE_ROUTINE States_Control _States_Clear (
return (current_state & ~states_to_clear);
}
-/*PAGE
- *
- * _States_Is_ready
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_states indicates that the
* state is READY, and FALSE otherwise.
*/
@@ -69,12 +62,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_ready (
return (the_states == STATES_READY);
}
-/*PAGE
- *
- * _States_Is_only_dormant
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the DORMANT state is the ONLY state
* set in the_states, and FALSE otherwise.
*/
@@ -86,12 +74,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_only_dormant (
return (the_states == STATES_DORMANT);
}
-/*PAGE
- *
- * _States_Is_dormant
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the DORMANT state is set in
* the_states, and FALSE otherwise.
*/
@@ -103,12 +86,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_dormant (
return (the_states & STATES_DORMANT);
}
-/*PAGE
- *
- * _States_Is_suspended
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the SUSPENDED state is set in
* the_states, and FALSE otherwise.
*/
@@ -120,12 +98,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_suspended (
return (the_states & STATES_SUSPENDED);
}
-/*PAGE
- *
- * _States_Is_Transient
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the TRANSIENT state is set in
* the_states, and FALSE otherwise.
*/
@@ -137,12 +110,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_transient (
return (the_states & STATES_TRANSIENT);
}
-/*PAGE
- *
- * _States_Is_delaying
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the DELAYING state is set in
* the_states, and FALSE otherwise.
*/
@@ -154,12 +122,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_delaying (
return (the_states & STATES_DELAYING);
}
-/*PAGE
- *
- * _States_Is_waiting_for_buffer
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_BUFFER state is set in
* the_states, and FALSE otherwise.
*/
@@ -171,12 +134,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_buffer (
return (the_states & STATES_WAITING_FOR_BUFFER);
}
-/*PAGE
- *
- * _States_Is_waiting_for_segment
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_SEGMENT state is set in
* the_states, and FALSE otherwise.
*/
@@ -188,12 +146,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_segment (
return (the_states & STATES_WAITING_FOR_SEGMENT);
}
-/*PAGE
- *
- * _States_Is_waiting_for_message
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_MESSAGE state is set in
* the_states, and FALSE otherwise.
*/
@@ -205,12 +158,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_message (
return (the_states & STATES_WAITING_FOR_MESSAGE);
}
-/*PAGE
- *
- * _States_Is_waiting_for_event
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_EVENT state is set in
* the_states, and FALSE otherwise.
*/
@@ -222,12 +170,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_event (
return (the_states & STATES_WAITING_FOR_EVENT);
}
-/*PAGE
- *
- * _States_Is_waiting_for_mutex
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_MUTEX state
* is set in the_states, and FALSE otherwise.
*/
@@ -239,12 +182,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_mutex (
return (the_states & STATES_WAITING_FOR_MUTEX);
}
-/*PAGE
- *
- * _States_Is_waiting_for_semaphore
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_SEMAPHORE state
* is set in the_states, and FALSE otherwise.
*/
@@ -256,12 +194,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_semaphore (
return (the_states & STATES_WAITING_FOR_SEMAPHORE);
}
-/*PAGE
- *
- * _States_Is_waiting_for_time
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_TIME state is set in
* the_states, and FALSE otherwise.
*/
@@ -273,12 +206,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_time (
return (the_states & STATES_WAITING_FOR_TIME);
}
-/*PAGE
- *
- * _States_Is_waiting_for_rpc_reply
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_TIME state is set in
* the_states, and FALSE otherwise.
*/
@@ -290,12 +218,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_rpc_reply (
return (the_states & STATES_WAITING_FOR_RPC_REPLY);
}
-/*PAGE
- *
- * _States_Is_waiting_for_period
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the WAITING_FOR_PERIOD state is set in
* the_states, and FALSE otherwise.
*/
@@ -307,12 +230,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_for_period (
return (the_states & STATES_WAITING_FOR_PERIOD);
}
-/*PAGE
- *
- * _States_Is_locally_blocked
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if one of the states which indicates
* that a task is blocked waiting for a local resource is set in
* the_states, and FALSE otherwise.
@@ -325,12 +243,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_locally_blocked (
return (the_states & STATES_LOCALLY_BLOCKED);
}
-/*PAGE
- *
- * _States_Is_waiting_on_thread_queue
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if one of the states which indicates
* that a task is blocked waiting for a local resource is set in
* the_states, and FALSE otherwise.
@@ -343,12 +256,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_waiting_on_thread_queue (
return (the_states & STATES_WAITING_ON_THREAD_QUEUE);
}
-/*PAGE
- *
- * _States_Is_blocked
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if one of the states which indicates
* that a task is blocked is set in the_states, and FALSE otherwise.
*/
@@ -360,13 +268,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Is_blocked (
return (the_states & STATES_BLOCKED);
}
-/*PAGE
- *
- *
- * _States_Are_set
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if any of the states in the mask
* are set in the_states, and FALSE otherwise.
*/
@@ -379,5 +281,7 @@ RTEMS_INLINE_ROUTINE boolean _States_Are_set (
return ( (the_states & mask) != STATES_READY);
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/sysstate.inl b/cpukit/score/inline/rtems/score/sysstate.inl
index 4aa3295efe..63cfe8cde4 100644
--- a/cpukit/score/inline/rtems/score/sysstate.inl
+++ b/cpukit/score/inline/rtems/score/sysstate.inl
@@ -1,9 +1,12 @@
-/* sysstates.inl
+/**
+ * @file sysstate.inl
*
* This file contains the inline implementation of routines regarding the
* system state.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __SYSTEM_STATE_inl
#define __SYSTEM_STATE_inl
-/*PAGE
- *
- * _System_state_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreSysState
+ * @{
+ */
+
+/**
* This routine initializes the system state handler.
*/
@@ -33,12 +36,7 @@ RTEMS_INLINE_ROUTINE void _System_state_Handler_initialization (
_System_state_Is_multiprocessing = is_multiprocessing;
}
-/*PAGE
- *
- * _System_state_Set
- *
- * DESCRIPTION:
- *
+/**
* This routine sets the current system state to that specified by
* the called.
*/
@@ -50,12 +48,7 @@ RTEMS_INLINE_ROUTINE void _System_state_Set (
_System_state_Current = state;
}
-/*PAGE
- *
- * _System_state_Get
- *
- * DESCRIPTION:
- *
+/**
* This function returns the current system state.
*/
@@ -64,12 +57,7 @@ RTEMS_INLINE_ROUTINE System_state_Codes _System_state_Get ( void )
return _System_state_Current;
}
-/*PAGE
- *
- * _System_state_Is_before_initialization
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the state is equal to the
* "before initialization" state, and FALSE otherwise.
*/
@@ -81,12 +69,7 @@ RTEMS_INLINE_ROUTINE boolean _System_state_Is_before_initialization (
return (state == SYSTEM_STATE_BEFORE_INITIALIZATION);
}
-/*PAGE
- *
- * _System_state_Is_before_multitasking
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the state is equal to the
* "before multitasking" state, and FALSE otherwise.
*/
@@ -98,12 +81,7 @@ RTEMS_INLINE_ROUTINE boolean _System_state_Is_before_multitasking (
return (state == SYSTEM_STATE_BEFORE_MULTITASKING);
}
-/*PAGE
- *
- * _System_state_Is_begin_multitasking
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the state is equal to the
* "begin multitasking" state, and FALSE otherwise.
*/
@@ -115,12 +93,7 @@ RTEMS_INLINE_ROUTINE boolean _System_state_Is_begin_multitasking (
return (state == SYSTEM_STATE_BEGIN_MULTITASKING);
}
-/*PAGE
- *
- * _System_state_Is_up
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the state is equal to the
* "up" state, and FALSE otherwise.
*/
@@ -132,12 +105,7 @@ RTEMS_INLINE_ROUTINE boolean _System_state_Is_up (
return (state == SYSTEM_STATE_UP);
}
-/*PAGE
- *
- * _System_state_Is_failed
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the state is equal to the
* "failed" state, and FALSE otherwise.
*/
@@ -149,5 +117,7 @@ RTEMS_INLINE_ROUTINE boolean _System_state_Is_failed (
return (state == SYSTEM_STATE_FAILED);
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/thread.inl b/cpukit/score/inline/rtems/score/thread.inl
index e4f113f70c..3d38f8e6da 100644
--- a/cpukit/score/inline/rtems/score/thread.inl
+++ b/cpukit/score/inline/rtems/score/thread.inl
@@ -1,9 +1,12 @@
-/* thread.inl
+/**
+ * @file thread.inl
*
* This file contains the macro implementation of the inlined
* routines from the Thread handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __THREAD_inl
#define __THREAD_inl
-/*PAGE
- *
- * _Thread_Stop_multitasking
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreThread
+ * @{
+ */
+
+/**
* This routine halts multitasking and returns control to
* the "thread" (i.e. the BSP) which initially invoked the
* routine which initialized the system.
@@ -32,12 +35,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Stop_multitasking( void )
_Context_Switch( &_Thread_Executing->Registers, &_Thread_BSP_context );
}
-/*PAGE
- *
- * _Thread_Is_executing
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_thread is the currently executing
* thread, and FALSE otherwise.
*/
@@ -49,12 +47,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_executing (
return ( the_thread == _Thread_Executing );
}
-/*PAGE
- *
- * _Thread_Is_heir
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_thread is the heir
* thread, and FALSE otherwise.
*/
@@ -66,12 +59,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_heir (
return ( the_thread == _Thread_Heir );
}
-/*PAGE
- *
- * _Thread_Is_executing_also_the_heir
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the currently executing thread
* is also the heir thread, and FALSE otherwise.
*/
@@ -81,12 +69,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_executing_also_the_heir( void )
return ( _Thread_Executing == _Thread_Heir );
}
-/*PAGE
- *
- * _Thread_Unblock
- *
- * DESCRIPTION:
- *
+/**
* This routine clears any blocking state for the_thread. It performs
* any necessary scheduling operations including the selection of
* a new heir thread.
@@ -99,12 +82,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Unblock (
_Thread_Clear_state( the_thread, STATES_BLOCKED );
}
-/*PAGE
- *
- * _Thread_Restart_self
- *
- * DESCRIPTION:
- *
+/**
* This routine resets the current context of the calling thread
* to that of its initial state.
*/
@@ -119,12 +97,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Restart_self( void )
_CPU_Context_Restart_self( &_Thread_Executing->Registers );
}
-/*PAGE
- *
- * _Thread_Calculate_heir
- *
- * DESCRIPTION:
- *
+/**
* This function returns a pointer to the highest priority
* ready thread.
*/
@@ -135,12 +108,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Calculate_heir( void )
_Thread_Ready_chain[ _Priority_Get_highest() ].first;
}
-/*PAGE
- *
- * _Thread_Is_allocated_fp
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the floating point context of
* the_thread is currently loaded in the floating point unit, and
* FALSE otherwise.
@@ -155,12 +123,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_allocated_fp (
}
#endif
-/*PAGE
- *
- * _Thread_Deallocate_fp
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked when the currently loaded floating
* point context is now longer associated with an active thread.
*/
@@ -172,12 +135,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Deallocate_fp( void )
}
#endif
-/*PAGE
- *
- * _Thread_Disable_dispatch
- *
- * DESCRIPTION:
- *
+/**
* This routine prevents dispatching.
*/
@@ -186,12 +144,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Disable_dispatch( void )
_Thread_Dispatch_disable_level += 1;
}
-/*PAGE
- *
- * _Thread_Enable_dispatch
- *
- * DESCRIPTION:
- *
+/**
* This routine allows dispatching to occur again. If this is
* the outer most dispatching critical section, then a dispatching
* operation will be performed and, if necessary, control of the
@@ -210,12 +163,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Enable_dispatch()
void _Thread_Enable_dispatch( void );
#endif
-/*PAGE
- *
- * _Thread_Unnest_dispatch
- *
- * DESCRIPTION:
- *
+/**
* This routine allows dispatching to occur again. However,
* no dispatching operation is performed even if this is the outer
* most dispatching critical section.
@@ -226,12 +174,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Unnest_dispatch( void )
_Thread_Dispatch_disable_level -= 1;
}
-/*PAGE
- *
- * _Thread_Is_dispatching_enabled
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if dispatching is disabled, and FALSE
* otherwise.
*/
@@ -241,12 +184,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_dispatching_enabled( void )
return ( _Thread_Dispatch_disable_level == 0 );
}
-/*PAGE
- *
- * _Thread_Is_context_switch_necessary
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if dispatching is disabled, and FALSE
* otherwise.
*/
@@ -256,12 +194,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_context_switch_necessary( void )
return ( _Context_Switch_necessary );
}
-/*PAGE
- *
- * _Thread_Dispatch_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine initializes the thread dispatching subsystem.
*/
@@ -270,12 +203,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Dispatch_initialization( void )
_Thread_Dispatch_disable_level = 1;
}
-/*PAGE
- *
- * _Thread_Is_null
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_thread is NULL and FALSE otherwise.
*/
@@ -286,12 +214,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_null (
return ( the_thread == NULL );
}
-/*PAGE
- *
- * _Thread_Get
- *
- * DESCRIPTION:
- *
+/**
* This function maps thread IDs to thread control
* blocks. If ID corresponds to a local thread, then it
* returns the_thread control pointer which maps to ID
@@ -301,7 +224,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_null (
* Otherwise, location is set to OBJECTS_ERROR and
* the_thread is undefined.
*
- * NOTE: XXX... This routine may be able to be optimized.
+ * @note XXX... This routine may be able to be optimized.
*/
RTEMS_INLINE_ROUTINE Thread_Control *_Thread_Get (
@@ -347,15 +270,10 @@ done:
}
-/*
- * _Thread_Is_proxy_blocking
+/** @brief _Thread_Is_proxy_blocking
*
- * DESCRIPTION:
- *
- * This function returns TRUE if the status code is equal to the
* status which indicates that a proxy is blocking, and FALSE otherwise.
*/
-
RTEMS_INLINE_ROUTINE boolean _Thread_Is_proxy_blocking (
uint32_t code
)
@@ -363,12 +281,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_proxy_blocking (
return (code == THREAD_STATUS_PROXY_BLOCKING);
}
-/*PAGE
- *
- * _Thread_Internal_allocate
- *
- * DESCRIPTION:
- *
+/**
* This routine allocates an internal thread.
*/
@@ -377,12 +290,7 @@ RTEMS_INLINE_ROUTINE Thread_Control *_Thread_Internal_allocate( void )
return (Thread_Control *) _Objects_Allocate( &_Thread_Internal_information );
}
-/*PAGE
- *
- * _Thread_Internal_free
- *
- * DESCRIPTION:
- *
+/**
* This routine frees an internal thread.
*/
@@ -393,12 +301,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Internal_free (
_Objects_Free( &_Thread_Internal_information, &the_task->Object );
}
-/*PAGE
- *
- * _Thread_Get_libc_reent
- *
- * DESCRIPTION:
- *
+/**
* This routine returns the C library re-enterant pointer.
*/
@@ -407,12 +310,7 @@ RTEMS_INLINE_ROUTINE struct _reent **_Thread_Get_libc_reent( void )
return _Thread_libc_reent;
}
-/*PAGE
- *
- * _Thread_Set_libc_reent
- *
- * DESCRIPTION:
- *
+/**
* This routine set the C library re-enterant pointer.
*/
@@ -423,5 +321,7 @@ RTEMS_INLINE_ROUTINE void _Thread_Set_libc_reent (
_Thread_libc_reent = libc_reent;
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/threadmp.inl b/cpukit/score/inline/rtems/score/threadmp.inl
index fbb247c49c..67978a32d7 100644
--- a/cpukit/score/inline/rtems/score/threadmp.inl
+++ b/cpukit/score/inline/rtems/score/threadmp.inl
@@ -1,9 +1,12 @@
-/* inline/threadmp.inl
+/**
+ * @file threadmp.inl
*
* This include file contains the bodies of all inlined routines
* for the multiprocessing part of thread package.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __INLINE_MP_THREAD_inl
#define __INLINE_MP_THREAD_inl
-/*PAGE
- *
- * _Thread_MP_Is_receive
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreThreadMP
+ * @{
+ */
+
+/**
* This function returns true if the thread in question is the
* multiprocessing receive thread.
*/
@@ -33,12 +36,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_MP_Is_receive (
return the_thread == _Thread_MP_Receive;
}
-/*PAGE
- *
- * _Thread_MP_Free_proxy
- *
- * DESCRIPTION:
- *
+/**
* This routine frees a proxy control block to the
* inactive chain of free proxy control blocks.
*/
@@ -56,5 +54,7 @@ RTEMS_INLINE_ROUTINE void _Thread_MP_Free_proxy (
_Chain_Append( &_Thread_MP_Inactive_proxies, &the_thread->Object.Node );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/tod.inl b/cpukit/score/inline/rtems/score/tod.inl
index 7c2a4ffdfc..0854654453 100644
--- a/cpukit/score/inline/rtems/score/tod.inl
+++ b/cpukit/score/inline/rtems/score/tod.inl
@@ -1,9 +1,12 @@
-/* tod.inl
+/**
+ * @file tod.inl
*
* This file contains the static inline implementation of the inlined routines
* from the Time of Day Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __TIME_OF_DAY_inl
#define __TIME_OF_DAY_inl
-/*PAGE
- *
- * _TOD_Tickle_ticks
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreTOD
+ * @{
+ */
+
+/**
* This routine increments the ticks field of the current time of
* day at each clock tick.
*/
@@ -32,12 +35,7 @@ RTEMS_INLINE_ROUTINE void _TOD_Tickle_ticks( void )
_Watchdog_Ticks_since_boot += 1;
}
-/*PAGE
- *
- * _TOD_Deactivate
- *
- * DESCRIPTION:
- *
+/**
* This routine deactivates updating of the current time of day.
*/
@@ -46,12 +44,7 @@ RTEMS_INLINE_ROUTINE void _TOD_Deactivate( void )
_Watchdog_Remove( &_TOD_Seconds_watchdog );
}
-/*PAGE
- *
- * _TOD_Activate
- *
- * DESCRIPTION:
- *
+/**
* This routine activates updating of the current time of day.
*/
@@ -62,5 +55,7 @@ RTEMS_INLINE_ROUTINE void _TOD_Activate(
_Watchdog_Insert_ticks( &_TOD_Seconds_watchdog, ticks );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/tqdata.inl b/cpukit/score/inline/rtems/score/tqdata.inl
index aff81708b8..85662b394d 100644
--- a/cpukit/score/inline/rtems/score/tqdata.inl
+++ b/cpukit/score/inline/rtems/score/tqdata.inl
@@ -1,9 +1,12 @@
-/* tqdata.inl
+/**
+ * @file tqdata.inl
*
* This file contains the static inline implementation of the inlined
* routines needed to support the Thread Queue Data.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -13,15 +16,15 @@
* $Id$
*/
-#ifndef __THREAD_QUEUE_DATA_inl
-#define __THREAD_QUEUE_DATA_inl
+#ifndef __THREAD_QUEUE_inl
+#define __THREAD_QUEUE_inl
-/*PAGE
- *
- * _Thread_queue_Header_number
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreThreadQ
+ * @{
+ */
+
+/**
* This function returns the index of the priority chain on which
* a thread of the_priority should be placed.
*/
@@ -33,12 +36,7 @@ RTEMS_INLINE_ROUTINE uint32_t _Thread_queue_Header_number (
return (the_priority / TASK_QUEUE_DATA_PRIORITIES_PER_HEADER);
}
-/*PAGE
- *
- * _Thread_queue_Is_reverse_search
- *
- * DESCRIPTION:
- *
+/**
* This function returns TRUE if the_priority indicates that the
* enqueue search should start at the front of this priority
* group chain, and FALSE if the search should start at the rear.
@@ -51,12 +49,7 @@ RTEMS_INLINE_ROUTINE boolean _Thread_queue_Is_reverse_search (
return ( the_priority & TASK_QUEUE_DATA_REVERSE_SEARCH_MASK );
}
-/*PAGE
- *
- * _Thread_queue_Enter_critical_section
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked to indicate that the specified thread queue is
* entering a critical section.
*/
diff --git a/cpukit/score/inline/rtems/score/userext.inl b/cpukit/score/inline/rtems/score/userext.inl
index 2aef8001ff..205968d5dc 100644
--- a/cpukit/score/inline/rtems/score/userext.inl
+++ b/cpukit/score/inline/rtems/score/userext.inl
@@ -1,9 +1,12 @@
-/* userext.inl
+/**
+ * @file userext.inl
*
* This file contains the macro implementation of the inlined routines
* from the User Extension Handler
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -18,15 +21,15 @@
#include <rtems/score/wkspace.h>
-/*PAGE
- *
- * _User_extensions_Add_set
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreUserExt
+ * @{
+ */
+
+/**
* This routine is used to add a user extension set to the active list.
*
- * NOTE: Must be before _User_extensions_Handler_initialization to
+ * @note Must be before _User_extensions_Handler_initialization to
* ensure proper inlining.
*/
@@ -49,12 +52,7 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_set (
}
}
-/*PAGE
- *
- * _User_extensions_Handler_initialization
- *
- * DESCRIPTION:
- *
+/**
* This routine performs the initialization necessary for this handler.
*/
@@ -88,12 +86,7 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Handler_initialization (
}
}
-/*PAGE
- *
- * _User_extensions_Add_API_set
- *
- * DESCRIPTION:
- *
+/**
* This routine is used to add an API extension set to the active list.
*/
@@ -114,12 +107,7 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_API_set (
}
}
-/*PAGE
- *
- * _User_extensions_Remove_set
- *
- * DESCRIPTION:
- *
+/**
* This routine is used to remove a user extension set from the active list.
*/
@@ -137,12 +125,7 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Remove_set (
_Chain_Extract( &the_extension->Switch.Node );
}
-/*PAGE
- *
- * _User_extensions_Thread_switch
- *
- * DESCRIPTION:
- *
+/**
* This routine is used to invoke the user extension which
* is invoked when a context switch occurs.
*/
@@ -165,5 +148,7 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Thread_switch (
}
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/watchdog.inl b/cpukit/score/inline/rtems/score/watchdog.inl
index aace2123a6..4aebc4b34b 100644
--- a/cpukit/score/inline/rtems/score/watchdog.inl
+++ b/cpukit/score/inline/rtems/score/watchdog.inl
@@ -1,9 +1,12 @@
-/* watchdog.inl
+/**
+ * @file watchdog.inl
*
* This file contains the static inline implementation of all inlined
* routines in the Watchdog Handler.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __WATCHDOG_inl
#define __WATCHDOG_inl
-/*PAGE
- *
- * _Watchdog_Initialize
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreWatchdog
+ * @{
+ */
+
+/**
* This routine initializes the specified watchdog. The watchdog is
* made inactive, the watchdog id and handler routine are set to the
* specified values.
@@ -40,12 +43,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Initialize(
the_watchdog->user_data = user_data;
}
-/*PAGE
- *
- * _Watchdog_Is_active
- *
- * DESCRIPTION:
- *
+/**
* This routine returns TRUE if the watchdog timer is in the ACTIVE
* state, and FALSE otherwise.
*/
@@ -59,12 +57,7 @@ RTEMS_INLINE_ROUTINE boolean _Watchdog_Is_active(
}
-/*PAGE
- *
- * _Watchdog_Activate
- *
- * DESCRIPTION:
- *
+/**
* This routine activates THE_WATCHDOG timer which is already
* on a watchdog chain.
*/
@@ -78,12 +71,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Activate(
}
-/*PAGE
- *
- * _Watchdog_Deactivate
- *
- * DESCRIPTION:
- *
+/**
* This routine deactivates THE_WATCHDOG timer which will remain
* on a watchdog chain.
*/
@@ -97,12 +85,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Deactivate(
}
-/*PAGE
- *
- * _Watchdog_Tickle_ticks
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked at each clock tick to update the ticks
* watchdog chain.
*/
@@ -114,12 +97,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Tickle_ticks( void )
}
-/*PAGE
- *
- * _Watchdog_Tickle_seconds
- *
- * DESCRIPTION:
- *
+/**
* This routine is invoked at each clock tick to update the seconds
* watchdog chain.
*/
@@ -131,12 +109,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Tickle_seconds( void )
}
-/*PAGE
- *
- * _Watchdog_Insert_ticks
- *
- * DESCRIPTION:
- *
+/**
* This routine inserts THE_WATCHDOG into the ticks watchdog chain
* for a time of UNITS ticks. The INSERT_MODE indicates whether
* THE_WATCHDOG is to be activated automatically or later, explicitly
@@ -155,12 +128,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Insert_ticks(
}
-/*PAGE
- *
- * _Watchdog_Insert_seconds
- *
- * DESCRIPTION:
- *
+/**
* This routine inserts THE_WATCHDOG into the seconds watchdog chain
* for a time of UNITS seconds. The INSERT_MODE indicates whether
* THE_WATCHDOG is to be activated automatically or later, explicitly
@@ -179,12 +147,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Insert_seconds(
}
-/*PAGE
- *
- * _Watchdog_Adjust_seconds
- *
- * DESCRIPTION:
- *
+/**
* This routine adjusts the seconds watchdog chain in the forward
* or backward DIRECTION for UNITS seconds. This is invoked when the
* current time of day is changed.
@@ -200,12 +163,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Adjust_seconds(
}
-/*PAGE
- *
- * _Watchdog_Adjust_ticks
- *
- * DESCRIPTION:
- *
+/**
* This routine adjusts the ticks watchdog chain in the forward
* or backward DIRECTION for UNITS ticks.
*/
@@ -220,12 +178,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Adjust_ticks(
}
-/*PAGE
- *
- * _Watchdog_Reset
- *
- * DESCRIPTION:
- *
+/**
* This routine resets THE_WATCHDOG timer to its state at INSERT
* time. This routine is valid only on interval watchdog timers
* and is used to make an interval watchdog timer fire "every" so
@@ -243,12 +196,7 @@ RTEMS_INLINE_ROUTINE void _Watchdog_Reset(
}
-/*PAGE
- *
- * _Watchdog_Next
- *
- * DESCRIPTION:
- *
+/**
* This routine returns a pointer to the watchdog timer following
* THE_WATCHDOG on the watchdog chain.
*/
@@ -262,12 +210,7 @@ RTEMS_INLINE_ROUTINE Watchdog_Control *_Watchdog_Next(
}
-/*PAGE
- *
- * _Watchdog_Previous
- *
- * DESCRIPTION:
- *
+/**
* This routine returns a pointer to the watchdog timer preceding
* THE_WATCHDOG on the watchdog chain.
*/
@@ -281,12 +224,7 @@ RTEMS_INLINE_ROUTINE Watchdog_Control *_Watchdog_Previous(
}
-/*PAGE
- *
- * _Watchdog_First
- *
- * DESCRIPTION:
- *
+/**
* This routine returns a pointer to the first watchdog timer
* on the watchdog chain HEADER.
*/
@@ -300,12 +238,7 @@ RTEMS_INLINE_ROUTINE Watchdog_Control *_Watchdog_First(
}
-/*PAGE
- *
- * _Watchdog_Last
- *
- * DESCRIPTION:
- *
+/**
* This routine returns a pointer to the last watchdog timer
* on the watchdog chain HEADER.
*/
@@ -319,5 +252,7 @@ RTEMS_INLINE_ROUTINE Watchdog_Control *_Watchdog_Last(
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/inline/rtems/score/wkspace.inl b/cpukit/score/inline/rtems/score/wkspace.inl
index baa6297220..d9bd16eed3 100644
--- a/cpukit/score/inline/rtems/score/wkspace.inl
+++ b/cpukit/score/inline/rtems/score/wkspace.inl
@@ -1,9 +1,12 @@
-/* wkspace.inl
+/**
+ * @file wkspace.inl
*
* This include file contains the bodies of the routines which contains
* information related to the RAM Workspace.
- *
- * COPYRIGHT (c) 1989-1999.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -16,12 +19,12 @@
#ifndef __WORKSPACE_inl
#define __WORKSPACE_inl
-/*PAGE
- *
- * _Workspace_Allocate
- *
- * DESCRIPTION:
- *
+/**
+ * @addtogroup ScoreWorkspace
+ * @{
+ */
+
+/**
* This routine returns the address of a block of memory of size
* bytes. If a block of the appropriate size cannot be allocated
* from the workspace, then NULL is returned.
@@ -34,12 +37,7 @@ RTEMS_INLINE_ROUTINE void *_Workspace_Allocate(
return _Heap_Allocate( &_Workspace_Area, size );
}
-/*PAGE
- *
- * _Workspace_Free
- *
- * DESCRIPTION:
- *
+/**
* This function frees the specified block of memory. If the block
* belongs to the Workspace and can be successfully freed, then
* TRUE is returned. Otherwise FALSE is returned.
@@ -52,5 +50,7 @@ RTEMS_INLINE_ROUTINE boolean _Workspace_Free(
return _Heap_Free( &_Workspace_Area, block );
}
+/**@}*/
+
#endif
/* end of include file */
diff --git a/cpukit/score/mainpage.h b/cpukit/score/mainpage.h
new file mode 100644
index 0000000000..9bd4051c5d
--- /dev/null
+++ b/cpukit/score/mainpage.h
@@ -0,0 +1,5 @@
+/**
+ * @mainpage
+
+This is the RTEMS SuperCore documentation.
+*/