Re: [PATCH 8/8] qemu-options: Add the description of smp-cache object

[Markus Armbruster <armbru@redhat.com>]

Zhao Liu <zhao1.liu@intel.com> writes:

> Hi Markus,
>
> On Mon, Jul 22, 2024 at 03:37:43PM +0200, Markus Armbruster wrote:
>> Date: Mon, 22 Jul 2024 15:37:43 +0200
>> From: Markus Armbruster <armbru@redhat.com>
>> Subject: Re: [PATCH 8/8] qemu-options: Add the description of smp-cache
>>  object
>> 
>> Zhao Liu <zhao1.liu@intel.com> writes:
>> 
>> > Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
>> 
>> This patch is just documentation.  The code got added in some previous
>> patch.  Would it make sense to squash this patch into that previous
>> patch?
>
> OK, I'll merge them.
>
>> > ---
>> > Changes since RFC v2:
>> >  * Rewrote the document of smp-cache object.
>> >
>> > Changes since RFC v1:
>> >  * Use "*_cache=topo_level" as -smp example as the original "level"
>> >    term for a cache has a totally different meaning. (Jonathan)
>> > ---
>> >  qemu-options.hx | 58 +++++++++++++++++++++++++++++++++++++++++++++++++
>> >  1 file changed, 58 insertions(+)
>> >
>> > diff --git a/qemu-options.hx b/qemu-options.hx
>> > index 8ca7f34ef0c8..4b84f4508a6e 100644
>> > --- a/qemu-options.hx
>> > +++ b/qemu-options.hx
>> > @@ -159,6 +159,15 @@ SRST
>> >          ::
>> >  
>> >              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
>> > +
>> > +    ``smp-cache='id'``
>> > +        Allows to configure cache property (now only the cache topology level).
>> > +
>> > +        For example:
>> > +        ::
>> > +
>> > +            -object '{"qom-type":"smp-cache","id":"cache","caches":[{"name":"l1d","topo":"core"},{"name":"l1i","topo":"core"},{"name":"l2","topo":"module"},{"name":"l3","topo":"die"}]}'
>> > +            -machine smp-cache=cache
>> >  ERST
>> >  
>> >  DEF("M", HAS_ARG, QEMU_OPTION_M,
>> > @@ -5871,6 +5880,55 @@ SRST
>> >          ::
>> >  
>> >              (qemu) qom-set /objects/iothread1 poll-max-ns 100000
>> > +
>> > +    ``-object '{"qom-type":"smp-cache","id":id,"caches":[{"name":cache_name,"topo":cache_topo}]}'``
>> > +        Create an smp-cache object that configures machine's cache
>> > +        property. Currently, cache property only include cache topology
>> > +        level.
>> > +
>> > +        This option must be written in JSON format to support JSON list.
>> 
>> Why?
>
> I'm not familiar with this, so I hope you could educate me if I'm wrong.
>
> All I know so far is for -object that defining a list can only be done in
> JSON format and not with a numeric index like a keyval based option, like:
>
> -object smp-cache,id=cache0,caches.0.name=l1i,caches.0.topo=core: Parameter 'caches' is missing
>
> the above doesn't work.
>
> Is there any other way to specify a list in command line?

The command line is a big, sprawling mess :)

-object supports either a JSON or a QemuOpts argument.  *Not* keyval!

Both QemuOpts and keyval parse something like KEY=VALUE,...  Keyval
supports arrays and objects via dotted keys.  QemuOpts doesn't natively
support arrays and objects, but its users can hack around that
limitation in various ways.  -object doesn't.  So you're right, it's
JSON or bust here.

However, if we used one object per cache instead, we could get something
like

    -object smp-cache,name=l1d,...
    -object smp-cache,name=l1u,...
    -object smp-cache,name=l2,...
    ...

>> > +
>> > +        The ``caches`` parameter accepts a list of cache property in JSON
>> > +        format.
>> > +
>> > +        A list element requires the cache name to be specified in the
>> > +        ``name`` parameter (currently ``l1d``, ``l1i``, ``l2`` and ``l3``
>> > +        are supported). ``topo`` parameter accepts CPU topology levels
>> > +        including ``thread``, ``core``, ``module``, ``cluster``, ``die``,
>> > +        ``socket``, ``book``, ``drawer`` and ``default``. The ``topo``
>> > +        parameter indicates CPUs winthin the same CPU topology container
>> > +        are sharing the same cache.
>> > +
>> > +        Some machines may have their own cache topology model, and this
>> > +        object may override the machine-specific cache topology setting
>> > +        by specifying smp-cache object in the -machine. When specifying
>> > +        the cache topology level of ``default``, it will honor the default
>> > +        machine-specific cache topology setting. For other topology levels,
>> > +        they will override the default setting.
>> > +
>> > +        An example list of caches to configure the cache model (l1d cache
>> > +        per core, l1i cache per core, l2 cache per module and l3 cache per
>> > +        socket) supported by PC machine might look like:
>> > +
>> > +        ::
>> > +
>> > +              {
>> > +                "caches": [
>> > +                   { "name": "l1d", "topo": "core" },
>> > +                   { "name": "l1i", "topo": "core" },
>> > +                   { "name": "l2", "topo": "module" },
>> > +                   { "name": "l3", "topo": "socket" },
>> > +                ]
>> > +              }
>> > +
>> > +        An example smp-cache object would look like:()
>> > +
>> > +        .. parsed-literal::
>> > +
>> > +             # |qemu_system| \\
>> > +                 ... \\
>> > +                 -object '{"qom-type":"smp-cache","id":id,"caches":[{"name":cache_name,"topo":cache_topo}]}' \\
>> > +                 ...
>> >  ERST
>>