[SYCL][Doc] Add FPGA properties to device global spec

[gmlueck]

Although these properties are intended mostly for FPGA users, there
is no prohibition against using them for other devices. Therefore,
we describe them in the main device global spec, rather than creating
a separate add-on spec for FPGA.

[gmlueck]

@GarveyJoe: Could you review this PR from the FPGA side? In particular, I changed the wording of device_image_life considerably.

@rolandschulz @Pennycook: Could you review synopsis for the compile-time-constant properties? I think these are the first properties whose value is an enum, so it would be good to consider if we like the style I chose here. Also, we should consider which namespace contains the properties. I put all of the properties in the top of the extension namespace (::sycl::ext::oneapi), which follows #4280, however I wonder if that namespace will get too crowded. Should we define a sub-namespace like ::sycl::ext::oneapi::property?

[Pennycook]

Also, we should consider which namespace contains the properties. I put all of the properties in the top of the extension namespace (::sycl::ext::oneapi), which follows #4280, however I wonder if that namespace will get too crowded. Should we define a sub-namespace like ::sycl::ext::oneapi::property?

I'm not sure how I feel about this, but looking to ISO C++ for inspiration they've had no problems with a single top-level std:: namespace containing everything. Conversely, I feel like SYCL's use of nested namespaces confuses a lot of people -- it's not enough to remember what a class is called, you also have to remember where it lives.

I've listed the different options I see below, ordered by preference. Where I say sycl:: I mean "sycl:: for standard features, sycl::ext::oneapi:: for extensions".

1. Everything in sycl:: namespace
2. Properties designed to be general in sycl::, class-specific properties defined in the class itself
3. Properties in sycl::property
4. Properties in nested namespaces like sycl::property::class_name

Note that 1) requires long names to avoid clashes (e.g. sycl::device_global_visibility) while 2) allows for shorter names with an obvious connection to the class (e.g. sycl::device_global::visibility).

EDIT: To properly finish the thought... I view the (existing) kernel properties as being generally applicable -- we already have many dispatch functions that care about things like work-group size and sub-group size, and we'll be able to re-use sycl::work_group_size everywhere we a property to describe that concept. But it's hard to imagine any other class except sycl::device_global caring about whether it is allocated per device or per device image.

[keryell]

Always interesting to see more FPGA stuff.

[gmlueck]

I like the naming suggestions that @keryell and @Pennycook made. This would result in the following property names:

• device_image_scope
• host_access (with values: read, write, read_write, none)
• init_mode (with the same values as before : reprogram, reset)
• implement_in_csr (with the same values as before: true, false)

Any objections from the FPGA team: @GarveyJoe, @mohammadfawaz, @mkinsner ?

[mohammadfawaz]

I like the naming suggestions that @keryell and @Pennycook made. This would result in the following property names:

• device_image_scope
• host_access (with values: read, write, read_write, none)
• init_mode (with the same values as before : reprogram, reset)
• implement_in_csr (with the same values as before: true, false)

Any objections from the FPGA team: @GarveyJoe, @mohammadfawaz, @mkinsner ?

The new names seem reasonable to me. I'll let @GarveyJoe and @mkinsner make the final call though.

[gmlueck]

The new names seem reasonable to me. I'll let @GarveyJoe and @mkinsner make the final call though.

I renamed the properties because I want the names in this PR to align with the names in the design doc I just submitted, and these proposed names seemed like the most likely outcome. I'm still happy to get feedback and alternatives from @GarveyJoe, @mkinsner, or anyone else, though. It's easy enough to update both PRs.

[GarveyJoe]

device_image_scope and host_access both sound better to me than the old versions. And I'm also happy with init_mode so long as we agree that it's still clear that it affects how initialization happens and not when it happens. I think the text makes that clear.

[artemrad]

I haven't read the Design Specification in full yet (it might get answered there), but wasn't there a need to template the copy operations on the instance of the device_global?

[gmlueck]

I haven't read the Design Specification in full yet (it might get answered there), but wasn't there a need to template the copy operations on the instance of the device_global?

@GarveyJoe proposed a solution that doesn't require this templating, and we decided that the API was nicer without the template parameter. The design doc describes how it works (see the section on integration header/footer).

[gmlueck]

Can I get an approval from someone on @intel/dpcpp-specification-reviewers? Maybe @Pennycook or @rolandschulz?