Skip to contentSkip to conversation

Use Doxygen and sphinx for html documentation

PATCH Superseded Luca Fancellu 3 participants 12 messages Apr 26, 2021 – Apr 29, 2021

v3 of 7 Superseded Latest is v7 →

lore
Share & tools
lore
#0 lore raw

v3 cover Use Doxygen and sphinx for html documentation

This serie introduce doxygen in the sphinx html docs generation. One benefit is to keep most of the documentation in the source files of xen so that it's more maintainable, on the other hand there are some limitation of doxygen that should be addressed modifying the current codebase (for example doxygen can't parse anonymous structure/union).

To reproduce the documentation xen must be compiled because most of the headers are generated on compilation time from the makefiles.

Here follows the steps to generate the sphinx html docs, some package may be required on your machine, everything is suggested by the autoconf script.
Here I'm building the arm64 docs (the only introduced for now by this serie):

./configure
make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" menuconfig make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" make -C docs XEN_TARGET_ARCH="arm64" sphinx-html

now in docs/sphinx/html/ we have the generated docs starting from the index.html page.

Luca Fancellu (3):
docs: add doxygen support for html documentation
docs: hypercalls sphinx skeleton for generated html docs/doxygen: doxygen documentation for grant_table.h

 .gitignore                                    |    7 +
 config/Docs.mk.in                             |    2 +
 docs/Makefile                                 |   46 +-
 docs/conf.py                                  |   48 +-
 docs/configure                                |  258 ++
 docs/configure.ac                             |   15 +
 docs/hypercall-interfaces/arm32.rst           |    4 +
 docs/hypercall-interfaces/arm64.rst           |   33 +
 .../arm64/grant_tables.rst                    |    8 +
 docs/hypercall-interfaces/index.rst.in        |    7 +
 docs/hypercall-interfaces/x86_64.rst          |    4 +
 docs/index.rst                                |    8 +
 docs/xen-doxygen/customdoxygen.css            |   36 +
 docs/xen-doxygen/doxy-preprocessor.py         |  110 +
 docs/xen-doxygen/doxy_input.list              |    1 +
 docs/xen-doxygen/doxygen_include.h.in         |   32 +
 docs/xen-doxygen/footer.html                  |   21 +
 docs/xen-doxygen/header.html                  |   56 +
 docs/xen-doxygen/mainpage.md                  |    5 +
 docs/xen-doxygen/xen_project_logo_165x67.png  |  Bin 0 -> 18223 bytes
 docs/xen.doxyfile.in                          | 2314 +++++++++++++++++
 m4/ax_python_module.m4                        |   56 +
 m4/docs_tool.m4                               |    9 +
 xen/include/public/grant_table.h              |   75 +-
 24 files changed, 3121 insertions(+), 34 deletions(-)
 create mode 100644 docs/hypercall-interfaces/arm32.rst
 create mode 100644 docs/hypercall-interfaces/arm64.rst
 create mode 100644 docs/hypercall-interfaces/arm64/grant_tables.rst
 create mode 100644 docs/hypercall-interfaces/index.rst.in
 create mode 100644 docs/hypercall-interfaces/x86_64.rst
 create mode 100644 docs/xen-doxygen/customdoxygen.css
 create mode 100755 docs/xen-doxygen/doxy-preprocessor.py
 create mode 100644 docs/xen-doxygen/doxy_input.list
 create mode 100644 docs/xen-doxygen/doxygen_include.h.in
 create mode 100644 docs/xen-doxygen/footer.html
 create mode 100644 docs/xen-doxygen/header.html
 create mode 100644 docs/xen-doxygen/mainpage.md
 create mode 100644 docs/xen-doxygen/xen_project_logo_165x67.png
 create mode 100644 docs/xen.doxyfile.in
 create mode 100644 m4/ax_python_module.m4
Signature · 1 line
2.17.1
#1 lore raw

PATCH v3 1/3 docs: add doxygen support for html documentation

Add doxygen support to build html documentation with sphinx, to do that the following modification are applied:

1) Modify docs/configure.ac and consequently configure script to check, through the ./configure script, the presence in the system of the sphinx-build binary, if it is found then it checks also the presence of the doxygen binary, breathe and sphinx-rtd-theme python packages.
Doxygen and the packages are required only if sphinx-build is found, otherwise the Makefile will simply skip the sphinx html generation.
The ax_python_module.m4 support is needed to check for python packages.
2) Add doxygen templates and configuration file
3) Modify docs/Makefile to call in sequence doxygen and sphinx-build, the doxygen configuration file will be modified to include the xen absolute path and
a list of header to parse.
A doxygen_input.h file is generated to include every header listed in the doxy_input.list file.
4) Add preprocessor called by doxygen before parsing headers, it will include in every header a doxygen_include.h file that provides missing defines and includes that are usually passed by the compiler.

---
v3 changes:
- add preprocessor to handle missing defines and anonymous structs/unions before doxygen parsing
- modification to Makefile to handle the new process v2 changes:
- Fix bug in Makefile when sphinx is not found in the system

---
 .gitignore                                   |    6 +
 config/Docs.mk.in                            |    2 +
 docs/Makefile                                |   42 +-
 docs/conf.py                                 |   48 +-
 docs/configure                               |  258 ++
 docs/configure.ac                            |   15 +
 docs/xen-doxygen/customdoxygen.css           |   36 +
 docs/xen-doxygen/doxy-preprocessor.py        |  110 +
 docs/xen-doxygen/doxy_input.list             |    0
 docs/xen-doxygen/doxygen_include.h.in        |   32 +
 docs/xen-doxygen/footer.html                 |   21 +
 docs/xen-doxygen/header.html                 |   56 +
 docs/xen-doxygen/mainpage.md                 |    5 +
 docs/xen-doxygen/xen_project_logo_165x67.png |  Bin 0 -> 18223 bytes
 docs/xen.doxyfile.in                         | 2314 ++++++++++++++++++
 m4/ax_python_module.m4                       |   56 +
 m4/docs_tool.m4                              |    9 +
 17 files changed, 3004 insertions(+), 6 deletions(-)
 create mode 100644 docs/xen-doxygen/customdoxygen.css
 create mode 100755 docs/xen-doxygen/doxy-preprocessor.py
 create mode 100644 docs/xen-doxygen/doxy_input.list
 create mode 100644 docs/xen-doxygen/doxygen_include.h.in
 create mode 100644 docs/xen-doxygen/footer.html
 create mode 100644 docs/xen-doxygen/header.html
 create mode 100644 docs/xen-doxygen/mainpage.md
 create mode 100644 docs/xen-doxygen/xen_project_logo_165x67.png
 create mode 100644 docs/xen.doxyfile.in
 create mode 100644 m4/ax_python_module.m4
.gitignore +6 -0
index 1c2fa1530b..d271e0ce6a 100644
@@ -58,6 +58,12 @@ docs/man7/
 docs/man8/
 docs/pdf/
 docs/txt/
+docs/doxygen-output
+docs/sphinx
+docs/xen.doxyfile
+docs/xen.doxyfile.tmp
+docs/xen-doxygen/doxygen_include.h
+docs/xen-doxygen/doxygen_include.h.tmp
 extras/mini-os*
 install/*
 stubdom/*-minios-config.mk
config/Docs.mk.in +2 -0
index e76e5cd5ff..dfd4a02838 100644
@@ -7,3 +7,5 @@ POD2HTML            := @POD2HTML@
 POD2TEXT            := @POD2TEXT@
 PANDOC              := @PANDOC@
 PERL                := @PERL@
+SPHINXBUILD         := @SPHINXBUILD@
+DOXYGEN             := @DOXYGEN@
docs/Makefile +39 -3

60 lines not on this page · raw message

docs/conf.py +45 -3

83 lines not on this page · raw message

docs/configure +258 -0

294 lines not on this page · raw message

docs/configure.ac +15 -0
index c2e5edd3b3..a2ff55f30a 100644
@@ -20,6 +20,7 @@ m4_include([../m4/docs_tool.m4])
 m4_include([../m4/path_or_fail.m4])
 m4_include([../m4/features.m4])
 m4_include([../m4/paths.m4])
+m4_include([../m4/ax_python_module.m4])
 
 AX_XEN_EXPAND_CONFIG()
 
@@ -29,6 +30,20 @@ AX_DOCS_TOOL_PROG([POD2HTML], [pod2html])
 AX_DOCS_TOOL_PROG([POD2TEXT], [pod2text])
 AX_DOCS_TOOL_PROG([PANDOC], [pandoc])
 
+# If sphinx is installed, make sure to have also the dependencies to build
+# Sphinx documentation.
+AC_CHECK_PROGS([SPHINXBUILD], [sphinx-build], [no])
+    AS_IF([test "x$SPHINXBUILD" = xno],
+        [AC_MSG_WARN(sphinx-build is not available so sphinx documentation \
+won't be built)],
+        [
+            AC_PATH_PROG([SPHINXBUILD], [sphinx-build])
+            AX_DOCS_TOOL_REQ_PROG([DOXYGEN], [doxygen])
+            AX_PYTHON_MODULE([breathe],[yes])
+            AX_PYTHON_MODULE([sphinx_rtd_theme], [yes])
+        ]
+    )
+
 AC_ARG_VAR([PERL], [Path to Perl parser])
 AX_PATH_PROG_OR_FAIL([PERL], [perl])
 
docs/xen-doxygen/customdoxygen.css new file +36 -0
new file mode 100644
index 0000000000..4735e41cf5
@@ -0,0 +1,36 @@
+/* Custom CSS for Doxygen-generated HTML
+ * Copyright (c) 2015 Intel Corporation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+code {
+  font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
+  background-color: #D8D8D8;
+  padding: 0 0.25em 0 0.25em;
+}
+
+pre.fragment {
+  display: block;
+  font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
+  padding: 1rem;
+  word-break: break-all;
+  word-wrap: break-word;
+  white-space: pre;
+  background-color: #D8D8D8;
+}
+
+#projectlogo
+{
+  vertical-align: middle;
+}
+
+#projectname
+{
+  font: 200% Tahoma, Arial,sans-serif;
+  color: #3D578C;
+}
+
+#projectbrief
+{
+  color: #3D578C;
+}
docs/xen-doxygen/doxy-preprocessor.py new file +110 -0

110 lines not on this page · raw message

docs/xen-doxygen/doxy_input.list new file +0 -0
new file mode 100644
index 0000000000..e69de29bb2
docs/xen-doxygen/doxygen_include.h.in new file +32 -0
new file mode 100644
index 0000000000..df284f3931
@@ -0,0 +1,32 @@
+/*
+ * Doxygen include header
+ * It supplies the xen/include/xen/config.h that is included using the -include
+ * argument of the compiler in Xen Makefile.
+ * Other macros are defined because they are usually provided by the compiler.
+ *
+ * Copyright (C) 2021 ARM Limited
+ *
+ * Author: Luca Fancellu <[email protected]>
+ *
+ * SPDX-License-Identifier: GPL-2.0
+ */
+
+#include "@XEN_BASE@/xen/include/xen/config.h"
+
+#if defined(CONFIG_X86_64)
+
+#define __x86_64__ 1
+
+#elif defined(CONFIG_ARM_64)
+
+#define __aarch64__ 1
+
+#elif defined(CONFIG_ARM_32)
+
+#define __arm__ 1
+
+#else
+
+#error Architecture not supported/recognized.
+
+#endif
docs/xen-doxygen/footer.html new file +21 -0
new file mode 100644
index 0000000000..a24bf2b9b4
@@ -0,0 +1,21 @@
+<!-- HTML footer for doxygen 1.8.13-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+    <li class="footer">$generatedby
+    <a href="http://www.doxygen.org/index.html">
+    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby &#160;<a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>
docs/xen-doxygen/header.html new file +56 -0

56 lines not on this page · raw message

docs/xen-doxygen/mainpage.md new file +5 -0
new file mode 100644
index 0000000000..ff548b87fc
@@ -0,0 +1,5 @@
+# API Documentation   {#index}
+
+## Introduction
+
+## Licensing
docs/xen-doxygen/xen_project_logo_165x67.png new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..7244959d59cdeb9f23c5202160ea45508dfc7265
GIT binary patch
docs/xen.doxyfile.in new file +2314 -0

2,259 lines not on this page · raw message

m4/ax_python_module.m4 new file +56 -0

56 lines not on this page · raw message

m4/docs_tool.m4 +9 -0
index 3e8814ac8d..39aa348026 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.17.1

Part of the diff is not shown here. View the raw message.

#2 lore raw

PATCH v3 2/3 docs: hypercalls sphinx skeleton for generated html

In reply to Luca Fancellu

Create a skeleton for the documentation about hypercalls

---
 .gitignore                             |  1 +
 docs/Makefile                          |  4 ++++
 docs/hypercall-interfaces/arm32.rst    |  4 ++++
 docs/hypercall-interfaces/arm64.rst    | 32 ++++++++++++++++++++++++++
 docs/hypercall-interfaces/index.rst.in |  7 ++++++
 docs/hypercall-interfaces/x86_64.rst   |  4 ++++
 docs/index.rst                         |  8 +++++++
 7 files changed, 60 insertions(+)
 create mode 100644 docs/hypercall-interfaces/arm32.rst
 create mode 100644 docs/hypercall-interfaces/arm64.rst
 create mode 100644 docs/hypercall-interfaces/index.rst.in
 create mode 100644 docs/hypercall-interfaces/x86_64.rst
.gitignore +1 -0
index d271e0ce6a..a9aab120ae 100644
@@ -64,6 +64,7 @@ docs/xen.doxyfile
 docs/xen.doxyfile.tmp
 docs/xen-doxygen/doxygen_include.h
 docs/xen-doxygen/doxygen_include.h.tmp
+docs/hypercall-interfaces/index.rst
 extras/mini-os*
 install/*
 stubdom/*-minios-config.mk
docs/Makefile +4 -0
index 2f784c36ce..b02c3dfb79 100644
@@ -61,6 +61,9 @@ build: html txt pdf man-pages figs
 sphinx-html: $(DOXY_DEPS) $(DOXY_LIST_SOURCES)
 ifneq ($(SPHINXBUILD),no)
 	$(DOXYGEN) xen.doxyfile
+	@echo "Generating hypercall-interfaces/index.rst"
+	@sed -e "s,@XEN_TARGET_ARCH@,$(XEN_TARGET_ARCH),g" \
+		hypercall-interfaces/index.rst.in > hypercall-interfaces/index.rst
 	XEN_ROOT=$(realpath $(XEN_ROOT)) $(SPHINXBUILD) -b html . sphinx/html
 else
 	@echo "Sphinx is not installed; skipping sphinx-html documentation."
@@ -108,6 +111,7 @@ clean: clean-man-pages
 	rm -f xen.doxyfile.tmp
 	rm -f xen-doxygen/doxygen_include.h
 	rm -f xen-doxygen/doxygen_include.h.tmp
+	rm -f hypercall-interfaces/index.rst
 
 .PHONY: distclean
 distclean: clean
docs/hypercall-interfaces/arm32.rst new file +4 -0
new file mode 100644
index 0000000000..4e973fbbaf
@@ -0,0 +1,4 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall Interfaces - arm32
+============================
docs/hypercall-interfaces/arm64.rst new file +32 -0
new file mode 100644
index 0000000000..5e701a2adc
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall Interfaces - arm64
+============================
+
+Starting points
+---------------
+.. toctree::
+   :maxdepth: 2
+
+
+
+Functions
+---------
+
+
+Structs
+-------
+
+
+Enums and sets of #defines
+--------------------------
+
+
+Typedefs
+--------
+
+
+Enum values and individual #defines
+-----------------------------------
+
+
docs/hypercall-interfaces/index.rst.in new file +7 -0
new file mode 100644
index 0000000000..e4dcc5db8d
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall Interfaces
+====================
+
+.. toctree::
+   @XEN_TARGET_ARCH@
docs/hypercall-interfaces/x86_64.rst new file +4 -0
new file mode 100644
index 0000000000..3ed70dff95
@@ -0,0 +1,4 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Hypercall Interfaces - x86_64
+=============================
docs/index.rst +8 -0
index b75487a05d..52226a42d8 100644
@@ -53,6 +53,14 @@ kind of development environment.
    hypervisor-guide/index
 
 
+Hypercall Interfaces documentation
+----------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   hypercall-interfaces/index
+
 Miscellanea
 -----------
 
Signature · 1 line
2.17.1
#3 lore raw

PATCH v3 3/3 docs/doxygen: doxygen documentation for grant_table.h

In reply to Luca Fancellu

Modification to include/public/grant_table.h:

1) Add doxygen tags to:
- Create Grant tables section
- include variables in the generated documentation
2) Add .rst file for grant table for Arm64

---
v3 changes:
- removed tags to skip anonymous union/struct
- moved back comment pointed out by Jan
- moved down defines related to struct gnttab_copy as pointed out by Jan
v2 changes:
- Revert back to anonymous union/struct
- add doxygen tags to skip anonymous union/struct

---
 docs/hypercall-interfaces/arm64.rst           |  1 +
 .../arm64/grant_tables.rst                    |  8 ++
 docs/xen-doxygen/doxy_input.list              |  1 +
 xen/include/public/grant_table.h              | 75 ++++++++++++-------
 4 files changed, 57 insertions(+), 28 deletions(-)
 create mode 100644 docs/hypercall-interfaces/arm64/grant_tables.rst
docs/hypercall-interfaces/arm64.rst +1 -0
index 5e701a2adc..c30a7142b1 100644
@@ -8,6 +8,7 @@ Starting points
 .. toctree::
    :maxdepth: 2
 
+   arm64/grant_tables
 
 
 Functions
docs/hypercall-interfaces/arm64/grant_tables.rst new file +8 -0
new file mode 100644
index 0000000000..8955ec5812
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Grant Tables
+============
+
+.. doxygengroup:: grant_table
+   :project: Xen
+   :members:
docs/xen-doxygen/doxy_input.list +1 -0
index e69de29bb2..233d692fa7 100644
@@ -0,0 +1 @@
+xen/include/public/grant_table.h
xen/include/public/grant_table.h +47 -28

195 lines not on this page · raw message

Signature · 1 line
2.17.1
#4 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 16 lines · Luca Fancellu
docs/hypercall-interfaces/arm64.rst +1 -0
@@ -8,6 +8,7 @@ Starting points
 .. toctree::
    :maxdepth: 2
 
+   arm64/grant_tables
 
 
 Functions
docs/hypercall-interfaces/arm64/grant_tables.rst new file +0 -0
new file mode 100644
index 0000000000..8955ec5812

docs/hypercall-interfaces/arm64/grant_tables.rst line 6

Quoted 6 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +6 -0
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Grant Tables
+============
+
+.. doxygengroup:: grant_table

I continue to object to this giving the impression that grant tables are something Arm64 specific.

Quoted 24 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +4 -0
@@ -66,6 +67,7 @@
  *     compiler barrier will still be required.
  *
  * Introducing a valid entry into the grant table:
+ * @code
  *  1. Write ent->domid.
  *  2. Write ent->frame:
  *      GTF_permit_access:   Frame to which access is permitted.
@@ -73,20 +75,25 @@
  *                           frame, or zero if none.
  *  3. Write memory barrier (WMB).
  *  4. Write ent->flags, inc. valid type.
+ * @endcode
  *
  * Invalidating an unused GTF_permit_access entry:
+ * @code
  *  1. flags = ent->flags.
  *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
  *  NB. No need for WMB as reuse of entry is control-dependent on success of
  *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
+ * @endcode
  *
  * Invalidating an in-use GTF_permit_access entry:

docs/hypercall-interfaces/arm64/grant_tables.rst line 99

Quoted 10 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +2 -0
+ *
  *  This cannot be done directly. Request assistance from the domain controller
  *  which can set a timeout on the use of a grant entry and take necessary
  *  action. (NB. This is not yet implemented!).
  *
  * Invalidating an unused GTF_accept_transfer entry:
+ * @code
  *  1. flags = ent->flags.
  *  2. Observe that !(flags & GTF_transfer_committed). [*]
  *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).

Since neither in the cover letter nor in the description here I could spot a link to the resulting generated doc, I wonder what the inconsistencies above are about: You add @code/@endcode (and no blank lines) to parts of what's being described, and _instead_ a blank line to another part. I think the goal should be that not only the generated doc ends up looking "nice", but that the source code also remains consistent. Otherwise, someone like me coming across this later on might easily conclude that there was a @code/@endcode pair missed.

docs/hypercall-interfaces/arm64/grant_tables.rst line 111

Quoted 9 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -0
@@ -97,18 +104,23 @@
  *      transferred frame is written. It is safe for the guest to spin waiting
  *      for this to occur (detect by observing GTF_transfer_completed in
  *      ent->flags).
+ * @endcode
  *
  * Invalidating a committed GTF_accept_transfer entry:
  *  1. Wait for (ent->flags & GTF_transfer_completed).
  *

Why did this not also get enclosed by @code/@endcode?

docs/hypercall-interfaces/arm64/grant_tables.rst line 118

Quoted 7 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +2 -0
  * Changing a GTF_permit_access from writable to read-only:
+ *
  *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
  *
  * Changing a GTF_permit_access from read-only to writable:
+ *
  *  Use SMP-safe bit-setting instruction.

And these two?

docs/hypercall-interfaces/arm64/grant_tables.rst line 119

Quoted 1 line
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -0
+ * @addtogroup grant_table Grant Tables

And no blank (comment) line ahead of this?

Quoted 6 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +0 -2
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
  * [GST]: This field is written by the guest and read by Xen.
  */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely

docs/hypercall-interfaces/arm64/grant_tables.rst typedef uint32_t grant_ref_t; · line 142

Quoted 10 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +4 -2
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Quoted 13 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +0 -5
@@ -451,11 +465,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
  * bytes to be copied.
  */
 
-#define _GNTCOPY_source_gref      (0)
-#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
-#define _GNTCOPY_dest_gref        (1)
-#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)
-
 struct gnttab_copy {
     /* IN parameters. */
     struct gnttab_copy_ptr {

docs/hypercall-interfaces/arm64/grant_tables.rst struct gnttab_copy { · line 487

Quoted 8 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +5 -0
@@ -471,6 +480,12 @@ struct gnttab_copy {
     /* OUT parameters. */
     int16_t       status;
 };
+
+#define _GNTCOPY_source_gref      (0)
+#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
+#define _GNTCOPY_dest_gref        (1)
+#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)

I guess I didn't express myself precisely enough: I think these would better live _immediately_ next to the field that uses them.

Jan

#5 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 7 lines · Jan Beulich
Quoted 7 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -0
new file mode 100644
index 0000000000..8955ec5812
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: CC-BY-4.0
Quoted 8 lines

docs/hypercall-interfaces/arm64/grant_tables.rst line 6

Quoted 5 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +5 -0
+
+Grant Tables
+============
+
+.. doxygengroup:: grant_table

I continue to object to this giving the impression that grant tables are something Arm64 specific.

+1, grant tables is common interface so why do they need to be described per arch?

I haven't looked at the history of the patch, but if there was some rationale about this approach, then this ought to be written in the commit message or at least after (---).

Cheers,

Signature · 1 line
Julien Grall
#6 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

In reply to Jan Beulich
Quoted 14 lines · Jan Beulich
Quoted 9 lines · Luca Fancellu
docs/hypercall-interfaces/arm64.rst +0 -0
@@ -8,6 +8,7 @@ Starting points

.. toctree::
:maxdepth: 2

+ arm64/grant_tables

Quoted 16 lines

docs/hypercall-interfaces/arm64/grant_tables.rst line 6

Quoted 13 lines

Functions

docs/hypercall-interfaces/arm64/grant_tables.rst new file +6 -0
new file mode 100644
index 0000000000..8955ec5812
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Grant Tables
+============
+
+.. doxygengroup:: grant_table

I continue to object to this giving the impression that grant tables are something Arm64 specific.

Hi Jan,

I’ll put it in a folder named “common"

Quoted 37 lines
Quoted 25 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +4 -0
@@ -66,6 +67,7 @@
 *     compiler barrier will still be required.
 *
 * Introducing a valid entry into the grant table:
+ * @code
 *  1. Write ent->domid.
 *  2. Write ent->frame:
 *      GTF_permit_access:   Frame to which access is permitted.
@@ -73,20 +75,25 @@
 *                           frame, or zero if none.
 *  3. Write memory barrier (WMB).
 *  4. Write ent->flags, inc. valid type.
+ * @endcode
 *
 * Invalidating an unused GTF_permit_access entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
 *  NB. No need for WMB as reuse of entry is control-dependent on success of
 *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
+ * @endcode
 *
 * Invalidating an in-use GTF_permit_access entry:

docs/hypercall-interfaces/arm64/grant_tables.rst line 99

Quoted 10 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +2 -0
+ *
 *  This cannot be done directly. Request assistance from the domain controller
 *  which can set a timeout on the use of a grant entry and take necessary
 *  action. (NB. This is not yet implemented!).
 *
 * Invalidating an unused GTF_accept_transfer entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & GTF_transfer_committed). [*]
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).

Since neither in the cover letter nor in the description here I could

Quoted 8 lines

spot a link to the resulting generated doc, I wonder what the inconsistencies above are about: You add @code/@endcode (and no blank lines) to parts of what's being described, and _instead_ a blank line to another part. I think the goal should be that not only the generated doc ends up looking "nice", but that the source code also remains consistent. Otherwise, someone like me coming across this later on might easily conclude that there was a @code/@endcode pair missed.

Yes I’ll explain better in the commit message, that part and other parts are enclosed by @code/@endcode because they are formatted using spaces. If the block is not enclosed the spaces are missing in the html page resulting In a mess.
If you can suggest an alias for the @code/@endcode command, I can create it so that the user looking the source code can understand better what's going on. An example: @keepformat/@endkeepformat OR @keepindent/@endkeepindent

Here a link to the documentation right now:
https://luca.fancellu.gitlab.io/xen-docs/hypercall-interfaces/arm64/grant_tables.html

Quoted 12 lines

docs/hypercall-interfaces/arm64/grant_tables.rst line 111

Quoted 10 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -0
@@ -97,18 +104,23 @@
 *      transferred frame is written. It is safe for the guest to spin waiting
 *      for this to occur (detect by observing GTF_transfer_completed in
 *      ent->flags).
+ * @endcode
 *
 * Invalidating a committed GTF_accept_transfer entry:
 *  1. Wait for (ent->flags & GTF_transfer_completed).
 *

Why did this not also get enclosed by @code/@endcode?

In this case there are no spaces that contributes to the indentation.

Quoted 10 lines

docs/hypercall-interfaces/arm64/grant_tables.rst line 118

Quoted 8 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +2 -0
 * Changing a GTF_permit_access from writable to read-only:
+ *
 *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
 *
 * Changing a GTF_permit_access from read-only to writable:
+ *
 *  Use SMP-safe bit-setting instruction.

And these two?

These two lines makes the resulting html page looks better, the source code however seems not too impacted by the change though.

Quoted 4 lines

docs/hypercall-interfaces/arm64/grant_tables.rst line 119

Quoted 2 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -0
+ * @addtogroup grant_table Grant Tables

And no blank (comment) line ahead of this?

Here there is no need for a blank line in the comment, but if in your opinion the source code will look better I can add it

Quoted 14 lines
Quoted 14 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +1 -4
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
 * [GST]: This field is written by the guest and read by Xen.
 */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
Quoted 8 lines

docs/hypercall-interfaces/arm64/grant_tables.rst typedef uint32_t grant_ref_t; · line 142

Quoted 3 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +3 -0
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Could you explain me better that? Do you want to get rid of this comment?

/**
* Version 1 of the grant table entry structure is maintained purely
* for backwards compatibility. New guests should use version 2. */

In this case I don’t think this commit is the right place to do that, I can just put it back where it was so that the documentation simply doesn’t show that.

Quoted 17 lines
Quoted 17 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +0 -5
@@ -451,11 +465,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
 * bytes to be copied.
 */
 
-#define _GNTCOPY_source_gref      (0)
-#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
-#define _GNTCOPY_dest_gref        (1)
-#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)
-
 struct gnttab_copy {
    /* IN parameters. */
    struct gnttab_copy_ptr {
@@ -471,6 +480,12 @@ struct gnttab_copy {
    /* OUT parameters. */
    int16_t       status;
 };
Quoted 8 lines

docs/hypercall-interfaces/arm64/grant_tables.rst struct gnttab_copy { · line 487

Quoted 5 lines
docs/hypercall-interfaces/arm64/grant_tables.rst new file +5 -0
+
+#define _GNTCOPY_source_gref      (0)
+#define GNTCOPY_source_gref       (1<<_GNTCOPY_source_gref)
+#define _GNTCOPY_dest_gref        (1)
+#define GNTCOPY_dest_gref         (1<<_GNTCOPY_dest_gref)

I guess I didn't express myself precisely enough: I think these would better live _immediately_ next to the field that uses them.

Ok I didn’t get that, I’ll put them right next to the field

Cheers,
Luca

Quoted 2 lines

Jan

#7 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 47 lines · Luca Fancellu
Quoted 38 lines · Jan Beulich
Quoted 24 lines · Luca Fancellu
xen/include/public/grant_table.h +4 -0
@@ -66,6 +67,7 @@
 *     compiler barrier will still be required.
 *
 * Introducing a valid entry into the grant table:
+ * @code
 *  1. Write ent->domid.
 *  2. Write ent->frame:
 *      GTF_permit_access:   Frame to which access is permitted.
@@ -73,20 +75,25 @@
 *                           frame, or zero if none.
 *  3. Write memory barrier (WMB).
 *  4. Write ent->flags, inc. valid type.
+ * @endcode
 *
 * Invalidating an unused GTF_permit_access entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
 *  NB. No need for WMB as reuse of entry is control-dependent on success of
 *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
+ * @endcode
 *
 * Invalidating an in-use GTF_permit_access entry:

xen/include/public/grant_table.h line 99

Quoted 10 lines
xen/include/public/grant_table.h +2 -0
+ *
 *  This cannot be done directly. Request assistance from the domain controller
 *  which can set a timeout on the use of a grant entry and take necessary
 *  action. (NB. This is not yet implemented!).
 *
 * Invalidating an unused GTF_accept_transfer entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & GTF_transfer_committed). [*]
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).

Since neither in the cover letter nor in the description here I could

Quoted 8 lines

spot a link to the resulting generated doc, I wonder what the inconsistencies above are about: You add @code/@endcode (and no blank lines) to parts of what's being described, and _instead_ a blank line to another part. I think the goal should be that not only the generated doc ends up looking "nice", but that the source code also remains consistent. Otherwise, someone like me coming across this later on might easily conclude that there was a @code/@endcode pair missed.

Quoted 7 lines

Yes I’ll explain better in the commit message, that part and other parts are enclosed by @code/@endcode because they are formatted using spaces. If the block is not enclosed the spaces are missing in the html page resulting In a mess.
If you can suggest an alias for the @code/@endcode command, I can create it so that the user looking the source code can understand better what's going on. An example: @keepformat/@endkeepformat OR @keepindent/@endkeepindent

Oh, are you suggesting @code / @endcode isn't something doxygen mandates? In this case either of your alternative suggestions would look better to me. Which one depend on whether the goal to to merely keep indentation or whether formatting should be kept altogether.

Quoted 12 lines
Quoted 11 lines

xen/include/public/grant_table.h line 111

Quoted 9 lines
xen/include/public/grant_table.h +1 -0
@@ -97,18 +104,23 @@
 *      transferred frame is written. It is safe for the guest to spin waiting
 *      for this to occur (detect by observing GTF_transfer_completed in
 *      ent->flags).
+ * @endcode
 *
 * Invalidating a committed GTF_accept_transfer entry:
 *  1. Wait for (ent->flags & GTF_transfer_completed).
 *

Why did this not also get enclosed by @code/@endcode?

Quoted 1 line

In this case there are no spaces that contributes to the indentation.

But if, for consistency, @code / @endcode were added here, all would still be well?

Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
xen/include/public/grant_table.h +2 -0
 * Changing a GTF_permit_access from writable to read-only:
+ *
 *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
 *
 * Changing a GTF_permit_access from read-only to writable:
+ *
 *  Use SMP-safe bit-setting instruction.
Quoted 4 lines
Quoted 1 line

And these two?

These two lines makes the resulting html page looks better, the source code however seems not too impacted by the change though.

I was rather asking about the absence of @code / @endcode here.

Quoted 6 lines
Quoted 3 lines

xen/include/public/grant_table.h line 119

Quoted 1 line
xen/include/public/grant_table.h +1 -0
+ * @addtogroup grant_table Grant Tables

And no blank (comment) line ahead of this?

Here there is no need for a blank line in the comment, but if in your opinion the source code will look better I can add it

I think so, yes.

Quoted 22 lines
Quoted 13 lines
Quoted 13 lines
xen/include/public/grant_table.h +1 -4
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
 * [GST]: This field is written by the guest and read by Xen.
 */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
Quoted 8 lines

xen/include/public/grant_table.h typedef uint32_t grant_ref_t; · line 142

Quoted 3 lines
xen/include/public/grant_table.h +3 -0
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Quoted 1 line

Could you explain me better that? Do you want to get rid of this comment?

Especially the second sentence is misleading. If new code used v2, it would not work on Xen with v2 support turned off.

Quoted 7 lines

/**
* Version 1 of the grant table entry structure is maintained purely
* for backwards compatibility. New guests should use version 2. */

In this case I don’t think this commit is the right place to do that, I can just put it back where it was so that the documentation simply doesn’t show that.

Keeping misleading information out of the docs is imo rather desirable. Of course we should, independently of that, also address the misleading information in the source code. I can accept that doing the adjustment right in this patch may not be ideal. I don't suppose I could talk you into adding a prereq patch dropping at least that 2nd sentence?

Jan

#8 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 60 lines · Jan Beulich
Quoted 47 lines · Luca Fancellu
Quoted 38 lines · Jan Beulich
Quoted 24 lines · Luca Fancellu
xen/include/public/grant_table.h +4 -0
@@ -66,6 +67,7 @@
 *     compiler barrier will still be required.
 *
 * Introducing a valid entry into the grant table:
+ * @code
 *  1. Write ent->domid.
 *  2. Write ent->frame:
 *      GTF_permit_access:   Frame to which access is permitted.
@@ -73,20 +75,25 @@
 *                           frame, or zero if none.
 *  3. Write memory barrier (WMB).
 *  4. Write ent->flags, inc. valid type.
+ * @endcode
 *
 * Invalidating an unused GTF_permit_access entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & (GTF_reading|GTF_writing)).
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).
 *  NB. No need for WMB as reuse of entry is control-dependent on success of
 *      step 3, and all architectures guarantee ordering of ctrl-dep writes.
+ * @endcode
 *
 * Invalidating an in-use GTF_permit_access entry:

xen/include/public/grant_table.h line 99

Quoted 10 lines
xen/include/public/grant_table.h +2 -0
+ *
 *  This cannot be done directly. Request assistance from the domain controller
 *  which can set a timeout on the use of a grant entry and take necessary
 *  action. (NB. This is not yet implemented!).
 *
 * Invalidating an unused GTF_accept_transfer entry:
+ * @code
 *  1. flags = ent->flags.
 *  2. Observe that !(flags & GTF_transfer_committed). [*]
 *  3. Check result of SMP-safe CMPXCHG(&ent->flags, flags, 0).

Since neither in the cover letter nor in the description here I could

Quoted 8 lines

spot a link to the resulting generated doc, I wonder what the inconsistencies above are about: You add @code/@endcode (and no blank lines) to parts of what's being described, and _instead_ a blank line to another part. I think the goal should be that not only the generated doc ends up looking "nice", but that the source code also remains consistent. Otherwise, someone like me coming across this later on might easily conclude that there was a @code/@endcode pair missed.

Quoted 7 lines

Yes I’ll explain better in the commit message, that part and other parts are enclosed by @code/@endcode because they are formatted using spaces. If the block is not enclosed the spaces are missing in the html page resulting In a mess.
If you can suggest an alias for the @code/@endcode command, I can create it so that the user looking the source code can understand better what's going on. An example: @keepformat/@endkeepformat OR @keepindent/@endkeepindent

Quoted 4 lines

Oh, are you suggesting @code / @endcode isn't something doxygen mandates? In this case either of your alternative suggestions would look better to me. Which one depend on whether the goal to to merely keep indentation or whether formatting should be kept altogether.

Hi Jan,

Sure, I can go with @keepindent/@endkeepindent

Quoted 13 lines
Quoted 13 lines
Quoted 12 lines

xen/include/public/grant_table.h line 111

Quoted 10 lines
xen/include/public/grant_table.h +1 -0
@@ -97,18 +104,23 @@
 *      transferred frame is written. It is safe for the guest to spin waiting
 *      for this to occur (detect by observing GTF_transfer_completed in
 *      ent->flags).
+ * @endcode
 *
 * Invalidating a committed GTF_accept_transfer entry:
 *  1. Wait for (ent->flags & GTF_transfer_completed).
 *

Why did this not also get enclosed by @code/@endcode?

Quoted 4 lines
Quoted 1 line

In this case there are no spaces that contributes to the indentation.

But if, for consistency, @code / @endcode were added here, all would still be well?

Yes it would be ok, in the html page you will see a box with this text inside. If you see the url I sent in previous mail, you can see the rendering of the @code/@endcode in the html page to have an idea on how it looks.

Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
Quoted 8 lines
xen/include/public/grant_table.h +2 -0
 * Changing a GTF_permit_access from writable to read-only:
+ *
 *  Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
 *
 * Changing a GTF_permit_access from read-only to writable:
+ *
 *  Use SMP-safe bit-setting instruction.
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

And these two?

These two lines makes the resulting html page looks better, the source code however seems not too impacted by the change though.

I was rather asking about the absence of @code / @endcode here.

I didn’t use it because there is no space indentation to be kept, it looks better either in the source code and in the html page in this way

Quoted 9 lines
Quoted 7 lines
Quoted 4 lines

xen/include/public/grant_table.h line 119

Quoted 2 lines
xen/include/public/grant_table.h +1 -0
+ * @addtogroup grant_table Grant Tables

And no blank (comment) line ahead of this?

Here there is no need for a blank line in the comment, but if in your opinion the source code will look better I can add it

I think so, yes.

I will add it in the next patch

Quoted 23 lines
Quoted 23 lines
Quoted 22 lines
Quoted 7 lines
xen/include/public/grant_table.h +0 -2
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
 * [GST]: This field is written by the guest and read by Xen.
 */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely

xen/include/public/grant_table.h typedef uint32_t grant_ref_t; · line 142

Quoted 10 lines
xen/include/public/grant_table.h +4 -2
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Quoted 4 lines
Quoted 1 line

Could you explain me better that? Do you want to get rid of this comment?

Especially the second sentence is misleading. If new code used v2, it would not work on Xen with v2 support turned off.

Can you suggest what to write here? I’m not very familiar with this xen Interface

Quoted 6 lines
Quoted 6 lines

/**
* Version 1 of the grant table entry structure is maintained purely
* for backwards compatibility. New guests should use version 2. */

Quoted 9 lines
Quoted 2 lines

In this case I don’t think this commit is the right place to do that, I can just put it back where it was so that the documentation simply doesn’t show that.

Keeping misleading information out of the docs is imo rather desirable. Of course we should, independently of that, also address the misleading information in the source code. I can accept that doing the adjustment right in this patch may not be ideal. I don't suppose I could talk you into adding a prereq patch dropping at least that 2nd sentence?

I will push a patch to change this comment and I will rebase this serie on Top of that.

Cheers,
Luca

Quoted 1 line

Jan

#9 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 26 lines · Luca Fancellu
Quoted 26 lines · Jan Beulich
Quoted 24 lines · Luca Fancellu
Quoted 23 lines · Jan Beulich
Quoted 6 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -2
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
 * [GST]: This field is written by the guest and read by Xen.
 */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely

xen/include/public/grant_table.h typedef uint32_t grant_ref_t; · line 142

Quoted 10 lines
xen/include/public/grant_table.h +4 -2
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Quoted 7 lines
Quoted 4 lines
Quoted 1 line

Could you explain me better that? Do you want to get rid of this comment?

Especially the second sentence is misleading. If new code used v2, it would not work on Xen with v2 support turned off.

Can you suggest what to write here? I’m not very familiar with this xen Interface

I've sent a patch myself just a few seconds ago.

Jan

#10 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 33 lines · Jan Beulich
Quoted 28 lines · Luca Fancellu
Quoted 28 lines · Jan Beulich
Quoted 25 lines · Luca Fancellu
Quoted 15 lines · Jan Beulich
Quoted 13 lines · Luca Fancellu
xen/include/public/grant_table.h +1 -4
@@ -120,24 +132,26 @@ typedef uint32_t grant_ref_t;
 * [GST]: This field is written by the guest and read by Xen.
 */
 
-/*
- * Version 1 of the grant table entry structure is maintained purely
- * for backwards compatibility.  New guests should use version 2.
- */
 #if __XEN_INTERFACE_VERSION__ < 0x0003020a
 #define grant_entry_v1 grant_entry
 #define grant_entry_v1_t grant_entry_t
 #endif
+/**
Quoted 8 lines

xen/include/public/grant_table.h typedef uint32_t grant_ref_t; · line 142

Quoted 3 lines
xen/include/public/grant_table.h +3 -0
+ * Version 1 of the grant table entry structure is maintained purely
+ * for backwards compatibility.  New guests should use version 2.
+ */

In case I didn't say so already before - I think this would be a good opportunity to drop the comment pointing at v2. With v2 optionally unavailable altogether, this can't possibly be a generally valid course of action.

Could you explain me better that? Do you want to get rid of this comment?

Quoted 7 lines
Quoted 5 lines
Quoted 2 lines

Especially the second sentence is misleading. If new code used v2, it would not work on Xen with v2 support turned off.

Can you suggest what to write here? I’m not very familiar with this xen Interface

I've sent a patch myself just a few seconds ago.

Hi Jan,

That’s great, I’m going to push the v4 for this serie soon, now that the comment is fixed, I can include it in the docs too, do you agree?

Cheers,
Luca

Quoted 2 lines

Jan

#11 lore raw

Re: [PATCH v3 3/3] docs/doxygen: doxygen documentation for grant_table.h

Quoted 2 lines · Luca Fancellu

That’s great, I’m going to push the v4 for this serie soon, now that the comment is fixed, I can include it in the docs too, do you agree?

Of course (provided the patch will not get objected to).

Jan