1 /* The libgomp plugin API.
2
3 Copyright (C) 2014-2023 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 /* Miscellaneous functions. */
111 extern void *GOMP_PLUGIN_malloc (size_t) __attribute__ ((malloc));
112 extern void *GOMP_PLUGIN_malloc_cleared (size_t) __attribute__ ((malloc));
113 extern void *GOMP_PLUGIN_realloc (void *, size_t);
114 void GOMP_PLUGIN_target_task_completion (void *);
115
116 extern void GOMP_PLUGIN_debug (int, const char *, ...)
117 __attribute__ ((format (printf, 2, 3)));
118 extern void GOMP_PLUGIN_error (const char *, ...)
119 __attribute__ ((format (printf, 1, 2)));
120 extern void GOMP_PLUGIN_fatal (const char *, ...)
121 __attribute__ ((noreturn, format (printf, 1, 2)));
122
123 extern void GOMP_PLUGIN_target_rev (uint64_t, uint64_t, uint64_t, uint64_t,
124 uint64_t, int,
125 void (*) (void *, const void *, size_t,
126 void *),
127 void (*) (void *, const void *, size_t,
128 void *), void *);
129
130 /* Prototypes for functions implemented by libgomp plugins. */
131 extern const char *GOMP_OFFLOAD_get_name (void);
132 extern unsigned int GOMP_OFFLOAD_get_caps (void);
133 extern int GOMP_OFFLOAD_get_type (void);
134 extern int GOMP_OFFLOAD_get_num_devices (unsigned int);
135 extern bool GOMP_OFFLOAD_init_device (int);
136 extern bool GOMP_OFFLOAD_fini_device (int);
137 extern unsigned GOMP_OFFLOAD_version (void);
138 extern int GOMP_OFFLOAD_load_image (int, unsigned, const void *,
139 struct addr_pair **, 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 bool GOMP_OFFLOAD_can_run (void *);
147 extern void GOMP_OFFLOAD_run (int, void *, void *, void **);
148 extern void GOMP_OFFLOAD_async_run (int, void *, void *, void **, void *);
149
150 extern void GOMP_OFFLOAD_openacc_exec (void (*) (void *), size_t, void **,
151 void **, unsigned *, void *);
152 extern void *GOMP_OFFLOAD_openacc_create_thread_data (int);
153 extern void GOMP_OFFLOAD_openacc_destroy_thread_data (void *);
154 extern struct goacc_asyncqueue *GOMP_OFFLOAD_openacc_async_construct (int);
155 extern bool GOMP_OFFLOAD_openacc_async_destruct (struct goacc_asyncqueue *);
156 extern int GOMP_OFFLOAD_openacc_async_test (struct goacc_asyncqueue *);
157 extern bool GOMP_OFFLOAD_openacc_async_synchronize (struct goacc_asyncqueue *);
158 extern bool GOMP_OFFLOAD_openacc_async_serialize (struct goacc_asyncqueue *,
159 struct goacc_asyncqueue *);
160 extern void GOMP_OFFLOAD_openacc_async_queue_callback (struct goacc_asyncqueue *,
161 void (*)(void *), void *);
162 extern void GOMP_OFFLOAD_openacc_async_exec (void (*) (void *), size_t, void **,
163 void **, unsigned *, void *,
164 struct goacc_asyncqueue *);
165 extern bool GOMP_OFFLOAD_openacc_async_dev2host (int, void *, const void *, size_t,
166 struct goacc_asyncqueue *);
167 extern bool GOMP_OFFLOAD_openacc_async_host2dev (int, void *, const void *, size_t,
168 struct goacc_asyncqueue *);
169 extern void *GOMP_OFFLOAD_openacc_cuda_get_current_device (void);
170 extern void *GOMP_OFFLOAD_openacc_cuda_get_current_context (void);
171 extern void *GOMP_OFFLOAD_openacc_cuda_get_stream (struct goacc_asyncqueue *);
172 extern int GOMP_OFFLOAD_openacc_cuda_set_stream (struct goacc_asyncqueue *,
173 void *);
174 extern union goacc_property_value
175 GOMP_OFFLOAD_openacc_get_property (int, enum goacc_property);
176
177 #ifdef __cplusplus
178 }
179 #endif
180
181 #endif