1/* The libgomp plugin API.
2
3   Copyright (C) 2014-2022 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
37extern "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.  */
47enum 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_INTEL_MIC = 6,
53  OFFLOAD_TARGET_TYPE_HSA = 7,
54  OFFLOAD_TARGET_TYPE_GCN = 8
55};
56
57/* Opaque type to represent plugin-dependent implementation of an
58   OpenACC asynchronous queue.  */
59struct goacc_asyncqueue;
60
61/* Used to keep a list of active asynchronous queues.  */
62struct goacc_asyncqueue_list
63{
64  struct goacc_asyncqueue *aq;
65  struct goacc_asyncqueue_list *next;
66};
67
68typedef struct goacc_asyncqueue *goacc_aq;
69typedef struct goacc_asyncqueue_list *goacc_aq_list;
70
71
72/* OpenACC 'acc_get_property' support.  */
73
74/* Device property values.  Keep in sync with
75   'libgomp/{openacc.h,openacc.f90}:acc_device_property_t'.  */
76enum goacc_property
77  {
78   /* Mask to tell numeric and string values apart.  */
79#define GOACC_PROPERTY_STRING_MASK 0x10000
80
81   /* Start from 1 to catch uninitialized use.  */
82   GOACC_PROPERTY_MEMORY =		1,
83   GOACC_PROPERTY_FREE_MEMORY =		2,
84   GOACC_PROPERTY_NAME =		GOACC_PROPERTY_STRING_MASK | 1,
85   GOACC_PROPERTY_VENDOR =		GOACC_PROPERTY_STRING_MASK | 2,
86   GOACC_PROPERTY_DRIVER =		GOACC_PROPERTY_STRING_MASK | 3
87  };
88
89/* Container type for passing device properties.  */
90union goacc_property_value
91{
92  const char *ptr;
93  size_t val;
94};
95
96
97/* Auxiliary struct, used for transferring pairs of addresses from plugin
98   to libgomp.  */
99struct addr_pair
100{
101  uintptr_t start;
102  uintptr_t end;
103};
104
105/* This symbol is to name a target side variable that holds the designated
106   'device number' of the target device. The symbol needs to be available to
107   libgomp code and the offload plugin (which in the latter case must be
108   stringified).  */
109#define GOMP_DEVICE_NUM_VAR __gomp_device_num
110
111/* Miscellaneous functions.  */
112extern void *GOMP_PLUGIN_malloc (size_t) __attribute__ ((malloc));
113extern void *GOMP_PLUGIN_malloc_cleared (size_t) __attribute__ ((malloc));
114extern void *GOMP_PLUGIN_realloc (void *, size_t);
115void GOMP_PLUGIN_target_task_completion (void *);
116
117extern void GOMP_PLUGIN_debug (int, const char *, ...)
118	__attribute__ ((format (printf, 2, 3)));
119extern void GOMP_PLUGIN_error (const char *, ...)
120	__attribute__ ((format (printf, 1, 2)));
121extern void GOMP_PLUGIN_fatal (const char *, ...)
122	__attribute__ ((noreturn, format (printf, 1, 2)));
123
124/* Prototypes for functions implemented by libgomp plugins.  */
125extern const char *GOMP_OFFLOAD_get_name (void);
126extern unsigned int GOMP_OFFLOAD_get_caps (void);
127extern int GOMP_OFFLOAD_get_type (void);
128extern int GOMP_OFFLOAD_get_num_devices (void);
129extern bool GOMP_OFFLOAD_init_device (int);
130extern bool GOMP_OFFLOAD_fini_device (int);
131extern unsigned GOMP_OFFLOAD_version (void);
132extern int GOMP_OFFLOAD_load_image (int, unsigned, const void *,
133				    struct addr_pair **);
134extern bool GOMP_OFFLOAD_unload_image (int, unsigned, const void *);
135extern void *GOMP_OFFLOAD_alloc (int, size_t);
136extern bool GOMP_OFFLOAD_free (int, void *);
137extern bool GOMP_OFFLOAD_dev2host (int, void *, const void *, size_t);
138extern bool GOMP_OFFLOAD_host2dev (int, void *, const void *, size_t);
139extern bool GOMP_OFFLOAD_dev2dev (int, void *, const void *, size_t);
140extern bool GOMP_OFFLOAD_can_run (void *);
141extern void GOMP_OFFLOAD_run (int, void *, void *, void **);
142extern void GOMP_OFFLOAD_async_run (int, void *, void *, void **, void *);
143
144extern void GOMP_OFFLOAD_openacc_exec (void (*) (void *), size_t, void **,
145				       void **, unsigned *, void *);
146extern void *GOMP_OFFLOAD_openacc_create_thread_data (int);
147extern void GOMP_OFFLOAD_openacc_destroy_thread_data (void *);
148extern struct goacc_asyncqueue *GOMP_OFFLOAD_openacc_async_construct (int);
149extern bool GOMP_OFFLOAD_openacc_async_destruct (struct goacc_asyncqueue *);
150extern int GOMP_OFFLOAD_openacc_async_test (struct goacc_asyncqueue *);
151extern bool GOMP_OFFLOAD_openacc_async_synchronize (struct goacc_asyncqueue *);
152extern bool GOMP_OFFLOAD_openacc_async_serialize (struct goacc_asyncqueue *,
153						  struct goacc_asyncqueue *);
154extern void GOMP_OFFLOAD_openacc_async_queue_callback (struct goacc_asyncqueue *,
155						       void (*)(void *), void *);
156extern void GOMP_OFFLOAD_openacc_async_exec (void (*) (void *), size_t, void **,
157					     void **, unsigned *, void *,
158					     struct goacc_asyncqueue *);
159extern bool GOMP_OFFLOAD_openacc_async_dev2host (int, void *, const void *, size_t,
160						 struct goacc_asyncqueue *);
161extern bool GOMP_OFFLOAD_openacc_async_host2dev (int, void *, const void *, size_t,
162						 struct goacc_asyncqueue *);
163extern void *GOMP_OFFLOAD_openacc_cuda_get_current_device (void);
164extern void *GOMP_OFFLOAD_openacc_cuda_get_current_context (void);
165extern void *GOMP_OFFLOAD_openacc_cuda_get_stream (struct goacc_asyncqueue *);
166extern int GOMP_OFFLOAD_openacc_cuda_set_stream (struct goacc_asyncqueue *,
167						 void *);
168extern union goacc_property_value
169  GOMP_OFFLOAD_openacc_get_property (int, enum goacc_property);
170
171#ifdef __cplusplus
172}
173#endif
174
175#endif
176