[SYCL][NATIVE_CPU] Update docs for Native CPU compiler pipeline #20042

coldav · 2025-09-10T16:27:55Z

This integrates the appropriate compiler documentation originally in the oneAPI Construction Kit (OCK) into the NativeCPU compiler pipeline documenation.

It has been updated to try to reflect the Native CPU pipeline, and remove some of the references to OCK's structures, as well as moving some of the documentation to markdown files to be consistent with some of the other documentation.

Some of it may be irrelevant for Native CPU, and if so this should be updated over time.

Support was added for the mermaid flowcharts in the config.

This integrates the appropriate compiler documentation originally in the oneAPI Construction Kit (OCK) into the NativeCPU compiler pipeline documentation. It has been updated to try to reflect the Native CPU pipeline, and remove some of the references to OCK's structures, as well as moving some of the documentation to markdown files to be consistent with some of the other documentation. Some of it may be irrelevant for Native CPU, and if so this should be updated over time. Support was added for the mermaid flowcharts in the config.

uwedolinsky · 2025-09-12T11:41:59Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+show how the `WorkItemLoopsPass` lays out and schedules a kernel\'s work-item
+loops in the face of barriers.
+
+```C


Maybe it's worth converting this code into SYCL?

if you want to do that, perhaps put in as a suggestion, I'm more familiar with OpenCL.

sycl/doc/design/SYCLNativeCPUPipeline.md

uwedolinsky · 2025-09-12T13:08:53Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+```
+
+As you can see, the `subhandler` steals the kernel's function name, and receives two pointer arguments: the first one points to the kernel arguments from the SYCL runtime, and the second one to the `nativecpu::state` struct.
+


It would be good to also keep the original input IR (from https://github.com/intel/llvm/blob/sycl/sycl/doc/design/SYCLNativeCPU.md) because it uses the original name - otherwise it's not clear (at least from this page) that "the subhandler steals the kernel's function name".

Added original IR earlier in the section.

sycl/doc/design/SYCLNativeCPUPipeline.md

sycl/doc/design/SYCLNativeCPUPipelinePasses.md

sycl/doc/design/SYCLNativeCPUVecz.md

sycl/doc/design/SYCLNativeCPU.md

sycl/doc/conf.py

coldav · 2025-09-16T12:40:39Z

Hi @intel/dpcpp-doc-reviewers I need a review.

steffenlarsen · 2025-09-16T13:06:22Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+3. All builtins which do not relate to scheduling have been processed and we are
+   left with some scheduling related calls to `mux builtins`.
+4.  The final compiled kernel is assumed to be invoked from the
+    host-side runtime once per *work-group* in the **NDRange**.


Nit; Why is the indentation of 1. and 4. different?

Thanks, removed bad indendation.

The indentation now matches between 1 and 4 (next lines start one space after the start of the first line's sentence), but 3 is different (next line is aligned with the first line's sentence).

steffenlarsen · 2025-09-16T13:07:36Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+
+The inner-most function is the original input kernel, which is *wrapped*
+by new functions in successive phases, until it is ready in a form to be
+executed by the Native CPU driver. These include effectively wrapping a  `for (wi : wg)`


Without additional context, it may not be clear what wg and wi are in this case. I assume it relates to the next paragraph, but if so this last sentence feels a little redundant.

removed this line

steffenlarsen · 2025-09-16T13:21:43Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+Simple fix-up passes take place at this stage: the IR is massaged to
+conform to specifications or to fix known deficiencies in earlier
+representations. The input IR at this point will contains special
+builtins, called `mux builtins` for ndrange or subgroup


Since it isn't code, it seems more appropriate to put quotations around "mux builtins" here, then drop the quotes for future mentions. Maybe mux can stay code, given it is a partial part of the builtin names.

steffenlarsen · 2025-09-16T13:25:57Z

sycl/doc/design/SYCLNativeCPUPipeline.md

+
+The [vecz](SYCLNativeCPUVecz.md) whole-function vectorizer is optionally run.
+
+Note that VECZ may perform its own scalarization, depending on the


Nit; It's referred to as "vecz" in the previous paragraph and then as "VECZ" here. Would be good to have it consistent.

Changed to Vecz

sycl/doc/design/SYCLNativeCPUPipelinePasses.md

coldav requested a review from a team as a code owner September 10, 2025 16:27

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch 2 times, most recently from 4e43981 to 0e74590 Compare September 11, 2025 09:44

coldav requested a review from a team as a code owner September 11, 2025 09:44

coldav had a problem deploying to WindowsCILock September 11, 2025 09:44 — with GitHub Actions Error

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from 0e74590 to a742204 Compare September 11, 2025 10:03

coldav had a problem deploying to WindowsCILock September 11, 2025 10:04 — with GitHub Actions Error

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from a742204 to 5c56997 Compare September 11, 2025 10:11

coldav temporarily deployed to WindowsCILock September 11, 2025 10:11 — with GitHub Actions Inactive

coldav temporarily deployed to WindowsCILock September 11, 2025 10:36 — with GitHub Actions Inactive

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from 5c56997 to 80bee8b Compare September 11, 2025 11:12

coldav requested a review from a team as a code owner September 11, 2025 11:12

coldav had a problem deploying to WindowsCILock September 11, 2025 11:12 — with GitHub Actions Failure

coldav temporarily deployed to WindowsCILock September 11, 2025 11:55 — with GitHub Actions Inactive

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from 80bee8b to afe1ace Compare September 11, 2025 12:38

coldav requested a review from a team as a code owner September 11, 2025 12:38

coldav requested a review from cperkinsintel September 11, 2025 12:38

coldav had a problem deploying to WindowsCILock September 11, 2025 12:38 — with GitHub Actions Error

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from afe1ace to 7c6e3a8 Compare September 11, 2025 12:46

coldav had a problem deploying to WindowsCILock September 11, 2025 12:47 — with GitHub Actions Error

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch from 7c6e3a8 to 3e06d72 Compare September 11, 2025 13:00

coldav had a problem deploying to WindowsCILock September 11, 2025 13:01 — with GitHub Actions Error

coldav force-pushed the colin/add_native_cpu_pipeline_docs branch 2 times, most recently from 37c026c to 6092762 Compare September 11, 2025 13:24

coldav temporarily deployed to WindowsCILock September 11, 2025 13:24 — with GitHub Actions Inactive

coldav temporarily deployed to WindowsCILock September 11, 2025 14:07 — with GitHub Actions Inactive

coldav temporarily deployed to WindowsCILock September 12, 2025 12:59 — with GitHub Actions Inactive

uwedolinsky reviewed Sep 12, 2025

View reviewed changes

Response to more comments on SYCLNativeCPUPipeline.md

ec1273c

coldav temporarily deployed to WindowsCILock September 12, 2025 14:32 — with GitHub Actions Inactive

coldav temporarily deployed to WindowsCILock September 12, 2025 15:33 — with GitHub Actions Inactive

hvdijk reviewed Sep 15, 2025

View reviewed changes

sycl/doc/design/SYCLNativeCPU.md Outdated Show resolved Hide resolved

hvdijk reviewed Sep 15, 2025

View reviewed changes

sycl/doc/conf.py Outdated Show resolved Hide resolved

hvdijk reviewed Sep 15, 2025

View reviewed changes

sycl/doc/conf.py Outdated Show resolved Hide resolved

More updates from comments

71cb2ad

coldav had a problem deploying to WindowsCILock September 16, 2025 08:33 — with GitHub Actions Error

Remove png output

e801dba

coldav temporarily deployed to WindowsCILock September 16, 2025 08:54 — with GitHub Actions Inactive

coldav temporarily deployed to WindowsCILock September 16, 2025 09:33 — with GitHub Actions Inactive

coldav added 2 commits September 16, 2025 12:27

Remove mermaid dependency in favour of images

0a936a4

Removed unnecessary `` and \.

bc5daab

Fixed bad references

d88de7b

steffenlarsen reviewed Sep 16, 2025

View reviewed changes

coldav added 2 commits September 16, 2025 15:24

Updated for latest review comments

1f9af14

More changes for Vecz capitalisation

864cd5c

hvdijk reviewed Sep 16, 2025

View reviewed changes

sycl/doc/design/SYCLNativeCPUPipelinePasses.md Show resolved Hide resolved

hvdijk reviewed Sep 16, 2025

View reviewed changes

sycl/doc/design/SYCLNativeCPUPipelinePasses.md Outdated Show resolved Hide resolved

coldav added 3 commits September 16, 2025 17:14

Update after review comments

fe53fcc

Fix header levels in SYCLNativeCPU

5d275f2

More updates from reviews

dc58a74

hvdijk approved these changes Sep 16, 2025

View reviewed changes

		```

		As you can see, the `subhandler` steals the kernel's function name, and receives two pointer arguments: the first one points to the kernel arguments from the SYCL runtime, and the second one to the `nativecpu::state` struct.


		The [vecz](SYCLNativeCPUVecz.md) whole-function vectorizer is optionally run.

		Note that VECZ may perform its own scalarization, depending on the

[SYCL][NATIVE_CPU] Update docs for Native CPU compiler pipeline #20042

Are you sure you want to change the base?

[SYCL][NATIVE_CPU] Update docs for Native CPU compiler pipeline #20042

Uh oh!

Conversation

coldav commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coldav commented Sep 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coldav commented Sep 10, 2025 •

edited

Loading