8370666: VectorAPI: Add clear comments for vector relative code in c2 #29130

XiaohongGong · 2026-01-09T01:36:50Z

The VectorMask implementation in Vector API involves complex interactions between types, nodes, and platform-specific
features, making the related code in HotSpot difficult to understand and review.

This patch adds comprehensive comments for vector mask related types, nodes, and methods in C2 to improve code clarity and
maintainability.

Note: This patch only adds comments; no functional changes are made.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8370666: VectorAPI: Add clear comments for vector relative code in c2 (Enhancement - P4)

Reviewers

Emanuel Peter (@eme64 - Reviewer)
Quan Anh Mai (@merykitty - Committer) Review applies to ed5e79f7
Jatin Bhateja (@jatin-bhateja - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/29130/head:pull/29130
$ git checkout pull/29130

Update a local copy of the PR:
$ git checkout pull/29130
$ git pull https://git.openjdk.org/jdk.git pull/29130/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 29130

View PR using the GUI difftool:
$ git pr show -t 29130

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/29130.diff

Using Webrev

Link to Webrev Comment

…in c2

bridgekeeper · 2026-01-09T01:37:55Z

👋 Welcome back xgong! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2026-01-09T01:39:31Z

@XiaohongGong This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8370666: VectorAPI: Add clear comments for vector relative code in c2

Reviewed-by: epeter, jbhateja, qamai

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 103 new commits pushed to the master branch:

75172e0: 8374717: Unclear wording in docs for recursion for List, Map and LazyConstant
a67979c: 8375125: assert(false) failed: "Attempting to acquire lock NativeHeapTrimmer_lock/nosafepoint out of order with lock ConcurrentHashTableResize_lock/nosafepoint-2 -- possible deadlock" when using native heap trimmer
1cdb817: 8375575: AttachNotSupportedException constructor missing @SInCE 27
... and 100 more: https://git.openjdk.org/jdk/compare/385c4f8180d30c0e41b848eb4b2c1c8788211422...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2026-01-09T01:40:17Z

@XiaohongGong The following label will be automatically applied to this pull request:

hotspot-compiler

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2026-01-09T01:44:55Z

Webrevs

eme64

Nice work, thanks for taking the time for this, much appreciated!

On the whole I'm super happy with this, but left a few extra comments :)

src/hotspot/share/opto/vectornode.hpp

src/hotspot/share/opto/type.cpp

src/hotspot/share/opto/vectornode.hpp

eme64 · 2026-01-09T13:30:15Z

src/hotspot/share/opto/vectornode.hpp

+// Convert a "BVectMask" into a platform-specific vector mask (either "NVectMask"
+// or "PVectMask").
 class VectorLoadMaskNode : public VectorNode {


I'd love to rename this. Because it is (as you say in the comments) a conversion, and not a "load" (memory op).
What about VectorConvertBooleans2MaskNode.

And below, rename VectorStoreMaskNode to VectorConvertMask2BooleansNode.

You may have an even better idea.

Yeah, I remember that @PaulSandoz gave a suggestion for the name before. I will take a consideration. Renaming of these two IRs is not an easy task that we need to go through all the code in mid-end, and backend of platforms that have supported Vector API. I'd like to leave it as a separate task with this PR. WDYT?

Hi @eme64 , do you have any insights on this? I’m wondering whether separating the renaming change into a different PR would be acceptable to you. Additionally, do you think it's better that we start a dedicated thread on the mailing list or github to discuss this further and gather more feedback from others?

I'm fine with a separate RFE. Why not file an RFE, and then we can discuss on JIRA, and the PR that we will create from it? That will keep the conversation accessible to all and once the change is made people can find the conversation that led up to the change more easily :)

Sounds good. I'v filed a JBS (https://bugs.openjdk.org/browse/JDK-8375509) to record and follow.

src/hotspot/share/opto/vectornode.hpp

XiaohongGong · 2026-01-13T08:47:19Z

Hi @eme64 , I updated the vector nodes part with adding comments for more vector nodes. Would you mind taking another look? Thanks a lot!

XiaohongGong · 2026-01-13T08:47:34Z

Thanks so much for your review @merykitty !

XiaohongGong · 2026-01-16T03:47:05Z

Hi @eme64 , regarding to the comments, could you please take another look and check whether it's clear enough? Thanks so much for any feedback.

eme64 · 2026-01-16T08:28:08Z

src/hotspot/share/opto/vectornode.hpp

+// Load the IOTA constant vector containing sequential indices starting from 0
+// and incrementing by 1 up to "VLENGTH - 1". So far, the first input is an int
+// constant 0. For example, a 128-bit vector with int (32-bit) elements produces
+// a vector like "[0, 1, 2, 3]".


Are you saying that in1 has to be a constant with value zero? Actually, it seems the backend just ignores the input value... so why do we even have it?

Yes, in1 is a constant with zero and it can be ignored in backend codegen. I'm unsure about the root cause why we still need it. It deserves an investigation. Maybe it's necessary for a floating node that has no control input for some phases? I'm not sure. When I tried to remove it , I met hotspot crashes when running jtreg tests:

# A fatal error has been detected by the Java Runtime Environment: # # Internal Error (jdk/src/hotspot/share/opto/node.hpp:418), pid=2345980, tid=2346012 # assert(i < _max) failed: oob: i=1, _max=1

The call stack is:

Stack: [0x0000e66182a7f000,0x0000e66182c7d000], sp=0x0000e66182c775d0, free space=2017k Native frames: (J=compiled Java code, j=interpreted, Vv=VM code, C=native code) V [libjvm.so+0x138a0ac] Node::in(unsigned int) const [clone .part.0]+0x2c (node.hpp:418) V [libjvm.so+0x13a36b4] PhaseIdealLoop::get_early_ctrl(Node*)+0x400 (node.hpp:418) V [libjvm.so+0x13a48e8] PhaseIdealLoop::build_loop_early(VectorSet&, Node_List&, Node_Stack&)+0x658 (loopnode.cpp:250) V [libjvm.so+0x13b26e4] PhaseIdealLoop::build_and_optimize()+0x654 (loopnode.cpp:5134) V [libjvm.so+0xa35ba0] PhaseIdealLoop::optimize(PhaseIterGVN&, LoopOptsMode)+0x360 (loopnode.hpp:1233)

src/hotspot/share/opto/vectornode.hpp

jatin-bhateja

Thanks @XiaohongGong , looks good.
I have also created https://bugs.openjdk.org/browse/JDK-8375498 so that we enable dumping of VectorIR created though vector inline expanders similar to auto-vectorization.

src/hotspot/share/opto/vectornode.hpp

XiaohongGong · 2026-01-19T03:12:54Z

Hi @eme64 , @jatin-bhateja , I'v updated a new commit to address the remaining comments. Could you please take another look? Thanks a lot!

jatin-bhateja

LGTM.

Best Regards,
Jatin

eme64 · 2026-01-19T08:14:17Z

@XiaohongGong Thanks for putting the effort into better documentation, really much appreciated 😊

XiaohongGong · 2026-01-20T01:41:55Z

Thanks so much for your review @eme64 , @jatin-bhateja and @merykitty !
/integrate

openjdk · 2026-01-20T01:43:40Z

Going to push as commit 303de9a.
Since your change was applied there have been 112 commits pushed to the master branch:

496af3c: 8375093: Convert GlobalCounter to use Atomic
f2d5290: 8367319: Add os interfaces to get machine and container values separately
c44a99a: 8374180: C2 crash in PhaseCCP::verify_type - fatal error: Not monotonic
... and 109 more: https://git.openjdk.org/jdk/compare/385c4f8180d30c0e41b848eb4b2c1c8788211422...master

Your commit was automatically rebased without conflicts.

openjdk · 2026-01-20T01:43:51Z

@XiaohongGong Pushed as commit 303de9a.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

8370666: VectorAPI: Add clear comments for vector mask relative code …

ed5e79f

…in c2

openjdk bot added the hotspot-compiler hotspot-compiler-dev@openjdk.org label Jan 9, 2026

openjdk bot added the rfr Pull request is ready for review label Jan 9, 2026

eme64 reviewed Jan 9, 2026

View reviewed changes

merykitty approved these changes Jan 12, 2026

View reviewed changes

Add more comments for vector nodes

6782b7f

XiaohongGong changed the title ~~8370666: VectorAPI: Add clear comments for vector mask relative code in c2~~ 8370666: VectorAPI: Add clear comments for vector relative code in c2 Jan 13, 2026

Update comments in type.cpp

083f575

eme64 reviewed Jan 16, 2026

View reviewed changes

src/hotspot/share/opto/vectornode.hpp Outdated Show resolved Hide resolved

jatin-bhateja reviewed Jan 16, 2026

View reviewed changes

src/hotspot/share/opto/vectornode.hpp Outdated Show resolved Hide resolved

Update comments in vectornode.hpp

431f2b8

jatin-bhateja approved these changes Jan 19, 2026

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jan 19, 2026

eme64 approved these changes Jan 19, 2026

View reviewed changes

openjdk bot added the integrated Pull request has been integrated label Jan 20, 2026

openjdk bot closed this Jan 20, 2026

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jan 20, 2026

XiaohongGong deleted the JDK-8370666 branch January 20, 2026 01:43

8370666: VectorAPI: Add clear comments for vector relative code in c2 #29130

8370666: VectorAPI: Add clear comments for vector relative code in c2 #29130

Conversation

XiaohongGong commented Jan 9, 2026 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Jan 9, 2026

Uh oh!

openjdk bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

eme64 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eme64 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

XiaohongGong Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

XiaohongGong Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eme64 Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

XiaohongGong Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

XiaohongGong commented Jan 13, 2026

Uh oh!

XiaohongGong commented Jan 13, 2026

Uh oh!

XiaohongGong commented Jan 16, 2026

Uh oh!

eme64 Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

XiaohongGong Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jatin-bhateja left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

XiaohongGong commented Jan 19, 2026

Uh oh!

jatin-bhateja left a comment

Choose a reason for hiding this comment

Uh oh!

eme64 commented Jan 19, 2026

Uh oh!

XiaohongGong commented Jan 20, 2026

Uh oh!

openjdk bot commented Jan 20, 2026

Uh oh!

openjdk bot commented Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

XiaohongGong commented Jan 9, 2026 •

edited by openjdk bot

Loading

openjdk bot commented Jan 9, 2026 •

edited

Loading

openjdk bot commented Jan 9, 2026 •

edited

Loading

mlbridge bot commented Jan 9, 2026 •

edited

Loading

XiaohongGong Jan 16, 2026 •

edited

Loading