[RFC,0/3] Improve scalability of the SMP related Docs

Message

Yanan Wang Oct. 7, 2021, 10:43 a.m. UTC

Hi,

The motivation of this series is to improve the scalability of SMP
related Docs, so that we can easily/clearly extend them without making
confusion when we plan to introduce more target specific CPU topology
members (e.g. CPU cluster in Arm and CPU drawer/book in s390).

With more and more target specific CPU topology members introduced,
it may not be a good method any longer to put all the mixed parameters
into one single hierarchy and then describe the exact meaning of each
member in the Docs, which makes confusion for the reader. On the contrary,
it may be clearer to describe the currently supported sub-hierarchies
separately and better to list some examples in the Docs. For example,
for now we can describe "sockets/cores/threads" and "sockets/dies/cores/
threads" separately from the mixture of "sockets | dies | cores | threads",
and more sub-hierarchies can be described when new parameters are added.

Based on above consideration, correspondingly -smp docs in qemu-options,
comment of struct CpuTopology and SMP related comments in qapi/machine
are somehow rewritten.

Besides the maintainers, I also keep some people on Cc list who may be
interested in having a look at this. Comments welcome!

Thanks,
Yanan
.

Yanan Wang (3):
  qemu-options: Improve scalability of the -smp documentation
  include/hw/boards: Improve scalability of the CpuTopology comment
  qapi/machine.json: Improve scalability of the SMP related comments

 include/hw/boards.h | 26 +++++++++++--
 qapi/machine.json   | 47 ++++++++++++++++++-----
 qemu-options.hx     | 90 ++++++++++++++++++++++++++++++++++++---------
 3 files changed, 133 insertions(+), 30 deletions(-)

--
2.19.1

Comments

Yanan Wang Oct. 20, 2021, 2:20 a.m. UTC | #1

Ping...

Is this a right direction to go or should I continue on with this ?

On 2021/10/7 18:43, Yanan Wang wrote:
> Hi,
>
> The motivation of this series is to improve the scalability of SMP
> related Docs, so that we can easily/clearly extend them without making
> confusion when we plan to introduce more target specific CPU topology
> members (e.g. CPU cluster in Arm and CPU drawer/book in s390).
>
> With more and more target specific CPU topology members introduced,
> it may not be a good method any longer to put all the mixed parameters
> into one single hierarchy and then describe the exact meaning of each
> member in the Docs, which makes confusion for the reader. On the contrary,
> it may be clearer to describe the currently supported sub-hierarchies
> separately and better to list some examples in the Docs. For example,
> for now we can describe "sockets/cores/threads" and "sockets/dies/cores/
> threads" separately from the mixture of "sockets | dies | cores | threads",
> and more sub-hierarchies can be described when new parameters are added.
>
> Based on above consideration, correspondingly -smp docs in qemu-options,
> comment of struct CpuTopology and SMP related comments in qapi/machine
> are somehow rewritten.
>
> Besides the maintainers, I also keep some people on Cc list who may be
> interested in having a look at this. Comments welcome!
>
> Thanks,
> Yanan
> .
>
> Yanan Wang (3):
>    qemu-options: Improve scalability of the -smp documentation
>    include/hw/boards: Improve scalability of the CpuTopology comment
>    qapi/machine.json: Improve scalability of the SMP related comments
>
>   include/hw/boards.h | 26 +++++++++++--
>   qapi/machine.json   | 47 ++++++++++++++++++-----
>   qemu-options.hx     | 90 ++++++++++++++++++++++++++++++++++++---------
>   3 files changed, 133 insertions(+), 30 deletions(-)
>
> --
> 2.19.1
>
> .