Message ID | 20210622125110.262843-4-kraxel@redhat.com (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
Series | modules: update developer documentation | expand |
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 > >
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;