diff options
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 36 | ||||
| -rw-r--r-- | c-user/semaphore_manager.rst | 6 | ||||
| -rw-r--r-- | common/conf.py | 17 | ||||
| -rw-r--r-- | common/latex.py | 7 | ||||
| -rw-r--r-- | common/rtemsdomain.py | 64 | ||||
| -rw-r--r-- | common/version.py | 5 | ||||
| -rw-r--r-- | common/waf.py | 26 | ||||
| -rw-r--r-- | eng/vc-users.rst | 83 |
8 files changed, 196 insertions, 48 deletions
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index 297c624..a779c9f 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 1988, 2008, 2021 On-Line Applications Research Corporation (OAR) Task Stack Allocator Configuration ================================== @@ -171,3 +171,37 @@ DESCRIPTION: NOTES: This configuration option may be used if a custom task stack allocator is configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. index:: _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +.. index:: IDLE task stack allocator + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE: + +CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +--------------------------------------- + +CONSTANT: + ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +OPTION TYPE: + This configuration option is an initializer define. + +DEFAULT VALUE: + The default value is ``_Stack_Allocator_allocate_for_idle``, which + indicates that IDLE task stacks will be allocated from an area statically + reserved by `<rtems/confdefs.h>``. + +VALUE CONSTRAINTS: + The value of this configuration option shall be defined to a valid + function pointer of the type ``void *( *allocate )( uint32_t, size_t )``. + +DESCRIPTION: + The value of this configuration option is the address for the the + IDLE stack allocator allocate handler. + +NOTES: + This configuration option is independent of the other thread stack allocator + configuration options. It is assumed that any memory allocated for IDLE + task stacks will not be from the RTEMS Workspace or the memory statically + reserved by default. + diff --git a/c-user/semaphore_manager.rst b/c-user/semaphore_manager.rst index 31a3c79..b99d384 100644 --- a/c-user/semaphore_manager.rst +++ b/c-user/semaphore_manager.rst @@ -377,9 +377,9 @@ NOTES: This directive may cause the calling task to be preempted due to an obtain and release of the object allocator mutex. - The priority inheritance and priority ceiling algorithms are only supported - for local, binary semaphores that use the priority task wait queue blocking - discipline. + The priority inheritance, priority ceiling, and MrsP algorithms are only + supported for local, binary semaphores that use the priority task wait + queue blocking discipline. The following semaphore attribute constants are defined by RTEMS: diff --git a/common/conf.py b/common/conf.py index 257bc4e..565e06d 100644 --- a/common/conf.py +++ b/common/conf.py @@ -1,4 +1,4 @@ -import version as rtems_version +import datetime extensions = [ "sphinx.ext.autodoc", @@ -12,6 +12,8 @@ extensions = [ "rtemsdomain", ] +bibtex_bibfiles = ['../common/refs.bib'] + extlinks = {'release_path': ('https://ftp.rtems.org/pub/rtems/releases', None) } # Add any paths that contain templates here, relative to this directory. @@ -28,21 +30,17 @@ master_doc = 'index' # General information about the project. project = u'RTEMS Documentation Project' -copyright = u'1988, 2020 RTEMS Project and contributors' +copyright = u'1988, ' + str(datetime.datetime.now().year) + ' RTEMS Project and contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = rtems_version.version() +#version = rtems_version.version() # The full version, including alpha/beta/rc tags. -release = rtems_version.string() - -major = rtems_version.major() -minor = rtems_version.minor() -revision = rtems_version.revision() +#release = rtems_version.string() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -75,6 +73,9 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig +numfig = True + # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] diff --git a/common/latex.py b/common/latex.py index a042510..17d3015 100644 --- a/common/latex.py +++ b/common/latex.py @@ -3,7 +3,6 @@ # import os -import platform import re package_test_preamble = ['\\newif\\ifsphinxKeepOldNames \\sphinxKeepOldNamestrue', @@ -82,7 +81,11 @@ def tex_test(test): def host_name(): uname = os.uname() if uname[0] == 'Linux': - distro = platform.dist() + try: + from distro import linux_distribution + except: + from platform import linux_distribution + distro = linux_distribution() name = '%s/%s' % (uname[0], distro[0]) version = distro[1] else: diff --git a/common/rtemsdomain.py b/common/rtemsdomain.py index 9b092a3..630f1e3 100644 --- a/common/rtemsdomain.py +++ b/common/rtemsdomain.py @@ -8,6 +8,8 @@ from sphinx.domains import Domain, ObjType, Index from sphinx.util.nodes import make_refnode from sphinx.util.docfields import Field, TypedField +import version as rtems_version + """ :r:bsp:`sparc/sis` @@ -30,28 +32,28 @@ role_name = { } role_url = { - "trac": ("Trac", "https://devel.rtems.org"), - "devel": ("Developer Site", "https://devel.rtems.org"), - "www": ("RTEMS Home", "https://www.rtems.org/"), - "buildbot": ("Buildbot Instance", "https://buildbot.rtems.org/"), - "builder": ("Builder Site", "https://builder.rtems.org/"), - "docs": ("Documentation Site", "https://docs.rtems.org/"), - "lists": ("Mailing Lists", "https://lists.rtems.org/"), - "git": ("Git Repositories", "https://git.rtems.org/"), - "ftp": ("FTP File Server", "https://ftp.rtems.org/"), - "review": ("Gerrit Code Review", "https://review.rtems.org/"), - "bugs": ("Bugs Database", "https://devel.rtems.org/wiki/Bugs/"), - "gsoc": ("Google Summer of Code", "https://devel.rtems.org/wiki/GSoC/"), - "socis": ("ESA SOCIS", "https://devel.rtems.org/wiki/SOCIS/") + "trac": ("Trac", "https://devel.rtems.org"), + "devel": ("Developer Site", "https://devel.rtems.org"), + "www": ("RTEMS Home", "https://www.rtems.org/"), + "buildbot": ("Buildbot Instance", "https://buildbot.rtems.org/"), + "builder": ("Builder Site", "https://builder.rtems.org/"), + "docs": ("Documentation Site", "https://docs.rtems.org/"), + "lists": ("Mailing Lists", "https://lists.rtems.org/"), + "git": ("Git Repositories", "https://git.rtems.org/"), + "ftp": ("FTP File Server", "https://ftp.rtems.org/"), + "review": ("Gerrit Code Review", "https://review.rtems.org/"), + "bugs": ("Bugs Database", "https://devel.rtems.org/wiki/Bugs/"), + "gsoc": ("Google Summer of Code", "https://devel.rtems.org/wiki/GSoC/"), + "socis": ("ESA SOCIS", "https://devel.rtems.org/wiki/SOCIS/") } role_list = { - "announce": ("Announce Mailing List", "https://lists.rtems.org/mailman/listinfo/announce/"), - "bugs": ("Bugs Mailing List", "https://lists.rtems.org/mailman/listinfo/bugs/"), - "devel": ("Developers Mailing List", "https://lists.rtems.org/mailman/listinfo/devel/"), - "build": ("Build Logs", "https://lists.rtems.org/mailman/listinfo/build"), - "users": ("Users Mailing List", "https://lists.rtems.org/mailman/listinfo/users/"), + "announce": ("Announce Mailing List", "https://lists.rtems.org/mailman/listinfo/announce/"), + "bugs": ("Bugs Mailing List", "https://lists.rtems.org/mailman/listinfo/bugs/"), + "devel": ("Developers Mailing List", "https://lists.rtems.org/mailman/listinfo/devel/"), + "build": ("Build Logs", "https://lists.rtems.org/mailman/listinfo/build"), + "users": ("Users Mailing List", "https://lists.rtems.org/mailman/listinfo/users/"), "vc": ("Version Control Mailing List", "https://lists.rtems.org/mailman/listinfo/vc/"), } @@ -119,7 +121,33 @@ class RTEMSDomain(Domain): pass # XXX is this needed? +def rtems_replace(app, docname, source): + dump = False + line = source[0] + for key in app.config.replacements: + line = line.replace(key, app.config.replacements[key]) + source[0] = line + +replacements = { +} def setup(app): + app.add_config_value('rtems_major', str(app.config.overrides['rtems_major']), True) + app.add_config_value('rtems_minor', str(app.config.overrides['rtems_minor']), True) + app.add_config_value('rtems_revision', str(app.config.overrides['rtems_revision']), True) + major = str(app.config.overrides['rtems_major']) + minor = str(app.config.overrides['rtems_minor']) + revision = str(app.config.overrides['rtems_revision']) + if revision.isdigit(): + majminrev = major + '.' + minor + '.' + revision + else: + majminrev = major + '.' + revision + replacements["@rtems-version@"] = str(app.config.overrides['version']) + replacements["@rtems-ver-major@"] = major + replacements["@rtems-ver-minor@"] = minor + replacements["@rtems-ver-revision@"] = revision + replacements["@rtems-ver-majminrev@"] = majminrev + app.add_config_value('replacements', replacements, True) + app.connect('source-read', rtems_replace) app.add_domain(RTEMSDomain) return {'version': "1.0", 'parallel_read_safe': True} diff --git a/common/version.py b/common/version.py index 281c880..bfe0e1b 100644 --- a/common/version.py +++ b/common/version.py @@ -111,6 +111,9 @@ def _pretty_day(ctx, date): def get(ctx, rtems_major_version): global _version + global _major + global _minor + global _revision global _date global _released version = _version @@ -184,7 +187,7 @@ def minor(): return _minor def revision(): - return revision + return _revision def date(): return _date diff --git a/common/waf.py b/common/waf.py index 7027eb6..0bd166a 100644 --- a/common/waf.py +++ b/common/waf.py @@ -181,13 +181,18 @@ def check_sphinx_extension(ctx, extension): def run_sphinx(bld): rst_node = bld.srcnode.make_node('testbuild/contents.rst') rst_node.parent.mkdir() - rst_node.write('.. COMMENT test sphinx\n') + rst_node.write('.. COMMENT test sphinx' + os.linesep) + bib_node = bld.srcnode.make_node('testbuild/refs.bib') + bib_node.write(os.linesep) + conf_node = bld.srcnode.make_node('testbuild/conf.py') + conf_node.write(os.linesep.join(["master_doc='contents'", + "bibtex_bibfiles = ['refs.bib']"])) bld(rule = bld.kw['rule'], source = rst_node) ctx.start_msg("Checking for '%s'" % (extension)) try: ctx.run_build(fragment = 'xx', - rule = "${BIN_SPHINX_BUILD} -b html -D extensions=%s -C . out" % (extension), + rule = "${BIN_SPHINX_BUILD} -b html -D extensions=%s -c . . out" % (extension), build_fun = run_sphinx, env = ctx.env) except ctx.errors.ConfigurationError: @@ -266,27 +271,27 @@ def cmd_configure(ctx): ctx.fatal('Unsupported latex engine: %s' % (conf.latex_engine)) ctx.env.BUILD_PDF = 'yes' - ctx.envBUILD_SINGLEHTML = 'no' + ctx.env.BUILD_SINGLEHTML = 'no' if ctx.options.singlehtml: check_inliner = not ctx.env.BIN_INLINER if check_inliner: - ctx.env.BUILD_SINGLEHTML = 'yes' ctx.find_program("inliner", var = "BIN_INLINER", mandatory = False) if not ctx.env.BIN_INLINER: ctx.fatal("Node.js inliner is required install with 'npm install -g inliner' " + "(https://github.com/remy/inliner)") + ctx.env.BUILD_SINGLEHTML = 'yes' - ctx.envBUILD_PLANTUML = 'no' + ctx.env.BUILD_PLANTUML = 'no' if ctx.options.plantuml: check_plantuml = not ctx.env.BIN_PUML if check_plantuml: - ctx.env.BUILD_PLANTUML = 'yes' ctx.find_program("puml", var = "BIN_PUML", mandatory = False) if not ctx.env.BIN_PUML: ctx.fatal("Node.js puml is required install with 'npm install -g node-plantuml' " + "(https://www.npmjs.com/package/node-plantuml)") + ctx.env.BUILD_PLANTUML = 'yes' - ctx.envBUILD_DITAA = 'no' + ctx.env.BUILD_DITAA = 'no' if ctx.options.ditaa: # # We use DITAA via PlantUML @@ -299,10 +304,10 @@ def cmd_configure(ctx): "(https://www.npmjs.com/package/node-plantuml)") check_ditaa = not ctx.env.BIN_DITAA if check_ditaa: - ctx.env.BUILD_DITAA = 'yes' ctx.find_program("ditaa", var = "BIN_DITAA", mandatory = False) if not ctx.env.BIN_DITAA: ctx.fatal("DITAA not found, plase install") + ctx.env.BUILD_DITAA = 'yes' def sources_exclude(ctx, sources): exclude = sources.get('exclude', []) @@ -335,12 +340,15 @@ def doc_pdf(ctx, source_dir, conf_dir, sources): target = ctx.path.find_or_declare("%s/%s.tex" % (buildtype, ctx.path.name)) ) + env_latex = ctx.env.derive() + env_latex.TEXINPUTS = output_dir + ':' ctx( features = 'tex', cwd = output_dir, type = ctx.env.LATEX_CMD, source = "%s/%s.tex" % (buildtype, ctx.path.name), - prompt = 0 + prompt = 0, + env = env_latex ) ctx.install_files('${PREFIX}', '%s/%s.pdf' % (buildtype, ctx.path.name), diff --git a/eng/vc-users.rst b/eng/vc-users.rst index 31de516..0ef7a66 100644 --- a/eng/vc-users.rst +++ b/eng/vc-users.rst @@ -422,20 +422,91 @@ then you rewrite those commits with ``git rebase`` and push them up again, the others will have to re-merge their work and trying to integrate their work into yours can become messy. -Accessing a developer's repository +Accessing a Developer's Repository ---------------------------------- RTEMS developers with Git commit access have personal repositories on https://git.rtems.org/ that can be cloned to view cutting-edge development work shared there. +Commit Message Guidance +----------------------- + +The commit message associated with a change to any software project +is of critical importance. It is the explanation of the change and the +rationale for it. Future users looing back through the project history +will rely on it. Even the author of the change will likely rely on it +once they have forgotten the details of the change. It is important to +make the message useful. Here are some guidelines followed by the RTEMS +Project to help improve the quality of our commit messages. + +* When committing a change the first line is a summary. Please make it short + while hinting at the nature of the change. You can discuses the change + if you wish in a ticket that has a PR number which can be referenced in + the commit message. After the first line, leave an empty line and add + whatever required details you feel are needed. + +* Patches should be as single purpose as possible. This is reflected in + the first line summary message. If you find yourself writing something + like "Fixed X and Y", "Updated A and B", or similar, then evaluate + whether the patch should really be a patch series rather than a single + larger patch. + +* Format the commit message so it is readable and clear. If you have + specific points related to the change make them with separate paragraphs + and if you wish you can optionally uses a `-` marker with suitable + indents and alignment to aid readability. + +* Limit the line length to less than 80 characters + +* Please use a real name with a valid email address. Please do not use + pseudonyms or provide anonymous contributions. + +* Please do not use terms such as "Fix bug", "With this change it + works", or "Bump hash". If you fix a bug please state the nature of the + bug and why this change fixes it. If a change makes something work then + detail the reason. You do not need to explain the change line by line + as the commits diff and associated ticket will. + +* If you change the formatting of source code in a repository please + make that a separate patch and use "Formatting changes only" on the first + line. Please indicate the reason or process. For example to "Conforming + to code standing", "Reverting to upstream format", "Result of automatic + formatting". + +* Similarly, if addressing a spelling, grammar, or Doxygen issue, please + put that in a commit by itself separate from technical changes. + +An example commit message: + +.. code-block:: shell + + test/change: Test message on formatting of commits + + - Shows a simple single first line + + - Has an empty second line + + - Shows the specifics of adding separate points in the commit message as + separate paragraphs. It also shows a `-` separator and multilines + that are less than the 80 character width + + - Show a ticket update and close + + Updates #9876 + Closes #8765 + +The first line generally starts with a file or directory name which +indicates the area in RTEMS to which the commit applies. For a patch +series which impacts multiple BSPs, it is common to put each BSP into +a separate patch. This improves the quality and specificity of the +commit messages. + Creating a Patch ----------------- +----------------- -Before submitting a patch read about `Contributing -<https://devel.rtems.org/wiki/Developer/Contributing>`_ to RTEMS and the -`Commit Message <https://devel.rtems.org/wiki/Developer/Git#GitCommits>`_ -formatting we require. +Before submitting a patch, please read `Commit Message Guidance`_ to +become familiar with the commit message formatting we require. The recommended way to create a patch is to branch the Git repository master and use one commit for each logical change. Then you can use |