gcc/ada/gnat_cuda.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                 C U D A                                  --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2010-2023, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  This package defines CUDA-specific datastructures and subprograms.
  27 --
  28 --  Compiling for CUDA requires compiling for two targets. One is the CPU (more
  29 --  frequently named "host"), the other is the GPU (the "device"). Compiling
  30 --  for the host requires compiling the whole program. Compiling for the device
  31 --  only requires compiling packages that contain CUDA kernels.
  32 --
  33 --  When compiling for the device, GNAT-LLVM is used. It produces assembly
  34 --  tailored to Nvidia's GPU (NVPTX). This NVPTX code is then assembled into
  35 --  an object file by ptxas, an assembler provided by Nvidia. This object file
  36 --  is then combined with its source code into a fat binary by a tool named
  37 --  `fatbin`, also provided by Nvidia. The resulting fat binary is turned into
  38 --  a regular object file by the host's linker and linked with the program that
  39 --  executes on the host.
  40 --
  41 --  A CUDA kernel is a procedure marked with the CUDA_Global pragma or aspect.
  42 --  CUDA_Global does not have any effect when compiling for the device. When
  43 --  compiling for the host, the frontend stores procedures marked with
  44 --  CUDA_Global in a hash table the key of which is the Node_Id of the package
  45 --  body that contains the CUDA_Global procedure. This is done in sem_prag.adb.
  46 --  When emitting an ALI file for a compilation unit, the frontend emits 'K'
  47 --  lines for each visible CUDA kernel (see Output_CUDA_Symbols in
  48 --  lib-writ.adb). This allows the binder to see all kernels in a program and
  49 --  emit code to register the kernels with the CUDA runtime.
  50
  51 --  Registering a CUDA kernel with the CUDA runtime requires multiple function
  52 --  calls:
  53 --  - The first one registers the fat binary which corresponds to the package
  54 --    with the CUDA runtime.
  55 --  - Then, as many function calls as there are kernels in order to bind them
  56 --    with the fat binary.
  57 --    fat binary.
  58 --  - The last call lets the CUDA runtime know that we are done initializing
  59 --    CUDA.
  60 --  All of that is performed by the code emitted by bindgen.adb.
  61 --
  62 --  Once a CUDA package is initialized, its kernels are ready to be used.
  63 --  Launching CUDA kernels is done by using the CUDA_Execute pragma. When
  64 --  compiling for the host, the CUDA_Execute pragma is expanded into a declare
  65 --  block which performs calls to the CUDA runtime functions.
  66 --  - The first one pushes a "launch configuration" on the "configuration
  67 --    stack" of the CUDA runtime.
  68 --  - The second call pops this call configuration, making it effective.
  69 --  - The third call actually launches the kernel.
  70 --  Light validation of the CUDA_Execute pragma is performed in sem_prag.adb
  71 --  and expansion is performed in exp_prag.adb.
  72
  73 with Types; use Types;
  74
  75 package GNAT_CUDA is
  76
  77    procedure Add_CUDA_Device_Entity (Pack_Id : Entity_Id; E : Entity_Id);
  78    --  And E to the list of CUDA_Device entities that belong to Pack_Id
  79
  80    procedure Add_CUDA_Kernel (Pack_Id : Entity_Id; Kernel : Entity_Id);
  81    --  Add Kernel to the list of CUDA_Global nodes that belong to Pack_Id.
  82    --  Kernel is a procedure entity marked with CUDA_Global, Pack_Id is the
  83    --  entity of its parent package body.
  84
  85    procedure Expand_CUDA_Package (N : Node_Id);
  86    --  When compiling for the host:
  87    --  - Empty content of CUDA_Global procedures.
  88    --  - Remove declarations of CUDA_Device entities.
  89
  90    function Get_CUDA_Kernels (Pack_Id : Entity_Id) return Elist_Id;
  91    --  Returns an Elist of all procedures marked with pragma CUDA_Global that
  92    --  are declared within package body Pack_Body. Returns No_Elist if Pack_Id
  93    --  does not contain such procedures.
  94
  95 end GNAT_CUDA;