Determine where to document platform-specific Vulkan interface requirements

[nsubtil]

There needs to be some location we can point people to when they need to find out about platform-specific requirements for interfacing with Vulkan. Some of these requirements include:

• What is the ABI?
• What libraries do I link against?
• What commands are directly exported by a Vulkan Implementation/Loader versus which ones do I have to use GIPA/GDPA for?
• Are layers available and how does a user integrate with them?
• Where can I go to ask further questions?

[krOoze]

I think the SDK documentation, i.e. Lunar Xchange Docs should fill that role. The questions 2) 3) 4) are specific to the loader/SDK used.

Where can I go to ask further questions?

Probably Vulkan repo if you need to speak to the authors. Otherwise StackOverflow or official Vulkan forum is good a place as any to get comunity help.

What is the ABI?

The usual C99 one as defined by the commands and structures in the Vulkan specification. There's even a separate specific chapter in the spec. Bindings to other languages should specify it at the place of their provider.

There already is Vulkan landing page, that should link to everything one might want to know and more.

[KarenGhavam-lunarG]

Question: Is this issue due to direct feedback from ISVs/developers? Is it possible they are not users of the SDK and therefore are wondering where to get documentation for items 2, 3, and 4 (and the other items as well)?

[critsec]

Android-specific documentation is here: https://developer.android.com/ndk/guides/graphics/index.html. There's certainly room for improvement, but it covers at least some of these topics.

[KarenGhavam-lunarG]

What commands are directly exported by a Vulkan Implementation/Loader versus which ones do I have to use GIPA/GDPA for?

The loader exports the Vulkan core API entrypoints to simplify Vulkan development when an application links directly to the loader library. The Vulkan loader does not export extensions because extensions can "come and go" and by exporting extensions, you will cause versioning issues. The only exception to this was the WSI extensions. It is defined by the Vulkan spec (via the Normative Reference "Vulkan Loader Specification and Architecture Overview"), that the WSI extensions are to be exported by the loader.

The Normative Reference, "Vulkan Loader Specification and Architecture Overview" documents how to interface with the loader. It is found in the Loader and Validation Layer repo here (see the section on "Interfacing with Vulkan Functions"). This document is for Linux and Windows. For Android, you can reference Android-specific information as referenced earlier by @critsec in this issue (https://developer.android.com/ndk/guides/graphics/index.html)

There has been other discussions about creating a utility that would do the series of vkGetInstanceProcAddr and vkGetDeviceProcAddr calls for the application to determine the address of all functions and extensions available to the application (@mtavenrath started an implementation of such a utility as mentioned in github issue 2143).

One of the challenges with this utility was the problem of WSI extensions being exported twice (once by the utility, and once by the loader), causing conflicts between the utility and the loader (and hence why LunarG hasn't included it as part of the Vulkan SDK). The conflicts occur because the utility detects the WSI extensions as extensions and exports them and the loader also exports the WSI extensions (as defined earlier by the normative reference in the Vulkan specification). Here are two possible solutions to this:

1. Hard code in the utility the WSI extensions and don't export them (they are documented in the platform's loader interface documentation mentioned earlier). This obviously has the disadvantage that if there were a change to the WSI extensions, the utility could get out of date. This risk is low because the actual liklihood of WSI extension changes is probably low.

2. Modify the Vulkan header XML to flag the WSI extensions so that the utility can pro-grammatically detect that these extensions shouldn't be exported. A modification to the XML could be sent to the working group for consideration.

[nsubtil]

Seeing as though we seem to be dealing with two separate problems in this issue, I decided to split off #21 to deal with the issues around extension loading.

I'd like to focus this issue on figuring out what platform-specific interactions are not currently documented and where to document them. @alonorbach had suggested that a good course of action might be to remove all platform-specific info from the main Vulkan spec and move them into separate, per-platform documents.

(Also tagging @jjulianoatnv, who has expressed interest in this topic as well.)

[linyaa-kiwi]

Now that Vulkan 1.1 is released, which adds new core entrypoints, I have questions about the loader's versioning scheme on Linux. Does the loader have a documented policy explaining how SONAME relates to the Vulkan version? Ditto for the installed filename. Ditto for pkg-config.

[lenny-lunarg]

Alright, after the discussions on the SI call, I've tried to get a better grip on what's going on with this issue. So I'm going to try to outline my understanding of the current state of documentation, and outline a proposal for what I think should be done. Please feel free to correct my understanding of the current state of documentation if it is wrong or incomplete. Also, feel free to comment on or criticize the proposal I have, but please suggest alternatives when you do so.

Documentation we currently have

The application interface to the loader is documented within the LoaderAndLayerInterace document, under the section titled "Application Interface to the Loader". This documentation answers several questions that were raised in the inital questions on this issue, such as:

• What libraries do I link against?
• What commands are directly exported by a Vulkan Implementation/Loader versus whih ones do I have to use GIPA/GDPA for?
• Are layers available and how does a user integrate with them?

This document contains more than just that, however. The same document also outlines the interface between the loader and layers, under the section "Loader And Layer Interface". On top of that, the "Vulkan Installable Client Driver Interface with the Loader" section outlines the loader/layer interface.

My understanding of the questions in this issue is that they mostly relate to the application interface, but I think we may also need to consider the layer and ICD interfaces, since they are all a part of the broader Vulkan ABI.

Documentation that I am unsure of the coverage:

There is a good deal of Android documentation floating around, but I am not aware of the current state of it. This page serves as a landing point for Vulkan Android documentation. This documentation looks to me like it's written more as a getting started guide, whereas the LoaderAndLayerInterface doc that I linked to in the previous section is more of technical specification-type document. I am unaware of what other Android documentation may or may not exist.

Documentation that is missing:

There is no documentation for any application-facing behavior that is not covered by the spec and which originates in the ICD. The loader behavior is documented in the LoaderAndLayerInterface document, and the loader-facing ICD behavior is documented in the loader doc. The main undocumented behavior that I am getting at is WSI-related. The spec is intentionally vague about WSI, because it is highly platform-specifc. This missing information is questions like:

• Can an application reuse a window after a surface has been created and destroyed on it?
• Exactly how must a window be configured for it to create a valid Vulkan surface?
• How does a full-screen exclusive-mode window that is part of a Vulkan swapchain behave?

If there are answers to these questions, I'm not aware of where they are.

Other thoughts

There are two other issues, which I think are worth touching on.

The first is that even when people have a question that is documented, people often don't know where to look for it. The fact that several of the questions from this thread were already documented in the LoaderAndLayerInterface file is indicative of this. This suggests that we need better organization and a clear place where people can go to look up behavior that is (intentionally) not covered by the spec.

The other issue I see is that the holes in documentation coverage mean that applications have to guess with regards to this behavior. And since there isn't a clear way to determine correct behavior, we could wind up with a situation where different drivers have different (and possibly mutually exclusive) behavior. But I think people here basically why undocumented behavior is bad.

Proposal

I suggest that we create the following documents:

• ABI Overview: An overview of the ABI, including some very basic info about the components, along with links to the other documents. It would mainly serve as an index page for more detailed documentation.
• Application Interface: A description of all of the application-facing behavior of the two loaders (desktop and android). This would include information such as what to link to, which entry points are exposed to, the benefits of vkGet*ProcAddr, etc.
• WSI Behavior: A description of the interaction between Vulkan and the native windowing system. This would cover behavior that is intentionally left vague in the Vulkan spec because it is platform-specific. This document would dictate proper driver behavior when interfacing with the windowing system.
• Layer Interface: A description of the interface between the loaders and layers
• ICD Interface: A description of the interface between the loaders and drivers

I think that it would be best to omit documents that are more about getting started on a platform, because I think those documents are best written as part of an SDK. Both the Android documentation and the LunarG SDK currently include documents that provide a step by step guide to get started.

While I've suggested what documentation we need, there isn't a clear place to put this documentation. The two natural locations seem like the Vulkan-Ecosystem repo and the Vulkan-Docs repo. However, the ecosystem repo is being used more as a dispatching repo than anything that actually contains files. The Vulkan-Docs repo is really the specification and does not include implementation-specific info, such as the documentation I'm proposing. Furthermore, the Vulkan-LoaderAndValidationLayers repo isn't an option, since that will be split into smaller repos, shortly.

I would suggest the we put the documentation in the new Vulkan-Headers repo, once that repo is up and running. Vulkan-Headers will contain the header files used for not only Vulkan, but also for the interfaces between the loader, layers, and ICDs. Since this documentation will largely cover those interfaces, this seems like the most natural location for it.

[nsubtil]

We discussed this in the Ecosystem call today. The overall sentiment is that none of the current repos seem like a natural home for this documentation.

The proposal to use the Vulkan-Headers repo conflicts with the use case where projects would want to embed that repo in their source tress to have access to the Vulkan headers --- adding documentation material in that repo makes it unwieldy (and potentially confusing). The Vulkan spec repo is dedicated to just the specification document, and it is tricky to extend the scope due to potential legal issues around it.

We'd like to drive towards the same level of quality as the spec for the platform-specific documentation, since this is a crucial piece of information for developers and probably just as important to have as the spec itself. To that end, it would be good if the platform-specific docs could be built in a similar way to the Vulkan spec (e.g., using the same asciidoc-based system), since that would help bring some consistency overall and make for easier concurrent development of both. It would also be really nice if we could have a single build process that generates both the spec as well as the platform-specific documents all at once.

One way to achieve this would be to create a new repo, which would host these platform-specific documents (plus any others that may make sense down the road) and reference the existing spec repo as a submodule. This could enable both concurrent development of specs + platform-specific documentation, a single consistent doc build, etc., without having to make changes (either in scope or in build logistics) to the spec repo itself. It would also become a single point for developers to obtain all of the Vulkan documentation from, without having to pull various crucial bits of documentation from different and seemingly unrelated repositories.

We intend to bring this feedback into the WG for consideration. Will hold off for about a week or so to allow folks the opportunity to comment on this beforehand.

[ianelliottus]

I wish I had seen this issue earlier, as I was involved in the early documentation efforts, and previous discussions of this. I also thought that the Ecosystem forum would have routed this to the SI TSG (at least for some of it, because that's where things were previously decided and documentation created). I'm not sure of the current doc state, including @chadversary's question about so-name versioning for Linux (I wrote that up 3 years ago). I can probably find things if they are missing.

[KarenGhavam-lunarG]

This issue was routed to the SI TSG and discussed there. Lenny (as a member of the SI TSG) took the action to document current state of documentation, what's missing, etc and make some recommendations. That is his post above.

[marty-johnson59]

This repository is being archived as it has been replaced with the vulkan.org website (https://www.vulkan.org) and is no longer being maintained (i.e., issues posted here are no longer being addressed ). After reviewing issues posted here, most (if not all) have been resolved or have already been re-opened in Vulkan-Docs (https://github.com/KhronosGroup/Vulkan-Docs) or other repositories for further consideration. Therefore, all issues in this repository will be closed. If you believe your issue has not yet been resolved, please re-open in Vulkan-Docs. Thanks!