On Mon, 17 Aug 2026 at 16:50, Paolo Bonzini <[email protected]> wrote: > > On 8/13/26 20:16, Philippe Mathieu-Daudé wrote: > > Be a bit more precise mentioning BQL use and blocking calls. > > > > Signed-off-by: Philippe Mathieu-Daudé <[email protected]> > > --- > > include/hw/core/cpu.h | 36 ++++++++++++++++++++---------------- > > 1 file changed, 20 insertions(+), 16 deletions(-) > > > > diff --git a/include/hw/core/cpu.h b/include/hw/core/cpu.h > > index 183ef9f4ef2..d610f87abd3 100644 > > --- a/include/hw/core/cpu.h > > +++ b/include/hw/core/cpu.h > > @@ -908,36 +908,40 @@ void do_run_on_cpu(CPUState *cpu, run_on_cpu_func > > func, run_on_cpu_data data, > > QemuMutex *mutex); > > > > /** > > - * run_on_cpu: > > + * run_on_cpu - Execute a function on a vCPU and wait for completion > > * @cpu: The vCPU to run on. > > * @func: The function to be executed. > > * @data: Data to pass to the function. > > * > > - * Schedules the function @func for execution on the vCPU @cpu. > > + * Schedules the function @func for execution on the vCPU @cpu and > > + * block until it completes. > > + * > > + * Note: The caller must hold the BQL. > > */ > > void run_on_cpu(CPUState *cpu, run_on_cpu_func func, run_on_cpu_data > > data);
> > +/** > > + * async_safe_run_on_cpu - Queue a function to run with other vCPUs paused > > + * @cpu: The vCPU to run on. > > + * @func: The function to be executed. > > + * @data: Data to pass to the function. > > + * > > + * Schedules the function @func for execution on the vCPU @cpu > > asynchronously. > > + * Unlike async_run_on_cpu(), all other vCPUs are paused while @func > > executes, > > + * ensuring @cpu has exclusive access to shared state. > > Might as well mention that @func is run without the BQL taken and in > fact must not take it (see comment in process_queued_cpu_work()). We should also mention the massive bear-trap in the run_on_cpu() function, which is that (a) you must call it with the BQL and (b) it will *drop the BQL* during the course of execution, so the caller must be prepared for other threads etc to be able to reenter it, update state, etc between when it calls run_on_cpu() and when it returns. (cf https://gitlab.com/qemu-project/qemu/-/work_items/1109 where we can segfault in the raspi display device, because memory_region_snapshot_and_clear_dirty() drops the BQL and allows the device code to be re-entered, much to its surprise.) thanks -- PMM
