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