Re: [PATCH v2 1/2] docs: update hyperlaunch device tree

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Tue, 8 Aug 2023, Daniel P. Smith wrote:
> On 8/3/23 20:09, Stefano Stabellini wrote:
> > On Thu, 3 Aug 2023, Stefano Stabellini wrote:
> > > On Thu, 3 Aug 2023, Daniel P. Smith wrote:
> > > > > Also, what is the plan for the existing dom0less dt properties?
> > > > > Will they need to be moved to new /hypervisor node or we will have to
> > > > > parse
> > > > > both /chosen and /hypervisor nodes?
> > > > 
> > > > In the proposal I sent to xen-devel in response to Luca's RFC for
> > > > rebranding
> > > > dom0less features under hyperlaunch, that is the purpose of this commit.
> > > > Get
> > > > this document up to date with what was done in v1 along with what we are
> > > > planning/working on for hyperlaunch. One could think of this as
> > > > effectively
> > > > the API to the capabilities hyperlaunch will provide. Not just how to
> > > > construct a domain, but what kinds of domains can be constructed by
> > > > hyperlaunch. Step one of the proposal is to publish a patch upon which
> > > > we all
> > > > can iterate over and get to an agreement on a suitable interface for
> > > > all. The
> > > > next step would be the introduction of hyperlaunch dom0less
> > > > compatibility
> > > > mode, that would see the moving of the parsing logic for the existing
> > > > dom0less
> > > > nodes under /xen/common/domain-builder. It would continue to exist there
> > > > even
> > > > after hyperlaunch proper is merged and can remain there for backward
> > > > compatibility until there is a decision to retire the compatibility
> > > > interface.
> > > 
> > > I like this plan. The two interfaces are so similar that it is basically
> > > one interface with a couple of tiny differences.
> > > 
> > > So I expect we would move the existing dom0less parsing code to common/,
> > > add a couple of extensions (such as parsing /hypervisor in addition to
> > > /chosen) and use it as it.
> > > 
> > > Later on, after a few years of using /hypervisor instead of /chosen, if
> > > nobody is using /chosen anymore, we could retire /chosen completely. But
> > > this is just one DT node/property that gets retired (there are a couple
> > > of others). I don't imagine we'll have a full new implementation of the
> > > DT parsing logic that supersedes the existing implementation of it
> > > (especially considering the difficulty of maintaining 2 different parsing
> > > logics in the hypervisor for similar interfaces).
> > > 
> > > Same thing for the DT interface documentation. I don't think we need two
> > > DT interface docs? We could start with the existing dom0less interface
> > > (docs/misc/arm/device-tree/booting.txt), and move it somewhere common
> > > like docs/misc/device-tree.
> > > 
> > > Then add any changes or extensions required by other architecture, such
> > > as x86 and RISC-V.
> > > 
> > > For sure for x86 we need "module-index". I don't know if anything else
> > > is must-have to get it to work on x86 but if there is, we should add
> > > those too.
> > 
> > 
> > For clarity, I think we should definitely have
> > docs/design/launch/hyperlaunch.rst, and maybe we should also have
> > hyperlaunch-devicetree.rst as an overview description and user guide.
> > That's useful.
> > 
> > But in terms of official device tree bindings interface description
> > (basically what in Linux would go under
> > Documentation/devicetree/bindings/), I think it would be best to only
> > have a single document. The current one is
> > docs/misc/arm/device-tree/booting.txt.
> 
> Does the proposal to your first message align with your follow-up here?

You are referring to a common docs/misc/device-tree/hyperlaunch.rst,
right? Then yes.