libgomp/libgomp-plugin.h

   1 /* The libgomp plugin API.
   2
   3    Copyright (C) 2014-2024 Free Software Foundation, Inc.
   4
   5    Contributed by Mentor Embedded.
   6
   7    This file is part of the GNU Offloading and Multi Processing Library
   8    (libgomp).
   9
  10    Libgomp is free software; you can redistribute it and/or modify it
  11    under the terms of the GNU General Public License as published by
  12    the Free Software Foundation; either version 3, or (at your option)
  13    any later version.
  14
  15    Libgomp is distributed in the hope that it will be useful, but WITHOUT ANY
  16    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  17    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  18    more details.
  19
  20    Under Section 7 of GPL version 3, you are granted additional
  21    permissions described in the GCC Runtime Library Exception, version
  22    3.1, as published by the Free Software Foundation.
  23
  24    You should have received a copy of the GNU General Public License and
  25    a copy of the GCC Runtime Library Exception along with this program;
  26    see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  27    <http://www.gnu.org/licenses/>.  */
  28
  29 #ifndef LIBGOMP_PLUGIN_H
  30 #define LIBGOMP_PLUGIN_H 1
  31
  32 #include <stdbool.h>
  33 #include <stddef.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /* Capabilities of offloading devices.  */
  41 #define GOMP_OFFLOAD_CAP_SHARED_MEM     (1 << 0)
  42 #define GOMP_OFFLOAD_CAP_NATIVE_EXEC    (1 << 1)
  43 #define GOMP_OFFLOAD_CAP_OPENMP_400     (1 << 2)
  44 #define GOMP_OFFLOAD_CAP_OPENACC_200    (1 << 3)
  45
  46 /* Type of offload target device.  Keep in sync with include/gomp-constants.h.  */
  47 enum offload_target_type
  48 {
  49   OFFLOAD_TARGET_TYPE_HOST = 2,
  50   /* OFFLOAD_TARGET_TYPE_HOST_NONSHM = 3 removed.  */
  51   OFFLOAD_TARGET_TYPE_NVIDIA_PTX = 5,
  52   OFFLOAD_TARGET_TYPE_HSA = 7,
  53   OFFLOAD_TARGET_TYPE_GCN = 8
  54 };
  55
  56 /* Opaque type to represent plugin-dependent implementation of an
  57    OpenACC asynchronous queue.  */
  58 struct goacc_asyncqueue;
  59
  60 /* Used to keep a list of active asynchronous queues.  */
  61 struct goacc_asyncqueue_list
  62 {
  63   struct goacc_asyncqueue *aq;
  64   struct goacc_asyncqueue_list *next;
  65 };
  66
  67 typedef struct goacc_asyncqueue *goacc_aq;
  68 typedef struct goacc_asyncqueue_list *goacc_aq_list;
  69
  70
  71 /* OpenACC 'acc_get_property' support.  */
  72
  73 /* Device property values.  Keep in sync with
  74    'libgomp/{openacc.h,openacc.f90}:acc_device_property_t'.  */
  75 enum goacc_property
  76   {
  77    /* Mask to tell numeric and string values apart.  */
  78 #define GOACC_PROPERTY_STRING_MASK 0x10000
  79
  80    /* Start from 1 to catch uninitialized use.  */
  81    GOACC_PROPERTY_MEMORY =              1,
  82    GOACC_PROPERTY_FREE_MEMORY =         2,
  83    GOACC_PROPERTY_NAME =                GOACC_PROPERTY_STRING_MASK | 1,
  84    GOACC_PROPERTY_VENDOR =              GOACC_PROPERTY_STRING_MASK | 2,
  85    GOACC_PROPERTY_DRIVER =              GOACC_PROPERTY_STRING_MASK | 3
  86   };
  87
  88 /* Container type for passing device properties.  */
  89 union goacc_property_value
  90 {
  91   const char *ptr;
  92   size_t val;
  93 };
  94
  95
  96 /* Auxiliary struct, used for transferring pairs of addresses from plugin
  97    to libgomp.  */
  98 struct addr_pair
  99 {
 100   uintptr_t start;
 101   uintptr_t end;
 102 };
 103
 104 /* This following symbol is used to name the target side variable struct that
 105    holds the designated ICVs of the target device. The symbol needs to be
 106    available to libgomp code and the offload plugin (which in the latter case
 107    must be stringified).  */
 108 #define GOMP_ADDITIONAL_ICVS __gomp_additional_icvs
 109
 110 #define GOMP_INDIRECT_ADDR_MAP __gomp_indirect_addr_map
 111
 112 /* Miscellaneous functions.  */
 113 extern void *GOMP_PLUGIN_malloc (size_t) __attribute__ ((malloc));
 114 extern void *GOMP_PLUGIN_malloc_cleared (size_t) __attribute__ ((malloc));
 115 extern void *GOMP_PLUGIN_realloc (void *, size_t);
 116 void GOMP_PLUGIN_target_task_completion (void *);
 117
 118 extern void GOMP_PLUGIN_debug (int, const char *, ...)
 119         __attribute__ ((format (printf, 2, 3)));
 120 extern void GOMP_PLUGIN_error (const char *, ...)
 121         __attribute__ ((format (printf, 1, 2)));
 122 extern void GOMP_PLUGIN_fatal (const char *, ...)
 123         __attribute__ ((noreturn, format (printf, 1, 2)));
 124
 125 extern void GOMP_PLUGIN_target_rev (uint64_t, uint64_t, uint64_t, uint64_t,
 126                                     uint64_t, int, struct goacc_asyncqueue *);
 127
 128 /* Prototypes for functions implemented by libgomp plugins.  */
 129 extern const char *GOMP_OFFLOAD_get_name (void);
 130 extern const char *GOMP_OFFLOAD_get_uid (int);
 131 extern unsigned int GOMP_OFFLOAD_get_caps (void);
 132 extern int GOMP_OFFLOAD_get_type (void);
 133 extern int GOMP_OFFLOAD_get_num_devices (unsigned int);
 134 extern bool GOMP_OFFLOAD_init_device (int);
 135 extern bool GOMP_OFFLOAD_fini_device (int);
 136 extern unsigned GOMP_OFFLOAD_version (void);
 137 extern int GOMP_OFFLOAD_load_image (int, unsigned, const void *,
 138                                     struct addr_pair **, uint64_t **,
 139                                     uint64_t *);
 140 extern bool GOMP_OFFLOAD_unload_image (int, unsigned, const void *);
 141 extern void *GOMP_OFFLOAD_alloc (int, size_t);
 142 extern bool GOMP_OFFLOAD_free (int, void *);
 143 extern bool GOMP_OFFLOAD_dev2host (int, void *, const void *, size_t);
 144 extern bool GOMP_OFFLOAD_host2dev (int, void *, const void *, size_t);
 145 extern bool GOMP_OFFLOAD_dev2dev (int, void *, const void *, size_t);
 146 extern int GOMP_OFFLOAD_memcpy2d (int, int, size_t, size_t,
 147                                   void*, size_t, size_t, size_t,
 148                                   const void*, size_t, size_t, size_t);
 149 extern int GOMP_OFFLOAD_memcpy3d (int, int, size_t, size_t, size_t, void *,
 150                                   size_t, size_t, size_t, size_t, size_t,
 151                                   const void *, size_t, size_t, size_t, size_t,
 152                                   size_t);
 153 extern bool GOMP_OFFLOAD_can_run (void *);
 154 extern void GOMP_OFFLOAD_run (int, void *, void *, void **);
 155 extern void GOMP_OFFLOAD_async_run (int, void *, void *, void **, void *);
 156
 157 extern void GOMP_OFFLOAD_openacc_exec (void (*) (void *), size_t, void **,
 158                                        void **, unsigned *, void *);
 159 extern void *GOMP_OFFLOAD_openacc_create_thread_data (int);
 160 extern void GOMP_OFFLOAD_openacc_destroy_thread_data (void *);
 161 extern struct goacc_asyncqueue *GOMP_OFFLOAD_openacc_async_construct (int);
 162 extern bool GOMP_OFFLOAD_openacc_async_destruct (struct goacc_asyncqueue *);
 163 extern int GOMP_OFFLOAD_openacc_async_test (struct goacc_asyncqueue *);
 164 extern bool GOMP_OFFLOAD_openacc_async_synchronize (struct goacc_asyncqueue *);
 165 extern bool GOMP_OFFLOAD_openacc_async_serialize (struct goacc_asyncqueue *,
 166                                                   struct goacc_asyncqueue *);
 167 extern void GOMP_OFFLOAD_openacc_async_queue_callback (struct goacc_asyncqueue *,
 168                                                        void (*)(void *), void *);
 169 extern void GOMP_OFFLOAD_openacc_async_exec (void (*) (void *), size_t, void **,
 170                                              void **, unsigned *, void *,
 171                                              struct goacc_asyncqueue *);
 172 extern bool GOMP_OFFLOAD_openacc_async_dev2host (int, void *, const void *, size_t,
 173                                                  struct goacc_asyncqueue *);
 174 extern bool GOMP_OFFLOAD_openacc_async_host2dev (int, void *, const void *, size_t,
 175                                                  struct goacc_asyncqueue *);
 176 extern void *GOMP_OFFLOAD_openacc_cuda_get_current_device (void);
 177 extern void *GOMP_OFFLOAD_openacc_cuda_get_current_context (void);
 178 extern void *GOMP_OFFLOAD_openacc_cuda_get_stream (struct goacc_asyncqueue *);
 179 extern int GOMP_OFFLOAD_openacc_cuda_set_stream (struct goacc_asyncqueue *,
 180                                                  void *);
 181 extern union goacc_property_value
 182   GOMP_OFFLOAD_openacc_get_property (int, enum goacc_property);
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif