[AMDGPU] Start documenting calling conventions. NFC

[rovka]

Summary

Add a section to AMDGPUUsage.rst about calling conventions and list the
ones from the CallingConv enum. Full descriptions can come later (help
appreciated).

[arsenm]

llvm/docs/AMDGPUUsage.rst

1084

"graphics targets?" Doesn't really say how it's not an entry point

[nhaehnle]

There could probably be a general section here to state that in the graphics calling conventions, inreg is used to denote arguments mapped to SGPRs, while other arguments are mapped to VGPRs.

llvm/docs/AMDGPUUsage.rst

1050–1054

The logic between Mesa and AMDPAL here is actually the same.

[scott.linder]

Can you reupload with full context? If you're using the web interface I think https://www.llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface is still accurate, so something like:

git show HEAD -U999999 > mypatch.patch

I ask because I think this should be cross-referenced with (or maybe even combined with) the existing Call Convention docs around line ~13500:

Call Convention
~~~~~~~~~~~~~~~

.. note::

  This section is currently incomplete and has inaccuracies. It is WIP that will
  be updated as information is determined.

See :ref:`amdgpu-dwarf-address-space-identifier` for information on swizzled
addresses. Unswizzled addresses are normal linear addresses.

.. _amdgpu-amdhsa-function-call-convention-kernel-functions:

Kernel Functions
++++++++++++++++

This section describes the call convention ABI for the outer kernel function.
...

llvm/docs/AMDGPUUsage.rst

1039

Nit: capitalize

1049

The omission of the default ccc convention seems like it might lead to confusion. The backend supports it, so I would suggest just adding it at the front of the list and making it clear that it is the default.

[scchan]

llvm/docs/AMDGPUUsage.rst

1048

Nit: this list seems to be in a random order, can we sort this in alphabetical order or organize it in a more meaningful way?

[rovka]

Address review comments.

[rovka]

llvm/docs/AMDGPUUsage.rst

1048

Ok, I alphabetized it for now, except for the ccc which looks good at the top imo. I'm open to other suggestions.

1084

"graphics targets?"

...apparently :) I just copied the comments from the enum, I have no idea what this is used for (one of the reasons why I thought we should start writing these things up in more detail).

Doesn't really say how it's not an entry point

I mentioned that now. Ideally we'd describe it more thoroughly in a follow-up patch.

[rovka]

In D151996#4400527, @scott.linder wrote:

Can you reupload with full context? If you're using the web interface I think https://www.llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface is still accurate, so something like:

git show HEAD -U999999 > mypatch.patch

Sorry, I haven't used the web interface in a while so I forgot that part... Anyway, I got arc working again now, so it shouldn't happen again in the future.

I ask because I think this should be cross-referenced with (or maybe even combined with) the existing Call Convention docs around line ~13500:

Call Convention
~~~~~~~~~~~~~~~

.. note::

  This section is currently incomplete and has inaccuracies. It is WIP that will
  be updated as information is determined.

See :ref:`amdgpu-dwarf-address-space-identifier` for information on swizzled
addresses. Unswizzled addresses are normal linear addresses.

.. _amdgpu-amdhsa-function-call-convention-kernel-functions:

Kernel Functions
++++++++++++++++

This section describes the call convention ABI for the outer kernel function.
...

I added a :ref: to this from `amdgpu_kernel. There should probably be a reference to amdgpu-amdhsa-function-call-convention-non-kernel-functions` somewhere but I'm not sure where. Is this actually the ccc?

[scott.linder]

In D151996#4403029, @rovka wrote:

In D151996#4400527, @scott.linder wrote:

Can you reupload with full context? If you're using the web interface I think https://www.llvm.org/docs/Phabricator.html#requesting-a-review-via-the-web-interface is still accurate, so something like:

git show HEAD -U999999 > mypatch.patch

Sorry, I haven't used the web interface in a while so I forgot that part... Anyway, I got arc working again now, so it shouldn't happen again in the future.

No worries!

I ask because I think this should be cross-referenced with (or maybe even combined with) the existing Call Convention docs around line ~13500:

Call Convention
~~~~~~~~~~~~~~~

.. note::

  This section is currently incomplete and has inaccuracies. It is WIP that will
  be updated as information is determined.

See :ref:`amdgpu-dwarf-address-space-identifier` for information on swizzled
addresses. Unswizzled addresses are normal linear addresses.

.. _amdgpu-amdhsa-function-call-convention-kernel-functions:

Kernel Functions
++++++++++++++++

This section describes the call convention ABI for the outer kernel function.
...

I added a :ref: to this from `amdgpu_kernel. There should probably be a reference to amdgpu-amdhsa-function-call-convention-non-kernel-functions` somewhere but I'm not sure where. Is this actually the ccc?

Perfect, thank you!

And yes, AFAIU we just use the default ccc for non-kernel functions. I am actually only basing this off the observation that the IR doesn't print an explicit CC, though; I'm not really sure what else it could be?

[rovka]

Add ref to the description of the calling convention for AMDHSA non-kernel functions to the entry about the ccc.

[arsenm]

llvm/docs/AMDGPUUsage.rst

1080

Also fastcc but currently treated identically to the default ccc

[rovka]

Added the fast and cold calling conventions. AFAICT the only difference between these and the C calling convention is how hard we try to TCO.

[sebastian-ne]

llvm/docs/AMDGPUUsage.rst

1096–1099

For the description: A difference between amdgpu_gfx and the C calling convention is that in amdgpu_gfx, SGPR arguments are callee-save (preserved), in the C cc, they are not.
Otherwise, there is not much difference.

[rovka]

llvm/docs/AMDGPUUsage.rst

1096–1099

Surely that's one difference, but I'm not 100% convinced it's the only one. I think we should leave the more detailed description for a future patch.

[JonChesterfield]

In D151996#4396815, @nhaehnle wrote:

There could probably be a general section here to state that in the graphics calling conventions, inreg is used to denote arguments mapped to SGPRs, while other arguments are mapped to VGPRs.

@arsenm does compute have this available? I've periodically wanted to be able to write a function which assumes a parameter is passed in SGPRs and hope for a compile time error calling it if that doesn't work out.

[arsenm]

In D151996#4435341, @JonChesterfield wrote:

@arsenm does compute have this available? I've periodically wanted to be able to write a function which assumes a parameter is passed in SGPRs and hope for a compile time error calling it if that doesn't work out.

No, I just consider this a bug. The handling for inreg was artificially limited to amdgpu_gfx. You would also get a waterfall loop, not an error.

Semi-related, I think we should start interpreting i1 argument values as SGPR masks (i1 inreg would be extended to sreg32)

[nhaehnle]

Semi-related, I think we should start interpreting i1 argument values as SGPR masks (i1 inreg would be extended to sreg32)

Yeah, that makes a lot of sense. I think one challenge for compute to truly leverage this is that I believe Clang emits bool as i8. Or is that only in struct types?

[arsenm]

In D151996#4437208, @nhaehnle wrote:

Semi-related, I think we should start interpreting i1 argument values as SGPR masks (i1 inreg would be extended to sreg32)

Yeah, that makes a lot of sense. I think one challenge for compute to truly leverage this is that I believe Clang emits bool as i8. Or is that only in struct types?

If it's a pure bool I know you get zeroext i1. It does look like struct elements give i8

llvm/docs/AMDGPUUsage.rst

.. table:: AMDGPU LLVM IR Attributes
 
      "amdgpu-no-dispatch-id"                 The same as amdgpu-no-workitem-id-x, except for the
                                              llvm.amdgcn.dispatch.id intrinsic.
 
      "amdgpu-no-queue-ptr"                   Similar to amdgpu-no-workitem-id-x, except for the
                                              llvm.amdgcn.queue.ptr intrinsic. Note that unlike the other ABI hint
                                              attributes, the queue pointer may be required in situations where the
                                              intrinsic call does not directly appear in the program. Some subtargets
                                              require the queue pointer for to handle some addrspacecasts, as well
                                              as the llvm.amdgcn.is.shared, llvm.amdgcn.is.private, llvm.trap, and
                                              llvm.debug intrinsics.
 
      "amdgpu-no-hostcall-ptr"                Similar to amdgpu-no-implicitarg-ptr, except specific to the implicit
                                              kernel argument that holds the pointer to the hostcall buffer. If this
                                              attribute is absent, then the amdgpu-no-implicitarg-ptr is also removed.
 
      "amdgpu-no-heap-ptr"                    Similar to amdgpu-no-implicitarg-ptr, except specific to the implicit
                                              kernel argument that holds the pointer to an initialized memory buffer
                                              that conforms to the requirements of the malloc/free device library V1
                                              version implementation. If this attribute is absent, then the
                                              amdgpu-no-implicitarg-ptr is also removed.
 
      "amdgpu-no-multigrid-sync-arg"          Similar to amdgpu-no-implicitarg-ptr, except specific to the implicit
                                              kernel argument that holds the multigrid synchronization pointer. If this
                                              attribute is absent, then the amdgpu-no-implicitarg-ptr is also removed.
 
      "amdgpu-no-default-queue"               Similar to amdgpu-no-implicitarg-ptr, except specific to the implicit
                                              kernel argument that holds the default queue pointer. If this
                                              attribute is absent, then the amdgpu-no-implicitarg-ptr is also removed.
 
      "amdgpu-no-completion-action"           Similar to amdgpu-no-implicitarg-ptr, except specific to the implicit
                                              kernel argument that holds the completion action pointer. If this
                                              attribute is absent, then the amdgpu-no-implicitarg-ptr is also removed.
 
      ======================================= ==========================================================
 
+Calling Conventions
+-------------------
+
+The AMDGPU backend supports the following calling conventions:
+
+  .. table:: AMDGPU Calling Conventions
+     :name: amdgpu-cc
+
+     =============================== ==========================================================
+     Calling Convention              Description
+     =============================== ==========================================================
+     ``ccc``                         The C calling convention. Used by default.
+                                     See :ref:`amdgpu-amdhsa-function-call-convention-non-kernel-functions`
+                                     for more details.
+
+     ``fastcc``                      The fast calling convention. Mostly the same as the ``ccc``.
+
+     ``coldcc``                      The cold calling convention. Mostly the same as the ``ccc`.
+
+     ``amdgpu_cs``                   Used for Mesa/AMDPAL compute shaders.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_es``                   Used for AMDPAL shader stage before geometry shader if geometry is in
+                                     use. So either the domain (= tessellation evaluation) shader if
+                                     tessellation is in use, or otherwise the vertex shader.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_gfx``                  Used for AMD graphics targets. Functions with this calling convention
+                                     cannot be used as entry points.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_gs``                   Used for Mesa/AMDPAL geometry shaders.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_hs``                   Used for Mesa/AMDPAL hull shaders (= tessellation control shaders).
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_kernel``               See :ref:`_amdgpu-amdhsa-function-call-convention-kernel-functions`
+
+     ``amdgpu_ls``                   Used for AMDPAL vertex shader if tessellation is in use.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_ps``                   Used for Mesa/AMDPAL pixel shaders.
+                                     ..TODO::
+                                     Describe.
+
+     ``amdgpu_vs``                   Used for Mesa/AMDPAL last shader stage before rasterization (vertex
+                                     shader if tessellation and geometry are not in use, or otherwise
+                                     copy shader if one is needed).
+                                     ..TODO::
+                                     Describe.
+
+     =============================== ==========================================================
+
+
 .. _amdgpu-elf-code-object:
 
 ELF Code Object
 ===============
 
 The AMDGPU backend generates a standard ELF [ELF]_ relocatable code object that
 can be linked by ``lld`` to produce a standard ELF shared code object which can
 be loaded and executed on an AMDGPU target.