From baff4dafe1ff85d128a55e7b73780ca28f5c7faf Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 1 Nov 2004 13:22:41 +0000 Subject: 2004-11-01 Joel Sherrill * score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/copyrt.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremsg.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/mppkt.inl, score/inline/rtems/score/objectmp.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/states.inl, score/inline/rtems/score/sysstate.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/threadmp.inl, score/inline/rtems/score/tod.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/watchdog.inl, score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working modifications which are not complete and may have broken code. Committing so work and testing can proceed. * score/Doxyfile, score/mainpage.h: New files. --- cpukit/ChangeLog | 52 ++ cpukit/score/Doxyfile | 1078 +++++++++++++++++++++++++ cpukit/score/cpu/no_cpu/rtems/score/cpu.h | 763 ++++++++++------- cpukit/score/include/rtems/debug.h | 10 +- cpukit/score/include/rtems/score/address.h | 19 +- cpukit/score/include/rtems/score/apiext.h | 112 +-- cpukit/score/include/rtems/score/apimutex.h | 88 +- cpukit/score/include/rtems/score/bitfield.h | 69 +- cpukit/score/include/rtems/score/chain.h | 163 ++-- cpukit/score/include/rtems/score/context.h | 125 +-- cpukit/score/include/rtems/score/copyrt.h | 18 +- cpukit/score/include/rtems/score/coremsg.h | 251 ++++-- cpukit/score/include/rtems/score/coremutex.h | 223 +++-- cpukit/score/include/rtems/score/coresem.h | 115 ++- cpukit/score/include/rtems/score/heap.h | 232 +++--- cpukit/score/include/rtems/score/interr.h | 32 +- cpukit/score/include/rtems/score/isr.h | 124 +-- cpukit/score/include/rtems/score/mpci.h | 206 ++--- cpukit/score/include/rtems/score/mppkt.h | 50 +- cpukit/score/include/rtems/score/objectmp.h | 56 +- cpukit/score/include/rtems/score/priority.h | 22 +- cpukit/score/include/rtems/score/stack.h | 18 +- cpukit/score/include/rtems/score/states.h | 18 +- cpukit/score/include/rtems/score/sysstate.h | 18 +- cpukit/score/include/rtems/score/thread.h | 400 ++++----- cpukit/score/include/rtems/score/threadmp.h | 54 +- cpukit/score/include/rtems/score/threadq.h | 135 +--- cpukit/score/include/rtems/score/tod.h | 198 +++-- cpukit/score/include/rtems/score/tqdata.h | 18 +- cpukit/score/include/rtems/score/userext.h | 133 +-- cpukit/score/include/rtems/score/watchdog.h | 166 ++-- cpukit/score/include/rtems/score/wkspace.h | 45 +- cpukit/score/include/rtems/seterr.h | 9 +- cpukit/score/include/rtems/system.h | 11 +- cpukit/score/inline/rtems/score/address.inl | 53 +- cpukit/score/inline/rtems/score/chain.inl | 174 +--- cpukit/score/inline/rtems/score/coremsg.inl | 100 +-- cpukit/score/inline/rtems/score/coremutex.inl | 61 +- cpukit/score/inline/rtems/score/coresem.inl | 57 +- cpukit/score/inline/rtems/score/heap.inl | 116 +-- cpukit/score/inline/rtems/score/isr.inl | 31 +- cpukit/score/inline/rtems/score/mppkt.inl | 32 +- cpukit/score/inline/rtems/score/objectmp.inl | 37 +- cpukit/score/inline/rtems/score/priority.inl | 93 +-- cpukit/score/inline/rtems/score/stack.inl | 39 +- cpukit/score/inline/rtems/score/states.inl | 164 +--- cpukit/score/inline/rtems/score/sysstate.inl | 72 +- cpukit/score/inline/rtems/score/thread.inl | 172 +--- cpukit/score/inline/rtems/score/threadmp.inl | 30 +- cpukit/score/inline/rtems/score/tod.inl | 37 +- cpukit/score/inline/rtems/score/tqdata.inl | 39 +- cpukit/score/inline/rtems/score/userext.inl | 53 +- cpukit/score/inline/rtems/score/watchdog.inl | 121 +-- cpukit/score/inline/rtems/score/wkspace.inl | 30 +- cpukit/score/mainpage.h | 5 + 55 files changed, 3749 insertions(+), 2798 deletions(-) create mode 100644 cpukit/score/Doxyfile create mode 100644 cpukit/score/mainpage.h diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog index 2292406292..4aba741237 100644 --- a/cpukit/ChangeLog +++ b/cpukit/ChangeLog @@ -1,3 +1,55 @@ +2004-11-01 Joel Sherrill + + * score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h, + score/include/rtems/seterr.h, score/include/rtems/system.h, + score/include/rtems/score/address.h, + score/include/rtems/score/apiext.h, + score/include/rtems/score/apimutex.h, + score/include/rtems/score/bitfield.h, + score/include/rtems/score/chain.h, + score/include/rtems/score/context.h, + score/include/rtems/score/copyrt.h, + score/include/rtems/score/coremsg.h, + score/include/rtems/score/coremutex.h, + score/include/rtems/score/coresem.h, + score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, + score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, + score/include/rtems/score/mppkt.h, + score/include/rtems/score/objectmp.h, + score/include/rtems/score/priority.h, + score/include/rtems/score/stack.h, + score/include/rtems/score/states.h, + score/include/rtems/score/sysstate.h, + score/include/rtems/score/thread.h, + score/include/rtems/score/threadmp.h, + score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, + score/include/rtems/score/tqdata.h, + score/include/rtems/score/userext.h, + score/include/rtems/score/watchdog.h, + score/include/rtems/score/wkspace.h, + score/inline/rtems/score/address.inl, + score/inline/rtems/score/chain.inl, + score/inline/rtems/score/coremsg.inl, + score/inline/rtems/score/coremutex.inl, + score/inline/rtems/score/coresem.inl, + score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, + score/inline/rtems/score/mppkt.inl, + score/inline/rtems/score/objectmp.inl, + score/inline/rtems/score/priority.inl, + score/inline/rtems/score/stack.inl, + score/inline/rtems/score/states.inl, + score/inline/rtems/score/sysstate.inl, + score/inline/rtems/score/thread.inl, + score/inline/rtems/score/threadmp.inl, + score/inline/rtems/score/tod.inl, + score/inline/rtems/score/tqdata.inl, + score/inline/rtems/score/userext.inl, + score/inline/rtems/score/watchdog.inl, + score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working + modifications which are not complete and may have broken code. + Committing so work and testing can proceed. + * score/Doxyfile, score/mainpage.h: New files. + 2004-11-01 Joel Sherrill * score/include/rtems/score/object.h, 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 , where +# is the value of the INPUT_FILTER tag, and 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 #include -/* - * 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 #include -/* - * 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 -/* +/** + * @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 -/* - * 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 #include -/* +/** * 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 #include -/* +/** * 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 #include -/* +/** * 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 #include -/* +/** * 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 #include -/* +/** * 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 #include -/* +/** * 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 #include -/* +/** @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 #include -/* +/** @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 -/* +/** @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 #include -/* - * 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 /* 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 #include -/*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 -/*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 -/*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 -/*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. +*/ -- cgit v1.2.3