Be a bit more precise mentioning BQL use and blocking calls. Signed-off-by: Philippe Mathieu-Daudé --- 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_run_on_cpu: - * @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. - */ -void async_run_on_cpu(CPUState *cpu, run_on_cpu_func func, run_on_cpu_data data); - -/** - * async_safe_run_on_cpu: + * async_run_on_cpu - Queue a function for execution on a vCPU * @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, - * while all other vCPUs are sleeping. + * then return immediately without waiting. * - * Unlike run_on_cpu and async_run_on_cpu, the function is run outside the - * BQL. + * Note: The vCPU will hold the BQL when executing @func. + */ +void async_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. */ void async_safe_run_on_cpu(CPUState *cpu, run_on_cpu_func func, run_on_cpu_data data); -- 2.53.0