Message ID | 20200615204008.3069956-1-armbru@redhat.com |
---|---|
State | New |
Headers | show |
On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote: > > The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb: > > Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging (2020-06-12 23:06:22 +0100) > > are available in the Git repository at: > > git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15 > > for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a: > > MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 22:06:04 +0200) > > ---------------------------------------------------------------- > QOM patches for 2020-06-15 > > * Make "info qom-tree" show children sorted > * Fixes around device realization > * Rework how we plug into devices into their parent bus Applied, thanks. Please update the changelog at https://wiki.qemu.org/ChangeLog/5.1 for any user-visible changes. -- PMM
On 16/06/2020 14.26, Peter Maydell wrote: > On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote: >> >> The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb: >> >> Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging (2020-06-12 23:06:22 +0100) >> >> are available in the Git repository at: >> >> git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15 >> >> for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a: >> >> MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 22:06:04 +0200) >> >> ---------------------------------------------------------------- >> QOM patches for 2020-06-15 >> >> * Make "info qom-tree" show children sorted >> * Fixes around device realization >> * Rework how we plug into devices into their parent bus > > > Applied, thanks. > > Please update the changelog at https://wiki.qemu.org/ChangeLog/5.1 > for any user-visible changes. This pull requests (with the patch "qdev: qdev_init_nofail() is now unused, drop") apparently broke some iotests: https://gitlab.com/qemu-project/qemu/-/jobs/597414772#L4376 Can you please have a look? Thanks, Thomas
On 6/16/20 5:26 PM, Thomas Huth wrote: > On 16/06/2020 14.26, Peter Maydell wrote: >> On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote: >>> >>> The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb: >>> >>> Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging (2020-06-12 23:06:22 +0100) >>> >>> are available in the Git repository at: >>> >>> git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15 >>> >>> for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a: >>> >>> MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 22:06:04 +0200) >>> >>> ---------------------------------------------------------------- >>> QOM patches for 2020-06-15 >>> >>> * Make "info qom-tree" show children sorted >>> * Fixes around device realization >>> * Rework how we plug into devices into their parent bus >> >> >> Applied, thanks. >> >> Please update the changelog at https://wiki.qemu.org/ChangeLog/5.1 >> for any user-visible changes. > > This pull requests (with the patch "qdev: qdev_init_nofail() is now > unused, drop") apparently broke some iotests: > > https://gitlab.com/qemu-project/qemu/-/jobs/597414772#L4376 > > Can you please have a look? Fix sent: https://lists.gnu.org/archive/html/qemu-devel/2020-06/msg04730.html > > Thanks, > Thomas > >
On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote: > > The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb: > > Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging (2020-06-12 23:06:22 +0100) > > are available in the Git repository at: > > git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15 > > for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a: > > MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 22:06:04 +0200) > > ---------------------------------------------------------------- > QOM patches for 2020-06-15 > > * Make "info qom-tree" show children sorted > * Fixes around device realization > * Rework how we plug into devices into their parent bus Hi. I've just noticed that this commit added new global-scope functions to header files without documentation comments, eg bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); Please could you provide some follow-up patches that document them? I don't think we have any hope of getting people to follow whatever the correct new way to create/configure/realize devices is if we don't document it :-( [Concrete example: I now have no idea how this is supposed to work after this patchset.] thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote: >> >> The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb: >> >> Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging (2020-06-12 23:06:22 +0100) >> >> are available in the Git repository at: >> >> git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15 >> >> for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a: >> >> MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 22:06:04 +0200) >> >> ---------------------------------------------------------------- >> QOM patches for 2020-06-15 >> >> * Make "info qom-tree" show children sorted >> * Fixes around device realization >> * Rework how we plug into devices into their parent bus > > Hi. I've just noticed that this commit added new global-scope > functions to header files without documentation comments, eg > > bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); They actually have doc comments: next to their definition, just like the functions they replace. We've argued about whether to put them next to definitions or next to declarations several times, and I'd prefer not to rehash all that now. QEMU uses different styles of function comments. I always try to make my new function comments consistent with nearby existing ones, if any. Sadly, not everybody does. Qdev used to be locally consistent, but we've let it degenerate into the current mess. It's what happens when major infrastructure subsystems have to go without a maintainer for years. > Please could you provide some follow-up patches that document them? > I don't think we have any hope of getting people to follow whatever > the correct new way to create/configure/realize devices is if we > don't document it :-( [Concrete example: I now have no idea > how this is supposed to work after this patchset.] Please check out my function comments, and if they leave you confused, let's talk about improvements. I'm content to use comment placement / formatting I dislike to make my code blend in, but I'm not willing to do conversion work from a style I like to style I dislike. That's a job for someone who won't feel icky afterwards :)
On Sat, 27 Jun 2020 at 12:53, Markus Armbruster <armbru@redhat.com> wrote: > Peter Maydell <peter.maydell@linaro.org> writes: > > Hi. I've just noticed that this commit added new global-scope > > functions to header files without documentation comments, eg > > > > bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); > > They actually have doc comments: next to their definition, just like the > functions they replace. > > Please could you provide some follow-up patches that document them? > > I don't think we have any hope of getting people to follow whatever > > the correct new way to create/configure/realize devices is if we > > don't document it :-( [Concrete example: I now have no idea > > how this is supposed to work after this patchset.] > > Please check out my function comments, and if they leave you confused, > let's talk about improvements. I will have a look at them, but we should move them (wholesale with other documentation comments for qdev) to the header files. (That we are having this discussion at all demonstrates why -- people don't look in the C files for API documentation of functions.) The headers are where the API that faces the rest of QEMU should be documented; comments in the C files are for people who care about the internals of the implementation. "New prototype in a header file should have a doc comment" is a standard part of my code review I apply to any code which I see going past. We absolutely have not been good about documenting our facing-the-rest-of-QEMU functions in the past but this is an area where I think we should be raising the bar. > I'm content to use comment placement / formatting I dislike to make my > code blend in, but I'm not willing to do conversion work from a style I > like to style I dislike. That's a job for someone who won't feel icky > afterwards :) Fair enough. I'm happy to write some patches to consistently put all the qdev doc info into the headers. thanks -- PMM
On 6/27/20 5:11 PM, Peter Maydell wrote: > On Sat, 27 Jun 2020 at 12:53, Markus Armbruster <armbru@redhat.com> wrote: >> Peter Maydell <peter.maydell@linaro.org> writes: >>> Hi. I've just noticed that this commit added new global-scope >>> functions to header files without documentation comments, eg >>> >>> bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); >> >> They actually have doc comments: next to their definition, just like the >> functions they replace. > >>> Please could you provide some follow-up patches that document them? >>> I don't think we have any hope of getting people to follow whatever >>> the correct new way to create/configure/realize devices is if we >>> don't document it :-( [Concrete example: I now have no idea >>> how this is supposed to work after this patchset.] >> >> Please check out my function comments, and if they leave you confused, >> let's talk about improvements. > > I will have a look at them, but we should move them (wholesale > with other documentation comments for qdev) to the header files. > (That we are having this discussion at all demonstrates why -- people > don't look in the C files for API documentation of functions.) > The headers are where the API that faces the rest of QEMU should > be documented; comments in the C files are for people who care > about the internals of the implementation. "New prototype in a header > file should have a doc comment" is a standard part of my code review > I apply to any code which I see going past. We absolutely have not > been good about documenting our facing-the-rest-of-QEMU functions > in the past but this is an area where I think we should be raising the bar. > >> I'm content to use comment placement / formatting I dislike to make my >> code blend in, but I'm not willing to do conversion work from a style I >> like to style I dislike. That's a job for someone who won't feel icky >> afterwards :) > > Fair enough. I'm happy to write some patches to consistently put > all the qdev doc info into the headers. As a start I can respin https://www.mail-archive.com/qemu-devel@nongnu.org/msg593422.html if you want.