Skip to content

doc: add riscv pv console diagram and PlantUML CI generation - #20

Merged
baptleduc merged 7 commits into
xcp-ng:mainfrom
baptleduc:riscv-doc
May 12, 2026
Merged

doc: add riscv pv console diagram and PlantUML CI generation#20
baptleduc merged 7 commits into
xcp-ng:mainfrom
baptleduc:riscv-doc

Conversation

@baptleduc

@baptleduc baptleduc commented May 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Add xen-console.puml sequence diagram documenting the full RISC-V Xen PV console flow (init, xenconsoled mapping, input path via HVIP)
  • Add CI workflow to auto-generate SVGs from doc/**/*.puml on PR and commit results to doc/generated/<subdir>/
  • Add doc/riscv/README.md with table linking diagrams to sources

Test plan

  • Open a PR touching doc/riscv/xen-console.puml and verify CI
    generates xen-console.svg as an artifact
  • Verify this artifact can be download with a nightly.link
  • Verify workflow does not run on PRs with no .puml changes
  • Make the xen-console.puml reviewed by @olkur or @tperard

@baptleduc
baptleduc requested a review from a team as a code owner May 4, 2026 16:06
@casasnovas

casasnovas commented May 5, 2026

Copy link
Copy Markdown
Collaborator

As an early comment I think it'd be better you just include a script to generate the SVG and devs do it as part of the commit changing the puml file. As it stands, your workflow will generate it and create a commit, but that commit will not be part of the PR that's changed the puml file and will simply be lost, I think.

@baptleduc

baptleduc commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

As an early comment I think it'd be better you just include a script to generate the SVG and devs do it as part of the commit changing the puml file. As it stands, your workflow will generate it and create a commit, but that commit will not be part of the PR that's changed the puml file and will simply be lost, I think.

Yes you're right. Maybe an another option would be to directly commit them in the main branch as this dedicated github actions does or to generate the SVG as artifacts. What do you think ?

@baptleduc
baptleduc force-pushed the riscv-doc branch 2 times, most recently from b4d3eac to 02d804c Compare May 5, 2026 09:17
@TSnake41

TSnake41 commented May 5, 2026

Copy link
Copy Markdown
Member

I don't think such documentation should belong here. You should upstream it to Xen Project (ask me if you need help on who to ask).

@baptleduc

baptleduc commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

I don't think such documentation should belong here. You should upstream it to Xen Project (ask me if you need help on who to ask).

As my riscv guest creation support is not yet upstream, I'm wondering if it's would make sense.

@baptleduc
baptleduc force-pushed the riscv-doc branch 12 times, most recently from 3220cdf to 1e34e34 Compare May 5, 2026 10:06
@casasnovas

casasnovas commented May 5, 2026

Copy link
Copy Markdown
Collaborator

I don't think such documentation should belong here. You should upstream it to Xen Project (ask me if you need help on who to ask).

I'd say one does not preclude the other, could serve as staging area until then.

@casasnovas

casasnovas commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

As an early comment I think it'd be better you just include a script to generate the SVG and devs do it as part of the commit changing the puml file. As it stands, your workflow will generate it and create a commit, but that commit will not be part of the PR that's changed the puml file and will simply be lost, I think.

Yes you're right. Maybe an another option would be to directly commit them in the main branch as this dedicated github actions does or to generate the SVG as artifacts. What do you think ?

Hrm I'd prefer to not give the rights to an action to commit directly to main so that everything that gets in has been reviewed. Artifacts are fine by me though, sounds like a better option :)

@baptleduc
baptleduc force-pushed the riscv-doc branch 6 times, most recently from f2f951d to 0ee4a36 Compare May 5, 2026 13:32
@baptleduc
ci: add PlantUML diagram generation workflow
f89ba3a 
Auto-generate SVGs from doc/**/*.puml on push and PR.
Upload as CI artifacts for download via nightly.link.

Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
baptleduc and others added 4 commits May 5, 2026 16:00
@baptleduc
ci/generate-plantuml: upload svg as artifacts
92fb6b7 
Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc
doc/riscv: add xen console puml sequence diagram
2405e7b 
Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc
doc: add README with CI artifact download link
0d69cbb 
Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc
README: add a doc section
0b65083 
Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc

baptleduc commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

@olkur or @tperard could you please review the pv console diagram ?
Thanks in advance

@olkur

olkur commented May 7, 2026

Copy link
Copy Markdown 
I don't think such documentation should belong here. You should upstream it to Xen Project (ask me if you need help on who to ask).

I'd say one does not preclude the other, could serve as staging area until then.

@casasnovas @baptleduc

I think it would be better to upstream the documentation in parallel with the changes (functionality), as something could change during the feature review. Otherwise, we may end up with outdated documentation or need to submit an additional patch to fix it.

Anyway, I think we want to have this somewhere in Xen repo or Xen Wiki project.

olkur
olkur reviewed May 7, 2026
View reviewed changes
Comment thread doc/riscv/xen-console.puml Outdated
Comment thread doc/riscv/xen-console.puml
Comment thread doc/riscv/xen-console.puml Outdated
baptleduc added 2 commits May 11, 2026 15:30
@baptleduc
doc/riscv/pv-console: fix wrong diagram comments
d1e0733 
Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc
doc/riscv/xen-console: use generic scheduler wake path
a03db45 
Replace null_unit_wake() with sched_wake() → s->wake(), valid for
all Xen schedulers. Also show vcpu_unblock() as always called by
vcpu_kick() regardless of vCPU state.

Signed-off-by: Baptiste Le Duc <baptiste.le-duc@vates.tech>
@baptleduc
baptleduc requested a review from olkur May 11, 2026 14:59
casasnovas
casasnovas approved these changes May 12, 2026
View reviewed changes

@casasnovas casasnovas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm for the generation part, and looks like Oleksii is OK with the diagrams being correct so feel free to merge.

@baptleduc
baptleduc merged commit 51baa83 into xcp-ng:main May 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@casasnovas casasnovas casasnovas approved these changes
@olkur olkur Awaiting requested review from olkur

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@baptleduc @casasnovas @TSnake41 @olkur