plugins/lockstep: document plugin logging requirement

qemu_plugin_outs() output from this plugin — including the
"No divergence :-)" summary and any divergence reports — is routed
through qemu_log_mask(CPU_LOG_PLUGIN, ...), which is silent unless
QEMU's own logging is enabled. A user running the plugin exactly as
shown in this file's own usage will see no output at all and can
reasonably conclude the plugin is doing nothing.

Document that -d plugin -D <logfile> is required to see any output.

Found via manual, reproducible experimentation (deterministic guest
binary, controlled single-instruction divergence, TB-address and
instruction-count cross-checked against objdump) with AI (Claude)
assistance in the investigation; the missing-output behavior and the
fix were independently verified by hand before this patch was written.

Signed-off-by: Dalbir <dalbirrana838@gmail.com>

diff --git a/contrib/plugins/lockstep.c b/contrib/plugins/lockstep.c
index xxxxxxx..xxxxxxx 100644
--- a/contrib/plugins/lockstep.c
+++ b/contrib/plugins/lockstep.c
@@ -7,6 +7,12 @@
  * introduced a subtle and hard to find bug.
  *
  * Caveats:
+ *   - qemu_plugin_outs() output (including "No divergence :-)" and any
+ *     divergence reports) is routed through the plugin log mask, so it is
+ *     silent unless QEMU's own logging is enabled, e.g.:
+ *         -d plugin -D /path/to/logfile
+ *     Without -d plugin, the plugin runs and compares correctly but
+ *     produces no visible output at all.
  *   - single-threaded linux-user apps only with non-deterministic syscalls
  *   - no MTTCG enabled system emulation (icount may help)
  *

Hi Dalbir,

On 8/23/2026 5:31 AM, Dalbir Singh wrote:
> plugins/lockstep: document plugin logging requirement
> 
> qemu_plugin_outs() output from this plugin — including the
> "No divergence :-)" summary and any divergence reports — is routed
> through qemu_log_mask(CPU_LOG_PLUGIN, ...), which is silent unless
> QEMU's own logging is enabled. A user running the plugin exactly as
> shown in this file's own usage will see no output at all and can
> reasonably conclude the plugin is doing nothing.
> 
> Document that -d plugin -D <logfile> is required to see any output.
> 
> Found via manual, reproducible experimentation (deterministic guest
> binary, controlled single-instruction divergence, TB-address and
> instruction-count cross-checked against objdump) with AI (Claude)
> assistance in the investigation; the missing-output behavior and the
> fix were independently verified by hand before this patch was written.
> 
> Signed-off-by: Dalbir <dalbirrana838@gmail.com>
> 
> diff --git a/contrib/plugins/lockstep.c b/contrib/plugins/lockstep.c
> index xxxxxxx..xxxxxxx 100644
> --- a/contrib/plugins/lockstep.c
> +++ b/contrib/plugins/lockstep.c
> @@ -7,6 +7,12 @@
>   * introduced a subtle and hard to find bug.
>   *
>   * Caveats:
> + *   - qemu_plugin_outs() output (including "No divergence :-)" and any
> + *     divergence reports) is routed through the plugin log mask, so it is
> + *     silent unless QEMU's own logging is enabled, e.g.:
> + *         -d plugin -D /path/to/logfile
> + *     Without -d plugin, the plugin runs and compares correctly but
> + *     produces no visible output at all.
>   *   - single-threaded linux-user apps only with non-deterministic syscalls
>   *   - no MTTCG enabled system emulation (icount may help)
>   *

it might not be intuitive, nor documented properly, but it's the default
for all plugins we have upstream.

Regards,
Pierrick

Hi Pierrick,

Thanks for the clarification. I hadn't realised that this was the default
logging behaviour for all upstream plugins.

I agree that documenting it specifically in lockstep.c would duplicate the
general plugin convention, so I'll withdraw this patch.

Regards,
Dalbir

On Mon, 24 Aug 2026 at 22:53, Pierrick Bouvier
<pierrick.bouvier@oss.qualcomm.com> wrote:
>
> Hi Dalbir,
>
> On 8/23/2026 5:31 AM, Dalbir Singh wrote:
> > plugins/lockstep: document plugin logging requirement
> >
> > qemu_plugin_outs() output from this plugin — including the
> > "No divergence :-)" summary and any divergence reports — is routed
> > through qemu_log_mask(CPU_LOG_PLUGIN, ...), which is silent unless
> > QEMU's own logging is enabled. A user running the plugin exactly as
> > shown in this file's own usage will see no output at all and can
> > reasonably conclude the plugin is doing nothing.
> >
> > Document that -d plugin -D <logfile> is required to see any output.
> >
> > Found via manual, reproducible experimentation (deterministic guest
> > binary, controlled single-instruction divergence, TB-address and
> > instruction-count cross-checked against objdump) with AI (Claude)
> > assistance in the investigation; the missing-output behavior and the
> > fix were independently verified by hand before this patch was written.
> >
> > Signed-off-by: Dalbir <dalbirrana838@gmail.com>
> >
> > diff --git a/contrib/plugins/lockstep.c b/contrib/plugins/lockstep.c
> > index xxxxxxx..xxxxxxx 100644
> > --- a/contrib/plugins/lockstep.c
> > +++ b/contrib/plugins/lockstep.c
> > @@ -7,6 +7,12 @@
> >   * introduced a subtle and hard to find bug.
> >   *
> >   * Caveats:
> > + *   - qemu_plugin_outs() output (including "No divergence :-)" and any
> > + *     divergence reports) is routed through the plugin log mask, so it is
> > + *     silent unless QEMU's own logging is enabled, e.g.:
> > + *         -d plugin -D /path/to/logfile
> > + *     Without -d plugin, the plugin runs and compares correctly but
> > + *     produces no visible output at all.
> >   *   - single-threaded linux-user apps only with non-deterministic syscalls
> >   *   - no MTTCG enabled system emulation (icount may help)
> >   *
>
> it might not be intuitive, nor documented properly, but it's the default
> for all plugins we have upstream.
>
> Regards,
> Pierrick