doc: update release branch with new docs

Signed-off-by: David B. Kinder <[email protected]>

Author: dbkinder

doc/.known-issues/doc/dupdecl.conf

@@ -6,5 +6,9 @@
 # Sphinx 2.0
 ^(?P<filename>[-._/\w]+/hld/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration, .*
 #
+^(?P<filename>[-._/\w]+/api/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: duplicate C object description.*
+#
+^(?P<filename>[-._/\w]+/hld/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: duplicate C object description.*
+#
 ^(?P<filename>[-._/\w]+/hld/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: Duplicate C\+\+ declaration, .*
 ^Declaration is .*

doc/asa.rst

@@ -1,8 +1,24 @@
- .. _asa:
+.. _asa:
 
 Security Advisory
 #################
 
+Addressed in ACRN v2.3
+************************
+
+We recommend that all developers upgrade to this v2.3 release (or later), which
+addresses the following security issue that was discovered in previous releases:
+
+------
+
+- NULL Pointer Dereference in ``devicemodel\hw\pci\virtio\virtio_mei.c``
+   ``vmei_proc_tx()`` function tries to find the ``iov_base`` by calling
+   function ``paddr_guest2host()``, which may return NULL (the ``vd``
+   struct control by the User VM OS).  There is a use of ``iov_base``
+   afterward that can cause a NULL pointer dereference (CVE-2020-28346).
+
+   **Affected Release:** v2.2 and earlier.
+
 Addressed in ACRN v2.1
 ************************
 

doc/conf.py

@@ -37,7 +37,7 @@
 sys.path.insert(0, os.path.join(os.path.abspath('.'), 'extensions'))
 extensions = [
    'breathe', 'sphinx.ext.graphviz', 'sphinx.ext.extlinks',
-   'kerneldoc', 'eager_only', 'html_redirects',
+   'kerneldoc', 'eager_only', 'html_redirects', 'link_roles',
    'sphinx_tabs.tabs'
 ]
 
@@ -166,7 +166,7 @@
         'analytics_id': '',
         'logo_only': False,
         'display_version': True,
-        'prev_next_buttons_location': 'None',
+        #'prev_next_buttons_location': 'None',
         # Toc options
         'collapse_navigation': False,
         'sticky_navigation': True,
@@ -318,7 +318,21 @@ def setup(app):
 	"Project ACRN" : "doxygen/xml",
 }
 breathe_default_project = "Project ACRN"
-breathe_default_members = ('members', 'undoc-members', 'content-only')
+# breathe_default_members = ('members', 'undoc-members', 'content-only')
+breathe_domain_by_extension = {
+   "h": "c",
+   "c": "c",
+}
+
+cpp_id_attributes = [
+    '__syscall', '__deprecated', '__may_alias',
+    '__used', '__unused', '__weak',
+    '__DEPRECATED_MACRO', 'FUNC_NORETURN',
+    '__subsystem',
+]
+c_id_attributes = cpp_id_attributes
+
+
 
 
 # Custom added feature to allow redirecting old URLs (caused by

doc/develop.rst

@@ -72,6 +72,7 @@ Enable ACRN Features
    tutorials/setup_openstack_libvirt
    tutorials/acrn_on_qemu
    tutorials/using_grub
+   tutorials/acrn-secure-boot-with-grub
    tutorials/pre-launched-rt
    tutorials/enable_ivshmem
 

doc/developer-guides/contribute_guidelines.rst

@@ -20,7 +20,7 @@ software continues to be available under the terms that the author
 desired.
 
 Project ACRN uses a BSD-3-Clause license, as found in the
-`LICENSE <https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE>`__
+:acrn_file:`LICENSE <LICENSE>`
 in the project's GitHub repo.
 
 A license tells you what rights you have as a developer, as provided by
@@ -221,14 +221,12 @@ following exceptions:
   8-column wide.
 
 You can use *checkpatch* from Linux kernel to check the compliance. ACRN
-maintains a `checkpatch conf`_ which customizes the script to stop warning on
+maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file
+that customizes the script to stop warnings on
 the exceptions above. Invoke *checkpatch* with the root of ``acrn-hypervisor``
 repository as the current working directory to make the configurations
 effective.
 
-.. _checkpatch conf:
-   https://github.com/projectacrn/acrn-hypervisor/blob/master/.checkpatch.conf
-
 .. _Contribution workflow:
 
 Contribution Workflow

doc/developer-guides/doc_guidelines.rst

@@ -297,6 +297,17 @@ markup (double backticks) to indicate a ``filename``.
 
 Don't use items within a single backtick, for example ```word```.
 
+For references to files that are in the ACRN Hypervisor GitHub tree, a special
+role can be used that creates a hyperlink to that file. For example a
+GitHub link to the reST file used to create this document can be generated
+using ``:acrn_file:`doc/developer-guides/doc_guidelines.rst``` that will show
+up as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to
+the “blob” file in the GitHub repo as displayed by GitHub. There’s also an
+``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link
+to the “raw” uninterpreted file,
+:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click
+on these links to see the difference.)
+
 .. _internal-linking:
 
 Internal Cross-Reference Linking

doc/developer-guides/hld/ivshmem-hld.rst

@@ -37,24 +37,40 @@ may only be done between VMs using the same solution.
 ivshmem hv:
    The **ivshmem hv** implements register virtualization
    and shared memory mapping in the ACRN hypervisor.
-   It will support notification/interrupt mechanism in the future.
+   Notification/interrupt mechanism is supported.
 
 ivshmem dm:
    The **ivshmem dm** implements register virtualization
    and shared memory mapping in the ACRN Device Model (``acrn-dm``).
    It will support notification/interrupt mechanism in the future.
 
 ivshmem server:
-   A daemon for inter-VM notification capability that will work with **ivshmem
-   dm**. This is currently **not implemented**, so the inter-VM communication
-   doesn't support a notification mechanism.
+   With **ivshmem server** support, VMs with ivshmem devices enabled can send
+   notification (interrupt) to each other by writing the target peer ID (VM ID)
+   and vector index to the doorbell register of ivshmem device, **ivshmem server**
+   forwards this notification event to target VM.
+
+   Two types of **ivshmem server** are defined in ACRN:
+
+   User land **ivshmem server** is a daemon in user space to forward notifications
+   for **dm-land** ivshmem devices only, by co-working with **ivshmem dm**.
+   User land **ivshmem server** is not implemented.
+
+   HV-land **ivshmem server** plays similar role with user land **ivshmem server**,
+   but it is a hypervisor module and forwards notification (virtual interrupt) to
+   target VM with  **hv-land** ivshmem devices enabled.
 
 Ivshmem Device Introduction
 ***************************
 
-The ``ivshmem`` device is a virtual standard PCI device consisting of
-two Base Address Registers (BARs): BAR0 is used for emulating interrupt
-related registers, and BAR2 is used for exposing shared memory region. The ``ivshmem`` device doesn't support any extra capabilities.
+   The ``ivshmem`` device is a virtual standard PCI device consisting of
+   three Base Address Registers (BARs):
+
+   * BAR0 is used for emulating interrupt related registers,
+   * BAR1 is used for emulating MSIX entry table, and
+   * BAR2 is used for exposing a shared memory region.
+
+  The ``ivshmem`` device supports no extra capabilities.
 
 Configuration Space Definition
 

doc/developer-guides/hld/virtio-net.rst

@@ -426,10 +426,11 @@ our case, we use systemd to automatically create the network by default.
 You can check the files with prefix 50- in the Service VM
 ``/usr/lib/systemd/network/``:
 
-- `50-acrn.netdev <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/acrn.netdev>`__
-- `50-acrn.network <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/acrn.network>`__
-- `50-tap0.netdev <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/tap0.netdev>`__
-- `50-eth.network <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/eth.network>`__
+- :acrn_raw:`50-acrn.netdev <misc/acrnbridge/acrn.netdev>`
+- :acrn_raw:`50-acrn.netdev <misc/acrnbridge/acrn.netdev>`
+- :acrn_raw:`50-acrn.network <misc/acrnbridge/acrn.network>`
+- :acrn_raw:`50-tap0.netdev <misc/acrnbridge/tap0.netdev>`
+- :acrn_raw:`50-eth.network <misc/acrnbridge/eth.network>`
 
 When the Service VM is started, run ``ifconfig`` to show the devices created by
 this systemd configuration:

doc/extensions/eager_only.py

@@ -30,7 +30,7 @@ def run(self, *args):
         # Evaluate the condition eagerly, and if false return no nodes right away
         env = self.state.document.settings.env
         env.app.builder.tags.add('TRUE')
-        #print(repr(self.arguments[0]))
+
         if not env.app.builder.tags.eval_condition(self.arguments[0]):
             return []
 
@@ -43,3 +43,13 @@ def run(self, *args):
 
 def setup(app):
     directives.register_directive('only', EagerOnly)
+
+    # The tags.add call above is setting tags.tags['TRUE'] = True.
+    # The operation is idempotent and will have taken effect before
+    # the next eval_condition() which may rely on it so this is thread
+    # safe both for read and writes (all other operations are local to
+    # the local nodes variable).
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+        }

doc/extensions/link_roles.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2019 Intel Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# based on http://protips.readthedocs.io/link-roles.html
+
+from __future__ import print_function
+from __future__ import unicode_literals
+import re
+import os
+import os.path
+from os import path
+import subprocess
+from docutils import nodes
+
+
+def run_cmd_get_output(cmd):
+    try:
+        with open(os.devnull, 'w') as devnull:
+            output = subprocess.check_output(cmd, stderr=devnull, shell=True).strip()
+    except subprocess.CalledProcessError as e:
+        output = e.output.decode('ascii')
+
+    return output
+
+def get_github_rev():
+    tag = run_cmd_get_output('git describe --exact-match')
+    if tag:
+        return tag.decode("utf-8")
+    else:
+        return 'master'
+
+
+def setup(app):
+    rev = get_github_rev()
+
+    baseurl = 'https://github.com/projectacrn/acrn-hypervisor'
+
+    app.add_role('acrn_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
+    app.add_role('acrn_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
+
+    # The role just creates new nodes based on information in the
+    # arguments; its behavior doesn't depend on any other documents.
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+
+def autolink(pattern):
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        m = re.search(r'(.*)\s*<(.*)>', text)
+        if m:
+            link_text = m.group(1)
+            link = m.group(2)
+        else:
+            link_text = text
+            link = text
+        url = pattern % (link,)
+        node = nodes.reference(rawtext, link_text, refuri=url, **options)
+        return [node], []
+    return role