modules: update developer documentation
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
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
@@ -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
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
@@ -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
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
@@ -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
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@@ -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
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
@@ -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
@@ -0,0 +1,5 @@ +============ +Qemu modules +============ + +.. kernel-doc:: include/qemu/module.h
Signature · 1 line
2.31.1
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: addmodule_obj()note to QOM docs
modules:module.hkerneldoc annotations
modules: hook upmodules.hto 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