Re: [PATCH v2 27/28] tcg: Update docs/devel/tcg-ops.rst for temporary changes

[Peter Maydell]

On Wed, 22 Feb 2023 at 23:32, Richard Henderson
<richard.henderson@linaro.org> wrote:
>
> Rewrite the sections which talked about 'local temporaries'.
> Remove some assumptions which no longer hold.
>
> Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
> ---
>  docs/devel/tcg-ops.rst | 103 +++++++++++++++++++++--------------------
>  1 file changed, 54 insertions(+), 49 deletions(-)
>
> diff --git a/docs/devel/tcg-ops.rst b/docs/devel/tcg-ops.rst
> index 9adc0c9b6c..53b7b6c93b 100644
> --- a/docs/devel/tcg-ops.rst
> +++ b/docs/devel/tcg-ops.rst
> @@ -29,21 +29,42 @@ In this document, we use *guest* to specify what 
> architecture we are
>  emulating; *target* always means the TCG target, the machine on which
>  we are running QEMU.
>
> -A TCG *function* corresponds to a QEMU Translated Block (TB).
> +A TCG *basic block* is a single entry, multiple exit region which
> +corresponds to a list of instructions terminated by a label, or
> +any branch instruction.
>
> -A TCG *temporary* is a variable only live in a basic block. Temporaries are 
> allocated explicitly in each function.
> +A TCG *extended basic block* is a single entry, multiple exit region
> +which corresponds to a list of instructions terminated by a label or
> +an unconditional branch.  Specifically, an extended basic block is
> +a sequence of basic blocks connected by the fall-through paths of
> +zero or more conditional branch instructions.
>
> -A TCG *local temporary* is a variable only live in a function. Local 
> temporaries are allocated explicitly in each function.
> +There is one TCG *fixed global* (``TEMP_FIXED``) variable, ``cpu_env``
> +which is live in all translation blocks, and holds a pointer to 
> ``CPUArchState``.
> +This fixed global is held in a host cpu register at all times in all
> +translation blocks.
>
> -A TCG *global* is a variable which is live in all the functions
> -(equivalent of a C global variable). They are defined before the
> -functions defined. A TCG global can be a memory location (e.g. a QEMU
> -CPU register), a fixed host register (e.g. the QEMU CPU state pointer)
> -or a memory location which is stored in a register outside QEMU TBs
> -(not implemented yet).
> +A TCG *global* (``TEMP_GLOBAL``) is a variable which is live in all
> +translation blocks, and correspond to memory locations that are within

"corresponds to a memory location that is within"

> +``CPUArchState``.  These may be specified as an offset from ``cpu_env``,
> +in which case they are called *direct globals*, or may be specified as
> +an offset from a direct global, in which case they are called
> +*indirect globals*.  Even indirect globals should still reference memory
> +within ``CPUArchState``.  All TCG globals are defined during
> +``TCGCPUOps.initialize``, before any translation blocks are generated.

We could split out the definitions of the different kinds of
variable into their own subsection "TCG Variables"...

> @@ -57,11 +78,11 @@ Intermediate representation
>  Introduction
>  ------------
>
> -TCG instructions operate on variables which are temporaries, local
> -temporaries or globals. TCG instructions and variables are strongly
> -typed. Two types are supported: 32 bit integers and 64 bit
> -integers. Pointers are defined as an alias to 32 bit or 64 bit
> -integers depending on the TCG target word size.
> +TCG instructions operate on variables which are temporaries.

...and then we could say here "TCG instructions operate on
TCG variables", avoiding the slightly confusing "which are
temporaries" that suggests that globals and constants are
not included.

Alternatively we could perhaps explicitly list them here
"operate on variables (TEMP_FIXED, TEMP_GLOBAL, TEMP_CONST,
TEMP_BB, TEMP_EBB)".

> +TCG instructions and variables are strongly typed.
> +Two types are supported: 32 bit integers and 64 bit integers.
> +Pointers are defined as an alias to 32 bit or 64 bit integers
> +depending on the TCG target word size.
>
>  Each instruction has a fixed number of output variable operands, input
>  variable operands and always constant operands.

Otherwise
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM