Make the relationship between CPUState, ArchCPU and cpu_env a bit
clearer in the kdoc comments.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 include/hw/core/cpu.h | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/include/hw/core/cpu.h b/include/hw/core/cpu.h
index bb398e8237..35d345371b 100644
--- a/include/hw/core/cpu.h
+++ b/include/hw/core/cpu.h
@@ -391,7 +391,8 @@ struct qemu_work_item;
 #define CPU_UNSET_NUMA_NODE_ID -1
 
 /**
- * CPUState:
+ * struct CPUState - common state of one CPU core or thread.
+ *
  * @cpu_index: CPU index (informative).
  * @cluster_index: Identifies which cluster this CPU is in.
  *   For boards which don't define clusters or for "loose" CPUs not assigned
@@ -439,10 +440,15 @@ struct qemu_work_item;
  * @kvm_fetch_index: Keeps the index that we last fetched from the per-vCPU
  *    dirty ring structure.
  *
- * State of one CPU core or thread.
+ * @neg_align: The CPUState is the common part of a concrete ArchCPU
+ * which is allocated when an individual CPU instance is created. As
+ * such care is taken is ensure there is no gap between between
+ * CPUState and CPUArchState within ArchCPU.
  *
- * Align, in order to match possible alignment required by CPUArchState,
- * and eliminate a hole between CPUState and CPUArchState within ArchCPU.
+ * @neg: The architectural register state ("cpu_env") immediately follows CPUState
+ * in ArchCPU and is passed to TCG code. The @neg structure holds some
+ * common TCG CPU variables which are accessed with a negative offset
+ * from cpu_env.
  */
 struct CPUState {
     /*< private >*/
-- 
2.39.2

On 30/5/24 21:42, Alex Bennée wrote:
> Make the relationship between CPUState, ArchCPU and cpu_env a bit
> clearer in the kdoc comments.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   include/hw/core/cpu.h | 14 ++++++++++----
>   1 file changed, 10 insertions(+), 4 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

On 5/30/24 12:42, Alex Bennée wrote:
> Make the relationship between CPUState, ArchCPU and cpu_env a bit
> clearer in the kdoc comments.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   include/hw/core/cpu.h | 14 ++++++++++----
>   1 file changed, 10 insertions(+), 4 deletions(-)
> 
> diff --git a/include/hw/core/cpu.h b/include/hw/core/cpu.h
> index bb398e8237..35d345371b 100644
> --- a/include/hw/core/cpu.h
> +++ b/include/hw/core/cpu.h
> @@ -391,7 +391,8 @@ struct qemu_work_item;
>   #define CPU_UNSET_NUMA_NODE_ID -1
>   
>   /**
> - * CPUState:
> + * struct CPUState - common state of one CPU core or thread.
> + *
>    * @cpu_index: CPU index (informative).
>    * @cluster_index: Identifies which cluster this CPU is in.
>    *   For boards which don't define clusters or for "loose" CPUs not assigned
> @@ -439,10 +440,15 @@ struct qemu_work_item;
>    * @kvm_fetch_index: Keeps the index that we last fetched from the per-vCPU
>    *    dirty ring structure.
>    *
> - * State of one CPU core or thread.
> + * @neg_align: The CPUState is the common part of a concrete ArchCPU
> + * which is allocated when an individual CPU instance is created. As
> + * such care is taken is ensure there is no gap between between
> + * CPUState and CPUArchState within ArchCPU.
>    *
> - * Align, in order to match possible alignment required by CPUArchState,
> - * and eliminate a hole between CPUState and CPUArchState within ArchCPU.
> + * @neg: The architectural register state ("cpu_env") immediately follows CPUState
> + * in ArchCPU and is passed to TCG code. The @neg structure holds some
> + * common TCG CPU variables which are accessed with a negative offset
> + * from cpu_env.
>    */
>   struct CPUState {
>       /*< private >*/

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>