[RFC PATCH 2/3] dt-bindings: riscv: Add Worlds per-hart properties

[Yu-Chien Peter Lin]

On Fri, Jul 17, 2026 at 04:55:00PM +0100, Conor Dooley wrote:
> On Fri, Jul 17, 2026 at 06:39:51PM +0800, Yu-Chien Peter Lin wrote:
> > Hi Conor,
> > 
> > On Tue, Jun 30, 2026 at 07:06:14PM +0100, Conor Dooley wrote:
> > > On Tue, Jun 30, 2026 at 07:11:26PM +0800, Yu-Chien Peter Lin wrote:
> > > > Hi Conor,
> > > > 
> > > > On Fri, Jun 26, 2026 at 03:36:38PM +0100, Conor Dooley wrote:
> > > > > On Fri, Jun 26, 2026 at 07:47:31PM +0800, Yu-Chien Peter Lin wrote:
> > > > > > Hi Conor,
> > > > > > 
> > > > > > On Mon, Jun 22, 2026 at 06:12:47PM +0100, Conor Dooley wrote:
> > > > > > > On Fri, Jun 19, 2026 at 06:58:33PM +0800, Yu-Chien Peter Lin wrote:
> > > > > > > > Add per-hart DT properties for RISC-V Worlds architecture:
> > > > > > > > riscv,pmwid, riscv,pmwidlist, and riscv,pmlwidlist. These
> > > > > > > > platform-defined values are primarily used by M-mode firmware
> > > > > > > > to configure World ID CSRs and restrict WID usage across
> > > > > > > > privilege levels.
> > > > > > > > 
> > > > > > > > Signed-off-by: Yu-Chien Peter Lin <peter.lin at sifive.com>
> > > > > > > > ---
> > > > > > > >  .../devicetree/bindings/riscv/cpus.yaml       | 21 +++++
> > > > > > > >  .../devicetree/bindings/riscv/worlds.yaml     | 77 +++++++++++++++++++
> > > > > > > >  2 files changed, 98 insertions(+)
> > > > > > > >  create mode 100644 Documentation/devicetree/bindings/riscv/worlds.yaml
> > > > > > > > 
> > > > > > > > diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml
> > > > > > > > index 5feeb2203050..4b5778b6d3e7 100644
> > > > > > > > --- a/Documentation/devicetree/bindings/riscv/cpus.yaml
> > > > > > > > +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml
> > > > > > > > @@ -26,6 +26,7 @@ description: |
> > > > > > > >  allOf:
> > > > > > > >    - $ref: /schemas/cpu.yaml#
> > > > > > > >    - $ref: extensions.yaml
> > > > > > > > +  - $ref: worlds.yaml
> > > > > > > >    - if:
> > > > > > > >        not:
> > > > > > > >          properties:
> > > > > > > > @@ -120,11 +121,31 @@ properties:
> > > > > > > >        thead systems where the vector register length is not identical on all harts, or
> > > > > > > >        the vlenb CSR is not available.
> > > > > > > >  
> > > > > > > > +  riscv,pmwid:
> > > > > > > > +    $ref: /schemas/types.yaml#/definitions/uint32
> > > > > > > > +    description:
> > > > > > > > +      Platform-defined M-mode World ID (WID) assigned to this hart.
> > > > > > > > +    minimum: 0
> > > > > > > > +    maximum: 63
> > > > > > > > +
> > > > > > > > +  riscv,pmwidlist:
> > > > > > > > +    $ref: /schemas/types.yaml#/definitions/uint64
> > > > > > > > +    description:
> > > > > > > > +      Platform-defined bitmap of M-mode World IDs (WIDs) that this hart may use.
> > > > > > > 
> > > > > > > I don't understand what the difference is between this property and the
> > > > > > > one before it are.
> > > > > > > Is this one meant to be used by m-mode software to then select one which
> > > > > > > will appear in riscv,pmwid?
> > > > > > 
> > > > > > pmwid (single value) is the reset default, while pmwidlist (bitmap)
> > > > > > defines the allowed set. The root-of-trust M-mode software may select
> > > > > > an allowed value from the pmwidlist and write it to the mwid CSR.
> > > > > 
> > > > > I don't understand the point of the property then. If it is the reset
> > > > > default, just read it out of the register?
> > > > > Unless I am missing something, it's useless to s-mode because it may
> > > > > not be what m-mode chose and useless to m-mode that has access to
> > > > > the csr.
> > > > 
> > > > Smwid is optional. In the no-Smwid case:
> > > > - M-mode's WID is fixed to pmwid (hardware-defined via fuse/pinstrap/SoC
> > > >   registers, exposed to software via riscv,pmwid DT property)
> > > > - S/U-mode's WID depends on opensbi-domain configuration [1]:
> > > >   - If next-wid is specified: S/U use that WID (via mlwid CSR)
> > > >   - If next-wid is absent   : S/U fall back to pmwid (M/S/U in same
> > > >     world)
> > > > 
> > > > So riscv,pmwid serves two purpose:
> > > > 1. Source of truth for M-mode's WID when mwid CSR doesn't exist
> > > > 2. Fallback value for OpenSBI to write to mlwid when domain config is
> > > >    absent.
> > > 
> > > So it is not the default at reset at all then. The reset default is
> > > something else entirely and this is used to overwrite that.
> > > 
> > > > - M-mode's WID is fixed to pmwid (hardware-defined via fuse/pinstrap/SoC
> > > >   registers, exposed to software via riscv,pmwid DT property)
> > > 
> > > In this case, it seems like pmwidlist would just contain a single entry,
> > > and there is no need for pwmid.
> > 
> > The pmwid and pmwidlist properties cannot merge because pmwidlist represents
> > an optional hardware mask. On physically unrestricted platforms, pmwidlist
> > doesn't exist, making pmwid essential to define the hardware reset default.
> > 
> > > 
> > > Quite frankly, it seems like you need to decouple these properties from
> > > being 1:1 mappings to your extension's CSRs and both name and explain
> > > how they are to be used by software.
> > 
> > These properties are actually not 1:1 CSR mappings. pmwid, pmwidlist, and
> > pmlwidlist are the exact terms used in the RISC-V specification to describe
> > these platform-defined hardware values, so I prefer to follow it.
> 
> CSRs or terms in your extension, it matters little.
> Your properties should reflect how software will actually interact with
> the devicetree and wordguard. There's no point having a bunch of
> properties that relate to aspects of the extension if software is not
> going to actually use them. 
> 
> I fundamentally do not understand why software ever needs both both the
> singular and list properties. What does software actually do with the
> list property when both it and the singular property are provided?
> 
> I expect to see something simpler and/or much better explained in the next
> revision.
> 
> > > Again same point applies here, why can a single-entry riscv,pmwidlist
> > > not suffice here?
> > 
> > As explained above, a single-entry pmwidlist cannot replace pmwid because
> > it would fail to represent the exact hardware reset default for platforms
> > without physical WID restrictions.
> 
> If there is one entry, use that, and if there are multiple entries, pick
> one?

Thank you, Conor. I am reworking OpenSBI part and hopefully PATCHv2
will address some of issues here. I will also rewrite description to
focus on software usage rather than hardware spec terminology.

Regards,
Peter Lin

> 
> Thanks,
> Conor.