[docs][tools][DirectX] Document DXContainer debug info parts#163
[docs][tools][DirectX] Document DXContainer debug info parts#163dzhidzhoev wants to merge 2 commits into
Conversation
This patch adds ILDB, ILDN, VERS, SRCI parts format documentation. It describes how to use LLVM tools to inspect them. Additionally, llvm-pdbutil documentation has been expanded with information on how to inspect PDB files generated by the DirectX compiler.
|
To check html version:
|
| .. option:: -dxcontainer | ||
|
|
||
| When used with :option:`-streams`, dump a summary of the DXContainer stored in | ||
| the PDB file's DXContainer stream. Shader companion PDB files produced by the | ||
| DirectX backend store debug-related container parts in this stream. For | ||
| example:: | ||
|
|
||
| llvm-pdbutil dump --streams --dxcontainer shader.pdb |
There was a problem hiding this comment.
These options work independently, --streams prints the list of all PDB streams, --dxcontainer tries to print only the DXContainer stream if there is one.
There was a problem hiding this comment.
Thank you! Fixed that.
| .. option:: -all | ||
|
|
||
| Dump everything :program:`llvm-pdbutil` knows how to dump, including the | ||
| DXContainer stream when present. |
There was a problem hiding this comment.
I think we shouldn't mention DXContainer here, maybe just make the description the same as in other commands, "Implies most other options."?
There was a problem hiding this comment.
Fixed. I agree with you.
| .. option:: --dxcontainer | ||
|
|
||
| Export the DXContainer stored in the PDB file's DXContainer stream. This is | ||
| the usual way to recover the debug-related container parts from a shader | ||
| companion PDB file. |
There was a problem hiding this comment.
Should we add that it's effectively a synonym to --stream=5?
| companion PDB file is requested, the ILDB part is written to the PDB unless | ||
| llc's ``--dx-embed-debug`` is specified, in which case it is written to both the main | ||
| DXContainer and the PDB. |
There was a problem hiding this comment.
Should this mention the Driver's flags too? Here and where other options are referenced. I know it's technically llvm docs, not clang, but where else would we write about driver flags and where to use them?
There was a problem hiding this comment.
Well, I think it should not mention clang-dxc flags here, because of the reason you mention, and because this doc is rather DXContainer format description (I was in doubt even about adding examples of tool flags, but Andrew asked for that specifically, since tools help to investigate DXContainers).
We could add dxc flags description to some clang document. However, I haven't found where we could add it:
- AFAIK there are some HLSL-specific documents, but they mention only a couple of dxc flags.
- Some dxc driver flags appear in
tools/clang/docs/html/ClangCommandLineReference.html, which is automatically generated fromHelpText<>of options described inclang/include/clang/Options/Options.td. However, only options usable withclangtool are visible in that doc file (notclang-dxc-only options, but those which haveClangOptionvisibility).
I think we should discuss separately where to document clang-dxc options, if we choose to add separate rst documentation for them.
There was a problem hiding this comment.
Let's ask people tomorrow how to approach this.
2 participants
This patch adds ILDB, ILDN, VERS, SRCI parts format documentation. It describes how to use LLVM tools to inspect them. Additionally, llvm-pdbutil documentation has been expanded with information on how to inspect PDB files generated by the DirectX compiler.