Re: [PATCH 08/16] cpus: Slightly improve *run_on_cpu() docstrings

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_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.

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()).

Paolo

>    */
>   void async_safe_run_on_cpu(CPUState *cpu, run_on_cpu_func func, run_on_cpu_data data);
>