Actual source code: petscdevicetypes.h
1: #pragma once
3: #include <petscsystypes.h>
4: #include <petscerror.h>
6: // Some overzealous older gcc versions warn that the comparisons below are always true. Neat
7: // that it can detect this, but the tautology *is* the point of the static_assert()!
8: #if defined(__GNUC__) && __GNUC__ >= 6 && !PetscDefined(HAVE_WINDOWS_COMPILERS)
9: #define PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING 1
10: #else
11: #define PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING 0
12: #endif
14: /* SUBMANSEC = Sys */
16: /*E
17: PetscMemType - Memory type of a pointer
19: Level: beginner
21: Note:
22: `PETSC_MEMTYPE_KOKKOS` depends on the Kokkos backend configuration
24: Developer Notes:
25: This enum uses a function (`PetscMemTypeToString()`) to convert to string representation so
26: cannot be used in `PetscOptionsEnum()`.
28: Encoding of the bitmask in binary\: xxxxyyyz
29: .vb
30: z = 0 - Host memory
31: z = 1 - Device memory
32: yyy = 000 - CUDA-related memory
33: yyy = 001 - HIP-related memory
34: yyy = 010 - SYCL-related memory
35: xxxxyyy1 = 0000,0001 - CUDA memory
36: xxxxyyy1 = 0001,0001 - CUDA NVSHMEM memory
37: xxxxyyy1 = 0000,0011 - HIP memory
38: xxxxyyy1 = 0000,0101 - SYCL memory
39: .ve
41: Other types of memory, e.g., CUDA managed memory, can be added when needed.
43: .seealso: `PetscMemTypeToString()`, `VecGetArrayAndMemType()`,
44: `PetscSFBcastWithMemTypeBegin()`, `PetscSFReduceWithMemTypeBegin()`
45: E*/
46: typedef enum {
47: PETSC_MEMTYPE_HOST = 0,
48: PETSC_MEMTYPE_DEVICE = 1, /* 0x01 */
49: PETSC_MEMTYPE_CUDA = 1, /* 0x01 */
50: PETSC_MEMTYPE_NVSHMEM = 17, /* 0x11 */
51: PETSC_MEMTYPE_HIP = 3, /* 0x03 */
52: PETSC_MEMTYPE_SYCL = 5 /* 0x05 */
53: } PetscMemType;
54: #if PetscDefined(HAVE_CUDA)
55: #define PETSC_MEMTYPE_KOKKOS PETSC_MEMTYPE_CUDA
56: #elif PetscDefined(HAVE_HIP)
57: #define PETSC_MEMTYPE_KOKKOS PETSC_MEMTYPE_HIP
58: #elif PetscDefined(HAVE_SYCL)
59: #define PETSC_MEMTYPE_KOKKOS PETSC_MEMTYPE_SYCL
60: #else
61: #define PETSC_MEMTYPE_KOKKOS PETSC_MEMTYPE_HOST
62: #endif
64: /*MC
65: PetscMemTypeHost - Returns `PETSC_TRUE` if a given `PetscMemType` refers to memory ONLY accessible from the host, thus Unified Virtual Memory (UVM) managed memory would return `PETSC_FALSE`
67: Synopsis:
68: #include <petscdevicetypes.h>
69: PetscBool PetscMemTypeHost(PetscMemType m)
71: Not Collective; No Fortran Support
73: Input Parameter:
74: . m - the `PetscMemType` value
76: Level: beginner
78: .seealso: `PetscMemType`, `PetscMemTypeDevice()`, `PetscMemTypeCUDA()`, `PetscMemTypeHIP()`, `PetscMemTypeSYCL()`, `PetscMemTypeNVSHMEM()`
79: M*/
80: #define PetscMemTypeHost(m) ((((m) & 0x1) == PETSC_MEMTYPE_HOST) ? PETSC_TRUE : PETSC_FALSE)
82: /*MC
83: PetscMemTypeDevice - Returns `PETSC_TRUE` if a given `PetscMemType` refers to any kind of memory accessible from the device, including Unified Virtual Memory (UVM) managed memory
85: Synopsis:
86: #include <petscdevicetypes.h>
87: PetscBool PetscMemTypeDevice(PetscMemType m)
89: Not Collective; No Fortran Support
91: Input Parameter:
92: . m - the `PetscMemType` value
94: Level: beginner
96: .seealso: `PetscMemType`, `PetscMemTypeHost()`, `PetscMemTypeCUDA()`, `PetscMemTypeHIP()`, `PetscMemTypeSYCL()`, `PetscMemTypeNVSHMEM()`
97: M*/
98: #define PetscMemTypeDevice(m) ((((m) & 0x1) == PETSC_MEMTYPE_DEVICE) ? PETSC_TRUE : PETSC_FALSE)
100: /*MC
101: PetscMemTypeCUDA - Returns `PETSC_TRUE` if a given `PetscMemType` refers to CUDA device memory (including CUDA NVSHMEM memory)
103: Synopsis:
104: #include <petscdevicetypes.h>
105: PetscBool PetscMemTypeCUDA(PetscMemType m)
107: Not Collective; No Fortran Support
109: Input Parameter:
110: . m - the `PetscMemType` value
112: Level: beginner
114: .seealso: `PetscMemType`, `PetscMemTypeDevice()`, `PetscMemTypeHIP()`, `PetscMemTypeSYCL()`, `PetscMemTypeNVSHMEM()`
115: M*/
116: #define PetscMemTypeCUDA(m) ((((m) & 0xF) == PETSC_MEMTYPE_CUDA) ? PETSC_TRUE : PETSC_FALSE)
118: /*MC
119: PetscMemTypeHIP - Returns `PETSC_TRUE` if a given `PetscMemType` refers to HIP device memory
121: Synopsis:
122: #include <petscdevicetypes.h>
123: PetscBool PetscMemTypeHIP(PetscMemType m)
125: Not Collective; No Fortran Support
127: Input Parameter:
128: . m - the `PetscMemType` value
130: Level: beginner
132: .seealso: `PetscMemType`, `PetscMemTypeDevice()`, `PetscMemTypeCUDA()`, `PetscMemTypeSYCL()`, `PetscMemTypeNVSHMEM()`
133: M*/
134: #define PetscMemTypeHIP(m) ((((m) & 0xF) == PETSC_MEMTYPE_HIP) ? PETSC_TRUE : PETSC_FALSE)
136: /*MC
137: PetscMemTypeSYCL - Returns `PETSC_TRUE` if a given `PetscMemType` refers to SYCL device memory
139: Synopsis:
140: #include <petscdevicetypes.h>
141: PetscBool PetscMemTypeSYCL(PetscMemType m)
143: Not Collective; No Fortran Support
145: Input Parameter:
146: . m - the `PetscMemType` value
148: Level: beginner
150: .seealso: `PetscMemType`, `PetscMemTypeDevice()`, `PetscMemTypeCUDA()`, `PetscMemTypeHIP()`, `PetscMemTypeNVSHMEM()`
151: M*/
152: #define PetscMemTypeSYCL(m) ((((m) & 0xF) == PETSC_MEMTYPE_SYCL) ? PETSC_TRUE : PETSC_FALSE)
154: /*MC
155: PetscMemTypeNVSHMEM - Returns `PETSC_TRUE` if a given `PetscMemType` refers to NVSHMEM memory
157: Synopsis:
158: #include <petscdevicetypes.h>
159: PetscBool PetscMemTypeNVSHMEM(PetscMemType m)
161: Not Collective; No Fortran Support
163: Input Parameter:
164: . m - the `PetscMemType` value
166: Level: beginner
168: .seealso: `PetscMemType`, `PetscMemTypeDevice()`, `PetscMemTypeCUDA()`, `PetscMemTypeHIP()`, `PetscMemTypeSYCL()`
169: M*/
170: #define PetscMemTypeNVSHMEM(m) (((m) == PETSC_MEMTYPE_NVSHMEM) ? PETSC_TRUE : PETSC_FALSE)
172: #if defined(__cplusplus)
173: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
174: #pragma GCC diagnostic push
175: #pragma GCC diagnostic ignored "-Wtautological-compare"
176: #endif
177: static_assert(PetscMemTypeHost(PETSC_MEMTYPE_HOST), "");
178: static_assert(!PetscMemTypeHost(PETSC_MEMTYPE_DEVICE), "");
179: static_assert(!PetscMemTypeHost(PETSC_MEMTYPE_CUDA), "");
180: static_assert(!PetscMemTypeHost(PETSC_MEMTYPE_HIP), "");
181: static_assert(!PetscMemTypeHost(PETSC_MEMTYPE_SYCL), "");
182: static_assert(!PetscMemTypeHost(PETSC_MEMTYPE_NVSHMEM), "");
184: static_assert(!PetscMemTypeDevice(PETSC_MEMTYPE_HOST), "");
185: static_assert(PetscMemTypeDevice(PETSC_MEMTYPE_DEVICE), "");
186: static_assert(PetscMemTypeDevice(PETSC_MEMTYPE_CUDA), "");
187: static_assert(PetscMemTypeDevice(PETSC_MEMTYPE_HIP), "");
188: static_assert(PetscMemTypeDevice(PETSC_MEMTYPE_SYCL), "");
189: static_assert(PetscMemTypeDevice(PETSC_MEMTYPE_NVSHMEM), "");
191: static_assert(PetscMemTypeCUDA(PETSC_MEMTYPE_CUDA), "");
192: static_assert(PetscMemTypeCUDA(PETSC_MEMTYPE_NVSHMEM), "");
193: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
194: #pragma GCC diagnostic pop
195: #endif
196: #endif // __cplusplus
198: PETSC_NODISCARD static inline PETSC_CONSTEXPR_14 const char *PetscMemTypeToString(PetscMemType mtype)
199: {
200: #if defined(__cplusplus)
201: static_assert(PETSC_MEMTYPE_CUDA == PETSC_MEMTYPE_DEVICE, "");
202: #endif
203: #define PETSC_CASE_NAME(v) \
204: case v: \
205: return PetscStringize(v)
207: switch (mtype) {
208: PETSC_CASE_NAME(PETSC_MEMTYPE_HOST);
209: /* PETSC_CASE_NAME(PETSC_MEMTYPE_DEVICE); same as PETSC_MEMTYPE_CUDA */
210: PETSC_CASE_NAME(PETSC_MEMTYPE_CUDA);
211: PETSC_CASE_NAME(PETSC_MEMTYPE_NVSHMEM);
212: PETSC_CASE_NAME(PETSC_MEMTYPE_HIP);
213: PETSC_CASE_NAME(PETSC_MEMTYPE_SYCL);
214: }
215: PetscUnreachable();
216: return "invalid";
217: #undef PETSC_CASE_NAME
218: }
220: #define PETSC_OFFLOAD_VECKOKKOS_DEPRECATED PETSC_OFFLOAD_VECKOKKOS PETSC_DEPRECATED_ENUM(3, 17, 0, "PETSC_OFFLOAD_KOKKOS", )
222: /*E
223: PetscOffloadMask - indicates which memory (CPU, GPU, or none) contains valid data
225: Values:
226: + `PETSC_OFFLOAD_UNALLOCATED` - no memory contains valid matrix entries; NEVER used for vectors
227: . `PETSC_OFFLOAD_GPU` - GPU has valid vector/matrix entries
228: . `PETSC_OFFLOAD_CPU` - CPU has valid vector/matrix entries
229: . `PETSC_OFFLOAD_BOTH` - Both GPU and CPU have valid vector/matrix entries and they match
230: - `PETSC_OFFLOAD_KOKKOS` - Reserved for Kokkos matrix and vector. It means the offload is managed by Kokkos, thus this flag itself cannot tell you where the valid data is.
232: Level: developer
234: Developer Note:
235: This enum uses a function (`PetscOffloadMaskToString()`) to convert to string representation so
236: cannot be used in `PetscOptionsEnum()`.
238: .seealso: `PetscOffloadMaskToString()`, `PetscOffloadMaskToMemType()`, `PetscOffloadMaskToDeviceCopyMode()`
239: E*/
240: typedef enum {
241: PETSC_OFFLOAD_UNALLOCATED = 0, /* 0x0 */
242: PETSC_OFFLOAD_CPU = 1, /* 0x1 */
243: PETSC_OFFLOAD_GPU = 2, /* 0x2 */
244: PETSC_OFFLOAD_BOTH = 3, /* 0x3 */
245: PETSC_OFFLOAD_VECKOKKOS_DEPRECATED = 256, /* 0x100 */
246: PETSC_OFFLOAD_KOKKOS = 256 /* 0x100 */
247: } PetscOffloadMask;
249: /*MC
250: PetscOffloadUnallocated - Returns `PETSC_TRUE` if a given `PetscOffloadMask` indicates that no memory has been allocated yet
252: Synopsis:
253: #include <petscdevicetypes.h>
254: PetscBool PetscOffloadUnallocated(PetscOffloadMask m)
256: Not Collective; No Fortran Support
258: Input Parameter:
259: . m - the `PetscOffloadMask` value
261: Level: developer
263: .seealso: `PetscOffloadMask`, `PetscOffloadHost()`, `PetscOffloadDevice()`, `PetscOffloadBoth()`
264: M*/
265: #define PetscOffloadUnallocated(m) ((m) == PETSC_OFFLOAD_UNALLOCATED)
267: /*MC
268: PetscOffloadHost - Returns `PETSC_TRUE` if a given `PetscOffloadMask` indicates that the host (CPU) memory holds valid data
270: Synopsis:
271: #include <petscdevicetypes.h>
272: PetscBool PetscOffloadHost(PetscOffloadMask m)
274: Not Collective; No Fortran Support
276: Input Parameter:
277: . m - the `PetscOffloadMask` value
279: Level: developer
281: .seealso: `PetscOffloadMask`, `PetscOffloadUnallocated()`, `PetscOffloadDevice()`, `PetscOffloadBoth()`
282: M*/
283: #define PetscOffloadHost(m) (((m) & PETSC_OFFLOAD_CPU) == PETSC_OFFLOAD_CPU)
285: /*MC
286: PetscOffloadDevice - Returns `PETSC_TRUE` if a given `PetscOffloadMask` indicates that device (GPU) memory holds valid data
288: Synopsis:
289: #include <petscdevicetypes.h>
290: PetscBool PetscOffloadDevice(PetscOffloadMask m)
292: Not Collective; No Fortran Support
294: Input Parameter:
295: . m - the `PetscOffloadMask` value
297: Level: developer
299: .seealso: `PetscOffloadMask`, `PetscOffloadUnallocated()`, `PetscOffloadHost()`, `PetscOffloadBoth()`
300: M*/
301: #define PetscOffloadDevice(m) (((m) & PETSC_OFFLOAD_GPU) == PETSC_OFFLOAD_GPU)
303: /*MC
304: PetscOffloadBoth - Returns `PETSC_TRUE` if a given `PetscOffloadMask` indicates that both host and device memory hold matching valid data
306: Synopsis:
307: #include <petscdevicetypes.h>
308: PetscBool PetscOffloadBoth(PetscOffloadMask m)
310: Not Collective; No Fortran Support
312: Input Parameter:
313: . m - the `PetscOffloadMask` value
315: Level: developer
317: .seealso: `PetscOffloadMask`, `PetscOffloadUnallocated()`, `PetscOffloadHost()`, `PetscOffloadDevice()`
318: M*/
319: #define PetscOffloadBoth(m) ((m) == PETSC_OFFLOAD_BOTH)
321: #if defined(__cplusplus)
322: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
323: #pragma GCC diagnostic push
324: #pragma GCC diagnostic ignored "-Wtautological-compare"
325: #endif
326: static_assert(!PetscOffloadHost(PETSC_OFFLOAD_UNALLOCATED), "");
327: static_assert(PetscOffloadHost(PETSC_OFFLOAD_BOTH), "");
328: static_assert(!PetscOffloadHost(PETSC_OFFLOAD_GPU), "");
329: static_assert(PetscOffloadHost(PETSC_OFFLOAD_BOTH), "");
330: static_assert(!PetscOffloadHost(PETSC_OFFLOAD_KOKKOS), "");
332: static_assert(!PetscOffloadDevice(PETSC_OFFLOAD_UNALLOCATED), "");
333: static_assert(!PetscOffloadDevice(PETSC_OFFLOAD_CPU), "");
334: static_assert(PetscOffloadDevice(PETSC_OFFLOAD_GPU), "");
335: static_assert(PetscOffloadDevice(PETSC_OFFLOAD_BOTH), "");
336: static_assert(!PetscOffloadDevice(PETSC_OFFLOAD_KOKKOS), "");
338: static_assert(PetscOffloadBoth(PETSC_OFFLOAD_BOTH), "");
339: static_assert(!PetscOffloadBoth(PETSC_OFFLOAD_CPU), "");
340: static_assert(!PetscOffloadBoth(PETSC_OFFLOAD_GPU), "");
341: static_assert(!PetscOffloadBoth(PETSC_OFFLOAD_GPU), "");
342: static_assert(!PetscOffloadBoth(PETSC_OFFLOAD_KOKKOS), "");
343: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
344: #pragma GCC diagnostic pop
345: #endif
346: #endif // __cplusplus
348: PETSC_NODISCARD static inline PETSC_CONSTEXPR_14 const char *PetscOffloadMaskToString(PetscOffloadMask mask)
349: {
350: #define PETSC_CASE_RETURN(v) \
351: case v: \
352: return PetscStringize(v)
354: switch (mask) {
355: PETSC_CASE_RETURN(PETSC_OFFLOAD_UNALLOCATED);
356: PETSC_CASE_RETURN(PETSC_OFFLOAD_CPU);
357: PETSC_CASE_RETURN(PETSC_OFFLOAD_GPU);
358: PETSC_CASE_RETURN(PETSC_OFFLOAD_BOTH);
359: PETSC_CASE_RETURN(PETSC_OFFLOAD_KOKKOS);
360: }
361: PetscUnreachable();
362: return "invalid";
363: #undef PETSC_CASE_RETURN
364: }
366: PETSC_NODISCARD static inline PETSC_CONSTEXPR_14 PetscMemType PetscOffloadMaskToMemType(PetscOffloadMask mask)
367: {
368: switch (mask) {
369: case PETSC_OFFLOAD_UNALLOCATED:
370: case PETSC_OFFLOAD_CPU:
371: return PETSC_MEMTYPE_HOST;
372: case PETSC_OFFLOAD_GPU:
373: case PETSC_OFFLOAD_BOTH:
374: return PETSC_MEMTYPE_DEVICE;
375: case PETSC_OFFLOAD_KOKKOS:
376: return PETSC_MEMTYPE_KOKKOS;
377: }
378: PetscUnreachable();
379: return PETSC_MEMTYPE_HOST;
380: }
382: /*E
383: PetscDeviceInitType - Initialization strategy for `PetscDevice`
385: Values:
386: + `PETSC_DEVICE_INIT_NONE` - PetscDevice is never initialized
387: . `PETSC_DEVICE_INIT_LAZY` - PetscDevice is initialized on demand
388: - `PETSC_DEVICE_INIT_EAGER` - PetscDevice is initialized as soon as possible
390: Level: intermediate
392: Note:
393: `PETSC_DEVICE_INIT_NONE` implies that any initialization of `PetscDevice` is disallowed and
394: doing so results in an error. Useful to ensure that no accelerator is used in a program.
396: .seealso: `PetscDevice`, `PetscDeviceType`, `PetscDeviceInitialize()`,
397: `PetscDeviceInitialized()`, `PetscDeviceCreate()`
398: E*/
399: typedef enum {
400: PETSC_DEVICE_INIT_NONE,
401: PETSC_DEVICE_INIT_LAZY,
402: PETSC_DEVICE_INIT_EAGER
403: } PetscDeviceInitType;
404: PETSC_EXTERN const char *const PetscDeviceInitTypes[];
406: /*E
407: PetscDeviceType - Kind of accelerator device backend
409: Values:
410: + `PETSC_DEVICE_HOST` - Host, no accelerator backend found
411: . `PETSC_DEVICE_CUDA` - CUDA enabled GPU
412: . `PETSC_DEVICE_HIP` - ROCM/HIP enabled GPU
413: . `PETSC_DEVICE_SYCL` - SYCL enabled device
414: - `PETSC_DEVICE_MAX` - Always 1 greater than the largest valid `PetscDeviceType`, invalid type, do not use
416: Level: beginner
418: Note:
419: One can also use the `PETSC_DEVICE_DEFAULT()` routine to get the current default `PetscDeviceType`.
421: .seealso: `PetscDevice`, `PetscDeviceInitType`, `PetscDeviceCreate()`, `PETSC_DEVICE_DEFAULT()`
422: E*/
423: typedef enum {
424: PETSC_DEVICE_HOST,
425: PETSC_DEVICE_CUDA,
426: PETSC_DEVICE_HIP,
427: PETSC_DEVICE_SYCL,
428: PETSC_DEVICE_MAX
429: } PetscDeviceType;
430: PETSC_EXTERN const char *const PetscDeviceTypes[];
432: /*E
433: PetscDeviceAttribute - Attribute detailing a property or feature of a `PetscDevice`
435: Values:
436: + `PETSC_DEVICE_ATTR_SIZE_T_SHARED_MEM_PER_BLOCK` - The maximum amount of shared memory per block in a device kernel
437: - `PETSC_DEVICE_ATTR_MAX` - Invalid attribute, do not use
439: Level: beginner
441: .seealso: `PetscDevice`, `PetscDeviceGetAttribute()`
442: E*/
443: typedef enum {
444: PETSC_DEVICE_ATTR_SIZE_T_SHARED_MEM_PER_BLOCK,
445: PETSC_DEVICE_ATTR_MAX
446: } PetscDeviceAttribute;
447: PETSC_EXTERN const char *const PetscDeviceAttributes[];
449: /*S
450: PetscDevice - Object to manage an accelerator "device" (usually a GPU)
452: Level: beginner
454: Note:
455: This object is used to house configuration and state of a device, but does not offer any
456: ability to interact with or drive device computation. This functionality is facilitated
457: instead by the `PetscDeviceContext` object.
459: .seealso: `PetscDeviceType`, `PetscDeviceInitType`, `PetscDeviceCreate()`,
460: `PetscDeviceConfigure()`, `PetscDeviceDestroy()`, `PetscDeviceContext`,
461: `PetscDeviceContextSetDevice()`, `PetscDeviceContextGetDevice()`, `PetscDeviceGetAttribute()`
462: S*/
463: typedef struct _n_PetscDevice *PetscDevice;
465: /*E
466: PetscStreamType - indicates how a stream implementation will interact
467: with other streams and if it blocks the host.
469: Values:
470: + `PETSC_STREAM_DEFAULT` - Same as the default stream in CUDA or HIP. Streams of this type may or may not synchronize implicitly with other streams. It does not block the host.
471: . `PETSC_STREAM_NONBLOCKING` - Same as the nonblocking stream in CUDA or HIP. Streams of this type is truly asynchronous, and is blocked by nothing. It does not block the host. In CUDA, it is created with cudaStreamCreateWithFlags(&stream, cudaStreamNonBlocking).
472: . `PETSC_STREAM_DEFAULT_WITH_BARRIER` - Same as the default stream in CUDA or HIP. PETSc async functions using this kind of stream will end with a stream synchronization. Stream of this type may or may not synchronize implicitly with other streams.
473: . `PETSC_STREAM_NONBLOCKING_WITH_BARRIER` - Same as the nonblocking stream in CUDA or HIP. PETSc async functions using this kind of stream will end with a stream synchronization. Streams of this type are truly asynchronous and are blocked by nothing.
474: - `PETSC_STREAM_MAX` - Always 1 greater than the largest `PetscStreamType`, do not use
476: Level: intermediate
478: Note:
479: The default stream, also known as the NULL stream or stream 0, can have two different behaviors: legacy behavior and per-thread behavior.
480: The behavior is determined at compile time. By default, the legacy default stream is used.
481: The legacy default stream implicitly synchronizes with per-thread default streams.
482: The per-thread default stream, like nonblocking streams, does not synchronizes with other per-thread streams, but synchronize with the default stream.
483: The per-thread default stream may be useful for running kernels launched from different threads concurrently on the same GPU when the Multi-Process Service is not available.
484: To use the per-thread default stream, one can enable it by using the nvcc option "--default-stream per-thread" or the hipcc option "-fgpu-default-stream=per-thread", depending on the backend used.
486: .seealso: `PetscDeviceContextSetStreamType()`, `PetscDeviceContextGetStreamType()`
487: E*/
488: typedef enum {
489: PETSC_STREAM_DEFAULT,
490: PETSC_STREAM_NONBLOCKING,
491: PETSC_STREAM_DEFAULT_WITH_BARRIER,
492: PETSC_STREAM_NONBLOCKING_WITH_BARRIER,
493: PETSC_STREAM_MAX
494: } PetscStreamType;
495: PETSC_EXTERN const char *const PetscStreamTypes[];
497: /*E
498: PetscDeviceContextJoinMode - Describes the type of join operation to perform in
499: `PetscDeviceContextJoin()`
501: Values:
502: + `PETSC_DEVICE_CONTEXT_JOIN_DESTROY` - Destroy all incoming sub-contexts after join.
503: . `PETSC_DEVICE_CONTEXT_JOIN_SYNC` - Synchronize incoming sub-contexts after join.
504: - `PETSC_DEVICE_CONTEXT_JOIN_NO_SYNC` - Do not synchronize incoming sub-contexts after join.
506: Level: advanced
508: .seealso: `PetscDeviceContext`, `PetscDeviceContextFork()`, `PetscDeviceContextJoin()`
509: E*/
510: typedef enum {
511: PETSC_DEVICE_CONTEXT_JOIN_DESTROY,
512: PETSC_DEVICE_CONTEXT_JOIN_SYNC,
513: PETSC_DEVICE_CONTEXT_JOIN_NO_SYNC
514: } PetscDeviceContextJoinMode;
515: PETSC_EXTERN const char *const PetscDeviceContextJoinModes[];
517: /*S
518: PetscDeviceContext - Container to manage stream dependencies and the various solver handles
519: for asynchronous device compute.
521: Level: beginner
523: Notes:
524: Public APIs taking a `PetscDeviceContext` require a valid context or, where supported, `PetscDeviceContextDefault`.
525: Obtain the current context with
526: `PetscDeviceContextGetCurrentContext()` and pass it explicitly; `NULL` does not select an implicit context.
527: This requirement also applies to operations with no work, such as zero-length memory operations.
528: `PetscDeviceContextDestroy()` accepts the address of a null handle.
530: In builds using the C-only device-interface fallback, `PetscDeviceContextCreate()` and
531: `PetscDeviceContextGetCurrentContext()` return null handles. These handles remain valid arguments to
532: the fallback APIs. This exception does not apply to host contexts in builds using the C++ device interface.
534: .seealso: `PetscDevice`, `PetscDeviceContextCreate()`, `PetscDeviceContextSetDevice()`,
535: `PetscDeviceContextDestroy()`, `PetscDeviceContextFork()`, `PetscDeviceContextJoin()`
536: S*/
537: typedef struct _p_PetscDeviceContext *PetscDeviceContext;
539: /*E
540: PetscDeviceCopyMode - Describes the copy direction of a device-aware `memcpy`
542: Values:
543: + `PETSC_DEVICE_COPY_HTOH` - Copy from host memory to host memory
544: . `PETSC_DEVICE_COPY_DTOH` - Copy from device memory to host memory
545: . `PETSC_DEVICE_COPY_HTOD` - Copy from host memory to device memory
546: . `PETSC_DEVICE_COPY_DTOD` - Copy from device memory to device memory
547: - `PETSC_DEVICE_COPY_AUTO` - Infer the copy direction from the pointers
549: Level: beginner
551: .seealso: `PetscDeviceArrayCopy()`, `PetscDeviceMemcpy()`
552: E*/
553: typedef enum {
554: PETSC_DEVICE_COPY_HTOH,
555: PETSC_DEVICE_COPY_DTOH,
556: PETSC_DEVICE_COPY_HTOD,
557: PETSC_DEVICE_COPY_DTOD,
558: PETSC_DEVICE_COPY_AUTO,
559: } PetscDeviceCopyMode;
560: PETSC_EXTERN const char *const PetscDeviceCopyModes[];
562: PETSC_NODISCARD static inline PetscDeviceCopyMode PetscOffloadMaskToDeviceCopyMode(PetscOffloadMask dest, PetscOffloadMask src)
563: {
564: PetscDeviceCopyMode mode;
566: PetscFunctionBegin;
567: PetscAssertAbort(dest != PETSC_OFFLOAD_UNALLOCATED, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Cannot copy to unallocated");
568: PetscAssertAbort(src != PETSC_OFFLOAD_UNALLOCATED, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Cannot copy from unallocated");
570: if (PetscOffloadDevice(dest)) {
571: mode = PetscOffloadHost(src) ? PETSC_DEVICE_COPY_HTOD : PETSC_DEVICE_COPY_DTOD;
572: } else {
573: mode = PetscOffloadHost(src) ? PETSC_DEVICE_COPY_HTOH : PETSC_DEVICE_COPY_DTOH;
574: }
575: PetscFunctionReturn(mode);
576: }
578: PETSC_NODISCARD static inline PETSC_CONSTEXPR_14 PetscDeviceCopyMode PetscMemTypeToDeviceCopyMode(PetscMemType dest, PetscMemType src)
579: {
580: if (PetscMemTypeHost(dest)) {
581: return PetscMemTypeHost(src) ? PETSC_DEVICE_COPY_HTOH : PETSC_DEVICE_COPY_DTOH;
582: } else {
583: return PetscMemTypeDevice(src) ? PETSC_DEVICE_COPY_DTOD : PETSC_DEVICE_COPY_HTOD;
584: }
585: }
587: /*E
588: PetscMemoryAccessMode - Describes the intended usage of a memory region
590: Values:
591: + `PETSC_MEMORY_ACCESS_READ` - Read only
592: . `PETSC_MEMORY_ACCESS_WRITE` - Write only
593: - `PETSC_MEMORY_ACCESS_READ_WRITE` - Read and write
595: Level: beginner
597: Notes:
598: This `enum` is a bitmask with the following encoding (assuming 2 bit)\:
600: .vb
601: PETSC_MEMORY_ACCESS_READ = 0b01
602: PETSC_MEMORY_ACCESS_WRITE = 0b10
603: PETSC_MEMORY_ACCESS_READ_WRITE = 0b11
605: // consequently
606: PETSC_MEMORY_ACCESS_READ | PETSC_MEMORY_ACCESS_WRITE = PETSC_MEMORY_ACCESS_READ_WRITE
607: .ve
609: The following convenience macros are also provided\:
611: + `PetscMemoryAccessRead(mode)` - `true` if `mode` is any kind of read, `false` otherwise
612: - `PetscMemoryAccessWrite(mode)` - `true` if `mode` is any kind of write, `false` otherwise
614: Developer Note:
615: This enum uses a function (`PetscMemoryAccessModeToString()`) to convert values to string
616: representation, so cannot be used in `PetscOptionsEnum()`.
618: .seealso: `PetscMemoryAccessModeToString()`, `PetscDevice`, `PetscDeviceContext`
619: E*/
620: typedef enum {
621: PETSC_MEMORY_ACCESS_READ = 1, /* 01 */
622: PETSC_MEMORY_ACCESS_WRITE = 2, /* 10 */
623: PETSC_MEMORY_ACCESS_READ_WRITE = 3 /* 11 */
624: } PetscMemoryAccessMode;
626: /*MC
627: PetscMemoryAccessRead - Returns `PETSC_TRUE` if a given `PetscMemoryAccessMode` includes read access
629: Synopsis:
630: #include <petscdevicetypes.h>
631: PetscBool PetscMemoryAccessRead(PetscMemoryAccessMode m)
633: Not Collective; No Fortran Support
635: Input Parameter:
636: . m - the `PetscMemoryAccessMode` value
638: Level: beginner
640: .seealso: `PetscMemoryAccessMode`, `PetscMemoryAccessWrite()`
641: M*/
642: #define PetscMemoryAccessRead(m) (((m) & PETSC_MEMORY_ACCESS_READ) == PETSC_MEMORY_ACCESS_READ)
644: /*MC
645: PetscMemoryAccessWrite - Returns `PETSC_TRUE` if a given `PetscMemoryAccessMode` includes write access
647: Synopsis:
648: #include <petscdevicetypes.h>
649: PetscBool PetscMemoryAccessWrite(PetscMemoryAccessMode m)
651: Not Collective; No Fortran Support
653: Input Parameter:
654: . m - the `PetscMemoryAccessMode` value
656: Level: beginner
658: .seealso: `PetscMemoryAccessMode`, `PetscMemoryAccessRead()`
659: M*/
660: #define PetscMemoryAccessWrite(m) (((m) & PETSC_MEMORY_ACCESS_WRITE) == PETSC_MEMORY_ACCESS_WRITE)
662: #if defined(__cplusplus)
663: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
664: #pragma GCC diagnostic push
665: #pragma GCC diagnostic ignored "-Wtautological-compare"
666: #endif
667: static_assert(PetscMemoryAccessRead(PETSC_MEMORY_ACCESS_READ), "");
668: static_assert(PetscMemoryAccessRead(PETSC_MEMORY_ACCESS_READ_WRITE), "");
669: static_assert(!PetscMemoryAccessRead(PETSC_MEMORY_ACCESS_WRITE), "");
670: static_assert(PetscMemoryAccessWrite(PETSC_MEMORY_ACCESS_WRITE), "");
671: static_assert(PetscMemoryAccessWrite(PETSC_MEMORY_ACCESS_READ_WRITE), "");
672: static_assert(!PetscMemoryAccessWrite(PETSC_MEMORY_ACCESS_READ), "");
673: static_assert((PETSC_MEMORY_ACCESS_READ | PETSC_MEMORY_ACCESS_WRITE) == PETSC_MEMORY_ACCESS_READ_WRITE, "");
674: #if PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING
675: #pragma GCC diagnostic pop
676: #endif
677: #endif
679: PETSC_NODISCARD static inline PETSC_CONSTEXPR_14 const char *PetscMemoryAccessModeToString(PetscMemoryAccessMode mode)
680: {
681: #define PETSC_CASE_RETURN(v) \
682: case v: \
683: return PetscStringize(v)
685: switch (mode) {
686: PETSC_CASE_RETURN(PETSC_MEMORY_ACCESS_READ);
687: PETSC_CASE_RETURN(PETSC_MEMORY_ACCESS_WRITE);
688: PETSC_CASE_RETURN(PETSC_MEMORY_ACCESS_READ_WRITE);
689: }
690: PetscUnreachable();
691: return "invalid";
692: #undef PETSC_CASE_RETURN
693: }
695: #undef PETSC_SHOULD_SILENCE_GCC_TAUTOLOGICAL_COMPARE_WARNING