Skip to contentSkip to conversation

modules: update developer documentation

PATCH In review Gerd Hoffmann 3 participants 7 messages Jun 22, 2021

lore
Share & tools
lore
#0 lore raw

cover modules: update developer documentation

Depends on the "modules: add meta-data database" patch series.

Gerd Hoffmann (4):
modules: add documentation for module sourcesets
modules: add module_obj() note to QOM docs
modules: module.h kerneldoc annotations
modules: hook up modules.h to docs build

 include/qemu/module.h       | 59 ++++++++++++++++++++++++++++---------
 docs/devel/build-system.rst | 17 +++++++++++
 docs/devel/index.rst        |  1 +
 docs/devel/modules.rst      |  5 ++++
 docs/devel/qom.rst          |  8 +++++
 5 files changed, 76 insertions(+), 14 deletions(-)
 create mode 100644 docs/devel/modules.rst
Signature · 1 line
2.31.1
#1 lore raw

PATCH 1/4 modules: add documentation for module sourcesets

---
 docs/devel/build-system.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
docs/devel/build-system.rst +17 -0
index 7ef36f42d0f5..fd1650442ecc 100644
@@ -272,6 +272,23 @@ Target-dependent emulator sourcesets:
     target_arch += {'arm': arm_ss}
     target_softmmu_arch += {'arm': arm_softmmu_ss}
 
+Module sourcesets:
+  There are two dictionaries for modules: `modules` is used for
+  target-independent modules and `target_modules` is used for
+  target-dependent modules.  When modules are disabled the `module`
+  source sets are added to `softmmu_ss` and the `target_modules`
+  source sets are added to `specific_ss`.
+
+  Both dictionaries are nested.  One dictionary is created per
+  subdirectory, and these per-subdirectory dictionaries are added to
+  the toplevel dictionaries.  For example::
+
+    hw_display_modules = {}
+    qxl_ss = ss.source_set()
+    ...
+    hw_display_modules += { 'qxl': qxl_ss }
+    modules += { 'hw-display': hw_display_modules }
+
 Utility sourcesets:
   All binaries link with a static library `libqemuutil.a`.  This library
   is built from several sourcesets; most of them however host generated
Signature · 1 line
2.31.1
#2 lore raw

PATCH 2/4 modules: add module_obj() note to QOM docs

In reply to Gerd Hoffmann
---
 docs/devel/qom.rst | 8 ++++++++
 1 file changed, 8 insertions(+)
docs/devel/qom.rst +8 -0
index 42d0dc4f4da8..e5fe3597cd82 100644
@@ -87,6 +87,14 @@ specific type:
    #define MY_DEVICE(obj) \
       OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
 
+In case the ObjectClass implementation can be built as module a
+module_obj() line must be added to make sure qemu loads the module
+when the object is needed.
+
+.. code-block:: c
+
+   module_obj(TYPE_MY_DEVICE);
+
 Class Initialization
 ====================
 
Signature · 1 line
2.31.1
#3 lore raw

PATCH 3/4 modules: module.h kerneldoc annotations

In reply to Gerd Hoffmann
---
 include/qemu/module.h | 59 +++++++++++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 14 deletions(-)
include/qemu/module.h +45 -14
index 7f4b1af8198c..8bc80535a4d4 100644
@@ -74,11 +74,18 @@ void module_load_qom_one(const char *type);
 void module_load_qom_all(void);
 void module_allow_arch(const char *arch);
 
-/*
- * module info annotation macros
+/**
+ * DOC: module info annotation macros
  *
- * scripts/modinfo-collect.py will collect module info,
- * using the preprocessor and -DQEMU_MODINFO
+ * `scripts/modinfo-collect.py` will collect module info,
+ * using the preprocessor and -DQEMU_MODINFO.
+ *
+ * `scripts/modinfo-generate.py` will create a module meta-data database
+ * from the collected information so qemu knows about module
+ * dependencies and QOM objects implemented by modules.
+ *
+ * See `*.modinfo` and `modinfo.c` in the build directory to check the
+ * script results.
  */
 #ifdef QEMU_MODINFO
 # define modinfo(kind, value) \
@@ -87,24 +94,48 @@ void module_allow_arch(const char *arch);
 # define modinfo(kind, value)
 #endif
 
-/* module implements QOM type <name> */
+/**
+ * module_obj
+ *
+ * @name: QOM type.
+ *
+ * This module implements QOM type @name.
+ */
 #define module_obj(name) modinfo(obj, name)
 
-/* module has a dependency on <name> */
+/**
+ * module_dep
+ *
+ * @name: module name
+ *
+ * This module depends on module @name.
+ */
 #define module_dep(name) modinfo(dep, name)
 
-/* module is for target architecture <name> */
+/**
+ * module_arch
+ *
+ * @arch: target architecture
+ *
+ * This module is for target architecture @arch.
+ *
+ * Note that target-dependent modules are tagged automatically, so
+ * this is only needed in case target-independent modules should be
+ * restricted.  Use case example: the ccw bus is implemented by s390x
+ * only.
+ */
 #define module_arch(name) modinfo(arch, name)
 
-/* module registers QemuOpts <name> */
+/**
+ * module_opts
+ *
+ * @name: QemuOpts name
+ *
+ * This module registers QemuOpts @name.
+ */
 #define module_opts(name) modinfo(opts, name)
 
-/*
- * module info database
- *
- * scripts/modinfo-generate.c will build this using the data collected
- * by scripts/modinfo-collect.py
- */
+/* module info database (created by scripts/modinfo-generate.py) */
 typedef struct QemuModinfo QemuModinfo;
 struct QemuModinfo {
     const char *name;
Signature · 1 line
2.31.1
#4 lore raw

Re: [PATCH 3/4] modules: module.h kerneldoc annotations

Hello Gerd,

Quoted 3 lines · Gerd Hoffmann
---
 include/qemu/module.h | 59 +++++++++++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 14 deletions(-)

This header has a copyright date from 2009. Not sure if it requires an update.

Quoted 91 lines
include/qemu/module.h +45 -14
index 7f4b1af8198c..8bc80535a4d4 100644
@@ -74,11 +74,18 @@ void module_load_qom_one(const char *type);
 void module_load_qom_all(void);
 void module_allow_arch(const char *arch);
 
-/*
- * module info annotation macros
+/**
+ * DOC: module info annotation macros
  *
- * scripts/modinfo-collect.py will collect module info,
- * using the preprocessor and -DQEMU_MODINFO
+ * `scripts/modinfo-collect.py` will collect module info,
+ * using the preprocessor and -DQEMU_MODINFO.
+ *
+ * `scripts/modinfo-generate.py` will create a module meta-data database
+ * from the collected information so qemu knows about module
+ * dependencies and QOM objects implemented by modules.
+ *
+ * See `*.modinfo` and `modinfo.c` in the build directory to check the
+ * script results.
  */
 #ifdef QEMU_MODINFO
 # define modinfo(kind, value) \
@@ -87,24 +94,48 @@ void module_allow_arch(const char *arch);
 # define modinfo(kind, value)
 #endif
 
-/* module implements QOM type <name> */
+/**
+ * module_obj
+ *
+ * @name: QOM type.
+ *
+ * This module implements QOM type @name.
+ */
 #define module_obj(name) modinfo(obj, name)
 
-/* module has a dependency on <name> */
+/**
+ * module_dep
+ *
+ * @name: module name
+ *
+ * This module depends on module @name.
+ */
 #define module_dep(name) modinfo(dep, name)
 
-/* module is for target architecture <name> */
+/**
+ * module_arch
+ *
+ * @arch: target architecture
+ *
+ * This module is for target architecture @arch.
+ *
+ * Note that target-dependent modules are tagged automatically, so
+ * this is only needed in case target-independent modules should be
+ * restricted.  Use case example: the ccw bus is implemented by s390x
+ * only.
+ */
 #define module_arch(name) modinfo(arch, name)
 
-/* module registers QemuOpts <name> */
+/**
+ * module_opts
+ *
+ * @name: QemuOpts name
+ *
+ * This module registers QemuOpts @name.
+ */
 #define module_opts(name) modinfo(opts, name)
 
-/*
- * module info database
- *
- * scripts/modinfo-generate.c will build this using the data collected
- * by scripts/modinfo-collect.py
- */
+/* module info database (created by scripts/modinfo-generate.py) */
 typedef struct QemuModinfo QemuModinfo;
 struct QemuModinfo {
     const char *name;
Signature · 1 line
2.31.1
#5 lore raw

PATCH 4/4 modules: hook up modules.h to docs build

In reply to Gerd Hoffmann
---
 docs/devel/index.rst   | 1 +
 docs/devel/modules.rst | 5 +++++
 2 files changed, 6 insertions(+)
 create mode 100644 docs/devel/modules.rst
docs/devel/index.rst +1 -0
index 977c3893bdaf..ba90badbbd6d 100644
@@ -41,6 +41,7 @@ Contents:
    s390-dasd-ipl
    clocks
    qom
+   modules
    block-coroutine-wrapper
    multi-process
    ebpf_rss
docs/devel/modules.rst new file +5 -0
new file mode 100644
index 000000000000..066f347b89ba
@@ -0,0 +1,5 @@
+============
+Qemu modules
+============
+
+.. kernel-doc:: include/qemu/module.h
Signature · 1 line
2.31.1
Reviewed-by on the v1 series
#6 lore raw
In reply to Gerd Hoffmann
Quoted 8 lines · Gerd Hoffmann

Depends on the "modules: add meta-data database" patch series.

Gerd Hoffmann (4):
modules: add documentation for module sourcesets
modules: add module_obj() note to QOM docs
modules: module.h kerneldoc annotations
modules: hook up modules.h to docs build

Quoted 8 lines
  include/qemu/module.h       | 59 ++++++++++++++++++++++++++++---------
  docs/devel/build-system.rst | 17 +++++++++++
  docs/devel/index.rst        |  1 +
  docs/devel/modules.rst      |  5 ++++
  docs/devel/qom.rst          |  8 +++++
  5 files changed, 76 insertions(+), 14 deletions(-)

create mode 100644 docs/devel/modules.rst

Thank you very much!

Paolo