Motivation
==========

Here is the motivation for this patch set. Please try to answer the
following 3 questions without checking QEMU source code:

1. How do you run RISC-V QEMU with a specific extension configuration?
   Please try to configure an rv64im user mode QEMU before you answer
   this question.
2. How do you know which extensions are supported in RISC-V QEMU?
3. How do you know which extensions are enabled in the current RISC-V QEMU?

And here are my answers to those 3 questions:

1. It's hard to configure RISC-V QEMU with a specific extension. The
   correct way to configure rv64im is:

     qemu-riscv64 -cpu rv64,a=false,d=false,f=false,zfa=false,zawrs=false,\
       c=false,zifencei=false,zicsr=false,zihintntl=false,zihintpause=false,\
       zbb=false,zba=false,zbs=false,zbc=false,zicbom=false,zicbop=false,\
       zicboz=false

   I've seen 4 different QEMU wrappers to handle arch string to QEMU CPU
   option: 3 in-house scripts, 1 open source script in riscv-gnu-toolchain,
   and I guess some vendors/developers may have their own scripts to do
   that as well...

2. I don't know a better way other than reading the QEMU source code.

3. I don't really know the answer...

So how do other tools/simulators address these problems? Toolchains like
Clang and GCC use -march with an arch string to configure, and Spike uses
--isa=<ISA-string> to configure.

Could we introduce a similar way to configure QEMU? Yes, I think we can.
That's what this patch set does.

  -cpu rv64,arch=<ISA-string>

to configure QEMU. And also introduce arch=help and arch=dump to show
which extensions are supported, and which extensions are enabled/disabled.

Also supported:

  arch=<profile>["_"optional-ext]*

to specify configuration with RISC-V profiles like the toolchain convention[1].

[1] https://github.com/riscv-non-isa/riscv-toolchain-conventions/blob/main/src/toolchain-conventions.adoc#specifying-the-target-profile-with--march

Overview
========

This patch series introduces the arch= CPU property for RISC-V, providing
a convenient interface to configure ISA extensions similar to GCC/Clang's
-march option.

The arch= property supports the following modes:

1. arch=dump
   Print the current ISA configuration and exit. Shows the full ISA string
   and the status of all supported extensions.

   Example:
     $ qemu-riscv64 -cpu rv64,v=true,arch=dump /bin/true

2. arch=help
   Print a list of all supported ISA extensions and exit. Lists standard
   single-letter extensions, multi-letter extensions, vendor extensions,
   profiles, and vector length extensions.

   Example:
     $ qemu-riscv64 -cpu rv64,arch=help /bin/true

3. arch=<ISA-STRING>
   Configure extensions using a standard RISC-V ISA string. The format is
   rv{32|64}[single-letter-exts][_multi-letter-ext]*.

   Key features:
   - First extension must be i, e, or g (base ISA requirement)
   - Single-letter extensions can be concatenated (rv64imafdc)
   - Single-letter extensions can use underscore separators (rv64i_m_a_f_d_c)
   - Multi-letter extensions are separated by underscores (_zba_zbb)
   - Single-letter can transition directly to multi-letter (rv64imazba)
   - Extensions i, e, g can only appear as the first extension
   - When arch= is specified, all extensions are first reset to disabled
   - G expands to imafd_zicsr_zifencei
   - B expands to zba_zbb_zbs

   Examples:
     $ qemu-riscv64 -cpu rv64,arch=rv64gc_zba_zbb /bin/true
     $ qemu-riscv64 -cpu rv64,arch=rv64imafdc_zba_zbb_zbc /bin/true

4. arch=<PROFILE>[_extension]*
   Configure the CPU using a standard RISC-V profile, optionally with
   additional extensions. Available profiles (64-bit only):
   - rva22u64, rva22s64, rva23u64, rva23s64

   Examples:
     $ qemu-riscv64 -cpu rv64,arch=rva23u64 /bin/true
     $ qemu-riscv64 -cpu rv64,arch=rva23u64_zbkb_zkne /bin/true

5. zvl*b extensions
   Specify vector length (VLEN) in bits using zvl<N>b where N is a power
   of 2 (32-65536). Requires v or zve* extension.

   Examples:
     $ qemu-riscv64 -cpu rv64,arch=rv64gcv_zvl256b /bin/true
     $ qemu-riscv64 -cpu rv64,arch=rv64i_zve64f_zvl128b /bin/true

Individual extension properties (e.g., zba=true) can be combined with
arch= and will override the ISA string settings when specified after arch=.

Kito Cheng (5):
  target/riscv: Add arch=dump CPU property for ISA introspection
  target/riscv: Add arch=help to list supported ISA extensions
  target/riscv: Add arch=ISA-STRING to configure extensions via ISA
    string
  target/riscv: Add arch=PROFILE to configure CPU using RISC-V profiles
  target/riscv: Add zvl*b extension support in arch= property

 docs/system/target-riscv.rst              | 144 ++++++++
 target/riscv/cpu.c                        | 226 ++++++++++++
 target/riscv/cpu.h                        |   1 +
 target/riscv/cpu_cfg_fields.h.inc         |   3 +
 target/riscv/tcg/tcg-cpu.c                | 424 ++++++++++++++++++++++
 tests/functional/riscv32/meson.build      |   4 +
 tests/functional/riscv32/test_cpu_arch.py |  94 +++++
 tests/functional/riscv64/meson.build      |   4 +
 tests/functional/riscv64/test_cpu_arch.py | 411 +++++++++++++++++++++
 9 files changed, 1311 insertions(+)
 create mode 100644 tests/functional/riscv32/test_cpu_arch.py
 create mode 100644 tests/functional/riscv64/test_cpu_arch.py

--
2.52.0

On 1/5/26 7:59 AM, Kito Cheng wrote:
> Motivation
> ==========
> 
> Here is the motivation for this patch set. Please try to answer the
> following 3 questions without checking QEMU source code:
> 
> 1. How do you run RISC-V QEMU with a specific extension configuration?
>     Please try to configure an rv64im user mode QEMU before you answer
>     this question.

I would use the 'rv64i' bare CPU that we introduced a few releases ago
and enable just 'm':

qemu-riscv64 -cpu rv64i,m=on


It gives you a bare bones CPU with only "RVI" enabled. We added this CPU
specifically to support the use case you mentioned: users that want to
have full control of what is enabled in the CPU.

> 2. How do you know which extensions are supported in RISC-V QEMU?

You mean all available extensions? We don't have an user friendly way of
knowing that. I usually grep the code.

> 3. How do you know which extensions are enabled in the current RISC-V QEMU?


We can fetch them using query-cpu-model-expansion from QMP. But that's
not exactly user friendly.

> 
> And here are my answers to those 3 questions:
> 
> 1. It's hard to configure RISC-V QEMU with a specific extension. The
>     correct way to configure rv64im is:
> 
>       qemu-riscv64 -cpu rv64,a=false,d=false,f=false,zfa=false,zawrs=false,\
>         c=false,zifencei=false,zicsr=false,zihintntl=false,zihintpause=false,\
>         zbb=false,zba=false,zbs=false,zbc=false,zicbom=false,zicbop=false,\
>         zicboz=false

As I said above:

qemu-riscv64 -cpu rv64i,m=on


> 
>     I've seen 4 different QEMU wrappers to handle arch string to QEMU CPU
>     option: 3 in-house scripts, 1 open source script in riscv-gnu-toolchain,
>     and I guess some vendors/developers may have their own scripts to do
>     that as well...

We can't control how riscv-gnu-toolchain and others implement their scripts and
wrappers. These are the kind of thing that people write once and never look it
back, and that's fine.

That said, we have 'rv64i' and other bare CPUs since QEMU 9.0, released in April
24. We don't need to do this kind of massive extension disablement to get a
clean CPU for almost 2 years.

I advise to not take QEMU wrappers, scripts and etc from other projects as a sort
of proof of what QEMU is currently capable. They're usually outdated.
  

> 
> 2. I don't know a better way other than reading the QEMU source code.
> 
> 3. I don't really know the answer...
> 
> So how do other tools/simulators address these problems? Toolchains like
> Clang and GCC use -march with an arch string to configure, and Spike uses
> --isa=<ISA-string> to configure.
> 
> Could we introduce a similar way to configure QEMU? Yes, I think we can.
> That's what this patch set does.
> 
>    -cpu rv64,arch=<ISA-string>

I don't mind the 'arch' property if users find it easier to enable extensions with
it rather than the boolean properties, but it should be used on top of bare CPUs
only. Otherwise the 'arch' property would include the already enabled extensions
from 'rv64' and others.

And we would need to be okay with the fact that this is redundant to what we already
can do with bare CPUs + manual extension enablement.

> 
> to configure QEMU. And also introduce arch=help and arch=dump to show
> which extensions are supported, and which extensions are enabled/disabled.

arch=help and arch=dump is indeed a nice addition.


> 
> Also supported:
> 
>    arch=<profile>["_"optional-ext]*
> 
> to specify configuration with RISC-V profiles like the toolchain convention[1].


We have profile CPUs for this use case:

$ ./qemu-riscv64 -cpu help
Available CPUs:
   max
   rv64
   rv64e
   rv64i
   rva22s64
   rva22u64
   rva23s64
   rva23u64
(...)


So 'qemu-riscv64 -cpu rva23u64'  creates an user mode QEMU with RVA23.


> 
> [1] https://github.com/riscv-non-isa/riscv-toolchain-conventions/blob/main/src/toolchain-conventions.adoc#specifying-the-target-profile-with--march
> 
> Overview
> ========
> 
> This patch series introduces the arch= CPU property for RISC-V, providing
> a convenient interface to configure ISA extensions similar to GCC/Clang's
> -march option.
> 
> The arch= property supports the following modes:
> 
> 1. arch=dump
>     Print the current ISA configuration and exit. Shows the full ISA string
>     and the status of all supported extensions.
> 
>     Example:
>       $ qemu-riscv64 -cpu rv64,v=true,arch=dump /bin/true
> 
> 2. arch=help
>     Print a list of all supported ISA extensions and exit. Lists standard
>     single-letter extensions, multi-letter extensions, vendor extensions,
>     profiles, and vector length extensions.
> 
>     Example:
>       $ qemu-riscv64 -cpu rv64,arch=help /bin/true
> 
> 3. arch=<ISA-STRING>
>     Configure extensions using a standard RISC-V ISA string. The format is
>     rv{32|64}[single-letter-exts][_multi-letter-ext]*.
> 
>     Key features:
>     - First extension must be i, e, or g (base ISA requirement)
>     - Single-letter extensions can be concatenated (rv64imafdc)
>     - Single-letter extensions can use underscore separators (rv64i_m_a_f_d_c)
>     - Multi-letter extensions are separated by underscores (_zba_zbb)
>     - Single-letter can transition directly to multi-letter (rv64imazba)
>     - Extensions i, e, g can only appear as the first extension
>     - When arch= is specified, all extensions are first reset to disabled
>     - G expands to imafd_zicsr_zifencei
>     - B expands to zba_zbb_zbs
> 
>     Examples:
>       $ qemu-riscv64 -cpu rv64,arch=rv64gc_zba_zbb /bin/true
>       $ qemu-riscv64 -cpu rv64,arch=rv64imafdc_zba_zbb_zbc /bin/true
> 
> 4. arch=<PROFILE>[_extension]*
>     Configure the CPU using a standard RISC-V profile, optionally with
>     additional extensions. Available profiles (64-bit only):
>     - rva22u64, rva22s64, rva23u64, rva23s64
> 
>     Examples:
>       $ qemu-riscv64 -cpu rv64,arch=rva23u64 /bin/true
>       $ qemu-riscv64 -cpu rv64,arch=rva23u64_zbkb_zkne /bin/true
> 
> 5. zvl*b extensions
>     Specify vector length (VLEN) in bits using zvl<N>b where N is a power
>     of 2 (32-65536). Requires v or zve* extension.
> 
>     Examples:
>       $ qemu-riscv64 -cpu rv64,arch=rv64gcv_zvl256b /bin/true
>       $ qemu-riscv64 -cpu rv64,arch=rv64i_zve64f_zvl128b /bin/true

We already have vlen and elen properties. Not sure if we need another way to set
the same stuff.

I'll give a closer look later at the first 2 patches (arch=dump and arch=help)
since these are nice additions for the user experience.

I would like to hear other opinions about arch=<ISA_STRING> because it would be
just another way (probably an easier way) of doing what we already support with
bare CPUs + manual extension enablement.

I don't see the need to support arch=PROFILE given that we have profile CPUs
that does exactly that. Same thing for the 'vlen' setting.





> 
> Individual extension properties (e.g., zba=true) can be combined with
> arch= and will override the ISA string settings when specified after arch=.
> 
> Kito Cheng (5):
>    target/riscv: Add arch=dump CPU property for ISA introspection
>    target/riscv: Add arch=help to list supported ISA extensions
>    target/riscv: Add arch=ISA-STRING to configure extensions via ISA
>      string
>    target/riscv: Add arch=PROFILE to configure CPU using RISC-V profiles
>    target/riscv: Add zvl*b extension support in arch= property
> 
>   docs/system/target-riscv.rst              | 144 ++++++++
>   target/riscv/cpu.c                        | 226 ++++++++++++
>   target/riscv/cpu.h                        |   1 +
>   target/riscv/cpu_cfg_fields.h.inc         |   3 +
>   target/riscv/tcg/tcg-cpu.c                | 424 ++++++++++++++++++++++
>   tests/functional/riscv32/meson.build      |   4 +
>   tests/functional/riscv32/test_cpu_arch.py |  94 +++++
>   tests/functional/riscv64/meson.build      |   4 +
>   tests/functional/riscv64/test_cpu_arch.py | 411 +++++++++++++++++++++
>   9 files changed, 1311 insertions(+)
>   create mode 100644 tests/functional/riscv32/test_cpu_arch.py
>   create mode 100644 tests/functional/riscv64/test_cpu_arch.py
> 
> --
> 2.52.0
>

Hi Daniel:

Thanks for your reply, and here is my response :)

> > 1. How do you run RISC-V QEMU with a specific extension configuration?
> >     Please try to configure an rv64im user mode QEMU before you answer
> >     this question.
>
> I would use the 'rv64i' bare CPU that we introduced a few releases ago
> and enable just 'm':
>
> qemu-riscv64 -cpu rv64i,m=on
>
>
> It gives you a bare bones CPU with only "RVI" enabled. We added this CPU
> specifically to support the use case you mentioned: users that want to
> have full control of what is enabled in the CPU.

Oh, thanks for this info, my impression of this is stuck in my memory of 2022,
which is the time I wrote the qemu wrapper for riscv-gnu-toolchain,
So I'm still using a rather clumsy way to play with qemu.

It's really good to know this, and I definitely need to update the
script in riscv-gnu-toolchain :)

> We can't control how riscv-gnu-toolchain and others implement their scripts and
> wrappers. These are the kind of thing that people write once and never look it
> back, and that's fine.
>
> That said, we have 'rv64i' and other bare CPUs since QEMU 9.0, released in April
> 24. We don't need to do this kind of massive extension disablement to get a
> clean CPU for almost 2 years.
>
> I advise to not take QEMU wrappers, scripts and etc from other projects as a sort
> of proof of what QEMU is currently capable. They're usually outdated.

Yeah, I admit that, I always spend time updating the script for
mapping extension to
extension to qemu option...and it's hard to always be up to date.

> > So how do other tools/simulators address these problems? Toolchains like
> > Clang and GCC use -march with an arch string to configure, and Spike uses
> > --isa=<ISA-string> to configure.
> >
> > Could we introduce a similar way to configure QEMU? Yes, I think we can.
> > That's what this patch set does.
> >
> >    -cpu rv64,arch=<ISA-string>
>
> I don't mind the 'arch' property if users find it easier to enable extensions with
> it rather than the boolean properties, but it should be used on top of bare CPUs
> only. Otherwise the 'arch' property would include the already enabled extensions
> from 'rv64' and others.
>
> And we would need to be okay with the fact that this is redundant to what we already
> can do with bare CPUs + manual extension enablement.

One point here is that the ISA string is the official way to represent
the ISA configuration in RISC-V, it would be simpler if we can use the
same string to set up every tool.

> We have profile CPUs for this use case:
>
> $ ./qemu-riscv64 -cpu help
> Available CPUs:
>    max
>    rv64
>    rv64e
>    rv64i
>    rva22s64
>    rva22u64
>    rva23s64
>    rva23u64
> (...)
>
>
> So 'qemu-riscv64 -cpu rva23u64'  creates an user mode QEMU with RVA23.

To be honest, I was a little hesitant about adding the `arch=<profile>` syntax,
because as you said, `-cpu` is already supported.

My final decision was to add it for alignment with the toolchain interface,
but that's because I'm a toolchain developer.

> > 5. zvl*b extensions
> >     Specify vector length (VLEN) in bits using zvl<N>b where N is a power
> >     of 2 (32-65536). Requires v or zve* extension.
> >
> >     Examples:
> >       $ qemu-riscv64 -cpu rv64,arch=rv64gcv_zvl256b /bin/true
> >       $ qemu-riscv64 -cpu rv64,arch=rv64i_zve64f_zvl128b /bin/true
>
> We already have vlen and elen properties. Not sure if we need another way to set
> the same stuff.
>
> I'll give a closer look later at the first 2 patches (arch=dump and arch=help)
> since these are nice additions for the user experience.

The first two patches should be less controversial, so I'm okay with
that if we decide to get the first two first :)

>
> I would like to hear other opinions about arch=<ISA_STRING> because it would be
> just another way (probably an easier way) of doing what we already support with
> bare CPUs + manual extension enablement.
>
> I don't see the need to support arch=PROFILE given that we have profile CPUs
> that does exactly that. Same thing for the 'vlen' setting.

The primary motivation for supporting zvl*b/VLEN syntax is to align
with the toolchain interface, allowing users to process both qemu and
the toolchain using a single string, and again, that is the official
way to describe that info in RISC-V ISA spec, so I adding this syntax
sugar in arch=<isa-str>.

On 1/5/26 10:43 AM, Kito Cheng wrote:
> Hi Daniel:
> 
> Thanks for your reply, and here is my response :)
> 
>>> 1. How do you run RISC-V QEMU with a specific extension configuration?
>>>      Please try to configure an rv64im user mode QEMU before you answer
>>>      this question.
>>
>> I would use the 'rv64i' bare CPU that we introduced a few releases ago
>> and enable just 'm':
>>
>> qemu-riscv64 -cpu rv64i,m=on
>>
>>
>> It gives you a bare bones CPU with only "RVI" enabled. We added this CPU
>> specifically to support the use case you mentioned: users that want to
>> have full control of what is enabled in the CPU.
> 
> Oh, thanks for this info, my impression of this is stuck in my memory of 2022,
> which is the time I wrote the qemu wrapper for riscv-gnu-toolchain,
> So I'm still using a rather clumsy way to play with qemu.
> 
> It's really good to know this, and I definitely need to update the
> script in riscv-gnu-toolchain :)
> 
>> We can't control how riscv-gnu-toolchain and others implement their scripts and
>> wrappers. These are the kind of thing that people write once and never look it
>> back, and that's fine.
>>
>> That said, we have 'rv64i' and other bare CPUs since QEMU 9.0, released in April
>> 24. We don't need to do this kind of massive extension disablement to get a
>> clean CPU for almost 2 years.
>>
>> I advise to not take QEMU wrappers, scripts and etc from other projects as a sort
>> of proof of what QEMU is currently capable. They're usually outdated.
> 
> Yeah, I admit that, I always spend time updating the script for
> mapping extension to
> extension to qemu option...and it's hard to always be up to date.
> 
>>> So how do other tools/simulators address these problems? Toolchains like
>>> Clang and GCC use -march with an arch string to configure, and Spike uses
>>> --isa=<ISA-string> to configure.
>>>
>>> Could we introduce a similar way to configure QEMU? Yes, I think we can.
>>> That's what this patch set does.
>>>
>>>     -cpu rv64,arch=<ISA-string>
>>
>> I don't mind the 'arch' property if users find it easier to enable extensions with
>> it rather than the boolean properties, but it should be used on top of bare CPUs
>> only. Otherwise the 'arch' property would include the already enabled extensions
>> from 'rv64' and others.
>>
>> And we would need to be okay with the fact that this is redundant to what we already
>> can do with bare CPUs + manual extension enablement.
> 
> One point here is that the ISA string is the official way to represent
> the ISA configuration in RISC-V, it would be simpler if we can use the
> same string to set up every tool.
> 
>> We have profile CPUs for this use case:
>>
>> $ ./qemu-riscv64 -cpu help
>> Available CPUs:
>>     max
>>     rv64
>>     rv64e
>>     rv64i
>>     rva22s64
>>     rva22u64
>>     rva23s64
>>     rva23u64
>> (...)
>>
>>
>> So 'qemu-riscv64 -cpu rva23u64'  creates an user mode QEMU with RVA23.
> 
> To be honest, I was a little hesitant about adding the `arch=<profile>` syntax,
> because as you said, `-cpu` is already supported.
> 
> My final decision was to add it for alignment with the toolchain interface,
> but that's because I'm a toolchain developer.
> 
>>> 5. zvl*b extensions
>>>      Specify vector length (VLEN) in bits using zvl<N>b where N is a power
>>>      of 2 (32-65536). Requires v or zve* extension.
>>>
>>>      Examples:
>>>        $ qemu-riscv64 -cpu rv64,arch=rv64gcv_zvl256b /bin/true
>>>        $ qemu-riscv64 -cpu rv64,arch=rv64i_zve64f_zvl128b /bin/true
>>
>> We already have vlen and elen properties. Not sure if we need another way to set
>> the same stuff.
>>
>> I'll give a closer look later at the first 2 patches (arch=dump and arch=help)
>> since these are nice additions for the user experience.
> 
> The first two patches should be less controversial, so I'm okay with
> that if we decide to get the first two first :)
> 
>>
>> I would like to hear other opinions about arch=<ISA_STRING> because it would be
>> just another way (probably an easier way) of doing what we already support with
>> bare CPUs + manual extension enablement.
>>
>> I don't see the need to support arch=PROFILE given that we have profile CPUs
>> that does exactly that. Same thing for the 'vlen' setting.
> 
> The primary motivation for supporting zvl*b/VLEN syntax is to align
> with the toolchain interface, allowing users to process both qemu and
> the toolchain using a single string, and again, that is the official
> way to describe that info in RISC-V ISA spec, so I adding this syntax
> sugar in arch=<isa-str>.

I see.

Maybe there's an argument for supporting arch=ISA_STR in its entirely instead of
cherry-picking what we want.

In the end the discussion you're prompting here is whether do we want/need to
implement and support an alternative way of enabling extensions, and in this
case one that is more compatible with the rest of the SW stack we use in the
RISC-V land.

The implementation per se isn't the hard part: the hard part is how to deal
with the upkeep of supporting both the ISA_STR and our current extension
enable/disable code in the long run. I'm not entirely sure also whether we can
use this new arch=ISA_STR as just a superficial layer to do what we already
do or if this would require additional changes in QMP and what not. Drew,
care to comment?


Daniel

On Mon, Jan 05, 2026 at 11:13:50AM -0300, Daniel Henrique Barboza wrote:
...
> Maybe there's an argument for supporting arch=ISA_STR in its entirely instead of
> cherry-picking what we want.

I don't think so. Focusing on adopting profiles to describe large
extension sets is the way to go in order to reduce extension management
pain. The toolchains should be doing the same.

> 
> In the end the discussion you're prompting here is whether do we want/need to
> implement and support an alternative way of enabling extensions, and in this
> case one that is more compatible with the rest of the SW stack we use in the
> RISC-V land.

riscv qemu should be striving to have a single consistent interface for
enabling extensions (cpufeatures) across all architectures. I don't think
we should support multiple description mechanisms nor anything that is
riscv unique. We also want boolean properties whenever possible as that
simplifies interfaces like cpu-model-expansion.

Users that prefer the ISA string are always free to write an ISA string to
qemu cpu property conversion script. qemu should never rename an
extension, so it should be a simple 's/_/,/g' and additions of '=on'. If
we do have special cases for naming, then I suggest we immediately add the
correct names and deprecate the incorrect ones.

Thanks,
drew