Skip to contentSkip to conversation

Use Doxygen and sphinx for html documentation

PATCH Superseded Luca Fancellu 2 participants 9 messages May 4, 2021

v4 of 7 Superseded Latest is v7 →

lore
Share & tools
lore
#0 lore raw

v4 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 +
 .../common/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                          | 2316 +++++++++++++++++
 m4/ax_python_module.m4                        |   56 +
 m4/docs_tool.m4                               |    9 +
 xen/include/public/grant_table.h              |   68 +-
 24 files changed, 3120 insertions(+), 30 deletions(-)
 create mode 100644 docs/hypercall-interfaces/arm32.rst
 create mode 100644 docs/hypercall-interfaces/arm64.rst
 create mode 100644 docs/hypercall-interfaces/common/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 v4 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.

---
v4 changes:
- create alias @keepindent/@endkeepindent for the doxygen command @code/@endcode
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                         | 2316 ++++++++++++++++++
 m4/ax_python_module.m4                       |   56 +
 m4/docs_tool.m4                              |    9 +
 17 files changed, 3006 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 +2316 -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 v4 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 v4 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
- Used @keepindent/@endkeepindent to enclose comment section that are indented using spaces, to keep the indentation.
2) Add .rst file for grant table for Arm64

---
v4 changes:
- Used @keepindent/@endkeepindent doxygen commands to keep text with spaces indentation.
- drop changes to grant_entry_v1 comment, it will be changed and included in the docs in a future patch
- Move docs .rst to "common" folder
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 +
 .../common/grant_tables.rst                   |  8 +++
 docs/xen-doxygen/doxy_input.list              |  1 +
 xen/include/public/grant_table.h              | 68 ++++++++++++-------
 4 files changed, 54 insertions(+), 24 deletions(-)
 create mode 100644 docs/hypercall-interfaces/common/grant_tables.rst
docs/hypercall-interfaces/arm64.rst +1 -0
index 5e701a2adc..cb4c0d13de 100644
@@ -8,6 +8,7 @@ Starting points
 .. toctree::
    :maxdepth: 2
 
+   common/grant_tables
 
 
 Functions
docs/hypercall-interfaces/common/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 +44 -24

183 lines not on this page · raw message

Signature · 1 line
2.17.1
#4 lore raw

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

Quoted 13 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -5
@@ -451,11 +466,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 {

xen/include/public/grant_table.h struct gnttab_copy { · line 488

Quoted 8 lines
xen/include/public/grant_table.h +5 -0
@@ -471,6 +481,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)

Didn't you say you agree with moving this back up some, next to the field using these?

Jan

#5 lore raw

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

Quoted 21 lines · Jan Beulich
Quoted 16 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -5
@@ -451,11 +466,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 +481,12 @@ struct gnttab_copy {
    /* OUT parameters. */
    int16_t       status;
 };
Quoted 8 lines

xen/include/public/grant_table.h struct gnttab_copy { · line 488

Quoted 5 lines
xen/include/public/grant_table.h +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)

Didn't you say you agree with moving this back up some, next to the field using these?

Hi Jan,

My mistake! I’ll move it in the next patch, did you spot anything else I might have forgot of what we agreed?

Cheers,
Luca

Quoted 2 lines

Jan

#6 lore raw

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

Quoted 27 lines · Luca Fancellu
Quoted 18 lines · Jan Beulich
Quoted 16 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -5
@@ -451,11 +466,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 +481,12 @@ struct gnttab_copy {
    /* OUT parameters. */
    int16_t       status;
 };
Quoted 8 lines

xen/include/public/grant_table.h struct gnttab_copy { · line 488

Quoted 5 lines
xen/include/public/grant_table.h +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)

Didn't you say you agree with moving this back up some, next to the field using these?

Quoted 1 line

My mistake! I’ll move it in the next patch, did you spot anything else I might have forgot of what we agreed?

No, thanks. I don't think I have any more comments to make on this series (once this last aspect got addressed, and assuming no new issues get introduced). But to be clear on that side as well - I don't think I'm up to actually ack-ing the patch (let alone the entire series).

Jan

#7 lore raw

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

Quoted 32 lines · Jan Beulich
Quoted 27 lines · Luca Fancellu
Quoted 26 lines · Jan Beulich
Quoted 13 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -5
@@ -451,11 +466,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 {

xen/include/public/grant_table.h struct gnttab_copy { · line 488

Quoted 8 lines
xen/include/public/grant_table.h +5 -0
@@ -471,6 +481,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)

Didn't you say you agree with moving this back up some, next to the field using these?

Quoted 7 lines
Quoted 1 line

My mistake! I’ll move it in the next patch, did you spot anything else I might have forgot of what we agreed?

No, thanks. I don't think I have any more comments to make on this series (once this last aspect got addressed, and assuming no new issues get introduced). But to be clear on that side as well - I don't think I'm up to actually ack-ing the patch (let alone the entire series).

Ok, at least would you mind to do a review by of the patches we discussed together?

Cheers,
Luca

Quoted 2 lines

Jan

#8 lore raw

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

Quoted 34 lines · Luca Fancellu
Quoted 34 lines · Jan Beulich
Quoted 28 lines · Luca Fancellu
Quoted 18 lines · Jan Beulich
Quoted 16 lines · Luca Fancellu
xen/include/public/grant_table.h +0 -5
@@ -451,11 +466,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 +481,12 @@ struct gnttab_copy {
   /* OUT parameters. */
   int16_t       status;
 };
Quoted 8 lines

xen/include/public/grant_table.h struct gnttab_copy { · line 488

Quoted 5 lines
xen/include/public/grant_table.h +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)

Didn't you say you agree with moving this back up some, next to the field using these?

My mistake! I’ll move it in the next patch, did you spot anything else I might have forgot of what we agreed?

Quoted 7 lines
Quoted 5 lines

No, thanks. I don't think I have any more comments to make on this series (once this last aspect got addressed, and assuming no new issues get introduced). But to be clear on that side as well - I don't think I'm up to actually ack-ing the patch (let alone the entire series).

Ok, at least would you mind to do a review by of the patches we discussed together?

I'm afraid I don't understand: I did look over this one.

Jan