* [PATCH 0/4] modules: update developer documentation
@ 2021-06-22 12:51 Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 1/4] modules: add documentation for module sourcesets Gerd Hoffmann
` (4 more replies)
0 siblings, 5 replies; 7+ messages in thread
From: Gerd Hoffmann @ 2021-06-22 12:51 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Daniel P. Berrangé, 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
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
--
2.31.1
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH 1/4] modules: add documentation for module sourcesets
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
@ 2021-06-22 12:51 ` Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 2/4] modules: add module_obj() note to QOM docs Gerd Hoffmann
` (3 subsequent siblings)
4 siblings, 0 replies; 7+ messages in thread
From: Gerd Hoffmann @ 2021-06-22 12:51 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Daniel P. Berrangé, Gerd Hoffmann
---
docs/devel/build-system.rst | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 7ef36f42d0f5..fd1650442ecc 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -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
--
2.31.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 2/4] modules: add module_obj() note to QOM docs
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 1/4] modules: add documentation for module sourcesets Gerd Hoffmann
@ 2021-06-22 12:51 ` Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 3/4] modules: module.h kerneldoc annotations Gerd Hoffmann
` (2 subsequent siblings)
4 siblings, 0 replies; 7+ messages in thread
From: Gerd Hoffmann @ 2021-06-22 12:51 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Daniel P. Berrangé, Gerd Hoffmann
---
docs/devel/qom.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 42d0dc4f4da8..e5fe3597cd82 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -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
====================
--
2.31.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 3/4] modules: module.h kerneldoc annotations
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 1/4] modules: add documentation for module sourcesets Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 2/4] modules: add module_obj() note to QOM docs Gerd Hoffmann
@ 2021-06-22 12:51 ` Gerd Hoffmann
2021-06-22 17:09 ` Jose R. Ziviani
2021-06-22 12:51 ` [PATCH 4/4] modules: hook up modules.h to docs build Gerd Hoffmann
2021-06-22 16:05 ` [PATCH 0/4] modules: update developer documentation Paolo Bonzini
4 siblings, 1 reply; 7+ messages in thread
From: Gerd Hoffmann @ 2021-06-22 12:51 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Daniel P. Berrangé, Gerd Hoffmann
---
include/qemu/module.h | 59 +++++++++++++++++++++++++++++++++----------
1 file changed, 45 insertions(+), 14 deletions(-)
diff --git a/include/qemu/module.h b/include/qemu/module.h
index 7f4b1af8198c..8bc80535a4d4 100644
--- a/include/qemu/module.h
+++ b/include/qemu/module.h
@@ -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;
--
2.31.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH 4/4] modules: hook up modules.h to docs build
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
` (2 preceding siblings ...)
2021-06-22 12:51 ` [PATCH 3/4] modules: module.h kerneldoc annotations Gerd Hoffmann
@ 2021-06-22 12:51 ` Gerd Hoffmann
2021-06-22 16:05 ` [PATCH 0/4] modules: update developer documentation Paolo Bonzini
4 siblings, 0 replies; 7+ messages in thread
From: Gerd Hoffmann @ 2021-06-22 12:51 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Daniel P. Berrangé, Gerd Hoffmann
---
docs/devel/index.rst | 1 +
docs/devel/modules.rst | 5 +++++
2 files changed, 6 insertions(+)
create mode 100644 docs/devel/modules.rst
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 977c3893bdaf..ba90badbbd6d 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -41,6 +41,7 @@ Contents:
s390-dasd-ipl
clocks
qom
+ modules
block-coroutine-wrapper
multi-process
ebpf_rss
diff --git a/docs/devel/modules.rst b/docs/devel/modules.rst
new file mode 100644
index 000000000000..066f347b89ba
--- /dev/null
+++ b/docs/devel/modules.rst
@@ -0,0 +1,5 @@
+============
+Qemu modules
+============
+
+.. kernel-doc:: include/qemu/module.h
--
2.31.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH 0/4] modules: update developer documentation
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
` (3 preceding siblings ...)
2021-06-22 12:51 ` [PATCH 4/4] modules: hook up modules.h to docs build Gerd Hoffmann
@ 2021-06-22 16:05 ` Paolo Bonzini
4 siblings, 0 replies; 7+ messages in thread
From: Paolo Bonzini @ 2021-06-22 16:05 UTC (permalink / raw)
To: Gerd Hoffmann, qemu-devel; +Cc: Daniel P. Berrangé
On 22/06/21 14:51, Gerd Hoffmann wrote:
> 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
>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Thank you very much!
Paolo
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH 3/4] modules: module.h kerneldoc annotations
2021-06-22 12:51 ` [PATCH 3/4] modules: module.h kerneldoc annotations Gerd Hoffmann
@ 2021-06-22 17:09 ` Jose R. Ziviani
0 siblings, 0 replies; 7+ messages in thread
From: Jose R. Ziviani @ 2021-06-22 17:09 UTC (permalink / raw)
To: Gerd Hoffmann; +Cc: Paolo Bonzini, Daniel P. Berrangé, qemu-devel
[-- Attachment #1: Type: text/plain, Size: 2927 bytes --]
Hello Gerd,
On Tue, Jun 22, 2021 at 02:51:09PM +0200, Gerd Hoffmann wrote:
> ---
> 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.
>
> diff --git a/include/qemu/module.h b/include/qemu/module.h
> index 7f4b1af8198c..8bc80535a4d4 100644
> --- a/include/qemu/module.h
> +++ b/include/qemu/module.h
> @@ -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;
> --
> 2.31.1
>
>
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2021-06-22 17:10 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-22 12:51 [PATCH 0/4] modules: update developer documentation Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 1/4] modules: add documentation for module sourcesets Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 2/4] modules: add module_obj() note to QOM docs Gerd Hoffmann
2021-06-22 12:51 ` [PATCH 3/4] modules: module.h kerneldoc annotations Gerd Hoffmann
2021-06-22 17:09 ` Jose R. Ziviani
2021-06-22 12:51 ` [PATCH 4/4] modules: hook up modules.h to docs build Gerd Hoffmann
2021-06-22 16:05 ` [PATCH 0/4] modules: update developer documentation Paolo Bonzini
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).