diff --git a/doc/developer-guides/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst
index 749b38834..481423585 100644
--- a/doc/developer-guides/doc_guidelines.rst
+++ b/doc/developer-guides/doc_guidelines.rst
@@ -751,9 +751,9 @@ During the documentation ``make html`` processing, the documentation annotations
in the ``.xsd`` files are extracted and transformed into reStructuredText using
an XSLT transformation found in ``doc/scripts/configdoc.xsl``. The generated
option documentation is organized and formatted to make it easy to create links
-to specific option descriptions using an ``:option:`` role, for example,
-``:option:`hv.DEBUG_OPTIONS.BUILD_TYPE``` would link to
-:option:`hv.DEBUG_OPTIONS.BUILD_TYPE`.
+to specific option descriptions using an ``:term:`` role, for example,
+``:term::`Build type``` would link to
+:term:`Build type`.
The transformed option documentation is
created in the ``_build/rst/reference/configdoc.txt`` file and included by
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 350359676..8921490a4 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -177,7 +177,6 @@ Glossary of Terms
post-launched standard, and post-launched real-time. *(Historically, a
User VM was also called a User OS, or simply UOS.)*
- VM
Virtual Machine
A compute resource that uses software instead of physical hardware to run a
program. Multiple VMs can run independently on the same physical machine,
diff --git a/doc/reference/config-options.rst b/doc/reference/config-options.rst
index ba848e177..e3809d5fa 100644
--- a/doc/reference/config-options.rst
+++ b/doc/reference/config-options.rst
@@ -20,8 +20,7 @@ Within this option documentation, we refer to some common type
definitions:
Boolean
- A true or false value specified as either ``y`` or ``n``. Other
- values such as ``t`` or ``f`` are not supported.
+ A true or false value specified as either ``y`` or ``n``.
Hexadecimal
A base-16 (integer) value represented by a leading ``0x`` or ``0X`` followed by
@@ -36,6 +35,51 @@ String
A sequence of UTF-8 characters. String-length limits or specific
string value restrictions are defined in the option description.
+.. comment These images are used in generated option documentation
+
+.. |icon-advanced| image:: images/Advanced.svg
+ :alt: Find this option on the Configurator's Advanced Parameters tab
+.. |icon-basic| image:: images/Basic.svg
+ :alt: Find this option on the Configurator's Basic Parameters tab
+.. |icon-not-available| image:: images/Not-available.svg
+ :alt: This is a hidden option and not user-editable using the Configurator
+.. |icon-post-launched-vm| image:: images/Post-launched-VM.svg
+ :alt: Find this option on a Configurator Post-launched VM tab
+.. |icon-pre-launched-vm| image:: images/Pre-launched-VM.svg
+ :alt: Find this option on a Configurator Pre-launched VM tab
+.. |icon-service-vm| image:: images/Service-VM.svg
+ :alt: Find this option on the Configurator Service VM tab
+.. |icon-hypervisor| image:: images/Hypervisor.svg
+ :alt: Find this option on the Configurator's Hypervisor Global Settings tab
+
+We use icons within an option description to indicate where the option can be
+found within the Configurator UI:
+
+.. list-table::
+ :header-rows: 1
+
+ * - **Hypervisor/VM Tab**
+ - **Basic/Advanced Tab**
+
+ * - |icon-hypervisor|
+ Find this option on the Configurator's **Hypervisor Global Settings** tab
+ - |icon-basic|
+ Find this option on the Hypervisor's or VM's **Basic Parameters** tab
+
+ * - |icon-pre-launched-vm|
+ Find this option on a Configurator **Pre-Launched VM** tab
+ - |icon-advanced|
+ Find this option on the Hypervisor's or VM's **Advanced Parameters** tab
+
+ * - |icon-post-launched-vm|
+ Find this option on a Configurator **Post-Launched VM** tab
+ -
+
+ * - |icon-service-vm|
+ Find this option on the Configurator **Service VM** tab
+ -
+
+-----
.. comment This configdoc.txt is generated during the doc build process
from the acrn config schema files found in misc/config_tools/schema
diff --git a/doc/reference/images/Advanced.svg b/doc/reference/images/Advanced.svg
new file mode 100644
index 000000000..ab87cdc5b
--- /dev/null
+++ b/doc/reference/images/Advanced.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/Basic.svg b/doc/reference/images/Basic.svg
new file mode 100644
index 000000000..d9b5a299b
--- /dev/null
+++ b/doc/reference/images/Basic.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/Hypervisor.svg b/doc/reference/images/Hypervisor.svg
new file mode 100644
index 000000000..0e4fa83c8
--- /dev/null
+++ b/doc/reference/images/Hypervisor.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/Not-available.svg b/doc/reference/images/Not-available.svg
new file mode 100644
index 000000000..490d214e2
--- /dev/null
+++ b/doc/reference/images/Not-available.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/Post-launched-VM.svg b/doc/reference/images/Post-launched-VM.svg
new file mode 100644
index 000000000..f2206aef6
--- /dev/null
+++ b/doc/reference/images/Post-launched-VM.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/Pre-launched-VM.svg b/doc/reference/images/Pre-launched-VM.svg
new file mode 100644
index 000000000..3e87e0b22
--- /dev/null
+++ b/doc/reference/images/Pre-launched-VM.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/reference/images/README b/doc/reference/images/README
new file mode 100644
index 000000000..2557e6d0b
--- /dev/null
+++ b/doc/reference/images/README
@@ -0,0 +1,3 @@
+These icon badges were created using https://shields.io static badges.
+Standard colors were used except for the Hypervisor #69BFAD (acrn-lightgreen) and post-launched VM
+#998265 (acrn-brown) colors defined in the acrn-custom.css
diff --git a/doc/reference/images/Service-VM.svg b/doc/reference/images/Service-VM.svg
new file mode 100644
index 000000000..6ca6bd34f
--- /dev/null
+++ b/doc/reference/images/Service-VM.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/scripts/configdoc.xsl b/doc/scripts/configdoc.xsl
index 2784c433d..67e7ede7f 100644
--- a/doc/scripts/configdoc.xsl
+++ b/doc/scripts/configdoc.xsl
@@ -1,165 +1,226 @@
-
-
+
-
-
+
-
-
-
-
-
-
+
+
+
+
-
+
-
-
+
-
+
-
+
-
+
-
-
-
-
-
-
+
+
+
+
+
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ described as an option -->
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-
+
- -
-
-
-
-
-
-
-
-
- -
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+ |icon-hypervisor|
+
+
+
+
+
+ |icon-pre-launched-vm|
+
+
+ |icon-post-launched-vm|
+
+
+ |icon-service-vm|
+
+
+
+
+ |icon-pre-launched-vm|
+
+
+ |icon-post-launched-vm|
+
+
+ |icon-service-vm|
+
+
+
+
+
+ /
+
+ |icon-not-available|
+
+
+
+ |icon-basic|
+
+
+ |icon-advanced|
+
+
+
+ |icon-basic|
+
+
+ |icon-advanced|
+
+
+
+
+
+
+
+ -
+
+
+
+
+
+
+
+
+
+
+
+
+ -
+
+
+
+
+
+
+
+
+
+
+
+
+
+
--->
-
-
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+ No type annotation found
+
+
+
-
-
@@ -169,7 +230,6 @@
1
-
@@ -178,10 +238,9 @@
1
-
- The **
+ The ``
- ** option is
+ `` option is optional
@@ -190,13 +249,12 @@
required
- and with
-
+ ( occurrence
-
+ s
@@ -207,10 +265,9 @@
occurrences
- .
+ ).
-
@@ -218,11 +275,16 @@
- *(Optional)*
+ *(Optional)*
+
+
+ *(Required)**
-
+
+
+
@@ -231,16 +293,23 @@
-
+
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+
+
@@ -248,23 +317,20 @@
-
-
-
+
-
-
+
+
-
@@ -275,51 +341,39 @@
-
+
-
-
-
-
-
- .. option::
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css
index b2267f7c7..5b87d6e43 100644
--- a/doc/static/acrn-custom.css
+++ b/doc/static/acrn-custom.css
@@ -389,3 +389,31 @@ html.writer-html5 .rst-content table.docutils td p {
margin-bottom: 0;
font-size: .9rem;
}
+
+/* Simulate look of an option directive on glossary items (particularly used on
+ * config option listings so we can use a glossary to sort config options within
+ * a section of options*/
+div#scenario-configuration-options dl.glossary dt {
+ display: table;
+ margin: 6px 10px;
+ font-weight: bold;
+ color: #000;
+ line-height: normal;
+ background: #e7f2fa;
+ color: #2980b9;
+ border-top: 3px solid #6ab0de;
+ padding: 6px;
+ position: relative;
+}
+div#scenario-configuration-options dl.glossary dt {
+ float: left;
+ clear: left;
+}
+div#scenario-configuration-options dl.glossary dd>p {
+ padding-top: 12px;
+ line-height: normal;
+ clear: right;
+}
+div#scenario-configuration-options dl.glossary dd ul {
+ clear: both;
+}
diff --git a/doc/static/acrn-custom.js b/doc/static/acrn-custom.js
index 9385120ea..095da3e24 100644
--- a/doc/static/acrn-custom.js
+++ b/doc/static/acrn-custom.js
@@ -6,4 +6,9 @@ $(document).ready(function(){
/* open external links in a new tab */
$('a[class*=external]').attr({target: '_blank', rel: 'noopener'});
+
+ /* copy image alt tags in config option page as title for hover text tool tip by browser */
+ $("div#scenario-configuration-options img[alt]").each(function(){
+ $(this).attr('title', $(this).attr('alt'));
+ });
});
diff --git a/doc/tutorials/nvmx_virtualization.rst b/doc/tutorials/nvmx_virtualization.rst
index eacdf8dce..1c02e7758 100644
--- a/doc/tutorials/nvmx_virtualization.rst
+++ b/doc/tutorials/nvmx_virtualization.rst
@@ -124,7 +124,7 @@ with these settings:
#. Configure system level features:
- - Edit :option:`hv.FEATURES.SCHEDULER` to ``SCHED_NOOP`` to disable CPU sharing
+ - Edit ``hv.features.scheduler`` to ``SCHED_NOOP`` to disable CPU sharing
.. code-block:: xml
:emphasize-lines: 3,18
@@ -150,11 +150,11 @@ with these settings:
#. In each guest VM configuration:
- - Edit :option:`vm.nested_virtualization_support` on the Service VM section and set it to `y`
+ - Edit ``vm.nested_virtualization_support`` on the Service VM section and set it to `y`
to enable the nested virtualization feature on the Service VM.
- - Edit :option:`vm.lapic_passthrough` and set it to `y` to enable local
+ - Edit ``vm.lapic_passthrough`` and set it to `y` to enable local
APIC passthrough on the Service VM.
- - Edit :option:`vm.cpu_affinity.pcpu_id` to assign ``pCPU`` IDs to run the Service VM. If you are
+ - Edit ``vm.cpu_affinity.pcpu_id`` to assign ``pCPU`` IDs to run the Service VM. If you are
using debug build and need the hypervisor console, don't assign
``pCPU0`` to the Service VM.
@@ -179,7 +179,7 @@ with these settings:
the PCI-vUART for the Service VM. Refer to :ref:`Enable vUART Configurations `
for more details about VUART configuration.
- - Set :option:`vm.console_vuart` to ``PCI``
+ - Set ``vm.console_vuart`` to ``PCI``
.. code-block:: xml
:emphasize-lines: 1
diff --git a/doc/tutorials/vcat_configuration.rst b/doc/tutorials/vcat_configuration.rst
index 6d4e0befe..adb7a4f41 100644
--- a/doc/tutorials/vcat_configuration.rst
+++ b/doc/tutorials/vcat_configuration.rst
@@ -13,12 +13,12 @@ into XML in the scenario file:
#. Configure system level features:
- - Edit :option:`hv.FEATURES.RDT.RDT_ENABLED` to `y` to enable RDT
+ - Edit ``hv.FEATURES.RDT.RDT_ENABLED`` to `y` to enable RDT
- - Edit :option:`hv.FEATURES.RDT.CDP_ENABLED` to `n` to disable CDP.
+ - Edit ``hv.FEATURES.RDT.CDP_ENABLED`` to `n` to disable CDP.
vCAT requires CDP to be disabled.
- - Edit :option:`hv.FEATURES.RDT.VCAT_ENABLED` to `y` to enable vCAT
+ - Edit ``hv.FEATURES.RDT.VCAT_ENABLED`` to `y` to enable vCAT
.. code-block:: xml
:emphasize-lines: 3,4,5
@@ -34,9 +34,9 @@ into XML in the scenario file:
#. In each Guest VM configuration:
- - Edit :option:`vm.virtual_cat_support` to 'y' to enable the vCAT feature on the VM.
+ - Edit ``vm.virtual_cat_support`` to 'y' to enable the vCAT feature on the VM.
- - Edit :option:`vm.clos.vcpu_clos` to assign COS IDs to the VM.
+ - Edit ``vm.clos.vcpu_clos`` to assign COS IDs to the VM.
If ``GUEST_FLAG_VCAT_ENABLED`` is not specified for a VM (abbreviated as RDT VM):
``vcpu_clos`` is per CPU in a VM and it configures each CPU in a VM to a desired COS ID.