[gcc.git] / libgomp / libgomp-plugin.h

/* The libgomp plugin API.

   Copyright (C) 2014-2022 Free Software Foundation, Inc.

   Contributed by Mentor Embedded.

   This file is part of the GNU Offloading and Multi Processing Library
   (libgomp).

   Libgomp is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3, or (at your option)
   any later version.

   Libgomp is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
   more details.

   Under Section 7 of GPL version 3, you are granted additional
   permissions described in the GCC Runtime Library Exception, version
   3.1, as published by the Free Software Foundation.

   You should have received a copy of the GNU General Public License and
   a copy of the GCC Runtime Library Exception along with this program;
   see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
   <http://www.gnu.org/licenses/>.  */

#ifndef LIBGOMP_PLUGIN_H
#define LIBGOMP_PLUGIN_H 1

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Capabilities of offloading devices.  */
#define GOMP_OFFLOAD_CAP_SHARED_MEM	(1 << 0)
#define GOMP_OFFLOAD_CAP_NATIVE_EXEC	(1 << 1)
#define GOMP_OFFLOAD_CAP_OPENMP_400	(1 << 2)
#define GOMP_OFFLOAD_CAP_OPENACC_200	(1 << 3)

/* Type of offload target device.  Keep in sync with include/gomp-constants.h.  */
enum offload_target_type
{
  OFFLOAD_TARGET_TYPE_HOST = 2,
  /* OFFLOAD_TARGET_TYPE_HOST_NONSHM = 3 removed.  */
  OFFLOAD_TARGET_TYPE_NVIDIA_PTX = 5,
  OFFLOAD_TARGET_TYPE_HSA = 7,
  OFFLOAD_TARGET_TYPE_GCN = 8
};

/* Opaque type to represent plugin-dependent implementation of an
   OpenACC asynchronous queue.  */
struct goacc_asyncqueue;

/* Used to keep a list of active asynchronous queues.  */
struct goacc_asyncqueue_list
{
  struct goacc_asyncqueue *aq;
  struct goacc_asyncqueue_list *next;
};

typedef struct goacc_asyncqueue *goacc_aq;
typedef struct goacc_asyncqueue_list *goacc_aq_list;


/* OpenACC 'acc_get_property' support.  */

/* Device property values.  Keep in sync with
   'libgomp/{openacc.h,openacc.f90}:acc_device_property_t'.  */
enum goacc_property
  {
   /* Mask to tell numeric and string values apart.  */
#define GOACC_PROPERTY_STRING_MASK 0x10000

   /* Start from 1 to catch uninitialized use.  */
   GOACC_PROPERTY_MEMORY =		1,
   GOACC_PROPERTY_FREE_MEMORY =		2,
   GOACC_PROPERTY_NAME =		GOACC_PROPERTY_STRING_MASK | 1,
   GOACC_PROPERTY_VENDOR =		GOACC_PROPERTY_STRING_MASK | 2,
   GOACC_PROPERTY_DRIVER =		GOACC_PROPERTY_STRING_MASK | 3
  };

/* Container type for passing device properties.  */
union goacc_property_value
{
  const char *ptr;
  size_t val;
};


/* Auxiliary struct, used for transferring pairs of addresses from plugin
   to libgomp.  */
struct addr_pair
{
  uintptr_t start;
  uintptr_t end;
};

/* This following symbol is used to name the target side variable struct that
   holds the designated ICVs of the target device. The symbol needs to be
   available to libgomp code and the offload plugin (which in the latter case
   must be stringified).  */
#define GOMP_ADDITIONAL_ICVS __gomp_additional_icvs

/* Miscellaneous functions.  */
extern void *GOMP_PLUGIN_malloc (size_t) __attribute__ ((malloc));
extern void *GOMP_PLUGIN_malloc_cleared (size_t) __attribute__ ((malloc));
extern void *GOMP_PLUGIN_realloc (void *, size_t);
void GOMP_PLUGIN_target_task_completion (void *);

extern void GOMP_PLUGIN_debug (int, const char *, ...)
	__attribute__ ((format (printf, 2, 3)));
extern void GOMP_PLUGIN_error (const char *, ...)
	__attribute__ ((format (printf, 1, 2)));
extern void GOMP_PLUGIN_fatal (const char *, ...)
	__attribute__ ((noreturn, format (printf, 1, 2)));

extern void GOMP_PLUGIN_target_rev (uint64_t, uint64_t, uint64_t, uint64_t,
				    uint64_t, int,
				    void (*) (void *, const void *, size_t,
					      void *),
				    void (*) (void *, const void *, size_t,
					      void *), void *);

/* Prototypes for functions implemented by libgomp plugins.  */
extern const char *GOMP_OFFLOAD_get_name (void);
extern unsigned int GOMP_OFFLOAD_get_caps (void);
extern int GOMP_OFFLOAD_get_type (void);
extern int GOMP_OFFLOAD_get_num_devices (unsigned int);
extern bool GOMP_OFFLOAD_init_device (int);
extern bool GOMP_OFFLOAD_fini_device (int);
extern unsigned GOMP_OFFLOAD_version (void);
extern int GOMP_OFFLOAD_load_image (int, unsigned, const void *,
				    struct addr_pair **, uint64_t **);
extern bool GOMP_OFFLOAD_unload_image (int, unsigned, const void *);
extern void *GOMP_OFFLOAD_alloc (int, size_t);
extern bool GOMP_OFFLOAD_free (int, void *);
extern bool GOMP_OFFLOAD_dev2host (int, void *, const void *, size_t);
extern bool GOMP_OFFLOAD_host2dev (int, void *, const void *, size_t);
extern bool GOMP_OFFLOAD_dev2dev (int, void *, const void *, size_t);
extern bool GOMP_OFFLOAD_can_run (void *);
extern void GOMP_OFFLOAD_run (int, void *, void *, void **);
extern void GOMP_OFFLOAD_async_run (int, void *, void *, void **, void *);

extern void GOMP_OFFLOAD_openacc_exec (void (*) (void *), size_t, void **,
				       void **, unsigned *, void *);
extern void *GOMP_OFFLOAD_openacc_create_thread_data (int);
extern void GOMP_OFFLOAD_openacc_destroy_thread_data (void *);
extern struct goacc_asyncqueue *GOMP_OFFLOAD_openacc_async_construct (int);
extern bool GOMP_OFFLOAD_openacc_async_destruct (struct goacc_asyncqueue *);
extern int GOMP_OFFLOAD_openacc_async_test (struct goacc_asyncqueue *);
extern bool GOMP_OFFLOAD_openacc_async_synchronize (struct goacc_asyncqueue *);
extern bool GOMP_OFFLOAD_openacc_async_serialize (struct goacc_asyncqueue *,
						  struct goacc_asyncqueue *);
extern void GOMP_OFFLOAD_openacc_async_queue_callback (struct goacc_asyncqueue *,
						       void (*)(void *), void *);
extern void GOMP_OFFLOAD_openacc_async_exec (void (*) (void *), size_t, void **,
					     void **, unsigned *, void *,
					     struct goacc_asyncqueue *);
extern bool GOMP_OFFLOAD_openacc_async_dev2host (int, void *, const void *, size_t,
						 struct goacc_asyncqueue *);
extern bool GOMP_OFFLOAD_openacc_async_host2dev (int, void *, const void *, size_t,
						 struct goacc_asyncqueue *);
extern void *GOMP_OFFLOAD_openacc_cuda_get_current_device (void);
extern void *GOMP_OFFLOAD_openacc_cuda_get_current_context (void);
extern void *GOMP_OFFLOAD_openacc_cuda_get_stream (struct goacc_asyncqueue *);
extern int GOMP_OFFLOAD_openacc_cuda_set_stream (struct goacc_asyncqueue *,
						 void *);
extern union goacc_property_value
  GOMP_OFFLOAD_openacc_get_property (int, enum goacc_property);

#ifdef __cplusplus
}
#endif

#endif
Commit	Line	Data
dced339c TS	1	/* The libgomp plugin API.
dced339c TS	2
7adcbafe	3	Copyright (C) 2014-2022 Free Software Foundation, Inc.
1df3f842	4
41dbbb37 TS	5	Contributed by Mentor Embedded.
41dbbb37 TS	6
f1f3453e TS	7	This file is part of the GNU Offloading and Multi Processing Library
f1f3453e TS	8	(libgomp).
1df3f842 JJ	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
41dbbb37 TS	29	#ifndef LIBGOMP_PLUGIN_H
	30	#define LIBGOMP_PLUGIN_H 1
	31
dced339c	32	#include <stdbool.h>
41dbbb37 TS	33	#include <stddef.h>
	34	#include <stdint.h>
	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
1df3f842	39
41dbbb37 TS	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. */
1df3f842 JJ	47	enum offload_target_type
1df3f842 JJ	48	{
41dbbb37	49	OFFLOAD_TARGET_TYPE_HOST = 2,
b97e78b7	50	/* OFFLOAD_TARGET_TYPE_HOST_NONSHM = 3 removed. */
41dbbb37	51	OFFLOAD_TARGET_TYPE_NVIDIA_PTX = 5,
fa499995 AS	52	OFFLOAD_TARGET_TYPE_HSA = 7,
fa499995 AS	53	OFFLOAD_TARGET_TYPE_GCN = 8
1df3f842 JJ	54	};
1df3f842 JJ	55
1f4c5b9b CLT	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
6fc0385c TS	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
a51df54e IV	96	/* Auxiliary struct, used for transferring pairs of addresses from plugin
	97	to libgomp. */
	98	struct addr_pair
1df3f842	99	{
a51df54e IV	100	uintptr_t start;
a51df54e IV	101	uintptr_t end;
1df3f842 JJ	102	};
1df3f842 JJ	103
9f2fca56 MV	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
0bac793e	109
41dbbb37 TS	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);
e4606348	114	void GOMP_PLUGIN_target_task_completion (void *);
41dbbb37 TS	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
131d18e9 TB	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
dced339c TS	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);
683f1184	134	extern int GOMP_OFFLOAD_get_num_devices (unsigned int);
dced339c TS	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 *,
0fcc0cf9	139	struct addr_pair , uint64_t );
dced339c TS	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 );
1f4c5b9b	149
345a8c17	150	extern void GOMP_OFFLOAD_openacc_exec (void () (void ), size_t, void **,
1f4c5b9b	151	void *, unsigned , void *);
dced339c TS	152	extern void *GOMP_OFFLOAD_openacc_create_thread_data (int);
dced339c TS	153	extern void GOMP_OFFLOAD_openacc_destroy_thread_data (void *);
d2903ce0	154	extern struct goacc_asyncqueue *GOMP_OFFLOAD_openacc_async_construct (int);
1f4c5b9b CLT	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 *);
345a8c17 TS	169	extern void *GOMP_OFFLOAD_openacc_cuda_get_current_device (void);
345a8c17 TS	170	extern void *GOMP_OFFLOAD_openacc_cuda_get_current_context (void);
1f4c5b9b CLT	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 *);
6fc0385c TS	174	extern union goacc_property_value
6fc0385c TS	175	GOMP_OFFLOAD_openacc_get_property (int, enum goacc_property);
dced339c	176
41dbbb37 TS	177	#ifdef __cplusplus
	178	}
	179	#endif
	180
	181	#endif